dycw-utilities 0.174.7__py3-none-any.whl → 0.174.9__py3-none-any.whl

{dycw_utilities-0.174.7.dist-info → dycw_utilities-0.174.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dycw-utilities
-Version: 0.174.7
+Version: 0.174.9
 Author: Derek Wan
 Author-email: Derek Wan <d.wan@icloud.com>
 Requires-Dist: atomicwrites>=1.4.1,<1.5

{dycw_utilities-0.174.7.dist-info → dycw_utilities-0.174.9.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=m6IBJ6HmwjCqt8xNdi4aHkF4CjRw4nrxq8SpNIQAq2Q,60
+utilities/__init__.py,sha256=s0yfL-qs6UI6ltNUkBKltAzsUuIudzaPhHhfNI2ILBI,60
 utilities/aeventkit.py,sha256=OmDBhYGgbsKrB7cdC5FFpJHUatX9O76eTeKVVTksp2Y,12673
 utilities/altair.py,sha256=rUK99g9x6CYDDfiZrf-aTx5fSRbL1Q8ctgKORowzXHg,9060
 utilities/asyncio.py,sha256=aJySVxBY0gqsIYnoNmH7-1r8djKuf4vSsU69VCD08t8,16772
@@ -25,7 +25,7 @@ utilities/grp.py,sha256=1vV3gNR9dQsl1vtUtvC_2qgVdQzm7O8lLMSh56cTbeg,694
 utilities/gzip.py,sha256=fkGP3KdsBfXlstodT4wtlp-PwNyUsogpbDCVVVGdsm4,781
 utilities/hashlib.py,sha256=SVTgtguur0P4elppvzOBbLEjVM3Pea0eWB61yg2ilxo,309
 utilities/http.py,sha256=TsavEfHlRtlLaeV21Z6KZh0qbPw-kvD1zsQdZ7Kep5Q,977
-utilities/hypothesis.py,sha256=uRgpkHhDOx9hEaOs7SyAuVMARCFo86VxlP72-jJCOAU,45471
+utilities/hypothesis.py,sha256=wk1HiNdBg7tGPEKLZ5uiNVbtlSZl58QJjlediYoSHkA,46753
 utilities/importlib.py,sha256=mV1xT_O_zt_GnZZ36tl3xOmMaN_3jErDWY54fX39F6Y,429
 utilities/inflect.py,sha256=v7YkOWSu8NAmVghPcf4F3YBZQoJCS47_DLf9jbfWIs0,581
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
@@ -47,6 +47,7 @@ utilities/orjson.py,sha256=T_0SlK811ysg46d3orvIPY3JpBa4FRMpP2wlPQo7-gU,41854
 utilities/os.py,sha256=kjKKSQfnRqFTTZ315iavaaGd3gGuYNoSWlxVLCJjyQs,4852
 utilities/parse.py,sha256=g7Qm9eBOIeDId2tGA021CIaeF6jp1TI8rx4srdvlyoo,17937
 utilities/pathlib.py,sha256=EKZn-wWxH7MEWFrQGqHIoB-GJzyXeiEj8iDIgvkr8Wk,9325
+utilities/permissions.py,sha256=PlY95KIon6onivvZt8H1dKlzPXatLdZ5cUPdfwZDfs4,9408
 utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
 utilities/platform.py,sha256=0pYO5v7L2sU5UN87zHhEEhTKsZ9NIEM8N6UCr0F7bLY,2778
 utilities/polars.py,sha256=cNFBLWgOMUAp_Sz4xtlto17uZswZRrcfQYC95QKyaY4,87483
@@ -80,7 +81,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=1mcFSteDnzIfFZT-UOWPg8lBjDKjRWvgSs5hzHXvsts,22231
+utilities/subprocess.py,sha256=dIBguvLB0WepJKqgBxlzF6r8z9HW5JiGKLg-eslpuec,22549
 utilities/tempfile.py,sha256=Lx6qa16lL1XVH6WdmD_G9vlN6gLI8nrIurxmsFkPKvg,3022
 utilities/testbook.py,sha256=j1KmaVbrX9VrbeMgtPh5gk55myAsn3dyRUn7jGbPbRk,1294
 utilities/text.py,sha256=7SvwcSR2l_5cOrm1samGnR4C-ZI6qyFLHLzSpO1zeHQ,13958
@@ -97,7 +98,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.174.7.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
-dycw_utilities-0.174.7.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
-dycw_utilities-0.174.7.dist-info/METADATA,sha256=q0-Hb1ta7Jppeysc4MdeoUaTPr3Nqwwb0uiMzysigw8,1709
-dycw_utilities-0.174.7.dist-info/RECORD,,
+dycw_utilities-0.174.9.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+dycw_utilities-0.174.9.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
+dycw_utilities-0.174.9.dist-info/METADATA,sha256=LpxiNDUuPoCbqx1Jb4H4UsVRdjGHNrGyeslCZqKy2AE,1709
+dycw_utilities-0.174.9.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.174.7"
+__version__ = "0.174.9"

utilities/hypothesis.py

@@ -77,6 +77,7 @@ from utilities.math import (
 )
 from utilities.os import get_env_var
 from utilities.pathlib import module_path, temp_cwd
+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
@@ -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,
@@ -1611,6 +1644,7 @@ __all__ = [
     "numbers",
     "pairs",
     "paths",
+    "permissions",
     "plain_date_times",
     "py_datetimes",
     "quadruples",

utilities/permissions.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+from contextlib import suppress
+from dataclasses import dataclass
+from functools import reduce
+from operator import or_
+from stat import (
+    S_IRGRP,
+    S_IROTH,
+    S_IRUSR,
+    S_IWGRP,
+    S_IWOTH,
+    S_IWUSR,
+    S_IXGRP,
+    S_IXOTH,
+    S_IXUSR,
+)
+from typing import Literal, Self, override
+
+from utilities.dataclasses import replace_non_sentinel
+from utilities.functions import ensure_member
+from utilities.re import (
+    ExtractGroupError,
+    ExtractGroupsError,
+    extract_group,
+    extract_groups,
+)
+from utilities.sentinel import Sentinel, sentinel
+from utilities.typing import get_args
+
+_MIN_INT = 0o0
+_MAX_INT = 0o777
+type _ZeroToSeven = Literal[0, 1, 2, 3, 4, 5, 6, 7]
+_ZERO_TO_SEVEN: list[_ZeroToSeven] = list(get_args(_ZeroToSeven.__value__))
+
+
+@dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
+class Permissions:
+    user_read: bool = False
+    user_write: bool = False
+    user_execute: bool = False
+    group_read: bool = False
+    group_write: bool = False
+    group_execute: bool = False
+    others_read: bool = False
+    others_write: bool = False
+    others_execute: bool = False
+
+    def __int__(self) -> int:
+        return (
+            100
+            * self._int(
+                read=self.user_read, write=self.user_write, execute=self.user_execute
+            )
+            + 10
+            * self._int(
+                read=self.group_read, write=self.group_write, execute=self.group_execute
+            )
+            + self._int(
+                read=self.others_read,
+                write=self.others_write,
+                execute=self.others_execute,
+            )
+        )
+
+    def _int(
+        self, *, read: bool = False, write: bool = False, execute: bool = False
+    ) -> _ZeroToSeven:
+        return (4 if read else 0) + (2 if write else 0) + (1 if execute else 0)
+
+    @override
+    def __repr__(self) -> str:
+        return ",".join([
+            self._repr_parts(
+                "u",
+                read=self.user_read,
+                write=self.user_write,
+                execute=self.user_execute,
+            ),
+            self._repr_parts(
+                "g",
+                read=self.group_read,
+                write=self.group_write,
+                execute=self.group_execute,
+            ),
+            self._repr_parts(
+                "o",
+                read=self.others_read,
+                write=self.others_write,
+                execute=self.others_execute,
+            ),
+        ])
+
+    def _repr_parts(
+        self,
+        prefix: Literal["u", "g", "o"],
+        /,
+        *,
+        read: bool = False,
+        write: bool = False,
+        execute: bool = False,
+    ) -> str:
+        parts: list[str] = []
+        if read:
+            parts.append("r")
+        if write:
+            parts.append("w")
+        if execute:
+            parts.append("x")
+        return f"{prefix}={''.join(parts)}"
+
+    @override
+    def __str__(self) -> str:
+        return repr(self)
+
+    @classmethod
+    def from_int(cls, n: int, /) -> Self:
+        with suppress(ExtractGroupsError):
+            user, group, others = extract_groups(r"^([0-7])([0-7])([0-7])$", str(n))
+            user_read, user_write, user_execute = cls._from_int(
+                ensure_member(int(user), _ZERO_TO_SEVEN)
+            )
+            group_read, group_write, group_execute = cls._from_int(
+                ensure_member(int(group), _ZERO_TO_SEVEN)
+            )
+            others_read, others_write, others_execute = cls._from_int(
+                ensure_member(int(others), _ZERO_TO_SEVEN)
+            )
+            return cls(
+                user_read=user_read,
+                user_write=user_write,
+                user_execute=user_execute,
+                group_read=group_read,
+                group_write=group_write,
+                group_execute=group_execute,
+                others_read=others_read,
+                others_write=others_write,
+                others_execute=others_execute,
+            )
+        with suppress(ExtractGroupsError):
+            group, others = extract_groups(r"^([0-7])([0-7])$", str(n))
+            group_read, group_write, group_execute = cls._from_int(
+                ensure_member(int(group), _ZERO_TO_SEVEN)
+            )
+            others_read, others_write, others_execute = cls._from_int(
+                ensure_member(int(others), _ZERO_TO_SEVEN)
+            )
+            return cls(
+                group_read=group_read,
+                group_write=group_write,
+                group_execute=group_execute,
+                others_read=others_read,
+                others_write=others_write,
+                others_execute=others_execute,
+            )
+        with suppress(ExtractGroupError):
+            others = extract_group(r"^([0-7])$", str(n))
+            others_read, others_write, others_execute = cls._from_int(
+                ensure_member(int(others), _ZERO_TO_SEVEN)
+            )
+            return cls(
+                others_read=others_read,
+                others_write=others_write,
+                others_execute=others_execute,
+            )
+        if n == 0:
+            return cls()
+        raise PermissionsFromIntError(n=n)
+
+    @classmethod
+    def _from_int(cls, n: _ZeroToSeven, /) -> tuple[bool, bool, bool]:
+        return bool(4 & n), bool(2 & n), bool(1 & n)
+
+    @classmethod
+    def from_octal(cls, n: int, /) -> Self:
+        if _MIN_INT <= n <= _MAX_INT:
+            return cls(
+                user_read=bool(n & S_IRUSR),
+                user_write=bool(n & S_IWUSR),
+                user_execute=bool(n & S_IXUSR),
+                group_read=bool(n & S_IRGRP),
+                group_write=bool(n & S_IWGRP),
+                group_execute=bool(n & S_IXGRP),
+                others_read=bool(n & S_IROTH),
+                others_write=bool(n & S_IWOTH),
+                others_execute=bool(n & S_IXOTH),
+            )
+        raise PermissionsFromOctalError(n=n)
+
+    @classmethod
+    def from_text(cls, text: str, /) -> Self:
+        try:
+            user, group, others = extract_groups(
+                r"^u=(r?w?x?),g=(r?w?x?),o=(r?w?x?)$", text
+            )
+        except ExtractGroupsError:
+            raise PermissionsFromTextError(text=text) from None
+        user_read, user_write, user_execute = cls._from_text_part(user)
+        group_read, group_write, group_execute = cls._from_text_part(group)
+        others_read, others_write, others_execute = cls._from_text_part(others)
+        return cls(
+            user_read=user_read,
+            user_write=user_write,
+            user_execute=user_execute,
+            group_read=group_read,
+            group_write=group_write,
+            group_execute=group_execute,
+            others_read=others_read,
+            others_write=others_write,
+            others_execute=others_execute,
+        )
+
+    @classmethod
+    def _from_text_part(cls, text: str, /) -> tuple[bool, bool, bool]:
+        read, write, execute = extract_groups("^(r?)(w?)(x?)$", text)
+        return read != "", write != "", execute != ""
+
+    @property
+    def octal(self) -> int:
+        flags: list[int] = [
+            S_IRUSR if self.user_read else 0,
+            S_IWUSR if self.user_write else 0,
+            S_IXUSR if self.user_execute else 0,
+            S_IRGRP if self.group_read else 0,
+            S_IWGRP if self.group_write else 0,
+            S_IXGRP if self.group_execute else 0,
+            S_IROTH if self.others_read else 0,
+            S_IWOTH if self.others_write else 0,
+            S_IXOTH if self.others_execute else 0,
+        ]
+        return reduce(or_, flags)
+
+    def replace(
+        self,
+        *,
+        user_read: bool | Sentinel = sentinel,
+        user_write: bool | Sentinel = sentinel,
+        user_execute: bool | Sentinel = sentinel,
+        group_read: bool | Sentinel = sentinel,
+        group_write: bool | Sentinel = sentinel,
+        group_execute: bool | Sentinel = sentinel,
+        others_read: bool | Sentinel = sentinel,
+        others_write: bool | Sentinel = sentinel,
+        others_execute: bool | Sentinel = sentinel,
+    ) -> Self:
+        return replace_non_sentinel(
+            self,
+            user_read=user_read,
+            user_write=user_write,
+            user_execute=user_execute,
+            group_read=group_read,
+            group_write=group_write,
+            group_execute=group_execute,
+            others_read=others_read,
+            others_write=others_write,
+            others_execute=others_execute,
+        )
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromIntError(PermissionsError):
+    n: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid integer for permissions; got {self.n}"
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromOctalError(PermissionsError):
+    n: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid octal for permissions; got {oct(self.n)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromTextError(PermissionsError):
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid string for permissions; got {self.text!r}"
+
+
+__all__ = [
+    "Permissions",
+    "PermissionsError",
+    "PermissionsFromIntError",
+    "PermissionsFromOctalError",
+    "PermissionsFromTextError",
+]

utilities/subprocess.py

@@ -5,7 +5,7 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from io import StringIO
 from pathlib import Path
-from shlex import join, quote
+from shlex import join
 from string import Template
 from subprocess import PIPE, CalledProcessError, Popen
 from threading import Thread
@@ -40,22 +40,37 @@ RESTART_SSHD = ["systemctl", "restart", "sshd"]
 UPDATE_CA_CERTIFICATES: str = "update-ca-certificates"
 
 
+##
+
+
 def apt_install_cmd(package: str, /) -> list[str]:
     return ["apt", "install", "-y", package]
 
 
+##
+
+
 def cat_cmd(path: PathLike, /) -> list[str]:
     return ["cat", str(path)]
 
 
+##
+
+
 def cd_cmd(path: PathLike, /) -> list[str]:
     return ["cd", str(path)]
 
 
+##
+
+
 def chmod_cmd(path: PathLike, mode: str, /) -> list[str]:
     return ["chmod", mode, str(path)]
 
 
+##
+
+
 def chown_cmd(
     path: PathLike, /, *, user: str | None = None, group: str | None = None
 ) -> list[str]:
@@ -80,14 +95,23 @@ class ChownCmdError(Exception):
         return "At least one of 'user' and/or 'group' must be given; got None"
 
 
+##
+
+
 def cp_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
     return ["cp", "-r", str(src), str(dest)]
 
 
+##
+
+
 def echo_cmd(text: str, /) -> list[str]:
     return ["echo", text]
 
 
+##
+
+
 def expand_path(
     path: PathLike, /, *, subs: StrMapping | None = None, sudo: bool = False
 ) -> Path:
@@ -98,47 +122,71 @@ def expand_path(
     return Path(path).expanduser()
 
 
+##
+
+
 def git_clone_cmd(url: str, path: PathLike, /) -> list[str]:
     return ["git", "clone", "--recurse-submodules", url, str(path)]
 
 
+##
+
+
 def git_hard_reset_cmd(*, branch: str | None = None) -> list[str]:
     branch_use = "master" if branch is None else branch
     return ["git", "hard-reset", branch_use]
 
 
+##
+
+
+def maybe_parent(path: PathLike, /, *, parent: bool = False) -> Path:
+    path = Path(path)
+    return path.parent if parent else path
+
+
+##
+
+
 def maybe_sudo_cmd(cmd: str, /, *args: str, sudo: bool = False) -> list[str]:
     parts: list[str] = [cmd, *args]
     return sudo_cmd(*parts) if sudo else parts
 
 
+##
+
+
 def mkdir(path: PathLike, /, *, sudo: bool = False, parent: bool = False) -> None:
     if sudo:  # pragma: no cover
         run(*sudo_cmd(*mkdir_cmd(path, parent=parent)))
     else:
-        path = expand_path(path)
-        path_use = path.parent if parent else path
-        path_use.mkdir(parents=True, exist_ok=True)
+        maybe_parent(path, parent=parent).mkdir(parents=True, exist_ok=True)
+
+
+##
 
 
 def mkdir_cmd(path: PathLike, /, *, parent: bool = False) -> list[str]:
-    args: list[str] = ["mkdir", "-p"]
-    quoted = quote(str(path))
-    if parent:
-        args.append(f"$(dirname {quoted})")
-    else:
-        args.append(quoted)
-    return args
+    return ["mkdir", "-p", str(maybe_parent(path, parent=parent))]
+
+
+##
 
 
 def mv_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
     return ["mv", str(src), str(dest)]
 
 
+##
+
+
 def rm_cmd(path: PathLike, /) -> list[str]:
     return ["rm", "-rf", str(path)]
 
 
+##
+
+
 def rsync(
     src_or_srcs: MaybeIterable[PathLike],
     user: str,
@@ -153,7 +201,6 @@ def rsync(
     print: bool = False,  # noqa: A002
     retry: Retry | None = None,
     logger: LoggerLike | None = None,
-    archive: bool = False,
     chown_user: str | None = None,
     chown_group: str | None = None,
     exclude: MaybeIterable[str] | None = None,
@@ -171,12 +218,13 @@ def rsync(
         retry=retry,
         logger=logger,
     )
+    is_dir = any(Path(s).is_dir() for s in always_iterable(src_or_srcs))  # skipif-ci
     rsync_args = rsync_cmd(  # skipif-ci
         src_or_srcs,
         user,
         hostname,
         dest,
-        archive=archive,
+        archive=is_dir,
         chown_user=chown_user,
         chown_group=chown_group,
         exclude=exclude,
@@ -184,6 +232,7 @@ def rsync(
         host_key_algorithms=host_key_algorithms,
         strict_host_key_checking=strict_host_key_checking,
         sudo=sudo,
+        parent=is_dir,
     )
     run(*rsync_args, print=print, retry=retry, logger=logger)  # skipif-ci
     if chmod is not None:  # skipif-ci
@@ -201,6 +250,9 @@ def rsync(
         )
 
 
+##
+
+
 def rsync_cmd(
     src_or_srcs: MaybeIterable[PathLike],
     user: str,
@@ -216,6 +268,7 @@ def rsync_cmd(
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
     sudo: bool = False,
+    parent: bool = False,
 ) -> list[str]:
     args: list[str] = ["rsync"]
     if archive:
@@ -244,7 +297,15 @@ def rsync_cmd(
     args.extend(["--rsh", join(rsh_args)])
     if sudo:
         args.extend(["--rsync-path", join(sudo_cmd("rsync"))])
-    return [*args, *map(str, always_iterable(src_or_srcs)), f"{user}@{hostname}:{dest}"]
+    dest_use = maybe_parent(dest, parent=parent)
+    return [
+        *args,
+        *map(str, always_iterable(src_or_srcs)),
+        f"{user}@{hostname}:{dest_use}",
+    ]
+
+
+##
 
 
 @overload
@@ -502,10 +563,16 @@ def _run_write_to_streams(text: str, /, *outputs: IO[str]) -> None:
         _ = output.write(text)
 
 
+##
+
+
 def set_hostname_cmd(hostname: str, /) -> list[str]:
     return ["hostnamectl", "set-hostname", hostname]
 
 
+##
+
+
 @overload
 def ssh(
     user: str,
@@ -641,6 +708,9 @@ def ssh(
     )
 
 
+##
+
+
 def ssh_cmd(
     user: str,
     hostname: str,
@@ -658,6 +728,9 @@ def ssh_cmd(
     return [*args, f"{user}@{hostname}", *cmd_and_cmds_or_args]
 
 
+##
+
+
 def ssh_opts_cmd(
     *,
     batch_mode: bool = True,
@@ -673,26 +746,44 @@ def ssh_opts_cmd(
     return [*args, "-T"]
 
 
+##
+
+
 def ssh_keygen_cmd(hostname: str, /) -> list[str]:
     return ["ssh-keygen", "-f", "~/.ssh/known_hosts", "-R", hostname]
 
 
+##
+
+
 def sudo_cmd(cmd: str, /, *args: str) -> list[str]:
     return ["sudo", cmd, *args]
 
 
+##
+
+
 def sudo_nopasswd_cmd(user: str, /) -> str:
     return f"{user} ALL=(ALL) NOPASSWD: ALL"
 
 
+##
+
+
 def symlink_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
     return ["ln", "-s", str(src), str(dest)]
 
 
+##
+
+
 def touch_cmd(path: PathLike, /) -> list[str]:
     return ["touch", str(path)]
 
 
+##
+
+
 def uv_run_cmd(module: str, /, *args: str) -> list[str]:
     return [
         "uv",
@@ -708,6 +799,9 @@ def uv_run_cmd(module: str, /, *args: str) -> list[str]:
     ]
 
 
+##
+
+
 @contextmanager
 def yield_ssh_temp_dir(
     user: str,
@@ -748,6 +842,7 @@ __all__ = [
     "expand_path",
     "git_clone_cmd",
     "git_hard_reset_cmd",
+    "maybe_parent",
     "maybe_sudo_cmd",
     "mkdir",
     "mkdir_cmd",