API: core

Common functionality

class pubtools.pulplib.PulpObject[source]

Base class for all modeled Pulp objects.

Instances of PulpObject subclasses may be obtained by get and search methods on Client, or may be instantiated directly by calls to from_data() when the client is not used.

Objects which are created via a client may be used to issue further requests to Pulp (for example, to update or delete the object).

Pulp objects use attrs. Attributes are immutable. Helper functions such as attr.evolve() may be used to produce new instances.

Attributes exposed on these Pulp objects include some generic attributes applicable to any Pulp installation, but also some custom attributes which only make sense for release-engineering Pulp servers.

classmethod from_data(data)[source]

Obtain a detached instance using data obtained from Pulp.

This method is provided so that callers who are not using Client may make use of the Pulp object classes.

This method must be invoked on the appropriate PulpObject subclass matching data. For example, Repository.from_data must be invoked with a repository object provided by Pulp’s API.

Parameters:

data (dict) – A dict containing a raw representation of a Pulp object, as rendered by Pulp’s API.

Returns:

a new instance of cls

Raises:

InvalidDataException – If the provided data fails validation against an expected schema.

Example

Opting-out of using the Client class and instead doing a plain requests.get:

url = 'https://pulp.example.com/pulp/api/v2/repositories/zoo/'
data = requests.get(url).json()
repo = Repository.from_data(data)

Repository

class pubtools.pulplib.Repository[source]

Represents a Pulp repository.

Method generated by attrs for class Repository.

id

ID of this repository (str).

type

Type of this repository (str).

This is a brief string denoting the content / Pulp plugin type used with this repository, e.g. rpm-repo.

created

datetime in UTC at which this repository was created, or None if this information is unavailable.

distributors

list of Distributor objects belonging to this repository.

eng_product_id

ID of the product to which this repository belongs (if any).

relative_url

Default publish URL for this repository, relative to the Pulp content root.

mutable_urls

A list of URLs relative to repository publish root which are expected to change at every publish (if any content of repo changed).

is_sigstore

True if this is a sigstore repository, used for container image manifest signatures.

Deprecated since version 2.24.0: The signatures are not stored in a Pulp repository any more.

is_temporary

True if this is a temporary repository.

A temporary repository is a repository created by release-engineering tools for temporary use during certain workflows. Such repos are not expected to be published externally and generally should have a lifetime of a few days or less.

New in version 1.3.0.

signing_keys

A list of GPG signing key IDs used to sign content in this repository.

skip_rsync_repodata

True if this repository is explicitly configured such that a publish of this repository will not publish repository metadata to remote hosts.

content_set

Name of content set that is associated with this repository.

arch

The primary architecture of content within this repository (e.g. ‘x86_64’).

New in version 2.29.0.

platform_full_version

A version string associated with the repository.

This field should be used with care, as the semantics are not well defined. It is often, but not always, equal to the $releasever yum variable associated with a repository.

Due to the unclear meaning of this field, it’s strongly recommended to avoid making use of it in any new code.

New in version 2.29.0.

product_versions

A list of product versions associated with this repository.

The versions found in this list are derived from the product versions found in any product certificates (productid) historically uploaded to this repository and related repositories.

This field is mutable and may be set by update_repository().

New in version 2.29.0.

include_in_download_service

Flag indicating whether the repository is visible in production instance of download service.

New in version 2.34.0.

include_in_download_service_preview

Flag indicating whether the repository is visible in staging instance of download service.

New in version 2.34.0.

provisioning

Flag indicating whether the repository is currently in process of creation and provisioning to other tools outside of Pulp.

New in version 2.37.0.

importer

An object of Importer that is associated with the repository.

New in version 2.39.0.

distributor(distributor_id)[source]

Look up a distributor by ID.

Returns:

Distributor

The distributor belonging to this repository with the given ID.

None

If this repository has no distributor with the given ID.

property file_content

A list of file units stored in this repository.

Returns:

list[FileUnit]

New in version 2.4.0.

property rpm_content

A list of rpm units stored in this repository.

Returns:

list[RpmUnit]

New in version 2.4.0.

property srpm_content

A list of srpm units stored in this repository.

Returns:

list[Unit]

New in version 2.4.0.

property modulemd_content

A list of modulemd units stored in this repository.

Returns:

list[ModulemdUnit]

New in version 2.4.0.

property modulemd_defaults_content

A list of modulemd_defaults units stored in this repository.

Returns:

list[ModulemdDefaultsUnit]

New in version 2.4.0.

search_content(criteria=None)[source]

Search this repository for content matching the given criteria.

Parameters:

criteria (Criteria) – A criteria object used for this search.

Returns:

Future[Page]

A future representing the first page of results.

Each page will contain a collection of Unit objects.

New in version 2.4.0.

delete()[source]

Delete this repository from Pulp.

Returns:

Future[list[Task]]

A future which is resolved when the repository deletion has completed.

The future contains a list of zero or more tasks triggered and awaited during the delete operation.

This object also becomes detached from the client; no further updates are possible.

Raises:

DetachedException – If this instance is not attached to a Pulp client.

publish(options=<pubtools.pulplib._impl.model.repository.base.PublishOptions object>)[source]

Publish this repository.

The specific operations triggered on Pulp in order to publish a repo are not defined, but in Pulp 2.x, generally consists of triggering one or more distributors in sequence.

Parameters:

options (PublishOptions) –

Options used to customize the behavior of this publish.

If omitted, the Pulp server’s defaults apply.

Returns:

Future[list[Task]]

A future which is resolved when publish succeeds.

The future contains a list of zero or more tasks triggered and awaited during the publish operation.

Raises:

DetachedException – If this instance is not attached to a Pulp client.

sync(options=None)[source]

Sync repository with feed.

Parameters:

options (SyncOptions) – Options used to customize the behavior of sync process. If omitted, the Pulp server’s defaults apply.

Returns:

Future[list[Task]]

A future which is resolved when sync succeeds.

The future contains a list of zero or more tasks triggered and awaited during the sync operation.

Raises:

DetachedException – If this instance is not attached to a Pulp client.

New in version 2.5.0.

lock(context, duration=None)[source]

Obtain an exclusive advisory lock on this repository.

Returns a context manager representing the lock, intended to be used via a with statement. When the context is entered, the caller will wait until the lock can be acquired (or raise an exception if the lock can’t be acquired).

Only a single Client is able to hold the lock on a repository at any given time. The lock does not prevent modifications to the repo with the Pulp API, and does not affect other Pulp client implementations or instances of Client not using the lock method.

Parameters:

  • context –

    A short description of the task being carried out with the lock.

    This value will be added to the lock in the repo and may be used for debugging.

  • duration –

    Maximum duration of the lock, in seconds.

    This value is used only if this client fails to release the lock (for example, because the current process is killed). In this case, the duration will be used by other clients in order to detect and release stale locks, avoiding a deadlock.

    There is no way to extend the duration of an acquired lock, so the caller should always ensure they request a duration high enough to cover the entire expected lifetime of the lock.

remove_content(criteria=None, **kwargs)[source]

Remove all content of requested types from this repository.

Parameters:

  • criteria (Criteria) –

    A criteria object used to filter the contents for removal.

    Type IDs must be included in the criteria with any other filters. If omitted, filter criteria will be ignored and all the content will be removed. If criteria is omitted, all the content will be removed.

  • limit (None, int) – Limit the maximum number of units that will be disassociated by pulp.

Returns:

Future[list[Task]]

A future which is resolved when content has been removed.

The future contains a list of zero or more tasks triggered and awaited during the removal.

To obtain information on the removed content, use units().

Raises:

DetachedException – If this instance is not attached to a Pulp client.

New in version 1.5.0.

class pubtools.pulplib.Distributor[source]

Represents a Pulp distributor.

Method generated by attrs for class Distributor.

id

ID of this distributor (str).

This is an arbitrary string, though often matches exactly the type_id.

type_id

Type ID of this distributor (str).

The type ID of a distributor determines which content may be handled and which steps may be performed by the distributor. For example, distributors of type yum_distributor may be used to create yum repositories.

repo_id

The pubtools.pulplib.Repository ID this distributor is attached to.

relative_url

Default distribution URL for the repository which the distributor is attached to, relative to the Pulp content root.

last_publish

The datetime at which this distributor was last published, if known.

is_rsync

True for distributors in the ‘rsync distributor’ family (e.g. rpm_rsync_distributor).

delete()[source]

Delete this distributor from Pulp.

Returns:

Future[list[Task]]

A future which is resolved when the distributor deletion has completed.

The future contains a list of zero or more tasks triggered and awaited during the delete operation.

This object also becomes detached from the client; no further updates are possible.

Raises:

DetachedException – If this instance is not attached to a Pulp client or repository.

New in version 2.3.0.

class pubtools.pulplib.PublishOptions[source]

Options controlling a repository publish().

Method generated by attrs for class PublishOptions.

force

If True, Pulp should publish all data within a repository, rather than attempting to publish only changed data (or even skipping the publish).

Setting force=True may have a major performance impact when publishing large repos.

clean

If True, certain publish tasks will not only publish new/changed content, but will also attempt to erase formerly published content which is no longer present in the repo.

Setting clean=True generally implies force=True.

origin_only

If True, Pulp should only update the content units / origin path on remote hosts.

Only relevant if a repository has one or more distributors where is_rsync() is True.

rsync_extra_args

If present, provide these additional arguments to any rsync commands run during publish.

Ignored when rsync is not used.

class pubtools.pulplib.SyncOptions[source]

Options controlling a repository sync().

See also

Subclasses for specific repository types: FileSyncOptions, YumSyncOptions, ContainerSyncOptions

Method generated by attrs for class SyncOptions.

feed

URL where the repository’s content will be synchronized from.

ssl_validation

Indicates if the server’s SSL certificate is verified against the CA certificate uploaded.

ssl_ca_cert

CA certificate string used to validate the feed source’s SSL certificate

ssl_client_cert

Certificate used as the client certificate when synchronizing the repository

ssl_client_key

Private key to the certificate specified in ssl_client_cert

max_speed

The maximum download speed in bytes/sec for a task (such as a sync).

Default is None

proxy_host

A string representing the URL of the proxy server that should be used when synchronizing

proxy_port

An integer representing the port that should be used when connecting to proxy_host.

proxy_username

A string representing the username that should be used to authenticate with the proxy server

proxy_password

A string representing the password that should be used to authenticate with the proxy server

basic_auth_username

Username to authenticate with source which supports basic authentication.

basic_auth_password

Password to authenticate with source which supports basic authentication.

class pubtools.pulplib.Importer[source]

Importer is a pulp object that needs to be associated with repository in order to successfully sync or upload content to it.

Method generated by attrs for class Importer.

type_id

Type id of the importer.

config

Configuration dictionary of the importer.

Units

class pubtools.pulplib.Unit[source]

Represents a Pulp unit (a single piece of content).

New in version 1.5.0.

Method generated by attrs for class Unit.

content_type_id

The type of this unit.

This value will match one of the content types returned by get_content_type_ids().

Task

class pubtools.pulplib.Task[source]

Represents a Pulp task.

Method generated by attrs for class Task.

id

ID of this task (str).

completed

True if this task has completed, successfully or otherwise.

May be None if the state of this task is unknown.

succeeded

True if this task has completed successfully.

May be None if the state of this task is unknown.

error_summary

A summary of the reason for this task’s failure (if any).

This is a short string, generally a single line, suitable for display to users. The string includes the ID of the failed task.

error_details

Detailed information for this task’s failure (if any).

This may be a multi-line string and may include technical information such as a Python backtrace generated by Pulp.

error_details is a superset of the information available via error_summary, so it is not necessary to display both.

tags

The tags for this task.

Typically includes info on the task’s associated action and repo, such as:

["pulp:repository:rhel-7-server-rpms__7Server_x86_64",
 "pulp:action:publish"]
repo_id

The ID of the repository associated with this task, otherwise None.

units

Info on the units which were processed as part of this task (e.g. associated or unassociated).

This is an iterable. Each element is an instance of Unit containing information on a processed unit.

New in version 1.5.0.

units_data

Info on the units which were processed as part of this task (e.g. associated or unassociated).

This is a list. The list elements are the raw dicts as returned by Pulp. These should at least contain a ‘type_id’ and a ‘unit_key’.

Deprecated since version 1.5.0: Use units() instead.