API Reference

All functions documented on this page are exported by the zoti_yaml module.

Handlers

class Project(keys: List[str] = [], pathvar: List[str] = [], ext: List[str] = ['.yaml', '.yml'], argfields: List[str] = ['zoti-args'], **kwargs)

Handler for loading and containing a set of ZOTI-YAML modules. All modules are loaded relative to the roots specified by pathvar, in a similar fashion as UNIX path variables. The order of priority for resolving paths to module names is right-to-left.

Parameters:

• keys – list of keys to mark for storing positional metadata (see Syntax Reference)

• pathvar – list of root paths where modules will be searched (see Syntax Reference)

• ext – list of file extensions for searching module sources. Any file with another extension that specified here will be ignored.

• argfields – list of keys for fields used as placholders for, e.g., argument exchange. These fields will be deleted from the output result.

modules: Dict[str, Module]

dictionary of loaded modules indexed by their name

resolve_path(name) → Path

Return a global file path where the source file for module name is found. If none found returns FileNotFoundError.

load_module(name, source, path, with_deps: bool = True) → None

Recursively loads a (top) module with an arbitrary name, along with all its include dependencies declared in the modules’ preamblies. source and path are passed to Module. If with_deps is unset it ignores the include directives.

build(name: str) → None

Parses and resolves module name.

class Module(preamble={}, doc={})

A ZOTI-YAML module wraps a document with metadata and a bunch of utilities used for convenient data access and manipulation.

The basic constructor requires the (possibly pre-stored) preamble and doc trees (see to_dump()).

name: str

path: Path

preamble: Dict

doc: Dict

classmethod from_zoml(stream, filepath: str, key_nodes: List = [])

Module constructor which incoprorates both file loader and parser.

Parameters:

• stream – input stream (e.g., file or stdin)

• filepath – mandatory identifier for source of input. Used in debug and error handling.

• tool – optional identifier for tool downstream. Used in logging.

• key_nodes – nodes whose children will be marked with positional info.

map_doc(f, with_path=False, **kwargs)

Functor on a Module document. Maps function f(n) on each node n in the document tree. If with_path is set to True, it expects function to be of form f(n, path) where path is this node’s path relative to the document root (see TreePath).’

get(ref_path: Union[TreePath, PurePosixPath, str], strict=True)

Returns an arbitrary node in the document tree vased on its path relative to the document root (see TreePath). The path is formed like:

/key1/key2[index2]/key3[index3]/....

where keyN is the dictionary key of that node, respectively indexN can be either the index postion of the node in a list, or the node in a list which has a field name: indexN.

The strict argument controls whether this method throws an exception or returns None if the path is not found.

OBS: it is the designer’s responsibility to ensure that no two nodes in a list share the same name value.

to_dump()

Returns the preamble and doc as a list suitable for storing.

Document Tree Paths

class TreePath(path: Union[str, PurePosixPath] = '')

Simple structure used to reference subtrees/nodes using a sytax similar to:

{/path/to/node}

The {path/to/node} part is stored as a PurePosixPath, thus it can also be a relative path.

path: PurePosixPath

is_relative()

Root paths always start with /. If not, then it is relative.

relative_to(root: TreePath) → TreePath

Returns the path obtained by concatenating this one to a root.

resolve(root) → None

Resolves this path (see relative-to()) and marks it as resolved

with_key(key)

appends a key at the end of this path (see Module).

with_name(name)

appends a name or an index at te end of this path (see Module).

Position Helpers

INFO

alias of _info

POS

alias of _pos

class Pos(line, column, ibegin=0, iend=-1, path=None, who=None)

Container for positional information in a YAML file. Depends on the info from a PyYAML loader.

line: int

line number

column: int

column number

ibegin: int

start index in the text file

iend: int

end index in the text file

path: str

location of the source file

who: Optional[str]

string for bookkeeping the processing pipeline for this node

classmethod from_mark(start_mark: Mark, end_mark: Mark, path: str = '<stdio>', who: Optional[str] = None)

dump() → List

Dump content to a JSON list of arguments that can be used to recreate it.

show() → str

Pretty print content. Checks logging.root.level.

class PosStack(stack)

A stack containing the history of attached positional informations.

show()

attach_pos(node: Dict, pos: Pos, to_head=False) → None

Helper function to attach position information to an JSON object

get_pos(node: Dict) → Optional[PosStack]

Helper function to retrieve position information from a JSON node, if any.

Exceptions

exception ModuleError(what, module=None, path=None)

Raised when some specific module metadata is missing or other reasons why a module cannot be loaded,

exception SearchError(what, path=None, obj=None)

Raised when a search based on a zoti_yaml.core.TreePath fails.

exception MarkedError(what, pos=None)

Generic error enhanced with positional information.