plexus-python-common 1.0.49__tar.gz → 1.0.50__tar.gz

{plexus_python_common-1.0.49 → plexus_python_common-1.0.50}/PKG-INFO

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

{plexus_python_common-1.0.49 → plexus_python_common-1.0.50}/src/plexus/common/utils/tagutils.py

@@ -13,7 +13,7 @@ import sqlalchemy as sa
 import sqlalchemy.dialects.sqlite as sa_sqlite
 import sqlalchemy.orm as sa_orm
 from iker.common.utils.dbutils import ConnectionMaker
-from iker.common.utils.funcutils import singleton
+from iker.common.utils.funcutils import memorized, 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
@@ -24,15 +24,17 @@ from iker.common.utils.strutils import is_blank
 from sqlmodel import Field, SQLModel
 
 from plexus.common.resources.tags import predefined_tagset_specs
+from plexus.common.utils.datautils import validate_bag_name, validate_dt_timezone
 from plexus.common.utils.datautils import validate_colon_tag, validate_snake_case, validate_vehicle_name
-from plexus.common.utils.datautils import validate_dt_timezone
 from plexus.common.utils.ormutils import SequenceModelMixinProtocol
 from plexus.common.utils.ormutils import clone_sequence_model_instance, make_base_model, make_sequence_model_mixin
 from plexus.common.utils.sqlutils import escape_sql_like
 
 __all__ = [
     "TagRecord",
+    "BagTagRecord",
     "TagRecordTable",
+    "BagTagRecordTable",
     "RichDesc",
     "Tag",
     "Tagset",
@@ -42,6 +44,7 @@ __all__ = [
     "render_tagset_markdown_readme",
     "tag_cache_file_path",
     "TagCache",
+    "tag_cache",
 ]
 
 BaseModel = make_base_model()
@@ -61,7 +64,7 @@ class TagRecord(BaseModel):
         description="End datetime of the tag record",
     )
     tag: str = Field(
-        sa_column=sa.Column(sa_sqlite.TEXT, nullable=False),
+        sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False),
         description="Tag name",
     )
     props: JsonType | None = Field(
@@ -91,7 +94,73 @@ class TagRecord(BaseModel):
     @pdt.model_validator(mode="after")
     def validate_begin_dt_end_dt(self) -> Self:
         if self.begin_dt > self.end_dt:
-            raise ValueError(f"begin dt '{self.begin_dt}' is greater than end dt '{self.end_dt}'")
+            raise ValueError(f"begin_dt '{self.begin_dt}' is greater than end_dt '{self.end_dt}'")
+        return self
+
+    @pdt.field_validator("tag", mode="after")
+    @classmethod
+    def validate_tag(cls, v: str) -> str:
+        validate_colon_tag(v)
+        return v
+
+
+class BagTagRecord(BaseModel):
+    vehicle_name: str = Field(
+        sa_column=sa.Column(sa_sqlite.TEXT, nullable=False),
+        description="Vehicle name associated with the tag record",
+    )
+    bag_name: str = Field(
+        sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False),
+        description="Name of the bag associated with the tag record",
+    )
+    begin_offset: int = Field(
+        sa_column=sa.Column(sa_sqlite.INTEGER, nullable=False),
+        description="Begin offset (in microseconds) of the tag record within the bag",
+    )
+    end_offset: int = Field(
+        sa_column=sa.Column(sa_sqlite.INTEGER, nullable=False),
+        description="End offset (in microseconds) of the tag record within the bag",
+    )
+    tag: str = Field(
+        sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False),
+        description="Tag name",
+    )
+    props: JsonType | None = Field(
+        sa_column=sa.Column(sa_sqlite.TEXT, nullable=True),
+        default=None,
+        description="Additional properties of the tag record in JSON format",
+    )
+
+    @pdt.field_validator("vehicle_name", mode="after")
+    @classmethod
+    def validate_vehicle_name(cls, v: str) -> str:
+        validate_vehicle_name(v)
+        return v
+
+    @pdt.field_validator("bag_name", mode="after")
+    @classmethod
+    def validate_bag_name(cls, v: str) -> str:
+        validate_bag_name(v)
+        return v
+
+    @pdt.field_validator("begin_offset", mode="after")
+    @classmethod
+    def validate_begin_offset(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError(f"begin_offset '{v}' is negative")
+        return v
+
+    @pdt.field_validator("end_offset", mode="after")
+    @classmethod
+    def validate_end_offset(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError(f"end_offset '{v}' is negative")
+        return v
+
+    @pdt.model_validator(mode="after")
+    def validate_begin_offset_end_offset(self) -> Self:
+        if self.begin_offset > self.end_offset:
+            raise ValueError(f"begin offset '{self.begin_offset}' is greater than end offset '{self.end_offset}'")
         return self
 
     @pdt.field_validator("tag", mode="after")
@@ -105,6 +174,10 @@ class TagRecordTable(TagRecord, make_sequence_model_mixin("sqlite"), table=True)
     __tablename__ = "tag_record"
 
 
+class BagTagRecordTable(BagTagRecord, make_sequence_model_mixin("sqlite"), table=True):
+    __tablename__ = "bag_tag_record"
+
+
 if typing.TYPE_CHECKING:
     class TagRecordTable(SQLModel, SequenceModelMixinProtocol):
         vehicle_name: sa_orm.Mapped[str] = ...
@@ -400,7 +473,21 @@ class TagCache(object):
         tag_pattern: str | None = None,
         *,
         tagsets: Sequence[Tagset] | None = None,
-    ) -> Generator[TagRecordTable]:
+        tagset_inverted: bool = False,
+    ) -> Generator[TagRecordTable, None, None]:
+        """
+        Query tag records in the cache with optional filters.
+
+        :param vehicle_name: Filter by vehicle name (exact match)
+        :param begin_time: Filter by begin time (inclusive)
+        :param end_time: Filter by end time (inclusive)
+        :param tag_pattern: Filter by tag name pattern (SQL LIKE syntax, e.g. "dummy_tag:%" to match all tags starting
+        with "dummy_tag:")
+        :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)
+        :return: Generator of ``TagRecordTable`` instances that match the filters
+        """
         with self.conn_maker.make_session() as session:
             query = session.query(TagRecordTable)
             if vehicle_name:
@@ -411,16 +498,62 @@ class TagCache(object):
                 query = query.filter(TagRecordTable.begin_dt <= end_time)
             if tag_pattern:
                 query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query = query.filter(
+                        TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query = query.filter(
+                        TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
 
-            if not tagsets:
-                yield from query.all()
-            else:
-                yield from (db_tag_record for db_tag_record in query.all()
-                            if any(db_tag_record.tag in tagset for tagset in tagsets))
+            yield from query.all()
+
+    def query_bag_tag(
+        self,
+        vehicle_name: str | None = None,
+        bag_name: str | None = None,
+        begin_offset: int | None = None,
+        end_offset: int | None = None,
+        tag_pattern: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+    ) -> Generator[BagTagRecordTable, None, None]:
+        """
+        Query bag tag records in the cache with optional filters.
+
+        :param vehicle_name: Filter by vehicle name (exact match)
+        :param bag_name: Filter by bag name (exact match)
+        :param begin_offset: Filter by begin offset (inclusive)
+        :param end_offset: Filter by end offset (inclusive)
+        :param tag_pattern: Filter by tag name pattern (SQL LIKE syntax, e.g. "dummy_tag:%" to match all tags starting
+        with "dummy_tag:")
+        :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)
+        :return: Generator of ``BagTagRecordTable`` instances that match the filters
+        """
+        with self.conn_maker.make_session() as session:
+            query = session.query(BagTagRecordTable)
+            if vehicle_name:
+                query = query.filter(BagTagRecordTable.vehicle_name == vehicle_name)
+            if bag_name:
+                query = query.filter(BagTagRecordTable.bag_name == bag_name)
+                if begin_offset:
+                    query = query.filter(BagTagRecordTable.end_offset >= begin_offset)
+                if end_offset:
+                    query = query.filter(BagTagRecordTable.begin_offset <= end_offset)
+            if tag_pattern:
+                query = query.filter(BagTagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query = query.filter(
+                        BagTagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query = query.filter(
+                        BagTagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
 
-    def undefined(self, tagsets: Sequence[Tagset]) -> Generator[TagRecordTable, None, None]:
-        yield from (db_tag_record for db_tag_record in self.query()
-                    if all(db_tag_record.tag not in tagset for tagset in tagsets))
+            yield from query.all()
 
     def add(
         self,
@@ -430,6 +563,16 @@ class TagCache(object):
         tag: str | Tag,
         props: JsonType | None = None,
     ) -> Self:
+        """
+        Add a tag record to the cache.
+
+        :param vehicle_name: Vehicle name associated with the tag record
+        :param begin_time: Begin datetime of the tag record
+        :param end_time: End datetime of the tag record
+        :param tag: Tag name or Tag instance to be added (if Tag instance is provided, its name will be used)
+        :param props: Additional properties of the tag record in JSON format (optional)
+        :return: Self instance for chaining
+        """
         with self.conn_maker.make_session() as session:
             tag_record = TagRecord(
                 vehicle_name=vehicle_name,
@@ -443,17 +586,132 @@ class TagCache(object):
 
         return self
 
-    def remove(self, vehicle_name: str, begin_time: datetime.datetime, end_time: datetime.datetime) -> Self:
+    def add_bag_tag(
+        self,
+        vehicle_name: str,
+        bag_name: str,
+        begin_offset: int,
+        end_offset: int,
+        tag: str | Tag,
+        props: JsonType | None = None,
+    ) -> Self:
+        """
+        Add a bag tag record to the cache.
+
+        :param vehicle_name: Vehicle name associated with the tag record
+        :param bag_name: Name of the bag associated with the tag record
+        :param begin_offset: Begin offset (in microseconds) of the tag record within the bag (inclusive)
+        :param end_offset: End offset (in microseconds) of the tag record within the bag (inclusive)
+        :param tag: Tag name or Tag instance to be added (if Tag instance is provided, its name will be used)
+        :param props: Additional properties of the tag record in JSON format (optional)
+        :return: Self instance for chaining
+        """
         with self.conn_maker.make_session() as session:
-            session.execute(
-                sa
-                .delete(TagRecordTable)
-                .where(
-                    TagRecordTable.vehicle_name == vehicle_name,
-                    TagRecordTable.end_dt >= begin_time,
-                    TagRecordTable.begin_dt <= end_time,
-                )
+            tag_record = BagTagRecord(
+                vehicle_name=vehicle_name,
+                bag_name=bag_name,
+                begin_offset=begin_offset,
+                end_offset=end_offset,
+                tag=tag.name if isinstance(tag, Tag) else tag,
+                props=props,
             )
+            session.add(clone_sequence_model_instance(BagTagRecordTable, tag_record))
+            session.commit()
+
+        return self
+
+    def remove(
+        self,
+        vehicle_name: str | None = None,
+        begin_time: datetime.datetime | None = None,
+        end_time: datetime.datetime | None = None,
+        tag_pattern: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+    ) -> Self:
+        """
+        Remove tag records from the cache that match the specified filters.
+
+        :param vehicle_name: Filter by vehicle name (exact match)
+        :param begin_time: Filter by begin time (inclusive)
+        :param end_time: Filter by end time (inclusive)
+        :param tag_pattern: Filter by tag name pattern (SQL LIKE syntax, e.g. "dummy_tag:%" to match all tags starting
+        with "dummy_tag:")
+        :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)
+        :return: Self instance for chaining
+        """
+        with self.conn_maker.make_session() as session:
+            query = session.query(TagRecordTable)
+            if vehicle_name:
+                query = query.filter(TagRecordTable.vehicle_name == vehicle_name)
+            if begin_time:
+                query = query.filter(TagRecordTable.end_dt >= begin_time)
+            if end_time:
+                query = query.filter(TagRecordTable.begin_dt <= end_time)
+            if tag_pattern:
+                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query = query.filter(
+                        TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query = query.filter(
+                        TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+
+            query.delete()
+            session.commit()
+
+        return self
+
+    def remove_bag_tag(
+        self,
+        vehicle_name: str | None = None,
+        bag_name: str | None = None,
+        begin_offset: int | None = None,
+        end_offset: int | None = None,
+        tag_pattern: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+    ) -> Self:
+        """
+        Remove bag tag records from the cache that match the specified filters.
+
+        :param vehicle_name: Filter by vehicle name (exact match)
+        :param bag_name: Filter by bag name (exact match)
+        :param begin_offset: Filter by begin offset (inclusive)
+        :param end_offset: Filter by end offset (inclusive)
+        :param tag_pattern: Filter by tag name pattern (SQL LIKE syntax, e.g. "dummy_tag:%" to match all tags starting
+        with "dummy_tag:")
+        :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)
+        :return: Self instance for chaining
+        """
+        with self.conn_maker.make_session() as session:
+            query = session.query(BagTagRecordTable)
+            if vehicle_name:
+                query = query.filter(BagTagRecordTable.vehicle_name == vehicle_name)
+            if bag_name:
+                query = query.filter(BagTagRecordTable.bag_name == bag_name)
+                if begin_offset:
+                    query = query.filter(BagTagRecordTable.end_offset >= begin_offset)
+                if end_offset:
+                    query = query.filter(BagTagRecordTable.begin_offset <= end_offset)
+            if tag_pattern:
+                query = query.filter(BagTagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query = query.filter(
+                        BagTagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query = query.filter(
+                        BagTagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+
+            query.delete()
             session.commit()
 
         return self
@@ -461,6 +719,7 @@ class TagCache(object):
     def clear(self):
         with self.conn_maker.make_session() as session:
             session.execute(sa.delete(TagRecordTable))
+            session.execute(sa.delete(BagTagRecordTable))
             session.commit()
 
     def append_to(self, target_file_path: str, *, overwrite: bool = False):
@@ -479,6 +738,29 @@ class TagCache(object):
     def clone_to(source: "TagCache", target: "TagCache"):
         target.clear()
         with source.conn_maker.make_session() as source_session, target.conn_maker.make_session() as target_session:
-            target_session.add_all([clone_sequence_model_instance(TagRecordTable, db_tag_record, clear_meta_fields=True)
-                                    for db_tag_record in source_session.query(TagRecordTable).all()])
+            target_session.add_all(
+                [clone_sequence_model_instance(TagRecordTable, db_tag_record, clear_meta_fields=True)
+                 for db_tag_record in source_session.query(TagRecordTable).all()],
+            )
+            target_session.add_all(
+                [clone_sequence_model_instance(BagTagRecordTable, db_tag_record, clear_meta_fields=True)
+                 for db_tag_record in source_session.query(BagTagRecordTable).all()],
+            )
             target_session.commit()
+
+
+@memorized
+def tag_cache(identifier: str | None = None) -> TagCache:
+    """
+    Get a ``TagCache`` instance associated with the given identifier. If the identifier is ``None``, return a
+    ``TagCache`` instance associated with a default file path. Otherwise, validate the identifier as a snake case
+    string and return a ``TagCache`` instance associated with a file path derived from the identifier.
+
+    :param identifier: An optional string identifier for the tag cache. If provided, it must be in snake case format
+    and will be used to derive the file path for the tag cache. If not provided, a default file path will be used.
+    :return: A ``TagCache`` instance associated with the specified or default file path.
+    """
+    if identifier is None:
+        return TagCache(file_path=tag_cache_file_path())
+    validate_snake_case(identifier)
+    return TagCache(file_path=tag_cache_file_path().parent / f"{identifier}.db")

{plexus_python_common-1.0.49 → plexus_python_common-1.0.50}/src/plexus_python_common.egg-info/PKG-INFO

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

{plexus_python_common-1.0.49 → plexus_python_common-1.0.50}/test/plexus_tests/common/utils/tagutils_test.py

@@ -55,10 +55,20 @@ class TagUtilsTest(unittest.TestCase):
                 dt_parse_iso("2021-01-01T00:00:00.000000+00:00") + datetime.timedelta(seconds=i + 1),
                 tags[i % len(tags)],
             )
+        for i in range(1000):
+            tag_cache.add_bag_tag(
+                "dummy_vehicle",
+                f"20200101T000000-dummy_vehicle-{i // 100}.bag",
+                i % 100,
+                i % 100 + 1,
+                tags[i % len(tags)],
+            )
 
         self.assertEqual(len(list(tag_cache.query())), 1000)
         self.assertEqual(len(list(tag_cache.query("dummy_vehicle"))), 1000)
         self.assertEqual(len(list(tag_cache.query(tagsets=[tagset]))), 500)
+        self.assertEqual(len(list(tag_cache.query(tagsets=[tagset], tagset_inverted=True))), 500)
+        self.assertEqual(len(list(tag_cache.query(tagsets=[tagset], tagset_inverted=False))), 500)
         self.assertEqual(
             len(list(tag_cache.query("dummy_vehicle",
                                      dt_parse_iso("2020-01-01T00:00:00.000000+00:00"),
@@ -90,15 +100,36 @@ class TagUtilsTest(unittest.TestCase):
         self.assertEqual(len(list(tag_cache.query("dummy_vehicle", tag_pattern="dummy:bar"))), 250)
         self.assertEqual(len(list(tag_cache.query("dummy_vehicle", tag_pattern="dummy"))), 1000)
         self.assertEqual(len(list(tag_cache.query("another_dummy_vehicle"))), 0)
-
-        self.assertEqual(len(list(tag_cache.undefined([tagset]))), 500)
+        self.assertEqual(len(list(tag_cache.query_bag_tag())), 1000)
+        self.assertEqual(len(list(tag_cache.query_bag_tag(tagsets=[tagset]))), 500)
+        self.assertEqual(len(list(tag_cache.query_bag_tag(tagsets=[tagset], tagset_inverted=True))), 500)
+        self.assertEqual(len(list(tag_cache.query_bag_tag(tagsets=[tagset], tagset_inverted=False))), 500)
+        self.assertEqual(len(list(tag_cache.query_bag_tag("dummy_vehicle"))), 1000)
+        self.assertEqual(len(list(tag_cache.query_bag_tag("dummy_vehicle",
+                                                          "20200101T000000-dummy_vehicle-0.bag"))),
+                         100)
+        self.assertEqual(len(list(tag_cache.query_bag_tag("dummy_vehicle",
+                                                          "20200101T000000-dummy_vehicle-0.bag",
+                                                          0,
+                                                          50))),
+                         51)
 
         tag_cache.remove("dummy_vehicle",
                          dt_parse_iso("2020-01-01T00:00:00.000000+00:00"),
                          dt_parse_iso("2020-01-01T00:01:00.000000+00:00"))
+        tag_cache.remove_bag_tag("dummy_vehicle",
+                                 "20200101T000000-dummy_vehicle-0.bag")
 
         self.assertEqual(len(list(tag_cache.query("dummy_vehicle"))), 939)
+        self.assertEqual(len(list(tag_cache.query_bag_tag("dummy_vehicle"))), 900)
+
+        tag_cache.remove(tagsets=[tagset], tagset_inverted=True)
+        tag_cache.remove_bag_tag(tagsets=[tagset], tagset_inverted=True)
+
+        self.assertEqual(len(list(tag_cache.query())), 469)
+        self.assertEqual(len(list(tag_cache.query_bag_tag())), 450)
 
         tag_cache.clear()
 
-        self.assertEqual(len(list(tag_cache.query("dummy_vehicle"))), 0)
+        self.assertEqual(len(list(tag_cache.query())), 0)
+        self.assertEqual(len(list(tag_cache.query_bag_tag())), 0)