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

esgvoc/__init__.py

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

esgvoc/api/__init__.py

@@ -1,62 +1,97 @@
-from esgvoc.api._utils import APIException
-from esgvoc.api.project_specs import (DrsCollection, DrsConstant, DrsPart,
-                                      DrsPartKind, DrsSpecification, DrsType,
-                                      ProjectSpecs)
+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,
-                                 get_all_terms_in_data_descriptor,
-                                 get_all_terms_in_universe)
+                                      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",
-           "APIException"]
+__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,69 +1,91 @@
 from esgvoc.api.data_descriptors.activity import Activity
+from esgvoc.api.data_descriptors.area_label import AreaLabel
+from esgvoc.api.data_descriptors.branded_suffix import BrandedSuffix
+from esgvoc.api.data_descriptors.branded_variable import BrandedVariable
 from esgvoc.api.data_descriptors.consortium import Consortium
+from esgvoc.api.data_descriptors.contact import Contact
+from esgvoc.api.data_descriptors.conventions import Convention
+from esgvoc.api.data_descriptors.creation_date import CreationDate
 from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
+from esgvoc.api.data_descriptors.data_specs_version import DataSpecsVersion
 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.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.further_info_url import FurtherInfoUrl
+from esgvoc.api.data_descriptors.grid_label import GridLabel
+from esgvoc.api.data_descriptors.horizontal_label import HorizontalLabel
+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.known_branded_variable import KnownBrandedVariable
+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.obs_type import ObsType
+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.publication_status import PublicationStatus
+from esgvoc.api.data_descriptors.realisation_index import RealisationIndex
 from esgvoc.api.data_descriptors.realm import Realm
+from esgvoc.api.data_descriptors.region import Region
 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.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.table import Table
+from esgvoc.api.data_descriptors.temporal_label import TemporalLabel
+from esgvoc.api.data_descriptors.time_range import TimeRange
+from esgvoc.api.data_descriptors.title import Title
+from esgvoc.api.data_descriptors.tracking_id import TrackingId
 from esgvoc.api.data_descriptors.variable import Variable
 from esgvoc.api.data_descriptors.variant_label import VariantLabel
-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[DataDescriptor]] = {
     "activity": Activity,
     "consortium": Consortium,
     "date": Date,
     "directory_date": DirectoryDate,
-    "experiment": Experiment, 
+    "experiment": Experiment,
     "forcing_index": ForcingIndex,
     "frequency": Frequency,
-    "grid": GridLabel,#Universe
-    "grid_label": GridLabel, # cmip6, cmip6plus
-    "initialisation_index": InitialisationIndex, 
+    "grid": GridLabel,  # Universe
+    "grid_label": GridLabel,  # cmip6, cmip6plus
+    "initialisation_index": InitialisationIndex,
     "institution": Institution,
     "license": License,
     "mip_era": MipEra,
     "model_component": ModelComponent,
-    "organisation": Organisation, 
+    "organisation": Organisation,
     "physic_index": PhysicIndex,
     "product": Product,
-    "realisation_index": RealisationIndex ,
+    "realisation_index": RealisationIndex,
     "realm": Realm,
     "resolution": Resolution,
-    "source": Source, 
-    "source_type": SourceType, 
+    "source": Source,
+    "source_type": SourceType,
     "sub_experiment": SubExperiment,
-    "table" : Table,
+    "table": Table,
     "time_range": TimeRange,
     "variable": Variable,
     "variant_label": VariantLabel,
     "area_label": AreaLabel,
     "temporal_label": TemporalLabel,
-    "vertical_label" : VerticalLabel,
-    "horizontal_label" : HorizontalLabel,
-    "branded_suffix" : BrandedSuffix,
-    "branded_variable" : BrandedVariable
+    "vertical_label": VerticalLabel,
+    "horizontal_label": HorizontalLabel,
+    "branded_suffix": BrandedSuffix,
+    "branded_variable": BrandedVariable,
+    "publication_status": PublicationStatus,
+    "known_branded_variable": KnownBrandedVariable,
+    "data_specs_version": DataSpecsVersion,
+    "further_info_url": FurtherInfoUrl,
+    "tracking_id": TrackingId,
+    "creation_date": CreationDate,
+    "conventions": Convention,
+    "title": Title,
+    "contact": Contact,
+    "region": Region,
+    "obs_type": ObsType,  # obs4Mips
 }

esgvoc/api/data_descriptors/activity.py

@@ -9,6 +9,6 @@ class Activity(PlainTermDataDescriptor):
     Activities are often organized around key research themes and may involve multiple experiments, \
     scenarios, and model configurations.
     """
-    name: str 
-    long_name: str 
-    url: str|None
+    name: str
+    long_name: str
+    url: str | None

esgvoc/api/data_descriptors/area_label.py

@@ -2,5 +2,20 @@ from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 
 class AreaLabel(PlainTermDataDescriptor):
+    """
+    Area sampling label.
+
+    This label provides information about the area sampling of a given dataset.
+    For a list of allowed values, see
+    [TODO think about how to cross-reference to somewhere where people can look up the allowed values,
+    e.g. some summary of the values in https://github.com/WCRP-CMIP/WCRP-universe/tree/esgvoc/area_label.]
+
+    This label is used as the area component of a branded variable's suffix
+    (see :py:class:`BrandedSuffix`).
+    By definition, the area label must be consistent with the branded suffix.
+    area labels must not contain dashes
+    (as the dash is used as a separator when constructing the branded suffix).
+    """
+
     description: str
-    label: str 
+    label: str

esgvoc/api/data_descriptors/branded_suffix.py

@@ -2,4 +2,24 @@ from esgvoc.api.data_descriptors.data_descriptor import CompositeTermDataDescrip
 
 
 class BrandedSuffix(CompositeTermDataDescriptor):
+    """
+    The suffix of a branded variable.
+
+    A branded variable is composed of two parts.
+    The first part is the root variable (see [TODO cross-ref to Variable]).
+    The second is the suffix, i.e. the component described here.
+    The suffix captures all the information
+    about the time sampling, horizontal sampling, vertical sampling
+    and area masking of the variable.
+
+    The suffix is composed of the following components:
+
+    #. :py:class:`TemporalLabel`
+    #. :py:class:`VerticalLabel`
+    #. :py:class:`HorizontalLabel`
+    #. :py:class:`AreaLabel`
+
+    These components are separated by a separator to create the branded suffix.
+    """
+
     description: str

esgvoc/api/data_descriptors/branded_variable.py

@@ -2,4 +2,16 @@ from esgvoc.api.data_descriptors.data_descriptor import CompositeTermDataDescrip
 
 
 class BrandedVariable(CompositeTermDataDescriptor):
+    """
+    A climate-related quantity or measurement, including information about sampling.
+
+    The concept of a branded variable was introduced in CMIP7.
+    A branded variable is composed of two parts.
+    The first part is the root variable (see :py:class:`Variable`).
+    The second is the suffix (see :py:class:`BrandedSuffix`).
+
+    For further details on the development of branded variables,
+    see [this paper draft](https://docs.google.com/document/d/19jzecgymgiiEsTDzaaqeLP6pTvLT-NzCMaq-wu-QoOc/edit?pli=1&tab=t.0).
+    """
+
     description: str

esgvoc/api/data_descriptors/consortium.py

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

esgvoc/api/data_descriptors/contact.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescriptor
+
+
+class Contact(PatternTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/conventions.py

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

esgvoc/api/data_descriptors/creation_date.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescriptor
+
+
+class CreationDate(PatternTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/data_descriptor.py

@@ -1,16 +1,17 @@
-from typing import Protocol, Any, ClassVar
 from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Protocol
+
 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,
+        validate_assignment=True,
+        validate_default=True,
+        extra="allow",
+        arbitrary_types_allowed=True,
+        use_enum_values=True,
+        strict=False,
     )
 
 
@@ -21,12 +22,15 @@ class DataDescriptorVisitor(Protocol):
     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."""
 
@@ -68,6 +72,7 @@ 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)
 
@@ -86,11 +91,11 @@ class CompositeTermPart(ConfiguredBaseModel):
     """
     A reference to a term, part of a composite term.
     """
-    id: str
+    id: str | list[str] | None = None
     """The id of the referenced term."""
     type: str
     """The type of the referenced term."""
-    is_required : bool
+    is_required: bool
     """Denote if the term is optional as part of a composite term."""
 
 

esgvoc/api/data_descriptors/data_specs_version.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescriptor
+
+
+class DataSpecsVersion(PatternTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/date.py

@@ -2,4 +2,4 @@ from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescripto
 
 
 class Date(PatternTermDataDescriptor):
-    pass
+    pass

esgvoc/api/data_descriptors/directory_date.py

@@ -2,4 +2,4 @@ from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescripto
 
 
 class DirectoryDate(PatternTermDataDescriptor):
-    pass
+    pass

esgvoc/api/data_descriptors/experiment.py

@@ -1,4 +1,5 @@
 from pydantic import Field
+
 from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 
@@ -10,16 +11,17 @@ class Experiment(PlainTermDataDescriptor):
     concentrations or solar radiation), and duration, to explore and understand climate behavior \
     under various scenarios and conditions.
     """
+
     activity: list[str] = Field(default_factory=list)
-    description: str 
-    tier: int|None
-    experiment_id: str 
-    sub_experiment_id: list[str]|None
+    description: str
+    tier: int | None
+    experiment_id: str
+    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
+    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

esgvoc/api/data_descriptors/forcing_index.py

@@ -2,4 +2,4 @@ from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescripto
 
 
 class ForcingIndex(PatternTermDataDescriptor):
-    pass
+    pass

esgvoc/api/data_descriptors/frequency.py

@@ -3,6 +3,6 @@ from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 class Frequency(PlainTermDataDescriptor):
     description: str
-    long_name: str 
-    name: str 
-    unit: str
+    long_name: str
+    name: str
+    unit: str

esgvoc/api/data_descriptors/further_info_url.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescriptor
+
+
+class FurtherInfoUrl(PatternTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/grid_label.py

@@ -3,6 +3,6 @@ from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 class GridLabel(PlainTermDataDescriptor):
     description: str
-    short_name: str 
-    name: str 
+    short_name: str
+    name: str
     region: str

esgvoc/api/data_descriptors/horizontal_label.py

@@ -2,5 +2,19 @@ from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 
 class HorizontalLabel(PlainTermDataDescriptor):
+    """
+    Horizontal sampling label.
+
+    This label provides information about the horizontal sampling of a given dataset.
+    For a list of allowed values, see
+    [TODO think about how to cross-reference to somewhere where people can look up the allowed values,
+    e.g. some summary of the values in https://github.com/WCRP-CMIP/WCRP-universe/tree/esgvoc/horizontal_label.]
+
+    This label is used as the horizontal component of a branded variable's suffix
+    (see :py:class:`BrandedSuffix`).
+    By definition, the horizontal label must be consistent with the branded suffix.
+    Horizontal labels must not contain the separator used when constructing the branded suffix.
+    """
+
     description: str
-    label: str 
+    label: str

esgvoc/api/data_descriptors/initialisation_index.py

@@ -2,4 +2,4 @@ from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescripto
 
 
 class InitialisationIndex(PatternTermDataDescriptor):
-    pass
+    pass

esgvoc/api/data_descriptors/institution.py

@@ -1,15 +1,18 @@
 from pydantic import Field
+
 from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
+
 class Institution(PlainTermDataDescriptor):
     """
     An registered institution for WCRP modelisation MIP.
     """
+
     acronyms: list[str] = Field(default_factory=list)
     aliases: list[str] = Field(default_factory=list)
-    established: int|None
+    established: int | None
     labels: list[str] = Field(default_factory=list)
-    location: dict = Field(default_factory=dict)  
-    name: str 
-    ror: str|None
-    url: list[str] = Field(default_factory=list)
+    location: dict = Field(default_factory=dict)
+    name: str
+    ror: str | None
+    url: list[str] = Field(default_factory=list)