pygeodesy 24.5.15__py2.py3-none-any.whl → 24.5.24__py2.py3-none-any.whl

pygeodesy/geohash.py

@@ -26,9 +26,9 @@ from pygeodesy.fmath import favg
 from pygeodesy.interns import NN, _COMMA_, _DOT_, _E_, _N_, _NE_, _NW_, \
                              _S_, _SE_, _SW_, _W_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS, _ALL_OTHER
-from pygeodesy.named import _NamedDict, _NamedTuple, nameof, _xnamed
-from pygeodesy.namedTuples import Bounds2Tuple, Bounds4Tuple, \
-                                  LatLon2Tuple, PhiLam2Tuple
+from pygeodesy.named import _name__, _NamedDict, _NamedTuple, nameof, _xnamed
+from pygeodesy.namedTuples import Bounds2Tuple, Bounds4Tuple, LatLon2Tuple, \
+                                  PhiLam2Tuple
 from pygeodesy.props import deprecated_function, deprecated_method, \
                             deprecated_property_RO, Property_RO, property_RO
 from pygeodesy.streprs import fstr
@@ -38,7 +38,7 @@ from pygeodesy.units import Degrees_, Int, Lat, Lon, Precision_, Str, \
 from math import fabs, ldexp, log10, radians
 
 __all__ = _ALL_LAZY.geohash
-__version__ = '23.12.18'
+__version__ = '24.05.23'
 
 
 class _GH(object):
@@ -71,34 +71,35 @@ class _GH(object):
     @Property_RO
     def Sizes(self):  # lat-, lon and radial size (in meter)
         # ... where radial = sqrt(latSize * lonWidth / PI)
-        return (_floatuple(20032e3, 20000e3, 11292815.096),  # 0
-                _floatuple( 5003e3,  5000e3,  2821794.075),  # 1
-                _floatuple(  650e3,  1225e3,   503442.397),  # 2
-                _floatuple(  156e3,   156e3,    88013.575),  # 3
-                _floatuple(  19500,   39100,    15578.683),  # 4
-                _floatuple(   4890,    4890,     2758.887),  # 5
-                _floatuple(    610,    1220,      486.710),  # 6
-                _floatuple(    153,     153,       86.321),  # 7
-                _floatuple(     19.1,    38.2,     15.239),  # 8
-                _floatuple(      4.77,    4.77,     2.691),  # 9
-                _floatuple(      0.596,   1.19,     0.475),  # 10
-                _floatuple(      0.149,   0.149,    0.084),  # 11
-                _floatuple(      0.0186,  0.0372,   0.015))  # 12  _MaxPrec
+        _t = _floatuple
+        return (_t(20032e3, 20000e3, 11292815.096),  # 0
+                _t( 5003e3,  5000e3,  2821794.075),  # 1
+                _t(  650e3,  1225e3,   503442.397),  # 2
+                _t(  156e3,   156e3,    88013.575),  # 3
+                _t(  19500,   39100,    15578.683),  # 4
+                _t(   4890,    4890,     2758.887),  # 5
+                _t(    610,    1220,      486.710),  # 6
+                _t(    153,     153,       86.321),  # 7
+                _t(     19.1,    38.2,     15.239),  # 8
+                _t(      4.77,    4.77,     2.691),  # 9
+                _t(      0.596,   1.19,     0.475),  # 10
+                _t(      0.149,   0.149,    0.084),  # 11
+                _t(      0.0186,  0.0372,   0.015))  # 12  _MaxPrec
 
 _GH      = _GH()  # PYCHOK singleton
 _MaxPrec =  12
 
 
-def _2bounds(LatLon, LatLon_kwds, s, w, n, e, name=NN):
+def _2bounds(LatLon, LatLon_kwds, s, w, n, e, **name):
     '''(INTERNAL) Return SW and NE bounds.
     '''
     if LatLon is None:
-        r = Bounds4Tuple(s, w, n, e, name=name)
+        r    =  Bounds4Tuple(s, w, n, e, **name)
     else:
-        sw = _xnamed(LatLon(s, w, **LatLon_kwds), name)
-        ne = _xnamed(LatLon(n, e, **LatLon_kwds), name)
-        r  =  Bounds2Tuple(sw, ne, name=name)
-    return r  # _xnamed(r, name)
+        kwds = _xkwds(LatLon_kwds, **name)
+        r    =  Bounds2Tuple(LatLon(s, w, **kwds),
+                             LatLon(n, e, **kwds), **name)
+    return r
 
 
 def _2center(bounds):
@@ -128,11 +129,11 @@ def _2geostr(geohash):
     '''
     try:
         if not (0 < len(geohash) <= _MaxPrec):
-            raise ValueError
+            raise ValueError()
         geostr = geohash.lower()
         for c in geostr:
             if c not in _GH.DecodedBase32:
-                raise ValueError
+                raise ValueError()
         return geostr
     except (AttributeError, TypeError, ValueError) as x:
         raise GeohashError(Geohash.__name__, geohash, cause=x)
@@ -142,7 +143,7 @@ class Geohash(Str):
     '''Geohash class, a named C{str}.
     '''
     # no str.__init__ in Python 3
-    def __new__(cls, cll, precision=None, name=NN):
+    def __new__(cls, cll, precision=None, **name):
         '''New L{Geohash} from an other L{Geohash} instance or C{str}
            or from a C{LatLon} instance or C{str}.
 
@@ -150,7 +151,7 @@ class Geohash(Str):
            @kwarg precision: Optional, the desired geohash length (C{int}
                              1..12), see function L{geohash.encode} for
                              some examples.
-           @kwarg name: Optional name (C{str}).
+           @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @return: New L{Geohash}.
 
@@ -177,7 +178,7 @@ class Geohash(Str):
             except AttributeError:
                 raise _xStrError(Geohash, cll=cll, Error=GeohashError)
 
-        self = Str.__new__(cls, gh, name=name or nameof(cll))
+        self = Str.__new__(cls, gh, name=_name__(name, _or_nameof=cll))
         self._latlon = ll
         return self
 
@@ -186,12 +187,12 @@ class Geohash(Str):
         '''DEPRECATED, use property C{philam}.'''
         return self.philam
 
-    def adjacent(self, direction, name=NN):
+    def adjacent(self, direction, **name):
         '''Determine the adjacent cell in the given compass direction.
 
            @arg direction: Compass direction ('N', 'S', 'E' or 'W').
-           @kwarg name: Optional name (C{str}), otherwise the name
-                        of this cell plus C{.D}irection.
+           @kwarg name: Optional C{B{name}=NN} (C{str}) otherwise this
+                        cell's name, either extended with C{.D}irection.
 
            @return: Geohash of adjacent cell (L{Geohash}).
 
@@ -215,7 +216,7 @@ class Geohash(Str):
         if p and (c in _GH.Borders[D][e]):
             p = Geohash(p).adjacent(D)
 
-        n = name or self.name
+        n = self._name__(name)
         if n:
             n = _DOT_(n, D)
         # append letter for direction to parent
@@ -242,7 +243,7 @@ class Geohash(Str):
         '''
         r = self._bounds
         return r if LatLon is None else \
-              _2bounds(LatLon, LatLon_kwds, *r, name=self.name)
+           _2bounds(LatLon, LatLon_kwds, *r, name=self.name)
 
     def _distanceTo(self, func_, other, **kwds):
         '''(INTERNAL) Helper for distances, see C{.formy._distanceTo*}.
@@ -532,21 +533,23 @@ def bounds(geohash, LatLon=None, **LatLon_kwds):
             i = _GH.DecodedBase32[c]
             for m in (16, 8, 4, 2, 1):
                 if d:  # longitude
-                    if i & m:
-                        w = _avg(w, e)
+                    a = _avg(w, e)
+                    if (i & m):
+                        w = a
                     else:
-                        e = _avg(w, e)
+                        e = a
                 else:  # latitude
-                    if i & m:
-                        s = _avg(s, n)
+                    a = _avg(s, n)
+                    if (i & m):
+                        s = a
                     else:
-                        n = _avg(s, n)
+                        n = a
                 d = not d
     except KeyError:
         raise GeohashError(geohash=geohash)
 
     return _2bounds(LatLon, LatLon_kwds, s, w, n, e,
-                                   name=nameof(geohash))
+                            name=nameof(geohash))  # _or_nameof=geohash
 
 
 def _bounds3(geohash):
@@ -598,7 +601,7 @@ def decode2(geohash, LatLon=None, **LatLon_kwds):
     '''
     t = map2(float, decode(geohash))
     r = LatLon2Tuple(t) if LatLon is None else LatLon(*t, **LatLon_kwds)  # *t
-    return _xnamed(r, decode2.__name__)
+    return _xnamed(r, name__=decode2)
 
 
 def decode_error(geohash):
@@ -636,19 +639,19 @@ def distance_(geohash1, geohash2):
 
 @deprecated_function
 def distance1(geohash1, geohash2):
-    '''DEPRECATED, used L{geohash.distance_}.'''
+    '''DEPRECATED, use L{geohash.distance_}.'''
     return distance_(geohash1, geohash2)
 
 
 @deprecated_function
 def distance2(geohash1, geohash2):
-    '''DEPRECATED, used L{geohash.equirectangular_}.'''
+    '''DEPRECATED, use L{geohash.equirectangular_}.'''
     return equirectangular_(geohash1, geohash2)
 
 
 @deprecated_function
 def distance3(geohash1, geohash2):
-    '''DEPRECATED, used L{geohash.haversine_}.'''
+    '''DEPRECATED, use L{geohash.haversine_}.'''
     return haversine_(geohash1, geohash2)
 
 

pygeodesy/geoids.py

@@ -87,19 +87,19 @@ from pygeodesy.constants import EPS, _float as _F, _0_0, _1_0, _180_0, _360_0
 # from pygeodesy.datums import _ellipsoidal_datum  # from .heights
 # from pygeodesy.dms import parseDMS2  # _MODS
 from pygeodesy.errors import _incompatible, LenError, RangeError, SciPyError, \
-                             _SciPyIssue
+                             _SciPyIssue, _xkwds_pop2
 from pygeodesy.fmath import favg, Fdot, fdot, Fhorner, frange
 # from pygoedesy.formy import heightOrthometric  # _MODS
 from pygeodesy.heights import _as_llis2, _ascalar, _height_called, HeightError, \
                               _HeightsBase,  _ellipsoidal_datum, _Wrap
 # from pygeodesy.internals import _version2  # _MODS
 from pygeodesy.interns import MISSING, NN, _4_, _COLONSPACE_, _COMMASPACE_, \
-                             _cubic_, _E_, _height_, _in_, _kind_, _knots_, \
-                             _lat_, _linear_, _lon_, _mean_, _N_, _n_a_, \
-                             _not_, _numpy_, _on_, _outside_, _S_, _s_, _scipy_, \
-                             _SPACE_, _stdev_, _supported_, _tbd_, _W_, _width_
+                             _cubic_, _E_, _height_, _in_, _kind_, _lat_, \
+                             _linear_, _lon_, _mean_, _N_, _n_a_, _numpy_, \
+                             _on_, _outside_, _S_, _s_, _scipy_, _SPACE_, \
+                             _stdev_, _tbd_, _W_, _width_
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS, _FOR_DOCS
-from pygeodesy.named import _Named, _NamedTuple
+from pygeodesy.named import _name__, _Named, _NamedTuple
 # from pygeodesy.namedTuples import LatLon3Tuple  # _MODS
 from pygeodesy.props import deprecated_method, Property_RO, property_RO
 from pygeodesy.streprs import attrs, Fmt, fstr, pairs
@@ -118,21 +118,21 @@ except ImportError:  # Python 3+
     from io import BytesIO as _BytesIO  # PYCHOK expected
 
 __all__ = _ALL_LAZY.geoids
-__version__ = '24.05.13'
+__version__ = '24.05.23'
 
 _assert_ = 'assert'
 _bHASH_  =  b'#'
 _endian_ = 'endian'
 _format_ = '%s %r'
 _header_ = 'header'
-# temporarily hold a single instance for each int value
-_intCs = {}
+_intCs   = {}  # cache int value
 _interp2d_ks = {-2: _linear_,
                 -3: _cubic_,
                 -5: 'quintic'}
 _lli_             = 'lli'
 _non_increasing_  = 'non-increasing'
 _rb_              = 'rb'
+_supported_       = 'supported'
 
 
 class _GeoidBase(_HeightsBase):
@@ -237,11 +237,11 @@ class _GeoidBase(_HeightsBase):
         '''Interpolate the geoid height for one or several locations.
 
            @arg llis: One or more locations (C{LatLon}s), all positional.
-           @kwarg wrap_H: Keyword arguments C{B{wrap}=False, B{H}=False}.
-                       If C{B{wrap} is True}, wrap or I{normalize} all
-                       B{C{llis}} locations (C{bool}).  If C{B{H} is True},
-                       return the I{orthometric} height instead of the
-                       I{geoid} height at each location (C{bool}).
+           @kwarg wrap_H: Keyword arguments C{B{wrap}=False} (C{bool}) and
+                       C{B{H}=False} (C{bool}).  If C{B{wrap} is True},
+                       wrap or I{normalize} all B{C{llis}} locations.  If
+                       C{B{H} is True}, return the I{orthometric} height
+                       instead of the I{geoid} height at each location.
 
            @return: A single interpolated geoid (or orthometric) height
                     (C{float}) or a list or tuple of interpolated geoid
@@ -679,7 +679,7 @@ class _GeoidBase(_HeightsBase):
                                         self.highest, self.lowest)) + \
             attrs( _mean_, _stdev_,           prec=prec, Nones=False) + \
             attrs((_kind_, 'smooth')[:s],     prec=prec, Nones=False) + \
-            attrs( 'cropped', 'dtype', _endian_, 'hits', _knots_, 'nBytes',
+            attrs( 'cropped', 'dtype', _endian_, 'hits', 'knots', 'nBytes',
                    'sizeB', _scipy_, _numpy_, prec=prec, Nones=False)
         return _COLONSPACE_(self, sep.join(t))
 
@@ -753,12 +753,11 @@ class GeoidG2012B(_GeoidBase):
        Use any of the binary C{le} (little endian) or C{be} (big endian)
        C{g2012b*.bin} grid files.
     '''
-    def __init__(self, g2012b_bin, crop=None, datum=None,  # NAD 83 Ellipsoid
-                                   kind=3, name=NN, smooth=0):
+    def __init__(self, g2012b_bin, datum=None,  # NAD 83 Ellipsoid
+                                   kind=3, smooth=0, **name_crop):
         '''New L{GeoidG2012B} interpolator.
 
            @arg g2012b_bin: A C{GEOID12B} grid file name (C{.bin}).
-           @kwarg crop: Optional crop box, not supported (C{None}).
            @kwarg datum: Optional grid datum (L{Datum}, L{Ellipsoid}, L{Ellipsoid2}
                          or L{a_f2Tuple}), default C{WGS84}.
            @kwarg kind: C{scipy.interpolate} order (C{int}), use 1..5 for
@@ -767,17 +766,18 @@ class GeoidG2012B(_GeoidBase):
                         -2 for U{interp2d linear<https://docs.SciPy.org/doc/scipy/
                         reference/generated/scipy.interpolate.interp2d.html>}, -3
                         for C{interp2d cubic} or -5 for C{interp2d quintic}.
-           @kwarg name: Optional geoid name (C{str}).
            @kwarg smooth: Smoothing factor for U{RectBivariateSpline
                           <https://docs.SciPy.org/doc/scipy/reference/generated/
                           scipy.interpolate.RectBivariateSpline.html>}
                           only (C{int}).
+           @kwarg name_crop: Optional geoid C{B{name}=NN} (C{str}) and UNSUPPORTED
+                       keyword argument C{B{crop}}, use C{B{crop}=None} to ignore.
 
            @raise GeoidError: G2012B grid file B{C{g2012b_bin}} issue or invalid
                               B{C{crop}}, B{C{kind}} or B{C{smooth}}.
 
-           @raise ImportError: Package C{numpy} or C{scipy} not found or
-                               not installed.
+           @raise ImportError: Package C{numpy} or C{scipy} not found or not
+                               installed.
 
            @raise LenError: Grid file B{C{g2012b_bin}} axis mismatch.
 
@@ -791,10 +791,11 @@ class GeoidG2012B(_GeoidBase):
            @note: C{scipy.interpolate.interp2d} has been C{DEPRECATED}, specify
                   C{B{kind}=1..5} for C{scipy.interpolate.RectBivariateSpline}.
         '''
+        crop, name = _xkwds_pop2(name_crop, crop=None)
         if crop is not None:
-            raise GeoidError(crop=crop, txt=_not_(_supported_))
+            raise GeoidError(crop=crop, txt_not_=_supported_)
 
-        g = self._open(g2012b_bin, datum, kind, name, smooth)
+        g = self._open(g2012b_bin, datum, kind, _name__(**name), smooth)
         _ = self.numpy  # import numpy for ._load and
 
         try:
@@ -953,7 +954,7 @@ class GeoidKarney(_GeoidBase):
     _yx_hits =  0  # cache hits
 
     def __init__(self, egm_pgm, crop=None, datum=None,  # WGS84
-                                kind=3, name=NN, smooth=None):
+                                kind=3, **name_smooth):
         '''New L{GeoidKarney} interpolator.
 
            @arg egm_pgm: An U{EGM geoid dataset<https://GeographicLib.SourceForge.io/
@@ -968,8 +969,8 @@ class GeoidKarney(_GeoidBase):
                          or L{a_f2Tuple}), default C{WGS84}.
            @kwarg kind: Interpolation order (C{int}), 2 for C{bilinear} or 3
                         for C{cubic}.
-           @kwarg name: Optional geoid name (C{str}).
-           @kwarg smooth: Smoothing factor, unsupported (C{None}).
+           @kwarg name_smooth: Optional geoid C{B{name}=NN} (C{str}) and UNSUPPORTED
+                       keyword argument C{B{smooth}}, use C{B{smooth}=None} to ignore.
 
            @raise GeoidError: EGM dataset B{C{egm_pgm}} issue or invalid
                               B{C{crop}}, B{C{kind}} or B{C{smooth}}.
@@ -982,15 +983,16 @@ class GeoidKarney(_GeoidBase):
                   by calling the C{close} method or by using this instance
                   in a C{with B{GeoidKarney}(...) as ...} context.
         '''
+        smooth, name = _xkwds_pop2(name_smooth, smooth=None)
         if smooth is not None:
-            raise GeoidError(smooth=smooth, txt=_not_(_supported_))
+            raise GeoidError(smooth=smooth, txt_not_=_supported_)
 
         if kind in (2,):
             self._evH = self._ev2H
         elif kind not in (3,):
             raise GeoidError(kind=kind)
 
-        self._egm = g =  self._open(egm_pgm, datum, kind, name, smooth)
+        self._egm = g =  self._open(egm_pgm, datum, kind, _name__(**name), None)
         self._pgm = p = _PGM(g, pgm=egm_pgm, itemsize=self.u2B, sizeB=self.sizeB)
 
         self._Rendian =  self._4endian.replace(_4_, str(p.nlon))
@@ -1302,7 +1304,7 @@ class GeoidPGM(_GeoidBase):
     _endian  = '>u2'
 
     def __init__(self, egm_pgm, crop=None, datum=None,  # WGS84
-                                kind=3, name=NN, smooth=0):
+                                kind=3, smooth=0, **name):
         '''New L{GeoidPGM} interpolator.
 
            @arg egm_pgm: An U{EGM geoid dataset<https://GeographicLib.SourceForge.io/
@@ -1319,11 +1321,11 @@ class GeoidPGM(_GeoidBase):
                         -2 for U{interp2d linear<https://docs.SciPy.org/doc/scipy/
                         reference/generated/scipy.interpolate.interp2d.html>}, -3
                         for C{interp2d cubic} or -5 for C{interp2d quintic}.
-           @kwarg name: Optional geoid name (C{str}).
            @kwarg smooth: Smoothing factor for U{RectBivariateSpline
                           <https://docs.SciPy.org/doc/scipy/reference/generated/
                           scipy.interpolate.RectBivariateSpline.html>}
                           only (C{int}).
+           @kwarg name: Optional geoid C{B{name}=NN} (C{str}).
 
            @raise GeoidError: EGM dataset B{C{egm_pgm}} issue or invalid B{C{crop}},
                               B{C{kind}} or B{C{smooth}}.
@@ -1337,7 +1339,7 @@ class GeoidPGM(_GeoidBase):
            @raise SciPyWarning: A C{RectBivariateSpline} or C{inter2d}
                                 warning as exception.
 
-           @raise TypeError: Invalid B{C{datum}}.
+           @raise TypeError: Invalid B{C{datum}} or unexpected argument.
 
            @note: C{scipy.interpolate.interp2d} has been C{DEPRECATED}, specify
                   C{B{kind}=1..5} for C{scipy.interpolate.RectBivariateSpline}.
@@ -1358,7 +1360,7 @@ class GeoidPGM(_GeoidBase):
         np = self.numpy
         self._u2B = np.dtype(self.endian).itemsize
 
-        g = self._open(egm_pgm, datum, kind, name, smooth)
+        g = self._open(egm_pgm, datum, kind, _name__(**name), smooth)
         self._pgm = p = _PGM(g, pgm=egm_pgm, itemsize=self.u2B, sizeB=self.sizeB)
         if crop:
             g = p._cropped(g, abs(kind) + 1, *self._swne(crop))