esgvoc 0.1.2__tar.gz

esgvoc-0.1.2/.github/workflows/pypi-publish.yml

@@ -0,0 +1,33 @@
+
+name: pypi-publish
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  pypi-publish:
+    name: upload release to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # This permission is needed for private repositories.
+      contents: read
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install the latest version of rye
+        uses: eifinger/setup-rye@v4
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: rye sync
+
+      - name: Build package
+        run: rye build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

esgvoc-0.1.2/.gitignore

@@ -0,0 +1,21 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+mip-cmor-tables/
+sb.py
+# venv
+.venv
+*.lock
+*.sqlite
+.pdm-python
+.DS_Store
+.vscode
+tmp*
+.cache
+CHANGELOG.md
+.mise.toml
+.mise.toml

esgvoc-0.1.2/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.3
+Name: esgvoc
+Version: 0.1.2
+Summary: python library and CLI to interact with WCRP CV
+Project-URL: Repository, https://github.com/ESPRI-Mod/cmipld
+Author-email: TROUSSELLIER Laurent <laurent.troussellier@ipsl.fr>, Gardoll Sébastien <sebastien@gardoll.fr>
+Requires-Python: >=3.12
+Requires-Dist: idna>=3.10
+Requires-Dist: pydantic>=2.9.2
+Requires-Dist: pyld>=2.0.4
+Requires-Dist: requests>=2.32.3
+Requires-Dist: sqlalchemy>=2.0.36
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: toml>=0.10.2
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+
+# Esgvoc Library
+
+Esgvoc is a Python library designed to simplify interaction with controlled vocabularies (CVs) used in climate data projects. It supports querying, caching, and validating terms across various CV repositories like the Universe and project-specific repositories (e.g., CMIP6Plus).
+
+---
+
+## Features
+
+- **Query controlled vocabularies**:
+  - Retrieve terms, collections, or descriptors.
+  - Perform cross-validation and search operations.
+
+- **Caching**:
+  - Download CVs to a local database for offline use.
+  - Keep the local cache up-to-date.
+
+- **Validation**:
+  - Validate strings against CV terms and templates.
+  - Supports case-sensitive, wildcard, and approximate matching.
+
+---
+
+## Installation
+
+Esgvoc is available on PyPI. Install it with pip:
+
+```bash
+pip install esgvoc
+```
+
+in order to get the latest possible CV 
+
+
+```bash
+esgvoc install
+```

esgvoc-0.1.2/README.md

@@ -0,0 +1,37 @@
+
+# Esgvoc Library
+
+Esgvoc is a Python library designed to simplify interaction with controlled vocabularies (CVs) used in climate data projects. It supports querying, caching, and validating terms across various CV repositories like the Universe and project-specific repositories (e.g., CMIP6Plus).
+
+---
+
+## Features
+
+- **Query controlled vocabularies**:
+  - Retrieve terms, collections, or descriptors.
+  - Perform cross-validation and search operations.
+
+- **Caching**:
+  - Download CVs to a local database for offline use.
+  - Keep the local cache up-to-date.
+
+- **Validation**:
+  - Validate strings against CV terms and templates.
+  - Supports case-sensitive, wildcard, and approximate matching.
+
+---
+
+## Installation
+
+Esgvoc is available on PyPI. Install it with pip:
+
+```bash
+pip install esgvoc
+```
+
+in order to get the latest possible CV 
+
+
+```bash
+esgvoc install
+```

esgvoc-0.1.2/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "esgvoc"
+version = "0.1.2"
+description = "python library and CLI to interact with WCRP CV"
+authors = [
+    {name = "TROUSSELLIER Laurent", email = "laurent.troussellier@ipsl.fr"},
+    {name = "Gardoll Sébastien", email = "sebastien@gardoll.fr"}
+]
+dependencies = [
+    "idna>=3.10",
+    "pydantic>=2.9.2",
+    "sqlalchemy>=2.0.36",
+    "sqlmodel>=0.0.22",
+    "pyld>=2.0.4",
+    "requests>=2.32.3",
+    "toml>=0.10.2",
+    "typer>=0.15.0",
+]
+readme = "README.md"
+requires-python = ">= 3.12"
+
+[build-system]
+requires = ["hatchling==1.26.3"]
+build-backend = "hatchling.build"
+
+[project.urls]
+Repository = "https://github.com/ESPRI-Mod/cmipld"
+
+[tool.rye]
+managed = true
+dev-dependencies = [
+    "pytest>=8.3.3",
+    "jupyter-console>=6.6.3",
+    "mypy>=1.13.0",
+    "pytest-mock>=3.14.0",
+    "isort>=5.13.2",
+]
+[tool.rye.scripts]
+ev = { cmd = "python src/esgvoc/cli/main.py" }
+evc = { cmd = "python src/esgvoc/cli/main.py config" }
+evcp = { cmd = "python src/esgvoc/cli/main.py config projects." }
+evg = { cmd = "python src/esgvoc/cli/main.py get" }
+evs = {cmd = "python src/esgvoc/cli/main.py status"}
+evv = {cmd = "python src/esgvoc/cli/main.py valid"}
+
+[project.scripts]
+esgvoc = "esgvoc.cli.main:main" 
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/esgvoc"]
+
+[tool.pytest.ini_options]
+log_cli = true
+log_cli_level = "ERROR"
+log_cli_format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"

esgvoc-0.1.2/src/esgvoc/__init__.py

@@ -0,0 +1 @@
+import esgvoc.core.logging_handler

esgvoc-0.1.2/src/esgvoc/api/__init__.py

@@ -0,0 +1,62 @@
+from esgvoc.api.search import MatchingTerm, SearchType, SearchSettings
+from esgvoc.api.report import (ValidationError,
+                               ValidationReport,
+                               ValidationErrorVisitor,
+                               BasicValidationErrorVisitor,
+                               ProjectTermError,
+                               UniverseTermError)
+from esgvoc.api.universe import (get_all_terms_in_universe,
+                                 get_all_data_descriptors_in_universe,
+                                 find_data_descriptors_in_universe,
+                                 get_all_terms_in_data_descriptor,
+                                 find_terms_in_universe,
+                                 find_terms_in_data_descriptor)
+from esgvoc.api.projects import (get_all_projects,
+                                 find_project,
+                                 get_all_terms_in_all_projects,
+                                 get_all_terms_in_project,
+                                 get_all_collections_in_project,
+                                 find_collections_in_project,
+                                 get_all_terms_in_collection,
+                                 find_terms_in_project,
+                                 find_terms_in_all_projects,
+                                 find_terms_from_data_descriptor_in_all_projects,
+                                 find_terms_from_data_descriptor_in_project,
+                                 find_terms_in_collection,
+                                 valid_term_in_all_projects,
+                                 valid_term_in_project,
+                                 valid_term_in_collection,
+                                 valid_term)
+
+
+__all__ = ["MatchingTerm",
+           "SearchType",
+           "SearchSettings",
+           "ValidationError",
+           "ValidationReport",
+           "ValidationErrorVisitor",
+           "BasicValidationErrorVisitor",
+           "ProjectTermError",
+           "UniverseTermError",
+           "get_all_terms_in_universe",
+           "get_all_data_descriptors_in_universe",
+           "find_data_descriptors_in_universe",
+           "get_all_terms_in_data_descriptor",
+           "find_terms_in_universe",
+           "find_terms_in_data_descriptor",
+           "get_all_projects",
+           "find_project",
+           "get_all_terms_in_all_projects",
+           "get_all_terms_in_project",
+           "get_all_collections_in_project",
+           "find_collections_in_project",
+           "get_all_terms_in_collection",
+           "find_terms_in_project",
+           "find_terms_in_all_projects",
+           "find_terms_from_data_descriptor_in_all_projects",
+           "find_terms_from_data_descriptor_in_project",
+           "find_terms_in_collection",
+           "valid_term_in_all_projects",
+           "valid_term_in_project",
+           "valid_term_in_collection",
+           "valid_term"]

esgvoc-0.1.2/src/esgvoc/api/_utils.py

@@ -0,0 +1,39 @@
+from typing import Sequence
+
+
+import esgvoc.core.constants as api_settings
+from esgvoc.api.data_descriptors import DATA_DESCRIPTOR_CLASS_MAPPING
+from esgvoc.core.db.models.project import PTerm
+from esgvoc.core.db.models.universe import UTerm
+from pydantic import BaseModel
+from sqlmodel import Session
+
+import esgvoc.core.service as service
+UNIVERSE_DB_CONNECTION = service.state_service.universe.db_connection
+
+
+def get_pydantic_class(data_descriptor_id_or_term_type: str) -> type[BaseModel]:
+    if data_descriptor_id_or_term_type in DATA_DESCRIPTOR_CLASS_MAPPING:
+        return DATA_DESCRIPTOR_CLASS_MAPPING[data_descriptor_id_or_term_type]
+    else:
+        raise ValueError(f"{data_descriptor_id_or_term_type} pydantic class not found")
+
+
+def get_universe_session() -> Session:
+
+    if UNIVERSE_DB_CONNECTION:
+        return UNIVERSE_DB_CONNECTION.create_session()
+    else:
+        raise RuntimeError('universe connection is not initialized')
+
+
+def instantiate_pydantic_term(term: UTerm|PTerm) -> BaseModel:
+    term_class = get_pydantic_class(term.specs[api_settings.TERM_TYPE_JSON_KEY])
+    return term_class(**term.specs)
+
+
+def instantiate_pydantic_terms(db_terms: Sequence[UTerm|PTerm],
+                               list_to_populate: list[BaseModel]) -> None:
+    for db_term in db_terms:
+        term = instantiate_pydantic_term(db_term)
+        list_to_populate.append(term)

esgvoc-0.1.2/src/esgvoc/api/data_descriptors/__init__.py

@@ -0,0 +1,60 @@
+from pydantic import BaseModel
+
+from esgvoc.api.data_descriptors.activity import Activity
+from esgvoc.api.data_descriptors.consortium import Consortium
+from esgvoc.api.data_descriptors.date import Date
+from esgvoc.api.data_descriptors.experiment import Experiment 
+from esgvoc.api.data_descriptors.forcing_index import ForcingIndex
+from esgvoc.api.data_descriptors.frequency import Frequency
+from esgvoc.api.data_descriptors.grid_label import GridLabel 
+from esgvoc.api.data_descriptors.initialisation_index import InitialisationIndex 
+from esgvoc.api.data_descriptors.institution import Institution
+from esgvoc.api.data_descriptors.license import License 
+from esgvoc.api.data_descriptors.mip_era import MipEra
+from esgvoc.api.data_descriptors.model_component import ModelComponent
+from esgvoc.api.data_descriptors.organisation import Organisation 
+from esgvoc.api.data_descriptors.physic_index import PhysicIndex
+from esgvoc.api.data_descriptors.product import Product
+from esgvoc.api.data_descriptors.realisation_index import RealisationIndex 
+from esgvoc.api.data_descriptors.realm import Realm
+from esgvoc.api.data_descriptors.resolution import Resolution
+from esgvoc.api.data_descriptors.source import Source 
+from esgvoc.api.data_descriptors.source_type import SourceType 
+from esgvoc.api.data_descriptors.sub_experiment import SubExperiment
+from esgvoc.api.data_descriptors.table import Table 
+from esgvoc.api.data_descriptors.time_range import TimeRange 
+from esgvoc.api.data_descriptors.variable import Variable
+from esgvoc.api.data_descriptors.variant_label import VariantLabel
+
+
+DATA_DESCRIPTOR_CLASS_MAPPING: dict[str, type[BaseModel]] = {
+    "activity": Activity,
+    "consortium": Consortium,
+    "date": Date,
+    "experiment": Experiment, 
+    "forcing_index": ForcingIndex,
+    "frequency": Frequency,
+    "grid": GridLabel, # DEBUG: the value of the key type for the terms of the DD grid is not consistent.
+    "grid-label": GridLabel, # DEBUG: the value of the key type for the terms of the DD grid is not consistent.
+    "grid_label": GridLabel, # DEBUG: the value of the key type for the terms of the DD grid is not consistent.
+    "initialisation_index": InitialisationIndex, 
+    "institution": Institution,
+    "license": License,
+    "mip_era": MipEra,
+    "model_component": ModelComponent,
+    "organisation": Organisation, 
+    "physic_index": PhysicIndex,
+    "product": Product,
+    "realisation_index": RealisationIndex ,
+    "realm": Realm,
+    "resolution": Resolution,
+    "source": Source, 
+    "source_type": SourceType, 
+    "sub_experiment": SubExperiment,
+    "table" : Table,
+    "time_range": TimeRange,
+    "variable": Variable,
+    "real": Variable, # DEBUG: key type should be the pydantic class for the terms of DD variable!
+    "integer": Variable, # DEBUG: key type should be the pydantic class for the terms of DD variable!
+    "variant_label": VariantLabel
+}

esgvoc-0.1.2/src/esgvoc/api/data_descriptors/activity.py

@@ -0,0 +1,51 @@
+
+from __future__ import annotations 
+from typing import (
+    Optional
+)
+from pydantic.version import VERSION  as PYDANTIC_VERSION 
+if int(PYDANTIC_VERSION[0])>=2:
+    from pydantic import (
+        BaseModel,
+        ConfigDict,
+        Field
+    )
+else:
+    from pydantic import (
+        BaseModel,
+        Field
+    )
+
+metamodel_version = "None"
+version = "None"
+
+
+class ConfiguredBaseModel(BaseModel):
+    model_config = ConfigDict(
+        validate_assignment = True,
+        validate_default = True,
+        extra = "allow",
+        arbitrary_types_allowed = True,
+        use_enum_values = True,
+        strict = False,
+    )
+    pass
+
+
+
+class Activity(ConfiguredBaseModel):
+    """
+    an 'activity' refers to a coordinated set of modeling experiments designed to address specific scientific questions or objectives. Each activity is focused on different aspects of climate science and utilizes various models to study a wide range of climate phenomena. Activities are often organized around key research themes and may involve multiple experiments, scenarios, and model configurations.
+    """
+
+    id: str 
+    validation_method: str = Field(default = "list")
+    name: str 
+    long_name: str 
+    cmip_acronym: str 
+    url: Optional[str] 
+
+
+# Model rebuild
+# see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model
+Activity.model_rebuild()

esgvoc-0.1.2/src/esgvoc/api/data_descriptors/consortium.py

@@ -0,0 +1,66 @@
+
+from __future__ import annotations 
+from typing import (
+    List,
+    Optional,
+    Union
+)
+from pydantic.version import VERSION  as PYDANTIC_VERSION 
+if int(PYDANTIC_VERSION[0])>=2:
+    from pydantic import (
+        BaseModel,
+        ConfigDict,
+        Field
+    )
+else:
+    from pydantic import (
+        BaseModel,
+        Field
+    )
+
+metamodel_version = "None"
+version = "None"
+
+
+class ConfiguredBaseModel(BaseModel):
+    model_config = ConfigDict(
+        validate_assignment = True,
+        validate_default = True,
+        extra = "allow",
+        arbitrary_types_allowed = True,
+        use_enum_values = True,
+        strict = False,
+    )
+    pass
+
+
+class Dates(ConfiguredBaseModel):
+
+    phase : str
+    from_ : int = Field(...,alias="from") # cause from is a keyword
+    to: Union[int,str]
+    
+
+class Member(ConfiguredBaseModel):
+    
+    type : str
+    institution : str # id 
+    dates : List[Dates] = Field(default_factory=list)
+    membership_type : str # prior, current
+
+class Consortium(ConfiguredBaseModel):
+
+    id: str 
+    validation_method: str = Field(default = "list")
+    type: str
+    name: Optional[str] = None 
+    cmip_acronym: str = Field(...,alias="cmip-acronym") 
+    status : Optional[str] = None
+    changes : Optional[str]
+    members : List[Member] = Field(default_factory=list)
+    url: Optional[str] 
+
+
+# Model rebuild
+# see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model
+Consortium.model_rebuild()

esgvoc-0.1.2/src/esgvoc/api/data_descriptors/date.py

@@ -0,0 +1,48 @@
+
+
+
+
+
+
+
+from __future__ import annotations 
+from pydantic.version import VERSION  as PYDANTIC_VERSION 
+if int(PYDANTIC_VERSION[0])>=2:
+    from pydantic import (
+        BaseModel,
+        ConfigDict
+    )
+else:
+    from pydantic import (
+        BaseModel
+    )
+
+metamodel_version = "None"
+version = "None"
+
+
+class ConfiguredBaseModel(BaseModel):
+    model_config = ConfigDict(
+        validate_assignment = True,
+        validate_default = True,
+        extra = "allow",
+        arbitrary_types_allowed = True,
+        use_enum_values = True,
+        strict = False,
+    )
+    pass
+
+
+
+
+
+class Date(ConfiguredBaseModel):
+
+
+
+    id: str 
+    type : str 
+    regex : str
+# Model rebuild
+# see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model
+Date.model_rebuild()

esgvoc-0.1.2/src/esgvoc/api/data_descriptors/experiment.py

@@ -0,0 +1,60 @@
+
+from __future__ import annotations 
+from typing import (
+    List,
+    Optional
+)
+from pydantic.version import VERSION  as PYDANTIC_VERSION 
+if int(PYDANTIC_VERSION[0])>=2:
+    from pydantic import (
+        BaseModel,
+        ConfigDict,
+        Field
+    )
+else:
+    from pydantic import (
+        BaseModel,
+        Field
+    )
+
+metamodel_version = "None"
+version = "None"
+
+
+class ConfiguredBaseModel(BaseModel):
+    model_config = ConfigDict(
+        validate_assignment = True,
+        validate_default = True,
+        extra = "allow",
+        arbitrary_types_allowed = True,
+        use_enum_values = True,
+        strict = False,
+    )
+    pass
+
+
+class Experiment(ConfiguredBaseModel):
+    """
+    an 'experiment' refers to a specific, controlled simulation conducted using climate models to investigate particular aspects of the Earth's climate system. These experiments are designed with set parameters, such as initial conditions, external forcings (like greenhouse gas concentrations or solar radiation), and duration, to explore and understand climate behavior under various scenarios and conditions.
+    """
+
+    id: str 
+    validation_method: str = Field(default ="list")
+    activity: List[str] = Field(default_factory=list)
+    description: str 
+    tier: Optional[int] 
+    experiment_id: str 
+    sub_experiment_id: Optional[List[str]] 
+    experiment: str 
+    required_model_components: Optional[List[str]] 
+    additionnal_allowed_model_components: Optional[List[str]] = Field(default_factory=list) 
+    start_year: Optional[int] 
+    end_year: Optional[int] 
+    min_number_yrs_per_sim: Optional[int] 
+    parent_activity_id: Optional[List[str]] 
+    parent_experiment_id: Optional[List[str]] 
+
+
+# Model rebuild
+# see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model
+Experiment.model_rebuild()

esgvoc-0.1.2/src/esgvoc/api/data_descriptors/forcing_index.py

@@ -0,0 +1,47 @@
+
+
+
+
+
+
+from __future__ import annotations 
+from pydantic.version import VERSION  as PYDANTIC_VERSION 
+if int(PYDANTIC_VERSION[0])>=2:
+    from pydantic import (
+        BaseModel,
+        ConfigDict
+    )
+else:
+    from pydantic import (
+        BaseModel
+    )
+
+metamodel_version = "None"
+version = "None"
+
+
+class ConfiguredBaseModel(BaseModel):
+    model_config = ConfigDict(
+        validate_assignment = True,
+        validate_default = True,
+        extra = "allow",
+        arbitrary_types_allowed = True,
+        use_enum_values = True,
+        strict = False,
+    )
+    pass
+
+
+
+
+
+class ForcingIndex(ConfiguredBaseModel):
+
+
+
+    id: str 
+    type : str 
+    regex : str
+# Model rebuild
+# see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model
+ForcingIndex.model_rebuild()

esgvoc-0.1.2/src/esgvoc/api/data_descriptors/frequency.py

@@ -0,0 +1,45 @@
+
+from __future__ import annotations 
+from pydantic.version import VERSION  as PYDANTIC_VERSION 
+if int(PYDANTIC_VERSION[0])>=2:
+    from pydantic import (
+        BaseModel,
+        ConfigDict
+    )
+else:
+    from pydantic import (
+        BaseModel
+    )
+
+metamodel_version = "None"
+version = "None"
+
+
+class ConfiguredBaseModel(BaseModel):
+    model_config = ConfigDict(
+        validate_assignment = True,
+        validate_default = True,
+        extra = "allow",
+        arbitrary_types_allowed = True,
+        use_enum_values = True,
+        strict = False,
+    )
+    pass
+
+
+
+
+
+class Frequency(ConfiguredBaseModel):
+
+
+
+    id: str 
+    description :str
+    long_name :str 
+    name : str 
+    unit : str 
+    type : str 
+# Model rebuild
+# see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model
+Frequency.model_rebuild()