ButlerLogRecords

class lsst.daf.butler.logging.ButlerLogRecords(records: list[lsst.daf.butler.logging.ButlerLogRecord], extra: dict[str, object] | None = None)

Bases: MutableSequence[ButlerLogRecord]

A container class for ButlerLogRecord objects.

Parameters:

recordslist [ButlerLogRecord]

List of records to use directly as the backing store for the container.

extradict, optional

Additional JSON data included with the log records. Subclasses may interpret structured information, but the base class just sets this as the extra attribute.

Notes

ButlerLogRecords supports two different file formats:

• Full-container serialization to JSON, in which records are stored in a records array and extra fields may be present (for backwards compatibility, reading records directly from a JSON list is also supported).

• Streaming serialization, in which each each line is a one-line JSON representation of a single ButlerLogRecord. Extra fields may be added included to this format by appending a single line with the value given by STREAMING_EXTRA_DELIMITER, which indicates that the remainder of the file is a single JSON block.

Subclasses of ButlerLogRecords are expected to support these formats by using the “extra” JSON fields to hold any additional state. If subclasses intercept extra at construction in a way that prevents that information from being held in the base class extra field, they must override _from_record_subset and to_json_data to pass that state to slices and save it, respectively.

Attributes Summary

STREAMING_EXTRA_DELIMITER	Special string written (on its own line) after streamed log records to indicate that the rest of the file is a JSON blob of "extra" data.
log_format	The log format string for these records.

Methods Summary

append(value)	S.append(value) -- append value to the end of the sequence
from_file(filename)	Read records from file.
from_raw(serialized)	Parse raw serialized form and return records.
from_records(records[, extra])	Create collection from iterable.
from_stream(stream)	Read records from I/O stream.
insert(index, value)	S.insert(index, value) -- insert value before index
set_log_format(format)	Set the log format string for these records.
to_json_data()	Serialize to a JSON string.
write_streaming_extra(file, extra_data)	Append the special delimiter and extra JSON data to a file written in streaming mode.

Attributes Documentation

STREAMING_EXTRA_DELIMITER: ClassVar[str] = '###EXTRA###'

Special string written (on its own line) after streamed log records to indicate that the rest of the file is a JSON blob of “extra” data.

log_format

The log format string for these records.

Methods Documentation

append(value: LogRecord | ButlerLogRecord) → None

S.append(value) – append value to the end of the sequence

classmethod from_file(filename: str) → Self

Read records from file.

Parameters:

filenamestr

Name of file containing the JSON records.

Notes

Works with one-record-per-line format JSON files and a direct serialization of the Pydantic model.

classmethod from_raw(serialized: str | bytes) → ButlerLogRecords

Parse raw serialized form and return records.

Parameters:

serializedbytes or str

Either the serialized JSON of the model created using write or a streaming format of one JSON ButlerLogRecord per line. This can also support a zero-length string.

Returns:

containerButlerLogRecords

New log record container.

classmethod from_records(records: Iterable[ButlerLogRecord], extra: dict[str, object] | None = None) → Self

Create collection from iterable.

Parameters:

recordsiterable of ButlerLogRecord or LogRecord

The records to seed this class with.

extradict, optional

Additional JSON data included with the log records. Subclasses may interpret structured information, but the base class just sets this as the extra attribute.

Returns:

containerButlerLogRecords

New log record container.

classmethod from_stream(stream: IO) → Self

Read records from I/O stream.

Parameters:

streamtyping.IO

Stream from which to read JSON records.

Returns:

containerButlerLogRecords

New log record container.

insert(index: int, value: LogRecord | ButlerLogRecord) → None

S.insert(index, value) – insert value before index

set_log_format(format: str | None) → str | None

Set the log format string for these records.

This may also be set via the property; method is provided for backwards compatibility.

Parameters:

formatstr, optional

The new format string to use for converting this collection of records into a string. If None the default format will be used.

Returns:

old_formatstr, optional

The previous log format.

to_json_data() → str

Serialize to a JSON string.

Returns:

datastr

String containing JSON data.

classmethod write_streaming_extra(file: IO[str], extra_data: str) → None

Append the special delimiter and extra JSON data to a file written in streaming mode.

Parameters:

filetyping.IO

File object to write to, pointing to the end of the streamed log records.

extra_datastr

Extra JSON data as a string.