esgvoc 2.0.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

esgvoc/__init__.py

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

esgvoc/api/data_descriptors/EMD_models/coordinate.py

@@ -3,50 +3,34 @@ from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 class Coordinate(PlainTermDataDescriptor):
     """
-    Native vertical grid coordinate type. The coordinate types are all CF standard names (except where indicated) with the same definitions. See section 5.2 Native vertical grid properties.
+    Native vertical grid coordinate type.
+
+    The coordinate types are all CF standard names (except where indicated)
+    with the same definitions. See section 5.2 Native vertical grid properties.
+
     Options for the native vertical grid Coordinate property:
-        • none
-            ◦ (Not a standard name) There is no vertical dimension.
-        • height
-            ◦ Height is the vertical distance above the earth's surface.
-        • geopotential_height
-            ◦ Geopotential height is the geopotential divided by the standard acceleration due to gravity.
-        • air_pressure
-            ◦ Air pressure is the pressure that exists in the medium of air.
-        • air_potential_temperature
-            ◦ Air potential temperature is the temperature a parcel of air would have if moved dry adiabatically to a standard pressure.
-        • atmosphere_ln_pressure_coordinate
-            ◦ Parametric atmosphere natural log pressure coordinate.
-        • atmosphere_sigma_coordinate
-            ◦ Parametric atmosphere sigma coordinate.
-        • atmosphere_hybrid_sigma_pressure_coordinate
-            ◦ Parametric atmosphere hybrid sigma pressure coordinate.
-        • atmosphere_hybrid_height_coordinate
-            ◦ Parametric atmosphere hybrid height coordinate.
-        • atmosphere_sleve_coordinate
-            ◦ Parametric atmosphere smooth vertical level coordinate.
-        • depth
-            ◦ Depth is the vertical distance below the earth's surface.
-        • sea_water_pressure
-            ◦ Sea water pressure is the pressure that exists in the medium of sea water.
-        • sea_water_potential_temperature
-            ◦ Sea water potential temperature is the temperature a parcel of sea water would have if moved adiabatically to sea level pressure.
-        • ocean_sigma_coordinate
-            ◦ Parametric ocean sigma coordinate.
-        • ocean_s_coordinate
-            ◦ Parametric ocean s-coordinate.
-        • ocean_s_coordinate_g1
-            ◦ Parametric ocean s-coordinate, generic form 1.
-        • ocean_s_coordinate_g2
-            ◦ Parametric ocean s-coordinate, generic form 2.
-        • ocean_sigma_z_coordinate
-            ◦ Parametric ocean sigma over z coordinate.
-        • ocean_double_sigma_coordinate
-            ◦ Parametric ocean double sigma coordinate.
-        • land_ice_sigma_coordinate
-            ◦ Land ice (glaciers, ice-caps and ice-sheets resting on bedrock and also includes ice-shelves) sigma coordinate.
-        • z*
-            ◦ (Not a standard name) The z* coordinate of Adcroft and Campin (2004).
+
+    * **none** - (Not a standard name) There is no vertical dimension.
+    * **height** - Height is the vertical distance above the earth's surface.
+    * **geopotential_height** - Geopotential height is the geopotential divided by the standard acceleration due to gravity.
+    * **air_pressure** - Air pressure is the pressure that exists in the medium of air.
+    * **air_potential_temperature** - Air potential temperature is the temperature a parcel of air would have if moved dry adiabatically to a standard pressure.
+    * **atmosphere_ln_pressure_coordinate** - Parametric atmosphere natural log pressure coordinate.
+    * **atmosphere_sigma_coordinate** - Parametric atmosphere sigma coordinate.
+    * **atmosphere_hybrid_sigma_pressure_coordinate** - Parametric atmosphere hybrid sigma pressure coordinate.
+    * **atmosphere_hybrid_height_coordinate** - Parametric atmosphere hybrid height coordinate.
+    * **atmosphere_sleve_coordinate** - Parametric atmosphere smooth vertical level coordinate.
+    * **depth** - Depth is the vertical distance below the earth's surface.
+    * **sea_water_pressure** - Sea water pressure is the pressure that exists in the medium of sea water.
+    * **sea_water_potential_temperature** - Sea water potential temperature is the temperature a parcel of sea water would have if moved adiabatically to sea level pressure.
+    * **ocean_sigma_coordinate** - Parametric ocean sigma coordinate.
+    * **ocean_s_coordinate** - Parametric ocean s-coordinate.
+    * **ocean_s_coordinate_g1** - Parametric ocean s-coordinate, generic form 1.
+    * **ocean_s_coordinate_g2** - Parametric ocean s-coordinate, generic form 2.
+    * **ocean_sigma_z_coordinate** - Parametric ocean sigma over z coordinate.
+    * **ocean_double_sigma_coordinate** - Parametric ocean double sigma coordinate.
+    * **land_ice_sigma_coordinate** - Land ice (glaciers, ice-caps and ice-sheets resting on bedrock and also includes ice-shelves) sigma coordinate.
+    * **z*** - (Not a standard name) The z* coordinate of Adcroft and Campin (2004).
     """
 
     pass

esgvoc/api/data_descriptors/EMD_models/reference.py

@@ -14,18 +14,17 @@ class Reference(PlainTermDataDescriptor):
     An academic reference to published work for the top-level model or one of its model
     components is defined by the following properties:
 
-    • Citation
-        ◦ A human-readable citation for the work.
-        ◦ E.g. Smith, R. S., Mathiot, P., Siahaan, A., Lee, V., Cornford, S. L., Gregory, J. M.,
-          et al. (2021). Coupling the U.K. Earth System model to dynamic models of the Greenland
-          and Antarctic ice sheets. Journal of Advances in Modeling Earth Systems, 13,
-          e2021MS002520. https://doi.org/10.1029/2021MS002520, 2023
-    • DOI
-        ◦ The persistent identifier (DOI) used to identify the work.
-        ◦ A DOI is required for all references. A reference that does not already have a DOI
-          (as could be the case for some technical reports, for instance) must be given one
-          (e.g. with a service like Zenodo).
-        ◦ E.g. https://doi.org/10.1029/2021MS002520
+    * **Citation** - A human-readable citation for the work.
+      E.g. Smith, R. S., Mathiot, P., Siahaan, A., Lee, V., Cornford, S. L., Gregory, J. M.,
+      et al. (2021). Coupling the U.K. Earth System model to dynamic models of the Greenland
+      and Antarctic ice sheets. Journal of Advances in Modeling Earth Systems, 13,
+      e2021MS002520. https://doi.org/10.1029/2021MS002520, 2023
+
+    * **DOI** - The persistent identifier (DOI) used to identify the work.
+      A DOI is required for all references. A reference that does not already have a DOI
+      (as could be the case for some technical reports, for instance) must be given one
+      (e.g. with a service like Zenodo).
+      E.g. https://doi.org/10.1029/2021MS002520
     """
 
     citation: str = Field(description="A human-readable citation for the work.", min_length=1)

esgvoc/api/data_descriptors/EMD_models/resolution.py

@@ -3,46 +3,33 @@ from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
 
 class EMDResolution(PlainTermDataDescriptor):
     """
-    The nominal resolution (in km) characterises the resolution of a model's native horizontal grid. See section 5.1 Native horizontal grid properties.
-    Options for the native horizontal grid nominal resolution property are defined in the following table as a function of the value of the mean resolution km property:
+    The nominal resolution (in km) characterises the resolution of a model's native horizontal grid.
 
-    for mean resolution, R, in the range (km):
-    nominal resolution is:
-    0.036 ≤ R < 0.072
-    0.05 km
-    0.072 ≤ R < 0.16
-    0.1 km
-    0.16 ≤ R < 0.36
-    0.25 km
-    0.36 ≤ R < 0.72
-    0.5 km
-    0.72 ≤ R < 1.6
-    1 km
-    1.6 ≤ R < 3.6
-    2.5 km
-    3.6 ≤ R < 7.2
-    5 km
-    7.2 ≤ R < 16
-    10 km
-    16 ≤ R < 36
-    25 km
-    36 ≤ R < 72
-    50 km
-    72 ≤ R < 160
-    100 km
-    160 ≤ R < 360
-    250 km
-    360 ≤ R < 720
-    500 km
-    720 ≤ R < 1600
-    1000 km
-    1600 ≤ R < 3600
-    2500 km
-    3600 ≤ R < 7200
-    5000 km
-    7200 ≤ R < 16000
-    10000 km
-            7.10. Native vertical grid "Coordinate" CV
+    See section 5.1 Native horizontal grid properties.
+    Options for the native horizontal grid nominal resolution property are defined
+    in the following table as a function of the value of the mean resolution km property:
+
+    ==================== ====================
+    Mean resolution R    Nominal resolution
+    ==================== ====================
+    0.036 ≤ R < 0.072    0.05 km
+    0.072 ≤ R < 0.16     0.1 km
+    0.16 ≤ R < 0.36      0.25 km
+    0.36 ≤ R < 0.72      0.5 km
+    0.72 ≤ R < 1.6       1 km
+    1.6 ≤ R < 3.6        2.5 km
+    3.6 ≤ R < 7.2        5 km
+    7.2 ≤ R < 16         10 km
+    16 ≤ R < 36          25 km
+    36 ≤ R < 72          50 km
+    72 ≤ R < 160         100 km
+    160 ≤ R < 360        250 km
+    360 ≤ R < 720        500 km
+    720 ≤ R < 1600       1000 km
+    1600 ≤ R < 3600      2500 km
+    3600 ≤ R < 7200      5000 km
+    7200 ≤ R < 16000     10000 km
+    ==================== ====================
     """
 
     mean_resolution: str

esgvoc/api/data_descriptors/data_descriptor.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Any, ClassVar, Protocol
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field, model_serializer
 
 
 class ConfiguredBaseModel(BaseModel):
@@ -68,10 +68,39 @@ class DataDescriptor(ConfiguredBaseModel, ABC):
 class DataDescriptorSubSet(DataDescriptor):
     """
     A sub set of the information contains in a term.
+    When using selected_term_fields, only id is guaranteed to be present.
+    Other fields (type, description) may be None if not selected.
     """
 
-    MANDATORY_TERM_FIELDS: ClassVar[tuple[str, str]] = ("id", "type")
-    """The set of mandatory term fields."""
+    # Override inherited fields to make them truly optional using Field()
+    # Using default_factory to ensure Pydantic treats them as optional
+    type: str | None = Field(default=None, validate_default=False)  # type: ignore[assignment]
+    """The data descriptor to which the term belongs (optional in subset)."""
+    description: str | None = Field(default=None, validate_default=False)  # type: ignore[assignment]
+    """The description of the term (optional in subset)."""
+
+    MANDATORY_TERM_FIELDS: ClassVar[tuple[str]] = ("id",)
+    """The set of mandatory term fields (only id is guaranteed when using selected_term_fields)."""
+
+    @model_serializer(mode='wrap')
+    def serialize_model(self, serializer: Any) -> dict[str, Any]:
+        """
+        Custom serializer that only includes fields that actually exist on the instance.
+        This prevents Pydantic warnings when fields are removed via delattr().
+        Uses 'wrap' mode to override default serialization behavior completely.
+        """
+        # Serialize all attributes from __dict__ that are not private
+        result = {
+            field_name: field_value
+            for field_name, field_value in self.__dict__.items()
+            if not field_name.startswith('_')
+        }
+
+        # Also include extra fields (like drs_name) that are stored in __pydantic_extra__
+        if hasattr(self, '__pydantic_extra__') and self.__pydantic_extra__:
+            result.update(self.__pydantic_extra__)
+
+        return result
 
     def accept(self, visitor: DataDescriptorVisitor) -> Any:
         return visitor.visit_sub_set_term(self)

esgvoc/api/projects.py

@@ -8,7 +8,7 @@ from sqlmodel import Session, and_, col, select
 import esgvoc.api.universe as universe
 import esgvoc.core.constants as constants
 import esgvoc.core.service as service
-from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
+from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor, DataDescriptorSubSet
 from esgvoc.api.project_specs import ProjectSpecs
 from esgvoc.api.report import ProjectTermError, UniverseTermError, ValidationReport
 from esgvoc.api.pydantic_handler import instantiate_pydantic_term
@@ -483,7 +483,7 @@ def valid_term_in_all_projects(value: str) -> list[MatchingTerm]:
 
 def get_all_terms_in_collection(
     project_id: str, collection_id: str, selected_term_fields: Iterable[str] | None = None
-) -> list[DataDescriptor]:
+) -> list[DataDescriptor | DataDescriptorSubSet]:
     """
     Gets all terms of the given collection of a project.
     This function performs an exact match on the `project_id` and `collection_id`,
@@ -496,10 +496,13 @@ def get_all_terms_in_collection(
     :param collection_id: A collection id
     :type collection_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: a list of term instances. Returns an empty list if no matches are found.
-    :rtype: list[DataDescriptor]
+    :returns: A list of term instances. Each term is a full DataDescriptor when \
+    selected_term_fields is None, or a DataDescriptorSubSet when selected_term_fields is provided. \
+    Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor | DataDescriptorSubSet]
     """
     result = list()
     if connection := _get_project_connection(project_id):
@@ -610,7 +613,7 @@ def _get_all_terms_in_collection(
 
 def get_all_terms_in_project(
     project_id: str, selected_term_fields: Iterable[str] | None = None
-) -> list[DataDescriptor]:
+) -> list[DataDescriptor | DataDescriptorSubSet]:
     """
     Gets all terms of the given project.
     This function performs an exact match on the `project_id` and
@@ -621,10 +624,13 @@ def get_all_terms_in_project(
     :param project_id: A project id
     :type project_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A list of term instances. Returns an empty list if no matches are found.
-    :rtype: list[DataDescriptor]
+    :returns: A list of term instances. Each term is a full DataDescriptor when \
+    selected_term_fields is None, or a DataDescriptorSubSet when selected_term_fields is provided. \
+    Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor | DataDescriptorSubSet]
     """
     result = list()
     if connection := _get_project_connection(project_id):
@@ -638,15 +644,17 @@ def get_all_terms_in_project(
 
 def get_all_terms_in_all_projects(
     selected_term_fields: Iterable[str] | None = None,
-) -> list[tuple[str, list[DataDescriptor]]]:
+) -> list[tuple[str, list[DataDescriptor | DataDescriptorSubSet]]]:
     """
     Gets all terms of all projects.
 
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A list of tuple project_id and term instances of that project.
-    :rtype: list[tuple[str, list[DataDescriptor]]]
+    :returns: A list of tuples containing (project_id, terms). Each term is a full DataDescriptor when \
+    selected_term_fields is None, or a DataDescriptorSubSet when selected_term_fields is provided.
+    :rtype: list[tuple[str, list[DataDescriptor | DataDescriptorSubSet]]]
     """
     project_ids = get_all_projects()
     result = list()
@@ -676,7 +684,7 @@ def _get_term_in_project(term_id: str, session: Session) -> PTerm | None:
 
 def get_term_in_project(
     project_id: str, term_id: str, selected_term_fields: Iterable[str] | None = None
-) -> DataDescriptor | None:
+) -> DataDescriptor | DataDescriptorSubSet | None:
     """
     Returns the first occurrence of the terms, in the given project, whose id corresponds exactly to
     the given term id.
@@ -691,12 +699,14 @@ def get_term_in_project(
     :param term_id: The id of a term to be found.
     :type term_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A term instance. Returns `None` if no match is found.
-    :rtype: DataDescriptor | None
+    :returns: A term instance. The term is a full DataDescriptor when selected_term_fields is None, \
+    or a DataDescriptorSubSet when selected_term_fields is provided. Returns `None` if no match is found.
+    :rtype: DataDescriptor | DataDescriptorSubSet | None
     """
-    result: DataDescriptor | None = None
+    result: DataDescriptor | DataDescriptorSubSet | None = None
     if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
             term_found = _get_term_in_project(term_id, session)
@@ -714,7 +724,7 @@ def _get_term_in_collection(collection_id: str, term_id: str, session: Session)
 
 def get_term_in_collection(
     project_id: str, collection_id: str, term_id: str, selected_term_fields: Iterable[str] | None = None
-) -> DataDescriptor | None:
+) -> DataDescriptor | DataDescriptorSubSet | None:
     """
     Returns the term, in the given project and collection,
     whose id corresponds exactly to the given term id.
@@ -730,12 +740,14 @@ def get_term_in_collection(
     :param term_id: The id of a term to be found.
     :type term_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A term instance. Returns `None` if no match is found.
-    :rtype: DataDescriptor | None
+    :returns: A term instance. The term is a full DataDescriptor when selected_term_fields is None, \
+    or a DataDescriptorSubSet when selected_term_fields is provided. Returns `None` if no match is found.
+    :rtype: DataDescriptor | DataDescriptorSubSet | None
     """
-    result: DataDescriptor | None = None
+    result: DataDescriptor | DataDescriptorSubSet | None = None
     if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
             term_found = _get_term_in_collection(collection_id, term_id, session)
@@ -871,7 +883,7 @@ def _get_term_from_universe_term_id_in_project(
 
 def get_term_from_universe_term_id_in_project(
     project_id: str, data_descriptor_id: str, universe_term_id: str, selected_term_fields: Iterable[str] | None = None
-) -> tuple[str, DataDescriptor] | None:
+) -> tuple[str, DataDescriptor | DataDescriptorSubSet] | None:
     """
     Returns the term, in the given project, that corresponds to the given term in the universe.
     This function performs an exact match on the `project_id`, `data_descriptor_id`
@@ -887,12 +899,15 @@ def get_term_from_universe_term_id_in_project(
     :param universe_term_id: The id of the given universe term.
     :type universe_term_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A collection id and the project term instance. Returns `None` if no matches are found.
-    :rtype: tuple[str, DataDescriptor] | None
+    :returns: A collection id and the project term instance. The term is a full DataDescriptor when \
+    selected_term_fields is None, or a DataDescriptorSubSet when selected_term_fields is provided. \
+    Returns `None` if no matches are found.
+    :rtype: tuple[str, DataDescriptor | DataDescriptorSubSet] | None
     """
-    result: tuple[str, DataDescriptor] | None = None
+    result: tuple[str, DataDescriptor | DataDescriptorSubSet] | None = None
     if connection := _get_project_connection(project_id):
         with connection.create_session() as session:
             term_found = _get_term_from_universe_term_id_in_project(data_descriptor_id, universe_term_id, session)
@@ -904,7 +919,7 @@ def get_term_from_universe_term_id_in_project(
 
 def get_term_from_universe_term_id_in_all_projects(
     data_descriptor_id: str, universe_term_id: str, selected_term_fields: Iterable[str] | None = None
-) -> list[tuple[str, str, DataDescriptor]]:
+) -> list[tuple[str, str, DataDescriptor | DataDescriptorSubSet]]:
     """
     Returns the terms, in all projects, that correspond to the given term in the universe.
     This function performs an exact match on the `data_descriptor_id`
@@ -918,13 +933,15 @@ def get_term_from_universe_term_id_in_all_projects(
     :param universe_term_id: The id of the given universe term.
     :type universe_term_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A project_id, collection id and the project term instance. \
-    Returns an empty list if no matches are found.
-    :rtype: list[tuple[str, str, DataDescriptor]]
+    :returns: A list of tuples containing (project_id, collection_id, term). The term is a full \
+    DataDescriptor when selected_term_fields is None, or a DataDescriptorSubSet when \
+    selected_term_fields is provided. Returns an empty list if no matches are found.
+    :rtype: list[tuple[str, str, DataDescriptor | DataDescriptorSubSet]]
     """
-    result: list[tuple[str, str, DataDescriptor]] = list()
+    result: list[tuple[str, str, DataDescriptor | DataDescriptorSubSet]] = list()
     project_ids = get_all_projects()
     for project_id in project_ids:
         term_found = get_term_from_universe_term_id_in_project(

esgvoc/api/pydantic_handler.py

@@ -6,7 +6,7 @@ import esgvoc.core.constants as api_settings
 from esgvoc.core.exceptions import EsgvocDbError
 
 if TYPE_CHECKING:
-    from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
+    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
 
@@ -103,7 +103,7 @@ def get_pydantic_class(data_descriptor_id_or_term_type: str) -> type["DataDescri
         raise EsgvocDbError(f"'{data_descriptor_id_or_term_type}' pydantic class not found")
 
 
-def instantiate_pydantic_term(term: "UTerm | PTerm", selected_term_fields: Iterable[str] | None) -> "DataDescriptor":
+def instantiate_pydantic_term(term: "UTerm | PTerm", selected_term_fields: Iterable[str] | None) -> "DataDescriptor | DataDescriptorSubSet":
     """
     Instantiate a Pydantic DataDescriptor from a database term.
 
@@ -112,32 +112,42 @@ def instantiate_pydantic_term(term: "UTerm | PTerm", selected_term_fields: Itera
         selected_term_fields: Optional list of specific fields to include. If None, all fields are included.
 
     Returns:
-        A DataDescriptor instance (either DataDescriptorSubSet or the full model)
+        A DataDescriptor instance (full model) when selected_term_fields is None,
+        or a DataDescriptorSubSet instance when selected_term_fields is provided.
     """
     from esgvoc.api.data_descriptors.data_descriptor import DataDescriptorSubSet
 
     type = term.specs[api_settings.TERM_TYPE_JSON_KEY]
     if selected_term_fields is not None:
-        subset = DataDescriptorSubSet(id=term.id, type=type)
-
-        # Get model field defaults to use when fields are missing from term.specs
-        model_fields = DataDescriptorSubSet.model_fields
+        # Build data dict with only id (truly mandatory) + selected fields
+        data = {
+            "id": term.id,
+        }
 
+        # Add selected fields from term.specs, but only if they exist
         for field in selected_term_fields:
-            # Use model's default value if field is missing from specs
-            if field in model_fields and field not in term.specs:
-                default_value = model_fields[field].default
-                setattr(subset, field, default_value if default_value is not None else term.specs.get(field, None))
-            else:
-                setattr(subset, field, term.specs.get(field, None))
+            if field in term.specs:
+                data[field] = term.specs[field]
+
+        # Create instance with all fields initially
+        # We need type for validation, will remove it if not selected
+        if "type" not in data:
+            data["type"] = type
+        if "description" not in data:
+            data["description"] = ""  # Use default value
+
+        subset = DataDescriptorSubSet.model_construct(**data)
+
+        # Now remove unselected optional fields using delattr
+        # This maintains backward compatibility (hasattr will return False)
+        if "type" not in selected_term_fields and hasattr(subset, "type"):
+            delattr(subset, "type")
+        if "description" not in selected_term_fields and hasattr(subset, "description"):
+            delattr(subset, "description")
+
+        # Mark which fields were actually set
+        subset.__pydantic_fields_set__ = {"id"} | set(selected_term_fields)
 
-        for field in DataDescriptorSubSet.MANDATORY_TERM_FIELDS:
-            # Use model's default value if field is missing from specs
-            if field in model_fields and field not in term.specs:
-                default_value = model_fields[field].default
-                setattr(subset, field, default_value if default_value is not None else term.specs.get(field, None))
-            else:
-                setattr(subset, field, term.specs.get(field, None))
         return subset
     else:
         term_class = get_pydantic_class(type)

esgvoc/api/universe.py

@@ -3,7 +3,7 @@ from typing import Iterable, Sequence
 from sqlalchemy import text
 from sqlmodel import Session, col, select
 
-from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
+from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor, DataDescriptorSubSet
 from esgvoc.api.pydantic_handler import instantiate_pydantic_term
 from esgvoc.api.search import (
     Item,
@@ -28,7 +28,7 @@ def _get_all_terms_in_data_descriptor(
 
 def get_all_terms_in_data_descriptor(
     data_descriptor_id: str, selected_term_fields: Iterable[str] | None = None
-) -> list[DataDescriptor]:
+) -> list[DataDescriptor | DataDescriptorSubSet]:
     """
     Gets all the terms of the given data descriptor.
     This function performs an exact match on the `data_descriptor_id` and does not search
@@ -38,10 +38,13 @@ def get_all_terms_in_data_descriptor(
     :param data_descriptor_id: A data descriptor id
     :type data_descriptor_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: a list of term instances. Returns an empty list if no matches are found.
-    :rtype: list[DataDescriptor]
+    :returns: A list of term instances. Each term is a full DataDescriptor when \
+    selected_term_fields is None, or a DataDescriptorSubSet when selected_term_fields is provided. \
+    Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor | DataDescriptorSubSet]
     """
     with get_universe_session() as session:
         data_descriptor = _get_data_descriptor_in_universe(data_descriptor_id, session)
@@ -74,16 +77,18 @@ def get_all_data_descriptors_in_universe() -> list[str]:
     return result
 
 
-def get_all_terms_in_universe(selected_term_fields: Iterable[str] | None = None) -> list[DataDescriptor]:
+def get_all_terms_in_universe(selected_term_fields: Iterable[str] | None = None) -> list[DataDescriptor | DataDescriptorSubSet]:
     """
     Gets all the terms of the universe.
     Terms are unique within a data descriptor but may have some synonyms in the universe.
 
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A list of term instances.
-    :rtype: list[DataDescriptor]
+    :returns: A list of term instances. Each term is a full DataDescriptor when \
+    selected_term_fields is None, or a DataDescriptorSubSet when selected_term_fields is provided.
+    :rtype: list[DataDescriptor | DataDescriptorSubSet]
     """
     result = list()
     with get_universe_session() as session:
@@ -104,7 +109,7 @@ def _get_term_in_data_descriptor(data_descriptor_id: str, term_id: str, session:
 
 def get_term_in_data_descriptor(
     data_descriptor_id: str, term_id: str, selected_term_fields: Iterable[str] | None = None
-) -> DataDescriptor | None:
+) -> DataDescriptor | DataDescriptorSubSet | None:
     """
     Returns the term, in the given data descriptor, whose id corresponds exactly to the given term id.
     This function performs an exact match on the `term_id` and the `data_descriptor_id` and does
@@ -116,10 +121,12 @@ def get_term_in_data_descriptor(
     :param term_id: The id of a term to be found.
     :type term_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A term instance. Returns `None` if no match is found.
-    :rtype: DataDescriptor | None
+    :returns: A term instance. The term is a full DataDescriptor when selected_term_fields is None, \
+    or a DataDescriptorSubSet when selected_term_fields is provided. Returns `None` if no match is found.
+    :rtype: DataDescriptor | DataDescriptorSubSet | None
     """
     with get_universe_session() as session:
         term_found = _get_term_in_data_descriptor(data_descriptor_id, term_id, session)
@@ -137,7 +144,7 @@ def _get_term_in_universe(term_id: str, session: Session) -> UTerm | None:
     return result
 
 
-def get_term_in_universe(term_id: str, selected_term_fields: Iterable[str] | None = None) -> DataDescriptor | None:
+def get_term_in_universe(term_id: str, selected_term_fields: Iterable[str] | None = None) -> DataDescriptor | DataDescriptorSubSet | None:
     """
     Returns the first occurrence of the terms, in the universe, whose id corresponds exactly to
     the given term id.
@@ -148,10 +155,12 @@ def get_term_in_universe(term_id: str, selected_term_fields: Iterable[str] | Non
     :param term_id: The id of a term to be found.
     :type term_id: str
     :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
-    fields of the terms are returned. If empty, selects the id and type fields.
+    fields of the terms are returned (full DataDescriptor). If provided, only the selected fields \
+    are included (returns DataDescriptorSubSet with id + selected fields that exist).
     :type selected_term_fields: Iterable[str] | None
-    :returns: A term instance. Returns `None` if no match is found.
-    :rtype: DataDescriptor | None
+    :returns: A term instance. The term is a full DataDescriptor when selected_term_fields is None, \
+    or a DataDescriptorSubSet when selected_term_fields is provided. Returns `None` if no match is found.
+    :rtype: DataDescriptor | DataDescriptorSubSet | None
     """
     with get_universe_session() as session:
         term_found = _get_term_in_universe(term_id, session)

esgvoc/cli/get.py

@@ -107,7 +107,7 @@ def display(data: Any):
 @app.command()
 def get(
     keys: List[str] = typer.Argument(..., help="List of keys in XXXX:YYYY:ZZZZ format"),
-    select: Optional[List[str]] = typer.Option(None, "--select", help="keys selected for the result"),
+    select: Optional[List[str]] = typer.Option(None, "--select", help="keys selected for the result. Can be used as --select field1 --select field2 or --select [field1,field2]"),
 ):
     """
     Retrieve a specific value from the database system.\n
@@ -117,25 +117,65 @@ def get(
 
     Usage:\n
         `get <project>:<collection>:<term>`\n
+        `get <project>:<collection>:<term> --select <field>`\n
+        `get <project>:<collection>:<term> --select [<field1>,<field2>,...]`\n
     \n
     Arguments:\n
         <project>\tThe project id to query. like `cmip6plus`\n
         <collection>\tThe collection id in the specified database.\n
         <term>\t\tThe term id within the specified collection.\n
     \n
-    Example:
-        To retrieve the value from the "cmip6plus" project, under the "institution_id" column, the term with the identifier "ipsl", you would use: \n
+    Options:\n
+        --select\tSelect specific fields to display. By default, all fields are returned.\n
+        \t\tThe result will always include the 'id' field plus the selected fields.\n
+        \t\tYou can use this option in multiple ways:\n
+        \t\t  - Single field: --select drs_name\n
+        \t\t  - Multiple flags: --select drs_name --select description\n
+        \t\t  - Bracket notation: --select [drs_name,description]\n
+    \n
+    Examples:\n
+        Retrieve full term information:\n
             `get cmip6plus:institution_id:ipsl`\n
-        The default project is the universe CV : the argument would be like `universe:institution:ipsl` or `:institution:ipsl` \n
-        - to get list of available term from universe institution `:institution:` \n
+        \n
+        Retrieve only specific fields:\n
+            `get :activity:volmip --select drs_name`\n
+            Returns: id='volmip' drs_name='VolMIP'\n
+        \n
+        Retrieve multiple fields using bracket notation:\n
+            `get :activity:volmip --select [drs_name,description]`\n
+            Returns: id='volmip' drs_name='VolMIP' description=...\n
+        \n
+        Retrieve multiple fields using multiple flags:\n
+            `get :activity:volmip --select drs_name --select description`\n
+        \n
+        List all terms in a collection with selected fields:\n
+            `get :activity: --select drs_name`\n
+        \n
+        The default project is the universe CV: the argument would be like `universe:institution:ipsl` or `:institution:ipsl`\n
         \n
     \n
     Notes:\n
         - Ensure data exist in your system before using this command (use `esgvoc status` command to see whats available).\n
         - Use a colon (`:`) to separate the parts of the argument.  \n
-        - if more than one argument is given i.e get X:Y:Z A:B:C the 2 results are appended. \n
+        - If more than one argument is given i.e get X:Y:Z A:B:C the 2 results are appended. \n
+        - The 'id' field is always included in the result, even when using --select.\n
     \n
     """
+    # Parse select parameter to handle bracket notation [field1,field2,...]
+    parsed_select = None
+    if select is not None:
+        parsed_select = []
+        for item in select:
+            # Check if item is in bracket notation like [field1,field2]
+            if item.startswith("[") and item.endswith("]"):
+                # Remove brackets and split by comma
+                fields = item[1:-1].split(",")
+                # Strip whitespace and quotes from each field
+                parsed_select.extend([f.strip().strip("'\"") for f in fields if f.strip()])
+            else:
+                # Regular field, just add it
+                parsed_select.append(item.strip().strip("'\""))
+
     known_projects = get_all_projects()
 
     # Validate and process each key
@@ -146,9 +186,9 @@ def get(
         what = what if what != "" else None
         who = who if who != "" else None
         if where == "" or where == "universe":
-            res = handle_universe(what, who, select)
+            res = handle_universe(what, who, parsed_select)
         elif where in known_projects:
-            res = handle_project(where, what, who, select)
+            res = handle_project(where, what, who, parsed_select)
         else:
             res = handle_unknown(where, what, who)
 

{esgvoc-2.0.2.dist-info → esgvoc-2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: esgvoc
-Version: 2.0.2
+Version: 2.1.0
 Summary: python library and CLI to interact with WCRP CVs
 Project-URL: Repository, https://github.com/ESGF/esgf-vocab
 Author-email: Sébastien Gardoll <sebastien@gardoll.fr>, Guillaume Levavasseur <guillaume.levavasseur@ipsl.fr>, Laurent Troussellier <laurent.troussellier@ipsl.fr>

{esgvoc-2.0.2.dist-info → esgvoc-2.1.0.dist-info}/RECORD

@@ -1,12 +1,12 @@
-esgvoc/__init__.py,sha256=7eC8qPIlBApL95flwVy-OGVzl6hUFFu0pPPTPUtd7k0,66
+esgvoc/__init__.py,sha256=2csMOm138N0yfN9CTw8qW94oSOWgtMvOh5_oryxlx9E,66
 esgvoc/api/__init__.py,sha256=5MK2lhD2L8DC_qlVjj5KNJNQ90UkX60eoPJOBuSG18A,3916
 esgvoc/api/project_specs.py,sha256=-kjNx6EcFRKJrMU7yy_0YmMqTv4Crvh4e2fPI2wGrbI,4285
-esgvoc/api/projects.py,sha256=dhvBhAAokptUvkA3B9tPfoQsD4F-jGCSA4t5tThXcgw,59018
+esgvoc/api/projects.py,sha256=6KCmVnTOnni6DcNK8oQi8TRdBQJ5ftg7RF2a1-tMOvc,61187
 esgvoc/api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-esgvoc/api/pydantic_handler.py,sha256=vWNBlzkQu_fx1bbfmAcFZts9C36VfBd-9yge5q54TLQ,6058
+esgvoc/api/pydantic_handler.py,sha256=10m7h7WlMDwaToaa7FVAB5bV9I_7_dzY7QhupxsPuVQ,6254
 esgvoc/api/report.py,sha256=OlK5ApnaikMKmC6FyJ1uTSBeTezZe85yTCJwsk14uZE,3526
 esgvoc/api/search.py,sha256=W0RHTymqn67exjp0DJWNMC9mxX4EpMgLKEdMXsOYeLw,6665
-esgvoc/api/universe.py,sha256=K0BbX8bCM2x0OY_-fkd0UCEj4_Vq4hRE7UVn43OvEKw,21257
+esgvoc/api/universe.py,sha256=6w4va8sm0afunAOjelfIwE7kytMT5a_RA-czw4JT3hA,22455
 esgvoc/api/data_descriptors/__init__.py,sha256=yqTDrr7VydWPUUkoZ3EC9c4xclHrKXKscSDB8cnELmM,8090
 esgvoc/api/data_descriptors/activity.py,sha256=ZJ5_jHNaFcX78Hho_ve-G7YiArSm_-U7wVd0rtnKzoE,2179
 esgvoc/api/data_descriptors/archive.py,sha256=5tmY5AsKAvyoU8839VdzLCbvP0pAhrCYP6EggZXFMTY,131
@@ -17,7 +17,7 @@ esgvoc/api/data_descriptors/citation_url.py,sha256=R0bjM8MU6IdqvLzc4q0aeAbndmRod
 esgvoc/api/data_descriptors/contact.py,sha256=q1tNm8VcG7xvv4ophVIuy58_2y-rSozs86c7_gMupdk,135
 esgvoc/api/data_descriptors/conventions.py,sha256=U3qugWG1KRIqxQqvUTFFc5v9DtTdxNAIQxc_bZAA6ns,1072
 esgvoc/api/data_descriptors/creation_date.py,sha256=QftPsJwoEmpitTs6xnWHVGZytppYymiouD33Vanp8gM,566
-esgvoc/api/data_descriptors/data_descriptor.py,sha256=p-ACPn8gRfZ4N7TK2Vno95KHr-WOKjSNhX_oDdfi0g0,3281
+esgvoc/api/data_descriptors/data_descriptor.py,sha256=ndenK4yInquk8ehiuIAQpIuZH9xkCVhffUU7z1mOwxI,4832
 esgvoc/api/data_descriptors/data_specs_version.py,sha256=Sy1JI2bZOP0RNylkGMfJveV-OhSQgyPYCwkhUuKDHyo,1003
 esgvoc/api/data_descriptors/date.py,sha256=mkWivY0orl0wha38sMamrVbUbdZks-iUS_Wf6Gqz0-4,132
 esgvoc/api/data_descriptors/directory_date.py,sha256=lq50IGnUrgWstPHjwW0w0_DMFDYDet19BesZWly9nQE,743
@@ -62,7 +62,7 @@ esgvoc/api/data_descriptors/EMD_models/arrangement.py,sha256=W8PR1dJ4DJTKDIY2h-z
 esgvoc/api/data_descriptors/EMD_models/calendar.py,sha256=jBLtjK5aQBoPPnWzPse6ZDRhlcBAjvEAJitBvm1kmZU,132
 esgvoc/api/data_descriptors/EMD_models/cell_variable_type.py,sha256=T12HPRU1l3HGoQEkfMLee7NQjwE_nOyBIU5mIk6hd1I,488
 esgvoc/api/data_descriptors/EMD_models/component_type.py,sha256=3oMEtc9DMqHnN09zbRNKN6FEHub5i4O_Umw_5j0of6E,137
-esgvoc/api/data_descriptors/EMD_models/coordinate.py,sha256=siYPtEeyBfrXnwIIyVKYYlhlFQQTjOu0yKMeHG11lgU,2795
+esgvoc/api/data_descriptors/EMD_models/coordinate.py,sha256=5YNb8eT0bGES4_FoQ-1yH3WolXZkJ3SawBVk4pY6Y4Q,2470
 esgvoc/api/data_descriptors/EMD_models/grid_mapping.py,sha256=dI0tH5Ag36af-39OYNuKKKoF52xyxRhtN8Xd3z3D6F4,436
 esgvoc/api/data_descriptors/EMD_models/grid_region.py,sha256=GUaJwSidLHVCdKNJetPgAAoqyBqMfyRWx9495Y1-T7k,445
 esgvoc/api/data_descriptors/EMD_models/grid_type.py,sha256=Z4MFHr8WWIVskv8w9JsjtFeaSaAyWYfjuNdCuxt52_Y,444
@@ -72,8 +72,8 @@ esgvoc/api/data_descriptors/EMD_models/horizontal_subgrid.py,sha256=vSUsrDhRX6VV
 esgvoc/api/data_descriptors/EMD_models/horizontal_units.py,sha256=npSeoQNf0-OqFCzhLGwZGXIjoTK2R7DE288o3-qPYLQ,139
 esgvoc/api/data_descriptors/EMD_models/model.py,sha256=CGQ9iosUqHr0zboJnugEsPJxMBgWiOp7WX6dxE8dCfw,5031
 esgvoc/api/data_descriptors/EMD_models/model_component.py,sha256=Cy3kF2HccH5VObes3AWcEdimOw5JSBMGhP3Yr8-Op4c,4629
-esgvoc/api/data_descriptors/EMD_models/reference.py,sha256=ZjNsbXQkcAMFsLSPVbQG_5sq2ovBhKa-309yRLydkOY,2517
-esgvoc/api/data_descriptors/EMD_models/resolution.py,sha256=CcBUAzeYSkvVjeCfhFSwTND6atldZQxS3rzNZqldmjI,1162
+esgvoc/api/data_descriptors/EMD_models/reference.py,sha256=-Gywq1a-H1yhqJSjI_Vn9HAalGX_A5iXrGjNfmq71Fg,2464
+esgvoc/api/data_descriptors/EMD_models/resolution.py,sha256=iFT4Bm0xiK4AKgzMdQ1u9_9Zf0_HfQivGvITiR8Hv3I,1261
 esgvoc/api/data_descriptors/EMD_models/temporal_refinement.py,sha256=7vSJb5kUkoH_0AWKOLO-MsuJ9JCYGsuE0ts4CbQm09A,421
 esgvoc/api/data_descriptors/EMD_models/truncation_method.py,sha256=TBKVGeha7Tjg2xSrLVRzhCQdQc5Y14Vx-aoVjJRz1eQ,383
 esgvoc/api/data_descriptors/EMD_models/vertical_computational_grid.py,sha256=3EQtYfLI8ncYkxrvnPgaoPvdNTqdzLNcjW8AkSjlG9U,4176
@@ -110,7 +110,7 @@ esgvoc/cli/cmor.py,sha256=Q1Q0AvP3Up8wAkylSGveBw1c_Mqo752wEE2NTUDqCYw,1098
 esgvoc/cli/config.py,sha256=iPU6OKkHQEo2qXdzjl35C5-C_I8pu122E2H7xj0HpYs,52555
 esgvoc/cli/drs.py,sha256=X89syVrxs82ZIc1YdWRPw_HmafOZH1u-wXRe6N-xBcM,9427
 esgvoc/cli/find.py,sha256=DxpEvSbQIJ3-XL-pgH5RicBzS3asjG2Cn_fJhjXKSoU,4497
-esgvoc/cli/get.py,sha256=Ucz0nE68wLB3K55aJfDnVNt8jCvPvBL4c1qmS_YHTh0,5451
+esgvoc/cli/get.py,sha256=hxVUEkVOcZPq47fHXA4SRPTwlCYDvLN3g-6sw9S8so8,7368
 esgvoc/cli/install.py,sha256=qTtWQp0SlpQ7uIJnUeFUfdU0RRb2s55QAv11TogfwGk,1381
 esgvoc/cli/main.py,sha256=QzDhSXRnc1e3RlXD7KJBCwlnQV_DL-f9zaAlzlqoyx4,1866
 esgvoc/cli/offline.py,sha256=I9gccId98FLXPQ9VOmmZQ9aU_zfZYtCGZyO7XabQnc8,9007
@@ -140,8 +140,8 @@ esgvoc/core/service/term_cache.py,sha256=xH8No2w8KXDg7N3L9b4bv-dMGwqvlbko1bPxPMT
 esgvoc/core/service/uri_resolver.py,sha256=USDvnEkJwPJgdGduup_EQJODHZyAWj62MG8-AEaLMTo,3963
 esgvoc/core/service/configuration/config_manager.py,sha256=adKeK8xDE72UIfYqQ4pc7pPxAmBuCsybyx7ZdchbL6U,8797
 esgvoc/core/service/configuration/setting.py,sha256=aaBE6P8TttQr0kJjSRNH4Vaa_guWPFQGHdB24B1oYtU,13514
-esgvoc-2.0.2.dist-info/METADATA,sha256=H-uYgjZG98AWezy4zTNgd-LULeUrJfnUU0waFg1N4jw,2368
-esgvoc-2.0.2.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-esgvoc-2.0.2.dist-info/entry_points.txt,sha256=ZXufSC7Jlx1lb52U6Buv9IitJMcqAAXOerR2V9DaIto,48
-esgvoc-2.0.2.dist-info/licenses/LICENSE.txt,sha256=rWJoZt3vach8ZNdLq-Ee5djzCMFnJ1gIfBeJU5RIop4,21782
-esgvoc-2.0.2.dist-info/RECORD,,
+esgvoc-2.1.0.dist-info/METADATA,sha256=NSc8Jrv6DX_8Kaav4TQfyjryfJ-lc7vcjtL0_92aPbE,2368
+esgvoc-2.1.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+esgvoc-2.1.0.dist-info/entry_points.txt,sha256=ZXufSC7Jlx1lb52U6Buv9IitJMcqAAXOerR2V9DaIto,48
+esgvoc-2.1.0.dist-info/licenses/LICENSE.txt,sha256=rWJoZt3vach8ZNdLq-Ee5djzCMFnJ1gIfBeJU5RIop4,21782
+esgvoc-2.1.0.dist-info/RECORD,,