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 nestedbool
,int
,float
,str
,NoneType
,list
, and string-keyeddict
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)
.)- a “type” field; the innermost
-
conf_schema
= {'properties': {}, 'type': 'object'}¶
-
spec_schema
= {'$ref': '#/definitions/cmdgraph|Configurable'}¶
-
class
-
class
Scope
[source]¶ A
dict
context that makes its entries available toresolve
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.
- a “type” field; the innermost
-
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.
- a “type” field; the innermost
-
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.
-
cmd_status
¶
-
cmd_spec
¶
-
-
class
Command
(**conf)[source]¶ An operation that creates a
Record
.To specify the output path, define an
output_path
property or defineoutput_path
as a class-level format string to be resolved with the command configuration.Override
run
to do something useful.-
status
¶ “running”, “done”, “stopped”, or “unbegun”.
-
conf_schema
= {'properties': {}, 'type': 'object'}¶
-
spec_schema
= {'$ref': '#/definitions/cmdgraph|Command'}¶
-