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.

class xblock.runtime.IdGenerator

An abstract object that creates usage and definition ids

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)

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.

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.

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 definition id of the XBlockAside. Returns:The definition_id of the xblock 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.

class xblock.runtime.KeyValueStore

The abstract interface for Key Value Stores.

class Key

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.

KeyValueStore.default(key)

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

KeyValueStore.delete(key)

Deletes key from storage.

KeyValueStore.get(key)

Reads the value of the given key from storage.

KeyValueStore.has(key)

Returns whether or not key is present in storage.

KeyValueStore.set(key, value)

Sets key equal to value in storage.

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

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.

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 (dictionary) – 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.

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 all of the asides which might be decorating this block.

Parameters:block (XBlock) – The block to render retrieve asides for.

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

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 (html) – The result from rendering the block

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.

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.

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().

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, 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 (an XBlock) – this block’s class will be examined for service decorators.
• service_name (string) – the name of the service requested.

Returns:

An object implementing the requested service, or None.

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