pyrocko.guts

Lightweight declarative YAML and XML data binding for Python.

Functions

clone(x[, pool])	Clone guts object tree.
dump(*args, **kwargs)	Serialize to YAML.
dump_xml(*args, **kwargs)	Serialize to XML.
get_elements(obj, ypath)	Get all elements matching a given ypath specification.
iter_elements(obj, ypath)	Generator yielding elements matching a given ypath specification.
set_elements(obj, ypath, value[, validate, ...])	Set elements matching a given ypath specification.
to_dict(obj)	Get dict of guts object attributes.

Classes

Any(**kwargs)	Placeholder for any object.
Bool(...)	Placeholder for bool.
Bytes(...)	Placeholder for bytes.
Choice(**kwargs)	Any out of a set of different types.
Complex(...)	Placeholder for complex.
DateTimestamp(...)	Placeholder for a UTC timestamp which (de)serializes as a date string.
DefaultMaker()	Base class for default value factories.
Dict(...)	Placeholder for dict.
Duration(...)	Placeholder for float time duration [s] with human-readable (de)serialization.
Float(...)	Placeholder for float.
Int(...)	Placeholder for int.
IntChoice(...)	Any int out of [].
List(...)	Placeholder for list.
Object(**kwargs)	Base class for Guts objects.
ObjectDefaultMaker(cls, args, kwargs)	Default value factory for Object derived classes.
SObject(**kwargs)	Base class for simple str-serializable Guts objects.
String(...)	Placeholder for str.
StringChoice(...)	Any str out of [].
StringPattern(...)	Any str matching pattern '.*'.
StringUnion(...)	Any str matching any of a set of constraints.
TBase([default, optional, xmlstyle, ...])	Base class for Guts type definitions.
Timestamp(...)	Placeholder for a UTC timestamp.
Tuple(...)	Placeholder for tuple.
Unicode(...)	Placeholder for str.
UnicodePattern(...)	Any str matching pattern '.*'.

Exceptions

ArgumentError	Raised when invalid arguments would be used in an object's initialization.
ValidationError	Raised when an object is invalid according to its definition.
YPathError	This exception is raised for invalid ypath specifications.

class TBase(default=None, optional=False, xmlstyle='element', xmltagname=None, xmlns=None, help=None, position=None)

Bases: object

Base class for Guts type definitions.

Parameters:

• default – Default value or DefaultMaker object (see Object.D()) to be used to generate a default.

• optional (bool) – If True, the attribute is optional and may be set to None.

• xmlstyle (str) – Controls how the attribute is serialized in XML. :Choices: 'element', 'attribute', 'content'. Only scalar and SObject values may be serialized as 'attribute'. Only one attribute in a class may be serialized as 'content'.

• xmltagname (str) – XML tag name to be used. By default, the attribute name converted to camel-case is used.

• xmlns (str) – XML namespace to be used for this attribute.

• help (rst formatted str) – Description of the attribute used in documentation and online help.

• position (int) – Position index to be used when the attribute should be output in non-default order.

exception ValidationError

Bases: ValueError

Raised when an object is invalid according to its definition.

exception ArgumentError

Bases: ValueError

Raised when invalid arguments would be used in an object’s initialization.

class DefaultMaker

Bases: object

Base class for default value factories.

make()

Create a new object.

class ObjectDefaultMaker(cls, args, kwargs)

Bases: DefaultMaker

Default value factory for Object derived classes.

class Object(**kwargs)

Bases: object

Base class for Guts objects.

Variables:

• dummy_for – (class variable) If set, this indicates that the containing class is a dummy for another type. This can be used to hold native Python objects and non-Guts based objects as children of a Guts object.

• dummy_for_description – (class variable) Overrides the name shown in the “dummy for …” documentation strings.

classmethod D(*args, **kwargs)

Get a default value factory for this class, configured with specified arguments.

Returns:

Factory for default values.

Return type:

ObjectDefaultMaker object

validate(regularize=False, depth=-1)

Validate this object.

Raises ValidationError when the object is invalid.

Parameters:

depth (int) – Maximum depth to descend into child objects.

regularize(depth=-1)

Regularize this object.

Regularization tries to convert child objects of invalid types to the expected types.

Raises ValidationError when the object is invalid and cannot be regularized.

Parameters:

depth (int) – Maximum depth to descend into child objects.

dump(stream=None, filename=None, header=False)

Serialize to YAML.

If neither stream nor filename is set, a string containing the serialized data is returned.

Parameters:

• stream – Output to stream.

• filename (str) – Output to file of given name.

• header (str) – File header to prepend to the output.

dump_xml(stream=None, filename=None, header=False, ns_ignore=False)

Serialize to XML.

If neither stream nor filename is set, a string containing the serialized data is returned.

Parameters:

• stream – Output to stream.

• filename (str) – Output to file of given name.

• header (str) – File header to prepend to the output.

• ns_ignore (bool) – Whether to ignore the XML namespace.

classmethod load(stream=None, filename=None, string=None)

Deserialize from YAML.

Parameters:

• stream – Read input from stream.

• filename (str) – Read input from file of given name.

• string (str) – Read input from string.

classmethod load_xml(stream=None, filename=None, string=None, ns_hints=None, ns_ignore=False)

Deserialize from XML.

Parameters:

• stream – Read input from stream.

• filename (str) – Read input from file of given name.

• string (str) – Read input from string.

to_dict(obj)

Get dict of guts object attributes.

Parameters:

obj – :py:class`Object` object

class SObject(**kwargs)

Bases: Object

Base class for simple str-serializable Guts objects.

Derived classes must support (de)serialization as in X(str(x)).

class Any(**kwargs)

Bases: Object

Placeholder for any object.

class Int(...) → int

Bases: Object

Placeholder for int.

class Float(...) → float

Bases: Object

Placeholder for float.

class Complex(...) → complex

Bases: Object

Placeholder for complex.

class Bool(...) → bool

Bases: Object

Placeholder for bool.

class String(...) → str

Bases: Object

Placeholder for str.

class Bytes(...) → bytes

Bases: Object

Placeholder for bytes.

class Unicode(...) → str

Bases: Object

Placeholder for str.

class Dict(...) → dict

Bases: Object

Placeholder for dict.

class List(...) → list

Bases: Object

Placeholder for list.

class Tuple(...) → tuple

Bases: Object

Placeholder for tuple.

class Duration(...) → float

Bases: Object

Placeholder for float time duration [s] with human-readable (de)serialization.

Examples:

• '1s' -> 1 second

• '1m' -> 1 minute

• '1h' -> 1 hour

• '1d' -> 1 day

• '1y' -> about 1 year = 365*24*3600 seconds

class Timestamp(...) → pyrocko.util.get_time_float

Bases: Object

Placeholder for a UTC timestamp.

class DateTimestamp(...) → pyrocko.util.get_time_float

Bases: Object

Placeholder for a UTC timestamp which (de)serializes as a date string.

class StringPattern(...) → str

Bases: String

Any str matching pattern '.*'.

class UnicodePattern(...) → str

Bases: Unicode

Any str matching pattern '.*'.

class StringChoice(...) → str

Bases: String

Any str out of [].

Variables:

• choices – Allowed choices (list of str).

• ignore_case – Whether to behave case-insensitive (bool, default: False).

class IntChoice(...) → int

Bases: Int

Any int out of [].

class StringUnion(...) → str

Bases: Object

Any str matching any of a set of constraints.

Variables:

members – List of constraints, e.g. StringChoice, StringPattern, … (list of TBase derived objects).

class Choice(**kwargs)

Bases: Object

Any out of a set of different types.

Variables:

choices – Allowed types (list of TBase derived objects).

clone(x, pool=None)

Clone guts object tree.

Traverses guts object tree and recursively clones all guts attributes, falling back to copy.deepcopy() for non-guts objects. Objects deriving from Object are instantiated using their respective init function. Multiply referenced objects in the source tree are multiply referenced also in the destination tree.

This function can be used to clone guts objects ignoring any contained run-time state, i.e. any of their attributes not defined as a guts property.

exception YPathError

Bases: Exception

This exception is raised for invalid ypath specifications.

iter_elements(obj, ypath)

Generator yielding elements matching a given ypath specification.

Parameters:

• obj – guts Object instance

• ypath – Dot-separated object path (e.g. ‘root.child.child’). To access list objects use slice notatation (e.g. ‘root.child[:].child[1:3].child[1]’).

Raises YPathError on failure.

get_elements(obj, ypath)

Get all elements matching a given ypath specification.

Parameters:

• obj – guts Object instance

• ypath – Dot-separated object path (e.g. ‘root.child.child’). To access list objects use slice notatation (e.g. ‘root.child[:].child[1:3].child[1]’).

Raises YPathError on failure.

set_elements(obj, ypath, value, validate=False, regularize=False)

Set elements matching a given ypath specification.

Parameters:

• obj – guts Object instance

• ypath – Dot-separated object path (e.g. ‘root.child.child’). To access list objects use slice notatation (e.g. ‘root.child[:].child[1:3].child[1]’).

• value – All matching elements will be set to value.

• validate – Whether to validate affected subtrees.

• regularize – Whether to regularize affected subtrees.

Raises YPathError on failure.

dump(*args, **kwargs)

Serialize to YAML.

If neither stream nor filename is set, a string containing the serialized data is returned.

Parameters:

• obj (Object) – Object to be serialized.

• stream – Output to stream.

• filename (str) – Output to file of given name.

• header (str) – File header to prepend to the output.

dump_xml(*args, **kwargs)

Serialize to XML.

If neither stream nor filename is set, a string containing the serialized data is returned.

Parameters:

• obj (Object) – Object to be serialized.

• stream – Output to stream.

• filename (str) – Output to file of given name.

• header (str) – File header to prepend to the output.

• ns_ignore (bool) – Whether to ignore the XML namespace.