plexus-python-common 1.0.68__py3-none-any.whl → 1.0.70__py3-none-any.whl

plexus/common/utils/ormutils.py

@@ -1092,12 +1092,12 @@ def db_read_sequence_models[SequenceModelT: SequenceModelMixin](
     limit: int | None = None,
     order_by: list[str] | None = None,
 ) -> list[SequenceModelT]:
-    query = db.query(model).order_by(*db_make_order_by_clause(model, order_by))
+    query_stmt = db.query(model).order_by(*db_make_order_by_clause(model, order_by))
     if skip is not None:
-        query = query.offset(skip)
+        query_stmt = query_stmt.offset(skip)
     if limit is not None:
-        query = query.limit(limit)
-    return query.all()
+        query_stmt = query_stmt.limit(limit)
+    return query_stmt.all()
 
 
 def db_update_sequence_model[SequenceModelT: SequenceModelMixin](
@@ -1285,7 +1285,7 @@ def db_read_latest_snapshot_models[SnapshotModelT: SnapshotModelMixin](
     limit: int | None = None,
     order_by: list[str] | None = None,
 ) -> list[SnapshotModelT]:
-    subquery = (
+    subquery_stmt = (
         db
         .query(model.record_sqn,
                sa.func.max(model.created_at).label("max_created_at"))
@@ -1293,18 +1293,19 @@ def db_read_latest_snapshot_models[SnapshotModelT: SnapshotModelMixin](
         .subquery()
     )
 
-    query = (
+    query_stmt = (
         db
         .query(model)
-        .join(subquery,
-              sa.and_(model.record_sqn == subquery.c.record_sqn, model.created_at == subquery.c.max_created_at))
+        .join(subquery_stmt,
+              sa.and_(model.record_sqn == subquery_stmt.c.record_sqn,
+                      model.created_at == subquery_stmt.c.max_created_at))
         .order_by(*db_make_order_by_clause(model, order_by))
     )
     if skip is not None:
-        query = query.offset(skip)
+        query_stmt = query_stmt.offset(skip)
     if limit is not None:
-        query = query.limit(limit)
-    return query.all()
+        query_stmt = query_stmt.limit(limit)
+    return query_stmt.all()
 
 
 def db_read_active_snapshot_models[SnapshotModelT: SnapshotModelMixin](
@@ -1314,12 +1315,12 @@ def db_read_active_snapshot_models[SnapshotModelT: SnapshotModelMixin](
     limit: int | None = None,
     order_by: list[str] | None = None,
 ) -> list[SnapshotModelT]:
-    query = db.query(model).where(model.expired_at.is_(None)).order_by(*db_make_order_by_clause(model, order_by))
+    query_stmt = db.query(model).where(model.expired_at.is_(None)).order_by(*db_make_order_by_clause(model, order_by))
     if skip is not None:
-        query = query.offset(skip)
+        query_stmt = query_stmt.offset(skip)
     if limit is not None:
-        query = query.limit(limit)
-    return query.all()
+        query_stmt = query_stmt.limit(limit)
+    return query_stmt.all()
 
 
 def db_update_snapshot_model[SnapshotModelT: SnapshotModelMixin](
@@ -1512,7 +1513,7 @@ def db_read_latest_revision_models[RevisionModelT: RevisionModelMixin](
     limit: int | None = None,
     order_by: list[str] | None = None,
 ) -> list[RevisionModelT]:
-    subquery = (
+    subquery_stmt = (
         db
         .query(model.record_sqn,
                sa.func.max(model.revision).label("max_revision"))
@@ -1520,18 +1521,19 @@ def db_read_latest_revision_models[RevisionModelT: RevisionModelMixin](
         .subquery()
     )
 
-    query = (
+    query_stmt = (
         db
         .query(model)
-        .join(subquery,
-              sa.and_(model.record_sqn == subquery.c.record_sqn, model.revision == subquery.c.max_revision))
+        .join(subquery_stmt,
+              sa.and_(model.record_sqn == subquery_stmt.c.record_sqn,
+                      model.revision == subquery_stmt.c.max_revision))
         .order_by(*db_make_order_by_clause(model, order_by))
     )
     if skip is not None:
-        query = query.offset(skip)
+        query_stmt = query_stmt.offset(skip)
     if limit is not None:
-        query = query.limit(limit)
-    return query.all()
+        query_stmt = query_stmt.limit(limit)
+    return query_stmt.all()
 
 
 def db_read_active_revision_models[RevisionModelT: RevisionModelMixin](
@@ -1541,12 +1543,12 @@ def db_read_active_revision_models[RevisionModelT: RevisionModelMixin](
     limit: int | None = None,
     order_by: list[str] | None = None,
 ) -> list[RevisionModelT]:
-    query = db.query(model).where(model.expired_at.is_(None)).order_by(*db_make_order_by_clause(model, order_by))
+    query_stmt = db.query(model).where(model.expired_at.is_(None)).order_by(*db_make_order_by_clause(model, order_by))
     if skip is not None:
-        query = query.offset(skip)
+        query_stmt = query_stmt.offset(skip)
     if limit is not None:
-        query = query.limit(limit)
-    return query.all()
+        query_stmt = query_stmt.limit(limit)
+    return query_stmt.all()
 
 
 def db_update_revision_model[RevisionModelT: RevisionModelMixin](

plexus/common/utils/tagutils.py

@@ -394,15 +394,20 @@ def make_tag_target_model_mixin() -> type[pdt.BaseModel]:
         )
         vehicle_name: str = Field(
             sa_column=sa.Column(sa_sqlite.VARCHAR(128), nullable=False),
-            description="Vehicle name associated with the tag record",
+            description="Name of the tagger's applicability vehicle",
         )
         begin_dt: datetime.datetime = Field(
             sa_column=sa.Column(SQLiteDateTime, nullable=False),
-            description="Begin datetime of the target range associated with the tag record",
+            description="Beginning of the tagger's applicability time range",
         )
         end_dt: datetime.datetime = Field(
             sa_column=sa.Column(SQLiteDateTime, nullable=False),
-            description="End datetime of the target range associated with the tag record",
+            description="End of the tagger's applicability time range",
+        )
+        props: JsonType | None = Field(
+            sa_column=sa.Column(sa_sqlite.JSON, nullable=True),
+            default=None,
+            description="Additional properties of the tag target in JSON format",
         )
 
         @pdt.field_validator("identifier", mode="after")
@@ -414,7 +419,7 @@ def make_tag_target_model_mixin() -> type[pdt.BaseModel]:
         @pdt.field_validator("tagger_name", mode="after")
         @classmethod
         def validate_tagger_name(cls, v: str) -> str:
-            validate_snake_case(v)
+            validate_slash_tag(v)
             return v
 
         @pdt.field_validator("tagger_version", mode="after")
@@ -466,21 +471,21 @@ def make_tag_record_model_mixin() -> type[pdt.BaseModel]:
         )
         begin_dt: datetime.datetime = Field(
             sa_column=sa.Column(SQLiteDateTime, nullable=False),
-            description="Begin datetime of the tag record",
+            description="Begin of the tag record time range",
         )
         end_dt: datetime.datetime = Field(
             sa_column=sa.Column(SQLiteDateTime, nullable=False),
-            description="End datetime of the tag record",
+            description="End of the tag record time range",
         )
         tagset_namespace: str | None = Field(
             sa_column=sa.Column(sa_sqlite.VARCHAR(64), nullable=True),
             default=None,
-            description="Namespace of the tagset that the tag belongs to",
+            description="Namespace of the tagset that the tag in this record belongs to",
         )
         tagset_version: str | None = Field(
             sa_column=sa.Column(sa_sqlite.VARCHAR(32), nullable=True),
             default=None,
-            description="Version of the tagset that the tag belongs to",
+            description="Version of the tagset that the tag in this record belongs to",
         )
         tag: str = Field(
             sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False),
@@ -573,6 +578,7 @@ if typing.TYPE_CHECKING:
         vehicle_name: sa_orm.Mapped[str] = ...
         begin_dt: sa_orm.Mapped[datetime.datetime] = ...
         end_dt: sa_orm.Mapped[datetime.datetime] = ...
+        props: sa_orm.Mapped[JsonType | None] = ...
 
 
     class TagTargetTable(TagTarget, SequenceModelMixinProtocol):
@@ -645,21 +651,21 @@ class TagCache(object):
         end_dt: datetime.datetime | None = None,
     ) -> list[TagTargetTable]:
         with self.make_session() as session:
-            query = session.query(TagTargetTable)
+            query_stmt = session.query(TagTargetTable)
             if identifier:
-                query = query.filter(TagTargetTable.identifier == identifier)
+                query_stmt = query_stmt.filter(TagTargetTable.identifier == identifier)
             if tagger_name:
-                query = query.filter(TagTargetTable.tagger_name == tagger_name)
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_name == tagger_name)
             if tagger_version:
-                query = query.filter(TagTargetTable.tagger_version == tagger_version)
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_version == tagger_version)
             if vehicle_name:
-                query = query.filter(TagTargetTable.vehicle_name == vehicle_name)
+                query_stmt = query_stmt.filter(TagTargetTable.vehicle_name == vehicle_name)
             if begin_dt:
-                query = query.filter(TagTargetTable.end_dt >= begin_dt)
+                query_stmt = query_stmt.filter(TagTargetTable.end_dt >= begin_dt)
             if end_dt:
-                query = query.filter(TagTargetTable.begin_dt <= end_dt)
+                query_stmt = query_stmt.filter(TagTargetTable.begin_dt <= end_dt)
 
-            return query.all()
+            return query_stmt.all()
 
     def add_target(
         self,
@@ -669,18 +675,20 @@ class TagCache(object):
         vehicle_name: str,
         begin_dt: datetime.datetime,
         end_dt: datetime.datetime,
+        props: JsonType | None = None,
     ) -> TagTargetTable:
         with self.make_session() as session:
-            target_info = TagTarget(
+            tag_target = TagTarget(
                 identifier=identifier,
                 tagger_name=tagger_name,
                 tagger_version=tagger_version,
                 vehicle_name=vehicle_name,
                 begin_dt=begin_dt,
                 end_dt=end_dt,
+                props=props,
             )
-            db_target_info = clone_sequence_model_instance(TagTargetTable, target_info)
-            session.add(db_target_info)
+            db_tag_target = clone_sequence_model_instance(TagTargetTable, tag_target)
+            session.add(db_tag_target)
             session.commit()
 
         return self.get_target(identifier)
@@ -695,21 +703,21 @@ class TagCache(object):
         end_dt: datetime.datetime | None = None,
     ):
         with self.make_session() as session:
-            query = session.query(TagTargetTable)
+            query_stmt = session.query(TagTargetTable)
             if identifier:
-                query = query.filter(TagTargetTable.identifier == identifier)
+                query_stmt = query_stmt.filter(TagTargetTable.identifier == identifier)
             if tagger_name:
-                query = query.filter(TagTargetTable.tagger_name == tagger_name)
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_name == tagger_name)
             if tagger_version:
-                query = query.filter(TagTargetTable.tagger_version == tagger_version)
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_version == tagger_version)
             if vehicle_name:
-                query = query.filter(TagTargetTable.vehicle_name == vehicle_name)
+                query_stmt = query_stmt.filter(TagTargetTable.vehicle_name == vehicle_name)
             if begin_dt:
-                query = query.filter(TagTargetTable.end_dt >= begin_dt)
+                query_stmt = query_stmt.filter(TagTargetTable.end_dt >= begin_dt)
             if end_dt:
-                query = query.filter(TagTargetTable.begin_dt <= end_dt)
+                query_stmt = query_stmt.filter(TagTargetTable.begin_dt <= end_dt)
 
-            query.delete()
+            query_stmt.delete()
             session.commit()
 
             (
@@ -721,12 +729,16 @@ class TagCache(object):
             session.commit()
 
     def with_target(self, target: int | str) -> "TargetedTagCache":
-        target_info = self.get_target(target)
-        if target_info is None:
-            raise ValueError(f"target '{target}' not found in cache")
-        return TargetedTagCache(cache=self, target_info=target_info)
+        db_tag_target = self.get_target(target)
+        if db_tag_target is None:
+            raise ValueError(f"tag target '{target}' not found in cache")
+        return TargetedTagCache(cache=self, tag_target=db_tag_target)
+
+    def count_records(self) -> int:
+        with self.make_session() as session:
+            return session.query(sa.func.count(TagRecordTable.sqn)).scalar()
 
-    def iter_tags(
+    def iter_records(
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
@@ -736,6 +748,8 @@ class TagCache(object):
         *,
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
+        skip: int | None = None,
+        limit: int | None = None,
         batch_size: int = 1000,
     ) -> Generator[TagRecordTable, None, None]:
         """
@@ -749,33 +763,41 @@ class TagCache(object):
         :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
         :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
                                 tagsets)
+        :param skip: Number of records to skip (for pagination)
+        :param limit: Maximum number of records to return (for pagination)
         :param batch_size: Number of records to fetch per batch from the database (for memory efficiency)
         :return: Generator of ``TagRecordTable`` instances that match the filters
         """
         with self.make_session() as session:
-            query = session.query(TagRecordTable)
+            query_stmt = session.query(TagRecordTable)
             if begin_dt:
-                query = query.filter(TagRecordTable.end_dt >= begin_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
-                query = query.filter(TagRecordTable.begin_dt <= end_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
             if tagset_namespace:
-                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
             if tagset_version:
-                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
             if tag_prefix:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
                 else:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
-
-            for result in query.yield_per(batch_size):
+            if skip is not None or limit is not None:
+                query_stmt = query_stmt.order_by(TagRecordTable.sqn.desc())
+                if skip is not None:
+                    query_stmt = query_stmt.offset(skip)
+                if limit is not None:
+                    query_stmt = query_stmt.limit(limit)
+
+            for result in query_stmt.yield_per(batch_size):
                 yield result
 
-    def iter_tag_and_targets(
+    def iter_record_and_targets(
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
@@ -791,10 +813,12 @@ class TagCache(object):
         target_end_dt: datetime.datetime | None = None,
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
+        skip: int | None = None,
+        limit: int | None = None,
         batch_size: int = 1000,
     ) -> Generator[tuple[TagRecordTable, TagTargetTable], None, None]:
         """
-        Query tag records along with their target info in the cache with optional filters.
+        Query tag records along with their target in the cache with optional filters.
 
         :param begin_dt: Filter by begin time (inclusive)
         :param end_dt: Filter by end time (inclusive)
@@ -810,49 +834,57 @@ class TagCache(object):
         :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
         :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
                                 tagsets)
+        :param skip: Number of records to skip (for pagination)
+        :param limit: Maximum number of records to return (for pagination)
         :param batch_size: Number of records to fetch per batch from the database (for memory efficiency)
         :return: Generator of ``TagRecordTable`` instances that match the filters
         """
         with self.make_session() as session:
-            query = (
+            query_stmt = (
                 session
                 .query(TagRecordTable, TagTargetTable)
                 .join(TagTargetTable, TagRecordTable.target_sqn == TagTargetTable.sqn)
             )
             if begin_dt:
-                query = query.filter(TagRecordTable.end_dt >= begin_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
-                query = query.filter(TagRecordTable.begin_dt <= end_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
             if tagset_namespace:
-                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
             if tagset_version:
-                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
             if tag_prefix:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if target_identifier:
-                query = query.filter(TagTargetTable.identifier == target_identifier)
+                query_stmt = query_stmt.filter(TagTargetTable.identifier == target_identifier)
             if target_tagger_name:
-                query = query.filter(TagTargetTable.tagger_name == target_tagger_name)
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_name == target_tagger_name)
             if target_tagger_version:
-                query = query.filter(TagTargetTable.tagger_version == target_tagger_version)
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_version == target_tagger_version)
             if target_vehicle_name:
-                query = query.filter(TagTargetTable.vehicle_name == target_vehicle_name)
+                query_stmt = query_stmt.filter(TagTargetTable.vehicle_name == target_vehicle_name)
             if target_begin_dt:
-                query = query.filter(TagTargetTable.end_dt >= target_begin_dt)
+                query_stmt = query_stmt.filter(TagTargetTable.end_dt >= target_begin_dt)
             if target_end_dt:
-                query = query.filter(TagTargetTable.begin_dt <= target_end_dt)
+                query_stmt = query_stmt.filter(TagTargetTable.begin_dt <= target_end_dt)
             if tagsets:
                 if tagset_inverted:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
                 else:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
-
-            for result in query.yield_per(batch_size):
+            if skip is not None or limit is not None:
+                query_stmt = query_stmt.order_by(TagRecordTable.sqn.desc())
+                if skip is not None:
+                    query_stmt = query_stmt.offset(skip)
+                if limit is not None:
+                    query_stmt = query_stmt.limit(limit)
+
+            for result in query_stmt.yield_per(batch_size):
                 yield result
 
-    def remove_tags(
+    def remove_records(
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
@@ -876,26 +908,26 @@ class TagCache(object):
                                 tagsets)
         """
         with self.make_session() as session:
-            query = session.query(TagRecordTable)
+            query_stmt = session.query(TagRecordTable)
             if begin_dt:
-                query = query.filter(TagRecordTable.end_dt >= begin_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
-                query = query.filter(TagRecordTable.begin_dt <= end_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
             if tagset_namespace:
-                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
             if tagset_version:
-                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
             if tag_prefix:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
                 else:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
 
-            query.delete()
+            query_stmt.delete()
             session.commit()
 
     def clear(self):
@@ -924,42 +956,59 @@ class TagCache(object):
             return
 
         with src.make_session() as src_session, dst.make_session() as dst_session:
-            src_targets = src_session.query(TagTargetTable).all()
-            dst_targets = [
-                clone_sequence_model_instance(TagTargetTable, db_tag_target_info, clear_meta_fields=True)
-                for db_tag_target_info in src_targets
+            src_db_tag_targets = src_session.query(TagTargetTable).all()
+            dst_db_tag_targets = [
+                clone_sequence_model_instance(TagTargetTable, db_tag_target, clear_meta_fields=True)
+                for db_tag_target in src_db_tag_targets
             ]
-            dst_session.add_all(dst_targets)
+            dst_session.add_all(dst_db_tag_targets)
             dst_session.flush()  # ensure new sqn values are assigned
 
-            sqn_map = {src_target.sqn: dst_target.sqn for src_target, dst_target in zip(src_targets, dst_targets)}
+            sqn_map = {src_db_tag_target.sqn: dst_db_tag_target.sqn
+                       for src_db_tag_target, dst_db_tag_target in zip(src_db_tag_targets, dst_db_tag_targets)}
 
-            for results in batched(src_session.query(TagRecordTable).yield_per(1000), 1000):
-                clones = []
-                for db_tag_record in results:
-                    cloned = clone_sequence_model_instance(TagRecordTable, db_tag_record, clear_meta_fields=True)
+            for db_tag_records in batched(src_session.query(TagRecordTable).yield_per(1000), 1000):
+                cloned_db_tag_records = []
+                for db_tag_record in db_tag_records:
+                    cloned_db_tag_record = clone_sequence_model_instance(TagRecordTable,
+                                                                         db_tag_record,
+                                                                         clear_meta_fields=True)
                     try:
-                        cloned.target_sqn = sqn_map[db_tag_record.target_sqn]
+                        cloned_db_tag_record.target_sqn = sqn_map[db_tag_record.target_sqn]
                     except KeyError as e:
-                        raise ValueError(f"no cloned target for target_sqn '{db_tag_record.target_sqn}'") from e
-                    clones.append(cloned)
-                dst_session.add_all(clones)
+                        raise ValueError(f"no cloned tag target for target_sqn '{db_tag_record.target_sqn}'") from e
+                    cloned_db_tag_records.append(cloned_db_tag_record)
+                dst_session.add_all(cloned_db_tag_records)
             dst_session.commit()
 
+    count_tags = count_records
+    iter_tags = iter_records
+    iter_tag_and_targets = iter_record_and_targets
+    remove_tags = remove_records
+
 
 class TargetedTagCache(object):
-    def __init__(self, cache: TagCache, target_info: TagTargetTable):
-        self.target_info = target_info
+    def __init__(self, cache: TagCache, tag_target: TagTargetTable):
         self.cache = cache
+        self.tag_target = tag_target
 
     @contextlib.contextmanager
     def make_session(self) -> Generator[sa_orm.Session, None, None]:
         with self.cache.make_session() as session:
-            if not session.query(TagTargetTable).filter(TagTargetTable.sqn == self.target_info.sqn).first():
-                raise ValueError(f"target info with sqn '{self.target_info.sqn}' is no longer present in cache")
+            if not session.query(TagTargetTable).filter(TagTargetTable.sqn == self.tag_target.sqn).first():
+                raise ValueError(f"tag target with sqn '{self.tag_target.sqn}' is no longer present in cache")
             yield session
 
-    def iter_tags(
+    def count_records(self) -> int:
+        with self.make_session() as session:
+            return (
+                session
+                .query(sa.func.count(TagRecordTable.sqn))
+                .filter(TagRecordTable.target_sqn == self.tag_target.sqn)
+                .scalar()
+            )
+
+    def iter_records(
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
@@ -969,6 +1018,8 @@ class TargetedTagCache(object):
         *,
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
+        skip: int | None = None,
+        limit: int | None = None,
         batch_size: int = 1000,
     ) -> Generator[TagRecordTable, None, None]:
         """
@@ -982,34 +1033,42 @@ class TargetedTagCache(object):
         :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
         :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
                                 tagsets)
+        :param skip: Number of records to skip (for pagination)
+        :param limit: Maximum number of records to return (for pagination)
         :param batch_size: Number of records to fetch per batch from the database (for memory efficiency)
         :return: Generator of ``TagRecordTable`` instances that match the filters
         """
 
         with self.make_session() as session:
-            query = session.query(TagRecordTable).filter(TagRecordTable.target_sqn == self.target_info.sqn)
+            query_stmt = session.query(TagRecordTable).filter(TagRecordTable.target_sqn == self.tag_target.sqn)
             if begin_dt:
-                query = query.filter(TagRecordTable.end_dt >= begin_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
-                query = query.filter(TagRecordTable.begin_dt <= end_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
             if tagset_namespace:
-                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
             if tagset_version:
-                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
             if tag_prefix:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
                 else:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
-
-            for result in query.yield_per(batch_size):
+            if skip is not None or limit is not None:
+                query_stmt = query_stmt.order_by(TagRecordTable.sqn.desc())
+                if skip is not None:
+                    query_stmt = query_stmt.offset(skip)
+                if limit is not None:
+                    query_stmt = query_stmt.limit(limit)
+
+            for result in query_stmt.yield_per(batch_size):
                 yield result
 
-    def add_ranged_tag(
+    def add_ranged_record(
         self,
         begin_dt: datetime.datetime | None,
         end_dt: datetime.datetime | None,
@@ -1036,9 +1095,9 @@ class TargetedTagCache(object):
         """
         with self.make_session() as session:
             tag_record = TagRecord(
-                target_sqn=self.target_info.sqn,
-                begin_dt=begin_dt or self.target_info.begin_dt,
-                end_dt=end_dt or self.target_info.end_dt,
+                target_sqn=self.tag_target.sqn,
+                begin_dt=begin_dt or self.tag_target.begin_dt,
+                end_dt=end_dt or self.tag_target.end_dt,
                 tagset_namespace=tag.namespace if isinstance(tag, BoundTag) else tagset_namespace,
                 tagset_version=tag.version if isinstance(tag, BoundTag) else tagset_version,
                 tag=tag.name if isinstance(tag, Tag) else tag,
@@ -1050,7 +1109,7 @@ class TargetedTagCache(object):
 
             return chainable(self, db_tag_record)
 
-    def add_tag(
+    def add_record(
         self,
         tag: str | Tag | BoundTag,
         props: JsonType | None = None,
@@ -1071,16 +1130,16 @@ class TargetedTagCache(object):
                                will be used.
         :return: Self instance for chaining
         """
-        return self.add_ranged_tag(
-            begin_dt=self.target_info.begin_dt,
-            end_dt=self.target_info.end_dt,
+        return self.add_ranged_record(
+            begin_dt=self.tag_target.begin_dt,
+            end_dt=self.tag_target.end_dt,
             tag=tag,
             tagset_namespace=tagset_namespace,
             tagset_version=tagset_version,
             props=props,
         )
 
-    def update_tag(
+    def update_record(
         self,
         sqn: int,
         *,
@@ -1134,7 +1193,7 @@ class TargetedTagCache(object):
 
             return chainable(self, db_tag_record)
 
-    def remove_tags(
+    def remove_records(
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
@@ -1159,30 +1218,37 @@ class TargetedTagCache(object):
         :return: Self instance for chaining
         """
         with self.make_session() as session:
-            query = session.query(TagRecordTable).filter(TagRecordTable.target_sqn == self.target_info.sqn)
+            query_stmt = session.query(TagRecordTable).filter(TagRecordTable.target_sqn == self.tag_target.sqn)
             if begin_dt:
-                query = query.filter(TagRecordTable.end_dt >= begin_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
-                query = query.filter(TagRecordTable.begin_dt <= end_dt)
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
             if tagset_namespace:
-                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
             if tagset_version:
-                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
             if tag_prefix:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
                 else:
-                    query = query.filter(
+                    query_stmt = query_stmt.filter(
                         TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
 
-            query.delete()
+            query_stmt.delete()
             session.commit()
 
         return self
 
+    count_tags = count_records
+    iter_tags = iter_records
+    add_ranged_tag = add_ranged_record
+    add_tag = add_record
+    update_tag = update_record
+    remove_tags = remove_records
+
 
 @memorized
 def tag_cache(*, identifier: str | None = None, file_path: str | os.PathLike[str] | None = None) -> TagCache:

{plexus_python_common-1.0.68.dist-info → plexus_python_common-1.0.70.dist-info}/METADATA

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

{plexus_python_common-1.0.68.dist-info → plexus_python_common-1.0.70.dist-info}/RECORD

@@ -16,14 +16,14 @@ plexus/common/utils/datautils.py,sha256=mgnr-dcHpw-Pk3qBud0lC3JX_pv-iKzI8llsPW9Q
 plexus/common/utils/dockerutils.py,sha256=WPxQuabRWyyM8wpSSYhb_HZaOw5yZ2TbU2dEQ2xRIlQ,5787
 plexus/common/utils/gisutils.py,sha256=UR3uVoD1nAy0SWJ1AYWCUy94Lo8zNb4nv_JdpcANBDE,11462
 plexus/common/utils/jsonutils.py,sha256=-_uKlQMLMgmVO9pB99S45Y_Vufx5dFSq43DIwGz1a54,3328
-plexus/common/utils/ormutils.py,sha256=CHrp6l5shRL2qa8GzRLqeVbtC-eZZkfWCOpBy32JDok,60433
+plexus/common/utils/ormutils.py,sha256=bAJDSp-53406E5iySueh09yQUs0OuCshygRSzU9aaW0,60667
 plexus/common/utils/pathutils.py,sha256=hGJqSLj08tuOeZ7WeC5d4BtjnPI732BuntVQBQsqOaI,9581
 plexus/common/utils/s3utils.py,sha256=zlO4kGs-c2gUeOfPfiKIE5liQZsbYxqAZYCwA8kL0Lo,36017
 plexus/common/utils/sqlutils.py,sha256=D6kTBjhO5YlNRt3uFlPt6z3uH61m9ajEzPYmsI6NoFc,231
 plexus/common/utils/strutils.py,sha256=O9Inv4ffUTf6Xjc5ftoZwbIua1NeG7itCT9S3zjZxBc,16436
-plexus/common/utils/tagutils.py,sha256=n4yd4KIq8Ub4sGN8wYFom1Ea4IJ19s9UEW-rTl30NDs,52104
+plexus/common/utils/tagutils.py,sha256=F1t62lxNCskirUQ9sIs5Q7hVWAF71f5Hs1aQ3Sj0X4w,55759
 plexus/common/utils/testutils.py,sha256=N8ijLu7X-hlQlHzvv0TtSsQpIF4T1hbr-AjkILoV2Ac,6152
-plexus_python_common-1.0.68.dist-info/METADATA,sha256=qUVFVvm5czJv0ATp6QvMPfAjPfoJGn0CCcD_ckNNfVA,1481
-plexus_python_common-1.0.68.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-plexus_python_common-1.0.68.dist-info/top_level.txt,sha256=ug_g7CVwaMQuas5UzAXbHUrQvKGCn8ezc6ZNvvRlJOE,7
-plexus_python_common-1.0.68.dist-info/RECORD,,
+plexus_python_common-1.0.70.dist-info/METADATA,sha256=ZZjSJxN2hxIf9b9wmR0HqftEGdvADSZuf3KNBX3ad1g,1481
+plexus_python_common-1.0.70.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+plexus_python_common-1.0.70.dist-info/top_level.txt,sha256=ug_g7CVwaMQuas5UzAXbHUrQvKGCn8ezc6ZNvvRlJOE,7
+plexus_python_common-1.0.70.dist-info/RECORD,,