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 anXBlock
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.
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 defaultname – 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 anXBlock
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 overridingservice()
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 callingXBlock.load_class()
to resolve a block_type. This is the same select as used byPlugin.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.
- 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.
- 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