Merge pull request #209 from dstansby/xarray

Make new xarray namespace

cdflib/xarray/__init__.py

@@ -0,0 +1,2 @@
+from cdflib.xarray.cdf_to_xarray import cdf_to_xarray
+from cdflib.xarray.xarray_to_cdf import xarray_to_cdf

cdflib/cdf_to_xarray.py → cdflib/xarray/cdf_to_xarray.py

@@ -540,9 +540,6 @@ def _generate_xarray_data_variables(
     all_variable_properties: Dict[str, VDRInfo],
     fillval_to_nan: bool,
 ) -> Tuple[Dict[str, xr.Variable], Dict[str, int]]:
-    # Import here to avoid xarray as a dependency of all of cdflib
-    import xarray as xr
-
     # Make a list of all of the special variables in the file.  These are variables that are pointed to by
     # other variables.
     depend_variables = _discover_depend_variables(all_variable_data, all_variable_attributes, all_variable_properties)
@@ -681,19 +678,19 @@ def cdf_to_xarray(filename: str, to_datetime: bool = False, to_unixtime: bool =
         An XArray Dataset Object
 
     Example MMS:
-        >>> #Import necessary libraries
+        >>> # Import necessary libraries
         >>> import cdflib
         >>> import xarray as xr
         >>> import os
         >>> import urllib.request
 
-        >>> #Download a CDF file
+        >>> # Download a CDF file
         >>> fname = 'mms2_fgm_srvy_l2_20160809_v4.47.0.cdf'
         >>> url = ("https://lasp.colorado.edu/maven/sdc/public/data/sdc/web/cdflib_testing/mms2_fgm_srvy_l2_20160809_v4.47.0.cdf")
         >>> if not os.path.exists(fname):
         >>>     urllib.request.urlretrieve(url, fname)
 
-        >>> #Load in and display the CDF file
+        >>> # Load in and display the CDF file
         >>> mms_data = cdflib.cdf_to_xarray("mms2_fgm_srvy_l2_20160809_v4.47.0.cdf", to_unixtime=True, fillval_to_nan=True)
         >>> print(mms_data)
 
@@ -709,19 +706,19 @@ def cdf_to_xarray(filename: str, to_datetime: bool = False, to_unixtime: bool =
         >>> mms_data3['mms2_fgm_b_gse_srvy_l2'].plot()
 
     Example THEMIS:
-        >>> #Import necessary libraries
+        >>> # Import necessary libraries
         >>> import cdflib
         >>> import xarray as xr
         >>> import os
         >>> import urllib.request
 
-        >>> #Download a CDF file
+        >>> # Download a CDF file
         >>> fname = 'thg_l2_mag_amd_20070323_v01.cdf'
         >>> url = ("https://lasp.colorado.edu/maven/sdc/public/data/sdc/web/cdflib_testing/thg_l2_mag_amd_20070323_v01.cdf")
         >>> if not os.path.exists(fname):
         >>>     urllib.request.urlretrieve(url, fname)
 
-        >>> #Load in and display the CDF file
+        >>> # Load in and display the CDF file
         >>> thg_data = cdflib.cdf_to_xarray(fname, to_unixtime=True, fillval_to_nan=True)
         >>> print(thg_data)
 

doc/Makefile

@@ -12,6 +12,12 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+
+clean:
+	@echo Removing files created by sphinx-build
+	rm -rf $(BUILDDIR)
+	rm -rf $(SOURCEDIR)/api/
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

doc/changelog.rst

@@ -2,12 +2,22 @@
 Changelog
 =========
 
+1.0.2
+=====
+To make the ``xarray`` functionality easier to discover and import, a new
+``cdflib.xarray`` namespace has been added. This means the recommended
+way to import the xarray functionality is now
+``from cdflib.xarray import cdf_to_xarray, xarray_to_cdf``
+
+
 1.0.1
 =====
 To keep ``astropy`` and ``xarray`` as optional dependencies, ``cdfastropy``,
 ``cdf_to_xarray``, and ``xarray_to_cdf`` are no longer available under ``cdflib``.
-Instead import them from ``cdflib.xarray_to_cdf``, ``cdflib.cdf_to_xarray``, or
-``cdflib.epochs_astropy``.
+Instead import them from
+``cdflib.xarray_to_cdf.xarray_to_cdf``,
+``cdflib.cdf_to_xarray.cdf_to_xarray``, or
+``cdflib.epochs_astropy.CDFAstropy``.
 
 1.0.0
 =====

doc/modules/xarray.rst

@@ -8,6 +8,5 @@ the ``xarray`` package installed.
 These will attempt to determine any
 `ISTP Compliance <https://spdf.gsfc.nasa.gov/istp_guide/istp_guide.html>`_, and incorporate that into the output.
 
-.. autofunction:: cdflib.cdf_to_xarray
-
-.. autofunction:: cdflib.xarray_to_cdf
+.. automodapi:: cdflib.xarray
+    :no-inheritance-diagram:

tests/test_xarray_reader_writer.py

@@ -4,8 +4,7 @@
 import pytest
 import xarray as xr
 
-from cdflib.cdf_to_xarray import cdf_to_xarray
-from cdflib.xarray_to_cdf import xarray_to_cdf
+from cdflib.xarray import cdf_to_xarray, xarray_to_cdf
 
 # To run these tests use `pytest --remote-data`