openedx.core.djangoapps.xblock package

Subpackages

• openedx.core.djangoapps.xblock.learning_context package
  • Submodules
  • openedx.core.djangoapps.xblock.learning_context.learning_context module
    • LearningContext
      • LearningContext.can_edit_block()
      • LearningContext.can_view_block()
      • LearningContext.can_view_block_for_editing()
      • LearningContext.definition_for_usage()
  • openedx.core.djangoapps.xblock.learning_context.manager module
    • LearningContextPluginManager
      • LearningContextPluginManager.NAMESPACE
    • get_learning_context_impl()
  • Module contents
• openedx.core.djangoapps.xblock.rest_api package
  • Submodules
  • openedx.core.djangoapps.xblock.rest_api.serializers module
    • XBlockOlxSerializer
  • openedx.core.djangoapps.xblock.rest_api.url_converters module
    • UsageKeyV2Converter
      • UsageKeyV2Converter.regex
      • UsageKeyV2Converter.to_python()
      • UsageKeyV2Converter.to_url()
    • VersionConverter
      • VersionConverter.regex
      • VersionConverter.to_python()
      • VersionConverter.to_url()
  • openedx.core.djangoapps.xblock.rest_api.urls module
  • openedx.core.djangoapps.xblock.rest_api.views module
    • BlockFieldsView
      • BlockFieldsView.authentication_classes
      • BlockFieldsView.get()
      • BlockFieldsView.get_explicitly_set_fields_by_scope()
      • BlockFieldsView.permission_classes
      • BlockFieldsView.post()
    • block_metadata()
    • cors_allow_xblock_handler()
    • embed_block_view()
    • get_block_olx_view()
    • get_handler_url()
    • render_block_view()
    • xblock_handler()
  • Module contents
• openedx.core.djangoapps.xblock.runtime package
  • Submodules
  • openedx.core.djangoapps.xblock.runtime.ephemeral_field_data module
    • EphemeralKeyValueStore
      • EphemeralKeyValueStore.delete()
      • EphemeralKeyValueStore.get()
      • EphemeralKeyValueStore.has()
      • EphemeralKeyValueStore.set()
    • NotFound
  • openedx.core.djangoapps.xblock.runtime.id_managers module
    • OpaqueKeyReader
      • OpaqueKeyReader.get_aside_type_from_definition()
      • OpaqueKeyReader.get_aside_type_from_usage()
      • OpaqueKeyReader.get_block_type()
      • OpaqueKeyReader.get_definition_id()
      • OpaqueKeyReader.get_definition_id_from_aside()
      • OpaqueKeyReader.get_usage_id_from_aside()
  • openedx.core.djangoapps.xblock.runtime.mixin module
    • LmsBlockMixin
      • LmsBlockMixin.has_score
      • LmsBlockMixin.public_view()
      • LmsBlockMixin.publish_completion()
  • openedx.core.djangoapps.xblock.runtime.openedx_content_runtime module
    • OpenedXContentFieldData
      • OpenedXContentFieldData.delete()
      • OpenedXContentFieldData.get()
      • OpenedXContentFieldData.has_changes()
      • OpenedXContentFieldData.mark_unchanged()
      • OpenedXContentFieldData.set()
    • OpenedXContentRuntime
      • OpenedXContentRuntime.get_block()
      • OpenedXContentRuntime.get_block_assets()
      • OpenedXContentRuntime.get_component_version_from_block()
      • OpenedXContentRuntime.save_block()
  • openedx.core.djangoapps.xblock.runtime.runtime module
    • GetHandlerFunction
    • XBlockRuntime
      • XBlockRuntime.add_node_as_child()
      • XBlockRuntime.applicable_aside_types()
      • XBlockRuntime.authored_data_store
      • XBlockRuntime.block_field_datas
      • XBlockRuntime.django_field_data_caches
      • XBlockRuntime.get_event_handler()
      • XBlockRuntime.handle_completion_event()
      • XBlockRuntime.handle_grade_event()
      • XBlockRuntime.handler_url()
      • XBlockRuntime.local_resource_url()
      • XBlockRuntime.log_event_to_tracking_log()
      • XBlockRuntime.parse_xml_file()
      • XBlockRuntime.publish()
      • XBlockRuntime.render()
      • XBlockRuntime.resource_url()
      • XBlockRuntime.service()
      • XBlockRuntime.suppports_state_for_anonymous_users
      • XBlockRuntime.user
      • XBlockRuntime.view_name
    • make_track_function()
  • openedx.core.djangoapps.xblock.runtime.shims module
    • RuntimeShim
      • RuntimeShim.STATIC_URL
      • RuntimeShim.anonymous_student_id
      • RuntimeShim.cache
      • RuntimeShim.can_execute_unsafe_code
      • RuntimeShim.course_id
      • RuntimeShim.error_tracker
      • RuntimeShim.export_fs
      • RuntimeShim.filestore
      • RuntimeShim.get_field_provenance()
      • RuntimeShim.get_policy()
      • RuntimeShim.get_python_lib_zip()
      • RuntimeShim.handle()
      • RuntimeShim.process_xml()
      • RuntimeShim.render()
      • RuntimeShim.render_template()
      • RuntimeShim.resources_fs
      • RuntimeShim.seed
      • RuntimeShim.user_is_staff
      • RuntimeShim.user_location
      • RuntimeShim.xqueue
    • XBlockShim
      • XBlockShim.always_recalculate_grades
      • XBlockShim.get_icon_class()
      • XBlockShim.graded
      • XBlockShim.has_dynamic_children()
      • XBlockShim.icon_class
      • XBlockShim.location
      • XBlockShim.show_in_read_only_mode
      • XBlockShim.system
  • Module contents

Submodules

openedx.core.djangoapps.xblock.api module

Python API for interacting with edx-platform’s new XBlock Runtime.

For content in modulestore (currently all course content), you’ll need to use the older runtime.

Note that these views are only for interacting with existing blocks. Other Studio APIs cover use cases like adding/deleting/editing blocks.

openedx.core.djangoapps.xblock.api.get_block_display_name(block: XBlock) → str

Get the display name from an instatiated XBlock, falling back to the XBlock-type-defined-default.

openedx.core.djangoapps.xblock.api.get_block_draft_olx(usage_key: UsageKeyV2) → str

DEPRECATED. Use get_block_olx(). Can be removed post-Teak.

openedx.core.djangoapps.xblock.api.get_block_metadata(block, includes=())

Get metadata about the specified XBlock.

This metadata is the same for all users. Any data which varies per-user must be served from a different API.

Optionally provide a list or set of metadata keys to include. Valid keys are:

index_dictionary: a dictionary of data used to add this XBlock’s content

to a search index.

student_view_data: data needed to render the XBlock on mobile or in

custom frontends.

children: list of usage keys of the XBlock’s children editable_children: children in the same bundle, as opposed to linked

children in other bundles.

openedx.core.djangoapps.xblock.api.get_block_olx(usage_key: UsageKeyV2, *, version: int | LatestVersion = LatestVersion.AUTO) → str

Get the OLX source of the of the given openedx_content-backed XBlock and a version.

openedx.core.djangoapps.xblock.api.get_component_from_usage_key(usage_key: UsageKeyV2) → Component

Fetch the Component object for a given usage key.

Raises a ObjectDoesNotExist error if no such Component exists.

This is a lower-level function that will return a Component even if there is no current draft version of that Component (because it’s been soft-deleted).

openedx.core.djangoapps.xblock.api.get_handler_url(usage_key: UsageKeyV2, handler_name: str, user: User | None, *, version: int | LatestVersion = LatestVersion.AUTO)

A method for getting the URL to any XBlock handler. The URL must be usable without any authentication (no cookie, no OAuth/JWT), and may expire. (So that we can render the XBlock in a secure IFrame without any access to existing cookies.)

The returned URL will contain the provided handler_name, but is valid for any other handler on the same XBlock. Callers may replace any occurrences of the handler name in the resulting URL with the name of any other handler and the URL will still work. (This greatly reduces the number of calls to this API endpoint that are needed to interact with any given XBlock.)

Params:

usage_key - Usage Key (Opaque Key object or string) handler_name - Name of the handler or a dummy name like ‘any_handler’ user - Django User (registered or anonymous) version - Run the handler against a specific version of the

block (e.g. when viewing an old version of it in Studio). Some blocks use handlers to load their data so it’s important the handler matches the student_view etc.

This view does not check/care if the XBlock actually exists.

openedx.core.djangoapps.xblock.api.get_runtime(user: User | None) → OpenedXContentRuntime

Return a new XBlockRuntime.

Each XBlockRuntime is bound to one user (and usually one request or one celery task). It is typically used just to load and render a single block, but the API _does_ allow a single runtime instance to load multiple blocks (as long as they’re for the same user).

openedx.core.djangoapps.xblock.api.load_block(usage_key: UsageKeyV2, user: User | None, *, check_permission: CheckPerm | None = CheckPerm.CAN_LEARN, version: int | LatestVersion = LatestVersion.AUTO)

Load the specified XBlock for the given user.

Returns an instantiated XBlock.

Exceptions:

NotFound - if the XBlock doesn’t exist PermissionDenied - if the user doesn’t have the necessary permissions

Parameters:

• usage_key (OpaqueKey) – block identifier

• user (User) – user requesting the block

openedx.core.djangoapps.xblock.api.render_block_view(block, view_name, user)

Get the HTML, JS, and CSS needed to render the given XBlock view.

The only difference between this method and calling

load_block().render(view_name)

is that this method can fall back from ‘author_view’ to ‘student_view’

Returns a Fragment.

openedx.core.djangoapps.xblock.api.xblock_type_display_name(block_type)

Get the display name for the specified XBlock class.

openedx.core.djangoapps.xblock.apps module

Django app configuration for the XBlock Runtime django app

class openedx.core.djangoapps.xblock.apps.LmsXBlockAppConfig(app_name, app_module)

Bases: XBlockAppConfig

LMS-specific configuration of the XBlock Runtime django app.

get_runtime_params()

Get the OpenedXContentRuntime parameters appropriate for viewing and/or editing XBlock content in the LMS

get_site_root_url()

Get the absolute root URL to this site, e.g. ‘https://courses.example.com’ Should not have any trailing slash.

class openedx.core.djangoapps.xblock.apps.StudioXBlockAppConfig(app_name, app_module)

Bases: XBlockAppConfig

Studio-specific configuration of the XBlock Runtime django app.

get_learning_context_params()

Get additional kwargs that are passed to learning context implementations (LearningContext subclass constructors).

get_runtime_params()

Get the OpenedXContentRuntime parameters appropriate for viewing and/or editing XBlock content in Studio

get_site_root_url()

Get the absolute root URL to this site, e.g. ‘https://studio.example.com’ Should not have any trailing slash.

class openedx.core.djangoapps.xblock.apps.XBlockAppConfig(app_name, app_module)

Bases: AppConfig

Django app configuration for the new XBlock Runtime django app

get_learning_context_params()

Get additional kwargs that are passed to learning context implementations (LearningContext subclass constructors).

get_runtime_params()

Get the OpenedXContentRuntime parameters appropriate for viewing and/or editing XBlock content.

get_site_root_url()

Get the absolute root URL to this site, e.g. ‘https://courses.example.com’ Should not have any trailing slash.

label = 'xblock_new'

name = 'openedx.core.djangoapps.xblock'

verbose_name = 'New XBlock Runtime'

openedx.core.djangoapps.xblock.apps.get_xblock_app_config()

Get whichever of the above AppConfig subclasses is active.

openedx.core.djangoapps.xblock.data module

Data structures for the XBlock Django app’s python APIs

class openedx.core.djangoapps.xblock.data.AuthoredDataMode(*values)

Bases: Enum

Runtime configuration which determines whether published or draft versions of content is used by default.

DEFAULT_DRAFT = 'persisted'

STRICTLY_PUBLISHED = 'published'

class openedx.core.djangoapps.xblock.data.CheckPerm(*values)

Bases: Enum

Options for the default permission check done by load_block()

CAN_EDIT = 3

CAN_LEARN = 1

CAN_READ_AS_AUTHOR = 2

class openedx.core.djangoapps.xblock.data.LatestVersion(*values)

Bases: Enum

Options for specifying which version of an XBlock you want to load, if not specifying a specific version.

AUTO = 'auto'

DRAFT = 'draft'

PUBLISHED = 'published'

class openedx.core.djangoapps.xblock.data.StudentDataMode(*values)

Bases: Enum

Is student data (like which answer was selected) persisted in the DB or just stored temporarily in the session? Generally, the LMS uses persistence and Studio uses ephemeral data.

Ephemeral = 'ephemeral'

Persisted = 'persisted'

openedx.core.djangoapps.xblock.utils module

Useful helper methods related to the XBlock runtime

openedx.core.djangoapps.xblock.utils.get_auto_latest_version(version: int | LatestVersion) → int | LatestVersion

Gets the actual LatestVersion if is LatestVersion.AUTO; otherwise, returns the same value.

openedx.core.djangoapps.xblock.utils.get_secure_token_for_xblock_handler(user_id, block_key_str, time_idx=0)

Get a secure token (one-way hash) used to authenticate XBlock handler requests. This token replaces both the session ID cookie (or OAuth bearer token) and the CSRF token for such requests.

The token is specific to one user and one XBlock usage ID, though may be used for any handler. It expires and is only valid for 2-4 days (our current best guess at a reasonable trade off between “what if the user left their browser open overnight and tried to continue the next day” which should work vs. “for security, tokens should not last too long”)

We use this token because XBlocks may sometimes be sandboxed (run in a client-side JavaScript environment with no access to cookies) and because the XBlock python and JavaScript handler_url APIs do not provide any way of authenticating the handler requests, other than assuming cookies are present or including this sort of secure token in the handler URL.

For security, we need these tokens to have an expiration date. So: the hash incorporates the current time, rounded to the lowest TOKEN_PERIOD value. When checking this, you should check both time_idx=0 and time_idx=-1 in case we just recently moved from one time period to another (i.e. at the stroke of midnight UTC or similar). The effect of this is that each token is valid for 2-4 days.

(Alternatively, we could make each token expire after exactly X days, but that requires storing the expiration date of each token on the server side, making the implementation needlessly complex. The “time window” approach we are using here also has the advantage that throughout a typical day, the token each user gets for a given XBlock doesn’t change, which makes debugging and reasoning about the system simpler.)

openedx.core.djangoapps.xblock.utils.get_xblock_id_for_anonymous_user(user)

Get a unique string that identifies the current anonymous (not logged in) user. (This is different than the “anonymous user ID”, which is an anonymized identifier for a logged in user.)

Note that this ID is a string, not an int. It is guaranteed to be in a unique namespace that won’t collide with “normal” user IDs, even when they are converted to a string.

openedx.core.djangoapps.xblock.utils.validate_secure_token_for_xblock_handler(user_id, block_key_str, token)

Returns True if the specified handler authentication token is valid for the given Xblock ID and user ID. Otherwise returns false.

See get_secure_token_for_xblock_handler

Module contents

The new XBlock runtime and related code.