heurist-api 0.1.2__py3-none-any.whl

heurist/models/dynamic/annotation.py

@@ -0,0 +1,143 @@
+from typing import Any, Optional
+
+from heurist.models.dynamic.type import FieldType
+from heurist.sql.sql_safety import SafeSQLName
+from pydantic import Field
+
+
+class PydanticField:
+    trm_validation_alias_suffix = "_TRM"
+
+    def __init__(
+        self, dty_ID: int, rst_DisplayName: str, dty_Type: str, rst_MaxValues: int
+    ):
+        """
+        Using information of 1 detail (data field) from a Heurist record, build a \
+            Pydantic data field annotation.
+
+        Args:
+            dty_ID (int): Detail's ID.
+            rst_DisplayName (str): Name of the detail displayed in Heurist.
+            dty_Type (str): Detail's data type.
+            rst_MaxValues (int): Heurist indicator if the detail can be repeated.
+        """
+        self.dty_ID = dty_ID
+        self.rst_DisplayName = rst_DisplayName
+        self.dty_Type = dty_Type
+        self.rst_MaxValues = rst_MaxValues
+
+    @classmethod
+    def _get_validation_alias(cls, dty_ID: int) -> str:
+        return f"DTY{dty_ID}"
+
+    @property
+    def validation_alias(self) -> str:
+        return self._get_validation_alias(dty_ID=self.dty_ID)
+
+    @property
+    def serlialization_alias(self) -> str:
+        return SafeSQLName().create_column_name(
+            field_name=self.rst_DisplayName, field_type=self.dty_Type
+        )
+
+    @property
+    def pydantic_type(self) -> Any:
+        fieldtype = FieldType.to_pydantic(datatype=self.dty_Type)
+        if self._is_type_repeatable():
+            return list[fieldtype]
+        else:
+            return fieldtype
+
+    def build_field(self) -> dict:
+        """
+        Build a Pydantic field annotation for a detail whose value will simply be the \
+            result of the `RecordDetailConverter`, meaning not a date and not a \
+            vocabulary term.
+
+        Returns:
+            dict: Pydantic field annotation.
+        """
+
+        return self._compose_annotation(
+            validation_alias=self.validation_alias,
+            serialization_alias=self.serlialization_alias,
+            pydantic_type=self.pydantic_type,
+        )
+
+    def build_term_fk(self) -> dict:
+        """
+        Build a Pydantic field annotation for a foreign key reference to the vocabulary\
+            term in the constructed database's trm table. This field is written to the \
+            Pydantic model in addition to a column for the term that simply has the \
+            label.
+
+        Returns:
+            dict: Pydantic field annotation.
+        """
+
+        validation_alias = self.validation_alias + self.trm_validation_alias_suffix
+        serialization_alias = self.serlialization_alias + " TRM-ID"
+        if self._is_type_repeatable():
+            pydantic_type = list[Optional[int]]
+        else:
+            pydantic_type = Optional[int]
+
+        return self._compose_annotation(
+            validation_alias=validation_alias,
+            serialization_alias=serialization_alias,
+            pydantic_type=pydantic_type,
+        )
+
+    def _is_type_repeatable(self) -> bool:
+        """
+        Heurist uses the code 0 to indicate that a record's detail (field) \
+            can be repeated. Parse this information on the record structure \
+            to determine a boolean indicating whether or not the detail is repeated.
+
+        Returns:
+            bool: Whether the detail can be repeated.
+        """
+
+        if self.rst_MaxValues == 0:
+            return True
+        else:
+            return False
+
+    def _compose_annotation(
+        self, validation_alias: str, serialization_alias: str, pydantic_type: Any
+    ) -> dict:
+        """
+        Using the Heurist information stored in the class instance's attributes, build \
+            the Pydantic data field's alias and compose its annotation.
+
+        Returns:
+            dict: Key-value pair: Pydantic field's alias (key) - annotation (value)
+        """
+
+        if not validation_alias:
+            raise ValueError()
+        if not serialization_alias:
+            raise ValueError()
+        if not pydantic_type:
+            raise ValueError()
+
+        if self.rst_MaxValues == 0:
+            default = []
+        else:
+            default = None
+
+        return {
+            validation_alias: (
+                pydantic_type,
+                Field(
+                    # ID of the column's data type in Heurist
+                    description=self.dty_ID,
+                    # Formatted way to identify the Pydantic column
+                    validation_alias=validation_alias,
+                    # SQL-safe version of the column name
+                    serialization_alias=serialization_alias,
+                    # Default value to write in DuckDB column
+                    default=default,
+                ),
+            )
+        }

heurist/models/dynamic/create_model.py

@@ -0,0 +1,82 @@
+from heurist.models.dynamic.annotation import PydanticField
+from heurist.sql.sql_safety import SafeSQLName
+from pydantic import BaseModel, Field
+from pydantic import create_model as pydantic_create_model
+
+
+class HeuristRecord:
+    def __init__(self, rty_Name: str, rty_ID: int, detail_metadata: list[dict]):
+        self.rty_ID = rty_ID
+        # Create an SQL-safe name to give the model when it's serialized to a table
+        self.table_name = SafeSQLName().create_table_name(record_name=rty_Name)
+        # Create the Pydantic model
+        self.model = create_record_type_model(
+            model_name=self.table_name, detail_metadata=detail_metadata
+        )
+
+
+def create_record_type_model(model_name: str, detail_metadata: list[dict]) -> BaseModel:
+    """
+    Each detail's set of metadata must be a dictionary with the following keys:
+        dty_ID,
+        rst_DisplayName,
+        dty_Type,
+        rst_MaxValues
+
+    Examples:
+        >>> d1 = {'dty_ID': 1,
+        ... 'rst_DisplayName': 'label',
+        ... 'dty_Type': 'enum',
+        ... 'rst_MaxValues': 1}
+        >>> d2 = {'dty_ID': 2,
+        ... 'rst_DisplayName': 'date',
+        ... 'dty_Type': 'date',
+        ... 'rst_MaxValues': 1}
+        >>> model = create_record_type_model('test', [d1, d2])
+        >>> model.__annotations__.keys()
+        dict_keys(['id', 'type', 'DTY1', 'DTY1_TRM', 'DTY2'])
+
+    Args:
+        model_name (str): The model's name.
+        detail_metadata (list[dict]): A list of metadata about each field (detail).
+
+    Return:
+        (BaseModel): Pydantic model.
+    """
+
+    # Indifferent to the record's data fields, set up universal data fields
+    # present in every dynamic Pydantic model for records of any type
+    kwargs = {
+        "id": (
+            int,
+            Field(
+                default=0,
+                alias="rec_ID",
+                validation_alias="rec_ID",
+                serialization_alias="H-ID",
+            ),
+        ),
+        "type": (
+            int,
+            Field(
+                default=0,
+                alias="rec_RecTypeID",
+                validation_alias="rec_RecTypeID",
+                serialization_alias="type_id",
+            ),
+        ),
+    }
+
+    # Convert each of the record's details into a Pydantic kwarg
+    for detail in detail_metadata:
+        # Add the field's default parsed value
+        annotation = PydanticField(**detail)
+        field = annotation.build_field()
+        kwargs.update(field)
+
+        if detail["dty_Type"] == "enum":
+            field = annotation.build_term_fk()
+            kwargs.update(field)
+
+    # Using Pydantic's 'create_model' module, build the dynamic model
+    return pydantic_create_model(model_name, **kwargs)

heurist/models/dynamic/date.py

@@ -0,0 +1,61 @@
+from datetime import datetime
+from typing import Annotated, Optional
+
+from heurist.validators import parse_heurist_date
+from pydantic import BaseModel, BeforeValidator, Field
+
+PROFILE_MAP = {"0": "flat", "1": "central", "2": "slowStart", "3": "slowFinish"}
+DETERMINATION_MAP = {
+    "0": "unknown",
+    "1": "attested",
+    "2": "conjecture",
+    "3": "measurement",
+}
+
+
+def parse_profile(value) -> str | None:
+    if PROFILE_MAP.get(value):
+        return PROFILE_MAP[value]
+
+
+def parse_determination(value) -> str | None:
+    if DETERMINATION_MAP.get(value):
+        return DETERMINATION_MAP[value]
+
+
+HeuristDate = Annotated[datetime, BeforeValidator(parse_heurist_date)]
+HeuristProfile = Annotated[str, BeforeValidator(parse_profile)]
+HeuristDetermination = Annotated[str, BeforeValidator(parse_determination)]
+
+
+class DateLimit(BaseModel):
+    earliest: Optional[HeuristDate] = Field(default=None)
+    latest: Optional[HeuristDate] = Field(default=None)
+    estProfile: Optional[HeuristProfile] = Field(
+        default=None, validation_alias="profile"
+    )
+    estDetermination: Optional[HeuristDetermination] = Field(
+        default=None, validation_alias="determination"
+    )
+
+
+class Timestamp(BaseModel):
+    inYear: Optional[HeuristDate] = Field(default=None, alias="in")
+    typeTime: Optional[str] = Field(default=None, alias="type")
+    circa: Optional[bool] = Field(default=False)
+
+
+class TemporalObject(BaseModel):
+    comment: Optional[str] = Field(default=None)
+    value: Optional[HeuristDate] = Field(default=None)
+    start: Optional[DateLimit] = Field(default=DateLimit(**{}))
+    end: Optional[DateLimit] = Field(default=DateLimit(**{}))
+    estDetermination: Optional[HeuristDetermination] = Field(
+        default=None, validation_alias="determination"
+    )
+    estProfile: Optional[HeuristProfile] = Field(
+        default=None, validation_alias="profile"
+    )
+    timestamp: Optional[Timestamp] = Field(default=Timestamp(**{}))
+    estMinDate: Optional[HeuristDate] = Field(default=None)
+    estMaxDate: Optional[HeuristDate] = Field(default=None)

heurist/models/dynamic/type.py

@@ -0,0 +1,96 @@
+"""Dataclass to organize and convert the data type of a Record's detail."""
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class FieldType:
+    """Organize and convert the data types of a Record's detail."""
+
+    dropdown = "enum"
+    numeric = "float"
+    single_line = "freetext"
+    multi_line = "blocktext"
+    date_time = "date"
+    geospatial = "geo"
+    file_or_media_url = "file"
+    record_pointer = "resource"
+    relationship_marker = "relmarker"
+
+    @classmethod
+    def to_sql(cls, datatype: str) -> str:
+        """
+        Convert a Heurist data type label (i.e. "enum") to an SQL equivalent.
+
+        Args:
+            datatype (str): Heurist data type.
+
+        Returns:
+            str: SQL data type.
+        """
+
+        if datatype == cls.numeric:
+            return "FLOAT"
+        elif datatype == cls.date_time:
+            return "DATE[2]"
+        elif datatype == cls.record_pointer or datatype == cls.relationship_marker:
+            return "INTEGER"
+        elif datatype == cls.dropdown:
+            return "VARCHAR"
+        else:
+            return "TEXT"
+
+    @classmethod
+    def from_detail(cls, detail: dict) -> str:
+        """Extract the field type from a record's detail.
+
+        Args:
+            detail (dict): Record's detail.
+
+        Returns:
+            str: Field type name.
+        """
+
+        return detail["fieldType"]
+
+    @classmethod
+    def to_pydantic(cls, datatype: str) -> Any:
+        """Convert Heurist field type to Python type.
+
+        Args:
+            datatype (str): Field type name.
+
+        Returns:
+            Any: Python type.
+        """
+
+        if datatype == cls.dropdown:
+            return Optional[str]
+
+        elif datatype == cls.numeric:
+            return Optional[float]
+
+        elif datatype == cls.single_line:
+            return Optional[str]
+
+        elif datatype == cls.multi_line:
+            return Optional[str]
+
+        elif datatype == cls.date_time:
+            return dict
+
+        elif datatype == cls.geospatial:
+            return Optional[str]
+
+        elif datatype == cls.file_or_media_url:
+            return Optional[str]
+
+        elif datatype == cls.record_pointer:
+            return Optional[int]
+
+        elif datatype == cls.relationship_marker:
+            return Optional[str]
+
+        else:
+            return Optional[str]

heurist/models/structural/DetailTypes.py

@@ -0,0 +1,34 @@
+from heurist.models.structural.dty import DTY
+from pydantic_xml import BaseXmlModel, element
+
+
+class DetailTypes(BaseXmlModel):
+    """Dataclass for modeling all of the database structure's Detail Types.
+
+    Attributes:
+        dty (list): list of instantiated dataclasses that model all of the database's
+            Detail Types.
+
+    Examples:
+        >>> from mock_data import DB_STRUCTURE_XML
+        >>> from heurist.models.structural import HMLStructure
+        >>>
+        >>>
+        >>> # Parse structure
+        >>> xml = DB_STRUCTURE_XML
+        >>> hml = HMLStructure.from_xml(xml)
+        >>>
+        >>> # Test class
+        >>> first_detail_type = hml.DetailTypes.dty[0]
+        >>> first_detail_type.dty_ID
+        1
+        >>> singular_pointer = [d for d in hml.DetailTypes.dty if d.dty_ID == 1295][0]
+        >>> singular_pointer.dty_PtrTargetRectypeIDs
+        [101]
+        >>> plural_pointer = [d for d in hml.DetailTypes.dty if d.dty_ID == 1256][0]
+        >>> plural_pointer.dty_PtrTargetRectypeIDs
+        [101, 105, 106]
+
+    """
+
+    dty: list[DTY] = element()

heurist/models/structural/RecStructure.py

@@ -0,0 +1,27 @@
+from heurist.models.structural.rst import RST
+from pydantic_xml import BaseXmlModel, element
+
+
+class RecStructure(BaseXmlModel):
+    """Dataclass for modeling all of the database structure's Record Structures.
+
+    Attributes:
+        rst (list): list of instantiated dataclasses that model all of the database's
+            Record Structures.
+
+    Examples:
+        >>> from mock_data import DB_STRUCTURE_XML
+        >>> from heurist.models.structural import HMLStructure
+        >>>
+        >>>
+        >>> # Parse structure
+        >>> xml = DB_STRUCTURE_XML
+        >>> hml = HMLStructure.from_xml(xml)
+        >>>
+        >>> # Test class
+        >>> first_record_structure = hml.RecStructure.rst[0]
+        >>> first_record_structure.rst_ID
+        1
+    """
+
+    rst: list[RST] = element()

heurist/models/structural/RecTypeGroups.py

@@ -0,0 +1,27 @@
+from heurist.models.structural.rtg import RTG
+from pydantic_xml import BaseXmlModel, element
+
+
+class RecTypeGroups(BaseXmlModel):
+    """Dataclass for modeling all of the database structure's Record Type Groups.
+
+    Attributes:
+        rtg (list): list of instantiated dataclasses that model all of the database's
+            Record Type Groups.
+
+    Examples:
+        >>> from mock_data import DB_STRUCTURE_XML
+        >>> from heurist.models.structural import HMLStructure
+        >>>
+        >>>
+        >>> # Parse structure
+        >>> xml = DB_STRUCTURE_XML
+        >>> hml = HMLStructure.from_xml(xml)
+        >>>
+        >>> # Test class
+        >>> first_record_type = hml.RecTypeGroups.rtg[0]
+        >>> first_record_type.rtg_ID
+        4
+    """
+
+    rtg: list[RTG] = element()

heurist/models/structural/RecTypes.py

@@ -0,0 +1,27 @@
+from heurist.models.structural.rty import RTY
+from pydantic_xml import BaseXmlModel, element
+
+
+class RecTypes(BaseXmlModel):
+    """Dataclass for modeling all of the database structure's Record Types.
+
+    Attributes:
+        rty (list): list of instantiated dataclasses that model all of the database's
+            Record Types.
+
+    Examples:
+        >>> from mock_data import DB_STRUCTURE_XML
+        >>> from heurist.models.structural import HMLStructure
+        >>>
+        >>>
+        >>> # Parse structure
+        >>> xml = DB_STRUCTURE_XML
+        >>> hml = HMLStructure.from_xml(xml)
+        >>>
+        >>> # Test class
+        >>> first_record_type = hml.RecTypes.rty[0]
+        >>> first_record_type.rty_ID
+        1
+    """
+
+    rty: list[RTY] = element()

heurist/models/structural/Terms.py

@@ -0,0 +1,27 @@
+from heurist.models.structural.trm import TRM
+from pydantic_xml import BaseXmlModel, element
+
+
+class Terms(BaseXmlModel):
+    """Dataclass for modeling all of the database structure's Terms.
+
+    Attributes:
+        trm (list): list of instantiated dataclasses that model all of the database's
+            Terms.
+
+    Examples:
+        >>> from mock_data import DB_STRUCTURE_XML
+        >>> from heurist.models.structural import HMLStructure
+        >>>
+        >>>
+        >>> # Parse structure
+        >>> xml = DB_STRUCTURE_XML
+        >>> hml = HMLStructure.from_xml(xml)
+        >>>
+        >>> # Test class
+        >>> first_detail_type = hml.Terms.trm[0]
+        >>> first_detail_type.trm_ID
+        12
+    """
+
+    trm: list[TRM] = element()

heurist/models/structural/__init__.py

@@ -0,0 +1,19 @@
+from heurist.models.structural.DetailTypes import DetailTypes
+from heurist.models.structural.dty import DTY
+from heurist.models.structural.hml_structure import HMLStructure
+from heurist.models.structural.RecStructure import RecStructure
+from heurist.models.structural.RecTypeGroups import RecTypeGroups
+from heurist.models.structural.RecTypes import RecTypes
+from heurist.models.structural.rst import RST
+from heurist.models.structural.rtg import RTG
+from heurist.models.structural.rty import RTY
+
+DetailTypes
+DTY
+HMLStructure
+RecStructure
+RecTypeGroups
+RecTypes
+RST
+RTG
+RTY

heurist/models/structural/dty.py

@@ -0,0 +1,121 @@
+from datetime import datetime
+from typing import List, Literal, Optional
+
+from heurist.models.structural.utils import split_ids
+from pydantic import field_validator
+from pydantic_xml import BaseXmlModel, element
+
+
+class DTY(BaseXmlModel, tag="dty", search_mode="unordered"):
+    """Dataclass to model one of the database's Detail Types. A Detail Type is the
+        generic schema that defines the type of data one of a record's field.
+
+    When possible, the attribute descriptions are taken from Heurist's source code.
+
+    Attributes:
+        dty_ID (int): Code for the detail type (field) - may vary between Heurist DBs.
+        dty_Name (str): The canonical (standard) name of the detail type, used as \
+            default in edit form.
+        dty_Documentation (Optional[str]): Documentation of the detail type, what it \
+            means, how defined.
+        dty_Type (Literal['freetext','blocktext','integer','date','year','relmarker',\
+            'boolean','enum','relationtype','resource','float','file','geo','separator',\
+            'calculated','fieldsetmarker','urlinclude']): The value-type of this \
+            detail type, what sort of data is stored.
+        dty_HelpText (Optional[str]):The default help text displayed to the user under \
+            the field.
+        dty_ExtendedDescription (Optional[str]): Extended text describing this detail \
+            type, for display in rollover.
+        dty_EntryMask (Optional[str]): Data entry mask, use to control decimals on \
+            numeric values, content of text fields etc.
+        dty_Status (Literal["reserved","approved","pending","open"]): 'Reserved' for \
+            the system, cannot be changed; 'Approved' for community standards; \
+            'Pending' for work in progress; 'Open' for freely modifiable/personal \
+            record types.
+        dty_OriginatingDBID (int): Database where this detail type originated, 0 = \
+            locally.
+        dty_NameInOriginatingDB (Optional[str]): Name used in database where this \
+            detail type originated.
+        dty_IDInOriginatingDB (int): ID used in database where this detail type \
+            originated.
+        dty_DetailTypeGroupID (int): The general role of this detail allowing \
+            differentiated lists of detail types.
+        dty_OrderInGroup (int): The display order of DetailType within group, \
+            alphabetic if equal values.
+        dty_JsonTermIDTree (Optional[str]): Tree of Term IDs to show for this field \
+            (display-only header terms set in HeaderTermIDs).
+        dty_TermIDTreeNonSelectableIDs (List[Optional[int]]): Term IDs to use as \
+            non-selectable headers for this field.
+        dty_PtrTargetRectypeIDs (List[Optional[int]]): CSVlist of target Rectype IDs, \
+            null = any.
+        dty_FieldSetRectypeID (Optional[int]): For a FieldSetMarker, the record type \
+            to be inserted as a fieldset.
+        dty_ShowInLists (bool): Show this field type in pulldown lists etc. (always \
+            visible in field management screen).
+        dty_NonOwnerVisibility (Literal["hidden","viewable","public"]): Hidden = \
+            visible only to owners, Viewable = any logged in user, Public = visible \
+                to non-logged in viewers.
+        dty_Modified (datetime): Date of last modification of this record, used to get \
+            last updated date for table.
+        dty_LocallyModified (bool): Flags a definition element which has been modified \
+            relative to the original source.
+        dty_SemanticReferenceURL (Optional[str]): URI to a full description or \
+            ontological reference definition of the base field (optional).
+    """
+
+    dty_ID: int = element()
+    dty_Name: str = element()
+    dty_Documentation: Optional[str] = element(default=None)
+    dty_Type: Literal[
+        "freetext",
+        "blocktext",
+        "integer",
+        "date",
+        "year",
+        "relmarker",
+        "boolean",
+        "enum",
+        "relationtype",
+        "resource",
+        "float",
+        "file",
+        "geo",
+        "separator",
+        "calculated",
+        "fieldsetmarker",
+        "urlinclude",
+    ] = element()
+    dty_HelpText: Optional[str] = element(default=None)
+    dty_ExtendedDescription: Optional[str] = element(default=None)
+    dty_EntryMask: Optional[str] = element(default=None)
+    dty_Status: Literal["reserved", "approved", "pending", "open"] = element()
+    dty_OriginatingDBID: int = element()
+    dty_NameInOriginatingDB: Optional[str] = element(default=None)
+    dty_IDInOriginatingDB: int = element()
+    dty_DetailTypeGroupID: int = element()
+    dty_OrderInGroup: int = element()
+    dty_JsonTermIDTree: Optional[str] = element(default=None)
+    dty_TermIDTreeNonSelectableIDs: List[Optional[int]] = element(default=[])
+    dty_PtrTargetRectypeIDs: List[Optional[int]] = element(default=[])
+    dty_FieldSetRectypeID: Optional[int] = element(default=None)
+    dty_ShowInLists: bool = element()
+    dty_NonOwnerVisibility: Literal["hidden", "viewable", "public"] = element()
+    dty_Modified: datetime = element()
+    dty_LocallyModified: bool = element()
+    dty_SemanticReferenceURL: Optional[str] = element(default=None)
+
+    @field_validator("dty_TermIDTreeNonSelectableIDs", mode="before")
+    @classmethod
+    def validate_selectable_ids(cls, input_value: str | None) -> list:
+        if input_value:
+            return split_ids(input=input_value)
+        else:
+            return []
+
+    @field_validator("dty_PtrTargetRectypeIDs", mode="before")
+    @classmethod
+    def validate_rectype_ids(cls, input_value: str | None) -> list:
+        if input_value:
+            return split_ids(input=input_value)
+        else:
+            return []