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

pyinfra/operations/docker.py

@@ -8,9 +8,15 @@ from __future__ import annotations
 
 from pyinfra import host
 from pyinfra.api import operation
-from pyinfra.facts.docker import DockerContainer, DockerNetwork, DockerPlugin, DockerVolume
+from pyinfra.facts.docker import (
+    DockerContainer,
+    DockerImage,
+    DockerNetwork,
+    DockerPlugin,
+    DockerVolume,
+)
 
-from .util.docker import ContainerSpec, handle_docker
+from .util.docker import ContainerSpec, handle_docker, parse_image_reference
 
 
 @operation()
@@ -21,6 +27,7 @@ def container(
     networks: list[str] | None = None,
     volumes: list[str] | None = None,
     env_vars: list[str] | None = None,
+    labels: list[str] | None = None,
     pull_always: bool = False,
     present: bool = True,
     force: bool = False,
@@ -35,6 +42,7 @@ def container(
     + ports: port list to expose
     + volumes: volume list to map on container
     + env_vars: environment variable list to inject on container
+    + labels: Label list to attach to the container
     + pull_always: force image pull
     + force: remove a container with same name and create a new one
     + present: whether the container should be up and running
@@ -44,6 +52,7 @@ def container(
 
     .. code:: python
 
+        from pyinfra.operations import docker
         # Run a container
         docker.container(
             name="Deploy Nginx container",
@@ -78,6 +87,7 @@ def container(
         networks or list(),
         volumes or list(),
         env_vars or list(),
+        labels or list(),
         pull_always,
     )
     existent_container = host.get_fact(DockerContainer, object_id=container)
@@ -127,13 +137,14 @@ def container(
         )
 
 
-@operation(is_idempotent=False)
-def image(image, present=True):
+@operation()
+def image(image: str, present: bool = True, force: bool = False):
     """
     Manage Docker images
 
     + image: Image and tag ex: nginx:alpine
     + present: whether the Docker image should exist
+    + force: always pull the image if present is True
 
     **Examples:**
 
@@ -153,20 +164,55 @@ def image(image, present=True):
             present=False,
         )
     """
-
+    image_info = parse_image_reference(image)
     if present:
-        yield handle_docker(
-            resource="image",
-            command="pull",
-            image=image,
-        )
-
+        if force:
+            # always pull the image if force is True
+            yield handle_docker(
+                resource="image",
+                command="pull",
+                image=image,
+            )
+            return
+        else:
+            existent_image = host.get_fact(DockerImage, object_id=image)
+            if image_info.digest:
+                # If a digest is specified, we must ensure the exact image is present
+                if existent_image:
+                    host.noop(f"Image with digest {image_info.digest} already exists!")
+                else:
+                    yield handle_docker(
+                        resource="image",
+                        command="pull",
+                        image=image,
+                    )
+            elif image_info.tag == "latest" or not image_info.tag:
+                # If the tag is 'latest' or not specified, always pull to ensure freshness
+                yield handle_docker(
+                    resource="image",
+                    command="pull",
+                    image=image,
+                )
+            else:
+                # For other tags, check if the image exists
+                if existent_image:
+                    host.noop(f"Image with tag {image_info.tag} already exists!")
+                else:
+                    yield handle_docker(
+                        resource="image",
+                        command="pull",
+                        image=image,
+                    )
     else:
-        yield handle_docker(
-            resource="image",
-            command="remove",
-            image=image,
-        )
+        existent_image = host.get_fact(DockerImage, object_id=image)
+        if existent_image:
+            yield handle_docker(
+                resource="image",
+                command="remove",
+                image=image,
+            )
+        else:
+            host.noop("There is no {0} image!".format(image))
 
 
 @operation()

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

@@ -96,6 +96,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",