plexus-python-common 1.0.56__tar.gz → 1.0.57__tar.gz

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/PKG-INFO

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

plexus_python_common-1.0.56/src/plexus/common/resources/tags/unittest.tagset.yaml → plexus_python_common-1.0.57/src/plexus/common/resources/tags/unittest-1.0.0.tagset.yaml

@@ -1,4 +1,5 @@
 $namespace: "unittest"
+$version: "1.0.0"
 # language=markdown
 $desc: !markdown |
   **Unit Test Tagset**

plexus_python_common-1.0.56/src/plexus/common/resources/tags/universal.tagset.yaml → plexus_python_common-1.0.57/src/plexus/common/resources/tags/universal-1.0.0.tagset.yaml

@@ -1,4 +1,5 @@
 $namespace: "universal"
+$version: "1.0.0"
 # language=markdown
 $desc: !markdown |
   **Universal Tagset**

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/src/plexus/common/utils/bagutils.py

@@ -217,9 +217,9 @@ class BagWriter(AbstractContextManager, BagIOBase):
 
         :param bag_file_path: path to the SQLite DB file to create.
         :param overwrite: whether to overwrite the SQLite DB file if it already exists. If False and the file already
-        exists, a FileExistsError is raised. If True, the existing file is deleted and a new one is created.
+          exists, a FileExistsError is raised. If True, the existing file is deleted and a new one is created.
         :param exist_ok: whether to ignore if the SQLite DB file already exists. If False and the file already exists,
-        a FileExistsError is raised. If True, the existing file is used and no new file is created.
+          a FileExistsError is raised. If True, the existing file is used and no new file is created.
         """
         super().__init__(bag_file_path)
 

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/src/plexus/common/utils/ormutils.py

@@ -267,6 +267,7 @@ class ChangingModelMixinProtocol(SequenceModelMixinProtocol):
     def make_index_created_at(cls, index_name: str) -> sa.Index:
         """
         Helper to create an index on the ``created_at`` field with the given index name.
+
         :param index_name: Name of the index to create.
         :return: The created SQLAlchemy Index object.
         """
@@ -282,6 +283,7 @@ class SnapshotModelMixinProtocol(SequenceModelMixinProtocol):
     def make_index_created_at_expired_at(cls, index_name: str) -> sa.Index:
         """
         Helper to create an index on the ``created_at`` and ``expired_at`` fields with the given index name.
+
         :param index_name: Name of the index to create.
         :return: The created SQLAlchemy Index object.
         """
@@ -292,6 +294,7 @@ class SnapshotModelMixinProtocol(SequenceModelMixinProtocol):
         """
         Helper to create a unique index on the ``record_sqn`` field for active records (where ``expired_at`` is NULL).
         This ensures that there is only one active snapshot per record at any given time.
+
         :param index_name: Name of the index to create.
         :return: The created SQLAlchemy Index object.
         """
@@ -302,6 +305,7 @@ class SnapshotModelMixinProtocol(SequenceModelMixinProtocol):
         """
         Helper to create a non-unique index on the specified fields for active records (where ``expired_at`` is NULL).
         This allows efficient querying of active snapshots based on the specified fields.
+
         :param index_name: Name of the index to create.
         :param fields: Fields to include in the index.
         :return: The created SQLAlchemy Index object.
@@ -314,6 +318,7 @@ class SnapshotModelMixinProtocol(SequenceModelMixinProtocol):
         Helper to create a unique index on the specified fields for active records (where ``expired_at`` is NULL).
         This ensures that there is only one active snapshot per combination of the specified fields at any given
         time.
+
         :param index_name: Name of the index to create.
         :param fields: Fields to include in the unique index.
         :return: The created SQLAlchemy Index object.
@@ -333,6 +338,7 @@ class RevisionModelMixinProtocol(SequenceModelMixinProtocol):
         """
         Helper to create an index on the ``created_at``, ``updated_at``, and ``expired_at`` fields with the given
         index name.
+
         :param index_name: Name of the index to create.
         :return: The created SQLAlchemy Index object.
         """
@@ -343,6 +349,7 @@ class RevisionModelMixinProtocol(SequenceModelMixinProtocol):
         """
         Helper to create a unique index on the ``record_sqn`` and ``revision`` fields.
         This ensures that each revision number is unique per record.
+
         :param index_name: Name of the index to create.
         :return: The created SQLAlchemy Index object.
         """
@@ -353,6 +360,7 @@ class RevisionModelMixinProtocol(SequenceModelMixinProtocol):
         """
         Helper to create a unique index on the ``record_sqn`` field for active records (where ``expired_at`` is NULL).
         This ensures that there is only one active revision per record at any given time.
+
         :param index_name: Name of the index to create.
         :return: The created SQLAlchemy Index object.
         """
@@ -363,6 +371,7 @@ class RevisionModelMixinProtocol(SequenceModelMixinProtocol):
         """
         Helper to create a non-unique index on the specified fields for active records (where ``expired_at`` is NULL).
         This allows efficient querying of active revisions based on the specified fields.
+
         :param index_name: Name of the index to create.
         :param fields: Fields to include in the index.
         :return: The created SQLAlchemy Index object.
@@ -375,6 +384,7 @@ class RevisionModelMixinProtocol(SequenceModelMixinProtocol):
         Helper to create a unique index on the specified fields for active records (where ``expired_at`` is NULL).
         This ensures that there is only one active revision per combination of the specified fields at any given
         time.
+
         :param index_name: Name of the index to create.
         :param fields: Fields to include in the unique index.
         :return: The created SQLAlchemy Index object.
@@ -465,7 +475,7 @@ def make_changing_model_mixin(dialect: str | None = None) -> type[ChangingModelM
 
     :param dialect: The database dialect to determine the column types for the fields.
     :return: A mixin class that can be used with SQLModel models to add the common fields and validation logic for
-    updatable records.
+             updatable records.
     """
 
     class ModelMixin(SQLModel):
@@ -527,7 +537,7 @@ def make_snapshot_model_mixin(dialect: str | None = None) -> type[SnapshotModelM
 
     :param dialect: The database dialect to determine the column types for the fields.
     :return: A mixin class that can be used with SQLModel models to add the common fields and validation logic for
-    record snapshots.
+             record snapshots.
     """
 
     class ModelMixin(SQLModel):
@@ -622,7 +632,7 @@ def make_revision_model_mixin(dialect: str | None = None) -> type[RevisionModelM
 
     :param dialect: The database dialect to determine the column types for the fields.
     :return: A mixin class that can be used with SQLModel models to add the common fields and validation logic for
-    record revisions.
+             record revisions.
     """
 
     class ModelMixin(SQLModel):

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/src/plexus/common/utils/s3utils.py

@@ -549,15 +549,16 @@ def s3_archive_member_tree(
     Directory members are recognized by names ending with a trailing slash ("/").
 
     Example:
-    {
-      "dir1/": (ZipInfo, {
-          "file1.txt": (ZipInfo, None),
-          "subdir/": (ZipInfo, {
-              "file2.txt": (ZipInfo, None)
-          })
-      }),
-      "file3.txt": (ZipInfo, None)
-    }
+
+    >>> {
+    ...   "dir1/": (ZipInfo, {
+    ...       "file1.txt": (ZipInfo, None),
+    ...       "subdir/": (ZipInfo, {
+    ...           "file2.txt": (ZipInfo, None)
+    ...       })
+    ...   }),
+    ...   "file3.txt": (ZipInfo, None)
+    ... }
 
     :param client: An instance of ``S3Client``.
     :param bucket: Bucket name.
@@ -602,7 +603,9 @@ def s3_archive_list_files(
     under that directory will be included in the results.
 
     Example usage:
-    >>> archive_size, member_zip_infos, missed_members = s3_archive_list_files(client, bucket, key, members=["file1.txt", "dir1/"])
+
+    >>> archive_size, member_zip_infos, missed_members = s3_archive_list_files(
+    ...         client, bucket, key, members=["file1.txt", "dir1/"])
     >>> for info in member_zip_infos:
     ...     print(info.filename, info.file_size)
     >>> if missed_members:

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/src/plexus/common/utils/tagutils.py

@@ -71,6 +71,9 @@ class Tag(object):
     def parent_tag_name(self) -> str | None:
         return head_or_none(self.name.rsplit(":", 1))
 
+    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:
             return True
@@ -83,18 +86,30 @@ class Tag(object):
             return False
 
 
+@dataclasses.dataclass(frozen=True, eq=True, order=True)
+class BoundTag(Tag):
+    namespace: str | None = None
+    version: str | None = None
+
+    def unbind(self) -> Tag:
+        return Tag(name=self.name, desc=self.desc, schema=self.schema)
+
+
 class Tagset(Sequence[Tag], Mapping[str, Tag]):
-    def __init__(self, namespace: str, desc: str | RichDesc) -> None:
+    def __init__(self, namespace: str, version: str, desc: str | RichDesc) -> None:
         super().__init__()
         self.namespace = namespace
+        self.version = version
         self.desc = desc
         self.tags: list[Tag] = []
         self.tags_dict: dict[str, Tag] = {}
         self.tags_tree: dicttree[str, Tag] = {}
 
-    def __contains__(self, item: str | Tag) -> bool:
-        tag_name = item.name if isinstance(item, Tag) else item
-        return tag_name in self.tags_dict
+    def __contains__(self, item: str | Tag | BoundTag | None) -> bool:
+        try:
+            return self.get(item) is not None
+        except ValueError:
+            return False
 
     def __len__(self) -> int:
         return len(self.tags)
@@ -111,10 +126,22 @@ class Tagset(Sequence[Tag], Mapping[str, Tag]):
     def items(self):
         return self.tags_dict.items()
 
-    def get(self, item: str | Tag) -> Tag | None:
+    def get(self, item: str | Tag | BoundTag) -> Tag | None:
+        if item is None:
+            return None
+        if isinstance(item, BoundTag):
+            if item.namespace != self.namespace or item.version != self.version:
+                raise ValueError(f"tag bind '{item}' does not belong to this tagset")
         tag_name = item.name if isinstance(item, Tag) else item
         return self.tags_dict.get(tag_name)
 
+    def bind(self, tag: Tag) -> BoundTag:
+        return BoundTag(tag.name, tag.desc, tag.schema, self.namespace, self.version)
+
+    def get_bound(self, item: str | Tag | BoundTag) -> BoundTag | None:
+        tag = self.get(item)
+        return None if tag is None else self.bind(tag)
+
     def clone(self) -> Self:
         return clone_tagset(self)
 
@@ -128,22 +155,18 @@ class Tagset(Sequence[Tag], Mapping[str, Tag]):
     def tag_names(self) -> list[str]:
         return list(self.tags_dict.keys())
 
-    def child_tags(self, parent: str | Tag) -> list[Tag]:
+    def child_tags(self, parent: str | Tag | BoundTag) -> list[BoundTag]:
+        parent = self.get(parent)
         if parent is None:
             return []
-        if isinstance(parent, str):
-            return self.child_tags(self.get(parent))
-
         subtree = dicttree_subtree(self.tags_tree, parent.tag_parts)
-        return list(dicttree_children(subtree)) if subtree else []
+        return list(self.bind(tag) for tag in dicttree_children(subtree)) if subtree else []
 
-    def parent_tags(self, child: str | Tag) -> list[Tag]:
+    def parent_tags(self, child: str | Tag | BoundTag) -> list[BoundTag]:
+        child = self.get(child)
         if child is None:
             return []
-        if isinstance(child, str):
-            return self.parent_tags(self.get(child))
-
-        return list(dicttree_lineage(self.tags_tree, child.tag_parts[:-1]))
+        return list(self.bind(tag) for tag in dicttree_lineage(self.tags_tree, child.tag_parts[:-1]))
 
     def validate(self, tag_name: str, props: JsonType | None, *, raise_on_error: bool = False) -> bool:
         tag = self.get(tag_name)
@@ -161,9 +184,14 @@ class MutableTagset(Tagset):
     def frozen(self):
         return clone_tagset(self)
 
-    def add(self, tag: Tag) -> Self:
+    def add(self, tag: Tag | BoundTag) -> Self:
         if tag.name in self.tags_dict:
             raise ValueError(f"duplicate tag name '{tag.name}'")
+        if isinstance(tag, BoundTag):
+            if tag.namespace != self.namespace or tag.version != self.version:
+                raise ValueError(f"tag bind '{tag}' does not belong to this tagset")
+
+        tag = tag.unbind()
 
         self.tags.append(tag)
         self.tags_dict[tag.name] = tag
@@ -187,7 +215,7 @@ class MutableTagset(Tagset):
 
 def clone_tagset(tagset: Tagset) -> Tagset:
     tagset = clone_mutable_tagset(tagset)
-    new_tagset = Tagset(namespace=tagset.namespace, desc=tagset.desc)
+    new_tagset = Tagset(namespace=tagset.namespace, version=tagset.version, desc=tagset.desc)
     new_tagset.tags = tagset.tags
     new_tagset.tags_dict = tagset.tags_dict
     new_tagset.tags_tree = tagset.tags_tree
@@ -195,7 +223,7 @@ def clone_tagset(tagset: Tagset) -> Tagset:
 
 
 def clone_mutable_tagset(tagset: Tagset) -> MutableTagset:
-    new_tagset = MutableTagset(namespace=tagset.namespace, desc=tagset.desc)
+    new_tagset = MutableTagset(namespace=tagset.namespace, version=tagset.version, desc=tagset.desc)
     for tag in tagset.tags:
         new_tagset.add(tag)
     return new_tagset
@@ -250,6 +278,14 @@ def populate_tagset(tagset_spec: JsonObject) -> Tagset:
     except ValueError as e:
         raise ValueError(f"tagset namespace '{namespace}' is not in snake case") from e
 
+    version = tagset_spec.get("$version")
+    if version is None:
+        raise ValueError("missing '$version' in tagset spec")
+    try:
+        validate_semver(version)
+    except ValueError as e:
+        raise ValueError(f"tagset version '{version}' is not a valid semantic version") from e
+
     desc = tagset_spec.get("$desc")
     if desc is None:
         raise ValueError("missing '$desc' in tagset spec")
@@ -260,7 +296,7 @@ def populate_tagset(tagset_spec: JsonObject) -> Tagset:
     if tags is None:
         raise ValueError("missing '$tags' in tagset spec")
 
-    tagset = MutableTagset(namespace=namespace, desc=desc)
+    tagset = MutableTagset(namespace=namespace, version=version, desc=desc)
 
     for tag in validate_and_collect("", tags):
         tagset.add(tag)
@@ -270,10 +306,26 @@ def populate_tagset(tagset_spec: JsonObject) -> Tagset:
 
 @singleton
 def predefined_tagsets() -> dict[str, Tagset]:
+    from packaging.version import Version
+
     tagsets: dict[str, Tagset] = {}
+    latest_targets: dict[str, tuple[Version, Tagset]] = {}
+
     for _, tagset_spec in predefined_tagset_specs():
         tagset = populate_tagset(tagset_spec)
+        version = Version(tagset.version)
+        if tagset.namespace in latest_targets:
+            latest_version, _ = latest_targets[tagset.namespace]
+            if version > latest_version:
+                latest_targets[tagset.namespace] = (version, tagset)
+        else:
+            latest_targets[tagset.namespace] = (version, tagset)
+
+        tagsets[f"{tagset.namespace}:{tagset.version}"] = tagset
+
+    for _, tagset in latest_targets.values():
         tagsets[tagset.namespace] = tagset
+
     return tagsets
 
 
@@ -289,7 +341,7 @@ def render_tagset_markdown_readme(tagset: Tagset) -> str:
 
     template_str = textwrap.dedent(
         """
-        # Tagset {{ tagset.namespace }}
+        # Tagset {{ tagset.namespace }} (Version {{ tagset.version }})
 
         {{ tagset.desc | render_desc }}
 
@@ -401,6 +453,16 @@ class TagRecord(BaseModel):
         sa_column=sa.Column(sa_sqlite.TIMESTAMP, nullable=False),
         description="End datetime of the tag record",
     )
+    tagset_namespace: str | None = Field(
+        sa_column=sa.Column(sa_sqlite.VARCHAR(128), nullable=True),
+        default=None,
+        description="Namespace of the tagset that the tag belongs to",
+    )
+    tagset_version: str | None = Field(
+        sa_column=sa.Column(sa_sqlite.VARCHAR(64), nullable=True),
+        default=None,
+        description="Version of the tagset that the tag belongs to",
+    )
     tag: str = Field(
         sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False),
         description="Tag name",
@@ -423,6 +485,20 @@ class TagRecord(BaseModel):
         validate_dt_timezone(v, allow_naive=True)
         return v
 
+    @pdt.field_validator("tagset_namespace", mode="after")
+    @classmethod
+    def validate_tagset_namespace(cls, v: str | None) -> str | None:
+        if v is not None:
+            validate_snake_case(v)
+        return v
+
+    @pdt.field_validator("tagset_version", mode="after")
+    @classmethod
+    def validate_tagset_version(cls, v: str | None) -> str | None:
+        if v is not None:
+            validate_semver(v)
+        return v
+
     @pdt.model_validator(mode="after")
     def validate_begin_dt_end_dt(self) -> Self:
         if self.begin_dt > self.end_dt:
@@ -458,6 +534,8 @@ if typing.TYPE_CHECKING:
         target_sqn: sa_orm.Mapped[int] = ...
         begin_dt: sa_orm.Mapped[datetime.datetime] = ...
         end_dt: sa_orm.Mapped[datetime.datetime] = ...
+        tagset_namespace: sa_orm.Mapped[str | None] = ...
+        tagset_version: sa_orm.Mapped[str | None] = ...
         tag: sa_orm.Mapped[str] = ...
         props: sa_orm.Mapped[JsonType | None] = ...
 
@@ -591,7 +669,9 @@ class TagCache(object):
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
-        tag_pattern: str | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
         *,
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
@@ -602,11 +682,12 @@ class TagCache(object):
 
         :param begin_dt: Filter by begin time (inclusive)
         :param end_dt: 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 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)
+          tagsets)
         :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
         """
@@ -616,8 +697,12 @@ class TagCache(object):
                 query = query.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
                 query = query.filter(TagRecordTable.begin_dt <= end_dt)
-            if tag_pattern:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagset_namespace:
+                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
                     query = query.filter(
@@ -633,7 +718,9 @@ class TagCache(object):
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
-        tag_pattern: str | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
         *,
         target_identifier: str | None = None,
         target_tagger_name: str | None = None,
@@ -650,8 +737,9 @@ class TagCache(object):
 
         :param begin_dt: Filter by begin time (inclusive)
         :param end_dt: 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 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 target_identifier: Filter by target identifier (exact match)
         :param target_tagger_name: Filter by target tagger name (exact match)
         :param target_tagger_version: Filter by target tagger version (exact match)
@@ -660,7 +748,7 @@ class TagCache(object):
         :param target_end_dt: Filter by target end time (inclusive)
         :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)
+          tagsets)
         :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
         """
@@ -674,8 +762,12 @@ class TagCache(object):
                 query = query.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
                 query = query.filter(TagRecordTable.begin_dt <= end_dt)
-            if tag_pattern:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagset_namespace:
+                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if target_identifier:
                 query = query.filter(TagTargetTable.identifier == target_identifier)
             if target_tagger_name:
@@ -703,7 +795,9 @@ class TagCache(object):
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
-        tag_pattern: str | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
         *,
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
@@ -713,11 +807,12 @@ class TagCache(object):
 
         :param begin_dt: Filter by begin time (inclusive)
         :param end_dt: 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 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)
+          tagsets)
         """
         with self.make_session() as session:
             query = session.query(TagRecordTable)
@@ -725,8 +820,12 @@ class TagCache(object):
                 query = query.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
                 query = query.filter(TagRecordTable.begin_dt <= end_dt)
-            if tag_pattern:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagset_namespace:
+                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
                     query = query.filter(
@@ -803,7 +902,9 @@ class TargetedTagCache(object):
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
-        tag_pattern: str | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
         *,
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
@@ -814,11 +915,12 @@ class TargetedTagCache(object):
 
         :param begin_dt: Filter by begin time (inclusive)
         :param end_dt: 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 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)
+          tagsets)
         :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
         """
@@ -829,8 +931,12 @@ class TargetedTagCache(object):
                 query = query.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
                 query = query.filter(TagRecordTable.begin_dt <= end_dt)
-            if tag_pattern:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagset_namespace:
+                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
                     query = query.filter(
@@ -846,17 +952,24 @@ class TargetedTagCache(object):
         self,
         begin_dt: datetime.datetime | None,
         end_dt: datetime.datetime | None,
-        tag: str | Tag,
+        tag: str | Tag | BoundTag,
         props: JsonType | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
     ) -> Self:
         """
-        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.
+        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 instance to be added (if Tag instance is provided, its name will be used)
+        :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
         """
         with self.make_session() as session:
@@ -864,6 +977,8 @@ class TargetedTagCache(object):
                 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,
+                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,
                 props=props,
             )
@@ -872,18 +987,31 @@ class TargetedTagCache(object):
 
         return self
 
-    def add_tag(self, tag: str | Tag, props: JsonType | None = None) -> Self:
+    def add_tag(
+        self,
+        tag: str | Tag | BoundTag,
+        props: JsonType | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+    ) -> Self:
         """
         Add a tag record to the cache for the entire target range.
 
-        :param tag: Tag name or Tag instance to be added (if Tag instance is provided, its name will be used)
+        :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
         """
         return self.add_ranged_tag(
             begin_dt=self.target_info.begin_dt,
             end_dt=self.target_info.end_dt,
             tag=tag,
+            tagset_namespace=tagset_namespace,
+            tagset_version=tagset_version,
             props=props,
         )
 
@@ -891,7 +1019,9 @@ class TargetedTagCache(object):
         self,
         begin_dt: datetime.datetime | None = None,
         end_dt: datetime.datetime | None = None,
-        tag_pattern: str | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
         *,
         tagsets: Sequence[Tagset] | None = None,
         tagset_inverted: bool = False,
@@ -901,11 +1031,12 @@ class TargetedTagCache(object):
 
         :param begin_dt: Filter by begin time (inclusive)
         :param end_dt: 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 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)
+          tagsets)
         :return: Self instance for chaining
         """
         with self.make_session() as session:
@@ -914,8 +1045,12 @@ class TargetedTagCache(object):
                 query = query.filter(TagRecordTable.end_dt >= begin_dt)
             if end_dt:
                 query = query.filter(TagRecordTable.begin_dt <= end_dt)
-            if tag_pattern:
-                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_pattern)}%", escape="\\"))
+            if tagset_namespace:
+                query = query.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query = query.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query = query.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
             if tagsets:
                 if tagset_inverted:
                     query = query.filter(
@@ -938,10 +1073,10 @@ def tag_cache(*, identifier: str | None = None, file_path: str | None = None) ->
     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.
+      and will be used to derive the file path for the tag cache. If not provided, a default file path will be used.
     :param file_path: An optional file path for the tag cache. If provided, it will be used directly. If not provided,
-    the file path will be derived from the identifier if it is provided, or a default file path will be used if the
-    identifier is not provided. Note that both 'identifier' and 'file_path' cannot be specified at the same time.
+      the file path will be derived from the identifier if it is provided, or a default file path will be used if the
+      identifier is not provided. Note that both 'identifier' and 'file_path' cannot be specified at the same time.
     :return: A ``TagCache`` instance associated with the specified or default file path.
     """
     if identifier is not None and file_path is not None:

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/src/plexus/common/utils/testutils.py

@@ -80,7 +80,6 @@ def patched_value_factory[T](
 
     :param app: FastAPI application instance.
     :param value_factory: Original value factory to be overridden.
-    :return:
     """
 
     class Patcher(object):

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/src/plexus_python_common.egg-info/PKG-INFO

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

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/src/plexus_python_common.egg-info/SOURCES.txt

@@ -48,8 +48,8 @@ src/plexus/common/carto/OSMWay.py
 src/plexus/common/carto/__init__.py
 src/plexus/common/resources/__init__.py
 src/plexus/common/resources/tags/__init__.py
-src/plexus/common/resources/tags/unittest.tagset.yaml
-src/plexus/common/resources/tags/universal.tagset.yaml
+src/plexus/common/resources/tags/unittest-1.0.0.tagset.yaml
+src/plexus/common/resources/tags/universal-1.0.0.tagset.yaml
 src/plexus/common/utils/__init__.py
 src/plexus/common/utils/apiutils.py
 src/plexus/common/utils/bagutils.py

{plexus_python_common-1.0.56 → plexus_python_common-1.0.57}/test/plexus_tests/common/utils/tagutils_test.py

@@ -25,14 +25,16 @@ class TagUtilsTest(unittest.TestCase):
             for tag in tagset:
                 self.assertIn(tag, tagset)
                 self.assertIn(tag.name, tagset)
-                self.assertEqual(tag, tagset.get(tag))
-                self.assertEqual(tag, tagset.get(tag.name))
+                self.assertEqual(tag.name, tagset.get(tag).name)
+                self.assertEqual(tag.name, tagset.get(tag.name).name)
 
             markdown = render_tagset_markdown_readme(tagset)
             self.assertIsInstance(markdown, str)
 
             print(markdown)
 
+        self.assertEqual(predefined_tagsets().get("unittest"), predefined_tagsets().get("unittest:1.0.0"))
+
     data_tag_validate = [
         ("level_1_tag", {"dummy_property": "dummy_value"}, True,),
 
@@ -71,7 +73,7 @@ class TagUtilsTest(unittest.TestCase):
 
     @ddt.idata(data_tag_validate)
     @ddt.unpack
-    def test_tag_validate(self, tag: str, props: JsonObject, should_pass: bool):
+    def test_tagset_validate(self, tag: str, props: JsonObject, should_pass: bool):
         tagset = predefined_tagsets().get("unittest")
 
         if should_pass:
@@ -82,7 +84,7 @@ class TagUtilsTest(unittest.TestCase):
                 tagset.validate(tag, props, raise_on_error=True)
 
     def test_tag_cache(self):
-        tagset = MutableTagset(namespace="tagset", desc="A dummy tagset for testing")
+        tagset = MutableTagset(namespace="tagset", version="1.0.0", desc="A dummy tagset for testing")
         tagset.add(Tag(name="dummy:foo", desc="A dummy tag for testing"))
         tagset.add(Tag(name="dummy:bar", desc="Another dummy tag for testing"))
 
@@ -125,21 +127,21 @@ class TagUtilsTest(unittest.TestCase):
                          60 + 1)
         self.assertEqual(len(list(target_cache.iter_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"),
                                                          dt_parse_iso("2020-01-01T00:01:00+00:00"),
-                                                         tag_pattern="dummy:foo"))),
+                                                         tag_prefix="dummy:foo"))),
                          60 // len(tags) + 1)
         self.assertEqual(len(list(target_cache.iter_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"),
                                                          dt_parse_iso("2020-01-01T00:01:00+00:00"),
-                                                         tag_pattern="dummy:bar"))),
+                                                         tag_prefix="dummy:bar"))),
                          60 // len(tags))
         self.assertEqual(len(list(target_cache.iter_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"),
                                                          dt_parse_iso("2020-01-01T00:01:00+00:00"),
-                                                         tag_pattern="dummy"))),
+                                                         tag_prefix="dummy"))),
                          60 + 1)
-        self.assertEqual(len(list(target_cache.iter_tags(tag_pattern="dummy:foo"))),
+        self.assertEqual(len(list(target_cache.iter_tags(tag_prefix="dummy:foo"))),
                          tags_count // len(tags))
-        self.assertEqual(len(list(target_cache.iter_tags(tag_pattern="dummy:bar"))),
+        self.assertEqual(len(list(target_cache.iter_tags(tag_prefix="dummy:bar"))),
                          tags_count // len(tags))
-        self.assertEqual(len(list(target_cache.iter_tags(tag_pattern="dummy"))), tags_count)
+        self.assertEqual(len(list(target_cache.iter_tags(tag_prefix="dummy"))), tags_count)
 
         self.assertEqual(len(list(cache.iter_tags())), tags_count)
         self.assertEqual(len(list(cache.iter_tags(tagsets=[tagset]))), tags_count // 2)
@@ -150,19 +152,19 @@ class TagUtilsTest(unittest.TestCase):
                          60 + 1)
         self.assertEqual(len(list(cache.iter_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"),
                                                   dt_parse_iso("2020-01-01T00:01:00+00:00"),
-                                                  tag_pattern="dummy:foo"))),
+                                                  tag_prefix="dummy:foo"))),
                          60 // len(tags) + 1)
         self.assertEqual(len(list(cache.iter_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"),
                                                   dt_parse_iso("2020-01-01T00:01:00+00:00"),
-                                                  tag_pattern="dummy:bar"))),
+                                                  tag_prefix="dummy:bar"))),
                          60 // len(tags))
         self.assertEqual(len(list(cache.iter_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"),
                                                   dt_parse_iso("2020-01-01T00:01:00+00:00"),
-                                                  tag_pattern="dummy"))),
+                                                  tag_prefix="dummy"))),
                          60 + 1)
-        self.assertEqual(len(list(cache.iter_tags(tag_pattern="dummy:foo"))), tags_count // len(tags))
-        self.assertEqual(len(list(cache.iter_tags(tag_pattern="dummy:bar"))), tags_count // len(tags))
-        self.assertEqual(len(list(cache.iter_tags(tag_pattern="dummy"))), tags_count)
+        self.assertEqual(len(list(cache.iter_tags(tag_prefix="dummy:foo"))), tags_count // len(tags))
+        self.assertEqual(len(list(cache.iter_tags(tag_prefix="dummy:bar"))), tags_count // len(tags))
+        self.assertEqual(len(list(cache.iter_tags(tag_prefix="dummy"))), tags_count)
 
         target_cache.remove_tags(dt_parse_iso("2020-01-01T00:00:00+00:00"), dt_parse_iso("2020-01-01T00:01:00+00:00"))
 
@@ -180,7 +182,7 @@ class TagUtilsTest(unittest.TestCase):
         self.assertEqual(len(list(cache.iter_tags())), 0)
 
     def test_tag_cache__multithread(self):
-        tagset = MutableTagset(namespace="tagset", desc="A dummy tagset for testing")
+        tagset = MutableTagset(namespace="tagset", version="1.0.0", desc="A dummy tagset for testing")
         tagset.add(Tag(name="dummy:foo", desc="A dummy tag for testing"))
         tagset.add(Tag(name="dummy:bar", desc="Another dummy tag for testing"))
 
@@ -239,15 +241,15 @@ class TagUtilsTest(unittest.TestCase):
 
             for target_cache in target_caches:
                 self.assertEqual(len(list(target_cache.iter_tags())), tasks_count_per_target_cache)
-                self.assertEqual(len(list(target_cache.iter_tags(tag_pattern="dummy:bar"))),
+                self.assertEqual(len(list(target_cache.iter_tags(tag_prefix="dummy:bar"))),
                                  tasks_count_per_target_cache // len(tags))
 
             self.assertEqual(len(list(cache.iter_tag_and_targets())), total_tasks_count)
-            self.assertEqual(len(list(cache.iter_tag_and_targets(tag_pattern="dummy:bar"))),
+            self.assertEqual(len(list(cache.iter_tag_and_targets(tag_prefix="dummy:bar"))),
                              total_tasks_count // len(tags))
 
     def test_tag_cache__clone(self):
-        tagset = MutableTagset(namespace="tagset", desc="A dummy tagset for testing")
+        tagset = MutableTagset(namespace="tagset", version="1.0.0", desc="A dummy tagset for testing")
         tagset.add(Tag(name="dummy:foo", desc="A dummy tag for testing"))
         tagset.add(Tag(name="dummy:bar", desc="Another dummy tag for testing"))
 
@@ -301,7 +303,7 @@ class TagUtilsTest(unittest.TestCase):
                              tags_count // 2)
 
     def test_tag_cache__clone_same_file(self):
-        tagset = MutableTagset(namespace="tagset", desc="A dummy tagset for testing")
+        tagset = MutableTagset(namespace="tagset", version="1.0.0", desc="A dummy tagset for testing")
         tagset.add(Tag(name="dummy:foo", desc="A dummy tag for testing"))
         tagset.add(Tag(name="dummy:bar", desc="Another dummy tag for testing"))