pyinfra 0.11.dev3__py3-none-any.whl → 3.6__py3-none-any.whl

pyinfra/api/deploy.py

@@ -1,22 +1,30 @@
-'''
+"""
 Deploys come in two forms: on-disk, eg deploy.py, and @deploy wrapped functions.
 The latter enable re-usable (across CLI and API based execution) pyinfra extension
 creation (eg pyinfra-openstack).
-'''
+"""
 
 from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Optional, cast
 
-from pyinfra import logger, pseudo_host, pseudo_state
-from pyinfra.pseudo_modules import PseudoModule
+from typing_extensions import ParamSpec
 
+import pyinfra
+from pyinfra import context
+from pyinfra.context import ctx_host, ctx_state
+
+from .arguments import pop_global_arguments
+from .arguments_typed import PyinfraOperation
 from .exceptions import PyinfraError
 from .host import Host
-from .state import State
-from .util import get_caller_frameinfo, pop_op_kwargs
+from .util import get_call_location
+
+if TYPE_CHECKING:
+    from pyinfra.api.state import State
 
 
-def add_deploy(state, deploy_func, *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.
 
     Args:
@@ -24,75 +32,66 @@ def add_deploy(state, deploy_func, *args, **kwargs):
         deploy_func (function): the operation function from one of the modules,
         ie ``server.user``
         args/kwargs: passed to the operation function
-    '''
+    """
+
+    if pyinfra.is_cli:
+        raise PyinfraError(
+            (
+                "`add_deploy` should not be called when pyinfra is executing in CLI mode! ({0})"
+            ).format(get_call_location()),
+        )
+
+    hosts = kwargs.pop("host", state.inventory.iter_active_hosts())
+    if isinstance(hosts, Host):
+        hosts = [hosts]
 
-    frameinfo = get_caller_frameinfo()
-    kwargs['frameinfo'] = frameinfo
+    with ctx_state.use(state):
+        for deploy_host in hosts:
+            with ctx_host.use(deploy_host):
+                deploy_func(*args, **kwargs)
 
-    for host in state.inventory:
-        deploy_func(state, host, *args, **kwargs)
 
+P = ParamSpec("P")
 
-def deploy(func_or_name, 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.
-    '''
+    """
 
-    # If not decorating, return function with config attached
-    if isinstance(func_or_name, str):
-        name = func_or_name
+    if name and not isinstance(name, str):
+        raise PyinfraError(
+            (
+                "The `deploy` decorator must be called, ie `@deploy()`, "
+                "see: https://docs.pyinfra.com/en/3.x/compatibility.html#upgrading-pyinfra-from-2-x-3-x"  # noqa
+            )
+        )
 
-        def decorator(f):
-            setattr(f, 'deploy_name', name)
+    def decorator(func: Callable[P, Any]) -> PyinfraOperation[P]:
+        func.deploy_name = name or func.__name__  # type: ignore[attr-defined]
+        if data_defaults:
+            func.deploy_data = data_defaults  # type: ignore[attr-defined]
+        return _wrap_deploy(func)
 
-            if data_defaults:
-                setattr(f, 'deploy_data', data_defaults)
+    return decorator
 
-            return deploy(f)
 
-        return decorator
+def _wrap_deploy(func: Callable[P, Any]) -> PyinfraOperation[P]:
+    @wraps(func)
+    def decorated_func(*args: P.args, **kwargs: P.kwargs) -> Any:
+        deploy_kwargs, _ = pop_global_arguments(context.state, context.host, kwargs)
 
-    # Actually decorate!
-    func = func_or_name
+        deploy_data = getattr(func, "deploy_data", None)
 
-    @wraps(func)
-    def decorated_func(*args, **kwargs):
-        # If we're in CLI mode, there's no state/host passed down, we need to
-        # use the global "pseudo" modules.
-        if len(args) < 2 or not (
-            isinstance(args[0], (State, PseudoModule))
-            and isinstance(args[1], (Host, PseudoModule))
+        with context.host.deploy(
+            name=func.deploy_name,  # type: ignore[attr-defined]
+            kwargs=deploy_kwargs,
+            data=deploy_data,
         ):
-            state = pseudo_state._module
-            host = pseudo_host._module
-
-            if state.in_deploy:
-                raise PyinfraError((
-                    'Nested deploy called without state/host: {0}'
-                ).format(func))
-
-        # Otherwise (API mode) we just trim off the commands
-        else:
-            args_copy = list(args)
-            state, host = args[0], args[1]
-            args = args_copy[2:]
-
-        # In API mode we have the kwarg - if a nested deploy we actually
-        # want the frame of the caller (ie inside the deploy package).
-        frameinfo = kwargs.pop('frameinfo', get_caller_frameinfo())
-        logger.debug('Adding deploy, called @ {0}:{1}'.format(
-            frameinfo.filename, frameinfo.lineno,
-        ))
-
-        deploy_kwargs = pop_op_kwargs(state, kwargs)
-
-        # Name the deploy
-        deploy_name = getattr(func, 'deploy_name', func.__name__)
-        deploy_data = getattr(func, 'deploy_data', None)
-
-        with state.deploy(deploy_name, deploy_kwargs, deploy_data, frameinfo.lineno):
-            # Execute the deploy, passing state and host
-            func(state, host, *args, **kwargs)
-
-    return decorated_func
+            return func(*args, **kwargs)
+
+    decorated_func._inner = func  # type: ignore[attr-defined]
+    return cast(PyinfraOperation[P], decorated_func)

pyinfra/api/exceptions.py

@@ -1,41 +1,96 @@
 class PyinfraError(Exception):
-    '''
+    """
     Generic pyinfra exception.
-    '''
+    """
+
+
+class ConnectError(PyinfraError):
+    """
+    Exception raised when connecting fails.
+    """
+
+
+class FactError(PyinfraError):
+    """
+    Exception raised during fact gathering staging if a fact is unable to
+    generate output/change state.
+    """
+
+
+class FactTypeError(FactError, TypeError):
+    """
+    Exception raised when a fact is passed invalid argument types.
+    """
+
+
+class FactValueError(FactError, ValueError):
+    """
+    Exception raised when a fact is passed invalid argument values.
+    """
+
+
+class FactProcessError(FactError, RuntimeError):
+    """
+    Exception raised when the data gathered for a fact cannot be processed.
+    """
 
 
 class OperationError(PyinfraError):
-    '''
+    """
     Exception raised during fact gathering staging if an operation is unable to
     generate output/change state.
-    '''
+    """
+
+
+class OperationTypeError(OperationError, TypeError):
+    """
+    Exception raised when an operation is passed invalid argument types.
+    """
+
+
+class OperationValueError(OperationError, ValueError):
+    """
+    Exception raised when an operation is passed invalid argument values.
+    """
 
 
 class DeployError(PyinfraError):
-    '''
+    """
     User exception for raising in deploys or sub deploys.
-    '''
+    """
 
 
 class InventoryError(PyinfraError):
-    '''
+    """
     Exception raised for inventory related errors.
-    '''
+    """
 
 
-class NoConnectorError(PyinfraError, TypeError):
-    '''
+class NoConnectorError(PyinfraError, ValueError):
+    """
     Raised when a requested connector is missing.
-    '''
+    """
 
 
-class NoHostError(PyinfraError, TypeError):
-    '''
+class NoHostError(PyinfraError, KeyError):
+    """
     Raised when an inventory is missing a host.
-    '''
+    """
+
+
+class NoGroupError(PyinfraError, KeyError):
+    """
+    Raised when an inventory is missing a group.
+    """
+
+
+class ConnectorDataTypeError(PyinfraError, TypeError):
+    """
+    Raised when host connector data has invalid types.
+    """
 
 
-class NoGroupError(PyinfraError, TypeError):
-    '''
-    Raise when an inventory is missing a group.
-    '''
+class ArgumentTypeError(PyinfraError, TypeError):
+    """
+    Raised when global arguments are passed with invalid types.
+    """