def find(self, obj, name=None, module=None, globs=None, |
extraglobs=None): |
""" |
Return a list of the DocTests that are defined by the given |
object's docstring, or by any of its contained objects' |
docstrings. |
|
The optional parameter `module` is the module that contains |
the given object. If the module is not specified or is None, then |
the test finder will attempt to automatically determine the |
correct module. The object's module is used: |
|
- As a default namespace, if `globs` is not specified. |
- To prevent the DocTestFinder from extracting DocTests |
from objects that are imported from other modules. |
- To find the name of the file containing the object. |
- To help find the line number of the object within its |
file. |
|
Contained objects whose module does not match `module` are ignored. |
|
If `module` is False, no attempt to find the module will be made. |
This is obscure, of use mostly in tests: if `module` is False, or |
is None but cannot be found automatically, then all objects are |
considered to belong to the (non-existent) module, so all contained |
objects will (recursively) be searched for doctests. |
|
The globals for each DocTest is formed by combining `globs` |
and `extraglobs` (bindings in `extraglobs` override bindings |
in `globs`). A new copy of the globals dictionary is created |
for each DocTest. If `globs` is not specified, then it |
defaults to the module's `__dict__`, if specified, or {} |
otherwise. If `extraglobs` is not specified, then it defaults |
to {}. |
|
""" |
|
if name is None: |
name = getattr(obj, '__name__', None) |
if name is None: |
raise ValueError("DocTestFinder.find: name must be given " |
"when obj.__name__ doesn't exist: %r" % |
(type(obj),)) |
|
|
|
|
if module is False: |
module = None |
elif module is None: |
module = inspect.getmodule(obj) |
|
|
|
|
try: |
file = inspect.getsourcefile(obj) or inspect.getfile(obj) |
source_lines = linecache.getlines(file) |
if not source_lines: |
source_lines = None |
except TypeError: |
source_lines = None |
|
|
if globs is None: |
if module is None: |
globs = {} |
else: |
globs = module.__dict__.copy() |
else: |
globs = globs.copy() |
if extraglobs is not None: |
globs.update(extraglobs) |
|
|
tests = [] |
self._find(tests, obj, name, module, source_lines, globs, {}) |
|
|
|
|
tests.sort() |
return tests |