.. module:: fitparse

Interface for reading a .FIT file.

Provided a .FIT file fileish, this is the main interface to parsing a .FIT file and reading its data.

# Specifying a file path
fitfile = FitFile('/path.to/fitfile.fit')

# Providing a file-like object
file_obj = open('/path.to/fitfile.fit', 'rb')
fitfile = FitFile(file_obj)

# Providing a raw string of bytes
file_obj = open('/path.to/fitfile.fit', 'rb')
raw_fit_data = file_obj.read()
fitfile = FitFile(raw_fit_data)

.. method:: get_messages(name=None, with_definitions=False, as_dict=False)

    TODO: document and implement

.. method:: parse()

    Parse the underlying FIT data completely.

    :raises: May raise a :exc:`FitParseError` exception.

    .. _exception_warning:
    .. warning:: Note on Exceptions While Parsing a ``.FIT`` File

        In general, any operation on a that :class:`FitFile` that results in
        parsing the underlying FIT data may throw a :exc:`FitParseError`
        exception when invalid data is encountered.

        One way to catch these before you start reading going through the
        messages contained in a :class:`FitFile` is to call
        :meth:`parse()` immediately after creating a
        :class:`FitFile` object. For example::


            import sys
            from fitparse import FitFile, FitParseError

            try:
                fitfile = FitFile('/path.to/fitfile.fit')
                fitfile.parse()
            except FitParseError, e:
                print "Error while parsing .FIT file: %s" % e
                sys.exit(1)


        Any file related IO exceptions caught during a `read()` or `close()`
        operation will be raised as usual.

.. attribute:: messages

    The complete `list` of :class:`DataMessage` record objects that are
    contained in this :class:`FitFile`. This list is provided as a
    convenience attribute that wraps :meth:`get_messages()`. It is
    functionally equivalent to::

        class FitFile(object):
            # ...

            @property
            def messages(self):
                return list(self.get_messages())

    :raises: Reading this property may raise a :exc:`FitParseError`
        exception. See the :ref:`note on exceptions <exception_warning>`.

.. attribute:: profile_version

    The profile version of the FIT data read (see ANT FIT SDK for)

.. attribute:: protocol_version

    The protocol version of the FIT data read (see ANT FIT SDK)

A list of DataMessage objects are returned by :meth:`FitFile.get_messages()` and :attr:`FitFile.messages`. These are not meant to be created directly.

.. attribute:: fields

    A `list` of :class:`FieldData` objects representing the fields contained
    in this message.

.. method:: get(field_name, as_dict=False)

    Returns a :class:`FieldData` for field `field_name` if it exists,
    otherwise `None`. If `as_dict` is set to `True`, returns a `dict`
    representation of the field (see :class:`FieldData.as_dict()`)

.. method:: get_value(field_name)

    Returns the value of `field_name` if it exists, otherwise `None`

.. method:: get_values()

    Return a `dict` mapping of field names to their values. For example::

        >> data_message.get_values()
        {
            'altitude': 24.6,
            'cadence': 97,
            'distance': 81.97,
            'grade': None,
            'heart_rate': 153,
            'position_lat': None,
            'position_long': None,
            'power': None,
            'resistance': None,
            'speed': 7.792,
            'temperature': 20,
            'time_from_course': None,
            'timestamp': datetime.datetime(2011, 11, 6, 13, 41, 50)
        }

.. method:: as_dict()

    TODO: document me

.. attribute:: name

    The name of this `DataMessage`, as defined by its :attr:`def_mesg`.

.. attribute:: def_mesg

    .. note::

        Generally this attribute is for access to FIT internals only

    The :class:`DefinitionMessage` associated with this `DataMessage`.
    These are encountered while parsing FIT data and are declared to define
    the data contained in a `DataMessage.

.. attribute:: mesg_num

    The message number of this `DataMessage`, as defined by its
    :attr:`def_mesg`.

.. attribute:: mesg_type

    The :class:`MessageType` associated with the :attr:`mesg_num` for this
    `DataMessage`. If no associated message type is defined in the
    :ref:`SDK profile <profile>`, then this is set to `None`.

    TODO: Document SDK profile and update link