Import OSM data files.

        ``import_locations()`` returns a list of ``Node`` and ``Way`` objects.

        It expects data files conforming to the `OpenStreetMap 0.5 DTD`_, which
        is XML such as::

            <?xml version="1.0" encoding="UTF-8"?>
            <osm version="0.5" generator="upoints/0.9.0">
              <node id="0" lat="52.015749" lon="-0.221765" user="jnrowe" visible="true" timestamp="2008-01-25T12:52:11+00:00" />
              <node id="1" lat="52.015761" lon="-0.221767" visible="true" timestamp="2008-01-25T12:53:00+00:00">
                <tag k="created_by" v="hand" />
                <tag k="highway" v="crossing" />
              </node>
              <node id="2" lat="52.015754" lon="-0.221766" user="jnrowe" visible="true" timestamp="2008-01-25T12:52:30+00:00">
                <tag k="amenity" v="pub" />
              </node>
              <way id="0" visible="true" timestamp="2008-01-25T13:00:00+0000">
                <nd ref="0" />
                <nd ref="1" />
                <nd ref="2" />
                <tag k="ref" v="My Way" />
                <tag k="highway" v="primary" />
              </way>
            </osm>

        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 `Osm` object::

            Osm([
                Node(0, 52.015749, -0.221765, True, "jnrowe",
                     utils.Timestamp(2008, 1, 25, 12, 52, 11), None),
                Node(1, 52.015761, -0.221767, True,
                     utils.Timestamp(2008, 1, 25, 12, 53), None,
                     {"created_by": "hand", "highway": "crossing"}),
                Node(2, 52.015754, -0.221766, True, "jnrowe",
                     utils.Timestamp(2008, 1, 25, 12, 52, 30),
                     {"amenity": "pub"}),
                Way(0, [0, 1, 2], True, None,
                    utils.Timestamp(2008, 1, 25, 13, 00),
                    {"ref": "My Way", "highway": "primary"})],
                generator="upoints/0.9.0")

        Args:
            osm_file (iter): OpenStreetMap data to read

        Returns:
            Osm: Nodes and ways from the data

        .. _OpenStreetMap 0.5 DTD:
            http://wiki.openstreetmap.org/wiki/OSM_Protocol_Version_0.5/DTD

def import_locations(self, osm_file):
        """Import OSM data files.

        ``import_locations()`` returns a list of ``Node`` and ``Way`` objects.

        It expects data files conforming to the `OpenStreetMap 0.5 DTD`_, which
        is XML such as::

            <?xml version="1.0" encoding="UTF-8"?>
            <osm version="0.5" generator="upoints/0.9.0">
              <node id="0" lat="52.015749" lon="-0.221765" user="jnrowe" visible="true" timestamp="2008-01-25T12:52:11+00:00" />
              <node id="1" lat="52.015761" lon="-0.221767" visible="true" timestamp="2008-01-25T12:53:00+00:00">
                <tag k="created_by" v="hand" />
                <tag k="highway" v="crossing" />
              </node>
              <node id="2" lat="52.015754" lon="-0.221766" user="jnrowe" visible="true" timestamp="2008-01-25T12:52:30+00:00">
                <tag k="amenity" v="pub" />
              </node>
              <way id="0" visible="true" timestamp="2008-01-25T13:00:00+0000">
                <nd ref="0" />
                <nd ref="1" />
                <nd ref="2" />
                <tag k="ref" v="My Way" />
                <tag k="highway" v="primary" />
              </way>
            </osm>

        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 `Osm` object::

            Osm([
                Node(0, 52.015749, -0.221765, True, "jnrowe",
                     utils.Timestamp(2008, 1, 25, 12, 52, 11), None),
                Node(1, 52.015761, -0.221767, True,
                     utils.Timestamp(2008, 1, 25, 12, 53), None,
                     {"created_by": "hand", "highway": "crossing"}),
                Node(2, 52.015754, -0.221766, True, "jnrowe",
                     utils.Timestamp(2008, 1, 25, 12, 52, 30),
                     {"amenity": "pub"}),
                Way(0, [0, 1, 2], True, None,
                    utils.Timestamp(2008, 1, 25, 13, 00),
                    {"ref": "My Way", "highway": "primary"})],
                generator="upoints/0.9.0")

        Args:
            osm_file (iter): OpenStreetMap data to read

        Returns:
            Osm: Nodes and ways from the data

        .. _OpenStreetMap 0.5 DTD:
            http://wiki.openstreetmap.org/wiki/OSM_Protocol_Version_0.5/DTD
        """
        self._osm_file = osm_file
        data = utils.prepare_xml_read(osm_file, objectify=True)

        # This would be a lot simpler if OSM exports defined a namespace
        if not data.tag == 'osm':
            raise ValueError("Root element %r is not `osm'" % data.tag)
        self.version = data.get('version')
        if not self.version:
            raise ValueError('No specified OSM version')
        elif not self.version == '0.5':
            raise ValueError('Unsupported OSM version %r' % data)

        self.generator = data.get('generator')

        for elem in data.getchildren():
            if elem.tag == 'node':
                self.append(Node.parse_elem(elem))
            elif elem.tag == 'way':
                self.append(Way.parse_elem(elem))