1.1. reader

class fitdecode.reader.CrcCheck(value)

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(value)

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.