A class used to extract the DocTests that are relevant to a given object, from its docstring and the docstrings of its contained objects. Doctests can currently be extracted from the following object types: modules, functions, classes, methods, staticmethods, classmethods, and
| 842 | ###################################################################### |
| 843 | |
| 844 | class DocTestFinder: |
| 845 | """ |
| 846 | A class used to extract the DocTests that are relevant to a given |
| 847 | object, from its docstring and the docstrings of its contained |
| 848 | objects. Doctests can currently be extracted from the following |
| 849 | object types: modules, functions, classes, methods, staticmethods, |
| 850 | classmethods, and properties. |
| 851 | """ |
| 852 | |
| 853 | def __init__(self, verbose=False, parser=DocTestParser(), |
| 854 | recurse=True, exclude_empty=True): |
| 855 | """ |
| 856 | Create a new doctest finder. |
| 857 | |
| 858 | The optional argument `parser` specifies a class or |
| 859 | function that should be used to create new DocTest objects (or |
| 860 | objects that implement the same interface as DocTest). The |
| 861 | signature for this factory function should match the signature |
| 862 | of the DocTest constructor. |
| 863 | |
| 864 | If the optional argument `recurse` is false, then `find` will |
| 865 | only examine the given object, and not any contained objects. |
| 866 | |
| 867 | If the optional argument `exclude_empty` is false, then `find` |
| 868 | will include tests for objects with empty docstrings. |
| 869 | """ |
| 870 | self._parser = parser |
| 871 | self._verbose = verbose |
| 872 | self._recurse = recurse |
| 873 | self._exclude_empty = exclude_empty |
| 874 | |
| 875 | def find(self, obj, name=None, module=None, globs=None, extraglobs=None): |
| 876 | """ |
| 877 | Return a list of the DocTests that are defined by the given |
| 878 | object's docstring, or by any of its contained objects' |
| 879 | docstrings. |
| 880 | |
| 881 | The optional parameter `module` is the module that contains |
| 882 | the given object. If the module is not specified or is None, then |
| 883 | the test finder will attempt to automatically determine the |
| 884 | correct module. The object's module is used: |
| 885 | |
| 886 | - As a default namespace, if `globs` is not specified. |
| 887 | - To prevent the DocTestFinder from extracting DocTests |
| 888 | from objects that are imported from other modules. |
| 889 | - To find the name of the file containing the object. |
| 890 | - To help find the line number of the object within its |
| 891 | file. |
| 892 | |
| 893 | Contained objects whose module does not match `module` are ignored. |
| 894 | |
| 895 | If `module` is False, no attempt to find the module will be made. |
| 896 | This is obscure, of use mostly in tests: if `module` is False, or |
| 897 | is None but cannot be found automatically, then all objects are |
| 898 | considered to belong to the (non-existent) module, so all contained |
| 899 | objects will (recursively) be searched for doctests. |
| 900 | |
| 901 | The globals for each DocTest is formed by combining `globs` |
no outgoing calls