Base Models

pulpcore.app.models.repository

Repository related Django models.

Repository(*args, **kwargs)

Bases: MasterModel

Collection of content.

Fields:

name (models.TextField): The repository name.
pulp_labels (HStoreField): Dictionary of string values.
description (models.TextField): An optional description.
next_version (models.PositiveIntegerField): A record of the next version number to be
    created.
retain_repo_versions (models.PositiveIntegerField): Number of repo versions to keep
user_hidden (models.BooleanField): Whether to expose this repo to users via the API

Relations:

content (models.ManyToManyField): Associated content.
remote (models.ForeignKeyField): Associated remote
pulp_domain (models.ForeignKeyField): The domain the Repository is a part of.

disk_size property

Returns the approximate size on disk for all artifacts stored across all versions.

on_demand_size property

Returns the approximate size of all on-demand artifacts stored across all versions.

on_new_version(version)

Called after a new repository version has been created.

Subclasses are expected to override this to do useful things.

Parameters:

Name	Type	Description	Default
version		The new repository version.	required

save(*args, **kwargs)

Saves Repository model and creates an initial repository version.

Parameters:

Name	Type	Description	Default
args	list	list of positional arguments for Model.save()	()
kwargs	dict	dictionary of keyword arguments to pass to Model.save()	{}

create_initial_version()

Create an initial repository version (version 0).

This method can be overriden by plugins if they require custom logic.

new_version(base_version=None)

Create a new RepositoryVersion for this Repository

Creation of a RepositoryVersion should be done in a RQ Job.

Parameters:

Name	Type	Description	Default
repository	Repository	to create a new version of	required
base_version	RepositoryVersion	an optional repository version whose content will be used as the set of content for the new version	None

Returns:

Type	Description
	pulpcore.app.models.RepositoryVersion: The Created RepositoryVersion

initialize_new_version(new_version)

Initialize the new RepositoryVersion with plugin-provided code.

This method should be overridden by plugin writers for an opportunity for plugin input. This method is intended to be called with the incomplete pulpcore.app.models.RepositoryVersion to validate or modify the content.

This method does not adjust the value of complete, or save the RepositoryVersion itself. Its intent is to allow the plugin writer an opportunity for plugin input before any other actions performed on the new RepositoryVersion.

Parameters:

Name	Type	Description	Default
new_version	RepositoryVersion	The incomplete RepositoryVersion to finalize.	required

finalize_new_version(new_version)

Finalize the incomplete RepositoryVersion with plugin-provided code.

This method should be overridden by plugin writers for an opportunity for plugin input. This method is intended to be called with the incomplete pulpcore.app.models.RepositoryVersion to validate or modify the content.

This method does not adjust the value of complete, or save the RepositoryVersion itself. Its intent is to allow the plugin writer an opportunity for plugin input before pulpcore marks the RepositoryVersion as complete.

Parameters:

Name	Type	Description	Default
new_version	RepositoryVersion	The incomplete RepositoryVersion to finalize.	required

Returns:

latest_version()

Get the latest RepositoryVersion on a repository

Parameters:

Name	Type	Description	Default
repository	Repository	to get the latest version of	required

Returns:

Type	Description
	pulpcore.app.models.RepositoryVersion: The latest RepositoryVersion

alatest_version() async

Get the latest RepositoryVersion on a repository asynchronously

Parameters:

Name	Type	Description	Default
repository	Repository	to get the latest version of	required

Returns:

Type	Description
	pulpcore.app.models.RepositoryVersion: The latest RepositoryVersion

natural_key()

Get the model's natural key.

:return: The model's natural key. :rtype: tuple

on_demand_artifacts_for_version(version) staticmethod

Returns the remote artifacts of on-demand content for a repository version.

Provides a method that plugins can override since RepositoryVersions aren't typed. Note: this only returns remote artifacts that have a non-null size.

Parameters:

Name	Type	Description	Default
version	RepositoryVersion	to get the remote artifacts for.	required

Returns: django.db.models.QuerySet: The remote artifacts that are contained within this version.

artifacts_for_version(version) staticmethod

Return the artifacts for a repository version.

Provides a method that plugins can override since RepositoryVersions aren't typed.

Parameters:

Name	Type	Description	Default
version	RepositoryVersion	to get the artifacts for	required

Returns:

Type	Description
	django.db.models.QuerySet: The artifacts that are contained within this version.

protected_versions()

Return repository versions that are protected.

A protected version is one that is being served by a distro directly or via publication.

Returns:

Type	Description
	django.db.models.QuerySet: Repo versions which are protected.

cleanup_old_versions()

Cleanup old repository versions based on retain_repo_versions.

invalidate_cache(everything=False)

Invalidates the cache if repository is present.

Remote(*args, **kwargs)

Bases: MasterModel

A remote source for content.

This is meant to be subclassed by plugin authors as an opportunity to provide plugin-specific persistent data attributes for a plugin remote subclass.

This object is a Django model that inherits from pulpcore.app.models.Remote which provides the platform persistent attributes for a remote object. Plugin authors can add additional persistent remote data by subclassing this object and adding Django fields. We defer to the Django docs on extending this model definition with additional fields.

Validation of the remote is done at the API level by a plugin defined subclass of [pulpcore.plugin.serializers.repository.RemoteSerializer][].

Fields:

name (models.TextField): The remote name.
pulp_labels (HStoreField): Dictionary of string values.
url (models.TextField): The URL of an external content source.
ca_cert (models.TextField): A PEM encoded CA certificate used to validate the
    server certificate presented by the external source.
client_cert (models.TextField): A PEM encoded client certificate used
    for authentication.
client_key (models.TextField): A PEM encoded private key used for authentication.
tls_validation (models.BooleanField): If True, TLS peer validation must be performed.
proxy_url (models.TextField): The optional proxy URL.
    Format: scheme://host:port
proxy_username (models.TextField): The optional username to authenticate with the proxy.
proxy_password (models.TextField): The optional password to authenticate with the proxy.
username (models.TextField): The username to be used for authentication when syncing.
password (models.TextField): The password to be used for authentication when syncing.
download_concurrency (models.PositiveIntegerField): Total number of
    simultaneous connections allowed to any remote during a sync.
policy (models.TextField): The policy to use when downloading content.
total_timeout (models.FloatField): Value for aiohttp.ClientTimeout.total on connections
connect_timeout (models.FloatField): Value for aiohttp.ClientTimeout.connect
sock_connect_timeout (models.FloatField): Value for aiohttp.ClientTimeout.sock_connect
sock_read_timeout (models.FloatField): Value for aiohttp.ClientTimeout.sock_read
headers (models.JSONField): Headers set on the aiohttp.ClientSession
rate_limit (models.IntegerField): Limits requests per second for each concurrent downloader

Relations:

pulp_domain (models.ForeignKey): The domain the Remote is a part of.

download_factory property

Return the DownloaderFactory which can be used to generate asyncio capable downloaders.

Upon first access, the DownloaderFactory is instantiated and saved internally.

Plugin writers are expected to override when additional configuration of the DownloaderFactory is needed.

Returns:

Name	Type	Description
DownloadFactory		The instantiated DownloaderFactory to be used by get_downloader().

download_throttler property

Return the Throttler which can be used to rate limit downloaders.

Upon first access, the Throttler is instantiated and saved internally. Plugin writers are expected to override when additional configuration of the DownloaderFactory is needed.

Returns:

Name	Type	Description
Throttler		The instantiated Throttler to be used by get_downloader()

get_downloader(remote_artifact=None, url=None, download_factory=None, **kwargs)

Get a downloader from either a RemoteArtifact or URL that is configured with this Remote.

This method accepts either remote_artifact or url but not both. At least one is required. If neither or both are passed a ValueError is raised.

Plugin writers are expected to override when additional configuration is needed or when another class of download is required.

Parameters:

Name	Type	Description	Default
url	str	The URL to download.	None
kwargs	dict	This accepts the parameters of [pulpcore.plugin.download.BaseDownloader][].	{}

Raises:

Type	Description
ValueError	If neither remote_artifact and url are passed, or if both are passed.

Returns:

Type	Description
	subclass of [pulpcore.plugin.download.BaseDownloader][]: A downloader that
	is configured with the remote settings.

get_remote_artifact_url(relative_path=None, request=None)

Get the full URL for a RemoteArtifact from relative path and request.

This method returns the URL for a RemoteArtifact by concatenating the Remote's url and the relative path. Plugin writers are expected to override this method when a more complex algorithm is needed to determine the full URL.

Parameters:

Name	Type	Description	Default
relative_path	str	The relative path of a RemoteArtifact	None
request	Request	The request object for this relative path	None

Raises:

Type	Description
ValueError	If relative_path starts with a '/'.

Returns:

Name	Type	Description
str		A URL for a RemoteArtifact available at the Remote.

get_remote_artifact_content_type(relative_path=None)

Get the type of content that should be available at the relative path.

Plugin writers are expected to implement this method. This method can return None if the relative path is for metadata that should only be streamed from the remote and not saved.

Parameters:

Name	Type	Description	Default
relative_path	str	The relative path of a RemoteArtifact	None

Returns:

Type	Description
	Optional[Class]: The optional Class of the content type that should be available at the relative path.

invalidate_cache()

Invalidates the cache if remote is present.

RepositoryContent

Bases: BaseModel

Association between a repository and its contained content.

Fields:

created (models.DatetimeField): When the association was created.

Relations:

content (models.ForeignKey): The associated content.
repository (models.ForeignKey): The associated repository.
version_added (models.ForeignKey): The RepositoryVersion which added the referenced
    Content.
version_removed (models.ForeignKey): The RepositoryVersion which removed the referenced
    Content.

RepositoryVersionQuerySet

Bases: QuerySet

A queryset that provides repository version filtering methods.

with_content(content)

Filters repository versions that contain the provided content units.

Parameters:

Name	Type	Description	Default
content	QuerySet	query of content	required

Returns:

Type	Description
	django.db.models.QuerySet: Repository versions which contains content.

RepositoryVersion

Bases: BaseModel

A version of a repository's content set.

Plugin Writers are strongly encouraged to use RepositoryVersion as a context manager to provide transactional safety, working directory set up, plugin finalization, and cleaning up the database on failures.

Examples::

with repository.new_version(repository) as new_version:
    new_version.add_content(content_q)
    new_version.remove_content(content_q)

Fields:

number (models.PositiveIntegerField): A positive integer that uniquely identifies a version
    of a specific repository. Each new version for a repo should have this field set to
    1 + the most recent version.
complete (models.BooleanField): If true, the RepositoryVersion is visible. This field is set
    to true when the task that creates the RepositoryVersion is complete.

Relations:

repository (models.ForeignKey): The associated repository.
base_version (models.ForeignKey): The repository version this was created from.

content property

Returns a set of content for a repository version

Returns:

Type	Description
	django.db.models.QuerySet: The content that is contained within this version.

Examples:

>>> repository_version = ...
>>>
>>> for content in repository_version.content:
>>>     content = content.cast()  # optional downcast.
>>>     ...
>>>
>>> for content in FileContent.objects.filter(pk__in=repository_version.content):
>>>     ...
>>>

artifacts property

Returns a set of artifacts for a repository version.

Returns:

Type	Description
	django.db.models.QuerySet: The artifacts that are contained within this version.

disk_size property

Returns the size on disk of all the artifacts in this repository version.

on_demand_size property

Returns the size of on-demand artifacts in this repository version.

get_content(content_qs=None)

Returns a set of content for a repository version

Parameters:

Name	Type	Description	Default
content_qs	QuerySet	The queryset for Content that will be restricted further to the content present in this repository version. If not given, Content.objects.all() is used (to return over all content types present in the repository version).	None

Returns:

Type	Description
	django.db.models.QuerySet: The content that is contained within this version.

Examples:

>>> repository_version = ...
>>>
>>> # Return a queryset of File objects in the repository
>>> repository_version.get_content(content_qs=File.objects)):

content_batch_qs(content_qs=None, order_by_params=('pk'), batch_size=1000)

Generate content batches to efficiently iterate over all content.

Generates query sets that span the content_qs content of the repository version. Each yielded query set evaluates to at most batch_size content records. This is useful to limit the memory footprint when iterating over all content of a repository version.

.. note::

* This generator is not safe against changes (i.e. add/remove content) during
  the iteration!

* As the method uses slices internally, the queryset must be ordered to yield
  stable results. By default, it is ordered by primary key.

Parameters:

Name	Type	Description	Default
order_by_params	tuple of str	The parameters for the order_by clause for the content. The Default is ("pk",). This needs to specify a stable order. For example, if you want to iterate by decreasing creation time stamps use ("-pulp_created", "pk") to ensure that content records are still sorted by primary key even if their creation timestamp happens to be equal.	('pk')
batch_size	int	The maximum batch size.	1000

Yields:

Type	Description
	[django.db.models.QuerySet][]: A QuerySet representing a slice of the content.

Example

The following code could be used to loop over all FileContent in repository_version. It prefetches the related pulpcore.plugin.models.ContentArtifact instances for every batch::

repository_version = ...

batch_generator = repository_version.content_batch_qs(
    content_class=FileContent.objects.all()
)
for content_batch_qs in batch_generator:
    content_batch_qs.prefetch_related("contentartifact_set")
    for content in content_batch_qs:
        ...

added(base_version=None)

Parameters:

Name	Type	Description	Default
base_version	RepositoryVersion	an optional repository version	None

Returns:

Name	Type	Description
QuerySet		The Content objects that were added by this version.

removed(base_version=None)

Parameters:

Name	Type	Description	Default
base_version	RepositoryVersion	an optional repository version	None

Returns:

Name	Type	Description
QuerySet		The Content objects that were removed by this version.

contains(content)

Check whether a content exists in this repository version's set of content

Returns:

Name	Type	Description
bool		True if the repository version contains the content, False otherwise

add_content(content)

Add a content unit to this version.

Parameters:

Name	Type	Description	Default
content	QuerySet	Set of Content to add	required

Raise

pulpcore.exception.ResourceImmutableError: if add_content is called on a complete RepositoryVersion

remove_content(content)

Remove content from the repository.

Parameters:

Name	Type	Description	Default
content	QuerySet	Set of Content to remove	required

Raise

pulpcore.exception.ResourceImmutableError: if remove_content is called on a complete RepositoryVersion

set_content(content)

Sets the repo version content by calling remove_content() then add_content().

Parameters:

Name	Type	Description	Default
content	QuerySet	Set of desired content	required

Raise

pulpcore.exception.ResourceImmutableError: if set_content is called on a complete RepositoryVersion

next()

Returns:

Type	Description
	pulpcore.app.models.RepositoryVersion: The next complete RepositoryVersion
	for the same repository.

Raises:

Type	Description
[RepositoryVersion.DoesNotExist][]	if there is not a RepositoryVersion for the same repository and with a higher "number".

previous()

Returns:

Type	Description
	pulpcore.app.models.RepositoryVersion: The previous complete RepositoryVersion for the same repository.

Raises:

Type	Description
DoesNotExist	if there is not a RepositoryVersion for the same repository and with a lower "number".

check_protected()

Check if a repo version is protected before trying to delete it.

delete(**kwargs)

Deletes a RepositoryVersion

If RepositoryVersion is complete and has a successor, squash RepositoryContent changes into the successor. If version is incomplete, delete and and clean up RepositoryContent, CreatedResource, and Repository objects.

Deletion of a complete RepositoryVersion should be done in a RQ Job.

__enter__()

Create the repository version

Returns:

Name	Type	Description
RepositoryVersion		self

__exit__(exc_type, exc_value, traceback)

Finalize and save the RepositoryVersion if no errors are raised, delete it if not

RepositoryVersionContentDetails

Bases: Model

content_href property

Generate URLs for the content types added, removed, or present in the RepositoryVersion.

For each content type present in or removed from this RepositoryVersion, create the URL of the viewset of that variety of content along with a query parameter which filters it by presence in this RepositoryVersion summary.

Parameters:

Name	Type	Description	Default
obj	RepositoryVersion	The RepositoryVersion being serialized.	required

Returns: dict: {: }

pulpcore.app.models.content

Content related Django models.

BulkCreateManager

Bases: Manager

A manager that provides a bulk_get_or_create()

bulk_get_or_create(objs, batch_size=None)

Insert the list of objects into the database and get existing objects from the database.

Do not call save() on each of the instances, do not send any pre/post_save signals, and do not set the primary key attribute if it is an autoincrement field (except if features.can_return_ids_from_bulk_insert=True). Multi-table models are not supported.

If an IntegrityError is raised while performing a bulk insert, this method falls back to inserting each instance individually. The already-existing instances are retrieved from the database and returned with the other newly created instances.

Parameters:

Name	Type	Description	Default
objs	iterable of models.Model	an iterable of Django Model instances	required
batch_size	int	how many are created in a single query	None

Returns:

Type	Description
	List of instances that were inserted into the database.

BulkTouchQuerySet

Bases: QuerySet

A query set that provides touch().

touch()

Update the timestamp_of_interest on all objects of the query.

Postgres' UPDATE call doesn't support order-by. This can (and does) result in deadlocks in high-concurrency environments, when using touch() on overlapping data sets. In order to prevent this, we choose to SELECT FOR UPDATE with SKIP LOCKS == True, and only update the rows that we were able to get locks on. Since a previously-locked-row implies that updating that row's timestamp-of-interest is the responsibility of whoever currently owns it, this results in correct data, while closing the window on deadlocks.

QueryMixin

A mixin that provides models with querying utilities.

q()

Returns a Q object that represents the model

HandleTempFilesMixin

A mixin that provides methods for handling temporary files.

save(*args, **kwargs)

Saves Model and closes the file associated with the Model

Parameters:

Name	Type	Description	Default
args	list	list of positional arguments for Model.save()	()
kwargs	dict	dictionary of keyword arguments to pass to Model.save()	{}

delete(*args, **kwargs)

Deletes Model and the file associated with the Model

Parameters:

Name	Type	Description	Default
args	list	list of positional arguments for Model.delete()	()
kwargs	dict	dictionary of keyword arguments to pass to Model.delete()	{}

ArtifactQuerySet

Bases: BulkTouchQuerySet

orphaned(orphan_protection_time)

Returns set of orphaned artifacts that are ready to be cleaned up.

Artifact

Bases: HandleTempFilesMixin, BaseModel

A file associated with a piece of content.

When calling save() on an Artifact, if the file is not stored in Django's storage backend, it is moved into place then.

Artifact is compatible with Django's bulk_create() method.

Fields:

file (pulpcore.app.models.fields.ArtifactFileField): The stored file. This field should
    be set using an absolute path to a temporary file.
    It also accepts `class:django.core.files.File`.
size (models.BigIntegerField): The size of the file in bytes.
md5 (models.CharField): The MD5 checksum of the file.
sha1 (models.CharField): The SHA-1 checksum of the file.
sha224 (models.CharField): The SHA-224 checksum of the file.
sha256 (models.CharField): The SHA-256 checksum of the file (REQUIRED).
sha384 (models.CharField): The SHA-384 checksum of the file.
sha512 (models.CharField): The SHA-512 checksum of the file.
timestamp_of_interest (models.DateTimeField): timestamp that prevents orphan cleanup.
pulp_domain (models.ForeignKey): The domain the artifact is a part of.

storage_path(name)

Callable used by FileField to determine where the uploaded file should be stored.

Parameters:

Name	Type	Description	Default
name	str	Original name of uploaded file. It is ignored by this method because the sha256 checksum is used to determine a file path instead.	required

before_save()

Pre-save hook that validates checksum rules prior to allowing an Artifact to be saved.

An Artifact with any checksums from the FORBIDDEN set will fail to save while raising an UnsupportedDigestValidationError exception.

Similarly, any checksums in DIGEST_FIELDS that is NOT set will raise a MissingDigestValidationError exception.

Raises:

Type	Description
	class: ~pulpcore.exceptions.UnsupportedDigestValidationError: When any of the keys on FORBIDDEN_DIGESTS are set for the Artifact
	class: ~pulpcore.exceptions.MissingDigestValidationError: When any of the keys on DIGEST_FIELDS are found to be missing from the Artifact

is_equal(other)

Is equal by matching digest.

Parameters:

Name	Type	Description	Default
other	Artifact	A artifact to match.	required

Returns:

Name	Type	Description
bool		True when equal.

init_and_validate(file, expected_digests=None, expected_size=None) staticmethod

Initialize an in-memory Artifact from a file, and validate digest and size info.

This accepts both a path to a file on-disk or a [pulpcore.app.files.PulpTemporaryUploadedFile][].

Parameters:

Name	Type	Description	Default
file	[pulpcore.app.files.PulpTemporaryUploadedFile][] or str	The PulpTemporaryUploadedFile to create the Artifact from or a string with the full path to the file on disk.	required
expected_digests	dict	Keyed on the algorithm name provided by hashlib and stores the value of the expected digest. e.g. {'md5': '912ec803b2ce49e4a541068d495ab570'}	None
expected_size	int	The number of bytes the download is expected to have.	None

Raises:

Type	Description
[pulpcore.exceptions.DigestValidationError][]	When any of the expected_digest values don't match the digest of the data
[pulpcore.exceptions.SizeValidationError][]	When the expected_size value doesn't match the size of the data
[pulpcore.exceptions.UnsupportedDigestValidationError][]	When any of the expected_digest algorithms aren't in the ALLOWED_CONTENT_CHECKSUMS list

Returns: An in-memory, unsaved pulpcore.plugin.models.Artifact

from_pulp_temporary_file(temp_file) classmethod

Creates an Artifact from PulpTemporaryFile.

Returns:

Type	Description
	An saved pulpcore.plugin.models.Artifact

touch()

Update timestamp_of_interest.

PulpTemporaryFile

Bases: HandleTempFilesMixin, BaseModel

A temporary file saved to the storage backend.

Commonly used to pass data to one or more tasks.

Fields:

file (pulpcore.app.models.fields.ArtifactFileField): The stored file. This field should
    be set using an absolute path to a temporary file.
    It also accepts `class:django.core.files.File`.

Relations

pulp_domain (pulpcore.app.models.Domain): The domain this temp file is a part of.

storage_path(name)

Callable used by FileField to determine where the uploaded file should be stored.

Parameters:

Name	Type	Description	Default
name	str	Original name of uploaded file. It is ignored by this method because the pulp_id is used to determine a file path instead.	required

init_and_validate(file, expected_digests=None, expected_size=None) staticmethod

Initialize an in-memory PulpTemporaryFile from a file, and validate digest and size info.

This accepts both a path to a file on-disk or a [pulpcore.app.files.PulpTemporaryUploadedFile][].

Parameters:

Name	Type	Description	Default
file	[pulpcore.app.files.PulpTemporaryUploadedFile][] or str	The PulpTemporaryUploadedFile to create the PulpTemporaryFile from or a string with the full path to the file on disk.	required
expected_digests	dict	Keyed on the algorithm name provided by hashlib and stores the value of the expected digest. e.g. {'md5': '912ec803b2ce49e4a541068d495ab570'}	None
expected_size	int	The number of bytes the download is expected to have.	None

Raises:

Type	Description
[pulpcore.exceptions.DigestValidationError][]	When any of the expected_digest values don't match the digest of the data
[pulpcore.exceptions.SizeValidationError][]	When the expected_size value doesn't match the size of the data
[pulpcore.exceptions.UnsupportedDigestValidationError][]	When any of the expected_digest algorithms aren't in the ALLOWED_CONTENT_CHECKSUMS list

Returns:

Type	Description
	An in-memory, unsaved pulpcore.plugin.models.PulpTemporaryFile

ContentQuerySet

Bases: BulkTouchQuerySet

orphaned(orphan_protection_time, content_pks=None)

Returns set of orphaned content that is ready to be cleaned up.

Content(*args, **kwargs)

Bases: MasterModel, QueryMixin

A piece of managed content.

Fields

upstream_id (models.UUIDField) : identifier of content imported from an 'upstream' Pulp timestamp_of_interest (models.DateTimeField): timestamp that prevents orphan cleanup

Relations:

_artifacts (models.ManyToManyField): Artifacts related to Content through ContentArtifact
pulp_domain (models.ForeignKey): Pulp Domain this content lives in

repository_types() classmethod

Tuple of the repository models that can store this content type.

Populated at start up time. Read only.

natural_key_fields() classmethod

Returns a tuple of the natural key fields which usually equates to unique_together fields.

This can be overwritten in subclasses and should return a tuple of field names.

natural_key()

Get the model's natural key based on natural_key_fields.

Returns:

Name	Type	Description
tuple		The natural key.

natural_key_dict()

Get the model's natural key as a dictionary of keys and values.

init_from_artifact_and_relative_path(artifact, relative_path) staticmethod

Return an instance of the specific content by inspecting an artifact.

Plugin writers are expected to override this method with an implementation for a specific content type. If the content type is stored with multiple artifacts plugin writers can instead return a tuple of the unsaved content instance and a dictionary of the content's artifacts by their relative paths.

For example::

if path.isabs(relative_path):
    raise ValueError(_("Relative path can't start with '/'."))
return FileContent(relative_path=relative_path, digest=artifact.sha256)

Parameters:

Name	Type	Description	Default
relative_path	str	Relative path for the content	required

Raises:

Type	Description
ValueError	If relative_path starts with a '/'.

Returns:

Type	Description
	An un-saved instance of pulpcore.plugin.models.Content sub-class. Or a
	tuple of an un-saved instance of pulpcore.plugin.models.Content and a dict
	of form [relative_path:str, Optional[artifact:~pulpcore.plugin.models.Artifact]]

touch()

Update timestamp_of_interest.

ContentArtifact

Bases: BaseModel, QueryMixin

A relationship between a Content and an Artifact.

Serves as a through model for the '_artifacts' ManyToManyField in Content. Artifact is protected from deletion if it's present in a ContentArtifact relationship.

sort_key(ca) staticmethod

Static method for defining a sort-key for a specified ContentArtifact.

Sorting lists of ContentArtifacts is critical for avoiding deadlocks in high-concurrency environments, when multiple workers may be operating on similar sets of content at the same time. Providing a stable sort-order becomes problematic when the CAs in question haven't been persisted - in that case, pulp_id can't be relied on, as it will change when the object is stored in the DB and its "real" key is generated.

This method produces a key based on the content/artifact represented by the CA.

Returns:

Type	Description
	a tuple of (str(content-key), str(artifact-key)) that can be reliably sorted on

RemoteArtifactQuerySet

Bases: QuerySet

QuerySet that provides methods for querying RemoteArtifact.

acs()

Return RemoteArtifacts if they belong to an ACS in the same Domain.

order_by_acs()

Order RemoteArtifacts returning ones with ACSes first.

RemoteArtifact

Bases: BaseModel, QueryMixin

Represents a content artifact that is provided by a remote (external) repository.

Remotes that want to support deferred download policies should use this model to store information required for downloading an Artifact at some point in the future. At a minimum this includes the URL, the ContentArtifact, and the Remote that created it. It can also store expected size and any expected checksums.

Fields:

url (models.TextField): The URL where the artifact can be retrieved.
size (models.BigIntegerField): The expected size of the file in bytes.
md5 (models.CharField): The expected MD5 checksum of the file.
sha1 (models.CharField): The expected SHA-1 checksum of the file.
sha224 (models.CharField): The expected SHA-224 checksum of the file.
sha256 (models.CharField): The expected SHA-256 checksum of the file.
sha384 (models.CharField): The expected SHA-384 checksum of the file.
sha512 (models.CharField): The expected SHA-512 checksum of the file.

Relations:

content_artifact (pulpcore.app.models.ForeignKey)
    ContentArtifact associated with this RemoteArtifact.
remote (django.db.models.ForeignKey) Remote that created the
    RemoteArtifact.
pulp_domain (django.db.models.ForeignKey) Domain the RemoteArtifact is a part of.

validate_checksums()

Validate if RemoteArtifact has allowed checksum or no checksum at all.

SigningService

Bases: BaseModel

A model used for producing signatures.

Fields

name (models.TextField): A unique name describing a script (or executable) used for signing. public_key (models.TextField): The value of the public key. script (models.TextField): An absolute path to an external signing script (or executable).

sign(filename, env_vars=None)

Signs the file provided via 'filename' by invoking an external script (or executable).

The external script is run as a subprocess. This is done in the expectation that the script has been validated as an external signing service by the validate() method. This validation is currently only done when creating the signing service object, but not at the time of use.

Parameters:

Name	Type	Description	Default
filename	str	A relative path to a file which is intended to be signed.	required
env_vars	dict	dictionary of environment variables	None

Raises:

Type	Description
RuntimeError	If the return code of the script is not equal to 0.

Returns:

Type	Description
	A dictionary as validated by the validate() method.

asign(filename, env_vars=None) async

Async version of sign.

validate()

Ensure that the external signing script produces the desired behaviour.

With desired behaviour we mean the behaviour as validated by this method. Subclasses are required to implement this method. Works by calling the sign() method on some test data, and verifying that any desired signatures/signature files are returned and are valid. Must also enforce the desired return value format of the sign() method.

Raises:

Type	Description
RuntimeError	If the script failed to produce the desired outcome for the test data.

save(*args, **kwargs)

Save a signing service to the database (unless it fails to validate).

AsciiArmoredDetachedSigningService

Bases: SigningService

A model used for creating detached ASCII armored signatures.

validate()

Validate a signing service for a detached ASCII armored signature.

The validation seeks to ensure that the sign() method returns a dict as follows:

{"file": "signed_file.xml", "signature": "signed_file.asc"}

The method creates a file with some content, signs the file, and checks if the signature can be verified by the provided public key.

Raises:

Type	Description
RuntimeError	If the validation has failed.

pulpcore.app.models.publication

PublicationQuerySet

Bases: QuerySet

A queryset that provides publication filtering methods.

with_content(content)

Filters publictions that contain the provided content units.

Parameters:

Name	Type	Description	Default
content	QuerySet	query of content	required

Returns:

Type	Description
	django.db.models.QuerySet: Publications that contain content.

Publication(*args, **kwargs)

Bases: MasterModel

A publication contains metadata and artifacts associated with content contained within a RepositoryVersion.

Using as a context manager is highly encouraged. On context exit, the complete attribute is set True provided that an exception has not been raised. In the event and exception has been raised, the publication is deleted.

Fields

complete (models.BooleanField): State tracking; for internal use. Indexed. pass_through (models.BooleanField): Indicates that the publication is a pass-through to the repository version. Enabling pass-through has the same effect as creating a PublishedArtifact for all of the content (artifacts) in the repository.

Relations

repository_version (models.ForeignKey): The RepositoryVersion used to create this Publication. pulp_domain (models.ForeignKey): The domain the Publication is a part of.

Examples:

>>> repository_version = ...
>>>
>>> with Publication.create(repository_version) as publication:
>>>     for content in repository_version.content():
>>>         for content_artifact in content.contentartifact_set.all():
>>>             artifact = PublishedArtifact(...)
>>>             artifact.save()
>>>             metadata = PublishedMetadata.create_from_file(...)
>>>             ...
>>>

repository property

Return the associated repository

Returns:

Type	Description
	pulpcore.app.models.Repository: The repository associated to this publication

create(repository_version, pass_through=False) classmethod

Create a publication.

This should be used to create a publication. Using Publication() directly is highly discouraged.

Parameters:

Name	Type	Description	Default
repository_version	RepositoryVersion	The repository version to be published.	required
pass_through	bool	Indicates that the publication is a pass-through to the repository version. Enabling pass-through has the same effect as creating a PublishedArtifact for all of the content (artifacts) in the repository.	False

Returns:

Type	Description
	pulpcore.app.models.Publication: A created Publication in an incomplete state.

Notes

Adds a Task.created_resource for the publication.

delete(**kwargs)

Delete the publication.

Parameters:

Name	Type	Description	Default
**kwargs	dict	Delete options.	{}

Notes

Deletes the Task.created_resource when complete is False.

finalize_new_publication()

Finalize the incomplete Publication with plugin-provided code.

This method should be overridden by plugin writers for an opportunity for plugin input. This method is intended to be used to validate or modify the content.

This method does not adjust the value of complete, or save the Publication itself. Its intent is to allow the plugin writer an opportunity for plugin input before pulpcore marks the Publication as complete.

__enter__()

Enter context.

Returns:

Name	Type	Description
Publication		self

__exit__(exc_type, exc_val, exc_tb)

Set the complete=True, create the publication.

Parameters:

Name	Type	Description	Default
exc_type	Type	(optional) Type of exception raised.	required
exc_val	Exception	(optional) Instance of exception raised.	required
exc_tb	TracebackType	(optional) stack trace.	required

PublishedArtifact

Bases: BaseModel

An artifact that is part of a publication.

Fields

relative_path (models.TextField): The (relative) path component of the published url.

Relations

content_artifact (models.ForeignKey): The referenced content artifact. publication (models.ForeignKey): The publication in which the artifact is included.

PublishedMetadata(*args, **kwargs)

Bases: Content

Metadata file that is part of a publication.

Fields

relative_path (models.TextField): The (relative) path component of the published url.

Relations

publication (models.ForeignKey): The publication in which the artifact is included.

create_from_file(file, publication, relative_path=None) classmethod

Creates PublishedMetadata along with Artifact, ContentArtifact, and PublishedArtifact.

Parameters:

Name	Type	Description	Default
file	File	an open File that contains metadata	required
publication	Publication	The publication in which the PublishedMetadata is included.	required
relative_path	str	relative path at which the Metadata is published at. If None, the name of the 'file' is used.	None

Returns:

Name	Type	Description
PublishedMetadata	PublishedMetadata	A saved instance of PublishedMetadata.

ContentGuard(*args, **kwargs)

Bases: MasterModel

Defines a named content guard.

This is meant to be subclassed by plugin authors as an opportunity to provide plugin-specific persistent attributes and additional validation for those attributes. The permit() method must be overridden to provide the web request authorization logic.

This object is a Django model that inherits from pulpcore.app.models.ContentGuard which provides the platform persistent attributes for a content-guard. Plugin authors can add additional persistent attributes by subclassing this class and adding Django fields. We defer to the Django docs on extending this model definition with additional fields.

Fields

name (models.TextField): Unique guard name per domain. description (models.TextField): An optional description. pulp_domain (models.ForeignKey): The domain the ContentGuard is a part of.

permit(request)

Authorize the specified web request.

Parameters:

Name	Type	Description	Default
request	Request	A request for a published file.	required

Raises:

Type	Description
PermissionError	When not authorized.

RBACContentGuard(*args, **kwargs)

Bases: ContentGuard, AutoAddObjPermsMixin

A content guard that protects content based on RBAC permissions.

permit(request)

Authorize the specified web request. Expects the request to have already been authenticated.

ContentRedirectContentGuard(*args, **kwargs)

Bases: ContentGuard, AutoAddObjPermsMixin

Content guard to allow preauthenticated redirects to the content app.

permit(request)

Permit preauthenticated redirects from pulp-api.

preauthenticate_url(url, salt=None)

Add validate_token to urls query string.

HeaderContentGuard(*args, **kwargs)

Bases: ContentGuard, AutoAddObjPermsMixin

Content guard to protect content based on a header value.

CompositeContentGuard(*args, **kwargs)

Bases: ContentGuard, AutoAddObjPermsMixin

Content guard to allow a list of contentguards to be evaluated on access.

Content-guards in the guards list have their permit() calls issued in order. At the first "pass" result, access is permitted. Only if ALL guards in the list forbid access, is access forbidden.

guards (django.db.models.ManyToManyField): ContentGuards to invoke.

permit(request)

Permit if ANY content-guard allows (OR permissions).

BaseDistribution(*args, **kwargs)

Bases: MasterModel

A distribution defines how a publication is distributed by the Content App.

This abstract model can be used by plugin writers to create concrete distributions that are stored in separate tables from the Distributions provided by pulpcore.

The name must be unique.

The base_path must have no overlapping components. So if a Distribution with base_path of a/path/foo existed, you could not make a second Distribution with a base_path of a/path or a because both are subpaths of a/path/foo.

Note

This class is no longer supported and cannot be removed from Pulp 3 due to possible problems with old migrations for plugins. Until the migrations are squashed, this class should be preserved.

Fields

name (models.TextField): The name of the distribution. Examples: "rawhide" and "stable". base_path (models.TextField): The base (relative) path component of the published url.

Relations

content_guard (models.ForeignKey): An optional content-guard. remote (models.ForeignKey): A remote that the content app can use to find content not yet stored in Pulp.

Distribution(*args, **kwargs)

Bases: MasterModel

A Distribution defines how the Content App distributes a publication or repository_version.

This master model can be used by plugin writers to create detail Distribution objects.

The name must be unique.

The base_path must have no overlapping components. So if a Distribution with base_path of a/path/foo existed, you could not make a second Distribution with a base_path of a/path or a because both are subpaths of a/path/foo.

Subclasses are expected to use either the publication or repository_version field, but not both. The content app that serves content is not prepared to serve content both ways at the same time.

Fields

name (models.TextField): The name of the distribution. Examples: "rawhide" and "stable". pulp_labels (HStoreField): Dictionary of string values. base_path (models.TextField): The base (relative) path component of the published url. hidden (models.BooleanField): Whether this distribution should be hidden in the content app.

Relations

content_guard (models.ForeignKey): An optional content-guard. publication (models.ForeignKey): Publication to be served. remote (models.ForeignKey): A remote that the content app can use to find content not yet stored in Pulp. repository (models.ForeignKey): The latest RepositoryVersion for this Repository will be served. repository_version (models.ForeignKey): RepositoryVersion to be served. pulp_domain (models.ForeignKey): The domain the Distribution is a part of.

content_handler(path)

Handler to serve extra, non-Artifact content for this Distribution

Parameters:

Name	Type	Description	Default
path	str	The path being requested	required

Returns: None if there is no content to be served at path. Otherwise a aiohttp.web_response.Response with the content.

content_handler_list_directory(rel_path)

Generate the directory listing entries for content_handler

Parameters:

Name	Type	Description	Default
rel_path	str	relative path inside the distribution's base_path. For example,	required

Returns: Set of strings for the extra entries in rel_path

content_headers_for(path)

Opportunity for Distribution to specify response-headers for a specific path

Parameters:

Name	Type	Description	Default
path	str	The path being requested	required

Returns: Empty dictionary, or a dictionary with HTTP Response header/value pairs.

invalidate_cache()

Invalidates the cache if enabled.

ArtifactDistribution(*args, **kwargs)

Bases: Distribution

Serve artifacts by their uuid.

content_handler(path)

Serve an artifact or return 404.