Add types and fix google docstrings to agree

MANIFEST.in

@@ -1,5 +1,6 @@
 include *.md
 include *.py
+include *.toml
 include run_doctests.sh
 include *.txt
 include LICENSE

requirements/jupyter.txt

@@ -6,6 +6,7 @@
 # python ~/local/tools/supported_python_versions_pip.py debugpy
 # python ~/local/tools/supported_python_versions_pip.py jedi
 # python ~/local/tools/supported_python_versions_pip.py attrs
+# python ~/local/tools/supported_python_versions_pip.py ipython_genutils
 
 
 nbconvert>=6.0.0;                              python_version >= '3.6.0'   # Python 3.6+
@@ -31,6 +32,11 @@ debugpy>=1.0.0     ; python_version < '3.8' and python_version >= '3.7'    # Pyt
 debugpy>=1.0.0     ; python_version < '3.7' and python_version >= '3.6'    # Python 3.6
 
 
+# Needed for 3.10 tests
+ipython_genutils >= 0.2.0 ;                            python_version >= '3.10'    # Python 3.10+
+
+
+
 # For IPython
 jedi>=0.16  ; python_version >= '3.6'    # Python 3.6+
 

setup.py

@@ -222,6 +222,9 @@ def gen_packages_items():
         # packages=['xdoctest', 'xdoctest.utils', 'xdoctest.docstr'],
         # custom PyPI classifier for pytest plugins
         python_requires='>=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*',
+        package_data={
+            'xdoctest': ['py.typed', '*.pyi'],
+        },
         classifiers=[
             'Development Status :: 5 - Production/Stable',
             'Intended Audience :: Developers',

xdoctest/__main__.pyi

@@ -0,0 +1,5 @@
+from _typeshed import Incomplete
+
+
+def main(argv: Incomplete | None = ...):
+    ...

xdoctest/checker.pyi

@@ -0,0 +1,57 @@
+from _typeshed import Incomplete
+
+unicode_literal_re: Incomplete
+bytes_literal_re: Incomplete
+BLANKLINE_MARKER: str
+ELLIPSIS_MARKER: str
+TRAILING_WS: Incomplete
+
+
+def check_got_vs_want(want: str,
+                      got_stdout: str,
+                      got_eval: str = ...,
+                      runstate: Incomplete | None = ...):
+    ...
+
+
+def extract_exc_want(want):
+    ...
+
+
+def check_exception(exc_got, want, runstate: Incomplete | None = ...):
+    ...
+
+
+def check_output(got, want, runstate: Incomplete | None = ...):
+    ...
+
+
+def normalize(got, want, runstate: Incomplete | None = ...):
+    ...
+
+
+class ExtractGotReprException(AssertionError):
+    orig_ex: Incomplete
+
+    def __init__(self, msg, orig_ex) -> None:
+        ...
+
+
+class GotWantException(AssertionError):
+    got: Incomplete
+    want: Incomplete
+
+    def __init__(self, msg, got, want) -> None:
+        ...
+
+    def output_difference(self,
+                          runstate: Incomplete | None = ...,
+                          colored: bool = ...):
+        ...
+
+    def output_repr_difference(self, runstate: Incomplete | None = ...):
+        ...
+
+
+def remove_blankline_marker(text):
+    ...

xdoctest/constants.pyi

@@ -0,0 +1,27 @@
+from _typeshed import Incomplete
+
+
+class _NOT_EVAL_TYPE:
+
+    def __new__(cls):
+        ...
+
+    def __reduce__(self):
+        ...
+
+    def __copy__(self):
+        ...
+
+    def __deepcopy__(self, memo):
+        ...
+
+    def __call__(self, default) -> None:
+        ...
+
+    def __bool__(self):
+        ...
+
+    __nonzero__: Incomplete
+
+
+NOT_EVALED: Incomplete

xdoctest/core.py

@@ -444,7 +444,7 @@ def package_calldefs(pkg_identifier, exclude=[], ignore_syntax_errors=True,
     Statically generates all callable definitions in a module or package
 
     Args:
-        pkg_identifier (str | Module): path to or name of the module to be
+        pkg_identifier (str | ModuleType): path to or name of the module to be
             tested (or the live module itself, which is not recommended)
 
         exclude (List[str]): glob-patterns of file names to exclude
@@ -459,7 +459,7 @@ def package_calldefs(pkg_identifier, exclude=[], ignore_syntax_errors=True,
             dynamic analysis is used to parse all calldefs.
 
     Yields:
-        Tuple[Dict[str, CallDefNode], str | Module] -
+        Tuple[Dict[str, xdoctest.static_analysis.CallDefNode], str | ModuleType] -
             * item[0]: the mapping of callnames-to-calldefs
             * item[1]: the path to the file containing the doctest
               (usually a module) or the module itself
@@ -514,7 +514,7 @@ def parse_calldefs(module_identifier, analysis='auto'):
     analysis.
 
     Args:
-        module_identifier (str | Module): path to or name of the module to be
+        module_identifier (str | ModuleType): path to or name of the module to be
             tested (or the live module itself, which is not recommended)
 
         analysis (str, default='auto'):
@@ -524,8 +524,8 @@ def parse_calldefs(module_identifier, analysis='auto'):
             dynamic analysis is used to parse all calldefs.
 
     Returns:
-        Dict[str, CallDefNode]: the mapping of callnames-to-calldefs within
-          the module.
+        Dict[str, xdoctest.static_analysis.CallDefNode]:
+            the mapping of callnames-to-calldefs within the module.
     """
     # backwards compatibility hacks
     if '--allow-xdoc-dynamic' in sys.argv:
@@ -607,7 +607,7 @@ def parse_doctestables(module_identifier, exclude=[], style='auto',
     example objects.  The style influences which tests are found.
 
     Args:
-        module_identifier (str | PathLike | Module):
+        module_identifier (str | PathLike | ModuleType):
             path or name of a module or a module itself (we prefer a path)
 
         exclude (List[str]): glob-patterns of file names to exclude

xdoctest/core.pyi

@@ -0,0 +1,75 @@
+from typing import Union
+from os import PathLike
+import xdoctest
+from types import ModuleType
+from typing import List
+from typing import Dict
+from _typeshed import Incomplete
+from collections.abc import Generator
+from typing import Any
+
+DOCTEST_STYLES: Incomplete
+
+
+def parse_freeform_docstr_examples(
+    docstr: str,
+    callname: str = None,
+    modpath: Union[str, PathLike] = None,
+    lineno: int = 1,
+    fpath: Union[str, PathLike] = None,
+    asone: bool = True
+) -> Generator[xdoctest.doctest_example.DocTest, None, Any]:
+    ...
+
+
+def parse_google_docstr_examples(
+    docstr: str,
+    callname: str = None,
+    modpath: Union[str, PathLike] = None,
+    lineno: int = 1,
+    fpath: Union[str, PathLike] = None,
+    eager_parse: bool = True
+) -> Generator[xdoctest.doctest_example.DocTest, None, None]:
+    ...
+
+
+def parse_auto_docstr_examples(docstr, *args,
+                               **kwargs) -> Generator[Any, None, None]:
+    ...
+
+
+def parse_docstr_examples(
+    docstr: str,
+    callname: str = None,
+    modpath: Union[str, PathLike] = None,
+    lineno: int = 1,
+    style: str = 'auto',
+    fpath: Union[str, PathLike] = None,
+    parser_kw: dict = ...
+) -> Generator[xdoctest.doctest_example.DocTest, None, None]:
+    ...
+
+
+def package_calldefs(pkg_identifier: Union[str, ModuleType],
+                     exclude: List[str] = ...,
+                     ignore_syntax_errors: bool = True,
+                     analysis: str = 'auto') -> Generator[None, None, None]:
+    ...
+
+
+def parse_calldefs(
+        module_identifier: Union[str, ModuleType],
+        analysis: str = 'auto'
+) -> Dict[str, xdoctest.static_analysis.CallDefNode]:
+    ...
+
+
+def parse_doctestables(
+    module_identifier: Union[str, PathLike, ModuleType],
+    exclude: List[str] = ...,
+    style: str = 'auto',
+    ignore_syntax_errors: bool = True,
+    parser_kw=...,
+    analysis: str = 'auto'
+) -> Generator[xdoctest.doctest_example.DocTest, None, None]:
+    ...

xdoctest/demo.pyi

@@ -0,0 +1,20 @@
+from _typeshed import Incomplete
+
+
+def myfunc():
+    ...
+
+
+class MyClass:
+    data: Incomplete
+
+    def __init__(self, *args, **kw) -> None:
+        ...
+
+    @classmethod
+    def demo(cls, **kw):
+        ...
+
+    @staticmethod
+    def always_fails() -> None:
+        ...

xdoctest/directive.pyi

@@ -0,0 +1,86 @@
+from typing import List
+from typing import Dict
+from _typeshed import Incomplete
+from collections.abc import Generator
+from typing import NamedTuple
+from xdoctest import utils
+
+
+def named(key, pattern):
+    ...
+
+
+DEFAULT_RUNTIME_STATE: Incomplete
+
+
+class Effect(NamedTuple):
+    action: Incomplete
+    key: Incomplete
+    value: Incomplete
+
+
+class RuntimeState(utils.NiceRepr):
+
+    def __init__(self, default_state: Incomplete | None = ...) -> None:
+        ...
+
+    def to_dict(self):
+        ...
+
+    def __nice__(self):
+        ...
+
+    def __getitem__(self, key):
+        ...
+
+    def __setitem__(self, key, value) -> None:
+        ...
+
+    def set_report_style(self,
+                         reportchoice,
+                         state: Incomplete | None = ...) -> None:
+        ...
+
+    def update(self, directives: List[Directive]) -> None:
+        ...
+
+
+class Directive(utils.NiceRepr):
+    name: Incomplete
+    args: Incomplete
+    inline: Incomplete
+    positive: Incomplete
+
+    def __init__(self,
+                 name,
+                 positive: bool = ...,
+                 args=...,
+                 inline: Incomplete | None = ...) -> None:
+        ...
+
+    @classmethod
+    def extract(cls, text: str) -> Generator[Directive, None, None]:
+        ...
+
+    def __nice__(self):
+        ...
+
+    def effect(self,
+               argv: Incomplete | None = ...,
+               environ: Incomplete | None = ...):
+        ...
+
+    def effects(self,
+                argv: List[str] = None,
+                environ: Dict[str, str] = None) -> List[Effect]:
+        ...
+
+
+COMMANDS: Incomplete
+DIRECTIVE_PATTERNS: Incomplete
+DIRECTIVE_RE: Incomplete
+
+
+def parse_directive_optstr(optpart,
+                           inline: Incomplete | None = ...) -> Directive:
+    ...

xdoctest/docstr/docscrape_google.py

@@ -33,7 +33,7 @@ def split_google_docblocks(docstr):
         docstr (str): a docstring
 
     Returns:
-        List[Tuple[str, DocBlock[str, int]]]:
+        List[Tuple[str, DocBlock]]:
             list of 2-tuples where the first item is a google style docstring
             tag and the second item is the bock corresponding to that tag. The
             block itself is a 2-tuple where the first item is the unindented
@@ -303,7 +303,7 @@ def parse_google_returns(docstr, return_annot=None):
         >>> docstr = split_google_docblocks.__doc__
         >>> retdict_list = list(parse_google_returns(docstr))
         >>> print([sorted(d.items())[1] for d in retdict_list])
-        [('type', 'List[Tuple[str, DocBlock[str, int]]]')]
+        [('type', 'List[Tuple[str, DocBlock]]')]
     """
     blocks = split_google_docblocks(docstr)
     for key, block in blocks: