pyinfra 3.1.1__py2.py3-none-any.whl → 3.3__py2.py3-none-any.whl

pyinfra/operations/docker.py

@@ -1,12 +1,14 @@
 """
-Manager Docker Containers, Volumes and Networks
+Manager Docker containers, volumes and networks. These operations allow you to manage Docker from
+the view of the current inventory host. See the :doc:`../connectors/docker` to use Docker containers
+as inventory directly.
 """
 
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.docker import DockerContainer, DockerNetwork, DockerVolume
 
-from .util.docker import handle_docker
+from .util.docker import ContainerSpec, handle_docker
 
 
 @operation()
@@ -30,9 +32,9 @@ def container(
     + networks: network list to attach on container
     + ports: port list to expose
     + volumes: volume list to map on container
-    + env_vars: environment varible list to inject on container
+    + env_vars: environment variable list to inject on container
     + pull_always: force image pull
-    + force: remove a contaner with same name and create a new one
+    + force: remove a container with same name and create a new one
     + present: whether the container should be up and running
     + start: start or stop the container
 
@@ -68,56 +70,60 @@ def container(
         )
     """
 
+    want_spec = ContainerSpec(
+        image,
+        ports or list(),
+        networks or list(),
+        volumes or list(),
+        env_vars or list(),
+        pull_always,
+    )
     existent_container = host.get_fact(DockerContainer, object_id=container)
 
-    if force:
-        if existent_container:
-            yield handle_docker(
-                resource="container",
-                command="remove",
-                container=container,
-            )
+    container_spec_changes = want_spec.diff_from_inspect(existent_container)
 
-    if present:
-        if not existent_container or force:
-            yield handle_docker(
-                resource="container",
-                command="create",
-                container=container,
-                image=image,
-                ports=ports,
-                networks=networks,
-                volumes=volumes,
-                env_vars=env_vars,
-                pull_always=pull_always,
-                present=present,
-                force=force,
-                start=start,
-            )
-
-    if existent_container and start:
-        if existent_container[0]["State"]["Status"] != "running":
-            yield handle_docker(
-                resource="container",
-                command="start",
-                container=container,
-            )
-
-    if existent_container and not start:
-        if existent_container[0]["State"]["Status"] == "running":
-            yield handle_docker(
-                resource="container",
-                command="stop",
-                container=container,
-            )
-
-    if existent_container and not present:
+    is_running = (
+        (existent_container[0]["State"]["Status"] == "running")
+        if existent_container and existent_container[0]
+        else False
+    )
+    recreating = existent_container and (force or container_spec_changes)
+    removing = existent_container and not present
+
+    do_remove = recreating or removing
+    do_create = (present and not existent_container) or recreating
+    do_start = start and (recreating or not is_running)
+    do_stop = not start and not removing and is_running
+
+    if do_remove:
         yield handle_docker(
             resource="container",
             command="remove",
             container=container,
         )
 
+    if do_create:
+        yield handle_docker(
+            resource="container",
+            command="create",
+            container=container,
+            spec=want_spec,
+        )
+
+    if do_start:
+        yield handle_docker(
+            resource="container",
+            command="start",
+            container=container,
+        )
+
+    if do_stop:
+        yield handle_docker(
+            resource="container",
+            command="stop",
+            container=container,
+        )
+
 
 @operation(is_idempotent=False)
 def image(image, present=True):
@@ -125,7 +131,7 @@ def image(image, present=True):
     Manage Docker images
 
     + image: Image and tag ex: nginx:alpine
-    + present: whether the Docker image should be exist
+    + present: whether the Docker image should exist
 
     **Examples:**
 
@@ -188,7 +194,7 @@ def volume(volume, driver="", labels=None, present=True):
     if present:
 
         if existent_volume:
-            host.noop("Volume alredy exist!")
+            host.noop("Volume already exists!")
             return
 
         yield handle_docker(
@@ -231,8 +237,8 @@ def network(
     """
     Manage docker networks
 
-    + network_name: Image name
-    + driver: Container image and tag ex: nginx:alpine
+    + network: Network name
+    + driver: Network driver ex: bridge or overlay
     + gateway: IPv4 or IPv6 Gateway for the master subnet
     + ip_range: Allocate container ip from a sub-range
     + ipam_driver: IP Address Management Driver
@@ -251,8 +257,7 @@ def network(
 
         # Create Docker network
         docker.network(
-            name="Create nginx network",
-            network_name="nginx",
+            network="nginx",
             attachable=True,
             present=True,
         )
@@ -261,7 +266,7 @@ def network(
 
     if present:
         if existent_network:
-            host.noop("Alredy exist a network with {0} name!".format(network))
+            host.noop("Network {0} already exists!".format(network))
             return
 
         yield handle_docker(
@@ -284,12 +289,12 @@ def network(
 
     else:
         if existent_network is None:
-            host.noop("Ther is not network with {0} name!".format(network))
+            host.noop("Network {0} does not exist!".format(network))
             return
 
         yield handle_docker(
             resource="network",
-            command="create",
+            command="remove",
             network=network,
         )
 
@@ -297,7 +302,7 @@ def network(
 @operation(is_idempotent=False)
 def prune(
     all=False,
-    volume=False,
+    volumes=False,
     filter="",
 ):
     """
@@ -334,6 +339,6 @@ def prune(
         resource="system",
         command="prune",
         all=all,
-        volume=volume,
+        volumes=volumes,
         filter=filter,
     )

pyinfra/operations/files.py

@@ -51,6 +51,7 @@ from pyinfra.facts.files import (
     Md5File,
     Sha1File,
     Sha256File,
+    Sha384File,
 )
 from pyinfra.facts.server import Date, Which
 
@@ -67,6 +68,7 @@ def download(
     mode: str | None = None,
     cache_time: int | None = None,
     force=False,
+    sha384sum: str | None = None,
     sha256sum: str | None = None,
     sha1sum: str | None = None,
     md5sum: str | None = None,
@@ -84,6 +86,7 @@ def download(
     + mode: permissions of the files
     + cache_time: if the file exists already, re-download after this time (in seconds)
     + force: always download the file, even if it already exists
+    + sha384sum: sha384 hash to checksum the downloaded file against
     + sha256sum: sha256 hash to checksum the downloaded file against
     + sha1sum: sha1 hash to checksum the downloaded file against
     + md5sum: md5 hash to checksum the downloaded file against
@@ -135,6 +138,10 @@ def download(
             if sha256sum != host.get_fact(Sha256File, path=dest):
                 download = True
 
+        if sha384sum:
+            if sha384sum != host.get_fact(Sha384File, path=dest):
+                download = True
+
         if md5sum:
             if md5sum != host.get_fact(Md5File, path=dest):
                 download = True
@@ -211,6 +218,17 @@ def download(
                 QuoteString("SHA256 did not match!"),
             )
 
+        if sha384sum:
+            yield make_formatted_string_command(
+                (
+                    "(( sha384sum {0} 2> /dev/null || shasum -a 384 {0} ) "
+                    "| grep {1}) || ( echo {2} && exit 1 )"
+                ),
+                QuoteString(dest),
+                sha384sum,
+                QuoteString("SHA384 did not match!"),
+            )
+
         if md5sum:
             yield make_formatted_string_command(
                 (
@@ -647,7 +665,7 @@ def sync(
 
 
 @memoize
-def show_rsync_warning():
+def show_rsync_warning() -> None:
     logger.warning("The `files.rsync` operation is in alpha!")
 
 
@@ -940,6 +958,9 @@ def template(
         a dict with arguments that will be passed as keyword args to the jinja2
         `Environment() <https://jinja.palletsprojects.com/en/3.0.x/api/#jinja2.Environment>`_.
 
+    The ``host``, ``state``, and ``inventory`` objects will be automatically passed to the 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).
@@ -997,6 +1018,21 @@ def template(
             foo_dict=foo_dict,
             foo_list=foo_list
         )
+
+        # Example showing how to use host and inventory in a template file.
+        template = StringIO("""
+        name: "{{ host.name }}"
+        list_contents:
+        {% for entry in inventory.groups.my_servers %}
+            - "{{ entry }}"
+        {% endfor %}
+        """)
+
+        files.template(
+            name="Create a templated file",
+            src=template,
+            dest="/tmp/foo.yml"
+        )
     '''
 
     if not hasattr(src, "read") and state.cwd:
@@ -1051,6 +1087,34 @@ def template(
     )
 
 
+@operation()
+def move(src: str, dest: str, overwrite=False):
+    """
+    Move remote file/directory/link into remote directory
+
+    + src: remote file/directory to move
+    + dest: remote directory to move `src` into
+    + overwrite: whether to overwrite dest, if present
+    """
+
+    if host.get_fact(File, src) is None:
+        raise OperationError("src {0} does not exist".format(src))
+
+    if not host.get_fact(Directory, dest):
+        raise OperationError("dest {0} is not an existing directory".format(dest))
+
+    full_dest_path = os.path.join(dest, os.path.basename(src))
+    if host.get_fact(File, full_dest_path) is not None:
+        if overwrite:
+            yield StringCommand("rm", "-rf", QuoteString(full_dest_path))
+        else:
+            raise OperationError(
+                "dest {0} already exists and `overwrite` is unset".format(full_dest_path)
+            )
+
+    yield StringCommand("mv", QuoteString(src), QuoteString(dest))
+
+
 def _validate_path(path):
     try:
         return os.fspath(path)

pyinfra/operations/freebsd/__init__.py

@@ -0,0 +1,12 @@
+# This file only exists to support:
+# from pyinfra.operations import freebsd
+# freebsd.X.Y
+
+from glob import glob
+from os import path
+
+module_filenames = glob(path.join(path.dirname(__file__), "*.py"))
+module_names = [path.basename(name)[:-3] for name in module_filenames]
+__all__ = [name for name in module_names if name != "__init__"]
+
+from . import *  # noqa

pyinfra/operations/freebsd/freebsd_update.py

@@ -0,0 +1,70 @@
+"""
+Fetch and install binary updates to FreeBSD.
+"""
+
+from __future__ import annotations
+
+from typing_extensions import List, Optional, Union
+
+from pyinfra.api import QuoteString, StringCommand, operation
+
+
+@operation()
+def update(
+    force: bool = False,
+    basedir: Optional[str] = None,
+    workdir: Optional[str] = None,
+    conffile: Optional[str] = None,
+    jail: Optional[str] = None,
+    key: Optional[str] = None,
+    currently_running: Optional[str] = None,
+    server: Optional[str] = None,
+):
+    """
+    Based on the currently installed world and the configuration options set, fetch
+    all available binary updates and install them.
+
+    + force: See ``-F`` in ``freebsd-update(8)``.
+    + basedir: See ``-b`` in ``freebsd-update(8)``.
+    + workdir: See ``-d`` in ``freebsd-update(8)``.
+    + conffile: See ``-f`` in ``freebsd-update(8)``.
+    + jail: See ``-j`` in ``freebsd-update(8)``.
+    + key: See ``-k`` in ``freebsd-update(8)``.
+    + currently_running: See ``--currently-running`` in ``freebsd-update(8)``.
+    + server: See ``-s`` in ``freebsd-update(8)``.
+
+    **Example:**
+
+    .. code:: python
+
+        freebsd_update.update()
+    """
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.extend(["PAGER=cat", "freebsd-update", "--not-running-from-cron"])
+
+    if force:
+        args.append("-F")
+
+    if basedir is not None:
+        args.extend(["-b", QuoteString(basedir)])
+
+    if workdir is not None:
+        args.extend(["-d", QuoteString(workdir)])
+
+    if conffile is not None:
+        args.extend(["-f", QuoteString(conffile)])
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    if key is not None:
+        args.extend(["-k", QuoteString(key)])
+
+    if server is not None:
+        args.extend(["-s", QuoteString(server)])
+
+    args.extend(["fetch", "install"])
+
+    yield StringCommand(*args)

pyinfra/operations/freebsd/pkg.py

@@ -0,0 +1,219 @@
+"""
+Manage FreeBSD packages.
+"""
+
+from __future__ import annotations
+
+from typing_extensions import List, Optional, Union
+
+from pyinfra import host
+from pyinfra.api import QuoteString, StringCommand, operation
+from pyinfra.facts.freebsd import PkgPackage
+
+
+@operation()
+def update(jail: Optional[str] = None, force: bool = False, reponame: Optional[str] = None):
+    """
+    Update the local catalogues of the enabled package repositories.
+
+    + jail: See ``-j`` in ``pkg(8)``.
+    + force: See ``-f`` in ``pkg-update(8)``.
+    + reponame: See ``-r`` in ``pkg-update(8)``
+
+    **Examples:**
+
+    .. code:: python
+
+        # host
+        pkg.update()
+
+        # jail
+        pkg.update(
+            jail="nginx"
+        )
+    """
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.append("pkg")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    args.extend(["update"])
+
+    if force:
+        args.append("-f")
+
+    if reponame is not None:
+        args.extend(["-r", QuoteString(reponame)])
+
+    yield StringCommand(*args)
+
+
+@operation()
+def upgrade(jail: Optional[str] = None, force: bool = False, reponame: Optional[str] = None):
+    """
+    Perform upgrades of package software distributions.
+
+    + jail: See ``-j`` in ``pkg(8)``.
+    + force: See ``-f`` in ``pkg-upgrade(8)``.
+    + reponame: See ``-r`` in ``pkg-upgrade(8)``.
+
+    **Examples:**
+
+    .. code:: python
+
+        # host
+        pkg.upgrade()
+
+        # jail
+        pkg.upgrade(
+            jail="nginx"
+        )
+    """
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.append("pkg")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    args.extend(["upgrade", "-y"])
+
+    if force:
+        args.append("-f")
+
+    if reponame is not None:
+        args.extend(["-r", QuoteString(reponame)])
+
+    yield StringCommand(*args)
+
+
+@operation()
+def install(package: str, jail: Optional[str] = None, reponame: Optional[str] = None):
+    """
+    Install packages from remote packages repositories or local archives.
+
+    + package: Package to install.
+    + jail: See ``-j`` in ``pkg(8)``.
+    + reponame: See ``-r`` in ``pkg-install(8)``.
+
+    **Example:**
+
+    .. code:: python
+
+        pkg.install("nginx")
+    """
+
+    if host.get_fact(PkgPackage, package=package, jail=jail):
+        host.noop(f"Package '{package}' already installed")
+        return
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.append("pkg")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    args.extend(["install", "-y"])
+
+    if reponame is not None:
+        args.extend(["-r", QuoteString(reponame)])
+
+    args.extend(["--", QuoteString(package)])
+
+    yield StringCommand(*args)
+
+
+@operation()
+def remove(package: str, jail: Optional[str] = None):
+    """
+    Deletes packages from the database and the system.
+
+    + package: Package to remove.
+    + jail: See ``-j`` in ``pkg(8)``.
+
+    **Example:**
+
+    .. code:: python
+
+        pkg.remove("nginx")
+    """
+
+    if not host.get_fact(PkgPackage, package=package, jail=jail):
+        host.noop(f"Package '{package}' cannot be found")
+        return
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.append("pkg")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    args.extend(["remove", "-y"])
+
+    args.extend(["--", QuoteString(package)])
+
+    yield StringCommand(*args)
+
+
+@operation()
+def autoremove(jail: Optional[str] = None):
+    """
+    Remove orphan packages.
+
+    + jail: See ``-j`` in ``pkg(8)``.
+
+    **Example:**
+
+    .. code:: python
+
+        pkg.autoremove()
+    """
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.append("pkg")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    args.extend(["autoremove", "-y"])
+
+    yield StringCommand(*args)
+
+
+@operation()
+def clean(all_pkg: bool = False, jail: Optional[str] = None):
+    """
+    Clean the local cache of fetched remote packages.
+
+    + all_pkg: See ``-a`` in ``pkg-clean(8)``.
+    + jail: See ``-j`` in ``pkg(8)``.
+
+    **Example:**
+
+    .. code:: python
+
+        pkg.clean(
+            all_pkg=True
+        )
+    """
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.append("pkg")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    args.extend(["clean", "-y"])
+
+    if all_pkg:
+        args.append("-a")
+
+    yield StringCommand(*args)