numpy.lib.utils

module documentation

(source)

Undocumented

Function	`byte_bounds`	Returns pointers to the end-points of an array.
Function	`deprecate`	Issues a DeprecationWarning, adds warning to `old_name`'s docstring, rebinds `old_name.__name__` and returns the new function object.
Function	`deprecate_with_doc`	Deprecates a function and includes the deprecation in its docstring.
Function	`get_include`	Return the directory that contains the NumPy *.h header files.
Function	`info`	Get help information for a function, class, or module.
Function	`issubclass_`	Determine if a class is a subclass of a second class.
Function	`issubsctype`	Determine if the first argument is a subclass of the second argument.
Function	`lookfor`	Do a keyword search on docstrings.
Function	`safe_eval`	Protected string evaluation.
Function	`show_runtime`	Print information about various resources in the system including available intrinsic support and BLAS/LAPACK library in use
Function	`source`	Print or write to a file the source code for a NumPy object.
Function	`who`	Print the NumPy arrays in the given dictionary.
Class	`_Deprecate`	Decorator class to deprecate old functions.
Function	`_get_indent`	Determines the leading whitespace that could be removed from all the lines.
Function	`_getmembers`	Undocumented
Function	`_info`	Provide information about ndarray obj.
Function	`_lookfor_generate_cache`	Generate docstring cache for given module.
Function	`_makenamedict`	Undocumented
Function	`_median_nancheck`	Utility function to check median result from data for NaN values at the end and return NaN in that case. Input result can also be a MaskedArray.
Function	`_opt_info`	Returns a string contains the supported CPU features by the current build.
Function	`_split_line`	Undocumented
Variable	`_dictlist`	Undocumented
Variable	`_function_signature_re`	Undocumented
Variable	`_lookfor_caches`	Undocumented
Variable	`_namedict`	Undocumented

def byte_bounds(a): (source) ¶

Returns pointers to the end-points of an array.

Examples

>>> I = np.eye(2, dtype='f'); I.dtype
dtype('float32')
>>> low, high = np.byte_bounds(I)
>>> high - low == I.size*I.itemsize
True
>>> I = np.eye(2); I.dtype
dtype('float64')
>>> low, high = np.byte_bounds(I)
>>> high - low == I.size*I.itemsize
True

Parameters
a:`ndarray`	Input array. It must conform to the Python-side of the array interface.
Returns
`tuple` of 2 integers	(low, high) - The first integer is the first byte of the array, the second integer is just past the last byte of the array. If `a` is not contiguous it will not use every byte between the (`low`, `high`) values.

def deprecate(*args, **kwargs): (source) ¶

Issues a DeprecationWarning, adds warning to old_name's docstring, rebinds old_name.__name__ and returns the new function object.

This function may also be used as a decorator.

Examples

Note that olduint returns a value after printing Deprecation Warning:

>>> olduint = np.deprecate(np.uint)
DeprecationWarning: `uint64` is deprecated! # may vary
>>> olduint(6)
6

Parameters
*args	Undocumented
**kwargs	Undocumented
func:`function`	The function to be deprecated.
old_name:`str`, optional	The name of the function to be deprecated. Default is None, in which case the name of `func` is used.
new_name:`str`, optional	The new name for the function. Default is None, in which case the deprecation message is that `old_name` is deprecated. If given, the deprecation message is that `old_name` is deprecated and `new_name` should be used instead.
message:`str`, optional	Additional explanation of the deprecation. Displayed in the docstring after the warning.
Returns
`function`	old_func - The deprecated function.

def deprecate_with_doc(msg): (source) ¶

Deprecates a function and includes the deprecation in its docstring.

This function is used as a decorator. It returns an object that can be used to issue a DeprecationWarning, by passing the to-be decorated function as argument, this adds warning to the to-be decorated function's docstring and returns the new function object.

See Also

deprecate: Decorate a function such that it issues a DeprecationWarning

Parameters
msg:`str`	Additional explanation of the deprecation. Displayed in the docstring after the warning.
Returns
`object`	obj

def get_include(): (source) ¶

Return the directory that contains the NumPy *.h header files.

Extension modules that need to compile against NumPy should use this function to locate the appropriate include directory.

Notes

When using distutils, for example in setup.py:

import numpy as np
...
Extension('extension_name', ...
        include_dirs=[np.get_include()])
...

@set_module('numpy')
def info(object=None, maxwidth=76, output=None, toplevel='numpy'): (source) ¶

Get help information for a function, class, or module.

See Also

source, lookfor

Notes

When used interactively with an object, np.info(obj) is equivalent to help(obj) on the Python prompt or obj? on the IPython prompt.

Examples

>>> np.info(np.polyval) # doctest: +SKIP
   polyval(p, x)
     Evaluate the polynomial p at x.
     ...

When using a string for object it is possible to get multiple results.

>>> np.info('fft') # doctest: +SKIP
     *** Found in numpy ***
Core FFT routines
...
     *** Found in numpy.fft ***
 fft(a, n=None, axis=-1)
...
     *** Repeat reference found in numpy.fft.fftpack ***
     *** Total of 3 references found. ***

Parameters
object:`object` or `str`, optional	Input object or name to get information about. If `object` is a numpy object, its docstring is given. If it is a string, available modules are searched for matching objects. If None, information about `info` itself is returned.
maxwidth:`int`, optional	Printing width.
output:file like object, optional	File like object that the output is written to, default is `None`, in which case `sys.stdout` will be used. The object has to be opened in 'w' or 'a' mode.
toplevel:`str`, optional	Start search at this level.

@set_module('numpy')
def issubclass_(arg1, arg2): (source) ¶

Determine if a class is a subclass of a second class.

issubclass_ is equivalent to the Python built-in issubclass, except that it returns False instead of raising a TypeError if one of the arguments is not a class.

See Also

issubsctype, issubdtype, issctype

Examples

>>> np.issubclass_(np.int32, int)
False
>>> np.issubclass_(np.int32, float)
False
>>> np.issubclass_(np.float64, float)
True

Parameters
arg1:`class`	Input class. True is returned if `arg1` is a subclass of `arg2`.
arg2:`class` or `tuple` of `classes.`	Input class. If a tuple of classes, True is returned if `arg1` is a subclass of any of the tuple elements.
Returns
`bool`	out - Whether `arg1` is a subclass of `arg2` or not.

@set_module('numpy')
def issubsctype(arg1, arg2): (source) ¶

Determine if the first argument is a subclass of the second argument.

See Also

issctype, issubdtype, obj2sctype

Examples

>>> np.issubsctype('S8', str)
False
>>> np.issubsctype(np.array([1]), int)
True
>>> np.issubsctype(np.array([1]), float)
False

Parameters
arg1:`dtype` or dtype specifier	Data-types.
arg2:`dtype` or dtype specifier	Data-types.
Returns
`bool`	out - The result.

@set_module('numpy')
def lookfor(what, module=None, import_modules=True, regenerate=False, output=None): (source) ¶

Do a keyword search on docstrings.

A list of objects that matched the search is displayed, sorted by relevance. All given keywords need to be found in the docstring for it to be returned as a result, but the order does not matter.

See Also

source, info

Notes

Relevance is determined only roughly, by checking if the keywords occur in the function name, at the start of a docstring, etc.

Examples

>>> np.lookfor('binary representation') # doctest: +SKIP
Search results for 'binary representation'
------------------------------------------
numpy.binary_repr
    Return the binary representation of the input number as a string.
numpy.core.setup_common.long_double_representation
    Given a binary dump as given by GNU od -b, look for long double
numpy.base_repr
    Return a string representation of a number in the given base system.
...

Parameters
what:`str`	String containing words to look for.
module:`str` or `list`, optional	Name of module(s) whose docstrings to go through.
import_modules:`bool`, optional	Whether to import sub-modules in packages. Default is True.
regenerate:`bool`, optional	Whether to re-generate the docstring cache. Default is False.
output:`file-like`, optional	File-like object to write the output to. If omitted, use a pager.

def safe_eval(source): (source) ¶

Protected string evaluation.

Evaluate a string containing a Python literal expression without allowing the execution of arbitrary non-literal code.

Warning

This function is identical to ast.literal_eval and has the same security implications. It may not always be safe to evaluate large input strings.

Examples

>>> np.safe_eval('1')
1
>>> np.safe_eval('[1, 2, 3]')
[1, 2, 3]
>>> np.safe_eval('{"foo": ("bar", 10.0)}')
{'foo': ('bar', 10.0)}

>>> np.safe_eval('import os')
Traceback (most recent call last):
  ...
SyntaxError: invalid syntax

>>> np.safe_eval('open("/home/user/.ssh/id_dsa").read()')
Traceback (most recent call last):
  ...
ValueError: malformed node or string: <_ast.Call object at 0x...>

Parameters
source:`str`	The string to evaluate.
Returns
`object`	obj - The result of evaluating `source`.
Raises
`SyntaxError`	If the code has invalid Python syntax, or if it contains non-literal code.

def show_runtime(): (source) ¶

Print information about various resources in the system including available intrinsic support and BLAS/LAPACK library in use

See Also

show_config: Show libraries in the system on which NumPy was built.

Notes

Information is derived with the help of threadpoolctl library.
SIMD related information is derived from __cpu_features__, __cpu_baseline__ and __cpu_dispatch__

Examples

>>> import numpy as np
>>> np.show_runtime()
[{'simd_extensions': {'baseline': ['SSE', 'SSE2', 'SSE3'],
                      'found': ['SSSE3',
                                'SSE41',
                                'POPCNT',
                                'SSE42',
                                'AVX',
                                'F16C',
                                'FMA3',
                                'AVX2'],
                      'not_found': ['AVX512F',
                                    'AVX512CD',
                                    'AVX512_KNL',
                                    'AVX512_KNM',
                                    'AVX512_SKX',
                                    'AVX512_CLX',
                                    'AVX512_CNL',
                                    'AVX512_ICL']}},
 {'architecture': 'Zen',
  'filepath': '/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so',
  'internal_api': 'openblas',
  'num_threads': 12,
  'prefix': 'libopenblas',
  'threading_layer': 'pthreads',
  'user_api': 'blas',
  'version': '0.3.20'}]

@set_module('numpy')
def source(object, output=sys.stdout): (source) ¶

Print or write to a file the source code for a NumPy object.

The source code is only returned for objects written in Python. Many functions and classes are defined in C and will therefore not return useful information.

See Also

lookfor, info

Examples

>>> np.source(np.interp)                        #doctest: +SKIP
In file: /usr/lib/python2.6/dist-packages/numpy/lib/function_base.py
def interp(x, xp, fp, left=None, right=None):
    """.... (full docstring printed)"""
    if isinstance(x, (float, int, number)):
        return compiled_interp([x], xp, fp, left, right).item()
    else:
        return compiled_interp(x, xp, fp, left, right)

The source code is only returned for objects written in Python.

>>> np.source(np.array)                         #doctest: +SKIP
Not available for this object.

Parameters
object:numpy object	Input object. This can be any object (function, class, module, ...).
output:file object, optional	If `output` not supplied then source code is printed to screen (sys.stdout). File object must be created with either write 'w' or append 'a' modes.

def who(vardict=None): (source) ¶

Print the NumPy arrays in the given dictionary.

If there is no dictionary passed in or vardict is None then returns NumPy arrays in the globals() dictionary (all NumPy arrays in the namespace).

Notes

Prints out the name, shape, bytes and type of all of the ndarrays present in vardict.

Examples

>>> a = np.arange(10)
>>> b = np.ones(20)
>>> np.who()
Name            Shape            Bytes            Type
===========================================================
a               10               80               int64
b               20               160              float64
Upper bound on total bytes  =       240

>>> d = {'x': np.arange(2.0), 'y': np.arange(3.0), 'txt': 'Some str',
... 'idx':5}
>>> np.who(d)
Name            Shape            Bytes            Type
===========================================================
x               2                16               float64
y               3                24               float64
Upper bound on total bytes  =       40

Parameters
vardict:`dict`, optional	A dictionary possibly containing ndarrays. Default is globals().
Returns
`None`	out - Returns 'None'.

def _get_indent(lines): (source) ¶

Determines the leading whitespace that could be removed from all the lines.

def _getmembers(item): (source) ¶

Undocumented

def _info(obj, output=None): (source) ¶

Provide information about ndarray obj.

Notes

Copied over from the numarray module prior to its removal. Adapted somewhat as only numpy is an option now.

Called by info.

Parameters
obj:`ndarray`	Must be ndarray, not checked.
output	Where printed output goes.

def _lookfor_generate_cache(module, import_modules, regenerate): (source) ¶

Generate docstring cache for given module.

Parameters
module:`str`, `None`, `module`	Module for which to generate docstring cache
import_modules:`bool`	Whether to import sub-modules in packages.
regenerate:`bool`	Re-generate the docstring cache
Returns
dict {obj_full_name: (`docstring`, `kind`, `index)`, ...}	cache - Docstring cache for the module, either cached one (regenerate=False) or newly generated.

def _makenamedict(module='numpy'): (source) ¶

Undocumented

def _median_nancheck(data, result, axis): (source) ¶

Utility function to check median result from data for NaN values at the end and return NaN in that case. Input result can also be a MaskedArray.

Parameters
data:`array`	Sorted input data to median function
result:`Array` or `MaskedArray`	Result of median function.
axis:`int`	Axis along which the median was computed.
Returns
`scalar` or `ndarray`	result - Median or NaN in axes which contained NaN in the input. If the input was an array, NaN will be inserted in-place. If a scalar, either the input itself or a scalar NaN.

def _opt_info(): (source) ¶

Returns a string contains the supported CPU features by the current build.

The string format can be explained as follows:

dispatched features that are supported by the running machine end with *.
dispatched features that are "not" supported by the running machine end with ?.
remained features are representing the baseline.

def _split_line(name, arguments, width): (source) ¶

Undocumented

_dictlist = (source) ¶

Undocumented

_function_signature_re = (source) ¶

Undocumented

_lookfor_caches: dict = (source) ¶

Undocumented

_namedict = (source) ¶

Undocumented