pyinfra 2.9.1__py2.py3-none-any.whl → 3.0__py2.py3-none-any.whl

pyinfra/operations/npm.py

@@ -2,6 +2,8 @@
 Manage npm (aka node aka Node.js) packages.
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.npm import NpmPackages
@@ -9,8 +11,13 @@ from pyinfra.facts.npm import NpmPackages
 from .util.packaging import ensure_packages
 
 
-@operation
-def packages(packages=None, present=True, latest=False, directory=None):
+@operation()
+def packages(
+    packages: str | list[str] | None = None,
+    present=True,
+    latest=False,
+    directory: str | None = None,
+):
     """
     Install/remove/update npm packages.
 

pyinfra/operations/openrc.py

@@ -2,6 +2,8 @@
 Manage OpenRC init services.
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.openrc import OpenrcEnabled, OpenrcStatus
@@ -9,14 +11,14 @@ from pyinfra.facts.openrc import OpenrcEnabled, OpenrcStatus
 from .util.service import handle_service_control
 
 
-@operation
+@operation()
 def service(
-    service,
+    service: str,
     running=True,
     restarted=False,
     reloaded=False,
-    command=None,
-    enabled=None,
+    command: str | None = None,
+    enabled: bool | None = None,
     runlevel="default",
 ):
     """

pyinfra/operations/pacman.py

@@ -2,6 +2,8 @@
 Manage pacman packages. (Arch Linux package manager)
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.pacman import PacmanPackages, PacmanUnpackGroup
@@ -18,7 +20,7 @@ def upgrade():
     yield "pacman --noconfirm -Su"
 
 
-_upgrade = upgrade  # noqa: E305
+_upgrade = upgrade._inner  # noqa: E305
 
 
 @operation(is_idempotent=False)
@@ -30,12 +32,12 @@ def update():
     yield "pacman -Sy"
 
 
-_update = update  # noqa: E305
+_update = update._inner  # noqa: E305
 
 
-@operation
+@operation()
 def packages(
-    packages=None,
+    packages: str | list[str] | None = None,
     present=True,
     update=False,
     upgrade=False,
@@ -75,8 +77,5 @@ def packages(
         present,
         install_command="pacman --noconfirm -S",
         uninstall_command="pacman --noconfirm -R",
-        expand_package_fact=lambda package: host.get_fact(
-            PacmanUnpackGroup,
-            name=package,
-        ),
+        expand_package_fact=lambda package: host.get_fact(PacmanUnpackGroup, package=package),
     )

pyinfra/operations/pip.py

@@ -3,6 +3,8 @@ Manage pip (python) packages. Compatible globally or inside
 a virtualenv (virtual environment).
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.files import File
@@ -12,10 +14,10 @@ from . import files
 from .util.packaging import ensure_packages
 
 
-@operation
+@operation()
 def virtualenv(
-    path,
-    python=None,
+    path: str,
+    python: str | None = None,
     venv=False,
     site_packages=False,
     always_copy=False,
@@ -46,7 +48,7 @@ def virtualenv(
 
     if present is False:
         if host.get_fact(File, path=activate_script_path):
-            yield from files.directory(path, present=False)
+            yield from files.directory._inner(path, present=False)
         else:
             host.noop("virtualenv {0} does not exist".format(path))
 
@@ -72,23 +74,17 @@ def virtualenv(
             command.append(path)
 
             yield " ".join(command)
-
-            host.create_fact(
-                File,
-                kwargs={"path": activate_script_path},
-                data={"user": None, "group": None},
-            )
         else:
             host.noop("virtualenv {0} exists".format(path))
 
 
-_virtualenv = virtualenv  # noqa
+_virtualenv = virtualenv._inner  # noqa
 
 
-@operation
+@operation()
 def venv(
-    path,
-    python=None,
+    path: str,
+    python: str | None = None,
     site_packages=False,
     always_copy=False,
     present=True,
@@ -111,7 +107,7 @@ def venv(
         )
     """
 
-    yield from virtualenv(
+    yield from _virtualenv(
         venv=True,
         path=path,
         python=python,
@@ -121,16 +117,16 @@ def venv(
     )
 
 
-@operation
+@operation()
 def packages(
-    packages=None,
+    packages: str | list[str] | None = None,
     present=True,
     latest=False,
-    requirements=None,
+    requirements: str | None = None,
     pip="pip",
-    virtualenv=None,
-    virtualenv_kwargs=None,
-    extra_install_args=None,
+    virtualenv: str | None = None,
+    virtualenv_kwargs: dict | None = None,
+    extra_install_args: str | None = None,
 ):
     """
     Install/remove/update pip packages.
@@ -173,10 +169,10 @@ def packages(
         virtualenv = virtualenv.rstrip("/")
         pip = "{0}/bin/{1}".format(virtualenv, pip)
 
-    install_command = [pip, "install"]
+    install_command_args = [pip, "install"]
     if extra_install_args:
-        install_command.append(extra_install_args)
-    install_command = " ".join(install_command)
+        install_command_args.append(extra_install_args)
+    install_command = " ".join(install_command_args)
 
     uninstall_command = " ".join([pip, "uninstall", "--yes"])
 
@@ -191,6 +187,11 @@ def packages(
     if packages:
         current_packages = host.get_fact(PipPackages, pip=pip)
 
+        # PEP-0426 states that Python packages should be compared using lowercase, so lowercase both
+        # the input packages and the fact packages before comparison.
+        packages = [pkg.lower() for pkg in packages]
+        current_packages = {pkg.lower(): versions for pkg, versions in current_packages.items()}
+
         yield from ensure_packages(
             host,
             packages,

pyinfra/operations/pkg.py

@@ -2,6 +2,8 @@
 Manage BSD packages and repositories. Note that BSD package names are case-sensitive.
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.files import File
@@ -11,8 +13,8 @@ from pyinfra.facts.server import Arch, Os, OsVersion, Which
 from .util.packaging import ensure_packages
 
 
-@operation
-def packages(packages=None, present=True, pkg_path=None):
+@operation()
+def packages(packages: str | list[str] | None = None, present=True, pkg_path: str | None = None):
     """
     Install/remove/update pkg packages. This will use ``pkg ...`` where available
     (FreeBSD) and the ``pkg_*`` variants elsewhere.

pyinfra/operations/pkgin.py

@@ -2,6 +2,8 @@
 Manage pkgin packages.
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import operation
 from pyinfra.facts.pkgin import PkginPackages
@@ -18,7 +20,7 @@ def upgrade():
     yield "pkgin -y upgrade"
 
 
-_upgrade = upgrade  # noqa: E305
+_upgrade = upgrade._inner  # noqa: E305
 
 
 @operation(is_idempotent=False)
@@ -30,12 +32,12 @@ def update():
     yield "pkgin -y update"
 
 
-_update = update  # noqa: E305
+_update = update._inner  # noqa: E305
 
 
-@operation
+@operation()
 def packages(
-    packages=None,
+    packages: str | list[str] | None = None,
     present=True,
     latest=False,
     update=False,

pyinfra/operations/postgres.py

@@ -0,0 +1,349 @@
+"""
+The PostgreSQL modules manage PostgreSQL databases, users and privileges.
+
+Requires the ``psql`` CLI executable on the target host(s).
+
+All operations in this module take four optional arguments:
+    + ``psql_user``: the username to connect to postgresql to
+    + ``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
+
+See example/postgresql.py for detailed example
+
+"""
+
+from __future__ import annotations
+
+from pyinfra import host
+from pyinfra.api import MaskString, StringCommand, operation
+from pyinfra.facts.postgres import (
+    PostgresDatabases,
+    PostgresRoles,
+    make_execute_psql_command,
+    make_psql_command,
+)
+
+
+@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,
+):
+    """
+    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,
+    )
+
+
+@operation()
+def role(
+    role: str,
+    present=True,
+    password: str | None = None,
+    login=True,
+    superuser=False,
+    inherit=False,
+    createdb=False,
+    createrole=False,
+    replication=False,
+    connection_limit: int | 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,
+):
+    """
+    Add/remove PostgreSQL roles.
+
+    + role: name of the role
+    + present: whether the role should be present or absent
+    + password: the password for the role
+    + login: whether the role can login
+    + superuser: whether role will be a superuser
+    + inherit: whether the role inherits from other roles
+    + createdb: whether the role is allowed to create databases
+    + createrole: whether the role is allowed to create new roles
+    + replication: whether this role is allowed to replicate
+    + connection_limit: the connection limit for the role
+    + psql_*: global module arguments, see above
+
+    Updates:
+        pyinfra will not attempt to change existing roles - it will either
+        create or drop roles, but not alter them (if the role exists this
+        operation will make no changes).
+
+    **Example:**
+
+    .. code:: python
+
+        postgresql.role(
+            name="Create the pyinfra PostgreSQL role",
+            role="pyinfra",
+            password="somepassword",
+            superuser=True,
+            login=True,
+            sudo_user="postgres",
+        )
+
+    """
+
+    roles = host.get_fact(
+        PostgresRoles,
+        psql_user=psql_user,
+        psql_password=psql_password,
+        psql_host=psql_host,
+        psql_port=psql_port,
+    )
+
+    is_present = role in roles
+
+    # User not wanted?
+    if not present:
+        if is_present:
+            yield make_execute_psql_command(
+                'DROP ROLE "{0}"'.format(role),
+                user=psql_user,
+                password=psql_password,
+                host=psql_host,
+                port=psql_port,
+            )
+        else:
+            host.noop("postgresql role {0} does not exist".format(role))
+        return
+
+    # If we want the user and they don't exist
+    if not is_present:
+        sql_bits = ['CREATE ROLE "{0}"'.format(role)]
+
+        for key, value in (
+            ("LOGIN", login),
+            ("SUPERUSER", superuser),
+            ("INHERIT", inherit),
+            ("CREATEDB", createdb),
+            ("CREATEROLE", createrole),
+            ("REPLICATION", replication),
+        ):
+            if value:
+                sql_bits.append(key)
+
+        if connection_limit:
+            sql_bits.append("CONNECTION LIMIT {0}".format(connection_limit))
+
+        if password:
+            sql_bits.append(MaskString("PASSWORD '{0}'".format(password)))
+
+        yield make_execute_psql_command(
+            StringCommand(*sql_bits),
+            user=psql_user,
+            password=psql_password,
+            host=psql_host,
+            port=psql_port,
+        )
+    else:
+        host.noop("postgresql role {0} exists".format(role))
+
+
+@operation()
+def database(
+    database: str,
+    present=True,
+    owner: str | None = None,
+    template: str | None = None,
+    encoding: str | None = None,
+    lc_collate: str | None = None,
+    lc_ctype: str | None = None,
+    tablespace: str | None = None,
+    connection_limit: int | 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,
+):
+    """
+    Add/remove PostgreSQL databases.
+
+    + name: name of the database
+    + present: whether the database should exist or not
+    + owner: the PostgreSQL role that owns the database
+    + template: name of the PostgreSQL template to use
+    + encoding: encoding of the database
+    + lc_collate: lc_collate of the database
+    + lc_ctype: lc_ctype of the database
+    + tablespace: the tablespace to use for the template
+    + connection_limit: the connection limit to apply to the database
+    + psql_*: global module arguments, see above
+
+    Updates:
+        pyinfra will not attempt to change existing databases - it will either
+        create or drop databases, but not alter them (if the db exists this
+        operation will make no changes).
+
+    **Example:**
+
+    .. code:: python
+
+        postgresql.database(
+            name="Create the pyinfra_stuff database",
+            database="pyinfra_stuff",
+            owner="pyinfra",
+            encoding="UTF8",
+            sudo_user="postgres",
+        )
+
+    """
+
+    current_databases = host.get_fact(
+        PostgresDatabases,
+        psql_user=psql_user,
+        psql_password=psql_password,
+        psql_host=psql_host,
+        psql_port=psql_port,
+    )
+
+    is_present = database in current_databases
+
+    if not present:
+        if is_present:
+            yield make_execute_psql_command(
+                'DROP DATABASE "{0}"'.format(database),
+                user=psql_user,
+                password=psql_password,
+                host=psql_host,
+                port=psql_port,
+            )
+        else:
+            host.noop("postgresql database {0} does not exist".format(database))
+        return
+
+    # We want the database but it doesn't exist
+    if present and not is_present:
+        sql_bits = ['CREATE DATABASE "{0}"'.format(database)]
+
+        for key, value in (
+            ("OWNER", '"{0}"'.format(owner) if owner else owner),
+            ("TEMPLATE", template),
+            ("ENCODING", encoding),
+            ("LC_COLLATE", lc_collate),
+            ("LC_CTYPE", lc_ctype),
+            ("TABLESPACE", tablespace),
+            ("CONNECTION LIMIT", connection_limit),
+        ):
+            if value:
+                sql_bits.append("{0} {1}".format(key, value))
+
+        yield make_execute_psql_command(
+            StringCommand(*sql_bits),
+            user=psql_user,
+            password=psql_password,
+            host=psql_host,
+            port=psql_port,
+        )
+    else:
+        host.noop("postgresql database {0} exists".format(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,
+):
+    """
+    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:**
+
+    .. code:: python
+
+        postgresql.dump(
+            name="Dump the pyinfra_stuff database",
+            dest="/tmp/pyinfra_stuff.dump",
+            database="pyinfra_stuff",
+            sudo_user="postgres",
+        )
+
+    """
+
+    yield StringCommand(
+        make_psql_command(
+            executable="pg_dump",
+            database=database,
+            user=psql_user,
+            password=psql_password,
+            host=psql_host,
+            port=psql_port,
+        ),
+        ">",
+        dest,
+    )
+
+
+@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,
+):
+    """
+    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:**
+
+    .. code:: python
+
+        postgresql.load(
+            name="Import the pyinfra_stuff dump into pyinfra_stuff_copy",
+            src="/tmp/pyinfra_stuff.dump",
+            database="pyinfra_stuff_copy",
+            sudo_user="postgres",
+        )
+
+    """
+
+    yield StringCommand(
+        make_psql_command(
+            database=database,
+            user=psql_user,
+            password=psql_password,
+            host=psql_host,
+            port=psql_port,
+        ),
+        "<",
+        src,
+    )