dycw-utilities 0.129.10__py3-none-any.whl → 0.175.17__py3-none-any.whl

utilities/docker.py

@@ -0,0 +1,293 @@
+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:  # skipif-ci
+        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]:
+    """Yield a temporary directory in a Docker container."""
+    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

@@ -2,26 +2,29 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum, StrEnum
-from typing import Generic, Literal, assert_never, overload, override
+from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
 from utilities.functions import ensure_str
 from utilities.iterables import OneStrEmptyError, OneStrNonUniqueError, one_str
-from utilities.types import EnumLike, TEnum
+
+if TYPE_CHECKING:
+    from utilities.types import EnumLike
+
 
 ##
 
 
 @overload
-def ensure_enum(
-    value: None, enum: type[TEnum], /, *, case_sensitive: bool = False
+def ensure_enum[E: Enum](
+    value: None, enum: type[E], /, *, case_sensitive: bool = False
 ) -> None: ...
 @overload
-def ensure_enum(
-    value: EnumLike[TEnum], enum: type[TEnum], /, *, case_sensitive: bool = False
-) -> TEnum: ...
-def ensure_enum(
-    value: EnumLike[TEnum] | None, enum: type[TEnum], /, *, case_sensitive: bool = False
-) -> TEnum | None:
+def ensure_enum[E: Enum](
+    value: EnumLike[E], enum: type[E], /, *, case_sensitive: bool = False
+) -> E: ...
+def ensure_enum[E: Enum](
+    value: EnumLike[E] | None, enum: type[E], /, *, case_sensitive: bool = False
+) -> E | None:
     """Ensure the object is a member of the enum."""
     if value is None:
         return None
@@ -36,9 +39,9 @@ def ensure_enum(
 
 
 @dataclass(kw_only=True, slots=True)
-class EnsureEnumError(Exception, Generic[TEnum]):
-    value: EnumLike[TEnum]
-    enum: type[TEnum]
+class EnsureEnumError[E: Enum](Exception):
+    value: EnumLike[E]
+    enum: type[E]
 
 
 @dataclass(kw_only=True, slots=True)
@@ -58,9 +61,9 @@ class _EnsureEnumParseError(EnsureEnumError):
 ##
 
 
-def parse_enum(
-    value: str, enum: type[TEnum], /, *, case_sensitive: bool = False
-) -> TEnum:
+def parse_enum[E: Enum](
+    value: str, enum: type[E], /, *, case_sensitive: bool = False
+) -> E:
     """Parse a string into the enum."""
     by_name = _parse_enum_one(value, enum, "names", case_sensitive=case_sensitive)
     if not issubclass(enum, StrEnum):
@@ -92,28 +95,28 @@ def parse_enum(
                 by_name=by_name.name,
                 by_value=by_value.name,
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
 type _NamesOrValues = Literal["names", "values"]
 
 
-def _parse_enum_one(
+def _parse_enum_one[E: Enum](
     value: str,
-    enum: type[TEnum],
+    enum: type[E],
     names_or_values: _NamesOrValues,
     /,
     *,
     case_sensitive: bool = False,
-) -> TEnum | None:
+) -> E | None:
     """Pair one aspect of the enums."""
     match names_or_values:
         case "names":
             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)
@@ -132,9 +135,9 @@ def _parse_enum_one(
 
 
 @dataclass(kw_only=True, slots=True)
-class ParseEnumError(Exception, Generic[TEnum]):
+class ParseEnumError[E: Enum](Exception):
     value: str
-    enum: type[TEnum]
+    enum: type[E]
 
 
 @dataclass(kw_only=True, slots=True)

utilities/errors.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, assert_never, override
 
 if TYPE_CHECKING:
-    from utilities.types import MaybeType
+    from utilities.types import ExceptionTypeLike, MaybeType
 
 
 @dataclass(kw_only=True, slots=True)
@@ -21,6 +21,20 @@ class ImpossibleCaseError(Exception):
 ##
 
 
+def is_instance_error(
+    error: BaseException, class_or_tuple: ExceptionTypeLike[Exception], /
+) -> bool:
+    """Check if an instance relationship holds, allowing for groups."""
+    if isinstance(error, class_or_tuple):
+        return True
+    if not isinstance(error, BaseExceptionGroup):
+        return False
+    return any(is_instance_error(e, class_or_tuple) for e in error.exceptions)
+
+
+##
+
+
 def repr_error(error: MaybeType[BaseException], /) -> str:
     """Get a string representation of an error."""
     match error:
@@ -32,8 +46,8 @@ 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)
 
 
-__all__ = ["ImpossibleCaseError", "repr_error"]
+__all__ = ["ImpossibleCaseError", "is_instance_error", "repr_error"]

utilities/fastapi.py

@@ -1,23 +1,22 @@
 from __future__ import annotations
 
 from asyncio import Task, create_task
-from dataclasses import InitVar, dataclass, field
-from typing import TYPE_CHECKING, Any, Literal, Self, override
+from typing import TYPE_CHECKING, Any, override
 
 from fastapi import FastAPI
 from uvicorn import Config, Server
 
-from utilities.asyncio import Looper
-from utilities.datetime import SECOND, datetime_duration_to_float
+from utilities.asyncio import timeout_td
+from utilities.contextlib import enhanced_async_context_manager
+from utilities.whenever import get_now_local
 
 if TYPE_CHECKING:
-    from types import TracebackType
+    from collections.abc import AsyncIterator
 
-    from utilities.types import Duration
+    from utilities.types import Delta, MaybeType
 
 
-_LOCALHOST: str = "localhost"
-_TIMEOUT: Duration = SECOND
+_TASKS: list[Task[None]] = []
 
 
 class _PingerReceiverApp(FastAPI):
@@ -29,64 +28,29 @@ class _PingerReceiverApp(FastAPI):
 
         @self.get("/ping")  # skipif-ci
         def ping() -> str:
-            from utilities.tzlocal import get_now_local  # skipif-ci
-            from utilities.whenever import serialize_zoned_datetime  # skipif-ci
-
-            now = serialize_zoned_datetime(get_now_local())  # skipif-ci
-            return f"pong @ {now}"  # skipif-ci
+            return f"pong @ {get_now_local()}"  # skipif-ci
 
         _ = ping  # skipif-ci
 
 
-@dataclass(kw_only=True)
-class PingReceiver(Looper[None]):
-    """A ping receiver."""
-
-    host: InitVar[str] = _LOCALHOST
-    port: InitVar[int]
-    _app: _PingerReceiverApp = field(
-        default_factory=_PingerReceiverApp, 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
-    ) -> str | Literal[False]:
-        """Ping the receiver."""
-        from httpx import AsyncClient, ConnectError  # skipif-ci
-
-        url = f"http://{host}:{port}/ping"  # skipif-ci
-        timeout_use = datetime_duration_to_float(timeout)  # skipif-ci
-        try:  # skipif-ci
-            async with AsyncClient() as client:
-                response = await client.get(url, timeout=timeout_use)
-        except ConnectError:  # skipif-ci
-            return False
-        return response.text if response.status_code == 200 else False  # skipif-ci
-
-
-__all__ = ["PingReceiver"]
+@enhanced_async_context_manager
+async def yield_ping_receiver(
+    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, error=error):
+            yield
+    finally:  # skipif-ci
+        await server.shutdown()
+
+
+__all__ = ["yield_ping_receiver"]

utilities/fpdf2.py

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