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

esgvoc/api/report.py

@@ -1,86 +1,123 @@
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, Protocol
+
+from pydantic import BaseModel, computed_field
 
 import esgvoc.core.constants as api_settings
 from esgvoc.core.db.models.mixins import TermKind
-from esgvoc.core.db.models.project import PTerm
-from esgvoc.core.db.models.universe import UTerm
 
 
-class ValidationErrorVisitor(ABC):
-    @abstractmethod
+class ValidationErrorVisitor(Protocol):
+    """
+    Specifications for a term validation error visitor.
+    """
     def visit_universe_term_error(self, error: "UniverseTermError") -> Any:
+        """Visit a universe term error."""
         pass
 
-    @abstractmethod
     def visit_project_term_error(self, error: "ProjectTermError") -> Any:
+        """Visit a project term error."""
         pass
 
 
-class BasicValidationErrorVisitor(ValidationErrorVisitor):
-    def visit_universe_term_error(self, error: "UniverseTermError") -> Any:
-        term_id = error.term[api_settings.TERM_ID_JSON_KEY]
-        result = f"The term {term_id} from the data descriptor {error.data_descriptor_id} "+\
-                 f"does not validate the given value '{error.value}'"
-        return result
-
-    def visit_project_term_error(self, error: "ProjectTermError") -> Any:
-        term_id = error.term[api_settings.TERM_ID_JSON_KEY]
-        result = f"The term {term_id} from the collection {error.collection_id} "+\
-                 f"does not validate the given value '{error.value}'"
-        return result
-
-
-class ValidationError(ABC):
-    def __init__(self,
-                 value: str):
-        self.value: str = value
-    
+class ValidationError(BaseModel, ABC):
+    """
+    Generic class for the term validation error.
+    """
+    value: str
+    """The given value that is invalid."""
+    term: dict
+    """JSON specification of the term."""
+    term_kind: TermKind
+    """The kind of term."""
+    @computed_field # type: ignore
+    @property
+    def class_name(self) -> str:
+       """The class name of the issue for JSON serialization."""
+       return self.__class__.__name__
     @abstractmethod
     def accept(self, visitor: ValidationErrorVisitor) -> Any:
+        """
+        Accept a validation error visitor.
+
+        :param visitor: The validation error visitor.
+        :type visitor: ValidationErrorVisitor
+        :return: Depending on the visitor.
+        :rtype: Any
+        """
         pass
 
 class UniverseTermError(ValidationError):
-    def __init__(self,
-                 value: str,
-                 term: UTerm):
-        super().__init__(value)
-        self.term: dict = term.specs
-        self.term_kind: TermKind = term.kind
-        self.data_descriptor_id: str = term.data_descriptor.id
+    """
+    A validation error on a term from the universe.
+    """
+
+    data_descriptor_id: str
+    """The data descriptor that the term belongs."""
 
     def accept(self, visitor: ValidationErrorVisitor) -> Any:
         return visitor.visit_universe_term_error(self)
 
+    def __str__(self) -> str:
+        term_id = self.term[api_settings.TERM_ID_JSON_KEY]
+        result = f"The term {term_id} from the data descriptor {self.data_descriptor_id} "+\
+                 f"does not validate the given value '{self.value}'"
+        return result
+    def __repr__(self) -> str:
+        return self.__str__()
+
 
 class ProjectTermError(ValidationError):
-    def __init__(self,
-                 value: str,
-                 term: PTerm):
-        super().__init__(value)
-        self.term: dict = term.specs
-        self.term_kind: TermKind = term.kind
-        self.collection_id: str = term.collection.id
+    """
+    A validation error on a term from a project.
+    """
+
+    collection_id: str
+    """The collection id that the term belongs"""
 
     def accept(self, visitor: ValidationErrorVisitor) -> Any:
         return visitor.visit_project_term_error(self)
 
+    def __str__(self) -> str:
+        term_id = self.term[api_settings.TERM_ID_JSON_KEY]
+        result = f"The term {term_id} from the collection {self.collection_id} "+\
+                 f"does not validate the given value '{self.value}'"
+        return result
+    def __repr__(self) -> str:
+        return self.__str__()
+
+
+class ValidationReport(BaseModel):
+    """
+    Term validation report.
+    """
+
+    expression: str
+    """The given expression."""
+
+    errors: list[UniverseTermError|ProjectTermError]
+    """The validation errors."""
+
+    @computed_field # type: ignore
+    @property
+    def nb_errors(self) -> int:
+        """The number of validation errors."""
+        return len(self.errors) if self.errors else 0
+
+    @computed_field # type: ignore
+    @property
+    def validated(self) -> bool:
+        """The expression is validated or not."""
+        return False if self.errors else True
 
-class ValidationReport:
-    def __init__(self,
-                 given_expression: str,
-                 errors: list[ValidationError]):
-        self.expression: str = given_expression
-        self.errors: list[ValidationError] = errors
-        self.nb_errors = len(self.errors) if self.errors else 0
-        self.validated: bool = False if errors else True
-        self.message = f"'{self.expression}' has {self.nb_errors} error(s)"
-   
     def __len__(self) -> int:
         return self.nb_errors
-    
+
     def __bool__(self) -> bool:
         return self.validated
-    
+
+    def __str__(self) -> str:
+        return f"'{self.expression}' has {self.nb_errors} error(s)"
+
     def __repr__(self) -> str:
-        return self.message
+        return self.__str__()

esgvoc/api/search.py

@@ -1,35 +1,55 @@
-from dataclasses import dataclass
+from typing import Iterable
 from enum import Enum
-
 from pydantic import BaseModel
 from sqlalchemy import ColumnElement, func
 from sqlmodel import col
 
 
-@dataclass
-class MatchingTerm:
+class MatchingTerm(BaseModel):
+    """
+    Place holder for a term that matches a value (term validation).
+    """
     project_id: str
+    """The project id to which the term belongs."""
     collection_id: str
+    """The collection id to which the term belongs."""
     term_id: str
+    """The term id."""
 
 
 class SearchType(Enum):
-    EXACT = ("exact",)
-    LIKE = ("like",)  # can interpret %
-    STARTS_WITH = ("starts_with",)  # can interpret %
+    """
+    The search types used for to find terms.
+    """
+    EXACT = "exact"
+    """Performs exact match."""
+    LIKE = "like"  # can interpret %
+    """As SQL operator, it can interpret % as a wildcard."""
+    STARTS_WITH = "starts_with"  # can interpret %
+    """Prefix based search."""
     ENDS_WITH = "ends_with"  # can interpret %
-    REGEX = ("regex",)
+    """Suffix based search."""
+    REGEX = "regex"
+    """Search based on regex."""
 
 
 class SearchSettings(BaseModel):
+    """
+    Search configuration.
+    """
     type: SearchType = SearchType.EXACT
+    """The type of search."""
     case_sensitive: bool = True
+    """Enable case sensitivity or not."""
     not_operator: bool = False
+    """Give the opposite result like the NOT SQL operator."""
+    selected_term_fields: Iterable[str]|None = None
+    """Term fields to select"""
 
 
-def create_str_comparison_expression(field: str,
-                                     value: str,
-                                     settings: SearchSettings|None) -> ColumnElement:
+def _create_str_comparison_expression(field: str,
+                                      value: str,
+                                      settings: SearchSettings|None) -> ColumnElement:
     '''
     SQLite LIKE is case insensitive (and so STARTS/ENDS_WITH which are implemented with LIKE).
     So the case sensitive LIKE is implemented with REGEX.

esgvoc/api/universe.py

@@ -1,10 +1,10 @@
-from typing import Sequence
+from typing import Sequence, Iterable
 
 from esgvoc.api._utils import (get_universe_session,
                                instantiate_pydantic_terms)
-from esgvoc.api.search import SearchSettings, create_str_comparison_expression
-from esgvoc.core.db.models.universe import DataDescriptor, UTerm
-from pydantic import BaseModel
+from esgvoc.api.search import SearchSettings, _create_str_comparison_expression
+from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
+from esgvoc.core.db.models.universe import UDataDescriptor, UTerm
 from sqlmodel import Session, select
 
 
@@ -13,10 +13,10 @@ def _find_terms_in_data_descriptor(data_descriptor_id: str,
                                    session: Session,
                                    settings: SearchSettings|None) -> Sequence[UTerm]:
     """Settings only apply on the term_id comparison."""
-    where_expression = create_str_comparison_expression(field=UTerm.id,
-                                                        value=term_id,
-                                                        settings=settings)
-    statement = select(UTerm).join(DataDescriptor).where(DataDescriptor.id==data_descriptor_id,
+    where_expression = _create_str_comparison_expression(field=UTerm.id,
+                                                         value=term_id,
+                                                         settings=settings)
+    statement = select(UTerm).join(UDataDescriptor).where(UDataDescriptor.id==data_descriptor_id,
                                                          where_expression)
     results = session.exec(statement)
     result = results.all()
@@ -26,7 +26,7 @@ def _find_terms_in_data_descriptor(data_descriptor_id: str,
 def find_terms_in_data_descriptor(data_descriptor_id: str,
                                   term_id: str,
                                   settings: SearchSettings|None = None) \
-                                     -> list[BaseModel]:
+                                     -> list[DataDescriptor]:
     """
     Finds one or more terms in the given data descriptor based on the specified search settings.
     This function performs an exact match on the `data_descriptor_id` and 
@@ -39,9 +39,9 @@ def find_terms_in_data_descriptor(data_descriptor_id: str,
     returns an empty list.
 
     Behavior based on search type:
-    - `EXACT` and absence of `settings`: returns zero or one Pydantic term instance in the list.
-    - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more Pydantic term
-      instances in the list.
+        - `EXACT` and absence of `settings`: returns zero or one term instance in the list.
+        - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more term \
+          instances in the list.
 
     :param data_descriptor_id: A data descriptor id
     :type data_descriptor_id: str
@@ -49,23 +49,22 @@ def find_terms_in_data_descriptor(data_descriptor_id: str,
     :type term_id: str
     :param settings: The search settings
     :type settings: SearchSettings|None
-    :returns: A list of Pydantic model term instances.
-    Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+    :returns: A list of term instances. Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor]
     """
-    result: list[BaseModel] = list()
+    result: list[DataDescriptor] = list()
     with get_universe_session() as session:
         terms = _find_terms_in_data_descriptor(data_descriptor_id, term_id, session, settings)
-        instantiate_pydantic_terms(terms, result)
+        instantiate_pydantic_terms(terms, result, settings.selected_term_fields if settings else None)
     return result
 
 
 def _find_terms_in_universe(term_id: str,
                             session: Session,
                             settings: SearchSettings|None) -> Sequence[UTerm]:
-    where_expression = create_str_comparison_expression(field=UTerm.id,
-                                                        value=term_id,
-                                                        settings=settings)
+    where_expression = _create_str_comparison_expression(field=UTerm.id,
+                                                         value=term_id,
+                                                         settings=settings)
     statement = select(UTerm).where(where_expression)
     results = session.exec(statement).all()
     return results
@@ -73,7 +72,7 @@ def _find_terms_in_universe(term_id: str,
 
 def find_terms_in_universe(term_id: str,
                            settings: SearchSettings|None = None) \
-                              -> list[BaseModel]:
+                              -> list[DataDescriptor]:
     """
     Finds one or more terms of the universe.
     The given `term_id` is searched according to the search type specified in 
@@ -87,36 +86,38 @@ def find_terms_in_universe(term_id: str,
     :type term_id: str
     :param settings: The search settings
     :type settings: SearchSettings|None
-    :returns: A list of Pydantic term instances. Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+    :returns: A list of term instances. Returns an empty list if no matches are found.
+    :rtype: list[DataDescriptor]
     """
-    result: list[BaseModel] = list()
+    result: list[DataDescriptor] = list()
     with get_universe_session() as session:
         terms = _find_terms_in_universe(term_id, session, settings)
-        instantiate_pydantic_terms(terms, result)
+        instantiate_pydantic_terms(terms, result, settings.selected_term_fields if settings else None)
     return result
 
 
-def _get_all_terms_in_data_descriptor(data_descriptor: DataDescriptor) -> list[BaseModel]:
-    result: list[BaseModel] = list()
-    instantiate_pydantic_terms(data_descriptor.terms, result)
+def _get_all_terms_in_data_descriptor(data_descriptor: UDataDescriptor,
+                                      selected_term_fields: Iterable[str]|None) -> list[DataDescriptor]:
+    result: list[DataDescriptor] = list()
+    instantiate_pydantic_terms(data_descriptor.terms, result, selected_term_fields)
     return result
 
 
 def _find_data_descriptors_in_universe(data_descriptor_id: str,
                                        session: Session,
-                                       settings: SearchSettings|None) -> Sequence[DataDescriptor]:
-    where_expression = create_str_comparison_expression(field=DataDescriptor.id,
-                                                        value=data_descriptor_id,
-                                                        settings=settings)
-    statement = select(DataDescriptor).where(where_expression)
+                                       settings: SearchSettings|None) -> Sequence[UDataDescriptor]:
+    where_expression = _create_str_comparison_expression(field=UDataDescriptor.id,
+                                                         value=data_descriptor_id,
+                                                         settings=settings)
+    statement = select(UDataDescriptor).where(where_expression)
     results = session.exec(statement)
     result = results.all()      
     return result
 
 
-def get_all_terms_in_data_descriptor(data_descriptor_id: str) \
-                                        -> list[BaseModel]:
+def get_all_terms_in_data_descriptor(data_descriptor_id: str,
+                                     selected_term_fields: Iterable[str]|None = None) \
+                                                                            -> list[DataDescriptor]:
     """
     Gets all the terms of the given data descriptor.
     This function performs an exact match on the `data_descriptor_id` and does **not** search 
@@ -125,8 +126,11 @@ def get_all_terms_in_data_descriptor(data_descriptor_id: str) \
 
     :param data_descriptor_id: A data descriptor id
     :type data_descriptor_id: str
-    :returns: a list of Pydantic term instances. Returns an empty list if no matches are found.
-    :rtype: list[BaseModel]
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned.
+    :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]
     """
     with get_universe_session() as session:
         data_descriptors = _find_data_descriptors_in_universe(data_descriptor_id,
@@ -134,7 +138,7 @@ def get_all_terms_in_data_descriptor(data_descriptor_id: str) \
                                                               None)
         if data_descriptors:
             data_descriptor = data_descriptors[0]
-            result = _get_all_terms_in_data_descriptor(data_descriptor)
+            result = _get_all_terms_in_data_descriptor(data_descriptor, selected_term_fields)
         else:
             result = list()
     return result
@@ -153,9 +157,9 @@ def find_data_descriptors_in_universe(data_descriptor_id: str,
     If the provided `data_descriptor_id` is not found, the function returns an empty list.
     
     Behavior based on search type:
-    - `EXACT` and absence of `settings`: returns zero or one data descriptor context in the list.
-    - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more
-      data descriptor contexts in the list.
+        - `EXACT` and absence of `settings`: returns zero or one data descriptor context in the list.
+        - `REGEX`, `LIKE`, `STARTS_WITH` and `ENDS_WITH`: returns zero, one or more \
+          data descriptor contexts in the list.
 
     :param data_descriptor_id: A data descriptor id to be found
     :type data_descriptor_id: str
@@ -174,8 +178,8 @@ def find_data_descriptors_in_universe(data_descriptor_id: str,
     return result
 
 
-def _get_all_data_descriptors_in_universe(session: Session) -> Sequence[DataDescriptor]:
-    statement = select(DataDescriptor)
+def _get_all_data_descriptors_in_universe(session: Session) -> Sequence[UDataDescriptor]:
+    statement = select(UDataDescriptor)
     data_descriptors = session.exec(statement)
     result = data_descriptors.all()
     return result
@@ -196,23 +200,28 @@ def get_all_data_descriptors_in_universe() -> list[str]:
     return result
 
 
-def get_all_terms_in_universe() -> list[BaseModel]:
+def get_all_terms_in_universe(selected_term_fields: Iterable[str]|None = None) -> list[DataDescriptor]:
     """
     Gets all the terms of the universe.
     Terms are unique within a data descriptor but may have some synonyms in the universe.
 
-    :returns: A list of Pydantic term instances.
-    :rtype: list[BaseModel]
+    :param selected_term_fields: A list of term fields to select or `None`. If `None`, all the \
+    fields of the terms are returned.
+    :type selected_term_fields: Iterable[str]|None
+    :returns: A list of term instances.
+    :rtype: list[DataDescriptor]
     """
     result = list()
     with get_universe_session() as session:
         data_descriptors = _get_all_data_descriptors_in_universe(session)
         for data_descriptor in data_descriptors:
             # Term may have some synonyms within the whole universe.
-            terms = _get_all_terms_in_data_descriptor(data_descriptor)
+            terms = _get_all_terms_in_data_descriptor(data_descriptor, selected_term_fields)
             result.extend(terms)
     return result
 
 
 if __name__ == "__main__":
-    print(find_terms_in_data_descriptor('institution', 'ipsl'))
+    settings = SearchSettings()
+    settings.selected_term_fields = ('id',)
+    print(find_terms_in_data_descriptor('institution', 'ipsl', settings))

esgvoc/apps/__init__.py

@@ -0,0 +1,6 @@
+
+from esgvoc.apps.drs.generator import DrsGenerator
+from esgvoc.apps.drs.report import DrsGenerationReport, DrsValidationReport
+from esgvoc.apps.drs.validator import DrsValidator
+
+__all__ = ["DrsValidator", "DrsValidationReport", "DrsGenerator", "DrsGenerationReport"]

esgvoc/apps/drs/__init__.py

@@ -1,16 +0,0 @@
-from esgvoc.apps.drs.models import (DrsType,
-                                    DrsPartType,
-                                    DrsConstant,
-                                    DrsCollection,
-                                    DrsPart,
-                                    DrsSpecification,
-                                    ProjectSpecs)
-                                    
-
-__all__ = ["DrsType",
-           "DrsPartType",
-           "DrsConstant",
-           "DrsCollection",
-           "DrsPart",
-           "DrsSpecification",
-           "ProjectSpecs"]

esgvoc/apps/drs/constants.py

@@ -0,0 +1,2 @@
+FILE_NAME_EXTENSION_KEY = 'extension'
+FILE_NAME_EXTENSION_SEPARATOR_KEY = 'extension_separator'