lisa.utils.Serializable

class lisa.utils.Serializable

Bases: Loggable

A helper class for YAML serialization/deserialization

The following YAML tags are supported on top of what YAML provides out of the box:

• !call: call a Python callable with a mapping of arguments:

  # will execute:
  # package.module.Class(arg1='foo', arg2='bar', arg3=42)
  # NB: there is no space after "call:"
  !call:package.module.Class
      arg1: foo
      arg2: bar
      arg3: 42
  

• !include: include the content of another YAML file. Environment variables are expanded in the given path:

  !include /foo/$ENV_VAR/bar.yml
  

  Relative paths are treated as relative to the file in which the !include tag appears.

• !include-untrusted: Similar to !include but will disable custom tag interpretation when loading the content of the file. This is suitable to load untrusted input. Note that the env var interpolation and the relative path behavior depends on the mode of the YAML parser. This means that the path itself must be trusted, as this could leak environment variable values. Only the content of the included file is treated as untrusted.

• !env: take the value of an environment variable, and convert it to a Python type:

  !env:int MY_ENV_VAR
  

  If interpolate is used as type, the value will be interpolated using os.path.expandvars() and the resulting string returned:

  !env:interpolate /foo/$MY_ENV_VAR/bar
  

• !var: reference a module-level variable:

  !var package.module.var
  

• !untrusted: Interpret the given string as a YAML snippet, without any of the special constructor being enabled. This provides a way of safely including untrusted input in the YAML document without running the risk of the user being able to use e.g. !call.

  # Note the "|": this allows having a multiline string, leaving
  # its interpretation to the untrusted loader.
  !untrusted |
         foo: bar
  

Note

Not to be used on its own - instead, your class should inherit from this class to gain serialization superpowers.

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

Attributes

ATTRIBUTES_SERIALIZATION	Attributes to be treated specially during serialization.
DEFAULT_SERIALIZATION_FMT	Default format used when serializing objects.
YAML_ENCODING	Encoding used for YAML files.

Properties

logger inherited

Convenience short-hand for self.get_logger().

Methods

__copy__()	Regular shallow copy operation, without dropping any attributes.
__getstate__()	Filter the instance’s attributes upon serialization.
__setstate__()
from_path()	Deserialize an object from a file.
to_path()	Serialize the object to a file.
to_yaml()	Return a YAML string with the serialized object.
get_logger() inherited	Provides a logging.Logger named after cls.
log_locals() inherited	Debugging aid: log the local variables of the calling function.

Attributes

Serializable.ATTRIBUTES_SERIALIZATION = {'allowed': [], 'ignored': [], 'placeholders': {}}

Attributes to be treated specially during serialization.

See also

Serializable.__getstate__()

Serializable.DEFAULT_SERIALIZATION_FMT = 'yaml'

Default format used when serializing objects

Serializable.YAML_ENCODING = 'utf-8'

Encoding used for YAML files

Properties

property Serializable.logger

Inherited property, see lisa.utils.Loggable.logger

Convenience short-hand for self.get_logger().

Methods

Serializable.__copy__()

Regular shallow copy operation, without dropping any attributes.

Serializable.__getstate__()

Filter the instance’s attributes upon serialization.

The following keys in ATTRIBUTES_SERIALIZATION can be used to customize the serialized content:

• allowed: list of attribute names to serialize. All other attributes will be ignored and will not be saved/restored.

• ignored: list of attribute names to not serialize. All other attributes will be saved/restored.

• placeholders: Map of attribute names to placeholder values. These attributes will not be serialized, and the placeholder value will be used upon restoration.

If both allowed and ignored are specified, ignored is ignored.

Serializable.__setstate__(dct)

classmethod Serializable.from_path(filepath, fmt=None)

Deserialize an object from a file

Parameters:

• filepath (str) – The path of file in which the object has been dumped

• fmt (str) – Serialization format.

Raises:

AssertionError – if the deserialized object is not an instance of the class.

Note

Only deserialize files from trusted source, as both pickle and YAML formats can lead to arbitrary code execution.

Serializable.to_path(filepath, fmt=None)

Serialize the object to a file

Parameters:

• filepath (str or io.IOBase) – The path of the file or file-like object in which the object will be dumped.

• fmt (str) – Serialization format.

Serializable.to_yaml()

Return a YAML string with the serialized object.

classmethod Serializable.get_logger(suffix=None)

Inherited method, see lisa.utils.Loggable.get_logger()

Provides a logging.Logger named after cls.

classmethod Serializable.log_locals(var_names=None, level='debug')

Inherited method, see lisa.utils.Loggable.log_locals()

Debugging aid: log the local variables of the calling function.