dycw-utilities 0.175.17__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

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-from contextlib import contextmanager
 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 (
@@ -18,7 +19,93 @@ from utilities.subprocess import (
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
-    from utilities.types import LoggerLike, PathLike, Retry, StrStrMapping
+    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
@@ -47,48 +134,39 @@ def docker_cp(
     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(*docker_cp_cmd(src, dest, sudo=sudo), logger=logger)
+            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(*docker_cp_cmd(src, dest, sudo=sudo), logger=logger)
+            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, /, *, sudo: bool = False
-) -> list[str]: ...
+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, 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,
+    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()) 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 ((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=}"])
-    parts: list[str] = ["docker", "cp", str(src_use), str(dest_use)]
-    return maybe_sudo_cmd(*parts, sudo=sudo)
+
+
+##
 
 
 @overload
@@ -96,7 +174,7 @@ def docker_exec(
     container: str,
     cmd: str,
     /,
-    *cmds_or_args: str,
+    *args: str,
     env: StrStrMapping | None = None,
     user: str | None = None,
     workdir: PathLike | None = None,
@@ -116,7 +194,7 @@ def docker_exec(
     container: str,
     cmd: str,
     /,
-    *cmds_or_args: str,
+    *args: str,
     env: StrStrMapping | None = None,
     user: str | None = None,
     workdir: PathLike | None = None,
@@ -136,7 +214,7 @@ def docker_exec(
     container: str,
     cmd: str,
     /,
-    *cmds_or_args: str,
+    *args: str,
     env: StrStrMapping | None = None,
     user: str | None = None,
     workdir: PathLike | None = None,
@@ -156,7 +234,7 @@ def docker_exec(
     container: str,
     cmd: str,
     /,
-    *cmds_or_args: str,
+    *args: str,
     env: StrStrMapping | None = None,
     user: str | None = None,
     workdir: PathLike | None = None,
@@ -176,7 +254,7 @@ def docker_exec(
     container: str,
     cmd: str,
     /,
-    *cmds_or_args: str,
+    *args: str,
     env: StrStrMapping | None = None,
     user: str | None = None,
     workdir: PathLike | None = None,
@@ -195,7 +273,7 @@ def docker_exec(
     container: str,
     cmd: str,
     /,
-    *cmds_or_args: str,
+    *args: str,
     env: StrStrMapping | None = None,
     user: str | None = None,
     workdir: PathLike | None = None,
@@ -210,10 +288,11 @@ def docker_exec(
     logger: LoggerLike | None = None,
     **env_kwargs: str,
 ) -> str | None:
-    cmd_and_args = docker_exec_cmd(  # skipif-ci
+    """Execute a command in a container."""
+    run_cmd_and_args = docker_exec_cmd(  # skipif-ci
         container,
         cmd,
-        *cmds_or_args,
+        *args,
         env=env,
         interactive=input is not None,
         user=user,
@@ -221,7 +300,7 @@ def docker_exec(
         **env_kwargs,
     )
     return run(  # skipif-ci
-        *cmd_and_args,
+        *run_cmd_and_args,
         input=input,
         print=print,
         print_stdout=print_stdout,
@@ -238,28 +317,31 @@ def docker_exec_cmd(
     container: str,
     cmd: str,
     /,
-    *cmds_or_args: str,
+    *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"]
+    """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():
-        args.extend(["--env", f"{key}={value}"])
+        all_args.extend(["--env", f"{key}={value}"])
     if interactive:
-        args.append("--interactive")
+        all_args.append("--interactive")
     if user is not None:
-        args.extend(["--user", user])
+        all_args.extend(["--user", user])
     if workdir is not None:
-        args.extend(["--workdir", str(workdir)])
-    return [*args, container, cmd, *cmds_or_args]
+        all_args.extend(["--workdir", str(workdir)])
+    return [*all_args, container, cmd, *args]
+
+
+##
 
 
-@contextmanager
+@enhanced_context_manager
 def yield_docker_temp_dir(
     container: str,
     /,
@@ -290,4 +372,16 @@ def yield_docker_temp_dir(
             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"]
+__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