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 (str) – Username for gaiagps.com password (str) – Password for gaiagps.com cookies (http.cookiejar.CookieJar) – A cookie jar 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 (str) – The id if the folder in question objtype (str) – The type of the object to add objid (str) – The id of the object to add
Returns:	The updated folder description
Return type:	dict

create_object(objtype, objdata)¶

Create an object.

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

delete_object(objtype, id_)¶

Delete an object by id.

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

get_access(folderid)¶

Get access information for a folder.

Parameters:	folderid (str) – The id of the folder
Returns:	A list of API access objects for the folder
Return type:	list
Raises:	RuntimeError – if the server refuses to list accesses

get_invites(folderid)¶

Get invite information for a folder.

Parameters:	folderid (str) – The id of the folder
Returns:	A list of API invite objects for the folder
Return type:	list
Raises:	RuntimeError – if the server refuses to list invites

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 (str) – The name of the object id (str) – The id of the object fmt (str) – Optional format (`'gpx'` or `'kml'`)
Returns:	The waypoint data structure, or raw content if format is specified
Return type:	dict or bytes
Raises:	NotFound – if no folder by the given name is found RuntimeError – if more than one folder exists with the name

get_photo(photoid, size='fullsize')¶

Get the image contents of a photo by id.

Parameters:	photoid (str) – The id of the photo size (str) – The size of the image (one of `fullsize`, `scaled`, or `thumbnail`.
Returns:	A tuple of content-type and the bytes content of the photo
Return type:	tuple (str, bytes)

list_objects(objtype, archived=True)¶

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 (str) – The type of object to be listed archived (bool) – If `True`, archived objects will be included
Returns:	A list of objects
Return type:	list

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 (str) – The type of object to be found (waypoint, track, etc) name (str) – The name of the object to be found
Returns:	An object description
Return type:	dict
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 (str) – The type of object to be updated objdata (dict) – The exact raw object structure
Returns:	The resulting object, if successful, else `None`
Return type:	dict

remove_object_from_folder(folderid, objtype, objid)¶

Removes an object from a folder.

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

set_objects_archive(objtype, ids, archive=False)¶

Control archive (sync) status on a set of objects.

Parameters:	objtype (str) – The type of object to change ids (str) – A list of object IDs archive (bool) – `True` if the object should be archived
Returns:	`True` on success, `False` otherwise
Return type:	bool
Raises:	RuntimeError – if the server refused to provide the image NotFound – if the server reports the image does not exist

test_auth()¶

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

Returns:	`True` if we are already logged in
Return type:	bool

upload_file(filename)¶

Upload a file by name.

Parameters:	filename (str) – 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()`. None is returned if the server reports that the upload was queued for processing.
Return type:	dict

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¶

class gaiagps.util.ThingFormatter(thing)¶

Bases: object

Format helper for GaiaGPS objects.

This is intended to digest an object from the API and provide a relatively safe dict-like formatting object for strings.

Example usage:

obj = client.get_object( … ) fmt = ThingFormatter(obj) print(‘%(title)s’ % fmt)

Parameters:	thing (dict) – An object from the GaiaGPS API as returned from `GaiaClient`

format_altitude()¶: The altitude (elevation)

format_created()¶: The “time_created” datestamp

format_id()¶: The internal GaiaGPS identifier

format_public()¶: The “public” or “private” status

format_title()¶: The title or name

format_updated()¶: The “updated_date” datestamp

keys¶: A list of keys we definitely support for formatting

gaiagps.util.date_parse(thing, property_name='time_created')¶

Parse a local datetime from a thing with a datestamp.

This attempts to find a datestamp in an object and parse it for use in the local timezone.

Something like this is required:

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

Parameters:	thing (dict) – A raw object from the API
Returns:	A localized tz-aware datetime or None if no datestamp is found.
Return type:	`datetime.datetime`

gaiagps.util.datefmt(thing, property_name='time_created')¶

Nicely format a thing with a datestamp.

See date_parse() for more information.

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

gaiagps.util.get_editor()¶

Return a path to an editor command, if possible.

Returns:	Path to an editor command or None if one is not found

gaiagps.util.get_track_colors_from_gpx(source_file)¶

Return a dict of track names and colors from a GPX file.

Parameters:	source_file (str) – Source GPX filename
Returns:	Dict of name:color

gaiagps.util.is_id(idstr)¶

Detect if a string is likely an API identifier

Parameters:	idstr (str) – An ID string to be examined
Returns:	`True` if the string is an identifier, `False` otherwise
Return type:	bool

gaiagps.util.make_folder(name)¶

Make a folder object.

This returns an object suitable for sending to the API.

Parameters:	name (str) – A `str` representing the folder name
Returns:	A `dict` object
Return type:	dict

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 (list) – A flat `list` of folders like you get from `list_objects()`
Returns:	A hierarchical `dict` of folders
Return type:	dict

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

Make a raw waypoint object.

This returns an object suitable for sending to the API.

Parameters:	lat (float) – A `float` representing latitude lon (float) – A `float` representing longitude alt (float) – A `float` representing altitude in meters notes (str) – A `str` representing the notes field icon (str) – A `str` representing the icon (one of the values supported by gaiagps, for example `blue-pin-down.png`)
Returns:	A `dict` object
Return type:	dict

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, long=False)¶

Print a tree of folder contents.

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

Parameters:	folder (dict) – A folder tree root from `resolve_tree()` indent (int) – 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 (GaiaClient) – An instance of `GaiaClient` folder (dict) – A root folder of a hierarchical tree from `make_tree()`
Returns:	A hierarchical tree of full folder definitions.
Return type:	dict

gaiagps.util.strip_gpx_extensions(source_file, dest_file)¶

Strip any GPX extensions from a file.

Remove any GPX extensions from source_file and write the result to dest_file.

Parameters:	source_file (str) – Source filename dest_file (str) – Destination filename
Raises:	Exception – If the source file is not a GPX file

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 an altitude

Only meters are supported

Parameters:	alt (str) – An altitude string
Returns:	An altitude
Return type:	float
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 (str) – A latitude string
Returns:	A latitude
Return type:	float
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 (str) – A longitude string
Returns:	A longitude
Return type:	float
Raises:	ValueError – If the longitude is not parseable or within constraints