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

pygeodesy/units.py

@@ -12,7 +12,7 @@ from pygeodesy.constants import EPS, EPS1, PI, PI2, PI_2, _umod_360, _0_0, \
 from pygeodesy.dms import F__F, F__F_, S_NUL, S_SEP, parseDMS, parseRad, \
                          _toDMS, toDMS
 from pygeodesy.errors import _AssertionError, _IsnotError, TRFError, UnitError, \
-                             _xkwds, _xkwds_item2
+                             _xkwds
 from pygeodesy.interns import NN, _band_, _bearing_, _degrees_, _degrees2_, \
                              _distance_, _E_, _easting_, _epoch_, _EW_, _feet_, \
                              _height_, _lam_, _lat_, _LatLon_, _lon_, _meter_, \
@@ -23,13 +23,13 @@ from pygeodesy.interns import NN, _band_, _bearing_, _degrees_, _degrees2_, \
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY, _ALL_MODS as _MODS, _getenv
 from pygeodesy.props import Property_RO
 # from pygeodesy.streprs import Fmt, fstr  # from .unitsBase
-from pygeodesy.unitsBase import _Error, Float, Fmt, fstr, Int, _NamedUnit, \
-                                 Radius, Str  # PYCHOK shared .namedTuples
+from pygeodesy.unitsBase import _Error, Float, Fmt, fstr, Int, _arg_name_arg2, \
+                                _NamedUnit, Radius, Str  # PYCHOK shared .namedTuples
 
 from math import degrees, radians
 
 __all__ = _ALL_LAZY.units
-__version__ = '24.05.10'
+__version__ = '24.05.20'
 
 _negative_falsed_ = 'negative, falsed'
 
@@ -46,15 +46,15 @@ class Float_(Float):
            @kwarg Error: Optional error to raise, overriding the default L{UnitError}.
            @kwarg low: Optional lower B{C{arg}} limit (C{float} or C{None}).
            @kwarg high: Optional upper B{C{arg}} limit (C{float} or C{None}).
-           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}}
-                            and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of separate
+                            B{C{arg}} and B{C{name}} ones.
 
            @returns: A C{Float_} instance.
 
            @raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         self = Float.__new__(cls, arg=arg, name=name, Error=Error)
         if (low is not None) and self < low:
             txt = Fmt.limit(below=Fmt.g(low, prec=6, ints=isinstance(self, Epoch)))
@@ -77,15 +77,15 @@ class Int_(Int):
            @kwarg Error: Optional error to raise, overriding the default C{UnitError}.
            @kwarg low: Optional lower B{C{arg}} limit (C{int} or C{None}).
            @kwarg high: Optional upper B{C{arg}} limit (C{int} or C{None}).
-           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}}
-                            and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of separate
+                            B{C{arg}} and B{C{name}} ones.
 
            @returns: An L{Int_} instance.
 
            @raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         self = Int.__new__(cls, arg=arg, name=name, Error=Error)
         if (low is not None) and self < low:
             txt = Fmt.limit(below=low)
@@ -118,7 +118,7 @@ class Bool(Int, _NamedUnit):
            @raise Error: Invalid B{C{arg}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         try:
             b = bool(arg)
         except Exception as x:  # XXX not ... as x:
@@ -193,7 +193,7 @@ class Degrees(Float):
                          range and L{pygeodesy.rangerrors} set to C{True}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         try:
             d = Float.__new__(cls, parseDMS(arg, suffix=suffix, clip=clip),
                                                   Error=Error,  name=name)
@@ -253,15 +253,15 @@ class Degrees_(Degrees):
            @kwarg suffix: Optional, valid compass direction suffixes (C{NSEW}).
            @kwarg low: Optional lower B{C{arg}} limit (C{float} or C{None}).
            @kwarg high: Optional upper B{C{arg}} limit (C{float} or C{None}).
-           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}}
-                            and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of separate
+                            B{C{arg}} and B{C{name}} ones.
 
            @returns: A C{Degrees} instance.
 
            @raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         self = Degrees.__new__(cls, arg=arg, name=name, Error=Error, suffix=suffix, clip=0)
         if (low is not None) and self < low:
             txt = Fmt.limit(below=low)
@@ -295,8 +295,8 @@ class Radians(Float):
            @kwarg suffix: Optional, valid compass direction suffixes (C{NSEW}).
            @kwarg clip: Optional B{C{arg}} range B{C{-clip..+clip}} (C{radians} or C{0}
                         or C{None} for unclipped).
-           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}}
-                            and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of separate
+                            B{C{arg}} and B{C{name}} ones.
 
            @returns: A C{Radians} instance.
 
@@ -304,7 +304,7 @@ class Radians(Float):
                          range and L{pygeodesy.rangerrors} set to C{True}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         try:
             return Float.__new__(cls, parseRad(arg, suffix=suffix, clip=clip),
                                                      Error=Error,  name=name)
@@ -324,8 +324,8 @@ class Radians(Float):
     def toRepr(self, std=False, **prec_fmt_ints):  # PYCHOK prec=8, ...
         '''Return a representation of this C{Radians}.
 
-           @kwarg std: If C{True} return the standard C{repr},
-                       otherwise the named representation (C{bool}).
+           @kwarg std: If C{True} return the standard C{repr}, otherwise
+                       the named representation (C{bool}).
 
            @see: Methods L{Radians.toStr}, L{Float.toRepr} and function
                  L{pygeodesy.toDMS} for more documentation.
@@ -354,15 +354,15 @@ class Radians_(Radians):
            @kwarg suffix: Optional, valid compass direction suffixes (C{NSEW}).
            @kwarg low: Optional lower B{C{arg}} limit (C{float} or C{None}).
            @kwarg high: Optional upper B{C{arg}} limit (C{float} or C{None}).
-           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}}
-                            and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of separate
+                            B{C{arg}} and B{C{name}} ones.
 
            @returns: A C{Radians_} instance.
 
            @raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         self = Radians.__new__(cls, arg=arg, name=name, Error=Error, suffix=suffix, clip=0)
         if (low is not None) and self < low:
             txt = Fmt.limit(below=low)
@@ -392,7 +392,7 @@ class Bearing(Degrees):
         '''New L{Bearing} instance, see L{Degrees}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         d =  Degrees.__new__(cls, arg=arg, name=name, Error=Error, suffix=_N_, clip=clip)
         b = _umod_360(d)  # 0 <= b < 360
         return d if b == d else Degrees.__new__(cls, arg=b, name=name, Error=Error)
@@ -438,15 +438,15 @@ class Easting(Float):
            @kwarg Error: Optional error to raise, overriding the default L{UnitError}.
            @kwarg falsed: The B{C{arg}} value includes false origin (C{bool}).
            @kwarg high: Optional upper B{C{arg}} easting limit (C{scalar} or C{None}).
-           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}}
-                            and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of separate
+                            B{C{arg}} and B{C{name}} ones.
 
            @returns: An C{Easting} instance.
 
            @raise Error: Invalid B{C{arg}}, above B{C{high}} or negative, falsed B{C{arg}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         self = Float.__new__(cls, arg=arg, name=name, Error=Error)
         if high and (self < 0 or self > high):  # like Veness
             raise _Error(cls, arg, name, Error)
@@ -465,7 +465,7 @@ class Epoch(Float_):  # in .ellipsoidalBase, .trf
         '''New L{Epoch} instance, see L{Float_}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         return arg if isinstance(arg, Epoch) else Float_.__new__(cls,
                arg=arg, name=name, Error=Error, low=low, high=high)
 
@@ -513,8 +513,8 @@ class FIx(Float_):
            @arg fi: The fractional index (C{float} or C{int}).
            @kwarg fin: Optional C{len}, the number of C{points}, the index
                        C{[n]} wrapped to C{[0]} (C{int} or C{None}).
-           @kwarg name_Error: Optional keyword argument C{B{name}=NN}
-                              and C{B{Error}=UnitError}.
+           @kwarg name_Error: Optional C{B{name}=NN} (C{str}) and keyword
+                       argument C{B{Error}=UnitError}.
 
            @return: The B{C{fi}} (named L{FIx}).
 
@@ -629,7 +629,7 @@ class Lam_(Lam):
         '''New L{Lam_} instance, see L{Lam} and L{Radians}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         d = Lam.__new__(cls, arg=arg, name=name, Error=Error, clip=clip)
         return Radians.__new__(cls, radians(d), name=name, Error=Error)
 
@@ -750,15 +750,15 @@ class Northing(Float):
            @kwarg Error: Optional error to raise, overriding the default L{UnitError}.
            @kwarg falsed: The B{C{arg}} value includes false origin (C{bool}).
            @kwarg high: Optional upper B{C{arg}} northing limit (C{scalar} or C{None}).
-           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}}
-                            and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of separate
+                            B{C{arg}} and B{C{name}} ones.
 
            @returns: A C{Northing} instance.
 
            @raise Error: Invalid B{C{arg}}, above B{C{high}} or negative, falsed B{C{arg}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         self = Float.__new__(cls, arg=arg, name=name, Error=Error)
         if high and (self < 0 or self > high):
             raise _Error(cls, arg, name, Error)
@@ -792,7 +792,7 @@ class Phi_(Phi):
         '''New L{Phi_} instance, see L{Phi} and L{Radians}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         d = Phi.__new__(cls, arg=arg, name=name, Error=Error, clip=clip)
         return Radians.__new__(cls, arg=radians(d), name=name, Error=Error)
 

pygeodesy/unitsBase.py

@@ -4,9 +4,9 @@
 u'''Basic C{Float}, C{Int} and C{Str}ing units classes.
 '''
 
-from pygeodesy.errors import UnitError, _XError, _xkwds_item2
+from pygeodesy.errors import _UnexpectedError, UnitError, _XError
 from pygeodesy.interns import NN, _degrees_, _degrees2_, _invalid_, \
-                             _meter_, _radians_, _radians2_, \
+                             _meter_, MISSING, _radians_, _radians2_, \
                              _radius_, _UNDER_,  _std_  # PYCHOK used!
 from pygeodesy.lazily import _ALL_DOCS, _ALL_LAZY
 from pygeodesy.named import modulename, _Named, property_doc_
@@ -14,7 +14,7 @@ from pygeodesy.named import modulename, _Named, property_doc_
 from pygeodesy.streprs import Fmt, fstr
 
 __all__ = _ALL_LAZY.unitsBase
-__version__ = '24.02.20'
+__version__ = '24.05.20'
 
 
 class _NamedUnit(_Named):
@@ -69,14 +69,14 @@ class Float(float, _NamedUnit):
            @kwarg Error: Optional error to raise, overriding the default
                          L{UnitError}.
            @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu
-                            of B{C{name}} and B{C{arg}}.
+                            of separate B{C{arg}} and B{C{name}} ones.
 
            @returns: A C{Float} instance.
 
            @raise Error: Invalid B{C{arg}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         try:
             self = float.__new__(cls, arg)
             if name:
@@ -146,15 +146,15 @@ class Int(int, _NamedUnit):
            @kwarg name: Optional instance name (C{str}).
            @kwarg Error: Optional error to raise, overriding the
                          default L{UnitError}.
-           @kwarg name_arg: Optional C{name=arg} keyword argument,
-                            inlieu of B{C{name}} and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu
+                            of separate B{C{arg}} and B{C{name}} ones.
 
            @returns: An C{Int} instance.
 
            @raise Error: Invalid B{C{arg}}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         try:
             self = int.__new__(cls, arg)
             if name:
@@ -223,8 +223,8 @@ class Str(str, _NamedUnit):
            @kwarg name: Optional instance name (C{str}).
            @kwarg Error: Optional error to raise, overriding the
                          default (C{ValueError}).
-           @kwarg name_arg: Optional C{name=arg} keyword argument,
-                            inlieu of B{C{name}} and B{C{arg}}.
+           @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu
+                            of separate B{C{arg}} and B{C{name}} ones.
 
            @returns: A L{Str} instance.
 
@@ -233,7 +233,7 @@ class Str(str, _NamedUnit):
            @see: Callable, not-nameable class L{pygeodesy.Str_}.
         '''
         if name_arg:
-            name, arg = _xkwds_item2(name_arg)
+            name, arg = _arg_name_arg2(arg, **name_arg)
         try:
             self = str.__new__(cls, arg)
             if name:
@@ -324,6 +324,19 @@ def _Error(clas, arg, name, Error, txt=_invalid_, x=None):
     return _XError(Error, n, arg, txt=txt, cause=x)
 
 
+def _arg_name_arg2(arg, name__=None, **name_arg):  # in .units
+    '''(INTERNAL) Get the 2-tuple C{(name, arg)}.
+    '''
+    if name__ is None:
+        t =  name_arg.popitem() if len(name_arg) == 1 else \
+            (MISSING, arg)
+    else:
+        t =  name__.__name__, arg
+    if name_arg:
+        raise _UnexpectedError(**name_arg)
+    return t
+
+
 __all__ += _ALL_DOCS(_NamedUnit)
 
 # **) MIT License

pygeodesy/ups.py

@@ -26,14 +26,14 @@ from pygeodesy.constants import EPS, EPS0, _EPSmin as _Tol90, \
                                 isnear90, _0_0, _0_5, _1_0, _2_0
 from pygeodesy.datums import _ellipsoidal_datum, _WGS84
 from pygeodesy.dms import degDMS, _neg, parseDMS2
-from pygeodesy.errors import RangeError, _ValueError
+from pygeodesy.errors import RangeError, _ValueError, _xkwds_pop2
 from pygeodesy.fmath import hypot, hypot1, sqrt0
 # from pygeodesy.internals import _under  # from .named
 from pygeodesy.interns import NN, _COMMASPACE_, _inside_, _N_, \
                              _pole_, _range_, _S_, _scale0_, \
                              _SPACE_, _std_, _to_, _UTM_
 from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS,  _getenv
-from pygeodesy.named import nameof, _xnamed,  _under
+from pygeodesy.named import nameof,  _under
 from pygeodesy.namedTuples import EasNor2Tuple, UtmUps5Tuple, \
                                   UtmUps8Tuple, UtmUpsLatLon5Tuple
 from pygeodesy.props import deprecated_method, property_doc_, \
@@ -49,7 +49,7 @@ from pygeodesy.utmupsBase import Fmt, _LLEB, _hemi, _parseUTMUPS5, _to4lldn, \
 from math import atan2, fabs, radians, tan
 
 __all__ = _ALL_LAZY.ups
-__version__ = '25.05.13'
+__version__ = '25.05.31'
 
 _BZ_UPS  = _getenv('PYGEODESY_UPS_POLES', _std_) == _std_
 _Falsing =  Meter(2000e3)  # false easting and northing (C{meter})
@@ -57,18 +57,6 @@ _K0_UPS  =  Float(_K0_UPS= 0.994)  # scale factor at central meridian
 _K1_UPS  =  Float(_K1_UPS=_1_0)    # rescale point scale factor
 
 
-def _scale(E, rho, tau):
-    # compute the point scale factor, ala Karney
-    t = hypot1(tau)
-    return Float(scale=(rho / E.a) * t * sqrt0(E.e21 + E.e2 / t**2))
-
-
-def _toBand(lat, lon):  # see utm._toBand
-    '''(INTERNAL) Get the I{polar} Band letter for a (lat, lon).
-    '''
-    return _Bands[(0 if lat < 0 else 2) + (0 if -180 < lon < 0 else 1)]
-
-
 class UPSError(_ValueError):
     '''Universal Polar Stereographic (UPS) parse or other L{Ups} issue.
     '''
@@ -88,7 +76,7 @@ class Ups(UtmUpsBase):
     def __init__(self, zone=0, pole=_N_, easting=_Falsing,  # PYCHOK expected
                                          northing=_Falsing, band=NN, datum=_WGS84,
                                          falsed=True, gamma=None, scale=None,
-                                         name=NN, **convergence):
+                                       **name_convergence):
         '''New L{Ups} UPS coordinate.
 
            @kwarg zone: UPS zone (C{int}, zero) or zone with/-out I{polar} Band
@@ -100,13 +88,13 @@ class Ups(UtmUpsBase):
            @kwarg band: Optional, I{polar} Band (C{str}, 'A'|'B'|'Y'|'Z').
            @kwarg datum: Optional, this coordinate's datum (L{Datum},
                          L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}).
-           @kwarg falsed: If C{True}, both B{C{easting}} and B{C{northing}}
-                          are falsed (C{bool}).
-           @kwarg gamma: Optional, meridian convergence to save (C{degrees}).
-           @kwarg scale: Optional, computed scale factor k to save
-                         (C{scalar}).
-           @kwarg name: Optional name (C{str}).
-           @kwarg convergence: DEPRECATED, use keyword argument C{B{gamma}=None}.
+           @kwarg falsed: If C{True}, both B{C{easting}} and B{C{northing}} are
+                          falsed (C{bool}).
+           @kwarg gamma: Optional meridian convergence, bearing off grid North,
+                         clockwise from true North to save (C{degrees}) or C{None}.
+           @kwarg scale: Optional grid scale factor to save (C{scalar}) or C{None}.
+           @kwarg name_convergence: Optional C{B{name}=NN} (C{str}) and DEPRECATED
+                       keyword argument C{B{convergence}=None}, use B{C{gamma}}.
 
            @raise TypeError: Invalid B{C{datum}}.
 
@@ -114,18 +102,19 @@ class Ups(UtmUpsBase):
                             B{C{northing}}, B{C{band}}, B{C{convergence}}
                             or B{C{scale}}.
         '''
-        if name:
-            self.name = name
-
+        if name_convergence:
+            gamma, name = _xkwds_pop2(name_convergence, convergence=gamma)
+            if name:
+                self.name = name
         try:
-            z, B, p = _to3zBhp(zone, band, hemipole=pole)
+            z, B, self._pole = _to3zBhp(zone, band, hemipole=pole)
             if z != _UPS_ZONE or (B and (B not in _Bands)):
                 raise ValueError
         except (TypeError, ValueError) as x:
             raise UPSError(zone=zone, pole=pole, band=band, cause=x)
-        self._pole = p
+
         UtmUpsBase.__init__(self, easting, northing, band=B, datum=datum, falsed=falsed,
-                                                     gamma=gamma, scale=scale, **convergence)
+                                                             gamma=gamma, scale=scale)
 
     def __eq__(self, other):
         return isinstance(other, Ups) and other.zone     == self.zone \
@@ -161,13 +150,11 @@ class Ups(UtmUpsBase):
         f = _Falsing if self.falsed else 0
         return EasNor2Tuple(f, f)
 
-    def parse(self, strUPS, name=NN):
+    def parse(self, strUPS, **name):
         '''Parse a string to a similar L{Ups} instance.
 
-           @arg strUPS: The UPS coordinate (C{str}),
-                        see function L{parseUPS5}.
-           @kwarg name: Optional instance name (C{str}),
-                        overriding this name.
+           @arg strUPS: The UPS coordinate (C{str}), see function L{parseUPS5}.
+           @kwarg name: Optional C{B{name}=NN} (C{str}), overriding this name.
 
            @return: The similar instance (L{Ups}).
 
@@ -176,7 +163,7 @@ class Ups(UtmUpsBase):
            @see: Functions L{parseUTM5} and L{pygeodesy.parseUTMUPS5}.
         '''
         return parseUPS5(strUPS, datum=self.datum, Ups=self.classof,
-                                 name=name or self.name)
+                                  name=self._name__(name))
 
     @deprecated_method
     def parseUPS(self, strUPS):  # PYCHOK no cover
@@ -250,9 +237,8 @@ class Ups(UtmUpsBase):
             b, g, a = atan2(x, y), -1, _neg(a)
         ll = _LLEB(a, degrees180(b), datum=self._datum, name=self.name)
 
-        ll._gamma =  b * g
-        ll._scale = _scale(E, r, t) if r > 0 else self.scale0
-        self._latlon5args(ll, _toBand, unfalse)
+        k  = _scale(E, r, t) if r > 0 else self.scale0
+        self._latlon5args(ll, g * b, k, _toBand, unfalse)
 
     def toRepr(self, prec=0, fmt=Fmt.SQUARE, sep=_COMMASPACE_, B=False, cs=False, **unused):  # PYCHOK expected
         '''Return a string representation of this UPS coordinate.
@@ -353,7 +339,7 @@ class _Ups_K1(Ups):
     _scale0 = _K1_UPS
 
 
-def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, name=NN):
+def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, **name):
     '''Parse a string representing a UPS coordinate, consisting of
        C{"[zone][band] pole easting northing"} where B{C{zone}} is
        pseudo zone C{"00"|"0"|""} and C{band} is C{'A'|'B'|'Y'|'Z'|''}.
@@ -362,8 +348,9 @@ def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, name=NN):
        @kwarg datum: Optional datum to use (L{Datum}).
        @kwarg Ups: Optional class to return the UPS coordinate (L{Ups})
                    or C{None}.
-       @kwarg falsed: Both B{C{easting}} and B{C{northing}} are falsed (C{bool}).
-       @kwarg name: Optional B{C{Ups}} name (C{str}).
+       @kwarg falsed: If C{True}, both B{C{easting}} and B{C{northing}}
+                      are falsed (C{bool}).
+       @kwarg name: Optional B{C{Ups}} C{B{name}=NN} (C{str}).
 
        @return: The UPS coordinate (B{C{Ups}}) or a
                 L{UtmUps5Tuple}C{(zone, hemipole, easting, northing,
@@ -376,43 +363,54 @@ def parseUPS5(strUPS, datum=_WGS84, Ups=Ups, falsed=True, name=NN):
     if z != _UPS_ZONE or (B and B not in _Bands):
         raise UPSError(strUPS=strUPS, zone=z, band=B)
 
-    r = UtmUps5Tuple(z, p, e, n, B, Error=UPSError) if Ups is None \
-            else Ups(z, p, e, n, band=B, falsed=falsed, datum=datum)
-    return _xnamed(r, name)
+    r = UtmUps5Tuple(z, p, e, n, B, Error=UPSError, **name) if Ups is None \
+            else Ups(z, p, e, n, band=B, falsed=falsed, datum=datum, **name)
+    return r
+
+
+def _scale(E, rho, tau):
+    # compute the point scale factor, ala Karney
+    t = hypot1(tau)
+    return Float(scale=(rho / E.a) * t * sqrt0(E.e21 + E.e2 / t**2))
+
+
+def _toBand(lat, lon):  # see utm._toBand
+    '''(INTERNAL) Get the I{polar} Band letter for a (lat, lon).
+    '''
+    return _Bands[(0 if lat < 0 else 2) + (0 if -180 < lon < 0 else 1)]
 
 
 def toUps8(latlon, lon=None, datum=None, Ups=Ups, pole=NN,
-                             falsed=True, strict=True, name=NN):
+                             falsed=True, strict=True, **name):
     '''Convert a lat-/longitude point to a UPS coordinate.
 
-       @arg latlon: Latitude (C{degrees}) or an (ellipsoidal)
-                    geodetic C{LatLon} point.
+       @arg latlon: Latitude (C{degrees}) or an (ellipsoidal) geodetic
+                    C{LatLon} point.
        @kwarg lon: Optional longitude (C{degrees}) or C{None} if
                    B{C{latlon}} is a C{LatLon}.
-       @kwarg datum: Optional datum for this UPS coordinate,
-                     overriding B{C{latlon}}'s datum (C{Datum},
-                     L{Ellipsoid}, L{Ellipsoid2} or L{a_f2Tuple}).
-       @kwarg Ups: Optional class to return the UPS coordinate
-                   (L{Ups}) or C{None}.
+       @kwarg datum: Optional datum for this UPS coordinate, overriding
+                     B{C{latlon}}'s datum (C{Datum}, L{Ellipsoid},
+                     L{Ellipsoid2} or L{a_f2Tuple}).
+       @kwarg Ups: Optional class to return the UPS coordinate (L{Ups})
+                   or C{None}.
        @kwarg pole: Optional top/center of (stereographic) projection
                     (C{str}, C{'N[orth]'} or C{'S[outh]'}).
-       @kwarg falsed: False both easting and northing (C{bool}).
+       @kwarg falsed: If C{True}, false both easting and northing (C{bool}).
        @kwarg strict: Restrict B{C{lat}} to UPS ranges (C{bool}).
-       @kwarg name: Optional B{C{Ups}} name (C{str}).
+       @kwarg name: Optional B{C{Ups}} C{B{name}=NN} (C{str}).
 
-       @return: The UPS coordinate (B{C{Ups}}) or a
-                L{UtmUps8Tuple}C{(zone, hemipole, easting, northing,
-                band, datum, gamma, scale)} if B{C{Ups}} is C{None}.
-                The C{hemipole} is the C{'N'|'S'} pole, the UPS
-                projection top/center.
+       @return: The UPS coordinate (B{C{Ups}}) or a L{UtmUps8Tuple}C{(zone,
+                hemipole, easting, northing, band, datum, gamma, scale)} if
+                B{C{Ups}} is C{None}.  The C{hemipole} is the C{'N'|'S'}
+                pole, the UPS projection top/center.
 
        @raise RangeError: If B{C{strict}} and B{C{lat}} outside the valid
                           UPS bands or if B{C{lat}} or B{C{lon}} outside
                           the valid range and L{pygeodesy.rangerrors} set
                           to C{True}.
 
-       @raise TypeError: If B{C{latlon}} is not ellipsoidal or
-                         B{C{datum}} invalid.
+       @raise TypeError: If B{C{latlon}} is not ellipsoidal or if B{C{datum}}
+                         is invalid.
 
        @raise ValueError: If B{C{lon}} value is missing or if B{C{latlon}}
                           is invalid.
@@ -463,9 +461,7 @@ def toUps8(latlon, lon=None, datum=None, Ups=Ups, pole=NN,
         r = Ups(z, p, x, y, band=B, datum=d, falsed=falsed,
                                     gamma=g, scale=k, name=n)
         if isinstance(latlon, _LLEB) and d is latlon.datum:  # see utm._toXtm8
-            r._latlon5args(latlon, _toBand, falsed)  # XXX weakref(latlon)?
-            latlon._gamma = g
-            latlon._scale = k
+            r._latlon5args(latlon, g, k, _toBand, falsed)  # XXX weakref(latlon)?
         else:
             r._hemisphere = _hemi(lat)
             if not r._band:
@@ -473,18 +469,18 @@ def toUps8(latlon, lon=None, datum=None, Ups=Ups, pole=NN,
     return r
 
 
-def upsZoneBand5(lat, lon, strict=True, name=NN):
+def upsZoneBand5(lat, lon, strict=True, **name):
     '''Return the UTM/UPS zone number, I{polar} Band letter, pole and
        clipped lat- and longitude for a given location.
 
        @arg lat: Latitude in degrees (C{scalar} or C{str}).
        @arg lon: Longitude in degrees (C{scalar} or C{str}).
        @kwarg strict: Restrict B{C{lat}} to UPS ranges (C{bool}).
-       @kwarg name: Optional name (C{str}).
+       @kwarg name: Optional B{C{Ups}} C{B{name}=NN} (C{str}).
 
-       @return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole,
-                lat, lon)} where C{hemipole} is the C{'N'|'S'} pole,
-                the UPS projection top/center and C{lon} [-180..180).
+       @return: A L{UtmUpsLatLon5Tuple}C{(zone, band, hemipole, lat,
+                lon)} where C{hemipole} is the C{'N'|'S'} pole, the
+                UPS projection top/center and C{lon} [-180..180).
 
        @note: The C{lon} is set to C{0} if B{C{lat}} is C{-90} or
               C{90}, see env variable C{PYGEODESY_UPS_POLES} in
@@ -514,7 +510,7 @@ def upsZoneBand5(lat, lon, strict=True, name=NN):
 
     else:
         B, p = NN, _hemi(lat)
-    return UtmUpsLatLon5Tuple(z, B, p, lat, lon, Error=UPSError, name=name)
+    return UtmUpsLatLon5Tuple(z, B, p, lat, lon, Error=UPSError, **name)
 
 # **) MIT License
 #

pygeodesy/utily.py

@@ -17,7 +17,7 @@ from pygeodesy.constants import EPS, EPS0, INF, NAN, PI, PI2, PI_2, R_M, \
                                _N_180_0, _360_0, _400_0, _copysign_0_0, \
                                _float as _F, _isfinite, isnan, isnear0, \
                                _over, _umod_360, _umod_PI2
-from pygeodesy.errors import _ValueError, _xkwds, _xkwds_get,  _ALL_LAZY, _MODS
+from pygeodesy.errors import _ValueError, _xkwds, _xkwds_get1,  _ALL_LAZY, _MODS
 from pygeodesy.internals import _passargs  # , _MODS?
 from pygeodesy.interns import _edge_, _radians_, _semi_circular_, _SPACE_
 # from pygeodesy.lazily import _ALL_LAZY, _ALL_MODS as _MODS  # from .errors
@@ -27,7 +27,7 @@ from pygeodesy.units import Degrees, Degrees_, Feet, Float, Lam, Lam_, \
 from math import acos, asin, atan2, cos, degrees, fabs, radians, sin, tan  # pow
 
 __all__ = _ALL_LAZY.utily
-__version__ = '24.05.14'
+__version__ = '24.05.29'
 
 # read constant name "_M_Unit" as "meter per Unit"
 _M_CHAIN     = _F(  20.1168)     # yard2m(1) * 22
@@ -763,7 +763,7 @@ def sincos2d(deg, **adeg):
             q -= 1
         d = deg - q * _90_0
         if adeg:
-            t = _xkwds_get(adeg, adeg=_0_0)
+            t = _xkwds_get1(adeg, adeg=_0_0)
             d = _MODS.karney._around(d + t)
         t = _sin0cos2(q & 3, radians(d), deg)
     else: