pyinfra 3.1.1__tar.gz → 3.3__tar.gz

{pyinfra-3.1.1 → pyinfra-3.3}/CHANGELOG.md

@@ -1,3 +1,95 @@
+# v3.3
+
+Second release of 2025: loads of adds, fixes and documentation improvements. A huge THANK YOU to all contributors. Slightly changed format for the change list based on commit messages which should speed up releases:
+
+New operations & arguments:
+
+- operations/freebsd: add FreeBSD operations & facts (@DtxdF)
+- operations/files.move: new operation (@Pirols)
+- operations/server.user: enable adding user to secondary groups (Pirols)
+- operations/postgres: enhance role management by adding `ALTER ROLE` support (@wowi42)
+- operations/postgres: enable modifying existing postgres databases (@wowi42)
+- operations/docker.container: refactor to support container recreation (@minor-fixes)
+
+Operation/fact fixes:
+
+- operations/postgres: fix quoting of locale parameters (@xvello)
+- operations/server: remove leftover deprecated parameter (@wowi42)
+- operations/pacmen: update PACMAN_REGEX to support additional characters (@wowi42)
+- operations/server.sysctl: handle 0 integer values correctly (@lemmi)
+- operations/apt: dist-upgrade also supports --autoremove (@bauen1)
+- operations/apt: fix parameter name in docs (@bauen1)
+- operations/server: fix: lastlog is always null (@ingstem)
+- operations/docker: Fixed a typo with the volumes parameter to docker.prune operation (@mpilone)
+- facts/xbps.XbpsPackages: allow . in package names (@lemmi)
+
+Connectors, CLI:
+
+- connectors: improve detection of sudo password needed
+- connectors/ssh: add support for `ServerAliveInterval` (@chipot)
+- cli: enable -h as shorthand for --help (@NichtJens)
+
+Docs:
+
+- docs: Add a section explaining connector flow (@goetzk)
+- docs: Add inventory processing note and reference it (@goetzk)
+- docs: Add example of logging to using operations docs (@goetzk)
+- docs: fix wrong example operation using forbidden argument 'name' (@robertmx)
+- docs: Add a note to the docs about using `_inner` when calling operations from other operations (@CSDUMMI)
+- docs: Document host, state, inventory in files.template (@mpilone)
+- docs: Minor adjustments to wording help docs and help (@goetzk)
+- docs: expand connectors documentation (@goetzk)
+- docs: correct import path for any_changed, all_changed (@lemmi)
+- docs: Add note re: global arguments to operations (@simonhammes)
+
+Internal/meta:
+
+- refactor: update opkg documentation and add requires_command to ZFS and Git tests (@wowi42)
+- Update testing and development dependencies in setup.py (@wowi42)
+- tests: Load test specs with PyYAML instead of json (@taliaferro)
+- typing: Require explicit override decorator (@bauen1)
+- api: don't execute callbacks within a greenlet if we're already in one
+- ci: Github Actions support for python 3.12 (@wowi42)
+- ci: Prevent docs job from running on forks (@simonhammes)
+
+# v3.2
+
+Hello 2025! Here's pyinfra 3.2 - with another incredible round of contributions from the community, THANK YOU ALL. New stuff:
+
+- Add total counts to results summary (@NichtJens)
+- Enable passing extra data via `local.include` (@TimothyWillard)
+- Validate inventory files and display warnings for unexpected variables (@simonhammes)
+
+New operations/facts:
+
+- Add `pipx` operations (`packages`, `upgrade_all`, `ensure_path`) facts (`PipxPackages`, `PipxEnvironment`) and operations (@maisim)
+- Add `server.OsRelease` fact (@wowi42)
+- Add `podman.PodmanSystemInfo` and `podman.PodmanPs` facts (@bauen1)
+- Add many extra arguments (including generic args) to `files.FindFiles*` facts (@JakkuSakura)
+- Add `system` argument to `git.config` operation (@Pirols)
+- Add `psql_database` argument to postgres operations & facts (@hamishfagg)
+- Add `files.Sha384File` fact and `sha384sum` argument to `files.download` operation (@simonhammes)
+- Add `apt.SimulateOperationWillChange` fact (@bauen1)
+- Detect changes in `apt.upgrade` and `apt.dist_upgrade` operations (@bauen1)
+- Add `fibootmgr.EFIBootMgr` fact (@bauen1)
+- Add opkg facts and operations (@morrison12)
+
+Fixes:
+
+- Multiple fixes for `server.crontab` operation and facts (@JakkuSakura)
+- Correctly handle `latest` argument with requirements file in `pip.packages` operation (@amiraliakbari)
+- Fix regex used to parse installed apk packages (@simonhammes)
+- Fix SSH connector overwriting known hosts files (@vo452)
+
+Docs/internal tweaks:
+
+- Add type annotations for many more operations (@simonhammes)
+- Add typos CI checking to replace flake8-spellcheck (@simonhammes)
+- Bump CI actions and dependencies (@simonhammes)
+- Require JSON tests to include all arguments
+- Remove unused `configparser` dependency (@bkmgit)
+- Many small documentation fixes/tweaks
+
 # v3.1.1
 
 - Improve errors with 2.x style `@decorator` (vs `@decorator()`) functions

{pyinfra-3.1.1 → pyinfra-3.3}/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (C) 2020 Nick Barrett <nick@fizzadar.com>
+Copyright (C) 2025 Nick Barrett <nick@fizzadar.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

{pyinfra-3.1.1/pyinfra.egg-info → pyinfra-3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyinfra
-Version: 3.1.1
+Version: 3.3
 Summary: pyinfra automates/provisions/manages/deploys infrastructure.
 Home-page: https://pyinfra.com
 Author: Nick / Fizzadar
@@ -16,7 +16,6 @@ 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.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -24,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: System :: Installation/Setup
 Classifier: Topic :: Utilities
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Requires-Dist: gevent>=1.5
@@ -33,7 +32,6 @@ 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
@@ -42,14 +40,15 @@ 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: pytest==8.3.5; extra == "test"
+Requires-Dist: coverage==7.7.1; extra == "test"
+Requires-Dist: pytest-cov==6.0.0; extra == "test"
+Requires-Dist: black==25.1.0; extra == "test"
+Requires-Dist: isort==6.0.1; extra == "test"
+Requires-Dist: flake8==7.1.2; extra == "test"
 Requires-Dist: flake8-black==0.3.6; extra == "test"
-Requires-Dist: flake8-isort==6.1.1; extra == "test"
+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"
@@ -57,33 +56,34 @@ 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"
+Requires-Dist: pyinfra-guzzle_sphinx_theme==0.17; extra == "docs"
+Requires-Dist: myst-parser==4.0.1; extra == "docs"
+Requires-Dist: sphinx==8.2.3; extra == "docs"
 Provides-Extra: dev
-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: pytest==8.3.5; extra == "dev"
+Requires-Dist: coverage==7.7.1; extra == "dev"
+Requires-Dist: pytest-cov==6.0.0; extra == "dev"
+Requires-Dist: black==25.1.0; extra == "dev"
+Requires-Dist: isort==6.0.1; extra == "dev"
+Requires-Dist: flake8==7.1.2; extra == "dev"
 Requires-Dist: flake8-black==0.3.6; extra == "dev"
-Requires-Dist: flake8-isort==6.1.1; extra == "dev"
+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-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: pyinfra-guzzle_sphinx_theme==0.17; extra == "dev"
+Requires-Dist: myst-parser==4.0.1; extra == "dev"
+Requires-Dist: sphinx==8.2.3; 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: flake8-spellcheck==0.28.0; extra == "dev"
 Requires-Dist: redbaron; extra == "dev"
 
 <p align="center">

{pyinfra-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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-3.1.1 → pyinfra-3.3}/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(