pyutilkit 0.6.0__tar.gz

PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.3
+Name: pyutilkit
+Version: 0.6.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
+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
+
+[![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]
+
+[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://github.com/spapanik/pyutilkit/blob/main/docs/LICENSE.md
+[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://github.com/spapanik/pyutilkit/blob/main/docs/CHANGELOG.md

docs/README.md

@@ -0,0 +1,37 @@
+# pyutilkit: python's missing batteries
+
+[![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]
+
+[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://github.com/spapanik/pyutilkit/blob/main/docs/LICENSE.md
+[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://github.com/spapanik/pyutilkit/blob/main/docs/CHANGELOG.md

pyproject.toml

@@ -0,0 +1,192 @@
+[build-system]
+requires = [
+    "phosphorus>=0.5",
+]
+build-backend = "phosphorus.construction.api"
+
+[project]
+name = "pyutilkit"
+version = "0.6.0"
+
+authors = [
+    { name = "Stephanos Kuma", email = "stephanos@kuma.ai" },
+]
+license = { text = "BSD-3-Clause" }
+
+readme = "docs/README.md"
+description = "python's missing batteries"
+keywords = [
+    "utils",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+]
+
+requires-python = ">=3.9"
+
+[project.urls]
+homepage = "https://pyutilkit.readthedocs.io/en/stable/"
+repository = "https://github.com/spapanik/pyutilkit"
+documentation = "https://pyutilkit.readthedocs.io/en/stable/"
+
+[tool.phosphorus.dev-dependencies]
+dev = [
+    "ipdb~=0.13",
+    "ipython~=8.18",
+]
+lint = [
+    "black~=24.8",
+    "mypy~=1.11",
+    "ruff~=0.6",
+]
+test = [
+    "freezegun~=1.5",
+    "pytest~=8.3",
+    "pytest-cov~=5.0",
+]
+docs = [
+    "mkdocs~=1.6",
+    "mkdocs-material~=9.5",
+    "mkdocs-material-extensions~=1.3",
+    "pygments~=2.17",
+    "pymdown-extensions~=10.9",
+]
+
+[tool.black]
+target-version = [
+    "py39",
+]
+
+[tool.mypy]
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+extra_checks = true
+ignore_missing_imports = true
+no_implicit_reexport = true
+show_error_codes = true
+strict_equality = true
+warn_return_any = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+warn_unused_configs = true
+
+[tool.ruff]
+src = [
+    "src",
+]
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ANN",
+    "ARG",
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "COM",
+    "DTZ",
+    "E",
+    "EM",
+    "ERA",
+    "EXE",
+    "F",
+    "FA",
+    "FBT",
+    "FIX",
+    "FLY",
+    "FURB",
+    "G",
+    "I",
+    "ICN",
+    "INP",
+    "ISC",
+    "LOG",
+    "N",
+    "PGH",
+    "PERF",
+    "PIE",
+    "PL",
+    "PT",
+    "PTH",
+    "PYI",
+    "Q",
+    "RET",
+    "RSE",
+    "RUF",
+    "S",
+    "SIM",
+    "SLF",
+    "SLOT",
+    "T10",
+    "TCH",
+    "TD",
+    "TID",
+    "TRY",
+    "UP",
+    "W",
+    "YTT",
+]
+ignore = [
+    "ANN101",
+    "ANN102",
+    "ANN401",
+    "COM812",
+    "E501",
+    "FIX002",
+    "PLR09",
+    "TD002",
+    "TD003",
+    "TRY003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "FBT001",
+    "PLR2004",
+    "PT011",
+    "S101",
+]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"mock".msg = "Use unittest.mock"
+"pytz".msg = "Use zoneinfo"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+forced-separate = [
+    "tests",
+]
+split-on-trailing-comma = false
+
+[tool.pytest.ini_options]
+addopts = "-ra -v --cov"
+testpaths = "tests"
+
+[tool.coverage.run]
+branch = true
+source = [
+    "src/",
+]
+data_file = ".cov_cache/coverage.dat"
+
+[tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+]
+show_missing = true
+skip_covered = true
+skip_empty = true

src/pyutilkit/classes.py

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

src/pyutilkit/data/timezones.py

@@ -0,0 +1,195 @@
+DEPRECATED_TIMEZONES = {
+    "Africa/Asmera",
+    "Africa/Timbuktu",
+    "America/Argentina/ComodRivadavia",
+    "America/Atka",
+    "America/Buenos_Aires",
+    "America/Catamarca",
+    "America/Coral_Harbour",
+    "America/Cordoba",
+    "America/Ensenada",
+    "America/Fort_Wayne",
+    "America/Godthab",
+    "America/Indianapolis",
+    "America/Jujuy",
+    "America/Knox_IN",
+    "America/Louisville",
+    "America/Mendoza",
+    "America/Montreal",
+    "America/Porto_Acre",
+    "America/Rosario",
+    "America/Santa_Isabel",
+    "America/Shiprock",
+    "America/Virgin",
+    "Antarctica/South_Pole",
+    "Asia/Ashkhabad",
+    "Asia/Calcutta",
+    "Asia/Chongqing",
+    "Asia/Chungking",
+    "Asia/Dacca",
+    "Asia/Harbin",
+    "Asia/Istanbul",
+    "Asia/Kashgar",
+    "Asia/Katmandu",
+    "Asia/Macao",
+    "Asia/Rangoon",
+    "Asia/Saigon",
+    "Asia/Tel_Aviv",
+    "Asia/Thimbu",
+    "Asia/Ujung_Pandang",
+    "Asia/Ulan_Bator",
+    "Atlantic/Faeroe",
+    "Atlantic/Jan_Mayen",
+    "Australia/ACT",
+    "Australia/Canberra",
+    "Australia/Currie",
+    "Australia/LHI",
+    "Australia/NSW",
+    "Australia/North",
+    "Australia/Queensland",
+    "Australia/South",
+    "Australia/Tasmania",
+    "Australia/Victoria",
+    "Australia/West",
+    "Australia/Yancowinna",
+    "Brazil/Acre",
+    "Brazil/DeNoronha",
+    "Brazil/East",
+    "Brazil/West",
+    "CET",
+    "CST6CDT",
+    "Canada/Atlantic",
+    "Canada/Central",
+    "Canada/Eastern",
+    "Canada/Mountain",
+    "Canada/Newfoundland",
+    "Canada/Pacific",
+    "Canada/Saskatchewan",
+    "Canada/Yukon",
+    "Chile/Continental",
+    "Chile/EasterIsland",
+    "Cuba",
+    "EET",
+    "EST",
+    "EST5EDT",
+    "Egypt",
+    "Eire",
+    "Etc/GMT",
+    "Etc/GMT+0",
+    "Etc/GMT+1",
+    "Etc/GMT+10",
+    "Etc/GMT+11",
+    "Etc/GMT+12",
+    "Etc/GMT+2",
+    "Etc/GMT+3",
+    "Etc/GMT+4",
+    "Etc/GMT+5",
+    "Etc/GMT+6",
+    "Etc/GMT+7",
+    "Etc/GMT+8",
+    "Etc/GMT+9",
+    "Etc/GMT-0",
+    "Etc/GMT-1",
+    "Etc/GMT-10",
+    "Etc/GMT-11",
+    "Etc/GMT-12",
+    "Etc/GMT-13",
+    "Etc/GMT-14",
+    "Etc/GMT-2",
+    "Etc/GMT-3",
+    "Etc/GMT-4",
+    "Etc/GMT-5",
+    "Etc/GMT-6",
+    "Etc/GMT-7",
+    "Etc/GMT-8",
+    "Etc/GMT-9",
+    "Etc/GMT0",
+    "Etc/Greenwich",
+    "Etc/UCT",
+    "Etc/UTC",
+    "Etc/Universal",
+    "Etc/Zulu",
+    "Europe/Belfast",
+    "Europe/Nicosia",
+    "Europe/Tiraspol",
+    "Factory",
+    "GB",
+    "GB-Eire",
+    "GMT",
+    "GMT+0",
+    "GMT-0",
+    "GMT0",
+    "Greenwich",
+    "HST",
+    "Hongkong",
+    "Iceland",
+    "Iran",
+    "Israel",
+    "Jamaica",
+    "Japan",
+    "Kwajalein",
+    "Libya",
+    "MET",
+    "MST",
+    "MST7MDT",
+    "Mexico/BajaNorte",
+    "Mexico/BajaSur",
+    "Mexico/General",
+    "NZ",
+    "NZ-CHAT",
+    "Navajo",
+    "PRC",
+    "PST8PDT",
+    "Pacific/Johnston",
+    "Pacific/Ponape",
+    "Pacific/Samoa",
+    "Pacific/Truk",
+    "Pacific/Yap",
+    "Poland",
+    "Portugal",
+    "ROC",
+    "ROK",
+    "Singapore",
+    "Turkey",
+    "UCT",
+    "US/Alaska",
+    "US/Aleutian",
+    "US/Arizona",
+    "US/Central",
+    "US/East-Indiana",
+    "US/Eastern",
+    "US/Hawaii",
+    "US/Indiana-Starke",
+    "US/Michigan",
+    "US/Mountain",
+    "US/Pacific",
+    "US/Samoa",
+    "Universal",
+    "W-SU",
+    "WET",
+    "Zulu",
+}
+# Timezones that are removed from the IANA db, but still appear in some systems
+NON_IANA_TIMEZONES = {
+    "SystemV/AST4",
+    "SystemV/AST4ADT",
+    "SystemV/CST6",
+    "SystemV/CST6CDT",
+    "SystemV/EST5",
+    "SystemV/EST5EDT",
+    "SystemV/HST10",
+    "SystemV/MST7",
+    "SystemV/MST7MDT",
+    "SystemV/PST8",
+    "SystemV/PST8PDT",
+    "SystemV/YST9",
+    "SystemV/YST9YDT",
+    "localtime",
+}
+# Timezones that don't appear in all systems yet
+PROPOSED_TIMEZONES = {"Pacific/Kanton"}
+
+# All unavailable timezones
+UNAVAILABLE_TIMEZONES = set.union(
+    DEPRECATED_TIMEZONES, NON_IANA_TIMEZONES, PROPOSED_TIMEZONES
+)

src/pyutilkit/date_utils.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from datetime import datetime, tzinfo
+from zoneinfo import ZoneInfo, available_timezones
+
+from pyutilkit.data.timezones import UNAVAILABLE_TIMEZONES
+
+UTC = ZoneInfo("UTC")
+
+
+def get_timezones() -> set[str]:
+    """
+    Get all the available timezones
+
+    This takes into accounts timezones that might not be present in
+    all systems.
+    """
+    return available_timezones() - UNAVAILABLE_TIMEZONES
+
+
+def now(tz_info: ZoneInfo = UTC) -> datetime:
+    return datetime.now(UTC).astimezone(tz_info)
+
+
+def from_iso(date_string: str, tz_info: tzinfo = UTC) -> datetime:
+    """
+    Get datetime from an iso string
+
+    This to allow the Zulu timezone, which is a valid ISO timezone.
+    """
+    date_string = date_string.replace("Z", "+00:00")
+    dt = datetime.fromisoformat(date_string)
+    try:
+        return add_timezone(dt, tz_info)
+    except ValueError:
+        return convert_timezone(dt, tz_info)
+
+
+def from_timestamp(timestamp: float, tz_info: tzinfo = UTC) -> datetime:
+    """
+    Get a datetime tz-aware time object from a timestamp
+    """
+    utc_dt = datetime.fromtimestamp(timestamp, tz=UTC)
+    return convert_timezone(utc_dt, tz_info)
+
+
+def add_timezone(dt: datetime, tz_info: tzinfo = UTC) -> datetime:
+    """
+    Add a timezone to a naive datetime
+
+    Raise an error in case of a tz-aware datetime
+    """
+    if dt.tzinfo is not None:
+        msg = f"{dt} is already tz-aware"
+        raise ValueError(msg)
+    return dt.replace(tzinfo=tz_info)
+
+
+def convert_timezone(dt: datetime, tz_info: tzinfo = UTC) -> datetime:
+    """
+    Change the timezone of a tz-aware datetime
+
+    Raise an error in case of a naive datetime
+    """
+    if dt.tzinfo is None:
+        msg = f"{dt} is a naive datetime"
+        raise ValueError(msg)
+    return dt.astimezone(tz_info)

src/pyutilkit/files.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import hashlib
+import logging
+from functools import wraps
+from typing import TYPE_CHECKING, 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)
+
+
+def handle_exceptions(
+    *,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+    default: R_co | None = None,
+    log_level: str = "info",
+) -> Callable[[Callable[P, R_co]], Callable[P, R_co | None]]:
+    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)(
+                    INGEST_ERROR,
+                    func.__name__,
+                    exc.__class__.__name__,
+                    args,
+                    kwargs,
+                    exc_info=True,
+                )
+                return default
+
+        return wrapper
+
+    return decorator
+
+
+def hash_file(path: Path, buffer_size: int = 2**16) -> str:
+    sha256 = hashlib.sha256()
+
+    with path.open("rb") as f:
+        while data := f.read(buffer_size):
+            sha256.update(data)
+
+    return sha256.hexdigest()

src/pyutilkit/subprocess.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from subprocess import PIPE, Popen
+from typing import Any
+
+from pyutilkit.timing import Stopwatch, Timing
+
+
+@dataclass(frozen=True)
+class ProcessOutput:
+    stdout: bytes
+    stderr: bytes
+    pid: int
+    returncode: int
+    elapsed: Timing
+
+
+def run_command(command: str | list[str], **kwargs: Any) -> ProcessOutput:
+    if kwargs.setdefault("stdout", PIPE) != PIPE:
+        msg = "stdout must be set to PIPE"
+        raise ValueError(msg)
+    if kwargs.setdefault("stderr", PIPE) != PIPE:
+        msg = "stderr must be set to PIPE"
+        raise ValueError(msg)
+
+    stdout = []
+    stderr = []
+    stopwatch = Stopwatch()
+    with stopwatch:
+        process = Popen(command, **kwargs)  # noqa: S603
+
+        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,
+    )

src/pyutilkit/term.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+from enum import IntEnum, unique
+from math import ceil, floor
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from typing_extensions import Self  # py3.10: import from typing
+
+
+@unique
+class SGRCodes(IntEnum):
+    RESET = 0
+
+    BOLD = 1
+    ITALIC = 3
+    UNDERLINE = 4
+    BLINK = 5
+    REVERSE = 7
+    CONCEAL = 8
+
+    BLACK = 30
+    RED = 31
+    GREEN = 32
+    YELLOW = 33
+    BLUE = 34
+    MAGENTA = 35
+    CYAN = 36
+    GREY = 37
+
+    BG_BLACK = 40
+    BG_RED = 41
+    BG_GREEN = 42
+    BG_YELLOW = 43
+    BG_BLUE = 44
+    BG_MAGENTA = 45
+    BG_CYAN = 46
+    BG_GREY = 47
+
+    BLACK_BRIGHT = 90
+    RED_BRIGHT = 91
+    GREEN_BRIGHT = 92
+    YELLOW_BRIGHT = 93
+    BLUE_BRIGHT = 94
+    MAGENTA_BRIGHT = 95
+    CYAN_BRIGHT = 96
+    WHITE_BRIGHT = 97
+
+    BG_BLACK_BRIGHT = 100
+    BG_RED_BRIGHT = 101
+    BG_GREEN_BRIGHT = 102
+    BG_YELLOW_BRIGHT = 103
+    BG_BLUE_BRIGHT = 104
+    BG_MAGENTA_BRIGHT = 105
+    BG_CYAN_BRIGHT = 106
+    BG_WHITE_BRIGHT = 107
+
+    @property
+    def sequence(self) -> str:
+        return f"\033[{self.value}m"
+
+
+class SGRString(str):
+    _sgr: tuple[SGRCodes, ...]
+    _string: str
+    __slots__ = ("_sgr", "_string")
+
+    def __new__(cls, obj: Any, *, params: Iterable[SGRCodes] = ()) -> Self:
+        string = super().__new__(cls, obj)
+        object.__setattr__(string, "_string", str(obj))
+        object.__setattr__(string, "_sgr", tuple(params))
+        return string
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        msg = "SGRString is immutable"
+        raise AttributeError(msg)
+
+    def __delattr__(self, name: str) -> None:
+        msg = "SGRString is immutable"
+        raise AttributeError(msg)
+
+    def __str__(self) -> str:
+        if not self._sgr or os.getenv("USE_SGR_CODES") in {"0", "false", "no"}:
+            return self._string
+        prefix = "".join(code.sequence for code in self._sgr)
+        return f"{prefix}{self._string}{SGRCodes.RESET.sequence}"
+
+    def __mul__(self, other: Any) -> Self:
+        if not isinstance(other, int):
+            return NotImplemented
+        return type(self)(self._string * other, params=self._sgr)
+
+    def __rmul__(self, other: Any) -> Self:
+        if not isinstance(other, int):
+            return NotImplemented
+        return type(self)(self._string * other, params=self._sgr)
+
+    def header(
+        self,
+        *,
+        padding: str = " ",
+        left_spaces: int = 1,
+        right_spaces: int = 1,
+        space: str = " ",
+    ) -> None:
+        try:
+            # in pseudo-terminals it throws OSError
+            terminal_size = os.get_terminal_size()
+        except OSError:
+            columns = 80
+        else:
+            columns = terminal_size.columns
+        text = f"{space * left_spaces}{self}{space * right_spaces}"
+        title_length = left_spaces + len(self) + right_spaces
+        if title_length >= columns:
+            print(text.strip())
+            return
+
+        half = (columns - title_length) / 2
+        print(f"{padding * ceil(half)}{text}{padding * floor(half)}")

src/pyutilkit/timing.py

@@ -0,0 +1,130 @@
+from __future__ import annotations  # py3.9: remove this line
+
+from dataclasses import dataclass
+from time import perf_counter_ns
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from typing_extensions import Self  # py3.10: import Self from typing
+
+METRIC_MULTIPLIER = 1000
+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)
+class Timing:
+    __slots__ = ("nanoseconds",)  # py3.9: remove this line
+
+    nanoseconds: int
+
+    def __init__(
+        self,
+        *,
+        days: int = 0,
+        seconds: int = 0,
+        milliseconds: int = 0,
+        microseconds: int = 0,
+        nanoseconds: int = 0,
+    ) -> None:
+        total_nanoseconds = (
+            nanoseconds
+            + METRIC_MULTIPLIER * microseconds
+            + METRIC_MULTIPLIER**2 * milliseconds
+            + METRIC_MULTIPLIER**3 * seconds
+            + SECONDS_PER_DAY * METRIC_MULTIPLIER**3 * days
+        )
+        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 microseconds < METRIC_MULTIPLIER:
+            return f"{microseconds:.1f}µs"
+        milliseconds = microseconds / METRIC_MULTIPLIER
+        if milliseconds < METRIC_MULTIPLIER:
+            return f"{milliseconds:.1f}ms"
+        seconds = milliseconds / METRIC_MULTIPLIER
+        if seconds < SECONDS_PER_MINUTE:
+            return f"{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}"
+        days, hours = divmod(hours, HOURS_PER_DAY)
+        return f"{days:,}d {hours:02d}:{minutes:02d}:{seconds:02d}"
+
+    def __bool__(self) -> bool:
+        return bool(self.nanoseconds)
+
+    def __add__(self, other: Any) -> Timing:
+        if not isinstance(other, Timing):
+            return NotImplemented
+        return Timing(nanoseconds=self.nanoseconds + other.nanoseconds)
+
+    def __radd__(self, other: Any) -> Timing:
+        if not isinstance(other, Timing):
+            return NotImplemented
+        return Timing(nanoseconds=self.nanoseconds + other.nanoseconds)
+
+    def __mul__(self, other: Any) -> Timing:
+        if not isinstance(other, int):
+            return NotImplemented
+        return Timing(nanoseconds=self.nanoseconds * other)
+
+    def __rmul__(self, other: Any) -> Timing:
+        if not isinstance(other, int):
+            return NotImplemented
+        return Timing(nanoseconds=self.nanoseconds * other)
+
+    def __floordiv__(self, other: Any) -> Timing:
+        if not isinstance(other, int):
+            return NotImplemented
+        return Timing(nanoseconds=self.nanoseconds // other)
+
+    def __truediv__(self, other: Any) -> Timing:
+        if not isinstance(other, int):
+            return NotImplemented
+        return Timing(nanoseconds=self.nanoseconds // other)
+
+
+class Stopwatch:
+    _start: int
+    laps: list[Timing]
+
+    def __init__(self) -> None:
+        self._start = 0
+        self.laps: list[Timing] = []
+
+    def __enter__(self) -> Self:
+        self._start = perf_counter_ns()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        _end = perf_counter_ns()
+        self.laps.append(Timing(nanoseconds=_end - self._start))
+
+    def __bool__(self) -> bool:
+        return bool(self.elapsed)
+
+    @property
+    def elapsed(self) -> Timing:
+        return sum(self.laps, Timing())
+
+    @property
+    def average(self) -> Timing:
+        if not self.laps:
+            msg = "No laps recorded"
+            raise ZeroDivisionError(msg)
+        return self.elapsed // len(self.laps)