Merge pull request #64 from semuconsulting/RC-1.0.40

Rc 1.0.40

.vscode/settings.json

@@ -4,5 +4,5 @@
     "editor.formatOnSave": true,
     "modulename": "${workspaceFolderBasename}",
     "distname": "${workspaceFolderBasename}",
-    "moduleversion": "1.0.39",
+    "moduleversion": "1.0.40",
 }

README.md

@@ -287,6 +287,7 @@ b'$EIGNQ,RMC*24\r\n'
  - `haversine` - finds great circle distance in km between two sets of (lat, lon) coordinates
  - `planar` - finds planar distance in m between two sets of (lat, lon) coordinates
  - `bearing` - finds bearing in degrees between two sets of (lat, lon) coordinates
+ - `area` - finds spherical area bounded by two sets of (lat, lon) coordinates
 
 See [Sphinx documentation](https://www.semuconsulting.com/pynmeagps/pynmeagps.html#module-pynmeagaps.nmeahelpers) for details.
 

RELEASE_NOTES.md

@@ -1,5 +1,13 @@
 # pynmeagps Release Notes
 
+### RELEASE 1.0.40
+
+CHANGES:
+
+1. Add area() helper method to calculate spherical area of bounding box.
+1. Sphinx documentation and docstrings enhanced to include global constants and decodes.
+1. `socket_stream.SocketStream` class renamed to `socket_wrapper.SocketWrapper` class for clarity.
+
 ### RELEASE 1.0.39
 
 ENHANCEMENTS:

docs/pynmeagps.rst

@@ -1,85 +1,85 @@
-pynmeagps package
-=================
-
-Submodules
-----------
-
-pynmeagps.exceptions module
----------------------------
-
-.. automodule:: pynmeagps.exceptions
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.nmeahelpers module
-----------------------------
-
-.. automodule:: pynmeagps.nmeahelpers
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.nmeamessage module
-----------------------------
-
-.. automodule:: pynmeagps.nmeamessage
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.nmeareader module
----------------------------
-
-.. automodule:: pynmeagps.nmeareader
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.nmeatypes\_core module
---------------------------------
-
-.. automodule:: pynmeagps.nmeatypes_core
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.nmeatypes\_get module
--------------------------------
-
-.. automodule:: pynmeagps.nmeatypes_get
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.nmeatypes\_poll module
---------------------------------
-
-.. automodule:: pynmeagps.nmeatypes_poll
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.nmeatypes\_set module
--------------------------------
-
-.. automodule:: pynmeagps.nmeatypes_set
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pynmeagps.socket\_stream module
--------------------------------
-
-.. automodule:: pynmeagps.socket_stream
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: pynmeagps
-   :members:
-   :undoc-members:
-   :show-inheritance:
+pynmeagps package
+=================
+
+Submodules
+----------
+
+pynmeagps.exceptions module
+---------------------------
+
+.. automodule:: pynmeagps.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.nmeahelpers module
+----------------------------
+
+.. automodule:: pynmeagps.nmeahelpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.nmeamessage module
+----------------------------
+
+.. automodule:: pynmeagps.nmeamessage
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.nmeareader module
+---------------------------
+
+.. automodule:: pynmeagps.nmeareader
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.nmeatypes\_core module
+--------------------------------
+
+.. automodule:: pynmeagps.nmeatypes_core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.nmeatypes\_get module
+-------------------------------
+
+.. automodule:: pynmeagps.nmeatypes_get
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.nmeatypes\_poll module
+--------------------------------
+
+.. automodule:: pynmeagps.nmeatypes_poll
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.nmeatypes\_set module
+-------------------------------
+
+.. automodule:: pynmeagps.nmeatypes_set
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pynmeagps.socket\_wrapper module
+--------------------------------
+
+.. automodule:: pynmeagps.socket_wrapper
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pynmeagps
+   :members:
+   :undoc-members:
+   :show-inheritance:

examples/utilities.py

@@ -13,6 +13,7 @@
 from datums import DATUMS  # assumes this is in same folder
 
 from pynmeagps import (
+    area,
     bearing,
     ecef2llh,
     haversine,
@@ -44,21 +45,21 @@
     f" {LAT2}, {LON2} using default WGS84 datum...",
 )
 dist = haversine(LAT1, LON1, LAT2, LON2)
-print(f"Distance: {dist} km")
+print(f"Distance: {dist:.4f} km")
 
 print(
     f"\nFind planar distance between {LAT1}, {LON1} and",
     f" {LAT3}, {LON3} using default WGS84 datum...",
 )
 dist = planar(LAT1, LON1, LAT3, LON3)
-print(f"Distance: {dist} m")
+print(f"Distance: {dist:.4f} m")
 
 print(
     f"\nFind bearing between {LAT1}, {LON1} and",
     f" {LAT2}, {LON2} using default WGS84 datum...",
 )
 brng = bearing(LAT1, LON1, LAT2, LON2)
-print(f"Bearing: {brng} degrees")
+print(f"Bearing: {brng:.4f} degrees")
 
 X, Y, Z = 3822566.3113, -144427.5123, 5086857.1208
 print(f"\nConvert ECEF X: {X}, Y: {Y}, Z: {Z} to geodetic using default WGS84 datum...")
@@ -82,7 +83,14 @@
     f"{LAT2}, {LON2} using alternate {DATUM} ({ellipsoid}) datum...",
 )
 dist = haversine(LAT1, LON1, LAT2, LON2, a / 1000)
-print(f"Distance: {dist} km")
+print(f"Distance: {dist:.4f} km")
+
+print(
+    f"\nFind spherical area bound by {LAT1}, {LON1} and",
+    f"{LAT2}, {LON2}...",
+)
+bbarea = area(LAT1, LON1, LAT2, LON2)
+print(f"Area: {bbarea:.4f} km²")
 
 print(
     f"\nConvert ECEF X: {X}, Y: {Y}, Z: {Z} to",

pyproject.toml

@@ -7,7 +7,7 @@ name = "pynmeagps"
 authors = [{ name = "semuadmin", email = "[email protected]" }]
 maintainers = [{ name = "semuadmin", email = "[email protected]" }]
 description = "NMEA protocol parser and generator"
-version = "1.0.39"
+version = "1.0.40"
 license = { file = "LICENSE" }
 readme = "README.md"
 requires-python = ">=3.8"

src/pynmeagps/__init__.py

@@ -20,6 +20,6 @@
 from pynmeagps.nmeareader import NMEAReader
 from pynmeagps.nmeatypes_core import *
 from pynmeagps.nmeatypes_get import *
-from pynmeagps.socket_stream import SocketStream
+from pynmeagps.socket_wrapper import SocketWrapper
 
 version = __version__

src/pynmeagps/_version.py

@@ -8,4 +8,4 @@
 :license: BSD 3-Clause
 """
 
-__version__ = "1.0.39"
+__version__ = "1.0.40"

src/pynmeagps/nmeahelpers.py

@@ -546,6 +546,29 @@ def bearing(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
     return brng
 
 
+def area(
+    lat1: float,
+    lon1: float,
+    lat2: float,
+    lon2: float,
+    radius: int = WGS84_SMAJ_AXIS / 1000,
+) -> float:
+    """
+    Calculate spherical area bounded by two coordinates.
+
+    :param float lat1: lat1
+    :param float lon1: lon1
+    :param float lat2: lat2
+    :param float lon2: lon2
+    :param float radius: radius in km (Earth = 6378.137 km)
+    :return: area in km²
+    :rtype: float
+    """
+
+    phi1, phi2 = [c * pi / 180 for c in (lat1, lat2)]
+    return pow(radius, 2) * pi * abs(sin(phi1) - sin(phi2)) * abs(lon1 - lon2) / 180
+
+
 def get_gpswnotow(dat: datetime) -> tuple:
     """
     Get GPS Week number (Wno) and Time of Week (Tow)

src/pynmeagps/nmeareader.py

@@ -35,7 +35,7 @@
     VALCKSUM,
     VALMSGID,
 )
-from pynmeagps.socket_stream import SocketStream
+from pynmeagps.socket_wrapper import SocketWrapper
 
 
 class NMEAReader:
@@ -68,7 +68,7 @@ def __init__(
         # pylint: disable=too-many-arguments
 
         if isinstance(stream, socket):
-            self._stream = SocketStream(stream, bufsize=bufsize)
+            self._stream = SocketWrapper(stream, bufsize=bufsize)
         else:
             self._stream = stream
         if msgmode not in (0, 1, 2):

src/pynmeagps/nmeatypes_core.py

@@ -13,18 +13,39 @@
 from datetime import datetime
 
 INPUT = 1
+"""Input message type"""
 OUTPUT = 0
+"""Output message type"""
 GET = 0
+"""GET (receive, response) message types"""
 SET = 1
+"""SET (command) message types"""
 POLL = 2
+"""POLL (query) message types"""
+SETPOLL = 3
+"""SETPOLL (SET or POLL) message types"""
 VALNONE = 0
+"""Do not validate checksum or msgid"""
 VALCKSUM = 1
+"""Validate checksum"""
 VALMSGID = 2
-ERR_IGNORE = 0
-ERR_LOG = 1
+"""Validate message id"""
+NMEA_PROTOCOL = 1
+"""NMEA Protocol"""
+UBX_PROTOCOL = 2
+"""UBX Protocol"""
+RTCM3_PROTOCOL = 4
+"""RTCM3 Protocol"""
 ERR_RAISE = 2
+"""Raise error and quit"""
+ERR_LOG = 1
+"""Log errors"""
+ERR_IGNORE = 0
+"""Ignore errors"""
+
 # proprietary messages where msgId is first element of payload:
 PROP_MSGIDS = ("FEC", "UBX", "TNL", "ASHR", "GPPADV")
+"""Proprietary message prefixes"""
 
 GNSSLIST = {
     0: "GPS",
@@ -36,13 +57,27 @@
     6: "GLONASS",
     7: "NAVIC",
 }
+"""GNSS code"""
+FIXTYPE_GGA = {
+    0: "NO FIX",
+    1: "3D",
+    2: "3D",
+    4: "RTK FIXED",
+    5: "RTK FLOAT",
+    6: "DR",
+}
+"""Fix type from GGA"""
 
 GPSEPOCH0 = datetime(1980, 1, 6)
+"""GPS epoch base date"""
 # Geodetic datum spheroid values:
 # WGS84, ETRS89, EPSG4326
 WGS84 = "WGS_84"
+"""WGS84 datum descriptor"""
 WGS84_SMAJ_AXIS = 6378137.0  # semi-major axis
+"""WGS84 semi-major axis"""
 WGS84_FLATTENING = 298.257223563  # flattening
+"""WGS84 flattening"""
 
 # ***************************************************
 # THESE ARE THE NMEA PROTOCOL PAYLOAD ATTRIBUTE TYPES