Merge pull request #203 from Unidata/v1.3.0rel

update for 1.3.0 release

README.md

@@ -12,6 +12,15 @@ Time-handling functionality from netcdf4-python
 ## News
 For details on the latest updates, see the [Changelog](https://github.com/Unidata/cftime/blob/master/Changelog).
 
+11/03/2020:  Version 1.3.0 released. **API change**: The `cftime.datetime` constructor now creates 
+ 'calendar-aware' instances (default is `'standard'` calendar, if `calendar=''` or `None` the instance
+ is not calendar aware and some methods, like `dayofwk`, `dayofyr`, `__add__` and `__sub__`, will not work)
+ See discussion for issue [#198](https://github.com/Unidata/cftime/issues/198).
+ The calendar specific sub-classes are now deprecated, but remain for now
+ as stubs that just instantiate the base class and override `__repr__`.
+ The default calendar in `cftime.date2num` has been changed from `'standard'` to `None`
+ (the calendar associated with first input datetime object is used to define the calendar).
+
 07/20/2020: Version 1.2.1 released.  Fixes a couple of regressions introduced in 1.2.0. See Changelog for details.
 
 7/06/2020:  version 1.2.0 released. New microsecond accurate algorithm for date2num/num2date contributed by [spencerkclark](https://github.com/spencerkclark). Bugs fixed in masked array handling.

docs/_build/html/api.html

@@ -36,7 +36,7 @@
 <dl class="class">
 <dt id="cftime.datetime">
 <em class="property">class </em><code class="sig-prename descclassname">cftime.</code><code class="sig-name descname">datetime</code><span class="sig-paren">(</span><em class="sig-param">int year</em>, <em class="sig-param">int month</em>, <em class="sig-param">int day</em>, <em class="sig-param">int hour=0</em>, <em class="sig-param">int minute=0</em>, <em class="sig-param">int second=0</em>, <em class="sig-param">int microsecond=0</em>, <em class="sig-param">int dayofwk=-1</em>, <em class="sig-param">int dayofyr=-1</em>, <em class="sig-param">calendar='standard'</em><span class="sig-paren">)</span><a class="headerlink" href="#cftime.datetime" title="Permalink to this definition">¶</a></dt>
-<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.8)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>
+<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.9)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>
 <p>This class mimics datetime.datetime but support calendars other than the proleptic
 Gregorian calendar.</p>
 <p>Supports timedelta operations by overloading +/-, and
@@ -51,7 +51,7 @@
 Default is ‘standard’, which is a mixed Julian/Gregorian calendar.
 ‘standard’ and ‘gregorian’ are synonyms, as are ‘all_leap’/’366_day’
 and ‘noleap’/’365_day’.</p>
-<p>If the calendar kwarg is set to a blank string (‘’) the 
+<p>If the calendar kwarg is set to a blank string (‘’) or None (the default is ‘standard’) the 
 instance will not be calendar-aware and some methods will not work.</p>
 <p>Has isoformat, strftime, timetuple, replace, dayofwk, dayofyr, daysinmonth,
 __repr__, __add__, __sub__, __str__ and comparison methods.</p>
@@ -92,25 +92,28 @@
 
 <dl class="function">
 <dt id="cftime.date2num">
-<code class="sig-prename descclassname">cftime.</code><code class="sig-name descname">date2num</code><span class="sig-paren">(</span><em class="sig-param">dates</em>, <em class="sig-param">units</em>, <em class="sig-param">calendar='standard'</em><span class="sig-paren">)</span><a class="headerlink" href="#cftime.date2num" title="Permalink to this definition">¶</a></dt>
+<code class="sig-prename descclassname">cftime.</code><code class="sig-name descname">date2num</code><span class="sig-paren">(</span><em class="sig-param">dates</em>, <em class="sig-param">units</em>, <em class="sig-param">calendar=None</em><span class="sig-paren">)</span><a class="headerlink" href="#cftime.date2num" title="Permalink to this definition">¶</a></dt>
 <dd><p>Return numeric time values given datetime objects. The units
 of the numeric time values are described by the <strong>units</strong> argument
 and the <strong>calendar</strong> keyword. The datetime objects must
 be in UTC with no time-zone offset.  If there is a
 time-zone offset in <strong>units</strong>, it will be applied to the
 returned numeric values.</p>
 <p><strong>dates</strong>: A datetime object or a sequence of datetime objects.
-The datetime objects should not include a time-zone offset.</p>
+The datetime objects should not include a time-zone offset. They
+can be either native python datetime instances (which use
+the proleptic gregorian calendar) or cftime.datetime instances.</p>
 <p><strong>units</strong>: a string of the form <strong>&lt;time units&gt; since &lt;reference time&gt;</strong>
 describing the time units. <strong>&lt;time units&gt;</strong> can be days, hours, minutes,
 seconds, milliseconds or microseconds. <strong>&lt;reference time&gt;</strong> is the time
 origin. <strong>months_since</strong> is allowed <em>only</em> for the <strong>360_day</strong> calendar.</p>
-<p><strong>calendar</strong>: describes the calendar used in the time calculations.
+<p><strong>calendar</strong>: describes the calendar to be used in the time calculations.
 All the values currently defined in the
 [CF metadata convention](<a class="reference external" href="http://cfconventions.org">http://cfconventions.org</a>)
 Valid calendars <strong>‘standard’, ‘gregorian’, ‘proleptic_gregorian’
 ‘noleap’, ‘365_day’, ‘360_day’, ‘julian’, ‘all_leap’, ‘366_day’</strong>.
-Default is <strong>‘standard’</strong>, which is a mixed Julian/Gregorian calendar.</p>
+Default is <cite>None</cite> which means the calendar associated with the rist
+input datetime instance will be used.</p>
 <p>returns a numeric time value, or an array of numeric time values
 with approximately 1 microsecond accuracy.</p>
 </dd></dl>