dycw-utilities 0.146.2__py3-none-any.whl → 0.178.1__py3-none-any.whl

utilities/docker.py

@@ -0,0 +1,387 @@
+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.iterables import always_iterable
+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,
+        MaybeIterable,
+        PathLike,
+        Retry,
+        StrStrMapping,
+    )
+
+
+def docker_compose_down(
+    *,
+    files: MaybeIterable[PathLike] | None = None,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+) -> None:
+    """Stop and remove containers."""
+    args = docker_compose_down_cmd(files=files)  # pragma: no cover
+    run(  # pragma: no cover
+        *args, print=print, print_stdout=print_stdout, print_stderr=print_stderr
+    )
+
+
+def docker_compose_down_cmd(
+    *, files: MaybeIterable[PathLike] | None = None
+) -> list[str]:
+    """Command to use 'docker compose down' to stop and remove containers."""
+    return _docker_compose_cmd("down", files=files)
+
+
+def docker_compose_pull(
+    *,
+    files: MaybeIterable[PathLike] | None = None,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+) -> None:
+    """Pull service images."""
+    args = docker_compose_pull_cmd(files=files)  # pragma: no cover
+    run(  # pragma: no cover
+        *args, print=print, print_stdout=print_stdout, print_stderr=print_stderr
+    )
+
+
+def docker_compose_pull_cmd(
+    *, files: MaybeIterable[PathLike] | None = None
+) -> list[str]:
+    """Command to use 'docker compose pull' to pull service images."""
+    return _docker_compose_cmd("pull", files=files)
+
+
+def docker_compose_up(
+    *,
+    files: MaybeIterable[PathLike] | None = None,
+    detach: bool = True,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+) -> None:
+    """Create and start containers."""
+    args = docker_compose_up_cmd(files=files, detach=detach)  # pragma: no cover
+    run(  # pragma: no cover
+        *args, print=print, print_stdout=print_stdout, print_stderr=print_stderr
+    )
+
+
+def docker_compose_up_cmd(
+    *, files: MaybeIterable[PathLike] | None = None, detach: bool = True
+) -> list[str]:
+    """Command to use 'docker compose up' to create and start containers."""
+    args: list[str] = []
+    if detach:
+        args.append("--detach")
+    return _docker_compose_cmd("up", *args, files=files)
+
+
+def _docker_compose_cmd(
+    cmd: str, /, *args: str, files: MaybeIterable[PathLike] | None = None
+) -> list[str]:
+    all_args: list[str] = ["docker", "compose"]
+    if files is not None:
+        for file in always_iterable(files):
+            all_args.extend(["--file", str(file)])
+    return [*all_args, cmd, *args]
+
+
+##
+
+
+@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:
+    """Copy between a container and the local file system."""
+    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(*maybe_sudo_cmd(*docker_cp_cmd(src, dest), sudo=sudo), logger=logger)
+        case (str(), Path() | str()), Path() | str():
+            mkdir(dest, parent=True, sudo=sudo)
+            run(*maybe_sudo_cmd(*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, /) -> list[str]: ...
+@overload
+def docker_cp_cmd(src: PathLike, dest: tuple[str, PathLike], /) -> list[str]: ...
+def docker_cp_cmd(
+    src: PathLike | tuple[str, PathLike], dest: PathLike | tuple[str, PathLike], /
+) -> list[str]:
+    """Command to use 'docker cp' to copy between a container and the local file system."""
+    args: list[str] = ["docker", "cp"]
+    match src, dest:
+        case ((Path() | str()), (str() as cont, Path() | str() as path)):
+            return [*args, str(src), f"{cont}:{path}"]
+        case (str() as cont, (Path() | str()) as path), (Path() | str() as dest):
+            return [*args, f"{cont}:{path}", str(dest)]
+        case _:  # pragma: no cover
+            raise ImpossibleCaseError(case=[f"{src}", f"{dest=}"])
+
+
+##
+
+
+@overload
+def docker_exec(
+    container: str,
+    cmd: str,
+    /,
+    *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,
+    /,
+    *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,
+    /,
+    *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,
+    /,
+    *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,
+    /,
+    *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,
+    /,
+    *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:
+    """Execute a command in a container."""
+    run_cmd_and_args = docker_exec_cmd(  # skipif-ci
+        container,
+        cmd,
+        *args,
+        env=env,
+        interactive=input is not None,
+        user=user,
+        workdir=workdir,
+        **env_kwargs,
+    )
+    return run(  # skipif-ci
+        *run_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,
+    /,
+    *args: str,
+    env: StrStrMapping | None = None,
+    interactive: bool = False,
+    user: str | None = None,
+    workdir: PathLike | None = None,
+    **env_kwargs: str,
+) -> list[str]:
+    """Command to use `docker exec` to execute a command in a container."""
+    all_args: list[str] = ["docker", "exec"]
+    mapping: dict[str, str] = ({} if env is None else dict(env)) | env_kwargs
+    for key, value in mapping.items():
+        all_args.extend(["--env", f"{key}={value}"])
+    if interactive:
+        all_args.append("--interactive")
+    if user is not None:
+        all_args.extend(["--user", user])
+    if workdir is not None:
+        all_args.extend(["--workdir", str(workdir)])
+    return [*all_args, container, cmd, *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_compose_down",
+    "docker_compose_down_cmd",
+    "docker_compose_pull",
+    "docker_compose_pull_cmd",
+    "docker_compose_up",
+    "docker_compose_up_cmd",
+    "docker_cp",
+    "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

@@ -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

@@ -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,