pyinfra 2.9.2__tar.gz → 3.0__tar.gz

pyinfra-3.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# v3.0
+
+Welcome to pyinfra v3! This version is the biggest overhaul of pyinfra since it was created back in 2015. Most v2 deployment code should be automatically compatible, but as always be aware. Major changes:
+
+### Runtime operation execution
+
+pyinfra now executes operations at runtime, rather than pre-generating commands. Although the change isn't noticeable this fixes an entire class of bugs and confusion. See the [limitations](https://docs.pyinfra.com/en/2.x/deploy-process.html#limitations) section in the v2 docs. All of those issues are now a thing of the past.
+
+This represents a huge overhaul of pyinfra's internals and should be a huge improvement for users.
+
+Care has been taken to reduce the overhead of this change which still supports the same diffs and change proposal mechanism.
+
+### CLI flow & prompts
+
+The pyinfra CLI will now prompt (instead of ignore, or immediately exit) when problems are encountered, allowing the user to choose to continue. Additionally an approval step is added before executing changes (this can be skipped with `-y` or setting the `PYINFRA_YES` environment variable).
+
+### Extendable connectors API, typing overhaul
+
+v3 of pyinfra includes for the first time a (mostly) typed internal API with proper support for IDE linting. There's a whole new connectors API that provides a framework for building new connectors.
+
+### Breaking changes
+
+- Rename `_use_sudo_password` argument to `_sudo_password`
+- Remove `winrm` connector and `windows*` operations/facts, moving to [`pyinfra-windows`](https://github.com/pyinfra-dev/pyinfra-windows)
+- The deploy decorator must now be called, ie used as `@deploy()`, and is now typed
+- Remove broken Ansible inventory connector
+
+### Operations & Facts
+
+- Add `docker.container`, `docker.image`, `docker.volume`, `docker.network` & `docker.prune` operations (@apecnascimento)
+- Add `runit.service` operation and `RunitStatus` fact (@lemmi)
+- Add `TmpDir` fact
+- Add `services` argument to systemd facts for filtering
+- Add type hints for all the operations (@stone-w4tch3r)
+- Lowercase pip packages properly (PEP-0426)
+- Rename `postgresql` -> `postgres` operations & facts (old ones still work)
+- Improve IP/MAC parsing in `NetworkDevices` fact (@sudoBash418)
+- Enable getting `Home` fact for other users (@matthijskooijman)
+- Use users correct home directory in `server.user_authorized_keys` operation (@matthijskooijman)
+- Fix `destination`/`not_destination` arguments in `iptables.rule` operation
+- Fix remote dirs when executing from Windows in `files.sync` operation (@Renerick)
+- Fix quoting of systemd unit names (@martenlienen)
+
+### Other Changes
+
+- Add new `_if` global argument to control operation execution at runtime
+- Add `--debug-all` flag to set debug logging for all packages
+- Retry SSH connections on failure (configurable, see [SSH connector](https://docs.pyinfra.com/en/3.x/connectors/ssh.html#available-data)) (@fwiesel)
+- Documentation typo fixes (@szepeviktor, @sudoBash418)
+- Fix handling of binary files in Docker connector (@matthijskooijman)
+- Add `will_change` attribute and `did_change` context manager to `OperationMeta`
+- Replace use of `pkg_resources` with `importlib.metadata` (@diazona)
+- Fix identifying Python inventory files as modules (@martenlienen)
+- Fix typed arguments order (@cdleonard)
+- Check that fact commands don't take global arguments (@martenlienen)
+
+# v2.x
+
+[See this file in the `2.x` branch](https://github.com/Fizzadar/pyinfra/blob/2.x/CHANGELOG.md).
+
+# v1.x
+
+[See this file in the `1.x` branch](https://github.com/Fizzadar/pyinfra/blob/1.x/CHANGELOG.md).

{pyinfra-2.9.2/pyinfra.egg-info → pyinfra-3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyinfra
-Version: 2.9.2
+Version: 3.0
 Summary: pyinfra automates/provisions/manages/deploys infrastructure.
 Home-page: https://pyinfra.com
 Author: Nick / Fizzadar
@@ -16,20 +16,75 @@ Classifier: Intended Audience :: Information Technology
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: System :: Installation/Setup
 Classifier: Topic :: Utilities
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: gevent>=1.5
+Requires-Dist: paramiko<4,>=2.7
+Requires-Dist: click>2
+Requires-Dist: jinja2<4,>2
+Requires-Dist: python-dateutil<3,>2
+Requires-Dist: setuptools
+Requires-Dist: configparser
+Requires-Dist: pywinrm
+Requires-Dist: typeguard
+Requires-Dist: distro<2,>=1.6
+Requires-Dist: packaging>=16.1
+Requires-Dist: graphlib_backport; python_version < "3.9"
+Requires-Dist: typing-extensions; python_version < "3.11"
+Requires-Dist: importlib_metadata>=3.6; python_version < "3.10"
 Provides-Extra: test
+Requires-Dist: pytest==8.2.1; extra == "test"
+Requires-Dist: coverage==7.5.1; extra == "test"
+Requires-Dist: pytest-cov==5.0.0; extra == "test"
+Requires-Dist: black==24.4.2; extra == "test"
+Requires-Dist: isort==5.13.2; extra == "test"
+Requires-Dist: flake8==7.0.0; extra == "test"
+Requires-Dist: flake8-black==0.3.6; extra == "test"
+Requires-Dist: flake8-isort==6.1.1; extra == "test"
+Requires-Dist: mypy; extra == "test"
+Requires-Dist: types-cryptography; extra == "test"
+Requires-Dist: types-paramiko; extra == "test"
+Requires-Dist: types-python-dateutil; extra == "test"
+Requires-Dist: types-PyYAML; extra == "test"
+Requires-Dist: types-setuptools; extra == "test"
 Provides-Extra: docs
+Requires-Dist: pyinfra-guzzle_sphinx_theme==0.16; extra == "docs"
+Requires-Dist: myst-parser==2.0.0; extra == "docs"
+Requires-Dist: sphinx==6.2.1; extra == "docs"
 Provides-Extra: dev
-Provides-Extra: ansible
-License-File: LICENSE.md
+Requires-Dist: pytest==8.2.1; extra == "dev"
+Requires-Dist: coverage==7.5.1; extra == "dev"
+Requires-Dist: pytest-cov==5.0.0; extra == "dev"
+Requires-Dist: black==24.4.2; extra == "dev"
+Requires-Dist: isort==5.13.2; extra == "dev"
+Requires-Dist: flake8==7.0.0; extra == "dev"
+Requires-Dist: flake8-black==0.3.6; extra == "dev"
+Requires-Dist: flake8-isort==6.1.1; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-cryptography; extra == "dev"
+Requires-Dist: types-paramiko; extra == "dev"
+Requires-Dist: types-python-dateutil; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: pyinfra-guzzle_sphinx_theme==0.16; extra == "dev"
+Requires-Dist: myst-parser==2.0.0; extra == "dev"
+Requires-Dist: sphinx==6.2.1; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: ipdb; extra == "dev"
+Requires-Dist: ipdbplugin; extra == "dev"
+Requires-Dist: flake8-spellcheck==0.12.1; extra == "dev"
+Requires-Dist: redbaron; extra == "dev"
 
 <p align="center">
     <a href="https://pyinfra.com">
@@ -37,25 +92,27 @@ License-File: LICENSE.md
     </a>
 </p>
 
-<p align="center">
-    <em>pyinfra automates infrastructure using Python. It’s fast and scales from one server to thousands. Great for ad-hoc command execution, service deployment, configuration management and more.</em>
+<p>
+    <strong>Note: this is the v3 branch, which is currently in beta. <a href="https://docs.pyinfra.com/en/next">See the docs for v3</a>. If needed the <a href="https://github.com/pyinfra-dev/pyinfra/tree/2.x/">2.x branch is here</a>, but is in bugfix only mode.</strong>
+</p>
+
+<p>
+    pyinfra turns Python code into shell commands and runs them on your servers. Execute ad-hoc commands and write declarative operations. Target SSH servers, local machine and Docker containers. Fast and scales from one server to thousands. Think <code>ansible</code> but Python instead of YAML, and a lot faster.
 </p>
 
 ---
 
-<p align="center">
-    <a href="https://docs.pyinfra.com"><strong>Documentation</strong></a> &rArr;
+<h3>
     <a href="https://docs.pyinfra.com/page/getting-started.html"><strong>Getting Started</strong></a> &bull;
-    <a href="https://docs.pyinfra.com/page/examples.html"><strong>Examples</strong></a> &bull;
+    <a href="https://github.com/pyinfra-dev/pyinfra-examples"><strong>Examples Repo</strong></a> &bull;
+    <a href="https://matrix.to/#/#pyinfra:matrix.org"><strong>Chat on Matrix</strong></a>
+</h3>
+<p>
+    <a href="https://docs.pyinfra.com"><strong>Documentation</strong></a> &bull;
     <a href="https://docs.pyinfra.com/page/support.html"><strong>Help & Support</strong></a> &bull;
     <a href="https://docs.pyinfra.com/page/contributing.html"><strong>Contributing</strong></a>
 </p>
 
-<p align="center">
-    Chat &rArr;
-    <a href="https://matrix.to/#/#pyinfra:matrix.org"><strong><code>#pyinfra</code> on Matrix</strong></a>
-</p>
-
 ---
 
 Why pyinfra? Design features include:

{pyinfra-2.9.2 → pyinfra-3.0}/README.md

@@ -4,25 +4,27 @@
     </a>
 </p>
 
-<p align="center">
-    <em>pyinfra automates infrastructure using Python. It’s fast and scales from one server to thousands. Great for ad-hoc command execution, service deployment, configuration management and more.</em>
+<p>
+    <strong>Note: this is the v3 branch, which is currently in beta. <a href="https://docs.pyinfra.com/en/next">See the docs for v3</a>. If needed the <a href="https://github.com/pyinfra-dev/pyinfra/tree/2.x/">2.x branch is here</a>, but is in bugfix only mode.</strong>
+</p>
+
+<p>
+    pyinfra turns Python code into shell commands and runs them on your servers. Execute ad-hoc commands and write declarative operations. Target SSH servers, local machine and Docker containers. Fast and scales from one server to thousands. Think <code>ansible</code> but Python instead of YAML, and a lot faster.
 </p>
 
 ---
 
-<p align="center">
-    <a href="https://docs.pyinfra.com"><strong>Documentation</strong></a> &rArr;
+<h3>
     <a href="https://docs.pyinfra.com/page/getting-started.html"><strong>Getting Started</strong></a> &bull;
-    <a href="https://docs.pyinfra.com/page/examples.html"><strong>Examples</strong></a> &bull;
+    <a href="https://github.com/pyinfra-dev/pyinfra-examples"><strong>Examples Repo</strong></a> &bull;
+    <a href="https://matrix.to/#/#pyinfra:matrix.org"><strong>Chat on Matrix</strong></a>
+</h3>
+<p>
+    <a href="https://docs.pyinfra.com"><strong>Documentation</strong></a> &bull;
     <a href="https://docs.pyinfra.com/page/support.html"><strong>Help & Support</strong></a> &bull;
     <a href="https://docs.pyinfra.com/page/contributing.html"><strong>Contributing</strong></a>
 </p>
 
-<p align="center">
-    Chat &rArr;
-    <a href="https://matrix.to/#/#pyinfra:matrix.org"><strong><code>#pyinfra</code> on Matrix</strong></a>
-</p>
-
 ---
 
 Why pyinfra? Design features include:

{pyinfra-2.9.2 → pyinfra-3.0}/pyinfra/api/__init__.py

@@ -11,6 +11,9 @@ from .config import Config  # noqa: F401 # pragma: no cover
 from .deploy import deploy  # noqa: F401 # pragma: no cover
 from .exceptions import DeployError  # noqa: F401 # pragma: no cover
 from .exceptions import (  # noqa: F401
+    FactError,
+    FactTypeError,
+    FactValueError,
     InventoryError,
     OperationError,
     OperationTypeError,

pyinfra-3.0/pyinfra/api/arguments.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    get_type_hints,
+)
+
+from typing_extensions import TypedDict
+
+from pyinfra import context
+from pyinfra.api.exceptions import ArgumentTypeError
+from pyinfra.api.state import State
+from pyinfra.api.util import raise_if_bad_type
+
+if TYPE_CHECKING:
+    from pyinfra.api.config import Config
+    from pyinfra.api.host import Host
+
+T = TypeVar("T")
+default_sentinel = object()
+
+
+class ArgumentMeta(Generic[T]):
+    description: str
+    default: Callable[["Config"], T]
+    handler: Optional[Callable[["Config", T], T]]
+
+    def __init__(self, description, default, handler=None) -> None:
+        self.description = description
+        self.default = default
+        self.handler = handler
+
+
+# Connector arguments
+# These are arguments passed to the various connectors that provide the underlying
+# API to read/write external systems.
+
+
+# Note: ConnectorArguments is specifically not total as it's used to type many
+# functions via Unpack and we don't want to specify every kwarg.
+class ConnectorArguments(TypedDict, total=False):
+    # Auth arguments
+    _sudo: bool
+    _sudo_user: str
+    _use_sudo_login: bool
+    _sudo_password: str
+    _preserve_sudo_env: bool
+    _su_user: str
+    _use_su_login: bool
+    _preserve_su_env: bool
+    _su_shell: str
+    _doas: bool
+    _doas_user: str
+
+    # Shell arguments
+    _shell_executable: str
+    _chdir: str
+    _env: Mapping[str, str]
+
+    # Connector control (outside of command generation)
+    _success_exit_codes: Iterable[int]
+    _timeout: int
+    _get_pty: bool
+    _stdin: Union[str, Iterable[str]]
+
+
+def generate_env(config: "Config", value: dict) -> dict:
+    env = config.ENV.copy()
+    env.update(value)
+    return env
+
+
+auth_argument_meta: dict[str, ArgumentMeta] = {
+    "_sudo": ArgumentMeta(
+        "Execute/apply any changes with sudo.",
+        default=lambda config: config.SUDO,
+    ),
+    "_sudo_user": ArgumentMeta(
+        "Execute/apply any changes with sudo as a non-root user.",
+        default=lambda config: config.SUDO_USER,
+    ),
+    "_use_sudo_login": ArgumentMeta(
+        "Execute sudo with a login shell.",
+        default=lambda config: config.USE_SUDO_LOGIN,
+    ),
+    "_sudo_password": ArgumentMeta(
+        "Password to sudo with. If needed and not specified pyinfra will prompt for it.",
+        default=lambda config: config.SUDO_PASSWORD,
+    ),
+    "_preserve_sudo_env": ArgumentMeta(
+        "Preserve the shell environment of the connecting user when using sudo.",
+        default=lambda config: config.PRESERVE_SUDO_ENV,
+    ),
+    "_su_user": ArgumentMeta(
+        "Execute/apply any changes with this user using su.",
+        default=lambda config: config.SU_USER,
+    ),
+    "_use_su_login": ArgumentMeta(
+        "Execute su with a login shell.",
+        default=lambda config: config.USE_SU_LOGIN,
+    ),
+    "_preserve_su_env": ArgumentMeta(
+        "Preserve the shell environment of the connecting user when using su.",
+        default=lambda config: config.PRESERVE_SU_ENV,
+    ),
+    "_su_shell": ArgumentMeta(
+        "Use this shell (instead of user login shell) when using ``_su``). "
+        + "Only available under Linux, for use when using `su` with a user that "
+        + "has nologin/similar as their login shell.",
+        default=lambda config: config.SU_SHELL,
+    ),
+    "_doas": ArgumentMeta(
+        "Execute/apply any changes with doas.",
+        default=lambda config: config.DOAS,
+    ),
+    "_doas_user": ArgumentMeta(
+        "Execute/apply any changes with doas as a non-root user.",
+        default=lambda config: config.DOAS_USER,
+    ),
+}
+
+shell_argument_meta: dict[str, ArgumentMeta] = {
+    "_shell_executable": ArgumentMeta(
+        "The shell executable to use for executing commands.",
+        default=lambda config: config.SHELL,
+    ),
+    "_chdir": ArgumentMeta(
+        "Directory to switch to before executing the command.",
+        default=lambda _: "",
+    ),
+    "_env": ArgumentMeta(
+        "Dictionary of environment variables to set.",
+        default=lambda _: {},
+        handler=generate_env,
+    ),
+    "_success_exit_codes": ArgumentMeta(
+        "List of exit codes to consider a success.",
+        default=lambda _: [0],
+    ),
+    "_timeout": ArgumentMeta(
+        "Timeout for *each* command executed during the operation.",
+        default=lambda _: None,
+    ),
+    "_get_pty": ArgumentMeta(
+        "Whether to get a pseudoTTY when executing any commands.",
+        default=lambda _: False,
+    ),
+    "_stdin": ArgumentMeta(
+        "String or buffer to send to the stdin of any commands.",
+        default=lambda _: None,
+    ),
+}
+
+
+# Meta arguments
+# These provide/extend additional operation metadata
+
+
+class MetaArguments(TypedDict):
+    name: str
+    _ignore_errors: bool
+    _continue_on_error: bool
+    _if: Union[List[Callable[[], bool]], Callable[[], bool], None]
+
+
+meta_argument_meta: dict[str, ArgumentMeta] = {
+    # NOTE: name is the only non-_-prefixed argument
+    "name": ArgumentMeta(
+        "Name of the operation.",
+        default=lambda _: None,
+    ),
+    "_ignore_errors": ArgumentMeta(
+        "Ignore errors when executing the operation.",
+        default=lambda config: config.IGNORE_ERRORS,
+    ),
+    "_continue_on_error": ArgumentMeta(
+        (
+            "Continue executing operation commands after error. "
+            "Only applies when ``_ignore_errors`` is true."
+        ),
+        default=lambda _: False,
+    ),
+    "_if": ArgumentMeta(
+        "Only run this operation if these functions return True",
+        default=lambda _: [],
+    ),
+}
+
+
+# Execution arguments
+# These alter how pyinfra is to execute an operation. Notably these must all have the same value
+# over every target host for the same operation.
+
+
+class ExecutionArguments(TypedDict):
+    _parallel: int
+    _run_once: bool
+    _serial: bool
+
+
+execution_argument_meta: dict[str, ArgumentMeta] = {
+    "_parallel": ArgumentMeta(
+        "Run this operation in batches of hosts.",
+        default=lambda config: config.PARALLEL,
+    ),
+    "_run_once": ArgumentMeta(
+        "Only execute this operation once, on the first host to see it.",
+        default=lambda _: False,
+    ),
+    "_serial": ArgumentMeta(
+        "Run this operation host by host, rather than in parallel.",
+        default=lambda _: False,
+    ),
+}
+
+
+class AllArguments(ConnectorArguments, MetaArguments, ExecutionArguments):
+    pass
+
+
+def all_global_arguments() -> List[tuple[str, Type]]:
+    """Return all global arguments and their types."""
+    return list(get_type_hints(AllArguments).items())
+
+
+all_argument_meta: dict[str, ArgumentMeta] = {
+    **auth_argument_meta,
+    **shell_argument_meta,
+    **meta_argument_meta,
+    **execution_argument_meta,
+}
+
+EXECUTION_KWARG_KEYS = list(ExecutionArguments.__annotations__.keys())
+CONNECTOR_ARGUMENT_KEYS = list(ConnectorArguments.__annotations__.keys())
+
+__argument_docs__ = {
+    "Privilege & user escalation": (
+        auth_argument_meta,
+        """
+        .. code:: python
+
+            # Execute a command with sudo
+            server.user(
+                name="Create pyinfra user using sudo",
+                user="pyinfra",
+                _sudo=True,
+            )
+
+            # Execute a command with a specific sudo password
+            server.user(
+                name="Create pyinfra user using sudo",
+                user="pyinfra",
+                _sudo=True,
+                _sudo_password="my-secret-password",
+            )
+        """,
+    ),
+    "Shell control & features": (
+        shell_argument_meta,
+        """
+        .. code:: python
+
+            # Execute from a specific directory
+            server.shell(
+                name="Bootstrap nginx params",
+                commands=["openssl dhparam -out dhparam.pem 4096"],
+                _chdir="/etc/ssl/certs",
+            )
+        """,
+    ),
+    "Operation meta & callbacks": (meta_argument_meta, ""),
+    "Execution strategy": (execution_argument_meta, ""),
+}
+
+
+def pop_global_arguments(
+    kwargs: dict[str, Any],
+    state: Optional["State"] = None,
+    host: Optional["Host"] = None,
+    keys_to_check=None,
+) -> tuple[AllArguments, list[str]]:
+    """
+    Pop and return operation global keyword arguments, in preferred order:
+
+    + From the current context (a direct @operator or @deploy function being called)
+    + From any current @deploy context (deploy kwargs)
+    + From the host data variables
+    + From the config variables
+    """
+
+    state = state or context.state
+    host = host or context.host
+
+    config = state.config
+    if context.ctx_config.isset():
+        config = context.config
+
+    meta_kwargs: dict[str, Any] = host.current_deploy_kwargs or {}  # type: ignore[assignment]
+
+    arguments: dict[str, Any] = {}
+    found_keys: list[str] = []
+
+    for key, type_ in all_global_arguments():
+        if keys_to_check and key not in keys_to_check:
+            continue
+
+        argument_meta = all_argument_meta[key]
+        handler = argument_meta.handler
+        default: Any = argument_meta.default(config)
+
+        host_default = getattr(host.data, key, default_sentinel)
+        if host_default is not default_sentinel:
+            default = host_default
+
+        if key in kwargs:
+            found_keys.append(key)
+            value = kwargs.pop(key)
+        else:
+            value = meta_kwargs.get(key, default)
+
+        if handler:
+            value = handler(config, value)
+
+        if value != default:
+            raise_if_bad_type(
+                value,
+                type_,
+                ArgumentTypeError,
+                f"Invalid argument `{key}`:",
+            )
+
+        # TODO: why is type failing here?
+        arguments[key] = value  # type: ignore
+    return cast(AllArguments, arguments), found_keys

pyinfra-3.0/pyinfra/api/arguments_typed.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Generator,
+    Generic,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Union,
+)
+
+from typing_extensions import ParamSpec, Protocol
+
+if TYPE_CHECKING:
+    from pyinfra.api.operation import OperationMeta
+
+P = ParamSpec("P")
+
+
+# Unfortunately we have to re-type out all of the global arguments here because
+# Python typing doesn't (yet) support merging kwargs. This acts as the operation
+# decorator output function which merges actual operation args/kwargs in paramspec
+# with the global arguments available in all operations.
+# The nature of "global arguments" is somewhat opposed to static typing as it's
+# indirect and somewhat magic, but we are where we are.
+class PyinfraOperation(Generic[P], Protocol):
+    _inner: Callable[P, Generator]
+
+    def __call__(
+        self,
+        #
+        # op args
+        # needs to be first
+        #
+        *args: P.args,
+        #
+        # ConnectorArguments
+        #
+        # Auth
+        _sudo: bool = False,
+        _sudo_user: Optional[str] = None,
+        _use_sudo_login: bool = False,
+        _sudo_password: Optional[str] = None,
+        _preserve_sudo_env: bool = False,
+        _su_user: Optional[str] = None,
+        _use_su_login: bool = False,
+        _preserve_su_env: bool = False,
+        _su_shell: Optional[str] = None,
+        _doas: bool = False,
+        _doas_user: Optional[str] = None,
+        # Shell arguments
+        _shell_executable: Optional[str] = None,
+        _chdir: Optional[str] = None,
+        _env: Optional[Mapping[str, str]] = None,
+        # Connector control
+        _success_exit_codes: Iterable[int] = (0,),
+        _timeout: Optional[int] = None,
+        _get_pty: bool = False,
+        _stdin: Union[None, str, list[str], tuple[str, ...]] = None,
+        #
+        # MetaArguments
+        #
+        name: Optional[str] = None,
+        _ignore_errors: bool = False,
+        _continue_on_error: bool = False,
+        _if: Union[List[Callable[[], bool]], Callable[[], bool], None] = None,
+        #
+        # ExecutionArguments
+        #
+        _parallel: Optional[int] = None,
+        _run_once: bool = False,
+        _serial: bool = False,
+        #
+        # op kwargs
+        #
+        **kwargs: P.kwargs,
+    ) -> "OperationMeta": ...