dycw-utilities 0.148.5__py3-none-any.whl → 0.174.12__py3-none-any.whl

utilities/dataclasses.py

@@ -6,11 +6,7 @@ from dataclasses import MISSING, dataclass, field, fields, replace
 from typing import TYPE_CHECKING, Any, Literal, assert_never, overload, override
 
 from utilities.errors import ImpossibleCaseError
-from utilities.functions import (
-    get_class_name,
-    is_dataclass_class,
-    is_dataclass_instance,
-)
+from utilities.functions import get_class_name
 from utilities.iterables import (
     OneStrEmptyError,
     OneStrNonUniqueError,
@@ -25,7 +21,7 @@ from utilities.parse import (
     serialize_object,
 )
 from utilities.re import ExtractGroupError, extract_group
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.text import (
     BRACKETS,
     LIST_SEPARATOR,
@@ -34,8 +30,8 @@ from utilities.text import (
     _SplitKeyValuePairsSplitError,
     split_key_value_pairs,
 )
-from utilities.types import SupportsLT
-from utilities.typing import get_type_hints
+from utilities.types import MaybeType, SupportsLT
+from utilities.typing import get_type_hints, is_dataclass_class, is_dataclass_instance
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -214,7 +210,7 @@ def is_nullable_lt[T: SupportsLT](x: T | None, y: T | None, /) -> bool | None:
             return True
         case 0:
             return None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -275,8 +271,7 @@ def mapping_to_dataclass[T: Dataclass](
     default = {
         f.name
         for f in fields_use
-        if (not isinstance(f.default, Sentinel))
-        or (not isinstance(f.default_factory, Sentinel))
+        if (not is_sentinel(f.default)) or (not is_sentinel(f.default_factory))
     }
     have = set(field_names_to_values) | default
     missing = {f.name for f in fields_use} - have
@@ -434,12 +429,10 @@ def replace_non_sentinel[T: Dataclass](
     """Replace attributes on a dataclass, filtering out sentinel values."""
     if in_place:
         for k, v in kwargs.items():
-            if not isinstance(v, Sentinel):
+            if not is_sentinel(v):
                 setattr(obj, k, v)
         return None
-    return replace(
-        obj, **{k: v for k, v in kwargs.items() if not isinstance(v, Sentinel)}
-    )
+    return replace(obj, **{k: v for k, v in kwargs.items() if not is_sentinel(v)})
 
 
 ##
@@ -520,7 +513,7 @@ def parse_dataclass[T: Dataclass](
             )
         case Mapping() as keys_to_serializes:
             ...
-        case _ as never:
+        case never:
             assert_never(never)
     fields = list(
         yield_fields(
@@ -833,7 +826,7 @@ def yield_fields(
     warn_name_errors: bool = False,
 ) -> Iterator[_YieldFieldsClass[Any]]: ...
 def yield_fields(
-    obj: Dataclass | type[Dataclass],
+    obj: MaybeType[Dataclass],
     /,
     *,
     globalns: StrMapping | None = None,
@@ -912,17 +905,11 @@ class _YieldFieldsInstance[T]:
         extra: Mapping[type[U], Callable[[U, U], bool]] | None = None,
     ) -> bool:
         """Check if the field value equals its default."""
-        if isinstance(self.default, Sentinel) and isinstance(
-            self.default_factory, Sentinel
-        ):
+        if is_sentinel(self.default) and is_sentinel(self.default_factory):
             return False
-        if (not isinstance(self.default, Sentinel)) and isinstance(
-            self.default_factory, Sentinel
-        ):
+        if (not is_sentinel(self.default)) and is_sentinel(self.default_factory):
             expected = self.default
-        elif isinstance(self.default, Sentinel) and (
-            not isinstance(self.default_factory, Sentinel)
-        ):
+        elif is_sentinel(self.default) and (not is_sentinel(self.default_factory)):
             expected = self.default_factory()
         else:  # pragma: no cover
             raise ImpossibleCaseError(
@@ -1002,7 +989,7 @@ def _empty_error_str_core(
             return f"any field starting with {key!r}"
         case True, False:
             return f"any field starting with {key!r} (modulo case)"
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1043,7 +1030,7 @@ def _non_unique_error_str_core(
             head_msg = f"exactly one field starting with {key!r}"
         case True, False:
             head_msg = f"exactly one field starting with {key!r} (modulo case)"
-        case _ as never:
+        case never:
             assert_never(never)
     return f"{head_msg}; got {first!r}, {second!r} and perhaps more"
 

utilities/docker.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, overload
+
+from utilities.errors import ImpossibleCaseError
+from utilities.logging import to_logger
+from utilities.subprocess import (
+    MKTEMP_DIR_CMD,
+    maybe_sudo_cmd,
+    mkdir,
+    mkdir_cmd,
+    rm_cmd,
+    run,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from utilities.types import LoggerLike, PathLike, Retry, StrStrMapping
+
+
+@overload
+def docker_cp(
+    src: tuple[str, PathLike],
+    dest: PathLike,
+    /,
+    *,
+    sudo: bool = False,
+    logger: LoggerLike | None = None,
+) -> None: ...
+@overload
+def docker_cp(
+    src: PathLike,
+    dest: tuple[str, PathLike],
+    /,
+    *,
+    sudo: bool = False,
+    logger: LoggerLike | None = None,
+) -> None: ...
+def docker_cp(
+    src: PathLike | tuple[str, PathLike],
+    dest: PathLike | tuple[str, PathLike],
+    /,
+    *,
+    sudo: bool = False,
+    logger: LoggerLike | None = None,
+) -> None:
+    match src, dest:
+        case Path() | str(), (str() as cont, Path() | str() as dest_path):
+            docker_exec(
+                cont, *maybe_sudo_cmd(*mkdir_cmd(dest_path, parent=True), sudo=sudo)
+            )
+            run(*docker_cp_cmd(src, dest, sudo=sudo), logger=logger)
+        case (str(), Path() | str()), Path() | str():
+            mkdir(dest, parent=True, sudo=sudo)
+            run(*docker_cp_cmd(src, dest, sudo=sudo), logger=logger)
+        case _:  # pragma: no cover
+            raise ImpossibleCaseError(case=[f"{src}", f"{dest=}"])
+
+
+@overload
+def docker_cp_cmd(
+    src: tuple[str, PathLike], dest: PathLike, /, *, sudo: bool = False
+) -> list[str]: ...
+@overload
+def docker_cp_cmd(
+    src: PathLike, dest: tuple[str, PathLike], /, *, sudo: bool = False
+) -> list[str]: ...
+def docker_cp_cmd(
+    src: PathLike | tuple[str, PathLike],
+    dest: PathLike | tuple[str, PathLike],
+    /,
+    *,
+    sudo: bool = False,
+) -> list[str]:
+    match src, dest:
+        case (Path() | str()) as src_use, (
+            str() as dest_cont,
+            Path() | str() as dest_path,
+        ):
+            dest_use = f"{dest_cont}:{dest_path}"
+        case (str() as src_cont, (Path() | str()) as src_path), (
+            Path() | str() as dest_use
+        ):
+            src_use = f"{src_cont}:{src_path}"
+        case _:  # pragma: no cover
+            raise ImpossibleCaseError(case=[f"{src}", f"{dest=}"])
+    parts: list[str] = ["docker", "cp", str(src_use), str(dest_use)]
+    return maybe_sudo_cmd(*parts, sudo=sudo)
+
+
+@overload
+def docker_exec(
+    container: str,
+    cmd: str,
+    /,
+    *cmds_or_args: str,
+    env: StrStrMapping | None = None,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    input: str | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[True],
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    **env_kwargs: str,
+) -> str: ...
+@overload
+def docker_exec(
+    container: str,
+    cmd: str,
+    /,
+    *cmds_or_args: str,
+    env: StrStrMapping | None = None,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    input: str | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: Literal[True],
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    **env_kwargs: str,
+) -> str: ...
+@overload
+def docker_exec(
+    container: str,
+    cmd: str,
+    /,
+    *cmds_or_args: str,
+    env: StrStrMapping | None = None,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    input: str | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: Literal[True],
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    **env_kwargs: str,
+) -> str: ...
+@overload
+def docker_exec(
+    container: str,
+    cmd: str,
+    /,
+    *cmds_or_args: str,
+    env: StrStrMapping | None = None,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    input: str | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[False] = False,
+    return_stdout: Literal[False] = False,
+    return_stderr: Literal[False] = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    **env_kwargs: str,
+) -> None: ...
+@overload
+def docker_exec(
+    container: str,
+    cmd: str,
+    /,
+    *cmds_or_args: str,
+    env: StrStrMapping | None = None,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    input: str | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    **env_kwargs: str,
+) -> str | None: ...
+def docker_exec(
+    container: str,
+    cmd: str,
+    /,
+    *cmds_or_args: str,
+    env: StrStrMapping | None = None,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    input: str | None = None,  # noqa: A002
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    **env_kwargs: str,
+) -> str | None:
+    cmd_and_args = docker_exec_cmd(  # skipif-ci
+        container,
+        cmd,
+        *cmds_or_args,
+        env=env,
+        interactive=input is not None,
+        user=user,
+        workdir=workdir,
+        **env_kwargs,
+    )
+    return run(  # skipif-ci
+        *cmd_and_args,
+        input=input,
+        print=print,
+        print_stdout=print_stdout,
+        print_stderr=print_stderr,
+        return_=return_,
+        return_stdout=return_stdout,
+        return_stderr=return_stderr,
+        retry=retry,
+        logger=logger,
+    )
+
+
+def docker_exec_cmd(
+    container: str,
+    cmd: str,
+    /,
+    *cmds_or_args: str,
+    env: StrStrMapping | None = None,
+    interactive: bool = False,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    **env_kwargs: str,
+) -> list[str]:
+    """Build a command for `docker exec`."""
+    args: list[str] = ["docker", "exec"]
+    mapping: dict[str, str] = ({} if env is None else dict(env)) | env_kwargs
+    for key, value in mapping.items():
+        args.extend(["--env", f"{key}={value}"])
+    if interactive:
+        args.append("--interactive")
+    if user is not None:
+        args.extend(["--user", user])
+    if workdir is not None:
+        args.extend(["--workdir", str(workdir)])
+    return [*args, container, cmd, *cmds_or_args]
+
+
+@contextmanager
+def yield_docker_temp_dir(
+    container: str,
+    /,
+    *,
+    user: str | None = None,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    keep: bool = False,
+) -> Iterator[Path]:
+    path = Path(  # skipif-ci
+        docker_exec(
+            container,
+            *MKTEMP_DIR_CMD,
+            user=user,
+            return_=True,
+            retry=retry,
+            logger=logger,
+        )
+    )
+    try:  # skipif-ci
+        yield path
+    finally:  # skipif-ci
+        if keep:
+            if logger is not None:
+                to_logger(logger).info("Keeping temporary directory '%s'...", path)
+        else:
+            docker_exec(container, *rm_cmd(path), user=user, retry=retry, logger=logger)
+
+
+__all__ = ["docker_cp_cmd", "docker_exec", "docker_exec_cmd", "yield_docker_temp_dir"]

utilities/enum.py

@@ -95,7 +95,7 @@ def parse_enum[E: Enum](
                 by_name=by_name.name,
                 by_value=by_value.name,
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -116,7 +116,7 @@ def _parse_enum_one[E: Enum](
             names = [e.name for e in enum]
         case "values":
             names = [ensure_str(e.value) for e in enum]
-        case _ as never:
+        case never:
             assert_never(never)
     try:
         name = one_str(names, value, case_sensitive=case_sensitive)

utilities/errors.py

@@ -46,7 +46,7 @@ def repr_error(error: MaybeType[BaseException], /) -> str:
             return f"{error_obj.__class__.__name__}({error_obj})"
         case type() as error_cls:
             return error_cls.__name__
-        case _ as never:
+        case never:
             assert_never(never)
 
 

utilities/fastapi.py

@@ -13,7 +13,7 @@ from utilities.whenever import get_now_local
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator
 
-    from utilities.types import Delta
+    from utilities.types import Delta, MaybeType
 
 
 _TASKS: list[Task[None]] = []
@@ -35,14 +35,19 @@ class _PingerReceiverApp(FastAPI):
 
 @enhanced_async_context_manager
 async def yield_ping_receiver(
-    port: int, /, *, host: str = "localhost", timeout: Delta | None = None
+    port: int,
+    /,
+    *,
+    host: str = "localhost",
+    timeout: Delta | None = None,
+    error: MaybeType[BaseException] = TimeoutError,
 ) -> AsyncIterator[None]:
     """Yield the ping receiver."""
     app = _PingerReceiverApp()  # skipif-ci
     server = Server(Config(app, host=host, port=port))  # skipif-ci
     _TASKS.append(create_task(server.serve()))  # skipif-ci
     try:  # skipif-ci
-        async with timeout_td(timeout):
+        async with timeout_td(timeout, error=error):
             yield
     finally:  # skipif-ci
         await server.shutdown()

utilities/fpdf2.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, override
 from fpdf import FPDF
 from fpdf.enums import XPos, YPos
 
-from utilities.whenever import format_compact, get_now, to_local_plain
+from utilities.whenever import format_compact, get_now_local
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
@@ -47,7 +47,7 @@ def yield_pdf(*, header: str | None = None) -> Iterator[_BasePDF]:
         def footer(self) -> None:
             self.set_y(-15)
             self.set_font(family="Helvetica", style="I", size=8)
-            page_no, now = (self.page_no(), format_compact(to_local_plain(get_now())))
+            page_no, now = (self.page_no(), format_compact(get_now_local()))
             text = f"page {page_no}/{{}}; {now}"
             _ = self.cell(
                 w=0,