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,
| 815 | ###################################################################### |
| 816 | |
| 817 | class DocTestFinder: |
| 818 | """ |
| 819 | A class used to extract the DocTests that are relevant to a given |
| 820 | object, from its docstring and the docstrings of its contained |
| 821 | objects. Doctests can currently be extracted from the following |
| 822 | object types: modules, functions, classes, methods, staticmethods, |
| 823 | classmethods, and properties. |
| 824 | """ |
| 825 | |
| 826 | def __init__(self, verbose=False, parser=DocTestParser(), |
| 827 | recurse=True, exclude_empty=True): |
| 828 | """ |
| 829 | Create a new doctest finder. |
| 830 | |
| 831 | The optional argument `parser` specifies a class or |
| 832 | function that should be used to create new DocTest objects (or |
| 833 | objects that implement the same interface as DocTest). The |
| 834 | signature for this factory function should match the signature |
| 835 | of the DocTest constructor. |
| 836 | |
| 837 | If the optional argument `recurse` is false, then `find` will |
| 838 | only examine the given object, and not any contained objects. |
| 839 | |
| 840 | If the optional argument `exclude_empty` is false, then `find` |
| 841 | will include tests for objects with empty docstrings. |
| 842 | """ |
| 843 | self._parser = parser |
| 844 | self._verbose = verbose |
| 845 | self._recurse = recurse |
| 846 | self._exclude_empty = exclude_empty |
| 847 | |
| 848 | def find(self, obj, name=None, module=None, globs=None, extraglobs=None): |
| 849 | """ |
| 850 | Return a list of the DocTests that are defined by the given |
| 851 | object's docstring, or by any of its contained objects' |
| 852 | docstrings. |
| 853 | |
| 854 | The optional parameter `module` is the module that contains |
| 855 | the given object. If the module is not specified or is None, then |
| 856 | the test finder will attempt to automatically determine the |
| 857 | correct module. The object's module is used: |
| 858 | |
| 859 | - As a default namespace, if `globs` is not specified. |
| 860 | - To prevent the DocTestFinder from extracting DocTests |
| 861 | from objects that are imported from other modules. |
| 862 | - To find the name of the file containing the object. |
| 863 | - To help find the line number of the object within its |
| 864 | file. |
| 865 | |
| 866 | Contained objects whose module does not match `module` are ignored. |
| 867 | |
| 868 | If `module` is False, no attempt to find the module will be made. |
| 869 | This is obscure, of use mostly in tests: if `module` is False, or |
| 870 | is None but cannot be found automatically, then all objects are |
| 871 | considered to belong to the (non-existent) module, so all contained |
| 872 | objects will (recursively) be searched for doctests. |
| 873 | |
| 874 | The globals for each DocTest is formed by combining `globs` |
no outgoing calls