pyutilkit 0.5.0__tar.gz → 0.9.0__tar.gz

pyutilkit-0.9.0/LICENSE.md

@@ -0,0 +1,11 @@
+# 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.

PKG-INFO → pyutilkit-0.9.0/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyutilkit
-Version: 0.5.0
+Version: 0.9.0
 Summary: python's missing batteries
 Home-page: https://pyutilkit.readthedocs.io/en/stable/
 License: BSD-3-Clause
@@ -9,14 +9,18 @@ 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
-Requires-Dist: pyutilkit (~=0.4)
+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]
@@ -36,10 +40,14 @@ hopes to stop this repetition.
 -   [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://github.com/spapanik/pyutilkit/blob/main/docs/LICENSE.md
+[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
@@ -51,4 +59,4 @@ hopes to stop this repetition.
 [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
+[Changelog]: https://pyutilkit.readthedocs.io/en/stable/CHANGELOG/

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

@@ -1,5 +1,7 @@
 # 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]
@@ -19,10 +21,14 @@ hopes to stop this repetition.
 -   [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://github.com/spapanik/pyutilkit/blob/main/docs/LICENSE.md
+[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
@@ -34,4 +40,4 @@ hopes to stop this repetition.
 [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
+[Changelog]: https://pyutilkit.readthedocs.io/en/stable/CHANGELOG/

pyproject.toml → pyutilkit-0.9.0/pyproject.toml

@@ -1,12 +1,12 @@
 [build-system]
 requires = [
-    "phosphorus>=0.4",
+    "phosphorus>=0.8",
 ]
 build-backend = "phosphorus.construction.api"
 
 [project]
 name = "pyutilkit"
-version = "0.5.0"
+version = "0.9.0"
 
 authors = [
     { name = "Stephanos Kuma", email = "stephanos@kuma.ai" },
@@ -21,11 +21,13 @@ keywords = [
 classifiers = [
     "Development Status :: 4 - Beta",
     "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: BSD License",
 ]
 
 requires-python = ">=3.9"
 dependencies = [
-    "pyutilkit~=0.4",
+    "tzdata; os_name == 'nt'",
 ]
 
 [project.urls]
@@ -35,26 +37,25 @@ documentation = "https://pyutilkit.readthedocs.io/en/stable/"
 
 [tool.phosphorus.dev-dependencies]
 dev = [
-    "ipdb~=0.13; python_version>='3.10'",
-    "ipython~=8.21; python_version>='3.10'",
+    "ipdb~=0.13",
+    "ipython~=8.18",
 ]
 lint = [
-    "black~=24.1",
-    "mypy~=1.8",
-    "ruff~=0.5",
-    "typing_extensions~=4.11",
+    "black~=24.10",
+    "mypy~=1.13",
+    "ruff~=0.8",
 ]
 test = [
     "freezegun~=1.5",
-    "pytest~=8.0",
-    "pytest-cov~=5.0",
+    "pytest~=8.3",
+    "pytest-cov~=6.0",
 ]
 docs = [
     "mkdocs~=1.6",
     "mkdocs-material~=9.5",
     "mkdocs-material-extensions~=1.3",
-    "Pygments~=2.17",
-    "pymdown-extensions~=10.8",
+    "pygments~=2.18",
+    "pymdown-extensions~=10.12",
 ]
 
 [tool.black]
@@ -64,7 +65,11 @@ target-version = [
 
 [tool.mypy]
 check_untyped_defs = true
+disallow_any_decorated = true
+disallow_any_explicit = true
+disallow_any_expr = false          # many builtins are Any
 disallow_any_generics = true
+disallow_any_unimported = true
 disallow_incomplete_defs = true
 disallow_subclassing_any = true
 disallow_untyped_calls = true
@@ -73,13 +78,18 @@ disallow_untyped_defs = true
 extra_checks = true
 ignore_missing_imports = true
 no_implicit_reexport = true
+show_column_numbers = true
 show_error_codes = true
 strict_equality = true
-warn_return_any = true
 warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
 warn_unused_ignores = true
 warn_unreachable = true
-warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_any_decorated = false # mock.MagicMock is Any
 
 [tool.ruff]
 src = [
@@ -89,74 +99,23 @@ 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",
-    "PLC",
-    "PLE",
-    "PLW",
-    "PT",
-    "PTH",
-    "Q",
-    "RET",
-    "RSE",
-    "RUF",
-    "S",
-    "SIM",
-    "SLF",
-    "SLOT",
-    "T10",
-    "TCH",
-    "TD",
-    "TID",
-    "TRY",
-    "UP",
-    "W",
-    "YTT",
+    "ALL",
 ]
 ignore = [
-    "ANN101",
-    "ANN102",
-    "ANN401",
-    "COM812",
-    "E501",
-    "FIX002",
-    "TD002",
-    "TD003",
-    "TRY003",
+    "C901",   # Adding a limit to complexity is too arbitrary
+    "COM812", # Avoid magic trailing commas
+    "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
 ]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [
-    "FBT001",
-    "PT011",
-    "S101",
+    "FBT001",  # Test arguments are handled by pytest
+    "PLR2004", # Tests should contain magic number comparisons
+    "S101",    # Pytest needs assert statements
 ]
 
 [tool.ruff.lint.flake8-tidy-imports]
@@ -174,16 +133,22 @@ forced-separate = [
 split-on-trailing-comma = false
 
 [tool.pytest.ini_options]
-addopts = "-vv"
+addopts = "-ra -v"
 testpaths = "tests"
 
 [tool.coverage.run]
+branch = true
 source = [
     "src/",
 ]
 data_file = ".cov_cache/coverage.dat"
 
 [tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+]
+fail_under = 90
+precision = 2
 show_missing = true
 skip_covered = true
 skip_empty = true

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

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

{src → pyutilkit-0.9.0/src}/pyutilkit/date_utils.py

@@ -9,8 +9,7 @@ UTC = ZoneInfo("UTC")
 
 
 def get_timezones() -> set[str]:
-    """
-    Get all the available timezones
+    """Get all the available timezones.
 
     This takes into accounts timezones that might not be present in
     all systems.
@@ -23,8 +22,7 @@ def now(tz_info: ZoneInfo = UTC) -> datetime:
 
 
 def from_iso(date_string: str, tz_info: tzinfo = UTC) -> datetime:
-    """
-    Get datetime from an iso string
+    """Get datetime from an iso string.
 
     This to allow the Zulu timezone, which is a valid ISO timezone.
     """
@@ -37,16 +35,13 @@ def from_iso(date_string: str, tz_info: tzinfo = UTC) -> datetime:
 
 
 def from_timestamp(timestamp: float, tz_info: tzinfo = UTC) -> datetime:
-    """
-    Get a datetime tz-aware time object from a timestamp
-    """
+    """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
+    """Add a timezone to a naive datetime.
 
     Raise an error in case of a tz-aware datetime
     """
@@ -57,8 +52,7 @@ def add_timezone(dt: datetime, tz_info: tzinfo = UTC) -> datetime:
 
 
 def convert_timezone(dt: datetime, tz_info: tzinfo = UTC) -> datetime:
-    """
-    Change the timezone of a tz-aware datetime
+    """Change the timezone of a tz-aware datetime.
 
     Raise an error in case of a naive datetime
     """

{src → pyutilkit-0.9.0/src}/pyutilkit/subprocess.py

@@ -3,10 +3,13 @@ from __future__ import annotations
 import sys
 from dataclasses import dataclass
 from subprocess import PIPE, Popen
-from typing import Any
+from typing import TYPE_CHECKING
 
 from pyutilkit.timing import Stopwatch, Timing
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 
 @dataclass(frozen=True)
 class ProcessOutput:
@@ -17,19 +20,18 @@ class ProcessOutput:
     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)
-
+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(command, **kwargs)  # noqa: S603
+        process = Popen(  # noqa: S603
+            command, stdout=PIPE, stderr=PIPE, cwd=cwd, env=env
+        )
 
         for line in process.stdout or []:
             sys.stdout.buffer.write(line)

pyutilkit-0.9.0/src/pyutilkit/term.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from enum import IntEnum, unique
+from math import ceil, floor
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from typing_extensions import Self  # py3.10: import from typing
+
+TRUE_VAR = {"0", "false", "no"}
+
+
+@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"
+
+
+@dataclass(frozen=True, order=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
+    _suffix: str
+    _force_prefix: bool
+    _force_sgr: bool
+    _is_error: bool
+
+    def __init__(
+        self,
+        obj: object,
+        *,
+        prefix: str = "",
+        suffix: str = "",
+        params: Iterable[SGRCodes] = (),
+        force_prefix: bool = False,
+        force_sgr: bool = False,
+        is_error: bool = False,
+    ) -> None:
+        params = tuple(params)
+        force_prefix = (
+            force_prefix or os.getenv("PY_UTIL_FORCE_PREFIX", "").lower() in TRUE_VAR
+        )
+        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))
+        object.__setattr__(self, "_sgr", params)
+        object.__setattr__(self, "_suffix", suffix)
+        object.__setattr__(self, "_force_prefix", force_prefix)
+        object.__setattr__(self, "_force_sgr", force_sgr)
+        object.__setattr__(self, "_is_error", is_error)
+
+    def __str__(self) -> str:
+        sgr_prefix = "".join(code.sequence for code in self._sgr)
+        sgr_suffix = SGRCodes.RESET.sequence if self._sgr else ""
+        return f"{self._prefix}{sgr_prefix}{self._string}{sgr_suffix}{self._suffix}"
+
+    def __len__(self) -> int:
+        return len(self._prefix) + len(self._string) + len(self._suffix)
+
+    def __mul__(self, other: object) -> Self:
+        if not isinstance(other, int):
+            return NotImplemented
+        return type(self)(
+            self._string * other,
+            prefix=self._prefix,
+            suffix=self._suffix,
+            params=self._sgr,
+            force_prefix=self._force_prefix,
+            force_sgr=self._force_sgr,
+            is_error=self._is_error,
+        )
+
+    def __rmul__(self, other: object) -> Self:
+        if not isinstance(other, int):
+            return NotImplemented
+        return type(self)(
+            self._string * other,
+            prefix=self._prefix,
+            suffix=self._suffix,
+            params=self._sgr,
+            force_prefix=self._force_prefix,
+            force_sgr=self._force_sgr,
+            is_error=self._is_error,
+        )
+
+    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,
+        otherwise to stderr.
+
+        If the output stream isn't a tty, it will strip the SGR codes and the prefix,
+        unless forced to keep them.
+        """
+        file = sys.stderr if self._is_error else sys.stdout
+        if file.isatty():
+            prefix = self._prefix
+            sgr_prefix = "".join(code.sequence for code in self._sgr)
+            sgr_suffix = SGRCodes.RESET.sequence
+            suffix = self._suffix
+        else:
+            prefix = ""
+            sgr_prefix = ""
+            sgr_suffix = ""
+            suffix = ""
+            if self._force_sgr:
+                sgr_prefix = "".join(code.sequence for code in self._sgr)
+                sgr_suffix = SGRCodes.RESET.sequence if self._sgr else ""
+            if self._force_prefix:
+                prefix = self._prefix
+                suffix = self._suffix
+
+        if full_color:
+            prefix, sgr_prefix = sgr_prefix, prefix
+            suffix, sgr_suffix = sgr_suffix, suffix
+
+        print(
+            prefix,
+            sgr_prefix,
+            self._string,
+            sgr_suffix,
+            suffix,
+            sep="",
+            end=end,
+            file=file,
+        )
+
+    def header(
+        self,
+        *,
+        padding: str = " ",
+        left_spaces: int = 1,
+        right_spaces: int = 1,
+        space: str = " ",
+    ) -> None:
+        try:
+            terminal_size = os.get_terminal_size()
+        except OSError:
+            # in pseudo-terminals an OSError is thrown
+            self.print()
+            return
+
+        columns = terminal_size.columns
+        title_length = left_spaces + len(self) + right_spaces
+        if title_length >= columns:
+            self.print()
+            return
+
+        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()
+
+
+@dataclass(frozen=True, order=True)
+class SGROutput:
+    __slots__ = ("_strings",)  # py3.9: remove this line
+    _strings: tuple[SGRString, ...]
+
+    def __init__(
+        self,
+        strings: Iterable[SGRString],
+        force_prefix: bool | None = None,
+        force_sgr: bool | None = None,
+        is_error: bool | None = None,
+    ) -> None:
+        strings = tuple(
+            self._clean_string(
+                string,
+                force_prefix=force_prefix,
+                force_sgr=force_sgr,
+                is_error=is_error,
+            )
+            for string in strings
+        )
+
+        object.__setattr__(self, "_strings", strings)
+
+    @staticmethod
+    def _clean_string(
+        string: SGRString,
+        force_prefix: bool | None,
+        force_sgr: bool | None,
+        is_error: bool | None,
+    ) -> SGRString:
+        force_prefix = (
+            string._force_prefix  # noqa: SLF001
+            if force_prefix is None
+            else force_prefix
+        )
+        force_sgr = (
+            string._force_sgr if force_sgr is None else force_sgr  # noqa: SLF001
+        )
+        is_error = string._is_error if is_error is None else is_error  # noqa: SLF001
+        return SGRString(
+            string._string,  # noqa: SLF001
+            prefix=string._prefix,  # noqa: SLF001
+            suffix=string._suffix,  # noqa: SLF001
+            params=string._sgr,  # noqa: SLF001
+            force_prefix=force_prefix,
+            force_sgr=force_sgr,
+            is_error=is_error,
+        )
+
+    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
+            string.print(end=current_end)
+
+    def header(
+        self,
+        *,
+        padding: str = " ",
+        left_spaces: int = 1,
+        right_spaces: int = 1,
+        space: str = " ",
+    ) -> None:
+        n = len(self._strings)
+        if n > 1:
+            msg = "Only one string is allowed for the header"
+            raise ValueError(msg)
+
+        self._strings[0].header(
+            padding=padding,
+            left_spaces=left_spaces,
+            right_spaces=right_spaces,
+            space=space,
+        )

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

@@ -2,13 +2,19 @@ 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
+from typing import TYPE_CHECKING
 
 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:
@@ -27,65 +33,65 @@ class Timing:
     ) -> None:
         total_nanoseconds = (
             nanoseconds
-            + 1000 * microseconds
-            + 1_000_000 * milliseconds
-            + 1_000_000_000 * seconds
-            + 86_400_000_000_000 * days
+            + 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 < 1000:
+        if self.nanoseconds < METRIC_MULTIPLIER:
             return f"{self.nanoseconds}ns"
-        microseconds = self.nanoseconds / 1000
-        if microseconds < 1000:
+        microseconds = self.nanoseconds / METRIC_MULTIPLIER
+        if microseconds < METRIC_MULTIPLIER:
             return f"{microseconds:.1f}µs"
-        milliseconds = microseconds / 1000
-        if milliseconds < 1000:
+        milliseconds = microseconds / METRIC_MULTIPLIER
+        if milliseconds < METRIC_MULTIPLIER:
             return f"{milliseconds:.1f}ms"
-        seconds = milliseconds / 1000
-        if seconds < 60:
+        seconds = milliseconds / METRIC_MULTIPLIER
+        if seconds < SECONDS_PER_MINUTE:
             return f"{seconds:.2f}s"
         round_seconds = int(seconds)
-        minutes, seconds = divmod(round_seconds, 60)
-        hours, minutes = divmod(minutes, 60)
-        if hours < 24:
+        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, 24)
+        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:
+    def __add__(self, other: object) -> Timing:
         if not isinstance(other, Timing):
             return NotImplemented
         return Timing(nanoseconds=self.nanoseconds + other.nanoseconds)
 
-    def __radd__(self, other: Any) -> Timing:
+    def __radd__(self, other: object) -> Timing:
         if not isinstance(other, Timing):
             return NotImplemented
         return Timing(nanoseconds=self.nanoseconds + other.nanoseconds)
 
-    def __mul__(self, other: Any) -> Timing:
+    def __mul__(self, other: object) -> Timing:
         if not isinstance(other, int):
             return NotImplemented
         return Timing(nanoseconds=self.nanoseconds * other)
 
-    def __rmul__(self, other: Any) -> Timing:
+    def __rmul__(self, other: object) -> Timing:
         if not isinstance(other, int):
             return NotImplemented
         return Timing(nanoseconds=self.nanoseconds * other)
 
-    def __floordiv__(self, other: Any) -> Timing:
+    def __floordiv__(self, other: object) -> Timing:
         if not isinstance(other, int):
             return NotImplemented
         return Timing(nanoseconds=self.nanoseconds // other)
 
-    def __truediv__(self, other: Any) -> Timing:
+    def __truediv__(self, other: object) -> Timing:
         if not isinstance(other, int):
             return NotImplemented
-        return Timing(nanoseconds=self.nanoseconds // other)
+        return Timing(nanoseconds=round(self.nanoseconds / other))
 
 
 class Stopwatch:
@@ -102,8 +108,8 @@ class Stopwatch:
 
     def __exit__(
         self,
-        exc_type: type[Exception] | None,
-        exc_value: Exception | None,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
         traceback: TracebackType | None,
     ) -> None:
         _end = perf_counter_ns()

src/pyutilkit/term.py

@@ -1,117 +0,0 @@
-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:
-            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:
-        columns = os.get_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)}")