dycw-utilities 0.166.30__py3-none-any.whl → 0.185.8__py3-none-any.whl

utilities/dataclasses.py

@@ -2,17 +2,27 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from contextlib import suppress
-from dataclasses import MISSING, dataclass, field, fields, replace
-from typing import TYPE_CHECKING, Any, Literal, assert_never, overload, override
+from dataclasses import MISSING, dataclass, field, fields
+from typing import TYPE_CHECKING, Any, assert_never, overload, override
 
-from utilities.errors import ImpossibleCaseError
-from utilities.functions import get_class_name
-from utilities.iterables import (
+from utilities.constants import (
+    BRACKETS,
+    LIST_SEPARATOR,
+    PAIR_SEPARATOR,
+    Sentinel,
+    sentinel,
+)
+from utilities.core import (
+    ExtractGroupError,
     OneStrEmptyError,
     OneStrNonUniqueError,
-    cmp_nullable,
+    extract_group,
+    get_class_name,
+    is_sentinel,
     one_str,
 )
+from utilities.errors import ImpossibleCaseError
+from utilities.iterables import cmp_nullable
 from utilities.operator import is_equal
 from utilities.parse import (
     _ParseObjectExtraNonUniqueError,
@@ -20,12 +30,7 @@ from utilities.parse import (
     parse_object,
     serialize_object,
 )
-from utilities.re import ExtractGroupError, extract_group
-from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.text import (
-    BRACKETS,
-    LIST_SEPARATOR,
-    PAIR_SEPARATOR,
     _SplitKeyValuePairsDuplicateKeysError,
     _SplitKeyValuePairsSplitError,
     split_key_value_pairs,
@@ -46,85 +51,6 @@ if TYPE_CHECKING:
     )
 
 
-def dataclass_repr[T](
-    obj: Dataclass,
-    /,
-    *,
-    globalns: StrMapping | None = None,
-    localns: StrMapping | None = None,
-    warn_name_errors: bool = False,
-    include: Iterable[str] | None = None,
-    exclude: Iterable[str] | None = None,
-    rel_tol: float | None = None,
-    abs_tol: float | None = None,
-    extra: Mapping[type[T], Callable[[T, T], bool]] | None = None,
-    defaults: bool = False,
-    recursive: bool = False,
-) -> str:
-    """Repr a dataclass, without its defaults."""
-    out: dict[str, str] = {}
-    for fld in yield_fields(
-        obj, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
-    ):
-        if (
-            fld.keep(
-                include=include,
-                exclude=exclude,
-                rel_tol=rel_tol,
-                abs_tol=abs_tol,
-                extra=extra,
-                defaults=defaults,
-            )
-            and fld.repr
-        ):
-            if recursive:
-                if is_dataclass_instance(fld.value):
-                    repr_ = dataclass_repr(
-                        fld.value,
-                        globalns=globalns,
-                        localns=localns,
-                        warn_name_errors=warn_name_errors,
-                        include=include,
-                        exclude=exclude,
-                        rel_tol=rel_tol,
-                        abs_tol=abs_tol,
-                        extra=extra,
-                        defaults=defaults,
-                        recursive=recursive,
-                    )
-                elif isinstance(fld.value, list):
-                    repr_ = [
-                        dataclass_repr(
-                            v,
-                            globalns=globalns,
-                            localns=localns,
-                            warn_name_errors=warn_name_errors,
-                            include=include,
-                            exclude=exclude,
-                            rel_tol=rel_tol,
-                            abs_tol=abs_tol,
-                            extra=extra,
-                            defaults=defaults,
-                            recursive=recursive,
-                        )
-                        if is_dataclass_instance(v)
-                        else repr(v)
-                        for v in fld.value
-                    ]
-                    repr_ = f"[{', '.join(repr_)}]"
-                else:
-                    repr_ = repr(fld.value)
-            else:
-                repr_ = repr(fld.value)
-            out[fld.name] = repr_
-    cls = get_class_name(obj)
-    joined = ", ".join(f"{k}={v}" for k, v in out.items())
-    return f"{cls}({joined})"
-
-
-##
-
-
 def dataclass_to_dict[T](
     obj: Dataclass,
     /,
@@ -411,33 +337,6 @@ class _OneFieldNonUniqueError(OneFieldError):
 ##
 
 
-@overload
-def replace_non_sentinel(
-    obj: Dataclass, /, *, in_place: Literal[True], **kwargs: Any
-) -> None: ...
-@overload
-def replace_non_sentinel[T: Dataclass](
-    obj: T, /, *, in_place: Literal[False] = False, **kwargs: Any
-) -> T: ...
-@overload
-def replace_non_sentinel[T: Dataclass](
-    obj: T, /, *, in_place: bool = False, **kwargs: Any
-) -> T | None: ...
-def replace_non_sentinel[T: Dataclass](
-    obj: T, /, *, in_place: bool = False, **kwargs: Any
-) -> T | None:
-    """Replace attributes on a dataclass, filtering out sentinel values."""
-    if in_place:
-        for k, v in kwargs.items():
-            if not is_sentinel(v):
-                setattr(obj, k, v)
-        return None
-    return replace(obj, **{k: v for k, v in kwargs.items() if not is_sentinel(v)})
-
-
-##
-
-
 def serialize_dataclass[T](
     obj: Dataclass,
     /,
@@ -1041,13 +940,11 @@ __all__ = [
     "ParseDataClassError",
     "StrMappingToFieldMappingError",
     "YieldFieldsError",
-    "dataclass_repr",
     "dataclass_to_dict",
     "is_nullable_lt",
     "mapping_to_dataclass",
     "one_field",
     "parse_dataclass",
-    "replace_non_sentinel",
     "str_mapping_to_field_mapping",
     "yield_fields",
 ]

utilities/docker.py

@@ -0,0 +1,387 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, overload
+
+from utilities.contextlib import enhanced_context_manager
+from utilities.core import always_iterable
+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,
+        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]
+
+
+##
+
+
+@enhanced_context_manager
+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

@@ -4,8 +4,8 @@ from dataclasses import dataclass
 from enum import Enum, StrEnum
 from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
+from utilities.core import OneStrEmptyError, OneStrNonUniqueError, one_str
 from utilities.functions import ensure_str
-from utilities.iterables import OneStrEmptyError, OneStrNonUniqueError, one_str
 
 if TYPE_CHECKING:
     from utilities.types import EnumLike

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 ExceptionTypeLike, MaybeType
+    from utilities.types import MaybeType
 
 
 @dataclass(kw_only=True, slots=True)
@@ -21,20 +21,6 @@ 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:
@@ -50,4 +36,4 @@ def repr_error(error: MaybeType[BaseException], /) -> str:
             assert_never(never)
 
 
-__all__ = ["ImpossibleCaseError", "is_instance_error", "repr_error"]
+__all__ = ["ImpossibleCaseError", "repr_error"]

utilities/fastapi.py

@@ -6,14 +6,14 @@ from typing import TYPE_CHECKING, Any, override
 from fastapi import FastAPI
 from uvicorn import Config, Server
 
-from utilities.asyncio import timeout_td
+import utilities.asyncio
 from utilities.contextlib import enhanced_async_context_manager
-from utilities.whenever import get_now_local
+from utilities.core import get_now_local
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator
 
-    from utilities.types import Delta, MaybeType
+    from utilities.types import Duration, MaybeType
 
 
 _TASKS: list[Task[None]] = []
@@ -39,7 +39,7 @@ async def yield_ping_receiver(
     /,
     *,
     host: str = "localhost",
-    timeout: Delta | None = None,
+    timeout: Duration | None = None,
     error: MaybeType[BaseException] = TimeoutError,
 ) -> AsyncIterator[None]:
     """Yield the ping receiver."""
@@ -47,7 +47,7 @@ async def yield_ping_receiver(
     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):
+        async with utilities.asyncio.timeout(timeout, error=error):
             yield
     finally:  # skipif-ci
         await server.shutdown()

utilities/fpdf2.py

@@ -6,7 +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
+from utilities.core import get_now_local
+from utilities.whenever import format_compact
 
 if TYPE_CHECKING:
     from collections.abc import Iterator