plexus-python-common 1.0.40__tar.gz → 1.0.41__tar.gz

{plexus_python_common-1.0.40 → plexus_python_common-1.0.41}/PKG-INFO

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

plexus_python_common-1.0.41/src/plexus/common/resources/tags/__init__.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import yaml
+from iker.common.utils.funcutils import singleton
+from iker.common.utils.jsonutils import JsonObject
+
+__all__ = [
+    "predefined_tagset_specs",
+]
+
+
+@singleton
+def predefined_tagset_specs() -> list[tuple[Path, JsonObject]]:
+    def load():
+        root = Path(__file__).parent
+        for path in root.glob("**/*.tagset.yaml"):
+            text = path.read_text(encoding="utf-8")
+            yield path, yaml.safe_load(text)
+
+    return list(load())

plexus_python_common-1.0.41/src/plexus/common/resources/tags/universal.tagset.yaml

@@ -0,0 +1,176 @@
+$namespace: "universal"
+$desc: "Universal tags applicable across various scenarios."
+$def:
+  camera_views:
+    &camera_views
+    unified: { $desc: "unified" }
+    front_center: { $desc: "front center" }
+    front_left: { $desc: "front left" }
+    front_right: { $desc: "front right" }
+    side_left: { $desc: "side left" }
+    side_right: { $desc: "side right" }
+    rear_left: { $desc: "rear left" }
+    rear_right: { $desc: "rear right" }
+  radar_views:
+    &radar_views
+    unified: { $desc: "unified" }
+    bumper_center: { $desc: "bumper center" }
+    bumper_left: { $desc: "bumper left" }
+    bumper_right: { $desc: "bumper right" }
+  lidar_views:
+    &lidar_views
+    unified: { $desc: "unified" }
+    front_center: { $desc: "front center" }
+    front_left: { $desc: "front left" }
+    front_right: { $desc: "front right" }
+    side_left: { $desc: "side left" }
+    side_right: { $desc: "side right" }
+    rear_left: { $desc: "rear left" }
+    rear_right: { $desc: "rear right" }
+$tags:
+  environment:
+    tod:
+      dawn: { $desc: "dawn" }
+      daytime: { $desc: "daytime" }
+      dusk: { $desc: "dusk" }
+      nighttime: { $desc: "nighttime" }
+      unknown: { $desc: "unknown" }
+    weather:
+      cloudy: { $desc: "cloudy" }
+      foggy: { $desc: "foggy" }
+      rainy: { $desc: "rainy" }
+      snowy: { $desc: "snowy" }
+      unknown: { $desc: "unknown" }
+    visibility:
+      high: { $desc: "high" }
+      moderate: { $desc: "moderate" }
+      low: { $desc: "low" }
+      unknown: { $desc: "unknown" }
+    obstructions:
+      fog: { $desc: "fog" }
+      smoke: { $desc: "smoke" }
+      dust: { $desc: "dust" }
+      snowfall: { $desc: "snowfall" }
+      rainfall: { $desc: "rainfall" }
+      unknown: { $desc: "unknown" }
+    lighting:
+      normal: { $desc: "normal ambient lighting" }
+      low_light: { $desc: "low ambient lighting" }
+      glare: { $desc: "glare from sun or artificial source" }
+      shadows: { $desc: "shadows casting on the roadway" }
+      unknown: { $desc: "unknown" }
+    road_surface:
+      dry: { $desc: "dry" }
+      wet: { $desc: "wet" }
+      standing_water: { $desc: "standing water" }
+      icy: { $desc: "icy" }
+      snow_covered: { $desc: "snow covered" }
+      slush: { $desc: "covered in slush" }
+      gravel: { $desc: "covered in gravel" }
+      contaminated: { $desc: "contaminated with oil, mud, etc." }
+      unknown: { $desc: "unknown" }
+  roadway:
+    classification:
+      expressway: { $desc: "expressway/freeway" }
+      highway: { $desc: "highway/major road" }
+      arterial: { $desc: "arterial road" }
+      collector: { $desc: "collector road" }
+      residential: { $desc: "residential/street" }
+      rural: { $desc: "rural road" }
+      unpaved: { $desc: "unpaved road" }
+      service_road: { $desc: "service road/alley" }
+      parking_lot: { $desc: "parking lot/garage" }
+      unknown: { $desc: "unknown" }
+    layout:
+      single_way: { $desc: "single way" }
+      undivided_two_way: { $desc: "undivided two way" }
+      divided_two_way: { $desc: "divided two way" }
+      unknown: { $desc: "unknown" }
+    lane_config:
+      single_lane: { $desc: "single lane" }
+      two_lane: { $desc: "two lane" }
+      multi_lane: { $desc: "multi lane" }
+      unknown: { $desc: "unknown" }
+    shoulder:
+      none: { $desc: "no shoulder" }
+      median: { $desc: "median shoulder" }
+      verge: { $desc: "verge shoulder" }
+      sidewalk: { $desc: "sidewalk shoulder" }
+      emergency_lane: { $desc: "emergency lane" }
+      unknown: { $desc: "unknown" }
+    junction:
+      cross: { $desc: "cross intersection" }
+      tee_left_right: { $desc: "tee intersection left and right" }
+      tee_left_only: { $desc: "tee intersection left only and straight" }
+      tee_right_only: { $desc: "tee intersection right only and straight" }
+      y_intersection: { $desc: "y intersection" }
+      roundabout: { $desc: "roundabout" }
+      merge: { $desc: "merge" }
+      split: { $desc: "split" }
+      other: { $desc: "other junction type" }
+      unknown: { $desc: "unknown" }
+    infrastructure:
+      tunnel: { $desc: "tunnel" }
+      bridge: { $desc: "bridge/overpass" }
+      underpass: { $desc: "underpass" }
+      unknown: { $desc: "unknown" }
+    geometry:
+      curved: { $desc: "curved segment" }
+      incline: { $desc: "incline segment" }
+      decline: { $desc: "decline segment" }
+      hill_crest: { $desc: "hill crest" }
+      sag: { $desc: "sag segment" }
+  traffic:
+    density:
+      absent: { $desc: "no traffic" }
+      sparse: { $desc: "sparse traffic" }
+      light: { $desc: "light traffic" }
+      moderate: { $desc: "moderate traffic" }
+      dense: { $desc: "dense traffic" }
+      jammed: { $desc: "traffic jam" }
+      unknown: { $desc: "unknown" }
+    pedestrian_presence:
+      absent: { $desc: "no pedestrians" }
+      sparse: { $desc: "sparse pedestrians" }
+      moderate: { $desc: "moderate pedestrians" }
+      dense: { $desc: "dense pedestrians" }
+      unknown: { $desc: "unknown" }
+    cyclist_presence:
+      absent: { $desc: "no cyclists" }
+      sparse: { $desc: "sparse cyclists" }
+      moderate: { $desc: "moderate cyclists" }
+      dense: { $desc: "dense cyclists" }
+      unknown: { $desc: "unknown" }
+    construction_zone:
+      absent: { $desc: "no construction" }
+      minor: { $desc: "minor construction" }
+      major: { $desc: "major construction" }
+      unknown: { $desc: "unknown" }
+    accident:
+      road_block: { $desc: "road block" }
+      debris_on_road: { $desc: "debris on road" }
+      animal_on_road: { $desc: "animal on road" }
+      pedestrian_on_road: { $desc: "pedestrian on road" }
+      vehicle_breakdown: { $desc: "vehicle breakdown" }
+      emergency_vehicle_present: { $desc: "emergency vehicle present" }
+      police_stop: { $desc: "police stop" }
+      other: { $desc: "other accident type" }
+  data_fidelity:
+    camera_issue:
+      glare: { $desc: "glare from sun or artificial source", <<: *camera_views }
+      motion_blur: { $desc: "motion blur", <<: *camera_views }
+      lens_smear: { $desc: "lens smear or dirt", <<: *camera_views }
+      occlusion: { $desc: "occlusion by objects", <<: *camera_views }
+      underexposure: { $desc: "underexposure", <<: *camera_views }
+      overexposure: { $desc: "overexposure", <<: *camera_views }
+    radar_issue:
+      weather_effects: { $desc: "weather effects", <<: *radar_views }
+      interference: { $desc: "interference", <<: *radar_views }
+      multipath: { $desc: "multipath reflections", <<: *radar_views }
+      clutter: { $desc: "clutter", <<: *radar_views }
+    lidar_issue:
+      weather_effects: { $desc: "weather effects", <<: *lidar_views }
+      occlusion: { $desc: "occlusion by objects", <<: *lidar_views }
+      motion_distortion: { $desc: "motion distortion", <<: *lidar_views }
+      range_dropout: { $desc: "range dropout", <<: *lidar_views }
+      reflectivity: { $desc: "reflectivity issues", <<: *lidar_views }

{plexus_python_common-1.0.40 → plexus_python_common-1.0.41}/src/plexus/common/utils/datautils.py

@@ -1,13 +1,19 @@
+import dataclasses
 import datetime
-from collections.abc import Callable, Generator
+from collections.abc import Callable, Generator, Mapping, Sequence
 from typing import Any
 
 import pyparsing as pp
 import ujson as json
 from iker.common.utils.funcutils import singleton
-from iker.common.utils.jsonutils import JsonType
+from iker.common.utils.iterutils import dicttree
+from iker.common.utils.iterutils import dicttree_add, dicttree_remove
+from iker.common.utils.iterutils import dicttree_children, dicttree_lineage, dicttree_subtree
+from iker.common.utils.iterutils import head_or_none
+from iker.common.utils.jsonutils import JsonObject, JsonType
 from iker.common.utils.randutils import randomizer
 
+from plexus.common.resources.tags import predefined_tagset_specs
 from plexus.common.utils.strutils import BagName, UserName, VehicleName
 from plexus.common.utils.strutils import colon_tag_parser, slash_tag_parser
 from plexus.common.utils.strutils import dot_case_parser, kebab_case_parser, snake_case_parser
@@ -18,6 +24,38 @@ from plexus.common.utils.strutils import strict_abspath_parser, strict_relpath_p
 from plexus.common.utils.strutils import strict_fragmented_abspath_parser, strict_fragmented_relpath_parser
 from plexus.common.utils.strutils import topic_parser, vin_code_chars, vin_code_parser
 
+__all__ = [
+    "compute_vin_code_check_digit",
+    "validate_hex_string",
+    "validate_snake_case",
+    "validate_kebab_case",
+    "validate_dot_case",
+    "validate_uuid",
+    "validate_strict_relpath",
+    "validate_strict_abspath",
+    "validate_strict_fragmented_relpath",
+    "validate_strict_fragmented_abspath",
+    "validate_semver",
+    "validate_colon_tag",
+    "validate_slash_tag",
+    "validate_topic",
+    "validate_vin_code",
+    "validate_user_name",
+    "validate_vehicle_name",
+    "validate_bag_name",
+    "validate_dt_timezone",
+    "validate_json_type_dump_size",
+    "random_vin_code",
+    "known_topics",
+    "known_user_names",
+    "known_vehicle_names",
+    "random_bag_names_sequence",
+    "Tag",
+    "Tagset",
+    "populate_tagset",
+    "predefined_tagsets",
+]
+
 
 def make_compute_vin_code_check_digit() -> Callable[[str], str]:
     trans_nums = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3, 4, 5, 7, 9, 2, 3, 4, 5, 6, 7, 8, 9]
@@ -201,3 +239,152 @@ def random_bag_names_sequence(
 
     for record_sn in range(bags_count):
         yield BagName(vehicle_name=vehicle_name, record_dt=record_dt, record_sn=record_sn)
+
+
+@dataclasses.dataclass(frozen=True, eq=True, order=True)
+class Tag(object):
+    name: str
+    desc: str | None
+
+    @property
+    def tag_parts(self) -> list[str]:
+        return self.name.rsplit(":")
+
+    @property
+    def parent_tag_name(self) -> str | None:
+        return head_or_none(self.name.rsplit(":", 1))
+
+
+class Tagset(Sequence[Tag], Mapping[str, Tag]):
+    def __init__(self, namespace: str, desc: str) -> None:
+        super().__init__()
+        self.namespace = namespace
+        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 __len__(self) -> int:
+        return len(self.tags)
+
+    def __getitem__(self, index: int) -> Tag:
+        return self.tags[index]
+
+    def keys(self):
+        return self.tags_dict.keys()
+
+    def values(self):
+        return self.tags_dict.values()
+
+    def items(self):
+        return self.tags_dict.items()
+
+    def get(self, item: str | Tag) -> Tag | None:
+        tag_name = item.name if isinstance(item, Tag) else item
+        return self.tags_dict.get(tag_name)
+
+    @property
+    def tag_names(self) -> list[str]:
+        return list(self.tags_dict.keys())
+
+    def add(self, tag: Tag) -> None:
+        if tag.name in self.tags_dict:
+            raise ValueError(f"duplicate tag name '{tag.name}'")
+
+        self.tags.append(tag)
+        self.tags_dict[tag.name] = tag
+
+        dicttree_add(self.tags_tree, tag.tag_parts, tag, create_prefix=True)
+
+    def remove(self, tag_name: str) -> None:
+        tag = self.get(tag_name)
+        if tag is None:
+            raise ValueError(f"tag '{tag_name}' not found")
+
+        self.tags.remove(tag)
+        del self.tags_dict[tag_name]
+
+        dicttree_remove(self.tags_tree, tag.tag_parts, recursive=True)
+
+    def child_tags(self, parent: str | Tag) -> list[Tag]:
+        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 []
+
+    def parent_tags(self, child: str | Tag) -> list[Tag]:
+        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]))
+
+
+def populate_tagset(tagset_spec: JsonObject) -> Tagset:
+    """
+    Collect tags from tagset spec JSON object, validate the format along the way.
+
+    :param tagset_spec: JSON object of tagset spec
+    :return: Populated Tagset instance
+    """
+
+    def validate_and_collect(tag_name: str, tag_def: JsonObject) -> Generator[Tag, None, None]:
+        if not isinstance(tag_def, dict):
+            raise ValueError(f"tag '{tag_name}' definition is not a dict")
+
+        for child_tag_name, child_tag_def in tag_def.items():
+            if child_tag_name == "$desc":
+                continue
+
+            if not isinstance(child_tag_name, str):
+                raise ValueError(f"child '{child_tag_name}' of tag '{tag_name}' is not a string")
+            try:
+                validate_snake_case(child_tag_name)
+            except ValueError as e:
+                raise ValueError(f"child '{child_tag_name}' of tag '{tag_name}' is not in snake case") from e
+
+            child_tag_name = tag_name + ":" + child_tag_name if tag_name else child_tag_name
+
+            yield from validate_and_collect(child_tag_name, child_tag_def)
+
+        yield Tag(name=tag_name, desc=tag_def.get("$desc"))
+
+    namespace = tagset_spec.get("$namespace")
+    if namespace is None:
+        raise ValueError("missing '$namespace' in tagset spec")
+    try:
+        validate_snake_case(namespace)
+    except ValueError as e:
+        raise ValueError(f"tagset namespace '{namespace}' is not in snake case") from e
+
+    desc = tagset_spec.get("$desc")
+    if desc is None:
+        raise ValueError("missing '$desc' in tagset spec")
+
+    tags = tagset_spec.get("$tags")
+    if tags is None:
+        raise ValueError("missing '$tags' in tagset spec")
+
+    tagset = Tagset(namespace=namespace, desc=desc)
+
+    for tag in validate_and_collect("", tags):
+        tagset.add(tag)
+
+    return tagset
+
+
+@singleton
+def predefined_tagsets() -> dict[str, Tagset]:
+    tagsets: dict[str, Tagset] = {}
+    for _, tagset_spec in predefined_tagset_specs():
+        tagset = populate_tagset(tagset_spec)
+        tagsets[tagset.namespace] = tagset
+    return tagsets

{plexus_python_common-1.0.40 → plexus_python_common-1.0.41}/src/plexus/common/utils/jsonutils.py

@@ -5,9 +5,9 @@ from typing import Any
 
 import ujson as json
 from iker.common.utils.dtutils import dt_format, dt_parse, extended_format
+from iker.common.utils.iterutils import batched
 from iker.common.utils.jsonutils import JsonType, JsonValueCompatible
 from iker.common.utils.jsonutils import json_reformat
-from iker.common.utils.sequtils import batched
 
 from plexus.common.utils.shutils import collect_volumed_filenames, populate_volumed_filenames
 

{plexus_python_common-1.0.40 → plexus_python_common-1.0.41}/src/plexus/common/utils/s3utils.py

@@ -18,8 +18,8 @@ from typing import Literal
 import boto3
 import fsspec
 import fsspec.utils
+from iker.common.utils.iterutils import chunk_between, head, last
 from iker.common.utils.jsonutils import JsonObject
-from iker.common.utils.sequtils import chunk_between, head, last
 from iker.common.utils.shutils import glob_match, listfile, path_depth
 from iker.common.utils.strutils import is_empty, trim_to_none
 from mypy_boto3_s3 import S3Client

{plexus_python_common-1.0.40 → plexus_python_common-1.0.41}/src/plexus_python_common.egg-info/PKG-INFO

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

{plexus_python_common-1.0.40 → plexus_python_common-1.0.41}/src/plexus_python_common.egg-info/SOURCES.txt

@@ -46,6 +46,9 @@ src/plexus/common/carto/OSMNode.py
 src/plexus/common/carto/OSMTags.py
 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/universal.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.40 → plexus_python_common-1.0.41}/test/plexus_tests/common/utils/datautils_test.py

@@ -2,6 +2,8 @@ import unittest
 
 import ddt
 
+from plexus.common.utils.datautils import Tagset
+from plexus.common.utils.datautils import predefined_tagsets
 from plexus.common.utils.datautils import random_vin_code, validate_vin_code
 
 
@@ -36,3 +38,14 @@ class DataUtilsTest(unittest.TestCase):
     def test_validate_vin_code__bad_case(self, data):
         with self.assertRaises(ValueError):
             validate_vin_code(data)
+
+    def test_predefined_tagsets(self):
+        tagsets = predefined_tagsets()
+        for _, tagset in tagsets.items():
+            self.assertIsInstance(tagset, Tagset)
+
+            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))