pyinfra 3.0b0__py2.py3-none-any.whl → 3.0b2__py2.py3-none-any.whl

pyinfra/operations/mysql.py

@@ -13,6 +13,8 @@ See the example/mysql.py
 
 """
 
+from __future__ import annotations
+
 from pyinfra import host
 from pyinfra.api import MaskString, OperationError, QuoteString, StringCommand, operation
 from pyinfra.facts.mysql import (
@@ -26,13 +28,13 @@ from pyinfra.facts.mysql import (
 
 @operation(is_idempotent=False)
 def sql(
-    sql,
-    database=None,
+    sql: str,
+    database: str | None = None,
     # Details for speaking to MySQL via `mysql` CLI
-    mysql_user=None,
-    mysql_password=None,
-    mysql_host=None,
-    mysql_port=None,
+    mysql_user: str | None = None,
+    mysql_password: str | None = None,
+    mysql_host: str | None = None,
+    mysql_port: int | None = None,
 ):
     """
     Execute arbitrary SQL against MySQL.
@@ -54,27 +56,28 @@ def sql(
 
 @operation()
 def user(
-    user,
-    present=True,
-    user_hostname="localhost",
-    password=None,
-    privileges=None,
+    user: str,
+    present: bool = True,
+    user_hostname: str = "localhost",
+    password: str | None = None,
+    privileges: str | list[str] | None = None,
     # MySQL REQUIRE SSL/TLS options
-    require=None,  # SSL or X509
-    require_cipher=False,
-    require_issuer=False,
-    require_subject=False,
+    require: str | None = None,  # SSL or X509
+    require_cipher: str | None = None,
+    require_issuer: str | None = None,
+    require_subject: str | None = None,
     # MySQL WITH resource limit options
-    max_connections=None,
-    max_queries_per_hour=None,
-    max_updates_per_hour=None,
-    max_connections_per_hour=None,
+    max_connections: int | None = None,
+    max_queries_per_hour: int | None = None,
+    max_updates_per_hour: int | None = None,
+    max_connections_per_hour: int | None = None,
     # Details for speaking to MySQL via `mysql` CLI via `mysql` CLI
-    mysql_user=None,
-    mysql_password=None,
-    mysql_host=None,
-    mysql_port=None,
+    mysql_user: str | None = None,
+    mysql_password: str | None = None,
+    mysql_host: str | None = None,
+    mysql_port: int | None = None,
 ):
+    ...
     """
     Add/remove/update MySQL users.
 
@@ -282,24 +285,25 @@ def user(
 
 @operation()
 def database(
-    database,
+    database: str,
     # Desired database settings
-    present=True,
-    collate=None,
-    charset=None,
-    user=None,
-    user_hostname="localhost",
-    user_privileges="ALL",
+    present: bool = True,
+    collate: str | None = None,
+    charset: str | None = None,
+    user: str | None = None,
+    user_hostname: str = "localhost",
+    user_privileges: str | list[str] = "ALL",
     # Details for speaking to MySQL via `mysql` CLI
-    mysql_user=None,
-    mysql_password=None,
-    mysql_host=None,
-    mysql_port=None,
+    mysql_user: str | None = None,
+    mysql_password: str | None = None,
+    mysql_host: str | None = None,
+    mysql_port: int | None = None,
 ):
+    ...
     """
     Add/remove MySQL databases.
 
-    + name: the name of the database
+    + database: the name of the database
     + present: whether the database should exist or not
     + collate: the collate to use when creating the database
     + charset: the charset to use when creating the database
@@ -384,18 +388,18 @@ def database(
 
 @operation()
 def privileges(
-    user,
-    privileges,
+    user: str,
+    privileges: str | list[str] | set[str],
     user_hostname="localhost",
     database="*",
     table="*",
     flush=True,
     with_grant_option=False,
     # Details for speaking to MySQL via `mysql` CLI
-    mysql_user=None,
-    mysql_password=None,
-    mysql_host=None,
-    mysql_port=None,
+    mysql_user: str | None = None,
+    mysql_password: str | None = None,
+    mysql_host: str | None = None,
+    mysql_port: int | None = None,
 ):
     """
     Add/remove MySQL privileges for a user, either global, database or table specific.
@@ -524,13 +528,13 @@ _privileges = privileges  # noqa: E305 (for use where kwarg is the same)
 
 @operation(is_idempotent=False)
 def dump(
-    dest,
-    database=None,
+    dest: str,
+    database: str | None = None,
     # Details for speaking to MySQL via `mysql` CLI
-    mysql_user=None,
-    mysql_password=None,
-    mysql_host=None,
-    mysql_port=None,
+    mysql_user: str | None = None,
+    mysql_password: str | None = None,
+    mysql_host: str | None = None,
+    mysql_port: int | None = None,
 ):
     """
     Dump a MySQL database into a ``.sql`` file. Requires ``mysqldump``.
@@ -565,13 +569,13 @@ def dump(
 
 @operation(is_idempotent=False)
 def load(
-    src,
-    database=None,
+    src: str,
+    database: str | None = None,
     # Details for speaking to MySQL via `mysql` CLI
-    mysql_user=None,
-    mysql_password=None,
-    mysql_host=None,
-    mysql_port=None,
+    mysql_user: str | None = None,
+    mysql_password: str | None = None,
+    mysql_host: str | None = None,
+    mysql_port: int | None = None,
 ):
     """
     Load ``.sql`` file into a database.

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
@@ -10,7 +12,12 @@ from .util.packaging import ensure_packages
 
 
 @operation()
-def packages(packages=None, present=True, latest=False, directory=None):
+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
@@ -11,12 +13,12 @@ from .util.service import handle_service_control
 
 @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
@@ -35,7 +37,7 @@ _update = update._inner  # noqa: E305
 
 @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
@@ -14,8 +16,8 @@ from .util.packaging import ensure_packages
 
 @operation()
 def virtualenv(
-    path,
-    python=None,
+    path: str,
+    python: str | None = None,
     venv=False,
     site_packages=False,
     always_copy=False,
@@ -81,8 +83,8 @@ _virtualenv = virtualenv._inner  # noqa
 
 @operation()
 def venv(
-    path,
-    python=None,
+    path: str,
+    python: str | None = None,
     site_packages=False,
     always_copy=False,
     present=True,
@@ -117,14 +119,14 @@ def venv(
 
 @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.
@@ -185,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
@@ -12,7 +14,7 @@ from .util.packaging import ensure_packages
 
 
 @operation()
-def packages(packages=None, present=True, pkg_path=None):
+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
@@ -35,7 +37,7 @@ _update = update._inner  # noqa: E305
 
 @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,
+    )