r"""Import GPS NMEA-formatted data files.

        ``import_locations()`` returns a list of `Fix` objects representing the
        fix sentences found in the GPS data.

        It expects data files in NMEA 0183 format, as specified in `the
        official documentation`_, which is ASCII text such as::

            $GPGSV,6,6,21,32,65,170,35*48
            $GPGGA,142058,5308.6414,N,00300.9257,W,1,04,5.6,1374.6,M,34.5,M,,*6B
            $GPRMC,142058,A,5308.6414,N,00300.9257,W,109394.7,202.9,191107,5,E,A*2C
            $GPGSV,6,1,21,02,76,044,43,03,84,156,49,06,89,116,51,08,60,184,30*7C
            $GPGSV,6,2,21,09,87,321,50,10,77,243,44,11,85,016,49,12,89,100,52*7A
            $GPGSV,6,3,21,13,70,319,39,14,90,094,52,16,85,130,49,17,88,136,51*7E
            $GPGSV,6,4,21,18,57,052,27,24,65,007,34,25,62,142,32,26,88,031,51*73
            $GPGSV,6,5,21,27,64,343,33,28,45,231,16,30,84,198,49,31,90,015,52*7C
            $GPGSV,6,6,21,32,65,170,34*49
            $GPWPL,5200.9000,N,00013.2600,W,HOME*5E
            $GPGGA,142100,5200.9000,N,00316.6600,W,1,04,5.6,1000.0,M,34.5,M,,*68
            $GPRMC,142100,A,5200.9000,N,00316.6600,W,123142.7,188.1,191107,5,E,A*21

        The reader only imports the GGA, or GPS fix, sentences currently but
        future versions will probably support tracks and waypoints.  Other than
        that the data is out of scope for ``upoints``.

        The above file when processed by ``import_locations()`` will return the
        following ``list`` object::

            [Fix(datetime.time(14, 20, 58), 53.1440233333, -3.01542833333, 1,
                 4, 5.6, 1374.6, 34.5, None, None),
             Position(datetime.time(14, 20, 58), True, 53.1440233333,
                      -3.01542833333, 109394.7, 202.9,
                      datetime.date(2007, 11, 19), 5.0, 'A'),
             Waypoint(52.015, -0.221, 'Home'),
             Fix(datetime.time(14, 21), 52.015, -3.27766666667, 1, 4, 5.6,
                 1000.0, 34.5, None, None),
             Position(datetime.time(14, 21), True, 52.015, -3.27766666667,
                      123142.7, 188.1, datetime.date(2007, 11, 19), 5.0, 'A')]

        Note:
            The standard is quite specific in that sentences *must* be less
            than 82 bytes, while it would be nice to add yet another validity
            check it isn't all that uncommon for devices to break this
            requirement in their "extensions" to the standard.

        .. todo:: Add optional check for message length, on by default

        Args:
            gpsdata_file (iter): NMEA data to read
            checksum (bool): Whether checksums should be tested

        Returns:
            list: Series of locations taken from the data

        .. _the official documentation: http://en.wikipedia.org/wiki/NMEA_0183

def import_locations(self, gpsdata_file, checksum=True):
        r"""Import GPS NMEA-formatted data files.

        ``import_locations()`` returns a list of `Fix` objects representing the
        fix sentences found in the GPS data.

        It expects data files in NMEA 0183 format, as specified in `the
        official documentation`_, which is ASCII text such as::

            $GPGSV,6,6,21,32,65,170,35*48
            $GPGGA,142058,5308.6414,N,00300.9257,W,1,04,5.6,1374.6,M,34.5,M,,*6B
            $GPRMC,142058,A,5308.6414,N,00300.9257,W,109394.7,202.9,191107,5,E,A*2C
            $GPGSV,6,1,21,02,76,044,43,03,84,156,49,06,89,116,51,08,60,184,30*7C
            $GPGSV,6,2,21,09,87,321,50,10,77,243,44,11,85,016,49,12,89,100,52*7A
            $GPGSV,6,3,21,13,70,319,39,14,90,094,52,16,85,130,49,17,88,136,51*7E
            $GPGSV,6,4,21,18,57,052,27,24,65,007,34,25,62,142,32,26,88,031,51*73
            $GPGSV,6,5,21,27,64,343,33,28,45,231,16,30,84,198,49,31,90,015,52*7C
            $GPGSV,6,6,21,32,65,170,34*49
            $GPWPL,5200.9000,N,00013.2600,W,HOME*5E
            $GPGGA,142100,5200.9000,N,00316.6600,W,1,04,5.6,1000.0,M,34.5,M,,*68
            $GPRMC,142100,A,5200.9000,N,00316.6600,W,123142.7,188.1,191107,5,E,A*21

        The reader only imports the GGA, or GPS fix, sentences currently but
        future versions will probably support tracks and waypoints.  Other than
        that the data is out of scope for ``upoints``.

        The above file when processed by ``import_locations()`` will return the
        following ``list`` object::

            [Fix(datetime.time(14, 20, 58), 53.1440233333, -3.01542833333, 1,
                 4, 5.6, 1374.6, 34.5, None, None),
             Position(datetime.time(14, 20, 58), True, 53.1440233333,
                      -3.01542833333, 109394.7, 202.9,
                      datetime.date(2007, 11, 19), 5.0, 'A'),
             Waypoint(52.015, -0.221, 'Home'),
             Fix(datetime.time(14, 21), 52.015, -3.27766666667, 1, 4, 5.6,
                 1000.0, 34.5, None, None),
             Position(datetime.time(14, 21), True, 52.015, -3.27766666667,
                      123142.7, 188.1, datetime.date(2007, 11, 19), 5.0, 'A')]

        Note:
            The standard is quite specific in that sentences *must* be less
            than 82 bytes, while it would be nice to add yet another validity
            check it isn't all that uncommon for devices to break this
            requirement in their "extensions" to the standard.

        .. todo:: Add optional check for message length, on by default

        Args:
            gpsdata_file (iter): NMEA data to read
            checksum (bool): Whether checksums should be tested

        Returns:
            list: Series of locations taken from the data

        .. _the official documentation: http://en.wikipedia.org/wiki/NMEA_0183
        """
        self._gpsdata_file = gpsdata_file
        data = utils.prepare_read(gpsdata_file)

        parsers = {
            'GPGGA': Fix,
            'GPRMC': Position,
            'GPWPL': Waypoint,
            'GPGLL': LoranPosition,
            'LCGLL': LoranPosition,
        }

        if not checksum:
            logging.warning('Disabling the checksum tests should only be used'
                            'when the device is incapable of emitting the '
                            'correct values!')
        for line in data:
            # The standard tells us lines should end in \r\n even though some
            # devices break this, but Python's standard file object solves this
            # for us anyway.  However, be careful if you implement your own
            # opener.
            if not line[1:6] in parsers:
                continue
            if checksum:
                values, checksum = line[1:].split('*')
                if not calc_checksum(values) == int(checksum, 16):
                    raise ValueError('Sentence has invalid checksum')
            else:
                values = line[1:].split('*')[0]
            elements = values.split(',')
            parser = getattr(parsers[elements[0]], 'parse_elements')
            self.append(parser(elements[1:]))