1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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