esgvoc 0.2.1__tar.gz → 0.3.0__tar.gz

{esgvoc-0.2.1 → esgvoc-0.3.0}/.github/workflows/docs.yml

@@ -3,7 +3,7 @@ name: documentation
 on:
   push:
     branches:
-      - integration
+      - documentation
     paths:
       - docs/**
       - src/**
@@ -28,7 +28,7 @@ jobs:
 
       - name: deploy
         uses: peaceiris/actions-gh-pages@v3
-        if: ${{ github.ref == 'refs/heads/integration' }}
+        if: ${{ github.ref == 'refs/heads/documentation' }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/build/html

esgvoc-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+default_language_version:
+    python: python3
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: '(setup.cfg|.svg)'
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: debug-statements
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.9.4
+    hooks:
+      # Run the linter.
+      - id: ruff
+        language_version: python3
+        args: [ --fix, --exit-non-zero-on-fix, --show-fixes ]
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort

{esgvoc-0.2.1 → esgvoc-0.3.0}/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.3
 Name: esgvoc
-Version: 0.2.1
+Version: 0.3.0
 Summary: python library and CLI to interact with WCRP CVs
 Project-URL: Repository, https://github.com/ESGF/esgf-vocab
 Author-email: Sébastien Gardoll <sebastien@gardoll.fr>, Guillaume Levavasseur <guillaume.levavasseur@ipsl.fr>, Laurent Troussellier <laurent.troussellier@ipsl.fr>
 License: CECILL-2.1
 Requires-Python: <3.13,>=3.12
 Requires-Dist: idna>=3.10
+Requires-Dist: platformdirs>=4.3.6
 Requires-Dist: pydantic>=2.9.2
 Requires-Dist: pyld>=2.0.4
 Requires-Dist: requests>=2.32.3
-Requires-Dist: sphinx-copybutton>=0.5.2
-Requires-Dist: sphinx-tabs>=3.4.7
 Requires-Dist: sqlalchemy>=2.0.36
 Requires-Dist: sqlmodel>=0.0.22
 Requires-Dist: toml>=0.10.2
@@ -56,3 +55,35 @@ Following this command to install or update the latest CVs.
 ```bash
 esgvoc install
 ```
+
+## How to contribute
+
+### Install Python dev environment
+
+* Pip
+
+```bash
+pip install -e .
+```
+
+* Rye
+
+```bash
+rye sync
+```
+
+### Linters & code formatters
+
+* Pip
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+* Rye
+
+```bash
+rye install
+rye run pre-commit install
+```

{esgvoc-0.2.1 → esgvoc-0.3.0}/README.md

@@ -36,3 +36,35 @@ Following this command to install or update the latest CVs.
 ```bash
 esgvoc install
 ```
+
+## How to contribute
+
+### Install Python dev environment
+
+* Pip
+
+```bash
+pip install -e .
+```
+
+* Rye
+
+```bash
+rye sync
+```
+
+### Linters & code formatters
+
+* Pip
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+* Rye
+
+```bash
+rye install
+rye run pre-commit install
+```

esgvoc-0.3.0/docs/source/api_documentation/data_descriptors.md

@@ -0,0 +1,21 @@
+# Data descriptors
+
+## Data descriptors
+
+```{eval-rst}
+.. automodule:: esgvoc.api.data_descriptors
+   :members:
+   :exclude-members: DataDescriptor
+   :inherited-members: BaseModel
+   :imported-members:
+   :member-order: groupwise
+```
+
+## Generic classes
+
+```{eval-rst}
+.. automodule:: esgvoc.api.data_descriptors.data_descriptor
+   :members:
+   :inherited-members: BaseModel
+   :member-order: groupwise
+```

{esgvoc-0.2.1 → esgvoc-0.3.0}/docs/source/api_documentation/drs.md

@@ -23,6 +23,6 @@
 ```{eval-rst}
 .. automodule:: esgvoc.apps.drs.report
    :members:
-   :inherited-members: BaseModel
+   :inherited-members: BaseModel, str, Enum
    :member-order: groupwise
-```
+```

esgvoc-0.3.0/docs/source/api_documentation/projects.md

@@ -0,0 +1,36 @@
+# Projects
+
+## Get, find and validation functions
+
+```{eval-rst}
+.. note::
+  Values are validated against the DRS name of the terms of the projects whereas find functions are based on the id of the terms.
+```
+
+```{eval-rst}
+.. automodule:: esgvoc.api.projects
+   :members:
+   :member-order: groupwise
+```
+
+## Validation reporting
+
+```{eval-rst}
+.. automodule:: esgvoc.api.report
+   :members:
+   :inherited-members: BaseModel
+   :member-order: groupwise
+```
+
+## Search settings
+
+```{eval-rst}
+.. automodule:: esgvoc.api.search
+   :members:
+   :member-order: groupwise
+```
+```{eval-rst}
+.. autoclass:: esgvoc.core.db.models.mixins.TermKind
+   :members:
+   :member-order: groupwise
+```

esgvoc-0.3.0/docs/source/api_documentation/universe.md

@@ -0,0 +1,9 @@
+# Universe
+
+## Get and find functions
+
+```{eval-rst}
+.. automodule:: esgvoc.api.universe
+   :members:
+   :member-order: groupwise
+```

{esgvoc-0.2.1 → esgvoc-0.3.0}/docs/source/guides/basics_drs.ipynb

@@ -254,7 +254,7 @@
     {
      "data": {
       "text/plain": [
-       "[missing token for time_range at position 7]"
+       "[missing term for time_range at position 7]"
       ]
      },
      "execution_count": 8,
@@ -271,7 +271,7 @@
    "id": "b9886b6b-baf1-444f-891f-766fafc911ca",
    "metadata": {},
    "source": [
-    "The validator supports a wild range issues, such as blank token:"
+    "The validator supports a wild range issues, such as blank term:"
    ]
   },
   {
@@ -285,7 +285,7 @@
      "output_type": "stream",
      "text": [
       "'CMIP6Plus/CMIP/ /NCC/MIROC6/amip/r2i2p1f2/ACmon/od550aer/gn/v20190923' has 1 error(s) and 0 warning(s)\n",
-      "report.errors=[blank token at column 16]\n"
+      "report.errors=[blank term at column 16]\n"
      ]
     }
    ],
@@ -301,7 +301,7 @@
    "id": "76ff0c16",
    "metadata": {},
    "source": [
-    "Extra tokens at the end of the expression or separator stuttering:"
+    "Extra terms at the end of the expression or separator stuttering:"
    ]
   },
   {
@@ -319,7 +319,7 @@
      "output_type": "stream",
      "text": [
       "'CMIP6Plus.CMIP.IPSL.MIROC6.amip..r2i2p1f2.ACmon.od550aer.gn.some_thing' has 2 error(s) and 0 warning(s)\n",
-      "report.errors=[extra separator(s) at column 33, extra token some_thing at position 9]\n"
+      "report.errors=[extra separator(s) at column 33, extra term some_thing at position 9]\n"
      ]
     }
    ],
@@ -353,7 +353,7 @@
      "output_type": "stream",
      "text": [
       "'CMIP6Plus/CMIP_ERROR_HERE/NCC/MIROC6/amip/r2i2p1f2/ACmon/od550aer/gn/v20190923' has 1 error(s) and 0 warning(s)\n",
-      "report.errors=[token 'CMIP_ERROR_HERE' not compliant with activity_id at position 2]\n"
+      "report.errors=[term 'CMIP_ERROR_HERE' not compliant with activity_id at position 2]\n"
      ]
     }
    ],
@@ -369,7 +369,7 @@
    "id": "3643f5ee-a11b-4bbb-a2b8-fd55ddfee003",
    "metadata": {},
    "source": [
-    "The validation issues can be processed by implementing a [parser issue visitor](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.ParserIssueVisitor) and a [validation issue visitor](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.ValidationIssueVisitor):"
+    "The validation issues can be processed by implementing a [parsing issue visitor](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.ParsingIssueVisitor) and a [compliance issue visitor](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.ComplianceIssueVisitor):"
    ]
   },
   {
@@ -382,17 +382,17 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Doing something automatically with a invalid token issue, rather then printing it\n"
+      "Doing something automatically with a invalid term issue, rather then printing it\n"
      ]
     }
    ],
    "source": [
     "class MyValidationVisitor:\n",
-    "    def visit_invalid_token_issue(self, issue):\n",
-    "        print('Doing something automatically with a invalid token issue, ' +\n",
+    "    def visit_invalid_term_issue(self, issue):\n",
+    "        print('Doing something automatically with a invalid term issue, ' +\n",
     "              'rather then printing it')\n",
-    "    # You should implement the other methods of ParserIssueVisitor and \n",
-    "    # ValidatorIssueVisitor too!\n",
+    "    # You should implement the other methods of ParsingIssueVisitor and \n",
+    "    # ComplianceIssueVisitor too!\n",
     "    # Read https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.ValidationIssueVisitor\n",
     "\n",
     "my_visitor = MyValidationVisitor()\n",
@@ -412,7 +412,7 @@
    "id": "d7e4c7ab-8578-4153-8fe8-e049f0febeaa",
    "metadata": {},
    "source": [
-    "The DRS generation consists of generate a DRS expression from an unordered mapping of collections and tokens or a bag of unordered tokens."
+    "The DRS generation consists of generate a DRS expression from an unordered mapping of collections and terms or a bag of unordered terms."
    ]
   },
   {
@@ -480,7 +480,7 @@
    "id": "c2455012-e8ce-44c7-9bee-19ffc4fe480f",
    "metadata": {},
    "source": [
-    "Build a dictionary that maps tokens with their collections:"
+    "Build a dictionary that maps terms with their collections:"
    ]
   },
   {
@@ -590,7 +590,7 @@
    "id": "0d8a263d-0e3e-483a-9a1b-9b8c8e7c5b94",
    "metadata": {},
    "source": [
-    "As for the DRS validation, the generator returns a report that you can display or visit (generator report [class](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.DrsGeneratorReport), generator visitor [specifications](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.GeneratorIssueVisitor)):"
+    "As for the DRS validation, the generator returns a report that you can display or visit (generation report [class](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.DrsGenerationReport), generator visitor [specifications](https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.GeneratorIssueVisitor)):"
    ]
   },
   {
@@ -603,7 +603,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "report.warnings=[missing token for time_range at position 7]\n"
+      "report.warnings=[missing term for time_range at position 7]\n"
      ]
     }
    ],
@@ -622,14 +622,14 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Doing something automatically with a missing token issue, rather then printing it\n"
+      "Doing something automatically with a missing term issue, rather then printing it\n"
      ]
     }
    ],
    "source": [
     "class MyGeneratorVisitor:\n",
-    "    def visit_missing_token_issue(self, issue):\n",
-    "            print('Doing something automatically with a missing token issue, ' +\n",
+    "    def visit_missing_term_issue(self, issue):\n",
+    "            print('Doing something automatically with a missing term issue, ' +\n",
     "                  'rather then printing it')\n",
     "    # You should implement the other methods of GeneratorIssueVisitor too!\n",
     "    # Read https://esgf.github.io/esgf-vocab/api_documentation/drs.html#esgvoc.apps.drs.report.GeneratorIssueVisitor\n",
@@ -690,8 +690,8 @@
      "output_type": "stream",
      "text": [
       "'od550aer_ACmon_[INVALID]_amip_[MISSING]_gn.nc' has 2 error(s) and 1 warning(s)\n",
-      "report.errors=[token 'MiRoC6' not compliant with source_id at position 3, missing token for member_id at position 5]\n",
-      "report.warnings=[missing token for time_range at position 7]\n"
+      "report.errors=[term 'MiRoC6' not compliant with source_id at position 3, missing term for member_id at position 5]\n",
+      "report.warnings=[missing term for time_range at position 7]\n"
      ]
     }
    ],
@@ -711,8 +711,8 @@
    "id": "e9c97077",
    "metadata": {},
    "source": [
-    "### Bag of tokens\n",
-    "The bag of tokens methods consist of generating a DRS expression from a set of unordered tokens. The generator try to build a mapping between the collections of the DRS specification target and the given tokens, then it generates an expression."
+    "### Bag of terms\n",
+    "The bag of terms methods consist of generating a DRS expression from a set of unordered terms. The generator try to build a mapping between the collections of the DRS specification target and the given terms, then it generates an expression."
    ]
   },
   {
@@ -729,7 +729,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "bag_of_tokens=['r2i2p1f2', 'CMIP', 'MIROC6', 'CMIP6Plus', 'amip', 'od550aer', 'ACmon', 'gn', 'v20190923', 'IPSL', 'some_value']\n"
+      "bag_of_terms=['r2i2p1f2', 'CMIP', 'MIROC6', 'CMIP6Plus', 'amip', 'od550aer', 'ACmon', 'gn', 'v20190923', 'IPSL', 'some_value']\n"
      ]
     },
     {
@@ -744,9 +744,9 @@
     }
    ],
    "source": [
-    "bag_of_tokens = list(mapping.values())\n",
-    "print(f'{bag_of_tokens=}')\n",
-    "generator.generate_from_bag_of_tokens(tokens=bag_of_tokens, drs_type='dataset_id')"
+    "bag_of_terms = list(mapping.values())\n",
+    "print(f'{bag_of_terms=}')\n",
+    "generator.generate_from_bag_of_terms(terms=bag_of_terms, drs_type='dataset_id')"
    ]
   },
   {
@@ -754,7 +754,7 @@
    "id": "aeff5174",
    "metadata": {},
    "source": [
-    "Due to the lack of precision of some term patterns, some tokens can fit to more than one collection or fit the same collection. The generator supports these cases and try to untangle tokens and collections as it is possible to be. Warnings are raised if the generator makes unobvious assignments. But most of the time, the generator will raise errors. **So the mapping methods should always be preferred**."
+    "Due to the lack of precision of some pattern terms, some terms can fit to more than one collection or fit the same collection. The generator supports these cases and try to untangle terms and collections as it is possible to be. Warnings are raised if the generator makes unobvious assignments. But most of the time, the generator will raise errors. **So the mapping methods should always be preferred**."
    ]
   },
   {
@@ -768,7 +768,7 @@
      "output_type": "stream",
      "text": [
       "'CMIP6Plus.CMIP.[MISSING].MIROC6.amip.r2i2p1f2.ACmon.od550aer.gn' has 2 error(s) and 0 warning(s)\n",
-      "report.errors=[collection institution_id has more than one token (IPSL, UA), missing token for institution_id at position 3]\n"
+      "report.errors=[collection institution_id has more than one term (IPSL, UA), missing term for institution_id at position 3]\n"
      ]
     }
    ],
@@ -777,9 +777,9 @@
     "# This leads to two kinds of error:\n",
     "#    - The collection institution_id has more than one choice.\n",
     "#    - As the generator cannot choose, UA and IPSL are withdrawn,\n",
-    "#      hence the missing token error.\n",
-    "bag_of_tokens.append('UA')\n",
-    "report = generator.generate_from_bag_of_tokens(tokens=bag_of_tokens,\n",
+    "#      hence the missing term error.\n",
+    "bag_of_terms.append('UA')\n",
+    "report = generator.generate_from_bag_of_terms(terms=bag_of_terms,\n",
     "                                               drs_type='dataset_id')\n",
     "print(report)\n",
     "print(f'{report.errors=}')"