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

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(
                 (
@@ -256,7 +274,7 @@ def line(
         change bits of lines, see ``files.replace``.
 
     Regex line escaping:
-        If matching special characters (eg a crontab line containing *), remember to escape
+        If matching special characters (eg a crontab line containing ``*``), remember to escape
         it first using Python's ``re.escape``.
 
     Backup:
@@ -523,7 +541,7 @@ def sync(
     + mode: permissions of the files
     + dir_mode: permissions of the directories
     + delete: delete remote files not present locally
-    + exclude: string or list/tuple of strings to match & exclude files (eg *.pyc)
+    + exclude: string or list/tuple of strings to match & exclude files (eg ``*.pyc``)
     + exclude_dir: string or list/tuple of strings to match & exclude directories (eg node_modules)
     + add_deploy_dir: interpret src as relative to deploy directory instead of current directory
 

pyinfra/operations/git.py

@@ -16,24 +16,40 @@ from .util.files import chown, unix_path_join
 
 
 @operation()
-def config(key: str, value: str, multi_value=False, repo: str | None = None):
+def config(key: str, value: str, multi_value=False, repo: str | None = None, system=False):
     """
-    Manage git config for a repository or globally.
+    Manage git config at repository, user or system level.
 
     + key: the key of the config to ensure
     + value: the value this key should have
     + multi_value: Add the value rather than set it for settings that can have multiple values
     + repo: specify the git repo path to edit local config (defaults to global)
+    + system: whether, when ``repo`` is unspecified, to work at system level (or default to global)
 
-    **Example:**
+    **Examples:**
 
     .. code:: python
 
         git.config(
-            name="Ensure user name is set for a repo",
+            name="Always prune specified repo",
+            key="fetch.prune",
+            value="true",
+            repo="/usr/local/src/pyinfra",
+        )
+
+        git.config(
+            name="Ensure user name is set for all repos of specified user",
             key="user.name",
             value="Anon E. Mouse",
-            repo="/usr/local/src/pyinfra",
+            _sudo=True,
+            _sudo_user="anon"
+        )
+
+        git.config(
+            name="Ensure same date format for all users",
+            key="log.date",
+            value="iso",
+            system=True
         )
 
     """
@@ -41,14 +57,14 @@ def config(key: str, value: str, multi_value=False, repo: str | None = None):
     existing_config = {}
 
     if not repo:
-        existing_config = host.get_fact(GitConfig)
+        existing_config = host.get_fact(GitConfig, system=system)
 
     # Only get the config if the repo exists at this stage
     elif host.get_fact(Directory, path=unix_path_join(repo, ".git")):
         existing_config = host.get_fact(GitConfig, repo=repo)
 
     if repo is None:
-        base_command = "git config --global"
+        base_command = "git config" + (" --system" if system else " --global")
     else:
         base_command = "cd {0} && git config --local".format(repo)
 
@@ -184,7 +200,7 @@ def worktree(
     + from_remote_branch: a 2-tuple ``(remote, branch)`` that identifies a remote branch
     + present: whether the working tree should exist
     + assume_repo_exists: whether to assume the main repo exists
-    + force: remove unclean working tree if should not exist
+    + force: whether to use ``--force`` when adding/removing worktrees
     + user: chown files to this user after
     + group: chown files to this group after
 
@@ -205,6 +221,14 @@ def worktree(
             commitish="4e091aa0"
         )
 
+        git.worktree(
+            name="Create a worktree from the tag `4e091aa0`, even if already registered",
+            repo="/usr/local/src/pyinfra/master",
+            worktree="/usr/local/src/pyinfra/2.x",
+            commitish="2.x",
+            force=True
+        )
+
         git.worktree(
             name="Create a worktree with a new local branch `v1.0`",
             repo="/usr/local/src/pyinfra/master",
@@ -250,6 +274,15 @@ def worktree(
             commitish="v1.0"
         )
 
+        git.worktree(
+            name="Idempotent worktree creation, never pulls",
+            repo="/usr/local/src/pyinfra/master",
+            worktree="/usr/local/src/pyinfra/hotfix",
+            new_branch="v1.0",
+            commitish="v1.0",
+            pull=False
+        )
+
         git.worktree(
             name="Pull an existing worktree already linked to a tracking branch",
             repo="/usr/local/src/pyinfra/master",
@@ -295,6 +328,9 @@ def worktree(
         elif detached:
             command_parts.append("--detach")
 
+        if force:
+            command_parts.append("--force")
+
         command_parts.append(worktree)
 
         if commitish:
@@ -317,9 +353,12 @@ def worktree(
 
     # It exists and we still want it => pull/rebase it
     elif host.get_fact(Directory, path=worktree) and present:
+        if not pull:
+            host.noop("Pull is disabled")
+
         # pull the worktree only if it's already linked to a tracking branch or
         # if a remote branch is set
-        if host.get_fact(GitTrackingBranch, repo=worktree) or from_remote_branch:
+        elif host.get_fact(GitTrackingBranch, repo=worktree) or from_remote_branch:
             command = "cd {0} && git pull".format(worktree)
 
             if rebase:

pyinfra/operations/opkg.py

@@ -0,0 +1,88 @@
+"""
+    Manage packages on OpenWrt using opkg
+        + ``update`` - update local copy of package information
+        + ``packages`` -  install and remove packages
+
+    see https://openwrt.org/docs/guide-user/additional-software/opkg
+    OpenWrt recommends against upgrading all packages  thus there is no ``opkg.upgrade`` function
+"""
+
+from typing import List, Union
+
+from pyinfra import host
+from pyinfra.api import StringCommand, operation
+from pyinfra.facts.opkg import OpkgPackages
+from pyinfra.operations.util.packaging import ensure_packages
+
+EQUALS = "="
+
+
+@operation(is_idempotent=False)
+def update():
+    """
+    Update the local opkg information.
+    """
+
+    yield StringCommand("opkg update")
+
+
+_update = update
+
+
+@operation()
+def packages(
+    packages: Union[str, List[str]] = "",
+    present: bool = True,
+    latest: bool = False,
+    update: bool = True,
+):
+    """
+    Add/remove/update opkg packages.
+
+    + packages: package or list of packages to that must/must not be present
+    + present: whether the package(s) should be installed (default True) or removed
+    + latest: whether to attempt to upgrade the specified package(s) (default False)
+    + update: run ``opkg update`` before installing packages (default True)
+
+    Not Supported:
+        Opkg does not support version pinning, i.e. ``<pkg>=<version>`` is not allowed
+        and will cause an exception.
+
+    **Examples:**
+
+    .. code:: python
+
+        # 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)
+        opkg.packages(
+            'vim',
+            latest=True,
+            name="Ensure we have the latest version of Vim"
+        )
+    """
+    if str(packages) == "" or (
+        isinstance(packages, list) and (len(packages) < 1 or all(len(p) < 1 for p in packages))
+    ):
+        host.noop("empty or invalid package list provided to opkg.packages")
+        return
+
+    pkg_list = packages if isinstance(packages, list) else [packages]
+    have_equals = ",".join([pkg.split(EQUALS)[0] for pkg in pkg_list if EQUALS in pkg])
+    if len(have_equals) > 0:
+        raise ValueError(f"opkg does not support version pinning but found for: '{have_equals}'")
+
+    if update:
+        yield from _update._inner()
+
+    yield from ensure_packages(
+        host,
+        pkg_list,
+        host.get_fact(OpkgPackages),
+        present,
+        install_command="opkg install",
+        upgrade_command="opkg upgrade",
+        uninstall_command="opkg remove",
+        latest=latest,
+    )

pyinfra/operations/pip.py

@@ -174,12 +174,13 @@ def packages(
         install_command_args.append(extra_install_args)
     install_command = " ".join(install_command_args)
 
+    upgrade_command = "{0} --upgrade".format(install_command)
     uninstall_command = " ".join([pip, "uninstall", "--yes"])
 
     # (un)Install requirements
     if requirements is not None:
         if present:
-            yield "{0} -r {1}".format(install_command, requirements)
+            yield "{0} -r {1}".format(upgrade_command if latest else install_command, requirements)
         else:
             yield "{0} -r {1}".format(uninstall_command, requirements)
 
@@ -199,7 +200,7 @@ def packages(
             present,
             install_command=install_command,
             uninstall_command=uninstall_command,
-            upgrade_command="{0} --upgrade".format(install_command),
+            upgrade_command=upgrade_command,
             version_join="==",
             latest=latest,
         )

pyinfra/operations/pipx.py

@@ -0,0 +1,90 @@
+"""
+Manage pipx (python) applications.
+"""
+
+from pyinfra import host
+from pyinfra.api import operation
+from pyinfra.facts.pipx import PipxEnvironment, PipxPackages
+from pyinfra.facts.server import Path
+
+from .util.packaging import ensure_packages
+
+
+@operation()
+def packages(
+    packages=None,
+    present=True,
+    latest=False,
+    extra_args=None,
+):
+    """
+    Install/remove/update pipx packages.
+
+    + packages: list of packages to ensure
+    + present: whether the packages should be installed
+    + latest: whether to upgrade packages without a specified version
+    + extra_args: additional arguments to the pipx command
+
+    Versions:
+        Package versions can be pinned like pip: ``<pkg>==<version>``.
+
+    **Example:**
+
+    .. code:: python
+
+        pipx.packages(
+            name="Install ",
+            packages=["pyinfra"],
+        )
+    """
+
+    prep_install_command = ["pipx", "install"]
+
+    if extra_args:
+        prep_install_command.append(extra_args)
+    install_command = " ".join(prep_install_command)
+
+    uninstall_command = "pipx uninstall"
+    upgrade_command = "pipx upgrade"
+
+    current_packages = host.get_fact(PipxPackages)
+
+    # pipx support only one package name at a time
+    for package in packages:
+        yield from ensure_packages(
+            host,
+            [package],
+            current_packages,
+            present,
+            install_command=install_command,
+            uninstall_command=uninstall_command,
+            upgrade_command=upgrade_command,
+            version_join="==",
+            latest=latest,
+        )
+
+
+@operation()
+def upgrade_all():
+    """
+    Upgrade all pipx packages.
+    """
+    yield "pipx upgrade-all"
+
+
+@operation()
+def ensure_path():
+    """
+    Ensure pipx bin dir is in the PATH.
+    """
+
+    # Fetch the current user's PATH
+    path = host.get_fact(Path)
+    # Fetch the pipx environment variables
+    pipx_env = host.get_fact(PipxEnvironment)
+
+    # If the pipx bin dir is already in the user's PATH, we're done
+    if "PIPX_BIN_DIR" in pipx_env and pipx_env["PIPX_BIN_DIR"] in path.split(":"):
+        host.noop("pipx bin dir is already in the PATH")
+    else:
+        yield "pipx ensurepath"

pyinfra/operations/postgres.py

@@ -8,6 +8,7 @@ All operations in this module take four optional arguments:
     + ``psql_password``: the password for the connecting user
     + ``psql_host``: the hostname of the server to connect to
     + ``psql_port``: the port of the server to connect to
+    + ``psql_database``: the database on the server to connect to
 
 See example/postgresql.py for detailed example
 
@@ -28,28 +29,27 @@ from pyinfra.facts.postgres import (
 @operation(is_idempotent=False)
 def sql(
     sql: str,
-    database: str | None = None,
     # Details for speaking to PostgreSQL via `psql` CLI
     psql_user: str | None = None,
     psql_password: str | None = None,
     psql_host: str | None = None,
     psql_port: int | None = None,
+    psql_database: str | None = None,
 ):
     """
     Execute arbitrary SQL against PostgreSQL.
 
     + sql: SQL command(s) to execute
-    + database: optional database to execute against
     + psql_*: global module arguments, see above
     """
 
     yield make_execute_psql_command(
         sql,
-        database=database,
         user=psql_user,
         password=psql_password,
         host=psql_host,
         port=psql_port,
+        database=psql_database,
     )
 
 
@@ -70,6 +70,7 @@ def role(
     psql_password: str | None = None,
     psql_host: str | None = None,
     psql_port: int | None = None,
+    psql_database: str | None = None,
 ):
     """
     Add/remove PostgreSQL roles.
@@ -112,6 +113,7 @@ def role(
         psql_password=psql_password,
         psql_host=psql_host,
         psql_port=psql_port,
+        psql_database=psql_database,
     )
 
     is_present = role in roles
@@ -125,6 +127,7 @@ def role(
                 password=psql_password,
                 host=psql_host,
                 port=psql_port,
+                database=psql_database,
             )
         else:
             host.noop("postgresql role {0} does not exist".format(role))
@@ -157,6 +160,7 @@ def role(
             password=psql_password,
             host=psql_host,
             port=psql_port,
+            database=psql_database,
         )
     else:
         host.noop("postgresql role {0} exists".format(role))
@@ -178,6 +182,7 @@ def database(
     psql_password: str | None = None,
     psql_host: str | None = None,
     psql_port: int | None = None,
+    psql_database: str | None = None,
 ):
     """
     Add/remove PostgreSQL databases.
@@ -218,6 +223,7 @@ def database(
         psql_password=psql_password,
         psql_host=psql_host,
         psql_port=psql_port,
+        psql_database=psql_database,
     )
 
     is_present = database in current_databases
@@ -230,6 +236,7 @@ def database(
                 password=psql_password,
                 host=psql_host,
                 port=psql_port,
+                database=psql_database,
             )
         else:
             host.noop("postgresql database {0} does not exist".format(database))
@@ -257,6 +264,7 @@ def database(
             password=psql_password,
             host=psql_host,
             port=psql_port,
+            database=psql_database,
         )
     else:
         host.noop("postgresql database {0} exists".format(database))
@@ -265,18 +273,17 @@ def database(
 @operation(is_idempotent=False)
 def dump(
     dest: str,
-    database: str | None = None,
     # Details for speaking to PostgreSQL via `psql` CLI
     psql_user: str | None = None,
     psql_password: str | None = None,
     psql_host: str | None = None,
     psql_port: int | None = None,
+    psql_database: str | None = None,
 ):
     """
     Dump a PostgreSQL database into a ``.sql`` file. Requires ``pg_dump``.
 
     + dest: name of the file to dump the SQL to
-    + database: name of the database to dump
     + psql_*: global module arguments, see above
 
     **Example:**
@@ -286,7 +293,6 @@ def dump(
         postgresql.dump(
             name="Dump the pyinfra_stuff database",
             dest="/tmp/pyinfra_stuff.dump",
-            database="pyinfra_stuff",
             sudo_user="postgres",
         )
 
@@ -295,11 +301,11 @@ def dump(
     yield StringCommand(
         make_psql_command(
             executable="pg_dump",
-            database=database,
             user=psql_user,
             password=psql_password,
             host=psql_host,
             port=psql_port,
+            database=psql_database,
         ),
         ">",
         QuoteString(dest),
@@ -309,18 +315,17 @@ def dump(
 @operation(is_idempotent=False)
 def load(
     src: str,
-    database: str | None = None,
     # Details for speaking to PostgreSQL via `psql` CLI
     psql_user: str | None = None,
     psql_password: str | None = None,
     psql_host: str | None = None,
     psql_port: int | None = None,
+    psql_database: str | None = None,
 ):
     """
     Load ``.sql`` file into a database.
 
     + src: the filename to read from
-    + database: name of the database to import into
     + psql_*: global module arguments, see above
 
     **Example:**
@@ -330,7 +335,6 @@ def load(
         postgresql.load(
             name="Import the pyinfra_stuff dump into pyinfra_stuff_copy",
             src="/tmp/pyinfra_stuff.dump",
-            database="pyinfra_stuff_copy",
             sudo_user="postgres",
         )
 
@@ -338,11 +342,11 @@ def load(
 
     yield StringCommand(
         make_psql_command(
-            database=database,
             user=psql_user,
             password=psql_password,
             host=psql_host,
             port=psql_port,
+            database=psql_database,
         ),
         "<",
         QuoteString(src),

pyinfra/operations/runit.py

@@ -2,6 +2,8 @@
 Manage runit services.
 """
 
+from __future__ import annotations
+
 from typing import Optional
 
 from pyinfra import host