API: client

class pubtools.pulplib.Client(url, **kwargs)[source]

A client for the Pulp 2.x API.

This class provides high-level methods for querying a Pulp server and performing actions in Pulp.

Usage of futures:

Most values are returned as Future objects. Returned futures are resolved when:

  • a request to Pulp succeeded, if operation is synchronous (e.g. get, search)

  • or a request to Pulp succeeded and any spawned tasks succeeded, if operation is asynchronous (e.g. publish)

If a future is currently awaiting one or more Pulp tasks, cancelling the future will attempt to cancel those tasks.

Client lifecycle:

New in version 2.12.0.

Client instances support the context manager protocol and can be used via a with statement, as in example:

with Client(url="https://pulp.example.com/") as client:
    do_something_with(client)

While not mandatory, it is encouraged to ensure that any threads associated with the client are promptly shut down.

Proxy futures:

New in version 2.1.0.

All Future objects produced by this client are proxy futures, meaning that attribute and method lookups on the objects are proxied to the future’s result, blocking as needed.

This allows the client to be used within blocking code without having to scatter calls to .result() throughout.

For example, this block of code:

repo = client.get_repository(repo_id).result()
publish_tasks = repo.publish().result()
task_ids = ','.join([t.id for t in publish_tasks])
log.info("Published %s: %s", repo.id, task_ids)

…may be alternatively written without the calls to .result(), due to the usage of proxy futures:

repo = client.get_repository(repo_id)
publish_tasks = repo.publish()
task_ids = ','.join([t.id for t in publish_tasks])
log.info("Published %s: %s", repo.id, task_ids)

Retries:

In general, for all methods which represent an idempotent operation and which return a Future, the library may retry operations several times in case of failure.

Throttling:

This client will internally throttle the number of Pulp tasks allowed to be outstanding at any given time, so that no single client can overload the Pulp task queue.

Parameters:

  • url (str) – URL of a Pulp server, e.g. https://pulp.example.com/.

  • task_throttle (int) – Maximum number of queued or running tasks permitted for this client. If more than this number of tasks are running, the client will wait before triggering more. This can be used to ensure no single client overwhelms the Pulp server.

  • threads (int) –

    A hint for the number of threads the client should use in order to make concurrent requests to Pulp.

    This number should be considered as more of a scaling factor than a precise thread count. The client in practice will use more than this number of threads.

  • auth (object) –

    Any of these arguments, if provided, are used to initialize requests.Session objects used by the client.

    These may be used, for example, to configure the credentials for the Pulp server or to use an alternative CA bundle.

  • cert –

    Any of these arguments, if provided, are used to initialize requests.Session objects used by the client.

    These may be used, for example, to configure the credentials for the Pulp server or to use an alternative CA bundle.

  • headers –

    Any of these arguments, if provided, are used to initialize requests.Session objects used by the client.

    These may be used, for example, to configure the credentials for the Pulp server or to use an alternative CA bundle.

  • max_redirects –

    Any of these arguments, if provided, are used to initialize requests.Session objects used by the client.

    These may be used, for example, to configure the credentials for the Pulp server or to use an alternative CA bundle.

  • params –

    Any of these arguments, if provided, are used to initialize requests.Session objects used by the client.

    These may be used, for example, to configure the credentials for the Pulp server or to use an alternative CA bundle.

  • proxies –

    Any of these arguments, if provided, are used to initialize requests.Session objects used by the client.

    These may be used, for example, to configure the credentials for the Pulp server or to use an alternative CA bundle.

  • verify –

    Any of these arguments, if provided, are used to initialize requests.Session objects used by the client.

    These may be used, for example, to configure the credentials for the Pulp server or to use an alternative CA bundle.

New in version 2.31.0: Added the threads argument.

get_repository(repository_id)[source]

Get a repository by ID.

Parameters:

repository_id (str) – The ID of the repository to be fetched.

Returns:

Future[Repository]

A future holding the fetched Repository.

search_repository(criteria=None)[source]

Search for repositories matching the given criteria.

Parameters:

criteria (Criteria) – A criteria object used for this search. If None, search for all repositories.

Returns:

Future[Page]

A future representing the first page of results.

Each page will contain a collection of Repository objects.

search_content(criteria=None)[source]

Search for units across all repositories.

Parameters:

criteria (Criteria) – A criteria object used for this search. If None, search for all units.

Returns:

Future[Page]

A future representing the first page of results.

Each page will contain a collection of Unit subclasses objects.

New in version 2.6.0.

copy_content(from_repository, to_repository, criteria=None, options=CopyOptions(require_signed_rpms=None))[source]

Copy content from one repository to another.

Parameters:

  • from_repository (Repository) – A repository used as the source of content.

  • to_repository (Repository) – A repository to receive copied content.

  • criteria (Criteria) – A criteria object used to find units for copy. If None, all units in the source repo will be copied.

  • options (CopyOptions) –

    Options influencing the copy.

    Some options may be specific to certain repository and content types. Options which are not applicable to this copy will be ignored.

Returns:

Future[list[Task]]

A future which is resolved when the copy completes.

The units() attribute may be inspected to determine which unit(s) were copied. Note that the returned units typically will have only a subset of available fields.

New in version 2.17.0.

New in version 2.29.0: Added the options argument.

update_content(unit)[source]

Update mutable fields on an existing unit.

Parameters:

unit (Unit) –

A unit to be updated.

This unit must have a known unit_id.

Only those fields documented as mutable will have any effect during the update (e.g. cdn_path). Other fields either cannot be updated at all, or can only be updated by re-uploading the associated content.

Returns:

Future

A future which is resolved with a value of None once the unit has been updated.

New in version 2.20.0.

update_repository(repository)[source]

Update mutable fields on an existing repository.

Parameters:

repository (Repository) –

A repository to be updated.

Only those fields documented as mutable will have any effect during the update (e.g. product_versions). Other fields cannot be updated using this library.

Returns:

Future

A future which is resolved with a value of None once the repository has been updated.

New in version 2.29.0.

search_distributor(criteria=None)[source]

Search the distributors matching the given criteria.

Parameters:

criteria (Criteria) – A criteria object used for this search. If None, search for all distributors.

Returns:

Future[Page]

A future representing the first page of results.

Each page will contain a collection of Distributor objects.

New in version 2.1.0.

search_task(criteria=None)[source]

Search the tasks matching the given criteria.

Parameters:

criteria (Criteria) – A criteria object used for this search. If None, search for all tasks.

Returns:

Future[Page]

A future representing the first page of results.

Each page will contain a collection of Task objects.

New in version 2.19.0.

get_maintenance_report()[source]

Get the current maintenance mode status for this Pulp server.

Returns:

Future[MaintenanceReport]

A future describes the maintenance status

New in version 1.4.0.

set_maintenance(report)[source]

Set maintenance mode for this Pulp server.

Parameters:

report – An updated MaintenanceReport object that will be used as the newest maintenance report.

Returns:

Future[list[Task]]

A future which is resolved when maintenance mode has been updated successfully.

The future contains a task triggered and awaited during the publish maintenance repository operation.

New in version 1.4.0.

get_content_type_ids()[source]

Get the content types supported by this Pulp server.

Returns:

Future[list[str]]

A future holding the IDs of supported content types.

The returned values will depend on the plugins installed on the connected Pulp server.

”modulemd”, “rpm”, “srpm” and “erratum” are some examples of common return values.

New in version 1.4.0.

create_repository(repo)[source]
Create a repository with initial data provided in the

argument. Importer for repository is automatically associated if available. If repository already exists, warning is logged. After repository has been successfully created or if repository already exists, it is checked if expected and current repository configuration values are correct.

Parameters:

repo (Repository) – A repository object used for creation.

Returns:

Future[Repository]

A future which is resolved with a value of Repository once the repository has been created.

New in version 2.39.0.

class pubtools.pulplib.CopyOptions(*, require_signed_rpms: bool | None = None)[source]

Options influencing a call to copy_content().

Method generated by attrs for class CopyOptions.

require_signed_rpms

Whether to require signatures on all RPMs in the copy.

In order to copy unsigned RPMs between repositories, it is generally necessary to set this flag to False. Unsigned RPMs may otherwise be silently omitted from the copy.

Errors

class pubtools.pulplib.PulpException[source]

Raised when the Pulp server has responded with an unrecoverable error (generally a failed HTTP response which persisted over several retries).

class pubtools.pulplib.TaskFailedException(task)[source]

Raised when a Pulp task has completed with errors.

task

The Task which has failed. Error details may be accessed from the task.

class pubtools.pulplib.DetachedException[source]

If an operation is attempted on a Pulp object which requires an active client, and the object is not attached to any client, this exception is raised.

class pubtools.pulplib.InvalidDataException[source]

Raised if raw Pulp data appears to be invalid (i.e. not matching expected schema).