Python API Documentation¶

gaiagps.apiclient module¶

exception gaiagps.apiclient.AuthFailure¶

Bases: Exception

Indicates that login to gaiagps.com was not possible.

class gaiagps.apiclient.GaiaClient(username, password, cookies=None)¶

Bases: object

A low-level client for gaiagps.com.

Initialize and login (if necessary) to gaiagps.com. If a cookiejar is provided and the session stored within is still active, login credentials are not used.

Parameters:	username – Username for gaiagps.com password – Password for gaiagps.com cookies – A `http.cookiejar.CookieJar` or `None`
Raises:	AuthFailure – if login fails RuntimeError – if session is stale and credentials are not provided

add_object_to_folder(folderid, objtype, objid)¶

Adds an object to a folder.

Parameters:	folderid – The id if the folder in question objtype – The type of the object to add objid – The id of the object to add
Returns:	The updated folder description

create_object(objtype, objdata)¶

Create an object.

Parameters:	objtype – The type of object to create (waypoint, track, etc) objdata – The exact raw object structure
Returns:	The resulting object, if successful, else None

delete_object(objtype, id_)¶

Delete an object by id.

Parameters:	objtype – The type of object to delete id – The id of the object to delete

get_object(objtype, name=None, id_=None, fmt=None)¶

Return an object data structure by name or id.

Fetches an object and returns the raw data structure. If provided, id_ takes precedence over name.

Parameters:	name – The name of the object id – The id of the object fmt – Optional format (`'gpx'` or `'kml'`)
Returns:	The waypoint data structure, or a `bytes()` if format is specified
Raises:	NotFound – if no folder by the given name is found RuntimeError – if more than one folder exists with the name

list_objects(objtype)¶

Returns a list of object descriptions.

This is similar to the result of get_object(), but with object references instead of full objects.

Parameters:	objtype – The type of object to be listed
Returns:	A list of objects

login()¶

Login with our credentials.

There is usually no need to call this directly, as it will be called from init when necessary.

Raises:	AuthFailure – if login is not possible

lookup_object(objtype, name)¶

Lookup a single object by name.

This returns an object description like what you get in list_objects(), filtering by name. If more than one object with the specified name is found, an error is raised.

Parameters:	objtype – The type of object to be found (waypoint, track, etc) name – The name of the object to be found
Returns:	An object description
Raises:	RuntimeError – When multiple objects by the same name are found NotFound – When no object by the given name is found

put_object(objtype, objdata)¶

Update an object.

Parameters:	objtype – The type of object to be updated objdata – The exact raw object structure
Returns:	The resulting object, if successful, else `None`

remove_object_from_folder(folderid, objtype, objid)¶

Removes an object from a folder.

Parameters:	folderid – The id of the folder in question objtype – The type of the object to remove objid – The id of the object to remove
Returns:	The updated folder description

test_auth()¶

Test the session to see if we are successfully logged in.

Returns:	True if we are already logged in

upload_file(filename)¶

Upload a file by name.

Parameters:	filename – The local filename to upload
Returns:	The resulting folder object that is created to hold the contents of the file, as you would get from `get_object()`.

exception gaiagps.apiclient.NotFound¶

Bases: Exception

Indicates that an identified item could not be found.

gaiagps.apiclient.find(iterable, key, value)¶

Find exactly one item in iterable for which key equals value.

Parameters:	iterable – Items to search key – The key to match value – The value to match
Raises:	NotFound – If a match is not found RuntimeError – If multiple matches are found

gaiagps.apiclient.gurl(*sub)¶

Build a gaiagps.com url from components.

Ensure that the resulting URL ends in a slash and that none of the sub elements that have a slash cause duplicates.

gaiagps.apiclient.match(iterable, key, pattern)¶

Find items in iterable where key matches pattern.

Parameters:	iterable – Items to search key – The key to match pattern – A regular expression to use for matching
Returns:	A list of objects that match

gaiagps.util module¶

gaiagps.util.datefmt(thing)¶

Nicely format a thing with a datestamp.

This attempts to find a datestamp in an object, parse, and format it for display. Something like this is required:

{'id': '1234', 'title': 'Foo', 'time_created': '2019-01-01T10:11:12Z'}

Parameters:	thing – A `dict` raw object from the API.
Returns:	A nicely-formatted date string, or `'?'` if none is found or is parseable

gaiagps.util.is_id(idstr)¶

Detect if a string is likely an API identifier

Parameters:	idstr – A `str` to be examined
Returns:	`True` if the string is an identifier, `False` otherwise

gaiagps.util.make_folder(name)¶

Make a folder object.

This returns an object suitable for sending to the API.

Parameters:	name – A `str` representing the folder name
Returns:	A `dict` object

gaiagps.util.make_tree(folders)¶

Creates a hierarchical structure of folders.

This takes a flat list of folder objects and returns a nested dict with subfolders inside their parent’s subfolders key. A new root folder structure is at the top, with a name of /.

Parameters:	folders – A flat `list` of folders like you get from `list_objects()`
Returns:	A hierarchical `dict` of folders

gaiagps.util.make_waypoint(name, lat, lon, alt=0)¶

Make a raw waypoint object.

This returns an object suitable for sending to the API.

Parameters:	lat – A `float` representing latitude lon – A `float` representing longitude alt – A `float` representing altitude in meters
Returns:	A `dict` object

gaiagps.util.name_sort(iterable)¶

Return a sorted list of items by name.

Parameters:	iterable – Items to sort
Returns:	Items in name sort order

gaiagps.util.pprint_folder(folder, indent=0)¶

Print a tree of folder contents.

This prints a pseudo-filesystem view of a folder tree to the console.

Parameters:	folder – A folder tree root from `resolve_tree()` indent – Number of spaces to indent the first level

gaiagps.util.resolve_tree(client, folder)¶

Walk the tree and flesh out folders with waypoint/track data.

This takes a hierarchical folder tree from make_tree() and replaces the folder descriptions with full definitions, as you would get from get_object().

Parameters:	client – An instance of `GaiaClient` folder – A root folder of a hierarchical tree from `make_tree()`
Returns:	A hierarchical tree of full folder definitions.

gaiagps.util.title_sort(iterable)¶

Return a sorted list of items by title.

Parameters:	iterable – Items to sort
Returns:	Items in title sort order

gaiagps.util.validate_alt(alt)¶

Validate and normalize a latitude

Only meters are supported

Parameters:	alt – A `str` altitude
Returns:	A `float` representing the altitude
Raises:	ValueError – If the altitude is not parseable or within constraints

gaiagps.util.validate_lat(lat)¶

Validate and normalize a latitude

Only decimal degrees is supported

Parameters:	lat – A `str` latitude
Returns:	A `float` representing the latitude
Raises:	ValueError – If the latitude is not parseable or within constraints

gaiagps.util.validate_lon(lon)¶

Validate and normalize a longitude

Only decimal degrees is supported

Parameters:	lon – A `str` longitude
Returns:	A `float` representing the longitude
Raises:	ValueError – If the longitude is not parseable or within constraints