Coverage for pygeodesy/units.py : 94%

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 -*-
Sub-classes C{Float}, C{Int} and C{Str} from basic C{float}, C{int} respectively C{str} to named units as L{Degrees}, L{Feet}, L{Meter}, L{Radians}, etc. '''
S_NUL, S_SEP, _toDMS UnitError, _xkwds_popitem _bearing_, _degrees_, _degrees2_, \ _distance_, _E_, _easting_, _epoch_, \ _EW_, _feet_, _height_, _invalid_, _N_, \ _lam_, _lat_, _LatLon_, _lon_, _meter_, \ _meter2_, _northing_, _NS_, _NSEW_, \ _number_, _PERCENT_, _phi_, _precision_, \ _radians_, _radians2_, _radius_, _S_, \ _scalar_, _SPACE_, _UNDER_, _units_, \ _W_, _zone_, _0_0, _0_001
'''(INTERNAL) Base class for C{units}. '''
'''(INTERNAL) Representation "<name> (<value>)" or "<classname>(<value>)". '''
'''Get the representation (C{bool}, C{True} means standard). '''
'''Set the representation (C{True} or C{"std"} for standard). ''' self._std_repr = std in (True, _std_)
'''Get the units name (C{str}). '''
'''Set the units name for this instance (C{str} or C{None} for default). '''
'''Named C{float}. ''' # _std_repr = True # set below
'''New named C{float} instance.
@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 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}}. '''
raise _Error(cls, arg, name=name, Error=Error, txt=str(x))
'''Return a representation of this C{Float}.
@see: Method C{Float.toRepr} and property C{Float.std_repr}.
@note: Use C{env} variable C{PYGEODESY_FLOAT_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{Float} as standard C{str}. ''' # XXX must use super(Float, self)... since super()... # only works for Python 3+ and float.__str__(self) # invokes .__repr__(self); calling self.toRepr(std=True) # super(Float, self).__repr__() mimicks this behavior
'''Return a representation of this C{Float}.
@kwarg std: Use the standard C{repr} or the named representation (C{bool}).
@see: Function L{fstr} for more documentation. ''' # XXX must use super(Float, self)... since # super()... only works for Python 3+ self._toRepr(fstr(self, prec=prec, fmt=fmt, ints=ints))
'''Format this C{Float} as C{str}.
@see: Function L{fstr} for more documentation. '''
'''Named C{float} with optional C{low} and C{high} limit. ''' '''New named C{float} instance with limits.
@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}. ''' # _std_repr = True # set below
'''New named C{int} instance.
@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 name_arg: Optional C{name=arg} keyword argument, inlieu of B{C{name}} and B{C{arg}}.
@returns: An C{Int} instance.
@raise Error: Invalid B{C{arg}}. '''
raise _Error(cls, arg, name=name, Error=Error, txt=str(x))
'''Return a representation of this named C{int}.
@see: Method C{Int.toRepr} and property C{Int.std_repr}.
@note: Use C{env} variable C{PYGEODESY_INT_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{Int} as standard C{str}. '''
'''Return the representation of thisb is True C{Int}.
@kwarg std: Use the standard C{repr} or the named representation (C{bool}). '''
'''Return this C{Int} as standard C{str}. ''' # XXX must use '%d' % (self,) since # int.__str__(self) fails with 3.8+
'''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{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: 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 named 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 the 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}. ''' # _std_repr = True # set below
'''New named C{str} instance.
@kwarg cls: This class (C{Str} or sub-class). @kwarg arg: The value (any C{type} convertable to C{str}). @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}}.
@returns: A L{Str} 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))
'''Return a representation of this C{Str}.
@see: Method C{Str.toRepr} and property C{Str.std_repr}.
@note: Use C{env} variable C{PYGEODESY_STR_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{Str} as standard C{str}. '''
'''Return the named representation of this C{Str}.
@kwarg std: Use the standard C{repr} or the named representation (C{bool}). ''' # must use super(Str, self).. since # super()... only works for Python 3+ and # str.__repr__(self) fails with Python 3.8+
'''Return this C{Str} as standard C{str}. ''' # must use super(Str, self)... since # super()... only works for Python 3+ and # str.__str__(self) fails with Python 3.8+
'''Named C{str} representing a UTM/UPS band letter, unchecked. ''' '''See L{Str}. '''
'''Named C{float} representing a coordinate in C{degrees}, optionally clipped. '''
'''New named C{Degrees} instance.
@arg cls: This class (C{Degrees} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float} or parsable by L{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 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{rangerrors} set to C{True}. ''' name=name, Error=Error) t, E = str(x), type(x) raise _Error(cls, arg, name=name, Error=E, txt=t)
self._toRepr(self.toStr(prec=prec, fmt=fmt, ints=ints))
p = 8 if prec is None else prec return fstr(self, prec=p, fmt=fmt, ints=ints, sep=self._sep_) else: self._suf_[0 if self > 0 else (1 if self < 0 else 2)])
'''Named C{Degrees} representing a coordinate in C{degrees} with optional limits C{low} and C{high}. ''' '''New named C{Degrees} instance.
@arg cls: This class (C{Degrees_} or sub-class). @kwarg arg: The value (any C{type} convertable to C{float} or parsable by L{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{abs(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 named 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{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)}} below B{C{low}} or above B{C{high}}. ''' name=name, Error=Error) t, E = str(x), type(x) raise _Error(cls, arg, name=name, Error=E, txt=t)
'''Named C{float} representing a coordinate in C{radians} with optional limits C{low} and C{high}. ''' '''New named 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{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{abs(deg)}} outside the B{C{clip}} range and L{rangerrors} set to C{True}. ''' 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}. ''' '''See L{Float_}. '''
'''Named C{float} representing a bearing in compass C{degrees} from (true) North. '''
'''See L{Degrees}. '''
'''Named C{float} representing a bearing in C{radians} from compass C{degrees} from (true) North. ''' '''See L{Bearing} and L{Radians}. '''
'''Named C{float} representing a distance, conventionally in C{meter}. ''' '''See L{Distance}. '''
'''Named C{float} with optional C{low} and C{high} limits representing a distance, conventionally in C{meter}. ''' '''See L{Distance_}. '''
'''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 osgr: Check B{C{arg}} as an OSGR easting (C{bool}). @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}} 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. '''
'''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: Function L{fstr} for more documentation. '''
'''Format this C{Epoch} as C{str}.
@see: Function L{fstr} for more documentation. '''
'''Named C{float} representing a distance or length in C{feet}. ''' '''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{name=<name>} and/or C{Error=<Exception>}.
@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 LatLon_LatLon_kwds: Optional class to return the I{intermediate}, I{fractional} point (C{LatLon}) or C{None} and optional B{C{LatLon}} keyword arguments thereof.
@return: See function L{pygeodesy.fractional}.
@raise IndexError: Fractional index invalid for B{C{points}} or B{C{points}} not subscriptable or not closed. ''' # fi = 0 if self == self.fin else self
'''Named C{float} representing a height, conventionally in C{meter}. ''' '''See L{Float}. '''
'''Named C{float} representing a longitude in C{radians}. ''' '''See L{Radians}. '''
'''Named C{float} representing a longitude in C{radians} converted from C{degrees}. ''' '''See L{Degrees} and L{Radians}. '''
'''Named C{float} representing a latitude in C{degrees}. '''
'''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}. '''
'''See L{Degrees}. '''
'''Named C{float} representing a longitude in C{degrees} within limits C{low} and C{high}. '''
'''See L{Degrees_}. '''
'''Named C{float} representing a distance or length in C{meter}. ''' '''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}. ''' '''See L{Float_}. '''
'''Named C{float} representing an area in C{meter squared}. ''' '''See L{Float_}. '''
'''Named C{float} representing a volume in C{meter cubed}. ''' '''See L{Float_}. '''
'''Named C{float} representing a northing, conventionally in C{meter}. ''' '''New named 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 osgr: Check B{C{arg}} as an OSGR northing (C{bool}). @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}} 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. ''' '''See L{Int_}. '''
'''Named C{float} representing a latitude in C{radians}. ''' '''See L{Radians}. '''
'''Named C{float} representing a latitude in C{radians} converted from C{degrees}. ''' '''See L{Degrees} and L{Radians}. '''
'''Named C{int} with optional C{low} and C{high} limits representing a precision. ''' '''See L{Int_}. '''
'''Named C{float} representing a radius, conventionally in C{meter}. ''' '''See L{Float}. '''
'''Named C{float} with optional C{low} and C{high} limits representing a radius, conventionally in C{meter}. ''' '''See L{Float}. '''
'''Named C{float} representing a factor, fraction, scale, etc. ''' '''See L{Float}. '''
'''Named C{float} with optional C{low} and C{high} limits representing a factor, fraction, scale, etc. ''' '''See L{Float_}. '''
'''Named C{int} representing a UTM/UPS zone number. ''' '''See L{Int} ''' # usually low=_UTMUPS_ZONE_MIN, high=_UTMUPS_ZONE_MAX
'''(INTERNAL) Return an error with explanation.
@arg clas: The C{units} class or sub-class. @arg arg: The original C{unit} value. @kwarg name: The instance name (C{str}). @kwarg Error: Optional error, overriding the default L{UnitError}. @kwarg txt: Optional explanation of the error (C{str}).
@returns: An B{C{Error}} instance. '''
'''(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-2021 -- 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. |