pyutilkit 0.11.0__tar.gz → 0.12.0__tar.gz

pyutilkit-0.12.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.3
+Name: pyutilkit
+Version: 0.12.0
+Summary: python's missing batteries
+Keywords: utils
+Author: Stephanos Kuma
+Author-email: Stephanos Kuma <stephanos@kuma.ai>
+License: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Developers
+Requires-Dist: tzdata ; os_name == 'nt'
+Requires-Python: >=3.10
+Project-URL: homepage, https://pyutilkit.readthedocs.io/en/stable/
+Project-URL: repository, https://github.com/spapanik/pyutilkit
+Project-URL: documentation, https://pyutilkit.readthedocs.io/en/stable/
+Description-Content-Type: text/markdown
+
+# pyutilkit: python's missing batteries
+
+[![build][build_badge]][build_url]
+[![lint][lint_badge]][lint_url]
+[![tests][tests_badge]][tests_url]
+[![license][licence_badge]][licence_url]
+[![codecov][codecov_badge]][codecov_url]
+[![readthedocs][readthedocs_badge]][readthedocs_url]
+[![pypi][pypi_badge]][pypi_url]
+[![downloads][pepy_badge]][pepy_url]
+[![build automation: yam][yam_badge]][yam_url]
+[![Lint: ruff][ruff_badge]][ruff_url]
+
+Python has long maintained the philosophy of "batteries included", providing users with a rich
+standard library that avoids the need for third-party tools for most tasks. Some packages are so
+common they have achieved similar status to the standard library. Yet, certain utilities are
+reimplemented across countless projects. This lightweight library, with minimal dependencies,
+aims to eliminate that repetition.
+
+## Quick Start
+
+Install pyutilkit:
+
+```bash
+pip install pyutilkit
+```
+
+Or with uv (recommended for speed):
+
+```bash
+uv pip install pyutilkit
+```
+
+Basic usage example:
+
+```python
+from pyutilkit.date_utils import now
+from pyutilkit.timing import Stopwatch
+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}")
+
+# Measure execution time
+stopwatch = Stopwatch()
+with stopwatch:
+    # Your code here
+    result = sum(range(1000000))
+print(f"Computation took: {stopwatch.elapsed}")
+
+# Colorful terminal output
+success = SGRString("✓ Task completed", params=[SGRCodes.GREEN, SGRCodes.BOLD])
+success.print()
+```
+
+## Key Features
+
+- **🕐 Timezone Utilities**: Robust datetime handling with cross-platform timezone support, ISO parsing (including Zulu timezone), and seamless timezone conversion
+- **⏱️ High-Precision Timing**: Nanosecond-precision timing with human-readable formatting, lap tracking, and stopwatch functionality
+- **🎨 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 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
+
+## Documentation
+
+- **[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
+- **[Changelog](CHANGELOG.md)** - Version history and changes
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
+
+## Requirements
+
+- Python 3.10 or higher
+- No external dependencies (tzdata is automatically installed on Windows)
+
+## Links
+
+- [Full Documentation](https://pyutilkit.readthedocs.io/en/stable/)
+- [PyPI Package](https://pypi.org/project/pyutilkit)
+- [GitHub Repository](https://github.com/spapanik/pyutilkit)
+- [Changelog](CHANGELOG.md)
+- [Report Issues](https://github.com/spapanik/pyutilkit/issues)
+
+[build_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml/badge.svg
+[build_url]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml
+[lint_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml/badge.svg
+[lint_url]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml
+[tests_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml/badge.svg
+[tests_url]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml
+[licence_badge]: https://img.shields.io/pypi/l/pyutilkit
+[licence_url]: https://pyutilkit.readthedocs.io/en/stable/LICENSE/
+[codecov_badge]: https://codecov.io/github/spapanik/pyutilkit/graph/badge.svg?token=Q20F84BW72
+[codecov_url]: https://codecov.io/github/spapanik/pyutilkit
+[readthedocs_badge]: https://readthedocs.org/projects/pyutilkit/badge/?version=latest
+[readthedocs_url]: https://pyutilkit.readthedocs.io/en/latest/
+[pypi_badge]: https://img.shields.io/pypi/v/pyutilkit
+[pypi_url]: https://pypi.org/project/pyutilkit
+[pepy_badge]: https://pepy.tech/badge/pyutilkit
+[pepy_url]: https://pepy.tech/project/pyutilkit
+[yam_badge]: https://img.shields.io/badge/build%20automation-yamk-success
+[yam_url]: https://github.com/spapanik/yamk
+[ruff_badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
+[ruff_url]: https://github.com/charliermarsh/ruff
+[Documentation]: https://pyutilkit.readthedocs.io/en/stable/
+[Changelog]: https://pyutilkit.readthedocs.io/en/stable/CHANGELOG/

pyutilkit-0.12.0/docs/README.md

@@ -0,0 +1,118 @@
+# pyutilkit: python's missing batteries
+
+[![build][build_badge]][build_url]
+[![lint][lint_badge]][lint_url]
+[![tests][tests_badge]][tests_url]
+[![license][licence_badge]][licence_url]
+[![codecov][codecov_badge]][codecov_url]
+[![readthedocs][readthedocs_badge]][readthedocs_url]
+[![pypi][pypi_badge]][pypi_url]
+[![downloads][pepy_badge]][pepy_url]
+[![build automation: yam][yam_badge]][yam_url]
+[![Lint: ruff][ruff_badge]][ruff_url]
+
+Python has long maintained the philosophy of "batteries included", providing users with a rich
+standard library that avoids the need for third-party tools for most tasks. Some packages are so
+common they have achieved similar status to the standard library. Yet, certain utilities are
+reimplemented across countless projects. This lightweight library, with minimal dependencies,
+aims to eliminate that repetition.
+
+## Quick Start
+
+Install pyutilkit:
+
+```bash
+pip install pyutilkit
+```
+
+Or with uv (recommended for speed):
+
+```bash
+uv pip install pyutilkit
+```
+
+Basic usage example:
+
+```python
+from pyutilkit.date_utils import now
+from pyutilkit.timing import Stopwatch
+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}")
+
+# Measure execution time
+stopwatch = Stopwatch()
+with stopwatch:
+    # Your code here
+    result = sum(range(1000000))
+print(f"Computation took: {stopwatch.elapsed}")
+
+# Colorful terminal output
+success = SGRString("✓ Task completed", params=[SGRCodes.GREEN, SGRCodes.BOLD])
+success.print()
+```
+
+## Key Features
+
+- **🕐 Timezone Utilities**: Robust datetime handling with cross-platform timezone support, ISO parsing (including Zulu timezone), and seamless timezone conversion
+- **⏱️ High-Precision Timing**: Nanosecond-precision timing with human-readable formatting, lap tracking, and stopwatch functionality
+- **🎨 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 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
+
+## Documentation
+
+- **[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
+- **[Changelog](CHANGELOG.md)** - Version history and changes
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
+
+## Requirements
+
+- Python 3.10 or higher
+- No external dependencies (tzdata is automatically installed on Windows)
+
+## Links
+
+- [Full Documentation](https://pyutilkit.readthedocs.io/en/stable/)
+- [PyPI Package](https://pypi.org/project/pyutilkit)
+- [GitHub Repository](https://github.com/spapanik/pyutilkit)
+- [Changelog](CHANGELOG.md)
+- [Report Issues](https://github.com/spapanik/pyutilkit/issues)
+
+[build_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml/badge.svg
+[build_url]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml
+[lint_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml/badge.svg
+[lint_url]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml
+[tests_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml/badge.svg
+[tests_url]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml
+[licence_badge]: https://img.shields.io/pypi/l/pyutilkit
+[licence_url]: https://pyutilkit.readthedocs.io/en/stable/LICENSE/
+[codecov_badge]: https://codecov.io/github/spapanik/pyutilkit/graph/badge.svg?token=Q20F84BW72
+[codecov_url]: https://codecov.io/github/spapanik/pyutilkit
+[readthedocs_badge]: https://readthedocs.org/projects/pyutilkit/badge/?version=latest
+[readthedocs_url]: https://pyutilkit.readthedocs.io/en/latest/
+[pypi_badge]: https://img.shields.io/pypi/v/pyutilkit
+[pypi_url]: https://pypi.org/project/pyutilkit
+[pepy_badge]: https://pepy.tech/badge/pyutilkit
+[pepy_url]: https://pepy.tech/project/pyutilkit
+[yam_badge]: https://img.shields.io/badge/build%20automation-yamk-success
+[yam_url]: https://github.com/spapanik/yamk
+[ruff_badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
+[ruff_url]: https://github.com/charliermarsh/ruff
+[Documentation]: https://pyutilkit.readthedocs.io/en/stable/
+[Changelog]: https://pyutilkit.readthedocs.io/en/stable/CHANGELOG/

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

@@ -1,14 +1,12 @@
 [build-system]
 requires = [
-    "phosphorus>=0.10",
+    "uv_build>=0.11.0,<0.12.0",
 ]
-build-backend = "phosphorus.construction.api"
+build-backend = "uv_build"
 
 [project]
 name = "pyutilkit"
-dynamic = [
-    "version",
-]
+version = "0.12.0"
 
 authors = [
     { name = "Stephanos Kuma", email = "stephanos@kuma.ai" },
@@ -24,7 +22,7 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3 :: Only",
-    "License :: OSI Approved :: BSD License",
+    "Intended Audience :: Developers",
 ]
 
 requires-python = ">=3.10"
@@ -40,37 +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.18",
-    "ruff~=0.13",
+    "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.phosphorus.dynamic]
-version = { file = "src/pyutilkit/__version__.py" }
-
 [tool.mypy]
+# Keep mypy for CI/CD
 check_untyped_defs = true
 disallow_any_decorated = true
 disallow_any_explicit = true
@@ -95,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
 
@@ -110,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)
@@ -122,6 +122,7 @@ ignore = [
     "FBT001",  # Test arguments are handled by pytest
     "PLR2004", # Tests should contain magic number comparisons
     "S101",    # Pytest needs assert statements
+    "SLF001",  # Tests need to access private members for coverage
 ]
 
 [tool.ruff.lint.flake8-tidy-imports]
@@ -138,13 +139,15 @@ forced-separate = [
 ]
 split-on-trailing-comma = false
 
-[tool.pytest.ini_options]
+[tool.pytest]
 minversion = "9.0"
 strict = true
-addopts = ["-ra", "-v"]
+addopts = [
+    "-ra",
+    "-v",
+]
 testpaths = [
     "tests",
-    "integration",
 ]
 
 [tool.coverage.run]

pyutilkit-0.12.0/src/pyutilkit/__version__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("pyutilkit")

pyutilkit-0.12.0/src/pyutilkit/classes.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import threading
+from typing import TypeVar, cast
+
+_T = TypeVar("_T")
+
+
+class Singleton(type):
+    instance: object
+    _lock: threading.Lock
+
+    def __init__(
+        cls, name: str, bases: tuple[type[object], ...], namespace: dict[str, object]
+    ) -> None:
+        super().__init__(name, bases, namespace)
+        cls.instance = None
+        cls._lock = threading.Lock()
+
+    def __call__(cls: type[_T]) -> _T:
+        mcs = cast("Singleton", cls)
+        if mcs.instance is None:
+            with mcs._lock:
+                if mcs.instance is None:
+                    mcs.instance = super(Singleton, mcs).__call__()
+        return cast("_T", mcs.instance)

{pyutilkit-0.11.0 → 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,23 +13,35 @@ 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__,
+                    func.__name__,  # ty: ignore[unresolved-attribute]
                     exc.__class__.__name__,
                     args,
                     kwargs,

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 → 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 → 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/LICENSE.md

@@ -1,11 +0,0 @@
-# BSD 3-Clause License
-
-Copyright © 2025 Stephanos Kuma.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pyutilkit-0.11.0/PKG-INFO

@@ -1,65 +0,0 @@
-Metadata-Version: 2.3
-Name: pyutilkit
-Version: 0.11.0
-Summary: python's missing batteries
-Home-page: https://pyutilkit.readthedocs.io/en/stable/
-License: BSD-3-Clause
-Keywords: utils
-Author: Stephanos Kuma
-Author-email: "Stephanos Kuma" <stephanos@kuma.ai>
-Requires-Python: >=3.10
-Classifier: Development Status :: 4 - Beta
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Dist: tzdata ; os_name == 'nt'
-Project-URL: Documentation, https://pyutilkit.readthedocs.io/en/stable/
-Project-URL: Repository, https://github.com/spapanik/pyutilkit
-Description-Content-Type: text/markdown
-
-# pyutilkit: python's missing batteries
-
-[![build][build_badge]][build_url]
-[![lint][lint_badge]][lint_url]
-[![tests][tests_badge]][tests_url]
-[![license][licence_badge]][licence_url]
-[![codecov][codecov_badge]][codecov_url]
-[![readthedocs][readthedocs_badge]][readthedocs_url]
-[![pypi][pypi_badge]][pypi_url]
-[![downloads][pepy_badge]][pepy_url]
-[![build automation: yam][yam_badge]][yam_url]
-[![Lint: ruff][ruff_badge]][ruff_url]
-
-The Python has long maintained the philosophy of "batteries included", giving the user
-a rich standard library, avoiding the need for third party tools for most work. Some packages
-are so common, that the have a similar status to the standard library. Still, some code seems
-to be written time and again, with every project. This small library, with minimal requirements,
-hopes to stop this repetition.
-
-## Links
-
-- [Documentation]
-- [Changelog]
-
-[build_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml/badge.svg
-[build_url]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml
-[lint_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml/badge.svg
-[lint_url]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml
-[tests_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml/badge.svg
-[tests_url]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml
-[licence_badge]: https://img.shields.io/pypi/l/pyutilkit
-[licence_url]: https://pyutilkit.readthedocs.io/en/stable/LICENSE/
-[codecov_badge]: https://codecov.io/github/spapanik/pyutilkit/graph/badge.svg?token=Q20F84BW72
-[codecov_url]: https://codecov.io/github/spapanik/pyutilkit
-[readthedocs_badge]: https://readthedocs.org/projects/pyutilkit/badge/?version=latest
-[readthedocs_url]: https://pyutilkit.readthedocs.io/en/latest/
-[pypi_badge]: https://img.shields.io/pypi/v/pyutilkit
-[pypi_url]: https://pypi.org/project/pyutilkit
-[pepy_badge]: https://pepy.tech/badge/pyutilkit
-[pepy_url]: https://pepy.tech/project/pyutilkit
-[yam_badge]: https://img.shields.io/badge/build%20automation-yamk-success
-[yam_url]: https://github.com/spapanik/yamk
-[ruff_badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
-[ruff_url]: https://github.com/charliermarsh/ruff
-[Documentation]: https://pyutilkit.readthedocs.io/en/stable/
-[Changelog]: https://pyutilkit.readthedocs.io/en/stable/CHANGELOG/

pyutilkit-0.11.0/docs/README.md

@@ -1,46 +0,0 @@
-# pyutilkit: python's missing batteries
-
-[![build][build_badge]][build_url]
-[![lint][lint_badge]][lint_url]
-[![tests][tests_badge]][tests_url]
-[![license][licence_badge]][licence_url]
-[![codecov][codecov_badge]][codecov_url]
-[![readthedocs][readthedocs_badge]][readthedocs_url]
-[![pypi][pypi_badge]][pypi_url]
-[![downloads][pepy_badge]][pepy_url]
-[![build automation: yam][yam_badge]][yam_url]
-[![Lint: ruff][ruff_badge]][ruff_url]
-
-The Python has long maintained the philosophy of "batteries included", giving the user
-a rich standard library, avoiding the need for third party tools for most work. Some packages
-are so common, that the have a similar status to the standard library. Still, some code seems
-to be written time and again, with every project. This small library, with minimal requirements,
-hopes to stop this repetition.
-
-## Links
-
-- [Documentation]
-- [Changelog]
-
-[build_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml/badge.svg
-[build_url]: https://github.com/spapanik/pyutilkit/actions/workflows/build.yml
-[lint_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml/badge.svg
-[lint_url]: https://github.com/spapanik/pyutilkit/actions/workflows/lint.yml
-[tests_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml/badge.svg
-[tests_url]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml
-[licence_badge]: https://img.shields.io/pypi/l/pyutilkit
-[licence_url]: https://pyutilkit.readthedocs.io/en/stable/LICENSE/
-[codecov_badge]: https://codecov.io/github/spapanik/pyutilkit/graph/badge.svg?token=Q20F84BW72
-[codecov_url]: https://codecov.io/github/spapanik/pyutilkit
-[readthedocs_badge]: https://readthedocs.org/projects/pyutilkit/badge/?version=latest
-[readthedocs_url]: https://pyutilkit.readthedocs.io/en/latest/
-[pypi_badge]: https://img.shields.io/pypi/v/pyutilkit
-[pypi_url]: https://pypi.org/project/pyutilkit
-[pepy_badge]: https://pepy.tech/badge/pyutilkit
-[pepy_url]: https://pepy.tech/project/pyutilkit
-[yam_badge]: https://img.shields.io/badge/build%20automation-yamk-success
-[yam_url]: https://github.com/spapanik/yamk
-[ruff_badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
-[ruff_url]: https://github.com/charliermarsh/ruff
-[Documentation]: https://pyutilkit.readthedocs.io/en/stable/
-[Changelog]: https://pyutilkit.readthedocs.io/en/stable/CHANGELOG/

pyutilkit-0.11.0/src/pyutilkit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.11.0"

pyutilkit-0.11.0/src/pyutilkit/classes.py

@@ -1,21 +0,0 @@
-from __future__ import annotations
-
-import threading
-
-
-class Singleton(type):
-    instance: type | None
-
-    def __init__(
-        cls, name: str, bases: tuple[type[object], ...], namespace: dict[str, object]
-    ) -> None:
-        super().__init__(name, bases, namespace)
-        cls.instance = None
-        cls._lock = threading.Lock()
-
-    def __call__(cls) -> type:
-        if cls.instance is None:
-            with cls._lock:
-                if cls.instance is None:
-                    cls.instance = super().__call__()
-        return cls.instance

pyutilkit-0.11.0/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,
-    )