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

esgvoc/api/data_descriptors/temporal_label.py

@@ -2,5 +2,19 @@ from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 
 class TemporalLabel(PlainTermDataDescriptor):
+    """
+    Temporal sampling label.
+
+    This label provides information about the temporal 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/temporal_label.]
+
+    This label is used as the temporal component of a branded variable's suffix
+    (see :py:class:`BrandedSuffix`).
+    By definition, the temporal label must be consistent with the branded suffix.
+    Temporal labels must not contain the separator used when constructing the branded suffix.
+    """
+
     description: str
-    label: str 
+    label: str

esgvoc/api/data_descriptors/time_range.py

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

esgvoc/api/data_descriptors/title.py

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

esgvoc/api/data_descriptors/tracking_id.py

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

esgvoc/api/data_descriptors/variable.py

@@ -1,19 +1,32 @@
 from pydantic import Field
+
 from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 
 class Variable(PlainTermDataDescriptor):
     """
-    A variable refers to a specific type of climate-related quantity or measurement that is \
-    simulated and stored in a data file. These variables represent key physical, chemical, or \
-    biological properties of the Earth system and are outputs from climate models.
-    Each variable captures a different aspect of the climate system, such as temperature, \
-    precipitation, sea level, radiation, or atmospheric composition.
-    Examples of Variables: tas: Near-surface air temperature (often measured at 2 meters above \
-    the surface) pr: Precipitation psl: Sea level pressure zg: Geopotential height rlut: \
-    Top-of-atmosphere longwave radiation siconc: Sea ice concentration co2: Atmospheric CO2 concentration
+    A climate-related quantity or measurement.
+
+    These quantities represent key physical, chemical or biological properties of the Earth system
+    and can be the result of direct observation of the climate system or simulations.
+    Variables cover a range of aspects of the climate system,
+    such as temperature, precipitation, sea level, radiation, or atmospheric composition.
+    Some examples of variables that have been used in CMIP:
+
+    - *tas*: Near-surface air temperature (often measured at 2 meters above the surface)
+    - *pr*: Precipitation
+    - *psl*: Sea-level pressure
+    - *zg*: Geopotential height
+    - *rlut*: Top-of-atmosphere longwave radiation
+    - *siconc*: Sea-ice concentration
+    - *co2*: Atmospheric CO2 concentration
+
+    Since CMIP7, the concept of a variable has been augmented with the idea of 'branding',
+    leading to the idea of a 'branded variable'.
+    For details, see :py:class:`BrandedVariable`.
     """
-    validation_method: str = Field(default = "list")
-    long_name: str 
-    standard_name: str|None
-    units: str|None
+
+    validation_method: str = Field(default="list")
+    long_name: str
+    standard_name: str | None
+    units: str | None

esgvoc/api/data_descriptors/variant_label.py

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

esgvoc/api/data_descriptors/vertical_label.py

@@ -2,4 +2,18 @@ from esgvoc.api.data_descriptors.data_descriptor import PatternTermDataDescripto
 
 
 class VerticalLabel(PatternTermDataDescriptor):
+    """
+    Vertical label.
+
+    This label provides information about the vertical 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/vertical_label.]
+
+    This label is used as the vertical component of a branded variable's suffix
+    (see :py:class:`BrandedSuffix`).
+    By definition, the vertical label must be consistent with the branded suffix.
+    Vertical labels must not contain the separator used when constructing the branded suffix.
+    """
+
     pass

esgvoc/api/project_specs.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Annotated, Literal
+from typing import Annotated, Any, Literal, Optional, Protocol
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -8,6 +8,7 @@ class DrsType(str, Enum):
     """
     The types of DRS specification (directory, file name and dataset id).
     """
+
     DIRECTORY = "directory"
     """The DRS directory specification type."""
     FILE_NAME = "file_name"
@@ -20,6 +21,7 @@ class DrsPartKind(str, Enum):
     """
     The kinds of DRS part (constant and collection).
     """
+
     CONSTANT = "constant"
     """The constant part type."""
     COLLECTION = "collection"
@@ -30,10 +32,12 @@ class DrsConstant(BaseModel):
     """
     A constant part of a DRS specification (e.g., cmip5).
     """
+
     value: str
     """The value of the a constant part."""
     kind: Literal[DrsPartKind.CONSTANT] = DrsPartKind.CONSTANT
     """The DRS part kind."""
+
     def __str__(self) -> str:
         return self.value
 
@@ -42,12 +46,14 @@ class DrsCollection(BaseModel):
     """
     A collection part of a DRS specification (e.g., institution_id for CMIP6).
     """
+
     collection_id: str
     """The collection id."""
     is_required: bool
     """Whether the collection is required for the DRS specification or not."""
     kind: Literal[DrsPartKind.COLLECTION] = DrsPartKind.COLLECTION
     """The DRS part kind."""
+
     def __str__(self) -> str:
         return self.collection_id
 
@@ -60,6 +66,7 @@ class DrsSpecification(BaseModel):
     """
     A DRS specification.
     """
+
     type: DrsType
     """The type of the specification."""
     separator: str
@@ -70,14 +77,122 @@ class DrsSpecification(BaseModel):
     """The parts of the DRS specification."""
 
 
+class GlobalAttributeValueType(str, Enum):
+    """
+    The types of global attribute values.
+    """
+
+    STRING = "string"
+    """String value type."""
+    INTEGER = "integer"
+    """Integer value type."""
+    FLOAT = "float"
+    """Float value type."""
+
+
+class GlobalAttributeVisitor(Protocol):
+    """
+    Specifications for a global attribute visitor.
+    """
+    def visit_base_attribute(self,
+                             attribute_name: str,
+                             attribute: "GlobalAttributeSpecBase") -> Any:
+        """Visit a base global attribute."""
+        pass
+
+    def visit_specific_attribute(self,
+                                 attribute_name: str,
+                                 attribute: "GlobalAttributeSpecSpecific") -> Any:
+        """Visit a specific global attribute."""
+        pass
+
+
+class GlobalAttributeSpecBase(BaseModel):
+    """
+    Specification for a global attribute.
+    """
+
+    source_collection: str
+    """the source_collection to get the term from"""
+    value_type: GlobalAttributeValueType
+    """The expected value type."""
+
+    def accept(self, attribute_name: str, visitor: GlobalAttributeVisitor) -> Any:
+        return visitor.visit_base_attribute(attribute_name, self)
+
+
+class GlobalAttributeSpecSpecific(GlobalAttributeSpecBase):
+    """
+    Specification for a global attribute.
+    with a specific key
+    """
+
+    specific_key: str
+    """If the validation is for the value of a specific key, for instance description or ui-label """
+
+    def accept(self, attribute_name: str, visitor: GlobalAttributeVisitor) -> Any:
+        """
+        Accept a global attribute visitor.
+
+        :param attribute_name: The attribute name.
+        :param visitor: The global attribute visitor.
+        :type visitor: GlobalAttributeVisitor
+        :return: Depending on the visitor.
+        :rtype: Any
+        """
+        return visitor.visit_specific_attribute(attribute_name, self)
+
+
+GlobalAttributeSpec = GlobalAttributeSpecSpecific | GlobalAttributeSpecBase
+
+
+class GlobalAttributeSpecs(BaseModel):
+    """
+    Container for global attribute specifications.
+    """
+
+    specs: dict[str, GlobalAttributeSpec] = Field(default_factory=dict)
+    """The global attributes specifications dictionary."""
+
+    def __str__(self) -> str:
+        """Return all keys when printing."""
+        return str(list(self.specs.keys()))
+
+    def __repr__(self) -> str:
+        """Return all keys when using repr."""
+        return f"GlobalAttributeSpecs(keys={list(self.specs.keys())})"
+
+    # Dictionary-like access methods
+    def __getitem__(self, key: str) -> GlobalAttributeSpec:
+        return self.specs[key]
+
+    def __setitem__(self, key: str, value: GlobalAttributeSpec) -> None:
+        self.specs[key] = value
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.specs
+
+    def keys(self):
+        return self.specs.keys()
+
+    def values(self):
+        return self.specs.values()
+
+    def items(self):
+        return self.specs.items()
+
+
 class ProjectSpecs(BaseModel):
     """
     A project specifications.
     """
+
     project_id: str
     """The project id."""
     description: str
     """The description of the project."""
     drs_specs: list[DrsSpecification]
-    """The DRS specifications of the project (directory, file name and dataset id."""
+    """The DRS specifications of the project (directory, file name and dataset id)."""
+    global_attributes_specs: Optional[GlobalAttributeSpecs] = None
+    """The global attributes specifications of the project."""
     model_config = ConfigDict(extra="allow")