feat!: Add phase filter argument

.github/workflows/doc.yaml

@@ -66,29 +66,48 @@ jobs:
         shell: bash -l {0}
         run: |
           pip install altimetry-downloader-aviso
-      - name: Restore cached sample data
-        uses: actions/cache@v4
-        id: restore_samples
-        with:
-          path: docs/implementations/data
-          key: samples-${{ hashFiles('docs/implementations/scripts/pull_data*.py') }}
       - name: Setup AVISO credentials
-        if: steps.restore_samples.outputs['cache-hit'] != 'true'
         run: |
           echo "machine tds-odatis.aviso.altimetry.fr login ${{ secrets.AVISO_USER }} password ${{ secrets.AVISO_PASSWORD }}" > ~/.netrc
-      - name: Pull Samples
-        if: steps.restore_samples.outputs['cache-hit'] != 'true'
+      # Cached retrieval of L2_LR_SSH data
+      - name: Restore cached sample data for L2_LR_SSH
+        uses: actions/cache@v4
+        id: restore_samples_l2_lr_ssh
+        with:
+          path: docs/implementations/data_l2_lr_ssh
+          key: samples-${{ hashFiles('docs/implementations/scripts/pull_data_l2_lr_ssh.py') }}
+      - name: Pull L2_LR_SSH Samples
+        if: steps.restore_samples_l2_lr_ssh.outputs['cache-hit'] != 'true'
         shell: bash -l {0}
         run: |
           set -e
           python docs/implementations/scripts/pull_data_l2_lr_ssh.py
+      - name: Cache L2_LR_SSH data
+        uses: actions/cache/save@v4
+        if: steps.restore_samples_l2_lr_ssh.outputs['cache-hit'] != 'true'
+        with:
+          path: docs/implementations/data_l2_lr_ssh
+          key: samples-${{ hashFiles('docs/implementations/scripts/pull_data_l2_lr_ssh.py') }}
+      # Cached retrieval of L3_LR_SSH data
+      - name: Restore cached sample data for L3_LR_SSH
+        uses: actions/cache@v4
+        id: restore_samples_l3_lr_ssh
+        with:
+          path: docs/implementations/data_l3_lr_ssh
+          key: samples-${{ hashFiles('docs/implementations/scripts/pull_data_l3_lr_ssh.py') }}
+      - name: Pull L3_LR_SSH Samples
+        if: steps.restore_samples_l3_lr_ssh.outputs['cache-hit'] != 'true'
+        shell: bash -l {0}
+        run: |
+          set -e
           python docs/implementations/scripts/pull_data_l3_lr_ssh.py
-      - name: Save fetched data
+      - name: Cache L3_LR_SSH data
         uses: actions/cache/save@v4
-        if: steps.restore_samples.outputs['cache-hit'] != 'true'
+        if: steps.restore_samples_l3_lr_ssh.outputs['cache-hit'] != 'true'
         with:
-          path: docs/implementations/data
-          key: samples-${{ hashFiles('docs/implementations/scripts/pull_data*.py') }}
+          path: docs/implementations/data_l3_lr_ssh
+          key: samples-${{ hashFiles('docs/implementations/scripts/pull_data_l3_lr_ssh.py') }}
+      # DOC BUILD
       - name: Build Sphinx HTML
         shell: bash -l {0}
         run: |

docs/implementations/l2_lr_ssh.md

@@ -57,6 +57,10 @@ The following examples can be used to build complex queries
     ```python
     fc.query(cycle_number=slice(1, 4), pass_number=[1, 3])
     ```
+  - A specific orbit of the SWOT mission
+    ```python
+    fc.query(phase='CALVAL')
+    ```
 :::
 :::{tab-item} Periods
   - A time stamp

docs/implementations/l3_lr_ssh.md

@@ -53,6 +53,10 @@ The following examples can be used to build complex queries
     ```python
     fc.query(cycle_number=slice(1, 4), pass_number=[1, 3])
     ```
+  - A specific orbit of the SWOT mission
+    ```python
+    fc.query(phase='CALVAL')
+    ```
 :::
 :::{tab-item} Periods
   - A time stamp

src/fcollections/core/__init__.py

@@ -18,6 +18,7 @@
     FileNameFieldDatetime,
     FileNameFieldEnum,
     FileNameFieldFloat,
+    FileNameFieldGeoBox,
     FileNameFieldInteger,
     FileNameFieldISODuration,
     FileNameFieldPeriod,
@@ -26,7 +27,7 @@
 from ._filesdb import (
     Deduplicator,
     FilesDatabase,
-    IPredicate,
+    IFilterBuilder,
     NotExistingPathError,
     SubsetsUnmixer,
 )
@@ -74,6 +75,7 @@
     "FileNameFieldString",
     "FileNameFieldPeriod",
     "FileNameFieldISODuration",
+    "FileNameFieldGeoBox",
     "FileNameConvention",
     "FileListingError",
     "IFilesReader",
@@ -93,7 +95,7 @@
     "VariableMetadata",
     "DiscreteTimesMixin",
     "ITemporalMixin",
-    "IPredicate",
+    "IFilterBuilder",
     "Layout",
     "DecodingError",
     "ICodec",

src/fcollections/core/_filenames.py

@@ -27,6 +27,7 @@
     DateTimeTester,
     EnumTester,
     FloatTester,
+    GeoBoxTester,
     IntegerTester,
     ITester,
     PeriodTester,
@@ -257,6 +258,18 @@ def sanitize(self, reference: str | ISODuration) -> ISODuration:
         return reference
 
 
+class FileNameFieldGeoBox(FileNameField, StringCodec, GeoBoxTester):
+    """Geobox value.
+
+    Geobox is a tuple (lon_min, lat_min, lon_max, lat_max) in °.
+
+    Attributes
+    ----------
+    name: str
+        name of the field
+    """
+
+
 class FieldFormatter(string.Formatter):
 
     def __init__(self, fields: dict[str, FileNameField]):