Reference¶
The User Guide is aimed at software developers that want to use OnToCode in their projects.
If you are unfamiliar with OnToCode, we recommend you to go through the Quick Guide to get a rough overview of how it works, before you continue reading.
OnToCode uses Owlready2 to load and work with ontologies as well as to query them. Classes of this library are part of OnToCode’s API, so you might need to consult its documentation as well.
The following sections document the behavior of OnToCode’s classes and their interactions. The classes are described in an order that minimizes forward references.
Ontology Locators¶
Ontology locators tell OnToCode where to find ontologies. OnToCode uses Owlready2 to load ontologies and therefore supports loading OWL 2.0 ontologies in the following formats:
- NTriples
- OWL/XML
- RDF/XML
Ontologies can be loaded from the file system (see
FileSystemOntologyLocator
) or via URL (see
URLOntologyLocator
).
An ontology locator is created by calling the constructor of a ontology locator class.
Ontologies are loaded by instantiations for the ontology
locators passed to their constructors. Each
instantiation loads ontologies into its own
owlready2.namespace.World
object.
Queries¶
OnToCode’s queries specify SPARQL-queries that are run by instantiations against loaded ontologies. A query returns a list of dictionaries with variable names as keys and Owlready2 objects as values.
Result Processors¶
Result processors convert the output of queries, a list of dictionaries with variable names as keys and Owlready2 objects as values, into the form expected by templates.
A template instantiation is given a list of result processors, a result processor chain. The first element of that chain is applied to the result of the template instantiation´s query result and subsequent elements of the chain are then applied to the output of their predecessor.
A result processor is a callable with two parameters, input_
and
world
. input_
is the query result or the output of their predecessor,
while world
is the owlready2.namespace.World
object that the query
was run against.
It is the responsibility of the user, that a result processor chain is setup, so that the output of a result processor meets the expectations of its successor or, for the final result processor, of the template for its input value.
Built-In Result Processors¶
This module provides three result processors for commonly required transformation tasks and a base class for result processors of a commonly encountered transformation scheme.
-
class
ontocode.result_processor.
AbstractMapElementsProcessor
[source]¶ AbstractMapElementsProcessor is an abstract base class for result processors that expect a list of dictionaries as their
input_
parameter and, when called, apply a function,process_value()
, to every value of those dictionaries.-
__call__
(input_, world)[source]¶ Apply
process_value()
to every value of dictionaries ininput_
.Parameters: input (list) – a list of dictionaries Returns: input_
withprocess_value()
applied to every valueReturn type: a list of dictionaries
-
-
class
ontocode.result_processor.
ObjectNameProcessor
[source]¶ Bases:
ontocode.result_processor.AbstractMapElementsProcessor
Replaces Owlready2 objects with their names.
-
class
ontocode.result_processor.
NoNameError
[source]¶ Bases:
ValueError
Raised when ObjectNameProcessor encounters an object without name.
-
class
ontocode.result_processor.
ObjectLabelProcessor
[source]¶ Bases:
ontocode.result_processor.AbstractMapElementsProcessor
Replaces Owlready2 objects with their English (‘en’) labels.
Template Inputs¶
Template inputs aggregate queries and
result processors. A template input object produces
input for a template instantiation by executing its
Query
and passing it through its chain of
result processors.
-
class
ontocode.template_input.
TemplateInput
(query, result_processors)[source]¶ Constitutes a template input consisting of a
ontocode.query.Query
and corresponding result processors.Parameters: - query (ontocode.query.Query) – a query
- result_processors (list) – a list of result processors
Templates¶
Instances of ontocode.template.Template
´s subclasses represent
templates that are instantiated by the arguments provided by
template inputs.
-
class
ontocode.template.
Template
[source]¶ Abstract base class for templates.
-
render
(*args, **kwargs)[source]¶ Render the template.
Parameters: - *args –
*args
as passed to anInstantiation
´sexecute()
method - **kwargs – combination of
**kwargs
as passed to anInstantiation
´sexecute()
method and the arguments generated by the template inputs of thatInstantiation
. For more information consulte the section on Instantiations.
- *args –
-
Jinja2 Template¶
OnToCode optionally provides one implementation of
ontocode.template.Template
:
ontocode.jinja2_template.Jinja2Template
. This class provides
interoperability with the Jinja2 template library.
Note that ontocode.jinja2_template.Jinja2Template
is only available,
when the jinja2
package is on the python path.
-
class
ontocode.jinja2_template.
Jinja2Template
(template)[source]¶ Bases:
ontocode.template.Template
Template class for Jinja2 templates.
-
classmethod
from_environment
(environment, name)[source]¶ Creates a Jinja2Template object with the underlying Jinja2 template created from a named template in a
jinja2.Environment
.Parameters: - environment (jinja2.Environment) – a Jinja2 environment
- name (str) – a string designating a template in
environment
Return type:
-
classmethod
from_file
(path)[source]¶ Creates a Jinja2Template object with the underlying Jinja2 template created from the constants of a file.
Parameters: path (str) – path to a file containing a Jinja2 template Return type: Jinja2Template
-
classmethod
from_string
(string)[source]¶ Creates a Jinja2Template object with the underlying Jinja2 template created from a string.
Parameters: string (str) – Jinja2 template as string Return type: Jinja2Template
-
classmethod
Instantiations¶
Instantiations tie everything together. An
Instantiation
aggregates a list of
ontology locators, a template, and
list, as well as optionally a single instance, of
template inputs.
Calling one of their execution methods will cause it to load the ontologies specified by the ontology locators, let the template inputs generate arguments for the template and pass the results to its template.
A Instantiation
object can instantiate its
template multiple times for a single execution. This is
controlled by the second template input argument to
Instantiation
´s constructor:
per_row_input
.
Template inputs passed as arguments to
per_row_input
are expected to return a list of dictionaries, while all
template inputs in lists passed as arguments to
at_once_inputs
are expected to return dictionaries. The number of elements
in the list generated by the per_row_input
argument determines the number
of template instantiations.
When execute()
is called (directly
or via execute_and_write_to_file()
)
with arguments *args
and **kwargs
, the
template inputs passed to at_once_inputs
are called
to generate a set of dictionaries and, if not None
, the argument passed to
per_row_input
is called to generate a list of dictionaries.
Now two cases have to be distinguished: per_row_input
is None
or
generated an empty list and per_row_input
generated a non-empty list.
In the former case, the template is instantiated once.
*arg
is passed right through from
execute()
. The argument to
**kwargs
is a merge of **kwargs
as passed to
execute()
with the dictionaries
generated by the argument to at_once_inputs
, where
execute()
´s **kwargs
take
precedence over the generated dictionaries and the precedence order within
the dictionaries is determined by their order as part of the list passed to
at_once_inputs
.
In the latter case, the template is instantiated once for
each dictionary generated by the argument to per_row_input
. The arguments
to the template are constructed similarly to the previous
case. The only difference is, that for each invocation a different dictionary
of those generated by the argument to per_row_input
is merged with the
other dictionaries to produce the **kwargs
argument. In the precedence
order, it is located between the **kwargs
as passed to
execute()
and the dictionaries
generated by the argument to at_once_inputs
.
-
class
ontocode.instantiation.
Instantiation
(ontology_locators, template, at_once_inputs, per_row_input=None)[source]¶ Instantiation of a template based on data queried from ontologies.
Parameters: - ontology_locators (list) – a list of ontology locators
- template (ontocode.template.Template) – a template
- at_once_inputs (list) – a list of
TemplateInput
s - per_row_input (ontocode.template_input.TemplateInput) – a template input
-
execute
(*args, **kwargs)[source]¶ Executes the instantiation and returns a list of the results.
The Instantiations module documentation describes the instantiation process.
-
execute_and_write_to_file
(path, *args, **kwargs)[source]¶ Executes the instantiation and writes result to file.
Raises an
ontocode.instantiation.TemplateInputArgumentError
, if a non-null value forper_row_input
was passed into the constructor of thisInstantiation
instance.The Instantiations module documentation describes the instantiation process.
Parameters: path (str) – path to target file
-
execute_and_write_to_files
(path_function, *args, **kwargs)[source]¶ Executes the instantiation and writes result to files.
The Instantiations module documentation describes the instantiation process.
Parameters: path_function (generator) – a function that takes the same arguments as the instances template and returns a path for the corresponding template invocation
-
exception
ontocode.instantiation.
TemplateInputArgumentError
[source]¶ Raised when
execute_and_write_to_file()
is called on anInstantiation
´s instance that was created with a non-nullper_row_input
argument.