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

pygeodesy/fsums.py

@@ -25,27 +25,29 @@ from __future__ import division as _; del _  # PYCHOK semicolon
 
 from pygeodesy.basics import isbool, iscomplex, isint, isscalar, \
                             _signOf, itemsorted, signOf, _xiterable, \
-                            _enquote
+                            _xiterablen,  _enquote
 from pygeodesy.constants import INT0, _isfinite, NEG0, _pos_self, \
                                _0_0, _1_0, _N_1_0,  Float, Int
-from pygeodesy.errors import _OverflowError, _TypeError, _ValueError, \
-                             _xError, _xError2, _xkwds_get
+from pygeodesy.errors import _OverflowError, _TypeError, _UnexpectedError, \
+                             _ValueError, _xError, _xError2, _xkwds_get1, \
+                             _xkwds_pop2
 # from pygeodesy.internals import _enquote  # from .basics
 from pygeodesy.interns import NN, _arg_, _COMMASPACE_, _DASH_, _DOT_, \
                              _EQUAL_, _from_, _LANGLE_, _NOTEQUAL_, \
                              _not_finite_, _PERCENT_, _PLUS_, \
                              _RANGLE_, _SLASH_, _SPACE_, _STAR_, _UNDER_
 from pygeodesy.lazily import _ALL_LAZY, _getenv, _sys_version_info2
-from pygeodesy.named import _Named, _NamedTuple, _NotImplemented
+from pygeodesy.named import _name__, _name2__, _Named, _NamedTuple, \
+                            _NotImplemented
 from pygeodesy.props import _allPropertiesOf_n, deprecated_property_RO, \
-                             Property_RO, property_RO
+                             Property, Property_RO, property_RO
 from pygeodesy.streprs import Fmt, fstr, unstr
 # from pygeodesy.units import Float, Int  # from .constants
 
 from math import ceil as _ceil, fabs, floor as _floor  # PYCHOK used! .ltp
 
 __all__ = _ALL_LAZY.fsums
-__version__ = '24.05.13'
+__version__ = '24.05.29'
 
 _add_op_      = _PLUS_  # in .auxilats.auxAngle
 _eq_op_       = _EQUAL_ * 2  # _DEQUAL_
@@ -281,9 +283,15 @@ def _2sum(a, b):  # by .testFmath
     raise _OverflowError(u, txt=t)
 
 
-def _threshold(threshold):
-    '''(INTERNAL) Get the L{ResidualError}s threshold.
+def _threshold(threshold=_0_0, **kwds):
+    '''(INTERNAL) Get the L{ResidualError}s threshold,
+       optionally from single kwds C{B{RESIDUAL}=scalar}.
     '''
+    if kwds:
+        threshold, kwds = _xkwds_pop2(kwds, RESIDUAL=threshold)
+#       threshold = kwds.pop('RESIDUAL', threshold)
+        if kwds:
+            raise _UnexpectedError(**kwds)
     try:
         return _2finite(threshold)  # PYCHOK None
     except Exception as x:
@@ -320,21 +328,21 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
     def __init__(self, *xs, **name_RESIDUAL):
         '''New L{Fsum} for I{running} precision floating point summation.
 
-           @arg xs: No, one or more items to add (each C{scalar} or an L{Fsum}
-                    or L{Fsum2Tuple} instance), all positional.
-           @kwarg name_RESIDUAL: Optional C{B{name}=NN} for this L{Fsum} and
-                       the C{B{RESIDUAL}=0.0} threshold for L{ResidualError}s.
+           @arg xs: No, one or more initial items to add (each C{scalar} or
+                    an L{Fsum} or L{Fsum2Tuple} instance), all positional.
+           @kwarg name_RESIDUAL: Optional C{B{name}=NN} (C{str}) for this
+                       L{Fsum} and the C{B{RESIDUAL}=0.0} threshold for
+                       L{ResidualError}s (C{scalar}).
 
            @see: Methods L{Fsum.fadd} and L{Fsum.RESIDUAL}.
         '''
         if name_RESIDUAL:
-
-            def _n_R(name=NN, RESIDUAL=None):
-                return name, RESIDUAL
-
-            n, R = _n_R(**name_RESIDUAL)
-            if R is not None:
-                self.RESIDUAL(R)
+            n, kwds = _name2__(**name_RESIDUAL)
+            if kwds:
+                R =  Fsum._RESIDUAL
+                t = _threshold(R, **kwds)
+                if t != R:
+                    self._RESIDUAL = t
             if n:
                 self.name = n
 
@@ -391,9 +399,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
            in Python 2- and remainder C{mod} an L{Fsum} instance.
 
            @arg other: An L{Fsum}, L{Fsum2Tuple} or C{scalar} modulus.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @raise ResidualError: Non-zero, significant residual or invalid
                                  B{C{RESIDUAL}}.
@@ -543,9 +551,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
            @arg other: The exponent (C{scalar}, L{Fsum} or L{Fsum2Tuple}).
            @arg mod: Optional modulus (C{int} or C{None}) for the 3-argument
                      C{pow(B{self}, B{other}, B{mod})} version.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: This instance, updated (L{Fsum}).
 
@@ -601,9 +609,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         '''Apply C{B{self} /= B{other}} to this instance.
 
            @arg other: An L{Fsum}, L{Fsum2Tuple} or C{scalar} divisor.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: This instance, updated (L{Fsum}).
 
@@ -785,9 +793,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         '''Return C{B{self} / B{other}} as an L{Fsum}.
 
            @arg other: An L{Fsum}, L{Fsum2Tuple} or C{scalar} divisor.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: The quotient (L{Fsum}).
 
@@ -863,12 +871,15 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
             s = self.signOf()  # res=True
         return s
 
-    def copy(self, deep=False, name=NN):
+    def copy(self, deep=False, **name):
         '''Copy this instance, C{shallow} or B{C{deep}}.
 
+           @kwarg name: Optional, overriding C{B{name}='"copy"} (C{str}).
+
            @return: The copy (L{Fsum}).
          '''
-        f = _Named.copy(self, deep=deep, name=name)
+        n = _name__(name, name__=self.copy)
+        f = _Named.copy(self, deep=deep, name=n)
         if f._ps is self._ps:
             f._ps = list(self._ps)  # separate list
         if not deep:
@@ -879,7 +890,7 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
     def _copy_2(self, which, name=NN):
         '''(INTERNAL) Copy for I{dyadic} operators.
         '''
-        n =  name or which.__name__
+        n =  name or which.__name__  # _dunder_nameof
         # NOT .classof due to .Fdot(a, *b) args, etc.
         f = _Named.copy(self, deep=False, name=n)
         f._ps = list(self._ps)  # separate list
@@ -1091,9 +1102,29 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
             q -= 1
 #           t  = self.signOf()
 #           if t and t != s:
-#               raise self._Error(op, other, _AssertionError, txt=signOf.__name__)
+#               raise self._Error(op, other, _AssertionError, txt__=signOf)
         return DivMod2Tuple(q, self)  # q is C{int} in Python 3+, but C{float} in Python 2-
 
+    def _fhorner(self, x, cs, op):  # in .fmath
+        '''(INTERNAL) Add an L{Fhorner} evaluation of polynomial
+           M{sum(cs[i] * x**i for i=0..len(cs)-1)}.
+        '''
+        if _xiterablen(cs):
+            H = Fsum(name__=self._fhorner)
+            if _isFsumTuple(x):
+                _mul = H._mul_Fsum
+            else:
+                _mul = H._mul_scalar
+                x = _2float(x=x)
+            if len(cs) > 1 and x:
+                for c in reversed(cs):
+                    H._fset_ps(_mul(x, op))
+                    H._fadd(c, op, up=False)
+            else:  # x == 0
+                H = cs[0]
+            self._fadd(H, op)
+        return self
+
     def _finite(self, other, op=None):
         '''(INTERNAL) Return B{C{other}} if C{finite}.
         '''
@@ -1105,10 +1136,10 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
     def fint(self, name=NN, **raiser_RESIDUAL):
         '''Return this instance' current running sum as C{integer}.
 
-           @kwarg name: Optional name (C{str}), overriding C{"fint"}.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg name: Optional, overriding C{B{name}="fint"} (C{str}).
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: The C{integer} sum (L{Fsum}) if this instance C{is_integer}
                     with a zero or insignificant I{integer} residual.
@@ -1124,8 +1155,7 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
             if R:
                 t = _stresidual(_integer_, r, **R)
                 raise ResidualError(_integer_, i, txt=t)
-        f = self._copy_2(self.fint, name=name)
-        return f._fset(i)
+        return _Psum_(i, name=_name__(name, name__=self.fint))
 
     def fint2(self, **name):
         '''Return this instance' current running sum as C{int} and the
@@ -1139,7 +1169,7 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         '''
         return Fsum2Tuple(*self._fint2, **name)
 
-    @Property_RO
+    @Property
     def _fint2(self):  # see ._fset
         '''(INTERNAL) Get 2-tuple (C{int}, I{integer} residual).
         '''
@@ -1149,6 +1179,13 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         r = self._ps_1sum(i) if r and n > 1 else float(s - i)
         return i, (r or INT0)  # Fsum2Tuple?
 
+    @_fint2.setter_  # PYCHOK setter_underscore!
+    def _fint2(self, s):
+        '''(INTERNAL) Replace the C{_fint2} value.
+        '''
+        i = int(s)
+        return i, ((s - i) or INT0)
+
     @deprecated_property_RO
     def float_int(self):  # PYCHOK no cover
         '''DEPRECATED, use method C{Fsum.int_float}.'''
@@ -1200,9 +1237,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         '''Apply C{B{self} /= B{over}} and summate.
 
            @arg over: An L{Fsum} or C{scalar} denominator.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: Precision running sum (C{float}).
 
@@ -1233,7 +1270,7 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
             f = self._pow(other, other, op, **raiser_RESIDUAL)
         return self._fset(f)  # n=max(len(self), 1)
 
-    @Property_RO
+    @Property
     def _fprs(self):
         '''(INTERNAL) Get and cache this instance' precision
            running sum (C{float} or C{int}), ignoring C{residual}.
@@ -1244,7 +1281,13 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         s, _ = self._fprs2
         return s  # ._fprs2.fsum
 
-    @Property_RO
+    @_fprs.setter_  # PYCHOK setter_underscore!
+    def _fprs(self, s):
+        '''(INTERNAL) Replace the C{_fprs} value.
+        '''
+        return s
+
+    @Property
     def _fprs2(self):
         '''(INTERNAL) Get and cache this instance' precision
            running sum and residual (L{Fsum2Tuple}).
@@ -1268,6 +1311,12 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         # assert self._ps is ps
         return Fsum2Tuple(s, r)
 
+    @_fprs2.setter_  # PYCHOK setter_underscore!
+    def _fprs2(self, s_r):
+        '''(INTERNAL) Replace the C{_fprs2} value.
+        '''
+        return Fsum2Tuple(s_r)
+
     def fset_(self, *xs):
         '''Replace this instance' value with all positional items.
 
@@ -1300,27 +1349,22 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
             s = float(self._finite(other, **op)) if op else other
             self._ps[:] = s,
             self._n     = n or 1
-            if up:
-                i = int(s)  # see ._fint2
-                t = i, ((s - i) or INT0)
-                # Property_ROs _fint2, _fprs and _fprs2 can't be a Property:
-                # Property's _fset zaps the value just set by the @setter
-                self.__dict__.update(_fint2=t, _fprs=s, _fprs2=Fsum2Tuple(s, INT0))
+            if up:  # Property _fint2, _fprs and _fprs2 all have
+                # @.setter_underscore and NOT @.setter because the
+                # latter's _fset zaps the value set by @.setter
+                self._fint2 = s
+                self._fprs  = s
+                self._fprs2 = s, INT0
+                # assert self._fprs is s
         else:  # PYCHOK no cover
-            op = _xkwds_get(op, op=_fset_op_)
+            op = _xkwds_get1(op, op=_fset_op_)
             raise self._Error(op, other, _TypeError)
         return self
 
-    def _fset_ps(self, other, n=0):  # in .fmath
+    def _fset_ps(self, other):  # in .fmath
         '''(INTERNAL) Set partials from a known C{scalar}, L{Fsum} or L{Fsum2Tuple}.
         '''
-        if _isFsumTuple(other):
-            self._ps[:] = other._ps
-            self._n     = n or other._n
-        else:  # assert isscalar(other)
-            self._ps[:] = other,
-            self._n     = n or 1
-        return self
+        return self._fset(other, up=False)
 
     def fsub(self, xs=()):
         '''Subtract an iterable's items from this instance.
@@ -1399,13 +1443,13 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         '''
         return Fsum2Tuple(self._facc_1(xs)._fprs2, **name)
 
-    def fsum2(self, xs=(), name=NN):
+    def fsum2(self, xs=(), **name):
         '''Add an iterable's items, summate and return the
            current precision running sum I{and} the C{residual}.
 
            @arg xs: Iterable of items to add (each item C{scalar}
                     or an L{Fsum} or L{Fsum2Tuple} instance).
-           @kwarg name: Optional name (C{str}).
+           @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @return: L{Fsum2Tuple}C{(fsum, residual)} with C{fsum} the
                     current precision running sum and C{residual}, the
@@ -1493,9 +1537,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
     def int_float(self, **raiser_RESIDUAL):
         '''Return this instance' current running sum as C{int} or C{float}.
 
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: This C{integer} sum if this instance C{is_integer},
                     otherwise return the C{float} sum if the residual is
@@ -1550,9 +1594,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         '''Is this instance' running sum C{scalar} without residual or with
            a residual I{ratio} not exceeding the RESIDUAL threshold?
 
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to ignore
-                         L{ResidualError}s and C{B{RESIDUAL}=scalar} to override
-                         the L{RESIDUAL<Fsum.RESIDUAL>} threshold.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: C{True} if this instance' non-zero residual C{ratio} exceeds
                     the L{RESIDUAL<Fsum.RESIDUAL>} threshold (C{bool}).
@@ -1611,9 +1655,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
            @arg x: The exponent (C{scalar} or L{Fsum}).
            @arg mod: Optional modulus (C{int} or C{None}) for the 3-argument
                      C{pow(B{self}, B{other}, B{mod})} version.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: The C{pow(self, B{x})} or C{pow(self, B{x}, *B{mod})}
                     result (L{Fsum}).
@@ -1755,7 +1799,7 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         return self._pow_2_3(s, x, other, op, **raiser_RESIDUAL)
 
     def _ps_acc(self, ps, xs, up=True, **unused):
-        '''(INTERNAL) Accumulate C{xs} scalars into list C{ps}.
+        '''(INTERNAL) Accumulate C{xs} known scalars into list C{ps}.
         '''
         n   =  0
         _2s = _2sum
@@ -1820,7 +1864,7 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         if r and raiser:
             t = self._RESIDUAL
             if RESIDUAL:
-                t = _threshold(_xkwds_get(RESIDUAL, RESIDUAL=t))
+                t = _threshold(t, **RESIDUAL)
             if t < 0 or (s + r) != s:
                 q = (r / s) if s else s  # == 0.
                 if fabs(q) > fabs(t):
@@ -1895,9 +1939,9 @@ class Fsum(_Named):  # sync __methods__ with .vector3dBase.Vector3dBase
         '''Return C{B{self}**(1 / B{root})} as L{Fsum}.
 
            @arg root: The order (C{scalar} or L{Fsum}), non-zero.
-           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} (C{bool}) to
-                         ignore L{ResidualError}s and C{B{RESIDUAL}=scalar}
-                         to override the L{RESIDUAL<Fsum.RESIDUAL>}.
+           @kwarg raiser_RESIDUAL: Use C{B{raiser}=False} to ignore
+                         L{ResidualError}s (C{bool}) and C{B{RESIDUAL}=scalar}
+                         to override the current L{RESIDUAL<Fsum.RESIDUAL>}.
 
            @return: The C{self ** (1 / B{root})} result (L{Fsum}).
 
@@ -2182,7 +2226,7 @@ def fsum_(*xs, **floats):
 
        @see: Function L{fsum<fsums.fsum>} for further details.
     '''
-    return _fsum(xs if _xkwds_get(floats, floats=False) is True else
+    return _fsum(xs if _xkwds_get1(floats, floats=False) is True else
                 _2floats(xs, origin=1)) if xs else _0_0  # PYCHOK yield
 
 
@@ -2217,7 +2261,7 @@ def fsum1_(*xs, **floats):
 
        @see: Function L{fsum_<fsums.fsum_>} for further details.
     '''
-    return _fsum(_1primed(xs if _xkwds_get(floats, floats=False) is True else
+    return _fsum(_1primed(xs if _xkwds_get1(floats, floats=False) is True else
                          _2floats(xs, origin=1))) if xs else _0_0  # PYCHOK yield
 
 

pygeodesy/gars.py

@@ -13,14 +13,14 @@ by I{Charles Karney}.  See also U{Global Area Reference System
 <https://Earth-Info.NGA.mil/GandG/coordsys/grids/gars.html>}.
 '''
 
-# from pygeodesy.basics import isstr  # from .dms
+# 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, isstr  # parseDMS2
+from pygeodesy.dms import parse3llh,   Fmt  # parseDMS2
 from pygeodesy.errors import _ValueError, _xkwds
 from pygeodesy.interns import NN, _0to9_, _AtoZnoIO_, _COMMA_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_OTHER
-from pygeodesy.named import nameof, Property_RO
+from pygeodesy.named import _name__,  isstr, Property_RO
 from pygeodesy.namedTuples import LatLon2Tuple, LatLonPrec3Tuple
 # from pygeodesy.props import Property_RO  # from .named
 # from pygeodesy.streprs import Fmt  # from .dms
@@ -30,7 +30,7 @@ from pygeodesy.units import Int_, Lat, Lon, Precision_, Scalar_, \
 from math import floor
 
 __all__ = _ALL_LAZY.gars
-__version__ = '23.10.07'
+__version__ = '24.05.24'
 
 _Digits  = _0to9_
 _LatLen  =    2
@@ -112,7 +112,7 @@ class Garef(Str):
     '''Garef class, a named C{str}.
     '''
     # no str.__init__ in Python 3
-    def __new__(cls, cll, precision=1, name=NN):
+    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}.
 
@@ -121,7 +121,7 @@ class Garef(Str):
            @kwarg precision: Optional, the desired garef resolution
                              and length (C{int} 0..2), see function
                              L{gars.encode} for more details.
-           @kwarg name: Optional name (C{str}).
+           @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @return: New L{Garef}.
 
@@ -150,7 +150,7 @@ class Garef(Str):
             except AttributeError:
                 raise _xStrError(Garef, cll=cll)  # Error=GARSError
 
-        self = Str.__new__(cls, g, name=name or nameof(cll))
+        self = Str.__new__(cls, g, name=_name__(name, _or_nameof=cll))
         self._latlon    = ll
         self._precision = p
         return self
@@ -197,7 +197,7 @@ class Garef(Str):
               *self.latlon, **_xkwds(LatLon_kwds, name=self.name))
 
 
-def decode3(garef, center=True):
+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}).
@@ -245,10 +245,11 @@ def decode3(garef, center=True):
         lon += _0_5
         lat += _0_5
 
+    n = _name__(name, _or_nameof=garef)
     r = _Resolutions[precision]  # == 1.0 / unit
     return LatLonPrec3Tuple(Lat(lat * r, Error=GARSError),
                             Lon(lon * r, Error=GARSError),
-                            precision, name=nameof(garef))
+                            precision, name=n)
 
 
 def encode(lat, lon, precision=1):  # MCCABE 14

pygeodesy/geodesicw.py

@@ -18,7 +18,7 @@ from pygeodesy.constants import EPS, NAN, _EPSqrt as _TOL, _0_5
 from pygeodesy.datums import _earth_datum, _WGS84,  _EWGS84
 # from pygeodesy.dms import F_D  # from .latlonBase
 # from pygeodesy.ellipsoids import _EWGS84  # from .datums
-from pygeodesy.errors import IntersectionError, GeodesicError, _xkwds_pop2
+from pygeodesy.errors import IntersectionError, GeodesicError
 from pygeodesy.fsums import Fsum,  Fmt, unstr
 from pygeodesy.internals import _dunder_nameof, _under
 from pygeodesy.interns import NN, _DOT_, _SPACE_, _to_, _too_
@@ -26,7 +26,7 @@ from pygeodesy.karney import _atan2d, Caps, Direct9Tuple, GDict, \
                              _kWrapped, Inverse10Tuple
 from pygeodesy.latlonBase import LatLonBase as _LLB,  F_D, Radius_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS
-from pygeodesy.named import callername, classname
+from pygeodesy.named import callername, classname, _name1__, _name2__
 from pygeodesy.namedTuples import Destination3Tuple, Distance3Tuple
 from pygeodesy.props import Property, Property_RO, property_RO
 # from pygeodesy.streprs import Fmt, unstr  # from .fsums
@@ -37,7 +37,7 @@ from contextlib import contextmanager
 # from math import fabs  # from .utily
 
 __all__ = _ALL_LAZY.geodesicw
-__version__ = '24.05.14'
+__version__ = '24.05.24'
 
 _plumb_ = 'plumb'
 _TRIPS  =  65
@@ -66,20 +66,21 @@ class _gWrapped(_kWrapped):
             LINE_OFF =  0  # in .azimuthal._GnomonicBase and .css.CassiniSoldner
             _name    =  NN
 
-            def __init__(self, a_ellipsoid=_EWGS84, f=None, name=NN):  # PYCHOK signature
+            def __init__(self, a_ellipsoid=_EWGS84, f=None, **name):  # PYCHOK signature
                 '''New I{wrapped} C{geodesic.Geodesic} instance.
 
                    @arg a_ellipsoid: The equatorial radius I{a} (C{meter}, conventionally),
                                      an ellipsoid (L{Ellipsoid}) or a datum (L{Datum}).
                    @arg f: The ellipsoid's flattening (C{scalar}), ignored if B{C{a_ellipsoid})
                            is not C{meter}.
-                   @kwarg name: Optional name (C{str}).
+                   @kwarg name: Optional C{B{name}=NN} (C{str}).
                 '''
-                _earth_datum(self, a_ellipsoid, f=f, name=name)  # raiser=NN
-                with _wargs(self, *self.ellipsoid.a_f, name=name) as args:
+                _earth_datum(self, a_ellipsoid, f=f, **name)  # raiser=NN
+                E = self.ellipsoid
+                with _wargs(self, *E.a_f, **name) as args:
                     _Geodesic.__init__(self, *args)
                 if name:
-                    self._name = str(name)
+                    self._name, _ = _name2__(name, _or_nameof=E)
 
             def ArcDirect(self, lat1, lon1, azi1, a12, outmask=Caps._STD):
                 '''Return the C{_Geodesic.ArcDirect} result as L{GDict}.
@@ -266,7 +267,7 @@ class _gWrapped(_kWrapped):
             _geodesic = None
             _name     = NN
 
-            def __init__(self, geodesic, lat1, lon1, azi1, **caps_name_):  # salp1=NAN, calp1=NAN, name=NN
+            def __init__(self, geodesic, lat1, lon1, azi1, **caps_name_):  # salp1=NAN, calp1=NAN
                 '''New I{wrapped} C{geodesicline.GeodesicLine} instance.
 
                    @arg geodesic: A I{wrapped} C{Geodesic} instance.
@@ -281,10 +282,10 @@ class _gWrapped(_kWrapped):
                 '''
                 _xinstanceof(_wrapped.Geodesic, geodesic=geodesic)
                 with _wargs(self, geodesic, lat1, lon1, azi1, **caps_name_) as args:
-                    name, caps_ = _xkwds_pop2(caps_name_, name=geodesic.name)
-                    _GeodesicLine.__init__(self, *args, **caps_)
+                    name, caps_ = _name2__(caps_name_, _or_nameof=geodesic)
+                    _GeodesicLine.__init__(self, *args, **caps_)  # XXX avoid updates?
                     if name:
-                        self._name = str(name)
+                        self._name = name
                 self._geodesic = geodesic
 
             @Property_RO
@@ -428,7 +429,7 @@ class _gWrapped(_kWrapped):
 _wrapped = _gWrapped()  # PYCHOK singleton, .ellipsoids, .test/base.py
 
 
-def Geodesic(a_ellipsoid, f=None, name=NN):
+def Geodesic(a_ellipsoid, f=None, **name):
     '''Return a I{wrapped} C{geodesic.Geodesic} instance from I{Karney}'s
        Python U{geographiclib<https://PyPI.org/project/geographiclib>},
        provide the latter is installed, otherwise an C{ImportError}.
@@ -437,9 +438,10 @@ def Geodesic(a_ellipsoid, f=None, name=NN):
               or the equatorial radius I{a} of the ellipsoid (C{meter}).
        @arg f: The flattening of the ellipsoid (C{scalar}), ignored if
                B{C{a_ellipsoid}}) is not specified as C{meter}.
-       @kwarg name: Optional ellipsoid name (C{str}), ignored like B{C{f}}.
+       @kwarg name: Optional ellipsoid C{B{name}=NN} (C{str}), ignored
+                    like B{C{f}}.
     '''
-    return _wrapped.Geodesic(a_ellipsoid, f=f, name=name)
+    return _wrapped.Geodesic(a_ellipsoid, f=f, **name)
 
 
 def GeodesicLine(geodesic, lat1, lon1, azi1, caps=Caps._STD_LINE):
@@ -479,8 +481,8 @@ class _wargs(object):  # see also .formy._idllmn6, .latlonBase._toCartesian3, .v
         try:
             yield args
         except Exception as x:
-            n = _DOT_(classname(inst), callername(up=2, underOK=True))
-            raise GeodesicError(unstr(n, *args, **kwds), cause=x)
+            u = _DOT_(classname(inst), callername(up=2, underOK=True))
+            raise GeodesicError(unstr(u, *args, **_name1__(kwds)), cause=x)
 
 _wargs = _wargs()  # PYCHOK singleton
 

pygeodesy/geodesicx/__init__.py

@@ -23,7 +23,7 @@ from pygeodesy.karney import Caps, GeodesicError
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY
 
 __all__ = _ALL_LAZY.geodesicx + _ALL_DOCS(Caps, GeodesicError)
-__version__ = '23.12.03'
+__version__ = '24.05.31'
 
 # **) MIT License
 #

pygeodesy/geodesicx/__main__.py

@@ -5,7 +5,7 @@ u'''Print L{geodesicx} version, etc. using C{python -m pygeodesy.geodesicx}.
 '''
 
 __all__ = ()
-__version__ = '24.05.13'
+__version__ = '24.05.31'
 
 
 def _C4stats(nC4=None):  # PYCHOK no cover
@@ -88,4 +88,4 @@ _main()
 # OTHER DEALINGS IN THE SOFTWARE.
 
 # % python3 -m pygeodesy.geodesicx
-# pygeodesy.geodesicx.version=21.05.30, .C4Order=None, .C4len=5425, .C4set=5107, .C4set100=94, .C4x=465 (Python 3.9.5, 64bit, geographiclib 1.52)
+# pygeodesy.geodesicx.version=24.05.31, .C4len=5425, .C4order=30, .C4set=5107, .C4set_len=94.1%, .C4x=465 (Python 3.12.3, 64bit, arm64, geographiclib 2.0)