dycw-utilities 0.166.30__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/functions.py

@@ -693,7 +693,7 @@ def second[U](pair: tuple[Any, U], /) -> U:
 
 def skip_if_optimize[**P](func: Callable[P, None], /) -> Callable[P, None]:
     """Skip a function if we are in the optimized mode."""
-    if __debug__:
+    if __debug__:  # pragma: no cover
         return func
 
     @wraps(func)

utilities/grp.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import assert_never
+
+from utilities.os import EFFECTIVE_GROUP_ID
+from utilities.platform import SYSTEM
+
+
+def get_gid_name(gid: int, /) -> str | None:
+    """Get the name of a group."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":
+            from grp import getgrgid
+
+            return getgrgid(gid).gr_name
+        case never:
+            assert_never(never)
+
+
+ROOT_GROUP_NAME = get_gid_name(0)
+EFFECTIVE_GROUP_NAME = (
+    None if EFFECTIVE_GROUP_ID is None else get_gid_name(EFFECTIVE_GROUP_ID)
+)
+
+
+__all__ = ["EFFECTIVE_GROUP_NAME", "ROOT_GROUP_NAME", "get_gid_name"]

utilities/hypothesis.py

@@ -77,7 +77,8 @@ from utilities.math import (
 )
 from utilities.os import get_env_var
 from utilities.pathlib import module_path, temp_cwd
-from utilities.platform import IS_LINUX, IS_WINDOWS
+from utilities.permissions import Permissions
+from utilities.platform import IS_LINUX
 from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.tempfile import TEMP_DIR, TemporaryDirectory
 from utilities.version import Version
@@ -864,6 +865,38 @@ def _path_parts(draw: DrawFn, /) -> str:
 ##
 
 
+@composite
+def permissions(
+    draw: DrawFn,
+    /,
+    *,
+    user_read: MaybeSearchStrategy[bool | None] = None,
+    user_write: MaybeSearchStrategy[bool | None] = None,
+    user_execute: MaybeSearchStrategy[bool | None] = None,
+    group_read: MaybeSearchStrategy[bool | None] = None,
+    group_write: MaybeSearchStrategy[bool | None] = None,
+    group_execute: MaybeSearchStrategy[bool | None] = None,
+    others_read: MaybeSearchStrategy[bool | None] = None,
+    others_write: MaybeSearchStrategy[bool | None] = None,
+    others_execute: MaybeSearchStrategy[bool | None] = None,
+) -> Permissions:
+    """Strategy for generating `Permissions`."""
+    return Permissions(
+        user_read=draw2(draw, user_read, booleans()),
+        user_write=draw2(draw, user_write, booleans()),
+        user_execute=draw2(draw, user_execute, booleans()),
+        group_read=draw2(draw, group_read, booleans()),
+        group_write=draw2(draw, group_write, booleans()),
+        group_execute=draw2(draw, group_execute, booleans()),
+        others_read=draw2(draw, others_read, booleans()),
+        others_write=draw2(draw, others_write, booleans()),
+        others_execute=draw2(draw, others_execute, booleans()),
+    )
+
+
+##
+
+
 @composite
 def plain_date_times(
     draw: DrawFn,
@@ -1007,7 +1040,7 @@ def setup_hypothesis_profiles(
                     assert_never(never)
 
     phases = {Phase.explicit, Phase.reuse, Phase.generate, Phase.target}
-    if "HYPOTHESIS_NO_SHRINK" not in environ:
+    if "HYPOTHESIS_NO_SHRINK" not in environ:  # pragma: no cover
         phases.add(Phase.shrink)
     for profile in Profile:
         try:
@@ -1128,9 +1161,7 @@ def temp_dirs(draw: DrawFn, /) -> TemporaryDirectory:
     """Search strategy for temporary directories."""
     _TEMP_DIR_HYPOTHESIS.mkdir(exist_ok=True)
     uuid = draw(uuids())
-    return TemporaryDirectory(
-        prefix=f"{uuid}__", dir=_TEMP_DIR_HYPOTHESIS, ignore_cleanup_errors=IS_WINDOWS
-    )
+    return TemporaryDirectory(prefix=f"{uuid}__", dir=_TEMP_DIR_HYPOTHESIS)
 
 
 ##
@@ -1570,7 +1601,7 @@ def zoned_date_times(
     with (
         assume_does_not_raise(RepeatedTime),
         assume_does_not_raise(SkippedTime),
-        assume_does_not_raise(ValueError, match=r"Resulting datetime is out of range"),
+        assume_does_not_raise(ValueError, match=r"Resulting time is out of range"),
     ):
         zoned = plain.assume_tz(time_zone_.key, disambiguate="raise")
     with assume_does_not_raise(OverflowError, match=r"date value out of range"):
@@ -1613,6 +1644,7 @@ __all__ = [
     "numbers",
     "pairs",
     "paths",
+    "permissions",
     "plain_date_times",
     "py_datetimes",
     "quadruples",

utilities/importlib.py

@@ -1,7 +1,23 @@
 from __future__ import annotations
 
+import importlib.resources
 from importlib import import_module
 from importlib.util import find_spec
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from utilities.errors import ImpossibleCaseError
+
+if TYPE_CHECKING:
+    from importlib.resources import Anchor
+
+
+def files(*, anchor: Anchor | None = None) -> Path:
+    """Get the path for an anchor."""
+    path = importlib.resources.files(anchor)
+    if isinstance(path, Path):
+        return path
+    raise ImpossibleCaseError(case=[f"{path=}"])  # pragma: no cover
 
 
 def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
@@ -15,4 +31,4 @@ def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
     return hasattr(mod, name)
 
 
-__all__ = ["is_valid_import"]
+__all__ = ["files", "is_valid_import"]

utilities/jinja2.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, assert_never, override
+
+from jinja2 import BaseLoader, BytecodeCache, Environment, FileSystemLoader, Undefined
+from jinja2.defaults import (
+    BLOCK_END_STRING,
+    BLOCK_START_STRING,
+    COMMENT_END_STRING,
+    COMMENT_START_STRING,
+    KEEP_TRAILING_NEWLINE,
+    LINE_COMMENT_PREFIX,
+    LINE_STATEMENT_PREFIX,
+    LSTRIP_BLOCKS,
+    NEWLINE_SEQUENCE,
+    TRIM_BLOCKS,
+    VARIABLE_END_STRING,
+    VARIABLE_START_STRING,
+)
+
+from utilities.atomicwrites import writer
+from utilities.text import kebab_case, pascal_case, snake_case
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+    from pathlib import Path
+
+    from jinja2.ext import Extension
+
+    from utilities.types import StrMapping
+
+
+class EnhancedEnvironment(Environment):
+    """Environment with enhanced features."""
+
+    @override
+    def __init__(
+        self,
+        block_start_string: str = BLOCK_START_STRING,
+        block_end_string: str = BLOCK_END_STRING,
+        variable_start_string: str = VARIABLE_START_STRING,
+        variable_end_string: str = VARIABLE_END_STRING,
+        comment_start_string: str = COMMENT_START_STRING,
+        comment_end_string: str = COMMENT_END_STRING,
+        line_statement_prefix: str | None = LINE_STATEMENT_PREFIX,
+        line_comment_prefix: str | None = LINE_COMMENT_PREFIX,
+        trim_blocks: bool = TRIM_BLOCKS,
+        lstrip_blocks: bool = LSTRIP_BLOCKS,
+        newline_sequence: Literal["\n", "\r\n", "\r"] = NEWLINE_SEQUENCE,
+        keep_trailing_newline: bool = KEEP_TRAILING_NEWLINE,
+        extensions: Sequence[str | type[Extension]] = (),
+        optimized: bool = True,
+        undefined: type[Undefined] = Undefined,
+        finalize: Callable[..., Any] | None = None,
+        autoescape: bool | Callable[[str | None], bool] = False,
+        loader: BaseLoader | None = None,
+        cache_size: int = 400,
+        auto_reload: bool = True,
+        bytecode_cache: BytecodeCache | None = None,
+        enable_async: bool = False,
+    ) -> None:
+        super().__init__(
+            block_start_string,
+            block_end_string,
+            variable_start_string,
+            variable_end_string,
+            comment_start_string,
+            comment_end_string,
+            line_statement_prefix,
+            line_comment_prefix,
+            trim_blocks,
+            lstrip_blocks,
+            newline_sequence,
+            keep_trailing_newline,
+            extensions,
+            optimized,
+            undefined,
+            finalize,
+            autoescape,
+            loader,
+            cache_size,
+            auto_reload,
+            bytecode_cache,
+            enable_async,
+        )
+        self.filters["kebab"] = kebab_case
+        self.filters["pascal"] = pascal_case
+        self.filters["snake"] = snake_case
+
+
+@dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
+class TemplateJob:
+    """A template with an associated rendering job."""
+
+    template: Path
+    kwargs: StrMapping
+    target: Path
+    mode: Literal["write", "append"] = "write"
+
+    def __post_init__(self) -> None:
+        if not self.template.exists():
+            raise _TemplateJobTemplateDoesNotExistError(path=self.template)
+        if (self.mode == "append") and not self.target.exists():
+            raise _TemplateJobTargetDoesNotExistError(path=self.template)
+
+    def run(self) -> None:
+        """Run the job."""
+        match self.mode:
+            case "write":
+                with writer(self.target, overwrite=True) as temp:
+                    _ = temp.write_text(self.rendered)
+            case "append":
+                with self.target.open(mode="a") as fh:
+                    _ = fh.write(self.rendered)
+            case never:
+                assert_never(never)
+
+    @property
+    def rendered(self) -> str:
+        """The template, rendered."""
+        env = EnhancedEnvironment(loader=FileSystemLoader(self.template.parent))
+        return env.get_template(self.template.name).render(self.kwargs)
+
+
+@dataclass(kw_only=True, slots=True)
+class TemplateJobError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _TemplateJobTemplateDoesNotExistError(TemplateJobError):
+    path: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Template {str(self.path)!r} does not exist"
+
+
+@dataclass(kw_only=True, slots=True)
+class _TemplateJobTargetDoesNotExistError(TemplateJobError):
+    path: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Target {str(self.path)!r} does not exist"
+
+
+__all__ = ["EnhancedEnvironment", "TemplateJob", "TemplateJobError"]

utilities/logging.py

@@ -387,9 +387,7 @@ class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
     def emit(self, record: LogRecord) -> None:
         try:
             if (self._backup_count is not None) and self._should_rollover(record):
-                self._do_rollover(  # skipif-ci-and-windows
-                    backup_count=self._backup_count
-                )
+                self._do_rollover(backup_count=self._backup_count)
             FileHandler.emit(self, record)
         except Exception:  # noqa: BLE001  # pragma: no cover
             self.handleError(record)
@@ -399,23 +397,23 @@ class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
             self.stream.close()
             self.stream = None
 
-        actions = _compute_rollover_actions(  # skipif-ci-and-windows
+        actions = _compute_rollover_actions(
             self._directory,
             self._stem,
             self._suffix,
             patterns=self._patterns,
             backup_count=backup_count,
         )
-        actions.do()  # skipif-ci-and-windows
+        actions.do()
 
         if not self.delay:  # pragma: no cover
             self.stream = self._open()
-        self._time_handler.rolloverAt = (  # skipif-ci-and-windows
-            self._time_handler.computeRollover(get_now_local().timestamp())
+        self._time_handler.rolloverAt = self._time_handler.computeRollover(
+            get_now_local().timestamp()
         )
 
     def _should_rollover(self, record: LogRecord, /) -> bool:
-        if self._max_bytes is not None:  # skipif-ci-and-windows
+        if self._max_bytes is not None:
             try:
                 size = self._filename.stat().st_size
             except FileNotFoundError:
@@ -423,7 +421,7 @@ class SizeAndTimeRotatingFileHandler(BaseRotatingHandler):
             else:
                 if size >= self._max_bytes:
                     return True
-        return bool(self._time_handler.shouldRollover(record))  # skipif-ci-and-windows
+        return bool(self._time_handler.shouldRollover(record))
 
 
 def _compute_rollover_patterns(stem: str, suffix: str, /) -> _RolloverPatterns: