Terminology and class name changes

CFAPyX/__init__.py

@@ -1 +1 @@
-from .backendentrypoint import CFANetCDFBackendEntrypoint
+from .backend import CFANetCDFBackendEntrypoint

CFAPyX/backend.py

@@ -0,0 +1,178 @@
+__author__    = "Daniel Westwood"
+__contact__   = "[email protected]"
+__copyright__ = "Copyright 2023 United Kingdom Research and Innovation"
+
+from xarray.backends import StoreBackendEntrypoint, BackendEntrypoint
+from xarray.backends.common import AbstractDataStore
+from xarray.core.dataset import Dataset
+from xarray import conventions
+
+from CFAPyX.datastore import CFADataStore
+
+from importlib.metadata import entry_points
+#engine = entry_points(group='xarray.backends')
+
+def open_cfa_dataset(
+        filename_or_obj,
+        drop_variables=None,
+        mask_and_scale=None,
+        decode_times=None,
+        concat_characters=None,
+        decode_coords=None,
+        use_cftime=None,
+        decode_timedelta=None,
+        cfa_options={},
+        active_options={},
+        group=None,
+        ):
+    """
+    Top-level function which opens a CFA dataset using Xarray. Creates a CFA Datastore 
+    from the ``filename_or_obj`` provided, then passes this to a CFA StoreBackendEntrypoint
+    to create an Xarray Dataset. Most parameters are not handled by CFA, so only the 
+    CFA-relevant ones are described here.
+
+    :param filename_or_obj:       (str) The path to a CFA-netCDF file to be opened by Xarray
+
+    :param cfa_options:           (dict) A set of kwargs provided to CFA which provide additional 
+                                  configurations. Currently implemented are: substitutions (dict), 
+                                  decode_cfa (bool)
+
+    :param group:                 (str) The name or path to a NetCDF group. CFA can handle opening 
+                                  from specific groups and will inherit both ``group`` and ``global``
+                                  dimensions/attributes.
+
+    :returns:       An xarray.Dataset object composed of xarray.DataArray objects representing the different
+                    NetCDF variables and dimensions. CFA aggregated variables are decoded unless the ``decode_cfa``
+                    parameter in ``cfa_options`` is false.
+    """
+
+    # Load the CFA datastore from the provided file (object not supported).
+    store = CFADataStore.open(filename_or_obj, group=group)
+
+    # Expands cfa_options into individual kwargs for the store.
+    store.cfa_options    = cfa_options
+    store.active_options = active_options
+
+    # Xarray makes use of StoreBackendEntrypoints to provide the Dataset 'ds'
+    store_entrypoint = CFAStoreBackendEntrypoint()
+    ds = store_entrypoint.open_dataset(
+        store,
+        mask_and_scale=mask_and_scale,
+        decode_times=decode_times,
+        concat_characters=concat_characters,
+        decode_coords=decode_coords,
+        drop_variables=drop_variables,
+        use_cftime=use_cftime,
+        decode_timedelta=decode_timedelta,
+        use_active=store.use_active
+    )
+
+    return ds
+
+class CFANetCDFBackendEntrypoint(BackendEntrypoint):
+
+    description = "Open CFA-netCDF files (.nca) using CFA-PyX in Xarray"
+    url = "https://cedadev.github.io/CFAPyX/"
+
+    def open_dataset(
+            self,
+            filename_or_obj,
+            *,
+            drop_variables=None,
+            mask_and_scale=None,
+            decode_times=None,
+            concat_characters=None,
+            decode_coords=None,
+            use_cftime=None,
+            decode_timedelta=None,
+            cfa_options={},
+            active_options={},
+            group=None,
+            # backend specific keyword arguments
+            # do not use 'chunks' or 'cache' here
+        ):
+        """
+        Returns a complete xarray representation of a CFA-netCDF dataset which includes expanding/decoding
+        CFA aggregated variables into proper arrays.
+        """
+
+        return open_cfa_dataset(
+            filename_or_obj, 
+            drop_variables=drop_variables,
+            mask_and_scale=mask_and_scale,
+            decode_times=decode_times,
+            concat_characters=concat_characters,
+            decode_coords=decode_coords,
+            use_cftime=use_cftime,
+            decode_timedelta=decode_timedelta,
+            cfa_options=cfa_options,
+            active_options=active_options,
+            group=group)
+
+
+class CFAStoreBackendEntrypoint(StoreBackendEntrypoint):
+    description = "Open CFA-based Abstract Data Store"
+    url = "https://cedadev.github.io/CFAPyX/"
+
+    def open_dataset(
+        self,
+        cfa_xarray_store,
+        *,
+        mask_and_scale=True,
+        decode_times=True,
+        concat_characters=True,
+        decode_coords=True,
+        drop_variables=None,
+        use_cftime=None,
+        decode_timedelta=None,
+        use_active=False,
+    ) -> Dataset:
+        """
+        Takes cfa_xarray_store of type AbstractDataStore and creates an xarray.Dataset object.
+        Most parameters are not handled by CFA, so only the CFA-relevant ones are described here.
+
+        :param cfa_xarray_store:        (obj) The CFA Datastore object which loads and decodes CFA
+                                        aggregated variables and dimensions.
+
+        :returns:           An xarray.Dataset object composed of xarray.DataArray objects representing the different
+                            NetCDF variables and dimensions. CFA aggregated variables are decoded unless the ``decode_cfa``
+                            parameter in ``cfa_options`` is false.
+
+        """
+        assert isinstance(cfa_xarray_store, AbstractDataStore)
+
+        # Same as NetCDF4 operations, just with the CFA Datastore
+        vars, attrs = cfa_xarray_store.load()
+        encoding    = cfa_xarray_store.get_encoding()
+
+        # Ensures variables/attributes comply with CF conventions.
+        vars, attrs, coord_names = conventions.decode_cf_variables(
+            vars,
+            attrs,
+            mask_and_scale=mask_and_scale,
+            decode_times=decode_times,
+            concat_characters=concat_characters,
+            decode_coords=decode_coords,
+            drop_variables=drop_variables,
+            use_cftime=use_cftime,
+            decode_timedelta=decode_timedelta,
+        )
+
+        # Create the xarray.Dataset object here.
+        if use_active:
+            try:
+                from XarrayActive import ActiveDataset
+
+                ds = ActiveDataset(vars, attrs=attrs)
+            except ImportError:
+                raise ImportError(
+                    '"ActiveDataset" from XarrayActive failed to import - please ensure you have the XarrayActive package installed.'
+                )
+        else:
+            ds = Dataset(vars, attrs=attrs)
+
+        ds = ds.set_coords(coord_names.intersection(vars))
+        ds.set_close(cfa_xarray_store.close)
+        ds.encoding = encoding
+
+        return ds

CFAPyX/datastore.py

@@ -20,7 +20,7 @@
 import os
 import re
 
-from CFAPyX.fragmentarray import FragmentArrayWrapper
+from CFAPyX.wrappers import FragmentArrayWrapper
 from CFAPyX.decoder import get_fragment_positions, get_fragment_extents
 
 from CFAPyX.group import CFAGroupWrapper