mm-std 0.6.0__tar.gz → 0.7.0__tar.gz

{mm_std-0.6.0 → mm_std-0.7.0}/.claude/settings.local.json

@@ -8,7 +8,16 @@
       "mcp__ide__getDiagnostics",
       "Read(//Users/m/.vscode/extensions/ms-python.vscode-pylance-2025.7.1/dist/typeshed-fallback/stdlib/json/**)",
       "Bash(just lint)",
-      "Bash(python:*)"
+      "Bash(python:*)",
+      "Bash(wc:*)",
+      "Bash(pytest:*)",
+      "Bash(just test)",
+      "Bash(do echo \"=== $file ===\")",
+      "Bash(just audit:*)",
+      "Bash(test:*)",
+      "Bash(just test:*)",
+      "Bash(uv sync:*)",
+      "Bash(just:*)"
     ],
     "deny": []
   }

mm_std-0.7.0/CLAUDE.md

@@ -0,0 +1,18 @@
+# AI Agent Start Guide
+
+## Mandatory Rules (external)
+These files are REQUIRED. Read them fully and follow all rules.
+- `~/.claude/shared-rules/general.md`
+- `~/.claude/shared-rules/python.md`
+
+## Project Reading (context)
+These files are REQUIRED for project understanding.
+- `README.md`
+
+## Preflight (mandatory)
+Before your first response:
+1. Read all files listed above.
+2. Do not answer until all are read.
+3. In your first reply, list every file you have read from this document.
+
+Failure to follow this protocol is considered an error.

mm_std-0.7.0/PKG-INFO

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

{mm_std-0.6.0 → mm_std-0.7.0}/README.md

@@ -10,7 +10,6 @@ A collection of Python utilities for common data manipulation tasks with strict
 - **Random Utilities**: Type-safe random generation for decimals and datetimes
 - **String Utilities**: Efficient string matching utilities for prefixes, suffixes, and substrings, plus multiline text parsing
 - **Subprocess Utilities**: Safe shell command execution with comprehensive result handling
-- **Full Type Safety**: Strict mypy compliance with comprehensive type annotations
 
 ## Quick Start
 
@@ -78,34 +77,34 @@ parsed = parse_lines(
 Execute shell commands safely with comprehensive result handling:
 
 ```python
-from mm_std import shell, ssh_shell, ShellResult
+from mm_std import run_cmd, run_ssh_cmd, CmdResult
 
 # Execute local commands
-result = shell("ls -la /tmp")
+result = run_cmd("ls -la /tmp")
 print(f"Exit code: {result.code}")
 print(f"Output: {result.stdout}")
 print(f"Errors: {result.stderr}")
 print(f"Combined: {result.combined_output}")
 
 # Handle command errors gracefully
-result = shell("grep 'pattern' nonexistent.txt")
+result = run_cmd("grep 'pattern' nonexistent.txt")
 if result.code != 0:
     print(f"Command failed: {result.stderr}")
 
 # Execute with timeout
-result = shell("long-running-command", timeout=30)
+result = run_cmd("long-running-command", timeout=30)
 if result.code == 255:  # TIMEOUT_EXIT_CODE
     print("Command timed out")
 
 # Echo commands for debugging
-result = shell("echo 'Hello World'", echo_command=True)
+result = run_cmd("echo 'Hello World'", echo_command=True)
 
-# Complex shell operations with pipes
-result = shell("ps aux | grep python | wc -l")
+# Complex shell operations with pipes (requires shell=True)
+result = run_cmd("ps aux | grep python | wc -l", shell=True)
 python_processes = int(result.stdout.strip())
 
 # Execute commands on remote hosts via SSH
-ssh_result = ssh_shell(
+ssh_result = run_ssh_cmd(
     host="server.example.com",
     cmd="systemctl status nginx",
     ssh_key_path="~/.ssh/id_rsa",
@@ -113,7 +112,7 @@ ssh_result = ssh_shell(
 )
 
 # SSH commands are automatically quoted for security
-ssh_result = ssh_shell(
+ssh_result = run_ssh_cmd(
     "server.example.com",
     "echo 'hello world; ls -la'",  # Properly escaped
     echo_command=True
@@ -151,7 +150,7 @@ json_str = json_dumps(data, type_handlers={
 Clean up dictionaries by replacing or removing empty values:
 
 ```python
-from mm_std import replace_empty_dict_entries
+from mm_std import compact_dict
 
 data = {
     "name": "John",
@@ -162,16 +161,16 @@ data = {
 }
 
 # Remove empty entries entirely
-cleaned = replace_empty_dict_entries(data)
+cleaned = compact_dict(data)
 # Result: {"name": "John"}
 
 # Replace with defaults
 defaults = {"age": 25, "email": "unknown@example.com"}
-cleaned = replace_empty_dict_entries(data, defaults=defaults)
+cleaned = compact_dict(data, defaults=defaults)
 # Result: {"name": "John", "age": 25, "email": "unknown@example.com"}
 
 # Treat zero and false as empty too
-cleaned = replace_empty_dict_entries(
+cleaned = compact_dict(
     data,
     defaults=defaults,
     treat_zero_as_empty=True,
@@ -184,14 +183,14 @@ cleaned = replace_empty_dict_entries(
 UTC-focused datetime operations:
 
 ```python
-from mm_std import utc_now, utc_delta, parse_date
+from mm_std import utc_now, utc_now_offset, parse_datetime
 
 # Current UTC time
 now = utc_now()
 
 # Time calculations
-past = utc_delta(hours=-2, minutes=-30)
-future = utc_delta(days=7)
+past = utc_now_offset(hours=-2, minutes=-30)
+future = utc_now_offset(days=7)
 
 # Flexible date parsing
 dates = [
@@ -201,10 +200,10 @@ dates = [
     "2023/12/25"
 ]
 
-parsed_dates = [parse_date(d) for d in dates]
+parsed_dates = [parse_datetime(d) for d in dates]
 
 # Parse and ignore timezone info
-local_time = parse_date("2023-12-25T10:30:00+02:00", ignore_tz=True)
+local_time = parse_datetime("2023-12-25T10:30:00+02:00", ignore_tz=True)
 ```
 
 ### Random Utilities
@@ -212,16 +211,21 @@ local_time = parse_date("2023-12-25T10:30:00+02:00", ignore_tz=True)
 Generate random values with precision:
 
 ```python
-from mm_std import random_decimal, random_datetime
+from mm_std import random_decimal, random_datetime, random_datetime_offset
 from decimal import Decimal
-from datetime import datetime
+from datetime import datetime, timedelta
 
 # Random decimal with preserved precision
 price = random_decimal(Decimal("10.00"), Decimal("99.99"))
 
-# Random datetime within a range
+# Random datetime within a range (from_time to to_time)
+start = datetime.now()
+end = start + timedelta(days=7)
+random_time = random_datetime(start, end)
+
+# Random datetime with offset from base time
 base_time = datetime.now()
-random_time = random_datetime(
+random_time = random_datetime_offset(
     base_time,
     hours=24,      # Up to 24 hours later
     minutes=30,    # Plus up to 30 minutes

{mm_std-0.6.0 → mm_std-0.7.0}/justfile

@@ -17,6 +17,7 @@ test:
 lint: format pre-commit
     uv run ruff check src tests
     uv run mypy src
+    uv run ty check
 
 audit:
     # uv export --no-dev --all-extras --format requirements-txt --no-emit-project > requirements.txt

mm_std-0.7.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "mm-std"
+version = "0.7.0"
+description = ""
+requires-python = ">=3.14"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "bandit~=1.9.3",
+    "mypy~=1.19.1",
+    "pre-commit~=4.5.1",
+    "pydantic~=2.10",
+    "pytest~=9.0.2",
+    "pytest-xdist~=3.8.0",
+    "ruff~=0.14.14",
+    "ty~=0.0.13",
+]
+
+[tool.mypy]
+python_version = "3.14"
+warn_no_return = false
+strict = true
+exclude = ["^tests/", "^tmp/"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py314"
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "TC",       # flake8-type-checking, TYPE_CHECKING is dangerous, for example it doesn't work with pydantic
+    "A005",     # flake8-builtins: stdlib-module-shadowing
+    "ERA001",   # eradicate: commented-out-code
+    "PT",       # flake8-pytest-style
+    "FIX",      # flake8-fixme
+    "PLR0911",  # pylint: too-many-return-statements
+    "PLR0912",  # pylint: too-many-branches
+    "PLR0913",  # pylint: too-many-arguments
+    "PLR2004",  # pylint: magic-value-comparison
+    "PLC0414",  # pylint: useless-import-alias
+    "FBT",      # flake8-boolean-trap
+    "EM",       # flake8-errmsg
+    "TRY003",   # tryceratops: raise-vanilla-args
+    "C901",     # mccabe: complex-structure,
+    "BLE001",   # flake8-blind-except
+    "S311",     # bandit: suspicious-non-cryptographic-random-usage
+    "TD002",    # flake8-todos: missing-todo-author
+    "TD003",    # flake8-todos: missing-todo-link
+    "RET503",   # flake8-return: implicit-return
+    "COM812",   # it's used in ruff formatter
+    "ASYNC109",
+    "G004",
+    "DTZ001",
+    "D203",     # pydocstyle: one-blank-line-before-class (conflicts with D211)
+    "D213",     # pydocstyle: multi-line-summary-second-line (conflicts with D212)
+]
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["ANN", "S"]
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+skips = ["B311"]

mm_std-0.7.0/src/mm_std/__init__.py

@@ -0,0 +1,21 @@
+"""mm-std: Python utilities for common data manipulation tasks."""
+
+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-0.6.0 → mm_std-0.7.0}/src/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-0.6.0 → mm_std-0.7.0}/src/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-0.6.0 → mm_std-0.7.0}/src/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,21 +35,23 @@ 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, o: 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(o, type_):
@@ -62,20 +64,21 @@ class ExtendedJSONEncoder(json.JSONEncoder):
         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-0.6.0 → mm_std-0.7.0}/src/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-0.6.0 → mm_std-0.7.0}/src/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()