plexus-python-common 1.0.43__tar.gz → 1.0.45__tar.gz

{plexus_python_common-1.0.43 → plexus_python_common-1.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python-common
-Version: 1.0.43
+Version: 1.0.45
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13

{plexus_python_common-1.0.43 → plexus_python_common-1.0.45}/src/plexus/common/utils/datautils.py

@@ -1,22 +1,13 @@
-import dataclasses
 import datetime
-import textwrap
-from collections.abc import Callable, Generator, Mapping, Sequence
+from collections.abc import Callable, Generator
 from typing import Any
 
-import jinja2
 import pyparsing as pp
 import ujson as json
 from iker.common.utils.funcutils import singleton
-from iker.common.utils.iterutils import dicttree
-from iker.common.utils.iterutils import dicttree_add, dicttree_remove
-from iker.common.utils.iterutils import dicttree_children, dicttree_lineage, dicttree_subtree
-from iker.common.utils.iterutils import head_or_none
-from iker.common.utils.jsonutils import JsonObject, JsonType
+from iker.common.utils.jsonutils import JsonType
 from iker.common.utils.randutils import randomizer
-from iker.common.utils.strutils import is_blank
 
-from plexus.common.resources.tags import predefined_tagset_specs
 from plexus.common.utils.strutils import BagName, UserName, VehicleName
 from plexus.common.utils.strutils import colon_tag_parser, slash_tag_parser
 from plexus.common.utils.strutils import dot_case_parser, kebab_case_parser, snake_case_parser
@@ -53,12 +44,6 @@ __all__ = [
     "known_user_names",
     "known_vehicle_names",
     "random_bag_names_sequence",
-    "RichDesc",
-    "Tag",
-    "Tagset",
-    "populate_tagset",
-    "predefined_tagsets",
-    "render_tagset_markdown_readme",
 ]
 
 
@@ -244,204 +229,3 @@ def random_bag_names_sequence(
 
     for record_sn in range(bags_count):
         yield BagName(vehicle_name=vehicle_name, record_dt=record_dt, record_sn=record_sn)
-
-
-@dataclasses.dataclass(frozen=True, eq=True, order=True)
-class RichDesc(object):
-    type: str
-    text: str
-
-
-@dataclasses.dataclass(frozen=True, eq=True, order=True)
-class Tag(object):
-    name: str
-    desc: str | RichDesc | None
-
-    @property
-    def tag_parts(self) -> list[str]:
-        return self.name.rsplit(":")
-
-    @property
-    def parent_tag_name(self) -> str | None:
-        return head_or_none(self.name.rsplit(":", 1))
-
-
-class Tagset(Sequence[Tag], Mapping[str, Tag]):
-    def __init__(self, namespace: str, desc: str | RichDesc) -> None:
-        super().__init__()
-        self.namespace = namespace
-        self.desc = desc
-        self.tags: list[Tag] = []
-        self.tags_dict: dict[str, Tag] = {}
-        self.tags_tree: dicttree[str, Tag] = {}
-
-    def __contains__(self, item: str | Tag) -> bool:
-        tag_name = item.name if isinstance(item, Tag) else item
-        return tag_name in self.tags_dict
-
-    def __len__(self) -> int:
-        return len(self.tags)
-
-    def __getitem__(self, index: int) -> Tag:
-        return self.tags[index]
-
-    def keys(self):
-        return self.tags_dict.keys()
-
-    def values(self):
-        return self.tags_dict.values()
-
-    def items(self):
-        return self.tags_dict.items()
-
-    def get(self, item: str | Tag) -> Tag | None:
-        tag_name = item.name if isinstance(item, Tag) else item
-        return self.tags_dict.get(tag_name)
-
-    @property
-    def tag_names(self) -> list[str]:
-        return list(self.tags_dict.keys())
-
-    def add(self, tag: Tag) -> None:
-        if tag.name in self.tags_dict:
-            raise ValueError(f"duplicate tag name '{tag.name}'")
-
-        self.tags.append(tag)
-        self.tags_dict[tag.name] = tag
-
-        dicttree_add(self.tags_tree, tag.tag_parts, tag, create_prefix=True)
-
-    def remove(self, tag_name: str) -> None:
-        tag = self.get(tag_name)
-        if tag is None:
-            raise ValueError(f"tag '{tag_name}' not found")
-
-        self.tags.remove(tag)
-        del self.tags_dict[tag_name]
-
-        dicttree_remove(self.tags_tree, tag.tag_parts, recursive=True)
-
-    def child_tags(self, parent: str | Tag) -> list[Tag]:
-        if parent is None:
-            return []
-        if isinstance(parent, str):
-            return self.child_tags(self.get(parent))
-
-        subtree = dicttree_subtree(self.tags_tree, parent.tag_parts)
-        return list(dicttree_children(subtree)) if subtree else []
-
-    def parent_tags(self, child: str | Tag) -> list[Tag]:
-        if child is None:
-            return []
-        if isinstance(child, str):
-            return self.parent_tags(self.get(child))
-
-        return list(dicttree_lineage(self.tags_tree, child.tag_parts[:-1]))
-
-
-def populate_tagset(tagset_spec: JsonObject) -> Tagset:
-    """
-    Collect tags from tagset spec JSON object, validate the format along the way.
-
-    :param tagset_spec: JSON object of tagset spec
-    :return: Populated Tagset instance
-    """
-
-    def validate_and_collect(name: str, tag_def: JsonObject) -> Generator[Tag, None, None]:
-        if not isinstance(tag_def, dict):
-            raise ValueError(f"tag '{name}' definition is not a dict")
-
-        if not is_blank(name):
-            desc = tag_def.get("$desc")
-            if isinstance(desc, dict):
-                desc = RichDesc(**desc)
-
-            yield Tag(name=name, desc=desc)
-
-        for child_name, child_tag_def in tag_def.items():
-            if child_name == "$desc":
-                continue
-
-            if not isinstance(child_name, str):
-                raise ValueError(f"child '{child_name}' of tag '{name}' is not a string")
-            try:
-                validate_snake_case(child_name)
-            except ValueError as e:
-                raise ValueError(f"child '{child_name}' of tag '{name}' is not in snake case") from e
-
-            child_name = name + ":" + child_name if name else child_name
-
-            yield from validate_and_collect(child_name, child_tag_def)
-
-    namespace = tagset_spec.get("$namespace")
-    if namespace is None:
-        raise ValueError("missing '$namespace' in tagset spec")
-    try:
-        validate_snake_case(namespace)
-    except ValueError as e:
-        raise ValueError(f"tagset namespace '{namespace}' is not in snake case") from e
-
-    desc = tagset_spec.get("$desc")
-    if desc is None:
-        raise ValueError("missing '$desc' in tagset spec")
-    if isinstance(desc, dict):
-        desc = RichDesc(**desc)
-
-    tags = tagset_spec.get("$tags")
-    if tags is None:
-        raise ValueError("missing '$tags' in tagset spec")
-
-    tagset = Tagset(namespace=namespace, desc=desc)
-
-    for tag in validate_and_collect("", tags):
-        tagset.add(tag)
-
-    return tagset
-
-
-@singleton
-def predefined_tagsets() -> dict[str, Tagset]:
-    tagsets: dict[str, Tagset] = {}
-    for _, tagset_spec in predefined_tagset_specs():
-        tagset = populate_tagset(tagset_spec)
-        tagsets[tagset.namespace] = tagset
-    return tagsets
-
-
-def render_tagset_markdown_readme(tagset: Tagset) -> str:
-    def render_desc(desc: str | RichDesc | None) -> str:
-        if desc is None:
-            return ""
-        if isinstance(desc, str):
-            return desc
-        if isinstance(desc, RichDesc):
-            return desc.text
-        raise ValueError(f"unsupported desc type '{type(desc)}'")
-
-    template_str = textwrap.dedent(
-        """
-        # Tagset {{ tagset.namespace }}
-
-        {{ tagset.desc | render_desc }}
-
-        ## Contents
-
-        {% for tag in tagset.tags %}
-        - {{ tag.name }}
-        {% endfor %}
-
-        ## Tags
-
-        {% for tag in tagset.tags %}
-        ### {{ tag.name }}
-
-        {{ tag.desc | render_desc }}
-
-        {% endfor %}
-        """
-    )
-
-    env = jinja2.Environment(trim_blocks=True, lstrip_blocks=True)
-    env.filters["render_desc"] = render_desc
-
-    return env.from_string(template_str).render(tagset=tagset)

{plexus_python_common-1.0.43 → plexus_python_common-1.0.45}/src/plexus/common/utils/ormutils.py

@@ -4,8 +4,10 @@ from typing import Protocol, Self
 import pydantic as pdt
 import sqlalchemy as sa
 import sqlalchemy.dialects.postgresql as sa_pg
+import sqlalchemy.dialects.sqlite as sa_sqlite
 import sqlalchemy.exc as sa_exc
 import sqlalchemy.orm as sa_orm
+from iker.common.utils.dbutils import dialects
 from sqlmodel import Field, SQLModel
 
 from plexus.common.utils.datautils import validate_dt_timezone
@@ -13,6 +15,7 @@ from plexus.common.utils.jsonutils import json_datetime_encoder
 
 __all__ = [
     "compare_postgresql_types",
+    "compare_sqlite_types",
     "model_name_of",
     "validate_model_extended",
     "collect_model_tables",
@@ -110,6 +113,30 @@ def compare_postgresql_types(type_a, type_b) -> bool:
     }
 
 
+def compare_sqlite_types(type_a, type_b) -> bool:
+    """
+    Compares two SQLite-specific column types to determine if they are equivalent.
+    This includes types from sqlalchemy.dialects.sqlite like JSON, etc.
+    """
+    if not isinstance(type_a, type(type_b)):
+        return False
+    if isinstance(type_a, (sa_sqlite.VARCHAR, sa_sqlite.CHAR, sa_sqlite.TEXT)):
+        return type_a.length == type_b.length
+    if isinstance(type_a, (sa_sqlite.TIMESTAMP, sa_sqlite.TIME)):
+        return type_a.timezone == type_b.timezone
+    if isinstance(type_a, (sa_sqlite.NUMERIC, sa_sqlite.DECIMAL)):
+        return type_a.precision == type_b.precision and type_a.scale == type_b.scale
+    return type(type_a) in {
+        sa_sqlite.BOOLEAN,
+        sa_sqlite.INTEGER,
+        sa_sqlite.SMALLINT,
+        sa_sqlite.FLOAT,
+        sa_sqlite.REAL,
+        sa_sqlite.DATE,
+        sa_sqlite.JSON,
+    }
+
+
 def model_name_of(model: type[SQLModel], fallback_classname: bool = True) -> str | None:
     table_name = getattr(model, "__tablename__")
     if not table_name:
@@ -183,12 +210,12 @@ def make_base_model() -> type[SQLModel]:
 
 
 class SequenceModelMixinProtocol(Protocol):
-    sqn: int | None
+    sqn: sa_orm.Mapped[int | None]
 
 
 class ChangingModelMixinProtocol(SequenceModelMixinProtocol):
-    created_at: datetime.datetime | None
-    updated_at: datetime.datetime | None
+    created_at: sa_orm.Mapped[datetime.datetime | None]
+    updated_at: sa_orm.Mapped[datetime.datetime | None]
 
     @classmethod
     def make_index_created_at(cls, index_name: str) -> sa.Index:
@@ -201,9 +228,9 @@ class ChangingModelMixinProtocol(SequenceModelMixinProtocol):
 
 
 class SnapshotModelMixinProtocol(SequenceModelMixinProtocol):
-    created_at: datetime.datetime | None
-    expired_at: datetime.datetime | None
-    record_sqn: int | None
+    created_at: sa_orm.Mapped[datetime.datetime | None]
+    expired_at: sa_orm.Mapped[datetime.datetime | None]
+    record_sqn: sa_orm.Mapped[int | None]
 
     @classmethod
     def make_index_created_at_expired_at(cls, index_name: str) -> sa.Index:
@@ -249,11 +276,11 @@ class SnapshotModelMixinProtocol(SequenceModelMixinProtocol):
 
 
 class RevisionModelMixinProtocol(SequenceModelMixinProtocol):
-    created_at: datetime.datetime | None
-    updated_at: datetime.datetime | None
-    expired_at: datetime.datetime | None
-    record_sqn: int | None
-    revision: int | None
+    created_at: sa_orm.Mapped[datetime.datetime | None]
+    updated_at: sa_orm.Mapped[datetime.datetime | None]
+    expired_at: sa_orm.Mapped[datetime.datetime | None]
+    record_sqn: sa_orm.Mapped[int | None]
+    revision: sa_orm.Mapped[int | None]
 
     @classmethod
     def make_index_created_at_updated_at_expired_at(cls, index_name: str) -> sa.Index:
@@ -317,15 +344,67 @@ SnapshotModelMixin = SnapshotModelMixinProtocol | SQLModel
 RevisionModelMixin = RevisionModelMixinProtocol | SQLModel
 
 
-def make_sequence_model_mixin() -> type[SequenceModelMixin]:
+def model_sqn_type(dialect: str | None = None) -> sa.types.TypeEngine[int]:
+    """
+    Returns the appropriate SQLAlchemy column type for a sequence number (sqn) based on the specified database dialect.
+
+    :param dialect: The database dialect to determine the column type for. If None, defaults to PostgreSQL.
+    :return: The SQLAlchemy column type to use for the sqn field.
+    """
+    if dialect is None:
+        dialect = dialects.postgresql
+    if dialect == dialects.postgresql:
+        return sa_pg.BIGINT()
+    if dialect == dialects.sqlite:
+        return sa_sqlite.INTEGER()
+    raise ValueError(f"unsupported database dialect '{dialect}'")
+
+
+def model_datetime_tz_type(dialect: str | None = None) -> sa.types.TypeEngine[datetime.datetime]:
+    """
+    Returns the appropriate SQLAlchemy column type for a timezone-aware datetime field based on the specified database
+    dialect.
+
+    :param dialect: The database dialect to determine the column type for. If None, defaults to PostgreSQL.
+    :return: The SQLAlchemy column type to use for timezone-aware datetime fields.
+    """
+    if dialect is None:
+        dialect = dialects.postgresql
+    if dialect == dialects.postgresql:
+        return sa_pg.TIMESTAMP(timezone=True)
+    if dialect == dialects.sqlite:
+        return sa_sqlite.TIMESTAMP(timezone=True)
+    raise ValueError(f"unsupported database dialect '{dialect}'")
+
+
+def model_revision_type(dialect: str | None = None) -> sa.types.TypeEngine[int]:
+    """
+    Returns the appropriate SQLAlchemy column type for a revision number field based on the specified database dialect.
+
+    :param dialect: The database dialect to determine the column type for. If None, defaults to PostgreSQL.
+    :return: The SQLAlchemy column type to use for revision number fields.
+    """
+    if dialect is None:
+        dialect = dialects.postgresql
+    if dialect == dialects.postgresql:
+        return sa_pg.INTEGER()
+    if dialect == dialects.sqlite:
+        return sa_sqlite.INTEGER()
+    raise ValueError(f"unsupported database dialect '{dialect}'")
+
+
+def make_sequence_model_mixin(dialect: str | None = None) -> type[SequenceModelMixin]:
     """
     Creates a mixin class for SQLModel models that adds a unique identifier field `sqn`.
     Use this mixin to add an auto-incremented primary key to your models.
+
+    :param dialect: The database dialect to determine the column type for the `sqn` field.
+    :return: A mixin class that can be used with SQLModel models to add the `sqn` field.
     """
 
     class ModelMixin(SQLModel):
         sqn: int | None = Field(
-            sa_column=sa.Column(sa_pg.BIGINT, primary_key=True, autoincrement=True),
+            sa_column=sa.Column(model_sqn_type(dialect), primary_key=True, autoincrement=True),
             default=None,
             description="Unique auto-incremented primary key for the record",
         )
@@ -333,25 +412,29 @@ def make_sequence_model_mixin() -> type[SequenceModelMixin]:
     return ModelMixin
 
 
-def make_changing_model_mixin() -> type[ChangingModelMixin]:
+def make_changing_model_mixin(dialect: str | None = None) -> type[ChangingModelMixin]:
     """
     Creates a mixin class for SQLModel models that adds common fields and validation logic for updatable records.
     This mixin includes ``sqn``, ``created_at``, and ``updated_at`` fields, along with validation for timestamps.
+
+    :param dialect: The database dialect to determine the column types for the fields.
+    :return: A mixin class that can be used with SQLModel models to add the common fields and validation logic for
+    updatable records.
     """
 
     class ModelMixin(SQLModel):
         sqn: int | None = Field(
-            sa_column=sa.Column(sa_pg.BIGINT, primary_key=True, autoincrement=True),
+            sa_column=sa.Column(model_sqn_type(dialect), primary_key=True, autoincrement=True),
             default=None,
             description="Unique auto-incremented primary key for the record",
         )
         created_at: datetime.datetime | None = Field(
-            sa_column=sa.Column(sa_pg.TIMESTAMP(timezone=True)),
+            sa_column=sa.Column(model_datetime_tz_type(dialect)),
             default=None,
             description="Timestamp (with timezone) when the record was created",
         )
         updated_at: datetime.datetime | None = Field(
-            sa_column=sa.Column(sa_pg.TIMESTAMP(timezone=True)),
+            sa_column=sa.Column(model_datetime_tz_type(dialect)),
             default=None,
             description="Timestamp (with timezone) when the record was last updated",
         )
@@ -383,7 +466,7 @@ def make_changing_model_mixin() -> type[ChangingModelMixin]:
     return ModelMixin
 
 
-def make_snapshot_model_mixin() -> type[SnapshotModelMixin]:
+def make_snapshot_model_mixin(dialect: str | None = None) -> type[SnapshotModelMixin]:
     """
     Provides a mixin class for SQLModel models that adds common fields and validation logic for record snapshots.
     A snapshot model tracks the full change history of an entity: when any field changes, the current record (with a
@@ -395,26 +478,30 @@ def make_snapshot_model_mixin() -> type[SnapshotModelMixin]:
       - ``expired_at``: Time (with timezone) when this snapshot of the record was superseded or became inactive;
         ``None`` if still active.
       - ``record_sqn``: Foreign key to the record this snapshot belongs to; used to link snapshots together.
+
+    :param dialect: The database dialect to determine the column types for the fields.
+    :return: A mixin class that can be used with SQLModel models to add the common fields and validation logic for
+    record snapshots.
     """
 
     class ModelMixin(SQLModel):
         sqn: int | None = Field(
-            sa_column=sa.Column(sa_pg.BIGINT, primary_key=True, autoincrement=True),
+            sa_column=sa.Column(model_sqn_type(dialect), primary_key=True, autoincrement=True),
             default=None,
             description="Unique auto-incremented primary key for each record snapshot",
         )
         created_at: datetime.datetime | None = Field(
-            sa_column=sa.Column(sa_pg.TIMESTAMP(timezone=True)),
+            sa_column=sa.Column(model_datetime_tz_type(dialect)),
             default=None,
             description="Timestamp (with timezone) when this record snapshot became active",
         )
         expired_at: datetime.datetime | None = Field(
-            sa_column=sa.Column(sa_pg.TIMESTAMP(timezone=True)),
+            sa_column=sa.Column(model_datetime_tz_type(dialect)),
             default=None,
             description="Timestamp (with timezone) when this record snapshot became inactive; None if still active",
         )
         record_sqn: int | None = Field(
-            sa_column=sa.Column(sa_pg.BIGINT, nullable=True),
+            sa_column=sa.Column(model_sqn_type(dialect), nullable=True),
             default=None,
             description="Foreign key to the record this snapshot belongs to",
         )
@@ -472,7 +559,7 @@ def make_snapshot_model_mixin() -> type[SnapshotModelMixin]:
     return ModelMixin
 
 
-def make_revision_model_mixin() -> type[RevisionModelMixin]:
+def make_revision_model_mixin(dialect: str | None = None) -> type[RevisionModelMixin]:
     """
     Provides a mixin class for SQLModel models that adds common fields and validation logic for record revisions.
     A revision model tracks the full change history of an entity: when any field changes, the current record (with a
@@ -486,36 +573,40 @@ def make_revision_model_mixin() -> type[RevisionModelMixin]:
         ``None`` if still active.
       - ``record_sqn``: Auto-incremented key of the record this revision belongs to; used to link revisions together.
       - ``revision``: Revision number for the record, used to track changes over time.
+
+    :param dialect: The database dialect to determine the column types for the fields.
+    :return: A mixin class that can be used with SQLModel models to add the common fields and validation logic for
+    record revisions.
     """
 
     class ModelMixin(SQLModel):
         sqn: int | None = Field(
-            sa_column=sa.Column(sa_pg.BIGINT, primary_key=True, autoincrement=True),
+            sa_column=sa.Column(model_sqn_type(dialect), primary_key=True, autoincrement=True),
             default=None,
             description="Unique auto-incremented primary key for each record revision",
         )
         created_at: datetime.datetime | None = Field(
-            sa_column=sa.Column(sa_pg.TIMESTAMP(timezone=True)),
+            sa_column=sa.Column(model_datetime_tz_type(dialect)),
             default=None,
             description="Timestamp (with timezone) when this record is first created (preserved across revisions)",
         )
         updated_at: datetime.datetime | None = Field(
-            sa_column=sa.Column(sa_pg.TIMESTAMP(timezone=True)),
+            sa_column=sa.Column(model_datetime_tz_type(dialect)),
             default=None,
             description="Timestamp (with timezone) when this record is updated and this record revision became active",
         )
         expired_at: datetime.datetime | None = Field(
-            sa_column=sa.Column(sa_pg.TIMESTAMP(timezone=True)),
+            sa_column=sa.Column(model_datetime_tz_type(dialect)),
             default=None,
             description="Timestamp (with timezone) when this record revision became inactive; None if still active",
         )
         record_sqn: int | None = Field(
-            sa_column=sa.Column(sa_pg.BIGINT, nullable=True),
+            sa_column=sa.Column(model_sqn_type(dialect), nullable=True),
             default=None,
             description="Auto-incremented key of the record this revision belongs to",
         )
         revision: int | None = Field(
-            sa_column=sa.Column(sa_pg.INTEGER, nullable=True),
+            sa_column=sa.Column(model_revision_type(dialect), nullable=True),
             default=None,
             description="Revision number for the record",
         )