dycw-utilities 0.175.28__py3-none-any.whl → 0.175.30__py3-none-any.whl

{dycw_utilities-0.175.28.dist-info → dycw_utilities-0.175.30.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dycw-utilities
-Version: 0.175.28
+Version: 0.175.30
 Summary: Miscellaneous Python utilities
 Author: Derek Wan
 Author-email: Derek Wan <d.wan@icloud.com>

{dycw_utilities-0.175.28.dist-info → dycw_utilities-0.175.30.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=k4kaN7LN6ZF6oNv47GuGm1AaLmVrNa8LJBL_8oBnlMY,61
+utilities/__init__.py,sha256=MtsJJrbSJrW256hO7llrT3qk9914hd3MBaFYuonK4KU,61
 utilities/altair.py,sha256=TLfRFbG9HwG7SLXoJ-v0r-t49ZaGgTQZD82cpjVi4vs,9085
 utilities/asyncio.py,sha256=aJySVxBY0gqsIYnoNmH7-1r8djKuf4vSsU69VCD08t8,16772
 utilities/atomicwrites.py,sha256=tPo6r-Rypd9u99u66B9z86YBPpnLrlHtwox_8Z7T34Y,5790
@@ -11,7 +11,7 @@ utilities/contextvars.py,sha256=J8OhC7jqozAGYOCe2KUWysbPXNGe5JYz3HfaY_mIs08,883
 utilities/cryptography.py,sha256=5PFrzsNUGHay91dFgYnDKwYprXxahrBqztmUqViRzBk,956
 utilities/cvxpy.py,sha256=Rv1-fD-XYerosCavRF8Pohop2DBkU3AlFaGTfD8AEAA,13776
 utilities/dataclasses.py,sha256=xbU3QN1GFy7RC6hIJRZIeUZm7YRlodrgEWmahWG6k2g,32465
-utilities/docker.py,sha256=N__PKd3cnSRsXNEMHMLdLneLdyzfbr2ESkElcwrovvQ,7940
+utilities/docker.py,sha256=nzeuR5-OQKL2yhtY-SSqLS2ftl-iev0cUrshwEMwB2k,9808
 utilities/enum.py,sha256=5l6pwZD1cjSlVW4ss-zBPspWvrbrYrdtJWcg6f5_J5w,5781
 utilities/errors.py,sha256=mFlDGSM0LI1jZ1pbqwLAH3ttLZ2JVIxyZLojw8tGVZU,1479
 utilities/fastapi.py,sha256=TqyKvBjiMS594sXPjrz-KRTLMb3l3D3rZ1zAYV7GfOk,1454
@@ -80,7 +80,7 @@ utilities/sqlalchemy.py,sha256=HQYpd7LFxdTF5WYVWYtCJeEBI71EJm7ytvCGyAH9B-U,37163
 utilities/sqlalchemy_polars.py,sha256=JCGhB37raSR7fqeWV5dTsciRTMVzIdVT9YSqKT0piT0,13370
 utilities/statsmodels.py,sha256=koyiBHvpMcSiBfh99wFUfSggLNx7cuAw3rwyfAhoKpQ,3410
 utilities/string.py,sha256=shmBK87zZwzGyixuNuXCiUbqzfeZ9xlrFwz6JTaRvDk,582
-utilities/subprocess.py,sha256=f-bVgM-8dGYuqmfegp7y9JtU1WP3FX4AaU2munpeD-U,52304
+utilities/subprocess.py,sha256=ei0OD73S0WX7ZqHCQp9UB3hY9OWbAUVIrLoz9niIfQQ,53031
 utilities/tempfile.py,sha256=a3_M1QyxGZql_VcGkBOQBeWbbkItjgkfIpVyzU1UAic,3843
 utilities/testbook.py,sha256=j1KmaVbrX9VrbeMgtPh5gk55myAsn3dyRUn7jGbPbRk,1294
 utilities/text.py,sha256=7SvwcSR2l_5cOrm1samGnR4C-ZI6qyFLHLzSpO1zeHQ,13958
@@ -97,7 +97,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=F4ek0-OBWxHYrZdmoZt76N2RnNyKY5KrEHt7rqO4AQE,60183
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=tdIScrTB2-B-LH0ukb1HUXKooLknOfJNwHk10MuMYvA,3619
-dycw_utilities-0.175.28.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
-dycw_utilities-0.175.28.dist-info/entry_points.txt,sha256=cOGtKeJI0KXLSV7MJ8Dhc2G8jPgDcBDm53MVNJU4ycI,136
-dycw_utilities-0.175.28.dist-info/METADATA,sha256=k8PYEVjHbdSwrVP6nAsY8ptu8MEenozvTPprPs3Pgwk,1443
-dycw_utilities-0.175.28.dist-info/RECORD,,
+dycw_utilities-0.175.30.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
+dycw_utilities-0.175.30.dist-info/entry_points.txt,sha256=cOGtKeJI0KXLSV7MJ8Dhc2G8jPgDcBDm53MVNJU4ycI,136
+dycw_utilities-0.175.30.dist-info/METADATA,sha256=X2Hiaa6YhG9ZkFu1AfxlEDbXKDKYepqcVZylTh5hVds,1443
+dycw_utilities-0.175.30.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.175.28"
+__version__ = "0.175.30"

utilities/docker.py

@@ -5,6 +5,7 @@ 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,
@@ -18,7 +19,60 @@ 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) -> None:
+    """Stop and remove containers."""
+    run(*docker_compose_down_cmd(files=files))  # pragma: no cover
+
+
+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) -> None:
+    """Pull service images."""
+    run(*docker_compose_pull_cmd(files=files))  # pragma: no cover
+
+
+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) -> None:
+    """Create and start containers."""
+    run(*docker_compose_up_cmd(files=files))  # pragma: no cover
+
+
+def docker_compose_up_cmd(*, files: MaybeIterable[PathLike] | None = None) -> list[str]:
+    """Command to use 'docker compose up' to create and start containers."""
+    return _docker_compose_cmd("up", files=files)
+
+
+def _docker_compose_cmd(
+    cmd: str, /, *, files: MaybeIterable[PathLike] | None = None
+) -> list[str]:
+    args: list[str] = ["docker", "compose"]
+    if files is not None:
+        for file in always_iterable(files):
+            args.extend(["--file", str(file)])
+    return [*args, cmd]
+
+
+##
 
 
 @overload
@@ -47,48 +101,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
@@ -210,6 +255,7 @@ def docker_exec(
     logger: LoggerLike | None = None,
     **env_kwargs: str,
 ) -> str | None:
+    """Execute a command in a container."""
     cmd_and_args = docker_exec_cmd(  # skipif-ci
         container,
         cmd,
@@ -245,7 +291,7 @@ def docker_exec_cmd(
     workdir: PathLike | None = None,
     **env_kwargs: str,
 ) -> list[str]:
-    """Build a command for `docker exec`."""
+    """Command to use `docker exec` to execute a command in a container."""
     args: list[str] = ["docker", "exec"]
     mapping: dict[str, str] = ({} if env is None else dict(env)) | env_kwargs
     for key, value in mapping.items():
@@ -259,6 +305,9 @@ def docker_exec_cmd(
     return [*args, container, cmd, *cmds_or_args]
 
 
+##
+
+
 @contextmanager
 def yield_docker_temp_dir(
     container: str,
@@ -290,4 +339,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/subprocess.py

@@ -86,9 +86,10 @@ def apt_install(
     """Install packages."""
     if update:  # pragma: no cover
         apt_update(sudo=sudo)
-    run(  # pragma: no cover
-        *maybe_sudo_cmd(*apt_install_cmd(package, *packages), sudo=sudo)
+    args = maybe_sudo_cmd(  # pragma: no cover
+        *apt_install_cmd(package, *packages), sudo=sudo
     )
+    run(*args)  # pragma: no cover
 
 
 def apt_install_cmd(package: str, /, *packages: str) -> list[str]:
@@ -101,9 +102,10 @@ def apt_install_cmd(package: str, /, *packages: str) -> list[str]:
 
 def apt_remove(package: str, /, *packages: str, sudo: bool = False) -> None:
     """Remove a package."""
-    run(  # pragma: no cover
-        *maybe_sudo_cmd(*apt_remove_cmd(package, *packages), sudo=sudo)
+    args = maybe_sudo_cmd(  # pragma: no cover
+        *apt_remove_cmd(package, *packages), sudo=sudo
     )
+    run(*args)  # pragma: no cover
 
 
 def apt_remove_cmd(package: str, /, *packages: str) -> list[str]:
@@ -146,6 +148,29 @@ def cd_cmd(path: PathLike, /) -> list[str]:
 ##
 
 
+def chattr(
+    path: PathLike, /, *, immutable: bool | None = None, sudo: bool = False
+) -> None:
+    """Change file attributes."""
+    args = maybe_sudo_cmd(  # pragma: no cover
+        *chattr_cmd(path, immutable=immutable), sudo=sudo
+    )
+    run(*args)  # pragma: no cover
+
+
+def chattr_cmd(path: PathLike, /, *, immutable: bool | None = None) -> list[str]:
+    """Command to use 'chattr' to change file attributes."""
+    args: list[str] = ["chattr"]
+    if immutable is True:
+        args.append("+i")
+    elif immutable is False:
+        args.append("-i")
+    return [*args, str(path)]
+
+
+##
+
+
 def chmod(path: PathLike, perms: PermissionsLike, /, *, sudo: bool = False) -> None:
     """Change file mode."""
     if sudo:  # pragma: no cover
@@ -223,9 +248,8 @@ class ChownCmdError(Exception):
 
 def chpasswd(user_name: str, password: str, /, *, sudo: bool = False) -> None:
     """Update passwords."""
-    run(  # pragma: no cover
-        *maybe_sudo_cmd(CHPASSWD, sudo=sudo), input=f"{user_name}:{password}"
-    )
+    args = maybe_sudo_cmd(CHPASSWD, sudo=sudo)  # pragma: no cover
+    run(*args, input=f"{user_name}:{password}")  # pragma: no cover
 
 
 ##
@@ -421,8 +445,8 @@ def curl(
     logger: LoggerLike | None = None,
 ) -> str | None:
     """Transfer a URL."""
-    args = maybe_sudo_cmd(
-        *curl_cmd(  # skipif-ci
+    args = maybe_sudo_cmd(  # skipif-ci
+        *curl_cmd(
             url,
             fail=fail,
             location=location,
@@ -1860,6 +1884,8 @@ __all__ = [
     "apt_update",
     "cat",
     "cd_cmd",
+    "chattr",
+    "chattr_cmd",
     "chmod",
     "chmod_cmd",
     "chown",