1.1. reader
- class fitdecode.reader.CrcCheck(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
Defines the values expected by the
check_crc
parameter ofFitReader
’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’sfitdecode.DataProcessorBase.on_crc
method will still be called as well.
- READONLY = 1
CRC is computed but
FitReader
will never try to match CRCs. So nofitdecode.FitCRCError
will ever be raised.
- WARN = 2
CRC is computed and
FitReader
emits a warning message viawarnings.warn()
in case of mismatching CRC value. Nofitdecode.FitCRCError
will ever be raised.
- class fitdecode.reader.ErrorHandling(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
Defines the values expected by the
error_handling
parameter ofFitReader
’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 toBYTE
for the subsequentFitDataMessage
frames that rely on this definition.
- RAISE = 2
Strict mode.
FitReader
raises aFitParseError
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 byFitReader
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
andFitCRC
.While iterating a file with
FitReader
, you can for instance cut, stitch and/or reconstruct the file being read by using theFitChunk
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
).
- property processor
Read-only access to the data processor object.
- property last_timestamp
The last
timestamp
value (int
orfloat
).Often useful in FIT files since some data fields rely on it like
timestamp_16
andtimestamp_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 aFitHeader
frame, or after aFitCRC
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 aFitCRC
).
- 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 aFitCRC
).
- close()
Close the internal file handle if it is owned by this object, and clear the internal state.