Content Models

Content Models#

This is where we expose a small handful of models and model mixins that we want callers to extend or make foreign keys to. Callers importing this module should never instantiate any of the models themselves–there are API functions in authoring.py to create and modify data models in a way that keeps those models consistent.

class openedx_content.models_api.Collection(*args, **kwargs)#

Bases: Model

Represents a collection of library components

Parameters:

id (AutoField) – Primary key: Id
collection_code (MultiCollationCharField) –
Collection code

Every collection is uniquely and permanently identified within its learning package by a ‘code’ that is set during creation. Both will appear in the collection’s opaque key: e.g. lib-collection:{org_code}:{library_code}:{collection_code} is the opaque key for a library collection.
title (MultiCollationCharField) – Title. The title of the collection.
description (MultiCollationTextField) – Description. Provides extra information for the user about this collection.
enabled (BooleanField) – Enabled. Disabled collections are “soft deleted”, and should be re-enabled before use, or be deleted.
created (DateTimeField) – Created
modified (DateTimeField) – Modified

Relationship fields:

Parameters:

learning_package (ForeignKey to LearningPackage) –
Learning package (related name: collection)

Each collection belongs to a LearningPackage.
created_by (ForeignKey to User) – Created by (related name: collection)
entities (ManyToManyField to PublishableEntity) – Entities (related name: collections)

Reverse relationships:

Parameters:: collectionpublishableentity (Reverse ForeignKey from CollectionPublishableEntity) – All collection publishable entitys of this collection (related name of collection)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

collection_code#

MultiCollationCharField

Collection code

Every collection is uniquely and permanently identified within its learning package by a ‘code’ that is set during creation. Both will appear in the collection’s opaque key: e.g. lib-collection:{org_code}:{library_code}:{collection_code} is the opaque key for a library collection.

Type:: Type

learning_package#

ForeignKey to LearningPackage

Learning package (related name: collection)

Each collection belongs to a LearningPackage.

Type:: Type

class openedx_content.models_api.CollectionPublishableEntity(*args, **kwargs)#

Bases: Model

Collection → PublishableEntity association.

Parameters:

id (BigAutoField) – Primary key: ID
created (DateTimeField) – Created

Relationship fields:

Parameters:

collection (ForeignKey to Collection) – Collection (related name: collectionpublishableentity)
entity (ForeignKey to PublishableEntity) – Entity (related name: collectionpublishableentity)
created_by (ForeignKey to User) – Created by (related name: collectionpublishableentity)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

class openedx_content.models_api.Component(*args, **kwargs)#

Bases: PublishableEntityMixin

This represents any Component that has ever existed in a LearningPackage.

What is a Component#

A Component is an entity like a Problem or Video. It has enough information to identify itself and determine what the handler should be (e.g. XBlock Problem), but little beyond that.

A Component will have many ComponentVersion objects over time, and most metadata is associated with the ComponentVersion model and the Media that ComponentVersion objects are associated with.

A Component belongs to exactly one LearningPackage.

A Component is 1:1 with PublishableEntity and has matching primary key values. More specifically, Component.pk maps to Component.publishable_entity_id, and any place where the Publishing API module expects to get a PublishableEntity.id, you can use a Component.pk instead.

Identifiers#

Components have a publishable_entity OneToOneField to the publishing app’s PublishableEntity field, and it uses this as its primary key. Please see PublishableEntity’s docstring for how you should use its uuid and key fields.

State Consistency#

The key field on Component’s publishable_entity is derived from the component_type and component_code fields in this model. We don’t support changing the keys yet, but if we do, those values need to be kept in sync.

How build on this model#

Make a foreign key to the Component model when you need a stable reference that will exist for as long as the LearningPackage itself exists.

param component_code:

Component code

component_code is an identifier that is local to the learning_package and component_type. The publishable.entity_ref is derived from component_type and component_code.

type component_code:

~openedx_django_lib.fields.MultiCollationCharField

Relationship fields:

param publishable_entity:

Primary key: Publishable entity (related name: component)

type publishable_entity:

OneToOneField to PublishableEntity

param learning_package:

Learning package (related name: component)

This foreign key is technically redundant because we’re already locked to a single LearningPackage through our publishable_entity relation. However, having this foreign key directly allows us to make indexes that efficiently query by other Component fields within a given LearningPackage, which is going to be a common use case (and we can’t make a compound index using columns from different tables).

type learning_package:

ForeignKey to LearningPackage

param component_type:

Component type (related name: component)

What kind of Component are we? This will usually represent a specific XBlock block_type, but we want it to be more flexible in the long term.

type component_type:

ForeignKey to ComponentType

Reverse relationships:

param versions:: All versions of this Component (related name of component)
type versions:: Reverse ForeignKey from ComponentVersion

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

component_code#

MultiCollationCharField

Component code

component_code is an identifier that is local to the learning_package and component_type. The publishable.entity_ref is derived from component_type and component_code.

Type:: Type

component_type#

ForeignKey to ComponentType

Component type (related name: component)

What kind of Component are we? This will usually represent a specific XBlock block_type, but we want it to be more flexible in the long term.

Type:: Type

learning_package#

ForeignKey to LearningPackage

Learning package (related name: component)

Type:: Type

property pk#: Mark the .pk attribute as deprecated

class openedx_content.models_api.ComponentType(*args, **kwargs)#

Bases: Model

Normalized representation of a type of Component.

The only namespace being used initially will be xblock.v1, but we will probably add a few others over time, such as a component type to represent packages of files for things like Files and Uploads or python_lib.zip files.

Make a foreign key against this table if you have to set policy based on the type of Components–e.g. marking certain types of XBlocks as approved vs. experimental for use in libraries.

Parameters:

id (AutoField) –
Primary key: Id

This is intentionally a 4-byte AutoField instead of an 8-byte BigAutoField. We don’t need the app default of 8-bytes for this primary key, but there is just a tiny chance that we’ll use ComponentType in a novel, user-customizable way that will require more than 32K entries that a SmallAutoField would allow us.
namespace (MultiCollationCharField) –
Namespace

namespace and name work together to help figure out what Component needs to handle this data. A namespace is required. The namespace for XBlocks is xblock.v1 (to match XBlock’s entrypoint naming scheme).
name (MultiCollationCharField) –
Name

name is a way to help sub-divide namespace if that’s convenient. This field cannot be null, but it can be blank if it’s not necessary. For an XBlock, this corresponds to tag, e.g. “video”. It’s also the block_type in the UsageKey.

Reverse relationships:

Parameters:

component (Reverse ForeignKey from Component) –

All Components of this component type (related name of component_type)

This is technically redundant, since we can get this through publishable_entity_version.publishable.component, but this is more convenient.

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

id#

AutoField

Primary key: Id

This is intentionally a 4-byte AutoField instead of an 8-byte BigAutoField. We don’t need the app default of 8-bytes for this primary key, but there is just a tiny chance that we’ll use ComponentType in a novel, user-customizable way that will require more than 32K entries that a SmallAutoField would allow us.

Type:: Type

name#

MultiCollationCharField

Name

name is a way to help sub-divide namespace if that’s convenient. This field cannot be null, but it can be blank if it’s not necessary. For an XBlock, this corresponds to tag, e.g. “video”. It’s also the block_type in the UsageKey.

Type:: Type

namespace#

MultiCollationCharField

Namespace

namespace and name work together to help figure out what Component needs to handle this data. A namespace is required. The namespace for XBlocks is xblock.v1 (to match XBlock’s entrypoint naming scheme).

Type:: Type

class openedx_content.models_api.ComponentVersion(*args, **kwargs)#

Bases: PublishableEntityVersionMixin

A particular version of a Component.

This holds the media using a M:M relationship with Media via ComponentVersionMedia.

Relationship fields:

Parameters:

publishable_entity_version (OneToOneField to PublishableEntityVersion) – Primary key: Publishable entity version (related name: componentversion)
component (ForeignKey to Component) –
Component (related name: versions)

This is technically redundant, since we can get this through publishable_entity_version.publishable.component, but this is more convenient.
media (ManyToManyField to Media) –
Media (related name: component_versions)

The media relation holds the actual interesting data associated with this ComponentVersion.

Reverse relationships:

Parameters:: componentversionmedia (Reverse ForeignKey from ComponentVersionMedia) – All component version medias of this Component Version (related name of component_version)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

component#

ForeignKey to Component

Component (related name: versions)

This is technically redundant, since we can get this through publishable_entity_version.publishable.component, but this is more convenient.

Type:: Type

media: models.ManyToManyField[Media, ComponentVersionMedia]#

ManyToManyField to Media

Media (related name: component_versions)

The media relation holds the actual interesting data associated with this ComponentVersion.

Type:: Type

class openedx_content.models_api.ComponentVersionMedia(*args, **kwargs)#

Bases: Model

Determines the Media for a given ComponentVersion.

An ComponentVersion may be associated with multiple pieces of binary data. For instance, a Video ComponentVersion might be associated with multiple transcripts in different languages.

When Media is associated with a ComponentVersion, it has a path that is unique within the context of that ComponentVersion. This is used as a local file-path-like identifier, e.g. static/image.png.

Media is immutable and sharable across multiple ComponentVersion objects.

Parameters:

id (BigAutoField) –
Primary key: ID

This is intentionally a 4-byte AutoField instead of an 8-byte BigAutoField. We don’t need the app default of 8-bytes for this primary key, but there is just a tiny chance that we’ll use ComponentType in a novel, user-customizable way that will require more than 32K entries that a SmallAutoField would allow us.
path (MultiCollationCharField) –
Path

path is a local file-path-like identifier for the media within a ComponentVersion.

Relationship fields:

Parameters:

component_version (ForeignKey to ComponentVersion) – Component version (related name: componentversionmedia)
media (ForeignKey to Media) –
Media (related name: componentversionmedia)

The media relation holds the actual interesting data associated with this ComponentVersion.

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

path#

MultiCollationCharField

Path

path is a local file-path-like identifier for the media within a ComponentVersion.

Type:: Type

class openedx_content.models_api.Container(*args, **kwargs)#

Bases: PublishableEntityMixin

A Container is a type of PublishableEntity that holds other PublishableEntity objects. For example, a “Unit” Container might hold several Component objects.

For now, all containers have a static “entity list” that defines which containers/components/enities they hold. As we complete the Containers API, we will also add support for dynamic containers which may contain different entities for different learners or at different times.

Parameters:

container_code (MultiCollationCharField) –

Container code

container_code is an identifier that is local to the learning_package. Unlike component_code, it is unique across all container types within the same LearningPackage.

Relationship fields:

Parameters:

publishable_entity (OneToOneField to PublishableEntity) – Primary key: Publishable entity (related name: container)
learning_package (ForeignKey to LearningPackage) –
Learning package (related name: container)

This foreign key is technically redundant because we’re already locked to a single LearningPackage through our publishable_entity relation. However, having this foreign key directly allows us to make indexes that efficiently query by other Container fields within a given LearningPackage.
container_type (ForeignKey to ContainerType) –
Container type (related name: container)

The type of the container. Cannot be changed once the container is created.

Reverse relationships:

Parameters:

versions (Reverse ForeignKey from ContainerVersion) – All versions of this container (related name of container)
unit (Reverse OneToOneField from Unit) – The unit of this container (related name of container)
subsection (Reverse OneToOneField from Subsection) – The subsection of this container (related name of container)
section (Reverse OneToOneField from Section) – The section of this container (related name of container)
testcontainer (Reverse OneToOneField from TestContainer) – The test container of this container (related name of container)
containercontainer (Reverse OneToOneField from ContainerContainer) – The container container of this container (related name of base_container)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

static all_subclasses() → list[type[Container]]#: Get a list of all installed container types

container_code#

MultiCollationCharField

Container code

container_code is an identifier that is local to the learning_package. Unlike component_code, it is unique across all container types within the same LearningPackage.

Type:: Type

container_type#

ForeignKey to ContainerType

Container type (related name: container)

The type of the container. Cannot be changed once the container is created.

Type:: Type

final classmethod get_container_type() → ContainerType#: Get the ContainerType for this type of container, auto-creating it if need be.

learning_package#

ForeignKey to LearningPackage

Learning package (related name: container)

Type:: Type

olx_tag_name: str = ''#: The OLX <tag_name> for XML serialization. Subclasses _may_ override this. Only used in openedx-platform at the moment. We’ll likely have to replace this with something more sophisticated.

property pk#: Mark the .pk attribute as deprecated

static register_subclass(container_subclass: type[Container])#: Register a Container subclass

final static reset_cache() → None#: Helper for test cases that truncate the database between tests. Call this to delete the cache used in get_container_type(), which will be invalid after the ContainerType table is truncated.

static subclass_for_type_code(type_code: str) → type[Container]#: Get the subclass for the specified container type_code.

classmethod validate_entity(entity: PublishableEntity) → None#

Check if the given entity is allowed as a child of this Container type

Subclasses should raise ValidationError if “entity” is invalid.

class openedx_content.models_api.ContainerVersion(*args, **kwargs)#

Bases: PublishableEntityVersionMixin

A version of a Container.

By convention, we would only want to create new versions when the Container itself changes, and not when the Container’s child elements change. For example:

Something was added to the Container.
We re-ordered the rows in the container.
Something was removed to the container.
The Container’s metadata changed, e.g. the title.
We pin to different versions of the Container.

The last looks a bit odd, but it’s because how we’ve defined the Unit has changed if we decide to explicitly pin a set of versions for the children, and then later change our minds and move to a different set. It also just makes things easier to reason about if we say that entity_list never changes for a given ContainerVersion.

Relationship fields:

Parameters:

publishable_entity_version (OneToOneField to PublishableEntityVersion) – Primary key: Publishable entity version (related name: containerversion)
container (ForeignKey to Container) – Container (related name: versions)
entity_list (ForeignKey to EntityList) –
Entity list (related name: container_versions)

The list of entities (frozen and/or unfrozen) in this container.

Reverse relationships:

Parameters:

unitversion (Reverse OneToOneField from UnitVersion) – The unit version of this container version (related name of container_version)
subsectionversion (Reverse OneToOneField from SubsectionVersion) – The subsection version of this container version (related name of container_version)
sectionversion (Reverse OneToOneField from SectionVersion) – The section version of this container version (related name of container_version)
testcontainerversion (Reverse OneToOneField from TestContainerVersion) – The test container version of this container version (related name of container_version)
containercontainerversion (Reverse OneToOneField from ContainerContainerVersion) – The container container version of this container version (related name of container_version)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

clean()#: Validate this model before saving. Not called normally, but will be called if anything is edited via a ModelForm like the Django admin.

entity_list#

ForeignKey to EntityList

Entity list (related name: container_versions)

The list of entities (frozen and/or unfrozen) in this container.

Type:: Type

class openedx_content.models_api.Draft(*args, **kwargs)#

Bases: Model

Find the active draft version of an entity (usually most recently created).

This model mostly only exists to allow us to join against a bunch of PublishableEntity objects at once and get all their latest drafts. You might use this together with Published in order to see which Drafts haven’t been published yet.

A Draft entry should be created whenever a new PublishableEntityVersion is created. This means there are three possible states:

No Draft entry for a PublishableEntity: This means a PublishableEntity was created, but no PublishableEntityVersion was ever made for it, so there was never a Draft version.
A Draft entry exists and points to a PublishableEntityVersion: This is the most common state.
A Draft entry exists and points to a null version: This means a version used to be the draft, but it’s been functionally “deleted”. The versions still exist in our history, but we’re done using it.

It would have saved a little space to add this data to the Published model (and possibly call the combined model something else). Split Modulestore did this with its active_versions table. I keep it separate here to get a better separation of lifecycle events: i.e. this table only changes when drafts are updated, not when publishing happens. The Published model only changes when something is published.

Relationship fields:

Parameters:

entity (OneToOneField to PublishableEntity) –
Primary key: Entity (related name: draft)

If we’re removing a PublishableEntity entirely, also remove the Draft entry for it. This isn’t a normal operation, but can happen if you’re deleting an entire LearningPackage.
version (OneToOneField to PublishableEntityVersion) – Version (related name: draft)
draft_log_record (ForeignKey to DraftChangeLogRecord) –
Draft log record (related name: draft)

Note: this is actually a 1:1 relation in practice, but I’m keeping the definition more consistent with the Published model, which has an fkey to PublishLogRecord. Unlike PublishLogRecord, this fkey is a late addition to this data model, so we have to allow null values for the initial migration. But making this nullable also has another advantage, in that it allows us to set the draft_log_record to the most recent change while inside a bulk_draft_changes_for operation, and then delete that log record if it is undone in the same bulk operation.

exception DoesNotExist#: Bases: ObjectDoesNotExist

class DraftQuerySet(model=None, query=None, using=None, hints=None)#

Bases: QuerySet

Custom QuerySet/Manager so we can chain common queries.

with_unpublished_changes()#

Draft objects with versions that are different from what is Published.

This will not return Draft objects that have unpublished changes in their dependencies. Example: A Unit is published with a Component as one of its child. Then someone modifies the draft of the Component. If both the Unit and the Component Draft objects were part of the queryset, this method would return only the changed Component, and not the Unit. (We can add this as an optional flag later if we want.)

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

draft_log_record#

ForeignKey to DraftChangeLogRecord

Draft log record (related name: draft)

Note: this is actually a 1:1 relation in practice, but I’m keeping the definition more consistent with the Published model, which has an fkey to PublishLogRecord. Unlike PublishLogRecord, this fkey is a late addition to this data model, so we have to allow null values for the initial migration. But making this nullable also has another advantage, in that it allows us to set the draft_log_record to the most recent change while inside a bulk_draft_changes_for operation, and then delete that log record if it is undone in the same bulk operation.

Type:: Type

entity#

OneToOneField to PublishableEntity

Primary key: Entity (related name: draft)

If we’re removing a PublishableEntity entirely, also remove the Draft entry for it. This isn’t a normal operation, but can happen if you’re deleting an entire LearningPackage.

Type:: Type

class openedx_content.models_api.DraftChangeLog(*args, **kwargs)#

Bases: Model

There is one row in this table for every time Draft objects are created/modified.

There are some operations that affect many Draft objects at once, such as discarding changes (i.e. reset to the published versions) or doing an import. These would be represented by one DraftChangeLog with many DraftChangeLogRecord objects in it—one DraftChangeLogRecord for every PublishableEntity that was modified.

Even if we’re only directly changing the draft version of one PublishableEntity, we will get multiple DraftChangeLogRecord objects if changing that entity causes side-effects. See the docstrings for DraftChangeLogRecord and DraftSideEffect for more details.

Parameters:

id (BigAutoField) – Primary key: ID
uuid (UUIDField) – UUID
changed_at (DateTimeField) – Changed at

Relationship fields:

Parameters:

learning_package (ForeignKey to LearningPackage) – Learning package (related name: draftchangelog)
changed_by (ForeignKey to User) – Changed by (related name: draftchangelog)

Reverse relationships:

Parameters:: records (Reverse ForeignKey from DraftChangeLogRecord) – All records of this Draft Change Log (related name of draft_change_log)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

class openedx_content.models_api.DraftChangeLogRecord(*args, **kwargs)#

Bases: Model

A single change in the PublishableEntity that Draft points to.

Within a single DraftChangeLog, there can be only one DraftChangeLogRecord per PublishableEntity. If a PublishableEntity goes from v1 → v2 and then v2 → v3 within the same DraftChangeLog, the expectation is that these will be collapsed into one DraftChangeLogRecord that goes from v1 → v3. A single PublishableEntity may have many DraftChangeLogRecord objects that describe its full draft edit history, but each DraftChangeLogRecord will be a part of a different DraftChangeLog.

New PublishableEntityVersion objects are created with a monotonically increasing version_num for their PublishableEntity. However, knowing that is not enough to accurately reconstruct how the Draft changes over time because the Draft does not always point to the most recently created PublishableEntityVersion. We also have the concept of side-effects, where we consider a PublishableEntity to have changed in some way, even if no new version is explicitly created.

The following scenarios may occur:

Scenario 1: old_version is None, new_version.version_num = 1

This is the common case when we’re creating the first version for editing.

Scenario 2: old_version.version_num + 1 == new_version.version_num

This is the common case when we’ve made an edit to something, which creates the next version of an entity, which we then point the Draft at.

Scenario 3: old_version.version_num >=1, new_version is None

This is a soft-deletion. We never actually delete a row from the PublishableEntity model, but set its current Draft version to be None instead.

Scenario 4: old_version.version_num > new_version.version_num

This can happen if we “discard changes”, meaning that we call reset_drafts_to_published(). The versions we created before resetting don’t get deleted, but the Draft model’s pointer to the current version has been reset to match the Published model.

Scenario 5: old_version.version_num + 1 < new_version.version_num

Sometimes we’ll have a gap between the two version numbers that is > 1. This can happen if we make edits (new versions) after we called reset_drafts_to_published. PublishableEntityVersion objects are created with a monotonically incrementing version_num which will continue to go up with the next edit, regardless of whether Draft is pointing to the most recently created version or not. In terms of (old_version, new_version) changes, it could look like this:

(None, v1): Initial creation
# Publish happens here, so v1 of this PublishableEntity is published.
(v1, v2): Normal edit in draft
(v2, v3): Normal edit in draft
(v3, v1): Reset to published happened here.
(v1, v4): Normal edit in draft

This could also technically happen if we change the same entity more than once in the the same bulk_draft_changes_for() context, thereby putting them into the same DraftChangeLog, which forces us to squash the changes together into one DraftChangeLogRecord.

Scenario 6: old_version is None, new_version > 1

This edge case can happen if we soft-deleted a published entity, and then called reset_drafts_to_published before we published that soft-deletion. It would effectively undo our soft-delete because the published version was not yet marked as deleted.

Scenario 7: old_version == new_version

This means that the data associated with the Draft version of an entity has changed purely as a side-effect of some other entity changing.

The main example we have of this are containers. Imagine that we have a Unit that is at v1, and has unpinned references to various Components that are its children. The Unit’s version does not get incremented when the Components are edited, because the Unit container is defined to always get the most recent version of those Components. We would only make a new version of the Unit if we changed the metadata of the Unit itself (e.g. the title), or if we added, removed, or reordered the children.

Yet updating a Component intuitively changes what we think of as the content of the Unit. Users who are working on Units also expect that a change to a Component will be reflected when looking at a Unit’s “last updated” info. The old_version == new_version convention lets us represent that in a useful way because that Unit is a part of the change set represented by a DraftChangeLog, even if its own versioned data hasn’t changed.

Parameters:

id (BigAutoField) – Primary key: ID
dependencies_hash_digest (CharField) –
Dependencies hash digest

The dependencies_hash_digest is used when the version alone isn’t enough to let us know the full draft state of an entity. This happens any time a Draft version has dependencies (see the PublishableEntityVersionDependency model), because changes in those dependencies will cause changes to the state of the Draft. The main example of this is containers, where changing an unpinned child affects the state of the parent container, even if that container’s definition (and thus version) does not change.

If a Draft has no dependencies, then its entire state is captured by its version, and the dependencies_hash_digest is blank. (Blank is slightly more convenient for database comparisons than NULL.)

Note: There is an equivalent of this field in the Published model and the the values may drift away from each other.

Relationship fields:

Parameters:

draft_change_log (ForeignKey to DraftChangeLog) – Draft change log (related name: records)
entity (ForeignKey to PublishableEntity) –
Entity (related name: draftchangelogrecord)

If we’re removing a PublishableEntity entirely, also remove the Draft entry for it. This isn’t a normal operation, but can happen if you’re deleting an entire LearningPackage.
old_version (ForeignKey to PublishableEntityVersion) – Old version (related name: +)
new_version (ForeignKey to PublishableEntityVersion) – New version (related name: draftchangelogrecord)

Reverse relationships:

Parameters:

draft (Reverse ForeignKey from Draft) – All drafts of this Draft Change Log Record (related name of draft_log_record)
causes (Reverse ForeignKey from DraftSideEffect) – All causes of this Draft Change Log Record (related name of cause)
affected_by (Reverse ForeignKey from DraftSideEffect) – All affected by of this Draft Change Log Record (related name of effect)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

dependencies_hash_digest#

CharField

Dependencies hash digest

The dependencies_hash_digest is used when the version alone isn’t enough to let us know the full draft state of an entity. This happens any time a Draft version has dependencies (see the PublishableEntityVersionDependency model), because changes in those dependencies will cause changes to the state of the Draft. The main example of this is containers, where changing an unpinned child affects the state of the parent container, even if that container’s definition (and thus version) does not change.

If a Draft has no dependencies, then its entire state is captured by its version, and the dependencies_hash_digest is blank. (Blank is slightly more convenient for database comparisons than NULL.)

Note: There is an equivalent of this field in the Published model and the the values may drift away from each other.

Type:: Type

class openedx_content.models_api.DraftSideEffect(*args, **kwargs)#

Bases: Model

Model to track when a change in one Draft affects other Draft objects.

Our first use case for this is that changes involving child components are thought to affect parent Units, even if the parent’s version doesn’t change.

Side-effects are recorded in a collapsed form that only captures one level. So if Components C1 and C2 are both changed and they are part of Unit U1, which is in turn a part of Subsection SS1, then the DraftSideEffect entries are:

(C1, U1)
(C2, U1)
(U1, SS1)

We do not keep entries for (C1, SS1) or (C2, SS1). This is to make the model simpler, so we don’t have to differentiate between direct side-effects and transitive side-effects in the model.

We will record side-effects on a parent container whenever a child changes, even if the parent container is also changing in the same DraftChangeLog. The child change is still affecting the parent container, whether the container happens to be changing for other reasons as well. Whether a parent-child relationship exists or not depends on the draft state of the container at the end of a bulk_draft_changes_for context. To give concrete examples:

Setup: A Unit version U1.v1 has defined C1 to be a child. The current draft version of C1 is C1.v1.

Scenario 1: In the a bulk_draft_changes_for context, we edit C1 so that the draft version of C1 is now C1.v2.

Result:

a DraftChangeLogRecord is created for C1.v1 → C1.v2
a DraftChangeLogRecord is created for U1.v1 → U1.v1
a DraftSideEffect is created with cause (C1.v1 → C1.v2) and effect (U1.v1 → U1.v1). The Unit draft version has not been incremented because the metadata a Unit defines for itself hasn’t been altered, but the Unit has changed in some way because of the side effect of its child being edited.

Scenario 2: In a bulk_draft_changes_for context, we edit C1 so that the draft version of C1 is now C1.v2. In the same context, we edit U1’s metadata so that the draft version of U1 is now U1.v2. U1.v2 still lists C1 as a child entity.

Result:

a DraftChangeLogRecord is created for C1.v1 → C1.v2
a DraftChangeLogRecord is created for U1.v1 → U1.v2
a DraftSideEffect is created with cause (C1.v1 → C1.v2) and effect (U1.v1 → U1.v2)

Scenario 3: In a bulk_draft_changes_for context, we edit C1 so that the draft version of C1 is now C1.v2. In the same context, we edit U1’s list of children so that C1 is no longer a child of U1.v2.

Result:

a DraftChangeLogRecord is created for C1.v1 → C1.v2
a DraftChangeLogRecord is created for U1.v1 → U1.v2
no SideEffect is created, since changing C1 does not have an impact on the current draft of U1 (U1.v2). A DraftChangeLog is considered a single atomic operation, so there was never a point at which C1.v1 → C1.v2 affected the draft state of U1.

Parameters:: id (BigAutoField) – Primary key: ID

Relationship fields:

Parameters:

cause (ForeignKey to DraftChangeLogRecord) – Cause (related name: causes)
effect (ForeignKey to DraftChangeLogRecord) – Effect (related name: affected_by)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

class openedx_content.models_api.EntityList(*args, **kwargs)#

Bases: Model

EntityList is a common structure to hold parent-child relations.

EntityList objects are not PublishableEntity objects in and of themselves. That’s because sometimes we’ll want the same kind of data structure for things that we dynamically generate for individual students (e.g. Variants). EntityList objects are anonymous in a sense–they’re pointed to by ContainerVersion objects and other models, rather than being looked up by their own identifiers.

Parameters:: id (BigAutoField) – Primary key: ID

Reverse relationships:

Parameters:

entitylistrow (Reverse ForeignKey from EntityListRow) – All entity list rows of this entity list (related name of entity_list)
container_versions (Reverse ForeignKey from ContainerVersion) – All container versions of this entity list (related name of entity_list)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

property rows#

Convenience method to iterate rows.

I’d normally make this the reverse lookup name for the EntityListRow → EntityList foreign key relation, but we already have references to entitylistrow_set in various places, and I thought this would be better than breaking compatibility.

class openedx_content.models_api.EntityListRow(*args, **kwargs)#

Bases: Model

Each EntityListRow points to a PublishableEntity, optionally at a specific version.

There is a row in this table for each member of an EntityList. The order_num field is used to determine the order of the members in the list.

Parameters:

id (BigAutoField) – Primary key: ID
order_num (PositiveIntegerField) –
Order num

This ordering should be treated as immutable–if the ordering needs to change, we create a new EntityList and copy things over.

Relationship fields:

Parameters:

entity_list (ForeignKey to EntityList) –
Entity list (related name: entitylistrow)

The list of entities (frozen and/or unfrozen) in this container.
entity (ForeignKey to PublishableEntity) –
Entity (related name: entitylistrow)

Simple case would use this field with our convention that null versions means “get the latest draft or published as appropriate”. These entities could be Selectors, in which case we’d need to do more work to find the right variant.
entity_version (ForeignKey to PublishableEntityVersion) –
Entity version (related name: +)

The version references point to the specific PublishableEntityVersion that this EntityList has for this PublishableEntity for both the draft and published states. However, we don’t want to have to create new EntityList every time that a member is updated, because that would waste a lot of space and make it difficult to figure out when the metadata of something like a Unit actually changed, vs. when its child members were being updated. Doing so could also potentially lead to race conditions when updating multiple layers of containers.

So our approach to this is to use a value of None (null) to represent an unpinned reference to a PublishableEntity. It’s shorthand for “just use the latest draft or published version of this, as appropriate”.

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

entity#

ForeignKey to PublishableEntity

Entity (related name: entitylistrow)

Simple case would use this field with our convention that null versions means “get the latest draft or published as appropriate”. These entities could be Selectors, in which case we’d need to do more work to find the right variant.

Type:: Type

entity_version#

ForeignKey to PublishableEntityVersion

Entity version (related name: +)

The version references point to the specific PublishableEntityVersion that this EntityList has for this PublishableEntity for both the draft and published states. However, we don’t want to have to create new EntityList every time that a member is updated, because that would waste a lot of space and make it difficult to figure out when the metadata of something like a Unit actually changed, vs. when its child members were being updated. Doing so could also potentially lead to race conditions when updating multiple layers of containers.

So our approach to this is to use a value of None (null) to represent an unpinned reference to a PublishableEntity. It’s shorthand for “just use the latest draft or published version of this, as appropriate”.

Type:: Type

order_num#

PositiveIntegerField

Order num

This ordering should be treated as immutable–if the ordering needs to change, we create a new EntityList and copy things over.

Type:: Type

class openedx_content.models_api.LearningPackage(*args, **kwargs)#

Bases: Model

Top level container for a grouping of authored content.

Each PublishableEntity belongs to exactly one LearningPackage.

Parameters:

id (IDField) – Primary key: Id
uuid (UUIDField) – UUID
package_ref (MultiCollationCharField) –
Package ref

An opaque reference string for the LearningPackage.
title (MultiCollationCharField) – Title
description (MultiCollationTextField) –
Description

TODO: We should probably defer this field, since many things pull back LearningPackage as select_related. Usually those relations only care about the UUID and package_ref, so maybe it makes sense to separate the model at some point.
created (DateTimeField) – Created
updated (DateTimeField) – Updated

Reverse relationships:

Parameters:

publishable_entities (Reverse ForeignKey from PublishableEntity) – All publishable entities of this Learning Package (related name of learning_package)
draftchangelog (Reverse ForeignKey from DraftChangeLog) – All Draft Change Logs of this Learning Package (related name of learning_package)
publishlog (Reverse ForeignKey from PublishLog) – All Publish Logs of this Learning Package (related name of learning_package)
collection (Reverse ForeignKey from Collection) – All Collections of this Learning Package (related name of learning_package)
media (Reverse ForeignKey from Media) – All Media of this Learning Package (related name of learning_package)
component (Reverse ForeignKey from Component) – All Components of this Learning Package (related name of learning_package)
container (Reverse ForeignKey from Container) – All containers of this Learning Package (related name of learning_package)

exception DoesNotExist#: Bases: ObjectDoesNotExist

class IDField(*args, **kwargs)#

Bases: TypedAutoField

Explictly declare a 4-byte ID instead of using the app-default 8-byte ID. We do not expect to have more than 2 billion LearningPackages on a given site. Furthermore, many, many things have foreign keys to this model and uniqueness indexes on those foreign keys + their own fields, so the 4 bytes saved will add up over time.

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

description#

MultiCollationTextField

Description

TODO: We should probably defer this field, since many things pull back LearningPackage as select_related. Usually those relations only care about the UUID and package_ref, so maybe it makes sense to separate the model at some point.

Type:: Type

package_ref#

MultiCollationCharField

Package ref

An opaque reference string for the LearningPackage.

Type:: Type

class openedx_content.models_api.Media(*args, **kwargs)#

Bases: Model

This is the most primitive piece of content.

This model serves to lookup, de-duplicate, and store text and files. A piece of Media is identified purely by its data, the media type, and the LearningPackage it is associated with. It has no version or file name metadata associated with it. It exists to be a dumb blob of data that higher level models like ComponentVersion objects can assemble together.

In-model Text vs. File#

That being said, the Media model does have some complexity to accomodate different access patterns that we have in our app. In particular, it can store data in two ways: the text field and a file (has_file=True) A Media object must use at least one of these methods, but can use both if it’s appropriate.

Use the text field when:

the content is a relatively small (< 50K, usually much less) piece of text
you want to do be able to query across many rows at once
low, predictable latency is important

Use file storage when:

the content is large, or not text-based
you want to be able to serve the file content directly to the browser

The high level tradeoff is that text will give you faster access, and file storage will give you a much more affordable and scalable backend. The backend used for files will also eventually allow direct browser download access, whereas the text field will not. But again, you can use both at the same time if needed.

Association with a LearningPackage#

Media is associated with a specific LearningPackage. Doing so allows us to more easily query for how much storage space a specific LearningPackage is using, and to clean up unused data.

When we use Media across LearningPackage objects, we need to copy them. That way, even if the originating LearningPackage is deleted, it won’t break other LearningPackage objects that are making use if it.

Media Types, and file duplication#

Media is almost 1:1 with the files that it pushes to a storage backend, but not quite. The file locations are generated purely as a product of the LearningPackage UUID and the Media’s hash_digest, but Media also takes into account the media_type.

For example, say we had a Media with the following data:

["hello", "world"]

That is legal syntax for both JSON and YAML. If you want to attach some YAML-specific metadata in a new model, you could make it 1:1 with the Media that matched the application/yaml media type. The YAML and JSON versions of this data would be two separate Media rows that would share the same hash_digest value. If they both stored a file, they would be pointing to the same file location. If they only used the text field, then that value would be duplicated across the two separate Media rows.

The alternative would have been to associate media types at the level where this data was being added to a ComponentVersion, but that would have added more complexity. Right now, you could make an ImageMedia 1:1 model that analyzed images and created metatdata entries for them (dimensions, GPS) without having to understand how ComponentVersion objects work.

This is definitely an edge case, and it’s likely the only time collisions like this will happen in practice is with blank files. It also means that using this table to measure disk usage may be slightly inaccurate when used in a LearningPackage with collisions–though we expect to use numbers like that mostly to get a broad sense of usage and look for major outliers, rather than for byte-level accuracy (it wouldn’t account for the non-trivial indexing storage costs either).

Immutability#

From the outside, Media should appear immutable. Since the Media is looked up by a hash of its data, a change in the data means that we should look up the hash value of that new data and create a new Media if we don’t find a match.

That being said, the Media model has different ways of storing that data, and that is mutable. We could decide that a certain type of Media should be optimized to store its text in the table. Or that a media type that we had previously only stored as text now also needs to be stored on in the file storage backend so that it can be made available to be downloaded. These operations would be done as data migrations.

Extensibility#

Third-party apps are encouraged to create models that have a OneToOneField relationship with Media. For instance, an ImageMedia model might join 1:1 with all Media that has image/* media types, and provide additional metadata for that data.

param id:

Primary key: Id

We’re going to have many foreign key references from Media into this model, and we don’t need to store those as 8-byte BigAutoField, as is the default for this app. It’s likely that a SmallAutoField would work, but I can just barely imagine using more than 32K Media types if we have a bunch of custom vnd. entries, or start tracking suffixes and parameters. Which is how we end up at the 4-byte AutoField.

type id:

~openedx_content.applets.media.models.IDField

param size:

Size

This is the size of the file in bytes. This can be different than the character length of a text file, since UTF-8 encoding can use anywhere between 1-4 bytes to represent any given character.

type size:

~django.db.models.PositiveBigIntegerField

param hash_digest:

Hash digest

This hash value may be calculated using create_hash_digest from the openedx.lib.fields module. When storing text, we hash the UTF-8 encoding of that text value, regardless of whether we also write it to a file or not. When storing just a file, we hash the bytes in the file.

type hash_digest:

~django.db.models.CharField

param has_file:

Has file

Do we have file data stored for this Media in our file storage backend? We use has_file instead of a FileField because it’s more space efficient. The location of a Media’s file data is derivable from the LearningPackage’s UUID and the hash of the Media. There’s no need to waste that space to encode it in every row.

type has_file:

~django.db.models.BooleanField

param text:

Text

The text field contains the text representation of the Media, if it is available. A blank value means means that we are storing text for this Media, and that text happens to be an empty string. A null value here means that we are not storing any text here, and the Media exists only in file form. It is an error for text to be None and has_file to be False, since that would mean we haven’t stored data anywhere at all.

type text:

~openedx_django_lib.fields.MultiCollationTextField

param created:

Created

This should be manually set so that multiple Media rows being set in the same transaction are created with the same timestamp. The timestamp should be UTC.

type created:

~django.db.models.DateTimeField

Relationship fields:

param learning_package:

Learning package (related name: media)

type learning_package:

ForeignKey to LearningPackage

param media_type:

Media type (related name: media)

What is the MediaType (a.k.a. MIME type) of this data?

type media_type:

ForeignKey to MediaType

Reverse relationships:

param component_versions:: All component versions of this Media (related name of media)
type component_versions:: Reverse ManyToManyField from ComponentVersion
param componentversionmedia:: All component version medias of this Media (related name of media)
type componentversionmedia:: Reverse ForeignKey from ComponentVersionMedia

exception DoesNotExist#: Bases: ObjectDoesNotExist

class IDField(*args, **kwargs)#: Bases: TypedBigAutoField

MAX_FILE_SIZE = 50000000#: Max size of the file.

MAX_TEXT_LENGTH = 50000#: 50K is our limit for text data, like OLX. This means 50K characters, not bytes. Since UTF-8 encodes characters using as many as 4 bytes, this could be as much as 200K of data if we had nothing but emojis.

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

clean()#

Make sure we’re actually storing something.

If this Media has neither a file or text data associated with it, it’s in a broken/useless state and shouldn’t be saved.

created#

DateTimeField

Created

This should be manually set so that multiple Media rows being set in the same transaction are created with the same timestamp. The timestamp should be UTC.

Type:: Type

file_url() → str#: This will sometimes be a time-limited signed URL.

has_file#

BooleanField

Has file

Type:: Type

hash_digest#

CharField

Hash digest

Type:: Type

media_type#

ForeignKey to MediaType

Media type (related name: media)

What is the MediaType (a.k.a. MIME type) of this data?

Type:: Type

property mime_type: str#

The IANA media type (a.k.a. MIME type) of the Media, in string form.

MIME types reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types

os_path()#

The full OS path for the underlying file for this Media.

This will not be supported by all Storage class types.

This will return None if there is no backing file (has_file=False).

property path#

Logical path at which this content is stored (or would be stored).

This path is relative to OPENEDX_LEARNING['MEDIA'] configured storage root. This file may not exist because has_file=False, or because we haven’t written the file yet (this is the method we call when trying to figure out where the file should go).

For historical reasons (and backwards compatibility), the prefix for this path is content/ and not media/.

read_file() → File#

Get a File object that has been open for reading.

We intentionally don’t expose an open() call where callers can open this file in write mode. Writing a Media file should happen at most once, and the logic is not obvious (see write_file()).

At the end of the day, the caller can close the returned File and reopen it in whatever mode they want, but we’re trying to gently discourage that kind of usage.

size#

PositiveBigIntegerField

Size

This is the size of the file in bytes. This can be different than the character length of a text file, since UTF-8 encoding can use anywhere between 1-4 bytes to represent any given character.

Type:: Type

text#

MultiCollationTextField

Text

Type:: Type

write_file(file: File) → None#

Write file contents to the file storage backend.

This function does nothing if the file already exists. Note that Media is supposed to be immutable, so this should normally only be called once for a given Media row.

class openedx_content.models_api.MediaType(*args, **kwargs)#

Bases: Model

Stores Media types for use by Media models.

This is the same as MIME types (the IANA renamed MIME Types to Media Types). We don’t pre-populate this table, so APIs that add Media must ensure that the desired Media Type exists.

Media types are written as {type}/{sub_type}+{suffix}, where suffixes are seldom used. Examples:

application/json
text/css
image/svg+xml
application/vnd.openedx.xblock.v1.problem+xml

We have this as a separate model (instead of a field on Media) because:

We can save a lot on storage and indexing for Media if we’re just storing foreign key references there, rather than the entire content string to be indexed. This is especially relevant for our (long) custom types like application/vnd.openedx.xblock.v1.problem+xml.
These values can occasionally change. For instance, text/javascript vs. application/javascript. Also, we will be using a fair number of vnd. style of custom content types, and we may want the flexibility of changing that without having to worry about migrating millions of rows of Media.

Media types are denoted as {type}/{sub_type}+{suffix}. We currently do not support parameters.

Parameters:

id (AutoField) –
Primary key: Id

We’re going to have many foreign key references from Media into this model, and we don’t need to store those as 8-byte BigAutoField, as is the default for this app. It’s likely that a SmallAutoField would work, but I can just barely imagine using more than 32K Media types if we have a bunch of custom vnd. entries, or start tracking suffixes and parameters. Which is how we end up at the 4-byte AutoField.
type (MultiCollationCharField) –
Type

Media type, e.g. application, text, image. Per RFC 4288, this can be at most 127 chars long and is case insensitive. In practice, it’s almost always written in lowercase.
sub_type (MultiCollationCharField) –
Sub type

Media sub-type, e.g. json, css, png. Per RFC 4288, this can be at most 127 chars long and is case insensitive. In practice, it’s almost always written in lowercase.
suffix (MultiCollationCharField) –
Suffix

Suffix, like xml (e.g. image/svg+xml). Usually blank. I couldn’t find an RFC description of the length limit, and 127 is probably excessive. But this table should be small enough where it doesn’t really matter.

Reverse relationships:

Parameters:: media (Reverse ForeignKey from Media) – All Media of this media type (related name of media_type)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

id#

AutoField

Primary key: Id

Type:: Type

sub_type#

MultiCollationCharField

Sub type

Media sub-type, e.g. json, css, png. Per RFC 4288, this can be at most 127 chars long and is case insensitive. In practice, it’s almost always written in lowercase.

Type:: Type

suffix#

MultiCollationCharField

Suffix

Suffix, like xml (e.g. image/svg+xml). Usually blank. I couldn’t find an RFC description of the length limit, and 127 is probably excessive. But this table should be small enough where it doesn’t really matter.

Type:: Type

type#

MultiCollationCharField

Type

Media type, e.g. application, text, image. Per RFC 4288, this can be at most 127 chars long and is case insensitive. In practice, it’s almost always written in lowercase.

Type:: Type

class openedx_content.models_api.PublishLog(*args, **kwargs)#

Bases: Model

There is one row in this table for every time content is published.

Each PublishLog has 0 or more PublishLogRecord objects describing exactly which PublishableEntity objects were published and what the version changes are. A PublishLog is like a git commit in that sense, with individual PublishLogRecord objects representing the files changed.

Open question: Empty publishes are allowed at this time, and might be useful for “fake” publishes that are necessary to invoke other post-publish actions. It’s not clear at this point how useful this will actually be.

The absence of a version_num field in this model is intentional, because having one would potentially cause write contention/locking issues when there are many people working on different entities in a very large library. We already see some contention issues occuring in ModuleStore for courses, and we want to support Libraries that are far larger.

If you need a LearningPackage-wide indicator for version and the only thing you care about is “has something changed?”, you can make a foreign key to the most recent PublishLog, or use the most recent PublishLog’s primary key. This should be monotonically increasing, though there will be large gaps in values, e.g. (5, 190, 1291, etc.). Be warned that this value will not port across sites. If you need site-portability, the UUIDs for this model are a safer bet, though there’s a lot about import/export that we haven’t fully mapped out yet.

Parameters:

id (BigAutoField) – Primary key: ID
uuid (UUIDField) – UUID
message (MultiCollationCharField) – Message
published_at (DateTimeField) – Published at

Relationship fields:

Parameters:

learning_package (ForeignKey to LearningPackage) – Learning package (related name: publishlog)
published_by (ForeignKey to User) – Published by (related name: publishlog)

Reverse relationships:

Parameters:: records (Reverse ForeignKey from PublishLogRecord) – All records of this Publish Log (related name of publish_log)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

class openedx_content.models_api.PublishLogRecord(*args, **kwargs)#

Bases: Model

A record for each publishable entity version changed, for each publish.

To revert a publish, we would make a new publish that swaps old_version and new_version field values.

If the old_version and new_version of a PublishLogRecord match, it means that the definition of the entity itself did not change (i.e. no new PublishableEntityVersion was created), but something else was published that had the side-effect of changing the published state of this entity. For instance, if a Unit has unpinned references to its child Components (which it almost always will), then publishing one of those Components will alter the published state of the Unit, even if the UnitVersion does not change.

Parameters:

id (BigAutoField) – Primary key: ID
dependencies_hash_digest (CharField) –
Dependencies hash digest

The dependencies_hash_digest is used when the version alone isn’t enough to let us know the full draft state of an entity. This happens any time a Published version has dependencies (see the PublishableEntityVersionDependency model), because changes in those dependencies will cause changes to the state of the Draft. The main example of this is containers, where changing an unpinned child affects the state of the parent container, even if that container’s definition (and thus version) does not change.

If a Published version has no dependencies, then its entire state is captured by its version, and the dependencies_hash_digest is blank. (Blank is slightly more convenient for database comparisons than NULL.)

Note: There is an equivalent of this field in the Draft model and the the values may drift away from each other.
direct (BooleanField) –
Direct

The direct field captures user intent during the publishing process. It is True if the user explicitly requested to publish the entity represented by this PublishLogRecord—i.e. they clicked “publish” on this entity or selected it for bulk publish.

This field is False if this entity was indirectly published either as a child/dependency or side-effect of a directly published entity.

If this field is None, that means that this PublishLogRecord was created before we started capturing user intent (pre-Verawood release), and we cannot reliably infer what the user clicked on. For example, say we had a Subsection > Unit > Component arrangement where the Component had an unpublished change. The user is allowed to press the “publish” button at the Subsection, Unit, or Component levels in the UI. Before we started recording this field, the resulting PublishLog objects would have looked identical in all three cases: a version change PublishLogRecord for Component, and side-effect records for the Unit and Subsection. Therefore, we cannot accurately backfill this field.

Here are some examples to illustrate how direct gets set and why:

Example 1: The user clicks “publish” on a Component that’s in a Unit.

The Component has direct=True, but the side-effect PublishLogRecord for the Unit has direct=False. Likewise, any side-effect records at higher levels (subsection, section) also have direct=False.

Example 2: The user clicks “publish” on a Unit, where both the Unit and Component have unpublished changes.

In this case, the Unit has direct=True, and the Component has direct=False. The draft status of the Component is irrelevant. The user asked for the Unit to the published, so the Unit’s PublishLogRecord is the only thing that gets direct=True.

Example 3: The user clicks “publish” on a Unit that has no changes of its own (draft version == published version), but the Unit contains a Component that has changes.

Again, only the PublishLogRecord for the Unit has direct=True. The Component’s PublishLogRecord has direct=False. Even though the Unit’s published version_num does not change (i.e. it is purely a side-effect publish), the user intent was to publish the Unit (and anything it contains), so the Unit gets direct=True.

Example 4: The user selects multiple entities for bulk publishing.

Those exact entities that the user selected get direct=True. It does not matter if some of those entities are children of other selected items or not. Other entries like dependencies or side-effects have direct=False.

Example 5: The user selects “publish all”.

Selecting “publish all” in our system currently translates into “publish all the entities that have a draft version that is different from its published version”. Those entities would get PublishLogRecord objects with direct=True, while all side-effects would get records with direct=False. So if a Unit’s draft and published versions match, and one of its Components has unpublished changes, then “publish all” would cause the Component’s record to have direct=True and the Unit’s record to have direct=False.

Relationship fields:

Parameters:

publish_log (ForeignKey to PublishLog) – Publish log (related name: records)
entity (ForeignKey to PublishableEntity) – Entity (related name: publishlogrecord)
old_version (ForeignKey to PublishableEntityVersion) – Old version (related name: +)
new_version (ForeignKey to PublishableEntityVersion) – New version (related name: publishlogrecord)

Reverse relationships:

Parameters:

published (Reverse ForeignKey from Published) – All Published Entities of this Publish Log Record (related name of publish_log_record)
causes (Reverse ForeignKey from PublishSideEffect) – All causes of this Publish Log Record (related name of cause)
affected_by (Reverse ForeignKey from PublishSideEffect) – All affected by of this Publish Log Record (related name of effect)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

dependencies_hash_digest#

CharField

Dependencies hash digest

The dependencies_hash_digest is used when the version alone isn’t enough to let us know the full draft state of an entity. This happens any time a Published version has dependencies (see the PublishableEntityVersionDependency model), because changes in those dependencies will cause changes to the state of the Draft. The main example of this is containers, where changing an unpinned child affects the state of the parent container, even if that container’s definition (and thus version) does not change.

If a Published version has no dependencies, then its entire state is captured by its version, and the dependencies_hash_digest is blank. (Blank is slightly more convenient for database comparisons than NULL.)

Note: There is an equivalent of this field in the Draft model and the the values may drift away from each other.

Type:: Type

direct#

BooleanField

Direct

The direct field captures user intent during the publishing process. It is True if the user explicitly requested to publish the entity represented by this PublishLogRecord—i.e. they clicked “publish” on this entity or selected it for bulk publish.

This field is False if this entity was indirectly published either as a child/dependency or side-effect of a directly published entity.

If this field is None, that means that this PublishLogRecord was created before we started capturing user intent (pre-Verawood release), and we cannot reliably infer what the user clicked on. For example, say we had a Subsection > Unit > Component arrangement where the Component had an unpublished change. The user is allowed to press the “publish” button at the Subsection, Unit, or Component levels in the UI. Before we started recording this field, the resulting PublishLog objects would have looked identical in all three cases: a version change PublishLogRecord for Component, and side-effect records for the Unit and Subsection. Therefore, we cannot accurately backfill this field.

Here are some examples to illustrate how direct gets set and why:

Example 1: The user clicks “publish” on a Component that’s in a Unit.

The Component has direct=True, but the side-effect PublishLogRecord for the Unit has direct=False. Likewise, any side-effect records at higher levels (subsection, section) also have direct=False.

Example 2: The user clicks “publish” on a Unit, where both the Unit and Component have unpublished changes.

In this case, the Unit has direct=True, and the Component has direct=False. The draft status of the Component is irrelevant. The user asked for the Unit to the published, so the Unit’s PublishLogRecord is the only thing that gets direct=True.

Example 3: The user clicks “publish” on a Unit that has no changes of its own (draft version == published version), but the Unit contains a Component that has changes.

Again, only the PublishLogRecord for the Unit has direct=True. The Component’s PublishLogRecord has direct=False. Even though the Unit’s published version_num does not change (i.e. it is purely a side-effect publish), the user intent was to publish the Unit (and anything it contains), so the Unit gets direct=True.

Example 4: The user selects multiple entities for bulk publishing.

Those exact entities that the user selected get direct=True. It does not matter if some of those entities are children of other selected items or not. Other entries like dependencies or side-effects have direct=False.

Example 5: The user selects “publish all”.

Selecting “publish all” in our system currently translates into “publish all the entities that have a draft version that is different from its published version”. Those entities would get PublishLogRecord objects with direct=True, while all side-effects would get records with direct=False. So if a Unit’s draft and published versions match, and one of its Components has unpublished changes, then “publish all” would cause the Component’s record to have direct=True and the Unit’s record to have direct=False.

Type:: Type

class openedx_content.models_api.PublishSideEffect(*args, **kwargs)#

Bases: Model

Model to track when a change in one Published entity affects others.

Our first use case for this is that changes involving child components are thought to affect parent Units, even if the parent’s version doesn’t change.

Side-effects are recorded in a collapsed form that only captures one level. So if Components C1 and C2 are both published and they are part of Unit U1, which is in turn a part of Subsection SS1, then the PublishSideEffect entries are:

(C1, U1)
(C2, U1)
(U1, SS1)

We do not keep entries for (C1, SS1) or (C2, SS1). This is to make the model simpler, so we don’t have to differentiate between direct side-effects and transitive side-effects in the model.

Parameters:: id (BigAutoField) – Primary key: ID

Relationship fields:

Parameters:

cause (ForeignKey to PublishLogRecord) – Cause (related name: causes)
effect (ForeignKey to PublishLogRecord) – Effect (related name: affected_by)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

class openedx_content.models_api.PublishableContentModelRegistry#

Bases: object

This class tracks content models built on PublishableEntity (and PublishableEntityVersion).

classmethod register(content_model_cls: type[PublishableEntityMixin], content_version_model_cls: type[PublishableEntityVersionMixin])#

If you want to call this from another app, please use the register_publishable_models function in this app’s api module instead.

class openedx_content.models_api.PublishableEntity(*args, **kwargs)#

Bases: Model

This represents any publishable thing that has ever existed in a LearningPackage. It serves as a stable model that will not go away even if these things are later unpublished or deleted.

A PublishableEntity belongs to exactly one LearningPackage.

Examples of Publishable Entities#

Component objects (e.g. VideoBlock, ProblemBlock), Units, and Sections/Subsections would all be considered Publishable Entites. But anything that can be imported, exported, published, and reverted in a course or library could be modeled as a PublishableEntity, including things like Grading Policy or possibly Taxonomies (?).

How to use this model#

The publishing app understands that publishable entities exist, along with their drafts and published versions. It has some basic metadata, such as identifiers, who created it, and when it was created. It’s meant to encapsulate the draft and publishing related aspects of your content, but the publishing app doesn’t know anything about the actual content being referenced.

You have to provide actual meaning to PublishableEntity by creating your own models that will represent your particular content and associating them to PublishableEntity via a OneToOneField with primary_key=True. The easiest way to do this is to have your model inherit from PublishableEntityMixin.

Identifiers#

The UUID is globally unique and should be treated as immutable.

The key field is mutable, but changing it will affect all PublishableEntityVersion objects. They are locally unique within the LearningPackage.

If you are referencing this model from within the same process, use a foreign key to the id. If you are referencing this PublishableEntity from an external system/service, use the UUID. The key is the part that is most likely to be human-readable, and may be exported/copied, but try not to rely on it, since this value may change.

Note: When we actually implement the ability to change identifiers, we should make a history table and a modified attribute on this model.

Why are Identifiers in this Model?#

A PublishableEntity never stands alone–it’s always intended to be used with a 1:1 model like Component or Unit. So why have all the identifiers in this model instead of storing them in those other models? Two reasons:

Published things need to have the right identifiers so they can be used throughout the system, and the UUID is serving the role of ISBN in physical book publishing.
We want to be able to enforce the idea that entity_ref is locally unique across all PublishableEntity objects within a given LearningPackage. Component and Unit can’t do that without a shared model.

That being said, models that build on PublishableEntity are free to add their own identifiers if it’s useful to do so.

Why not Inherit from this Model?#

Django supports multi-table inheritance.

We don’t use that, primarily because we want to more clearly decouple publishing concerns from the rest of the logic around Component objects, Units, etc. If you made a Component and ComponentVersion models that subclassed PublishableEntity and PublishableEntityVersion, and then accessed component.versions, you might expect ComponentVersion objects to come back and be surprised when you get EntityVersions instead.

In general, we want freedom to add new Publishing models, fields, and methods without having to worry about the downstream name collisions with other apps (many of which might live in other repositories). The helper mixins will provide a little syntactic sugar to make common access patterns more convenient, like file access.

param id:

Primary key: Id

type id:

~openedx_content.applets.publishing.models.publishable_entity.IDField

param uuid:

UUID

type uuid:

~django.db.models.UUIDField

param entity_ref:

Entity ref

entity_ref is an opaque reference string assigned by the creator of this entity (e.g. derived from component_type + component_code for Component objects). Consumers must treat it as an atomic string — do not parse or reconstruct it.

type entity_ref:

~openedx_django_lib.fields.MultiCollationCharField

param created:

Created

All PublishableEntityVersion objects created as part of the same publish should have the exact same created datetime (not off by a handful of microseconds).

type created:

~django.db.models.DateTimeField

param can_stand_alone:

Can stand alone. Set to True when created independently, False when created as part of a container.

type can_stand_alone:

~django.db.models.BooleanField

Relationship fields:

param learning_package:

Learning package (related name: publishable_entities)

type learning_package:

ForeignKey to LearningPackage

param created_by:

Created by (related name: publishableentity)

User who created the PublishableEntityVersion. This can be null if the user is later removed. Open edX in general doesn’t let you remove users, but we should try to model it so that this is possible eventually.

type created_by:

ForeignKey to User

Reverse relationships:

param versions:: All versions of this Publishable Entity (related name of entity)
type versions:: Reverse ForeignKey from PublishableEntityVersion
param affects:: All affects of this Publishable Entity (related name of dependencies)
type affects:: Reverse ManyToManyField from PublishableEntityVersion
param publishableentityversiondependency:: All publishable entity version dependencys of this Publishable Entity (related name of referenced_entity)
type publishableentityversiondependency:: Reverse ForeignKey from PublishableEntityVersionDependency
param draft:: The draft of this Publishable Entity (related name of entity)
type draft:: Reverse OneToOneField from Draft
param draftchangelogrecord:: All Draft Change Log Records of this Publishable Entity (related name of entity)
type draftchangelogrecord:: Reverse ForeignKey from DraftChangeLogRecord
param publishlogrecord:: All Publish Log Records of this Publishable Entity (related name of entity)
type publishlogrecord:: Reverse ForeignKey from PublishLogRecord
param published:: The Published Entity of this Publishable Entity (related name of entity)
type published:: Reverse OneToOneField from Published
param collections:: All collections of this Publishable Entity (related name of entities)
type collections:: Reverse ManyToManyField from Collection
param collectionpublishableentity:: All collection publishable entitys of this Publishable Entity (related name of entity)
type collectionpublishableentity:: Reverse ForeignKey from CollectionPublishableEntity
param component:: The Component of this Publishable Entity (related name of publishable_entity)
type component:: Reverse OneToOneField from Component
param entitylistrow:: All entity list rows of this Publishable Entity (related name of entity)
type entitylistrow:: Reverse ForeignKey from EntityListRow
param container:: The container of this Publishable Entity (related name of publishable_entity)
type container:: Reverse OneToOneField from Container
param testentity:: The test entity of this Publishable Entity (related name of publishable_entity)
type testentity:: Reverse OneToOneField from TestEntity

exception DoesNotExist#: Bases: ObjectDoesNotExist

class IDField(*args, **kwargs)#: Bases: TypedBigAutoField

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

entity_ref#

MultiCollationCharField

Entity ref

Type:: Type

class openedx_content.models_api.PublishableEntityMixin(*args, **kwargs)#

Bases: Model

Convenience mixin to link your models against PublishableEntity.

Please see docstring for PublishableEntity for more details.

If you use this class, you MUST also use PublishableEntityVersionMixin and the publishing app’s api.register_publishable_models (see its docstring for details).

Relationship fields:

Parameters:: publishable_entity (OneToOneField to PublishableEntity) – Primary key: Publishable entity

class VersioningHelper(content_obj)#

Bases: object

Helper class to link content models to their versions.

The publishing app has PublishableEntity and PublishableEntityVersion. This is a helper class so that if you mix PublishableEntityMixin into a content model like Component, then you can do something like:

component.versioning.draft  # current draft ComponentVersion
component.versioning.published  # current published ComponentVersion

It links the relationships between content models and their versioned counterparts through the connection between PublishableEntity and PublishableEntityVersion. So component.versioning.draft ends up querying: Component → PublishableEntity → Draft → PublishableEntityVersion → ComponentVersion. But the people writing Component don’t need to understand how the publishing models work to do these common queries.

Caching Warning#

Note that because we’re just using the underlying model’s relations, calling this a second time will returned the cached relation, and not cause a fetch of new data from the database. So for instance, if you do:

# Create a new Component + ComponentVersion
component, component_version = create_component_and_version(
    learning_package_id=learning_package.id,
    namespace="xblock.v1",
    type="problem",
    component_code="monty_hall",
    title="Monty Hall Problem",
    created=now,
    created_by=None,
)

# This will work, because it's never been published
assert component.versioning.published is None

# Publishing happens
publish_all_drafts(learning_package.id, published_at=now)

# This will FAIL because it's going to use the relation value
# cached on component instead of going to the database again.
# You need to re-fetch the component for this to work.
assert component.versioning.published == component_version

# You need to manually refetch it from the database to see the new
# publish status:
component = get_component(component.id)

# Now this will work:
assert component.versioning.published == component_version

TODO: This probably means we should use a custom Manager to select related fields.

__init__(content_obj)#

property draft#

Return the content version object that is the current draft.

So if you mix PublishableEntityMixin into Component, then component.versioning.draft will return you the ComponentVersion that is the current draft (not the underlying PublishableEntityVersion).

If this is causing many queries, it might be the case that you need to add select_related('publishable_entity__draft__version') to the queryset.

property has_unpublished_changes#

Do we have unpublished changes?

The simplest way to implement this would be to check self.published vs. self.draft, but that would cause unnecessary queries. This implementation should require no extra queries provided that the model was instantiated using a queryset that used a select related that has at least publishable_entity__draft and publishable_entity__published.

property last_publish_log#

Return the most recent PublishLog for this component.

Return None if the component is not published.

property latest#

Return the most recently created version for this content object.

This can be None if no versions have been created.

This is often the same as the draft version, but can differ if the content object was soft deleted or the draft was reverted.

property published#

Return the content version object that is currently published.

So if you mix PublishableEntityMixin into Component, then component.versioning.published will return you the ComponentVersion that is currently published (not the underlying PublishableEntityVersion).

If this is causing many queries, it might be the case that you need to add select_related('publishable_entity__published__version') to the queryset.

version_num(version_num)#: Return a specific numbered version model.

property versions#

Return a QuerySet of content version models for this content model.

Example: If you mix PublishableEntityMixin into a Component model, this would return you a QuerySet of ComponentVersion models.

class openedx_content.models_api.PublishableEntityVersion(*args, **kwargs)#

Bases: Model

A particular version of a PublishableEntity.

This model has its own uuid so that it can be referenced directly. The uuid should be treated as immutable.

PublishableEntityVersion objects are created once and never updated. So for instance, the title should never be modified.

Like PublishableEntity, the data in this model is only enough to cover the parts that are most important for the actual process of managing drafts and publishes. You will want to create your own models to represent the actual content data that’s associated with this PublishableEntityVersion, and connect them using a OneToOneField with primary_key=True. The easiest way to do this is to inherit from PublishableEntityVersionMixin. Be sure to treat these versioned models in your app as immutable as well.

Parameters:

id (BigAutoField) – Primary key: ID
uuid (UUIDField) – UUID
title (MultiCollationCharField) –
Title

Most publishable things will have some sort of title, but blanks are allowed for those that don’t require one.
version_num (PositiveIntegerField) –
Version num

The version_num starts at 1 and increments by 1 with each new version for a given PublishableEntity. Doing it this way makes it more convenient for users to refer to than a hash or UUID value. It also helps us catch race conditions on save, by setting a unique constraint on the entity and version_num.
created (DateTimeField) –
Created

All PublishableEntityVersion objects created as part of the same publish should have the exact same created datetime (not off by a handful of microseconds).

Relationship fields:

Parameters:

entity (ForeignKey to PublishableEntity) – Entity (related name: versions)
created_by (ForeignKey to User) –
Created by (related name: publishableentityversion)

User who created the PublishableEntityVersion. This can be null if the user is later removed. Open edX in general doesn’t let you remove users, but we should try to model it so that this is possible eventually.
dependencies (ManyToManyField to PublishableEntity) – Dependencies (related name: affects)

Reverse relationships:

Parameters:

publishableentityversiondependency (Reverse ForeignKey from PublishableEntityVersionDependency) – All publishable entity version dependencys of this Publishable Entity Version (related name of referring_version)
draft (Reverse OneToOneField from Draft) – The draft of this Publishable Entity Version (related name of version)
draftchangelogrecord (Reverse ForeignKey from DraftChangeLogRecord) – All Draft Change Log Records of this Publishable Entity Version (related name of new_version)
publishlogrecord (Reverse ForeignKey from PublishLogRecord) – All Publish Log Records of this Publishable Entity Version (related name of new_version)
published (Reverse OneToOneField from Published) – The Published Entity of this Publishable Entity Version (related name of version)
componentversion (Reverse OneToOneField from ComponentVersion) – The Component Version of this Publishable Entity Version (related name of publishable_entity_version)
containerversion (Reverse OneToOneField from ContainerVersion) – The container version of this Publishable Entity Version (related name of publishable_entity_version)
testentityversion (Reverse OneToOneField from TestEntityVersion) – The test entity version of this Publishable Entity Version (related name of publishable_entity_version)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

created#

DateTimeField

Created

All PublishableEntityVersion objects created as part of the same publish should have the exact same created datetime (not off by a handful of microseconds).

Type:: Type

created_by#

ForeignKey to User

Created by (related name: publishableentityversion)

Type:: Type

title#

MultiCollationCharField

Title

Most publishable things will have some sort of title, but blanks are allowed for those that don’t require one.

Type:: Type

version_num#

PositiveIntegerField

Version num

The version_num starts at 1 and increments by 1 with each new version for a given PublishableEntity. Doing it this way makes it more convenient for users to refer to than a hash or UUID value. It also helps us catch race conditions on save, by setting a unique constraint on the entity and version_num.

Type:: Type

class openedx_content.models_api.PublishableEntityVersionDependency(*args, **kwargs)#

Bases: Model

Track the PublishableEntity objects that a PublishableEntityVersion depends on.

For example, a partcular version of a Unit (U1.v1) might be defined to have unpinned references to Components C1 and C2. That means that any changes in C1 or C2 will affect U1.v1 via DraftSideEffect and PublishSideEffect. We say that C1 and C2 are dependencies of U1.v1.

An important restriction is that a PublishableEntityVersion’s list of dependencies are defined when the version is created. It is not modified after that. No matter what happens to C1 or C2 (e.g. edit, deletion, un-deletion, reset-draft-version-to-published), they will always be dependencies of U1.v1.

If someone removes C2 from U1, then that requires creating a new version of U1 (so U1.v2).

This restriction is important because our ability to calculate and cache the state of “this version of this publishable entity and all its dependencies (children)” relies on this being true.

Parameters:: id (BigAutoField) – Primary key: ID

Relationship fields:

Parameters:

referring_version (ForeignKey to PublishableEntityVersion) – Referring version (related name: publishableentityversiondependency)
referenced_entity (ForeignKey to PublishableEntity) – Referenced entity (related name: publishableentityversiondependency)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

class openedx_content.models_api.PublishableEntityVersionMixin(*args, **kwargs)#

Bases: Model

Convenience mixin to link your models against PublishableEntityVersion.

Please see docstring for PublishableEntityVersion for more details.

If you use this class, you MUST also use PublishableEntityMixin and the publishing app’s api.register_publishable_models (see its docstring for details).

Relationship fields:

Parameters:: publishable_entity_version (OneToOneField to PublishableEntityVersion) – Primary key: Publishable entity version

class openedx_content.models_api.Published(*args, **kwargs)#

Bases: Model

Find the currently published version of an entity.

Notes:

There is only ever one published PublishableEntityVersion per PublishableEntity at any given time.
It may be possible for a PublishableEntity to exist only as a Draft (and thus not show up in this table).
If a row exists for a PublishableEntity, but the version field is None, it means that the entity was published at some point, but is no longer published now–i.e. it’s functionally “deleted”, even though all the version history is preserved behind the scenes.

Relationship fields:

Parameters:

entity (OneToOneField to PublishableEntity) – Primary key: Entity (related name: published)
version (OneToOneField to PublishableEntityVersion) – Version (related name: published)
publish_log_record (ForeignKey to PublishLogRecord) – Publish log record (related name: published)

exception DoesNotExist#: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

class openedx_content.models_api.Section(*args, **kwargs)#

Bases: Container

A Section is type of Container that holds Subsection children.

Via Container and its PublishableEntityMixin, Sections are also publishable entities and can be added to other containers.

Parameters:: container_code (MultiCollationCharField) – Container code

Relationship fields:

Parameters:

publishable_entity (OneToOneField to PublishableEntity) – Primary key: Publishable entity (related name: container)
learning_package (ForeignKey to LearningPackage) – Learning package (related name: container)
container_type (ForeignKey to ContainerType) – Container type (related name: container)
container (OneToOneField to Container) – Primary key: Container (related name: section)

Reverse relationships:

Parameters:: versions (Reverse ForeignKey from ContainerVersion) – All versions of this container (related name of container)

exception DoesNotExist#: Bases: DoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

olx_tag_name: str = 'chapter'#: The OLX <tag_name> for XML serialization. Subclasses _may_ override this. Only used in openedx-platform at the moment. We’ll likely have to replace this with something more sophisticated.

classmethod validate_entity(entity: PublishableEntity) → None#: Check if the given entity is allowed as a child of a Section

class openedx_content.models_api.SectionVersion(*args, **kwargs)#

Bases: ContainerVersion

A SectionVersion is a specific version of a Section.

Via ContainerVersion and its EntityList, it defines the list of Subsection children in this version of the Section.

Relationship fields:

Parameters:

publishable_entity_version (OneToOneField to PublishableEntityVersion) – Primary key: Publishable entity version (related name: containerversion)
container (ForeignKey to Container) – Container (related name: versions)
entity_list (ForeignKey to EntityList) – Entity list (related name: container_versions)
container_version (OneToOneField to ContainerVersion) – Primary key: Container version (related name: sectionversion)

exception DoesNotExist#: Bases: DoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

property section: Section#: Convenience accessor to the Section this version is associated with

class openedx_content.models_api.Subsection(*args, **kwargs)#

Bases: Container

A Subsection is type of Container that holds Unit children.

Via Container and its PublishableEntityMixin, Subsections are also publishable entities and can be added to other containers.

Parameters:: container_code (MultiCollationCharField) – Container code

Relationship fields:

Parameters:

publishable_entity (OneToOneField to PublishableEntity) – Primary key: Publishable entity (related name: container)
learning_package (ForeignKey to LearningPackage) – Learning package (related name: container)
container_type (ForeignKey to ContainerType) – Container type (related name: container)
container (OneToOneField to Container) – Primary key: Container (related name: subsection)

Reverse relationships:

Parameters:: versions (Reverse ForeignKey from ContainerVersion) – All versions of this container (related name of container)

exception DoesNotExist#: Bases: DoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

olx_tag_name: str = 'sequential'#: The OLX <tag_name> for XML serialization. Subclasses _may_ override this. Only used in openedx-platform at the moment. We’ll likely have to replace this with something more sophisticated.

classmethod validate_entity(entity: PublishableEntity) → None#: Check if the given entity is allowed as a child of a Subsection

class openedx_content.models_api.SubsectionVersion(*args, **kwargs)#

Bases: ContainerVersion

A SubsectionVersion is a specific version of a Subsection.

Via ContainerVersion and its EntityList, it defines the list of Unit children in this version of the Subsection.

Relationship fields:

Parameters:

publishable_entity_version (OneToOneField to PublishableEntityVersion) – Primary key: Publishable entity version (related name: containerversion)
container (ForeignKey to Container) – Container (related name: versions)
entity_list (ForeignKey to EntityList) – Entity list (related name: container_versions)
container_version (OneToOneField to ContainerVersion) – Primary key: Container version (related name: subsectionversion)

exception DoesNotExist#: Bases: DoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

property subsection: Subsection#: Convenience accessor to the Subsection this version is associated with

class openedx_content.models_api.Unit(*args, **kwargs)#

Bases: Container

A Unit is type of Container that holds Component children.

Via Container and its PublishableEntityMixin, Units are also publishable entities and can be added to other containers.

Parameters:: container_code (MultiCollationCharField) – Container code

Relationship fields:

Parameters:

publishable_entity (OneToOneField to PublishableEntity) – Primary key: Publishable entity (related name: container)
learning_package (ForeignKey to LearningPackage) – Learning package (related name: container)
container_type (ForeignKey to ContainerType) – Container type (related name: container)
container (OneToOneField to Container) – Primary key: Container (related name: unit)

Reverse relationships:

Parameters:: versions (Reverse ForeignKey from ContainerVersion) – All versions of this container (related name of container)

exception DoesNotExist#: Bases: DoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

olx_tag_name: str = 'vertical'#: The OLX <tag_name> for XML serialization. Subclasses _may_ override this. Only used in openedx-platform at the moment. We’ll likely have to replace this with something more sophisticated.

classmethod validate_entity(entity: PublishableEntity) → None#: Check if the given entity is allowed as a child of a Unit

class openedx_content.models_api.UnitVersion(*args, **kwargs)#

Bases: ContainerVersion

A UnitVersion is a specific version of a Unit.

Via ContainerVersion and its EntityList, it defines the list of Component children in this version of the Unit.

Relationship fields:

Parameters:

publishable_entity_version (OneToOneField to PublishableEntityVersion) – Primary key: Publishable entity version (related name: containerversion)
container (ForeignKey to Container) – Container (related name: versions)
entity_list (ForeignKey to EntityList) – Entity list (related name: container_versions)
container_version (OneToOneField to ContainerVersion) – Primary key: Container version (related name: unitversion)

exception DoesNotExist#: Bases: DoesNotExist

exception MultipleObjectsReturned#: Bases: MultipleObjectsReturned

property unit: Unit#: Convenience accessor to the Unit this version is associated with

Content Models

Contents

Content Models#

What is a Component#

Identifiers#

State Consistency#

How build on this model#

In-model Text vs. File#

Association with a LearningPackage#

Media Types, and file duplication#

Immutability#

Extensibility#

Examples of Publishable Entities#

How to use this model#

Identifiers#

Why are Identifiers in this Model?#

Why not Inherit from this Model?#

Caching Warning#