Merge pull request #14 from cedadev/creator

CFA: Create Functionality

.github/workflows/ci.yml

@@ -14,19 +14,19 @@ jobs:
 
       # Firstly, checkout repo
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       # Set up Python env
       - name: Setup Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: 3.11
       # Install dependencies
       - name: Install Python dependencies
         run: |
           python3 -m pip install --upgrade pip
-          pip3 install -r requirements.txt
-          pip3 install -e .
+          pip3 install poetry
+          poetry install
       # Test with pytest
       - name: Run pytest
         run: |
-          pytest
+          poetry run pytest

.github/workflows/sphinx.yml

@@ -12,32 +12,46 @@ on:
 
 jobs:
   build:
-    # Linux version requirements
+    # Specify an OS for the runner
     runs-on: ubuntu-latest
+
+    #Define steps
     steps:
-    # Checkout and build the docs with sphinx
-    - uses: actions/checkout@v2
 
-    - name: Set up Python 3.10
-      uses: actions/setup-python@v2
-      with:
-        python-version: "3.10"
+      # Firstly, checkout repo
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      # Set up Python env
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+      # Install dependencies
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip3 install poetry
+          poetry install
+
+      - name: Build documentation
+        run: |
+          mkdir gh-pages
+          touch gh-pages/.nojekyll
+          pushd docs/source/
+          poetry run sphinx-build -b html . _build
+          popd
+          cp -r docs/source/_build/* gh-pages/
 
-    - name: Build HTML
-      uses: ammaraskar/sphinx-action@master
-      with: 
-        docs-folder: "docs/"
-        # pre-build-command: "mkdir /tmp/sphinx-log"
-    - name: Upload artifacts
-      uses: actions/upload-artifact@v1
-      with:
-        name: html-docs
-        path: docs/build/html/
-    # Deploys to the gh-pages branch if the commit was made to main, the 
-    # gh-pages then takes over serving the html
-    - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
-      if: github.ref == 'refs/heads/main'
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/build/html
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: gh-pages
+      # Deploys to the gh-pages branch if the commit was made to main, the 
+      # gh-pages then takes over serving the html
+      - name: Deploy documentation
+        if: ${{ github.event_name == 'push' }}
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: gh-pages

README.md

@@ -3,18 +3,20 @@
 CFA python Xarray module for using CFA files with xarray.
 
 See the [Documentation](https://cedadev.github.io/CFAPyX/) for more details.
-CFAPyX on [Github](https://github.com/cedadev/CFAPyX)
+cfapyx on [Github](https://github.com/cedadev/CFAPyX)
 
 For use with the Xarray module as an additional backend.
 
+> **_NOTE:_** The `create` functionality was added to version 2024.10.11 and is currently in alpha release. Please report any unexpected errors or issues using the GitHub Issues tab for this repository.
+
 # Installation
 
 ```
 pip install xarray==2024.6.0
-pip install CFAPyX
+pip install cfapyx
 ```
 
-# Usage
+# Usage as Xarray Engine
 
 ```
 import xarray as xr

cfapyx/__init__.py

@@ -0,0 +1,3 @@
+from .backend import CFANetCDFBackendEntrypoint
+
+from .creator import CFANetCDF

CFAPyX/backend.py → cfapyx/backend.py

@@ -7,7 +7,11 @@
 from xarray.core.dataset import Dataset
 from xarray import conventions
 
-from CFAPyX.datastore import CFADataStore
+from cfapyx.datastore import CFADataStore
+
+import logging
+
+logger = logging.getLogger(__name__)
 
 def open_cfa_dataset(
         filename_or_obj,
@@ -18,7 +22,7 @@ def open_cfa_dataset(
         decode_coords=None,
         use_cftime=None,
         decode_timedelta=None,
-        cfa_options={},
+        cfa_options: dict=None,
         group=None,
         ):
     """
@@ -42,6 +46,8 @@ def open_cfa_dataset(
                     parameter in ``cfa_options`` is false.
     """
 
+    cfa_options = cfa_options or {}
+
     # Load the CFA datastore from the provided file (object not supported).
     store = CFADataStore.open(filename_or_obj, group=group)
 
@@ -70,7 +76,7 @@ def open_cfa_dataset(
 
 class CFANetCDFBackendEntrypoint(BackendEntrypoint):
 
-    description = "Open CFA-netCDF files (.nca) using CFA-PyX in Xarray"
+    description = 'Open CFA-netCDF files (.nca) using "cfapyx" in Xarray'
     url = "https://cedadev.github.io/CFAPyX/"
 
     def open_dataset(
@@ -84,7 +90,7 @@ def open_dataset(
             decode_coords=None,
             use_cftime=None,
             decode_timedelta=None,
-            cfa_options={},
+            cfa_options=None,
             group=None,
             # backend specific keyword arguments
             # do not use 'chunks' or 'cache' here
@@ -94,6 +100,8 @@ def open_dataset(
         CFA aggregated variables into proper arrays.
         """
 
+        cfa_options = cfa_options or {}
+
         return open_cfa_dataset(
             filename_or_obj, 
             drop_variables=drop_variables,
@@ -113,7 +121,6 @@ class CFAStoreBackendEntrypoint(StoreBackendEntrypoint):
     def open_dataset(
         self,
         cfa_xarray_store,
-        *,
         mask_and_scale=True,
         decode_times=True,
         concat_characters=True,