pyinfra 3.5.1__py3-none-any.whl → 3.6.1__py3-none-any.whl

pyinfra/operations/files.py

@@ -117,6 +117,7 @@ def download(
 
     .. code:: python
 
+        from pyinfra.operations import files
         files.download(
             name="Download the Docker repo file",
             src="https://download.docker.com/linux/centos/docker-ce.repo",
@@ -167,8 +168,12 @@ def download(
 
     # If we download, always do user/group/mode as SSH user may be different
     if download:
+        # Use explicit temp_dir if provided, otherwise fall back to _temp_dir global argument
+        effective_temp_dir = temp_dir
+        if effective_temp_dir is None and host.current_op_global_arguments:
+            effective_temp_dir = host.current_op_global_arguments.get("_temp_dir")
         temp_file = host.get_temp_filename(
-            dest, temp_directory=str(temp_dir) if temp_dir is not None else None
+            dest, temp_directory=str(effective_temp_dir) if effective_temp_dir is not None else None
         )
 
         curl_args: list[Union[str, StringCommand]] = ["-sSLf"]
@@ -751,6 +756,15 @@ def _file_equal(local_path: str | IO[Any] | None, remote_path: str) -> bool:
     return False
 
 
+def _remote_file_equal(remote_path_a: str, remote_path_b: str) -> bool:
+    for fact in [Sha1File, Md5File, Sha256File]:
+        sum_a = host.get_fact(fact, path=remote_path_a)
+        sum_b = host.get_fact(fact, path=remote_path_b)
+        if sum_a and sum_b:
+            return sum_a == sum_b
+    return False
+
+
 @operation(
     # We don't (currently) cache the local state, so there's nothing we can
     # update to flag the local file as present.
@@ -797,19 +811,32 @@ def get(
 
     remote_file = host.get_fact(File, path=src)
 
+    # Use _temp_dir global argument if provided
+    temp_dir = None
+    if host.current_op_global_arguments:
+        temp_dir = host.current_op_global_arguments.get("_temp_dir")
+
     # No remote file, so assume exists and download it "blind"
     if not remote_file or force:
-        yield FileDownloadCommand(src, dest, remote_temp_filename=host.get_temp_filename(dest))
+        yield FileDownloadCommand(
+            src, dest, remote_temp_filename=host.get_temp_filename(dest, temp_directory=temp_dir)
+        )
 
     # No local file, so always download
     elif not os.path.exists(dest):
-        yield FileDownloadCommand(src, dest, remote_temp_filename=host.get_temp_filename(dest))
+        yield FileDownloadCommand(
+            src, dest, remote_temp_filename=host.get_temp_filename(dest, temp_directory=temp_dir)
+        )
 
     # Remote file exists - check if it matches our local
     else:
         # Check hash sum, download if needed
         if not _file_equal(dest, src):
-            yield FileDownloadCommand(src, dest, remote_temp_filename=host.get_temp_filename(dest))
+            yield FileDownloadCommand(
+                src,
+                dest,
+                remote_temp_filename=host.get_temp_filename(dest, temp_directory=temp_dir),
+            )
         else:
             host.noop("file {0} has already been downloaded".format(dest))
 
@@ -998,6 +1025,11 @@ def put(
     if create_remote_dir:
         yield from _create_remote_dir(dest, user, group)
 
+    # Use _temp_dir global argument if provided
+    temp_dir = None
+    if host.current_op_global_arguments:
+        temp_dir = host.current_op_global_arguments.get("_temp_dir")
+
     # No remote file, always upload and user/group/mode if supplied
     if not remote_file or force:
         if state.config.DIFF:
@@ -1013,7 +1045,7 @@ def put(
         yield FileUploadCommand(
             local_file,
             dest,
-            remote_temp_filename=host.get_temp_filename(dest),
+            remote_temp_filename=host.get_temp_filename(dest, temp_directory=temp_dir),
         )
 
         if user or group:
@@ -1060,7 +1092,7 @@ def put(
             yield FileUploadCommand(
                 local_file,
                 dest,
-                remote_temp_filename=host.get_temp_filename(dest),
+                remote_temp_filename=host.get_temp_filename(dest, temp_directory=temp_dir),
             )
 
             if user or group:
@@ -1156,11 +1188,14 @@ def template(
     if not set explicitly.
 
     Notes:
-       Common convention is to store templates in a "templates" directory and
-       have a filename suffix with '.j2' (for jinja2).
+        Common convention is to store templates in a "templates" directory and
+        have a filename suffix with '.j2' (for jinja2).
+
+        The default template lookup directory (used with jinjas ``extends``, ``import`` and
+        ``include`` statements) is the current working directory.
 
-       For information on the template syntax, see
-       `the jinja2 docs <https://jinja.palletsprojects.com>`_.
+        For information on the template syntax, see
+        `the jinja2 docs <https://jinja.palletsprojects.com>`_.
 
     **Examples:**
 
@@ -1309,6 +1344,39 @@ def move(src: str, dest: str, overwrite=False):
     yield StringCommand("mv", QuoteString(src), QuoteString(dest))
 
 
+@operation()
+def copy(src: str, dest: str, overwrite=False):
+    """
+    Copy remote file/directory/link into remote directory
+
+    + src: remote file/directory to copy
+    + dest: remote directory to copy `src` into
+    + overwrite: whether to overwrite dest, if present
+    """
+    src_is_dir = host.get_fact(Directory, src)
+    if not host.get_fact(File, src) and not src_is_dir:
+        raise OperationError(f"src {src} does not exist")
+
+    if not host.get_fact(Directory, dest):
+        raise OperationError(f"dest {dest} is not an existing directory")
+
+    dest_file_path = os.path.join(dest, os.path.basename(src))
+    dest_file_exists = host.get_fact(File, dest_file_path)
+    if dest_file_exists and not overwrite:
+        if _remote_file_equal(src, dest_file_path):
+            host.noop(f"{dest_file_path} already exists")
+            return
+        else:
+            raise OperationError(f"{dest_file_path} already exists and is different than src")
+
+    cp_cmd = ["cp -r"]
+
+    if overwrite:
+        cp_cmd.append("-f")
+
+    yield StringCommand(*cp_cmd, QuoteString(src), QuoteString(dest))
+
+
 def _validate_path(path):
     try:
         return os.fspath(path)
@@ -1786,7 +1854,7 @@ def block(
         # put complex alias into .zshrc
         files.block(
             path="/home/user/.zshrc",
-            content="eval $(thefuck -a)",
+            content="eval $(thef -a)",
             try_prevent_shell_expansion=True,
             marker="## {mark} ALIASES ##"
         )
@@ -1800,6 +1868,13 @@ def block(
     current = host.get_fact(Block, path=path, marker=marker, begin=begin, end=end)
     cmd = None
 
+    # Use _temp_dir global argument if provided, otherwise fall back to config
+    tmp_dir = None
+    if host.current_op_global_arguments:
+        tmp_dir = host.current_op_global_arguments.get("_temp_dir")
+    if not tmp_dir:
+        tmp_dir = host.get_temp_dir_config()
+
     # standard awk doesn't have an "in-place edit" option so we write to a tempfile and
     # if edits were successful move to dest i.e. we do: <out_prep> ... do some work ... <real_out>
     q_path = QuoteString(path)
@@ -1815,7 +1890,7 @@ def block(
         )
     )
     out_prep = StringCommand(
-        'OUT="$(TMPDIR=/tmp mktemp -t pyinfra.XXXXXX)" && ',
+        f'OUT="$(TMPDIR={tmp_dir} mktemp -t pyinfra.XXXXXX)" && ',
         *mode_get,
         'OWNER="$(stat -c "%u:%g"',
         q_path,

pyinfra/operations/flatpak.py

@@ -26,6 +26,7 @@ def packages(
 
     .. code:: python
 
+        from pyinfra.operations import flatpak
         # Install vlc flatpak
         flatpak.package(
             name="Install vlc",

pyinfra/operations/gem.py

@@ -27,6 +27,7 @@ def packages(packages: str | list[str] | None = None, present=True, latest=False
 
     .. code:: python
 
+        from pyinfra.operations import gem
         # Note: Assumes that 'gem' is installed.
         gem.packages(
             name="Install rspec",

pyinfra/operations/git.py

@@ -30,6 +30,7 @@ def config(key: str, value: str, multi_value=False, repo: str | None = None, sys
 
     .. code:: python
 
+        from pyinfra.operations import git
         git.config(
             name="Always prune specified repo",
             key="fetch.prune",

pyinfra/operations/iptables.py

@@ -118,6 +118,7 @@ def rule(
 
     .. code:: python
 
+        from pyinfra.operations import iptables
         iptables.rule(
             name="Block SSH traffic",
             chain="INPUT",

pyinfra/operations/lxd.py

@@ -38,6 +38,7 @@ def container(
 
     .. code:: python
 
+        from pyinfra.operations import lxd
         lxd.container(
             name="Add an ubuntu container",
             id="ubuntu19",

pyinfra/operations/mysql.py

@@ -101,6 +101,7 @@ def user(
 
     .. code:: python
 
+        from pyinfra.operations import mysql
         mysql.user(
             name="Create the pyinfra@localhost MySQL user",
             user="pyinfra",

pyinfra/operations/opkg.py

@@ -52,7 +52,8 @@ def packages(
 
     .. code:: python
 
-        # Ensure packages are installed∂ (will not force package upgrade)
+        from pyinfra.operations import opkg
+        # Ensure packages are installed (will not force package upgrade)
         opkg.packages(['asterisk', 'vim'], name="Install Asterisk and Vim")
 
         # Install the latest versions of packages (always check)

pyinfra/operations/pacman.py

@@ -57,6 +57,7 @@ def packages(
 
     .. code:: python
 
+        from pyinfra.operations import pacman
         pacman.packages(
             name="Install Vim and a plugin",
             packages=["vim-fugitive", "vim"],

pyinfra/operations/pip.py

@@ -36,6 +36,7 @@ def virtualenv(
 
     .. code:: python
 
+        from pyinfra.operations import pip
         pip.virtualenv(
             name="Create a virtualenv",
             path="/usr/local/bin/venv",

pyinfra/operations/pipx.py

@@ -34,6 +34,7 @@ def packages(
 
     .. code:: python
 
+        from pyinfra.operations import pipx
         pipx.packages(
             name="Install ",
             packages=["pyinfra"],

pyinfra/operations/pkg.py

@@ -35,6 +35,7 @@ def packages(packages: str | list[str] | None = None, present=True, pkg_path: st
 
     .. code:: python
 
+        from pyinfra.operations import pkg
         pkg.packages(
             name="Install Vim and Vim Addon Manager",
             packages=["vim-addon-manager", "vim"],

pyinfra/operations/pkgin.py

@@ -56,6 +56,7 @@ def packages(
 
     .. code:: python
 
+        from pyinfra.operations import pkgin
         # Update package list and install packages
         pkgin.packages(
             name="Install tmux and Vim",

pyinfra/operations/postgres.py

@@ -53,7 +53,12 @@ def sql(
     )
 
 
-@operation()
+@operation(
+    idempotent_notice=(
+        "This operation will always execute commands when a password is provided, "
+        "as pyinfra cannot reliably validate the current password."
+    ),
+)
 def role(
     role: str,
     present: bool = True,
@@ -96,6 +101,7 @@ def role(
 
     .. code:: python
 
+        from pyinfra.operations import postgresql
         postgresql.role(
             name="Create the pyinfra PostgreSQL role",
             role="pyinfra",

pyinfra/operations/puppet.py

@@ -19,6 +19,7 @@ def agent(server: str | None = None, port: int | None = None):
 
     .. code:: python
 
+        from pyinfra.operations import puppet
         puppet.agent()
 
         # We also expect a return code of:

pyinfra/operations/python.py

@@ -22,6 +22,7 @@ def call(function: Callable, *args, **kwargs):
 
     .. code:: python
 
+        from pyinfra.operations import python
         def my_callback(hello=None):
             command = 'echo hello'
             if hello:

pyinfra/operations/selinux.py

@@ -39,6 +39,7 @@ def boolean(bool_name: str, value: Boolean, persistent=False):
 
     .. code:: python
 
+        from pyinfra.operations import selinux
         selinux.boolean(
             name='Allow Apache to connect to LDAP server',
             'httpd_can_network_connect',

pyinfra/operations/server.py

@@ -68,6 +68,7 @@ def reboot(delay=10, interval=1, reboot_timeout=300):
 
     .. code:: python
 
+        from pyinfra.operations import server
         server.reboot(
             name="Reboot the server and wait to reconnect",
             delay=60,

pyinfra/operations/snap.py

@@ -32,7 +32,8 @@ def package(
 
     .. code:: python
 
-        # Install vlc snap
+        from pyinfra.operations import snap
+        # Install vlc via snap
         snap.package(
             name="Install vlc",
             packages="vlc",

pyinfra/operations/ssh.py

@@ -28,6 +28,7 @@ def keyscan(hostname: str, force=False, port=22):
 
     .. code:: python
 
+        from pyinfra.operations import ssh
         ssh.keyscan(
             name="Set add server two to known_hosts on one",
             hostname="two.example.com",

pyinfra/operations/systemd.py

@@ -66,6 +66,7 @@ def service(
 
     .. code:: python
 
+        from pyinfra.operations import systemd
         systemd.service(
             name="Restart and enable the dnsmasq service",
             service="dnsmasq.service",

pyinfra/operations/sysvinit.py

@@ -38,7 +38,7 @@ def service(
         support enabling/disabling services:
 
         + Ubuntu/Debian (``update-rc.d``)
-        + CentOS/Fedora/RHEL (``chkconfig``)
+        + Fedora/RHEL (``chkconfig``)
         + Gentoo (``rc-update``)
 
         For other distributions and more granular service control, see the
@@ -48,6 +48,7 @@ def service(
 
     .. code:: python
 
+        from pyinfra.operations import sysvinit
         sysvinit.service(
             name="Restart and enable rsyslog",
             service="rsyslog",

pyinfra/operations/util/docker.py

@@ -1,17 +1,172 @@
-import dataclasses
-from typing import Any, Dict, List
+from dataclasses import dataclass, field
+from typing import Any
 
 from pyinfra.api import OperationError
 
 
-@dataclasses.dataclass
+@dataclass
+class ImageReference:
+    """Represents a parsed Docker image reference."""
+
+    repository: str
+    namespace: str | None = None
+    tag: str | None = None
+    digest: str | None = None
+    registry_host: str | None = None
+    registry_port: int | None = None
+
+    @property
+    def registry(self) -> str | None:
+        """Get the full registry address (host:port)."""
+        if not self.registry_host:
+            return None
+        if self.registry_port:
+            return f"{self.registry_host}:{self.registry_port}"
+        return self.registry_host
+
+    @property
+    def name(self) -> str:
+        """Get the full image name without tag or digest."""
+        parts = []
+        if self.registry:
+            parts.append(self.registry)
+        if self.namespace:
+            parts.append(self.namespace)
+        parts.append(self.repository)
+        return "/".join(parts)
+
+    @property
+    def full_reference(self) -> str:
+        """Get the complete image reference string."""
+        ref = self.name
+        if self.tag:
+            ref += f":{self.tag}"
+        if self.digest:
+            ref += f"@{self.digest}"
+        return ref
+
+
+def parse_registry(registry: str) -> tuple[str, int | None]:
+    """
+    Parse a registry string into host and port components.
+
+    Args:
+        registry: String like "registry.io:5000" or "registry.io"
+
+    Returns:
+        tuple: (host, port) where port is None if not specified
+
+    Raises:
+        ValueError: If port is specified but not a valid integer
+    """
+    if ":" in registry:
+        host, port_str = registry.rsplit(":", 1)
+        if port_str:  # Only try to parse if port_str is not empty
+            try:
+                port = int(port_str)
+                if port < 0 or port > 65535:
+                    raise ValueError(
+                        f"Invalid port number: {port}. Port must be between 0 and 65535"
+                    )
+                return host, port
+            except ValueError as e:
+                if "invalid literal" in str(e):
+                    raise ValueError(
+                        f"Invalid port in registry '{registry}': '{port_str}' is not a valid port number"
+                    )
+                raise  # Re-raise port range error
+        else:
+            # Empty port (e.g., "registry.io:")
+            raise ValueError(f"Invalid registry format '{registry}': port cannot be empty")
+    else:
+        return registry, None
+
+
+def parse_image_reference(image: str) -> ImageReference:
+    """
+    Parse a Docker image reference into components.
+
+    Format: [HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG][@DIGEST]
+
+    Raises:
+        ValueError: If the image reference is empty or invalid
+    """
+    if not image or not image.strip():
+        raise ValueError("Image reference cannot be empty")
+
+    original = image.strip()
+    registry_host = None
+    registry_port = None
+    namespace = None
+    repository = None
+    tag = None
+    digest = None
+
+    # Extract digest first (format: name@digest)
+    if "@" in original:
+        original, digest = original.rsplit("@", 1)
+
+    # Extract tag (format: name:tag)
+    if ":" in original:
+        parts = original.split(":")
+        if len(parts) >= 2:
+            potential_tag = parts[-1]
+            # Tag cannot contain '/' - if it does, the colon is part of the registry, separating host and port
+            if "/" not in potential_tag:
+                original = ":".join(parts[:-1])
+                tag = potential_tag
+
+    # Split by '/' to separate registry/namespace/repository
+    parts = original.split("/")
+
+    if len(parts) == 1:
+        # Just repository name (e.g., "nginx")
+        repository = parts[0]
+    elif len(parts) == 2:
+        # Could be namespace/repository or registry/repository
+        if "." in parts[0] or ":" in parts[0]:
+            # Likely a registry (registry.io:5000/repo or registry.io/repo)
+            registry_host, registry_port = parse_registry(parts[0])
+            repository = parts[1]
+        else:
+            # Likely namespace/repository
+            namespace = parts[0]
+            repository = parts[1]
+    elif len(parts) >= 3:
+        # registry/namespace/repository or registry/nested/namespace/repository
+        registry_host, registry_port = parse_registry(parts[0])
+        namespace = "/".join(parts[1:-1])
+        repository = parts[-1]
+
+    # Validate that we found a repository
+    if not repository:
+        raise ValueError(f"Invalid image reference: no repository found in '{image}'")
+
+    # Default tag to 'latest' if neither tag nor digest specified. This is Docker's default behavior.
+    if tag is None and digest is None:
+        tag = "latest"
+
+    return ImageReference(
+        repository=repository,
+        namespace=namespace,
+        tag=tag,
+        digest=digest,
+        registry_host=registry_host,
+        registry_port=registry_port,
+    )
+
+
+@dataclass
 class ContainerSpec:
     image: str = ""
-    ports: List[str] = dataclasses.field(default_factory=list)
-    networks: List[str] = dataclasses.field(default_factory=list)
-    volumes: List[str] = dataclasses.field(default_factory=list)
-    env_vars: List[str] = dataclasses.field(default_factory=list)
+    ports: list[str] = field(default_factory=list)
+    networks: list[str] = field(default_factory=list)
+    volumes: list[str] = field(default_factory=list)
+    env_vars: list[str] = field(default_factory=list)
+    labels: list[str] = field(default_factory=list)
     pull_always: bool = False
+    restart_policy: str | None = None
+    auto_remove: bool = False
 
     def container_create_args(self):
         args = []
@@ -27,14 +182,23 @@ class ContainerSpec:
         for env_var in self.env_vars:
             args.append("-e {0}".format(env_var))
 
+        for label in self.labels:
+            args.append("--label {0}".format(label))
+
         if self.pull_always:
             args.append("--pull always")
 
+        if self.restart_policy:
+            args.append("--restart {0}".format(self.restart_policy))
+
+        if self.auto_remove:
+            args.append("--rm")
+
         args.append(self.image)
 
         return args
 
-    def diff_from_inspect(self, inspect_dict: Dict[str, Any]) -> List[str]:
+    def diff_from_inspect(self, inspect_dict: dict[str, Any]) -> list[str]:
         # TODO(@minor-fixes): Diff output of "docker inspect" against this spec
         # to determine if the container needs to be recreated. Currently, this
         # function will never recreate when attributes change, which is

pyinfra/operations/util/packaging.py

@@ -172,6 +172,8 @@ def ensure_packages(
         return
     if isinstance(packages_to_ensure, str):
         packages_to_ensure = [packages_to_ensure]
+    if len(packages_to_ensure) == 0:
+        return
 
     packages: list[PkgInfo] = []
     if isinstance(packages_to_ensure[0], PkgInfo):

pyinfra/operations/xbps.py

@@ -54,6 +54,7 @@ def packages(
 
     .. code:: python
 
+        from pyinfra.operations import xbps
         xbps.packages(
             name="Install Vim and Vim Pager",
             packages=["vimpager", "vim"],

pyinfra/operations/yum.py

@@ -25,6 +25,9 @@ def key(src: str):
 
     .. code:: python
 
+        from pyinfra import host
+        from pyinfra.operations import dnf
+        from pyinfra.facts.server import LinuxDistribution
         linux_id = host.get_fact(LinuxDistribution)["release_meta"].get("ID")
         yum.key(
             name="Add the Docker CentOS gpg key",
@@ -75,7 +78,7 @@ def repo(
 
         # Create the repository file from baseurl/etc
         yum.repo(
-            name="Add the Docker CentOS repo",
+            name="Add the Docker repo",
             src="DockerCE",
             baseurl="https://download.docker.com/linux/centos/7/$basearch/stable",
         )

pyinfra/operations/zfs.py

@@ -33,6 +33,7 @@ def dataset(
 
     .. code:: python
 
+        from pyinfra.operations import zfs
         zfs.dataset(
             "tank/srv",
             mountpoint="/srv",

pyinfra/operations/zypper.py

@@ -42,6 +42,7 @@ def repo(
 
     .. code:: python
 
+        from pyinfra.operations import zypper
         # Download a repository file
         zypper.repo(
             name="Install container virtualization repo via URL",