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

pyinfra/operations/docker.py

@@ -8,7 +8,7 @@ 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()
@@ -70,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):
@@ -298,7 +302,7 @@ def network(
 @operation(is_idempotent=False)
 def prune(
     all=False,
-    volume=False,
+    volumes=False,
     filter="",
 ):
     """
@@ -335,6 +339,6 @@ def prune(
         resource="system",
         command="prune",
         all=all,
-        volume=volume,
+        volumes=volumes,
         filter=filter,
     )

pyinfra/operations/files.py

@@ -665,7 +665,7 @@ def sync(
 
 
 @memoize
-def show_rsync_warning():
+def show_rsync_warning() -> None:
     logger.warning("The `files.rsync` operation is in alpha!")
 
 
@@ -958,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).
@@ -1015,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:
@@ -1069,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)

pyinfra/operations/freebsd/service.py

@@ -0,0 +1,116 @@
+"""
+Manage FreeBSD services.
+"""
+
+from __future__ import annotations
+
+from typing_extensions import List, Optional, Union
+
+from pyinfra import host
+from pyinfra.api import QuoteString, StringCommand, operation
+from pyinfra.api.exceptions import OperationValueError
+from pyinfra.facts.freebsd import ServiceScript, ServiceStatus
+
+SRV_STARTED: str = "started"
+SRV_STOPPED: str = "stopped"
+SRV_RESTARTED: str = "restarted"
+SRV_RELOADED: str = "reloaded"
+SRV_CUSTOM: str = "custom"
+
+
+@operation()
+def service(
+    srvname: str,
+    jail: Optional[str] = None,
+    srvstate: str = SRV_STARTED,
+    command: Optional[Union[str, List[str]]] = None,
+    environment: Optional[List[str]] = None,
+    verbose: bool = False,
+):
+    """
+    Control (start/stop/etc.) ``rc(8)`` scripts.
+
+    + srvname: Service.
+    + jail: See ``-j`` in ``service(8)``.
+    + srvstate: Desire state of the service.
+    + command: When ``srvstate`` is ``custom``, the command to execute.
+    + environment: See ``-E`` in ``service(8)``.
+    + verbose: See ``-v`` in ``service(8)``.
+
+    States:
+        There are a few states you can use to manipulate the service:
+
+        - started: The service must be started.
+        - stopped: The service must be stopped.
+        - restarted: The service must be restarted.
+        - reloaded: The service must be reloaded.
+        - custom: Run a custom command for this service.
+
+    **Examples:**
+
+    .. code:: python
+
+        # Start a service.
+        service.service(
+            "beanstalkd",
+            srvstate="started"
+        )
+
+        # Execute a custom command.
+        service.service(
+            "sopel",
+            srvstate="custom",
+            command="configure"
+        )
+    """
+
+    if not host.get_fact(ServiceScript, srvname=srvname, jail=jail):
+        host.noop(f"Cannot find rc(8) script '{srvname}'")
+        return
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.append("service")
+
+    if verbose:
+        args.append("-v")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    if environment is not None:
+        for env_var in environment:
+            args.extend(["-E", QuoteString(env_var)])
+
+    if srvstate == SRV_STARTED:
+        if host.get_fact(ServiceStatus, srvname=srvname, jail=jail):
+            host.noop(f"Service '{srvname}' already started")
+            return
+
+        args.extend([QuoteString(srvname), "start"])
+
+    elif srvstate == SRV_STOPPED:
+        if not host.get_fact(ServiceStatus, srvname=srvname, jail=jail):
+            host.noop(f"Service '{srvname}' already stopped")
+            return
+
+        args.extend([QuoteString(srvname), "stop"])
+    elif srvstate == SRV_RESTARTED:
+        args.extend([QuoteString(srvname), "restart"])
+
+    elif srvstate == SRV_RELOADED:
+        args.extend([QuoteString(srvname), "reload"])
+
+    elif srvstate == SRV_CUSTOM:
+        args.append(QuoteString(srvname))
+
+        if command is not None:
+            if isinstance(command, str):
+                command = [command]
+
+            args.extend([QuoteString(c) for c in command])
+
+    else:
+        raise OperationValueError(f"Invalid service command: {srvstate}")
+
+    yield StringCommand(*args)

pyinfra/operations/freebsd/sysrc.py

@@ -0,0 +1,92 @@
+"""
+Manipulate system rc files.
+"""
+
+from __future__ import annotations
+
+from typing_extensions import List, Optional, Union
+
+from pyinfra import host
+from pyinfra.api import QuoteString, StringCommand, operation
+from pyinfra.api.exceptions import OperationValueError
+from pyinfra.facts.freebsd import Sysrc
+
+SYSRC_ADD: str = "add"
+SYSRC_SUB: str = "sub"
+SYSRC_SET: str = "set"
+SYSRC_DEL: str = "del"
+
+
+@operation()
+def sysrc(
+    parameter: str,
+    value: str,
+    jail: Optional[str] = None,
+    command: str = SYSRC_SET,
+    overwrite: bool = False,
+):
+    """
+    Safely edit system rc files.
+
+    + parameter: Parameter to manipulate.
+    + value: Value, if the parameter requires it.
+    + jail: See ``-j`` in ``sysrc(8)``.
+    + command: Desire state of the parameter.
+    + overwrite: Overwrite the value of the parameter when ``command`` is set to ``set``.
+
+    Commands:
+        There are a few commands you can use to manipulate the rc file:
+
+        - add: Adds the value to the parameter.
+        - sub: Delete the parameter value.
+        - set: Change the parameter value. If the parameter already has a value
+               set, the changes will not be applied unless ``overwrite`` is set
+               to ``True``.
+        - del: Delete the parameter.
+
+    **Example:**
+
+    .. code:: python
+
+        sysrc.sysrc(
+            "beanstalkd_enable",
+            "YES",
+            command="set"
+        )
+    """
+
+    args: List[Union[str, "QuoteString"]] = []
+
+    args.extend(["sysrc", "-i"])
+
+    if command == SYSRC_DEL:
+        sign = "="
+
+        if not host.get_fact(Sysrc, parameter=parameter, jail=jail):
+            host.noop(f"Cannot find sysrc(8) parameter '{parameter}'")
+            return
+
+        args.append("-x")
+
+    elif command == SYSRC_SET:
+        sign = "="
+
+        if not overwrite and host.get_fact(Sysrc, parameter=parameter, jail=jail):
+            host.noop(f"sysrc(8) parameter '{parameter}' already set")
+            return
+
+    elif command == SYSRC_ADD:
+        sign = "+="
+
+    elif command == SYSRC_SUB:
+        sign = "-="
+
+    else:
+        raise OperationValueError(f"Invalid sysrc command: {command}")
+
+    if jail is not None:
+        args.extend(["-j", QuoteString(jail)])
+
+    args.extend(["--", QuoteString(f"{parameter}{sign}{value}")])
+
+    yield StringCommand(*args)