plexus-python-pulse-common 1.1.79__tar.gz → 1.1.81__tar.gz

{plexus_python_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/PKG-INFO

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

{plexus_python_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/src/plexus/pulse/common/carto/OSMFile.py

@@ -12,12 +12,12 @@ class OSMFile(object):
     @classmethod
     def load_file(cls, path: str, proj: Proj | None) -> Self:
         """
-        Loads OSM from file given the path
+        Loads an OSM file from the given path.
 
-        :param path: path of OSM file
-        :param proj: cartographic projection
+        :param path: Path to the OSM file.
+        :param proj: Cartographic projection to use for coordinates.
 
-        :return: an OSM file instance
+        :return: Loaded OSM file.
         """
         root = lxml.etree.parse(path).getroot()
 
@@ -71,12 +71,12 @@ class OSMFile(object):
     @classmethod
     def from_coords(cls, coords: list[Coord], way_tags: dict[str, Any] = None) -> Self:
         """
-        Constructs a single-way OSM file from the given coords
+        Constructs a single-way OSM file from the given coordinates.
 
-        :param coords: coords on a single way
-        :param way_tags: tags of the corresponding way
+        :param coords: Coordinates that make up the way.
+        :param way_tags: Tags to assign to the way.
 
-        :return: OSM file contains one way
+        :return: OSM file containing one way.
         """
         osm = OSMFile()
         osm.add_way_from_coords(coords, way_tags or {})
@@ -86,12 +86,12 @@ class OSMFile(object):
     @classmethod
     def from_coords_list(cls, coords_list: list[list[Coord]], way_tags_list: list[dict[str, Any]] = None) -> Self:
         """
-        Constructs a multi-way OSM file from the given coords
+        Constructs a multi-way OSM file from the given coordinate lists.
 
-        :param coords_list: coords of each way
-        :param way_tags_list: tags of each corresponding way
+        :param coords_list: Coordinates for each way.
+        :param way_tags_list: Tags to assign to each corresponding way.
 
-        :return: OSM file contains multiple ways
+        :return: OSM file containing multiple ways.
         """
         osm = OSMFile()
 
@@ -106,10 +106,10 @@ class OSMFile(object):
 
     def __init__(self, nodes: dict[int, OSMNode] = None, ways: dict[int, OSMWay] = None):
         """
-        Represents an editable general purpose OSM file
+        Represents an editable general-purpose OSM file.
 
-        :param nodes: nodes
-        :param ways: ways
+        :param nodes: Initial nodes to include.
+        :param ways: Initial ways to include.
         """
         self.nodes: dict[int, OSMNode] = {}
         self.ways: dict[int, OSMWay] = {}
@@ -126,11 +126,11 @@ class OSMFile(object):
 
     def add_node(self, node: OSMNode) -> OSMNode:
         """
-        Adds the given node
+        Adds the given node.
 
-        :param node: the node to be added
+        :param node: Node to add.
 
-        :return: added node
+        :return: Added node.
         """
         self.nodes[node.node_id] = node
         if node.node_id >= self.next_node_id:
@@ -139,22 +139,22 @@ class OSMFile(object):
 
     def add_node_from_coord(self, coord: Coord, tags: dict[str, Any] = None) -> OSMNode:
         """
-        Adds node given the coord and tags
+        Adds a node from the given coordinate and tags.
 
-        :param coord: coord of the node
-        :param tags: tags of the node
+        :param coord: Node coordinate.
+        :param tags: Node tags.
 
-        :return: added node
+        :return: Added node.
         """
         return self.add_node(OSMNode(self.next_node_id, coord, OSMTags.from_any_tags(tags)))
 
     def add_way(self, way: OSMWay) -> OSMWay:
         """
-        Adds the given way
+        Adds the given way.
 
-        :param way: the way to be added
+        :param way: Way to add.
 
-        :return: added way
+        :return: Added way.
         """
         self.ways[way.way_id] = way
         if way.way_id >= self.next_way_id:
@@ -163,34 +163,34 @@ class OSMFile(object):
 
     def add_way_from_coords(self, coords: list[Coord], tags: dict[str, Any] = None) -> OSMWay:
         """
-        Adds way given the coords of the nodes and tags
+        Adds a way from node coordinates and tags.
 
-        :param coords: coords of the nodes on the way
-        :param tags: tags of the way
+        :param coords: Coordinates of the nodes on the way.
+        :param tags: Way tags.
 
-        :return: added way
+        :return: Added way.
         """
         return self.add_way_from_nodes(coords, tags)
 
     def add_way_from_node_ids(self, node_ids: list[int], tags: dict[str, Any] = None) -> OSMWay:
         """
-        Adds way given the ids of the nodes and tags
+        Adds a way from node IDs and tags.
 
-        :param node_ids: ids of the nodes on the way
-        :param tags: tags of the way
+        :param node_ids: IDs of the nodes on the way.
+        :param tags: Way tags.
 
-        :return: added way
+        :return: Added way.
         """
         return self.add_way_from_nodes(node_ids, tags)
 
     def add_way_from_nodes(self, elements: list[OSMNode | Coord | int], tags: dict[str, Any] = None) -> OSMWay:
         """
-        Adds way given list of the nodes, the coords, or the ids of the nodes and tags
+        Adds a way from nodes, coordinates, or node IDs and tags.
 
-        :param elements: a list of the nodes, the coords, or the ids of the nodes on the way
-        :param tags: tags of the way
+        :param elements: Nodes, coordinates, or node IDs that make up the way.
+        :param tags: Way tags.
 
-        :return: added way
+        :return: Added way.
         """
         node_ids = []
         for elem in elements:
@@ -204,9 +204,9 @@ class OSMFile(object):
 
     def write(self, filename: str):
         """
-        Writes this OSM file instance to the given file name
+        Writes this OSM file to the given path.
 
-        :param filename: file path to write into
+        :param filename: Destination file path.
         """
         root = lxml.etree.Element("osm")
         root.attrib.update({

{plexus_python_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/src/plexus/pulse/common/carto/OSMNode.py

@@ -11,11 +11,11 @@ class OSMNode(object):
 
     def __init__(self, node_id: int, coord: Coord, tags: OSMTags):
         """
-        Creates an instance from the given node id, coord, and tags
+        Creates an OSM node from the given ID, coordinate, and tags.
 
-        :param node_id: id
-        :param coord: node coordinate
-        :param tags: tags
+        :param node_id: Node ID.
+        :param coord: Node coordinate.
+        :param tags: Node tags.
         """
         self.node_id = node_id
         self.coord = coord

{plexus_python_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/src/plexus/pulse/common/carto/OSMTags.py

@@ -12,11 +12,11 @@ class OSMTags(object):
     @classmethod
     def from_any_tags(cls, any_tags: dict[str, Any] = None) -> Self:
         """
-        Creates an instance from any-typed tags by automatically inferring data types
+        Creates an OSM tag collection from values with inferred data types.
 
-        :param any_tags: tags with any-typed values
+        :param any_tags: Tags whose values may have any supported type.
 
-        :return: OSM tag instance
+        :return: OSM tag collection.
         """
         if any_tags is None:
             return OSMTags({})
@@ -24,9 +24,9 @@ class OSMTags(object):
 
     def __init__(self, tags: dict[str, Any]):
         """
-        Creates an instance from the given tags
+        Creates an OSM tag collection from string tags.
 
-        :param tags: given tags
+        :param tags: Tags to store.
         """
         self.tags = tags
 

{plexus_python_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/src/plexus/pulse/common/carto/OSMWay.py

@@ -10,11 +10,11 @@ class OSMWay(object):
 
     def __init__(self, way_id: int, node_ids: list[int], tags: OSMTags):
         """
-        Creates an instance from the given way id, node ids, and tags
+        Creates an OSM way from the given ID, node IDs, and tags.
 
-        :param way_id: id
-        :param node_ids: nodes ids
-        :param tags: tags
+        :param way_id: Way ID.
+        :param node_ids: Node IDs that make up the way.
+        :param tags: Way tags.
         """
         self.way_id = way_id
         self.node_ids = node_ids

{plexus_python_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/src/plexus/pulse/common/utils/bagutils.py

@@ -150,10 +150,10 @@ class BagReader(AbstractContextManager, BagIOBase):
         """
         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 db_dir: Directory containing the SQLite DB file.
+        :param db_filename: SQLite DB filename to read. Default is "bag.db".
+        :param kwargs: Additional keyword arguments to pass to the ``BagReader`` constructor.
+        :return: A ``BagReader`` instance.
         """
         return BagReader(make_path(db_dir) / db_filename)
 
@@ -161,7 +161,7 @@ class BagReader(AbstractContextManager, BagIOBase):
         """
         Creates a ``BagReader`` instance to read messages from a ROS2 bag file.
 
-        :param bag_file_path: path to the SQLite DB file to read.
+        :param bag_file_path: Path to the SQLite DB file to read.
         """
         super().__init__(bag_file_path)
 
@@ -204,10 +204,10 @@ class BagWriter(AbstractContextManager, BagIOBase):
         """
         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 db_dir: Directory where the SQLite DB file will be created.
+        :param db_filename: SQLite DB filename to create. Default is "bag.db".
+        :param kwargs: Additional keyword arguments to pass to the ``BagWriter`` constructor.
+        :return: A ``BagWriter`` instance.
         """
         return BagWriter(make_path(db_dir) / db_filename, **kwargs)
 
@@ -215,13 +215,13 @@ class BagWriter(AbstractContextManager, BagIOBase):
         """
         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
+        :param bag_file_path: Path to the SQLite DB file to create.
+        :param overwrite: Whether to replace 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 exist_ok: Whether to allow an existing SQLite DB file. 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_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/src/plexus/pulse/common/utils/gisutils.py

@@ -57,9 +57,9 @@ class Pose(object):
     @classmethod
     def interpolate(cls, a: Self, b: Self, t: float) -> Self:
         """
-        Interpolates between two given poses, as a * t + b * (1 - t)
+        Interpolates between two poses using ``a * t + b * (1 - t)``.
 
-        :return: interpolated pose
+        :return: Interpolated pose.
         """
         ts = a.ts + (b.ts - a.ts) * t
         p = a.p + (b.p - a.p) * t
@@ -68,11 +68,11 @@ class Pose(object):
 
     def __init__(self, ts: float, p: np.ndarray, q: np.ndarray):
         """
-        Represents a pose
+        Represents a timestamped pose.
 
-        :param ts: timestamp
-        :param p: position vector
-        :param q: orientation quaternion
+        :param ts: Pose timestamp.
+        :param p: Position vector.
+        :param q: Orientation quaternion.
         """
         self.ts = ts
         self.p = p
@@ -80,9 +80,9 @@ class Pose(object):
 
     def matrix(self) -> np.ndarray:
         """
-        Returns the transformation matrix of this pose
+        Returns the transformation matrix for this pose.
 
-        :return: transformation matrix
+        :return: Transformation matrix.
         """
         r = pyquat.Quaternion(self.q).rotation_matrix
         t = self.p[:, None]
@@ -90,21 +90,21 @@ class Pose(object):
 
     def translate(self, v: np.ndarray) -> np.ndarray:
         """
-        Translate the given vector with the pose position
+        Translates the given vector by the pose position.
 
-        :param v: the vector to be translated
+        :param v: Vector to translate.
 
-        :return: translated vector
+        :return: Translated vector.
         """
         return self.p + v
 
     def rotate(self, v: np.ndarray) -> np.ndarray:
         """
-        Rotates the given vector with the pose orientation
+        Rotates the given vector by the pose orientation.
 
-        :param v: the vector to be rotated
+        :param v: Vector to rotate.
 
-        :return: rotated vector
+        :return: Rotated vector.
         """
         return pyquat.Quaternion(self.q).rotate(v)
 
@@ -134,24 +134,24 @@ class Proj(ABC):
     @abstractmethod
     def from_latlon(self, lat: float, lon: float) -> tuple[float, float]:
         """
-        Performs forward projection from latitude/longitude to projection coordinate system
+        Projects latitude and longitude into the projection coordinate system.
 
-        :param lat: latitude
-        :param lon: longitude
+        :param lat: Latitude.
+        :param lon: Longitude.
 
-        :return: tuple of x and y in projection coordinate system
+        :return: Projected ``x`` and ``y`` coordinates.
         """
         pass
 
     @abstractmethod
     def to_latlon(self, x: float, y: float) -> tuple[float, float]:
         """
-        Performs inverse projection from projection coordinate system to latitude/longitude
+        Converts projection coordinates back to latitude and longitude.
 
-        :param x: x in projection coordinate system
-        :param y: y in projection coordinate system
+        :param x: X coordinate in the projection coordinate system.
+        :param y: Y coordinate in the projection coordinate system.
 
-        :return: tuple of latitude and longitude
+        :return: Latitude and longitude.
         """
         pass
 
@@ -301,11 +301,11 @@ def default_proj() -> Proj:
 
 def make_proj(spec_str: str) -> Proj | None:
     """
-    Constructs cartographic projection from the given name and arguments
+    Constructs a cartographic projection from a projection spec string.
 
-    :param spec_str: projection spec string
+    :param spec_str: Projection spec string.
 
-    :return: projection
+    :return: Cartographic projection, or ``None`` when no spec is provided.
     """
 
     if spec_str is None:
@@ -333,27 +333,27 @@ class Coord(object):
     @classmethod
     def from_pose(cls, pose: Pose, proj: Proj | None) -> Self:
         """
-        Creates a coord from given pose
+        Creates a coordinate from a pose.
 
-        :param pose: pose based on which the coord is created
-        :param proj: cartographic projection
+        :param pose: Pose to convert.
+        :param proj: Cartographic projection to use.
 
-        :return: generated coord
+        :return: Generated coordinate.
         """
         return cls.from_xy(pose.p[0], pose.p[1], pose.p[2], proj, pose.ts)
 
     @classmethod
     def from_latlon(cls, lat: float, lon: float, ele: float, proj: Proj | None, ts: float = 0) -> Self:
         """
-        Creates a coord from latitude/longitude
+        Creates a coordinate from latitude and longitude.
 
-        :param lat: latitude
-        :param lon: longitude
-        :param ele: elevation
-        :param proj: cartographic projection
-        :param ts: timestamp
+        :param lat: Latitude.
+        :param lon: Longitude.
+        :param ele: Elevation.
+        :param proj: Cartographic projection to use.
+        :param ts: Timestamp.
 
-        :return: generated coord
+        :return: Generated coordinate.
         """
         if proj is None:
             return Coord(ts, lat, lon, ele, 0.0, 0.0, pdt.BaseModel())
@@ -364,15 +364,15 @@ class Coord(object):
     @classmethod
     def from_xy(cls, x: float, y: float, ele: float, proj: Proj | None, ts: float = 0) -> Self:
         """
-        Creates a coord from coordinate in cartographic projection
+        Creates a coordinate from projected coordinates.
 
-        :param x: x coordinate in cartographic projection
-        :param y: y coordinate in cartographic projection
-        :param ele: elevation
-        :param proj: cartographic projection
-        :param ts: timestamp
+        :param x: X coordinate in cartographic projection.
+        :param y: Y coordinate in cartographic projection.
+        :param ele: Elevation.
+        :param proj: Cartographic projection to use.
+        :param ts: Timestamp.
 
-        :return: a coord
+        :return: Generated coordinate.
         """
         if proj is None:
             return Coord(ts, 0.0, 0.0, ele, x, y, pdt.BaseModel())
@@ -382,15 +382,15 @@ class Coord(object):
 
     def __init__(self, ts: float, lat: float, lon: float, ele: float, x: float, y: float, spec: pdt.BaseModel):
         """
-        Represents a coordinate
-
-        :param ts: timestamp
-        :param lat: latitude
-        :param lon: longitude
-        :param ele: elevation
-        :param x: x in projection coordinate system
-        :param y: y in projection coordinate system
-        :param spec: projection specification
+        Represents a timestamped coordinate.
+
+        :param ts: Timestamp.
+        :param lat: Latitude.
+        :param lon: Longitude.
+        :param ele: Elevation.
+        :param x: X coordinate in the projection coordinate system.
+        :param y: Y coordinate in the projection coordinate system.
+        :param spec: Projection specification.
         """
         self.ts = ts
         self.lat = lat

{plexus_python_pulse_common-1.1.79 → plexus_python_pulse_common-1.1.81}/src/plexus/pulse/common/utils/pathutils.py

@@ -40,7 +40,7 @@ def make_trivial_volume_func() -> Callable[[str], int]:
     value each time the function is called with the same name. If a new name is provided,
     a new generator is created for that name.
 
-    :return: a callable function that takes a name (str) and returns the next integer volume.
+    :return: Callable that takes a name (str) and returns the next integer volume.
     """
 
     def trivial_volume_generator() -> Generator[int, None, None]:
@@ -67,12 +67,11 @@ def make_volume_parser(template: str) -> Callable[[str], dict[str, int]]:
     The returned parser function takes a filename as input and extracts the volume values
     as a dictionary where the keys are the placeholder names and the values are the corresponding integers.
 
-    :param template: a string template defining the filename structure with placeholders for volumes.
+    :param template: String template defining the filename structure with volume placeholders.
                      Placeholders are enclosed in double curly braces `{{}}` and can optionally include
                      a name, a prefix, and a suffix (e.g., `{name:prefix{}suffix}`).
 
-    :return: a callable function that takes a filename (str) and returns a dictionary mapping
-             placeholder names to their extracted integer values.
+    :return: Callable that takes a filename (str) and returns extracted integer values keyed by placeholder name.
 
     :raises ValueError: if the template is invalid or cannot be parsed.
     """
@@ -128,13 +127,12 @@ def make_volume_generator(template: str) -> Callable[[Callable[[str], int]], tup
     The returned generator function takes a volume function as input, which determines the
     volume values for each placeholder, and produces filenames with the corresponding volumes.
 
-    :param template: a string template defining the filename structure with placeholders for volumes.
+    :param template: String template defining the filename structure with volume placeholders.
                      Placeholders are enclosed in double curly braces `{{}}` and can optionally include
                      a name, a prefix, and a suffix (e.g., `{name:prefix{}suffix}`).
 
-    :return: a callable generator function that takes a volume function (Callable[[str], int]) as input
-             and returns a tuple containing the generated filename (str) and a dictionary mapping
-             placeholder names to their corresponding volume values (dict[str, int]).
+    :return: Callable generator that takes a volume function (Callable[[str], int]) and returns the generated
+             filename (str) with the volume values keyed by placeholder name (dict[str, int]).
 
     :raises ValueError: if the template is invalid or cannot be parsed.
     """
@@ -181,13 +179,12 @@ def collect_volumed_filenames(template: str) -> Generator[tuple[str, dict[str, i
     This function scans the folder containing the template and attempts to parse filenames
     to extract volume values based on the template.
 
-    :param template: a string template defining the filename structure with placeholders for volumes.
+    :param template: String template defining the filename structure with volume placeholders.
                      Placeholders are enclosed in double curly braces `{{}}` and can optionally include
                      a name, a prefix, and a suffix (e.g., `{name:prefix{}suffix}`).
 
-    :return: a generator yielding tuples where the first element is the full path of the filename
-             and the second element is a dictionary mapping placeholder names to their extracted
-             integer volume values.
+    :return: Generator yielding each matching filename path and its extracted integer volume values keyed by
+             placeholder name.
     """
     folder = os.path.dirname(template)
     basename = os.path.basename(template)
@@ -214,14 +211,13 @@ def populate_volumed_filenames(
     This function uses a volume function to generate unique volume values for each placeholder
     and produces filenames with the corresponding volumes.
 
-    :param template: a string template defining the filename structure with placeholders for volumes.
+    :param template: String template defining the filename structure with volume placeholders.
                      Placeholders are enclosed in double curly braces `{{}}` and can optionally include
                      a name, a prefix, and a suffix (e.g., `{name:prefix{}suffix}`).
-    :param volume_func: a callable function that takes a placeholder name (str) and returns the next
-                        integer volume value. If not provided, a trivial volume function is used.
+    :param volume_func: Callable that takes a placeholder name (str) and returns the next integer volume value.
+                        If not provided, a trivial volume function is used.
 
-    :return: a generator yielding tuples where the first element is the generated filename (str)
-             and the second element is a dictionary mapping placeholder names to their corresponding
+    :return: Generator yielding each generated filename and its volume values keyed by placeholder name.
     """
     folder = os.path.dirname(template)
     basename = os.path.basename(template)