API reference

Configuration management:

Configurable(**conf)	An object that can be constructed from JSON-object-like structures.
Namespace	An dict that supports accessing items as attributes
Scope	A dict context that makes its entries available to resolve when active.
create(spec)	Instantiate a configurable object from a specification.
describe(obj)	Generate the specification for a configurable object.
identify(obj)	Search the scope stack and module path for an object’s name.
resolve(sym)	Search the scope stack and module path for an object.

Commands and records:

Command(**conf)	An operation that creates a Record.
Record(path)	A record of the execution of a Command.
require(cmd)	Ensure that a command has started and block until it is finished.

User interfaces:

cli()	Run a command-line interface derived from the current scope stack.
serve(rec_path[, port])	Start a server providing access to the records in a directory.

---

class Configurable(**conf)

An object that can be constructed from JSON-object-like structures.

A JSON-object-like structure is a string-keyed dict composed of arbitrarily nested bool, int, float, str, NoneType, list, and string-keyed dict instances.

An object’s configuration should be passed to its constructor as a set of keyword arguments.

class Conf

Override this to specify a configuration schema.

Members of Conf are interpreted in the following way:

• The member’s name corresponds to the expected property’s name.
• A type value specify the property’s expected type.
• A single-element list value specifies the property’s default value.
• A str value specifies the property’s docstring.
• A dict value specifies raw JSON-Schema constraints.
• A tuple value may specify any combination of the above.

Examples:

class Person(cg.Configurable):
    class Conf:
        name = str, 'a long-winded pointer'
        age = int, [0], 'solar rotation count'
        shoe_size = 'European standard as of 2018-08-17'

spec

Return the object’s specification.

A specification is a dict with

• a “type” field; the innermost Scope symbol corresponding to the object’s type, or “{module_name}|{type_name}”, if none exist.
• other fields corresponding to the object’s configuration properties.

(This is equivalent to cg.describe(self).)

conf_schema = {'properties': {}, 'type': 'object'}

spec_schema = {'$ref': '#/definitions/cmdgraph|Configurable'}

class Namespace

An dict that supports accessing items as attributes

class Scope

A dict context that makes its entries available to resolve when active.

If multiple scopes are active, the innermost scope (the one entered most recently) takes precedence.

create(spec)

Instantiate a configurable object from a specification.

A specification is a dict with

• a “type” field; the innermost Scope symbol corresponding to the object’s type, or “{module_name}|{type_name}”, if none exist.
• other fields corresponding to the object’s configuration properties.

describe(obj)

Generate the specification for a configurable object.

A specification is a dict with

• a “type” field; the innermost Scope symbol corresponding to the object’s type, or “{module_name}|{type_name}”, if none exist.
• other fields corresponding to the object’s configuration properties.

identify(obj)

Search the scope stack and module path for an object’s name.

resolve(sym)

Search the scope stack and module path for an object.

class Record(path)

A record of the execution of a Command.

A Record is an array-friendly view of a directory. It also supports reading command metadata (stored in “_cmd-spec.yaml” and “_cmd-status.yaml”).

TODO: Document this more.

append(key, val)

cmd_status

cmd_spec

keys()

values()

items()

flat_keys()

flat_values()

flat_items()

class Command(**conf)

An operation that creates a Record.

To specify the output path, define an output_path property or define output_path as a class-level format string to be resolved with the command configuration.

Override run to do something useful.

run()

Override this, writing the output of the command to cmd.output.

status

“running”, “done”, “stopped”, or “unbegun”.

conf_schema = {'properties': {}, 'type': 'object'}

spec_schema = {'$ref': '#/definitions/cmdgraph|Command'}

require(cmd)

Ensure that a command has started and block until it is finished.

cli()

Run a command-line interface derived from the current scope stack.

serve(rec_path, port=3000)

Start a server providing access to the records in a directory.