Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/numpy/lib/utils.py : 19%

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
1import os
2import sys
3import textwrap
4import types
5import re
6import warnings
8from numpy.core.numerictypes import issubclass_, issubsctype, issubdtype
9from numpy.core.overrides import set_module
10from numpy.core import ndarray, ufunc, asarray
11import numpy as np
13# getargspec and formatargspec were removed in Python 3.6
14from numpy.compat import getargspec, formatargspec
16__all__ = [
17 'issubclass_', 'issubsctype', 'issubdtype', 'deprecate',
18 'deprecate_with_doc', 'get_include', 'info', 'source', 'who',
19 'lookfor', 'byte_bounds', 'safe_eval'
20 ]
22def get_include():
23 """
24 Return the directory that contains the NumPy \\*.h header files.
26 Extension modules that need to compile against NumPy should use this
27 function to locate the appropriate include directory.
29 Notes
30 -----
31 When using ``distutils``, for example in ``setup.py``.
32 ::
34 import numpy as np
35 ...
36 Extension('extension_name', ...
37 include_dirs=[np.get_include()])
38 ...
40 """
41 import numpy
42 if numpy.show_config is None:
43 # running from numpy source directory
44 d = os.path.join(os.path.dirname(numpy.__file__), 'core', 'include')
45 else:
46 # using installed numpy core headers
47 import numpy.core as core
48 d = os.path.join(os.path.dirname(core.__file__), 'include')
49 return d
52def _set_function_name(func, name):
53 func.__name__ = name
54 return func
57class _Deprecate:
58 """
59 Decorator class to deprecate old functions.
61 Refer to `deprecate` for details.
63 See Also
64 --------
65 deprecate
67 """
69 def __init__(self, old_name=None, new_name=None, message=None):
70 self.old_name = old_name
71 self.new_name = new_name
72 self.message = message
74 def __call__(self, func, *args, **kwargs):
75 """
76 Decorator call. Refer to ``decorate``.
78 """
79 old_name = self.old_name
80 new_name = self.new_name
81 message = self.message
83 if old_name is None:
84 try:
85 old_name = func.__name__
86 except AttributeError:
87 old_name = func.__name__
88 if new_name is None:
89 depdoc = "`%s` is deprecated!" % old_name
90 else:
91 depdoc = "`%s` is deprecated, use `%s` instead!" % \
92 (old_name, new_name)
94 if message is not None:
95 depdoc += "\n" + message
97 def newfunc(*args,**kwds):
98 """`arrayrange` is deprecated, use `arange` instead!"""
99 warnings.warn(depdoc, DeprecationWarning, stacklevel=2)
100 return func(*args, **kwds)
102 newfunc = _set_function_name(newfunc, old_name)
103 doc = func.__doc__
104 if doc is None:
105 doc = depdoc
106 else:
107 lines = doc.expandtabs().split('\n')
108 indent = _get_indent(lines[1:])
109 if lines[0].lstrip():
110 # Indent the original first line to let inspect.cleandoc()
111 # dedent the docstring despite the deprecation notice.
112 doc = indent * ' ' + doc
113 else:
114 # Remove the same leading blank lines as cleandoc() would.
115 skip = len(lines[0]) + 1
116 for line in lines[1:]:
117 if len(line) > indent:
118 break
119 skip += len(line) + 1
120 doc = doc[skip:]
121 depdoc = textwrap.indent(depdoc, ' ' * indent)
122 doc = '\n\n'.join([depdoc, doc])
123 newfunc.__doc__ = doc
124 try:
125 d = func.__dict__
126 except AttributeError:
127 pass
128 else:
129 newfunc.__dict__.update(d)
130 return newfunc
133def _get_indent(lines):
134 """
135 Determines the leading whitespace that could be removed from all the lines.
136 """
137 indent = sys.maxsize
138 for line in lines:
139 content = len(line.lstrip())
140 if content:
141 indent = min(indent, len(line) - content)
142 if indent == sys.maxsize:
143 indent = 0
144 return indent
147def deprecate(*args, **kwargs):
148 """
149 Issues a DeprecationWarning, adds warning to `old_name`'s
150 docstring, rebinds ``old_name.__name__`` and returns the new
151 function object.
153 This function may also be used as a decorator.
155 Parameters
156 ----------
157 func : function
158 The function to be deprecated.
159 old_name : str, optional
160 The name of the function to be deprecated. Default is None, in
161 which case the name of `func` is used.
162 new_name : str, optional
163 The new name for the function. Default is None, in which case the
164 deprecation message is that `old_name` is deprecated. If given, the
165 deprecation message is that `old_name` is deprecated and `new_name`
166 should be used instead.
167 message : str, optional
168 Additional explanation of the deprecation. Displayed in the
169 docstring after the warning.
171 Returns
172 -------
173 old_func : function
174 The deprecated function.
176 Examples
177 --------
178 Note that ``olduint`` returns a value after printing Deprecation
179 Warning:
181 >>> olduint = np.deprecate(np.uint)
182 DeprecationWarning: `uint64` is deprecated! # may vary
183 >>> olduint(6)
184 6
186 """
187 # Deprecate may be run as a function or as a decorator
188 # If run as a function, we initialise the decorator class
189 # and execute its __call__ method.
191 if args:
192 fn = args[0]
193 args = args[1:]
195 return _Deprecate(*args, **kwargs)(fn)
196 else:
197 return _Deprecate(*args, **kwargs)
199deprecate_with_doc = lambda msg: _Deprecate(message=msg)
202#--------------------------------------------
203# Determine if two arrays can share memory
204#--------------------------------------------
206def byte_bounds(a):
207 """
208 Returns pointers to the end-points of an array.
210 Parameters
211 ----------
212 a : ndarray
213 Input array. It must conform to the Python-side of the array
214 interface.
216 Returns
217 -------
218 (low, high) : tuple of 2 integers
219 The first integer is the first byte of the array, the second
220 integer is just past the last byte of the array. If `a` is not
221 contiguous it will not use every byte between the (`low`, `high`)
222 values.
224 Examples
225 --------
226 >>> I = np.eye(2, dtype='f'); I.dtype
227 dtype('float32')
228 >>> low, high = np.byte_bounds(I)
229 >>> high - low == I.size*I.itemsize
230 True
231 >>> I = np.eye(2); I.dtype
232 dtype('float64')
233 >>> low, high = np.byte_bounds(I)
234 >>> high - low == I.size*I.itemsize
235 True
237 """
238 ai = a.__array_interface__
239 a_data = ai['data'][0]
240 astrides = ai['strides']
241 ashape = ai['shape']
242 bytes_a = asarray(a).dtype.itemsize
244 a_low = a_high = a_data
245 if astrides is None:
246 # contiguous case
247 a_high += a.size * bytes_a
248 else:
249 for shape, stride in zip(ashape, astrides):
250 if stride < 0:
251 a_low += (shape-1)*stride
252 else:
253 a_high += (shape-1)*stride
254 a_high += bytes_a
255 return a_low, a_high
258#-----------------------------------------------------------------------------
259# Function for output and information on the variables used.
260#-----------------------------------------------------------------------------
263def who(vardict=None):
264 """
265 Print the NumPy arrays in the given dictionary.
267 If there is no dictionary passed in or `vardict` is None then returns
268 NumPy arrays in the globals() dictionary (all NumPy arrays in the
269 namespace).
271 Parameters
272 ----------
273 vardict : dict, optional
274 A dictionary possibly containing ndarrays. Default is globals().
276 Returns
277 -------
278 out : None
279 Returns 'None'.
281 Notes
282 -----
283 Prints out the name, shape, bytes and type of all of the ndarrays
284 present in `vardict`.
286 Examples
287 --------
288 >>> a = np.arange(10)
289 >>> b = np.ones(20)
290 >>> np.who()
291 Name Shape Bytes Type
292 ===========================================================
293 a 10 80 int64
294 b 20 160 float64
295 Upper bound on total bytes = 240
297 >>> d = {'x': np.arange(2.0), 'y': np.arange(3.0), 'txt': 'Some str',
298 ... 'idx':5}
299 >>> np.who(d)
300 Name Shape Bytes Type
301 ===========================================================
302 x 2 16 float64
303 y 3 24 float64
304 Upper bound on total bytes = 40
306 """
307 if vardict is None:
308 frame = sys._getframe().f_back
309 vardict = frame.f_globals
310 sta = []
311 cache = {}
312 for name in vardict.keys():
313 if isinstance(vardict[name], ndarray):
314 var = vardict[name]
315 idv = id(var)
316 if idv in cache.keys():
317 namestr = name + " (%s)" % cache[idv]
318 original = 0
319 else:
320 cache[idv] = name
321 namestr = name
322 original = 1
323 shapestr = " x ".join(map(str, var.shape))
324 bytestr = str(var.nbytes)
325 sta.append([namestr, shapestr, bytestr, var.dtype.name,
326 original])
328 maxname = 0
329 maxshape = 0
330 maxbyte = 0
331 totalbytes = 0
332 for k in range(len(sta)):
333 val = sta[k]
334 if maxname < len(val[0]):
335 maxname = len(val[0])
336 if maxshape < len(val[1]):
337 maxshape = len(val[1])
338 if maxbyte < len(val[2]):
339 maxbyte = len(val[2])
340 if val[4]:
341 totalbytes += int(val[2])
343 if len(sta) > 0:
344 sp1 = max(10, maxname)
345 sp2 = max(10, maxshape)
346 sp3 = max(10, maxbyte)
347 prval = "Name %s Shape %s Bytes %s Type" % (sp1*' ', sp2*' ', sp3*' ')
348 print(prval + "\n" + "="*(len(prval)+5) + "\n")
350 for k in range(len(sta)):
351 val = sta[k]
352 print("%s %s %s %s %s %s %s" % (val[0], ' '*(sp1-len(val[0])+4),
353 val[1], ' '*(sp2-len(val[1])+5),
354 val[2], ' '*(sp3-len(val[2])+5),
355 val[3]))
356 print("\nUpper bound on total bytes = %d" % totalbytes)
357 return
359#-----------------------------------------------------------------------------
362# NOTE: pydoc defines a help function which works similarly to this
363# except it uses a pager to take over the screen.
365# combine name and arguments and split to multiple lines of width
366# characters. End lines on a comma and begin argument list indented with
367# the rest of the arguments.
368def _split_line(name, arguments, width):
369 firstwidth = len(name)
370 k = firstwidth
371 newstr = name
372 sepstr = ", "
373 arglist = arguments.split(sepstr)
374 for argument in arglist:
375 if k == firstwidth:
376 addstr = ""
377 else:
378 addstr = sepstr
379 k = k + len(argument) + len(addstr)
380 if k > width:
381 k = firstwidth + 1 + len(argument)
382 newstr = newstr + ",\n" + " "*(firstwidth+2) + argument
383 else:
384 newstr = newstr + addstr + argument
385 return newstr
387_namedict = None
388_dictlist = None
390# Traverse all module directories underneath globals
391# to see if something is defined
392def _makenamedict(module='numpy'):
393 module = __import__(module, globals(), locals(), [])
394 thedict = {module.__name__:module.__dict__}
395 dictlist = [module.__name__]
396 totraverse = [module.__dict__]
397 while True:
398 if len(totraverse) == 0:
399 break
400 thisdict = totraverse.pop(0)
401 for x in thisdict.keys():
402 if isinstance(thisdict[x], types.ModuleType):
403 modname = thisdict[x].__name__
404 if modname not in dictlist:
405 moddict = thisdict[x].__dict__
406 dictlist.append(modname)
407 totraverse.append(moddict)
408 thedict[modname] = moddict
409 return thedict, dictlist
412def _info(obj, output=sys.stdout):
413 """Provide information about ndarray obj.
415 Parameters
416 ----------
417 obj : ndarray
418 Must be ndarray, not checked.
419 output
420 Where printed output goes.
422 Notes
423 -----
424 Copied over from the numarray module prior to its removal.
425 Adapted somewhat as only numpy is an option now.
427 Called by info.
429 """
430 extra = ""
431 tic = ""
432 bp = lambda x: x
433 cls = getattr(obj, '__class__', type(obj))
434 nm = getattr(cls, '__name__', cls)
435 strides = obj.strides
436 endian = obj.dtype.byteorder
438 print("class: ", nm, file=output)
439 print("shape: ", obj.shape, file=output)
440 print("strides: ", strides, file=output)
441 print("itemsize: ", obj.itemsize, file=output)
442 print("aligned: ", bp(obj.flags.aligned), file=output)
443 print("contiguous: ", bp(obj.flags.contiguous), file=output)
444 print("fortran: ", obj.flags.fortran, file=output)
445 print(
446 "data pointer: %s%s" % (hex(obj.ctypes._as_parameter_.value), extra),
447 file=output
448 )
449 print("byteorder: ", end=' ', file=output)
450 if endian in ['|', '=']:
451 print("%s%s%s" % (tic, sys.byteorder, tic), file=output)
452 byteswap = False
453 elif endian == '>':
454 print("%sbig%s" % (tic, tic), file=output)
455 byteswap = sys.byteorder != "big"
456 else:
457 print("%slittle%s" % (tic, tic), file=output)
458 byteswap = sys.byteorder != "little"
459 print("byteswap: ", bp(byteswap), file=output)
460 print("type: %s" % obj.dtype, file=output)
463@set_module('numpy')
464def info(object=None, maxwidth=76, output=sys.stdout, toplevel='numpy'):
465 """
466 Get help information for a function, class, or module.
468 Parameters
469 ----------
470 object : object or str, optional
471 Input object or name to get information about. If `object` is a
472 numpy object, its docstring is given. If it is a string, available
473 modules are searched for matching objects. If None, information
474 about `info` itself is returned.
475 maxwidth : int, optional
476 Printing width.
477 output : file like object, optional
478 File like object that the output is written to, default is
479 ``stdout``. The object has to be opened in 'w' or 'a' mode.
480 toplevel : str, optional
481 Start search at this level.
483 See Also
484 --------
485 source, lookfor
487 Notes
488 -----
489 When used interactively with an object, ``np.info(obj)`` is equivalent
490 to ``help(obj)`` on the Python prompt or ``obj?`` on the IPython
491 prompt.
493 Examples
494 --------
495 >>> np.info(np.polyval) # doctest: +SKIP
496 polyval(p, x)
497 Evaluate the polynomial p at x.
498 ...
500 When using a string for `object` it is possible to get multiple results.
502 >>> np.info('fft') # doctest: +SKIP
503 *** Found in numpy ***
504 Core FFT routines
505 ...
506 *** Found in numpy.fft ***
507 fft(a, n=None, axis=-1)
508 ...
509 *** Repeat reference found in numpy.fft.fftpack ***
510 *** Total of 3 references found. ***
512 """
513 global _namedict, _dictlist
514 # Local import to speed up numpy's import time.
515 import pydoc
516 import inspect
518 if (hasattr(object, '_ppimport_importer') or
519 hasattr(object, '_ppimport_module')):
520 object = object._ppimport_module
521 elif hasattr(object, '_ppimport_attr'):
522 object = object._ppimport_attr
524 if object is None:
525 info(info)
526 elif isinstance(object, ndarray):
527 _info(object, output=output)
528 elif isinstance(object, str):
529 if _namedict is None:
530 _namedict, _dictlist = _makenamedict(toplevel)
531 numfound = 0
532 objlist = []
533 for namestr in _dictlist:
534 try:
535 obj = _namedict[namestr][object]
536 if id(obj) in objlist:
537 print("\n "
538 "*** Repeat reference found in %s *** " % namestr,
539 file=output
540 )
541 else:
542 objlist.append(id(obj))
543 print(" *** Found in %s ***" % namestr, file=output)
544 info(obj)
545 print("-"*maxwidth, file=output)
546 numfound += 1
547 except KeyError:
548 pass
549 if numfound == 0:
550 print("Help for %s not found." % object, file=output)
551 else:
552 print("\n "
553 "*** Total of %d references found. ***" % numfound,
554 file=output
555 )
557 elif inspect.isfunction(object):
558 name = object.__name__
559 arguments = formatargspec(*getargspec(object))
561 if len(name+arguments) > maxwidth:
562 argstr = _split_line(name, arguments, maxwidth)
563 else:
564 argstr = name + arguments
566 print(" " + argstr + "\n", file=output)
567 print(inspect.getdoc(object), file=output)
569 elif inspect.isclass(object):
570 name = object.__name__
571 arguments = "()"
572 try:
573 if hasattr(object, '__init__'):
574 arguments = formatargspec(
575 *getargspec(object.__init__.__func__)
576 )
577 arglist = arguments.split(', ')
578 if len(arglist) > 1:
579 arglist[1] = "("+arglist[1]
580 arguments = ", ".join(arglist[1:])
581 except Exception:
582 pass
584 if len(name+arguments) > maxwidth:
585 argstr = _split_line(name, arguments, maxwidth)
586 else:
587 argstr = name + arguments
589 print(" " + argstr + "\n", file=output)
590 doc1 = inspect.getdoc(object)
591 if doc1 is None:
592 if hasattr(object, '__init__'):
593 print(inspect.getdoc(object.__init__), file=output)
594 else:
595 print(inspect.getdoc(object), file=output)
597 methods = pydoc.allmethods(object)
598 if methods != []:
599 print("\n\nMethods:\n", file=output)
600 for meth in methods:
601 if meth[0] == '_':
602 continue
603 thisobj = getattr(object, meth, None)
604 if thisobj is not None:
605 methstr, other = pydoc.splitdoc(
606 inspect.getdoc(thisobj) or "None"
607 )
608 print(" %s -- %s" % (meth, methstr), file=output)
610 elif inspect.ismethod(object):
611 name = object.__name__
612 arguments = formatargspec(
613 *getargspec(object.__func__)
614 )
615 arglist = arguments.split(', ')
616 if len(arglist) > 1:
617 arglist[1] = "("+arglist[1]
618 arguments = ", ".join(arglist[1:])
619 else:
620 arguments = "()"
622 if len(name+arguments) > maxwidth:
623 argstr = _split_line(name, arguments, maxwidth)
624 else:
625 argstr = name + arguments
627 print(" " + argstr + "\n", file=output)
628 print(inspect.getdoc(object), file=output)
630 elif hasattr(object, '__doc__'):
631 print(inspect.getdoc(object), file=output)
634@set_module('numpy')
635def source(object, output=sys.stdout):
636 """
637 Print or write to a file the source code for a NumPy object.
639 The source code is only returned for objects written in Python. Many
640 functions and classes are defined in C and will therefore not return
641 useful information.
643 Parameters
644 ----------
645 object : numpy object
646 Input object. This can be any object (function, class, module,
647 ...).
648 output : file object, optional
649 If `output` not supplied then source code is printed to screen
650 (sys.stdout). File object must be created with either write 'w' or
651 append 'a' modes.
653 See Also
654 --------
655 lookfor, info
657 Examples
658 --------
659 >>> np.source(np.interp) #doctest: +SKIP
660 In file: /usr/lib/python2.6/dist-packages/numpy/lib/function_base.py
661 def interp(x, xp, fp, left=None, right=None):
662 \"\"\".... (full docstring printed)\"\"\"
663 if isinstance(x, (float, int, number)):
664 return compiled_interp([x], xp, fp, left, right).item()
665 else:
666 return compiled_interp(x, xp, fp, left, right)
668 The source code is only returned for objects written in Python.
670 >>> np.source(np.array) #doctest: +SKIP
671 Not available for this object.
673 """
674 # Local import to speed up numpy's import time.
675 import inspect
676 try:
677 print("In file: %s\n" % inspect.getsourcefile(object), file=output)
678 print(inspect.getsource(object), file=output)
679 except Exception:
680 print("Not available for this object.", file=output)
683# Cache for lookfor: {id(module): {name: (docstring, kind, index), ...}...}
684# where kind: "func", "class", "module", "object"
685# and index: index in breadth-first namespace traversal
686_lookfor_caches = {}
688# regexp whose match indicates that the string may contain a function
689# signature
690_function_signature_re = re.compile(r"[a-z0-9_]+\(.*[,=].*\)", re.I)
693@set_module('numpy')
694def lookfor(what, module=None, import_modules=True, regenerate=False,
695 output=None):
696 """
697 Do a keyword search on docstrings.
699 A list of objects that matched the search is displayed,
700 sorted by relevance. All given keywords need to be found in the
701 docstring for it to be returned as a result, but the order does
702 not matter.
704 Parameters
705 ----------
706 what : str
707 String containing words to look for.
708 module : str or list, optional
709 Name of module(s) whose docstrings to go through.
710 import_modules : bool, optional
711 Whether to import sub-modules in packages. Default is True.
712 regenerate : bool, optional
713 Whether to re-generate the docstring cache. Default is False.
714 output : file-like, optional
715 File-like object to write the output to. If omitted, use a pager.
717 See Also
718 --------
719 source, info
721 Notes
722 -----
723 Relevance is determined only roughly, by checking if the keywords occur
724 in the function name, at the start of a docstring, etc.
726 Examples
727 --------
728 >>> np.lookfor('binary representation') # doctest: +SKIP
729 Search results for 'binary representation'
730 ------------------------------------------
731 numpy.binary_repr
732 Return the binary representation of the input number as a string.
733 numpy.core.setup_common.long_double_representation
734 Given a binary dump as given by GNU od -b, look for long double
735 numpy.base_repr
736 Return a string representation of a number in the given base system.
737 ...
739 """
740 import pydoc
742 # Cache
743 cache = _lookfor_generate_cache(module, import_modules, regenerate)
745 # Search
746 # XXX: maybe using a real stemming search engine would be better?
747 found = []
748 whats = str(what).lower().split()
749 if not whats:
750 return
752 for name, (docstring, kind, index) in cache.items():
753 if kind in ('module', 'object'):
754 # don't show modules or objects
755 continue
756 doc = docstring.lower()
757 if all(w in doc for w in whats):
758 found.append(name)
760 # Relevance sort
761 # XXX: this is full Harrison-Stetson heuristics now,
762 # XXX: it probably could be improved
764 kind_relevance = {'func': 1000, 'class': 1000,
765 'module': -1000, 'object': -1000}
767 def relevance(name, docstr, kind, index):
768 r = 0
769 # do the keywords occur within the start of the docstring?
770 first_doc = "\n".join(docstr.lower().strip().split("\n")[:3])
771 r += sum([200 for w in whats if w in first_doc])
772 # do the keywords occur in the function name?
773 r += sum([30 for w in whats if w in name])
774 # is the full name long?
775 r += -len(name) * 5
776 # is the object of bad type?
777 r += kind_relevance.get(kind, -1000)
778 # is the object deep in namespace hierarchy?
779 r += -name.count('.') * 10
780 r += max(-index / 100, -100)
781 return r
783 def relevance_value(a):
784 return relevance(a, *cache[a])
785 found.sort(key=relevance_value)
787 # Pretty-print
788 s = "Search results for '%s'" % (' '.join(whats))
789 help_text = [s, "-"*len(s)]
790 for name in found[::-1]:
791 doc, kind, ix = cache[name]
793 doclines = [line.strip() for line in doc.strip().split("\n")
794 if line.strip()]
796 # find a suitable short description
797 try:
798 first_doc = doclines[0].strip()
799 if _function_signature_re.search(first_doc):
800 first_doc = doclines[1].strip()
801 except IndexError:
802 first_doc = ""
803 help_text.append("%s\n %s" % (name, first_doc))
805 if not found:
806 help_text.append("Nothing found.")
808 # Output
809 if output is not None:
810 output.write("\n".join(help_text))
811 elif len(help_text) > 10:
812 pager = pydoc.getpager()
813 pager("\n".join(help_text))
814 else:
815 print("\n".join(help_text))
817def _lookfor_generate_cache(module, import_modules, regenerate):
818 """
819 Generate docstring cache for given module.
821 Parameters
822 ----------
823 module : str, None, module
824 Module for which to generate docstring cache
825 import_modules : bool
826 Whether to import sub-modules in packages.
827 regenerate : bool
828 Re-generate the docstring cache
830 Returns
831 -------
832 cache : dict {obj_full_name: (docstring, kind, index), ...}
833 Docstring cache for the module, either cached one (regenerate=False)
834 or newly generated.
836 """
837 # Local import to speed up numpy's import time.
838 import inspect
840 from io import StringIO
842 if module is None:
843 module = "numpy"
845 if isinstance(module, str):
846 try:
847 __import__(module)
848 except ImportError:
849 return {}
850 module = sys.modules[module]
851 elif isinstance(module, list) or isinstance(module, tuple):
852 cache = {}
853 for mod in module:
854 cache.update(_lookfor_generate_cache(mod, import_modules,
855 regenerate))
856 return cache
858 if id(module) in _lookfor_caches and not regenerate:
859 return _lookfor_caches[id(module)]
861 # walk items and collect docstrings
862 cache = {}
863 _lookfor_caches[id(module)] = cache
864 seen = {}
865 index = 0
866 stack = [(module.__name__, module)]
867 while stack:
868 name, item = stack.pop(0)
869 if id(item) in seen:
870 continue
871 seen[id(item)] = True
873 index += 1
874 kind = "object"
876 if inspect.ismodule(item):
877 kind = "module"
878 try:
879 _all = item.__all__
880 except AttributeError:
881 _all = None
883 # import sub-packages
884 if import_modules and hasattr(item, '__path__'):
885 for pth in item.__path__:
886 for mod_path in os.listdir(pth):
887 this_py = os.path.join(pth, mod_path)
888 init_py = os.path.join(pth, mod_path, '__init__.py')
889 if (os.path.isfile(this_py) and
890 mod_path.endswith('.py')):
891 to_import = mod_path[:-3]
892 elif os.path.isfile(init_py):
893 to_import = mod_path
894 else:
895 continue
896 if to_import == '__init__':
897 continue
899 try:
900 old_stdout = sys.stdout
901 old_stderr = sys.stderr
902 try:
903 sys.stdout = StringIO()
904 sys.stderr = StringIO()
905 __import__("%s.%s" % (name, to_import))
906 finally:
907 sys.stdout = old_stdout
908 sys.stderr = old_stderr
909 # Catch SystemExit, too
910 except BaseException:
911 continue
913 for n, v in _getmembers(item):
914 try:
915 item_name = getattr(v, '__name__', "%s.%s" % (name, n))
916 mod_name = getattr(v, '__module__', None)
917 except NameError:
918 # ref. SWIG's global cvars
919 # NameError: Unknown C global variable
920 item_name = "%s.%s" % (name, n)
921 mod_name = None
922 if '.' not in item_name and mod_name:
923 item_name = "%s.%s" % (mod_name, item_name)
925 if not item_name.startswith(name + '.'):
926 # don't crawl "foreign" objects
927 if isinstance(v, ufunc):
928 # ... unless they are ufuncs
929 pass
930 else:
931 continue
932 elif not (inspect.ismodule(v) or _all is None or n in _all):
933 continue
934 stack.append(("%s.%s" % (name, n), v))
935 elif inspect.isclass(item):
936 kind = "class"
937 for n, v in _getmembers(item):
938 stack.append(("%s.%s" % (name, n), v))
939 elif hasattr(item, "__call__"):
940 kind = "func"
942 try:
943 doc = inspect.getdoc(item)
944 except NameError:
945 # ref SWIG's NameError: Unknown C global variable
946 doc = None
947 if doc is not None:
948 cache[name] = (doc, kind, index)
950 return cache
952def _getmembers(item):
953 import inspect
954 try:
955 members = inspect.getmembers(item)
956 except Exception:
957 members = [(x, getattr(item, x)) for x in dir(item)
958 if hasattr(item, x)]
959 return members
962def safe_eval(source):
963 """
964 Protected string evaluation.
966 Evaluate a string containing a Python literal expression without
967 allowing the execution of arbitrary non-literal code.
969 Parameters
970 ----------
971 source : str
972 The string to evaluate.
974 Returns
975 -------
976 obj : object
977 The result of evaluating `source`.
979 Raises
980 ------
981 SyntaxError
982 If the code has invalid Python syntax, or if it contains
983 non-literal code.
985 Examples
986 --------
987 >>> np.safe_eval('1')
988 1
989 >>> np.safe_eval('[1, 2, 3]')
990 [1, 2, 3]
991 >>> np.safe_eval('{"foo": ("bar", 10.0)}')
992 {'foo': ('bar', 10.0)}
994 >>> np.safe_eval('import os')
995 Traceback (most recent call last):
996 ...
997 SyntaxError: invalid syntax
999 >>> np.safe_eval('open("/home/user/.ssh/id_dsa").read()')
1000 Traceback (most recent call last):
1001 ...
1002 ValueError: malformed node or string: <_ast.Call object at 0x...>
1004 """
1005 # Local import to speed up numpy's import time.
1006 import ast
1007 return ast.literal_eval(source)
1010def _median_nancheck(data, result, axis, out):
1011 """
1012 Utility function to check median result from data for NaN values at the end
1013 and return NaN in that case. Input result can also be a MaskedArray.
1015 Parameters
1016 ----------
1017 data : array
1018 Input data to median function
1019 result : Array or MaskedArray
1020 Result of median function
1021 axis : {int, sequence of int, None}, optional
1022 Axis or axes along which the median was computed.
1023 out : ndarray, optional
1024 Output array in which to place the result.
1025 Returns
1026 -------
1027 median : scalar or ndarray
1028 Median or NaN in axes which contained NaN in the input.
1029 """
1030 if data.size == 0:
1031 return result
1032 data = np.moveaxis(data, axis, -1)
1033 n = np.isnan(data[..., -1])
1034 # masked NaN values are ok
1035 if np.ma.isMaskedArray(n):
1036 n = n.filled(False)
1037 if result.ndim == 0:
1038 if n == True:
1039 if out is not None:
1040 out[...] = data.dtype.type(np.nan)
1041 result = out
1042 else:
1043 result = data.dtype.type(np.nan)
1044 elif np.count_nonzero(n.ravel()) > 0:
1045 result[n] = np.nan
1046 return result
1048#-----------------------------------------------------------------------------