pyutilkit 0.10.0__tar.gz → 0.11.0.post1__tar.gz

pyutilkit-0.11.0.post1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.3
+Name: pyutilkit
+Version: 0.11.0.post1
+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 shell 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.post1/docs/README.md

@@ -0,0 +1,117 @@
+# 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 shell 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.10.0 → pyutilkit-0.11.0.post1}/pyproject.toml

@@ -1,12 +1,12 @@
 [build-system]
 requires = [
-    "phosphorus>=0.8",
+    "uv_build>=0.11.0,<0.12.0",
 ]
-build-backend = "phosphorus.construction.api"
+build-backend = "uv_build"
 
 [project]
 name = "pyutilkit"
-version = "0.10.0"
+version = "0.11.0.post1"
 
 authors = [
     { name = "Stephanos Kuma", email = "stephanos@kuma.ai" },
@@ -22,10 +22,10 @@ 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.9"
+requires-python = ">=3.10"
 dependencies = [
     "tzdata; os_name == 'nt'",
 ]
@@ -35,32 +35,35 @@ homepage = "https://pyutilkit.readthedocs.io/en/stable/"
 repository = "https://github.com/spapanik/pyutilkit"
 documentation = "https://pyutilkit.readthedocs.io/en/stable/"
 
-[tool.phosphorus.dev-dependencies]
+[dependency-groups]
 dev = [
     "ipdb~=0.13",
-    "ipython~=8.18",
+    "ipython~=8.37",
+    "ptpython~=3.0",
+    { include-group = "lint" },
+    { include-group = "test" },
+    { include-group = "docs" },
 ]
 lint = [
-    "black~=24.10",
-    "mypy~=1.13",
-    "ruff~=0.8",
+    "mypy~=1.19",
+    "ruff~=0.15",
+    "ty~=0.0.26",
+    { include-group = "test_core" },
 ]
 test = [
+    "pytest-cov~=7.0",
+    { include-group = "test_core" },
+]
+test_core = [
     "freezegun~=1.5",
-    "pytest~=8.3",
-    "pytest-cov~=6.0",
+    "pytest~=9.0",
 ]
 docs = [
     "mkdocs~=1.6",
-    "mkdocs-material~=9.5",
+    "mkdocs-material~=9.6",
     "mkdocs-material-extensions~=1.3",
-    "pygments~=2.18",
-    "pymdown-extensions~=10.12",
-]
-
-[tool.black]
-target-version = [
-    "py39",
+    "pygments~=2.19",
+    "pymdown-extensions~=10.15",
 ]
 
 [tool.mypy]
@@ -95,7 +98,7 @@ disallow_any_decorated = false # mock.MagicMock is Any
 src = [
     "src",
 ]
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = [
@@ -103,11 +106,10 @@ select = [
 ]
 ignore = [
     "C901",   # Adding a limit to complexity is too arbitrary
-    "COM812", # Avoid magic trailing commas
+    "COM812", # Avoid conflicts with the formatter
     "D10",    # Not everything needs a docstring
     "D203",   # Prefer `no-blank-line-before-class` (D211)
     "D213",   # Prefer `multi-line-summary-first-line` (D212)
-    "E501",   # Avoid clashes with black
     "PLR09",  # Adding a limit to complexity is too arbitrary
 ]
 
@@ -116,6 +118,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]
@@ -132,9 +135,16 @@ forced-separate = [
 ]
 split-on-trailing-comma = false
 
-[tool.pytest.ini_options]
-addopts = "-ra -v"
-testpaths = "tests"
+[tool.pytest]
+minversion = "9.0"
+strict = true
+addopts = [
+    "-ra",
+    "-v",
+]
+testpaths = [
+    "tests",
+]
 
 [tool.coverage.run]
 branch = true
@@ -142,12 +152,17 @@ source = [
     "src/",
 ]
 data_file = ".cov_cache/coverage.dat"
+omit = [
+    "src/**/type_defs.py",
+]
 
 [tool.coverage.report]
 exclude_also = [
     "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "raise UnreachableCodeError",
 ]
-fail_under = 90
+fail_under = 100
 precision = 2
 show_missing = true
 skip_covered = true

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

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

pyutilkit-0.11.0.post1/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.10.0 → pyutilkit-0.11.0.post1}/src/pyutilkit/date_utils.py

@@ -17,7 +17,7 @@ def get_timezones() -> set[str]:
     return available_timezones() - UNAVAILABLE_TIMEZONES
 
 
-def now(tz_info: ZoneInfo = UTC) -> datetime:
+def now(tz_info: tzinfo = UTC) -> datetime:
     return datetime.now(UTC).astimezone(tz_info)
 
 

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

@@ -3,19 +3,16 @@ from __future__ import annotations
 import hashlib
 import logging
 from functools import wraps
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING, ParamSpec, TypeVar
 
 if TYPE_CHECKING:
     from collections.abc import Callable
     from pathlib import Path
 
-    from typing_extensions import ParamSpec  # upgrade: py3.9: import from typing
-
-    P = ParamSpec("P")
-
 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")
 
 
 def handle_exceptions(
@@ -32,7 +29,7 @@ def handle_exceptions(
             except exceptions as exc:
                 getattr(logger, log_level)(
                     INGEST_ERROR,
-                    func.__name__,
+                    func.__name__,  # ty: ignore[unresolved-attribute]
                     exc.__class__.__name__,
                     args,
                     kwargs,

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

@@ -67,18 +67,8 @@ class SGRCodes(IntEnum):
         return f"\033[{self.value}m"
 
 
-@dataclass(frozen=True, order=True)
+@dataclass(frozen=True, order=True, slots=True)
 class SGRString:
-    __slots__ = (  # upgrade: py3.9: use __slots__ = True
-        "_force_prefix",
-        "_force_sgr",
-        "_is_error",
-        "_prefix",
-        "_sgr",
-        "_string",
-        "_suffix",
-    )
-
     _string: str
     _sgr: tuple[SGRCodes, ...]
     _prefix: str
@@ -215,14 +205,14 @@ class SGRString:
         type(self)(self._string, prefix=prefix, suffix=suffix, params=self._sgr).print()
 
 
-@dataclass(frozen=True, order=True)
+@dataclass(frozen=True, order=True, slots=True)
 class SGROutput:
-    __slots__ = ("_strings",)  # upgrade: py3.9: use __slots__ = True
     _strings: tuple[SGRString, ...]
 
     def __init__(
         self,
         strings: Iterable[object],
+        *,
         force_prefix: bool | None = None,
         force_sgr: bool | None = None,
         is_error: bool | None = None,
@@ -242,6 +232,7 @@ class SGROutput:
     @staticmethod
     def _clean_string(
         string: object,
+        *,
         force_prefix: bool | None,
         force_sgr: bool | None,
         is_error: bool | None,

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

@@ -5,21 +5,20 @@ from time import perf_counter_ns
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
     from types import TracebackType
 
     from typing_extensions import Self  # upgrade: py3.10: import from typing
 
-METRIC_MULTIPLIER = 1000
+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
 
 
-@dataclass(frozen=True, order=True)
+@dataclass(frozen=True, order=True, slots=True)
 class Timing:
-    __slots__ = ("nanoseconds",)  # upgrade: py3.9: use __slots__ = True
-
     nanoseconds: int
 
     def __init__(
@@ -41,28 +40,35 @@ class Timing:
         object.__setattr__(self, "nanoseconds", total_nanoseconds)
 
     def __str__(self) -> str:
-        if self.nanoseconds < METRIC_MULTIPLIER:
-            return f"{self.nanoseconds}ns"
-        microseconds = self.nanoseconds / METRIC_MULTIPLIER
+        if self.nanoseconds == 0:
+            return "0ns"
+        sign = "" if self.nanoseconds > 0 else "-"
+        nanoseconds = abs(self.nanoseconds)
+        if nanoseconds < METRIC_MULTIPLIER:
+            return f"{sign}{nanoseconds}ns"
+        microseconds = nanoseconds / METRIC_MULTIPLIER
         if microseconds < METRIC_MULTIPLIER:
-            return f"{microseconds:.1f}µs"
+            return f"{sign}{microseconds:.1f}µs"
         milliseconds = microseconds / METRIC_MULTIPLIER
         if milliseconds < METRIC_MULTIPLIER:
-            return f"{milliseconds:.1f}ms"
+            return f"{sign}{milliseconds:.1f}ms"
         seconds = milliseconds / METRIC_MULTIPLIER
         if seconds < SECONDS_PER_MINUTE:
-            return f"{seconds:.2f}s"
+            return f"{sign}{seconds:.2f}s"
         round_seconds = int(seconds)
         minutes, seconds = divmod(round_seconds, SECONDS_PER_MINUTE)
         hours, minutes = divmod(minutes, MINUTES_PER_HOUR)
         if hours < HOURS_PER_DAY:
-            return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+            return f"{sign}{hours:02d}:{minutes:02d}:{seconds:02d}"
         days, hours = divmod(hours, HOURS_PER_DAY)
-        return f"{days:,}d {hours:02d}:{minutes:02d}:{seconds:02d}"
+        return f"{sign}{days:,}d {hours:02d}:{minutes:02d}:{seconds:02d}"
 
     def __bool__(self) -> bool:
         return bool(self.nanoseconds)
 
+    def __neg__(self) -> Self:
+        return self.__class__(nanoseconds=-self.nanoseconds)
+
     def __add__(self, other: object) -> Timing:
         if not isinstance(other, Timing):
             return NotImplemented
@@ -73,6 +79,16 @@ class Timing:
             return NotImplemented
         return Timing(nanoseconds=self.nanoseconds + other.nanoseconds)
 
+    def __sub__(self, other: object) -> Timing:
+        if not isinstance(other, Timing):
+            return NotImplemented
+        return Timing(nanoseconds=self.nanoseconds - other.nanoseconds)
+
+    def __rsub__(self, other: object) -> Timing:
+        if not isinstance(other, Timing):
+            return NotImplemented
+        return Timing(nanoseconds=other.nanoseconds - self.nanoseconds)
+
     def __mul__(self, other: object) -> Timing:
         if not isinstance(other, int):
             return NotImplemented
@@ -97,10 +113,11 @@ class Timing:
 class Stopwatch:
     _start: int
     laps: list[Timing]
+    __slots__ = ("_start", "_zero", "laps")
 
     def __init__(self) -> None:
-        self._start = 0
         self.laps: list[Timing] = []
+        self._zero = Timing()
 
     def __enter__(self) -> Self:
         self._start = perf_counter_ns()
@@ -112,19 +129,37 @@ class Stopwatch:
         exc_value: BaseException | None,
         traceback: TracebackType | None,
     ) -> None:
-        _end = perf_counter_ns()
-        self.laps.append(Timing(nanoseconds=_end - self._start))
+        end = perf_counter_ns()
+        self.laps.append(Timing(nanoseconds=end - self._start))
+        del self._start
 
     def __bool__(self) -> bool:
         return bool(self.elapsed)
 
+    def __len__(self) -> int:
+        return len(self.laps)
+
+    def __iter__(self) -> Iterator[Timing]:
+        return iter(self.laps)
+
+    def reset(self) -> None:
+        self.laps.clear()
+
     @property
     def elapsed(self) -> Timing:
-        return sum(self.laps, Timing())
+        return sum(self.laps, self._zero)
 
     @property
     def average(self) -> Timing:
         if not self.laps:
             msg = "No laps recorded"
             raise ZeroDivisionError(msg)
-        return self.elapsed // len(self.laps)
+        return self.elapsed // len(self)
+
+    @property
+    def min(self) -> Timing:
+        return min(self.laps)
+
+    @property
+    def max(self) -> Timing:
+        return max(self.laps)

pyutilkit-0.10.0/LICENSE.md

@@ -1,11 +0,0 @@
-# BSD 3-Clause License
-
-Copyright © 2024 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.10.0/PKG-INFO

@@ -1,62 +0,0 @@
-Metadata-Version: 2.3
-Name: pyutilkit
-Version: 0.10.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.9
-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][test_badge]][test_url]
-[![license][licence_badge]][licence_url]
-[![pypi][pypi_badge]][pypi_url]
-[![downloads][pepy_badge]][pepy_url]
-[![code style: black][black_badge]][black_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
-[test_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml/badge.svg
-[test_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/
-[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
-[black_badge]: https://img.shields.io/badge/code%20style-black-000000.svg
-[black_url]: https://github.com/psf/black
-[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.10.0/docs/README.md

@@ -1,43 +0,0 @@
-# pyutilkit: python's missing batteries
-
-[![build][build_badge]][build_url]
-[![lint][lint_badge]][lint_url]
-[![tests][test_badge]][test_url]
-[![license][licence_badge]][licence_url]
-[![pypi][pypi_badge]][pypi_url]
-[![downloads][pepy_badge]][pepy_url]
-[![code style: black][black_badge]][black_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
-[test_badge]: https://github.com/spapanik/pyutilkit/actions/workflows/tests.yml/badge.svg
-[test_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/
-[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
-[black_badge]: https://img.shields.io/badge/code%20style-black-000000.svg
-[black_url]: https://github.com/psf/black
-[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.10.0/src/pyutilkit/classes.py

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