plainbox.impl.exporter – shared code for session state exporters



class plainbox.impl.exporter.ByteStringStreamTranslator(dest_stream, encoding)[source]

Bases: io.RawIOBase

This is a sort of “impedance matcher” that bridges the gap between something that expects to write strings to a stream and a stream that expects to receive bytes. Instead of using, for instance, an intermediate in-memory IO object, this decodes on the fly and has the same interface as a writable stream, so it can be initialized with the destination string stream and then passed to something (usually a dump-style function) that writes bytes.


Flush and close the IO object.

This method has no effect if the file is already closed.


Returns underlying file descriptor if one exists.

OSError is raised if the IO object does not use a file descriptor.


Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.


Return whether this is an ‘interactive’ stream.

Return False if it can’t be determined.


Return whether object was opened for reading.

If False, read() will raise OSError.


Read until EOF, using multiple read() call.


Read and return a line from the stream.

If size is specified, at most size bytes will be read.

The line terminator is always b’n’ for binary files; for text files, the newlines argument to open can be used to select the line terminator(s) recognized.


Return a list of lines from the stream.

hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint.


Change stream position.

Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are:

  • 0 – start of stream (the default); offset should be zero or positive
  • 1 – current stream position; offset may be negative
  • 2 – end of stream; offset is usually negative

Return the new absolute position.


Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().


Return current stream position.


Truncate file to size bytes.

File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Returns the new size.


Return whether object was opened for writing.

If False, write() will raise OSError.


Writes to the stream, takes bytes and decodes them per the object’s specified encoding prior to writing. :param data: the chunk of data to write.

class plainbox.impl.exporter.SessionStateExporterBase(option_list=None, exporter_unit=None)[source]


Base class for “exporter” that write out the state of the session after all jobs have finished running, in a user-selected format. The intent is not to preserve everything that the session may hold but instead to present it to the user in the best format possible.

Each exporter can support a set of options that can alter the way it operates. Options can either be set boolean-like, or they can be assigned a value (a string). If an option contains a “=”, the part of the string on the right of the equal sign will be assigned as the option’s value; otherwise they operate in a boolean fashion.

It’s best to keep the list of exporter options under control to keep the user interface from becoming annoying.

OPTION_FLATTEN_IO_LOG = 'flatten-io-log'
OPTION_SQUASH_IO_LOG = 'squash-io-log'
OPTION_WITH_ATTACHMENTS = 'with-attachments'
OPTION_WITH_CATEGORY_MAP = 'with-category-map'
OPTION_WITH_CERTIFICATION_STATUS = 'with-certification-status'
OPTION_WITH_COMMENTS = 'with-comments'
OPTION_WITH_IO_LOG = 'with-io-log'
OPTION_WITH_JOB_DEFS = 'with-job-defs'
OPTION_WITH_JOB_HASH = 'with-job-hash'
OPTION_WITH_JOB_LIST = 'with-job-list'
OPTION_WITH_JOB_VIA = 'with-job-via'
OPTION_WITH_RESOURCE_MAP = 'with-resource-map'
OPTION_WITH_RUN_LIST = 'with-run-list'
SUPPORTED_OPTION_LIST = ('with-io-log', 'squash-io-log', 'flatten-io-log', 'with-run-list', 'with-job-list', 'with-resource-map', 'with-job-defs', 'with-attachments', 'with-comments', 'with-job-via', 'with-job-hash', 'with-category-map', 'with-certification-status')
dump(data, stream)

Dump data to stream.

This method operates on data that was returned by get_session_data_subset(). It may not really process bytes or simple collections. Instead, for efficiency, anything is required.

As in get_session_data_subset() it’s essential to safely save arbitrarily large data sets (or actually, only where it matters the most, like in io_log).

Data is a text stream suitable for writing.

dump_from_session_manager(session_manager, stream)[source]

Dump session information pulled from session manager to stream.

This method takes session manager instance, extracts session information from it, and dumps it to a stream.


Returns the value assigned to an option.


Compute a subset of session data.

The subset of the data that should be saved may depend on a particular saver class and options selected by the user.

Must return a collection that can be handled by dump(). Special care must be taken when processing io_log (and in the future, attachments) as those can be arbitrarily large.

set_option_value(option, value=True)[source]

assigns a value to an option. If no value is given, it just “sets” the option to True

supported_option_list = ('with-io-log', 'squash-io-log', 'flatten-io-log', 'with-run-list', 'with-job-list', 'with-resource-map', 'with-job-defs', 'with-attachments', 'with-comments', 'with-job-via', 'with-job-hash', 'with-category-map', 'with-certification-status')

Exporter unit this exporter was created with.

The exporter unit holds additional information that may be of use to applications, such as typical file name extension.

class plainbox.impl.exporter.classproperty(func)[source]

Bases: object

Class property.

comments powered by Disqus