Import KML data files.

        ``import_locations()`` returns a dictionary with keys containing the
        section title, and values consisting of :class:`Placemark` objects.

        It expects data files in KML format, as specified in `KML Reference`_,
        which is XML such as::

            <?xml version="1.0" encoding="utf-8"?>
            <kml xmlns="http://earth.google.com/kml/2.1">
                <Document>
                    <Placemark id="Home">
                        <name>Home</name>
                        <Point>
                            <coordinates>-0.221,52.015,60</coordinates>
                        </Point>
                    </Placemark>
                    <Placemark id="Cambridge">
                        <name>Cambridge</name>
                        <Point>
                            <coordinates>0.390,52.167</coordinates>
                        </Point>
                    </Placemark>
                </Document>
            </kml>

        The reader uses the :mod:`ElementTree` module, so should be very fast
        when importing data.  The above file processed by
        ``import_locations()`` will return the following ``dict`` object::

            {"Home": Placemark(52.015, -0.221, 60),
             "Cambridge": Placemark(52.167, 0.390, None)}

        Args:
            kml_file (iter): KML data to read

        Returns:
            dict: Named locations with optional comments

        .. _KML Reference:
           http://code.google.com/apis/kml/documentation/kmlreference.html

def import_locations(self, kml_file):
        """Import KML data files.

        ``import_locations()`` returns a dictionary with keys containing the
        section title, and values consisting of :class:`Placemark` objects.

        It expects data files in KML format, as specified in `KML Reference`_,
        which is XML such as::

            <?xml version="1.0" encoding="utf-8"?>
            <kml xmlns="http://earth.google.com/kml/2.1">
                <Document>
                    <Placemark id="Home">
                        <name>Home</name>
                        <Point>
                            <coordinates>-0.221,52.015,60</coordinates>
                        </Point>
                    </Placemark>
                    <Placemark id="Cambridge">
                        <name>Cambridge</name>
                        <Point>
                            <coordinates>0.390,52.167</coordinates>
                        </Point>
                    </Placemark>
                </Document>
            </kml>

        The reader uses the :mod:`ElementTree` module, so should be very fast
        when importing data.  The above file processed by
        ``import_locations()`` will return the following ``dict`` object::

            {"Home": Placemark(52.015, -0.221, 60),
             "Cambridge": Placemark(52.167, 0.390, None)}

        Args:
            kml_file (iter): KML data to read

        Returns:
            dict: Named locations with optional comments

        .. _KML Reference:
           http://code.google.com/apis/kml/documentation/kmlreference.html
        """
        self._kml_file = kml_file
        data = utils.prepare_xml_read(kml_file, objectify=True)

        for place in data.Document.Placemark:
            name = place.name.text
            coords = place.Point.coordinates.text
            if coords is None:
                logging.info('No coordinates found for %r entry' % name)
                continue
            coords = coords.split(',')
            if len(coords) == 2:
                longitude, latitude = coords
                altitude = None
            elif len(coords) == 3:
                longitude, latitude, altitude = coords
            else:
                raise ValueError('Unable to handle coordinates value %r'
                                 % coords)
            try:
                description = place.description
            except AttributeError:
                description = None
            self[name] = Placemark(latitude, longitude, altitude, name,
                                   description)