/gdata/geo/__init__.py

  1# -*-*- encoding: utf-8 -*-*-
  2#
  3# This is gdata.photos.geo, implementing geological positioning in gdata structures
  4#
  5# $Id: __init__.py 81 2007-10-03 14:41:42Z havard.gulldahl $
  6#
  7# Copyright 2007 H?vard Gulldahl 
  8# Portions copyright 2007 Google Inc.
  9#
 10# Licensed under the Apache License, Version 2.0 (the "License");
 11# you may not use this file except in compliance with the License.
 12# You may obtain a copy of the License at
 13#
 14#      http://www.apache.org/licenses/LICENSE-2.0
 15#
 16# Unless required by applicable law or agreed to in writing, software
 17# distributed under the License is distributed on an "AS IS" BASIS,
 18# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 19# See the License for the specific language governing permissions and
 20# limitations under the License.
 21
 22"""Picasa Web Albums uses the georss and gml namespaces for 
 23elements defined in the GeoRSS and Geography Markup Language specifications.
 24
 25Specifically, Picasa Web Albums uses the following elements:
 26
 27georss:where
 28gml:Point
 29gml:pos
 30
 31http://code.google.com/apis/picasaweb/reference.html#georss_reference
 32
 33
 34Picasa Web Albums also accepts geographic-location data in two other formats:
 35W3C format and plain-GeoRSS (without GML) format. 
 36"""
 37# 
 38#Over the wire, the Picasa Web Albums only accepts and sends the 
 39#elements mentioned above, but this module will let you seamlessly convert 
 40#between the different formats (TODO 2007-10-18 hg)
 41
 42__author__ = u'havard@gulldahl.no'# (H?vard Gulldahl)' #BUG: api chokes on non-ascii chars in __author__
 43__license__ = 'Apache License v2'
 44
 45
 46import atom
 47import gdata
 48
 49GEO_NAMESPACE = 'http://www.w3.org/2003/01/geo/wgs84_pos#'
 50GML_NAMESPACE = 'http://www.opengis.net/gml'
 51GEORSS_NAMESPACE = 'http://www.georss.org/georss'
 52
 53class GeoBaseElement(atom.AtomBase):
 54  """Base class for elements.
 55
 56  To add new elements, you only need to add the element tag name to self._tag
 57  and the namespace to self._namespace
 58  """
 59  
 60  _tag = ''
 61  _namespace = GML_NAMESPACE
 62  _children = atom.AtomBase._children.copy()
 63  _attributes = atom.AtomBase._attributes.copy()
 64
 65  def __init__(self, name=None, extension_elements=None,
 66      extension_attributes=None, text=None):
 67    self.name = name
 68    self.text = text
 69    self.extension_elements = extension_elements or []
 70    self.extension_attributes = extension_attributes or {}
 71
 72class Pos(GeoBaseElement):
 73  """(string) Specifies a latitude and longitude, separated by a space,
 74  e.g. `35.669998 139.770004'"""
 75  
 76  _tag = 'pos'
 77def PosFromString(xml_string):
 78  return atom.CreateClassFromXMLString(Pos, xml_string)
 79
 80class Point(GeoBaseElement):
 81  """(container)  Specifies a particular geographical point, by means of
 82  a <gml:pos> element."""
 83  
 84  _tag = 'Point'
 85  _children = atom.AtomBase._children.copy()
 86  _children['{%s}pos' % GML_NAMESPACE] = ('pos', Pos) 
 87  def __init__(self, pos=None, extension_elements=None, extension_attributes=None, text=None):
 88    GeoBaseElement.__init__(self, extension_elements=extension_elements,
 89                            extension_attributes=extension_attributes,
 90                            text=text)
 91    if pos is None:
 92      pos = Pos()
 93    self.pos=pos
 94def PointFromString(xml_string):
 95  return atom.CreateClassFromXMLString(Point, xml_string)
 96
 97class Where(GeoBaseElement):
 98  """(container) Specifies a geographical location or region.
 99  A container element, containing a single <gml:Point> element.
100  (Not to be confused with <gd:where>.) 
101  
102  Note that the (only) child attribute, .Point, is title-cased.
103  This reflects the names of elements in the xml stream
104  (principle of least surprise).
105  
106  As a convenience, you can get a tuple of (lat, lon) with Where.location(),
107  and set the same data with Where.setLocation( (lat, lon) ).
108
109  Similarly, there are methods to set and get only latitude and longitude.
110  """
111  
112  _tag = 'where'
113  _namespace = GEORSS_NAMESPACE
114  _children = atom.AtomBase._children.copy()
115  _children['{%s}Point' % GML_NAMESPACE] = ('Point', Point) 
116  def __init__(self, point=None, extension_elements=None, extension_attributes=None, text=None):
117    GeoBaseElement.__init__(self, extension_elements=extension_elements,
118                            extension_attributes=extension_attributes,
119                            text=text)
120    if point is None:
121      point = Point()
122    self.Point=point
123  def location(self):
124    "(float, float) Return Where.Point.pos.text as a (lat,lon) tuple"
125    try:
126      return tuple([float(z) for z in self.Point.pos.text.split(' ')])
127    except AttributeError:
128      return tuple()
129  def set_location(self, latlon):
130    """(bool) Set Where.Point.pos.text from a (lat,lon) tuple.
131
132    Arguments:
133    lat (float): The latitude in degrees, from -90.0 to 90.0
134    lon (float): The longitude in degrees, from -180.0 to 180.0
135    
136    Returns True on success.
137
138    """
139    
140    assert(isinstance(latlon[0], float))
141    assert(isinstance(latlon[1], float))
142    try:
143      self.Point.pos.text = "%s %s" % (latlon[0], latlon[1])
144      return True
145    except AttributeError:
146      return False
147  def latitude(self):
148    "(float) Get the latitude value of the geo-tag. See also .location()"
149    lat, lon = self.location()
150    return lat
151  
152  def longitude(self):
153    "(float) Get the longtitude value of the geo-tag. See also .location()"
154    lat, lon = self.location()
155    return lon
156
157  longtitude = longitude
158
159  def set_latitude(self, lat):
160    """(bool) Set the latitude value of the geo-tag.
161
162    Args:
163    lat (float): The new latitude value
164
165    See also .set_location()
166    """
167    _lat, lon = self.location()
168    return self.set_location(lat, lon)
169  
170  def set_longitude(self, lon):
171    """(bool) Set the longtitude value of the geo-tag.
172    
173    Args:
174    lat (float): The new latitude value
175
176    See also .set_location()
177    """
178    lat, _lon = self.location()
179    return self.set_location(lat, lon)
180
181  set_longtitude = set_longitude
182
183def WhereFromString(xml_string):
184  return atom.CreateClassFromXMLString(Where, xml_string)
185