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

pyinfra/api/operation.py

@@ -11,7 +11,7 @@ from functools import wraps
 from inspect import signature
 from io import StringIO
 from types import FunctionType
-from typing import Any, Callable, Generator, Iterator, Optional, cast
+from typing import TYPE_CHECKING, Any, Callable, Generator, Iterator, Optional, cast
 
 from typing_extensions import ParamSpec
 
@@ -36,16 +36,19 @@ from .util import (
 
 op_meta_default = object()
 
+if TYPE_CHECKING:
+    from pyinfra.connectors.util import CommandOutput
+
 
 class OperationMeta:
     _hash: str
 
-    _combined_output_lines = None
+    _combined_output: Optional["CommandOutput"] = None
     _commands: Optional[list[Any]] = None
-    _maybe_is_change: bool = False
+    _maybe_is_change: Optional[bool] = None
     _success: Optional[bool] = None
 
-    def __init__(self, hash, is_change=False):
+    def __init__(self, hash, is_change: Optional[bool]):
         self._hash = hash
         self._maybe_is_change = is_change
 
@@ -57,7 +60,7 @@ class OperationMeta:
         if self._commands is not None:
             return (
                 "OperationMeta(executed=True, "
-                f"changed={self.did_change()}, hash={self._hash}, commands={len(self._commands)})"
+                f"success={self.did_succeed}, hash={self._hash}, commands={len(self._commands)})"
             )
         return (
             "OperationMeta(executed=False, "
@@ -69,13 +72,13 @@ class OperationMeta:
         self,
         success: bool,
         commands: list[Any],
-        combined_output_lines,
+        combined_output: "CommandOutput",
     ) -> None:
         if self.is_complete():
             raise RuntimeError("Cannot complete an already complete operation")
         self._success = success
         self._commands = commands
-        self._combined_output_lines = combined_output_lines
+        self._combined_output = combined_output
 
     def is_complete(self) -> bool:
         return self._success is not None
@@ -84,31 +87,57 @@ class OperationMeta:
         if not self.is_complete():
             raise RuntimeError("Cannot evaluate operation result before execution")
 
-    def did_change(self) -> bool:
-        self._raise_if_not_complete()
+    @property
+    def will_change(self) -> bool:
+        if self._maybe_is_change is not None:
+            return self._maybe_is_change
+
+        op_data = context.state.get_op_data_for_host(context.host, self._hash)
+        cmd_gen = op_data.command_generator
+        for _ in cmd_gen():
+            self._maybe_is_change = True
+            return True
+        self._maybe_is_change = False
+        return False
+
+    def _did_change(self) -> bool:
         return bool(self._success and len(self._commands or []) > 0)
 
-    def did_succeed(self) -> bool:
-        self._raise_if_not_complete()
+    @property
+    def did_change(self):
+        return context.host.when(self._did_change)
+
+    @property
+    def did_not_change(self):
+        return context.host.when(lambda: not self._did_change())
+
+    def did_succeed(self, _raise_if_not_complete=True) -> bool:
+        if _raise_if_not_complete:
+            self._raise_if_not_complete()
         return self._success is True
 
     def did_error(self) -> bool:
         self._raise_if_not_complete()
         return self._success is False
 
-    # Output lines
-    def _get_lines(self, types=("stdout", "stderr")):
-        self._raise_if_not_complete()
-        assert self._combined_output_lines is not None
-        return [line for type_, line in self._combined_output_lines if type_ in types]
+    # TODO: deprecated, remove in v4
+    @property
+    def changed(self) -> bool:
+        if self.is_complete():
+            return self._did_change()
+        return self.will_change
 
     @property
-    def stdout_lines(self):
-        return self._get_lines(types=("stdout",))
+    def stdout_lines(self) -> list[str]:
+        self._raise_if_not_complete()
+        assert self._combined_output is not None
+        return self._combined_output.stdout_lines
 
     @property
-    def stderr_lines(self):
-        return self._get_lines(types=("stderr",))
+    def stderr_lines(self) -> list[str]:
+        self._raise_if_not_complete()
+        assert self._combined_output is not None
+        return self._combined_output.stderr_lines
 
     @property
     def stdout(self) -> str:
@@ -118,14 +147,6 @@ class OperationMeta:
     def stderr(self) -> str:
         return "\n".join(self.stderr_lines)
 
-    # TODO: deprecated, remove in v4
-    @property
-    def changed(self) -> int:
-        if not self.is_complete():
-            logger.warning("Checking changed before execution can give unexpected results")
-            return self._maybe_is_change
-        return self.did_change()
-
 
 def add_op(state: State, op_func, *args, **kwargs):
     """
@@ -164,6 +185,8 @@ P = ParamSpec("P")
 def operation(
     is_idempotent: bool = True,
     idempotent_notice: Optional[str] = None,
+    is_deprecated: bool = False,
+    deprecated_for: Optional[str] = None,
     _set_in_op: bool = True,
 ) -> Callable[[Callable[P, Generator]], PyinfraOperation[P]]:
     """
@@ -175,6 +198,8 @@ def operation(
     def decorator(f: Callable[P, Generator]) -> PyinfraOperation[P]:
         f.is_idempotent = is_idempotent  # type: ignore[attr-defined]
         f.idempotent_notice = idempotent_notice  # type: ignore[attr-defined]
+        f.is_deprecated = is_deprecated  # type: ignore[attr-defined]
+        f.deprecated_for = deprecated_for  # type: ignore[attr-defined]
         return _wrap_operation(f, _set_in_op=_set_in_op)
 
     return decorator
@@ -192,6 +217,15 @@ def _wrap_operation(func: Callable[P, Generator], _set_in_op: bool = True) -> Py
                 + "function to call the underlying operation."
             )
 
+        if func.is_deprecated:  # type: ignore[attr-defined]
+            if func.deprecated_for:  # type: ignore[attr-defined]
+                logger.warning(
+                    f"The {get_operation_name_from_func(func)} operation is "
+                    + f"deprecated, please use: {func.deprecated_for}",  # type: ignore[attr-defined] # noqa
+                )
+            else:
+                logger.warning(f"The {get_operation_name_from_func(func)} operation is deprecated")
+
         # Configure operation
         #
         # Get the meta kwargs (globals that apply to all hosts)
@@ -217,22 +251,30 @@ def _wrap_operation(func: Callable[P, Generator], _set_in_op: bool = True) -> Py
                     break
 
             if has_run:
-                return OperationMeta(op_hash)
+                return OperationMeta(op_hash, is_change=False)
+
+        # Grab a reference to any *current* deploy data as this may change when
+        # we later evaluate the operation at runtime.This means we put back the
+        # expected deploy data.
+        current_deploy_data = host.current_deploy_data
 
         # "Run" operation - here we make a generator that will yield out actual commands to execute
         # and, if we're diff-ing, we then iterate the generator now to determine if any changes
         # *would* be made based on the *current* remote state.
 
         def command_generator() -> Iterator[PyinfraCommand]:
-            # Check global _if_ argument function and do nothing if returns False
+            # Check global _if argument function and do nothing if returns False
             if state.is_executing:
-                _if = global_arguments.get("_if")
-                if _if and _if() is False:
+                _ifs = global_arguments.get("_if")
+                if isinstance(_ifs, list) and not all(_if() for _if in _ifs):
+                    return
+                elif callable(_ifs) and not _ifs():
                     return
 
             host.in_op = _set_in_op
             host.current_op_hash = op_hash
             host.current_op_global_arguments = global_arguments
+            host.current_op_deploy_data = current_deploy_data
 
             try:
                 for command in func(*args, **kwargs):
@@ -243,10 +285,12 @@ def _wrap_operation(func: Callable[P, Generator], _set_in_op: bool = True) -> Py
                 host.in_op = False
                 host.current_op_hash = None
                 host.current_op_global_arguments = None
+                host.current_op_deploy_data = None
 
-        op_is_change = False
+        op_is_change = None
         if state.should_check_for_changes():
-            for command in command_generator():
+            op_is_change = False
+            for _ in command_generator():
                 op_is_change = True
                 break
         else:
@@ -279,6 +323,15 @@ def _wrap_operation(func: Callable[P, Generator], _set_in_op: bool = True) -> Py
     return cast(PyinfraOperation[P], decorated_func)
 
 
+def get_operation_name_from_func(func):
+    if func.__module__:
+        module_bits = func.__module__.split(".")
+        module_name = module_bits[-1]
+        return "{0}.{1}".format(module_name, func.__name__)
+    else:
+        return func.__name__
+
+
 def generate_operation_name(func, host, kwargs, global_arguments):
     # Generate an operation name if needed (Module/Operation format)
     name = global_arguments.get("name")
@@ -287,14 +340,7 @@ def generate_operation_name(func, host, kwargs, global_arguments):
         names = {name}
     else:
         add_args = True
-
-        if func.__module__:
-            module_bits = func.__module__.split(".")
-            module_name = module_bits[-1]
-            name = "{0}/{1}".format(module_name.title(), func.__name__.title())
-        else:
-            name = func.__name__
-
+        name = get_operation_name_from_func(func)
         names = {name}
 
     if host.current_deploy_name:

pyinfra/api/operations.py

@@ -67,17 +67,16 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
     timeout = global_arguments.get("_timeout", 0)
 
     executor_kwarg_keys = CONNECTOR_ARGUMENT_KEYS
-    base_connector_arguments: ConnectorArguments = (
-        cast(  # https://github.com/python/mypy/issues/10371
-            ConnectorArguments,
-            {key: global_arguments[key] for key in executor_kwarg_keys if key in global_arguments},
-        )
+    # See: https://github.com/python/mypy/issues/10371
+    base_connector_arguments: ConnectorArguments = cast(
+        ConnectorArguments,
+        {key: global_arguments[key] for key in executor_kwarg_keys if key in global_arguments},  # type: ignore[literal-required] # noqa
     )
 
     did_error = False
     executed_commands = 0
     commands = []
-    all_combined_output_lines: list[OutputLine] = []
+    all_output_lines: list[OutputLine] = []
 
     for command in op_data.command_generator():
         commands.append(command)
@@ -103,19 +102,19 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
                 )
 
         elif isinstance(command, StringCommand):
-            combined_output_lines = CommandOutput([])
+            output_lines = CommandOutput([])
             try:
-                status, combined_output_lines = command.execute(
+                status, output_lines = command.execute(
                     state,
                     host,
                     connector_arguments,
                 )
             except (timeout_error, socket_error, SSHException) as e:
                 log_host_command_error(host, e, timeout=timeout)
-            all_combined_output_lines.extend(combined_output_lines)
+            all_output_lines.extend(output_lines)
             # If we failed and have not already printed the stderr, print it
             if status is False and not state.print_output:
-                print_host_combined_output(host, combined_output_lines)
+                print_host_combined_output(host, output_lines)
 
         else:
             try:
@@ -170,7 +169,7 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
     op_data.operation_meta.set_complete(
         op_success,
         commands,
-        all_combined_output_lines,
+        CommandOutput(all_output_lines),
     )
 
     return return_status

pyinfra/api/state.py

@@ -344,10 +344,19 @@ class State:
     def get_results_for_host(self, host: "Host") -> StateHostResults:
         return self.results[host]
 
-    def get_op_data_for_host(self, host: "Host", op_hash: str):
+    def get_op_data_for_host(
+        self,
+        host: "Host",
+        op_hash: str,
+    ) -> StateOperationHostData:
         return self.ops[host][op_hash]
 
-    def set_op_data_for_host(self, host: "Host", op_hash: str, op_data: StateOperationHostData):
+    def set_op_data_for_host(
+        self,
+        host: "Host",
+        op_hash: str,
+        op_data: StateOperationHostData,
+    ):
         self.ops[host][op_hash] = op_data
 
     def activate_host(self, host: "Host"):

pyinfra/api/util.py

@@ -109,16 +109,16 @@ def get_caller_frameinfo(frame_offset: int = 0):
 
 
 def get_operation_order_from_stack(state: "State"):
+
     stack_items = list(reversed(stack()))
 
+    i = 0
     # Find the *first* occurrence of our deploy file in the reversed stack
     if state.current_deploy_filename:
         for i, stack_item in enumerate(stack_items):
             frame = getframeinfo(stack_item[0])
             if frame.filename == state.current_deploy_filename:
                 break
-    else:
-        i = 0
 
     # Now generate a list of line numbers *following that file*
     line_numbers = []
@@ -139,7 +139,7 @@ def get_operation_order_from_stack(state: "State"):
     return line_numbers
 
 
-def get_template(filename_or_io: str):
+def get_template(filename_or_io: str | IO):
     """
     Gets a jinja2 ``Template`` object for the input filename or string, with caching
     based on the filename of the template, or the SHA1 of the input string.
@@ -301,19 +301,27 @@ def make_hash(obj):
             if isinstance(obj, int)
             # Constants - the values can change between hosts but we should still
             # group them under the same operation hash.
-            else "_PYINFRA_CONSTANT"
-            if obj in (True, False, None)
-            # Plain strings
-            else obj
-            if isinstance(obj, str)
-            # Objects with __name__s
-            else obj.__name__
-            if hasattr(obj, "__name__")
-            # Objects with names
-            else obj.name
-            if hasattr(obj, "name")
-            # Repr anything else
-            else repr(obj)
+            else (
+                "_PYINFRA_CONSTANT"
+                if obj in (True, False, None)
+                # Plain strings
+                else (
+                    obj
+                    if isinstance(obj, str)
+                    # Objects with __name__s
+                    else (
+                        obj.__name__
+                        if hasattr(obj, "__name__")
+                        # Objects with names
+                        else (
+                            obj.name
+                            if hasattr(obj, "name")
+                            # Repr anything else
+                            else repr(obj)
+                        )
+                    )
+                )
+            )
         )
 
     return sha1_hash(hash_string)

pyinfra/connectors/base.py

@@ -84,7 +84,7 @@ class BaseConnector(abc.ABC):
 
     @staticmethod
     @abc.abstractmethod
-    def make_names_data(id: str) -> Iterator[tuple[str, dict, list[str]]]:
+    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.
@@ -108,8 +108,7 @@ class BaseConnector(abc.ABC):
         print_output: bool,
         print_input: bool,
         **arguments: Unpack["ConnectorArguments"],
-    ) -> tuple[bool, "CommandOutput"]:
-        ...
+    ) -> tuple[bool, "CommandOutput"]: ...
 
     @abc.abstractmethod
     def put_file(
@@ -120,8 +119,7 @@ class BaseConnector(abc.ABC):
         print_output: bool = False,
         print_input: bool = False,
         **arguments: Unpack["ConnectorArguments"],
-    ) -> bool:
-        ...
+    ) -> bool: ...
 
     @abc.abstractmethod
     def get_file(
@@ -132,8 +130,7 @@ class BaseConnector(abc.ABC):
         print_output: bool = False,
         print_input: bool = False,
         **arguments: Unpack["ConnectorArguments"],
-    ) -> bool:
-        ...
+    ) -> bool: ...
 
     def check_can_rsync(self):
         raise NotImplementedError("This connector does not support rsync")

pyinfra/connectors/chroot.py

@@ -40,17 +40,17 @@ class ChrootConnector(BaseConnector):
         self.local = LocalConnector(state, host)
 
     @staticmethod
-    def make_names_data(directory: Optional[str] = None):
-        if not directory:
+    def make_names_data(name: Optional[str] = None):
+        if not name:
             raise InventoryError("No directory provided!")
 
         show_warning()
 
-        yield "@chroot/{0}".format(directory), {
-            "chroot_directory": "/{0}".format(directory.lstrip("/")),
+        yield "@chroot/{0}".format(name), {
+            "chroot_directory": "/{0}".format(name.lstrip("/")),
         }, ["@chroot"]
 
-    def connect(self):
+    def connect(self) -> None:
         self.local.connect()
 
         chroot_directory = self.host.data.chroot_directory
@@ -65,7 +65,6 @@ class ChrootConnector(BaseConnector):
             raise ConnectError(e.args[0])
 
         self.host.connector_data["chroot_directory"] = chroot_directory
-        return True
 
     def run_shell_command(
         self,

pyinfra/connectors/docker.py

@@ -24,7 +24,7 @@ if TYPE_CHECKING:
     from pyinfra.api.state import State
 
 
-class ConnectorData(TypedDict, total=False):
+class ConnectorData(TypedDict):
     docker_identifier: str
 
 
@@ -35,6 +35,7 @@ connector_data_meta: dict[str, DataMeta] = {
 
 def _find_start_docker_container(container_id) -> tuple[str, bool]:
     docker_info = local.shell("docker container inspect {0}".format(container_id))
+    assert isinstance(docker_info, str)
     docker_info = json.loads(docker_info)[0]
     if docker_info["State"]["Running"] is False:
         logger.info("Starting stopped container: {0}".format(container_id))
@@ -60,8 +61,10 @@ 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:
 
-    + 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
+    + 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
 
@@ -91,17 +94,17 @@ class DockerConnector(BaseConnector):
         self.local = LocalConnector(state, host)
 
     @staticmethod
-    def make_names_data(identifier=None):
-        if not identifier:
+    def make_names_data(name=None):
+        if not name:
             raise InventoryError("No docker base ID provided!")
 
         yield (
-            "@docker/{0}".format(identifier),
-            {"docker_identifier": identifier},
+            "@docker/{0}".format(name),
+            {"docker_identifier": name},
             ["@docker"],
         )
 
-    def connect(self):
+    def connect(self) -> None:
         self.local.connect()
 
         docker_identifier = self.data["docker_identifier"]
@@ -113,8 +116,6 @@ class DockerConnector(BaseConnector):
             except PyinfraError:
                 self.container_id = _start_docker_image(docker_identifier)
 
-        return True
-
     def disconnect(self):
         container_id = self.container_id
 
@@ -264,17 +265,10 @@ class DockerConnector(BaseConnector):
             )
 
             # Load the temporary file and write it to our file or IO object
-            with open(temp_filename, encoding="utf-8") as temp_f:
+            with open(temp_filename, "rb") as temp_f:
                 with get_file_io(filename_or_io, "wb") as file_io:
                     data = temp_f.read()
-                    data_bytes: bytes
-
-                    if isinstance(data, str):
-                        data_bytes = data.encode()
-                    else:
-                        data_bytes = data
-
-                    file_io.write(data_bytes)
+                    file_io.write(data)
         finally:
             os.close(fd)
             os.remove(temp_filename)

pyinfra/connectors/dockerssh.py

@@ -30,7 +30,8 @@ class DockerSSHConnector(BaseConnector):
     """
     **Note**: this connector is in beta!
 
-    The ``@dockerssh`` connector allows you to run commands on Docker containers on a remote machine.
+    The ``@dockerssh`` connector allows you to run commands on Docker containers \
+    on a remote machine.
 
     .. code:: shell
 
@@ -50,10 +51,10 @@ class DockerSSHConnector(BaseConnector):
         self.ssh = SSHConnector(state, host)
 
     @staticmethod
-    def make_names_data(host_image_str):
+    def make_names_data(name):
         try:
-            hostname, image = host_image_str.split(":", 1)
-        except (AttributeError, ValueError):  # failure to parse the host_image_str
+            hostname, image = name.split(":", 1)
+        except (AttributeError, ValueError):  # failure to parse the name
             raise InventoryError("No ssh host or docker base image provided!")
 
         if not image:

pyinfra/connectors/local.py

@@ -1,5 +1,5 @@
 import os
-from distutils.spawn import find_executable
+from shutil import which
 from tempfile import mkstemp
 from typing import TYPE_CHECKING, Tuple
 
@@ -25,7 +25,8 @@ if TYPE_CHECKING:
 
 class LocalConnector(BaseConnector):
     """
-    The ``@local`` connector executes changes on the local machine using subprocesses. **This connector is only compatible with MacOS & Linux hosts**.
+    The ``@local`` connector executes changes on the local machine using
+    subprocesses. **This connector is only compatible with MacOS & Linux hosts**.
 
     Examples:
 
@@ -38,8 +39,8 @@ class LocalConnector(BaseConnector):
     handles_execution = True
 
     @staticmethod
-    def make_names_data(_=None):
-        if _ is not None:
+    def make_names_data(name=None):
+        if name is not None:
             raise InventoryError("Cannot have more than one @local")
 
         yield "@local", {}, ["@local"]
@@ -205,9 +206,8 @@ class LocalConnector(BaseConnector):
 
         return True
 
-    @staticmethod
-    def check_can_rsync(host):
-        if not find_executable("rsync"):
+    def check_can_rsync(self):
+        if not which("rsync"):
             raise NotImplementedError("The `rsync` binary is not available on this system.")
 
     def rsync(