Pulp

+1 to this task. We should also use these tools internally for #3234.

This might be a good fit for the Facade[1] design pattern. The goal is to provide the plugin writer a domain object that can be safely used like a RepositoryVersion but encapsulates the complexity of managing them. By doing so we avoid adding methods that manage other models on the RepositoryVersion model goes against django best practices. And, provides an intuitive and appropriate place for the context manger.

The plugin API could include something like this in a module named repository.py (see similar domain object in tasking.py).

from contextlib import suppress
from gettext import gettext

from pulpcore.app import models
from pulpcore.plugin.tasking import Task

class RepositoryVersion:

    @classmethod
    def latest(cls, repository):
        model = repository.versions.exclude(complete=False).latest()
        return RepositoryVersionFacade(model)

    @classmethod
    def create(cls, repository):
        with transaction.atomic():
            version = models.RepositoryVersion(
                repository=repository,
                number=repository.last_version + 1)
            repository.last_version = version.number
            repository.save()
            version.save()
            resource = models.CreatedResource(content_object=version)
            resource.save()
            return cls(version)

    def __init__(self, model):
        self._model = model

    @property
    def content(self):
        # moved from RepositoryVersion model.
        associations = models.RepositoryContent.objects.filter(
            repository=self._model.repository,
            version_added__number__lte=self.number).exclude(
            version_removed__number__lte=self.number)
        content_model = self._repository.content.model
        return content_model.objects.filter(version_memberships__in=associations)

    def add_content(self, content):
        # moved from RepositoryVersion model.
        assert not self._model.complete, _('Complete repository version is immutable.')
        with suppress(IntegrityError):
            association = RepositoryContent(
                repository=self._model.repository,
                content=content,
                version_added=self._model)
            association.save()

    def remove_content(self, content):
        # moved from RepositoryVersion model.
        assert not self._model.complete, _('Complete repository version is immutable.')
        q_set = models.RepositoryContent.objects.filter(
            repository=self._model.repository,
            content=content,
            version_removed=None)
        q_set.update(version_removed=self._model)

    def complete(self):
        self._model.complete = True
        self._model.save()

    def delete(self):
        with transaction.atomic():
            models.CreatedResource.objcets.delete(content_object=self._model)
            self._model.delete()

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        if exc_value:
            self.delete()

# List content on latest version.
latest_version = RepositoryVersion.latest(repository)
for content in latest_version.content():
    ...

# Create new version.
with RepositoryVersion.create(repository) as created_version:
    changeset = ChangeSet(created_version, ...)

[1] https://en.wikipedia.org/wiki/Facade_pattern

I'd like this to also include CreatedResource.

Since RepositoryVersions should always be created in a Task, it will always need a CreatedResource. Also, if things go badly, the CreatedResource needs to be cleaned up at the same time as the RepositoryVersion.