pyinfra 3.4__tar.gz → 3.5__tar.gz

{pyinfra-3.4 → pyinfra-3.5}/CHANGELOG.md

@@ -1,3 +1,37 @@
+# v3.5
+
+New release with some really awesome new features, brought to you by the fantastic contributions of the community. New stuff:
+
+- add `--diff` argument to show file diffs for potential file changes (@jgelens)
+- add `_retries`, `_retry_delay` and `_retry_until` global arguments (@shohamd4)
+- parallelize disconnecting from hosts (@gwelch-contegix)
+- enable using SCP instead of SFTP for SSH file transfers (@DonDebonair)
+
+New and updated operations/facts:
+- facts/server: add `RebootRequired` fact (@wowi42)
+- operations/pip: support PEP-508 package versions (@morrison12)
+- operations+facts/docker: add Docker plugin support (@DonDebonair)
+- operations/files.put: add `atime` and `mtime` arguments (@vram0gh2)
+- operations/openrc: support runlevel when enabling services (@sengo4hd)
+- facts/yum+dnf+zypper: return `repoid` in repository facts
+
+Operation/fact fixes:
+
+- facts/files.File: add ls fallback support (@mrkbac)
+- operations/openrc: add missing noop messages (@sengo4hd)
+- operations/server.crontab: fix newline when replacing existing values (@Nananas)
+- operations/files.block: fix examples doc (@morrison12)
+- operations/files.block: fix case where file exists but line is missing (@morrison12)
+- operations/files.block: improve handling of special characters in marker lines (@morrison12)
+
+Internal/meta:
+
+- documentation link fix (@sengo4hd)
+
+# v3.4.1
+
+- fix config context when getting operation arguments
+
 # v3.4
 
 Much delayed 3.4, great collection of additions and improvements. Huge THANK YOU to all contributors as always. New features:
@@ -27,7 +61,7 @@ Operation/fact fixes:
 
 Internal/meta:
 
-- remove unncessary setuptools runtime dependency (@karlicoss)
+- remove unnecessary setuptools runtime dependency (@karlicoss)
 
 # v3.3.1
 

{pyinfra-3.4/pyinfra.egg-info → pyinfra-3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyinfra
-Version: 3.4
+Version: 3.5
 Summary: pyinfra automates/provisions/manages/deploys infrastructure.
 Home-page: https://pyinfra.com
 Author: Nick / Fizzadar
@@ -52,7 +52,7 @@ Requires-Dist: flake8-isort==6.1.2; extra == "test"
 Requires-Dist: pyyaml==6.0.2; extra == "test"
 Requires-Dist: mypy; extra == "test"
 Requires-Dist: types-cryptography; extra == "test"
-Requires-Dist: types-paramiko; extra == "test"
+Requires-Dist: types-paramiko<4; extra == "test"
 Requires-Dist: types-python-dateutil; extra == "test"
 Requires-Dist: types-PyYAML; extra == "test"
 Provides-Extra: docs
@@ -73,7 +73,7 @@ Requires-Dist: flake8-isort==6.1.2; extra == "dev"
 Requires-Dist: pyyaml==6.0.2; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: types-cryptography; extra == "dev"
-Requires-Dist: types-paramiko; extra == "dev"
+Requires-Dist: types-paramiko<4; extra == "dev"
 Requires-Dist: types-python-dateutil; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Requires-Dist: pyinfra-guzzle_sphinx_theme==0.17; extra == "dev"

{pyinfra-3.4 → pyinfra-3.5}/pyinfra/api/arguments.py

@@ -72,6 +72,11 @@ class ConnectorArguments(TypedDict, total=False):
     _get_pty: bool
     _stdin: Union[str, Iterable[str]]
 
+    # Retry arguments
+    _retries: int
+    _retry_delay: Union[int, float]
+    _retry_until: Optional[Callable[[dict], bool]]
+
 
 def generate_env(config: "Config", value: dict) -> dict:
     env = config.ENV.copy()
@@ -232,11 +237,28 @@ def all_global_arguments() -> List[tuple[str, Type]]:
     return list(get_type_hints(AllArguments).items())
 
 
+# Create a dictionary for retry arguments
+retry_argument_meta: dict[str, ArgumentMeta] = {
+    "_retries": ArgumentMeta(
+        "Number of times to retry failed operations.",
+        default=lambda config: config.RETRY,
+    ),
+    "_retry_delay": ArgumentMeta(
+        "Delay in seconds between retry attempts.",
+        default=lambda config: config.RETRY_DELAY,
+    ),
+    "_retry_until": ArgumentMeta(
+        "Callable taking output data that returns True to continue retrying.",
+        default=lambda config: None,
+    ),
+}
+
 all_argument_meta: dict[str, ArgumentMeta] = {
     **auth_argument_meta,
     **shell_argument_meta,
     **meta_argument_meta,
     **execution_argument_meta,
+    **retry_argument_meta,  # Add retry arguments
 }
 
 EXECUTION_KWARG_KEYS = list(ExecutionArguments.__annotations__.keys())
@@ -286,6 +308,45 @@ __argument_docs__ = {
     ),
     "Operation meta & callbacks": (meta_argument_meta, "", ""),
     "Execution strategy": (execution_argument_meta, "", ""),
+    "Retry behavior": (
+        retry_argument_meta,
+        """
+        Retry arguments allow you to automatically retry operations that fail. You can specify
+        how many times to retry, the delay between retries, and optionally a condition
+        function to determine when to stop retrying.
+        """,
+        """
+        .. code:: python
+
+            # Retry a command up to 3 times with the default 5 second delay
+            server.shell(
+                name="Run flaky command with retries",
+                commands=["flaky_command"],
+                _retries=3,
+            )
+            # Retry with a custom delay
+            server.shell(
+                name="Run flaky command with custom delay",
+                commands=["flaky_command"],
+                _retries=2,
+                _retry_delay=10,  # 10 second delay between retries
+            )
+            # Retry with a custom condition
+            def retry_on_specific_error(output_data):
+                # Retry if stderr contains "temporary failure"
+                for line in output_data["stderr_lines"]:
+                    if "temporary failure" in line.lower():
+                        return True
+                return False
+
+            server.shell(
+                name="Run command with conditional retry",
+                commands=["flaky_command"],
+                _retries=5,
+                _retry_until=retry_on_specific_error,
+            )
+        """,
+    ),
 }
 
 
@@ -305,7 +366,8 @@ def pop_global_arguments(
 
     config = state.config
     if ctx_config.isset():
-        config = config
+        config = ctx_config.get()
+        assert config is not None
 
     cdkwargs = host.current_deploy_kwargs
     meta_kwargs: dict[str, Any] = cdkwargs or {}  # type: ignore[assignment]

{pyinfra-3.4 → pyinfra-3.5}/pyinfra/api/config.py

@@ -53,6 +53,12 @@ class ConfigDefaults:
     IGNORE_ERRORS: bool = False
     # Shell to use to execute commands
     SHELL: str = "sh"
+    # Whether to display full diffs for files
+    DIFF: bool = False
+    # Number of times to retry failed operations
+    RETRY: int = 0
+    # Delay in seconds between retry attempts
+    RETRY_DELAY: int = 5
 
 
 config_defaults = {key: value for key, value in ConfigDefaults.__dict__.items() if key.isupper()}

{pyinfra-3.4 → pyinfra-3.5}/pyinfra/api/connect.py

@@ -46,5 +46,22 @@ def connect_all(state: "State"):
 
 
 def disconnect_all(state: "State"):
-    for host in state.activated_hosts:  # only hosts we connected to please!
-        host.disconnect()  # normally a noop
+    """
+    Disconnect from all of the configured servers in parallel. Reads/writes state.inventory.
+
+    Args:
+        state (``pyinfra.api.State`` obj): the state containing an inventory to connect to
+    """
+    greenlet_to_host = {
+        state.pool.spawn(host.disconnect): host
+        for host in state.activated_hosts  # only hosts we connected to please!
+    }
+
+    with progress_spinner(greenlet_to_host.values()) as progress:
+        for greenlet in gevent.iwait(greenlet_to_host.keys()):
+            host = greenlet_to_host[greenlet]
+            progress(host)
+
+    for greenlet, host in greenlet_to_host.items():
+        # Raise any unexpected exception
+        greenlet.get()

{pyinfra-3.4 → pyinfra-3.5}/pyinfra/api/operation.py

@@ -47,6 +47,9 @@ class OperationMeta:
     _commands: Optional[list[Any]] = None
     _maybe_is_change: Optional[bool] = None
     _success: Optional[bool] = None
+    _retry_attempts: int = 0
+    _max_retries: int = 0
+    _retry_succeeded: Optional[bool] = None
 
     def __init__(self, hash, is_change: Optional[bool]):
         self._hash = hash
@@ -59,9 +62,17 @@ class OperationMeta:
         """
 
         if self._commands is not None:
+            retry_info = ""
+            if self._retry_attempts > 0:
+                retry_result = "succeeded" if self._retry_succeeded else "failed"
+                retry_info = (
+                    f", retries={self._retry_attempts}/{self._max_retries} ({retry_result})"
+                )
+
             return (
                 "OperationMeta(executed=True, "
-                f"success={self.did_succeed()}, hash={self._hash}, commands={len(self._commands)})"
+                f"success={self.did_succeed()}, hash={self._hash}, "
+                f"commands={len(self._commands)}{retry_info})"
             )
         return (
             "OperationMeta(executed=False, "
@@ -74,12 +85,20 @@ class OperationMeta:
         success: bool,
         commands: list[Any],
         combined_output: "CommandOutput",
+        retry_attempts: int = 0,
+        max_retries: int = 0,
     ) -> None:
         if self.is_complete():
             raise RuntimeError("Cannot complete an already complete operation")
         self._success = success
         self._commands = commands
         self._combined_output = combined_output
+        self._retry_attempts = retry_attempts
+        self._max_retries = max_retries
+
+        # Determine if operation succeeded after retries
+        if retry_attempts > 0:
+            self._retry_succeeded = success
 
     def is_complete(self) -> bool:
         return self._success is not None
@@ -150,6 +169,40 @@ class OperationMeta:
     def stderr(self) -> str:
         return "\n".join(self.stderr_lines)
 
+    @property
+    def retry_attempts(self) -> int:
+        return self._retry_attempts
+
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries
+
+    @property
+    def was_retried(self) -> bool:
+        """
+        Returns whether this operation was retried at least once.
+        """
+        return self._retry_attempts > 0
+
+    @property
+    def retry_succeeded(self) -> Optional[bool]:
+        """
+        Returns whether this operation succeeded after retries.
+        Returns None if the operation was not retried.
+        """
+        return self._retry_succeeded
+
+    def get_retry_info(self) -> dict[str, Any]:
+        """
+        Returns a dictionary with all retry-related information.
+        """
+        return {
+            "retry_attempts": self._retry_attempts,
+            "max_retries": self._max_retries,
+            "was_retried": self.was_retried,
+            "retry_succeeded": self._retry_succeeded,
+        }
+
 
 def add_op(state: State, op_func, *args, **kwargs):
     """

{pyinfra-3.4 → pyinfra-3.5}/pyinfra/api/operations.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import time
 import traceback
 from itertools import product
 from socket import error as socket_error, timeout as timeout_error
@@ -66,6 +67,11 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
     continue_on_error = global_arguments["_continue_on_error"]
     timeout = global_arguments.get("_timeout", 0)
 
+    # Extract retry arguments
+    retries = global_arguments.get("_retries", 0)
+    retry_delay = global_arguments.get("_retry_delay", 5)
+    retry_until = global_arguments.get("_retry_until", None)
+
     executor_kwarg_keys = CONNECTOR_ARGUMENT_KEYS
     # See: https://github.com/python/mypy/issues/10371
     base_connector_arguments: ConnectorArguments = cast(
@@ -73,67 +79,114 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
         {key: global_arguments[key] for key in executor_kwarg_keys if key in global_arguments},  # type: ignore[literal-required] # noqa
     )
 
+    retry_attempt = 0
     did_error = False
     executed_commands = 0
-    commands = []
+    commands: list[PyinfraCommand] = []
     all_output_lines: list[OutputLine] = []
 
-    for command in op_data.command_generator():
-        commands.append(command)
-
-        status = False
-
-        connector_arguments = base_connector_arguments.copy()
-        connector_arguments.update(command.connector_arguments)
-
-        if not isinstance(command, PyinfraCommand):
-            raise TypeError("{0} is an invalid pyinfra command!".format(command))
-
-        if isinstance(command, FunctionCommand):
-            try:
-                status = command.execute(state, host, connector_arguments)
-            except Exception as e:
-                # Custom functions could do anything, so expect anything!
-                logger.warning(traceback.format_exc())
-                host.log_styled(
-                    f"Unexpected error in Python callback: {format_exception(e)}",
-                    fg="red",
-                    log_func=logger.warning,
-                )
-
-        elif isinstance(command, StringCommand):
-            output_lines = CommandOutput([])
-            try:
-                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_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, output_lines)
-
-        else:
-            try:
-                status = command.execute(state, host, connector_arguments)
-            except (timeout_error, socket_error, SSHException, IOError) as e:
-                log_host_command_error(host, e, timeout=timeout)
-
-        # Break the loop to trigger a failure
-        if status is False:
-            did_error = True
-            if continue_on_error is True:
-                continue
-            break
+    # Retry loop
+    while retry_attempt <= retries:
+        did_error = False
+        executed_commands = 0
+        commands = []
+        all_output_lines = []
+
+        for command in op_data.command_generator():
+            commands.append(command)
+            status = False
+            connector_arguments = base_connector_arguments.copy()
+            connector_arguments.update(command.connector_arguments)
+
+            if not isinstance(command, PyinfraCommand):
+                raise TypeError("{0} is an invalid pyinfra command!".format(command))
+
+            if isinstance(command, FunctionCommand):
+                try:
+                    status = command.execute(state, host, connector_arguments)
+                except Exception as e:
+                    # Custom functions could do anything, so expect anything!
+                    logger.warning(traceback.format_exc())
+                    host.log_styled(
+                        f"Unexpected error in Python callback: {format_exception(e)}",
+                        fg="red",
+                        log_func=logger.warning,
+                    )
+
+            elif isinstance(command, StringCommand):
+                output_lines = CommandOutput([])
+                try:
+                    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_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, output_lines)
+
+            else:
+                try:
+                    status = command.execute(state, host, connector_arguments)
+                except (timeout_error, socket_error, SSHException, IOError) as e:
+                    log_host_command_error(host, e, timeout=timeout)
+
+            # Break the loop to trigger a failure
+            if status is False:
+                did_error = True
+                if continue_on_error is True:
+                    continue
+                break
+
+            executed_commands += 1
+
+        # Check if we should retry
+        should_retry = False
+        if retry_attempt < retries:
+            # Retry on error
+            if did_error:
+                should_retry = True
+            # Retry on condition if no error
+            elif retry_until and not did_error:
+                try:
+                    output_data = {
+                        "stdout_lines": [
+                            line.line for line in all_output_lines if line.buffer_name == "stdout"
+                        ],
+                        "stderr_lines": [
+                            line.line for line in all_output_lines if line.buffer_name == "stderr"
+                        ],
+                        "commands": [str(command) for command in commands],
+                        "executed_commands": executed_commands,
+                        "host": host.name,
+                        "operation": ", ".join(state.get_op_meta(op_hash).names) or "Operation",
+                    }
+                    should_retry = retry_until(output_data)
+                except Exception as e:
+                    host.log_styled(
+                        f"Error in retry_until function: {format_exception(e)}",
+                        fg="red",
+                        log_func=logger.warning,
+                    )
+
+        if should_retry:
+            retry_attempt += 1
+            state.trigger_callbacks("operation_host_retry", host, op_hash, retry_attempt, retries)
+            op_name = ", ".join(state.get_op_meta(op_hash).names) or "Operation"
+            host.log_styled(
+                f"Retrying {op_name} (attempt {retry_attempt}/{retries}) after {retry_delay}s...",
+                fg="yellow",
+                log_func=logger.info,
+            )
+            time.sleep(retry_delay)
+            continue
 
-        executed_commands += 1
+        break
 
     # Handle results
-    #
-
     op_success = return_status = not did_error
     host_results = state.get_results_for_host(host)
 
@@ -142,10 +195,13 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
         host_results.success_ops += 1
 
         _status_log = "Success" if executed_commands > 0 else "No changes"
+        if retry_attempt > 0:
+            _status_log = f"{_status_log} on retry {retry_attempt}"
+
         _click_log_status = click.style(_status_log, "green")
         logger.info("{0}{1}".format(host.print_prefix, _click_log_status))
 
-        state.trigger_callbacks("operation_host_success", host, op_hash)
+        state.trigger_callbacks("operation_host_success", host, op_hash, retry_attempt)
     else:
         if ignore_errors:
             host_results.ignored_error_ops += 1
@@ -156,6 +212,11 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
             host_results.partial_ops += 1
 
         _command_description = f"executed {executed_commands} commands"
+        if retry_attempt > 0:
+            _command_description = (
+                f"{_command_description} (failed after {retry_attempt}/{retries} retries)"
+            )
+
         log_error_or_warning(host, ignore_errors, _command_description, continue_on_error)
 
         # Ignored, op "completes" w/ ignored error
@@ -164,12 +225,14 @@ def _run_host_op(state: "State", host: "Host", op_hash: str) -> Optional[bool]:
             return_status = True
 
         # Unignored error -> False
-        state.trigger_callbacks("operation_host_error", host, op_hash)
+        state.trigger_callbacks("operation_host_error", host, op_hash, retry_attempt, retries)
 
     op_data.operation_meta.set_complete(
         op_success,
         commands,
         CommandOutput(all_output_lines),
+        retry_attempts=retry_attempt,
+        max_retries=retries,
     )
 
     return return_status

{pyinfra-3.4 → pyinfra-3.5}/pyinfra/api/state.py

@@ -70,11 +70,19 @@ class BaseStateCallback:
         pass
 
     @staticmethod
-    def operation_host_success(state: "State", host: "Host", op_hash):
+    def operation_host_success(state: "State", host: "Host", op_hash, retry_count: int = 0):
         pass
 
     @staticmethod
-    def operation_host_error(state: "State", host: "Host", op_hash):
+    def operation_host_error(
+        state: "State", host: "Host", op_hash, retry_count: int = 0, max_retries: int = 0
+    ):
+        pass
+
+    @staticmethod
+    def operation_host_retry(
+        state: "State", host: "Host", op_hash, retry_num: int, max_retries: int
+    ):
         pass
 
     @staticmethod

pyinfra-3.5/pyinfra/connectors/scp/__init__.py

@@ -0,0 +1 @@
+from .client import SCPClient  # noqa: F401