pulpcore.plugin.models¶

All models documented here should be imported directly from the pulpcore.plugin.models namespace.

class pulpcore.plugin.models.AccessPolicy(*args, **kwargs)

A model storing a viewset authorization policy and permission assignment of new objects created.

Fields

creation_hooks (models.JSONField) – A list of dictionaries identifying callables on the pulpcore.plugin.access_policy.AccessPolicyFromDB which can add user or group roles for newly created objects. This is a nullable field due to not all endpoints creating objects.
statements (models.JSONField) – A list of drf-access-policy statements.
viewset_name (models.CharField) – The name of the viewset this instance controls authorization for.
customized (BooleanField) – False if the AccessPolicy has been user-modified. True otherwise. Defaults to False.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.AlternateContentSource(*args, **kwargs)

Alternate sources of content.

Fields

name (models.TextField) – The alternate content source name.
last_refreshed (models.DateTimeField) – Last refreshed date.
url (models.TextField) – URL of Alternate Content Source.

Relations

remote (models.ForeignKeyField) – Associated remote

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.AlternateContentSourcePath(*args, **kwargs)

Alternate sources of content.

Fields

path (models.TextField) – The alternate content source name.

Relations

alternate_content_source (models.ForeignKeyField) – Associated AlternateContentSource
repository (models.ForeignKeyField) – Associated repository

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.Artifact(*args, **kwargs)

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

exception DoesNotExist

exception MultipleObjectsReturned

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: class: ~pulpcore.exceptions.UnsupportedDigestValidationError: When any of the keys on FORBIDDEN_DIGESTS are set for the Artifact
Raises: class: ~pulpcore.exceptions.MissingDigestValidationError: When any of the keys on DIGEST_FIELDS are found to be missing from the Artifact

classmethod from_pulp_temporary_file(temp_file)

Creates an Artifact from PulpTemporaryFile.

Returns: An saved Artifact

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

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 PulpTemporaryUploadedFile.

Parameters

file (PulpTemporaryUploadedFile or str) – The PulpTemporaryUploadedFile to create the Artifact from or a string with the full path to the file on disk.
expected_digests (dict) – Keyed on the algorithm name provided by hashlib and stores the value of the expected digest. e.g. {‘md5’: ‘912ec803b2ce49e4a541068d495ab570’}
expected_size (int) – The number of bytes the download is expected to have.

Raises

DigestValidationError – When any of the expected_digest values don’t match the digest of the data
SizeValidationError – When the expected_size value doesn’t match the size of the data
UnsupportedDigestValidationError – When any of the expected_digest algorithms aren’t in the ALLOWED_CONTENT_CHECKSUMS list

Returns

An in-memory, unsaved Artifact

is_equal(other)

Is equal by matching digest.

Parameters: other (pulpcore.app.models.Artifact) – A artifact to match.
Returns: True when equal.
Return type: bool

storage_path(name)

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

Parameters: 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.

touch(): Update timestamp_of_interest.

class pulpcore.plugin.models.AsciiArmoredDetachedSigningService(*args, **kwargs)

A model used for creating detached ASCII armored signatures.

exception DoesNotExist

exception MultipleObjectsReturned

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: RuntimeError – If the validation has failed.

class pulpcore.plugin.models.AutoAddObjPermsMixin(*args, **kwargs)

A mixin that automatically adds roles based on the creation_hooks data.

To use this mixin, your model must support django-lifecycle.

To use this mixin, you must define a class attribute named ACCESS_POLICY_VIEWSET_NAME containing the name of the ViewSet associated with this object.

This mixin adds an after_create hook which properly interprets the creation_hooks data and calls methods also provided by this mixin to add roles.

These mixing are provided by default:

add_for_object_creator will add the permissions to the creator of the object.
add_for_users will add the permissions for one or more users by name.
add_for_groups will add the permissions for one or more groups by name.
add_roles_for_object_creator will add the roles to the creator of the object.
add_roles_for_users will add the roles for one or more users by name.
add_roles_for_groups will add the roles for one or more groups by name.

add_for_groups(permissions, groups)

Adds object-level permissions for one or more groups for this newly created object.

Parameters

permissions (str or list) – One or more object-level permissions to be added for the groups. The permission names are in the form of <app_name>.<codename>, e.g. "core.change_task". This can either be a single permission as a string, or list of permission names.
groups (str or list) – One or more groups who will receive object-level permissions. This can either be a single group name as a string or a list of group names.

Raises

ObjectDoesNotExist – If any of the groups do not exist.

add_for_object_creator(permissions, *args)

Adds object-level permissions for the user creating the newly created object.

If the django_currentuser.middleware.get_current_authenticated_user returns None because the API client did not provide authentication credentials, no permissions are added and this passes silently. This allows endpoints which create objects and do not require authorization to execute without error.

Parameters: permissions (str or list) – One or more object-level permissions to be added for the users. The permission names are in the form of <app_name>.<codename>, e.g. "core.change_task". This can either be a single permission as a string, or list of permission names.

add_for_users(permissions, users)

Adds object-level permissions for one or more users for this newly created object.

Parameters

permissions (str or list) – One or more object-level permissions to be added for the users. The permission names are in the form of <app_name>.<codename>, e.g. "core.change_task". This can either be a single permission as a string, or list of permission names.
users (str or list) – One or more users who will receive object-level permissions. This can either be a single username as a string or a list of usernames.

Raises

ObjectDoesNotExist – If any of the users do not exist.

add_roles_for_groups(roles, groups)

Adds object-level roles for one or more groups for this newly created object.

Parameters

roles (str or list) – One or more object-level roles to be added for the groups. This can either be a single role as a string, or list of role names.
groups (str or list) – One or more groups who will receive object-level roles. This can either be a single group name as a string or a list of group names.

Raises

ObjectDoesNotExist – If any of the groups do not exist.

add_roles_for_object_creator(roles)

Adds object-level roles for the user creating the newly created object.

If the django_currentuser.middleware.get_current_authenticated_user returns None because the API client did not provide authentication credentials, no permissions are added and this passes silently. This allows endpoints which create objects and do not require authorization to execute without error.

Parameters: roles (list or str) – One or more roles to be added at the object-level for the user. This can either be a single role as a string, or list of role names.

add_roles_for_users(roles, users)

Adds object-level roles for one or more users for this newly created object.

Parameters

roles (str or list) – One or more roles to be added at object-level for the users. This can either be a single role as a string, or a list of role names.
users (str or list) – One or more users who will receive object-level roles. This can either be a single username as a string or a list of usernames.

Raises

ObjectDoesNotExist – If any of the users do not exist.

class pulpcore.plugin.models.AutoDeleteObjPermsMixin

A mixin that automatically deletes user and group permissions for an object prior to deletion.

To use this mixin, your model must support django-lifecycle.

remove_for_groups(permissions, groups)

Removes object-level permissions for one or more groups for this object. Requires AutoAddObjPermsMixin

Parameters

permissions (str or list) – One or more object-level permissions to be removed for the groups. The permission names are in the form of <app_name>.<codename>, e.g. "core.change_task". This can either be a single permission as a string, or list of permission names.
groups (str or list) – One or more groups who will lose these object-level permissions. This can either be a single group name as a string or a list of group names.

Raises

ObjectDoesNotExist – If any of the groups do not exist.

remove_for_users(permissions, users)

Removes object-level permissions for one or more users for this object. Requires AutoAddObjPermsMixin

Parameters

permissions (str or list) – One or more object-level permissions to be added for the users. The permission names are in the form of <app_name>.<codename>, e.g. "core.change_task". This can either be a single permission as a string, or list of permission names.
users (str or list) – One or more users who will lose these object-level permissions. This can either be a single username as a string or a list of usernames.

Raises

ObjectDoesNotExist – If any of the users do not exist.

class pulpcore.plugin.models.BaseModel(*args, **kwargs)

Base model class for all Pulp models.

This model inherits from LifecycleModel which allows all Pulp models to be used with django-lifecycle.

Fields

pulp_created (models.DateTimeField) – Created timestamp UTC.
pulp_last_updated (models.DateTimeField) – Last updated timestamp UTC.

Relations

pulp_labels (GenericRelation) – A list of key/value labels.

References

class pulpcore.plugin.models.Content(*args, **kwargs)

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

exception DoesNotExist

exception MultipleObjectsReturned

static init_from_artifact_and_relative_path(artifact, relative_path)

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.

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

artifact (Artifact) – An instance of an Artifact
relative_path (str) – Relative path for the content

Raises

ValueError – If relative_path starts with a ‘/’.

Returns

An un-saved instance of Content sub-class.

natural_key()

Get the model’s natural key based on natural_key_fields.

Returns: The natural key.
Return type: tuple

natural_key_dict(): Get the model’s natural key as a dictionary of keys and values.

classmethod natural_key_fields()

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.

touch(): Update timestamp_of_interest.

class pulpcore.plugin.models.ContentArtifact(*args, **kwargs)

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.

exception DoesNotExist

exception MultipleObjectsReturned

static sort_key(ca)

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.

Parameters: ca (ContentArtifact) – The CA we need a key for
Returns: a tuple of (str(content-key), str(artifact-key)) that can be reliably sorted on

class pulpcore.plugin.models.ContentGuard(*args, **kwargs)

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 :class: 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.
description (models.TextField) – An optional description.

exception DoesNotExist

exception MultipleObjectsReturned

permit(request)

Authorize the specified web request.

Parameters: request (aiohttp.web.Request) – A request for a published file.
Raises: PermissionError – When not authorized.

pulpcore.plugin.models.ContentManager: alias of django.db.models.manager.ContentManagerFromBulkTouchQuerySet

class pulpcore.plugin.models.CreatedResource(*args, **kwargs)

Resources created by the task.

Relations: task (models.ForeignKey) – The task that created the resource.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.Distribution(*args, **kwargs)

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”.
base_path (models.TextField) – The base (relative) path component of the published url.

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.

exception DoesNotExist

exception MultipleObjectsReturned

content_handler(path)

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

Parameters: path (str) – The path being requested
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

rel_path (str) – relative path inside the distribution’s base_path. For example,
'' (the root of the base_path is) –
'subdir/'. (a subdir within the base_path is) –

Returns

Set of strings for the extra entries in rel_path

invalidate_cache(): Invalidates the cache if enabled.

class pulpcore.plugin.models.Export(*args, **kwargs)

A model that represents an Export.

Fields

params (models.JSONField) – A set of parameters used to create the export

Relations

task (models.ForeignKey) – The Task that created the export
exporter (models.ForeignKey) – The Exporter that exported the resource.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.Exporter(*args, **kwargs)

A base model that provides logic to export a set of content and keep track of Exports.

Fields: name (models.TextField) – The exporter unique name.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.FilesystemExporter(*args, **kwargs)

A base model that provides logic to export a set of content to the filesystem.

Fields: path (models.TextField) – a full path where the export will go.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.GroupProgressReport(*args, **kwargs)

A model for all progress reporting in a Task Group.

All progress reports have a message, code and are related to a Task Group.

Once a Task Group is created, plugin writers should create these objects ahead. For example:

>>> task_group = TaskGroup(description="Migration Sub-tasks")
>>> task_group.save()
>>> group_pr = GroupProgressReport(
>>>     message="Repo migration",
>>>     code="create.repo_version",
>>>     task_group=task_group).save()

Taks that will be executing certain work, and is part of a TaskGroup, will look for the Task group it belongs to and find appropriate progress report by its code and will update it accordingly.

For example:

>>> task_group = TaskGroup.current()
>>> progress_repo = task_group.group_progress_reports.filter(code='create.repo_version')
>>> progress_repo.update(done=F('done') + 1)

To avoid race conditions/cache invalidation issues, this pattern needs to be used so that operations are performed directly inside the database:

.update(done=F(‘done’) + 1)

See: https://docs.djangoproject.com/en/3.0/ref/models/expressions/#f-expressions Important: F() objects assigned to model fields persist after saving the model instance and will be applied on each save(). Do not use save() and use update() instead, otherwise refresh_from_db() should be called after each save()

Fields

message (models.TextField) – short message for the progress update, typically shown to the user. (required)
code (models.TextField) – identifies the type of progress report
total – (models.IntegerField) The total count of items to be handled
done (models.IntegerField) – The count of items already processed. Defaults to 0.
suffix (models.TextField) – Customizable suffix rendered with the progress report See the docs. for more info.

Relations

task_group – The task group associated with this group progress report.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.Import(*args, **kwargs)

A model that represents imports into Pulp.

Fields

params (models.JSONField) – A set of parameters used to run the import

Relations

task (models.ForeignKey) – The Task that ran the import
importer (models.ForeignKey) – The Importer that imported the export

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.Importer(*args, **kwargs)

A base model that provides logic to import data into Pulp.

Can be extended by plugins to provide import functionality.

Fields: name (models.TextField) – The importer unique name.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.Label(*args, **kwargs)

Model for handling resource labels.

Labels are key/value data that can be associated with any BaseModel.

Fields

pulp_id (models.UUIDField) – Primary key identifier
object_id (models.UUIDField) – Resource id
key (models.CharField) – Key of the label
value (models.TextField) – Value of the label

Relations

content_object (GenericForeignKey) – Associated resource
content_type (models.ForeignKey) – Content type of the resource

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.MasterModel(*args, **kwargs)

Base model for the “Master” model in a “Master-Detail” relationship.

Provides methods for casting down to detail types, back up to the master type, as well as a model field for tracking the type.

Variables: TYPE (str) – Default constant value saved into the pulp_type field of Model instances
Fields: pulp_type – The user-facing string identifying the detail type of this model

Warning

Subclasses of this class rely on there being no other parent/child Model relationships than the Master/Detail relationship. All subclasses must use only abstract Model base classes for MasterModel to behave properly. Specifically, OneToOneField relationships must not be used in any MasterModel subclass.

cast()

Return a “Detail” model instance of this master-detail pair.

If this model is already an instance of its detail type, it will return itself.

classmethod get_pulp_type(): Get the “pulp_type” string associated with this MasterModel type.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

property master

The “Master” model instance of this master-detail pair

If this is already the master model instance, it will return itself.

class pulpcore.plugin.models.ProgressReport(*args, **kwargs)

A model for all progress reporting.

All progress reports have a message, state, and are related to a Task.

Plugin writers should create these objects to show progress reporting of a single step or aspect of work which has a name and state. For example:

>>> ProgressReport(
>>>     message='Publishing files', code='publish', total=23
>>> )  # default: state='waiting' and done=0

>>> ProgressReport(
>>>     message='Publishing files', code='publish', total=23, state='running'
>>> )  # specify the state
>>> ProgressReport(
>>>     message='Publishing files', code='publish', total=23, done=16
>>> )  # already completed 16

Update the state to COMPLETED and save it:

>>> progress_bar = ProgressReport(
>>>     message='Publishing files', code='publish', total=23, state='running'
>>> )
>>> progress_bar.state = 'completed'
>>> progress_bar.save()

The ProgressReport() is a context manager that provides automatic state transitions and saving for the RUNNING CANCELED COMPLETED and FAILED states. The increment() method can be called in the loop as work is completed. When ProgressReport() is used as a context manager progress reporting is rate limited to every 500 milliseconds. Use it as follows:

>>> progress_bar = ProgressReport(
>>>     message='Publishing files', code='publish', total=len(files_iterator)
>>> )
>>> progress_bar.save()
>>> with progress_bar:
>>>     # progress_bar saved as 'running'
>>>     for file in files_iterator:
>>>         handle(file)
>>>         progress_bar.increment()  # increments and saves
>>> # progress_bar is saved as 'completed' if no exception or 'failed' otherwise

A convenience method called iter() allows you to avoid calling increment() directly:

>>> progress_bar = ProgressReport(
>>>     message='Publishing files', code='publish', total=len(files_iterator)
>>> )
>>> progress_bar.save()
>>> with progress_bar:
>>>     for file in progress_bar.iter(files_iterator):
>>>         handle(file)

You can also use this short form which handles all necessary save() calls:

>>> data = dict(message='Publishing files', code='publish', total=len(files_iterator))
>>> with ProgressReport(**data) as pb:
>>>     for file in pb.iter(files_iterator):
>>>         handle(file)

ProgressReport objects are associated with a Task and auto-discover and populate the task id when saved.

When using threads to update a ProgressReport in parallel, it is recommended that all threads share the same in-memory instance. Django does not synchronize in-memory model instances, so multiple instances of a specific ProgressReport will diverge as they are written to from separate threads.

Fields

message (models.TextField) – short message for the progress update, typically shown to the user. (required)
code (models.TextField) – identifies the type of progress report
state (models.TextField) – The state of the progress update. Defaults to WAITING. This field uses a limited set of choices of field states. See STATES for possible states.
total – (models.IntegerField) The total count of items to be handled
done (models.IntegerField) – The count of items already processed. Defaults to 0.
suffix (models.TextField) –
Customizable suffix rendered with the progress report See the docs. for more info.

Relations

task – The task associated with this progress report. If left unset when save() is called it will be set to the current task_id.

exception DoesNotExist

exception MultipleObjectsReturned

increase_by(count)

Increase the done count and save the progress report.

This will increment and save the self.done attribute which is useful to put into a loop processing items.

increment()

Increment done count and save the progress report.

This will increment and save the self.done attribute which is useful to put into a loop processing items.

iter(iter)

Iterate and automatically call increment().

>>> progress_bar = ProgressReport(message='Publishing files', code='publish', total=23)
>>> progress_bar.save()
>>> for file in progress_bar.iter(files_iterator):
>>>     handle(file)

Parameters: iter (iterator) – The iterator to loop through while incrementing
Returns: generator of iter argument items

save(*args, **kwargs)

Auto-set the task_id if running inside a task

If the task_id is already set it will not be updated. If it is unset and this is running inside of a task it will be auto-set prior to saving.

args (list): positional arguments to be passed on to the real save kwargs (dict): keyword arguments to be passed on to the real save

class pulpcore.plugin.models.Publication(*args, **kwargs)

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.

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(...)
>>>             ...
>>>

exception DoesNotExist

exception MultipleObjectsReturned

classmethod create(repository_version, pass_through=False)

Create a publication.

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

Parameters

repository_version (pulpcore.app.models.RepositoryVersion) – The repository version to be published.
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.

Returns

A created Publication in an incomplete state.

Return type

pulpcore.app.models.Publication

Notes

Adds a Task.created_resource for the publication.

delete(**kwargs)

Delete the publication.

Parameters: **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.

property repository

Return the associated repository

Returns: The repository associated to this publication
Return type: pulpcore.app.models.Repository

class pulpcore.plugin.models.PublishedArtifact(*args, **kwargs)

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.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.PublishedMetadata(*args, **kwargs)

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.

exception DoesNotExist

exception MultipleObjectsReturned

classmethod create_from_file(file, publication, relative_path=None)

Creates PublishedMetadata along with Artifact, ContentArtifact, and PublishedArtifact.

Parameters

file (django.core.files.File) – an open File that contains metadata
publication (pulpcore.app.models.Publication) – The publication in which the PublishedMetadata is included.
relative_path (str) – relative path at which the Metadata is published at. If None, the name of the ‘file’ is used.

Returns

A saved instance of PublishedMetadata.

Return type

PublishedMetadata (pulpcore.app.models.PublishedMetadata)

class pulpcore.plugin.models.PulpTemporaryFile(*args, **kwargs)

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.

exception DoesNotExist

exception MultipleObjectsReturned

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

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 PulpTemporaryUploadedFile.

Parameters

file (PulpTemporaryUploadedFile or str) – The PulpTemporaryUploadedFile to create the PulpTemporaryFile from or a string with the full path to the file on disk.
expected_digests (dict) – Keyed on the algorithm name provided by hashlib and stores the value of the expected digest. e.g. {‘md5’: ‘912ec803b2ce49e4a541068d495ab570’}
expected_size (int) – The number of bytes the download is expected to have.

Raises

DigestValidationError – When any of the expected_digest values don’t match the digest of the data
SizeValidationError – When the expected_size value doesn’t match the size of the data
UnsupportedDigestValidationError – When any of the expected_digest algorithms aren’t in the ALLOWED_CONTENT_CHECKSUMS list

Returns

An in-memory, unsaved PulpTemporaryFile

storage_path(name)

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

Parameters: 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.

class pulpcore.plugin.models.Remote(*args, **kwargs)

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 :class: 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 :class: pulpcore.plugin.serializers.repository.RemoteSerializer.

Fields

name (models.TextField) – The remote name.
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 total download rate in requests per second.

exception DoesNotExist

exception MultipleObjectsReturned

get_downloader(remote_artifact=None, url=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

remote_artifact (RemoteArtifact) – The RemoteArtifact to download.
url (str) – The URL to download.
kwargs (dict) – This accepts the parameters of BaseDownloader.

Raises

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

Returns

A downloader that is configured with the remote settings.

Return type

subclass of BaseDownloader

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.

Parameters: relative_path (str) – The relative path of a RemoteArtifact
Returns: The Class of the content type that should be available at the relative path.
Return type: Class

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

relative_path (str) – The relative path of a RemoteArtifact
request (aiohttp.web.Request) – The request object for this relative path

Raises

ValueError – If relative_path starts with a ‘/’.

Returns

A URL for a RemoteArtifact available at the Remote.

Return type

str

invalidate_cache(): Invalidates the cache if remote is present.

property download_factory

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

The instantiated DownloaderFactory to be used by: get_downloader().

Return type

DownloadFactory

property download_throttler

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: The instantiated Throttler to be used by get_downloader()
Return type: Throttler

class pulpcore.plugin.models.RemoteArtifact(*args, **kwargs)

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.

exception DoesNotExist

exception MultipleObjectsReturned

validate_checksums(): Validate if RemoteArtifact has allowed checksum or no checksum at all.

class pulpcore.plugin.models.Repository(*args, **kwargs)

Collection of content.

Fields

name (models.TextField) – The repository name.
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

exception DoesNotExist

exception MultipleObjectsReturned

static artifacts_for_version(version)

Return the artifacts for a repository version.

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

Parameters: version (pulpcore.app.models.RepositoryVersion) – to get the artifacts for
Returns: The artifacts that are contained within this version.
Return type: django.db.models.QuerySet

cleanup_old_versions(): Cleanup old repository versions based on retain_repo_versions.

create_initial_version()

Create an initial repository version (version 0).

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

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: new_version (pulpcore.app.models.RepositoryVersion) – The incomplete RepositoryVersion to finalize.

Returns:

invalidate_cache(everything=False): Invalidates the cache if repository is present.

latest_version()

Get the latest RepositoryVersion on a repository

Parameters: repository (pulpcore.app.models.Repository) – to get the latest version of
Returns: The latest RepositoryVersion
Return type: pulpcore.app.models.RepositoryVersion

natural_key()

Get the model’s natural key.

Returns: The model’s natural key.
Return type: tuple

new_version(base_version=None)

Create a new RepositoryVersion for this Repository

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

Parameters

repository (pulpcore.app.models.Repository) – to create a new version of
base_version (pulpcore.app.models.RepositoryVersion) – an optional repository version whose content will be used as the set of content for the new version

Returns

The Created RepositoryVersion

Return type

pulpcore.app.models.RepositoryVersion

on_new_version(version)

Called when new repository versions are created.

Subclasses are expected to override this to do useful things.

Parameters: version – The new repository version.

save(*args, **kwargs)

Saves Repository model and creates an initial repository version.

Parameters

args (list) – list of positional arguments for Model.save()
kwargs (dict) – dictionary of keyword arguments to pass to Model.save()

class pulpcore.plugin.models.RepositoryContent(*args, **kwargs)

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.

exception DoesNotExist

exception MultipleObjectsReturned

class pulpcore.plugin.models.RepositoryVersion(*args, **kwargs)

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.

exception DoesNotExist

exception MultipleObjectsReturned

add_content(content)

Add a content unit to this version.

Parameters: content (django.db.models.QuerySet) – Set of Content to add
Raises: pulpcore.exception.ResourceImmutableError – if add_content is called on a complete RepositoryVersion

added(base_version=None)

Parameters: base_version (pulpcore.app.models.RepositoryVersion) – an optional repository version
Returns: The Content objects that were added by this version.
Return type: QuerySet

contains(content)

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

Returns: True if the repository version contains the content, False otherwise
Return type: bool

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

content_qs (django.db.models.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 iterate over all content present in the repository version). A plugin may want to use a specific subclass of Content or use e.g. filter() to select a subset of the repository version’s content.
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.
batch_size (int) – The maximum batch size.

Yields

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 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:
        ...

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.

get_content(content_qs=None)

Returns a set of content for a repository version

Parameters: content_qs (django.db.models.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).
Returns: The content that is contained within this version.
Return type: django.db.models.QuerySet

Examples

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

next()

Returns

The next complete RepositoryVersion for the same: repository.

Return type

pulpcore.app.models.RepositoryVersion

Raises

RepositoryVersion.DoesNotExist – if there is not a RepositoryVersion for the same repository and with a higher “number”.

previous()

Returns

The previous complete RepositoryVersion for the: same repository.

Return type

pulpcore.app.models.RepositoryVersion

Raises

RepositoryVersion.DoesNotExist – if there is not a RepositoryVersion for the same repository and with a lower “number”.

remove_content(content)

Remove content from the repository.

Parameters: content (django.db.models.QuerySet) – Set of Content to remove
Raises: pulpcore.exception.ResourceImmutableError – if remove_content is called on a complete RepositoryVersion

removed(base_version=None)

Parameters: base_version (pulpcore.app.models.RepositoryVersion) – an optional repository version
Returns: The Content objects that were removed by this version.
Return type: QuerySet

set_content(content)

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

Parameters: content (django.db.models.QuerySet) – Set of desired content
Raises: pulpcore.exception.ResourceImmutableError – if set_content is called on a complete RepositoryVersion

property artifacts

Returns a set of artifacts for a repository version.

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

property content

Returns a set of content for a repository version

Returns: The content that is contained within this version.
Return type: django.db.models.QuerySet

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):
>>>     ...
>>>

class pulpcore.plugin.models.SigningService(*args, **kwargs)

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).

exception DoesNotExist

exception MultipleObjectsReturned

save(*args, **kwargs): Save a signing service to the database (unless it fails to validate).

sign(filename)

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: filename (str) – A relative path to a file which is intended to be signed.
Raises: RuntimeError – If the return code of the script is not equal to 0.
Returns: A dictionary as validated by the validate() method.

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: RuntimeError – If the script failed to produce the desired outcome for the test data.

class pulpcore.plugin.models.Task(*args, **kwargs)

Represents a task

Fields

state (models.TextField) – The state of the task
name (models.TextField) – The name of the task
logging_cid (models.CharField) – The logging CID associated with the task
started_at (models.DateTimeField) – The time the task started executing
finished_at (models.DateTimeField) – The time the task finished executing
error (models.JSONField) – Fatal errors generated by the task
args (models.JSONField) – The JSON serialized arguments for the task
kwargs (models.JSONField) – The JSON serialized keyword arguments for the task
reserved_resources_record (django.contrib.postgres.fields.ArrayField) – The reserved resources required for the task.

Relations

parent (models.ForeignKey) – Task that spawned this task (if any)
worker (models.ForeignKey) – The worker that this task is in

exception DoesNotExist

exception MultipleObjectsReturned

static current()

Returns: The current task.
Return type: pulpcore.app.models.Task

set_completed()

Set this Task to the completed state, save it, and log output in warning cases.

This updates the finished_at and sets the state to COMPLETED.

set_failed(exc, tb)

Set this Task to the failed state and save it.

This updates the finished_at attribute, sets the state to FAILED, and sets the error attribute.

Parameters

exc (Exception) – The exception raised by the task.
tb (traceback) – Traceback instance for the current exception.

set_running()

Set this Task to the running state, save it, and log output in warning cases.

This updates the started_at and sets the state to RUNNING.

class pulpcore.plugin.models.TaskGroup(pulp_id, pulp_created, pulp_last_updated, description, all_tasks_dispatched)

exception DoesNotExist

exception MultipleObjectsReturned

static current()

Returns: The task group the current task is being executed and belongs to.
Return type: pulpcore.app.models.TaskGroup

finish()

Finalize the task group.

Set ‘all_tasks_dispatched’ to True so that API users can know that there are no tasks in the group yet to be created.

class pulpcore.plugin.models.Upload(*args, **kwargs)

A chunked upload. Stores chunks until used to create an artifact, etc.

Fields: size (models.BigIntegerField) – The size of the file in bytes.

exception DoesNotExist

exception MultipleObjectsReturned

append(chunk, offset, sha256=None)

Append a chunk to an upload.

Parameters

chunk (File) – Binary file to append to the upload file.
offset (int) – First byte position to write chunk to.

class pulpcore.plugin.models.UploadChunk(*args, **kwargs)

A chunk for an uploaded file.

Fields

file (fields.FileField) – A file where the uploaded chunk is stored.
upload (models.ForeignKey) – Upload this chunk belongs to.
offset (models.BigIntegerField) – Start of the chunk in bytes.
size (models.BigIntegerField) – Size of the chunk in bytes.

exception DoesNotExist

exception MultipleObjectsReturned

storage_path(name)

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

Parameters: 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.