openedx.core.djangoapps.xblock.runtime package

openedx.core.djangoapps.xblock.runtime package#

Submodules#

openedx.core.djangoapps.xblock.runtime.blockstore_field_data module#

Key-value store that holds XBlock field data read out of Blockstore

class openedx.core.djangoapps.xblock.runtime.blockstore_field_data.ActiveBlock(olx_hash, changed_fields)#

Bases: tuple

changed_fields#: Alias for field number 1

olx_hash#: Alias for field number 0

class openedx.core.djangoapps.xblock.runtime.blockstore_field_data.BlockInstanceUniqueKey#

Bases: object

An empty object used as a unique key for each XBlock instance, see get_weak_key_for_block() and BlockstoreFieldData._get_active_block(). Every XBlock instance will get a unique one of these keys, even if they are otherwise identical. Its purpose is similar to id(block).

class openedx.core.djangoapps.xblock.runtime.blockstore_field_data.BlockstoreChildrenData(blockstore_field_data)#

Bases: FieldData

An XBlock FieldData implementation that reads ‘children’ data out of the definition fields in BlockstoreFieldData.

The children field contains usage keys and so is usage-specific; the BlockstoreFieldData can only store field data that is not usage-specific. So we store data about the <xblock-include /> elements that define the children in BlockstoreFieldData (since that is not usage-specific), and this field data implementation loads that <xblock-include /> data and transforms it into the usage keys that comprise the standard .children field.

append_include(block, parsed_include)#: Append an <xblock-include /> element to this XBlock’s list of children

delete(block, name)#: Reset the value of the field named name to the default

get(block, name)#

Get the “children’ field value.

We do this by reading the parsed <xblock-include /> values from the regular authored data store and then transforming them to usage IDs.

get_includes(block)#: Get the list of <xblock-include /> elements representing this XBlock’s children.

set(block, name, value)#: Set the value of the field; requires name=’children’

class openedx.core.djangoapps.xblock.runtime.blockstore_field_data.BlockstoreFieldData#

Bases: FieldData

An XBlock FieldData implementation that reads XBlock field data directly out of Blockstore.

It requires that every XBlock have a BundleDefinitionLocator as its “definition key”, since the BundleDefinitionLocator is what specifies the OLX file path and version to use.

Within Blockstore there is no mechanism for setting different field values at the usage level compared to the definition level, so we treat usage-scoped fields identically to definition-scoped fields.

cache_fields(block)#

Cache field data: This is called by the runtime after a block has parsed its OLX via its parse_xml() methods and written all of its field values into this field data store. The values will be stored in

self._get_active_block(block).changed_fields

so we know at this point that that isn’t really “changed” field data, it’s the result of parsing the OLX. Save a copy into loaded_definitions.

default(block, name)#: Get the default value for block’s field ‘name’. The XBlock class will provide the default if KeyError is raised; this is mostly for the purpose of context-specific overrides.

delete(block, name)#: Reset the value of the field named name to the default

free_unused_definitions()#: Free unused field data cache entries from self.loaded_definitions as long as they’re not in use.

get(block, name)#

Get the given field value from Blockstore

If the XBlock has been making changes to its fields, the value will be in self._get_active_block(block).changed_fields[name]

Otherwise, the value comes from self.loaded_definitions which is a dict of OLX file field data, keyed by the hash of the OLX file.

has_cached_definition(definition_key)#: Has the specified OLX file been loaded into memory?

has_changes(block)#: Does the specified block have any unsaved changes?

set(block, name, value)#: Set the value of the field named name

openedx.core.djangoapps.xblock.runtime.blockstore_field_data.get_olx_hash_for_definition_key(def_key)#: Given a BundleDefinitionLocator, which identifies a specific version of an OLX file, return the hash of the OLX file as given by the Blockstore API.

openedx.core.djangoapps.xblock.runtime.blockstore_field_data.get_weak_key_for_block(block)#: Given an XBlock instance, return an object with the same lifetime as the block, suitable as a key to hold block-specific data in a WeakKeyDictionary.

openedx.core.djangoapps.xblock.runtime.blockstore_runtime module#

A runtime designed to work with Blockstore, reading and writing XBlock field data directly from Blockstore.

class openedx.core.djangoapps.xblock.runtime.blockstore_runtime.BlockstoreXBlockRuntime(system: XBlockRuntimeSystem, user: UserType | None)#

Bases: XBlockRuntime

A runtime designed to work with Blockstore, reading and writing XBlock field data directly from Blockstore.

add_child_include(block, parsed_include)#: Given an XBlockInclude tuple that represents a new <xblock-include /> node, add it as a child of the specified XBlock. This is the only supported API for adding a new child to an XBlock - one cannot just modify block.children to append a usage ID, since that doesn’t provide enough information to serialize the block’s <xblock-include /> elements.

add_node_as_child(block, node, id_generator=None)#: This runtime API should normally be used via runtime.get_block() -> block.parse_xml() -> runtime.add_node_as_child

block_field_datas: dict[ScopeIds, FieldData | None]#

child_includes_of(block)#: Get the list of <xblock-include /> directives that define the children of this block’s definition.

django_field_data_caches: dict[LearningContextKey, FieldDataCache]#

get_block(usage_id, for_parent=None)#

Create an XBlock instance in this runtime.

Parameters:: usage_key (OpaqueKey) – identifier used to find the XBlock class and data.

parse_xml_file(fileobj, id_generator=None)#: Parse an open XML file, returning a usage id.

save_block(block)#

Save any pending field data values to Blockstore.

This gets called by block.save() - do not call this directly.

user: UserType | None#

view_name: str | None#

openedx.core.djangoapps.xblock.runtime.blockstore_runtime.xml_for_definition(definition_key)#: Method for loading OLX from Blockstore and parsing it to an etree.

openedx.core.djangoapps.xblock.runtime.ephemeral_field_data module#

An KeyValueStore that stores data in the django cache

This is used for low-priority ephemeral student state data: * Anonymous users browsing and previewing content * Studio authors testing out XBlocks

We could also store this data in django sessions, but its a bit tricky to access session data during any requests which don’t have any cookies or other normal authentication mechanisms (like XBlock handler calls from within XBlock <iframe> sandboxes). And keeping this storage completely separate from django session data and registered user XBlock state reduces the potential for security problems. We expect the data in this store to be low-value and free of personally identifiable information (PII) so if some security bug results in one user accessing a different user’s entries in this particular store, it’s not a big deal.

class openedx.core.djangoapps.xblock.runtime.ephemeral_field_data.EphemeralKeyValueStore#

Bases: KeyValueStore

An XBlock field data key-value store that is backed by the django cache

delete(key)#: Deletes key from storage.

get(key)#: Reads the value of the given key from storage.

has(key)#: Returns whether or not key is present in storage.

set(key, value)#: Sets key equal to value in storage.

class openedx.core.djangoapps.xblock.runtime.ephemeral_field_data.NotFound#

Bases: object

This class is a unique value that can be stored in a cache to indicate “not found”

openedx.core.djangoapps.xblock.runtime.id_managers module#

Implementation of the APIs required for XBlock runtimes to work with our newer Open edX-specific opaque key formats.

class openedx.core.djangoapps.xblock.runtime.id_managers.OpaqueKeyReader#

Bases: IdReader

IdReader for DefinitionKey and :class:`UsageKey`s.

get_aside_type_from_definition(aside_id)#

Retrieve the XBlockAside aside_type associated with this aside definition id.

Parameters:: aside_id – The definition id of the XBlockAside.
Returns:: The aside_type of the aside.

get_aside_type_from_usage(aside_id)#

Retrieve the XBlockAside aside_type associated with this aside usage id.

Parameters:: aside_id – The usage id of the XBlockAside.
Returns:: The aside_type of the aside.

get_block_type(def_id)#

Retrieve the block_type of a particular definition

Parameters:: def_id – The id of the definition to query
Returns:: The block_type of the definition

get_definition_id(usage_id)#

Retrieve the definition that a usage is derived from.

Parameters:: usage_id – The id of the usage to query
Returns:: The definition_id the usage is derived from

get_definition_id_from_aside(aside_id)#

Retrieve the XBlock definition_id associated with this aside definition id.

Parameters:: aside_id – The usage id of the XBlockAside.
Returns:: The definition_id of the usage the aside is commenting on.

get_usage_id_from_aside(aside_id)#

Retrieve the XBlock usage_id associated with this aside usage id.

Parameters:: aside_id – The usage id of the XBlockAside.
Returns:: The usage_id of the usage the aside is commenting on.

openedx.core.djangoapps.xblock.runtime.mixin module#

A mixin that provides functionality and default attributes for all XBlocks in the new XBlock runtime.

class openedx.core.djangoapps.xblock.runtime.mixin.LmsBlockMixin(scope_ids, field_data=None, **kwargs)#

Bases: XBlockMixin

A mixin that provides functionality and default attributes for all XBlocks in the new XBlock runtime.

These are not standard XBlock attributes but are used by the LMS (and possibly Studio).

has_score = False#

public_view(_context)#

Default message for blocks that don’t implement public_view

public_view is shown when users aren’t logged in and/or are not enrolled in a particular course.

publish_completion(data, suffix='')#

Allow the frontend app that’s rendering this XBlock to mark it as completed when the user views it, if appropriate.

Copied from lms.djangoapps.lms_xblock.mixin.LmsBlockMixin

openedx.core.djangoapps.xblock.runtime.olx_parsing module#

Helpful methods to use when parsing OLX (XBlock XML)

exception openedx.core.djangoapps.xblock.runtime.olx_parsing.BundleFormatException#

Bases: Exception

Raised when certain errors are found when parsing the OLX in a content library bundle.

class openedx.core.djangoapps.xblock.runtime.olx_parsing.XBlockInclude(link_id, block_type, definition_id, usage_hint)#

Bases: tuple

block_type#: Alias for field number 1

definition_id#: Alias for field number 2

link_id#: Alias for field number 0

usage_hint#: Alias for field number 3

openedx.core.djangoapps.xblock.runtime.olx_parsing.definition_for_include(parsed_include, parent_definition_key)#

Given a parsed <xblock-include /> element as a XBlockInclude tuple, get the definition (OLX file) that it is pointing to.

Arguments:

parsed_include: An XBlockInclude tuple

parent_definition_key: The BundleDefinitionLocator for the XBlock whose OLX: contained the <xblock-include /> (i.e. the parent).

Returns: a BundleDefinitionLocator

openedx.core.djangoapps.xblock.runtime.olx_parsing.parse_xblock_include(include_node)#: Given an etree XML node that represents an <xblock-include /> element, parse it and return the BundleDefinitionLocator that it points to.

openedx.core.djangoapps.xblock.runtime.runtime module#

Common base classes for all new XBlock runtimes.

class openedx.core.djangoapps.xblock.runtime.runtime.XBlockRuntime(system: XBlockRuntimeSystem, user: UserType | None)#

Bases: RuntimeShim, Runtime

This class manages one or more instantiated XBlocks for a particular user, providing those XBlocks with the standard XBlock runtime API (and some Open edX-specific additions) so that it can interact with the platform, and the platform can interact with it.

The main reason we cannot make the runtime a long-lived singleton is that the XBlock runtime API requires ‘user_id’ to be a property of the runtime, not an argument passed in when loading particular blocks.

add_node_as_child(block, node, id_generator=None)#: Called by XBlock.parse_xml to treat a child node as a child block.

applicable_aside_types(block: XBlock)#: Disable XBlock asides in this runtime

block_field_datas: dict[ScopeIds, FieldData | None]#

django_field_data_caches: dict[LearningContextKey, FieldDataCache]#

get_event_handler(event_type: str) → Callable[[XBlock, dict], None] | None#

Return an appropriate function to handle the event.

Returns None if no special processing is required.

handle_completion_event(block: XBlock, event: dict)#: Submit a completion object for the block.

handle_grade_event(block: XBlock, event: dict)#: Submit a grade for the block.

handler_url(block, handler_name: str, suffix='', query='', thirdparty=False)#: Get the URL to a specific handler.

local_resource_url(block: XBlock, uri: str) → str#: Get the absolute URL to a resource file (like a CSS/JS file or an image) that is part of an XBlock’s python module.

log_event_to_tracking_log(block: XBlock, event_type: str, event_data: dict) → None#: Log this XBlock event to the tracking log

parse_xml_file(fileobj, id_generator=None)#: Parse an open XML file, returning a usage id.

publish(block: XBlock, event_type: str, event_data: dict)#: Handle XBlock events like grades and completion

render(block: XBlock, view_name: str, context: dict | None = None)#: Render a specific view of an XBlock.

resource_url(resource)#

Get the URL for a static resource file.

resource is the application local path to the resource.

The return value is a complete absolute URL that will locate the resource on your runtime.

service(block: XBlock, service_name: str)#: Return a service, or None. Services are objects implementing arbitrary other interfaces.

suppports_state_for_anonymous_users = True#

user: UserType | None#

view_name: str | None#

class openedx.core.djangoapps.xblock.runtime.runtime.XBlockRuntimeSystem(handler_url: Callable[[UsageKey, str, UserType | None], str], student_data_mode: StudentDataMode, runtime_class: type[XBlockRuntime])#

Bases: object

This class is essentially a factory for XBlockRuntimes. This is a long-lived object which provides the behavior specific to the application that wants to use XBlocks. Unlike XBlockRuntime, a single instance of this class can be used with many different XBlocks, whereas each XBlock gets its own instance of XBlockRuntime.

get_runtime(user: UserType | None) → XBlockRuntime#: Get the XBlock runtime for the specified Django user. The user can be a regular user, an AnonymousUser, or None.

get_service(block, service_name: str)#

Get a runtime service

Runtime services may come from this XBlockRuntimeSystem, or if this method returns None, they may come from the XBlockRuntime.

openedx.core.djangoapps.xblock.runtime.runtime.make_track_function()#: Make a tracking function that logs what happened, for XBlock events.

openedx.core.djangoapps.xblock.runtime.shims module#

Code to implement backwards compatibility

class openedx.core.djangoapps.xblock.runtime.shims.RuntimeShim(*args, **kwargs)#

Bases: object

All the old/deprecated APIs that our XBlock runtime(s) need to support are captured in this mixin.

property STATIC_URL#: Get the django STATIC_URL path. Deprecated in favor of the settings.STATIC_URL configuration.

property anonymous_student_id#: Get an anonymized identifier for this user.

property cache#

Access to a cache.

Seems only to be used by capa. Remove this if capa can be refactored.

property can_execute_unsafe_code#

Determine if capa problems in this context/course are allowed to run unsafe code. See xmodule/util/sandboxing.py

Seems only to be used by capa.

property course_id#: Old API to get the course ID.

property error_tracker#: Accessor for the course’s error tracker

export_fs = <object object>#

property filestore#: Alternate name for ‘resources_fs’.

get_field_provenance(xblock, field)#

A Studio-specific method that was implemented on DescriptorSystem. Used by the problem block.

For the given xblock, return a dict for the field’s current state: {

‘default_value’: what json’d value will take effect if field is unset: either the field default or inherited value, ‘explicitly_set’: boolean for whether the current value is set v default/inherited,

}

get_policy(_usage_id)#: A function that takes a usage id and returns a dict of policy to apply.

get_python_lib_zip()#

A function returning a bytestring or None. The bytestring is the contents of a zip file that should be importable by other Python code running in the module.

Only used for capa problems.

handle(block, handler_name, request, suffix='')#: Render a block by invoking its view.

process_xml(xml)#: Code to handle parsing of child XML for old blocks that use XmlMixin.

render(block, view_name, context=None)#: Render a block by invoking its view.

render_template(template_name, dictionary, namespace='main')#: Render a mako template

property resources_fs#: A filesystem that XBlocks can use to read large binary assets.

property seed#

A number to seed the random number generator. Used by capa and the randomize block.

Should be based on the user ID, per the existing implementation.

user_is_staff#: Is the current user a global staff user?

property user_location#: Old API to get the user’s country code (or None) Used by the Video XBlock to select a CDN for user.

xqueue#

An accessor for XQueue, the platform’s interface for external grader services.

Seems only to be used by capa. Remove this if capa can be refactored.

class openedx.core.djangoapps.xblock.runtime.shims.XBlockShim#

Bases: object

Mixin added to XBlock classes in this runtime, to support older/XModule APIs

always_recalculate_grades = False#

get_icon_class()#: Return a css class identifying this module in the context of an icon

property graded#: Not sure what this is or how it’s supposed to be set. Capa seems to expect a ‘graded’ attribute to be present on itself. Possibly through contentstore’s update_section_grader_type() ?

has_dynamic_children()#: Returns True if this XBlock has dynamic children for a given student when the module is created. This is deprecated and discouraged.

icon_class = 'other'#

property location#: Accessor for the usage ID

show_in_read_only_mode = False#

property system#: Accessor for the XModule runtime

openedx.core.djangoapps.xblock.runtime package

Contents

openedx.core.djangoapps.xblock.runtime package#

Submodules#

openedx.core.djangoapps.xblock.runtime.blockstore_field_data module#

openedx.core.djangoapps.xblock.runtime.blockstore_runtime module#

openedx.core.djangoapps.xblock.runtime.ephemeral_field_data module#

openedx.core.djangoapps.xblock.runtime.id_managers module#

openedx.core.djangoapps.xblock.runtime.mixin module#

openedx.core.djangoapps.xblock.runtime.olx_parsing module#

openedx.core.djangoapps.xblock.runtime.runtime module#

openedx.core.djangoapps.xblock.runtime.shims module#

Module contents#