sgraaf / gpx

A python package that brings support for reading, writing and converting GPX files.

PyGPX

PyGPX is a Python package that brings support for reading, writing and converting GPX files.

Installation

From PyPI

PyGPX is available on PyPI. Install with pip or your package manager of choice:

pip install gpx

From source

If you'd like, you can also install PyGPX from source (with flit):

git clone https://github.com/sgraaf/gpx.git
cd gpx
python3 -m pip install flit
flit install

Documentation

Check out the PyGPX documentation for the User's Guide and API Reference.

Usage

Reading a GPX file

>>> from gpx import GPX
>>> # read the GPX data from file
>>> gpx = GPX.from_file("path/to/file.gpx")
>>> # print the bounds of the GPX data
>>> print(gpx.bounds)

Manipulating GPX data

>>> from gpx import Waypoint
>>>
>>> # delete the last waypoint
>>> del gpx.waypoints[-1]
>>>
>>> # add a new waypoint
>>> wpt = Waypoint()
>>> wpt.latitude = 52.123
>>> wpt.longitude = 4.123
>>> gpx.waypoints.append(wpt)

Writing a GPX file

>>> # write the GPX data to a file
>>> gpx.to_file("path/to/file.gpx")

gpx's Issues

Format docstrings

Automatically format docstrings with docformatter, possibly via a pre-commit hook.

Drop support for Python 3.7

Python 3.7 has gone end-of-life (EOL) on 27 June 2023 (https://endoflife.date/python).

Make PyGPX fully compatible with the GPX 1.1 specification

Make PyGPX fully compatible with the the GPX 1.1 specification

This involves introducing new type and element classes and using these where applicable, according to the specification.

Add additional statistics

Add additional statistics (beside the current distance and total duration), such as:

• "Time in motion" / moving type
• Speed (average and profile)
• Elevation (ascent & descent and profile)

Add conversion methods for other file formats

Add conversion methods (to and from) for other file formats, such as:

• GeoJSON
• Keyhole Markup Language (KML), possibly including KMZ

Dependency Issue: LXML has no M1 Mac Support

Just an FYI for other who end up here ...
https://bugs.launchpad.net/lxml/+bug/1913032

Refactor using `cookiecutter-python-package`

Refactor the PyGPX repository using my cookiecutter-python-package project template.

When fully implemented, this will bring about the following improvements:

• Linting with autofix (i.e. removing unused imports, formatting and Python syntax upgrades) with ruff
• Code formatting with Black and Prettier
• Static type-checking with mypy
• Testing with pytest
• Continuous Integration with GitHub Actions
• Documentation with Sphinx, MyST, and Read the Docs using the Furo theme
• Automated release builds and uploads to PyPI

Add an I/O interface / module

Add an I/O interface / module similar to that of pandas.

Import/Export of kml

Hello,
Would it be possible to add support for exporting/importing KML files?
Regards,
Jacques-D:

Mutable default values shared by class instances

Some classes have fields with mutable value (e.g. lists), which are assigned a default value (e.g. empty list). If you have several instances of such a class, they each share the default values.

See the following example for illustration:

my_track_seg = TrackSegement()

my_track_a = Track()
my_track_b = Track()

# Add track segment to track A.
my_track_a.trksegs.append(my_track_seg)

# Because all instances of Track share the same mutable default value for `trksegs`,
# the previous statement adds the track segment also to track B.
assert my_track_a.trksegs[0] == my_track_seg
assert my_track_b.trksegs[0] == my_track_seg

I assume this was an oversight and not a deliberate design decision. For a detailed explanation and possible solutions, see this section in the Python documentation.

Add tests

Add tests to the project (using the excellent pytest framework).