mcap.reader module

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

class mcap.reader.McapReader(stream: IO[bytes], validate_crcs: bool = False)

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:

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

• validate_crcs – if True, will validate Chunk and DataEnd CRC values as messages are read.

abstract get_header() → Header

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

abstract get_summary() → Optional[Summary]

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

abstract iter_attachments() → Iterator[Attachment]

Iterates through attachment records in the MCAP.

abstract iter_messages(topics: Optional[Iterable[str]] = None, start_time: Optional[int] = None, end_time: Optional[int] = None, log_time_order: bool = True, reverse: bool = False) → Iterator[Tuple[Optional[Schema], Channel, Message]]

iterates through the messages in an MCAP.

Parameters:

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

• start_time – an integer nanosecond timestamp. if provided, messages logged before this timestamp are not included.

• end_time – an integer nanosecond timestamp. if provided, messages logged after this timestamp are not included.

• 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.

abstract iter_metadata() → Iterator[Metadata]

Iterates through metadata records in the MCAP.

class mcap.reader.NonSeekingReader(stream: IO[bytes], validate_crcs: bool = False)

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.

get_header() → Header

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

get_summary() → Optional[Summary]

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: Optional[Iterable[str]] = None, start_time: Optional[int] = None, end_time: Optional[int] = None, log_time_order: bool = True, reverse: bool = False) → Iterator[Tuple[Optional[Schema], Channel, Message]]

Iterates through the messages in an MCAP.

Parameters:

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

• start_time – an integer nanosecond timestamp. if provided, messages logged before this timestamp are not included.

• end_time – an integer nanosecond timestamp. if provided, messages logged after this timestamp are not included.

• 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.

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)

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.

get_header() → Header

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

get_summary() → Optional[Summary]

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

iter_attachments() → Iterator[Attachment]

Iterates through attachment records in the MCAP.

iter_messages(topics: Optional[Iterable[str]] = None, start_time: Optional[int] = None, end_time: Optional[int] = None, log_time_order: bool = True, reverse: bool = False) → Iterator[Tuple[Optional[Schema], Channel, Message]]

iterates through the messages in an MCAP.

Parameters:

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

• start_time – an integer nanosecond timestamp. if provided, messages logged before this timestamp are not included.

• end_time – an integer nanosecond timestamp. if provided, messages logged after this timestamp are not included.

• 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.

iter_metadata() → Iterator[Metadata]

Iterates through metadata records in the MCAP.

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

constructs the appropriate McapReader implementation for this data source.