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

esgvoc/__init__.py

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

esgvoc/api/__init__.py

@@ -1,73 +1,97 @@
-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,
-                                 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)
+from esgvoc.api.project_specs import (
+                                      DrsCollection,
+                                      DrsConstant,
+                                      DrsPart,
+                                      DrsPartKind,
+                                      DrsSpecification,
+                                      DrsType,
+                                      ProjectSpecs,
+)
+from esgvoc.api.projects import (
+                                      find_collections_in_project,
+                                      find_items_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,
+                                      get_collection_from_data_descriptor_in_all_projects,
+                                      get_collection_from_data_descriptor_in_project,
+                                      get_collection_in_project,
+                                      get_project,
+                                      get_term_in_collection,
+                                      get_term_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
+from esgvoc.api.universe import (
+                                      find_data_descriptors_in_universe,
+                                      find_items_in_universe,
+                                      find_terms_in_data_descriptor,
+                                      find_terms_in_universe,
+                                      get_all_data_descriptors_in_universe,
+                                      get_all_terms_in_data_descriptor,
+                                      get_all_terms_in_universe,
+                                      get_data_descriptor_in_universe,
+                                      get_term_in_data_descriptor,
+                                      get_term_in_universe,
+)
 
-__all__ = ["MatchingTerm",
-           "SearchType",
-           "SearchSettings",
-           "ValidationError",
-           "ValidationReport",
-           "ValidationErrorVisitor",
-           "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",
-           "DrsType",
-           "DrsPartKind",
-           "DrsConstant",
-           "DrsCollection",
-           "DrsPart",
-           "DrsSpecification",
-           "ProjectSpecs"]
+__all__ = [
+    "DrsCollection",
+    "DrsConstant",
+    "DrsPart",
+    "DrsPartKind",
+    "DrsSpecification",
+    "DrsType",
+    "find_collections_in_project",
+    "find_data_descriptors_in_universe",
+    "find_items_in_project",
+    "find_items_in_universe",
+    "find_terms_in_all_projects",
+    "find_terms_in_collection",
+    "find_terms_in_data_descriptor",
+    "find_terms_in_project",
+    "find_terms_in_universe",
+    "get_all_collections_in_project",
+    "get_all_data_descriptors_in_universe",
+    "get_all_projects",
+    "get_all_terms_in_all_projects",
+    "get_all_terms_in_collection",
+    "get_all_terms_in_data_descriptor",
+    "get_all_terms_in_project",
+    "get_all_terms_in_universe",
+    "get_collection_from_data_descriptor_in_all_projects",
+    "get_collection_from_data_descriptor_in_project",
+    "get_collection_in_project",
+    "get_data_descriptor_in_universe",
+    "get_project",
+    "get_term_in_collection",
+    "get_term_in_data_descriptor",
+    "get_term_in_project",
+    "get_term_in_universe",
+    "MatchingTerm",
+    "ProjectSpecs",
+    "ProjectTermError",
+    "UniverseTermError",
+    "valid_term",
+    "valid_term_in_all_projects",
+    "valid_term_in_collection",
+    "valid_term_in_project",
+    "ValidationError",
+    "ValidationErrorVisitor",
+    "ValidationReport"
+          ]

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