esgvoc 2.0.2__py3-none-any.whl

esgvoc/api/pydantic_handler.py

@@ -0,0 +1,146 @@
+from typing import TYPE_CHECKING, Annotated, Any, Iterable, Type, Union, get_args, get_origin
+
+from pydantic import BaseModel, Discriminator, Tag, TypeAdapter
+
+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.core.db.models.project import PTerm
+    from esgvoc.core.db.models.universe import UTerm
+
+
+def create_union(*classes: Type[BaseModel]):
+    """
+    Create a Union type with automatic property-based discrimination.
+
+    Args:
+        *classes: BaseModel classes to include in the union (order matters - most specific first)
+        name: Optional name for the union type (used for debugging)
+
+    Returns:
+        An Annotated Union type with a discriminator that checks required properties
+    """
+    classes_list = list(classes)
+
+    def property_discriminator(v: Any) -> str:
+        """Generic discriminator that checks which class has matching required fields."""
+        if not isinstance(v, dict):
+            return v.__class__.__name__
+
+        # Get the input fields
+        input_fields = set(v.keys())
+
+        # Track which models failed and why
+        failed_matches = []
+
+        # Try each class and see which one's required fields match
+        for cls in classes_list:
+            # Get required fields for this class (excluding nullable fields)
+            required_fields = set()
+            for field_name, field_info in cls.model_fields.items():
+                # Only consider fields that are required AND not nullable
+                if field_info.is_required():
+                    # Check if None is allowed in the field type
+                    annotation = field_info.annotation
+                    is_nullable = False
+
+                    # Check for Optional[X] or X | None patterns using get_origin and get_args
+                    origin = get_origin(annotation)
+                    if origin is Union:
+                        # Check if None is in the union args
+                        args = get_args(annotation)
+                        is_nullable = type(None) in args
+
+                    # Only add to required fields if not nullable
+                    if not is_nullable:
+                        required_fields.add(field_name)
+
+            # Check if all required fields are present in input
+            missing_fields = required_fields - input_fields
+            if not missing_fields:
+                return cls.__name__
+            else:
+                failed_matches.append((cls.__name__, sorted(missing_fields)))
+
+        # If no model matched, raise a helpful error
+        error_parts = ["Could not discriminate union type. No model matched the input data."]
+        error_parts.append(f"Input fields: {sorted(input_fields)}")
+        error_parts.append("\nAttempted models:")
+        for model_name, missing in failed_matches:
+            error_parts.append(f"  - {model_name}: missing required fields {missing}")
+
+        raise ValueError("\n".join(error_parts))
+
+    # Create annotated versions with tags
+    tagged_classes = tuple(Annotated[cls, Tag(cls.__name__)] for cls in classes_list)
+
+    # Create Union dynamically
+    union_type = Union.__getitem__(tagged_classes)
+
+    return Annotated[union_type, Discriminator(property_discriminator)]
+
+
+def get_pydantic_class(data_descriptor_id_or_term_type: str) -> type["DataDescriptor"]:
+    """
+    Get the Pydantic class for a given data descriptor ID or term type.
+
+    Args:
+        data_descriptor_id_or_term_type: The identifier of the data descriptor or term type
+
+    Returns:
+        The corresponding Pydantic DataDescriptor class
+
+    Raises:
+        EsgvocDbError: If no matching pydantic class is found
+    """
+    from esgvoc.api.data_descriptors import DATA_DESCRIPTOR_CLASS_MAPPING
+
+    if data_descriptor_id_or_term_type in DATA_DESCRIPTOR_CLASS_MAPPING:
+        return DATA_DESCRIPTOR_CLASS_MAPPING[data_descriptor_id_or_term_type]
+    else:
+        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":
+    """
+    Instantiate a Pydantic DataDescriptor from a database term.
+
+    Args:
+        term: The database term (UTerm or PTerm) to instantiate
+        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)
+    """
+    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
+
+        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))
+
+        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)
+
+        adapter = TypeAdapter(term_class)
+        return adapter.validate_python(term.specs)

esgvoc/api/report.py

@@ -0,0 +1,127 @@
+from abc import ABC, abstractmethod
+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
+
+
+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
+
+    def visit_project_term_error(self, error: "ProjectTermError") -> Any:
+        """Visit a project term error."""
+        pass
+
+
+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):
+    """
+    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):
+    """
+    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
+
+    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.__str__()

esgvoc/api/search.py

@@ -0,0 +1,171 @@
+from enum import Enum
+from typing import Any, Iterable, MutableSequence, Sequence
+
+import sqlalchemy as sa
+from pydantic import BaseModel
+from sqlalchemy import ColumnElement
+from sqlalchemy.exc import OperationalError
+from sqlalchemy.sql.expression import Select
+from sqlalchemy.sql.selectable import ExecutableReturnsRows
+from sqlmodel import Column, Field, Session, col
+
+import esgvoc.core.service as service
+from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
+from esgvoc.api.pydantic_handler import instantiate_pydantic_term
+from esgvoc.core.db.models.project import PCollectionFTS5, PTerm, PTermFTS5
+from esgvoc.core.db.models.universe import UDataDescriptorFTS5, UTerm, UTermFTS5
+from esgvoc.core.exceptions import EsgvocDbError, EsgvocValueError
+
+
+class ItemKind(Enum):
+    DATA_DESCRIPTOR = "data_descriptor"
+    """Corresponds to a data descriptor"""
+    COLLECTION = "collection"
+    """Corresponds to a collection"""
+    TERM = "term"
+    """Corresponds to a term"""
+
+
+class Item(BaseModel):
+    """An item from the universe or a project (data descriptor, collection or term)."""
+
+    id: str
+    """The id of the item."""
+    kind: ItemKind = Field(sa_column=Column(sa.Enum(ItemKind)))
+    """The kind of the item."""
+    parent_id: str
+    """The id of the parent of the item."""
+
+
+def get_universe_session() -> Session:
+    UNIVERSE_DB_CONNECTION = service.current_state.universe.db_connection
+    if UNIVERSE_DB_CONNECTION:
+        return UNIVERSE_DB_CONNECTION.create_session()
+    else:
+        raise EsgvocDbError("universe connection is not initialized")
+
+
+def instantiate_pydantic_terms(
+    db_terms: Iterable[UTerm | PTerm],
+    list_to_populate: MutableSequence[DataDescriptor],
+    selected_term_fields: Iterable[str] | None,
+) -> None:
+    for db_term in db_terms:
+        try:
+            term = instantiate_pydantic_term(db_term, selected_term_fields)
+            list_to_populate.append(term)
+        except Exception as e:
+            # Add context about which term failed
+            term_type = db_term.specs.get('type', 'N/A') if hasattr(db_term, 'specs') else 'N/A'
+            dd_id = db_term.data_descriptor.id if hasattr(db_term, 'data_descriptor') and db_term.data_descriptor else 'N/A'
+            raise ValueError(f"Failed to instantiate term with ID: '{db_term.id}', type: '{term_type}', data_descriptor: '{dd_id}'. Original error: {e}") from e
+
+
+def process_expression(expression: str) -> str:
+    """
+    Allows only SQLite FST operators AND OR NOT and perform prefix search for single word expressions.
+    """
+    # 1. Remove single and double quotes.
+    result = expression.replace('"', "")
+    result = result.replace("'", "")
+
+    # 2. Escape keywords.
+    result = result.replace("NEAR", '"NEAR"')
+    result = result.replace("+", '"+"')
+    result = result.replace("-", '"-"')
+    result = result.replace(":", '":"')
+    result = result.replace("^", '"^"')
+    result = result.replace("(", '"("')
+    result = result.replace(")", '")"')
+    result = result.replace(",", '","')
+
+    # 3. Make single word request a prefix search.
+    if not result.endswith("*"):
+        tokens = result.split(sep=None)
+        if len(tokens) == 1:
+            result += "*"
+    return result
+
+
+def generate_matching_condition(
+    cls: type[UTermFTS5] | type[UDataDescriptorFTS5] | type[PTermFTS5] | type[PCollectionFTS5],
+    expression: str,
+    only_id: bool,
+) -> ColumnElement[bool]:
+    processed_expression = process_expression(expression)
+    # TODO: fix this when specs will ba available in collections and Data descriptors.
+    if cls is PTermFTS5 or cls is UTermFTS5:
+        if only_id:
+            result = col(cls.id).match(processed_expression)
+        else:
+            result = col(cls.specs).match(processed_expression)  # type: ignore
+    else:
+        result = col(cls.id).match(processed_expression)
+    return result
+
+
+def handle_rank_limit_offset(statement: Select, limit: int | None, offset: int | None) -> Select:
+    statement = statement.order_by(sa.text("rank"))
+    if limit and limit > 0:  # False if == 0 and is None ; True if != 0 and is not None.
+        statement = statement.limit(limit)
+    if offset and offset > 0:  # False if == 0 and is None ; True if != 0 and is not None.
+        statement = statement.offset(offset)
+    return statement
+
+
+def execute_match_statement(expression: str, statement: ExecutableReturnsRows, session: Session) -> Sequence:
+    try:
+        raw_results = session.exec(statement)  # type: ignore
+        # raw_results.all() returns a list of sqlalquemy rows.
+        results = [result[0] for result in raw_results.all()]
+        return results
+    except OperationalError as e:
+        raise EsgvocValueError(f"unable to interpret expression '{expression}'") from e
+
+
+def execute_find_item_statements(
+    session: Session,
+    expression: str,
+    first_statement: Select,
+    second_statement: Select,
+    limit: int | None,
+    offset: int | None,
+) -> list[Item]:
+    try:
+        # Items found are kind of tuple with an object, a kindness, a parent id and a rank.
+        first_statement_found = session.exec(first_statement).all()  # type: ignore
+        second_statement_found = session.exec(second_statement).all()  # type: ignore
+        tmp_result: list[Any] = list()
+        tmp_result.extend(first_statement_found)
+        tmp_result.extend(second_statement_found)
+        # According to https://sqlite.org/fts5.html#the_bm25_function,
+        # "the better matches are assigned numerically lower scores."
+        # Sort on the rank column (index 3).
+        sorted_tmp_result = sorted(tmp_result, key=lambda r: r[3], reverse=False)
+        if offset and offset > 0:  # False if == 0 and is None ; True if != 0 and is not None.
+            start = offset
+        else:
+            start = 0
+        if limit and limit > 0:  # False if == 0 and is None ; True if != 0 and is not None.
+            stop = start + limit
+            # is OK if stop > len of the list.
+            framed_tmp_result = sorted_tmp_result[start:stop]
+        else:
+            framed_tmp_result = sorted_tmp_result[start:]
+        result = [Item(id=r[0], kind=r[1], parent_id=r[2]) for r in framed_tmp_result]
+    except OperationalError as e:
+        raise EsgvocValueError(f"unable to interpret expression '{expression}'") from e
+    return result
+
+
+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."""