dycw-utilities 0.127.0__py3-none-any.whl → 0.129.13__py3-none-any.whl

utilities/fastapi.py

@@ -1,15 +1,18 @@
 from __future__ import annotations
 
+from asyncio import Task, create_task
 from dataclasses import InitVar, dataclass, field
-from typing import TYPE_CHECKING, Any, Literal, override
+from typing import TYPE_CHECKING, Any, Literal, Self, override
 
 from fastapi import FastAPI
 from uvicorn import Config, Server
 
-from utilities.asyncio import InfiniteLooper
+from utilities.asyncio import Looper
 from utilities.datetime import SECOND, datetime_duration_to_float
 
 if TYPE_CHECKING:
+    from types import TracebackType
+
     from utilities.types import Duration
 
 
@@ -36,7 +39,7 @@ class _PingerReceiverApp(FastAPI):
 
 
 @dataclass(kw_only=True)
-class PingReceiver(InfiniteLooper):
+class PingReceiver(Looper[None]):
     """A ping receiver."""
 
     host: InitVar[str] = _LOCALHOST
@@ -44,12 +47,31 @@ class PingReceiver(InfiniteLooper):
     _app: _PingerReceiverApp = field(
         default_factory=_PingerReceiverApp, init=False, repr=False
     )
-    _await_upon_aenter: bool = field(default=False, init=False, repr=False)
     _server: Server = field(init=False, repr=False)
+    _server_task: Task[None] | None = field(default=None, init=False, repr=False)
 
+    @override
     def __post_init__(self, host: str, port: int, /) -> None:
+        super().__post_init__()  # skipif-ci
         self._server = Server(Config(self._app, host=host, port=port))  # skipif-ci
 
+    @override
+    async def __aenter__(self) -> Self:
+        _ = await super().__aenter__()  # skipif-ci
+        async with self._lock:  # skipif-ci
+            self._server_task = create_task(self._server.serve())
+        return self  # skipif-ci
+
+    @override
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: TracebackType | None = None,
+    ) -> None:
+        await super().__aexit__(exc_type, exc_value, traceback)  # skipif-ci
+        await self._server.shutdown()  # skipif-ci
+
     @classmethod
     async def ping(
         cls, port: int, /, *, host: str = _LOCALHOST, timeout: Duration = _TIMEOUT
@@ -66,13 +88,5 @@ class PingReceiver(InfiniteLooper):
             return False
         return response.text if response.status_code == 200 else False  # skipif-ci
 
-    @override
-    async def _initialize(self) -> None:
-        await self._server.serve()  # skipif-ci
-
-    @override
-    async def _teardown(self) -> None:
-        await self._server.shutdown()  # skipif-ci
-
 
 __all__ = ["PingReceiver"]

utilities/git.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 from re import IGNORECASE, search
-from subprocess import PIPE, CalledProcessError, check_call, check_output
+from subprocess import PIPE, CalledProcessError, check_output
 from typing import TYPE_CHECKING, override
 
 from utilities.pathlib import PWD
@@ -12,63 +12,17 @@ if TYPE_CHECKING:
     from utilities.types import PathLike
 
 
-def fetch_all_tags(*, cwd: PathLike = PWD) -> None:
-    """Fetch the tags."""
-    _ = check_call(["git", "fetch", "--all", "--tags"], cwd=cwd)
-
-
-##
-
-
-def get_branch_name(*, cwd: PathLike = PWD) -> str:
-    """Get the current branch name."""
-    output = check_output(
-        _GIT_REV_PARSE_ABBREV_REV_HEAD, stderr=PIPE, cwd=cwd, text=True
-    )
-    return output.strip("\n")
-
-
-_GIT_REV_PARSE_ABBREV_REV_HEAD = ["git", "rev-parse", "--abbrev-ref", "HEAD"]
-
-
-##
-
-
-def get_ref_tags(ref: str, /, *, cwd: PathLike = PWD) -> list[str]:
-    """Get the tags of a reference."""
-    output = check_output([*_GIT_TAG_POINTS_AT, ref], stderr=PIPE, cwd=cwd, text=True)
-    return output.strip("\n").splitlines()
-
-
-_GIT_TAG_POINTS_AT = ["git", "tag", "--points-at"]
-
-
-##
-
-
-def get_repo_name(*, cwd: PathLike = PWD) -> str:
-    """Get the repo name."""
-    output = check_output(_GIT_REMOTE_GET_URL_ORIGIN, stderr=PIPE, cwd=cwd, text=True)
-    return Path(output.strip("\n")).stem  # not valid_path
-
-
-_GIT_REMOTE_GET_URL_ORIGIN = ["git", "remote", "get-url", "origin"]
-
-
-##
-
-
-def get_repo_root(*, cwd: PathLike = PWD) -> Path:
+def get_repo_root(*, path: PathLike = PWD) -> Path:
     """Get the repo root."""
     try:
         output = check_output(
-            ["git", "rev-parse", "--show-toplevel"], stderr=PIPE, cwd=cwd, text=True
+            ["git", "rev-parse", "--show-toplevel"], stderr=PIPE, cwd=path, text=True
         )
     except CalledProcessError as error:
         # newer versions of git report "Not a git repository", whilst older
         # versions report "not a git repository"
         if search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
-            raise GetRepoRootError(cwd=cwd) from error
+            raise GetRepoRootError(cwd=path) from error
         raise  # pragma: no cover
     else:
         return Path(output.strip("\n"))
@@ -83,11 +37,4 @@ class GetRepoRootError(Exception):
         return f"Path is not part of a `git` repository: {self.cwd}"
 
 
-__all__ = [
-    "GetRepoRootError",
-    "fetch_all_tags",
-    "get_branch_name",
-    "get_ref_tags",
-    "get_repo_name",
-    "get_repo_root",
-]
+__all__ = ["GetRepoRootError", "get_repo_root"]

utilities/hypothesis.py

@@ -506,13 +506,7 @@ def floats_extra(
 
 
 @composite
-def git_repos(
-    draw: DrawFn,
-    /,
-    *,
-    branch: MaybeSearchStrategy[str | None] = None,
-    remote: MaybeSearchStrategy[str | None] = None,
-) -> Path:
+def git_repos(draw: DrawFn, /) -> Path:
     path = draw(temp_paths())
     with temp_cwd(path):
         _ = check_call(["git", "init", "-b", "master"])
@@ -525,10 +519,6 @@ def git_repos(
         _ = check_call(["git", "commit", "-m", "add"])
         _ = check_call(["git", "rm", file_str])
         _ = check_call(["git", "commit", "-m", "rm"])
-        if (branch_ := draw2(draw, branch)) is not None:
-            _ = check_call(["git", "checkout", "-b", branch_])
-        if (remote_ := draw2(draw, remote)) is not None:
-            _ = check_call(["git", "remote", "add", "origin", remote_])
     return path
 
 

utilities/logging.py

@@ -23,7 +23,7 @@ from logging import (
 )
 from logging.handlers import BaseRotatingHandler, TimedRotatingFileHandler
 from pathlib import Path
-from re import Pattern, search
+from re import Pattern
 from sys import stdout
 from time import time
 from typing import (
@@ -46,9 +46,8 @@ from utilities.datetime import (
     serialize_compact,
 )
 from utilities.errors import ImpossibleCaseError
-from utilities.git import get_repo_root
 from utilities.iterables import OneEmptyError, always_iterable, one
-from utilities.pathlib import ensure_suffix, resolve_path
+from utilities.pathlib import ensure_suffix, get_path, get_root
 from utilities.reprlib import (
     RICH_EXPAND_ALL,
     RICH_INDENT_SIZE,
@@ -68,9 +67,9 @@ if TYPE_CHECKING:
     from utilities.types import (
         LoggerOrName,
         LogLevel,
+        MaybeCallablePathLike,
         MaybeIterable,
         PathLike,
-        PathLikeOrCallable,
     )
     from utilities.version import MaybeCallableVersionLike
 
@@ -86,6 +85,9 @@ except ModuleNotFoundError:  # pragma: no cover
 type _When = Literal[
     "S", "M", "H", "D", "midnight", "W0", "W1", "W2", "W3", "W4", "W5", "W6"
 ]
+_BACKUP_COUNT: int = 100
+_MAX_BYTES: int = 10 * 1024**2
+_WHEN: _When = "D"
 
 
 class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
@@ -101,15 +103,16 @@ class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
         encoding: str | None = None,
         delay: bool = False,
         errors: Literal["strict", "ignore", "replace"] | None = None,
-        maxBytes: int = 0,
-        when: _When = "midnight",
+        maxBytes: int = _MAX_BYTES,
+        when: _When = _WHEN,
         interval: int = 1,
-        backupCount: int = 0,
+        backupCount: int = _BACKUP_COUNT,
         utc: bool = False,
         atTime: dt.time | None = None,
     ) -> None:
-        filename = str(Path(filename))
-        super().__init__(filename, mode, encoding=encoding, delay=delay, errors=errors)
+        path = Path(filename)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        super().__init__(path, mode, encoding=encoding, delay=delay, errors=errors)
         self._max_bytes = maxBytes if maxBytes >= 1 else None
         self._backup_count = backupCount if backupCount >= 1 else None
         self._filename = Path(self.baseFilename)
@@ -118,7 +121,7 @@ class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
         self._suffix = self._filename.suffix
         self._patterns = _compute_rollover_patterns(self._stem, self._suffix)
         self._time_handler = TimedRotatingFileHandler(
-            filename,
+            path,
             when=when,
             interval=interval,
             backupCount=backupCount,
@@ -161,13 +164,11 @@ class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
     def _should_rollover(self, record: LogRecord, /) -> bool:
         if self._max_bytes is not None:  # skipif-ci-and-windows
             try:
-                current = self._filename.stat().st_size
+                size = self._filename.stat().st_size
             except FileNotFoundError:
                 pass
             else:
-                delta = len(f"{self.format(record)}\n")
-                new = current + delta
-                if new >= self._max_bytes:
+                if size >= self._max_bytes:
                     return True
         return bool(self._time_handler.shouldRollover(record))  # skipif-ci-and-windows
 
@@ -383,10 +384,10 @@ class StandaloneFileHandler(Handler):
 
     @override
     def __init__(
-        self, *, level: int = NOTSET, path: PathLikeOrCallable | None = None
+        self, *, level: int = NOTSET, path: MaybeCallablePathLike | None = None
     ) -> None:
         super().__init__(level=level)
-        self._path = path
+        self._path = get_path(path=path)
 
     @override
     def emit(self, record: LogRecord) -> None:
@@ -394,10 +395,8 @@ class StandaloneFileHandler(Handler):
         from utilities.tzlocal import get_now_local
 
         try:
-            path = (
-                resolve_path(path=self._path)
-                .joinpath(serialize_compact(get_now_local()))
-                .with_suffix(".txt")
+            path = self._path.joinpath(serialize_compact(get_now_local())).with_suffix(
+                ".txt"
             )
             formatted = self.format(record)
             with writer(path, overwrite=True) as temp, temp.open(mode="w") as fh:
@@ -420,16 +419,53 @@ def add_filters(handler: Handler, /, *filters: _FilterType) -> None:
 
 def basic_config(
     *,
-    format: str = "{asctime} | {name} | {levelname:8} | {message}",  # noqa: A002
+    obj: LoggerOrName | Handler | None = None,
+    format_: str = "{asctime} | {name} | {levelname:8} | {message}",
+    whenever: bool = False,
     level: LogLevel = "INFO",
+    plain: bool = False,
 ) -> None:
     """Do the basic config."""
-    basicConfig(
-        format=format,
-        datefmt=maybe_sub_pct_y("%Y-%m-%d %H:%M:%S"),
-        style="{",
-        level=level,
-    )
+    if whenever:
+        format_ = format_.replace("{asctime}", "{zoned_datetime}")
+    datefmt = maybe_sub_pct_y("%Y-%m-%d %H:%M:%S")
+    match obj:
+        case None:
+            basicConfig(format=format_, datefmt=datefmt, style="{", level=level)
+        case Logger() as logger:
+            logger.setLevel(level)
+            logger.addHandler(handler := StreamHandler())
+            basic_config(
+                obj=handler,
+                format_=format_,
+                whenever=whenever,
+                level=level,
+                plain=plain,
+            )
+        case str() as name:
+            basic_config(
+                obj=get_logger(logger=name),
+                format_=format_,
+                whenever=whenever,
+                level=level,
+                plain=plain,
+            )
+        case Handler() as handler:
+            handler.setLevel(level)
+            if plain:
+                formatter = Formatter(fmt=format_, datefmt=datefmt, style="{")
+            else:
+                try:
+                    from coloredlogs import ColoredFormatter
+                except ModuleNotFoundError:  # pragma: no cover
+                    formatter = Formatter(fmt=format_, datefmt=datefmt, style="{")
+                else:
+                    formatter = ColoredFormatter(
+                        fmt=format_, datefmt=datefmt, style="{"
+                    )
+            handler.setFormatter(formatter)
+        case _ as never:
+            assert_never(never)
 
 
 ##
@@ -473,7 +509,7 @@ class FilterForKeyError(Exception):
 
 def get_default_logging_path() -> Path:
     """Get the logging default path."""
-    return get_repo_root().joinpath(".logs")
+    return get_root().joinpath(".logs")
 
 
 ##
@@ -520,11 +556,11 @@ def setup_logging(
     console_level: LogLevel | None = "INFO",
     console_filters: Iterable[_FilterType] | None = None,
     console_fmt: str = "❯ {_zoned_datetime_str} | {name}:{funcName}:{lineno} | {message}",  # noqa: RUF001
-    files_dir: PathLikeOrCallable | None = get_default_logging_path,
-    files_when: _When = "D",
+    files_dir: MaybeCallablePathLike | None = get_default_logging_path,
+    files_when: _When = _WHEN,
     files_interval: int = 1,
-    files_backup_count: int = 10,
-    files_max_bytes: int = 10 * 1024**2,
+    files_backup_count: int = _BACKUP_COUNT,
+    files_max_bytes: int = _MAX_BYTES,
     files_filters: Iterable[_FilterType] | None = None,
     files_fmt: str = "{_zoned_datetime_str} | {name}:{funcName}:{lineno} | {levelname:8} | {message}",
     filters: MaybeIterable[_FilterType] | None = None,
@@ -616,7 +652,7 @@ def setup_logging(
         logger_use.addHandler(console_high_and_exc_handler)
 
     # debug & info
-    directory = resolve_path(path=files_dir)  # skipif-ci-and-windows
+    directory = get_path(path=files_dir)  # skipif-ci-and-windows
     levels: list[LogLevel] = ["DEBUG", "INFO"]  # skipif-ci-and-windows
     for level, (subpath, files_or_plain_formatter) in product(  # skipif-ci-and-windows
         levels, [(Path(), files_formatter), (Path("plain"), plain_formatter)]
@@ -754,29 +790,6 @@ class _AdvancedLogRecord(LogRecord):
         cls.time_zone = time_zone.key  # skipif-ci-and-windows
         super().__init_subclass__(**kwargs)  # skipif-ci-and-windows
 
-    @override
-    def getMessage(self) -> str:
-        """Return the message for this LogRecord."""
-        msg = str(self.msg)  # pragma: no cover
-        if self.args:  # pragma: no cover
-            try:
-                return msg % self.args  # compability for 3rd party code
-            except ValueError as error:
-                if len(error.args) == 0:
-                    raise
-                first = error.args[0]
-                if search("unsupported format character", first):
-                    return msg.format(*self.args)
-                raise
-            except TypeError as error:
-                if len(error.args) == 0:
-                    raise
-                first = error.args[0]
-                if search("not all arguments converted", first):
-                    return msg.format(*self.args)
-                raise
-        return msg  # pragma: no cover
-
     @classmethod
     def get_now(cls) -> Any:
         """Get the current zoned datetime."""

utilities/pathlib.py

@@ -1,15 +1,22 @@
 from __future__ import annotations
 
-from contextlib import contextmanager
+from collections.abc import Callable
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass
 from itertools import chain
 from os import chdir
+from os.path import expandvars
 from pathlib import Path
-from typing import TYPE_CHECKING
+from re import IGNORECASE, search
+from subprocess import PIPE, CalledProcessError, check_output
+from typing import TYPE_CHECKING, assert_never, overload, override
+
+from utilities.sentinel import Sentinel, sentinel
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
 
-    from utilities.types import PathLike, PathLikeOrCallable
+    from utilities.types import MaybeCallablePathLike, PathLike
 
 PWD = Path.cwd()
 
@@ -25,20 +32,83 @@ def ensure_suffix(path: PathLike, suffix: str, /) -> Path:
     return path.with_name(name)
 
 
-def list_dir(path: PathLike, /) -> Sequence[Path]:
-    """List the contents of a directory."""
-    return sorted(Path(path).iterdir())
+##
+
+
+def expand_path(path: PathLike, /) -> Path:
+    """Expand a path."""
+    path = str(path)
+    path = expandvars(path)
+    return Path(path).expanduser()
+
 
+##
 
-def resolve_path(*, path: PathLikeOrCallable | None = None) -> Path:
-    """Resolve for a path."""
+
+@overload
+def get_path(*, path: MaybeCallablePathLike | None) -> Path: ...
+@overload
+def get_path(*, path: Sentinel) -> Sentinel: ...
+def get_path(
+    *, path: MaybeCallablePathLike | None | Sentinel = sentinel
+) -> Path | None | Sentinel:
+    """Get the path."""
     match path:
+        case Path() | Sentinel():
+            return path
+        case str():
+            return Path(path)
         case None:
             return Path.cwd()
-        case Path() | str():
-            return Path(path)
-        case _:
-            return Path(path())
+        case Callable() as func:
+            return get_path(path=func())
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
+def get_root(*, path: MaybeCallablePathLike | None = None) -> Path:
+    """Get the root of a path."""
+    path = get_path(path=path)
+    try:
+        output = check_output(
+            ["git", "rev-parse", "--show-toplevel"], stderr=PIPE, cwd=path, text=True
+        )
+    except CalledProcessError as error:
+        # newer versions of git report "Not a git repository", whilst older
+        # versions report "not a git repository"
+        if not search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
+            raise  # pragma: no cover
+    else:
+        return Path(output.strip("\n"))
+    all_paths = list(chain([path], path.parents))
+    with suppress(StopIteration):
+        return next(
+            p for p in all_paths if any(p_i.name == ".envrc" for p_i in p.iterdir())
+        )
+    raise GetRootError(path=path)
+
+
+@dataclass(kw_only=True, slots=True)
+class GetRootError(Exception):
+    path: PathLike
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to determine root from {str(self.path)!r}"
+
+
+##
+
+
+def list_dir(path: PathLike, /) -> Sequence[Path]:
+    """List the contents of a directory."""
+    return sorted(Path(path).iterdir())
+
+
+##
 
 
 @contextmanager
@@ -52,4 +122,4 @@ def temp_cwd(path: PathLike, /) -> Iterator[None]:
         chdir(prev)
 
 
-__all__ = ["ensure_suffix", "list_dir", "resolve_path", "temp_cwd"]
+__all__ = ["PWD", "ensure_suffix", "expand_path", "get_path", "list_dir", "temp_cwd"]

utilities/pyinstrument.py

@@ -7,23 +7,25 @@ from typing import TYPE_CHECKING
 from pyinstrument.profiler import Profiler
 
 from utilities.datetime import serialize_compact
-from utilities.pathlib import PWD
+from utilities.pathlib import get_path
 from utilities.tzlocal import get_now_local
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
-    from utilities.types import PathLike
+    from utilities.types import MaybeCallablePathLike
 
 
 @contextmanager
-def profile(*, path: PathLike = PWD) -> Iterator[None]:
+def profile(*, path: MaybeCallablePathLike | None = Path.cwd) -> Iterator[None]:
     """Profile the contents of a block."""
     from utilities.atomicwrites import writer
 
     with Profiler() as profiler:
         yield
-    filename = Path(path, f"profile__{serialize_compact(get_now_local())}.html")
+    filename = get_path(path=path).joinpath(
+        f"profile__{serialize_compact(get_now_local())}.html"
+    )
     with writer(filename) as temp, temp.open(mode="w") as fh:
         _ = fh.write(profiler.output_html())
 

utilities/pytest_regressions.py

@@ -10,8 +10,8 @@ from pytest import fixture
 from pytest_regressions.file_regression import FileRegressionFixture
 
 from utilities.functions import ensure_str
-from utilities.git import get_repo_root
 from utilities.operator import is_equal
+from utilities.pathlib import get_root
 from utilities.pytest import node_id_to_path
 
 if TYPE_CHECKING:
@@ -153,7 +153,7 @@ def polars_regression(
 
 def _get_path(request: FixtureRequest, /) -> Path:
     tail = node_id_to_path(request.node.nodeid, head=_PATH_TESTS)
-    return get_repo_root().joinpath(_PATH_TESTS, "regressions", tail)
+    return get_root().joinpath(_PATH_TESTS, "regressions", tail)
 
 
 __all__ = [

utilities/python_dotenv.py

@@ -2,29 +2,33 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from os import environ
+from pathlib import Path
 from typing import TYPE_CHECKING, override
 
 from dotenv import dotenv_values
 
 from utilities.dataclasses import _ParseDataClassMissingValuesError, parse_dataclass
-from utilities.git import get_repo_root
 from utilities.iterables import MergeStrMappingsError, merge_str_mappings
-from utilities.pathlib import PWD
+from utilities.pathlib import get_root
 from utilities.reprlib import get_repr
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
     from collections.abc import Set as AbstractSet
-    from pathlib import Path
 
-    from utilities.types import ParseObjectExtra, PathLike, StrMapping, TDataclass
+    from utilities.types import (
+        MaybeCallablePathLike,
+        ParseObjectExtra,
+        StrMapping,
+        TDataclass,
+    )
 
 
 def load_settings(
     cls: type[TDataclass],
     /,
     *,
-    cwd: PathLike = PWD,
+    path: MaybeCallablePathLike | None = Path.cwd,
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
     warn_name_errors: bool = False,
@@ -33,7 +37,7 @@ def load_settings(
     extra_parsers: ParseObjectExtra | None = None,
 ) -> TDataclass:
     """Load a set of settings from the `.env` file."""
-    path = get_repo_root(cwd=cwd).joinpath(".env")
+    path = get_root(path=path).joinpath(".env")
     if not path.exists():
         raise _LoadSettingsFileNotFoundError(path=path) from None
     maybe_values_dotenv = dotenv_values(path)