mcap.reader module

High-level classes for reading content out of MCAP data sources.

class mcap.reader.DecodedMessageTuple(schema: Schema | None, channel: Channel, message: Message, decoded_message: Any)

Bases: NamedTuple

Yielded from every iteration of iter_decoded_messages().

channel: Channel

Alias for field number 1

decoded_message: Any

Alias for field number 3

message: Message

Alias for field number 2

schema: Schema | None

Alias for field number 0

class mcap.reader.McapReader(decoder_factories: Iterable[DecoderFactory] = ())

Bases: ABC

Reads data out of an MCAP file, using the summary section where available to efficiently read only the parts of the file that are needed.

Parameters:

decoder_factories – An iterable of DecoderFactory instances which can provide decoding functionality to iter_decoded_messages().

abstract get_header() → Header

Reads the Header records from the beginning of the MCAP file.

abstract get_summary() → Summary | None

Reads the (optional) summary section from the MCAP file.

abstract iter_attachments() → Iterator[Attachment]

Iterates through attachment records in the MCAP.

iter_decoded_messages(topics: Iterable[str] | str | None = None, start_time: int | None = None, end_time: int | None = None, log_time_order: bool = True, reverse: bool = False, *, starting_at: int | None = None, starting_after: int | None = None, ending_at: int | None = None, ending_before: int | None = None) → Iterator[DecodedMessageTuple]

iterates through messages in an MCAP, decoding their contents.

Accepts the same arguments as iter_messages().

abstract iter_messages(topics: Iterable[str] | str | None = None, start_time: int | None = None, end_time: int | None = None, log_time_order: bool = True, reverse: bool = False, *, starting_at: int | None = None, starting_after: int | None = None, ending_at: int | None = None, ending_before: int | None = None) → Iterator[Tuple[Schema | None, Channel, Message]]

iterates through the messages in an MCAP.

Parameters:

• topics – if not None, only messages from these topics will be returned.

• start_time – deprecated alias for starting_at; use starting_at or starting_after instead.

• end_time – deprecated alias for ending_before; use ending_before or ending_at instead.

• log_time_order – if True, messages will be yielded in ascending log time order. If False, messages will be yielded in the order they appear in the MCAP file.

• reverse – if both log_time_order and reverse are True, messages will be yielded in descending log time order.

• starting_at – an integer nanosecond timestamp. if provided, messages logged before this timestamp are not included (inclusive lower bound).

• starting_after – an integer nanosecond timestamp. if provided, messages logged at or before this timestamp are not included (exclusive lower bound).

• ending_at – an integer nanosecond timestamp. if provided, messages logged after this timestamp are not included (inclusive upper bound).

• ending_before – an integer nanosecond timestamp. if provided, messages logged at or after this timestamp are not included (exclusive upper bound).

At most one lower bound (start_time, starting_at, starting_after) and one upper bound (end_time, ending_at, ending_before) may be provided. The bounds resolve to a half-open range [start, end). start > end raises ValueError; start == end is a valid empty range.

abstract iter_metadata() → Iterator[Metadata]

Iterates through metadata records in the MCAP.

class mcap.reader.NonSeekingReader(stream: IO[bytes], validate_crcs: bool = False, decoder_factories: Iterable[DecoderFactory] = (), record_size_limit: int | None = 4294967296)

Bases: McapReader

an McapReader for reading out of non-seekable data sources, such as a pipe or socket.

Parameters:

• stream – a file-like object for reading the source data from.

• validate_crcs – if True, will validate chunk and data section CRC values.

• decoder_factories – An iterable of DecoderFactory instances which can provide decoding functionality to iter_decoded_messages().

• record_size_limit – An upper bound to the size of MCAP records that this reader will attempt to load in bytes, defaulting to 4 GiB. If this reader encounters a record with a greater length, it will throw an RecordLengthLimitExceeded error. Setting to None removes the limit, but can allow corrupted MCAP files to trigger a MemoryError exception.

get_header() → Header

Reads the Header record from the beginning of the MCAP file.

get_summary() → Summary | None

Returns a Summary object containing records from the (optional) summary section.

iter_attachments() → Iterator[Attachment]

Iterates through attachment records in the MCAP.

iter_messages(topics: Iterable[str] | str | None = None, start_time: int | None = None, end_time: int | None = None, log_time_order: bool = True, reverse: bool = False, *, starting_at: int | None = None, starting_after: int | None = None, ending_at: int | None = None, ending_before: int | None = None) → Iterator[Tuple[Schema | None, Channel, Message]]

Iterates through the messages in an MCAP.

See McapReader.iter_messages() for a description of the arguments.

Warning

setting log_time_order to True on a non-seekable stream will cause the entire content of the MCAP to be loaded into memory.

iter_metadata() → Iterator[Metadata]

Iterates through metadata records in the MCAP.

class mcap.reader.SeekingReader(stream: IO[bytes], validate_crcs: bool = False, decoder_factories: Iterable[DecoderFactory] = (), record_size_limit: int | None = 4294967296)

Bases: McapReader

an McapReader for reading out of seekable data sources.

Parameters:

• stream – a file-like object for reading the source data from.

• validate_crcs – if True, will validate Chunk CRCs for any chunks read. This class does not validate the data section CRC in the DataEnd record because it is designed not to read the entire data section when reading messages. To read messages while validating the data section CRC, use NonSeekingReader.

• decoder_factories – An iterable of DecoderFactory instances which can provide decoding functionality to iter_decoded_messages().

• record_size_limit – An upper bound to the size of MCAP records that this reader will attempt to load in bytes, defaulting to 4 GiB. If this reader encounters a record with a greater length, it will throw an RecordLengthLimitExceeded error. Setting to None removes the limit, but can allow corrupted MCAP files to trigger a MemoryError exception.

get_header() → Header

Reads the Header record from the beginning of the MCAP file.

get_summary() → Summary | None

Reads the (optional) summary section from the MCAP file.

iter_attachments() → Iterator[Attachment]

Iterates through attachment records in the MCAP.

iter_messages(topics: Iterable[str] | str | None = None, start_time: int | None = None, end_time: int | None = None, log_time_order: bool = True, reverse: bool = False, *, starting_at: int | None = None, starting_after: int | None = None, ending_at: int | None = None, ending_before: int | None = None) → Iterator[Tuple[Schema | None, Channel, Message]]

iterates through the messages in an MCAP.

See McapReader.iter_messages() for a description of the arguments.

iter_metadata() → Iterator[Metadata]

Iterates through metadata records in the MCAP.

mcap.reader.make_reader(stream: IO[bytes], validate_crcs: bool = False, decoder_factories: Iterable[DecoderFactory] = ()) → McapReader

constructs the appropriate McapReader implementation for this data source.