1.1. reader

class fitdecode.reader.CrcCheck(*values)

Defines the values expected by the check_crc parameter of FitReader’s constructor.

DISABLED = 0: CRC is not computed at all (fastest). fitdecode.FitCRC frame will still be yielded if present in the source FIT stream, but with meaningless values. In which case data processor’s fitdecode.DataProcessorBase.on_crc method will still be called as well.

READONLY = 1: CRC is computed but FitReader will never try to match CRCs. So no fitdecode.FitCRCError will ever be raised.

WARN = 2: CRC is computed and FitReader emits a warning message via warnings.warn() in case of mismatching CRC value. No fitdecode.FitCRCError will ever be raised.

RAISE = 3: CRC is computed and matched by FitReader. fitdecode.FitCRCError is raised upon incorrect CRC value.

ENABLED = 3: Alias of RAISE for backward compatibility.

class fitdecode.reader.ErrorHandling(*values)

Defines the values expected by the error_handling parameter of FitReader’s constructor.

IGNORE = 0

Disable developer types checking and other parsing error due to malformed FIT data. Parser proceeds when possible.

For instance, if a FitDefinitionMessage references an undefined so-called developer type (or an undefined field), FitReader will silently ignore the error and will default to BYTE for the subsequent FitDataMessage frames that rely on this definition.

WARN = 1: Default behavior. Same as IGNORE but FitReader emits a warning with warnings.warn().

RAISE = 2: Strict mode. FitReader raises a FitParseError exception when malformed data is found, thus stopping the parsing of the current stream.

class fitdecode.reader.RecordHeader(is_definition, is_developer_data, local_mesg_num, time_offset)

is_definition

is_developer_data

local_mesg_num

time_offset

class fitdecode.reader.FitReader(fileish, *, processor=<object object>, check_crc=CrcCheck.WARN, error_handling=ErrorHandling.WARN, keep_raw_chunks=False, data_bag=<object object>)

Parse the content of a FIT stream or storage.

Transparently supports “chained FIT Files” as per SDK’s definition. A FitHeader object is yielded during iteration to mark the beginning of each new “FIT File”.

First argument fileish can be passed as a file-like or a path-like object (os.PathLike). File-like object must be opened in byte-mode. File-like object is not owned by FitReader so it is up to the caller to close it manually.

Usage:

import fitdecode

with fitdecode.FitReader('file.fit') as fit:
    for frame in fit:
        # The yielded frame object is of one of the following types:
        # * fitdecode.FitHeader (FIT_FRAME_HEADER)
        # * fitdecode.FitDefinitionMessage (FIT_FRAME_DEFINITION)
        # * fitdecode.FitDataMessage (FIT_FRAME_DATA)
        # * fitdecode.FitCRC (FIT_FRAME_CRC)

        if frame.frame_type == fitdecode.FIT_FRAME_DATA:
            # Here, frame is a FitDataMessage object.
            # A FitDataMessage object contains decoded values that
            # are directly usable in your script logic.
            print(frame.name)

Data processing:

You can specify your own data processor object using the processor argument.
The argument can be left untouched so that DefaultDataProcessor is used.
Otherwise, it can be set to None or any other false value to skip data processing entirely. This can speed up things a bit if your intent is only to manipulate the file at binary level (i.e. chunks), in which case keep_raw_chunks must be set to true.

Raw chunks:

“raw chunk” or sometimes “frame”, is the name given in fitdecode to the bytes block that represents one of the four FIT entities: FitHeader, FitDefinitionMessage, FitDataMessage and FitCRC.
While iterating a file with FitReader, you can for instance cut, stitch and/or reconstruct the file being read by using the FitChunk object attached to any of the four aforementioned entities, as long as the keep_raw_chunks option is true.

Data bag:

A data_bag object can be passed to the constructor and then be retrieved via the data_bag property.
data_bag can be of any type (a dict by default) and will never be altered by this class.
A “data bag” is useful if you wish to store some context-sensitive data during the decoding of a file.
A typical use case is from a data processor that cannot hold its own context-sensitive data due to its instance being shared with other readers and/or by multiple threads (typically DefaultDataProcessor).

data_bag: the data_bag object that was passed to the constructor, or, by default, a dict object

property processor: Read-only access to the data processor object.

property last_header: The last read FitHeader object. May be None.

property last_timestamp

The last timestamp value (int or float).

Often useful in FIT files since some data fields rely on it like timestamp_16 and timestamp_ms for instance.

Hint: you usually want to use this property from your own processor class derived from on of the processors available from fitdecode.processors.

property file_id

The file_id FitDataMessage object related to the current FIT file.

May be None. Typically before a FitHeader frame, or after a FitCRC frame.

property fit_file_index

The zero-based index int of the so-called FIT file currently read from this data stream so far.

None if no FIT file header has been encoutered yet.

property fit_files_count: The number of FIT files found in this data stream so far.

property local_mesg_defs

Read-only access to the dict of local message types of the current “FIT file”.

It is cleared by close() (or __exit__()), and also each time a FIT file header is reached (i.e. at the beginning of a file, or after a FitCRC).

property local_dev_types

Read-only access to the dict of developer types of the current “FIT file”.

It is cleared by close() (or __exit__()), and also each time a FIT file header is reached (i.e. at the beginning of a file, or after a FitCRC).

close(): Close the internal file handle if it is owned by this object, and clear the internal state.