xotl.ql.interfaces – The core interfaces

Interfaces that describe the major types used in the Query Language API, and some internal interfaces as well.

Notice that we only aim for documentation of the types and not implementation.

We also explicitly divide the type of the objects from the type of object constructors. Given that types in Python are callable the type of object constructors can be provided via the __init__ method.

interface xotl.ql.interfaces.QueryObject

The required API-level interface for query objects.

Query objects provide access to the QST for the query.


The Query Syntax Tree


A MappingView for the locals in the query scope. See get_name()


A MappingView for the globals in the query scope. See get_name()

get_name(name, only_globals=False)

Give the value for the name.

Queries are defined in a scope where they could access any name (e.g. variables). The translator may need to access the value of such names.

Get name will prefer locals over globals unless only_globals is True.

interface xotl.ql.interfaces.QueryObjectType

A QueryObject factory.


Either a FrameType object or the fully qualified name of such an object. This object is used

__call__(qst, frame)

Return an instance of a QueryObject.


Different implementations of the QueryObject may required or support additional keyword arguments. For instance, the type of a PartionableQueryObject may allow for a partition argument.

interface xotl.ql.interfaces.Frame

A object that represents a Python stack frame.

This is an unavoidable requirement consequence of the query expression being a generator object that may access names which are not known to the translator.

The attributes f_locals and f_globals are required to be mappings (usually immutable) or mapping views that give access to the values of locals and globals of a stack frame.


A mapping of the locals of this frame. Though not required this could be a mapping view provided it has the mapping interface.


A mapping of the globals of this frame. Though not required this could be a mapping view provided it has the mapping interface.

interface xotl.ql.interfaces.FrameType

A Frame factory.

__call__(locals, globals)

Return a instance of a Frame object.

  • locals – A mapping that provide access to locals.
  • globals – A mapping that provide access to globals.
interface xotl.ql.interfaces.QueryTranslator

A query translator.


Since Python classes are callable, you may implement a translator/execution plan in a single class:

>>> class ExecutionPlan(object):
...     def __init__(self, query, **kwargs):
...         pass
...     def __call__(self, **options):
...         pass
...     def __iter__(self):
...         return self()

However this may hurt some extensions. For instance, below we describe a couple of possible extensions for translators and plans which are not easily implemented in a single unit of code.


Return an execution plan for the given query.

Parameters:query – The query to be translated. Translators must allow this object to be either a query expression or a query object that complies with the interface QueryObject.

Translators are allowed to provide other keyword-only arguments. Translators’ authors are encouraged to properly document those arguments.

Returns:The query execution plan.
Return type:QueryExecutionPlan
interface xotl.ql.interfaces.QueryExecutionPlan

Required API-level interface for a query execution plan.


The original query object this plan was built from. Even if the translator was given a query expression directly, like in most of our examples, this must be a query object.


Execution plans are callable.

Return an iterator. The returned iterator must produce the objects retrieved from the query. Though the plan itself is reusable and can be called several times, the iterator obtained from this method will be exhausted.

Translators are required to properly document the optional keyword arguments. Positional arguments are not allowed. All arguments must be optional.


Execution plans are iterable.

This is exactly the same as calling the plan without any arguments: plan().

interface xotl.ql.interfaces.QueryTranslatorExplainExtension

Extends: xotl.ql.interfaces.QueryTranslator

This interface documents optional-methods for query translators that are deemed required to provide interactive access to the translator.


Prints information about how the query might be translated/executed.

The signature should allow the same arguments as the __call__ method of translators.

interface xotl.ql.interfaces.QueryExecutionPlanExplainExtension

Extends: xotl.ql.interfaces.QueryExecutionPlan


Prints information about this plan of execution.

The details of the information are specific to the kind of plan.