pyinfra 3.0b1__py2.py3-none-any.whl → 3.0b3__py2.py3-none-any.whl

pyinfra/operations/docker.py

@@ -0,0 +1,339 @@
+"""
+Manager Docker Containers, Volumes and Networks
+"""
+
+from pyinfra import host
+from pyinfra.api import operation
+from pyinfra.facts.docker import DockerContainers, DockerNetworks, DockerVolumes
+
+from .util.docker import handle_docker
+
+
+@operation()
+def container(
+    container,
+    image="",
+    ports=None,
+    networks=None,
+    volumes=None,
+    env_vars=None,
+    pull_always=False,
+    present=True,
+    force=False,
+    start=True,
+):
+    """
+    Manage Docker containers
+
+    + container: name to identify the container
+    + image: container image and tag ex: nginx:alpine
+    + 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
+    + pull_always: force image pull
+    + force: remove a contaner with same name and create a new one
+    + present: whether the container should be up and running
+    + start: start or stop the container
+
+    **Examples:**
+
+    .. code:: python
+
+        # Run a container
+        docker.container(
+            name="Deploy Nginx container",
+            container="nginx",
+            image="nginx:alpine",
+            ports=["80:80"],
+            present=True,
+            force=True,
+            networks=["proxy", "services"],
+            volumes=["nginx_data:/usr/share/nginx/html"],
+            pull_always=True,
+        )
+
+        # Stop a container
+        docker.container(
+            name="Stop Nginx container",
+            container="nginx",
+            start=False,
+        )
+
+        # Start a container
+        docker.container(
+            name="Start Nginx container",
+            container="nginx",
+            start=True,
+        )
+    """
+
+    existent_container = [c for c in host.get_fact(DockerContainers) if container in c["Name"]]
+
+    if force:
+        if existent_container:
+            yield handle_docker(
+                resource="container",
+                command="remove",
+                container=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:
+        yield handle_docker(
+            resource="container",
+            command="remove",
+            container=container,
+        )
+
+
+@operation(is_idempotent=False)
+def image(image, present=True):
+    """
+    Manage Docker images
+
+    + image: Image and tag ex: nginx:alpine
+    + present: whether the Docker image should be exist
+
+    **Examples:**
+
+    .. code:: python
+
+        # Pull a Docker image
+        docker.image(
+            name="Pull nginx image",
+            image="nginx:alpine",
+            present=True,
+        )
+
+        # Remove a Docker image
+        docker.image(
+            name="Remove nginx image",
+            image:"nginx:image",
+            present=False,
+        )
+    """
+
+    if present:
+        yield handle_docker(
+            resource="image",
+            command="pull",
+            image=image,
+        )
+
+    else:
+        yield handle_docker(
+            resource="image",
+            command="remove",
+            image=image,
+        )
+
+
+@operation()
+def volume(volume, driver="", labels=None, present=True):
+    """
+    Manage Docker volumes
+
+    + volume: Volume name
+    + driver: Docker volume storage driver
+    + labels: Label list to attach in the volume
+    + present: whether the Docker volume should exist
+
+    **Examples:**
+
+    .. code:: python
+
+        # Create a Docker volume
+        docker.volume(
+            name="Create nginx volume",
+            volume="nginx_data",
+            present=True
+        )
+    """
+
+    existent_volume = [v for v in host.get_fact(DockerVolumes) if v["Name"] == volume]
+
+    if present:
+
+        if existent_volume:
+            host.noop("Volume alredy exist!")
+            return
+
+        yield handle_docker(
+            resource="volume",
+            command="create",
+            volume=volume,
+            driver=driver,
+            labels=labels,
+            present=present,
+        )
+
+    else:
+        if existent_volume is None:
+            host.noop("There is no {0} volume!".format(volume))
+            return
+
+        yield handle_docker(
+            resource="volume",
+            command="remove",
+            volume=volume,
+        )
+
+
+@operation()
+def network(
+    network,
+    driver="",
+    gateway="",
+    ip_range="",
+    ipam_driver="",
+    subnet="",
+    scope="",
+    opts=None,
+    ipam_opts=None,
+    labels=None,
+    ingress=False,
+    attachable=False,
+    present=True,
+):
+    """
+    Manage docker networks
+
+    + network_name: Image name
+    + driver: Container image and tag ex: nginx:alpine
+    + gateway: IPv4 or IPv6 Gateway for the master subnet
+    + ip_range: Allocate container ip from a sub-range
+    + ipam_driver: IP Address Management Driver
+    + subnet: Subnet in CIDR format that represents a network segment
+    + scope: Control the network's scope
+    + opts: Set driver specific options
+    + ipam_opts: Set IPAM driver specific options
+    + labels: Label list to attach in the network
+    + ingress: Create swarm routing-mesh network
+    + attachable: Enable manual container attachment
+    + present: whether the Docker network should exist
+
+    **Examples:**
+
+    .. code:: python
+
+        # Create Docker network
+        docker.network(
+            name="Create nginx network",
+            network_name="nginx",
+            attachable=True,
+            present=True,
+        )
+    """
+    existent_network = [n for n in host.get_fact(DockerNetworks) if n["Name"] == network]
+
+    if present:
+        if existent_network:
+            host.noop("Alredy exist a network with {0} name!".format(network))
+            return
+
+        yield handle_docker(
+            resource="network",
+            command="create",
+            network=network,
+            driver=driver,
+            gateway=gateway,
+            ip_range=ip_range,
+            ipam_driver=ipam_driver,
+            subnet=subnet,
+            scope=scope,
+            opts=opts,
+            ipam_opts=ipam_opts,
+            labels=labels,
+            ingress=ingress,
+            attachable=attachable,
+            present=present,
+        )
+
+    else:
+        if existent_network is None:
+            host.noop("Ther is not network with {0} name!".format(network))
+            return
+
+        yield handle_docker(
+            resource="network",
+            command="create",
+            network=network,
+        )
+
+
+@operation(is_idempotent=False)
+def prune(
+    all=False,
+    volume=False,
+    filter="",
+):
+    """
+    Execute a docker system prune.
+
+    + all: Remove all unused images not just dangling ones
+    + volumes: Prune anonymous volumes
+    + filter: Provide filter values (e.g. "label=<key>=<value>" or "until=24h")
+
+    **Examples:**
+
+    .. code:: python
+
+        # Remove dangling images
+        docker.prune(
+            name="remove dangling images",
+        )
+
+        # Remove all images and volumes
+        docker.prune(
+            name="Remove all images and volumes",
+            all=True,
+            volumes=True,
+        )
+
+        # Remove images older than 90 days
+        docker.prune(
+            name="Remove unused older than 90 days",
+            filter="until=2160h"
+        )
+    """
+
+    yield handle_docker(
+        resource="system",
+        command="prune",
+        all=all,
+        volume=volume,
+        filter=filter,
+    )

pyinfra/operations/files.py

@@ -12,7 +12,7 @@ from datetime import timedelta
 from fnmatch import fnmatch
 from io import StringIO
 from pathlib import Path
-from typing import Union
+from typing import IO, Any, Union
 
 from jinja2 import TemplateRuntimeError, TemplateSyntaxError, UndefinedError
 
@@ -60,19 +60,19 @@ from .util.files import adjust_regex, ensure_mode_int, get_timestamp, sed_replac
 
 @operation()
 def download(
-    src,
-    dest,
-    user=None,
-    group=None,
-    mode=None,
-    cache_time=None,
+    src: str,
+    dest: str,
+    user: str | None = None,
+    group: str | None = None,
+    mode: str | None = None,
+    cache_time: int | None = None,
     force=False,
-    sha256sum=None,
-    sha1sum=None,
-    md5sum=None,
-    headers=None,
+    sha256sum: str | None = None,
+    sha1sum: str | None = None,
+    md5sum: str | None = None,
+    headers: dict[str, str] | None = None,
     insecure=False,
-    proxy=None,
+    proxy: str | None = None,
 ):
     """
     Download files from remote locations using ``curl`` or ``wget``.
@@ -123,8 +123,8 @@ def download(
         if cache_time:
             # Time on files is not tz-aware, and will be the same tz as the server's time,
             # so we can safely remove the tzinfo from the Date fact before comparison.
-            cache_time = host.get_fact(Date).replace(tzinfo=None) - timedelta(seconds=cache_time)
-            if info["mtime"] and info["mtime"] < cache_time:
+            ctime = host.get_fact(Date).replace(tzinfo=None) - timedelta(seconds=cache_time)
+            if info["mtime"] and info["mtime"] < ctime:
                 download = True
 
         if sha1sum:
@@ -227,11 +227,11 @@ def download(
 
 @operation()
 def line(
-    path,
-    line,
+    path: str,
+    line: str,
     present=True,
-    replace=None,
-    flags=None,
+    replace: str | None = None,
+    flags: list[str] | None = None,
     backup=False,
     interpolate_variables=False,
     escape_regex_characters=False,
@@ -269,7 +269,7 @@ def line(
         it will be append to the end of the file.
 
     Ensure new line:
-        This will ensure that the ``line`` being appended is always on a seperate new
+        This will ensure that the ``line`` being appended is always on a separate new
         line in case the file doesn't end with a newline character.
 
 
@@ -427,10 +427,10 @@ def line(
 
 @operation()
 def replace(
-    path,
-    text=None,
-    replace=None,
-    flags=None,
+    path: str,
+    text: str | None = None,
+    replace: str | None = None,
+    flags: list[str] | None = None,
     backup=False,
     interpolate_variables=False,
     match=None,  # deprecated
@@ -501,15 +501,15 @@ def replace(
 
 @operation()
 def sync(
-    src,
-    dest,
-    user=None,
-    group=None,
-    mode=None,
-    dir_mode=None,
+    src: str,
+    dest: str,
+    user: str | None = None,
+    group: str | None = None,
+    mode: str | None = None,
+    dir_mode: str | None = None,
     delete=False,
-    exclude=None,
-    exclude_dir=None,
+    exclude: str | list[str] | tuple[str] | None = None,
+    exclude_dir: str | list[str] | tuple[str] | None = None,
     add_deploy_dir=True,
 ):
     """
@@ -652,7 +652,7 @@ def show_rsync_warning():
 
 
 @operation(is_idempotent=False)
-def rsync(src, dest, flags=["-ax", "--delete"]):
+def rsync(src: str, dest: str, flags: list[str] | None = None):
     """
     Use ``rsync`` to sync a local directory to the remote system. This operation will actually call
     the ``rsync`` binary on your system.
@@ -667,6 +667,8 @@ def rsync(src, dest, flags=["-ax", "--delete"]):
         global arguments.
     """
 
+    if flags is None:
+        flags = ["-ax", "--delete"]
     show_rsync_warning()
 
     try:
@@ -696,8 +698,8 @@ def _create_remote_dir(remote_filename, user, group):
     is_idempotent=False,
 )
 def get(
-    src,
-    dest,
+    src: str,
+    dest: str,
     add_deploy_dir=True,
     create_local_dir=False,
     force=False,
@@ -756,11 +758,11 @@ def get(
 
 @operation()
 def put(
-    src,
-    dest,
-    user=None,
-    group=None,
-    mode=None,
+    src: str | IO[Any],
+    dest: str,
+    user: str | None = None,
+    group: str | None = None,
+    mode: int | str | bool | None = None,
     add_deploy_dir=True,
     create_remote_dir=True,
     force=False,
@@ -821,6 +823,7 @@ def put(
 
     # Assume string filename
     else:
+        assert isinstance(src, (str, Path))
         # Add deploy directory?
         if add_deploy_dir and state.cwd:
             src = os.path.join(state.cwd, src)
@@ -835,7 +838,7 @@ def put(
             raise IOError("No such file: {0}".format(local_file))
 
     if mode is True:
-        if os.path.isfile(local_file):
+        if isinstance(local_file, str) and os.path.isfile(local_file):
             mode = get_path_permissions_mode(local_file)
         else:
             logger.warning(
@@ -849,6 +852,7 @@ def put(
     remote_file = host.get_fact(File, path=dest)
 
     if not remote_file and bool(host.get_fact(Directory, path=dest)):
+        assert isinstance(src, str)
         dest = unix_path_join(dest, os.path.basename(src))
         remote_file = host.get_fact(File, path=dest)
 
@@ -905,7 +909,15 @@ def put(
 
 
 @operation()
-def template(src, dest, user=None, group=None, mode=None, create_remote_dir=True, **data):
+def template(
+    src: str | IO[Any],
+    dest: str,
+    user: str | None = None,
+    group: str | None = None,
+    mode: str | None = None,
+    create_remote_dir=True,
+    **data,
+):
     '''
     Generate a template using jinja2 and write it to the remote system.
 
@@ -1055,16 +1067,16 @@ def _raise_or_remove_invalid_path(fs_type, path, force, force_backup, force_back
 
 @operation()
 def link(
-    path,
-    target=None,
+    path: str,
+    target: str | None = None,
     present=True,
-    user=None,
-    group=None,
+    user: str | None = None,
+    group: str | None = None,
     symbolic=True,
     create_remote_dir=True,
     force=False,
     force_backup=True,
-    force_backup_dir=None,
+    force_backup_dir: str | None = None,
 ):
     """
     Add/remove/update links.
@@ -1162,16 +1174,16 @@ def link(
 
 @operation()
 def file(
-    path,
+    path: str,
     present=True,
-    user=None,
-    group=None,
-    mode=None,
+    user: str | None = None,
+    group: str | None = None,
+    mode: int | str | None = None,
     touch=False,
     create_remote_dir=True,
     force=False,
     force_backup=True,
-    force_backup_dir=None,
+    force_backup_dir: str | None = None,
 ):
     """
     Add/remove/update files.
@@ -1264,15 +1276,15 @@ def file(
 
 @operation()
 def directory(
-    path,
+    path: str,
     present=True,
-    user=None,
-    group=None,
-    mode=None,
+    user: str | None = None,
+    group: str | None = None,
+    mode: int | str | None = None,
     recursive=False,
     force=False,
     force_backup=True,
-    force_backup_dir=None,
+    force_backup_dir: str | None = None,
     _no_check_owner_mode=False,
     _no_fail_on_link=False,
 ):
@@ -1365,7 +1377,7 @@ def directory(
 
 
 @operation()
-def flags(path, flags=None, present=True):
+def flags(path: str, flags: list[str] | None = None, present=True):
     """
     Set/clear file flags.
 
@@ -1414,18 +1426,18 @@ def flags(path, flags=None, present=True):
 
 @operation()
 def block(
-    path,
-    content=None,
+    path: str,
+    content: str | list[str] | None = None,
     present=True,
-    line=None,
+    line: str | None = None,
     backup=False,
     escape_regex_characters=False,
     try_prevent_shell_expansion=False,
     before=False,
     after=False,
-    marker=None,
-    begin=None,
-    end=None,
+    marker: str | None = None,
+    begin: str | None = None,
+    end: str | None = None,
 ):
     """
     Ensure content, surrounded by the appropriate markers, is present (or not) in the file.
@@ -1573,6 +1585,7 @@ def block(
                 f"\n{the_block}\n{here}",
             )
         elif current == []:  # markers not found and have a pattern to match (not start or end)
+            assert isinstance(line, str)
             regex = adjust_regex(line, escape_regex_characters)
             print_before = "{ print }" if before else ""
             print_after = "{ print }" if after else ""
@@ -1601,9 +1614,11 @@ def block(
                     out_prep,
                     prog,
                     q_path,
-                    '"' + "\n".join(content) + '"'
-                    if not try_prevent_shell_expansion
-                    else "'" + "\n".join(content) + "'",
+                    (
+                        '"' + "\n".join(content) + '"'
+                        if not try_prevent_shell_expansion
+                        else "'" + "\n".join(content) + "'"
+                    ),
                     "> $OUT &&",
                     real_out,
                 )

pyinfra/operations/gem.py

@@ -2,6 +2,8 @@
 Manage Ruby gem packages. (see https://rubygems.org/ )
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.gem import GemPackages
@@ -10,7 +12,7 @@ from .util.packaging import ensure_packages
 
 
 @operation()
-def packages(packages=None, present=True, latest=False):
+def packages(packages: str | list[str] | None = None, present=True, latest=False):
     """
     Add/remove/update gem packages.