plexus-python-common 1.0.58__tar.gz → 1.0.60__tar.gz

{plexus_python_common-1.0.58 → plexus_python_common-1.0.60}/PKG-INFO

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

plexus_python_common-1.0.60/README.md

@@ -0,0 +1,5 @@
+# Plexus Python Common Module
+
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/plexus-python-common?style=for-the-badge)
+![PyPI - Version](https://img.shields.io/pypi/v/plexus-python-common?style=for-the-badge)
+![Codecov](https://img.shields.io/codecov/c/github/ruyangshou/plexus-python-common?token=U8EPB2JZ70&style=for-the-badge)

{plexus_python_common-1.0.58 → plexus_python_common-1.0.60}/src/plexus/common/utils/bagutils.py

@@ -148,18 +148,18 @@ class BagReader(AbstractContextManager, BagIOBase):
     @staticmethod
     def open_ros2(db_dir: str | os.PathLike[str], db_filename: str = default_bag_db_file, **kwargs) -> "BagReader":
         """
-        Creates a BagReader instance to read messages from a ROS2 bag file in the specified directory.
+        Creates a ``BagReader`` instance to read messages from a ROS2 bag file in the specified directory.
 
         :param db_dir: path to the directory where the SQLite DB file is located.
         :param db_filename: name of the SQLite DB file to read. Default is "bag.db".
-        :param kwargs: additional keyword arguments to pass to the BagReader constructor.
-        :return: a BagReader instance.
+        :param kwargs: additional keyword arguments to pass to the ``BagReader`` constructor.
+        :return: a ``BagReader`` instance.
         """
         return BagReader(make_path(db_dir) / db_filename)
 
     def __init__(self, bag_file_path: str | os.PathLike[str]):
         """
-        Creates a BagReader instance to read messages from a ROS2 bag file.
+        Creates a ``BagReader`` instance to read messages from a ROS2 bag file.
 
         :param bag_file_path: path to the SQLite DB file to read.
         """
@@ -202,24 +202,26 @@ class BagWriter(AbstractContextManager, BagIOBase):
     @staticmethod
     def open_ros2(db_dir: str | os.PathLike[str], db_filename: str = default_bag_db_file, **kwargs) -> "BagWriter":
         """
-        Creates a BagWriter instance to write messages to a ROS2 bag file in the specified directory.
+        Creates a ``BagWriter`` instance to write messages to a ROS2 bag file in the specified directory.
 
         :param db_dir: path to the directory where the SQLite DB file will be created.
         :param db_filename: name of the SQLite DB file to create. Default is "bag.db".
-        :param kwargs: additional keyword arguments to pass to the BagWriter constructor.
-        :return: a BagWriter instance.
+        :param kwargs: additional keyword arguments to pass to the ``BagWriter`` constructor.
+        :return: a ``BagWriter`` instance.
         """
         return BagWriter(make_path(db_dir) / db_filename, **kwargs)
 
     def __init__(self, bag_file_path: str | os.PathLike[str], *, overwrite: bool = True, exist_ok: bool = False):
         """
-        Creates a BagWriter instance to write messages to a ROS2 bag file.
+        Creates a ``BagWriter`` instance to write messages to a ROS2 bag file.
 
         :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.
-        :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.
+        :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.
+        :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.
         """
         super().__init__(bag_file_path)
 

{plexus_python_common-1.0.58 → plexus_python_common-1.0.60}/src/plexus/common/utils/ormutils.py

@@ -451,11 +451,11 @@ def model_revision_type(dialect: str | None = None) -> sa.types.TypeEngine[int]:
 
 def make_sequence_model_mixin(dialect: str | None = None) -> type[SequenceModelMixin]:
     """
-    Creates a mixin class for SQLModel models that adds a unique identifier field `sqn`.
+    Creates a mixin class for SQLModel models that adds a unique identifier field ``sqn``.
     Use this mixin to add an auto-incremented primary key to your models.
 
-    :param dialect: The database dialect to determine the column type for the `sqn` field.
-    :return: A mixin class that can be used with SQLModel models to add the `sqn` field.
+    :param dialect: The database dialect to determine the column type for the ``sqn`` field.
+    :return: A mixin class that can be used with SQLModel models to add the ``sqn`` field.
     """
 
     class ModelMixin(SQLModel):
@@ -765,11 +765,11 @@ class RevisionModel(make_base_model(), make_revision_model_mixin(), table=True):
 def make_snapshot_model_trigger[SnapshotModelT: SnapshotModelMixin](engine: sa.Engine, model: type[SnapshotModelT]):
     """
     Creates the necessary database objects (sequence, function, trigger) to support automatic snapshot management
-    for the given snapshot model. This includes a sequence for `record_sqn`, a function to handle snapshot updates,
-    and a trigger to invoke the function before inserts. The model must extend `SnapshotModel`.
+    for the given snapshot model. This includes a sequence for ``record_sqn``, a function to handle snapshot updates,
+    and a trigger to invoke the function before inserts. The model must extend ``SnapshotModel``.
 
     :param engine: SQLAlchemy engine connected to the target database.
-    :param model: The snapshot model class extending `SnapshotModel`.
+    :param model: The snapshot model class extending ``SnapshotModel``.
     """
     table_name = model_name_of(model, fallback_classname=False)
     if not table_name:
@@ -834,11 +834,11 @@ def make_snapshot_model_trigger[SnapshotModelT: SnapshotModelMixin](engine: sa.E
 def make_revision_model_trigger[RevisionModelT: RevisionModelMixin](engine: sa.Engine, model: type[RevisionModelT]):
     """
     Creates the necessary database objects (sequence, function, trigger) to support automatic revision management
-    for the given revision model. This includes a sequence for `record_sqn`, a function to handle revision updates,
-    and a trigger to invoke the function before inserts. The model must extend `RevisionModel`.
+    for the given revision model. This includes a sequence for ``record_sqn``, a function to handle revision updates,
+    and a trigger to invoke the function before inserts. The model must extend ``RevisionModel``.
 
     :param engine: SQLAlchemy engine connected to the target database.
-    :param model: The revision model class extending `RevisionModel`.
+    :param model: The revision model class extending ``RevisionModel``.
     """
     table_name = model_name_of(model, fallback_classname=False)
     if not table_name:

{plexus_python_common-1.0.58 → plexus_python_common-1.0.60}/src/plexus/common/utils/tagutils.py

@@ -688,7 +688,7 @@ class TagCache(object):
         :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
         """
@@ -749,7 +749,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
         """
@@ -813,7 +813,7 @@ class TagCache(object):
         :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)
@@ -921,7 +921,7 @@ class TargetedTagCache(object):
         :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
         """
@@ -965,12 +965,13 @@ class TargetedTagCache(object):
         :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.
+                    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.
+                                 ``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:
@@ -999,12 +1000,14 @@ class TargetedTagCache(object):
         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.
+                    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.
+                                 ``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.
+                               ``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(
@@ -1037,7 +1040,7 @@ class TargetedTagCache(object):
         :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:
@@ -1074,10 +1077,12 @@ 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.58 → plexus_python_common-1.0.60}/src/plexus_python_common.egg-info/PKG-INFO

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

plexus_python_common-1.0.58/README.md

@@ -1,4 +0,0 @@
-# Plexus Python Common Module
-
-[![codecov](https://codecov.io/gh/ruyangshou/plexus-python-common/graph/badge.svg?token=U8EPB2JZ70)](
-https://codecov.io/gh/ruyangshou/plexus-python-common)