Coverage for pygeodesy/units.py : 95%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# -*- coding: utf-8 -*-
C{Str} from basic C{float}, C{int} respectively C{str} to named units as L{Degrees}, L{Feet}, L{Meter}, L{Radians}, etc. '''
_umod_360, _0_0, _0_001, \ _0_5, INT0 # PYCHOK for .mgrs, .namedTuples S_NUL, S_SEP, _toDMS TRFError, UnitError, _xkwds_popitem _distance_, _E_, _easting_, _epoch_, _EW_, \ _feet_, _height_, _lam_, _lat_, \ _LatLon_, _lon_, _meter_, _meter2_, _N_, \ _northing_, _NS_, _NSEW_, _number_, _PERCENT_, \ _phi_, _precision_, _radians_, _radians2_, \ _radius_, _S_, _scalar_, _units_, \ _W_, _zone_, _std_ # PYCHOK used! # from pygeodesy.streprs import Fmt, fstr # from .unitsBase Radius, Str # PYCHOK shared .namedTuples
'''Named C{float} with optional C{low} and C{high} limit. ''' '''New C{Float_} instance.
@arg cls: This class (C{Float_} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float}). @kwarg name: Optional instance name (C{str}). @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}}.
@returns: A C{Float_} instance.
@raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}. ''' txt = Fmt.limit(above=Fmt.g(high, prec=6, ints=isinstance(self, Epoch))) else: raise _Error(cls, arg, name=name, Error=Error, txt=txt)
'''Named C{int} with optional limits C{low} and C{high}. ''' '''New named C{int} instance with limits.
@kwarg cls: This class (C{Int_} or sub-class). @arg arg: The value (any C{type} convertable to C{int}). @kwarg name: Optional instance name (C{str}). @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}}.
@returns: An L{Int_} instance.
@raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}. ''' txt = Fmt.limit(below=low) txt = Fmt.limit(above=high) else: raise _Error(cls, arg, name=name, Error=Error, txt=txt)
'''Named C{bool}, a sub-class of C{int} like Python's C{bool}. ''' # _std_repr = True # set below
'''New C{Bool} instance.
@kwarg cls: This class (C{Bool} or sub-class). @kwarg arg: The value (any C{type} convertable to C{bool}). @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}}.
@returns: A L{Bool}, a C{bool}-like instance.
@raise Error: Invalid B{C{arg}}. ''' name, arg = _xkwds_popitem(name_arg) except (TypeError, ValueError) as x: # XXX not ... as x: raise _Error(cls, arg, name=name, Error=Error, txt=str(x))
# <https://StackOverflow.com/questions/9787890/assign-class-boolean-value-in-python> return self._bool_True_or_False
'''Return a representation of this C{Bool}.
@kwarg std: Use the standard C{repr} or the named representation (C{bool}).
@note: Use C{env} variable C{PYGEODESY_BOOL_STD_REPR=std} prior to C{import pygeodesy} to get the standard C{repr} or set property C{std_repr=False} to always get the named C{toRepr} representation. '''
'''Return this C{Bool} as standard C{str}. '''
'''Named C{str} representing a UTM/UPS band letter, unchecked. ''' '''New L{Band} instance, see L{Str}. '''
'''Named C{float} representing a coordinate in C{degrees}, optionally clipped. '''
'''New C{Degrees} instance, see L{Float}.
@arg cls: This class (C{Degrees} or sub-class). @kwarg arg: The value (any scalar C{type} convertable to C{float} or parsable by L{pygeodesy.parseDMS}). @kwarg name: Optional instance name (C{str}). @kwarg Error: Optional error to raise, overriding the default L{UnitError}. @kwarg suffix: Optional, valid compass direction suffixes (C{NSEW}). @kwarg clip: Optional B{C{arg}} range B{C{-clip..+clip}} (C{degrees} or C{0} or C{None} for unclipped). @kwarg wrap: Optionally adjust the B{C{arg}} value (L{pygeodesy.wrap90}, L{pygeodesy.wrap180} or L{pygeodesy.wrap360}). @kwarg name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}} and B{C{arg}}.
@returns: A C{Degrees} instance.
@raise Error: Invalid B{C{arg}} or B{C{abs(arg)}} outside the B{C{clip}} range and L{pygeodesy.rangerrors} set to C{True}. ''' name=name, Error=Error) except RangeError as x: t, E = str(x), type(x) except (TypeError, ValueError) as x: t, E = str(x), Error raise _Error(cls, arg, name=name, Error=E, txt=t)
'''Return a representation of this C{Degrees}.
@kwarg std: If C{True} return the standard C{repr}, otherwise the named representation (C{bool}).
@see: Methods L{Degrees.toStr}, L{Float.toRepr} and function L{pygeodesy.toDMS} for more documentation. '''
'''Return this C{Degrees} as standard C{str}.
@see: Function L{pygeodesy.toDMS} for keyword argument details. ''' p = 8 if prec is None else prec return fstr(self, prec=p, fmt=fmt, ints=ints, sep=self._sep_) else:
'''Named C{Degrees} representing a coordinate in C{degrees} with optional limits C{low} and C{high}. ''' '''New C{Degrees_} instance, see L{Degrees} and L{Float}..
@arg cls: This class (C{Degrees_} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float} or parsable by L{pygeodesy.parseDMS}). @kwarg name: Optional instance name (C{str}). @kwarg Error: Optional error to raise, overriding the default L{UnitError}. @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}}.
@returns: A C{Degrees} instance.
@raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}. ''' txt = Fmt.limit(below=low) else: raise _Error(cls, arg, name=name, Error=Error, txt=txt)
'''Named C{float} representing a distance in C{degrees squared}. ''' '''See L{Float}. '''
'''Named C{float} representing a coordinate in C{radians}, optionally clipped. ''' '''New C{Radians} instance, see L{Float}.
@arg cls: This class (C{Radians} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float} or parsable by L{pygeodesy.parseRad}). @kwarg name: Optional instance name (C{str}). @kwarg Error: Optional error to raise, overriding the default L{UnitError}. @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}}.
@returns: A C{Radians} instance.
@raise Error: Invalid B{C{arg}} or B{C{abs(arg)}} outside the B{C{clip}} range and L{pygeodesy.rangerrors} set to C{True}. ''' name=name, Error=Error) except RangeError as x: t, E = str(x), type(x) except (TypeError, ValueError) as x: t, E = str(x), Error raise _Error(cls, arg, name=name, Error=E, txt=t)
'''Return a representation of this C{Radians}.
@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. '''
'''Return this C{Degrees} as standard C{str}.
@see: Function L{pygeodesy.fstr} for keyword argument details. '''
'''Named C{float} representing a coordinate in C{radians} with optional limits C{low} and C{high}. ''' '''New C{Radians_} instance.
@arg cls: This class (C{Radians_} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float} or parsable by L{pygeodesy.parseRad}). @kwarg name: Optional instance name (C{str}). @kwarg Error: Optional error to raise, overriding the default L{UnitError}. @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}}.
@returns: A C{Radians_} instance.
@raise Error: Invalid B{C{arg}} or B{C{arg}} below B{C{low}} or above B{C{high}}. ''' txt = Fmt.limit(below=low) txt = Fmt.limit(above=high) else: raise _Error(cls, arg, name=name, Error=Error, txt=txt)
'''Named C{float} representing a distance in C{radians squared}. ''' '''New L{Radians2} instance, see L{Float_}. '''
'''Named C{float} representing a bearing in compass C{degrees} from (true) North. '''
'''New L{Bearing} instance, see L{Degrees}. '''
'''Named C{float} representing a bearing in C{radians} from compass C{degrees} from (true) North. ''' '''New L{Bearing_} instance, see L{Bearing} and L{Radians}. '''
'''Named C{float} representing a distance, conventionally in C{meter}. ''' '''New L{Distance} instance, see L{Float}. '''
'''Named C{float} with optional C{low} and C{high} limits representing a distance, conventionally in C{meter}. ''' '''New L{Distance_} instance, see L{Float}. '''
'''Named C{float} representing an easting, conventionally in C{meter}. ''' '''New named C{Easting} or C{Easting of Point} instance.
@arg cls: This class (C{Easting} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float}). @kwarg name: Optional instance name (C{str}). @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}}.
@returns: An C{Easting} instance.
@raise Error: Invalid B{C{arg}}, above B{C{high}} or negative, falsed B{C{arg}}. ''' raise _Error(cls, arg, name=name, Error=Error) raise _Error(cls, arg, name=name, Error=Error, txt=_negative_falsed_)
'''Named C{epoch} with optional C{low} and C{high} limits representing a fractional calendar year. '''
'''New L{Epoch} instance, see L{Float_}. ''' Float_.__new__(cls, arg=arg, name=name, Error=Error, low=low, high=high)
'''Return a representation of this C{Epoch}.
@kwarg std: Use the standard C{repr} or the named representation (C{bool}).
@see: Method L{Float.toRepr} for more documentation. '''
'''Format this C{Epoch} as C{str}.
@see: Function L{pygeodesy.fstr} for more documentation. '''
'''Named C{float} representing a distance or length in C{feet}. ''' '''New L{Feet} instance, see L{Float}. '''
'''A named I{Fractional Index}, an C{int} or C{float} index into a C{list} or C{tuple} of C{points}, typically. A C{float} I{Fractional Index} C{fi} represents a location on the edge between C{points[int(fi)]} and C{points[(int(fi) + 1) % len(points)]}. '''
'''New I{Fractional Index} in a C{list} or C{tuple} of points.
@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}.
@return: The B{C{fi}} (named L{FIx}).
@note: The returned B{C{fi}} may exceed the B{C{flen}} of the original C{points} in certain open/closed cases.
@see: Method L{fractional} or function L{pygeodesy.fractional}. ''' f = Float_.__new__(cls, i + 1, high=n, **name_Error)
'''Get the given C{len}, the index C{[n]} wrapped to C{[0]} (C{int}). '''
'''Return the point at this I{Fractional Index}.
@arg points: The points (C{LatLon}[], L{Numpy2LatLon}[], L{Tuple2LatLon}[] or C{other}[]). @kwarg wrap: Wrap and unroll longitudes (C{bool}) or C{None} for backward compatible L{LatLon2Tuple} or B{C{LatLon}} with averaged lat- and longitudes. @kwarg LatLon: Optional class to return the I{intermediate}, I{fractional} point (C{LatLon}) or C{None}. @kwarg Vector: Optional class to return the I{intermediate}, I{fractional} point (C{Cartesian}, C{Vector3d}) or C{None}. @kwarg kwds: Optional, additional B{C{LatLon}} I{or} B{C{Vector}} keyword arguments, ignored if both C{B{LatLon}} and C{B{Vector}} are C{None}.
@return: See function L{pygeodesy.fractional}.
@raise IndexError: This fractional index invalid or B{C{points}} not subscriptable or not closed.
@raise TypeError: Invalid B{C{LatLon}}, B{C{Vector}} or B{C{kwds}} argument.
@see: Function L{pygeodesy.fractional}. ''' # fi = 0 if self == self.fin else self LatLon=LatLon, Vector=Vector, **kwds)
# Get 2-tuple (C{fi}, C{j}) raise _AssertionError(i=i, n=n, f=f, r=f - float(i))
'''Named C{float} representing a height, conventionally in C{meter}. ''' '''New L{Height} instance, see L{Float}. '''
'''Named C{float} representing a longitude in C{radians}. ''' '''New L{Lam} instance, see L{Radians}. '''
'''Named C{float} representing a longitude in C{radians} converted from C{degrees}. ''' '''New L{Lam_} instance, see L{Lam} and L{Radians}. '''
'''Named C{float} representing a latitude in C{degrees}. '''
'''New L{Lat} instnace, see L{Degrees}. '''
'''Named C{float} representing a latitude in C{degrees} within limits C{low} and C{high}. '''
'''See L{Degrees_}. '''
'''Named C{float} representing a longitude in C{degrees}. '''
'''New L{Lon} instance, see L{Degrees}. '''
'''Named C{float} representing a longitude in C{degrees} within limits C{low} and C{high}. '''
'''New L{Lon_} instance, see L{Lon} and L{Degrees_}. '''
'''Named C{float} representing a distance or length in C{meter}. ''' '''New L{Meter} instance, see L{Float}. '''
'''Return a representation of this C{Meter}.
@see: Method C{Str.toRepr} and property C{Str.std_repr}.
@note: Use C{env} variable C{PYGEODESY_METER_STD_REPR=std} prior to C{import pygeodesy} to get the standard C{repr} or set property C{std_repr=False} to always get the named C{toRepr} representation. '''
'''Named C{float} representing a distance or length in C{meter}. ''' '''New L{Meter_} instance, see L{Meter} and L{Float_}. '''
'''Named C{float} representing an area in C{meter squared}. ''' '''New L{Meter2} instance, see L{Float_}. '''
'''Named C{float} representing a volume in C{meter cubed}. ''' '''New L{Meter3} instance, see L{Float_}. '''
'''Named C{float} representing a northing, conventionally in C{meter}. ''' '''New C{Northing} or C{Northing of point} instance.
@arg cls: This class (C{Northing} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float}). @kwarg name: Optional instance name (C{str}). @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}}.
@returns: A C{Northing} instance.
@raise Error: Invalid B{C{arg}}, above B{C{high}} or negative, falsed B{C{arg}}. ''' raise _Error(cls, arg, name=name, Error=Error) raise _Error(cls, arg, name=name, Error=Error, txt=_negative_falsed_)
'''Named C{int} representing a non-negative number. ''' '''New L{Number_} instance, see L{Int_}. '''
'''Named C{float} representing a latitude in C{radians}. ''' '''New L{Phi} instance, see L{Radians}. '''
'''Named C{float} representing a latitude in C{radians} converted from C{degrees}. ''' '''New L{Phi_} instance, see L{Phi} and L{Radians}. '''
'''Named C{int} with optional C{low} and C{high} limits representing a precision. ''' '''New L{Precision_} instance, see L{Int_}. '''
'''Named C{float} with optional C{low} and C{high} limits representing a radius, conventionally in C{meter}. ''' '''New L{Radius_} instance, see L{Radius} and L{Float}. '''
'''Named C{float} representing a factor, fraction, scale, etc. ''' '''New L{Scalar} instance, see L{Float}. '''
'''Named C{float} with optional C{low} and C{high} limits representing a factor, fraction, scale, etc. ''' '''New L{Scalar_} instance, see L{Scalar} and L{Float_}. '''
'''Named C{int} representing a UTM/UPS zone number. ''' '''New L{Zone} instance, see L{Int} ''' # usually low=_UTMUPS_ZONE_MIN, high=_UTMUPS_ZONE_MAX
'''(INTERNAL) Create a C{TypeError} for C{Garef}, C{Geohash}, C{Wgrs}. ''' r = tuple(r.__name__ for r in Refs) + (Str.__name__, _LatLon_, 'LatLon*Tuple') return _IsnotError(*r, **name_value_Error)
'''(INTERNAL) Get C{Unit} from C{Unit} or C{name}, ortherwise C{Base}. ''' raise _IsnotError(_NamedUnit.__name__, Base=Base) units if issubclassof(units, Base) else Base)
'''(INTERNAL) Set property C{units} as C{Unit} or C{Str}. ''' raise _IsnotError(_NamedUnit.__name__, Base=Base) return units else: raise _IsnotError(Base.__name__, Str.__name__, str.__name__, units=units)
'''(INTERNAL) Use standard C{repr} or named C{toRepr}. ''' C._std_repr = False
# **) MIT License # # Copyright (C) 2016-2022 -- mrJean1 at Gmail -- All Rights Reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included # in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR # OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. |