upoints.kml.Placemarks

Package upoints :: Module kml :: Class Placemarks |
[hide private]
[frames] | no frames]

# Class Placemarks

       object --+
                |
             dict --+
                    |
    point.KeyedPoints --+
                        |
                       Placemarks

Class for representing a group of Placemark objects

Since: 0.6.0

Instance Methods | [hide private]
    new empty dictionary
__init__(self, kml_file=None) Initialise a new Placemarks object |
`dict` |
import_locations(self, kml_file, kml_version=None) Import KML data files |
`ET.ElementTree` |
export_kml_file(self, kml_version=`'``2.2``'`, human_namespace=False) Generate KML element tree from Placemarks |
Inherited from `point.KeyedPoints`: `__repr__`, `bearing`, `destination`, `distance`, `final_bearing`, `forward`, `inverse`, `midpoint`, `range`, `sun_events`, `sunrise`, `sunset`, `to_grid_locator` Inherited from `dict`: `__cmp__`, `__contains__`, `__delitem__`, `__eq__`, `__ge__`, `__getattribute__`, `__getitem__`, `__gt__`, `__hash__`, `__iter__`, `__le__`, `__len__`, `__lt__`, `__ne__`, `__new__`, `__setitem__`, `clear`, `copy`, `fromkeys`, `get`, `has_key`, `items`, `iteritems`, `iterkeys`, `itervalues`, `keys`, `pop`, `popitem`, `setdefault`, `update`, `values` Inherited from `object`: `__delattr__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__str__`

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, kml_file=None) (Constructor) |
Initialise a new Placemarks object Parameters: `points` - Point objects to wrap `parse` - Whether to attempt import of `points` `units` - Unit type to be used for distances when parsing string locations Returns:
    new empty dictionary
Overrides: object.__init__

### import_locations(self, kml_file, kml_version=None) |
Import KML data files import_locations() returns a dictionary with keys containing the section title, and values consisting of 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 Python's 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)}
    >>> locations = Placemarks(open("kml"))
    >>> for value in sorted(locations.values(),
    ...                     key=lambda x: x.name.lower()):
    ...     print(value)
    Cambridge (52°10'01"N, 000°23'24"E)
    Home (52°00'54"N, 000°13'15"W alt 60m)
The `kml_version` parameter allows the caller to specify the specific KML version that should be processed, this allows the caller to process inputs which contain entries in more than one namespace without duplicates resulting from entries in being specified with different namespaces. Parameters: `kml_file` (`file`, `list` or `str`) - KML data to read `kml_version` (`str`) - Specific KML version entities to import Returns: `dict` Named locations with optional comments Overrides: point.KeyedPoints.import_locations

### export_kml_file(self, kml_version=`'``2.2``'`, human_namespace=False) |
Generate KML element tree from Placemarks
    >>> from sys import stdout
    >>> locations = Placemarks(open("kml"))
    >>> xml = locations.export_kml_file()
    >>> xml.write(stdout)
    <ns0:kml xmlns:ns0="http://earth.google.com/kml/2.2"><ns0:Document><ns0:Placemark id="Home"><ns0:name>Home</ns0:name><ns0:Point><ns0:coordinates>-0.221,52.015,60</ns0:coordinates></ns0:Point></ns0:Placemark><ns0:Placemark id="Cambridge"><ns0:name>Cambridge</ns0:name><ns0:Point><ns0:coordinates>0.39,52.167</ns0:coordinates></ns0:Point></ns0:Placemark></ns0:Document></ns0:kml>
    >>> xml = locations.export_kml_file("2.0")
    >>> xml.write(stdout)
    <ns0:kml xmlns:ns0="http://earth.google.com/kml/2.0"><ns0:Document><ns0:Placemark id="Home"><ns0:name>Home</ns0:name><ns0:Point><ns0:coordinates>-0.221,52.015,60</ns0:coordinates></ns0:Point></ns0:Placemark><ns0:Placemark id="Cambridge"><ns0:name>Cambridge</ns0:name><ns0:Point><ns0:coordinates>0.39,52.167</ns0:coordinates></ns0:Point></ns0:Placemark></ns0:Document></ns0:kml>
Parameters: `kml_version` (`str`) - KML version to generate `human_namespace` (`bool`) - Whether to generate output using human readable namespace prefixes Returns: `ET.ElementTree` KML element tree depicting Placemarks