numpy.lib.utils

module documentation

Undocumented

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 ​_set​_function​_name Undocumented
Function ​_split​_line 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 source Print or write to a file the source code for a NumPy object.
Function who Print the NumPy arrays in the given dictionary.
Variable ​_dictlist Undocumented
Variable ​_function​_signature​_re Undocumented
Variable ​_lookfor​_caches Undocumented
Variable ​_namedict Undocumented
def _get_indent(lines):
Determines the leading whitespace that could be removed from all the lines.
def _getmembers(item):

Undocumented

def _info(obj, output=sys.stdout):

Provide information about ndarray obj.

Parameters

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

Notes

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

Called by info.

def _lookfor_generate_cache(module, import_modules, regenerate):

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

cache : dict {obj_full_name: (docstring, kind, index), ...}
Docstring cache for the module, either cached one (regenerate=False) or newly generated.
def _makenamedict(module='numpy'):

Undocumented

def _median_nancheck(data, result, axis):

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

result : scalar or ndarray
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():

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 _set_function_name(func, name):

Undocumented

def _split_line(name, arguments, width):

Undocumented

def byte_bounds(a):

Returns pointers to the end-points of an array.

Parameters

a : ndarray
Input array. It must conform to the Python-side of the array interface.

Returns

(low, high) : tuple of 2 integers
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.

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
def deprecate(*args, **kwargs):

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.

Parameters

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

old_func : function
The deprecated function.

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
def deprecate_with_doc(msg):

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

obj : object

def get_include():

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=sys.stdout, toplevel='numpy'):

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

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 stdout. The object has to be opened in 'w' or 'a' mode.
toplevel : str, optional
Start search at this level.

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. ***
@set_module('numpy')
def issubclass_(arg1, arg2):

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.

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

out : bool
Whether arg1 is a subclass of arg2 or not.

See Also

issubsctype, issubdtype, issctype

Examples

>>> np.issubclass_(np.int32, int)
False
>>> np.issubclass_(np.int32, float)
False
>>> np.issubclass_(np.float64, float)
True
@set_module('numpy')
def issubsctype(arg1, arg2):

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

Parameters

arg1, arg2 : dtype or dtype specifier
Data-types.

Returns

out : bool
The result.

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
@set_module('numpy')
def lookfor(what, module=None, import_modules=True, regenerate=False, output=None):

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.

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.

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.
...
def safe_eval(source):

Protected string evaluation.

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

Parameters

source : str
The string to evaluate.

Returns

obj : object
The result of evaluating source.

Raises

SyntaxError
If the code has invalid Python syntax, or if it contains non-literal code.

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...>
@set_module('numpy')
def source(object, output=sys.stdout):

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.

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.

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.
def who(vardict=None):

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).

Parameters

vardict : dict, optional
A dictionary possibly containing ndarrays. Default is globals().

Returns

out : None
Returns 'None'.

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
_dictlist =

Undocumented

_function_signature_re =

Undocumented

_lookfor_caches: dict =

Undocumented

_namedict =

Undocumented