gpxity package¶

class gpxity.Activity(gpx=None)[source]¶

Bases: object

Represents an activity.

An activity is essentially a GPX file. If a backend supports attributes not directly supported by the GPX format like the MapMyTracks activity type, they will transparently be encodeded in existing GPX fields like keywords, see keywords.

The GPX part is done by https://github.com/tkrajina/gpxpy.

If an activity is assigned to a backend, all changes will by default be written directly to the backend. Some backends are able to change only one attribute with little time overhead, others always have to rewrite the entire activity.

However you can use the context manager batch_changes(). This holds back updating the backend until leaving the context.

If you manipulate the gpx directly, this goes unnoticed. Use rewrite() when done.

Not all backends support everything, you could get the exception NotImplementedError.

Some backends are able to change only one attribute with little time overhead, others always have to rewrite the entire activity.

Parameters:	gpx (GPX) – Initial content. To be used if you create a new Activity from scratch without loading it from some backend.

The data will only be loaded from the backend when it is needed. Some backends might support loading some attributes separately, but for now, we always load everything as soon as anything is needed.

legal_whats¶: tuple(str) – The legal values for what. The first one is used as default value. This is a mostly a superset of the values for the different backends. Every backend maps from its internal values into those when reading and maps them back when writing. Since not all backends support all values defined here and since some backends may define more values than we know, information may get lost when converting, even if you copy an activity between two backends of the same type.

header_data¶: dict – The backend may only deliver some general information about activities, the full data will only be loaded when needed. This general information can help avoiding having to load the full data. The backend will fill header_data if it can. The backends are free to put additional info here. MMT does this for time, title, what and distance. You are not supposed to change header_data.

add_keyword(value: str) → None[source]¶

Adds to the comma separated keywords. Duplicate keywords are not allowed. A keyword may not contain a comma.

Parameters:	value – the keyword

add_points(points) → None[source]¶

Adds points to last segment in the last track. If no track is allocated yet and points is not an empty list, allocates a track.

Parameters:	points (list(GPXTrackPoint) – The points to be added

adjust_time(delta)[source]¶: Adds a timedelta to all times. gpxpy.gpx.adjust_time does the same but it ignores waypoints.

angle() → float[source]¶

For me, the earth is flat.

Returns:	the angle in degrees 0..360 between start and end. If we have no track, return 0

backend¶

The backend this activity lives in. If the activity was constructed in memory, backend is None.

This is a read-only property. It is set with Backend.add.

It is not possible to decouple an activity from its backend, use clone().

batch_changes()[source]¶: This context manager disables the direct update in the backend and saves the entire activity when done. This may or may not make things faster. Directory and GPSIES profits from this, MMT maybe.

clone()[source]¶

Creates a new activity with the same content but without backend.

Returns:	the new activity
Return type:	Activity

description¶: str – The description.

gpx¶

Direct access to the GPX object. If you use it to change its content, remember to call rewrite() afterwards.

Returns:	the GPX object

id_in_backend¶: Every backend has its own scheme for unique activity ids. Some backends may change the id if the activity data changes.

identifier() → str[source]¶: The full identifier with backend name and id_in_backend. As used for gpxdo.

key(with_what: bool = True) → str[source]¶

For speed optimized equality checks, not granted to be exact, but sufficiently safe IMHO.

Parameters:	with_what – If False, do not use self.what. Needed for comparing activities for equality like in unittests because values can change and information can get lost while copying between different backends
Returns:	a string with selected attributes in printable form.

keywords¶

list(str) – represents them as a sorted list - in GPX they are comma separated. Content is whatever you want.

Because the GPX format does not have attributes for everything used by all backends, we encode some of the backend arguments in keywords.

Example for mapmytracks: keywords = ‘Status:public, What:Cycling’.

However this is transparent for you. When parsing theGPX file, those are removed from keywords, and the are re-added in when exporting in to_xml(). So Activity.keywords will never show those special values.

Some backends may change keywords. MMT converts the first character into upper case and will return it like that. Gpxity will not try to hide such problems. So if you save an activity in MMT, its keywords will change. But they will not change if you copy from MMT to Directory - so if you copy from DirectoryA to MMT to DirectoryB, the keywords in DirectoryA and DirectoryB will not be identical, for example “berlin” in DirectoryA but “Berlin” in DirectoryB.

last_time¶: datetime.datetime – the last time we received so far. If none, return None.

legal_whats = ('Cycling', 'Running', 'Mountain biking', 'Indoor cycling', 'Sailing', 'Walking', 'Hiking', 'Swimming', 'Driving', 'Off road driving', 'Motor racing', 'Motorcycling', 'Enduro', 'Skiing', 'Cross country skiing', 'Canoeing', 'Kayaking', 'Sea kayaking', 'Stand up paddle boarding', 'Rowing', 'Windsurfing', 'Kiteboarding', 'Orienteering', 'Mountaineering', 'Skating', 'Skateboarding', 'Horse riding', 'Hang gliding', 'Gliding', 'Flying', 'Snowboarding', 'Paragliding', 'Hot air ballooning', 'Nordic walking', 'Snowshoeing', 'Jet skiing', 'Powerboating', 'Pedelec', 'Crossskating', 'Handcycle', 'Motorhome', 'Cabriolet', 'Coach', 'Pack animal trekking', 'Train', 'Miscellaneous')

length() → float[source]¶

For me, the earth is flat.

Returns:	the length in km

merge(other) → list[source]¶

Merge other activity into this one. The track points must be identical. If either is public, the result is public. If self.title seems like a default and other.title does not, use other.title Combine description and keywords.

Parameters:	other (`Activity`) – The activity to be merged

Returns: list(str): Messages about what has been done

static overlapping_times(activities)[source]¶

” :Yields: groups of activities with overlapping times. Sorted by time.

This may be very slow for many long activities.

parse(indata)[source]¶

Parses GPX.

title, description and what from indata have precedence over the current values. public will be or-ed

Parameters:	indata – may be a file descriptor or str

points()[source]¶

Yields:	GPXTrackPoint – all points in all tracks and segments

points_equal(other) → bool[source]¶

Returns:	True if both activities have identical points.

All points of all tracks and segments are combined. Elevations are ignored.

points_hash() → float[source]¶: A hash that is hopefully different for every possible track. It is built using the combination of all points.

public¶: bool – Is this a private activity (can only be seen by the account holder) or is it public? Default value is False

remove()[source]¶: Removes this activity in the associated backend. If the activity is not coupled with a backend, raise an Exception.

remove_keyword(value: str) → None[source]¶

Removes from the keywords.

Parameters:	value – the keyword to be removed

rewrite() → None[source]¶: Call this after you directly manipulated gpx

segments()[source]¶

Yields:	GPXTrackSegment – all segments in all tracks

time¶

datetime.datetime – start time of activity. For a simpler implementation of backends, notably MMT, we ignore gpx.time. Instead we return the time of the earliest track point. Only if there is no track point, return gpx.time. If that is unknown too, return None.

For the same reason time is readonly.

We assume that the first point comes first in time and the last point comes last in time. In other words, points should be ordered by their time.

title¶: str – The title.

to_xml() → str[source]¶: Produces exactly one line per trackpoint for easier editing (like removal of unwanted points).

track(backend=None, points=None) → None[source]¶

Life tracking.

If this activity belongs to a backend supporting life tracking:

points is None: Stop life tracking
if life tracking is not active, start it and send all points already known in this activity. The backend may change id_in_backend.
if life tracking was already active, just send the new points.

MMT supports simultaneous life tracking for only one activity per account, others may support more.

For backends not supporting life tracking, the points are simply added.

Parameters:	backend – The backend which should track this Activity. Only pass this when you start tracking. points (list(GPXTrackPoint) – The points to be added

what¶

str – What is this activity doing? If we have no current value, return the default.

The value is automatically translated between our internal value and the value used by the backend. This happens when reading from or writing to the backend. :returns: The current value or the default value (see legal_whats)

class gpxity.Directory(url=None, auth=None, cleanup=False, debug=False, prefix: str = None)[source]¶

Bases: gpxity.backend.Backend

Uses a directory for storage. The filename minus the .gpx ending is used as the activity id. If the activity has a title, use the title as storage id, making it unique by attaching a number if needed. An activity without title gets a random name.

The main directory (given by Directory.url) will have subdirectories YYYY/MM (year/month) with only the activities for one month. Those are symbolic links to the main file and have the same file name.

If save() is given a value for ident, this is used as id, the file name will be id.gpx. Otherwise, this backend uses Activity.title for the id. If an activity has no title, it uses a random sequence of characters. Changing the title also changes the id.

Parameters:

url (str) – a directory. If no Url is given, either here or through auth, use a unique temporary directory named prefix.X where X are some random characters. If the directory does not exist, it is created.
auth (str) – You can use this as in every backend to define Url= in auth.cfg
cleanup (bool) – If True, destroy() will remove all activities. If url was not given, it will also remove the directory.
prefix – The prefix for a temporary directory path. Must not be given if url is given.

prefix¶: str – Class attribute, may be changed. The default prefix for temporary directories. Default value is gpxity.

fs_encoding¶: str – The encoding for file system names. By default, we expect the file system being able to handle arbitrary UTF-8 encoded names except character ‘/’ and special names ‘.’ and ‘..’. If needed, we will introduce new possible values for fs_encoding like perhaps ‘windows’. Gpxity will never support any other character set but UTF-8. Note that fs_encoding is independent of the platform we are running on - we might use a network file system.

is_temporary¶: bool – True if no Url was given and we created a temporary directory

decode_what(value: str) → str[source]¶: Not needed for directory, this is always the internal value.

destroy()[source]¶: If cleanup was set at init time, removes all activities. If url was set at init time, also removes the directory.

encode_what(value: str) → str[source]¶: Not needed for directory, this is always the internal value.

get_time() → datetime.datetime[source]¶: get server time as a Linux timestamp

gpx_path(ident)[source]¶: The full path name for the local copy of an activity

legal_whats¶: Returns – list(str) all legal values for what for this backend.

prefix = 'gpxity.'

supported = {'remove', '_write_all', 'get_time'}¶

class gpxity.GPSIES(url=None, auth=None, cleanup=False, debug=False, timeout=None)[source]¶

Bases: gpxity.backend.Backend

The implementation for gpsies.com. The activity ident is the fileId given by gpsies.

Searching arbitrary tracks is not supported. GPSIES only looks at the tracks of a specific user.

Parameters:	url (str) – The Url of the server. Default is https://gpsies.com auth (tuple(str, str)) – Username and password cleanup (bool) – If True, `destroy()` will remove all activities in the user account. timeout – If None, there are no timeouts: Gpxity waits forever. For legal values see http://docs.python-requests.org/en/master/user/advanced/#timeouts

decode_what(value: str) → str[source]¶: Translate the value from Gpsies into internal one.

destroy()[source]¶: also close session

encode_what(value: str) → str[source]¶: Translate internal value into Gpsies value

legal_whats¶: Returns – list(str) all legal values for what.

session¶: The requests.Session for this backend. Only initialized once.

supported = {'remove', '_write_title', '_write_description', '_write_what', '_write_public', '_write_all'}¶

class gpxity.MMT(url=None, auth=None, cleanup=False, debug=False, timeout=None)[source]¶

Bases: gpxity.backend.Backend

The implementation for MapMyTracks. The activity ident is the number given by MapMyTracks.

MMT knows tags. We map Activity.keywords to MMT tags. MMT will change keywords: It converts the first character to upper case. See Activity.keywords for how Gpxity handles this.

Parameters:	url (str) – The Url of the server. Default is http://mapmytracks.com auth (tuple(str, str)) – Username and password cleanup (bool) – If True, `destroy()` will remove all activities in the user account. timeout: If None, there are no timeouts: Gpxity waits forever. For legal values see http://docs.python-requests.org/en/master/user/advanced/#timeouts

decode_what(value: str) → str[source]¶: Translate the value from MMT into internal one. Since gpxity once decided to use MMT definitions for activities, this should mostly be 1:1 here.

destroy()[source]¶: also close session

encode_what(value: str) → str[source]¶: Translate internal value into MMT value

get_time() → datetime.datetime[source]¶: get MMT server time

legal_whats¶: Returns – list(str) all legal values for what.

mid¶: the member id on MMT belonging to auth

override_ident(ident: str)[source]¶: Temporarily override the activity ident. While this is active, only the one activity meant must be used.

session¶: The requests.Session for this backend. Only initialized once.

supported = {'remove', 'track', '_write_title', '_write_description', '_write_add_keyword', '_write_keywords', '_write_what', 'get_time', '_write_public', '_write_remove_keyword', '_write_all'}¶

class gpxity.TrackMMT(url=None, auth=None, cleanup=False, debug=False, timeout=None)[source]¶

Bases: gpxity.backends.mmt.MMT

This is a minimal implementation, it only supports listing and retrieving activities and life tracking. This is used for testing examples/mmtserver.py which in turn is used to receive life tracking data from smartphone apps like oruxmaps.

session¶

supported = {'track', '_write_all', 'get_time'}¶

class gpxity.ServerDirectory(url=None, auth=None, cleanup=False, debug=False, prefix: str = None)[source]¶

Bases: gpxity.backends.directory.Directory

Like Directory but the activity ids are different: Just a number. A new id is generated by adding 1 to the highest existing id.

The symbolic links per YYYY/MM use the title of the activity as link name.

skip_test = True¶

supported = {'remove', '_write_all', 'get_time'}¶

class gpxity.BackendDiff(left, right, key=None, right_key=None)[source]¶

Bases: object

Compares two backends.directory

Parameters:

left (Backend) – A backend
right (Backend) – The other one
key – A lambda which does the comparison. Default is the start time: key=lambda x: x.time
right_key – Default is key. If given, this will be used for activities from right. This allows things like BackendDiff(b1, b2, key_right = lambda x: x.time + hours2) where hours2 is a timedelta of two hours. If your GPX data has a problem with the time zone, this lets you find activities differring only by exactly 2 hours.

left¶: BackendDiffSide – Attributes for the left side

right¶: BackendDiffSide – Attributes for the right side

keys_in_both¶: list – keys appearing on both sides.

matches¶: list – For every keys_in_both, this lists all matching activities from both sides

class BackendDiffSide(backend, key_lambda=None)[source]¶

Bases: object

Represents a backend in BackendDiff.

backend¶: The backend

key_lambda¶: The used lambda for calculating the key values

entries¶: dict – keys are what key_lambda calculates. values are lists of matching activities

exclusive¶: dict – keys with corresponding activity lists for activities existing only on this side

Subpackages¶

gpxity.backends package

Submodules¶

gpxity.activity module¶

This module defines Activity

class gpxity.activity.Activity(gpx=None)[source]¶

Bases: object

Represents an activity.

An activity is essentially a GPX file. If a backend supports attributes not directly supported by the GPX format like the MapMyTracks activity type, they will transparently be encodeded in existing GPX fields like keywords, see keywords.

The GPX part is done by https://github.com/tkrajina/gpxpy.

If an activity is assigned to a backend, all changes will by default be written directly to the backend. Some backends are able to change only one attribute with little time overhead, others always have to rewrite the entire activity.

However you can use the context manager batch_changes(). This holds back updating the backend until leaving the context.

If you manipulate the gpx directly, this goes unnoticed. Use rewrite() when done.

Not all backends support everything, you could get the exception NotImplementedError.

Some backends are able to change only one attribute with little time overhead, others always have to rewrite the entire activity.

Parameters:	gpx (GPX) – Initial content. To be used if you create a new Activity from scratch without loading it from some backend.

The data will only be loaded from the backend when it is needed. Some backends might support loading some attributes separately, but for now, we always load everything as soon as anything is needed.

legal_whats¶: tuple(str) – The legal values for what. The first one is used as default value. This is a mostly a superset of the values for the different backends. Every backend maps from its internal values into those when reading and maps them back when writing. Since not all backends support all values defined here and since some backends may define more values than we know, information may get lost when converting, even if you copy an activity between two backends of the same type.

header_data¶: dict – The backend may only deliver some general information about activities, the full data will only be loaded when needed. This general information can help avoiding having to load the full data. The backend will fill header_data if it can. The backends are free to put additional info here. MMT does this for time, title, what and distance. You are not supposed to change header_data.

add_keyword(value: str) → None[source]¶

Adds to the comma separated keywords. Duplicate keywords are not allowed. A keyword may not contain a comma.

Parameters:	value – the keyword

add_points(points) → None[source]¶

Adds points to last segment in the last track. If no track is allocated yet and points is not an empty list, allocates a track.

Parameters:	points (list(GPXTrackPoint) – The points to be added

adjust_time(delta)[source]¶: Adds a timedelta to all times. gpxpy.gpx.adjust_time does the same but it ignores waypoints.

angle() → float[source]¶

For me, the earth is flat.

Returns:	the angle in degrees 0..360 between start and end. If we have no track, return 0

backend¶

The backend this activity lives in. If the activity was constructed in memory, backend is None.

This is a read-only property. It is set with Backend.add.

It is not possible to decouple an activity from its backend, use clone().

batch_changes()[source]¶: This context manager disables the direct update in the backend and saves the entire activity when done. This may or may not make things faster. Directory and GPSIES profits from this, MMT maybe.

clone()[source]¶

Creates a new activity with the same content but without backend.

Returns:	the new activity
Return type:	Activity

description¶: str – The description.

gpx¶

Direct access to the GPX object. If you use it to change its content, remember to call rewrite() afterwards.

Returns:	the GPX object

id_in_backend¶: Every backend has its own scheme for unique activity ids. Some backends may change the id if the activity data changes.

identifier() → str[source]¶: The full identifier with backend name and id_in_backend. As used for gpxdo.

key(with_what: bool = True) → str[source]¶

For speed optimized equality checks, not granted to be exact, but sufficiently safe IMHO.

Parameters:	with_what – If False, do not use self.what. Needed for comparing activities for equality like in unittests because values can change and information can get lost while copying between different backends
Returns:	a string with selected attributes in printable form.

keywords¶

list(str) – represents them as a sorted list - in GPX they are comma separated. Content is whatever you want.

Because the GPX format does not have attributes for everything used by all backends, we encode some of the backend arguments in keywords.

Example for mapmytracks: keywords = ‘Status:public, What:Cycling’.

However this is transparent for you. When parsing theGPX file, those are removed from keywords, and the are re-added in when exporting in to_xml(). So Activity.keywords will never show those special values.

Some backends may change keywords. MMT converts the first character into upper case and will return it like that. Gpxity will not try to hide such problems. So if you save an activity in MMT, its keywords will change. But they will not change if you copy from MMT to Directory - so if you copy from DirectoryA to MMT to DirectoryB, the keywords in DirectoryA and DirectoryB will not be identical, for example “berlin” in DirectoryA but “Berlin” in DirectoryB.

last_time¶: datetime.datetime – the last time we received so far. If none, return None.

legal_whats = ('Cycling', 'Running', 'Mountain biking', 'Indoor cycling', 'Sailing', 'Walking', 'Hiking', 'Swimming', 'Driving', 'Off road driving', 'Motor racing', 'Motorcycling', 'Enduro', 'Skiing', 'Cross country skiing', 'Canoeing', 'Kayaking', 'Sea kayaking', 'Stand up paddle boarding', 'Rowing', 'Windsurfing', 'Kiteboarding', 'Orienteering', 'Mountaineering', 'Skating', 'Skateboarding', 'Horse riding', 'Hang gliding', 'Gliding', 'Flying', 'Snowboarding', 'Paragliding', 'Hot air ballooning', 'Nordic walking', 'Snowshoeing', 'Jet skiing', 'Powerboating', 'Pedelec', 'Crossskating', 'Handcycle', 'Motorhome', 'Cabriolet', 'Coach', 'Pack animal trekking', 'Train', 'Miscellaneous')

length() → float[source]¶

For me, the earth is flat.

Returns:	the length in km

merge(other) → list[source]¶

Merge other activity into this one. The track points must be identical. If either is public, the result is public. If self.title seems like a default and other.title does not, use other.title Combine description and keywords.

Parameters:	other (`Activity`) – The activity to be merged

Returns: list(str): Messages about what has been done

static overlapping_times(activities)[source]¶

” :Yields: groups of activities with overlapping times. Sorted by time.

This may be very slow for many long activities.

parse(indata)[source]¶

Parses GPX.

title, description and what from indata have precedence over the current values. public will be or-ed

Parameters:	indata – may be a file descriptor or str

points()[source]¶

Yields:	GPXTrackPoint – all points in all tracks and segments

points_equal(other) → bool[source]¶

Returns:	True if both activities have identical points.

All points of all tracks and segments are combined. Elevations are ignored.

points_hash() → float[source]¶: A hash that is hopefully different for every possible track. It is built using the combination of all points.

public¶: bool – Is this a private activity (can only be seen by the account holder) or is it public? Default value is False

remove()[source]¶: Removes this activity in the associated backend. If the activity is not coupled with a backend, raise an Exception.

remove_keyword(value: str) → None[source]¶

Removes from the keywords.

Parameters:	value – the keyword to be removed

rewrite() → None[source]¶: Call this after you directly manipulated gpx

segments()[source]¶

Yields:	GPXTrackSegment – all segments in all tracks

time¶

datetime.datetime – start time of activity. For a simpler implementation of backends, notably MMT, we ignore gpx.time. Instead we return the time of the earliest track point. Only if there is no track point, return gpx.time. If that is unknown too, return None.

For the same reason time is readonly.

We assume that the first point comes first in time and the last point comes last in time. In other words, points should be ordered by their time.

title¶: str – The title.

to_xml() → str[source]¶: Produces exactly one line per trackpoint for easier editing (like removal of unwanted points).

track(backend=None, points=None) → None[source]¶

Life tracking.

If this activity belongs to a backend supporting life tracking:

points is None: Stop life tracking
if life tracking is not active, start it and send all points already known in this activity. The backend may change id_in_backend.
if life tracking was already active, just send the new points.

MMT supports simultaneous life tracking for only one activity per account, others may support more.

For backends not supporting life tracking, the points are simply added.

Parameters:	backend – The backend which should track this Activity. Only pass this when you start tracking. points (list(GPXTrackPoint) – The points to be added

what¶

str – What is this activity doing? If we have no current value, return the default.

The value is automatically translated between our internal value and the value used by the backend. This happens when reading from or writing to the backend. :returns: The current value or the default value (see legal_whats)

gpxity.auth module¶

This module defines Authenticate

class gpxity.auth.Authenticate(cls, username: str = None)[source]¶

Bases: object

Get password and / or Url from auth.cfg. If nothing is useable, sets them to None.

auth.cfg is expected in ~/.config/Gpxity/auth.cfg

Danger

auth.cfg is not encrypted. Better not use this unless you know what you are doing!

Parameters:	cls (Backend) – The class of the backend username (str) – For the wanted account in the backend

auth¶: tuple(str,str) – (username, password). Both are either str or None.

url¶: If given, overrides the url given to the backend

For every specific account in a backend, auth.cfg has a section:

[ClassName.username]

A section can define

Password
Url

An example for user gpxitytest on gpsies.com:

[GPSIES:gpxitytest]
Password = the_unencrypted_password

gpxity.backend module¶

This module defines Backend

class gpxity.backend.Backend(url: str = None, auth=None, cleanup: bool = False, debug: bool = False, timeout=None)[source]¶

Bases: object

A place where activities live. Something like the filesystem or http://mapmytracks.com.

A Backend should hold only activities for one person, and they should not overlap in time. This is not enforced but sometimes behaviour is undefined if you ignore this.

A Backend be used as a context manager. Upon termination, all activities may be removed automatically by setting cleanup=True. Some concrete implementations may also remove the backend itself.

A Backend allows indexing by normal int index, by Activity and by Activity.id_in_backend. if 'ident' in backend is possible. len(backend) shows the number of activities. Please note that Code like if backend: may not behave as expected. This will be False if the backend has no activity. If that is not what you want, consider if backend is not None

The backend will automatically synchronize. So something like len(Backend()) will work. However, some other Backend pointing to the same storage or even a different process might change things. If you want to cope with that, use scan().

Not all backends support all methods. The unsupported methods will raise NotImplementedError. As a convenience every backend has a list supported to be used like if 'track' in backend.supported: where track is the name of the method.

Backends support no locking. If others modify a backend concurrently, you may get surprises. It is up to you to handle those.

Some backends may use cookies.

Parameters:	url (str) – Initial value for `url` auth (tuple(str, str)) – (username, password). Alternatively you can pass the username as a single string. This will lookup the password from `Authenticate`. cleanup (bool) – If true, `destroy()` will remove all activities.

supported¶: set(str) – The names of supported methods. Creating the first instance of the backend initializes this. Only methods which may not be supported are mentioned here. Those are: remove, track, get_time, _write_title, _write_public, _write_what, _write_gpx, _write_description, _write_keywords, _write_add_keyword, _write_remove_keyword. If a particular _write_* like _write_public does not exist, the entire activity is written instead which normally results in a new ident for the activity.

url¶: str – the address. May be a real URL or a directory, depending on the backend implementation. Every implementation may define its own default for url.

debug¶: If True, print debugging information

timeout¶: If None, there are no timeouts: Gpxity waits forever. For legal values see http://docs.python-requests.org/en/master/user/advanced/#timeouts

exception BackendException[source]¶

Bases: Exception

Is raised for general backend exceptions, especially error messages from a remote server

exception NoMatch[source]¶

Bases: Exception

Is raised if an activity is expected to pass the match filter but does not

add(activity, ident: str = None)[source]¶

We do not check if it already exists in this backend. No activity already existing in this backend will be overwritten, the id_in_backend of activity will be deduplicated if needed. This is currently only needed for Directory.

If the activity does not pass the current match function, raise an exception.

Parameters:	activity (Activity) – The activity we want to save in this backend. ident – If given, a backend may use this as id_in_backend. `Directory` might but it will prefer the id_in_backend the activity might already have. Other backends always create their own new unique identifier when the full activity is saved/uploaded. attributes (set(str)) – If given and the backend supports specific saving for all given attributes, save only those. Otherwise, save the entire activity.
Returns:	The saved activity. If the original activity lives in a different backend, a new activity living in this backend will be created and returned.
Return type:	Activity

debug: True – output HTTP debugging data to stdout

decode_what(value: str) → str[source]¶: Translate the value from the backend into internal one.

destroy()[source]¶: If cleanup was set at init time, removes all activities. Some backends (example: Directory) may also remove the account (or directory). See also remove_all().

encode_what(value: str) → str[source]¶: Translate internal value into the backend specific value.

get_time() → datetime.datetime[source]¶: get time from the server where backend is located as a Linux timestamp. A backend implementation does not have to support this.

legal_whats¶: Returns – list(str) all legal values for this backend

match¶

A function with one argument returning None or str. The backend will call this with every activity and ignore activities where match does not return None. The returned str should explain why the activity does not match.

If you change an activity such that it does not match anymore, the exception NoMatch will be raised and the match stays unchanged.

matches(activity, exc_prefix: str = None)[source]¶

Does activity match the current match function?

Parameters:	exc_prefix – If not None, use it for the beginning of an exception message. If None, never raise an exception

merge(other, remove: bool = False) → list[source]¶

merge other backend into this one. If two activities have identical points, or-ify their other attributes. :param remove: If True, remove merged activities

Returns: list(str) A list of messages for verbose output

real_len()[source]¶: len(backend) without calling scan() first

remove(value) → None[source]¶

Removes activity. This can also be done for activities not passing the current match function.

Parameters:	value – If it is not an `Activity`, `remove()` looks it up by doing `self[value]`

remove_all()[source]¶

Removes all activities we know about. If their id_in_backend has meanwhile been changed through another backend instance or another process, we cannot find it anymore. We do not rescan all activities in the backend. If you want to make sure it will be empty, call scan() first.

If you use a match function, only matching activities will be removed.

scan(now: bool = False) → None[source]¶

Enforces a reload of the list of all activities in the backend. This will be delayed until the list is actually needed again.

If this finds an unsaved activity not matching the current match function, an exception is thrown. Saved Activities not matching the current match will no be loaded.

Parameters:	now – If True, do not delay scanning.

supported = None

class gpxity.backend.BackendDiff(left, right, key=None, right_key=None)[source]¶

Bases: object

Compares two backends.directory

Parameters:

left (Backend) – A backend
right (Backend) – The other one
key – A lambda which does the comparison. Default is the start time: key=lambda x: x.time
right_key – Default is key. If given, this will be used for activities from right. This allows things like BackendDiff(b1, b2, key_right = lambda x: x.time + hours2) where hours2 is a timedelta of two hours. If your GPX data has a problem with the time zone, this lets you find activities differring only by exactly 2 hours.

left¶: BackendDiffSide – Attributes for the left side

right¶: BackendDiffSide – Attributes for the right side

keys_in_both¶: list – keys appearing on both sides.

matches¶: list – For every keys_in_both, this lists all matching activities from both sides

class BackendDiffSide(backend, key_lambda=None)[source]¶

Bases: object

Represents a backend in BackendDiff.

backend¶: The backend

key_lambda¶: The used lambda for calculating the key values

entries¶: dict – keys are what key_lambda calculates. values are lists of matching activities

exclusive¶: dict – keys with corresponding activity lists for activities existing only on this side

gpxity package¶

Subpackages¶

Submodules¶

gpxity.activity module¶

gpxity.auth module¶

gpxity.backend module¶

Table Of Contents

Related Topics

This Page