esgvoc 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

esgvoc/__init__.py

@@ -1 +1,3 @@
-import esgvoc.core.logging_handler
+import esgvoc.core.logging_handler  # noqa
+
+__version__ = "0.3.0"

esgvoc/api/__init__.py

@@ -1,38 +1,26 @@
-from esgvoc.api.search import MatchingTerm, SearchType, SearchSettings
-from esgvoc.api.report import (ValidationError,
-                               ValidationReport,
-                               ValidationErrorVisitor,
-                               ProjectTermError,
-                               UniverseTermError)
-from esgvoc.api.universe import (get_all_terms_in_universe,
+from esgvoc.api._utils import APIException
+from esgvoc.api.project_specs import (DrsCollection, DrsConstant, DrsPart,
+                                      DrsPartKind, DrsSpecification, DrsType,
+                                      ProjectSpecs)
+from esgvoc.api.projects import (
+    find_collections_in_project, find_project,
+    find_terms_from_data_descriptor_in_all_projects,
+    find_terms_from_data_descriptor_in_project, find_terms_in_all_projects,
+    find_terms_in_collection, find_terms_in_project,
+    get_all_collections_in_project, get_all_projects,
+    get_all_terms_in_all_projects, get_all_terms_in_collection,
+    get_all_terms_in_project, valid_term, valid_term_in_all_projects,
+    valid_term_in_collection, valid_term_in_project)
+from esgvoc.api.report import (ProjectTermError, UniverseTermError,
+                               ValidationError, ValidationErrorVisitor,
+                               ValidationReport)
+from esgvoc.api.search import MatchingTerm, SearchSettings, SearchType
+from esgvoc.api.universe import (find_data_descriptors_in_universe,
+                                 find_terms_in_data_descriptor,
+                                 find_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)
-from esgvoc.api.project_specs import (DrsType,
-                               DrsPartKind,
-                               DrsConstant,
-                               DrsCollection,
-                               DrsPart,
-                               DrsSpecification,
-                               ProjectSpecs)
+                                 get_all_terms_in_universe)
 
 __all__ = ["MatchingTerm",
            "SearchType",
@@ -70,4 +58,5 @@ __all__ = ["MatchingTerm",
            "DrsCollection",
            "DrsPart",
            "DrsSpecification",
-           "ProjectSpecs"]
+           "ProjectSpecs",
+           "APIException"]

esgvoc/api/_utils.py

@@ -1,39 +1,53 @@
-from typing import Sequence
+from typing import Iterable, MutableSequence
 
+from sqlmodel import Session
 
 import esgvoc.core.constants as api_settings
+import esgvoc.core.service as service
 from esgvoc.api.data_descriptors import DATA_DESCRIPTOR_CLASS_MAPPING
+from esgvoc.api.data_descriptors.data_descriptor import (DataDescriptor,
+                                                         DataDescriptorSubSet)
 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
 
+class APIException(Exception): ...
 
-def get_pydantic_class(data_descriptor_id_or_term_type: str) -> type[BaseModel]:
+
+def get_pydantic_class(data_descriptor_id_or_term_type: str) -> type[DataDescriptor]:
     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")
+        raise RuntimeError(f"{data_descriptor_id_or_term_type} pydantic class not found")
 
 
 def get_universe_session() -> Session:
-
+    
+    UNIVERSE_DB_CONNECTION = service.current_state.universe.db_connection
     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_term(term: UTerm|PTerm,
+                              selected_term_fields: Iterable[str]|None) -> DataDescriptor:
+    type = term.specs[api_settings.TERM_TYPE_JSON_KEY]
+    if selected_term_fields:
+        subset = DataDescriptorSubSet(id=term.id, type=type)
+        for field in selected_term_fields:
+            setattr(subset, field, term.specs.get(field, None))
+        for field in DataDescriptorSubSet.MANDATORY_TERM_FIELDS:
+            setattr(subset, field, term.specs.get(field, None))
+        return subset
+    else:
+        term_class = get_pydantic_class(type)
+        return term_class(**term.specs)
 
 
-def instantiate_pydantic_terms(db_terms: Sequence[UTerm|PTerm],
-                               list_to_populate: list[BaseModel]) -> None:
+def instantiate_pydantic_terms(db_terms: Iterable[UTerm|PTerm],
+                               list_to_populate: MutableSequence[DataDescriptor],
+                               selected_term_fields: Iterable[str]|None) -> None:
     for db_term in db_terms:
-        term = instantiate_pydantic_term(db_term)
+        term = instantiate_pydantic_term(db_term, selected_term_fields)
         list_to_populate.append(term)

esgvoc/api/data_descriptors/__init__.py

@@ -1,9 +1,8 @@
-from esgvoc.api.data_descriptors.directory_date import DirectoryDate
-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.data_descriptor import DataDescriptor
 from esgvoc.api.data_descriptors.date import Date
+from esgvoc.api.data_descriptors.directory_date import DirectoryDate
 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
@@ -26,10 +25,14 @@ 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
-from esgvoc.api.data_descriptors.directory_date import DirectoryDate
-
+from esgvoc.api.data_descriptors.area_label import AreaLabel
+from esgvoc.api.data_descriptors.vertical_label import VerticalLabel
+from esgvoc.api.data_descriptors.horizontal_label import HorizontalLabel
+from esgvoc.api.data_descriptors.temporal_label import TemporalLabel
+from esgvoc.api.data_descriptors.branded_suffix import BrandedSuffix
+from esgvoc.api.data_descriptors.branded_variable import BrandedVariable
 
-DATA_DESCRIPTOR_CLASS_MAPPING: dict[str, type[BaseModel]] = {
+DATA_DESCRIPTOR_CLASS_MAPPING: dict[str, type[DataDescriptor]] = {
     "activity": Activity,
     "consortium": Consortium,
     "date": Date,
@@ -37,9 +40,8 @@ DATA_DESCRIPTOR_CLASS_MAPPING: dict[str, type[BaseModel]] = {
     "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.
+    "grid": GridLabel,#Universe
+    "grid_label": GridLabel, # cmip6, cmip6plus
     "initialisation_index": InitialisationIndex, 
     "institution": Institution,
     "license": License,
@@ -57,7 +59,11 @@ DATA_DESCRIPTOR_CLASS_MAPPING: dict[str, type[BaseModel]] = {
     "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
+    "variant_label": VariantLabel,
+    "area_label": AreaLabel,
+    "temporal_label": TemporalLabel,
+    "vertical_label" : VerticalLabel,
+    "horizontal_label" : HorizontalLabel,
+    "branded_suffix" : BrandedSuffix,
+    "branded_variable" : BrandedVariable
 }

esgvoc/api/data_descriptors/activity.py

@@ -1,51 +1,14 @@
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
-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):
+class Activity(PlainTermDataDescriptor):
     """
-    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.
+    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()
+    url: str|None

esgvoc/api/data_descriptors/area_label.py

@@ -0,0 +1,6 @@
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class AreaLabel(PlainTermDataDescriptor):
+    description: str
+    label: str 

esgvoc/api/data_descriptors/branded_suffix.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import CompositeTermDataDescriptor
+
+
+class BrandedSuffix(CompositeTermDataDescriptor):
+    description: str

esgvoc/api/data_descriptors/branded_variable.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import CompositeTermDataDescriptor
+
+
+class BrandedVariable(CompositeTermDataDescriptor):
+    description: str

esgvoc/api/data_descriptors/consortium.py

@@ -1,66 +1,26 @@
-
-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
+from pydantic import Field
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor, ConfiguredBaseModel
 
 
 class Dates(ConfiguredBaseModel):
-
-    phase : str
-    from_ : int = Field(...,alias="from") # cause from is a keyword
-    to: Union[int,str]
+    phase: str
+    from_: int = Field(...,alias="from") # Cause from is a keyword
+    to: int|str
     
 
 class Member(ConfiguredBaseModel):
-    
     type : str
-    institution : str # id 
-    dates : List[Dates] = Field(default_factory=list)
-    membership_type : str # prior, current
+    institution: str # id 
+    dates: list[Dates] = Field(default_factory=list)
+    membership_type: str # prior, current
 
-class Consortium(ConfiguredBaseModel):
 
-    id: str 
+class Consortium(PlainTermDataDescriptor):
     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()
+    name: str|None = None 
+    status: str|None = None
+    changes: str|None
+    members: list[Member] = Field(default_factory=list)
+    url: str|None
+    # TODO: remove default value when all json will have their description.
+    description: str = Field(default = "")

esgvoc/api/data_descriptors/data_descriptor.py

@@ -0,0 +1,106 @@
+from typing import Protocol, Any, ClassVar
+from abc import ABC, abstractmethod
+from pydantic import BaseModel, ConfigDict
+
+
+class ConfiguredBaseModel(BaseModel):
+    model_config = ConfigDict(
+        validate_assignment = True,
+        validate_default = True,
+        extra = "allow",
+        arbitrary_types_allowed = True,
+        use_enum_values = True,
+        strict = False,
+    )
+
+
+class DataDescriptorVisitor(Protocol):
+    """
+    The specifications for a term visitor.
+    """
+    def visit_sub_set_term(self, term: "DataDescriptorSubSet") -> Any:
+        """Visit a sub set of the information of a term."""
+        pass
+    def visit_plain_term(self, term: "PlainTermDataDescriptor") -> Any:
+        """Visit a plain term."""
+        pass
+    def visit_pattern_term(self, term: "PatternTermDataDescriptor") -> Any:
+        """Visit a pattern term."""
+        pass
+    def visit_composite_term(self, term: "CompositeTermDataDescriptor") -> Any:
+        """Visit a composite term."""
+
+
+class DataDescriptor(ConfiguredBaseModel, ABC):
+    """
+    Generic class for the data descriptor classes.
+    """
+    id: str
+    """The identifier of the terms."""
+    type: str
+    """The data descriptor to which the term belongs."""
+
+    @abstractmethod
+    def accept(self, visitor: DataDescriptorVisitor) -> Any:
+        """
+        Accept an term visitor.
+
+        :param visitor: The term visitor.
+        :type visitor: DataDescriptorVisitor
+        :return: Depending on the visitor.
+        :rtype: Any
+        """
+        pass
+
+
+class DataDescriptorSubSet(DataDescriptor):
+    """
+    A sub set of the information contains in a term.
+    """
+    MANDATORY_TERM_FIELDS: ClassVar[tuple[str, str]] = ('id', 'type')
+    """The set of mandatory term fields."""
+    def accept(self, visitor: DataDescriptorVisitor) -> Any:
+        return visitor.visit_sub_set_term(self)
+
+
+class PlainTermDataDescriptor(DataDescriptor):
+    """
+    A data descriptor that describes hand written terms.
+    """
+    drs_name: str
+    def accept(self, visitor: DataDescriptorVisitor) -> Any:
+        return visitor.visit_plain_term(self)
+
+
+class PatternTermDataDescriptor(DataDescriptor):
+    """
+    A data descriptor that describes terms defined by a regular expression.
+    """
+    regex: str
+    """The regular expression."""
+    def accept(self, visitor: DataDescriptorVisitor) -> Any:
+        return visitor.visit_pattern_term(self)
+
+
+class CompositeTermPart(ConfiguredBaseModel):
+    """
+    A reference to a term, part of a composite term.
+    """
+    id: str
+    """The id of the referenced term."""
+    type: str
+    """The type of the referenced term."""
+    is_required : bool
+    """Denote if the term is optional as part of a composite term."""
+
+
+class CompositeTermDataDescriptor(DataDescriptor):
+    """
+    A data descriptor that describes terms composed of other terms.
+    """
+    separator: str
+    """The components separator character."""
+    parts: list[CompositeTermPart]
+    """The components."""
+    def accept(self, visitor: DataDescriptorVisitor) -> Any:
+        return visitor.visit_composite_term(self)

esgvoc/api/data_descriptors/date.py

@@ -1,48 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescriptor
 
 
-
-
-
-
-
-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()
+class Date(PatternTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/directory_date.py

@@ -1,48 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescriptor
 
 
-
-from __future__ import annotations 
-from typing import (
-    List
-)
-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 Part(ConfiguredBaseModel):
-    id: str
-    type : str
-    is_required : bool
-
-class DirectoryDate(ConfiguredBaseModel):
-
-
-    id: str 
-    type: str 
-    regex : str
-
-# Model rebuild
-# see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model
-DirectoryDate.model_rebuild()
+class DirectoryDate(PatternTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/experiment.py

@@ -1,60 +1,25 @@
+from pydantic import Field
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
-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):
+class Experiment(PlainTermDataDescriptor):
     """
-    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.
+    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)
+    activity: list[str] = Field(default_factory=list)
     description: str 
-    tier: Optional[int] 
+    tier: int|None
     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()
+    sub_experiment_id: list[str]|None
+    experiment: str
+    required_model_components: list[str]|None
+    additional_allowed_model_components: list[str] = Field(default_factory=list) 
+    start_year: int|None
+    end_year: int|None
+    min_number_yrs_per_sim: int|None
+    parent_activity_id: list[str]|None
+    parent_experiment_id: list[str]|None