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, th
(self, obj, name=None, module=None, globs=None, extraglobs=None)
| 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` |
| 875 | and `extraglobs` (bindings in `extraglobs` override bindings |
| 876 | in `globs`). A new copy of the globals dictionary is created |
| 877 | for each DocTest. If `globs` is not specified, then it |
| 878 | defaults to the module's `__dict__`, if specified, or {} |
| 879 | otherwise. If `extraglobs` is not specified, then it defaults |
| 880 | to {}. |
| 881 | |
| 882 | """ |
| 883 | # If name was not specified, then extract it from the object. |
| 884 | if name is None: |
| 885 | name = getattr(obj, '__name__', None) |
| 886 | if name is None: |
| 887 | raise ValueError("DocTestFinder.find: name must be given " |
| 888 | "when obj.__name__ doesn't exist: %r" % |
| 889 | (type(obj),)) |
| 890 | |
| 891 | # Find the module that contains the given object (if obj is |
| 892 | # a module, then module=obj.). Note: this may fail, in which |
| 893 | # case module will be None. |
| 894 | if module is False: |
| 895 | module = None |
| 896 | elif module is None: |
| 897 | module = inspect.getmodule(obj) |
| 898 | |
| 899 | # Read the module's source code. This is used by |
| 900 | # DocTestFinder._find_lineno to find the line number for a |
| 901 | # given object's docstring. |
| 902 | try: |
| 903 | file = inspect.getsourcefile(obj) |
| 904 | except TypeError: |
| 905 | source_lines = None |
no test coverage detected