Package pygeodesy :: Module basics |
[frames] | no frames]

# Module basics

Basic constants, definitions and functions.

Version: 20.03.23

Classes
| LenError Error raised for mis-matching `len` values.
| LimitError Error raised for lat- or longitudinal deltas exceeding the `limit` in functions equirectangular and equirectangular_ and `nearestOn*` and `simplify*` functions or methods.
| property_RO

Functions
bool |
isinf(x) Check if float x is infinite (positive or negative). |
bool |
isnan(x) Check if float x is not a number (NaN). |
clips(bstr, limit=50, white=`'````'`) Clip a string to the given length limit. |
halfs2(str2) Split a string in 2 halfs. |
isfinite(obj) Check for `Inf` and `NaN` values. |
isint(obj, both=False) Check for integer type or an integer `float`. |
isneg0(obj) Check for NEG0, negative 0.0. |
isscalar(obj) Check for scalar types. |
issequence(obj, *excluded) Check for sequence types. |
isstr(obj) Check for string types. |
issubclassof(sub, sup) Check whether a class is a subclass of a super class. |
len2(items) Make built-in function `len` work for generators, iterators, etc. |
limiterrors(raiser=None) Get/set the raising of limit errors. |
map1(func, *xs) Apply each argument to a single-argument function and return a `tuple` of results. |
map2(func, *xs) Apply arguments to a function and return a `tuple` of results. |
property_doc_(doc) Decorator for a property with documentation. |
scalar(value, low=2.22044604925e-16, high=1.0, name=`'``scalar``'`, Error=<type 'exceptions.ValueError'>) Validate a scalar. |
splice(iterable, n=2, fill=object()) Split an iterable into `n` slices. |

Variables
| __all__ = `_ALL_LAZY.basics`
| EPS = `2.22044604925e-16` Epsilon (`float`) 2**-52?
| MANTIS = `53` Mantissa bits ≈53 (`int`)
| MAX = `1.79769313486e+308` Float max (`float`) ≈10**308, 2**1024?
| MIN = `2.22507385851e-308` System's float min (`float`)
| EPS_2 = `1.11022302463e-16` EPS / 2 ≈1.110223024625e-16 (`float`)
| EPS1 = `1.0` 1 - EPS ≈0.9999999999999998 (`float`)
| EPS1_2 = `1.0` 1 - EPS_2 ≈0.9999999999999999 (`float`)
| INF = `inf` Infinity (`float`), see function `isinf`, `isfinite`
| NAN = `nan` Not-A-Number (`float`), see function `isnan`
| NEG0 = `-0.0` Negative 0.0 (`float`), see function `isneg0`
| OK = ``'``OK``'``
| R_M = `6371008.77141` Mean, spherical earth radius (`meter`).

Function Details

### clips(bstr, limit=50, white=`'````'`) |
Clip a string to the given length limit. Parameters: `bstr` - String (`bytes` or `str`). `limit` - Length limit (`int`). `white` - Whitespace replacement (`str`). Returns: Un-/clipped `bstr`.

### halfs2(str2) |
Split a string in 2 halfs. Parameters: `str2` - String to split (`str`). Returns: 2-Tuple (1st, 2nd) half (`str`). Raises: `ValueError` - Zero or odd `len`(str2).

### isfinite(obj) |
Check for `Inf` and `NaN` values. Parameters: `obj` - Value (`scalar`). Returns: `False` if `obj` is `INF` or `NAN`, `True` otherwise. Raises: `TypeError` - Non-scalar `obj`.

### isint(obj, both=False) |
Check for integer type or an integer `float`. Parameters: `obj` - The object (any `type`). `both` - Optionally, check both type and value (`bool`). Returns: `True` if `obj` is `int`, `False` otherwise.

### isneg0(obj) |
Check for NEG0, negative 0.0. Parameters: `obj` - Value (`scalar`). Returns: `True` if `obj` is `NEG0` or -0.0, `False` otherwise.

### isscalar(obj) |
Check for scalar types. Parameters: `obj` - The object (any `type`). Returns: `True` if `obj` is `scalar`, `False` otherwise.

### issequence(obj, *excluded) |
Check for sequence types. Parameters: `obj` - The object (any `type`). `excluded` - Optional, exclusions (`type`). Returns: `True` if `obj` is a sequence, `False` otherwise. Note: Excluding `tuple` implies excluding `namedtuple`.

### isstr(obj) |
Check for string types. Parameters: `obj` - The object (any `type`). Returns: `True` if `obj` is `str`, `False` otherwise.

### issubclassof(sub, sup) |
Check whether a class is a subclass of a super class. Parameters: `sub` - The subclass (`class`). `sup` - The super class (`class`). Returns: `True` if `sub` is a subclass of `sup`.

### len2(items) |
Make built-in function `len` work for generators, iterators, etc. since those can only be started exactly once. Parameters: `items` - Generator, iterator, list, range, tuple, etc. Returns: 2-Tuple `(n, items)` of the number of items (`int`) and the items (`list` or `tuple`).

### limiterrors(raiser=None) |
Get/set the raising of limit errors. Parameters: `raiser` - Choose `True` to throw or `False` to ignore LimitError exceptions. Use `None` to leave the setting unchanged. Returns: Previous setting (`bool`).

### map1(func, *xs) |
Apply each argument to a single-argument function and return a `tuple` of results. Parameters: `func` - Function to apply (`callable`). `xs` - Arguments to apply (`any positional`). Returns: Function results (`tuple`).

### map2(func, *xs) |
Apply arguments to a function and return a `tuple` of results. Unlike Python 2's built-in `map`, Python 3+ `map` returns a `map` object, an iterator-like object which generates the results only once. Converting the `map` object to a tuple maintains Python 2 behavior. Parameters: `func` - Function to apply (`callable`). `xs` - Arguments to apply (`list, tuple, ...`). Returns: Function results (`tuple`).

### property_doc_(doc) |
Decorator for a property with documentation. Parameters: `doc` - The property documentation (`str`). Example:
    >>> @property_doc_("documentation text.")
    >>> def name(self):
    >>>     ...
    >>>
    >>> @name.setter
    >>> def name(self, value):
    >>>     ...

### scalar(value, low=2.22044604925e-16, high=1.0, name=`'``scalar``'`, Error=<type 'exceptions.ValueError'>) |
Validate a scalar. Parameters: `value` - The value (`scalar`). `low` - Optional lower bound (`scalar`). `high` - Optional upper bound (`scalar`). `name` - Optional name of value (`str`). `Error` - Exception to raise (`ValueError`). Returns: New value (`type` of `low`). Raises: `TypeError` - Non-scalar `value`. `Error` - Out-of-bounds `value`.

### splice(iterable, n=2, fill=object()) |
Split an iterable into `n` slices. Parameters: `iterable` - Items to be spliced (`list`, `tuple`, ...). `n` - Number of slices to generate (`int`). `fill` - Fill value for missing items. Returns: Generator of `n` slices iterable[i::n] for i=0..n. Raises: `ValueError` - Non-`int` or non-positive `n`. Note: Each generated slice is a `tuple` or a `list`, the latter only if the `iterable` is a `list`. Example:
    >>> from pygeodesy import splice
    >>> a, b = splice(range(10))
    >>> a, b
    ((0, 2, 4, 6, 8), (1, 3, 5, 7, 9))
    >>> a, b, c = splice(range(10), n=3)
    >>> a, b, c
    ((0, 3, 6, 9), (1, 4, 7], [2, 5, 8))
    >>> a, b, c = splice(range(10), n=3, fill=-1)
    >>> a, b, c
    ((0, 3, 6, 9), (1, 4, 7, -1), (2, 5, 8, -1))
    >>> list(splice(range(12), n=5))
    [(0, 5, 10), (1, 6, 11), (2, 7), (3, 8), (4, 9)]
    >>> splice(range(9), n=1)
    <generator object splice at 0x0...>