pyutilkit 0.11.0.post1__tar.gz → 0.12.0__tar.gz

{pyutilkit-0.11.0.post1 → pyutilkit-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyutilkit
-Version: 0.11.0.post1
+Version: 0.12.0
 Summary: python's missing batteries
 Keywords: utils
 Author: Stephanos Kuma
@@ -59,6 +59,7 @@ from pyutilkit.term import SGRString, SGRCodes
 
 # Get current time in any timezone
 from zoneinfo import ZoneInfo
+
 tokyo_time = now(ZoneInfo("Asia/Tokyo"))
 print(f"Current time in Tokyo: {tokyo_time}")
 
@@ -81,7 +82,7 @@ success.print()
 - **🎨 Terminal Formatting**: ANSI color codes with smart TTY detection, automatic style stripping for piped output, and convenient header formatting
 - **🛡️ Error Handling**: Elegant exception handling decorator that logs errors and returns defaults instead of raising exceptions
 - **📁 File Utilities**: Efficient SHA-256 file hashing with buffered reading for large files
-- **🚀 Subprocess Enhancement**: Run shell commands with real-time output streaming, automatic timing, and structured results
+- **🚀 Subprocess Enhancement**: Run external commands with real-time output streaming, automatic timing, and structured results
 - **🔧 Design Patterns**: Thread-safe Singleton metaclass implementation
 - **✨ Zero Dependencies**: Pure Python using only standard library (except optional tzdata on Windows)
 - **🧪 Fully Tested**: 100% test coverage with comprehensive type annotations
@@ -90,12 +91,12 @@ success.print()
 
 - **[Installation Guide](installation.md)** - Setup instructions and requirements
 - **[Usage Guide](usage/index.md)** - Comprehensive examples and tutorials for all modules
-  - [Classes](usage/classes.md) - Singleton pattern implementation
-  - [Date Utilities](usage/date_utils.md) - Timezone-aware datetime operations
-  - [File Utilities](usage/files.md) - Exception handling and file hashing
-  - [Subprocess](usage/subprocess.md) - Enhanced command execution
-  - [Terminal](usage/term.md) - Terminal formatting and colors
-  - [Timing](usage/timing.md) - Performance measurement and benchmarking
+    - [Classes](usage/classes.md) - Singleton pattern implementation
+    - [Date Utilities](usage/date_utils.md) - Timezone-aware datetime operations
+    - [File Utilities](usage/files.md) - Exception handling and file hashing
+    - [Subprocess](usage/subprocess.md) - Enhanced command execution
+    - [Terminal](usage/term.md) - Terminal formatting and colors
+    - [Timing](usage/timing.md) - Performance measurement and benchmarking
 - **[Changelog](CHANGELOG.md)** - Version history and changes
 - **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
 

{pyutilkit-0.11.0.post1 → pyutilkit-0.12.0}/docs/README.md

@@ -40,6 +40,7 @@ from pyutilkit.term import SGRString, SGRCodes
 
 # Get current time in any timezone
 from zoneinfo import ZoneInfo
+
 tokyo_time = now(ZoneInfo("Asia/Tokyo"))
 print(f"Current time in Tokyo: {tokyo_time}")
 
@@ -62,7 +63,7 @@ success.print()
 - **🎨 Terminal Formatting**: ANSI color codes with smart TTY detection, automatic style stripping for piped output, and convenient header formatting
 - **🛡️ Error Handling**: Elegant exception handling decorator that logs errors and returns defaults instead of raising exceptions
 - **📁 File Utilities**: Efficient SHA-256 file hashing with buffered reading for large files
-- **🚀 Subprocess Enhancement**: Run shell commands with real-time output streaming, automatic timing, and structured results
+- **🚀 Subprocess Enhancement**: Run external commands with real-time output streaming, automatic timing, and structured results
 - **🔧 Design Patterns**: Thread-safe Singleton metaclass implementation
 - **✨ Zero Dependencies**: Pure Python using only standard library (except optional tzdata on Windows)
 - **🧪 Fully Tested**: 100% test coverage with comprehensive type annotations
@@ -71,12 +72,12 @@ success.print()
 
 - **[Installation Guide](installation.md)** - Setup instructions and requirements
 - **[Usage Guide](usage/index.md)** - Comprehensive examples and tutorials for all modules
-  - [Classes](usage/classes.md) - Singleton pattern implementation
-  - [Date Utilities](usage/date_utils.md) - Timezone-aware datetime operations
-  - [File Utilities](usage/files.md) - Exception handling and file hashing
-  - [Subprocess](usage/subprocess.md) - Enhanced command execution
-  - [Terminal](usage/term.md) - Terminal formatting and colors
-  - [Timing](usage/timing.md) - Performance measurement and benchmarking
+    - [Classes](usage/classes.md) - Singleton pattern implementation
+    - [Date Utilities](usage/date_utils.md) - Timezone-aware datetime operations
+    - [File Utilities](usage/files.md) - Exception handling and file hashing
+    - [Subprocess](usage/subprocess.md) - Enhanced command execution
+    - [Terminal](usage/term.md) - Terminal formatting and colors
+    - [Timing](usage/timing.md) - Performance measurement and benchmarking
 - **[Changelog](CHANGELOG.md)** - Version history and changes
 - **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
 

{pyutilkit-0.11.0.post1 → pyutilkit-0.12.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pyutilkit"
-version = "0.11.0.post1"
+version = "0.12.0"
 
 authors = [
     { name = "Stephanos Kuma", email = "stephanos@kuma.ai" },
@@ -38,35 +38,37 @@ documentation = "https://pyutilkit.readthedocs.io/en/stable/"
 [dependency-groups]
 dev = [
     "ipdb~=0.13",
-    "ipython~=8.37",
+    "ipython~=8.39",
     "ptpython~=3.0",
     { include-group = "lint" },
     { include-group = "test" },
     { include-group = "docs" },
 ]
 lint = [
-    "mypy~=1.19",
-    "ruff~=0.15",
-    "ty~=0.0.26",
+    "mypy~=2.1",                     # Keep mypy for CI/CD
+    "ruff~=0.16",
+    "ty~=0.0.63",
+    "typing-extensions~=4.16",       # upgrade: py3.10: use typing module
     { include-group = "test_core" },
 ]
 test = [
-    "pytest-cov~=7.0",
+    "pytest-cov~=7.1",
     { include-group = "test_core" },
 ]
 test_core = [
     "freezegun~=1.5",
-    "pytest~=9.0",
+    "pytest~=9.1",
 ]
 docs = [
     "mkdocs~=1.6",
-    "mkdocs-material~=9.6",
+    "mkdocs-material~=9.7",
     "mkdocs-material-extensions~=1.3",
-    "pygments~=2.19",
-    "pymdown-extensions~=10.15",
+    "pygments~=2.20",
+    "pymdown-extensions~=11.0",
 ]
 
 [tool.mypy]
+# Keep mypy for CI/CD
 check_untyped_defs = true
 disallow_any_decorated = true
 disallow_any_explicit = true
@@ -91,6 +93,7 @@ warn_unused_ignores = true
 warn_unreachable = true
 
 [[tool.mypy.overrides]]
+# Keep mypy for CI/CD
 module = "tests.*"
 disallow_any_decorated = false # mock.MagicMock is Any
 
@@ -106,6 +109,7 @@ select = [
 ]
 ignore = [
     "C901",   # Adding a limit to complexity is too arbitrary
+    "CPY001", # Use only a project copyright
     "COM812", # Avoid conflicts with the formatter
     "D10",    # Not everything needs a docstring
     "D203",   # Prefer `no-blank-line-before-class` (D211)

{pyutilkit-0.11.0.post1 → pyutilkit-0.12.0}/src/pyutilkit/files.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import hashlib
 import logging
 from functools import wraps
-from typing import TYPE_CHECKING, ParamSpec, TypeVar
+from typing import TYPE_CHECKING, Literal, ParamSpec, TypeVar, cast
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -13,21 +13,33 @@ logger = logging.getLogger(__name__)
 INGEST_ERROR = "Function `%s` threw `%s` when called with args=%s and kwargs=%s"
 R_co = TypeVar("R_co", covariant=True)
 P = ParamSpec("P")
+LogLevel = Literal["debug", "info", "warning", "error", "critical", "exception"]
+LOG_LEVELS = frozenset({"debug", "info", "warning", "error", "critical", "exception"})
+
+
+def _validate_log_level(log_level: object) -> LogLevel:
+    if not isinstance(log_level, str) or log_level not in LOG_LEVELS:
+        supported = ", ".join(sorted(LOG_LEVELS))
+        msg = f"Unsupported log level {log_level!r}; expected one of: {supported}"
+        raise ValueError(msg)
+    return cast("LogLevel", log_level)
 
 
 def handle_exceptions(
     *,
     exceptions: tuple[type[Exception], ...] = (Exception,),
     default: R_co | None = None,
-    log_level: str = "info",
+    log_level: LogLevel = "info",
 ) -> Callable[[Callable[P, R_co]], Callable[P, R_co | None]]:
+    log = getattr(logger, _validate_log_level(log_level))
+
     def decorator(func: Callable[P, R_co]) -> Callable[P, R_co | None]:
         @wraps(func)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R_co | None:
             try:
                 return func(*args, **kwargs)
             except exceptions as exc:
-                getattr(logger, log_level)(
+                log(
                     INGEST_ERROR,
                     func.__name__,  # ty: ignore[unresolved-attribute]
                     exc.__class__.__name__,

pyutilkit-0.12.0/src/pyutilkit/subprocess.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from queue import SimpleQueue
+from subprocess import PIPE, Popen
+from threading import Thread
+from typing import TYPE_CHECKING, cast
+
+from pyutilkit.timing import Stopwatch, Timing
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from typing import BinaryIO
+
+
+@dataclass(frozen=True)
+class ProcessOutput:
+    stdout: bytes
+    stderr: bytes
+    pid: int
+    returncode: int
+    elapsed: Timing
+
+
+def _write_output(stream: BinaryIO, line: bytes) -> None:
+    stream.write(line)
+    stream.flush()
+
+
+def _drain_pipe(
+    pipe: BinaryIO,
+    output: BinaryIO,
+    captured: list[bytes],
+    errors: SimpleQueue[Exception],
+) -> None:
+    echo = True
+    for line in pipe:
+        captured.append(line)
+        if not echo:
+            continue
+        try:
+            _write_output(output, line)
+        except Exception as exc:  # noqa: BLE001
+            errors.put(exc)
+            echo = False
+
+
+def _validate_command(command: object) -> list[str]:
+    if not isinstance(command, list):
+        msg = "command must be a list of argument strings"
+        raise TypeError(msg)
+    return cast("list[str]", command)
+
+
+def run_command(
+    command: list[str],
+    cwd: str | Path | None = None,
+    env: dict[str, str] | None = None,
+) -> ProcessOutput:
+    command = _validate_command(command)
+
+    stdout: list[bytes] = []
+    stderr: list[bytes] = []
+    errors: SimpleQueue[Exception] = SimpleQueue()
+    stopwatch = Stopwatch()
+    with (
+        stopwatch,
+        Popen(  # noqa: S603
+            command, stdout=PIPE, stderr=PIPE, cwd=cwd, env=env
+        ) as process,
+    ):
+        stdout_pipe = cast("BinaryIO", process.stdout)
+        stderr_pipe = cast("BinaryIO", process.stderr)
+        readers = (
+            Thread(
+                target=_drain_pipe,
+                args=(stdout_pipe, sys.stdout.buffer, stdout, errors),
+                name=f"pyutilkit-stdout-{process.pid}",
+            ),
+            Thread(
+                target=_drain_pipe,
+                args=(stderr_pipe, sys.stderr.buffer, stderr, errors),
+                name=f"pyutilkit-stderr-{process.pid}",
+            ),
+        )
+        for reader in readers:
+            reader.start()
+
+        process.wait()
+        for reader in readers:
+            reader.join()
+
+    if not errors.empty():
+        raise errors.get()
+
+    return ProcessOutput(
+        stdout=b"".join(stdout),
+        stderr=b"".join(stderr),
+        pid=process.pid,
+        returncode=process.returncode,
+        elapsed=stopwatch.elapsed,
+    )

{pyutilkit-0.11.0.post1 → pyutilkit-0.12.0}/src/pyutilkit/term.py

@@ -12,7 +12,7 @@ if TYPE_CHECKING:
 
     from typing_extensions import Self  # upgrade: py3.10: import from typing
 
-TRUE_VAR = {"0", "false", "no"}
+TRUTHY_VALUES = {"1", "true", "yes"}
 
 
 @unique
@@ -90,9 +90,12 @@ class SGRString:
     ) -> None:
         params = tuple(params)
         force_prefix = (
-            force_prefix or os.getenv("PY_UTIL_FORCE_PREFIX", "").lower() in TRUE_VAR
+            force_prefix
+            or os.getenv("PY_UTIL_FORCE_PREFIX", "").lower() in TRUTHY_VALUES
+        )
+        force_sgr = (
+            force_sgr or os.getenv("PY_UTIL_FORCE_SGR", "").lower() in TRUTHY_VALUES
         )
-        force_sgr = force_sgr or os.getenv("PY_UTIL_FORCE_SGR", "").lower() in TRUE_VAR
 
         object.__setattr__(self, "_prefix", prefix)
         object.__setattr__(self, "_string", str(obj))
@@ -136,7 +139,7 @@ class SGRString:
             is_error=self._is_error,
         )
 
-    def print(self, end: str = os.linesep, *, full_color: bool = False) -> None:
+    def print(self, end: str = "\n", *, full_color: bool = False) -> None:
         """Print the command output.
 
         The command will be printed to stdout if it's not the output of an error,
@@ -202,7 +205,15 @@ class SGRString:
         half = (columns - title_length) / 2
         prefix = f"{padding * ceil(half)}{space * left_spaces}{self._prefix}"
         suffix = f"{self._suffix}{space * right_spaces}{padding * floor(half)}"
-        type(self)(self._string, prefix=prefix, suffix=suffix, params=self._sgr).print()
+        type(self)(
+            self._string,
+            prefix=prefix,
+            suffix=suffix,
+            params=self._sgr,
+            force_prefix=self._force_prefix,
+            force_sgr=self._force_sgr,
+            is_error=self._is_error,
+        ).print()
 
 
 @dataclass(frozen=True, order=True, slots=True)
@@ -258,7 +269,7 @@ class SGROutput:
             is_error=is_error,
         )
 
-    def print(self, sep: str = "", end: str = os.linesep) -> None:
+    def print(self, sep: str = "", end: str = "\n") -> None:
         n = len(self._strings)
         for index, string in enumerate(self._strings, start=1):
             current_end = end if index == n else sep
@@ -273,8 +284,8 @@ class SGROutput:
         space: str = " ",
     ) -> None:
         n = len(self._strings)
-        if n > 1:
-            msg = "Only one string is allowed for the header"
+        if n != 1:
+            msg = "Exactly one string is required for the header"
             raise ValueError(msg)
 
         self._strings[0].header(

{pyutilkit-0.11.0.post1 → pyutilkit-0.12.0}/src/pyutilkit/timing.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass
 from time import perf_counter_ns
 from typing import TYPE_CHECKING
@@ -14,7 +15,8 @@ METRIC_MULTIPLIER = 1_000
 SECONDS_PER_MINUTE = 60
 MINUTES_PER_HOUR = 60
 HOURS_PER_DAY = 24
-SECONDS_PER_DAY = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY
+SECONDS_PER_HOUR = SECONDS_PER_MINUTE * MINUTES_PER_HOUR
+SECONDS_PER_DAY = SECONDS_PER_HOUR * HOURS_PER_DAY
 
 
 @dataclass(frozen=True, order=True, slots=True)
@@ -25,6 +27,8 @@ class Timing:
         self,
         *,
         days: int = 0,
+        hours: int = 0,
+        minutes: int = 0,
         seconds: int = 0,
         milliseconds: int = 0,
         microseconds: int = 0,
@@ -35,9 +39,18 @@ class Timing:
             + METRIC_MULTIPLIER * microseconds
             + METRIC_MULTIPLIER**2 * milliseconds
             + METRIC_MULTIPLIER**3 * seconds
+            + SECONDS_PER_MINUTE * METRIC_MULTIPLIER**3 * minutes
+            + SECONDS_PER_HOUR * METRIC_MULTIPLIER**3 * hours
             + SECONDS_PER_DAY * METRIC_MULTIPLIER**3 * days
         )
-        object.__setattr__(self, "nanoseconds", total_nanoseconds)
+        rounded_nanoseconds = round(total_nanoseconds)
+        if rounded_nanoseconds != total_nanoseconds:
+            warnings.warn(
+                "Timing received a fractional duration; "
+                "rounding to the nearest nanosecond.",
+                stacklevel=2,
+            )
+        object.__setattr__(self, "nanoseconds", rounded_nanoseconds)
 
     def __str__(self) -> str:
         if self.nanoseconds == 0:
@@ -149,17 +162,22 @@ class Stopwatch:
     def elapsed(self) -> Timing:
         return sum(self.laps, self._zero)
 
-    @property
-    def average(self) -> Timing:
+    def _require_laps(self) -> None:
         if not self.laps:
             msg = "No laps recorded"
-            raise ZeroDivisionError(msg)
+            raise ValueError(msg)
+
+    @property
+    def average(self) -> Timing:
+        self._require_laps()
         return self.elapsed // len(self)
 
     @property
     def min(self) -> Timing:
+        self._require_laps()
         return min(self.laps)
 
     @property
     def max(self) -> Timing:
+        self._require_laps()
         return max(self.laps)

pyutilkit-0.11.0.post1/src/pyutilkit/subprocess.py

@@ -1,55 +0,0 @@
-from __future__ import annotations
-
-import sys
-from dataclasses import dataclass
-from subprocess import PIPE, Popen
-from typing import TYPE_CHECKING
-
-from pyutilkit.timing import Stopwatch, Timing
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-@dataclass(frozen=True)
-class ProcessOutput:
-    stdout: bytes
-    stderr: bytes
-    pid: int
-    returncode: int
-    elapsed: Timing
-
-
-def run_command(
-    command: str | list[str],
-    cwd: str | Path | None = None,
-    env: dict[str, str] | None = None,
-) -> ProcessOutput:
-    stdout = []
-    stderr = []
-    stopwatch = Stopwatch()
-    with stopwatch:
-        process = Popen(  # noqa: S603
-            command, stdout=PIPE, stderr=PIPE, cwd=cwd, env=env
-        )
-
-        for line in process.stdout or []:
-            sys.stdout.buffer.write(line)
-            sys.stdout.flush()
-            stdout.append(line)
-
-        for line in process.stderr or []:
-            sys.stderr.buffer.write(line)
-            sys.stderr.flush()
-            stderr.append(line)
-
-    with stopwatch:
-        process.wait()
-
-    return ProcessOutput(
-        stdout=b"".join(stdout),
-        stderr=b"".join(stderr),
-        pid=process.pid,
-        returncode=process.returncode,
-        elapsed=stopwatch.elapsed,
-    )