mm-std 0.5.4__py3-none-any.whl → 0.7.0__py3-none-any.whl

mm_std/__init__.py

@@ -1,24 +1,21 @@
-from .date_utils import parse_date, utc_delta, utc_now
-from .dict_utils import replace_empty_dict_entries
-from .json_utils import ExtendedJSONEncoder, json_dumps
-from .random_utils import random_datetime, random_decimal
-from .str_utils import parse_lines, str_contains_any, str_ends_with_any, str_starts_with_any
-from .subprocess_utils import ShellResult, shell, ssh_shell  # nosec
+"""mm-std: Python utilities for common data manipulation tasks."""
 
-__all__ = [
-    "ExtendedJSONEncoder",
-    "ShellResult",
-    "json_dumps",
-    "parse_date",
-    "parse_lines",
-    "random_datetime",
-    "random_decimal",
-    "replace_empty_dict_entries",
-    "shell",
-    "ssh_shell",
-    "str_contains_any",
-    "str_ends_with_any",
-    "str_starts_with_any",
-    "utc_delta",
-    "utc_now",
-]
+from .date_utils import parse_datetime as parse_datetime
+from .date_utils import utc_from_timestamp as utc_from_timestamp
+from .date_utils import utc_now as utc_now
+from .date_utils import utc_now_offset as utc_now_offset
+from .dict_utils import compact_dict as compact_dict
+from .json_utils import ExtendedJSONEncoder as ExtendedJSONEncoder
+from .json_utils import json_dumps as json_dumps
+from .random_utils import random_datetime as random_datetime
+from .random_utils import random_datetime_offset as random_datetime_offset
+from .random_utils import random_decimal as random_decimal
+from .str_utils import parse_lines as parse_lines
+from .str_utils import str_contains_any as str_contains_any
+from .str_utils import str_ends_with_any as str_ends_with_any
+from .str_utils import str_starts_with_any as str_starts_with_any
+
+# B404: re-exporting subprocess utilities with documented security considerations
+from .subprocess_utils import CmdResult as CmdResult  # nosec
+from .subprocess_utils import run_cmd as run_cmd  # nosec
+from .subprocess_utils import run_ssh_cmd as run_ssh_cmd  # nosec

mm_std/date_utils.py

@@ -1,3 +1,5 @@
+"""UTC-focused datetime operations and flexible date parsing."""
+
 from datetime import UTC, datetime, timedelta
 
 
@@ -6,37 +8,38 @@ def utc_now() -> datetime:
     return datetime.now(UTC)
 
 
-def utc_delta(
-    *,
-    days: int | None = None,
-    hours: int | None = None,
-    minutes: int | None = None,
-    seconds: int | None = None,
+def utc_now_offset(
+    *, days: int | None = None, hours: int | None = None, minutes: int | None = None, seconds: int | None = None
 ) -> datetime:
     """Get UTC time shifted by the specified delta.
 
     Use negative values to get time in the past.
     """
     params = {}
-    if days:
+    if days is not None:
         params["days"] = days
-    if hours:
+    if hours is not None:
         params["hours"] = hours
-    if minutes:
+    if minutes is not None:
         params["minutes"] = minutes
-    if seconds:
+    if seconds is not None:
         params["seconds"] = seconds
     return datetime.now(UTC) + timedelta(**params)
 
 
-def parse_date(value: str, ignore_tz: bool = False) -> datetime:
+def utc_from_timestamp(timestamp: float) -> datetime:
+    """Create UTC datetime from Unix timestamp."""
+    return datetime.fromtimestamp(timestamp, UTC)
+
+
+def parse_datetime(date_str: str, ignore_tz: bool = False) -> datetime:
     """Parse date string in various formats, with timezone handling.
 
     Converts 'Z' suffix to '+00:00' for ISO format compatibility.
     Use ignore_tz=True to strip timezone info from the result.
     """
-    if value.lower().endswith("z"):
-        value = value[:-1] + "+00:00"
+    if date_str.lower().endswith("z"):
+        date_str = date_str[:-1] + "+00:00"
     date_formats = [
         "%Y-%m-%d %H:%M:%S.%f%z",
         "%Y-%m-%dT%H:%M:%S.%f%z",
@@ -53,10 +56,10 @@ def parse_date(value: str, ignore_tz: bool = False) -> datetime:
 
     for fmt in date_formats:
         try:
-            dt = datetime.strptime(value, fmt)  # noqa: DTZ007
+            dt = datetime.strptime(date_str, fmt)  # noqa: DTZ007 - timezone deliberately ignored when ignore_tz=True
             if ignore_tz and dt.tzinfo is not None:
                 dt = dt.replace(tzinfo=None)
-            return dt  # noqa: TRY300
+            return dt  # noqa: TRY300 - return in try block is intentional for parse flow
         except ValueError:
             continue
-    raise ValueError(f"Time data '{value}' does not match any known format.")
+    raise ValueError(f"Time data '{date_str}' does not match any known format.")

mm_std/dict_utils.py

@@ -1,3 +1,5 @@
+"""Dictionary manipulation utilities with type preservation."""
+
 from collections import OrderedDict, defaultdict
 from collections.abc import Mapping, MutableMapping
 from decimal import Decimal
@@ -8,8 +10,8 @@ V = TypeVar("V")
 
 
 @overload
-def replace_empty_dict_entries(
-    data: defaultdict[K, V],
+def compact_dict(
+    mapping: defaultdict[K, V],
     defaults: Mapping[K, V] | None = None,
     treat_zero_as_empty: bool = False,
     treat_false_as_empty: bool = False,
@@ -18,8 +20,8 @@ def replace_empty_dict_entries(
 
 
 @overload
-def replace_empty_dict_entries(
-    data: OrderedDict[K, V],
+def compact_dict(
+    mapping: OrderedDict[K, V],
     defaults: Mapping[K, V] | None = None,
     treat_zero_as_empty: bool = False,
     treat_false_as_empty: bool = False,
@@ -28,8 +30,8 @@ def replace_empty_dict_entries(
 
 
 @overload
-def replace_empty_dict_entries(
-    data: dict[K, V],
+def compact_dict(
+    mapping: dict[K, V],
     defaults: Mapping[K, V] | None = None,
     treat_zero_as_empty: bool = False,
     treat_false_as_empty: bool = False,
@@ -37,15 +39,14 @@ def replace_empty_dict_entries(
 ) -> dict[K, V]: ...
 
 
-def replace_empty_dict_entries(
-    data: MutableMapping[K, V],
+def compact_dict(
+    mapping: MutableMapping[K, V],
     defaults: Mapping[K, V] | None = None,
     treat_zero_as_empty: bool = False,
     treat_false_as_empty: bool = False,
     treat_empty_string_as_empty: bool = True,
 ) -> MutableMapping[K, V]:
-    """
-    Replace empty entries in a dictionary with defaults or remove them entirely.
+    """Replace empty entries in a dictionary with defaults or remove them entirely.
 
     Preserves the exact type of the input mapping:
     - dict[str, int] → dict[str, int]
@@ -53,7 +54,7 @@ def replace_empty_dict_entries(
     - OrderedDict[str, str] → OrderedDict[str, str]
 
     Args:
-        data: The dictionary to process
+        mapping: The dictionary to process
         defaults: Default values to use for empty entries. If None or key not found, empty entries are removed
         treat_zero_as_empty: Treat 0 as empty value
         treat_false_as_empty: Treat False as empty value
@@ -61,16 +62,17 @@ def replace_empty_dict_entries(
 
     Returns:
         New dictionary of the same concrete type with empty entries replaced or removed
+
     """
     if defaults is None:
         defaults = {}
 
-    if isinstance(data, defaultdict):
-        result: MutableMapping[K, V] = defaultdict(data.default_factory)
+    if isinstance(mapping, defaultdict):
+        result: MutableMapping[K, V] = defaultdict(mapping.default_factory)
     else:
-        result = data.__class__()
+        result = mapping.__class__()
 
-    for key, value in data.items():
+    for key, value in mapping.items():
         should_replace = (
             value is None
             or (treat_false_as_empty and value is False)

mm_std/json_utils.py

@@ -1,4 +1,4 @@
-from __future__ import annotations
+"""Extended JSON encoder with support for Python types."""
 
 import json
 from collections.abc import Callable
@@ -35,47 +35,50 @@ class ExtendedJSONEncoder(json.JSONEncoder):
     }
 
     @classmethod
-    def register(cls, type_: type[Any], serializer: Callable[[Any], Any]) -> None:
+    def register(cls, type_: type[Any], handler: Callable[[Any], Any]) -> None:
         """Register a custom type with its serialization function.
 
         Args:
             type_: The type to register
-            serializer: Function that converts objects of this type to JSON-serializable data
+            handler: Function that converts objects of this type to JSON-serializable data
 
         Raises:
             ValueError: If type_ is a built-in JSON type
+
         """
         if type_ in (str, int, float, bool, list, dict, type(None)):
             raise ValueError(f"Cannot override built-in JSON type: {type_.__name__}")
-        cls._type_handlers[type_] = serializer
+        cls._type_handlers[type_] = handler
 
-    def default(self, obj: Any) -> Any:  # noqa: ANN401
+    def default(self, o: Any) -> Any:  # noqa: ANN401 - Any required for generic JSON encoding
+        """Encode object to JSON-serializable format."""
         # Check registered type handlers first
         for type_, handler in self._type_handlers.items():
-            if isinstance(obj, type_):
-                return handler(obj)
+            if isinstance(o, type_):
+                return handler(o)
 
         # Special case: dataclasses (requires is_dataclass check, not isinstance)
-        if is_dataclass(obj) and not isinstance(obj, type):
-            return asdict(obj)  # Don't need recursive serialization
+        if is_dataclass(o) and not isinstance(o, type):
+            return asdict(o)  # Don't need recursive serialization
 
-        return super().default(obj)
+        return super().default(o)
 
 
-def json_dumps(data: Any, type_handlers: dict[type[Any], Callable[[Any], Any]] | None = None, **kwargs: Any) -> str:  # noqa: ANN401
+def json_dumps(obj: Any, type_handlers: dict[type[Any], Callable[[Any], Any]] | None = None, **kwargs: Any) -> str:  # noqa: ANN401 - Any required for generic type handler
     """Serialize object to JSON with extended type support.
 
     Unlike standard json.dumps, uses ExtendedJSONEncoder which automatically handles
     UUID, Decimal, Path, datetime, dataclasses, enums, pydantic models, and other Python types.
 
     Args:
-        data: Object to serialize to JSON
+        obj: Object to serialize to JSON
         type_handlers: Optional additional type handlers for this call only.
                       These handlers take precedence over default ones.
         **kwargs: Additional arguments passed to json.dumps
 
     Returns:
         JSON string representation
+
     """
     if type_handlers:
         # Type narrowing for mypy
@@ -83,7 +86,7 @@ def json_dumps(data: Any, type_handlers: dict[type[Any], Callable[[Any], Any]] |
 
         class TemporaryEncoder(ExtendedJSONEncoder):
             _type_handlers: ClassVar[dict[type[Any], Callable[[Any], Any]]] = {
-                **ExtendedJSONEncoder._type_handlers,  # noqa: SLF001
+                **ExtendedJSONEncoder._type_handlers,  # noqa: SLF001 - accessing class internals for type handler inheritance
                 **handlers,
             }
 
@@ -91,14 +94,14 @@ def json_dumps(data: Any, type_handlers: dict[type[Any], Callable[[Any], Any]] |
     else:
         encoder_cls = ExtendedJSONEncoder
 
-    return json.dumps(data, cls=encoder_cls, **kwargs)
+    return json.dumps(obj, cls=encoder_cls, **kwargs)
 
 
 def _auto_register_optional_types() -> None:
     """Register handlers for optional dependencies if available."""
     # Pydantic models
     try:
-        from pydantic import BaseModel  # type: ignore[import-not-found]  # noqa: PLC0415
+        from pydantic import BaseModel  # noqa: PLC0415 - optional pydantic import at runtime
 
         ExtendedJSONEncoder.register(BaseModel, lambda obj: obj.model_dump())
     except ImportError:

mm_std/random_utils.py

@@ -1,3 +1,5 @@
+"""Type-safe random generation for decimals and datetimes."""
+
 import random
 from datetime import datetime, timedelta
 from decimal import Decimal
@@ -18,6 +20,7 @@ def random_decimal(from_value: Decimal, to_value: Decimal) -> Decimal:
 
     Raises:
         ValueError: If from_value > to_value
+
     """
     if from_value > to_value:
         raise ValueError("from_value must be <= to_value")
@@ -37,14 +40,33 @@ def random_decimal(from_value: Decimal, to_value: Decimal) -> Decimal:
     return Decimal(random_int) / Decimal(multiplier)
 
 
-def random_datetime(
-    from_time: datetime,
-    *,
-    hours: int = 0,
-    minutes: int = 0,
-    seconds: int = 0,
-) -> datetime:
-    """Generate a random datetime within a specified time range.
+def random_datetime(from_time: datetime, to_time: datetime) -> datetime:
+    """Generate a random datetime between from_time and to_time.
+
+    Args:
+        from_time: Minimum datetime (inclusive)
+        to_time: Maximum datetime (inclusive)
+
+    Returns:
+        Random datetime in the specified range
+
+    Raises:
+        ValueError: If from_time > to_time
+
+    """
+    if from_time > to_time:
+        raise ValueError("from_time must be <= to_time")
+
+    delta = (to_time - from_time).total_seconds()
+    if delta == 0:
+        return from_time
+
+    random_seconds = random.uniform(0, delta)  # nosec B311
+    return from_time + timedelta(seconds=random_seconds)
+
+
+def random_datetime_offset(from_time: datetime, *, hours: int = 0, minutes: int = 0, seconds: int = 0) -> datetime:
+    """Generate a random datetime within a specified offset from base time.
 
     Returns a random datetime between from_time and from_time + offset,
     where offset is calculated from the provided hours, minutes, and seconds.
@@ -60,13 +82,10 @@ def random_datetime(
 
     Raises:
         ValueError: If any offset value is negative
+
     """
     if hours < 0 or minutes < 0 or seconds < 0:
-        raise ValueError("Range values must be non-negative")
+        raise ValueError("Offset values must be non-negative")
 
     total_seconds = hours * 3600 + minutes * 60 + seconds
-    if total_seconds == 0:
-        return from_time
-
-    random_seconds = random.uniform(0, total_seconds)  # nosec B311
-    return from_time + timedelta(seconds=random_seconds)
+    return random_datetime(from_time, from_time + timedelta(seconds=total_seconds))

mm_std/str_utils.py

@@ -1,3 +1,5 @@
+"""String matching utilities and multiline text parsing."""
+
 from collections.abc import Iterable
 
 
@@ -16,12 +18,7 @@ def str_contains_any(value: str, substrings: Iterable[str]) -> bool:
     return any(substring in value for substring in substrings)
 
 
-def parse_lines(
-    text: str,
-    lowercase: bool = False,
-    remove_comments: bool = False,
-    deduplicate: bool = False,
-) -> list[str]:
+def parse_lines(text: str, lowercase: bool = False, remove_comments: bool = False, deduplicate: bool = False) -> list[str]:
     """Parse multiline text into a list of cleaned lines.
 
     Args:
@@ -32,6 +29,7 @@ def parse_lines(
 
     Returns:
         List of non-empty, stripped lines after applying specified transformations
+
     """
     if lowercase:
         text = text.lower()

mm_std/subprocess_utils.py

@@ -1,19 +1,16 @@
+"""Safe shell command execution with result handling."""
+
 import shlex
 import subprocess  # nosec
 from dataclasses import dataclass
 
 TIMEOUT_EXIT_CODE = 255
+"""Exit code returned when command execution times out."""
 
 
 @dataclass
-class ShellResult:
-    """Result of shell command execution.
-
-    Args:
-        stdout: Standard output from the command
-        stderr: Standard error from the command
-        code: Exit code of the command
-    """
+class CmdResult:
+    """Result of command execution."""
 
     stdout: str
     stderr: str
@@ -31,31 +28,66 @@ class ShellResult:
             result += self.stderr
         return result
 
+    @property
+    def is_success(self) -> bool:
+        """True if command completed successfully (exit code 0)."""
+        return self.code == 0
+
+    @property
+    def is_timeout(self) -> bool:
+        """True if command timed out."""
+        return self.code == TIMEOUT_EXIT_CODE
+
 
-def shell(cmd: str, timeout: int | None = 60, capture_output: bool = True, echo_command: bool = False) -> ShellResult:
-    """Execute a shell command.
+def run_cmd(
+    cmd: str, timeout: int | None = 60, capture_output: bool = True, echo_command: bool = False, shell: bool = False
+) -> CmdResult:
+    """Execute a command.
 
     Args:
         cmd: Command to execute
         timeout: Timeout in seconds, None for no timeout
         capture_output: Whether to capture stdout/stderr
         echo_command: Whether to print the command before execution
+        shell: If False (default), the command is parsed with shlex.split() and
+            executed without shell interpretation. Special characters like
+            backticks, $(), pipes (|), redirects (>, <), and wildcards (*) are
+            treated as literal text. This is the safe mode for commands with
+            user input.
+            If True, the command is passed to the shell as-is, enabling pipes,
+            redirects, command substitution, and other shell features. Use this
+            only for trusted commands that need shell functionality.
 
     Returns:
-        ShellResult with stdout, stderr and exit code
+        CmdResult with stdout, stderr and exit code
+
     """
     if echo_command:
-        print(cmd)  # noqa: T201
+        print(cmd)  # noqa: T201 - print is intentional for echo_command feature
     try:
-        process = subprocess.run(cmd, timeout=timeout, capture_output=capture_output, shell=True, check=False)  # noqa: S602 # nosec
+        if shell:
+            process = subprocess.run(  # noqa: S602 # nosec - shell=True required for pipe support
+                cmd, timeout=timeout, capture_output=capture_output, shell=True, check=False
+            )
+        else:
+            process = subprocess.run(  # noqa: S603 # nosec - subprocess with shell=False is safe
+                shlex.split(cmd), timeout=timeout, capture_output=capture_output, shell=False, check=False
+            )
         stdout = process.stdout.decode("utf-8", errors="replace") if capture_output else ""
         stderr = process.stderr.decode("utf-8", errors="replace") if capture_output else ""
-        return ShellResult(stdout=stdout, stderr=stderr, code=process.returncode)
+        return CmdResult(stdout=stdout, stderr=stderr, code=process.returncode)
     except subprocess.TimeoutExpired:
-        return ShellResult(stdout="", stderr="timeout", code=TIMEOUT_EXIT_CODE)
+        return CmdResult(stdout="", stderr="timeout", code=TIMEOUT_EXIT_CODE)
 
 
-def ssh_shell(host: str, cmd: str, ssh_key_path: str | None = None, timeout: int = 60, echo_command: bool = False) -> ShellResult:
+def run_ssh_cmd(
+    host: str,
+    cmd: str,
+    ssh_key_path: str | None = None,
+    timeout: int = 60,
+    echo_command: bool = False,
+    strict_host_key_checking: bool | None = None,
+) -> CmdResult:
     """Execute a command on remote host via SSH.
 
     Args:
@@ -64,12 +96,18 @@ def ssh_shell(host: str, cmd: str, ssh_key_path: str | None = None, timeout: int
         ssh_key_path: Path to SSH private key file
         timeout: Timeout in seconds
         echo_command: Whether to print the command before execution
+        strict_host_key_checking: If True/False, explicitly set StrictHostKeyChecking.
+            If None, leave SSH defaults unchanged.
 
     Returns:
-        ShellResult with stdout, stderr and exit code
+        CmdResult with stdout, stderr and exit code
+
     """
-    ssh_cmd = "ssh -o 'StrictHostKeyChecking=no' -o 'LogLevel=ERROR'"
+    ssh_cmd = "ssh -o 'LogLevel=ERROR'"
+    if strict_host_key_checking is not None:
+        option_value = "yes" if strict_host_key_checking else "no"
+        ssh_cmd += f" -o 'StrictHostKeyChecking={option_value}'"
     if ssh_key_path:
         ssh_cmd += f" -i {shlex.quote(ssh_key_path)}"
     ssh_cmd += f" {shlex.quote(host)} {shlex.quote(cmd)}"
-    return shell(ssh_cmd, timeout=timeout, echo_command=echo_command)
+    return run_cmd(ssh_cmd, timeout=timeout, echo_command=echo_command)

mm_std-0.7.0.dist-info/METADATA

@@ -0,0 +1,4 @@
+Metadata-Version: 2.4
+Name: mm-std
+Version: 0.7.0
+Requires-Python: >=3.14

mm_std-0.7.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mm_std/__init__.py,sha256=7hmdftEHF19ef6jtwVDH3J7vEZLV3j5ZgIksZTLd_l0,1161
+mm_std/date_utils.py,sha256=cGdTEXwsIQS6ZPTvjQRlkTTIf0yL2GCj_uYa8i0pzps,2117
+mm_std/dict_utils.py,sha256=bddxRbemL7UZ9rp7k2bkBDsYX-NbVXv8CPL7ESjPxXc,2882
+mm_std/json_utils.py,sha256=lOlleRdI9mdrB-s0nAfxiaQ5LTcbfEea2uObh0W-dzs,4196
+mm_std/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mm_std/random_utils.py,sha256=oGZhOg6rIft3SRpWv2lB6IAyvdWEN08-7BVrC5_vfoc,2889
+mm_std/str_utils.py,sha256=p6hxxoe3xiuPSqb1vc3TbNfUoSwdW6z_OJG_3Qx7ITA,1563
+mm_std/subprocess_utils.py,sha256=Sr8ENMg29CkhgpJi5PaW7h7tEviaEFurVJKcfR16itE,4057
+mm_std-0.7.0.dist-info/METADATA,sha256=scnEov8zndpkmqWOgIde_iVjbb-arHejeuiKDt7Csbg,74
+mm_std-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mm_std-0.7.0.dist-info/RECORD,,

{mm_std-0.5.4.dist-info → mm_std-0.7.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

mm_std-0.5.4.dist-info/METADATA

@@ -1,4 +0,0 @@
-Metadata-Version: 2.4
-Name: mm-std
-Version: 0.5.4
-Requires-Python: >=3.13

mm_std-0.5.4.dist-info/RECORD

@@ -1,11 +0,0 @@
-mm_std/__init__.py,sha256=V1na3dOxX52p44hOwhHFaIgrZEHR3yEjFdmSIcB2n0c,715
-mm_std/date_utils.py,sha256=aFdIacoNgDSPGeUkZihXZADd86TeHu4hr1uIT9zcqvw,1732
-mm_std/dict_utils.py,sha256=Gq_LYuidf24SWvzNmUx8wVPGuop9263GOxcIflB__uQ,2850
-mm_std/json_utils.py,sha256=NuDomTThfCkJBCmfQ6vkr7dvChKGsuLoAyLW0TON_dQ,3997
-mm_std/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mm_std/random_utils.py,sha256=3q5ZylCqfFHKN3VaDXuy4heo8C1jNbLHNNOFvyYJoZY,2253
-mm_std/str_utils.py,sha256=I6vVC81dGBDTHm7FxW-ka5OlUPjHmgagei7Zjld65lk,1520
-mm_std/subprocess_utils.py,sha256=6Bkw6ZYHT1NLIYbQUV9LGkBzUl5RtaVzMJiLJrTGq48,2507
-mm_std-0.5.4.dist-info/METADATA,sha256=SnanvJ0gBE6Y_5-dSOkUaH5BVV482k3KPXFhuUKeV5Q,74
-mm_std-0.5.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mm_std-0.5.4.dist-info/RECORD,,