plexus-python-common 1.0.67__tar.gz → 1.0.69__tar.gz

{plexus_python_common-1.0.67 → plexus_python_common-1.0.69}/.github/workflows/pr.yml

@@ -18,10 +18,10 @@ jobs:
         python-version: [ "3.12", "3.13", "3.14" ]
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "${{ matrix.python-version }}"
 

{plexus_python_common-1.0.67 → plexus_python_common-1.0.69}/.github/workflows/push.yml

@@ -15,10 +15,10 @@ jobs:
       options: --user github
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.14"
 
@@ -31,7 +31,7 @@ jobs:
           python -m twine upload --username __token__ --password ${{ secrets.PYPI_TOKEN }} dist/*
 
       - name: Upload Coverage Report
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: ${{ github.repository }}

{plexus_python_common-1.0.67 → plexus_python_common-1.0.69}/PKG-INFO

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

{plexus_python_common-1.0.67 → plexus_python_common-1.0.69}/src/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_python_common-1.0.67 → plexus_python_common-1.0.69}/src/plexus/common/utils/tagutils.py

@@ -645,21 +645,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,
@@ -671,7 +671,7 @@ class TagCache(object):
         end_dt: datetime.datetime,
     ) -> TagTargetTable:
         with self.make_session() as session:
-            target_info = TagTarget(
+            tag_target = TagTarget(
                 identifier=identifier,
                 tagger_name=tagger_name,
                 tagger_version=tagger_version,
@@ -679,8 +679,8 @@ class TagCache(object):
                 begin_dt=begin_dt,
                 end_dt=end_dt,
             )
-            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 +695,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 +721,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 iter_tags(
+    def count_records(self) -> int:
+        with self.make_session() as session:
+            return session.query(sa.func.count(TagRecordTable.sqn)).scalar()
+
+    def iter_records(
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
@@ -736,6 +740,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 +755,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 +805,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 +826,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 +900,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 +948,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 +1010,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 +1025,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 +1087,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 +1101,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 +1122,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 +1185,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 +1210,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.67 → plexus_python_common-1.0.69}/src/plexus_python_common.egg-info/PKG-INFO

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

{plexus_python_common-1.0.67 → plexus_python_common-1.0.69}/test/plexus_tests/common/utils/tagutils_test.py

@@ -149,6 +149,7 @@ class TagUtilsTest(unittest.TestCase):
                 },
             )
 
+        self.assertEqual(target_cache.count_tags(), tag_records_count)
         self.assertEqual(len(list(target_cache.iter_tags())), tag_records_count)
         self.assertEqual(len(list(target_cache.iter_tags(tagsets=[tagset]))),
                          tag_records_count * tagset_tags_count // tags_count)
@@ -204,15 +205,25 @@ class TagUtilsTest(unittest.TestCase):
 
         target_cache.remove_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"), dt_parse_iso("2020-01-01T00:01:00+00:00"))
 
+        self.assertEqual(target_cache.count_tags(), tag_records_count - (60 + 1))
         self.assertEqual(len(list(target_cache.iter_tags())), tag_records_count - (60 + 1))
+        self.assertEqual(cache.count_tags(), tag_records_count - (60 + 1))
         self.assertEqual(len(list(cache.iter_tags())), tag_records_count - (60 + 1))
 
         target_cache.remove_tags(tagsets=[tagset], tagset_inverted=True)
 
+        self.assertEqual(
+            target_cache.count_tags(),
+            tag_records_count * tagset_tags_count // tags_count - (60 * tagset_tags_count // tags_count + 1),
+        )
         self.assertEqual(
             len(list(target_cache.iter_tags())),
             tag_records_count * tagset_tags_count // tags_count - (60 * tagset_tags_count // tags_count + 1),
         )
+        self.assertEqual(
+            cache.count_tags(),
+            tag_records_count * tagset_tags_count // tags_count - (60 * tagset_tags_count // tags_count + 1),
+        )
         self.assertEqual(
             len(list(cache.iter_tags())),
             tag_records_count * tagset_tags_count // tags_count - (60 * tagset_tags_count // tags_count + 1),
@@ -220,7 +231,9 @@ class TagUtilsTest(unittest.TestCase):
 
         target_cache.remove_tags()
 
+        self.assertEqual(target_cache.count_tags(), 0)
         self.assertEqual(len(list(target_cache.iter_tags())), 0)
+        self.assertEqual(cache.count_tags(), 0)
         self.assertEqual(len(list(cache.iter_tags())), 0)
 
     def test_tag_cache__multithread(self):
@@ -307,6 +320,7 @@ class TagUtilsTest(unittest.TestCase):
                 thread.join()
 
             for target_cache in target_caches:
+                self.assertEqual(target_cache.count_tags(), tasks_count_per_target_cache)
                 self.assertEqual(len(list(target_cache.iter_tags())), tasks_count_per_target_cache)
                 self.assertEqual(len(list(target_cache.iter_tags(tag_prefix="dummy:bar"))),
                                  tasks_count_per_target_cache // tags_count)
@@ -315,6 +329,7 @@ class TagUtilsTest(unittest.TestCase):
                 self.assertEqual(len(list(target_cache.iter_tags(tagset_namespace="tagset", tagset_version="1.0.0"))),
                                  tasks_count_per_target_cache * old_tagset_tags_count // tags_count)
 
+            self.assertEqual(cache.count_tags(), total_tasks_count)
             self.assertEqual(len(list(cache.iter_tag_and_targets())), total_tasks_count)
             self.assertEqual(len(list(cache.iter_tag_and_targets(tag_prefix="dummy:bar"))),
                              total_tasks_count // tags_count)
@@ -357,7 +372,7 @@ class TagUtilsTest(unittest.TestCase):
             for i in range(tag_records_count):
                 tag_name = tag_names[i % len(tag_names)]
                 tag = tagset.get_bound(tag_name) or tag_name
-                src_target_cache.add_tag(tag)
+                src_target_cache.add_record(tag)
 
             dst_cache = TagCache(file_path=temp_directory / "dst_tag_cache.db")
 
@@ -366,24 +381,26 @@ class TagUtilsTest(unittest.TestCase):
             for i in range(tag_records_count):
                 tag_name = tag_names[i % len(tag_names)]
                 tag = tagset.get_bound(tag_name) or tag_name
-                src_target_cache.add_tag(tag)
+                src_target_cache.add_record(tag)
 
             dst_target_cache = dst_cache.with_target("awesome_tagger/20200101_000000/dummy_vehicle/0")
 
-            self.assertEqual(len(list(src_target_cache.iter_tags())), tag_records_count * 2)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset]))),
+            self.assertEqual(src_target_cache.count_records(), tag_records_count * 2)
+            self.assertEqual(len(list(src_target_cache.iter_records())), tag_records_count * 2)
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset]))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=True))),
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset], tagset_inverted=True))),
                              tag_records_count * 2 * (tags_count - tagset_tags_count) // tags_count)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=False))),
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset], tagset_inverted=False))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
 
-            self.assertEqual(len(list(dst_target_cache.iter_tags())), tag_records_count)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset]))),
+            self.assertEqual(dst_target_cache.count_records(), tag_records_count)
+            self.assertEqual(len(list(dst_target_cache.iter_records())), tag_records_count)
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset]))),
                              tag_records_count * tagset_tags_count // tags_count)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=True))),
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset], tagset_inverted=True))),
                              tag_records_count * (tags_count - tagset_tags_count) // tags_count)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=False))),
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset], tagset_inverted=False))),
                              tag_records_count * tagset_tags_count // tags_count)
 
     def test_tag_cache__clone_same_file(self):
@@ -422,7 +439,7 @@ class TagUtilsTest(unittest.TestCase):
             for i in range(tag_records_count):
                 tag_name = tag_names[i % len(tag_names)]
                 tag = tagset.get_bound(tag_name) or tag_name
-                src_target_cache.add_tag(tag)
+                src_target_cache.add_record(tag)
 
             dst_cache = TagCache(file_path=temp_directory / "tag_cache.db")
 
@@ -431,24 +448,26 @@ class TagUtilsTest(unittest.TestCase):
             for i in range(tag_records_count):
                 tag_name = tag_names[i % len(tag_names)]
                 tag = tagset.get_bound(tag_name) or tag_name
-                src_target_cache.add_tag(tag)
+                src_target_cache.add_record(tag)
 
             dst_target_cache = dst_cache.with_target("awesome_tagger/20200101_000000/dummy_vehicle/0")
 
-            self.assertEqual(len(list(src_target_cache.iter_tags())), tag_records_count * 2)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset]))),
+            self.assertEqual(src_target_cache.count_records(), tag_records_count * 2)
+            self.assertEqual(len(list(src_target_cache.iter_records())), tag_records_count * 2)
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset]))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=True))),
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset], tagset_inverted=True))),
                              tag_records_count * 2 * (tags_count - tagset_tags_count) // tags_count)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=False))),
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset], tagset_inverted=False))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
 
-            self.assertEqual(len(list(dst_target_cache.iter_tags())), tag_records_count * 2)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset]))),
+            self.assertEqual(dst_target_cache.count_records(), tag_records_count * 2)
+            self.assertEqual(len(list(dst_target_cache.iter_records())), tag_records_count * 2)
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset]))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=True))),
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset], tagset_inverted=True))),
                              tag_records_count * 2 * (tags_count - tagset_tags_count) // tags_count)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=False))),
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset], tagset_inverted=False))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
 
         with tempfile.TemporaryDirectory() as temp_directory:
@@ -470,7 +489,7 @@ class TagUtilsTest(unittest.TestCase):
             for i in range(tag_records_count):
                 tag_name = tag_names[i % len(tag_names)]
                 tag = tagset.get_bound(tag_name) or tag_name
-                src_target_cache.add_tag(tag)
+                src_target_cache.add_record(tag)
 
             dst_cache = src_cache
 
@@ -479,24 +498,26 @@ class TagUtilsTest(unittest.TestCase):
             for i in range(tag_records_count):
                 tag_name = tag_names[i % len(tag_names)]
                 tag = tagset.get_bound(tag_name) or tag_name
-                src_target_cache.add_tag(tag)
+                src_target_cache.add_record(tag)
 
             dst_target_cache = dst_cache.with_target("awesome_tagger/20200101_000000/dummy_vehicle/0")
 
-            self.assertEqual(len(list(src_target_cache.iter_tags())), tag_records_count * 2)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset]))),
+            self.assertEqual(src_target_cache.count_records(), tag_records_count * 2)
+            self.assertEqual(len(list(src_target_cache.iter_records())), tag_records_count * 2)
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset]))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=True))),
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset], tagset_inverted=True))),
                              tag_records_count * 2 * (tags_count - tagset_tags_count) // tags_count)
-            self.assertEqual(len(list(src_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=False))),
+            self.assertEqual(len(list(src_target_cache.iter_records(tagsets=[tagset], tagset_inverted=False))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
 
-            self.assertEqual(len(list(dst_target_cache.iter_tags())), tag_records_count * 2)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset]))),
+            self.assertEqual(dst_target_cache.count_records(), tag_records_count * 2)
+            self.assertEqual(len(list(dst_target_cache.iter_records())), tag_records_count * 2)
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset]))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=True))),
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset], tagset_inverted=True))),
                              tag_records_count * 2 * (tags_count - tagset_tags_count) // tags_count)
-            self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=False))),
+            self.assertEqual(len(list(dst_target_cache.iter_records(tagsets=[tagset], tagset_inverted=False))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
 
     data_populate_clip_ranges = [