plexus-python-common 1.0.63__tar.gz → 1.0.65__tar.gz

{plexus_python_common-1.0.63 → plexus_python_common-1.0.65}/PKG-INFO

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

{plexus_python_common-1.0.63 → plexus_python_common-1.0.65}/src/plexus/common/utils/tagutils.py

@@ -1,6 +1,7 @@
 import contextlib
 import dataclasses
 import datetime
+import math
 import os
 import pathlib
 import textwrap
@@ -16,7 +17,9 @@ import sqlalchemy as sa
 import sqlalchemy.dialects.sqlite as sa_sqlite
 import sqlalchemy.orm as sa_orm
 from iker.common.utils.dbutils import ConnectionMaker
-from iker.common.utils.funcutils import memorized, singleton
+from iker.common.utils.dtutils import dt_from_ts_us, dt_to_ts_us
+from iker.common.utils.funcutils import Chainable
+from iker.common.utils.funcutils import chainable, memorized, singleton
 from iker.common.utils.iterutils import batched, head_or_none
 from iker.common.utils.iterutils import dicttree
 from iker.common.utils.iterutils import dicttree_add, dicttree_remove
@@ -29,6 +32,7 @@ from sqlmodel import Field, SQLModel
 from plexus.common.resources.tags import predefined_tagset_specs
 from plexus.common.utils.datautils import validate_colon_tag, validate_snake_case, validate_vehicle_name
 from plexus.common.utils.datautils import validate_dt_timezone, validate_semver, validate_slash_tag
+from plexus.common.utils.jsonutils import json_datetime_encoder
 from plexus.common.utils.ormutils import SequenceModelMixinProtocol
 from plexus.common.utils.ormutils import clone_sequence_model_instance, make_base_model, make_sequence_model_mixin
 from plexus.common.utils.sqlutils import escape_sql_like
@@ -48,6 +52,8 @@ __all__ = [
     "tag_cache_file_path",
     "TagCache",
     "tag_cache",
+    "standard_clip_duration_us",
+    "populate_clip_ranges",
 ]
 
 
@@ -440,6 +446,14 @@ class TagTarget(BaseModel):
             raise ValueError(f"begin_dt '{self.begin_dt}' is greater than end_dt '{self.end_dt}'")
         return self
 
+    @pdt.field_serializer("begin_dt", mode="plain")
+    def serialize_begin_dt(self, v: datetime.datetime) -> str:
+        return json_datetime_encoder(v)
+
+    @pdt.field_serializer("end_dt", mode="plain")
+    def serialize_end_dt(self, v: datetime.datetime) -> str:
+        return json_datetime_encoder(v)
+
 
 class TagRecord(BaseModel):
     target_sqn: int = Field(
@@ -473,6 +487,11 @@ class TagRecord(BaseModel):
         default=None,
         description="Additional properties of the tag record in JSON format",
     )
+    flags: int = Field(
+        sa_column=sa.Column(sa_sqlite.INTEGER),
+        default=0,
+        description="Integer bitmask storing status or metadata flags for this tag record",
+    )
 
     @pdt.field_validator("begin_dt", mode="after")
     @classmethod
@@ -512,6 +531,14 @@ class TagRecord(BaseModel):
         validate_colon_tag(v)
         return v
 
+    @pdt.field_serializer("begin_dt", mode="plain")
+    def serialize_begin_dt(self, v: datetime.datetime) -> str:
+        return json_datetime_encoder(v)
+
+    @pdt.field_serializer("end_dt", mode="plain")
+    def serialize_end_dt(self, v: datetime.datetime) -> str:
+        return json_datetime_encoder(v)
+
 
 class TagTargetTable(TagTarget, make_sequence_model_mixin("sqlite"), table=True):
     __tablename__ = "tag_target_info"
@@ -539,6 +566,7 @@ if typing.TYPE_CHECKING:
         tagset_version: sa_orm.Mapped[str | None] = ...
         tag: sa_orm.Mapped[str] = ...
         props: sa_orm.Mapped[JsonType | None] = ...
+        flags: sa_orm.Mapped[int] = ...
 
 
 @singleton
@@ -571,9 +599,12 @@ class TagCache(object):
             with self.conn_maker.make_session() as session:
                 yield session
 
-    def get_target(self, identifier: str) -> TagTargetTable | None:
+    def get_target(self, target: int | str) -> TagTargetTable | None:
         with self.make_session() as session:
-            return session.query(TagTargetTable).filter(TagTargetTable.identifier == identifier).one_or_none()
+            if isinstance(target, int):
+                return session.get(TagTargetTable, target)
+            else:
+                return session.query(TagTargetTable).filter(TagTargetTable.identifier == target).one_or_none()
 
     def query_targets(
         self,
@@ -660,10 +691,10 @@ class TagCache(object):
             )
             session.commit()
 
-    def with_target(self, name: str) -> "TargetedTagCache":
-        target_info = self.get_target(name)
+    def with_target(self, target: int | str) -> "TargetedTagCache":
+        target_info = self.get_target(target)
         if target_info is None:
-            raise ValueError(f"target with name '{name}' not found in cache")
+            raise ValueError(f"target '{target}' not found in cache")
         return TargetedTagCache(cache=self, target_info=target_info)
 
     def iter_tags(
@@ -957,7 +988,7 @@ class TargetedTagCache(object):
         props: JsonType | None = None,
         tagset_namespace: str | None = None,
         tagset_version: str | None = None,
-    ) -> Self:
+    ) -> 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.
@@ -984,10 +1015,12 @@ class TargetedTagCache(object):
                 tag=tag.name if isinstance(tag, Tag) else tag,
                 props=props,
             )
-            session.add(clone_sequence_model_instance(TagRecordTable, tag_record))
+            db_tag_record = clone_sequence_model_instance(TagRecordTable, tag_record)
+            session.add(db_tag_record)
             session.commit()
 
-        return self
+            session.refresh(db_tag_record)
+            return chainable(self, db_tag_record)
 
     def add_tag(
         self,
@@ -995,7 +1028,7 @@ class TargetedTagCache(object):
         props: JsonType | None = None,
         tagset_namespace: str | None = None,
         tagset_version: str | None = None,
-    ) -> Self:
+    ) -> Chainable[Self, TagRecordTable]:
         """
         Add a tag record to the cache for the entire target range.
 
@@ -1019,6 +1052,61 @@ class TargetedTagCache(object):
             props=props,
         )
 
+    def update_tag(
+        self,
+        sqn: int,
+        *,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tag: str | Tag | BoundTag | 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
+        """
+        with self.make_session() as session:
+            db_tag_record = session.query(TagRecordTable).filter(TagRecordTable.sqn == sqn).one_or_none()
+            if not db_tag_record:
+                raise ValueError(f"tag record with sqn '{sqn}' not found in cache")
+
+            if begin_dt is not None:
+                db_tag_record.begin_dt = begin_dt
+            if end_dt is not None:
+                db_tag_record.end_dt = end_dt
+            if tagset_namespace is not None:
+                db_tag_record.tagset_namespace = tag.namespace if isinstance(tag, BoundTag) else tagset_namespace
+            if tagset_version is not None:
+                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 props is not None:
+                db_tag_record.props = props
+            if flags is not None:
+                db_tag_record.flags = flags
+
+            session.commit()
+
+            session.refresh(db_tag_record)
+            return chainable(self, db_tag_record)
+
     def remove_tags(
         self,
         begin_dt: datetime.datetime | None = None,
@@ -1093,3 +1181,50 @@ def tag_cache(*, identifier: str | None = None, file_path: str | None = None) ->
     if file_path is not None:
         return TagCache(file_path=file_path)
     return TagCache(file_path=tag_cache_file_path())
+
+
+@singleton
+def standard_clip_duration_us() -> int:
+    """Duration of clips to split samples into, in microseconds, which is fixed to 20 seconds for now."""
+    return 20 * 1_000_000  # 20 seconds
+
+
+def populate_clip_ranges(
+    data_begin_dt: datetime.datetime,
+    data_end_dt: datetime.datetime,
+    *,
+    clip_duration_us: int = None
+) -> Generator[tuple[datetime.datetime, datetime.datetime, datetime.datetime, datetime.datetime]]:
+    """
+    Generate clip begin datetime, clip data begin datetime, and clip data end datetime for each clip slot that overlaps
+    with the given data begin and end datetimes.
+    The clip begin datetime is the beginning of the clip slot, the clip data begin datetime is the maximum of the clip
+    begin datetime and the data begin datetime, and the clip data end datetime is the minimum of the clip end datetime
+    and the data end datetime.
+
+    :param data_begin_dt: The beginning datetime of the data.
+    :param data_end_dt: The end datetime of the data.
+    :param clip_duration_us: The duration of each clip in microseconds. If not provided,
+                             the standard clip duration will be used.
+    :return: A generator of tuples containing the clip begin datetime, clip data begin datetime,
+             and clip data end datetime
+    """
+    clip_duration_us = clip_duration_us or standard_clip_duration_us()
+
+    if data_begin_dt == data_end_dt:
+        clip_slot = math.floor(dt_to_ts_us(data_begin_dt) / clip_duration_us)
+        clip_begin_dt = dt_from_ts_us(clip_slot * clip_duration_us)
+        clip_end_dt = dt_from_ts_us((clip_slot + 1) * clip_duration_us)
+        yield clip_begin_dt, clip_end_dt, data_begin_dt, data_end_dt
+        return
+
+    begin_clip_slot = math.floor(dt_to_ts_us(data_begin_dt) / clip_duration_us)
+    end_clip_slot = math.ceil(dt_to_ts_us(data_end_dt) / clip_duration_us)
+
+    for clip_slot in range(begin_clip_slot, end_clip_slot):
+        clip_begin_dt = dt_from_ts_us(clip_slot * clip_duration_us)
+        clip_end_dt = dt_from_ts_us((clip_slot + 1) * clip_duration_us)
+        clip_data_begin_dt = max(clip_begin_dt, data_begin_dt)
+        clip_data_end_dt = min(clip_end_dt, data_end_dt)
+
+        yield clip_begin_dt, clip_end_dt, clip_data_begin_dt, clip_data_end_dt

{plexus_python_common-1.0.63 → plexus_python_common-1.0.65}/src/plexus_python_common.egg-info/PKG-INFO

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

{plexus_python_common-1.0.63 → plexus_python_common-1.0.65}/test/plexus_tests/common/utils/tagutils_test.py

@@ -10,6 +10,7 @@ from iker.common.utils.iterutils import last
 from iker.common.utils.jsonutils import JsonObject
 
 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
 
@@ -497,3 +498,177 @@ class TagUtilsTest(unittest.TestCase):
                              tag_records_count * 2 * (tags_count - tagset_tags_count) // tags_count)
             self.assertEqual(len(list(dst_target_cache.iter_tags(tagsets=[tagset], tagset_inverted=False))),
                              tag_records_count * 2 * tagset_tags_count // tags_count)
+
+    data_populate_clip_ranges = [
+        (
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:50.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:40.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:40.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:40.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:01:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:40.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:50.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:15.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:15.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:30.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:40.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:30.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:05.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:05.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:05.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:05.000000+00:00")),
+            ],
+        )
+    ]
+
+    @ddt.idata(data_populate_clip_ranges)
+    @ddt.unpack
+    def test_populate_clip_ranges(self, data_begin_dt, data_end_dt, expected):
+        result = list(populate_clip_ranges(data_begin_dt, data_end_dt))
+        self.assertEqual(result, expected)
+
+    data_populate_clip_ranges__customized_duration = [
+        (
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:50.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:30.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:30.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:30.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:40.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:30.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:40.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:40.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:50.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:40.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:50.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:15.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:15.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:30.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00")),
+                (dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:30.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:20.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:30.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:00.000000+00:00")),
+            ],
+        ),
+        (
+            dt_parse_iso("2023-01-01T00:00:05.000000+00:00"),
+            dt_parse_iso("2023-01-01T00:00:05.000000+00:00"),
+            [
+                (dt_parse_iso("2023-01-01T00:00:00.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:10.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:05.000000+00:00"),
+                 dt_parse_iso("2023-01-01T00:00:05.000000+00:00")),
+            ],
+        )
+    ]
+
+    @ddt.idata(data_populate_clip_ranges__customized_duration)
+    @ddt.unpack
+    def test_populate_clip_ranges__customized_duration(self, data_begin_dt, data_end_dt, expected):
+        result = list(populate_clip_ranges(data_begin_dt, data_end_dt, clip_duration_us=10_000_000))
+        self.assertEqual(result, expected)