apt module

AptAutoremovable

Packages apt autoremove would remove, as AptPackageInfo dicts.

Commands:

apt-get --just-print autoremove 2>/dev/null

Returns:

list[AptPackageInfo]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_apt_autoremovable.py.

AptHeldPackages

Packages marked as held, as a sorted list of AptPackageInfo dicts.

Commands:

apt-mark showhold

Returns:

list[AptPackageInfo]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_apt_held_packages.py.

AptKey

Attributes:

Name	Type	Description
id		The key id (the last 16 hex digits of the fingerprint), the identity a keyring file lists the key under.
validity		GPG's validity letter for the key (- unknown, f fully trusted, ...), exactly as the colon record prints it.
length		The key length in bits (e.g. 4096).
fingerprint		The full fingerprint, when a fpr record attached one.
uid_hash		The hash of the user id, when a uid record attached one.
uid		The user id string (name, comment and email), when a uid record attached one.
subkeys		The key's subkeys as further AptKey entries (only the last sub record before the next pub is kept); present on primary keys, absent on subkey entries.

AptKeys

The GPG keys available to APT, as a list of AptKey dicts.

Commands:

find "/etc/apt/trusted.gpg.d" "/etc/apt/keyrings" "/usr/share/keyrings" -type f \( -name '*.gpg' -o -name '*.kbx' \) 2>/dev/null -exec sh -c 'echo "KEYRING:$1"; gpg --list-keys --with-colons --keyring "$1" --no-default-keyring 2>/dev/null || true' _ {} \; ; find "/etc/apt/trusted.gpg.d" "/etc/apt/keyrings" "/usr/share/keyrings" -type f -name '*.asc' 2>/dev/null -exec sh -c 'echo "KEYRING:$1"; gpg --with-colons "$1" 2>/dev/null || true' _ {} \;

Returns:

list[AptKey]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_apt_keys.py.

AptPackageInfo

Attributes:

Name	Type	Description
name		The package name, architecture suffixes (libc6:i386) intact, exactly as the underlying apt command prints it.
versions		The package's versions, de-duplicated and sorted, epoch prefixes (5:24.0.7-1~ubuntu.22.04~jammy) intact: every installed version for AptPackages, the single bracketed Remv version for AptAutoremovable, and [] for AptHeldPackages (apt-mark showhold prints no version).

AptPackagePolicy

Attributes:

Name	Type	Description
installed		The installed version, or None when apt prints (none) (the package is known but not installed).
candidate		The version apt install <package> would pick right now, or None when apt prints (none) (no installable version, e.g. every offering pinned below zero).
versions		The version table as AptPolicyVersion dicts, in the order apt prints them (highest-priority offering first).

AptPackageUpgrade

Attributes:

Name	Type	Description
name		The package name, architecture suffixes (libc6:i386) intact, exactly as apt list --upgradable prints it.
installed		The currently installed version (the row's [upgradable from: ...] value), epoch prefixes (2:9.1.0016-1ubuntu7.4) intact, exactly as apt prints it.
candidate		The version apt upgrade would move the package to, epoch prefixes intact.

AptPackages

Installed apt packages, as a list of AptPackageInfo dicts.

Commands:

apt list --installed 2>/dev/null

Returns:

list[AptPackageInfo]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_apt_packages.py.

AptPolicy

One package's install candidate and origins, as an AptPackagePolicy.

Commands:

LC_ALL=C apt-cache policy <package>

Returns:

AptPackagePolicy | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_apt_policy.py.

AptPolicyVersion

Attributes:

Name	Type	Description
version		The version string, epoch prefixes (5:24.0.7-1) intact, exactly as apt-cache policy prints it.
priority		The pin priority apt assigns the version (500 for a normal repository, 100 for the installed dpkg status entry; negative for Pin-Priority: -1 blocks).
origins		The origin lines listed under the version, each with its leading priority stripped: a repository line like "http://archive.ubuntu.com/ubuntu noble/main amd64 Packages" or the local "/var/lib/dpkg/status" for the installed copy.

AptSource

Attributes:

Name	Type	Description
type		"deb" (binary packages) or "deb-src" (source packages).
url		The repository URL, e.g. "http://archive.ubuntu.com/ubuntu".
distribution		The suite/distribution, e.g. "noble" or "jammy/mongodb-org/7.0"; "/" for a flat repository.
components		The components, e.g. ["main", "restricted"]; empty for a flat repository.
options		The bracketed [key=value] options (arch, signed-by, trusted, ...). Every value is a list of strings, even a single-valued one -- the baseline collapses single values to a bare string, forcing callers to type-check; here options["arch"] is always e.g. ["amd64"]. An inline armored Signed-By PGP block stays one entry holding the whole key text.

AptSources

The configured apt sources, as a list of AptSource dicts.

Commands:

for f in /etc/apt/sources.list /etc/apt/sources.list.d/*.list /etc/apt/sources.list.d/*.sources; do [ -e "$f" ] || continue; printf "#reemote-aptsource %s\n" "$f"; cat "$f"; echo; done

Returns:

list[AptSource]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_apt_sources.py.

AptSourcesFile

The current content of one apt sources file, or None when it is absent.

Commands:

test -e <path> && { printf '#reemote-sourcesfile\n'; cat -- <path>; }

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_sources_file.py.

AptUpgradable

Packages with a pending upgrade, as a list of AptPackageUpgrade dicts.

Commands:

apt list --upgradable 2>/dev/null

Returns:

list[AptPackageUpgrade]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_apt_upgradable.py.

DebPackage

The name and version of a .deb file or an installed dpkg package.

Commands:

test -f <package> && case <package> in *.deb) dpkg -I <package> ;; *) dpkg -s <package> 2>/dev/null || true ;; esac || dpkg -s <package> 2>/dev/null || true

Returns:

DebPackageInfo | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_deb.py.

DebPackageInfo

Attributes:

Name	Type	Description
name		The package name from the Package: control field.
version		The package version from the Version: control field, epoch prefixes intact.

auto_remove async

auto_remove(
    ctx: OpContext,
    wait_for_lock: bool | int = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Remove transitive dependencies that are no longer needed.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
wait_for_lock	bool | int	Wait for the apt lock instead of failing instantly; True waits up to 60 seconds, an int sets the timeout in seconds. Defaults to False.	False
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt autoremove commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_auto_remove.py.

deb async

deb(
    ctx: OpContext,
    src: str,
    present: bool = True,
    wait_for_lock: bool | int = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add/remove a .deb file package.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
src	str	Path to the .deb file on the target host.	required
present	bool	Whether the package should be installed. Defaults to True.	True
wait_for_lock	bool | int	Wait for the apt lock instead of failing instantly; True waits up to 60 seconds, an int sets the timeout in seconds. Defaults to False.	False
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt deb package commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/apt/apt_deb.py.

dist_upgrade async

dist_upgrade(
    ctx: OpContext,
    wait_for_lock: bool | int = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Update all apt packages, employing dist-upgrade.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
wait_for_lock	bool | int	Wait for the apt lock instead of failing instantly; True waits up to 60 seconds, an int sets the timeout in seconds. Defaults to False.	False
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt dist-upgrade commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_dist_upgrade.py.

key async

key(
    ctx: OpContext, src: IO[Any], dest: str, **kwargs: Any
) -> AsyncGenerator[Command]

Install a GPG keyring file for APT.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
src	IO[Any]	The key content as a seekable IO-like object on the control machine (an io.BytesIO/io.StringIO, a file opened with open(), ...), rewound to position 0 before it is read; ASCII-armored and binary key content are both accepted.	required
dest	str	The keyring filename or absolute path on the target host; a relative name is resolved under /etc/apt/keyrings/ so a sources entry can reference it via signed-by= (the modern, non-deprecated replacement for apt-key add).	required
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt GPG keyring commands.

Raises:

ValueError

Examples:

Examples can be found in examples/modules/apt/apt_key.py.

mark async

mark(
    ctx: OpContext,
    packages: str | list[str] | tuple[str, ...],
    held: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Hold packages back from upgrades, or release held ones.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
packages	str | list[str] | tuple[str, ...]	Package names to mark; a single string or a list/tuple. Prefer tuples when building requests via op(), since OperationRequest kwargs must stay hashable.	required
held	bool	Whether the packages should be held (apt-mark hold, keeping them out of upgrades) or released (apt-mark unhold). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt-mark hold/unhold commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_mark.py.

packages async

packages(
    ctx: OpContext,
    packages: str
    | list[str]
    | tuple[str, ...]
    | None = None,
    present: bool = True,
    latest: bool = False,
    update: bool = False,
    upgrade: bool = False,
    no_recommends: bool = False,
    allow_downgrades: bool = False,
    purge: bool = False,
    extra_install_args: str | None = None,
    extra_uninstall_args: str | None = None,
    wait_for_lock: bool | int = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Install/remove/update apt packages.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
packages	str | list[str] | tuple[str, ...] | None	Packages to ensure; a single string, a list/tuple, or None. Prefer tuples when building requests via op(), since OperationRequest kwargs must stay hashable. Versions can be pinned as <pkg>=<version>. Defaults to None.	None
present	bool	Whether the packages should be installed. Defaults to True.	True
latest	bool	Whether to upgrade installed packages without a pinned version. Defaults to False.	False
update	bool	Run apt-get update before installing packages. Defaults to False.	False
upgrade	bool	Run apt-get upgrade before installing packages. Defaults to False.	False
no_recommends	bool	Add --no-install-recommends to the install command. Defaults to False.	False
allow_downgrades	bool	Add --allow-downgrades to the install command. Defaults to False.	False
purge	bool	When removing (present=False), use apt-get purge so configuration files are removed alongside the package. Defaults to False.	False
extra_install_args	str | None	Additional arguments to the apt install command. Defaults to None.	None
extra_uninstall_args	str | None	Additional arguments to the apt remove command. Defaults to None.	None
wait_for_lock	bool | int	Wait for the apt lock instead of failing instantly; True waits up to 60 seconds, an int sets the timeout in seconds. Defaults to False.	False
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt package commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_packages.py.

ppa async

ppa(
    ctx: OpContext,
    src: str,
    present: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add/remove an Ubuntu PPA repository.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
src	str	The PPA name, in full ppa:user/repo format.	required
present	bool	Whether the repository should exist. Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt PPA repository commands.

Raises:

None

Examples:

Examples can be found in examples/modules/apt/apt_ppa.py.

repo async

repo(
    ctx: OpContext,
    src: str,
    present: bool = True,
    filename: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add/remove an apt repository line.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
src	str	Apt source string, e.g. deb http://X hardy main.	required
present	bool	Whether the repository should exist on the system. Defaults to True.	True
filename	str | None	Base name under /etc/apt/sources.list.d/ (the .list extension is appended); by default /etc/apt/sources.list is managed. Defaults to None.	None
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt repository line commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_repo.py.

sources_file async

sources_file(
    ctx: OpContext,
    filename: str,
    types: str | list[str] | tuple[str, ...] = "deb",
    uris: str | list[str] | tuple[str, ...] | None = None,
    suites: str | list[str] | tuple[str, ...] | None = None,
    components: str
    | list[str]
    | tuple[str, ...]
    | None = None,
    architectures: str
    | list[str]
    | tuple[str, ...]
    | None = None,
    signed_by: str | None = None,
    present: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage a deb822 .sources file.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
filename	str	Base name for the file (without extension); the .sources extension is added automatically under /etc/apt/sources.list.d/.	required
types	str | list[str] | tuple[str, ...]	Repository type(s) -- "deb", "deb-src", or both. Defaults to "deb".	'deb'
uris	str | list[str] | tuple[str, ...] | None	One or more repository URLs. Defaults to None.	None
suites	str | list[str] | tuple[str, ...] | None	One or more suite/distribution names (e.g. "bookworm"). Defaults to None.	None
components	str | list[str] | tuple[str, ...] | None	One or more components (e.g. ["main", "contrib"]). Defaults to None.	None
architectures	str | list[str] | tuple[str, ...] | None	Restrict to specific architectures (e.g. "amd64"). Defaults to None.	None
signed_by	str | None	Absolute path to the keyring file used for signature verification. Defaults to None.	None
present	bool	Whether the sources file should exist. Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt deb822 sources file commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/apt/apt_sources_file.py.

update async

update(
    ctx: OpContext,
    wait_for_lock: bool | int = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Update apt repositories.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
wait_for_lock	bool | int	Wait for the apt lock instead of failing instantly; True waits up to 60 seconds, an int sets the timeout in seconds. Defaults to False.	False
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt update commands.

Raises:

None

Examples:

Examples can be found in examples/modules/apt/apt_update.py.

upgrade async

upgrade(
    ctx: OpContext,
    wait_for_lock: bool | int = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Upgrade all apt packages.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
wait_for_lock	bool | int	Wait for the apt lock instead of failing instantly; True waits up to 60 seconds, an int sets the timeout in seconds. Defaults to False.	False
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated apt upgrade commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/apt/apt_upgrade.py.