esgvoc 0.3.0__tar.gz → 0.4.0__tar.gz

esgvoc-0.4.0/.flake8

@@ -0,0 +1,3 @@
+[flake8]
+exclude = tests/*.py
+max-line-length = 120

{esgvoc-0.3.0 → esgvoc-0.4.0}/.gitignore

@@ -27,3 +27,4 @@ tmp*
 *.py[oc]
 sb.py
 CHANGELOG.md
+.coverage

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

@@ -0,0 +1,36 @@
+default_language_version:
+    python: python3
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: '(setup.cfg|.svg|.md)'
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: debug-statements
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.11.0
+    hooks:
+      # Run the linter.
+      - id: ruff
+        language_version: python3
+        args: [ --exit-non-zero-on-fix ]
+      # Sort imports.
+      - id: ruff
+        name: ruff-sort-imports
+        args: [--select, I, --fix]
+  - repo: local
+    hooks:
+    -   id: wily
+        name: wily
+        entry: wily diff
+        verbose: true
+        language: python
+        additional_dependencies: [wily]
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.2
+    hooks:
+      - id: flake8

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: esgvoc
-Version: 0.3.0
+Version: 0.4.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>

esgvoc-0.4.0/docs/source/api_documentation/miscellaneous.md

@@ -0,0 +1,18 @@
+# Miscellaneous
+
+```{eval-rst}
+.. automodule:: esgvoc.api.search
+   :members: Item
+   :imported-members:
+   :member-order: groupwise
+.. autoclass:: esgvoc.api.search.ItemKind
+   :members:
+   :member-order: groupwise
+.. autoclass:: esgvoc.core.db.models.mixins.TermKind
+   :members:
+   :member-order: groupwise
+.. automodule:: esgvoc.core.exceptions
+   :members:
+   :imported-members:
+   :member-order: groupwise
+```

{esgvoc-0.3.0 → esgvoc-0.4.0}/docs/source/api_documentation/projects.md

@@ -21,16 +21,3 @@
    :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 → esgvoc-0.4.0}/docs/source/guides/basics_esgvoc.ipynb

@@ -9,7 +9,7 @@
     {
      "data": {
       "text/plain": [
-       "datetime.datetime(2025, 3, 10, 10, 50, 58, 666709)"
+       "datetime.datetime(2025, 3, 21, 11, 3, 21, 470482)"
       ]
      },
      "execution_count": 1,
@@ -19,6 +19,7 @@
    ],
    "source": [
     "from datetime import datetime\n",
+    "\n",
     "datetime.now()"
    ]
   },
@@ -84,8 +85,8 @@
     "\n",
     "The API functions are sorted as follows:\n",
     "\n",
-    "- **get** functions return a list of something (collections from a project, terms from a collection, etc.)\n",
-    "- **find** functions try to find terms corresponding to an input string.  \n",
+    "- **get** functions return a list of something based on an id (collections from a project, terms from a collection, etc.)\n",
+    "- **find** functions try to find terms, data descriptors or collections corresponding to an expression.  \n",
     "- **valid** functions check the compliance of an input string to the DRS of terms."
    ]
   },
@@ -142,7 +143,6 @@
        " 'vertical_label',\n",
        " 'source',\n",
        " 'date',\n",
-       " 'branded_variable',\n",
        " 'model_component',\n",
        " 'product',\n",
        " 'institution',\n",
@@ -150,7 +150,6 @@
        " 'time_range',\n",
        " 'table',\n",
        " 'variant_label',\n",
-       " 'branded_suffix',\n",
        " 'organisation',\n",
        " 'experiment',\n",
        " 'area_label',\n",
@@ -187,7 +186,7 @@
     }
    ],
    "source": [
-    "ev.get_all_terms_in_data_descriptor(data_descriptor_id=\"activity\")[:3] \n",
+    "ev.get_all_terms_in_data_descriptor(data_descriptor_id=\"activity\")[:3]\n",
     "# each datadescriptor from the above cell could be use as argument\n",
     "# [:3] just to limit the result with the 3 first one"
    ]
@@ -201,7 +200,7 @@
     {
      "data": {
       "text/plain": [
-       "[Activity(id='aerchemmip', type='activity', drs_name='AerChemMIP', name='AerChemMIP', long_name='Aerosols and Chemistry Model Intercomparison Project', url=None, @context='000_context.jsonld', cmip_acronym='AerChemMIP')]"
+       "Activity(id='aerchemmip', type='activity', drs_name='AerChemMIP', name='AerChemMIP', long_name='Aerosols and Chemistry Model Intercomparison Project', url=None, @context='000_context.jsonld', cmip_acronym='AerChemMIP')"
       ]
      },
      "execution_count": 5,
@@ -210,7 +209,7 @@
     }
    ],
    "source": [
-    "ev.find_terms_in_data_descriptor(data_descriptor_id=\"activity\", term_id=\"aerchemmip\") "
+    "ev.get_term_in_data_descriptor(data_descriptor_id=\"activity\", term_id=\"aerchemmip\")"
    ]
   },
   {
@@ -247,7 +246,7 @@
     }
    ],
    "source": [
-    "my_activity = ev.find_terms_in_data_descriptor(data_descriptor_id=\"activity\", term_id=\"aerchemmip\")[0]\n",
+    "my_activity = ev.get_term_in_data_descriptor(data_descriptor_id=\"activity\", term_id=\"aerchemmip\")\n",
     "print(my_activity.id)\n",
     "print(my_activity.drs_name)\n",
     "print(my_activity.long_name)\n",
@@ -263,7 +262,7 @@
     {
      "data": {
       "text/plain": [
-       "[Activity(id='aerchemmip', type='activity', drs_name='AerChemMIP', name='AerChemMIP', long_name='Aerosols and Chemistry Model Intercomparison Project', url=None, @context='000_context.jsonld', cmip_acronym='AerChemMIP')]"
+       "Activity(id='aerchemmip', type='activity', drs_name='AerChemMIP', name='AerChemMIP', long_name='Aerosols and Chemistry Model Intercomparison Project', url=None, @context='000_context.jsonld', cmip_acronym='AerChemMIP')"
       ]
      },
      "execution_count": 7,
@@ -272,7 +271,105 @@
     }
    ],
    "source": [
-    "ev.find_terms_in_universe(term_id=\"aerchemmip\") # give the same result as above"
+    "ev.get_term_in_universe(term_id=\"aerchemmip\") # give the same result as above"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f8cfc8db",
+   "metadata": {},
+   "source": [
+    "### Find terms in universe"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "80475d91",
+   "metadata": {},
+   "source": [
+    "The find functions perform full text search (FTS) over terms or data descriptor specs. They accept expressions composed not only of keywords but boolean operators that relate them together. The result is sorted according to the hit rank (bm25): the first term in the list is the better match (index zero)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "c53bbf14",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[DataDescriptorSubSet(id='ipsl', type='institution', location={'city': 'Paris', 'country': ['France', 'FR'], 'lat': 48.855675, 'lon': 2.332105})]"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# The headquarter of the institution IPSL and the CNES are both located in Paris.\n",
+    "# We want to find the term which corresponds to the IPSL institution, but not the CNES one:\n",
+    "ev.find_terms_in_data_descriptor(expression='pArIs NOT CNES',\n",
+    "                                 data_descriptor_id='institution',\n",
+    "                                 selected_term_fields=['location'])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "73f624f4",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[DataDescriptorSubSet(id='ipsl', type='institution', location={'city': 'Paris', 'country': ['France', 'FR'], 'lat': 48.855675, 'lon': 2.332105}),\n",
+       " DataDescriptorSubSet(id='institution/ipsl', type='institution', location={'city': 'Paris', 'country': ['France', 'FR'], 'lat': 48.855675, 'lon': 2.332105})]"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We can also search in the whole universe, but expect to find many more terms:\n",
+    "ev.find_terms_in_universe(expression='pArIs NOT CNES',\n",
+    "                          selected_term_fields=['location'])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ab8e31bf",
+   "metadata": {},
+   "source": [
+    "### Find terms or data decriptors in universe"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "c205dff9",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[Item(id='daily', kind=<ItemKind.TERM: 'term'>, parent_id='time_range'),\n",
+       " Item(id='monthly', kind=<ItemKind.TERM: 'term'>, parent_id='time_range'),\n",
+       " Item(id='hourly', kind=<ItemKind.TERM: 'term'>, parent_id='time_range'),\n",
+       " Item(id='time_range', kind=<ItemKind.DATA_DESCRIPTOR: 'data_descriptor'>, parent_id='universe')]"
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We want to find the data descriptors time_range and its terms:\n",
+    "ev.find_items_in_universe(expression='time_range')"
    ]
   },
   {
@@ -283,9 +380,17 @@
     "## Project example: CMIP6plus"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "173137f6",
+   "metadata": {},
+   "source": [
+    "The API provides the same functions for the projects (get, find) and adds the validation functions."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 11,
    "id": "d12f6c7e-081d-42eb-922f-64e84a999e26",
    "metadata": {},
    "outputs": [
@@ -295,7 +400,7 @@
        "['cmip6', 'cmip6plus']"
       ]
      },
-     "execution_count": 8,
+     "execution_count": 11,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -306,7 +411,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 12,
    "id": "d92926f3-7494-4219-9f74-eb5dabe5a134",
    "metadata": {},
    "outputs": [
@@ -326,7 +431,7 @@
        " 'variable_id']"
       ]
      },
-     "execution_count": 9,
+     "execution_count": 12,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -337,7 +442,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 13,
    "id": "8cef4296-b9a6-42a9-8c2b-d52eeda55aa2",
    "metadata": {},
    "outputs": [
@@ -348,7 +453,7 @@
        " Activity(id='lesfmip', type='activity', drs_name='LESFMIP', name='LESFMIP', long_name='The Large Ensemble Single Forcing Model Intercomparison Project', url='https://www.frontiersin.org/articles/10.3389/fclim.2022.955414/full', @context='000_context.jsonld', cmip_acronym='LESFMIP')]"
       ]
      },
-     "execution_count": 10,
+     "execution_count": 13,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -359,23 +464,115 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 14,
    "id": "f99b6067-e323-4fa9-b423-d64e072ebe31",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "[Activity(id='cmip', type='activity', drs_name='CMIP', name='CMIP', long_name='CMIP DECK: 1pctCO2, abrupt4xCO2, amip, esm-piControl, esm-historical, historical, and piControl experiments', url='https://gmd.copernicus.org/articles/9/1937/2016/gmd-9-1937-2016.pdf', @context='000_context.jsonld', cmip_acronym='CMIP')]"
+       "Activity(id='cmip', type='activity', drs_name='CMIP', name='CMIP', long_name='CMIP DECK: 1pctCO2, abrupt4xCO2, amip, esm-piControl, esm-historical, historical, and piControl experiments', url='https://gmd.copernicus.org/articles/9/1937/2016/gmd-9-1937-2016.pdf', @context='000_context.jsonld', cmip_acronym='CMIP')"
       ]
      },
-     "execution_count": 11,
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "ev.get_term_in_collection(project_id=\"cmip6plus\", collection_id=\"activity_id\", term_id=\"cmip\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f20b9976",
+   "metadata": {},
+   "source": [
+    "### Find terms in a project"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "id": "8bdd8a84",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[DataDescriptorSubSet(id='miroc6', type='source'),\n",
+       " DataDescriptorSubSet(id='miroc', type='organisation')]"
+      ]
+     },
+     "execution_count": 15,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ev.find_terms_in_collection(project_id=\"cmip6plus\", collection_id=\"activity_id\", term_id=\"cmip\")"
+    "# We want to find all the term related to miroc:\n",
+    "ev.find_terms_in_project(expression='mir*', project_id='cmip6plus', selected_term_fields=[])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c386b5a7",
+   "metadata": {},
+   "source": [
+    "### Find terms and collections"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "635337a7",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "number of items: 41\n",
+      "id='institution_id' kind=<ItemKind.COLLECTION: 'collection'> parent_id='cmip6plus'\n"
+     ]
+    }
+   ],
+   "source": [
+    "# We want to find the collection named 'institution_id'\n",
+    "items_found = ev.find_items_in_project(expression='instit*', project_id='cmip6plus')\n",
+    "print(f'number of items: {len(items_found)}')\n",
+    "for item in items_found:\n",
+    "    if item.kind == 'collection':\n",
+    "        break\n",
+    "print(item)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "id": "fe8ad2ca",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[('institution_id',\n",
+       "  {'@context': {'id': '@id',\n",
+       "    'type': '@type',\n",
+       "    '@base': 'https://espri-mod.github.io/mip-cmor-tables/organisation/',\n",
+       "    'organisation': 'https://espri-mod.github.io/mip-cmor-tables/organisation',\n",
+       "    'myprop': 'http://TEST',\n",
+       "    'established': {'@id': 'https://schema.org/foundingDate'}}})]"
+      ]
+     },
+     "execution_count": 17,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# But we probably should execute this function:\n",
+    "ev.find_collections_in_project(expression='instit*', project_id='cmip6plus')"
    ]
   },
   {
@@ -388,13 +585,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 18,
    "id": "79a4d58e-3560-4c8c-aef3-9a1e80e862a4",
    "metadata": {},
    "outputs": [],
    "source": [
     "valid_string = \"IPSL\" # the standard name of the institution : \"Institut Pierre Simon Laplace\"\n",
-    "unvalid_string = \"ipsl\" # NOT the DRS name ! but in that case it is the 'id' of the term "
+    "unvalid_string = \"ipsl\" # NOT the DRS name ! but in that case it is the 'id' of the term"
    ]
   },
   {
@@ -407,7 +604,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 19,
    "id": "d67f80f0-ed4e-4c15-9c22-0cf00c2b20be",
    "metadata": {},
    "outputs": [
@@ -417,7 +614,7 @@
        "[MatchingTerm(project_id='cmip6plus', collection_id='institution_id', term_id='ipsl')]"
       ]
      },
-     "execution_count": 13,
+     "execution_count": 19,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -428,7 +625,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 20,
    "id": "16cdaf0a-17b3-4080-a910-6e590cafb0d0",
    "metadata": {},
    "outputs": [
@@ -438,7 +635,7 @@
        "[]"
       ]
      },
-     "execution_count": 14,
+     "execution_count": 20,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -449,7 +646,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 21,
    "id": "3c7a93a7-72b2-485b-ad62-9c95ff5098c2",
    "metadata": {},
    "outputs": [
@@ -470,7 +667,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 22,
    "id": "698f1676-036c-4999-91e2-360fe6e3aa2f",
    "metadata": {},
    "outputs": [
@@ -499,7 +696,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 23,
    "id": "44ddebd5-5cfb-4cae-8177-6d58422892c1",
    "metadata": {},
    "outputs": [
@@ -509,7 +706,7 @@
        "[MatchingTerm(project_id='cmip6plus', collection_id='institution_id', term_id='ipsl')]"
       ]
      },
-     "execution_count": 17,
+     "execution_count": 23,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -528,7 +725,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 24,
    "id": "5b485f84-bb45-49f8-b425-59d848079635",
    "metadata": {},
    "outputs": [

{esgvoc-0.3.0 → esgvoc-0.4.0}/docs/source/how_to/get.rst

@@ -27,8 +27,8 @@ One term
 
          import esgvoc.api as ev
 
-         ev.find_terms_in_data_descriptor(data_descriptor_id="institution", term_id="ipsl")
-         ev.find_terms_in_universe(term_id="ipsl") # same result but slower (still fast)
+         ev.get_term_in_data_descriptor(data_descriptor_id="institution", term_id="ipsl")
+         ev.get_term_in_universe(term_id="ipsl") # same result but slower but still fast
       .. image:: ../_static/Jup_one_term.png
 
 
@@ -98,9 +98,9 @@ A term from a CV
 
                 import esgvoc.api as ev
 
-                ev.find_terms_in_universe("ipsl")
-                ev.find_terms_in_project("cmip6","ipsl")
-                ev.find_terms_in_project("cmip6plus","ipsl")
+                ev.get_term_in_universe("ipsl")
+                ev.get_term_in_project("cmip6", "ipsl")
+                ev.get_term_in_project("cmip6plus", "ipsl")
 
         .. image:: ../_static/Jup_one_term_from_one_CV.png
 

{esgvoc-0.3.0 → esgvoc-0.4.0}/docs/source/index.md

@@ -113,4 +113,5 @@ api_documentation/projects.md
 api_documentation/project_specs.md
 api_documentation/drs.md
 api_documentation/data_descriptors.md
+api_documentation/miscellaneous.md
 ```

{esgvoc-0.3.0 → esgvoc-0.4.0}/docs/source/user/api.md

@@ -9,15 +9,16 @@ The ESGVOC Python API provides a powerful and read-only interface to query contr
 The API offers three main types of functions:
 
 1. **Retrieve functions (`get_*`)**
-   - Fetch collections, terms, or data descriptors.
+   - Fetch collections, terms or data descriptors.
    - Examples:
      - Retrieve all data descriptors in the universe CV.
      - Retrieve all terms within a specific collection or project.
+     - Retrieve a collection in a specific project.
 
 2. **Search functions (`find_*`)**
-   - Search for terms based on input strings.
+   - Search for terms based on expression (keywords, wildcard * and boolean operators).
    - Examples:
-     - Search for a specific term in a data descriptor.
+     - Search for terms in a data descriptor.
      - Search for terms within a project or collection.
 
 3. **Validation functions (`valid_*`)**
@@ -36,16 +37,28 @@ import esgvoc.api as ev
 # Retrieve Functions
 ev.get_all_data_descriptors_in_universe()
 ev.get_all_terms_in_data_descriptor(data_descriptor_id="activity")
+ev.get_term_in_universe(term_id='ipsl')
+ev.get_term_in_data_descriptor(data_descriptor_id='institution', term_id='ipsl')
+ev.get_data_descriptor_in_universe(data_descriptor_id='variable')
 
 ev.get_all_projects()
 ev.get_all_collections_in_project(project_id="cmip6plus")
 ev.get_all_terms_in_collection(project_id="cmip6plus", collection_id="activity_id")
+ev.get_project(project_id='cmip6')
+ev.get_term_in_project(project_id='cmip6', term_id='ipsl')
+ev.get_term_in_collection(project_id='cmip6', collection_id='institution_id', term_id='ipsl')
+ev.get_collection_in_project(project_id='cmip6', collection_id='variable_id')
 
 # Search Functions
-ev.find_terms_in_data_descriptor(data_descriptor_id="activity", term_id="aerchemmip")
-ev.find_terms_in_universe(term_id="aerchemmip")
-ev.find_terms_in_collection(project_id="cmip6plus", collection_id="activity_id", term_id="cmip")
-
+ev.find_data_descriptors_in_universe(expression='var*')
+ev.find_terms_in_data_descriptor(expression='aerchemmip', data_descriptor_id="activity")
+ev.find_terms_in_universe(expression="aer*mip")
+ev.find_items_in_universe(expression='ParIS NOT CNES')
+
+ev.find_collections_in_project(expression='_id', project_id='cmip6')
+ev.find_terms_in_collection(expression='aerchemmip', project_id='cmip6', collection_id="activity")
+ev.find_terms_in_project(expression="aer*mip", project_id='cmip6')
+ev.find_items_in_project(expression='ParIS AND ipsl', project_id='cmip6', limit=10)
 # Validation Functions
 ev.valid_term_in_collection(value="ipsl", project_id="cmip6plus", collection_id="institution_id")
 ev.valid_term_in_project(value="some_term", project_id="cmip6plus")