plexus-python-common 1.0.72__tar.gz → 1.0.74__tar.gz

{plexus_python_common-1.0.72 → plexus_python_common-1.0.74}/PKG-INFO

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

{plexus_python_common-1.0.72 → plexus_python_common-1.0.74}/src/plexus/common/utils/tagutils.py

@@ -38,6 +38,8 @@ from plexus.common.utils.ormutils import clone_sequence_model_instance, make_bas
 from plexus.common.utils.sqlutils import escape_sql_like
 
 __all__ = [
+    "versioned_identifier",
+    "split_versioned_identifier",
     "RichDesc",
     "Tag",
     "BoundTag",
@@ -60,6 +62,21 @@ __all__ = [
 ]
 
 
+def versioned_identifier(identifier: str | None, version: str | None) -> str | None:
+    if identifier is None or version is None:
+        return identifier
+    return f"{identifier}@{version}"
+
+
+def split_versioned_identifier(s: str | None) -> tuple[str | None, str | None]:
+    if s is None:
+        return None, None
+    if "@" not in s:
+        return s, None
+    identifier, version = s.rsplit("@", 1)
+    return identifier, version
+
+
 @dataclasses.dataclass(frozen=True, eq=True, order=True)
 class RichDesc(object):
     type: str
@@ -84,11 +101,11 @@ class Tag(object):
     def unbind(self) -> Self:
         return self
 
-    def validate(self, props: JsonType | None, *, raise_on_error: bool = False) -> bool:
-        if self.schema is None or props is None:
+    def validate(self, features: JsonType | None, *, raise_on_error: bool = False) -> bool:
+        if self.schema is None or features is None:
             return True
         try:
-            jsonschema.Draft7Validator(self.schema).validate(props)
+            jsonschema.Draft7Validator(self.schema).validate(features)
             return True
         except (jsonschema.ValidationError, jsonschema.SchemaError):
             if raise_on_error:
@@ -178,9 +195,9 @@ class Tagset(Sequence[Tag], Mapping[str, Tag]):
             return []
         return list(dicttree_lineage(self.tags_tree, child.tag_parts[:-1]))
 
-    def validate(self, tag_name: str, props: JsonType | None, *, raise_on_error: bool = False) -> bool:
+    def validate(self, tag_name: str, features: JsonType | None, *, raise_on_error: bool = False) -> bool:
         tag = self.get(tag_name)
-        return False if tag is None else tag.validate(props, raise_on_error=raise_on_error)
+        return False if tag is None else tag.validate(features, raise_on_error=raise_on_error)
 
 
 class MutableTagset(Tagset):
@@ -331,7 +348,7 @@ def predefined_tagsets() -> dict[str, Tagset]:
         else:
             latest_targets[tagset.namespace] = (version, tagset)
 
-        tagsets[f"{tagset.namespace}:{tagset.version}"] = tagset
+        tagsets[versioned_identifier(tagset.namespace, tagset.version)] = tagset
 
     for _, tagset in latest_targets.values():
         tagsets[tagset.namespace] = tagset
@@ -491,6 +508,11 @@ def make_tag_record_model_mixin() -> type[pdt.BaseModel]:
             sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False),
             description="Tag name",
         )
+        features: JsonType | None = Field(
+            sa_column=sa.Column(sa_sqlite.JSON, nullable=True),
+            default=None,
+            description="Tag features in JSON format, which can be used for storing preprocessed information of the tag record to facilitate querying and filtering",
+        )
         props: JsonType | None = Field(
             sa_column=sa.Column(sa_sqlite.JSON, nullable=True),
             default=None,
@@ -592,6 +614,7 @@ if typing.TYPE_CHECKING:
         tagset_namespace: sa_orm.Mapped[str | None] = ...
         tagset_version: sa_orm.Mapped[str | None] = ...
         tag: sa_orm.Mapped[str] = ...
+        features: sa_orm.Mapped[JsonType | None] = ...
         props: sa_orm.Mapped[JsonType | None] = ...
         flags: sa_orm.Mapped[int] = ...
 
@@ -676,7 +699,21 @@ class TagCache(object):
         begin_dt: datetime.datetime,
         end_dt: datetime.datetime,
         props: JsonType | None = None,
-    ) -> TagTargetTable:
+    ) -> Chainable[Self, TagTargetTable]:
+        """
+        Create a new tag target and add it to the cache.
+
+        :param identifier: Identifier of the tag target, which should be unique across the cache. It is recommended
+                           to use a slash tag (e.g. "dummy_name/dummy_name") to ensure uniqueness and facilitate
+                           organization, but other formats are also allowed as long as they are valid slash tags.
+        :param tagger_name: Name of the tagger creating the tag target.
+        :param tagger_version: Version of the tagger creating the tag target.
+        :param vehicle_name: Name of the vehicle associated with the tag target.
+        :param begin_dt: Start datetime for the tag target's validity period.
+        :param end_dt: End datetime for the tag target's validity period.
+        :param props: Additional properties for the tag target.
+        :return: Self instance for chaining along with the added ``TagTargetTable`` instance
+        """
         with self.make_session() as session:
             tag_target = TagTarget(
                 identifier=identifier,
@@ -691,7 +728,7 @@ class TagCache(object):
             session.add(db_tag_target)
             session.commit()
 
-        return self.get_target(identifier)
+        return chainable(self, db_tag_target)
 
     def remove_targets(
         self,
@@ -701,7 +738,23 @@ class TagCache(object):
         vehicle_name: str | None = None,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
+        *,
+        cascade_records: bool = True,
     ):
+        """
+        Remove tag targets from the cache that match the specified filters.
+
+        :param identifier: Filter by target identifier (exact match)
+        :param tagger_name: Filter by tagger name (exact match)
+        :param tagger_version: Filter by tagger version (exact match)
+        :param vehicle_name: Filter by vehicle name (exact match)
+        :param begin_dt: Filter by begin time (inclusive)
+        :param end_dt: Filter by end time (inclusive)
+        :param cascade_records: Whether to also remove tag records that are associated with the removed targets.
+                                If False, the tag records will be kept but become orphaned (i.e. their ``target_sqn``
+                                will not have a corresponding target in the cache).
+        :return: Self for chaining
+        """
         with self.make_session() as session:
             query_stmt = session.query(TagTargetTable)
             if identifier:
@@ -720,13 +773,16 @@ class TagCache(object):
             query_stmt.delete()
             session.commit()
 
-            (
-                session
-                .query(TagRecordTable)
-                .filter(TagRecordTable.target_sqn.notin_(session.query(TagTargetTable.sqn)))
-                .delete()
-            )
-            session.commit()
+            if cascade_records:
+                (
+                    session
+                    .query(TagRecordTable)
+                    .filter(TagRecordTable.target_sqn.notin_(session.query(TagTargetTable.sqn)))
+                    .delete()
+                )
+                session.commit()
+
+            return self
 
     def with_target(self, target: int | str) -> "TargetedTagCache":
         db_tag_target = self.get_target(target)
@@ -1010,6 +1066,7 @@ class TagCache(object):
         begin_dt: datetime.datetime,
         end_dt: datetime.datetime,
         tag: str | Tag | BoundTag,
+        features: JsonType | None = None,
         props: JsonType | None = None,
         tagset_namespace: str | None = None,
         tagset_version: str | None = None,
@@ -1022,6 +1079,8 @@ class TagCache(object):
         :param end_dt: End datetime of the tag record
         :param tag: Tag name or ``Tag``/``BoundTag`` instance to be added. If ``Tag``/``BoundTag`` instance is provided,
                     its name will be used.
+        :param features: Additional tag features of the tag record in JSON format (optional), which can be used for
+                         storing preprocessed information of the tag record to facilitate querying and filtering.
         :param props: Additional properties of the tag record in JSON format (optional)
         :param tagset_namespace: Namespace of the tagset that the tag belongs to. If the ``tag`` parameter is a
                                  ``BoundTag`` instance, this parameter will be ignored and the namespace from the
@@ -1038,6 +1097,7 @@ class TagCache(object):
                 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,
+                features=features,
                 props=props,
             )
             db_tag_record = clone_sequence_model_instance(TagRecordTable, tag_record)
@@ -1054,6 +1114,7 @@ class TagCache(object):
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
         tag: str | Tag | BoundTag | None = None,
+        features: JsonType | None = None,
         props: JsonType | None = None,
         tagset_namespace: str | None = None,
         tagset_version: str | None = None,
@@ -1068,6 +1129,8 @@ class TagCache(object):
         :param end_dt: New end datetime of the tag record (optional)
         :param tag: New tag name or ``Tag``/``BoundTag`` instance to be updated (optional). If ``Tag``/``BoundTag``
                     instance is provided, its name will be used.
+        :param features: Additional tag features of the tag record in JSON format (optional), which can be used for
+                         storing preprocessed information of the tag record to facilitate querying and filtering.
         :param props: New additional properties of the tag record in JSON format (optional)
         :param tagset_namespace: New namespace of the tagset that the tag belongs to (optional). If the ``tag``
                                  parameter is a ``BoundTag`` instance, this parameter will be ignored and the namespace
@@ -1098,6 +1161,8 @@ class TagCache(object):
                 db_tag_record.tagset_version = tag.version if isinstance(tag, BoundTag) else tagset_version
             if tag is not None:
                 db_tag_record.tag = tag.name if isinstance(tag, Tag) else tag
+            if features is not None:
+                db_tag_record.features = features
             if props is not None:
                 db_tag_record.props = props
             if flags is not None:
@@ -1251,31 +1316,17 @@ class TargetedTagCache(object):
         begin_dt: datetime.datetime | None,
         end_dt: datetime.datetime | None,
         tag: str | Tag | BoundTag,
+        features: JsonType | None = None,
         props: JsonType | None = None,
         tagset_namespace: str | None = None,
         tagset_version: str | None = None,
     ) -> Chainable[Self, TagRecordTable]:
-        """
-        Add a tag record to the cache for the specified time range. If ``begin_dt`` or ``end_dt`` is None, it will
-        default to the target's ``begin_dt`` or ``end_dt`` respectively.
-
-        :param begin_dt: Begin datetime of the tag record
-        :param end_dt: End datetime of the tag record
-        :param tag: Tag name or ``Tag``/``BoundTag`` instance to be added. If ``Tag``/``BoundTag`` instance is provided,
-                    its name will be used.
-        :param props: Additional properties of the tag record in JSON format (optional)
-        :param tagset_namespace: Namespace of the tagset that the tag belongs to. If the ``tag`` parameter is a
-                                 ``BoundTag`` instance, this parameter will be ignored and the namespace from the
-                                 instance will be used.
-        :param tagset_version: Version of the tagset that the tag belongs to. If the ``tag`` parameter is a ``BoundTag``
-                               instance, this parameter will be ignored and the version from the instance will be used.
-        :return: Self instance for chaining along with the added ``TagRecordTable`` instance
-        """
         result = self.cache.target_add_record(
             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,
             tag=tag,
+            features=features,
             props=props,
             tagset_namespace=tagset_namespace,
             tagset_version=tagset_version,
@@ -1285,28 +1336,16 @@ class TargetedTagCache(object):
     def add_record(
         self,
         tag: str | Tag | BoundTag,
+        features: JsonType | None = None,
         props: JsonType | None = None,
         tagset_namespace: str | None = None,
         tagset_version: str | None = None,
     ) -> Chainable[Self, TagRecordTable]:
-        """
-        Add a tag record to the cache for the entire target range.
-
-        :param tag: Tag name or ``Tag``/``BoundTag`` instance to be added. If ``Tag``/``BoundTag`` instance is provided,
-                    its name will be used.
-        :param props: Additional properties of the tag record in JSON format (optional)
-        :param tagset_namespace: Namespace of the tagset that the tag belongs to. If the ``tag`` parameter is a
-                                 ``BoundTag`` instance, this parameter will be ignored and the namespace from the
-                                 instance will be used.
-        :param tagset_version: Version of the tagset that the tag belongs to. If the ``tag`` parameter is a
-                               ``BoundTag`` instance, this parameter will be ignored and the version from the instance
-                               will be used.
-        :return: Self instance for chaining along with the added ``TagRecordTable`` instance
-        """
         result = self.add_ranged_record(
             begin_dt=self.tag_target.begin_dt,
             end_dt=self.tag_target.end_dt,
             tag=tag,
+            features=features,
             tagset_namespace=tagset_namespace,
             tagset_version=tagset_version,
             props=props,
@@ -1320,35 +1359,19 @@ class TargetedTagCache(object):
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
         tag: str | Tag | BoundTag | None = None,
+        features: JsonType | None = None,
         props: JsonType | None = None,
         tagset_namespace: str | None = None,
         tagset_version: str | None = None,
         flags: int | None = None,
     ) -> Chainable[Self, TagRecordTable]:
-        """
-        Update a tag record in the cache by its sequence number.
-
-        :param sqn: Sequence number of the tag record to be updated
-        :param begin_dt: New begin datetime of the tag record (optional)
-        :param end_dt: New end datetime of the tag record (optional)
-        :param tag: New tag name or ``Tag``/``BoundTag`` instance to be updated (optional). If ``Tag``/``BoundTag``
-                    instance is provided, its name will be used.
-        :param props: New additional properties of the tag record in JSON format (optional)
-        :param tagset_namespace: New namespace of the tagset that the tag belongs to (optional). If the ``tag``
-                                 parameter is a ``BoundTag`` instance, this parameter will be ignored and the namespace
-                                 from the instance will be used.
-        :param tagset_version: New version of the tagset that the tag belongs to (optional). If the ``tag`` parameter
-                               is a ``BoundTag`` instance, this parameter will be ignored and the version from the
-                               instance will be used.
-        :param flags: New integer bitmask storing status or metadata flags for this tag record (optional)
-        :return: Self instance for chaining along with the updated ``TagRecordTable`` instance
-        """
         result = self.cache.target_update_record(
             self.tag_target.sqn,
             sqn,
             begin_dt=begin_dt,
             end_dt=end_dt,
             tag=tag,
+            features=features,
             props=props,
             tagset_namespace=tagset_namespace,
             tagset_version=tagset_version,
@@ -1367,19 +1390,6 @@ class TargetedTagCache(object):
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
     ) -> Self:
-        """
-        Remove tag records from the cache that match the specified filters.
-
-        :param begin_dt: Filter by begin time (inclusive)
-        :param end_dt: Filter by end time (inclusive)
-        :param tagset_namespace: Filter by tagset namespace (exact match)
-        :param tagset_version: Filter by tagset version (exact match)
-        :param tag_prefix: Filter by tag name prefix, 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
-        """
         self.cache.target_remove_records(
             self.tag_target.sqn,
             begin_dt=begin_dt,

{plexus_python_common-1.0.72 → plexus_python_common-1.0.74}/src/plexus_python_common.egg-info/PKG-INFO

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

{plexus_python_common-1.0.72 → plexus_python_common-1.0.74}/test/plexus_tests/common/utils/tagutils_test.py

@@ -13,6 +13,7 @@ from plexus.common.utils.tagutils import MutableTagset, Tag, TagCache, Tagset
 from plexus.common.utils.tagutils import populate_clip_ranges
 from plexus.common.utils.tagutils import predefined_tagsets, render_tagset_markdown_readme
 from plexus.common.utils.tagutils import tag_cache_file_path
+from plexus.common.utils.tagutils import versioned_identifier
 
 
 @ddt.ddt
@@ -46,7 +47,8 @@ class TagUtilsTest(unittest.TestCase):
 
             print(markdown)
 
-        self.assertEqual(predefined_tagsets().get("unittest"), predefined_tagsets().get("unittest:1.0.0"))
+        self.assertEqual(predefined_tagsets().get("unittest"),
+                         predefined_tagsets().get(versioned_identifier("unittest", "1.0.0")))
 
     data_tag_validate = [
         ("level_1_tag", {"dummy_property": "dummy_value"}, True,),
@@ -86,15 +88,15 @@ class TagUtilsTest(unittest.TestCase):
 
     @ddt.idata(data_tag_validate)
     @ddt.unpack
-    def test_tagset_validate(self, tag: str, props: JsonObject, should_pass: bool):
+    def test_tagset_validate(self, tag: str, features: JsonObject, should_pass: bool):
         tagset = predefined_tagsets().get("unittest")
 
         if should_pass:
-            self.assertTrue(tagset.validate(tag, props))
+            self.assertTrue(tagset.validate(tag, features))
         else:
-            self.assertFalse(tagset.validate(tag, props))
+            self.assertFalse(tagset.validate(tag, features))
             with self.assertRaises(Exception):
-                tagset.validate(tag, props, raise_on_error=True)
+                tagset.validate(tag, features, raise_on_error=True)
 
     def test_tag_cache(self):
         tag_names = [
@@ -122,7 +124,7 @@ class TagUtilsTest(unittest.TestCase):
                          "dummy_vehicle",
                          dt_parse_iso("2020-01-01T00:00:00+00:00"),
                          dt_parse_iso("2020-01-01T01:00:00+00:00"),
-                         {"dummy_target_prop": "dummy_value"})
+                         props={"dummy_target_prop": "dummy_value"})
 
         target_cache = cache.with_target("awesome_tagger/20200101_000000/dummy_vehicle/0")
 
@@ -135,7 +137,7 @@ class TagUtilsTest(unittest.TestCase):
                 dt_parse_iso("2020-01-01T00:00:00+00:00") + datetime.timedelta(seconds=i),
                 dt_parse_iso("2020-01-02T00:00:00+00:00") + datetime.timedelta(seconds=i + 1),
                 tag,
-                props={
+                features={
                     "dummy_int": 1,
                     "dummy_float": 1.0e-1,
                     "dummy_bool": True,
@@ -148,6 +150,7 @@ class TagUtilsTest(unittest.TestCase):
                         "dummy_str": "dummy_string",
                     },
                 },
+                props={"dummy_record_prop": "dummy_value"},
             )
 
         self.assertEqual(target_cache.count_records(), tag_records_count)
@@ -277,7 +280,7 @@ class TagUtilsTest(unittest.TestCase):
                                  "dummy_vehicle",
                                  dt_parse_iso("2020-01-01T00:00:00+00:00"),
                                  dt_parse_iso("2020-01-01T01:00:00+00:00"),
-                                 {"dummy_target_prop": "dummy_value"})
+                                 props={"dummy_target_prop": "dummy_value"})
 
             target_caches = [cache.with_target(f"concurrent_tagger/20200101_000000/dummy_vehicle/{i}")
                              for i in range(target_caches_count)]
@@ -301,7 +304,7 @@ class TagUtilsTest(unittest.TestCase):
                         dt_parse_iso("2020-01-01T00:00:00+00:00") + datetime.timedelta(seconds=i),
                         dt_parse_iso("2020-01-02T00:00:00+00:00") + datetime.timedelta(seconds=i + 1),
                         tag,
-                        props={
+                        features={
                             "dummy_int": 1,
                             "dummy_float": 1.0e-1,
                             "dummy_bool": True,
@@ -314,6 +317,7 @@ class TagUtilsTest(unittest.TestCase):
                                 "dummy_str": "dummy_string",
                             },
                         },
+                        props={"dummy_record_prop": "dummy_value"},
                     )
 
             threads = [threading.Thread(target=worker, args=(tid,)) for tid in range(total_threads_count)]