Package Manager Provider API

This document provides an overview of the API used internally by Exosphere to implement package manager providers.

A package manager provider is a Python class that implements the low level API for a specific package manager. It is generally responsible for connecting to the host, querying available package updates, parsing that list and returning Update objects that can be used to populate state.

Implementing a new provider requires creating a new class under exosphere.providers that inherits from the base provider class exosphere.providers.api.Provider.

This class should implement the methods and members below.

Providers API

This module defines the abstract base class for package managers as well as helper functions and decorators to be used by package manager provider implementations.

class exosphere.providers.api.PkgManager

Bases: ABC

Abstract Base Class for Package Manager

Defines the interface for Package Manager implementations.

When implementing a Package Manager Provider, you should inherit from this class and implement the reposync and get_updates methods.

Note

If either of the methods require elevated privileges, (i.e., they use cx.sudo() instead of cx.run()), you should decorate them with the @requires_sudo decorator.

SUDOERS_COMMANDS: list[str] | None = None

List of commands that require sudo privileges. This will be used by the CLI helper commands to generate the appropriate sudoers file entries.

SUDOERS_COMMANDS = [
    "/usr/bin/apt-get update",
    "/usr/bin/something-else --with-args -o option=value",
]

If you do not require elevated privileges at all, omit it entirely from your implementation or set it to None.

abstractmethod get_updates(cx: Connection) → list[Update]

Get a list of available updates.

This method should be implemented by subclasses to provide the specific logic for retrieving updates for different package managers.

It is preferable if this can be done without the need for elevated privileges and remains read-only, as much as possible.

Parameters:

cx – Fabric Connection object

Returns:

List of available updates as Update objects.

abstractmethod reposync(cx: Connection) → bool

Synchronize the package repository.

This method should be implemented by subclasses to provide the specific synchronization logic for different package managers.

Some package managers may not require explicit synchronization, in which case this method can be a no-op that returns True.

If it is possible to perform the synchronization without elevated privileges, it is vastly preferable to do so.

Parameters:

cx – Fabric Connection object

Returns:

True if synchronization is successful, False otherwise.

exosphere.providers.api.requires_sudo(func: Callable) → Callable

Decorator to mark a function as requiring sudo privileges.

This decorator sets an attribute on the function to indicate that it requires sudo privileges to execute. You should add it to any method that requires elevated privileges, i.e. whenever you are using ‘cx.sudo()’ instead of ‘cx.run()’.