pyutilkit 0.9.0__tar.gz → 0.11.0__tar.gz

{pyutilkit-0.9.0 → pyutilkit-0.11.0}/LICENSE.md

@@ -1,6 +1,6 @@
 # BSD 3-Clause License
 
-Copyright © 2024 Stephanos Kuma.
+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:
 

{pyutilkit-0.9.0 → pyutilkit-0.11.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.3
 Name: pyutilkit
-Version: 0.9.0
+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.9
+Requires-Python: >=3.10
 Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
@@ -21,11 +21,12 @@ Description-Content-Type: text/markdown
 
 [![build][build_badge]][build_url]
 [![lint][lint_badge]][lint_url]
-[![tests][test_badge]][test_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]
-[![code style: black][black_badge]][black_url]
 [![build automation: yam][yam_badge]][yam_url]
 [![Lint: ruff][ruff_badge]][ruff_url]
 
@@ -37,23 +38,25 @@ hopes to stop this repetition.
 
 ## Links
 
--   [Documentation]
--   [Changelog]
+- [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
+[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
-[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

{pyutilkit-0.9.0 → pyutilkit-0.11.0}/docs/README.md

@@ -2,11 +2,12 @@
 
 [![build][build_badge]][build_url]
 [![lint][lint_badge]][lint_url]
-[![tests][test_badge]][test_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]
-[![code style: black][black_badge]][black_url]
 [![build automation: yam][yam_badge]][yam_url]
 [![Lint: ruff][ruff_badge]][ruff_url]
 
@@ -18,23 +19,25 @@ hopes to stop this repetition.
 
 ## Links
 
--   [Documentation]
--   [Changelog]
+- [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
+[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
-[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

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

@@ -1,12 +1,14 @@
 [build-system]
 requires = [
-    "phosphorus>=0.8",
+    "phosphorus>=0.10",
 ]
 build-backend = "phosphorus.construction.api"
 
 [project]
 name = "pyutilkit"
-version = "0.9.0"
+dynamic = [
+    "version",
+]
 
 authors = [
     { name = "Stephanos Kuma", email = "stephanos@kuma.ai" },
@@ -25,7 +27,7 @@ classifiers = [
     "License :: OSI Approved :: BSD License",
 ]
 
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     "tzdata; os_name == 'nt'",
 ]
@@ -35,33 +37,38 @@ 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.18",
+    "ruff~=0.13",
+    { 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",
+    "pygments~=2.19",
+    "pymdown-extensions~=10.15",
 ]
 
-[tool.black]
-target-version = [
-    "py39",
-]
+[tool.phosphorus.dynamic]
+version = { file = "src/pyutilkit/__version__.py" }
 
 [tool.mypy]
 check_untyped_defs = true
@@ -95,7 +102,7 @@ disallow_any_decorated = false # mock.MagicMock is Any
 src = [
     "src",
 ]
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = [
@@ -103,11 +110,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
 ]
 
@@ -133,8 +139,13 @@ forced-separate = [
 split-on-trailing-comma = false
 
 [tool.pytest.ini_options]
-addopts = "-ra -v"
-testpaths = "tests"
+minversion = "9.0"
+strict = true
+addopts = ["-ra", "-v"]
+testpaths = [
+    "tests",
+    "integration",
+]
 
 [tool.coverage.run]
 branch = true
@@ -142,12 +153,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/src/pyutilkit/__version__.py

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

{pyutilkit-0.9.0 → pyutilkit-0.11.0}/src/pyutilkit/classes.py

@@ -1,18 +1,21 @@
 from __future__ import annotations
 
-from typing import cast
+import threading
 
 
 class Singleton(type):
-    instance: type[Singleton] | None
+    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[Singleton]:
+    def __call__(cls) -> type:
         if cls.instance is None:
-            cls.instance = super().__call__()
-        return cast(type[Singleton], cls.instance)
+            with cls._lock:
+                if cls.instance is None:
+                    cls.instance = super().__call__()
+        return cls.instance

{pyutilkit-0.9.0 → pyutilkit-0.11.0}/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.9.0 → pyutilkit-0.11.0}/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  # 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(

{pyutilkit-0.9.0 → pyutilkit-0.11.0}/src/pyutilkit/term.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
-    from typing_extensions import Self  # py3.10: import from typing
+    from typing_extensions import Self  # upgrade: py3.10: import from typing
 
 TRUE_VAR = {"0", "false", "no"}
 
@@ -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__ = (  # py3.9: remove this line
-        "_force_prefix",
-        "_force_sgr",
-        "_is_error",
-        "_prefix",
-        "_sgr",
-        "_string",
-        "_suffix",
-    )
-
     _string: str
     _sgr: tuple[SGRCodes, ...]
     _prefix: str
@@ -146,7 +136,7 @@ class SGRString:
             is_error=self._is_error,
         )
 
-    def print(self, end: str = "\n", *, full_color: bool = False) -> None:
+    def print(self, end: str = os.linesep, *, 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,
@@ -159,7 +149,7 @@ class SGRString:
         if file.isatty():
             prefix = self._prefix
             sgr_prefix = "".join(code.sequence for code in self._sgr)
-            sgr_suffix = SGRCodes.RESET.sequence
+            sgr_suffix = SGRCodes.RESET.sequence if self._sgr else ""
             suffix = self._suffix
         else:
             prefix = ""
@@ -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",)  # py3.9: remove this line
     _strings: tuple[SGRString, ...]
 
     def __init__(
         self,
-        strings: Iterable[SGRString],
+        strings: Iterable[object],
+        *,
         force_prefix: bool | None = None,
         force_sgr: bool | None = None,
         is_error: bool | None = None,
@@ -241,11 +231,14 @@ class SGROutput:
 
     @staticmethod
     def _clean_string(
-        string: SGRString,
+        string: object,
+        *,
         force_prefix: bool | None,
         force_sgr: bool | None,
         is_error: bool | None,
     ) -> SGRString:
+        if not isinstance(string, SGRString):
+            string = SGRString(string)
         force_prefix = (
             string._force_prefix  # noqa: SLF001
             if force_prefix is None
@@ -265,7 +258,7 @@ class SGROutput:
             is_error=is_error,
         )
 
-    def print(self, sep: str = "", end: str = "\n") -> None:
+    def print(self, sep: str = "", end: str = os.linesep) -> None:
         n = len(self._strings)
         for index, string in enumerate(self._strings, start=1):
             current_end = end if index == n else sep

{pyutilkit-0.9.0 → pyutilkit-0.11.0}/src/pyutilkit/timing.py

@@ -1,25 +1,24 @@
-from __future__ import annotations  # py3.9: remove this line
+from __future__ import annotations
 
 from dataclasses import dataclass
 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  # py3.10: import Self from typing
+    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",)  # py3.9: remove this line
-
     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)