Coverage for pygeodesy/basics.py : 98%

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 -*-
'''
# all public contants, classes and functions
except ImportError: # PYCHOK no cover try: # _Ints imported by .utily _Ints = int, long #: (INTERNAL) Int objects (C{tuple}) except NameError: # Python 3+ _Ints = int, #: (INTERNAL) Int objects (C{tuple})
except ImportError: # PYCHOK no cover try: _Scalars = int, long, float #: (INTERNAL) Scalar objects (C{tuple}) except NameError: _Scalars = int, float #: (INTERNAL) Scalar objects (C{tuple})
# and isinstance(range(1), _Sequence): else: raise ImportError # AssertionError except ImportError: # PYCHOK no cover _Sequence = tuple # immutable for .points._Basequence _Seqs = list, _Sequence # , range for function len2 below
except AttributeError: # PYCHOK no cover EPS = 2.220446049250313e-16 #: Epsilon (C{float}) 2**-52? MANTIS = 53 #: Mantissa bits ≈53 (C{int}) MAX = pow(2.0, 1023) * (2 - EPS) #: Float max (C{float}) ≈10**308, 2**1024? MIN = pow(2.0, -1021) # Float min (C{float}) ≈10**-308, 2**-1021? # _1EPS = 1.0 + EPS #: M{1 + EPS} ≈1.0000000000000002 (C{float})
'''Error raised for mis-matching C{len} values. ''' '''New L{LenError}.
@arg where: Object with C{.__name__} attribute (C{class}, C{method}, or C{function}). @kwarg lens: Two or more C{name=len(name)} pairs (C{keyword arguments}). '''
'''Error raised for lat- or longitudinal deltas exceeding the B{C{limit}} in functions L{equirectangular} and L{equirectangular_} and C{nearestOn*} and C{simplify*} functions or methods. '''
'''Error raised for lat- or longitude values outside the B{C{clip}}, B{C{clipLat}}, B{C{clipLon}} or B{C{limit}} range in function L{clipDegrees}, L{clipRadians}, L{parse3llh}, L{parseDMS}, L{parseDMS2} or L{parseRad}.
@see: Function L{rangerrors}. '''
'''(INTERNAL) Prepend an article to a noun based on the pronounciation of the first letter. '''
'''(INTERNAL) Set applicable C{bool} attributes. ''' t = n, v, inst.__class__.__name__ # XXX .classname raise Error('not applicable: %s=%r for %s' % t)
'''Clip a string to the given length limit.
@arg bstr: String (C{bytes} or C{str}). @kwarg limit: Length limit (C{int}). @kwarg white: Optionally, replace all whitespace (C{str}).
@return: The clipped or unclipped B{C{bstr}}. '''
'''Split a string in 2 halfs.
@arg str2: String to split (C{str}).
@return: 2-Tuple (_1st, _2nd) half (C{str}).
@raise ValueError: Zero or odd C{len}(B{C{str2}}). ''' raise InvalidError(str2=str2)
'''Create a C{ValueError} for invalid C{name=value} pairs.
@kwarg name_value_s: One or more B{C{name=value}} pairs.
@return: A C{ValueError} or an B{C{Error}} instance. ''' else: else: t = 'missing %r' % ('name=value',)
'''Check for C{Inf} and C{NaN} values.
@arg obj: Value (C{scalar}).
@return: C{False} if B{C{obj}} is C{INF} or C{NAN}, C{True} otherwise.
@raise TypeError: Non-scalar B{C{obj}}. ''' raise IsnotError(isscalar.__name__, obj=obj)
'''Check for C{int} type or an integer C{float} value.
@arg obj: The object (any C{type}). @kwarg both: Optionally, check C{float} type and value (C{bool}).
@return: C{True} if B{C{obj}} is C{int} or an integer C{float}, C{False} otherwise. ''' except AttributeError: # PYCHOK no cover return False # XXX float(int(obj)) == obj?
'''Check for L{NEG0}, negative 0.0.
@arg obj: Value (C{scalar}).
@return: C{True} if B{C{obj}} is C{NEG0} or -0.0, C{False} otherwise. ''' # and str(obj).rstrip('0') == '-0.'
'''Create a C{TypeError} for an invalid C{name=value} type.
@arg noun_s: One or more expected class or type names, usually nouns (C{str}). @kwarg name_value_Error: One B{C{name=value}} pair and optionally an B{C{Error=...}} keyword argument to override the default B{C{Error=TypeError}}.
@return: A C{TypeError} or an B{C{Error}} instance. ''' else: n, v = repr('name=value'), 'missing'
'''Check for scalar types.
@arg obj: The object (any C{type}).
@return: C{True} if B{C{obj}} is C{scalar}, C{False} otherwise. '''
'''Check for sequence types.
@arg obj: The object (any C{type}). @arg excluded: Optional exclusions (C{type}).
@note: Excluding C{tuple} implies excluding C{namedtuple}.
@return: C{True} if B{C{obj}} is a sequence, C{False} otherwise. ''' isinstance(obj, _Seqs)
'''Check for string types.
@arg obj: The object (any C{type}).
@return: C{True} if B{C{obj}} is C{str}, C{False} otherwise. '''
'''Check whether a class is a sub-class of a super class.
@arg Sub: The sub-class (C{class}). @arg Super: The super class (C{class}).
@return: C{True} if B{C{Sub}} is a sub-class of B{C{Super}}, C{False} otherwise (C{bool}). '''
'''Make built-in function L{len} work for generators, iterators, etc. since those can only be started exactly once.
@arg items: Generator, iterator, list, range, tuple, etc.
@return: 2-Tuple C{(n, items)} of the number of items (C{int}) and the items (C{list} or C{tuple}). '''
'''Get/set the raising of L{LimitError}s.
@kwarg raiser: Choose C{True} to raise or C{False} to ignore L{LimitError} exceptions. Use C{None} to leave the setting unchanged.
@return: Previous setting (C{bool}). ''' global _limiterrors
'''Apply each argument to a single-argument function and return a C{tuple} of results.
@arg func: Function to apply (C{callable}). @arg xs: Arguments to apply (C{any positional}).
@return: Function results (C{tuple}). '''
'''Apply arguments to a function and return a C{tuple} of results.
Unlike Python 2's built-in L{map}, Python 3+ L{map} returns a L{map} object, an iterator-like object which generates the results only once. Converting the L{map} object to a tuple maintains Python 2 behavior.
@arg func: Function to apply (C{callable}). @arg xs: Arguments to apply (C{list, tuple, ...}).
@return: Function results (C{tuple}). '''
'''(INTERNAL) Join C{words} with C{', '} and C{' or '}. '''
'''Decorator for a property with documentation.
@arg doc: The property documentation (C{str}).
@example:
>>> @property_doc_("documentation text.") >>> def name(self): >>> ... >>> >>> @name.setter >>> def name(self, value): >>> ... ''' # See Luciano Ramalho, "Fluent Python", page 212ff, O'Reilly, 2016, # "Parameterized Decorators", especially Example 7-23. Also, see # <https://Python-3-Patterns-Idioms-Test.ReadTheDocs.io/en/latest/PythonDecorators.html>
'''(INTERNAL) Return C{method} as documented C{property.getter}. '''
# No __doc__ on purpose
'''New immutable, read-only L{property_RO}.
@arg method: The callable to be decorated as C{property.getter}.
@note: Like standard Python C{property} without a C{property.setter}, but with a more descriptive error message when set. '''
# U{Descriptor HowTo Guide<https://docs.Python.org/3/howto/descriptor.html>} '''Throws an C{AttributeError}, always. ''' raise AttributeError('%s property: %r.%s = %r' % t)
# def property_RO(method): # OBSOLETE # '''An immutable property (C{Read Only}). # # @arg method: The callable to be decorated as C{property.getter}. # # @note: Like standard Python C{property} without a C{property.setter}, # but with a more descriptive error message when set. # ''' # def Read_Only(inst, value): # '''Throws an C{AttributeError}, always. # ''' # t = Read_Only.__name__, inst, method.__name__, value # raise AttributeError('%s property: %r.%s = %r' % t) # # return property(method, Read_Only, None, method.__doc__ or 'N/A')
'''Get/set the raising of L{RangeError}s.
@kwarg raiser: Choose C{True} to raise or C{False} to ignore L{RangeError} exceptions. Use C{None} to leave the setting unchanged.
@return: Previous setting (C{bool}). ''' global _rangerrors
'''(INTERNAL) Copy attribute values from B{C{other}} to B{C{insto}}.
@arg insto: Object to copy attribute values to (any C{type}). @arg other: Object to copy attribute values from (any C{type}). @arg attrs: One or more attribute names (C{str}s).
@return: Object B{C{insto}}, updated.
@raise AttributeError: An B{C{attrs}} doesn't exist or is not settable. ''' raise AttributeError('.%s invalid: %r' % (a, o))
'''(INTERNAL) Copy an object, shallow or deep.
@arg inst: The object to copy (any C{type}). @kwarg deep: If C{True} make a deep, otherwise a shallow copy (C{bool}).
@return: The copy of B{C{inst}}. '''
'''(INTERNAL) Check C{Types} of all C{name=value} pairs.
@arg Types: One or more classes or types (C{class}). @kwarg name_value_s: One or more B{C{name=value}} pairs with the C{value} to be checked.
@raise TypeError: At least one of the B{C{name_value_s}} is not any of the B{C{Types}}. ''' raise TypeError('%s is not %s: %r' % (n, t, v))
'''(INTERNAL) Override C{dflts} with C{kwds}. '''
'''(INTERNAL) Check super C{Class} of all C{name=value} pairs.
@arg Class: A class or type (C{class}). @kwarg name_value_s: One or more B{C{name=value}} pairs with the C{value} to be checked.
@raise TypeError: At least one of the B{C{name_value_s}} is not a sub-class of B{C{Class}}. ''' t = _an(Class.__name__) raise TypeError('%s is not %s: %r' % (n, t, v))
# **) MIT License # # Copyright (C) 2016-2020 -- 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. |