fastgpx 0.1.0__cp311-cp311-win_amd64.whl

fastgpx/__init__.py

@@ -0,0 +1,5 @@
+# Re-export the C extension module to make it available as fastgpx instead of fastgpx.fastgpx.
+from .fastgpx import *  # type: ignore
+
+# Needed for sphinx autosummary to pick up the re-exported C extension module.
+__all__ = [name for name in dir(fastgpx) if not name.startswith('_')]  # type: ignore

fastgpx/__init__.pyi

@@ -0,0 +1,12 @@
+from __future__ import annotations
+from fastgpx.fastgpx import Bounds
+from fastgpx.fastgpx import Gpx
+from fastgpx.fastgpx import LatLong
+from fastgpx.fastgpx import Segment
+from fastgpx.fastgpx import TimeBounds
+from fastgpx.fastgpx import Track
+from fastgpx.fastgpx import geo
+from fastgpx.fastgpx import parse
+from fastgpx.fastgpx import polyline
+from . import fastgpx
+__all__ = ['Bounds', 'Gpx', 'LatLong', 'Segment', 'TimeBounds', 'Track', 'fastgpx', 'geo', 'parse', 'polyline']

fastgpx/fastgpx/__init__.pyi

@@ -0,0 +1,128 @@
+from __future__ import annotations
+import datetime
+import typing
+from . import geo
+from . import polyline
+__all__ = ['Bounds', 'Gpx', 'LatLong', 'Segment', 'TimeBounds', 'Track', 'geo', 'parse', 'polyline']
+class Bounds:
+    max: LatLong | None
+    min: LatLong | None
+    @typing.overload
+    def __init__(self) -> None:
+        ...
+    @typing.overload
+    def __init__(self, min: LatLong, max: LatLong) -> None:
+        ...
+    @typing.overload
+    def __init__(self, min: tuple[float, float], max: tuple[float, float]) -> None:
+        ...
+    @typing.overload
+    def add(self, location: LatLong) -> None:
+        ...
+    @typing.overload
+    def add(self, bounds: Bounds) -> None:
+        ...
+    def is_empty(self) -> bool:
+        ...
+    def max_bounds(self, bounds: Bounds) -> Bounds:
+        ...
+    @property
+    def max_latitude(self) -> float | None:
+        ...
+    @max_latitude.setter
+    def max_latitude(self, arg1: float) -> None:
+        ...
+    @property
+    def max_longitude(self) -> float | None:
+        ...
+    @max_longitude.setter
+    def max_longitude(self, arg1: float) -> None:
+        ...
+    @property
+    def min_latitude(self) -> float | None:
+        ...
+    @min_latitude.setter
+    def min_latitude(self, arg1: float) -> None:
+        ...
+    @property
+    def min_longitude(self) -> float | None:
+        ...
+    @min_longitude.setter
+    def min_longitude(self, arg1: float) -> None:
+        ...
+class Gpx:
+    tracks: list[Track]
+    def __init__(self) -> None:
+        ...
+    def bounds(self) -> Bounds:
+        ...
+    def get_bounds(self) -> Bounds:
+        ...
+    def get_time_bounds(self) -> TimeBounds:
+        ...
+    def length_2d(self) -> float:
+        ...
+    def length_3d(self) -> float:
+        ...
+    def time_bounds(self) -> TimeBounds:
+        ...
+class LatLong:
+    elevation: float
+    latitude: float
+    longitude: float
+    @typing.overload
+    def __init__(self) -> None:
+        ...
+    @typing.overload
+    def __init__(self, latitude: float, longitude: float, elevation: float = 0.0) -> None:
+        ...
+class Segment:
+    points: list[LatLong]
+    def __init__(self) -> None:
+        ...
+    def bounds(self) -> Bounds:
+        ...
+    def get_bounds(self) -> Bounds:
+        ...
+    def get_time_bounds(self) -> TimeBounds:
+        ...
+    def length_2d(self) -> float:
+        ...
+    def length_3d(self) -> float:
+        ...
+    def time_bounds(self) -> TimeBounds:
+        ...
+class TimeBounds:
+    end_time: datetime.datetime | None
+    start_time: datetime.datetime | None
+    @typing.overload
+    def __init__(self) -> None:
+        ...
+    @typing.overload
+    def __init__(self, start_time: datetime.datetime | None, end_time: datetime.datetime | None) -> None:
+        ...
+    def is_empty(self) -> bool:
+        ...
+class Track:
+    comment: str | None
+    description: str | None
+    name: str | None
+    number: int | None
+    segments: list[Segment]
+    type: str | None
+    def __init__(self) -> None:
+        ...
+    def bounds(self) -> Bounds:
+        ...
+    def get_bounds(self) -> Bounds:
+        ...
+    def get_time_bounds(self) -> TimeBounds:
+        ...
+    def length_2d(self) -> float:
+        ...
+    def length_3d(self) -> float:
+        ...
+    def time_bounds(self) -> TimeBounds:
+        ...
+def parse(path: str) -> Gpx:
+    ...

fastgpx/fastgpx/geo.pyi

@@ -0,0 +1,9 @@
+from __future__ import annotations
+import fastgpx.fastgpx
+__all__ = ['haversine', 'haversine_distance']
+def haversine(latlong1: fastgpx.fastgpx.LatLong, latlong2: fastgpx.fastgpx.LatLong) -> float:
+    ...
+def haversine_distance(latitude_1: float, longitude_1: float, latitude_2: float, longitude_2: float) -> float:
+    """
+    Compatibility with `gpxpy.geo.haversine_distance`
+    """

fastgpx/fastgpx/polyline.pyi

@@ -0,0 +1,54 @@
+from __future__ import annotations
+import fastgpx
+import fastgpx.fastgpx
+import typing
+__all__ = ['Precision', 'decode', 'encode']
+class Precision:
+    """
+    Members:
+    
+      Five
+    
+      Six
+    """
+    Five: typing.ClassVar[Precision]  # value = <Precision.Five: 5>
+    Six: typing.ClassVar[Precision]  # value = <Precision.Six: 6>
+    __members__: typing.ClassVar[dict[str, Precision]]  # value = {'Five': <Precision.Five: 5>, 'Six': <Precision.Six: 6>}
+    def __eq__(self, other: typing.Any) -> bool:
+        ...
+    def __getstate__(self) -> int:
+        ...
+    def __hash__(self) -> int:
+        ...
+    def __index__(self) -> int:
+        ...
+    def __init__(self, value: int) -> None:
+        ...
+    def __int__(self) -> int:
+        ...
+    def __ne__(self, other: typing.Any) -> bool:
+        ...
+    def __repr__(self) -> str:
+        ...
+    def __setstate__(self, state: int) -> None:
+        ...
+    def __str__(self) -> str:
+        ...
+    @property
+    def name(self) -> str:
+        ...
+    @property
+    def value(self) -> int:
+        ...
+@typing.overload
+def decode(encoded: str, precision: Precision = fastgpx.polyline.Precision.Five) -> list[fastgpx.fastgpx.LatLong]:
+    ...
+@typing.overload
+def decode(locations: str, precision: int = 5) -> list[fastgpx.fastgpx.LatLong]:
+    ...
+@typing.overload
+def encode(locations: list[fastgpx.fastgpx.LatLong], precision: Precision = fastgpx.polyline.Precision.Five) -> str:
+    ...
+@typing.overload
+def encode(locations: list[fastgpx.fastgpx.LatLong], precision: int = 5) -> str:
+    ...

fastgpx-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: fastgpx
+Version: 0.1.0
+Summary: An experimental Python library for parsing GPX files fast.
+Keywords: gpx,parser,fast
+Author: Thomas Thomassen
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: File Formats
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.11
+Project-URL: Documentation, https://thomthom.github.io/fastgpx/
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# fastgpx
+
+An experimental Python library for parsing GPX files fast.
+
+```py
+# Get the total length of the tracks in a GPX file:
+import fastgpx
+
+gpx = fastgpx.parse("example.gpx")
+print(f'{gpx.length_2d()} m')
+```
+
+```py
+# Iterate over GPX file:
+import fastgpx
+
+gpx = fastgpx.parse("example.gpx")
+for track in gpx.tracks:
+    print(f'Track: {track.name}')
+    print(f'Distance: {track.length_2d()} m')
+    if not track.time_bounds.is_empty():
+      print(f'Time: {track.time_bounds().start_time} - {track.time_bounds().end_time}')
+    for segment in track.segments:
+        print(f'Segment: {segment.name}')
+        for point in segment.points:
+            print(f'Point: {point.latitude}, {point.longitude}')
+```
+
+[Documentation](https://thomthom.github.io/fastgpx/)
+
+## GPX/XML Performance (Background)
+
+`gpxpy` appear to be the most popular GPX library for Python.
+
+`gpxpy` docs says that it uses `lxml` is available because it is faster than "`minidom`" (`etree`).
+When benchmarking that seemed not to be the case. It appear that the stdlib XML library has gotten
+much better since `gpxpy` was created.
+
+Reference: Open ticket on making `etree` default:
+https://github.com/tkrajina/gpxpy/issues/248
+
+## Benchmarks
+
+Test machine:
+
+* AMD Ryzen 7 5800 8-Core, 3.80 GHz
+* 32 GB memory
+* m2 SSD storage
+
+### gpxpy benchmarks
+
+Comparing getting the distance of a GPX file using `gpxpy` vs manually extracting
+the data using `xml_etree`, computing distance between points using `gpxpy`
+distance functions.
+
+#### gpxpy without `lxml`
+
+```
+Running benchmark with 3 iterations...
+gpxpy 5463041.784135511 meters
+gpxpy 5463041.784135511 meters
+gpxpy 5463041.784135511 meters
+gpxpy: 11.497863 seconds (Average: 3.832621 seconds)
+```
+
+#### gpxpy with `lxml`
+
+```
+Running benchmark with 3 iterations...
+gpxpy 5463041.784135511 meters
+gpxpy 5463041.784135511 meters
+gpxpy 5463041.784135511 meters
+gpxpy: 37.803625 seconds (Average: 12.601208 seconds)
+```
+
+#### xml_etree data extraction
+
+```
+Running benchmark with 3 iterations...
+xml_etree 5463043.740615641 meters
+xml_etree 5463043.740615641 meters
+xml_etree 5463043.740615641 meters
+xml_etree: 2.333200 seconds (Average: 0.777733 seconds)
+```
+
+Even with `gpxpy` using `etree` to parse the XML it is paster to parse it
+directly with `etree` and use `gpxpy.geo` distance functions to compute the
+distance of a GPX file. Unclear what the extra overhead is, possibly the cost
+of extraction additional data. (Some minor difference in how the total distance
+is computed in this example. Using different options for computing the distance.)
+
+### C++ benchmarks
+
+Since XML parsing itself appear to have a significant impact on performance some
+popular C++ XML libraries was tested:
+
+#### tinyxml2
+```
+Total Length: 5456930.710560566
+Elapsed time: 0.4980144 seconds
+```
+
+#### pugixml
+```
+Total Length: 5456930.710560566
+Elapsed time: 0.1890089 seconds
+```
+
+### C++ vs Python implementations
+
+
+```
+Running 5 benchmarks with 3 iterations...
+
+Running gpxpy ...
+gpxpy: 50.182288 seconds (Average: 16.727429 seconds)
+
+Running xml_etree ...
+xml_etree: 8.269050 seconds (Average: 2.756350 seconds)
+
+Running lxml ...
+lxml: 8.479702 seconds (Average: 2.826567 seconds)
+
+Running tinyxml (C++) ...
+tinyxml (C++): 2.699880 seconds (Average: 0.899960 seconds)
+
+Running pugixml (C++) ...
+pugixml (C++): 0.381095 seconds (Average: 0.127032 seconds)
+```
+
+For computing the length of a GPX file, `pugixml` in a Python C extension was ~140
+times faster than using `gpxpy`.

fastgpx-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+fastgpx/__init__.py,sha256=Dhn14Vj7rvcXHlI3d5U7YUJ9kpiNqwyN5jjx21vhX6U,305
+fastgpx/__init__.pyi,sha256=ZLJDcLlyBVoCyzfnNPJawul3-gaCEuk4cfBbE7gPlrg,496
+fastgpx/fastgpx/__init__.pyi,sha256=bkG-4KO_GAFqG7JkpD282BCqpAZMDUBo9z2PX0l4B9o,3462
+fastgpx/fastgpx/geo.pyi,sha256=ZVwdoWV2S2T_flLjubZP5w-8KBpSdCu9_XJiv_Nk1C8,396
+fastgpx/fastgpx/polyline.pyi,sha256=-rA0DhdBy_iifRD4Z_6fxolprXZAcjCsf7RbeVnn4sI,1619
+fastgpx/fastgpx.cp311-win_amd64.pyd,sha256=mBxEYe8M_ty7S1zeBuQkt2IISeW9VYWPWg-5hMD0vPE,1258496
+fastgpx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+include/pugiconfig.hpp,sha256=jlfegptw715KDgZqHwl0-jcYoO5cerHNphaM9WDoJPg,2973
+include/pugixml.hpp,sha256=geW_lTG67YQpTQy-OMqtttkNEPd8LXk-Lc6MX16vbCY,55813
+lib/cmake/pugixml/pugixml-config-version.cmake,sha256=1JpMX7bIytKDIQj-0sYRyWi3OuqhYW2ejtHT2tguaK8,2824
+lib/cmake/pugixml/pugixml-config.cmake,sha256=o26SUzcgGUIZx707opSfpPJulzF9qdZ5UhdxMPppIHE,1002
+lib/cmake/pugixml/pugixml-targets-relwithdebinfo.cmake,sha256=Q4VX-_0WNB1rP4unAefSUak4UoJWdLzd4FxMMlmxHe4,902
+lib/cmake/pugixml/pugixml-targets.cmake,sha256=Y_kk2s6vZuC3KKzBrBNUDVSHM-T_27jYwjl09j8amZU,4712
+lib/pkgconfig/pugixml.pc,sha256=r8nNBHbEvOaiHzr2AIwtM0CrQw_0TwksBsAaHkPm71c,457
+lib/pugixml.lib,sha256=6gVxeRqVvt4Jr08Nz_ka3Ke1yujjFolg_PhJP_dQ25o,1508704
+fastgpx-0.1.0.dist-info/METADATA,sha256=GKQtUXerwQfnbGjZUZVtq0kprxv8d_-o8yykGO8Yzfo,4036
+fastgpx-0.1.0.dist-info/WHEEL,sha256=xGZmaOXqwLlhmjR8ikRHIC1Wm-k3ULVrL-oi9GC-Mmc,106
+fastgpx-0.1.0.dist-info/licenses/LICENSE.md,sha256=uiiKRcSY4AXOaDKTBOVF_1FW-8W6ATVoXYPm3UTOpu0,1111
+fastgpx-0.1.0.dist-info/RECORD,,

fastgpx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.11.1
+Root-Is-Purelib: false
+Tag: cp311-cp311-win_amd64
+

fastgpx-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2024-2025 Thomas Thomassen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

include/pugiconfig.hpp

@@ -0,0 +1,77 @@
+/**
+ * pugixml parser - version 1.14
+ * --------------------------------------------------------
+ * Copyright (C) 2006-2023, by Arseny Kapoulkine (arseny.kapoulkine@gmail.com)
+ * Report bugs and download new versions at https://pugixml.org/
+ *
+ * This library is distributed under the MIT License. See notice at the end
+ * of this file.
+ *
+ * This work is based on the pugxml parser, which is:
+ * Copyright (C) 2003, by Kristen Wegner (kristen@tima.net)
+ */
+
+#ifndef HEADER_PUGICONFIG_HPP
+#define HEADER_PUGICONFIG_HPP
+
+// Uncomment this to enable wchar_t mode
+// #define PUGIXML_WCHAR_MODE
+
+// Uncomment this to enable compact mode
+// #define PUGIXML_COMPACT
+
+// Uncomment this to disable XPath
+// #define PUGIXML_NO_XPATH
+
+// Uncomment this to disable STL
+// #define PUGIXML_NO_STL
+
+// Uncomment this to disable exceptions
+// #define PUGIXML_NO_EXCEPTIONS
+
+// Set this to control attributes for public classes/functions, i.e.:
+// #define PUGIXML_API __declspec(dllexport) // to export all public symbols from DLL
+// #define PUGIXML_CLASS __declspec(dllimport) // to import all classes from DLL
+// #define PUGIXML_FUNCTION __fastcall // to set calling conventions to all public functions to fastcall
+// In absence of PUGIXML_CLASS/PUGIXML_FUNCTION definitions PUGIXML_API is used instead
+
+// Tune these constants to adjust memory-related behavior
+// #define PUGIXML_MEMORY_PAGE_SIZE 32768
+// #define PUGIXML_MEMORY_OUTPUT_STACK 10240
+// #define PUGIXML_MEMORY_XPATH_PAGE_SIZE 4096
+
+// Tune this constant to adjust max nesting for XPath queries
+// #define PUGIXML_XPATH_DEPTH_LIMIT 1024
+
+// Uncomment this to switch to header-only version
+// #define PUGIXML_HEADER_ONLY
+
+// Uncomment this to enable long long support
+// #define PUGIXML_HAS_LONG_LONG
+
+#endif
+
+/**
+ * Copyright (c) 2006-2023 Arseny Kapoulkine
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */