pyutilkit 0.1.0__tar.gz → 0.3.0__tar.gz

{pyutilkit-0.1.0 → pyutilkit-0.3.0}/PKG-INFO

@@ -1,18 +1,17 @@
 Metadata-Version: 2.1
 Name: pyutilkit
-Version: 0.1.0
+Version: 0.3.0
 Summary: python's missing batteries
 Home-page: https://pyutilkit.readthedocs.io/en/stable/
 License: LGPL-3.0+
 Keywords: utils
 Author: Stephanos Kuma
 Author-email: stephanos@kuma.ai
-Requires-Python: >=3.8,<4.0
+Requires-Python: >=3.9,<4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -31,7 +30,11 @@ Description-Content-Type: text/markdown
 [![build automation: yam][yam_badge]][yam_url]
 [![Lint: ruff][ruff_badge]][ruff_url]
 
-Long project description and tldr goes here
+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
 

{pyutilkit-0.1.0 → pyutilkit-0.3.0}/docs/README.md

@@ -8,7 +8,11 @@
 [![build automation: yam][yam_badge]][yam_url]
 [![Lint: ruff][ruff_badge]][ruff_url]
 
-Long project description and tldr goes here
+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
 

{pyutilkit-0.1.0 → pyutilkit-0.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.black]
 target-version = [
-    "py38",
+    "py39",
 ]
 
 [tool.mypy]
@@ -32,7 +32,7 @@ warn_unused_configs = true
 src = [
     "src",
 ]
-target-version = "py38"
+target-version = "py39"
 
 [tool.ruff.lint]
 select = [
@@ -126,7 +126,7 @@ skip_empty = true
 
 [tool.poetry]
 name = "pyutilkit"
-version = "0.1.0"
+version = "0.3.0"
 description = "python's missing batteries"
 authors = [
     "Stephanos Kuma <stephanos@kuma.ai>",
@@ -149,7 +149,7 @@ classifiers = [
 
 [tool.poetry.dependencies]
 # python version
-python = "^3.8"
+python = "^3.9"
 
 [tool.poetry.group.dev.dependencies]
 ipdb = { version = "^0.13", python = "^3.10" }
@@ -161,6 +161,7 @@ pipdeptree = "^2.13"
 black = "^24.1"
 mypy = "^1.8"
 ruff = "^0.4"
+typing_extensions = "^4.11"
 
 [tool.poetry.group.test.dependencies]
 freezegun = "^1.5"

{pyutilkit-0.1.0 → pyutilkit-0.3.0}/src/pyutilkit/date_utils.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from datetime import datetime, tzinfo
-
 from zoneinfo import ZoneInfo, available_timezones
 
 from pyutilkit.data.timezones import UNAVAILABLE_TIMEZONES

pyutilkit-0.3.0/src/pyutilkit/files.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import hashlib
+import logging
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    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()

pyutilkit-0.3.0/src/pyutilkit/term.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from enum import IntEnum, unique
+from math import ceil, floor
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    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)}")

{pyutilkit-0.1.0 → pyutilkit-0.3.0}/src/pyutilkit/timing.py

@@ -1,4 +1,12 @@
+from __future__ import annotations  # py3.9: remove this line
+
 from dataclasses import dataclass
+from time import perf_counter_ns
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self  # py3.10: import Self from typing
 
 
 @dataclass(frozen=True, order=True)
@@ -36,3 +44,25 @@ class Timing:
             return f"{milliseconds:.1f}ms"
         seconds = milliseconds / 1000
         return f"{seconds:,.2f}s"
+
+
+class Stopwatch:
+    _start: int
+    timing: Timing
+
+    def __init__(self) -> None:
+        self._start = 0
+        self.timing = Timing(nanoseconds=0)
+
+    def __enter__(self) -> Self:
+        self._start = perf_counter_ns()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[Exception] | None,
+        exc_value: Exception | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        _end = perf_counter_ns()
+        self.timing = Timing(nanoseconds=_end - self._start)

pyutilkit-0.1.0/src/pyutilkit/__init__.py

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

pyutilkit-0.1.0/src/pyutilkit/term.py

@@ -1,96 +0,0 @@
-from __future__ import annotations
-
-import os
-from collections.abc import Iterable
-from enum import IntEnum, unique
-from math import ceil, floor
-from typing import Any
-
-
-@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: str
-    __slots__ = ("_sgr",)
-
-    def __new__(cls, value: Any, *, params: Iterable[SGRCodes] = ()) -> SGRString:
-        string = super().__new__(cls, value)
-        suffix = SGRCodes.RESET.sequence
-        prefix = "".join(param.sequence for param in params) or SGRCodes.RESET.sequence
-        object.__setattr__(string, "_sgr", f"{prefix}{value}{suffix}")
-        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:
-        return self._sgr
-
-
-def header(
-    text: str, *, padding: str = " ", left_spaces: int = 1, right_spaces: int = 1
-) -> None:
-    columns = os.get_terminal_size().columns
-    text = f"{' ' * left_spaces}{text.strip()}{' ' * right_spaces}"
-    title_length = len(text)
-    if title_length >= columns:
-        print(text.strip())
-        return
-
-    half = (columns - len(text)) / 2
-    print(f"{padding * ceil(half)}{text}{padding * floor(half)}")