Runtime API

Runtime API#

Machinery to make the common case easy when building new runtimes

xblock.runtime.DbModel#: alias of KvsFieldData

class xblock.runtime.DictKeyValueStore(storage=None)#

A KeyValueStore that stores everything into a Python dictionary.

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.

set_many(update_dict)#

For each (key, value) in update_dict, set key to value in storage.

The default implementation brute force updates field by field through set which may be inefficient for any runtimes doing persistence operations on each set. Such implementations will want to override this method.

Update_dict:: field_name, field_value pairs for all cached changes

class xblock.runtime.IdGenerator#

An abstract object that creates usage and definition ids

abstract create_aside(definition_id, usage_id, aside_type)#

Make a new aside definition and usage ids, indicating an XBlockAside of type aside_type commenting on an XBlock usage usage_id

Returns:: (aside_definition_id, aside_usage_id)

abstract create_definition(block_type, slug=None)#

Make a definition, storing its block type.

If slug is provided, it is a suggestion that the definition id incorporate the slug somehow.

Returns the newly-created definition id.

abstract create_usage(def_id)#

Make a usage, storing its definition id.

Returns the newly-created usage id.

class xblock.runtime.IdReader#

An abstract object that stores usages and definitions.

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

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

abstract 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

abstract 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

abstract get_definition_id_from_aside(aside_id)#

Retrieve the XBlock definition_id associated with this aside definition id.

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

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

class xblock.runtime.KeyValueStore#

The abstract interface for Key Value Stores.

class Key(scope, user_id, block_scope_id, field_name, block_family='xblock.v1')#

Keys are structured to retain information about the scope of the data. Stores can use this information however they like to store and retrieve data.

Create new instance of Key(scope, user_id, block_scope_id, field_name, block_family)

default(key)#: Returns the context relevant default of the given key or raise KeyError which will result in the field’s global default.

abstract delete(key)#: Deletes key from storage.

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

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

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

set_many(update_dict)#

For each (key, value) in update_dict, set key to value in storage.

Update_dict:: field_name, field_value pairs for all cached changes

class xblock.runtime.KvsFieldData(kvs, **kwargs)#

An interface mapping value access that uses field names to one that uses the correct scoped keys for the underlying KeyValueStore

default(block, name)#

Ask the kvs for the default (default implementation which other classes may override).

Parameters:

block (XBlock) – block containing field to default
name – name of the field to default

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

get(block, name)#

Retrieve the value for the field named name.

If a value is provided for default, then it will be returned if no value is set

has(block, name)#: Return whether or not the field named name has a non-default value

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

set_many(block, update_dict)#: Update the underlying model with the correct values.

class xblock.runtime.MemoryIdManager#

A simple dict-based implementation of IdReader and IdGenerator.

ASIDE_DEFINITION_ID#: alias of MemoryAsideDefinitionId

ASIDE_USAGE_ID#: alias of MemoryAsideUsageId

clear()#: Remove all entries.

create_aside(definition_id, usage_id, aside_type)#: Create the aside.

create_definition(block_type, slug=None)#: Make a definition, storing its block type.

create_usage(def_id)#: Make a usage, storing its definition id.

get_aside_type_from_definition(aside_id)#: Get an aside’s type from its definition id.

get_aside_type_from_usage(aside_id)#: Get an aside’s type from its usage id.

get_block_type(def_id)#: Get a block_type by its definition id.

get_definition_id(usage_id)#: Get a definition_id by its usage id.

get_definition_id_from_aside(aside_id)#: Extract the original xblock’s definition_id from an aside’s definition_id.

get_usage_id_from_aside(aside_id)#: Extract the usage_id from the aside’s usage_id.

class xblock.runtime.Mixologist(mixins)#

Provides a facility to dynamically generate classes with additional mixins.

Parameters:: mixins (iterable of class) – Classes to mixin or names of classes to mixin.

mix(cls)#

Returns a subclass of cls mixed with self.mixins.

Parameters:: cls (class) – The base class to mix into

class xblock.runtime.NullI18nService#

A simple implementation of the runtime “i18n” service.

strftime(dtime, format)#: Locale-aware strftime, with format short-cuts.

property ugettext#

Dispatch to the appropriate gettext method to handle text objects.

Note that under python 3, this uses gettext(), while under python 2, it uses ugettext(). This should not be used with bytestrings.

property ungettext#

Dispatch to the appropriate ngettext method to handle text objects.

Note that under python 3, this uses ngettext(), while under python 2, it uses ungettext(). This should not be used with bytestrings.

class xblock.runtime.ObjectAggregator(*objects)#

Provides a single object interface that combines many smaller objects.

Attribute access on the aggregate object acts on the first sub-object that has that attribute.

class xblock.runtime.RegexLexer(*toks)#

Split text into lexical tokens based on regexes.

lex(text)#: Iterator that tokenizes text and yields up tokens as they are found

class xblock.runtime.Runtime(id_reader, field_data=None, mixins=(), services=None, default_class=None, select=None, id_generator=None)#

Access to the runtime environment for XBlocks.

Parameters:

id_reader (IdReader) – An object that allows the Runtime to map between usage_ids, definition_ids, and block_types.
id_generator (IdGenerator) – The IdGenerator to use for creating ids when importing XML or loading XBlockAsides.
field_data (FieldData) – The FieldData to use by default when constructing an XBlock from this Runtime.
mixins (tuple) – Classes that should be mixed in with every XBlock created by this Runtime.
services (dict) – Services to make available through the service() method. There’s no point passing anything here if you are overriding service() in your sub-class.
default_class (class) – The default class to use if a class can’t be found for a particular block_type when loading an XBlock.
select – A function to select from one or more XBlock subtypes found when calling XBlock.load_class() to resolve a block_type. This is the same select as used by Plugin.load_class().

add_block_as_child_node(block, node)#: Export block as a child node of node.

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)#: Return the set of applicable aside types for this runtime and block. This method allows the runtime to filter the set of asides it wants to support or to provide even block-level or block_type level filtering. We may extend this in the future to also take the user or user roles.

construct_xblock(block_type, scope_ids, field_data=None, *args, **kwargs)#: Construct a new xblock of the type identified by block_type, passing *args and **kwargs into __init__.

construct_xblock_from_class(cls, scope_ids, field_data=None, *args, **kwargs)#: Construct a new xblock of type cls, mixing in the mixins defined for this application.

create_aside(block_type, keys)#: The aside version of construct_xblock: take a type and key. Return an instance

export_to_xml(block, xmlfile)#: Export the block to XML, writing the XML to xmlfile.

property field_data#

Access the FieldData passed in the constructor.

Deprecated in favor of a ‘field-data’ service.

get_aside(aside_usage_id)#

Create an XBlockAside in this runtime.

The aside_usage_id is used to find the Aside class and data.

get_aside_of_type(block, aside_type)#

Return the aside of the given aside_type which might be decorating this block.

Parameters:

block (XBlock) – The block to retrieve asides for.
aside_type (str) – the type of the aside

get_asides(block)#

Return instances for all of the asides that will decorate this block.

Parameters:: block (XBlock) – The block to render retrieve asides for.
Returns:: List of XBlockAside instances

get_block(usage_id, for_parent=None)#

Create an XBlock instance in this runtime.

The usage_id is used to find the XBlock class and data.

handle(block, handler_name, request, suffix='')#

Handles any calls to the specified handler_name.

Provides a fallback handler if the specified handler isn’t found.

Parameters:

handler_name – The name of the handler to call
request (webob.Request) – The request to handle
suffix – The remainder of the url, after the handler url prefix, if available

abstract handler_url(block, handler_name, suffix='', query='', thirdparty=False)#

Get the actual URL to invoke a handler.

handler_name is the name of your handler function. Any additional portion of the url will be passed as the suffix argument to the handler.

The return value is a complete absolute URL that will route through the runtime to your handler.

Parameters:

block – The block to generate the url for
handler_name – The handler on that block that the url should resolve to
suffix – Any path suffix that should be added to the handler url
query – Any query string that should be added to the handler url (which should not include an initial ? or &)
thirdparty – If true, create a URL that can be used without the user being logged in. This is useful for URLs to be used by third-party services.

layout_asides(block, context, frag, view_name, aside_frag_fns)#

Execute and layout the aside_frags wrt the block’s frag. Runtimes should feel free to override this method to control execution, place, and style the asides appropriately for their application

This default method appends the aside_frags after frag. If you override this, you must call wrap_aside around each aside as per this function.

Parameters:

block (XBlock) – the block being rendered
frag (str) – The HTML result from rendering the block
aside_frag_fns (list((aside, aside_fn))) – The asides and closures for rendering to call

load_aside_type(aside_type)#: Returns a subclass of XBlockAside that corresponds to the specified aside_type.

load_block_type(block_type)#: Returns a subclass of XBlock that corresponds to the specified block_type.

abstract local_resource_url(block, uri)#

Get the URL to load a static resource from an XBlock.

block is the XBlock that owns the resource.

uri is a relative URI to the resource. The XBlock class’s: get_local_resource(uri) method should be able to open the resource identified by this uri.

Typically, this function uses open_local_resource defined on the XBlock class, which by default will only allow resources from the “public/” directory of the kit. Resources must be placed in “public/” to be successfully served with this URL.

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

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

parse_xml_string(xml, id_generator=None)#: Parse a string of XML, returning a usage id.

abstract publish(block, event_type, event_data)#

Publish an event.

For example, to participate in the course grade, an XBlock should set has_score to True, and should publish a grade event whenever the grade changes.

In this case the event_type would be grade, and the event_data would be a dictionary of the following form:

{
    'value': <number>,
    'max_value': <number>,
}

The grade event represents a grade of value/max_value for the current user.

block is the XBlock from which the event originates.

query(block)#

Query for data in the tree, starting from block.

Returns a Query object with methods for navigating the tree and retrieving information.

querypath(block, path)#: An XPath-like interface to query.

render(block, view_name, context=None)#

Render a block by invoking its view.

Finds the view named view_name on block. The default view will be used if a specific view hasn’t be registered. If there is no default view, an exception will be raised.

The view is invoked, passing it context. The value returned by the view is returned, with possible modifications by the runtime to integrate it into a larger whole.

render_asides(block, view_name, frag, context)#: Collect all of the asides’ add ons and format them into the frag. The frag already has the given block’s rendering.

render_child(child, view_name=None, context=None)#

A shortcut to render a child block.

Use this method to render your children from your own view function.

If view_name is not provided, it will default to the view name you’re being rendered with.

Returns the same value as render().

render_children(block, view_name=None, context=None)#

Render a block’s children, returning a list of results.

Each child of block will be rendered, just as render_child() does.

Returns a list of values, each as provided by render().

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

save_block(block)#

Finalize/commit changes for the field data from the specified block. Called at the end of an XBlock’s save() method. Runtimes may ignore this as generally the field data implementation is responsible for persisting changes.

(The main use case here is a runtime and field data implementation that want to store field data in XML format - the only way to correctly serialize a block to XML is to ask the block to serialize itself all at once, so such implementations cannot persist changes on a field-by-field basis.)

Parameters:: block (XBlock) – the block being saved

service(block, service_name)#

Return a service, or None.

Services are objects implementing arbitrary other interfaces. They are requested by agreed-upon names, see [XXX TODO] for a list of possible services. The object returned depends on the service requested.

XBlocks must announce their intention to request services with the XBlock.needs or XBlock.wants decorators. Use needs if you assume that the service is available, or wants if your code is flexible and can accept a None from this method.

Runtimes can override this method if they have different techniques for finding and delivering services.

Parameters:

block (XBlock) – this block’s class will be examined for service decorators.
service_name (str) – the name of the service requested.

Returns:

An object implementing the requested service, or None.

property user_id#

Access the current user ID.

Deprecated in favor of a ‘user’ service.

wrap_aside(block, aside, view, frag, context)#

Creates a div which identifies the aside, points to the original block, and writes out the json_init_args into a script tag.

The default implementation creates a frag to wraps frag w/ a div identifying the xblock. If you have javascript, you’ll need to override this impl

wrap_xblock(block, view, frag, context)#

Creates a div which identifies the xblock and writes out the json_init_args into a script tag.

If there’s a wrap_child method, it calls that with a deprecation warning.

The default implementation creates a frag to wraps frag w/ a div identifying the xblock. If you have javascript, you’ll need to override this impl

Runtime API

Contents

Runtime API#