WIP Add a CFTimeIndex-enabled xr.cftime_range function (#2301)

* Initial work on adding a cftime-compatible date_range function

Add docstring for xr.date_range

Fix failing test

Fix test skipping logic

Coerce result of zip to a list in test setup

Add and clean up tests

Fix skip logic

Skip roll_forward and roll_backward tests if cftime is not installed

Expose all possible arguments to pd.date_range

Add more detail to docstrings

flake8

Add a what's new entry

Add a short example to time-series.rst

* Allow empty CFTimeIndexes; add calendar to CFTimeIndex repr

* Enable CFTimeIndex constructor to optionally take date_range arguments

* Simplify date_range to use new CFTimeIndex constructor

* Rename xr.date_range to xr.cftime_range

* Follow pandas behavior/naming for rollforward, rollback, and onOffset

* Update docstring

* Add pandas copyright notice to cftime_offsets.py

* Check validity of offset constructor arguments

* Fix TypeError versus ValueError uses

* Use a module-level importorskip in test_cftime_offsets.py

* Only return a CFTimeIndex from cftime_range

* Keep CFTimeIndex constructor simple

* Add some explicitly calendar-specific tests

* Revert back to default repr

* lint

* return NotImplemented

* Convert pandas copyright notices to comments

* test_calendar_leap_year_length -> test_calendar_year_length

* Use return NotImplemented in __apply__ too

Author: spencerkclark

doc/api.rst

@@ -555,6 +555,13 @@ Custom Indexes
 
    CFTimeIndex
 
+Creating custom indexes
+-----------------------
+.. autosummary::
+   :toctree: generated/
+
+   cftime_range
+
 Plotting
 ========
 

doc/time-series.rst

@@ -258,7 +258,16 @@ coordinate with a no-leap calendar within a context manager setting the
    calendar, its times will be decoded into ``cftime.datetime`` objects,
    regardless of whether or not they can be represented using
    ``np.datetime64[ns]`` objects.
-                         
+
+xarray also includes a :py:func:`cftime_range` function, which enables creating a
+``CFTimeIndex`` with regularly-spaced dates.  For instance, we can create the
+same dates and DataArray we created above using:
+
+.. ipython:: python
+
+   dates = xr.cftime_range(start='0001', periods=24, freq='MS', calendar='noleap')
+   da = xr.DataArray(np.arange(24), coords=[dates], dims=['time'], name='foo')
+   
 For data indexed by a ``CFTimeIndex`` xarray currently supports:
 
 - `Partial datetime string indexing`_ using strictly `ISO 8601-format`_ partial

doc/whats-new.rst

@@ -54,6 +54,9 @@ Enhancements
   now displayed as `a b ... y z` rather than `a b c d ...`.
   (:issue:`1186`)
   By `Seth P <https://github.com/seth-p>`_.
+- A new CFTimeIndex-enabled :py:func:`cftime_range` function for use in
+  generating dates from standard or non-standard calendars.  By `Spencer Clark 
+  <https://github.com/spencerkclark>`_. 
 
 - When interpolating over a ``datetime64`` axis, you can now provide a datetime string instead of a ``datetime64`` object. E.g. ``da.interp(time='1991-02-01')``
   (:issue:`2284`)

xarray/__init__.py

@@ -26,6 +26,7 @@
 
 from .conventions import decode_cf, SerializationWarning
 
+from .coding.cftime_offsets import cftime_range
 from .coding.cftimeindex import CFTimeIndex
 
 from .util.print_versions import show_versions