API Reference

Unlike most other ZOTI tools the API of ZOTI-Gen is not particularly interesting, since it is meant to be used mainly as a CLI tool. More important, though, is its exported core representation used when creating Template Libraries, documented in its respective page.

The Project Handler

class zoti_gen.builder.Builder(main: str, srcs: List[zoti_yaml.handlers.Module], annotation=(None, None))

This handler takes care of loading input specifications, templates, building and dumping target code artifacts.

Parameters:

• main – the qualified name of the main module (containing a top entry in preamble which points to the project’s top block)

• srcs – a list of initialized zoti_yaml.Module containing all the raw input specifications. Used for their qualified name queries.

• annotations – formatted string for printing Block information (before, after) the template expansion. In the formatting, the variable comp represents the current Block object.

main: zoti_gen.core.Ref

Constructed path to the top (i.e., main) block

requs: zoti_gen.core.Requirement

Resolved dependencies. Available only after calling resolve().

decls: List

List of component declared at top level. Available only after calling resolve().

get(ref=None, caller=None) → zoti_gen.core.Block

Gets a Block object using its qualified name. If the the block has been parsed before it returns the previously-constructed block, otherwise it follows the decision flow:

it searches the specifications

if it refers to a library template

| it imports the base constructor using importlib

else

| uses Block base constructor

parses the specifications and constructs the block

parse()

Recursively parses a loaded project (i.e., containing input specifications) and creates the (hidden) internal representation starting from the main block inwards.

resolve()

Resolves names/bindings and renders code. OBS: alters the internal structure of each respective block entry.

The Core Representation

All core types are re-exported by zoti_gen and are meant to be used when defining template components.

class zoti_gen.core.Block(name: str, prototype: zoti_gen.core.Template =, requirement: typing.Optional[zoti_gen.core.Requirement] = None, label: collections.OrderedDict[str, zoti_gen.core.Label] = <factory>, param: typing.Dict = <factory>, code: typing.Optional[str] = None, instance: typing.List[zoti_gen.core.Instance] = <factory>, _info: typing.Dict = <factory>)

Base class for block structure.

name: str

Unique ID of block.

prototype: zoti_gen.core.Template

Target dependent function signature provided by the type system

requirement: Optional[zoti_gen.core.Requirement] = None

Block prerequisites.

label: collections.OrderedDict[str, zoti_gen.core.Label]

Ordered dictionary of labels

param: Dict

Generic parameters

code: Optional[str] = None

Target code for block, either as Jinja template or as raw text

instance: List[zoti_gen.core.Instance]

list of instances that bind template (code) placeholders to other blocks

class zoti_gen.core.Requirement(requirement, **kwargs)

Illustrates prerquisites. Stores input iterables (e.g., lists) as dependency graphs.

Parameters:

requirement – dictionary of iterables.

requirement: Dict[str, networkx.classes.digraph.DiGraph]

Dictionary of dependency graphs.

update(other: Optional[zoti_gen.core.Requirement])

merges two Requirement entries updating the dependency graphs.

dep_list(key) → List

Returns a list with the solved dependencies for a certain requirement type.

class zoti_gen.core.Label(name: str, usage: zoti_gen.core.Template, glue: typing.Dict, _info: typing.Dict = <factory>)

Carries information about labels (filled in by type system)

name: str

Unique name in the scope of a block

usage: zoti_gen.core.Template

Default usage template. Called on top-level (non-binding) instances.

glue: Dict

Dictionary of templates passed from the type system.

class zoti_gen.core.Instance(placeholder: typing.Optional[str], block: typing.Optional[typing.Dict], directive: typing.List[str], bind: typing.List[zoti_gen.core.Bind], usage: zoti_gen.core.Template, _info: typing.Dict = <factory>)

Entry binding a placeholder in the parent’s template code to another block.

placeholder: Optional[str]

ID for the template placeholder

block: Optional[Dict]

ID of the block referenced to fill the placeholder

bind: List[zoti_gen.core.Bind]

list of bindings between the parent block and referenced block

usage: zoti_gen.core.Template

Target-dependent template passed by type system

class zoti_gen.core.Bind(func: str, args: typing.Dict, _info: typing.Dict = <factory>)

Deserialized version of a binding, containing directily bind resolver arguments.

func: str

name of the binding function (see schema entries)

args: Dict

arguments passed to the binding function

class zoti_gen.core.Ref(module: str, name: str)

Hashable reference to a user block or a library component.

module: str

qualified name of module

name: str

name of block

class zoti_gen.core.Template(string, parent=None)

Container for a Jinja template.

string: str

formatted string template

Exceptions

exception zoti_gen.exceptions.ValidationError(what, obj=None, **kwargs)

Raised during the validation of the ZOTI schema.

exception zoti_gen.exceptions.ParseError(what, obj=None, **kwargs)

exception zoti_gen.exceptions.ModelError(what, name=None, obj=None, **kwargs)

exception zoti_gen.exceptions.TemplateError(template: str, context: Dict, err_line: int, err_string: str, msg: str = 'Jinja raised error when processing template', info=None, parent=None)

Wraps a Jinja template error into a friendlier message.