dycw-utilities 0.152.0__py3-none-any.whl → 0.153.0__py3-none-any.whl

utilities/postgres.py

@@ -10,7 +10,7 @@ from sqlalchemy.orm import DeclarativeBase
 
 from utilities.asyncio import stream_command
 from utilities.iterables import always_iterable
-from utilities.logging import get_logger
+from utilities.logging import to_logger
 from utilities.os import temp_environ
 from utilities.pathlib import ensure_suffix
 from utilities.sqlalchemy import extract_url, get_table_name
@@ -22,7 +22,7 @@ if TYPE_CHECKING:
 
     from utilities.sqlalchemy import TableOrORMInstOrClass
     from utilities.types import (
-        LoggerOrName,
+        LoggerLike,
         MaybeCollection,
         MaybeCollectionStr,
         PathLike,
@@ -53,7 +53,7 @@ async def pg_dump(
     role: str | None = None,
     docker: str | None = None,
     dry_run: bool = False,
-    logger: LoggerOrName | None = None,
+    logger: LoggerLike | None = None,
 ) -> None:
     """Run `pg_dump`."""
     path = _path_pg_dump(path, format_=format_)
@@ -79,14 +79,14 @@ async def pg_dump(
     )
     if dry_run:
         if logger is not None:
-            get_logger(logger=logger).info("Would run:\n\t%r", str(cmd))
+            to_logger(logger).info("Would run:\n\t%r", str(cmd))
         return
     with temp_environ(PGPASSWORD=url.password), Timer() as timer:  # pragma: no cover
         try:
             output = await stream_command(cmd)
         except KeyboardInterrupt:
             if logger is not None:
-                get_logger(logger=logger).info(
+                to_logger(logger).info(
                     "Cancelled backup to %r after %s", str(path), timer
                 )
             rmtree(path, ignore_errors=True)
@@ -94,12 +94,12 @@ async def pg_dump(
             match output.return_code:
                 case 0:
                     if logger is not None:
-                        get_logger(logger=logger).info(
+                        to_logger(logger).info(
                             "Backup to %r finished after %s", str(path), timer
                         )
                 case _:
                     if logger is not None:
-                        get_logger(logger=logger).exception(
+                        to_logger(logger).exception(
                             "Backup to %r failed after %s\nstderr:\n%s",
                             str(path),
                             timer,
@@ -217,7 +217,7 @@ async def restore(
     role: str | None = None,
     docker: str | None = None,
     dry_run: bool = False,
-    logger: LoggerOrName | None = None,
+    logger: LoggerLike | None = None,
 ) -> None:
     """Run `pg_restore`/`psql`."""
     cmd = _build_pg_restore_or_psql(
@@ -236,26 +236,26 @@ async def restore(
     )
     if dry_run:
         if logger is not None:
-            get_logger(logger=logger).info("Would run:\n\t%r", str(cmd))
+            to_logger(logger).info("Would run:\n\t%r", str(cmd))
         return
     with temp_environ(PGPASSWORD=url.password), Timer() as timer:  # pragma: no cover
         try:
             output = await stream_command(cmd)
         except KeyboardInterrupt:
             if logger is not None:
-                get_logger(logger=logger).info(
+                to_logger(logger).info(
                     "Cancelled restore from %r after %s", str(path), timer
                 )
         else:
             match output.return_code:
                 case 0:
                     if logger is not None:
-                        get_logger(logger=logger).info(
+                        to_logger(logger).info(
                             "Restore from %r finished after %s", str(path), timer
                         )
                 case _:
                     if logger is not None:
-                        get_logger(logger=logger).exception(
+                        to_logger(logger).exception(
                             "Restore from %r failed after %s\nstderr:\n%s",
                             str(path),
                             timer,

utilities/pottery.py

@@ -14,7 +14,7 @@ from utilities.asyncio import loop_until_succeed, sleep_td, timeout_td
 from utilities.contextlib import enhanced_async_context_manager
 from utilities.contextvars import yield_set_context
 from utilities.iterables import always_iterable
-from utilities.logging import get_logger
+from utilities.logging import to_logger
 from utilities.whenever import MILLISECOND, SECOND, to_seconds
 
 if TYPE_CHECKING:
@@ -23,7 +23,7 @@ if TYPE_CHECKING:
 
     from whenever import Delta
 
-    from utilities.types import Coro, LoggerOrName, MaybeIterable
+    from utilities.types import Coro, LoggerLike, MaybeIterable
 
 _NUM: int = 1
 _TIMEOUT_TRY_ACQUIRE: Delta = SECOND
@@ -57,7 +57,7 @@ async def try_yield_coroutine_looper(
     timeout_acquire: Delta = _TIMEOUT_TRY_ACQUIRE,
     sleep_acquire: Delta = _SLEEP,
     throttle: Delta | None = None,
-    logger: LoggerOrName | None = None,
+    logger: LoggerLike | None = None,
     sleep_error: Delta | None = None,
     context: ContextVar[bool] | None = None,
 ) -> AsyncIterator[CoroutineLooper | None]:
@@ -81,7 +81,7 @@ async def try_yield_coroutine_looper(
                     yield looper
     except _YieldAccessUnableToAcquireLockError as error:  # skipif-ci-and-not-linux
         if logger is not None:
-            get_logger(logger=logger).info("%s", error)
+            to_logger(logger).info("%s", error)
         async with nullcontext():
             yield
 
@@ -91,7 +91,7 @@ class CoroutineLooper:
     """Looper, guarded by a lock, to repeatedly call a coroutine until it succeeds."""
 
     lock: AIORedlock
-    logger: LoggerOrName | None = None
+    logger: LoggerLike | None = None
     sleep: Delta | None = None
 
     async def __call__[**P](

utilities/pyinstrument.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 from pyinstrument.profiler import Profiler
 
 from utilities.atomicwrites import writer
-from utilities.pathlib import get_path
+from utilities.pathlib import to_path
 from utilities.whenever import format_compact, get_now, to_local_plain
 
 if TYPE_CHECKING:
@@ -17,11 +17,11 @@ if TYPE_CHECKING:
 
 
 @contextmanager
-def profile(*, path: MaybeCallablePathLike | None = Path.cwd) -> Iterator[None]:
+def profile(path: MaybeCallablePathLike = Path.cwd, /) -> Iterator[None]:
     """Profile the contents of a block."""
     with Profiler() as profiler:
         yield
-    filename = get_path(path=path).joinpath(
+    filename = to_path(path).joinpath(
         f"profile__{format_compact(to_local_plain(get_now()))}.html"
     )
     with writer(filename) as temp:

utilities/pytest.py

@@ -173,7 +173,7 @@ def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
             def throttle_sync_on_pass(*args: Any, **kwargs: Any) -> None:
                 _skipif_recent(root=root, delta=delta)
                 cast("Callable[..., None]", func)(*args, **kwargs)
-                _write(root=root)
+                _write(root)
 
             return cast("Any", throttle_sync_on_pass)
 
@@ -182,7 +182,7 @@ def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
             @wraps(func)
             def throttle_sync_on_try(*args: Any, **kwargs: Any) -> None:
                 _skipif_recent(root=root, delta=delta)
-                _write(root=root)
+                _write(root)
                 cast("Callable[..., None]", func)(*args, **kwargs)
 
             return cast("Any", throttle_sync_on_try)
@@ -193,7 +193,7 @@ def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
             async def throttle_async_on_pass(*args: Any, **kwargs: Any) -> None:
                 _skipif_recent(root=root, delta=delta)
                 await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
-                _write(root=root)
+                _write(root)
 
             return cast("Any", throttle_async_on_pass)
 
@@ -202,7 +202,7 @@ def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
             @wraps(func)
             async def throttle_async_on_try(*args: Any, **kwargs: Any) -> None:
                 _skipif_recent(root=root, delta=delta)
-                _write(root=root)
+                _write(root)
                 await cast("Callable[..., Coro[None]]", func)(*args, **kwargs)
 
             return cast("Any", throttle_async_on_try)
@@ -214,7 +214,7 @@ def _throttle_inner[F: Callable[..., MaybeCoro[None]]](
 def _skipif_recent(*, root: PathLike | None = None, delta: Delta = SECOND) -> None:
     if skip is None:
         return  # pragma: no cover
-    path = _get_path(root=root)
+    path = _get_path(root)
     try:
         contents = path.read_text()
     except FileNotFoundError:
@@ -229,7 +229,7 @@ def _skipif_recent(*, root: PathLike | None = None, delta: Delta = SECOND) -> No
         _ = skip(reason=f"{_get_name()} throttled (age {age})")
 
 
-def _get_path(*, root: PathLike | None = None) -> Path:
+def _get_path(root: PathLike | None = None, /) -> Path:
     if root is None:
         root_use = get_root().joinpath(".pytest_cache", "throttle")  # pragma: no cover
     else:
@@ -246,8 +246,8 @@ def _get_name() -> str:
     return environ["PYTEST_CURRENT_TEST"]
 
 
-def _write(*, root: PathLike | None = None) -> None:
-    path = _get_path(root=root)
+def _write(root: PathLike | None = None, /) -> None:
+    path = _get_path(root)
     with writer(path, overwrite=True) as temp:
         _ = temp.write_text(get_now_local().format_common_iso())
 

utilities/pytest_plugins/pytest_randomly.py

@@ -17,7 +17,7 @@ else:
         """Fixture for a random state."""
         from utilities.random import get_state
 
-        return get_state(seed=seed)
+        return get_state(seed)
 
 
 __all__ = ["random_state"]

utilities/pytest_plugins/pytest_regressions.py

@@ -46,7 +46,7 @@ def _get_path(request: FixtureRequest, /) -> Path:
     path = Path(cast("Any", request).fspath)
     root = Path("src", "tests")
     tail = node_id_path(request.node.nodeid, root=root)
-    return get_root(path=path).joinpath(root, "regressions", tail)
+    return get_root(path).joinpath(root, "regressions", tail)
 
 
 __all__ = ["orjson_regression", "polars_regression"]

utilities/random.py

@@ -17,16 +17,16 @@ SYSTEM_RANDOM = SystemRandom()
 
 def bernoulli(*, true: float = 0.5, seed: Seed | None = None) -> bool:
     """Return a Bernoulli random variate."""
-    seed = get_state(seed=seed)
-    return bool(seed.binomialvariate(p=true))
+    state = get_state(seed)
+    return bool(state.binomialvariate(p=true))
 
 
 ##
 
 
-def get_docker_name(*, seed: Seed | None = None) -> str:
+def get_docker_name(seed: Seed | None = None, /) -> str:
     """Get a docker name."""
-    state = get_state(seed=seed)
+    state = get_state(seed)
     prefix = state.choice(_DOCKER_PREFIXES)
     suffix = state.choice(_DOCKER_SUFFIXES)
     digit = state.randint(0, 9)
@@ -47,16 +47,18 @@ _DOCKER_SUFFIXES = [
 ##
 
 
-def get_state(*, seed: Seed | None = None) -> Random:
+def get_state(seed: Seed | None = None, /) -> Random:
     """Get a random state."""
     return seed if isinstance(seed, Random) else Random(x=seed)
 
 
 ##
+
+
 def shuffle[T](iterable: Iterable[T], /, *, seed: Seed | None = None) -> list[T]:
     """Shuffle an iterable."""
     copy = list(iterable).copy()
-    state = get_state(seed=seed)
+    state = get_state(seed)
     state.shuffle(copy)
     return copy
 

utilities/text.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import re
 from collections import deque
+from collections.abc import Callable
 from dataclasses import dataclass
 from itertools import chain
 from os import getpid
@@ -9,16 +10,25 @@ from re import IGNORECASE, Match, escape, search
 from textwrap import dedent
 from threading import get_ident
 from time import time_ns
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, overload, override
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Literal,
+    assert_never,
+    overload,
+    override,
+)
 from uuid import uuid4
 
 from utilities.iterables import CheckDuplicatesError, check_duplicates, transpose
 from utilities.reprlib import get_repr
+from utilities.sentinel import Sentinel
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Mapping, Sequence
 
-    from utilities.types import StrStrMapping
+    from utilities.types import MaybeCallableBoolLike, StrStrMapping
 
 
 DEFAULT_SEPARATOR = ","
@@ -428,6 +438,30 @@ def strip_and_dedent(text: str, /, *, trailing: bool = False) -> str:
 ##
 
 
+@overload
+def to_bool(bool_: MaybeCallableBoolLike, /) -> bool: ...
+@overload
+def to_bool(bool_: None, /) -> None: ...
+@overload
+def to_bool(bool_: Sentinel, /) -> Sentinel: ...
+def to_bool(
+    bool_: MaybeCallableBoolLike | None | Sentinel, /
+) -> bool | None | Sentinel:
+    """Convert to a bool."""
+    match bool_:
+        case bool() | None | Sentinel():
+            return bool_
+        case str():
+            return parse_bool(bool_)
+        case Callable() as func:
+            return to_bool(func())
+        case never:
+            assert_never(never)
+
+
+##
+
+
 def unique_str() -> str:
     """Generate at unique string."""
     now = time_ns()
@@ -456,5 +490,6 @@ __all__ = [
     "split_str",
     "str_encode",
     "strip_and_dedent",
+    "to_bool",
     "unique_str",
 ]

utilities/traceback.py

@@ -15,9 +15,8 @@ from typing import TYPE_CHECKING, override
 
 from utilities.atomicwrites import writer
 from utilities.errors import repr_error
-from utilities.functions import to_bool
 from utilities.iterables import OneEmptyError, one
-from utilities.pathlib import get_path, module_path
+from utilities.pathlib import module_path, to_path
 from utilities.reprlib import (
     RICH_EXPAND_ALL,
     RICH_INDENT_SIZE,
@@ -27,8 +26,9 @@ from utilities.reprlib import (
     RICH_MAX_WIDTH,
     yield_mapping_repr,
 )
+from utilities.text import to_bool
 from utilities.tzlocal import LOCAL_TIME_ZONE_NAME
-from utilities.version import get_version
+from utilities.version import to_version
 from utilities.whenever import (
     format_compact,
     get_now,
@@ -43,9 +43,9 @@ if TYPE_CHECKING:
     from types import TracebackType
 
     from utilities.types import (
-        MaybeCallableBool,
+        MaybeCallableBoolLike,
         MaybeCallablePathLike,
-        MaybeCallableZonedDateTime,
+        MaybeCallableZonedDateTimeLike,
         PathLike,
     )
     from utilities.version import MaybeCallableVersionLike
@@ -54,15 +54,12 @@ if TYPE_CHECKING:
 ##
 
 
-_START = get_now()
-
-
 def format_exception_stack(
     error: BaseException,
     /,
     *,
     header: bool = False,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     capture_locals: bool = False,
     max_width: int = RICH_MAX_WIDTH,
@@ -93,12 +90,12 @@ def format_exception_stack(
 
 def _yield_header_lines(
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
 ) -> Iterator[str]:
     """Yield the header lines."""
     now = get_now_local()
-    start_use = to_zoned_date_time(date_time=start)
+    start_use = to_zoned_date_time(start)
     yield f"Date/time  | {format_compact(now)}"
     if start_use is None:
         start_str = ""
@@ -111,7 +108,7 @@ def _yield_header_lines(
     yield f"User       | {getuser()}"
     yield f"Host       | {gethostname()}"
     yield f"Process ID | {getpid()}"
-    version_use = "" if version is None else get_version(version=version)
+    version_use = "" if version is None else to_version(version)
     yield f"Version    | {version_use}"
     yield ""
 
@@ -205,7 +202,7 @@ def _trim_path(path: PathLike, pattern: str, /) -> Path | None:
 
 def make_except_hook(
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
     max_width: int = RICH_MAX_WIDTH,
@@ -215,7 +212,7 @@ def make_except_hook(
     max_depth: int | None = RICH_MAX_DEPTH,
     expand_all: bool = RICH_EXPAND_ALL,
     slack_url: str | None = None,
-    pudb: MaybeCallableBool = False,
+    pudb: MaybeCallableBoolLike = False,
 ) -> Callable[
     [type[BaseException] | None, BaseException | None, TracebackType | None], None
 ]:
@@ -242,7 +239,7 @@ def _make_except_hook_inner(
     traceback: TracebackType | None,
     /,
     *,
-    start: MaybeCallableZonedDateTime | None = _START,
+    start: MaybeCallableZonedDateTimeLike = get_now,
     version: MaybeCallableVersionLike | None = None,
     path: MaybeCallablePathLike | None = None,
     max_width: int = RICH_MAX_WIDTH,
@@ -252,7 +249,7 @@ def _make_except_hook_inner(
     max_depth: int | None = RICH_MAX_DEPTH,
     expand_all: bool = RICH_EXPAND_ALL,
     slack_url: str | None = None,
-    pudb: MaybeCallableBool = False,
+    pudb: MaybeCallableBoolLike = False,
 ) -> None:
     """Exception hook to log the traceback."""
     _ = (exc_type, traceback)
@@ -262,7 +259,7 @@ def _make_except_hook_inner(
     _ = sys.stderr.write(f"{slim}\n")  # don't 'from sys import stderr'
     if path is not None:
         path = (
-            get_path(path=path)
+            to_path(path)
             .joinpath(format_compact(to_local_plain(get_now())))
             .with_suffix(".txt")
         )
@@ -289,7 +286,7 @@ def _make_except_hook_inner(
         except SendToSlackError as error:
             _ = stderr.write(f"{error}\n")
 
-    if to_bool(bool_=pudb):  # pragma: no cover
+    if to_bool(pudb):  # pragma: no cover
         from pudb import post_mortem
 
         post_mortem(tb=traceback, e_type=exc_type, e_value=exc_val)

utilities/typed_settings.py

@@ -26,7 +26,7 @@ from whenever import (
 )
 
 from utilities.iterables import always_iterable
-from utilities.pathlib import get_path
+from utilities.pathlib import to_path
 from utilities.string import substitute_environ
 
 if TYPE_CHECKING:
@@ -86,12 +86,12 @@ def _make_converter[T](
 
 
 def _parse_path(
-    path: str, /, *, resolve: bool = False, pwd: MaybeCallablePathLike | None = None
+    path: str, /, *, resolve: bool = False, pwd: MaybeCallablePathLike = Path.cwd
 ) -> Path:
     path = substitute_environ(path, **environ)
     match resolve:
         case True:
-            return get_path(path=pwd).joinpath(path).resolve()
+            return to_path(pwd).joinpath(path).resolve()
         case False:
             return Path(path)
         case never:

utilities/types.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import datetime as dt
-from asyncio import Event
 from collections.abc import Callable, Collection, Coroutine, Iterable, Mapping
 from enum import Enum
 from ipaddress import IPv4Address, IPv6Address
@@ -19,6 +18,7 @@ from typing import (
     overload,
     runtime_checkable,
 )
+from uuid import UUID
 from zoneinfo import ZoneInfo
 
 from whenever import (
@@ -39,6 +39,7 @@ _T_contra = TypeVar("_T_contra", contravariant=True)
 
 
 # basic
+type BoolLike = MaybeStr[bool]
 type OpenMode = Literal[
     "r",
     "w",
@@ -62,8 +63,7 @@ type OpenMode = Literal[
     "a+b",
 ]
 type MaybeCallable[T] = T | Callable[[], T]
-type MaybeCallableBool = MaybeCallable[bool]
-type MaybeCallableStr = MaybeCallable[str]
+type MaybeCallableBoolLike = MaybeCallable[BoolLike]
 type MaybeStr[T] = T | str
 type MaybeType[T] = T | type[T]
 type StrMapping = Mapping[str, Any]
@@ -74,7 +74,6 @@ type TupleOrStrMapping = tuple[Any, ...] | StrMapping
 
 # asyncio
 type Coro[T] = Coroutine[Any, Any, T]
-type MaybeCallableEvent = MaybeCallable[Event]
 type MaybeCoro[T] = T | Coro[T]
 
 
@@ -115,10 +114,11 @@ IPv6AddressLike = MaybeStr[IPv6Address]
 
 
 # iterables
+type SequenceLT[T] = list[T] | tuple[T, ...]
+# iterables - maybe
 type MaybeCollection[T] = T | Collection[T]
 type MaybeIterable[T] = T | Iterable[T]
 type MaybeSequence[T] = T | SequenceLT[T]
-type SequenceLT[T] = list[T] | tuple[T, ...]
 # iterables - str
 type SequenceStr = SequenceLT[str]
 type CollectionStr = dict[str, Any] | frozenset[str] | set[str] | SequenceStr
@@ -129,7 +129,7 @@ type MaybeSequenceStr = str | SequenceStr
 
 # logging
 type LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
-type LoggerOrName = MaybeStr[Logger]
+type LoggerLike = MaybeStr[Logger]
 
 
 # math
@@ -213,8 +213,8 @@ type SerializeObjectExtra = Mapping[Any, Callable[[Any], str]]
 
 
 # pathlib
-type MaybeCallablePathLike = MaybeCallable[PathLike]
 type PathLike = MaybeStr[Path]
+type MaybeCallablePathLike = MaybeCallable[PathLike]
 
 
 # random
@@ -225,11 +225,20 @@ type Seed = int | float | str | bytes | bytearray | Random
 type PatternLike = MaybeStr[Pattern[str]]
 
 
+# text
+type MaybeCallableStr = MaybeCallable[str]
+
+
 # traceback
 type ExcInfo = tuple[type[BaseException], BaseException, TracebackType]
 type OptExcInfo = ExcInfo | tuple[None, None, None]
 
 
+# uuid
+type UUIDLike = MaybeStr[UUID]
+type MaybeCallableUUIDLike = MaybeCallable[UUIDLike | Seed]
+
+
 # whenever
 type DateDeltaLike = MaybeStr[DateDelta]
 type DateLike = MaybeStr[Date]
@@ -239,8 +248,8 @@ type DateTimeRoundMode = Literal[
     "ceil", "floor", "half_ceil", "half_floor", "half_even"
 ]
 type Delta = DateDelta | TimeDelta | DateTimeDelta
-type MaybeCallableDate = MaybeCallable[Date]
-type MaybeCallableZonedDateTime = MaybeCallable[ZonedDateTime]
+type MaybeCallableDateLike = MaybeCallable[DateLike]
+type MaybeCallableZonedDateTimeLike = MaybeCallable[ZonedDateTimeLike]
 type MonthDayLike = MaybeStr[MonthDay]
 type PlainDateTimeLike = MaybeStr[PlainDateTime]
 type TimeDeltaLike = MaybeStr[TimeDelta]
@@ -277,15 +286,15 @@ __all__ = [
     "IPv4AddressLike",
     "IPv6AddressLike",
     "LogLevel",
-    "LoggerOrName",
+    "LoggerLike",
     "MathRoundMode",
     "MaybeCallable",
-    "MaybeCallableBool",
-    "MaybeCallableDate",
-    "MaybeCallableEvent",
+    "MaybeCallableBoolLike",
+    "MaybeCallableDateLike",
     "MaybeCallablePathLike",
     "MaybeCallableStr",
-    "MaybeCallableZonedDateTime",
+    "MaybeCallableUUIDLike",
+    "MaybeCallableZonedDateTimeLike",
     "MaybeCollection",
     "MaybeCollectionStr",
     "MaybeCoro",
@@ -329,6 +338,7 @@ __all__ = [
     "TimeZoneLike",
     "TupleOrStrMapping",
     "TypeLike",
+    "UUIDLike",
     "WeekDay",
     "YearMonthLike",
     "ZonedDateTimeLike",