plexus-python-common 1.0.72__py3-none-any.whl → 1.0.74__py3-none-any.whl

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.dist-info → plexus_python_common-1.0.74.dist-info}/METADATA

@@ -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.dist-info → plexus_python_common-1.0.74.dist-info}/RECORD

@@ -21,9 +21,9 @@ plexus/common/utils/pathutils.py,sha256=hGJqSLj08tuOeZ7WeC5d4BtjnPI732BuntVQBQsq
 plexus/common/utils/s3utils.py,sha256=zlO4kGs-c2gUeOfPfiKIE5liQZsbYxqAZYCwA8kL0Lo,36017
 plexus/common/utils/sqlutils.py,sha256=D6kTBjhO5YlNRt3uFlPt6z3uH61m9ajEzPYmsI6NoFc,231
 plexus/common/utils/strutils.py,sha256=O9Inv4ffUTf6Xjc5ftoZwbIua1NeG7itCT9S3zjZxBc,16436
-plexus/common/utils/tagutils.py,sha256=U5JGeMl9MHXthauk89MWzxNeDZ665S28uaJVfcndolU,62213
+plexus/common/utils/tagutils.py,sha256=4r-g4JQ_zmJI4ttJHvlKq-iQuqA6GSPb3PQwaJfnBkg,61632
 plexus/common/utils/testutils.py,sha256=N8ijLu7X-hlQlHzvv0TtSsQpIF4T1hbr-AjkILoV2Ac,6152
-plexus_python_common-1.0.72.dist-info/METADATA,sha256=a6Gp00ANkZ9HsHTIIiTXzLkX0pGKcV0fJbtheMKb-GA,1481
-plexus_python_common-1.0.72.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-plexus_python_common-1.0.72.dist-info/top_level.txt,sha256=ug_g7CVwaMQuas5UzAXbHUrQvKGCn8ezc6ZNvvRlJOE,7
-plexus_python_common-1.0.72.dist-info/RECORD,,
+plexus_python_common-1.0.74.dist-info/METADATA,sha256=2RyK_d-GgT_5C4ojTgb5ONTTE0Oi11FB7Mz1Ub7ssyo,1481
+plexus_python_common-1.0.74.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+plexus_python_common-1.0.74.dist-info/top_level.txt,sha256=ug_g7CVwaMQuas5UzAXbHUrQvKGCn8ezc6ZNvvRlJOE,7
+plexus_python_common-1.0.74.dist-info/RECORD,,