pygeodesy 24.7.24__py2.py3-none-any.whl → 24.8.24__py2.py3-none-any.whl

pygeodesy/gars.py

@@ -3,33 +3,34 @@
 
 u'''I{Global Area Reference System} (GARS) en-/decoding.
 
-Classes L{Garef} and L{GARSError} and several functions to encode,
-decode and inspect I{Global Area Reference System} (GARS) references.
-
-Transcoded from C++ class U{GARS
-<https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GARS.html>}
-by I{Charles Karney}.  See also U{Global Area Reference System
-<https://WikiPedia.org/wiki/Global_Area_Reference_System>} and U{NGA (GARS)
-<https://Earth-Info.NGA.mil/GandG/coordsys/grids/gars.html>}.
+Class L{Garef} and several functions to encode, decode and inspect
+GARS references.
+
+Transcoded from I{Charles Karney}'s C++ class U{GARS
+<https://GeographicLib.SourceForge.io/C++/doc/classGeographicLib_1_1GARS.html>}.
+
+@see: U{Global Area Reference System
+      <https://WikiPedia.org/wiki/Global_Area_Reference_System>} and U{NGA
+      (GARS)<https://Earth-Info.NGA.mil/GandG/coordsys/grids/gars.html>}.
 '''
 
 # from pygeodesy.basics import isstr  # from .named
 from pygeodesy.constants import _off90, _1_over, _0_5, \
                                 _1_0  # PYCHOK used!
-from pygeodesy.dms import parse3llh,   Fmt  # parseDMS2
 from pygeodesy.errors import _ValueError, _xkwds, _xStrError
-from pygeodesy.interns import NN, _0to9_, _AtoZnoIO_, _COMMA_
-from pygeodesy.lazily import _ALL_LAZY, _ALL_OTHER
-from pygeodesy.named import _name__,  isstr, Property_RO
+from pygeodesy.interns import NN, _0to9_, _AtoZnoIO_, _COMMA_, \
+                             _INV_, _SPACE_
+from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY
+from pygeodesy.named import _name__,  Fmt, isstr, Property_RO
 from pygeodesy.namedTuples import LatLon2Tuple, LatLonPrec3Tuple
 # from pygeodesy.props import Property_RO  # from .named
-# from pygeodesy.streprs import Fmt  # from .dms
+# from pygeodesy.streprs import Fmt  # from .named
 from pygeodesy.units import Int_, Lat, Lon, Precision_, Scalar_, Str
 
 from math import floor
 
 __all__ = _ALL_LAZY.gars
-__version__ = '24.06.15'
+__version__ = '24.08.13'
 
 _Digits  = _0to9_
 _LatLen  =    2
@@ -86,9 +87,9 @@ def _2garstr2(garef):
     try:
         n, garstr = len(garef), garef.upper()
         if n < _MinLen or n > _MaxLen \
-                       or garstr[:3] == 'INV' \
+                       or garstr.startswith(_INV_) \
                        or not garstr.isalnum():
-            raise ValueError
+            raise ValueError()
         return garstr, _2Precision(n - _MinLen)
 
     except (AttributeError, TypeError, ValueError) as x:
@@ -111,45 +112,45 @@ class Garef(Str):
     '''Garef class, a named C{str}.
     '''
     # no str.__init__ in Python 3
-    def __new__(cls, cll, precision=1, **name):
-        '''New L{Garef} from an other L{Garef} instance or garef
-           C{str} or from a C{LatLon} instance or lat-/longitude C{str}.
-
-           @arg cll: Cell or location (L{Garef} or C{str}, C{LatLon}
-                     or C{str}).
-           @kwarg precision: Optional, the desired garef resolution
-                             and length (C{int} 0..2), see function
-                             L{gars.encode} for more details.
+    def __new__(cls, lat_gll, lon=None, precision=1, **name):
+        '''New L{Garef} from an other L{Garef} instance or garef C{str}
+           or from a lat- and longitude.
+
+           @arg lat_gll: Latitude (C{degrees90}), a garef (L{Garef},
+                         C{str}) or a location (C{LatLon}, C{LatLon*Tuple}).
+           @kwarg lon: Logitude (C{degrees180)}, required if B{C{lat_gll}}
+                       is C{degrees90}, ignored otherwise.
+           @kwarg precision: The desired garef resolution and length (C{int}
+                             0..2), see L{encode<pygeodesy.gars.encode>}.
            @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @return: New L{Garef}.
 
-           @raise RangeError: Invalid B{C{cll}} lat- or longitude.
+           @raise GARSError: INValid B{C{lat_gll}}.
 
-           @raise TypeError: Invalid B{C{cll}}.
+           @raise RangeError: Invalid B{C{lat_gll}} or B{C{lon}}.
 
-           @raise GARSError: INValid or non-alphanumeric B{C{cll}}.
+           @raise TypeError: Invalid B{C{lat_gll}} or B{C{lon}}.
         '''
-        ll = p = None
-
-        if isinstance(cll, Garef):
-            g, p = _2garstr2(str(cll))
-
-        elif isstr(cll):
-            if _COMMA_ in cll:
-                ll = _2fll(*parse3llh(cll))
-                g  =  encode(*ll, precision=precision)  # PYCHOK false
-            else:
-                g = cll.upper()
-
-        else:  # assume LatLon
-            try:
-                ll = _2fll(cll.lat, cll.lon)
-                g  =  encode(*ll, precision=precision)  # PYCHOK false
-            except AttributeError:
-                raise _xStrError(Garef, cll=cll)  # Error=GARSError
-
-        self = Str.__new__(cls, g, name=_name__(name, _or_nameof=cll))
+        if lon is None:
+            if isinstance(lat_gll, Garef):
+                g, ll, p = str(lat_gll), lat_gll.latlon, lat_gll.precision
+            elif isstr(lat_gll):
+                ll = lat_gll.replace(_COMMA_, _SPACE_).split()
+                if len(ll) > 1:
+                    g, ll, p = _encode3(ll[0], ll[1], precision)
+                else:
+                    g, ll =  lat_gll.upper(), None
+                    _, p  = _2garstr2(g)  # validate
+            else:  # assume LatLon
+                try:
+                    g, ll, p = _encode3(lat_gll.lat, lat_gll.lon, precision)
+                except AttributeError:
+                    raise _xStrError(Garef, gll=lat_gll, Error=GARSError)
+        else:
+            g, ll, p = _encode3(lat_gll, lon, precision)
+
+        self = Str.__new__(cls, g, name=_name__(name, _or_nameof=lat_gll))
         self._latlon    = ll
         self._precision = p
         return self
@@ -200,8 +201,8 @@ def decode3(garef, center=True, **name):
     '''Decode a C{garef} to lat-, longitude and precision.
 
        @arg garef: To be decoded (L{Garef} or C{str}).
-       @kwarg center: If C{True} the center, otherwise the south-west,
-                      lower-left corner (C{bool}).
+       @kwarg center: If C{True}, use the garef's center, otherwise
+                      the south-west, lower-left corner (C{bool}).
 
        @return: A L{LatLonPrec3Tuple}C{(lat, lon, precision)}.
 
@@ -251,7 +252,7 @@ def decode3(garef, center=True, **name):
                             precision, name=n)
 
 
-def encode(lat, lon, precision=1):  # MCCABE 14
+def encode(lat, lon, precision=1):
     '''Encode a lat-/longitude as a C{garef} of the given precision.
 
        @arg lat: Latitude (C{degrees}).
@@ -269,6 +270,13 @@ def encode(lat, lon, precision=1):  # MCCABE 14
               resolution is B{30′} for B{C{precision}} 0, B{15′} for 1
               and B{5′} for 2, respectively.
     '''
+    g, _, _ = _encode3(lat, lon, precision)
+    return g
+
+
+def _encode3(lat, lon, precision):  # MCCABE 14
+    '''Return 3-tuple C{(garef, (lat, lon), p)}.
+    '''
     def _digit(x, y, m):
         return _Digits[m * (m - y - 1) + x + 1],
 
@@ -282,12 +290,12 @@ def encode(lat, lon, precision=1):  # MCCABE 14
     p = _2Precision(precision)
 
     lat, lon = _2fll(lat, lon)
-    lat = _off90(lat)
 
-    ix, x = _2divmod2(lon, _LonOrig_M4)
-    iy, y = _2divmod2(lat, _LatOrig_M4)
+    ix, x = _2divmod2(       lon,  _LonOrig_M4)
+    iy, y = _2divmod2(_off90(lat), _LatOrig_M4)
 
-    g = _str(_Digits, ix + 1, _LonLen) + _str(_Letters, iy, _LatLen)
+    g = _str(_Digits,  ix + 1, _LonLen) + \
+        _str(_Letters, iy,     _LatLen)
     if p > 0:
         ix, x = divmod(x, _M3)
         iy, y = divmod(y, _M3)
@@ -295,7 +303,7 @@ def encode(lat, lon, precision=1):  # MCCABE 14
         if p > 1:
             g += _digit(x, y, _M3)
 
-    return NN.join(g)
+    return NN.join(g), (lat, lon), p
 
 
 def precision(res):
@@ -332,8 +340,8 @@ def resolution(prec):
     return _Resolutions[max(0, min(p, _MaxPrec))]
 
 
-__all__ += _ALL_OTHER(decode3,  # functions
-                      encode, precision, resolution)
+__all__ += _ALL_DOCS(decode3,  # functions
+                     encode, precision, resolution)
 
 # **) MIT License
 #

pygeodesy/geodesici.py

@@ -49,14 +49,14 @@ from pygeodesy.props import deprecated_method, Property, \
 from pygeodesy.solveBase import _SolveCapsBase,  pairs
 # from pygeodesy.streprs import pairs  # from .solveBase
 # from pygeodesy.streprs import Fmt, unstr  # from .ellipsoids
-from pygeodesy.units import Degrees, Float, Int, _isDegrees, \
-                            Lat, Lon, Meter, Meter_
+from pygeodesy.units import Azimuth as Azi, Degrees, Float, Int, \
+                           _isDegrees,  Lat, Lon, Meter, Meter_
 from pygeodesy.utily import sincos2,  atan2, fabs, radians
 
 # from math import atan2, ceil as _ceil, fabs, radians  # .fsums, .utily
 
 __all__ = _ALL_LAZY.geodesici
-__version__ = '24.07.22'
+__version__ = '24.07.25'
 
 _0t     =  0,  # int
 _1_1t   = -1, +1
@@ -77,12 +77,6 @@ _sX0_   = 'sX0'
 _TRIPS  =  128
 
 
-class Azi(Degrees):
-    '''(INTERNAL) Azimuth C{Unit}.
-    '''
-    pass
-
-
 class XDict(ADict):
     '''4+Item result from L{Intersectool} and L{Intersector} methods
        C{All}, C{Closest}, C{Next} and C{Segment} with the intersection
@@ -597,7 +591,7 @@ class Intersectool(_IntersectBase, _SolveCapsBase):
     def _GeodesicExact(self):
         '''Get the I{class} L{GeodesicExact}, I{once}.
         '''
-        return _MODS.geodesicx.GeodesicExact  # overwrite propertyROver
+        return _MODS.geodesicx.GeodesicExact  # overwrite property_ROver
 
     def _In5T(self, glA, glB, S, X, k2=False, **_2X):
         A = GDict(glA).set_(lat2=X.latA, lon2=X.lonA, s12=S.sA)

pygeodesy/geodesicx/gx.py

@@ -63,7 +63,7 @@ from pygeodesy.utily import atan2d as _atan2d_reverse, _unrollon, _Wrap, wrap360
 from math import atan2, copysign, cos, degrees, fabs, radians, sqrt
 
 __all__ = ()
-__version__ = '24.07.11'
+__version__ = '24.08.13'
 
 _MAXIT1 = 20
 _MAXIT2 = 10 + _MAXIT1 + MANT_DIG  # MANT_DIG == C++ digits
@@ -218,8 +218,8 @@ class GeodesicExact(_GeodesicBase):
         '''Set up a L{GeodesicAreaExact} to compute area and
            perimeter of a polygon.
 
-           @kwarg polyline: If C{True} perimeter only, otherwise
-                            area and perimeter (C{bool}).
+           @kwarg polyline: If C{True}, compute the perimeter only, otherwise
+                            the perimeter and area (C{bool}).
            @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @return: A L{GeodesicAreaExact} instance.

pygeodesy/geodesicx/gxarea.py

@@ -30,7 +30,7 @@ from pygeodesy.props import Property, Property_RO, property_RO
 from math import fmod as _fmod
 
 __all__ = ()
-__version__ = '24.05.19'
+__version__ = '24.08.13'
 
 
 class GeodesicAreaExact(_NamedBase):
@@ -413,8 +413,8 @@ class PolygonArea(GeodesicAreaExact):
 
            @arg earth: A geodesic (L{GeodesicExact}, I{wrapped}
                        C{Geodesic} or L{GeodesicSolve}).
-           @kwarg polyline: If C{True} perimeter only, otherwise
-                            area and perimeter (C{bool}).
+           @kwarg polyline: If C{True}, compute the perimeter only, otherwise
+                            perimeter and area (C{bool}).
            @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @raise GeodesicError: Invalid B{C{earth}}.

pygeodesy/geodsolve.py

@@ -24,7 +24,7 @@ from pygeodesy.solveBase import _SolveGDictBase, _SolveGDictLineBase
 from pygeodesy.utily import _unrollon, _Wrap, wrap360
 
 __all__ = _ALL_LAZY.geodsolve
-__version__ = '24.07.11'
+__version__ = '24.08.13'
 
 
 class _GeodesicSolveBase(_SolveGDictBase):
@@ -101,8 +101,8 @@ class GeodesicSolve(_GeodesicSolveBase):
         '''Set up a L{GeodesicAreaExact} to compute area and perimeter
            of a polygon.
 
-           @kwarg polyline: If C{True} perimeter only, otherwise area
-                            and perimeter (C{bool}).
+           @kwarg polyline: If C{True}, compute the perimeter only, otherwise
+                            perimeter and area (C{bool}).
            @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @return: A L{GeodesicAreaExact} instance.