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

pyinfra/api/arguments.py

@@ -248,6 +248,12 @@ __argument_docs__ = {
     "Privilege & user escalation": (
         auth_argument_meta,
         """
+        .. caution::
+            When combining privilege escalation arguments it is important to know the order they
+            are applied: ``doas`` -> ``sudo`` -> ``su``. For example
+            ``_sudo=True,_su_user="pyinfra"`` yields a command like ``sudo su pyinfra..``.
+        """,
+        """
         .. code:: python
 
             # Execute a command with sudo
@@ -268,6 +274,7 @@ __argument_docs__ = {
     ),
     "Shell control & features": (
         shell_argument_meta,
+        "",
         """
         .. code:: python
 
@@ -279,8 +286,8 @@ __argument_docs__ = {
             )
         """,
     ),
-    "Operation meta & callbacks": (meta_argument_meta, ""),
-    "Execution strategy": (execution_argument_meta, ""),
+    "Operation meta & callbacks": (meta_argument_meta, "", ""),
+    "Execution strategy": (execution_argument_meta, "", ""),
 }
 
 

pyinfra/api/arguments_typed.py

@@ -32,11 +32,6 @@ class PyinfraOperation(Generic[P], Protocol):
     def __call__(
         self,
         #
-        # op args
-        # needs to be first
-        #
-        *args: P.args,
-        #
         # ConnectorArguments
         #
         # Auth
@@ -74,6 +69,10 @@ class PyinfraOperation(Generic[P], Protocol):
         _run_once: bool = False,
         _serial: bool = False,
         #
+        # op args
+        #
+        *args: P.args,
+        #
         # op kwargs
         #
         **kwargs: P.kwargs,

pyinfra/api/command.py

@@ -6,9 +6,9 @@ from string import Formatter
 from typing import IO, TYPE_CHECKING, Callable, Union
 
 import gevent
-from typing_extensions import Unpack
+from typing_extensions import Unpack, override
 
-from pyinfra.context import ctx_config, ctx_host
+from pyinfra.context import LocalContextObject, ctx_config, ctx_host
 
 from .arguments import ConnectorArguments
 
@@ -58,6 +58,7 @@ class QuoteString:
     def __init__(self, obj: Union[str, "StringCommand"]):
         self.obj = obj
 
+    @override
     def __repr__(self) -> str:
         return f"QuoteString({self.obj})"
 
@@ -68,6 +69,7 @@ class PyinfraCommand:
     def __init__(self, **arguments: Unpack[ConnectorArguments]):
         self.connector_arguments = arguments
 
+    @override
     def __eq__(self, other) -> bool:
         if isinstance(other, self.__class__) and repr(self) == repr(other):
             return True
@@ -88,9 +90,11 @@ class StringCommand(PyinfraCommand):
         self.bits = bits
         self.separator = _separator
 
+    @override
     def __str__(self) -> str:
         return self.get_masked_value()
 
+    @override
     def __repr__(self) -> str:
         return f"StringCommand({self.get_masked_value()})"
 
@@ -131,6 +135,7 @@ class StringCommand(PyinfraCommand):
             ],
         )
 
+    @override
     def execute(self, state: "State", host: "Host", connector_arguments: ConnectorArguments):
         connector_arguments.update(self.connector_arguments)
 
@@ -155,9 +160,11 @@ class FileUploadCommand(PyinfraCommand):
         self.dest = dest
         self.remote_temp_filename = remote_temp_filename
 
+    @override
     def __repr__(self):
         return "FileUploadCommand({0}, {1})".format(self.src, self.dest)
 
+    @override
     def execute(self, state: "State", host: "Host", connector_arguments: ConnectorArguments):
         connector_arguments.update(self.connector_arguments)
 
@@ -184,9 +191,11 @@ class FileDownloadCommand(PyinfraCommand):
         self.dest = dest
         self.remote_temp_filename = remote_temp_filename
 
+    @override
     def __repr__(self):
         return "FileDownloadCommand({0}, {1})".format(self.src, self.dest)
 
+    @override
     def execute(self, state: "State", host: "Host", connector_arguments: ConnectorArguments):
         connector_arguments.update(self.connector_arguments)
 
@@ -213,6 +222,7 @@ class FunctionCommand(PyinfraCommand):
         self.args = args
         self.kwargs = func_kwargs
 
+    @override
     def __repr__(self):
         return "FunctionCommand({0}, {1}, {2})".format(
             self.function.__name__,
@@ -220,12 +230,19 @@ class FunctionCommand(PyinfraCommand):
             self.kwargs,
         )
 
+    @override
     def execute(self, state: "State", host: "Host", connector_arguments: ConnectorArguments):
         argspec = getfullargspec(self.function)
         if "state" in argspec.args and "host" in argspec.args:
             return self.function(state, host, *self.args, **self.kwargs)
 
-        def execute_function():
+        # If we're already running inside a greenlet (ie a nested callback) just execute the func
+        # without any gevent.spawn which will break the local host object.
+        if isinstance(host, LocalContextObject):
+            self.function(*self.args, **self.kwargs)
+            return
+
+        def execute_function() -> None:
             with ctx_config.use(state.config.copy()):
                 with ctx_host.use(host):
                     self.function(*self.args, **self.kwargs)
@@ -241,9 +258,11 @@ class RsyncCommand(PyinfraCommand):
         self.dest = dest
         self.flags = flags
 
+    @override
     def __repr__(self):
         return "RsyncCommand({0}, {1}, {2})".format(self.src, self.dest, self.flags)
 
+    @override
     def execute(self, state: "State", host: "Host", connector_arguments: ConnectorArguments):
         return host.rsync(
             self.src,

pyinfra/api/config.py

@@ -2,6 +2,7 @@ try:
     import importlib_metadata
 except ImportError:
     import importlib.metadata as importlib_metadata  # type: ignore[no-redef]
+
 from os import path
 from typing import Iterable, Optional, Set
 
@@ -9,6 +10,7 @@ from packaging.markers import Marker
 from packaging.requirements import Requirement
 from packaging.specifiers import SpecifierSet
 from packaging.version import Version
+from typing_extensions import override
 
 from pyinfra import __version__, state
 
@@ -207,6 +209,7 @@ class Config(ConfigDefaults):
         for key, value in config.items():
             setattr(self, key, value)
 
+    @override
     def __setattr__(self, key, value):
         super().__setattr__(key, value)
 
@@ -221,10 +224,10 @@ class Config(ConfigDefaults):
         for key, value in config_state:
             setattr(self, key, value)
 
-    def lock_current_state(self):
+    def lock_current_state(self) -> None:
         self._locked_config = self.get_current_state()
 
-    def reset_locked_state(self):
+    def reset_locked_state(self) -> None:
         self.set_current_state(self._locked_config)
 
     def copy(self) -> "Config":

pyinfra/api/deploy.py

@@ -23,7 +23,7 @@ if TYPE_CHECKING:
     from pyinfra.api.state import State
 
 
-def add_deploy(state: "State", deploy_func: Callable[..., Any], *args, **kwargs):
+def add_deploy(state: "State", deploy_func: Callable[..., Any], *args, **kwargs) -> None:
     """
     Prepare & add an deploy to pyinfra.state by executing it on all hosts.
 
@@ -54,7 +54,9 @@ def add_deploy(state: "State", deploy_func: Callable[..., Any], *args, **kwargs)
 P = ParamSpec("P")
 
 
-def deploy(name: Optional[str] = None, data_defaults=None):
+def deploy(
+    name: Optional[str] = None, data_defaults: Optional[dict] = None
+) -> Callable[[Callable[P, Any]], PyinfraOperation[P]]:
     """
     Decorator that takes a deploy function (normally from a pyinfra_* package)
     and wraps any operations called inside with any deploy-wide kwargs/data.

pyinfra/api/facts.py

@@ -19,6 +19,7 @@ from typing import TYPE_CHECKING, Any, Callable, Generic, Iterable, Optional, Ty
 import click
 import gevent
 from paramiko import SSHException
+from typing_extensions import override
 
 from pyinfra import logger
 from pyinfra.api import StringCommand
@@ -61,6 +62,7 @@ class FactBase(Generic[T]):
     def requires_command(self, *args, **kwargs) -> str | None:
         return None
 
+    @override
     def __init_subclass__(cls) -> None:
         super().__init_subclass__()
         module_name = cls.__module__.replace("pyinfra.facts.", "")
@@ -97,6 +99,7 @@ class ShortFactBase(Generic[T]):
     name: str
     fact: Type[FactBase]
 
+    @override
     def __init_subclass__(cls) -> None:
         super().__init_subclass__()
         module_name = cls.__module__.replace("pyinfra.facts.", "")

pyinfra/api/host.py

@@ -17,7 +17,7 @@ from typing import (
 from uuid import uuid4
 
 import click
-from typing_extensions import Unpack
+from typing_extensions import Unpack, override
 
 from pyinfra import logger
 from pyinfra.connectors.base import BaseConnector
@@ -75,9 +75,11 @@ class HostData:
 
         raise AttributeError(f"Host `{self.host}` has no data `{key}`")
 
+    @override
     def __setattr__(self, key: str, value: Any):
         self.override_datas[key] = value
 
+    @override
     def __str__(self):
         return str(self.datas)
 
@@ -147,8 +149,10 @@ class Host:
         name: str,
         inventory: "Inventory",
         groups,
-        connector_cls=get_execution_connector("ssh"),
+        connector_cls=None,
     ):
+        if connector_cls is None:
+            connector_cls = get_execution_connector("ssh")
         self.inventory = inventory
         self.groups = groups
         self.connector_cls = connector_cls
@@ -181,9 +185,11 @@ class Host:
         padding_diff = longest_name_len - len(self.name)
         self.print_prefix_padding = "".join(" " for _ in range(0, padding_diff))
 
+    @override
     def __str__(self):
         return "{0}".format(self.name)
 
+    @override
     def __repr__(self):
         return "Host({0})".format(self.name)
 
@@ -218,17 +224,19 @@ class Host:
             self.print_prefix_padding,
         )
 
-    def log(self, message, log_func=logger.info):
+    def log(self, message: str, log_func: Callable[[str], Any] = logger.info) -> None:
         log_func(f"{self.print_prefix}{message}")
 
-    def log_styled(self, message, log_func=logger.info, **kwargs):
+    def log_styled(
+        self, message: str, log_func: Callable[[str], Any] = logger.info, **kwargs
+    ) -> None:
         message_styled = click.style(message, **kwargs)
         self.log(message_styled, log_func=log_func)
 
     def get_deploy_data(self):
         return self.current_op_deploy_data or self.current_deploy_data or {}
 
-    def noop(self, description):
+    def noop(self, description: str) -> None:
         """
         Log a description for a noop operation.
         """
@@ -355,7 +363,7 @@ class Host:
     # Connector proxy
     #
 
-    def _check_state(self):
+    def _check_state(self) -> None:
         if not self.state:
             raise TypeError("Cannot call this function with no state!")
 
@@ -397,7 +405,7 @@ class Host:
                 self.state.trigger_callbacks("host_connect", self)
                 self.connected = True
 
-    def disconnect(self):
+    def disconnect(self) -> None:
         """
         Disconnect from the host using it's configured connector.
         """

pyinfra/api/operation.py

@@ -13,7 +13,7 @@ from io import StringIO
 from types import FunctionType
 from typing import TYPE_CHECKING, Any, Callable, Generator, Iterator, Optional, cast
 
-from typing_extensions import ParamSpec
+from typing_extensions import ParamSpec, override
 
 import pyinfra
 from pyinfra import context, logger
@@ -52,6 +52,7 @@ class OperationMeta:
         self._hash = hash
         self._maybe_is_change = is_change
 
+    @override
     def __repr__(self) -> str:
         """
         Return Operation object as a string.

pyinfra/api/state.py

@@ -122,7 +122,7 @@ class StateHostMeta:
     ops_no_change = 0
     op_hashes: set[str]
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.op_hashes = set()
 
 

pyinfra/connectors/base.py

@@ -86,14 +86,13 @@ class BaseConnector(abc.ABC):
     @abc.abstractmethod
     def make_names_data(name: str) -> Iterator[tuple[str, dict, list[str]]]:
         """
-        Generates hosts/data/groups information for inventory. This allows a
-        single connector reference to generate multiple target hosts.
+        Generate inventory targets. This is a staticmethod because each yield will become a new host
+        object with a new (ie not this) instance of the connector.
         """
-        ...
 
     def connect(self) -> None:
         """
-        Connect this connector instance.
+        Connect this connector instance. Should raise ConnectError exceptions to indicate failure.
         """
 
     def disconnect(self) -> None:
@@ -108,7 +107,20 @@ class BaseConnector(abc.ABC):
         print_output: bool,
         print_input: bool,
         **arguments: Unpack["ConnectorArguments"],
-    ) -> tuple[bool, "CommandOutput"]: ...
+    ) -> tuple[bool, "CommandOutput"]:
+        """
+        Execute a command.
+
+        Args:
+            command (StringCommand): actual command to execute
+            print_output (bool): whether to print command output
+            print_input (bool): whether to print command input
+            arguments: (ConnectorArguments): connector global arguments
+
+        Returns:
+            tuple: (bool, CommandOutput)
+            Bool indicating success and CommandOutput with stdout/stderr lines.
+        """
 
     @abc.abstractmethod
     def put_file(
@@ -119,7 +131,14 @@ class BaseConnector(abc.ABC):
         print_output: bool = False,
         print_input: bool = False,
         **arguments: Unpack["ConnectorArguments"],
-    ) -> bool: ...
+    ) -> bool:
+        """
+        Upload a local file or IO object by copying it to a temporary directory
+        and then writing it to the upload location.
+
+        Returns:
+            bool: indicating success or failure.
+        """
 
     @abc.abstractmethod
     def get_file(
@@ -130,9 +149,16 @@ class BaseConnector(abc.ABC):
         print_output: bool = False,
         print_input: bool = False,
         **arguments: Unpack["ConnectorArguments"],
-    ) -> bool: ...
+    ) -> bool:
+        """
+        Download a local file by copying it to a temporary location and then writing
+        it to our filename or IO object.
+
+        Returns:
+            bool: indicating success or failure.
+        """
 
-    def check_can_rsync(self):
+    def check_can_rsync(self) -> None:
         raise NotImplementedError("This connector does not support rsync")
 
     def rsync(

pyinfra/connectors/chroot.py

@@ -3,7 +3,7 @@ from tempfile import mkstemp
 from typing import TYPE_CHECKING, Optional
 
 import click
-from typing_extensions import Unpack
+from typing_extensions import Unpack, override
 
 from pyinfra import local, logger
 from pyinfra.api import QuoteString, StringCommand
@@ -22,7 +22,7 @@ if TYPE_CHECKING:
 
 
 @memoize
-def show_warning():
+def show_warning() -> None:
     logger.warning("The @chroot connector is in beta!")
 
 
@@ -39,6 +39,7 @@ class ChrootConnector(BaseConnector):
         super().__init__(state, host)
         self.local = LocalConnector(state, host)
 
+    @override
     @staticmethod
     def make_names_data(name: Optional[str] = None):
         if not name:
@@ -50,6 +51,7 @@ class ChrootConnector(BaseConnector):
             "chroot_directory": "/{0}".format(name.lstrip("/")),
         }, ["@chroot"]
 
+    @override
     def connect(self) -> None:
         self.local.connect()
 
@@ -66,6 +68,7 @@ class ChrootConnector(BaseConnector):
 
         self.host.connector_data["chroot_directory"] = chroot_directory
 
+    @override
     def run_shell_command(
         self,
         command,
@@ -97,6 +100,7 @@ class ChrootConnector(BaseConnector):
             **local_arguments,
         )
 
+    @override
     def put_file(
         self,
         filename_or_io,
@@ -148,6 +152,7 @@ class ChrootConnector(BaseConnector):
 
         return status
 
+    @override
     def get_file(
         self,
         remote_filename,

pyinfra/connectors/docker.py

@@ -6,7 +6,7 @@ from tempfile import mkstemp
 from typing import TYPE_CHECKING
 
 import click
-from typing_extensions import TypedDict, Unpack
+from typing_extensions import TypedDict, Unpack, override
 
 from pyinfra import local, logger
 from pyinfra.api import QuoteString, StringCommand
@@ -58,13 +58,20 @@ def _start_docker_image(image_name):
 
 class DockerConnector(BaseConnector):
     """
-    The docker connector allows you to build Docker images or modify running
-    Docker containers. You can pass either an image name or existing container ID:
+    The Docker connector allows you to use pyinfra to create new Docker images or modify running
+    Docker containers.
 
-    + Image - will create a new container from the image, execute operations \
-        against it, save into a new Docker image and remove the container
-    + Existing container ID - will execute operations against the running \
-        container, leaving it running
+    .. note::
+
+        The Docker connector allows pyinfra to target Docker containers as inventory and is
+        unrelated to the :doc:`../operations/docker` & :doc:`../facts/docker`.
+
+    You can pass either an image name or existing container ID:
+
+    + Image - will create a new container from the image, execute operations against it, save into \
+        a new Docker image and remove the container
+    + Existing container ID - will execute operations against the running container, leaving it \
+        running
 
     .. code:: shell
 
@@ -76,6 +83,10 @@ class DockerConnector(BaseConnector):
 
         # Execute against a running container
         pyinfra @docker/2beb8c15a1b1 ...
+
+    The Docker connector is great for testing pyinfra operations locally, rather than connecting to
+    a remote host over SSH each time. This gives you a fast, local-first devloop to iterate on when
+    writing deploys, operations or facts.
     """
 
     handles_execution = True
@@ -104,6 +115,7 @@ class DockerConnector(BaseConnector):
             ["@docker"],
         )
 
+    @override
     def connect(self) -> None:
         self.local.connect()
 
@@ -116,7 +128,8 @@ class DockerConnector(BaseConnector):
             except PyinfraError:
                 self.container_id = _start_docker_image(docker_identifier)
 
-    def disconnect(self):
+    @override
+    def disconnect(self) -> None:
         container_id = self.container_id
 
         if self.no_stop:
@@ -145,6 +158,7 @@ class DockerConnector(BaseConnector):
             ),
         )
 
+    @override
     def run_shell_command(
         self,
         command: StringCommand,
@@ -177,6 +191,7 @@ class DockerConnector(BaseConnector):
             **local_arguments,
         )
 
+    @override
     def put_file(
         self,
         filename_or_io,
@@ -234,6 +249,7 @@ class DockerConnector(BaseConnector):
 
         return status
 
+    @override
     def get_file(
         self,
         remote_filename,

pyinfra/connectors/dockerssh.py

@@ -3,7 +3,7 @@ from tempfile import mkstemp
 from typing import TYPE_CHECKING
 
 import click
-from typing_extensions import Unpack
+from typing_extensions import Unpack, override
 
 from pyinfra import logger
 from pyinfra.api import QuoteString, StringCommand
@@ -22,7 +22,7 @@ if TYPE_CHECKING:
 
 
 @memoize
-def show_warning():
+def show_warning() -> None:
     logger.warning("The @dockerssh connector is in beta!")
 
 
@@ -68,6 +68,7 @@ class DockerSSHConnector(BaseConnector):
             ["@dockerssh"],
         )
 
+    @override
     def connect(self) -> None:
         self.ssh.connect()
 
@@ -97,6 +98,7 @@ class DockerSSHConnector(BaseConnector):
 
         self.host.host_data["docker_container_id"] = container_id
 
+    @override
     def disconnect(self) -> None:
         container_id = self.host.host_data["docker_container_id"][:12]
 
@@ -118,6 +120,7 @@ class DockerSSHConnector(BaseConnector):
             ),
         )
 
+    @override
     def run_shell_command(
         self,
         command,
@@ -150,6 +153,7 @@ class DockerSSHConnector(BaseConnector):
             **local_arguments,
         )
 
+    @override
     def put_file(
         self,
         filename_or_io,
@@ -221,6 +225,7 @@ class DockerSSHConnector(BaseConnector):
 
         return status
 
+    @override
     def get_file(
         self,
         remote_filename,

pyinfra/connectors/local.py

@@ -4,7 +4,7 @@ from tempfile import mkstemp
 from typing import TYPE_CHECKING, Tuple
 
 import click
-from typing_extensions import Unpack
+from typing_extensions import Unpack, override
 
 from pyinfra import logger
 from pyinfra.api.command import QuoteString, StringCommand
@@ -45,6 +45,7 @@ class LocalConnector(BaseConnector):
 
         yield "@local", {}, ["@local"]
 
+    @override
     def run_shell_command(
         self,
         command: StringCommand,
@@ -101,6 +102,7 @@ class LocalConnector(BaseConnector):
 
         return status, combined_output
 
+    @override
     def put_file(
         self,
         filename_or_io,
@@ -152,6 +154,7 @@ class LocalConnector(BaseConnector):
 
         return status
 
+    @override
     def get_file(
         self,
         remote_filename,
@@ -206,10 +209,12 @@ class LocalConnector(BaseConnector):
 
         return True
 
-    def check_can_rsync(self):
+    @override
+    def check_can_rsync(self) -> None:
         if not which("rsync"):
             raise NotImplementedError("The `rsync` binary is not available on this system.")
 
+    @override
     def rsync(
         self,
         src,