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)[source]

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[source]

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[source]

An dict that supports accessing items as attributes

class Scope[source]

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)[source]

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)[source]

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)[source]

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

resolve(sym)[source]

Search the scope stack and module path for an object.

class Record(path)[source]

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)[source]
cmd_status
cmd_spec
keys()[source]
values()[source]
items()[source]
flat_keys()[source]
flat_values()[source]
flat_items()[source]
class Command(**conf)[source]

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()[source]

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)[source]

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

cli()[source]

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

serve(rec_path, port=3000)[source]

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