mm-std 0.4.17__py3-none-any.whl → 0.5.0__py3-none-any.whl

mm_std/__init__.py

@@ -1,56 +1,15 @@
-from .command import CommandResult as CommandResult
-from .command import run_command as run_command
-from .command import run_ssh_command as run_ssh_command
-from .concurrency.async_decorators import async_synchronized as async_synchronized
-from .concurrency.async_decorators import async_synchronized_parameter as async_synchronized_parameter
-from .concurrency.async_scheduler import AsyncScheduler as AsyncScheduler
-from .concurrency.async_task_runner import AsyncTaskRunner as AsyncTaskRunner
-from .concurrency.sync_decorators import synchronized as synchronized
-from .concurrency.sync_decorators import synchronized_parameter as synchronized_parameter
-from .concurrency.sync_scheduler import Scheduler as Scheduler
-from .concurrency.sync_task_runner import ConcurrentTasks as ConcurrentTasks
-from .config import BaseConfig as BaseConfig
-from .crypto.fernet import fernet_decrypt as fernet_decrypt
-from .crypto.fernet import fernet_encrypt as fernet_encrypt
-from .crypto.fernet import fernet_generate_key as fernet_generate_key
-from .crypto.openssl import openssl_decrypt as openssl_decrypt
-from .crypto.openssl import openssl_decrypt_base64 as openssl_decrypt_base64
-from .crypto.openssl import openssl_encrypt as openssl_encrypt
-from .crypto.openssl import openssl_encrypt_base64 as openssl_encrypt_base64
-from .date import parse_date as parse_date
-from .date import utc_delta as utc_delta
-from .date import utc_now as utc_now
-from .date import utc_random as utc_random
-from .dict import replace_empty_dict_entries as replace_empty_dict_entries
-from .env import get_dotenv as get_dotenv
-from .http.http_request import http_request as http_request
-from .http.http_request_sync import http_request_sync as http_request_sync
-from .http.http_response import HttpError as HttpError
-from .http.http_response import HttpResponse as HttpResponse
-from .json_ import CustomJSONEncoder as CustomJSONEncoder
-from .json_ import json_dumps as json_dumps
-from .log import configure_logging as configure_logging
-from .log import init_logger as init_logger
-from .net import check_port as check_port
-from .net import get_free_local_port as get_free_local_port
-from .print_ import PrintFormat as PrintFormat
-from .print_ import fatal as fatal
-from .print_ import pretty_print_toml as pretty_print_toml
-from .print_ import print_console as print_console
-from .print_ import print_json as print_json
-from .print_ import print_plain as print_plain
-from .print_ import print_table as print_table
-from .random_ import random_choice as random_choice
-from .random_ import random_decimal as random_decimal
-from .random_ import random_str_choice as random_str_choice
-from .result import Result as Result
-from .result import is_err as is_err
-from .result import is_ok as is_ok
-from .str import number_with_separator as number_with_separator
-from .str import str_contains_any as str_contains_any
-from .str import str_ends_with_any as str_ends_with_any
-from .str import str_starts_with_any as str_starts_with_any
-from .str import str_to_list as str_to_list
-from .toml import toml_dumps as toml_dumps
-from .toml import toml_loads as toml_loads
-from .zip import read_text_from_zip_archive as read_text_from_zip_archive
+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
+
+__all__ = [
+    "ExtendedJSONEncoder",
+    "json_dumps",
+    "parse_date",
+    "random_datetime",
+    "random_decimal",
+    "replace_empty_dict_entries",
+    "utc_delta",
+    "utc_now",
+]

mm_std/{date.py → date_utils.py}

@@ -1,8 +1,8 @@
-import random
 from datetime import UTC, datetime, timedelta
 
 
 def utc_now() -> datetime:
+    """Get current UTC time."""
     return datetime.now(UTC)
 
 
@@ -13,6 +13,10 @@ def utc_delta(
     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
@@ -26,12 +30,18 @@ def utc_delta(
 
 
 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",
@@ -50,20 +60,3 @@ def parse_date(value: str, ignore_tz: bool = False) -> datetime:
         except ValueError:
             continue
     raise ValueError(f"Time data '{value}' does not match any known format.")
-
-
-def utc_random(
-    *,
-    from_time: datetime | None = None,
-    range_hours: int = 0,
-    range_minutes: int = 0,
-    range_seconds: int = 0,
-) -> datetime:
-    if from_time is None:
-        from_time = utc_now()
-    to_time = from_time + timedelta(hours=range_hours, minutes=range_minutes, seconds=range_seconds)
-    return from_time + (to_time - from_time) * random.random()
-
-
-def is_too_old(value: datetime | None, seconds: int) -> bool:
-    return value is None or value < utc_delta(seconds=-1 * seconds)

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/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()

mm_std/random_utils.py

@@ -0,0 +1,72 @@
+import random
+from datetime import datetime, timedelta
+from decimal import Decimal
+
+
+def random_decimal(from_value: Decimal, to_value: Decimal) -> Decimal:
+    """Generate a random decimal between from_value and to_value.
+
+    Uses integer arithmetic to preserve decimal precision instead of
+    converting to float which would introduce rounding errors.
+
+    Args:
+        from_value: Minimum value (inclusive)
+        to_value: Maximum value (inclusive)
+
+    Returns:
+        Random decimal in the specified range
+
+    Raises:
+        ValueError: If from_value > to_value
+    """
+    if from_value > to_value:
+        raise ValueError("from_value must be <= to_value")
+
+    # Work with integers to preserve precision
+    from_exp = from_value.as_tuple().exponent
+    to_exp = to_value.as_tuple().exponent
+    from_scale = max(0, -from_exp if isinstance(from_exp, int) else 0)
+    to_scale = max(0, -to_exp if isinstance(to_exp, int) else 0)
+    scale = max(from_scale, to_scale)
+
+    multiplier = 10**scale
+    from_int = int(from_value * multiplier)
+    to_int = int(to_value * multiplier)
+
+    random_int = random.randint(from_int, to_int)
+    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.
+
+    Returns a random datetime between from_time and from_time + offset,
+    where offset is calculated from the provided hours, minutes, and seconds.
+
+    Args:
+        from_time: Base datetime (inclusive)
+        hours: Maximum hours offset (default: 0)
+        minutes: Maximum minutes offset (default: 0)
+        seconds: Maximum seconds offset (default: 0)
+
+    Returns:
+        Random datetime in the specified range
+
+    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")
+
+    total_seconds = hours * 3600 + minutes * 60 + seconds
+    if total_seconds == 0:
+        return from_time
+
+    random_seconds = random.uniform(0, total_seconds)
+    return from_time + timedelta(seconds=random_seconds)

mm_std-0.5.0.dist-info/METADATA

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

mm_std-0.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mm_std/__init__.py,sha256=k0Porl_jW30hWFQXHh1YTPPXoxnyjeiXp9SXl0ndsjI,409
+mm_std/date_utils.py,sha256=aFdIacoNgDSPGeUkZihXZADd86TeHu4hr1uIT9zcqvw,1732
+mm_std/dict_utils.py,sha256=GVegQXTIo3tzLGbBkiUSGTJkfaD5WWwz6OQnw9KcXlg,2275
+mm_std/json_utils.py,sha256=3tOv2rowc9B18TpJyGSci1MvPEj5XogRy3qrJ1W_7Bg,4129
+mm_std/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mm_std/random_utils.py,sha256=x3uNuKjKY8GxYjbnOq0LU1pGXhI2wezpH2K-t9hrhfA,2225
+mm_std-0.5.0.dist-info/METADATA,sha256=vUSybNxgw2PQtNpc1oFnoPXRj4yLbDXOkB5cRmj-kds,74
+mm_std-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mm_std-0.5.0.dist-info/RECORD,,

mm_std/command.py

@@ -1,35 +0,0 @@
-import subprocess  # nosec
-from dataclasses import dataclass
-
-
-@dataclass
-class CommandResult:
-    stdout: str
-    stderr: str
-    code: int
-
-    @property
-    def out(self) -> str:
-        if self.stdout:
-            return self.stdout + "\n" + self.stderr
-        return self.stderr
-
-
-def run_command(cmd: str, timeout: int | None = 60, capture_output: bool = True, echo_cmd_console: bool = False) -> CommandResult:
-    if echo_cmd_console:
-        print(cmd)  # noqa: T201
-    try:
-        process = subprocess.run(cmd, timeout=timeout, capture_output=capture_output, shell=True, check=False)  # noqa: S602 # nosec
-        stdout = process.stdout.decode("utf-8") if capture_output else ""
-        stderr = process.stderr.decode("utf-8") if capture_output else ""
-        return CommandResult(stdout=stdout, stderr=stderr, code=process.returncode)
-    except subprocess.TimeoutExpired:
-        return CommandResult(stdout="", stderr="timeout", code=124)
-
-
-def run_ssh_command(host: str, cmd: str, ssh_key_path: str | None = None, timeout: int = 60) -> CommandResult:
-    ssh_cmd = "ssh -o 'StrictHostKeyChecking=no' -o 'LogLevel=ERROR'"
-    if ssh_key_path:
-        ssh_cmd += f" -i {ssh_key_path} "
-    ssh_cmd += f" {host} {cmd}"
-    return run_command(ssh_cmd, timeout=timeout)

mm_std/concurrency/async_decorators.py

@@ -1,54 +0,0 @@
-import asyncio
-import functools
-from collections import defaultdict
-from collections.abc import Awaitable, Callable
-from typing import ParamSpec, TypeVar
-
-P = ParamSpec("P")
-R = TypeVar("R")
-
-
-def async_synchronized(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
-    lock = asyncio.Lock()
-
-    @functools.wraps(func)
-    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-        async with lock:
-            return await func(*args, **kwargs)
-
-    return wrapper
-
-
-T = TypeVar("T")
-
-
-def async_synchronized_parameter[T, **P](
-    arg_index: int = 0, skip_if_locked: bool = False
-) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T | None]]]:
-    locks: dict[object, asyncio.Lock] = defaultdict(asyncio.Lock)
-
-    def outer(func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T | None]]:
-        @functools.wraps(func)
-        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T | None:
-            if len(args) <= arg_index:
-                raise ValueError(f"Function called with fewer than {arg_index + 1} positional arguments")
-
-            key = args[arg_index]
-
-            if skip_if_locked and locks[key].locked():
-                return None
-
-            try:
-                async with locks[key]:
-                    return await func(*args, **kwargs)
-            finally:
-                # Clean up the lock if no one is waiting
-                # TODO: I'm not sure if the next like is OK
-                if not locks[key].locked() and not locks[key]._waiters:  # noqa: SLF001
-                    locks.pop(key, None)
-
-        # Store locks for potential external access
-        wrapper.locks = locks  # type: ignore[attr-defined]
-        return wrapper
-
-    return outer

mm_std/concurrency/async_scheduler.py

@@ -1,172 +0,0 @@
-import asyncio
-import logging
-from collections.abc import Awaitable, Callable
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any
-
-from mm_std.date import utc_now
-
-type AsyncFunc = Callable[..., Awaitable[object]]
-type Args = tuple[object, ...]
-type Kwargs = dict[str, object]
-
-logger = logging.getLogger(__name__)
-
-
-class AsyncScheduler:
-    """
-    A scheduler for running async tasks at fixed intervals.
-
-    Each task runs on its own schedule and waits for the specified interval
-    between executions.
-    """
-
-    @dataclass
-    class TaskInfo:
-        """Information about a scheduled task."""
-
-        task_id: str
-        interval: float
-        func: AsyncFunc
-        args: Args = ()
-        kwargs: Kwargs = field(default_factory=dict)
-        run_count: int = 0
-        error_count: int = 0
-        last_run: datetime | None = None
-        running: bool = False
-
-    def __init__(self, name: str = "AsyncScheduler") -> None:
-        """Initialize the async scheduler."""
-        self.tasks: dict[str, AsyncScheduler.TaskInfo] = {}
-        self._running: bool = False
-        self._tasks: list[asyncio.Task[Any]] = []
-        self._main_task: asyncio.Task[Any] | None = None
-        self._name = name
-
-    def add_task(self, task_id: str, interval: float, func: AsyncFunc, args: Args = (), kwargs: Kwargs | None = None) -> None:
-        """
-        Register a new task with the scheduler.
-
-        Args:
-            task_id: Unique identifier for the task
-            interval: Time in seconds between task executions
-            func: Async function to execute
-            args: Positional arguments to pass to the function
-            kwargs: Keyword arguments to pass to the function
-
-        Raises:
-            ValueError: If a task with the same ID already exists
-        """
-        if kwargs is None:
-            kwargs = {}
-        if task_id in self.tasks:
-            raise ValueError(f"Task with id {task_id} already exists")
-        self.tasks[task_id] = AsyncScheduler.TaskInfo(task_id=task_id, interval=interval, func=func, args=args, kwargs=kwargs)
-
-    async def _run_task(self, task_id: str) -> None:
-        """
-        Internal loop for running a single task repeatedly.
-
-        Args:
-            task_id: ID of the task to run
-        """
-        task = self.tasks[task_id]
-        task.running = True
-
-        elapsed = 0.0
-        try:
-            while self._running:
-                task.last_run = utc_now()
-                task.run_count += 1
-                try:
-                    await task.func(*task.args, **task.kwargs)
-                except Exception:
-                    task.error_count += 1
-                    logger.exception("Error in task", extra={"task_id": task_id, "error_count": task.error_count})
-
-                # Calculate elapsed time and sleep if needed
-                elapsed = (utc_now() - task.last_run).total_seconds()
-                sleep_time = max(0.0, task.interval - elapsed)
-                if sleep_time > 0:
-                    try:
-                        await asyncio.sleep(sleep_time)
-                    except asyncio.CancelledError:
-                        break
-        finally:
-            task.running = False
-            logger.debug("Finished task", extra={"task_id": task_id, "elapsed": elapsed})
-
-    async def _start_all_tasks(self) -> None:
-        """Starts all tasks concurrently using asyncio tasks."""
-        self._tasks = []
-
-        for task_id in self.tasks:
-            task = asyncio.create_task(self._run_task(task_id), name=self._name + "-" + task_id)
-            self._tasks.append(task)
-
-        try:
-            # Keep the main task alive while the scheduler is running
-            while self._running:  # noqa: ASYNC110
-                await asyncio.sleep(0.1)
-        except asyncio.CancelledError:
-            logger.debug("Cancelled all tasks")
-        finally:
-            # Cancel all running tasks when we exit
-            for task in self._tasks:
-                if not task.done():
-                    task.cancel()
-
-            # Wait for all tasks to finish
-            if self._tasks:
-                await asyncio.gather(*self._tasks, return_exceptions=True)
-            self._tasks = []
-
-    def start(self) -> None:
-        """
-        Start the scheduler.
-
-        Creates tasks in the current event loop for each registered task.
-        """
-        if self._running:
-            logger.warning("AsyncScheduler already running")
-            return
-
-        self._running = True
-        logger.debug("starting")
-        self._main_task = asyncio.create_task(self._start_all_tasks())
-
-    def stop(self) -> None:
-        """
-        Stop the scheduler.
-
-        Cancels all running tasks and waits for them to complete.
-        """
-        if not self._running:
-            logger.warning("now running")
-            return
-
-        logger.debug("stopping")
-        self._running = False
-
-        if self._main_task and not self._main_task.done():
-            self._main_task.cancel()
-
-        logger.debug("stopped")
-
-    def is_running(self) -> bool:
-        """
-        Check if the scheduler is currently running.
-
-        Returns:
-            True if the scheduler is running, False otherwise
-        """
-        return self._running
-
-    def clear_tasks(self) -> None:
-        """Clear all tasks from the scheduler."""
-        if self._running:
-            logger.warning("Cannot clear tasks while scheduler is running")
-            return
-        self.tasks.clear()
-        logger.debug("cleared tasks")