mm-std 0.0.1__tar.gz → 0.5.3__tar.gz

mm_std-0.5.3/.gitignore

@@ -0,0 +1,16 @@
+.idea
+.vscode
+.venv
+.env
+.coverage
+/htmlcov
+__pycache__
+*.egg-info
+pip-wheel-metadata
+.pytest_cache
+.mypy_cache
+.ruff_cache
+/dist
+/build
+/tmp
+.DS_Store

mm_std-0.5.3/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files

mm_std-0.5.3/PKG-INFO

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

mm_std-0.5.3/README.md

@@ -0,0 +1,230 @@
+# mm-std
+
+A collection of Python utilities for common data manipulation tasks with strict type safety and modern Python support.
+
+## Features
+
+- **JSON Utilities**: Extended JSON encoder with support for datetime, UUID, Decimal, dataclasses, enums, and Pydantic models
+- **Dictionary Utilities**: Advanced dictionary manipulation with type preservation
+- **Date Utilities**: UTC-focused datetime operations and flexible date parsing
+- **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
+
+### String Utilities
+
+Efficient string matching for common patterns:
+
+```python
+from mm_std import str_starts_with_any, str_ends_with_any, str_contains_any
+
+# Check URL protocols
+url = "https://example.com"
+is_web_url = str_starts_with_any(url, ["http://", "https://"])  # True
+
+# Check file extensions
+filename = "document.pdf"
+is_document = str_ends_with_any(filename, [".pdf", ".doc", ".docx"])  # True
+
+# Check log levels in messages
+log_message = "ERROR: Database connection failed"
+has_error = str_contains_any(log_message, ["ERROR", "CRITICAL", "FATAL"])  # True
+
+# All functions accept any iterable
+prefixes = ("admin_", "super_", "root_")
+username = "admin_john"
+is_privileged = str_starts_with_any(username, prefixes)  # True
+```
+
+Parse multiline text into cleaned lines:
+
+```python
+from mm_std import parse_lines
+
+# Basic line parsing
+text = """
+line1
+line2
+   line3
+
+line4
+"""
+lines = parse_lines(text)  # ["line1", "line2", "line3", "line4"]
+
+# Advanced parsing with options
+config_text = """
+DEBUG=true # Enable debug mode
+HOST=localhost
+PORT=8080 # Application port
+# This is a comment
+DEBUG=true # Duplicate line
+"""
+
+# Parse with all options
+parsed = parse_lines(
+    config_text,
+    lowercase=True,        # Convert to lowercase
+    remove_comments=True,  # Remove everything after '#'
+    deduplicate=True       # Remove duplicates, preserve order
+)
+# Result: ["debug=true", "host=localhost", "port=8080"]
+```
+
+### Subprocess Utilities
+
+Execute shell commands safely with comprehensive result handling:
+
+```python
+from mm_std import shell, ssh_shell, ShellResult
+
+# Execute local commands
+result = shell("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")
+if result.code != 0:
+    print(f"Command failed: {result.stderr}")
+
+# Execute with timeout
+result = shell("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)
+
+# Complex shell operations with pipes
+result = shell("ps aux | grep python | wc -l")
+python_processes = int(result.stdout.strip())
+
+# Execute commands on remote hosts via SSH
+ssh_result = ssh_shell(
+    host="server.example.com",
+    cmd="systemctl status nginx",
+    ssh_key_path="~/.ssh/id_rsa",
+    timeout=10
+)
+
+# SSH commands are automatically quoted for security
+ssh_result = ssh_shell(
+    "server.example.com",
+    "echo 'hello world; ls -la'",  # Properly escaped
+    echo_command=True
+)
+```
+
+### JSON Utilities
+
+Extended JSON serialization with automatic handling of Python types:
+
+```python
+from mm_std import json_dumps, ExtendedJSONEncoder
+from datetime import datetime
+from decimal import Decimal
+from uuid import UUID
+
+data = {
+    "timestamp": datetime.now(),
+    "price": Decimal("19.99"),
+    "user_id": UUID("12345678-1234-5678-1234-567812345678"),
+    "tags": {"python", "json"}  # set will be converted to list
+}
+
+# Simple serialization
+json_str = json_dumps(data)
+
+# Custom type handlers for specific use cases
+json_str = json_dumps(data, type_handlers={
+    Decimal: lambda d: float(d)  # Convert Decimal to float instead of string
+})
+```
+
+### Dictionary Utilities
+
+Clean up dictionaries by replacing or removing empty values:
+
+```python
+from mm_std import replace_empty_dict_entries
+
+data = {
+    "name": "John",
+    "age": None,
+    "email": "",
+    "score": 0,
+    "active": False
+}
+
+# Remove empty entries entirely
+cleaned = replace_empty_dict_entries(data)
+# Result: {"name": "John"}
+
+# Replace with defaults
+defaults = {"age": 25, "email": "unknown@example.com"}
+cleaned = replace_empty_dict_entries(data, defaults=defaults)
+# Result: {"name": "John", "age": 25, "email": "unknown@example.com"}
+
+# Treat zero and false as empty too
+cleaned = replace_empty_dict_entries(
+    data,
+    defaults=defaults,
+    treat_zero_as_empty=True,
+    treat_false_as_empty=True
+)
+```
+
+### Date Utilities
+
+UTC-focused datetime operations:
+
+```python
+from mm_std import utc_now, utc_delta, parse_date
+
+# Current UTC time
+now = utc_now()
+
+# Time calculations
+past = utc_delta(hours=-2, minutes=-30)
+future = utc_delta(days=7)
+
+# Flexible date parsing
+dates = [
+    "2023-12-25",
+    "2023-12-25T10:30:00Z",
+    "2023-12-25 10:30:00.123456+00:00",
+    "2023/12/25"
+]
+
+parsed_dates = [parse_date(d) for d in dates]
+
+# Parse and ignore timezone info
+local_time = parse_date("2023-12-25T10:30:00+02:00", ignore_tz=True)
+```
+
+### Random Utilities
+
+Generate random values with precision:
+
+```python
+from mm_std import random_decimal, random_datetime
+from decimal import Decimal
+from datetime import datetime
+
+# Random decimal with preserved precision
+price = random_decimal(Decimal("10.00"), Decimal("99.99"))
+
+# Random datetime within a range
+base_time = datetime.now()
+random_time = random_datetime(
+    base_time,
+    hours=24,      # Up to 24 hours later
+    minutes=30,    # Plus up to 30 minutes
+    seconds=45     # Plus up to 45 seconds
+)
+```

mm_std-0.5.3/justfile

@@ -0,0 +1,40 @@
+version := `uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])'`
+
+
+clean:
+    rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage dist build src/*.egg-info
+
+build: clean
+    uv build
+
+format:
+    uv run ruff check --select I --fix src tests
+    uv run ruff format src tests
+
+test:
+    uv run pytest -n auto tests
+
+lint: format pre-commit
+    uv run ruff check src tests
+    uv run mypy src
+
+audit:
+    # uv export --no-dev --all-extras --format requirements-txt --no-emit-project > requirements.txt
+    # uv run pip-audit -r requirements.txt --disable-pip
+    # rm requirements.txt
+    uv run bandit -q -r -c "pyproject.toml" src
+
+publish: build lint audit test
+    git diff-index --quiet HEAD
+    printf "Enter PyPI token: " && IFS= read -rs TOKEN && echo && uv publish --token "$TOKEN"
+    git tag -a 'v{{version}}' -m 'v{{version}}'
+    git push origin v{{version}}
+
+sync:
+    uv sync
+
+pre-commit:
+    uv run pre-commit run --all-files
+
+pre-commit-autoupdate:
+    uv run pre-commit autoupdate

mm_std-0.5.3/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "mm-std"
+version = "0.5.3"
+description = ""
+requires-python = ">=3.13"
+dependencies = [
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest~=8.4.0",
+    "pytest-xdist~=3.7.0",
+    "ruff~=0.11.13",
+    "mypy~=1.16.0",
+    "bandit~=1.8.3",
+    "pre-commit~=4.2.0",
+]
+
+[tool.mypy]
+python_version = "3.13"
+warn_no_return = false
+strict = true
+exclude = ["^tests/", "^tmp/"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py313"
+[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
+    "D", # pydocstyle
+    "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"
+]
+[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.5.3/requirements.txt

@@ -0,0 +1,2 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --no-dev --all-extras --format requirements-txt --no-emit-project

mm_std-0.5.3/src/mm_std/__init__.py

@@ -0,0 +1,24 @@
+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
+
+__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",
+]

mm_std-0.5.3/src/mm_std/date_utils.py

@@ -0,0 +1,62 @@
+from datetime import UTC, datetime, timedelta
+
+
+def utc_now() -> datetime:
+    """Get current UTC time."""
+    return datetime.now(UTC)
+
+
+def utc_delta(
+    *,
+    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:
+        params["days"] = days
+    if hours:
+        params["hours"] = hours
+    if minutes:
+        params["minutes"] = minutes
+    if seconds:
+        params["seconds"] = seconds
+    return datetime.now(UTC) + timedelta(**params)
+
+
+def parse_date(value: 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"
+    date_formats = [
+        "%Y-%m-%d %H:%M:%S.%f%z",
+        "%Y-%m-%dT%H:%M:%S.%f%z",
+        "%Y-%m-%d %H:%M:%S.%f",
+        "%Y-%m-%dT%H:%M:%S%z",
+        "%Y-%m-%d %H:%M:%S%z",
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%d %H:%M%z",
+        "%Y-%m-%d %H:%M",
+        "%Y-%m-%d",
+        "%Y/%m/%d",
+        # Add more formats as needed
+    ]
+
+    for fmt in date_formats:
+        try:
+            dt = datetime.strptime(value, fmt)  # noqa: DTZ007
+            if ignore_tz and dt.tzinfo is not None:
+                dt = dt.replace(tzinfo=None)
+            return dt  # noqa: TRY300
+        except ValueError:
+            continue
+    raise ValueError(f"Time data '{value}' does not match any known format.")

mm_std-0.5.3/src/mm_std/dict_utils.py

@@ -0,0 +1,63 @@
+from collections import defaultdict
+from collections.abc import Mapping, MutableMapping
+from decimal import Decimal
+from typing import TypeVar, cast
+
+K = TypeVar("K")
+V = TypeVar("V")
+# TypeVar bound to MutableMapping with same K, V as defaults parameter
+# 'type: ignore' needed because mypy can't handle TypeVar bounds with other TypeVars
+DictType = TypeVar("DictType", bound=MutableMapping[K, V])  # type: ignore[valid-type]
+
+
+def replace_empty_dict_entries(
+    data: DictType,
+    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,
+) -> DictType:
+    """
+    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]
+    - defaultdict[str, float] → defaultdict[str, float]
+    - OrderedDict[str, str] → OrderedDict[str, str]
+
+    Args:
+        data: 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
+        treat_empty_string_as_empty: Treat "" as empty value
+
+    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)
+    else:
+        result = data.__class__()
+
+    for key, value in data.items():
+        should_replace = (
+            value is None
+            or (treat_false_as_empty and value is False)
+            or (treat_empty_string_as_empty and isinstance(value, str) and value == "")
+            or (treat_zero_as_empty and isinstance(value, (int, float, Decimal)) and not isinstance(value, bool) and value == 0)
+        )
+
+        if should_replace:
+            if key in defaults:
+                new_value = defaults[key]
+            else:
+                continue  # Skip the key if no default is available
+        else:
+            new_value = value
+
+        result[key] = new_value
+    return cast(DictType, result)

mm_std-0.5.3/src/mm_std/json_utils.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import asdict, is_dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any, ClassVar
+from uuid import UUID
+
+
+class ExtendedJSONEncoder(json.JSONEncoder):
+    """JSON encoder with extended type support for common Python objects.
+
+    Supports built-in Python types, dataclasses, enums, exceptions, and custom registered types.
+    Automatically registers pydantic BaseModel if available.
+    All type handlers are unified in a single registration system for consistency and performance.
+    """
+
+    _type_handlers: ClassVar[dict[type[Any], Callable[[Any], Any]]] = {
+        # Order matters: more specific types first
+        datetime: lambda obj: obj.isoformat(),  # Must be before date (inheritance)
+        date: lambda obj: obj.isoformat(),
+        UUID: str,
+        Decimal: str,
+        Path: str,
+        set: list,
+        frozenset: list,
+        bytes: lambda obj: obj.decode("latin-1"),
+        complex: lambda obj: {"real": obj.real, "imag": obj.imag},
+        Enum: lambda obj: obj.value,
+        Exception: str,
+    }
+
+    @classmethod
+    def register(cls, type_: type[Any], serializer: 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
+
+        Raises:
+            TypeError: If serializer is not callable
+            ValueError: If type_ is a built-in JSON type
+        """
+        if not callable(serializer):
+            raise TypeError("Serializer must be callable")
+        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
+
+    def default(self, obj: Any) -> Any:  # noqa: ANN401
+        # Check registered type handlers first
+        for type_, handler in self._type_handlers.items():
+            if isinstance(obj, type_):
+                return handler(obj)
+
+        # 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
+
+        return super().default(obj)
+
+
+def json_dumps(data: Any, type_handlers: dict[type[Any], Callable[[Any], Any]] | None = None, **kwargs: Any) -> str:  # noqa: ANN401
+    """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
+        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
+        handlers: dict[type[Any], Callable[[Any], Any]] = type_handlers
+
+        class TemporaryEncoder(ExtendedJSONEncoder):
+            _type_handlers: ClassVar[dict[type[Any], Callable[[Any], Any]]] = {
+                **ExtendedJSONEncoder._type_handlers,  # noqa: SLF001
+                **handlers,
+            }
+
+        encoder_cls: type[json.JSONEncoder] = TemporaryEncoder
+    else:
+        encoder_cls = ExtendedJSONEncoder
+
+    return json.dumps(data, 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]
+
+        ExtendedJSONEncoder.register(BaseModel, lambda obj: obj.model_dump())
+    except ImportError:
+        pass
+
+
+# Auto-register optional types when module is imported
+_auto_register_optional_types()