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

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)

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)
 

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"