Package sabx10 :: Package oxm
[hide private]
[frames] | no frames]

Source Code for Package sabx10.oxm

  1  ############################################################################### 
  2  # 
  3  # sabx10.oxm - an SABX file manipulation library 
  4  # Copyright (C) 2009, 2010 Jay Farrimond (jay@sabikerides.com) 
  5  # 
  6  # This file is part of sabx10.oxm. 
  7  # 
  8  # sabx10.oxm is free software: you can redistribute it and/or modify it under 
  9  # the terms of the GNU Lesser General Public License as published by the Free 
 10  # Software Foundation, either version 3 of the License, or (at your option) any 
 11  # later version. 
 12  # 
 13  # sabx10.oxm is distributed in the hope that it will be useful, but WITHOUT ANY 
 14  # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 
 15  # A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more 
 16  # details. 
 17  # 
 18  # You should have received a copy of the GNU Lesser General Public License 
 19  # along with sabx10.oxm.  If not, see <http://www.gnu.org/licenses/>. 
 20  # 
 21  ############################################################################### 
 22  """ 
 23  Overview 
 24  ======== 
 25   
 26  The C{oxm} package reads and manipulates data from files in the SABX 1.0 file 
 27  format.  It makes very heavy use of the C{ElementTree} XML handling library to 
 28  do this.  C{ElementTree} is part of Python's Standard Library and is documented 
 29  there. 
 30   
 31  The SABX 1.0 file format is described at 
 32  U{http://www.sabikerides.com/sabx/1/0/}. One thing to notice is the distinction 
 33  between ride and rideset.  A rideset is comprised of one or more rides, usually 
 34  in the same geographic area.  It may be easier to think of a ride as a route, 
 35  and remember that a you can have different routes through an area. 
 36   
 37  There are two main ways to use this package.  The first is to take a file 
 38  containing SABX data and parse it into an object hierarchy that closely 
 39  resembles the SABX XML file.  This is useful when you're manipulating the XML 
 40  files themselves.  I use this for doing things like re-numbering id's, adding 
 41  USGS elevations to a file, converting to a different format, etc...  All the 
 42  functions with "parse" in their names are primarily used for this.  The 
 43  L{sabx10.oxm.parse} module explains this more fully. 
 44   
 45  The second way to use the package is to take a file containing SABX data and 
 46  process it into a ride-centric hierarchy that gives all the pertinent 
 47  information for each ride, fleshing-out the stop, POI, turn, segment, and 
 48  parking information that is a simple reference in the file.  This way you can 
 49  very easily access the SABX data in an object hierarchy that is not as memory 
 50  efficient as the native SABX file, but which is much more logically attuned to 
 51  how you would use it for presentation.  The functions with "process" in their 
 52  names work together to accomplish this.  The L{sabx10.oxm.ride} module goes 
 53  into more detail about this. 
 54   
 55  There are also a host of auxiliary uses for this library, and the functions it 
 56  contains can typically be mixed-and-matched as necessary.  Still, by thinking 
 57  of things as "parse" vs. "process", you'll be in tune with how the library 
 58  usage has evolved over time. 
 59   
 60  It's important to know that all of the functions in this library expect 
 61  C{ElementTree} C{Element}s that have been stripped of their default namespace 
 62  information. This way they don't have to specify the whole namespace string 
 63  when querying for elements in the tree.  The function 
 64  L{sabx10.oxm.utils.parse_no_def_namespaces} handles this and should always be 
 65  used to create C{Element} representations of SABX files. 
 66   
 67  Also, make note of the fact that this library has been designed without any 
 68  consideration to memory usage or speed.  It is generally used in scripts that 
 69  are run as part of a build process and has been optimized for usability over 
 70  efficiency.  Beware of this. 
 71   
 72  By the way, the name C{oxm} is my lame attempt at humour.  I like to think of 
 73  the parsing portion of this package as an "object-XML mapper", kind of like the 
 74  "object-relational mapper (orm)" concept from the database world.  Therefore, I 
 75  coined the name C{oxm} as a take-off on the acronym C{orm}. 
 76   
 77  Copyright 
 78  ========= 
 79   
 80  The sabx10.oxm package constitutes sabx10.oxm. 
 81   
 82  sabx10.oxm - an SABX file manipulation library 
 83  Copyright (C) 2009, 2010 Jay Farrimond (jay@sabikerides.com) 
 84   
 85  sabx10.oxm is free software: you can redistribute it and/or modify it under the 
 86  terms of the GNU Lesser General Public License as published by the Free 
 87  Software Foundation, either version 3 of the License, or (at your option) any 
 88  later version. 
 89   
 90  sabx10.oxm is distributed in the hope that it will be useful, but WITHOUT ANY 
 91  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
 92  PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more 
 93  details. 
 94   
 95  You should have received a copy of the GNU Lesser General Public License along 
 96  with sabx10.oxm.  If not, see U{http://www.gnu.org/licenses/}. 
 97  """ 
 98  from geom import Point, Box 
 99  from parking import Parking 
100  from parse import parse_tree, parse_top_level, parse_history, parse_photos 
101  from poi import Poi 
102  from ride import process_rides, Ride 
103  from segment import parse_segments, Segment 
104  from stop import Stop 
105  from turn import Turn 
106  from utils import meter_feet, mile_feet, pt_dist_from_pt, VersionException, \ 
107      parse_no_def_namespaces 
108