Hello community,
here is the log from the commit of package python-sphinx-autodoc-typehints for
openSUSE:Factory checked in at 2019-09-17 13:39:12
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Comparing /work/SRC/openSUSE:Factory/python-sphinx-autodoc-typehints (Old)
and /work/SRC/openSUSE:Factory/.python-sphinx-autodoc-typehints.new.7948
(New)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "python-sphinx-autodoc-typehints"
Tue Sep 17 13:39:12 2019 rev:4 rq:731298 version:1.8.0
Changes:
--------
---
/work/SRC/openSUSE:Factory/python-sphinx-autodoc-typehints/python-sphinx-autodoc-typehints.changes
2019-09-11 10:35:15.795298493 +0200
+++
/work/SRC/openSUSE:Factory/.python-sphinx-autodoc-typehints.new.7948/python-sphinx-autodoc-typehints.changes
2019-09-17 13:39:14.165825381 +0200
@@ -1,0 +2,10 @@
+Mon Sep 16 13:38:42 UTC 2019 - Tomáš Chvátal <[email protected]>
+
+- Update to 1.8.0:
+ * Fixed regression which caused TypeError or OSError when trying to set
annotations due to PR #87
+ * Fixed unintentional mangling of annotation type names
+ * Added proper :py:data targets for NoReturn, ClassVar and Tuple
+ * Added support for inline type comments (like (int, str) -> None) (PR by
Bernát Gábor)
+ * Use the native AST parser for type comment support on Python 3.8+
+
+-------------------------------------------------------------------
Old:
----
sphinx-autodoc-typehints-1.7.0.tar.gz
New:
----
sphinx-autodoc-typehints-1.8.0.tar.gz
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Other differences:
------------------
++++++ python-sphinx-autodoc-typehints.spec ++++++
--- /var/tmp/diff_new_pack.PQw8Mk/_old 2019-09-17 13:39:14.845825273 +0200
+++ /var/tmp/diff_new_pack.PQw8Mk/_new 2019-09-17 13:39:14.845825273 +0200
@@ -19,7 +19,7 @@
%{?!python_module:%define python_module() python-%{**} python3-%{**}}
%define skip_python2 1
Name: python-sphinx-autodoc-typehints
-Version: 1.7.0
+Version: 1.8.0
Release: 0
Summary: Type hints (PEP 484) support for the Sphinx autodoc extension
License: MIT
++++++ sphinx-autodoc-typehints-1.7.0.tar.gz ->
sphinx-autodoc-typehints-1.8.0.tar.gz ++++++
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-autodoc-typehints-1.7.0/CHANGELOG.rst
new/sphinx-autodoc-typehints-1.8.0/CHANGELOG.rst
--- old/sphinx-autodoc-typehints-1.7.0/CHANGELOG.rst 2019-07-24
17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/CHANGELOG.rst 2019-09-12
08:34:03.000000000 +0200
@@ -1,3 +1,14 @@
+1.8.0
+=====
+
+* Fixed regression which caused ``TypeError`` or ``OSError`` when trying to
set annotations due to
+ PR #87
+* Fixed unintentional mangling of annotation type names
+* Added proper ``:py:data`` targets for ``NoReturn``, ``ClassVar`` and
``Tuple``
+* Added support for inline type comments (like ``(int, str) -> None``) (PR by
Bernát Gábor)
+* Use the native AST parser for type comment support on Python 3.8+
+
+
1.7.0
=====
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-autodoc-typehints-1.7.0/PKG-INFO
new/sphinx-autodoc-typehints-1.8.0/PKG-INFO
--- old/sphinx-autodoc-typehints-1.7.0/PKG-INFO 2019-07-24 17:21:34.000000000
+0200
+++ new/sphinx-autodoc-typehints-1.8.0/PKG-INFO 2019-09-12 08:34:19.000000000
+0200
@@ -1,13 +1,14 @@
Metadata-Version: 2.1
Name: sphinx-autodoc-typehints
-Version: 1.7.0
+Version: 1.8.0
Summary: Type hints (PEP 484) support for the Sphinx autodoc extension
Home-page: UNKNOWN
Author: Alex Grönholm
Author-email: [email protected]
License: MIT
-Project-URL: Bug Tracker,
https://github.com/agronholm/sphinx-autodoc-typehints/issues
-Project-URL: Source Code, https://github.com/agronholm/sphinx-autodoc-typehints
+Project-URL: Change log,
https://github.com/agronholm/sphinx-autodoc-typehints/blob/master/CHANGELOG.rst
+Project-URL: Source code, https://github.com/agronholm/sphinx-autodoc-typehints
+Project-URL: Issue tracker,
https://github.com/agronholm/sphinx-autodoc-typehints/issues
Description: sphinx-autodoc-typehints
========================
@@ -70,6 +71,9 @@
* ``typehints_fully_qualified`` (default: ``False``): if ``True``,
class names are always fully
qualified (e.g. ``module.for.Class``). If ``False``, just the class
name displays (e.g.
``Class``)
+ * ``always_document_param_types`` (default: ``False``): If ``False``,
do not add type info for
+ undocumented parameters. If ``True``, add stub documentation for
undocumented parameters to
+ be able to add type info.
How it works
@@ -112,15 +116,24 @@
------------------------
If you're documenting code that needs to stay compatible with Python
2.7, you cannot use regular
- type annotations. Instead, you must have typed_ast_ installed and add
type hint comments in the
- following manner:
+ type annotations. Instead, you must either be using Python 3.8 or
later or have typed_ast_
+ installed. The package extras ``type_comments`` will pull in the
appropiate dependencies automatically.
+ Then you can add type hint comments in the following manner:
+
+ .. code-block:: python
+
+ def myfunction(arg1, arg2):
+ # type: (int, str) -> int
+ return 42
+
+ or alternatively:
.. code-block:: python
def myfunction(
arg1, # type: int
arg2 # type: str
- )
+ ):
# type: (...) -> int
return 42
@@ -140,4 +153,5 @@
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.5.2
+Provides-Extra: type_comments
Provides-Extra: test
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-autodoc-typehints-1.7.0/README.rst
new/sphinx-autodoc-typehints-1.8.0/README.rst
--- old/sphinx-autodoc-typehints-1.7.0/README.rst 2019-07-24
17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/README.rst 2019-09-12
08:34:03.000000000 +0200
@@ -60,6 +60,9 @@
* ``typehints_fully_qualified`` (default: ``False``): if ``True``, class names
are always fully
qualified (e.g. ``module.for.Class``). If ``False``, just the class name
displays (e.g.
``Class``)
+* ``always_document_param_types`` (default: ``False``): If ``False``, do not
add type info for
+ undocumented parameters. If ``True``, add stub documentation for
undocumented parameters to
+ be able to add type info.
How it works
@@ -102,15 +105,24 @@
------------------------
If you're documenting code that needs to stay compatible with Python 2.7, you
cannot use regular
-type annotations. Instead, you must have typed_ast_ installed and add type
hint comments in the
-following manner:
+type annotations. Instead, you must either be using Python 3.8 or later or
have typed_ast_
+installed. The package extras ``type_comments`` will pull in the appropiate
dependencies automatically.
+Then you can add type hint comments in the following manner:
+
+.. code-block:: python
+
+ def myfunction(arg1, arg2):
+ # type: (int, str) -> int
+ return 42
+
+or alternatively:
.. code-block:: python
def myfunction(
arg1, # type: int
arg2 # type: str
- )
+ ):
# type: (...) -> int
return 42
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-autodoc-typehints-1.7.0/pyproject.toml
new/sphinx-autodoc-typehints-1.8.0/pyproject.toml
--- old/sphinx-autodoc-typehints-1.7.0/pyproject.toml 2019-07-24
17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/pyproject.toml 2019-09-12
08:34:03.000000000 +0200
@@ -1,2 +1,7 @@
[build-system]
-requires = ["setuptools >= 36.2.7", "wheel", "setuptools_scm >= 1.7.0"]
+requires = [
+ "setuptools >= 40.0.4",
+ "setuptools_scm >= 2.0.0",
+ "wheel >= 0.29.0",
+]
+build-backend = 'setuptools.build_meta'
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-autodoc-typehints-1.7.0/setup.cfg
new/sphinx-autodoc-typehints-1.8.0/setup.cfg
--- old/sphinx-autodoc-typehints-1.7.0/setup.cfg 2019-07-24
17:21:34.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/setup.cfg 2019-09-12
08:34:19.000000000 +0200
@@ -6,8 +6,9 @@
author_email = [email protected]
license = MIT
project_urls =
- Bug Tracker =
https://github.com/agronholm/sphinx-autodoc-typehints/issues
- Source Code = https://github.com/agronholm/sphinx-autodoc-typehints
+ Change log =
https://github.com/agronholm/sphinx-autodoc-typehints/blob/master/CHANGELOG.rst
+ Source code = https://github.com/agronholm/sphinx-autodoc-typehints
+ Issue tracker =
https://github.com/agronholm/sphinx-autodoc-typehints/issues
classifiers =
Development Status :: 5 - Production/Stable
Framework :: Sphinx :: Extension
@@ -31,8 +32,9 @@
test =
pytest >= 3.1.0
typing_extensions >= 3.5
- typed_ast >= 1.4.0
dataclasses; python_version == "3.6"
+type_comments =
+ typed_ast >= 1.4.0; python_version < "3.8"
[flake8]
max-line-length = 99
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-autodoc-typehints-1.7.0/sphinx_autodoc_typehints.egg-info/PKG-INFO
new/sphinx-autodoc-typehints-1.8.0/sphinx_autodoc_typehints.egg-info/PKG-INFO
---
old/sphinx-autodoc-typehints-1.7.0/sphinx_autodoc_typehints.egg-info/PKG-INFO
2019-07-24 17:21:33.000000000 +0200
+++
new/sphinx-autodoc-typehints-1.8.0/sphinx_autodoc_typehints.egg-info/PKG-INFO
2019-09-12 08:34:19.000000000 +0200
@@ -1,13 +1,14 @@
Metadata-Version: 2.1
Name: sphinx-autodoc-typehints
-Version: 1.7.0
+Version: 1.8.0
Summary: Type hints (PEP 484) support for the Sphinx autodoc extension
Home-page: UNKNOWN
Author: Alex Grönholm
Author-email: [email protected]
License: MIT
-Project-URL: Bug Tracker,
https://github.com/agronholm/sphinx-autodoc-typehints/issues
-Project-URL: Source Code, https://github.com/agronholm/sphinx-autodoc-typehints
+Project-URL: Change log,
https://github.com/agronholm/sphinx-autodoc-typehints/blob/master/CHANGELOG.rst
+Project-URL: Source code, https://github.com/agronholm/sphinx-autodoc-typehints
+Project-URL: Issue tracker,
https://github.com/agronholm/sphinx-autodoc-typehints/issues
Description: sphinx-autodoc-typehints
========================
@@ -70,6 +71,9 @@
* ``typehints_fully_qualified`` (default: ``False``): if ``True``,
class names are always fully
qualified (e.g. ``module.for.Class``). If ``False``, just the class
name displays (e.g.
``Class``)
+ * ``always_document_param_types`` (default: ``False``): If ``False``,
do not add type info for
+ undocumented parameters. If ``True``, add stub documentation for
undocumented parameters to
+ be able to add type info.
How it works
@@ -112,15 +116,24 @@
------------------------
If you're documenting code that needs to stay compatible with Python
2.7, you cannot use regular
- type annotations. Instead, you must have typed_ast_ installed and add
type hint comments in the
- following manner:
+ type annotations. Instead, you must either be using Python 3.8 or
later or have typed_ast_
+ installed. The package extras ``type_comments`` will pull in the
appropiate dependencies automatically.
+ Then you can add type hint comments in the following manner:
+
+ .. code-block:: python
+
+ def myfunction(arg1, arg2):
+ # type: (int, str) -> int
+ return 42
+
+ or alternatively:
.. code-block:: python
def myfunction(
arg1, # type: int
arg2 # type: str
- )
+ ):
# type: (...) -> int
return 42
@@ -140,4 +153,5 @@
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.5.2
+Provides-Extra: type_comments
Provides-Extra: test
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-autodoc-typehints-1.7.0/sphinx_autodoc_typehints.egg-info/requires.txt
new/sphinx-autodoc-typehints-1.8.0/sphinx_autodoc_typehints.egg-info/requires.txt
---
old/sphinx-autodoc-typehints-1.7.0/sphinx_autodoc_typehints.egg-info/requires.txt
2019-07-24 17:21:33.000000000 +0200
+++
new/sphinx-autodoc-typehints-1.8.0/sphinx_autodoc_typehints.egg-info/requires.txt
2019-09-12 08:34:19.000000000 +0200
@@ -3,7 +3,11 @@
[test]
pytest>=3.1.0
typing_extensions>=3.5
-typed_ast>=1.4.0
[test:python_version == "3.6"]
dataclasses
+
+[type_comments]
+
+[type_comments:python_version < "3.8"]
+typed_ast>=1.4.0
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-autodoc-typehints-1.7.0/sphinx_autodoc_typehints.py
new/sphinx-autodoc-typehints-1.8.0/sphinx_autodoc_typehints.py
--- old/sphinx-autodoc-typehints-1.7.0/sphinx_autodoc_typehints.py
2019-07-24 17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/sphinx_autodoc_typehints.py
2019-09-12 08:34:03.000000000 +0200
@@ -1,4 +1,5 @@
import inspect
+import sys
import textwrap
import typing
from typing import get_type_hints, TypeVar, Any, AnyStr, Generic, Union
@@ -12,6 +13,8 @@
Protocol = None
logger = logging.getLogger(__name__)
+pydata_annotations = {'Any', 'AnyStr', 'Callable', 'ClassVar', 'NoReturn',
'Optional', 'Tuple',
+ 'Union'}
def format_annotation(annotation, fully_qualified=False):
@@ -22,14 +25,14 @@
return ':py:class:`{}`'.format(annotation.__qualname__)
annotation_cls = annotation if inspect.isclass(annotation) else
type(annotation)
- class_name = None
if annotation_cls.__module__ == 'typing':
+ class_name = str(annotation).split('[')[0].split('.')[-1]
params = None
- prefix = ':py:class:'
module = 'typing'
extra = ''
- if inspect.isclass(getattr(annotation, '__origin__', None)):
+ origin = getattr(annotation, '__origin__', None)
+ if inspect.isclass(origin):
annotation_cls = annotation.__origin__
try:
mro = annotation_cls.mro()
@@ -46,8 +49,6 @@
return '\\%r' % annotation
elif (annotation is Union or getattr(annotation, '__origin__', None)
is Union or
hasattr(annotation, '__union_params__')):
- prefix = ':py:data:'
- class_name = 'Union'
if hasattr(annotation, '__union_params__'):
params = annotation.__union_params__
elif hasattr(annotation, '__args__'):
@@ -62,7 +63,6 @@
if annotation.__tuple_use_ellipsis__:
params += (Ellipsis,)
elif annotation_cls.__qualname__ == 'Callable':
- prefix = ':py:data:'
arg_annotations = result_annotation = None
if hasattr(annotation, '__result__'):
arg_annotations = annotation.__args__
@@ -81,6 +81,9 @@
for param in arg_annotations)),
result_annotation
]
+ elif str(annotation).startswith('typing.ClassVar[') and
hasattr(annotation, '__type__'):
+ # < py3.7
+ params = (annotation.__type__,)
elif hasattr(annotation, 'type_var'):
# Type alias
class_name = annotation.name
@@ -94,11 +97,8 @@
extra = '\\[{}]'.format(', '.join(
format_annotation(param, fully_qualified) for param in params))
- if not class_name:
- class_name = annotation_cls.__qualname__.title()
-
return '{prefix}`{qualify}{module}.{name}`{extra}'.format(
- prefix=prefix,
+ prefix=':py:data:' if class_name in pydata_annotations else
':py:class:',
qualify="" if fully_qualified else "~",
module=module,
name=class_name,
@@ -191,8 +191,9 @@
try:
rv = get_type_hints(obj)
- except (AttributeError, TypeError):
- # Introspecting a slot wrapper will raise TypeError
+ except (AttributeError, TypeError, RecursionError):
+ # Introspecting a slot wrapper will raise TypeError, and and some
recursive type
+ # definitions will cause a RecursionError
(https://github.com/python/typing/issues/574).
pass
except NameError as exc:
logger.warning('Cannot resolve forward reference in type annotations
of "%s": %s',
@@ -206,7 +207,7 @@
try:
obj.__annotations__ = rv
- except AttributeError:
+ except (AttributeError, TypeError):
return rv
try:
@@ -222,15 +223,18 @@
def backfill_type_hints(obj, name):
- rv = {}
-
- try:
- import typed_ast.ast3 as ast
- except ImportError:
- return rv
+ parse_kwargs = {}
+ if sys.version_info < (3, 8):
+ try:
+ import typed_ast.ast3 as ast
+ except ImportError:
+ return {}
+ else:
+ import ast
+ parse_kwargs = {'type_comments': True}
def _one_child(module):
- children = list(ast.iter_child_nodes(module))
+ children = module.body # use the body to ignore type comments
if len(children) != 1:
logger.warning(
@@ -240,57 +244,100 @@
return children[0]
try:
- obj_ast = ast.parse(textwrap.dedent(inspect.getsource(obj)))
+ obj_ast = ast.parse(textwrap.dedent(inspect.getsource(obj)),
**parse_kwargs)
except TypeError:
- return rv
+ return {}
obj_ast = _one_child(obj_ast)
if obj_ast is None:
- return rv
+ return {}
try:
type_comment = obj_ast.type_comment
except AttributeError:
- return rv
+ return {}
if not type_comment:
- return rv
+ return {}
try:
comment_args_str, comment_returns = type_comment.split(' -> ')
except ValueError:
logger.warning('Unparseable type hint comment for "%s": Expected to
contain ` -> `', name)
- return rv
+ return {}
+ rv = {}
if comment_returns:
rv['return'] = comment_returns
- if comment_args_str not in ('()', '(...)'):
- logger.warning(
- 'Only supporting `type: (...) -> rv`-style type hint comments, '
- 'skipping types for "%s"', name
- )
- return rv
-
- try:
- args = list(ast.iter_child_nodes(obj_ast.args))
- except AttributeError:
- logger.warning('No args found on "%s"', name)
- return rv
-
- for arg in args:
- comment = getattr(arg, 'type_comment', None)
- if not comment:
+ args = load_args(obj_ast)
+ comment_args = split_type_comment_args(comment_args_str)
+ is_inline = len(comment_args) == 1 and comment_args[0] == "..."
+ if not is_inline:
+ if args and args[0].arg in ("self", "cls") and len(comment_args) !=
len(args):
+ comment_args.insert(0, None) # self/cls may be omitted in type
comments, insert blank
+
+ if len(args) != len(comment_args):
+ logger.warning('Not enough type comments found on "%s"', name)
+ return rv
+
+ for at, arg in enumerate(args):
+ arg_key = getattr(arg, "arg", None)
+ if arg_key is None:
continue
- if not hasattr(arg, 'arg'):
- continue
+ if is_inline: # the type information now is tied to the argument
+ value = getattr(arg, "type_comment", None)
+ else: # type data from comment
+ value = comment_args[at]
- rv[arg.arg] = comment
+ if value is not None:
+ rv[arg_key] = value
return rv
+def load_args(obj_ast):
+ func_args = obj_ast.args
+ args = []
+ pos_only = getattr(func_args, 'posonlyargs', None)
+ if pos_only:
+ args.extend(pos_only)
+
+ args.extend(func_args.args)
+ if func_args.vararg:
+ args.append(func_args.vararg)
+
+ args.extend(func_args.kwonlyargs)
+ if func_args.kwarg:
+ args.append(func_args.kwarg)
+
+ return args
+
+
+def split_type_comment_args(comment):
+ def add(val):
+ result.append(val.strip().lstrip("*")) # remove spaces, and var/kw
arg marker
+
+ comment = comment.strip().lstrip("(").rstrip(")")
+ result = []
+ if not comment:
+ return result
+
+ brackets, start_arg_at, at = 0, 0, 0
+ for at, char in enumerate(comment):
+ if char in ("[", "("):
+ brackets += 1
+ elif char in ("]", ")"):
+ brackets -= 1
+ elif char == "," and brackets == 0:
+ add(comment[start_arg_at:at])
+ start_arg_at = at + 1
+
+ add(comment[start_arg_at: at + 1])
+ return result
+
+
def process_docstring(app, what, name, obj, options, lines):
if isinstance(obj, property):
obj = obj.fget
@@ -303,39 +350,52 @@
type_hints = get_all_type_hints(obj, name)
for argname, annotation in type_hints.items():
+ if argname == 'return':
+ continue # this is handled separately later
if argname.endswith('_'):
argname = '{}\\_'.format(argname[:-1])
formatted_annotation = format_annotation(
annotation,
fully_qualified=app.config.typehints_fully_qualified)
- if argname == 'return':
- if what in ('class', 'exception'):
- # Don't add return type None from __init__()
- continue
+ searchfor = ':param {}:'.format(argname)
+ insert_index = None
+ for i, line in enumerate(lines):
+ if line.startswith(searchfor):
+ insert_index = i
+ break
+
+ if insert_index is None and app.config.always_document_param_types:
+ lines.append(searchfor)
insert_index = len(lines)
- for i, line in enumerate(lines):
- if line.startswith(':rtype:'):
- insert_index = None
- break
- elif line.startswith(':return:') or
line.startswith(':returns:'):
- insert_index = i
-
- if insert_index is not None:
- if insert_index == len(lines):
- # Ensure that :rtype: doesn't get joined with a
paragraph of text, which
- # prevents it being interpreted.
- lines.append('')
- insert_index += 1
-
- lines.insert(insert_index, ':rtype:
{}'.format(formatted_annotation))
- else:
- searchfor = ':param {}:'.format(argname)
- for i, line in enumerate(lines):
- if line.startswith(searchfor):
- lines.insert(i, ':type {}: {}'.format(argname,
formatted_annotation))
- break
+
+ if insert_index is not None:
+ lines.insert(
+ insert_index,
+ ':type {}: {}'.format(argname, formatted_annotation)
+ )
+
+ if 'return' in type_hints and what not in ('class', 'exception'):
+ formatted_annotation = format_annotation(
+ type_hints['return'],
fully_qualified=app.config.typehints_fully_qualified)
+
+ insert_index = len(lines)
+ for i, line in enumerate(lines):
+ if line.startswith(':rtype:'):
+ insert_index = None
+ break
+ elif line.startswith(':return:') or
line.startswith(':returns:'):
+ insert_index = i
+
+ if insert_index is not None:
+ if insert_index == len(lines):
+ # Ensure that :rtype: doesn't get joined with a paragraph
of text, which
+ # prevents it being interpreted.
+ lines.append('')
+ insert_index += 1
+
+ lines.insert(insert_index, ':rtype:
{}'.format(formatted_annotation))
def builder_ready(app):
@@ -345,6 +405,7 @@
def setup(app):
app.add_config_value('set_type_checking_flag', False, 'html')
+ app.add_config_value('always_document_param_types', False, 'html')
app.add_config_value('typehints_fully_qualified', False, 'env')
app.connect('builder-inited', builder_ready)
app.connect('autodoc-process-signature', process_signature)
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-autodoc-typehints-1.7.0/tests/conftest.py
new/sphinx-autodoc-typehints-1.8.0/tests/conftest.py
--- old/sphinx-autodoc-typehints-1.7.0/tests/conftest.py 2019-07-24
17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/tests/conftest.py 2019-09-12
08:34:03.000000000 +0200
@@ -9,7 +9,7 @@
collect_ignore = ['roots']
[email protected](scope='session', autouse=True)
[email protected](autouse=True)
def remove_sphinx_projects(sphinx_test_tempdir):
# Remove any directory which appears to be a Sphinx project from
# the temporary directory area.
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-autodoc-typehints-1.7.0/tests/roots/test-dummy/dummy_module.py
new/sphinx-autodoc-typehints-1.8.0/tests/roots/test-dummy/dummy_module.py
--- old/sphinx-autodoc-typehints-1.7.0/tests/roots/test-dummy/dummy_module.py
2019-07-24 17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/tests/roots/test-dummy/dummy_module.py
2019-09-12 08:34:03.000000000 +0200
@@ -1,4 +1,5 @@
import typing
+from typing import Callable, Union
try:
from dataclasses import dataclass
@@ -136,7 +137,7 @@
"""
-def function_with_unresolvable_annotation(x: 'a.b.c'):
+def function_with_unresolvable_annotation(x: 'a.b.c'): # noqa: F821
"""
Function docstring.
@@ -144,7 +145,6 @@
"""
-
def function_with_typehint_comment(
x, # type: int
y # type: str
@@ -185,6 +185,55 @@
return 42
+def function_with_typehint_comment_not_inline(x=None, *y, z, **kwargs):
+ # type: (Union[str, bytes], *str, bytes, **int) -> None
+ """
+ Function docstring.
+
+ :param x: foo
+ :param y: bar
+ :param z: baz
+ :param kwargs: some kwargs
+ """
+
+
+class ClassWithTypehintsNotInline(object):
+ """
+ Class docstring.
+
+ :param x: foo
+ """
+
+ def __init__(self, x=None):
+ # type: (Callable[[int, bytes], int]) -> None
+ pass
+
+ def foo(self, x=1):
+ # type: (Callable[[int, bytes], int]) -> int
+ """
+ Method docstring.
+
+ :param x: foo
+ """
+ return x(1, b'')
+
+ @classmethod
+ def mk(cls, x=None):
+ # type: (Callable[[int, bytes], int]) -> ClassWithTypehintsNotInline
+ """
+ Method docstring.
+
+ :param x: foo
+ """
+ return cls(x)
+
+
+def undocumented_function(x: int) -> str:
+ """Hi"""
+
+ return str(x)
+
+
@dataclass
class DataClass:
"""Class docstring."""
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-autodoc-typehints-1.7.0/tests/roots/test-dummy/index.rst
new/sphinx-autodoc-typehints-1.8.0/tests/roots/test-dummy/index.rst
--- old/sphinx-autodoc-typehints-1.7.0/tests/roots/test-dummy/index.rst
2019-07-24 17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/tests/roots/test-dummy/index.rst
2019-09-12 08:34:03.000000000 +0200
@@ -22,6 +22,13 @@
.. autoclass:: dummy_module.ClassWithTypehints
:members:
+.. autofunction:: dummy_module.function_with_typehint_comment_not_inline
+
+.. autoclass:: dummy_module.ClassWithTypehintsNotInline
+ :members:
+
+.. autofunction:: dummy_module.undocumented_function
+
.. autoclass:: dummy_module.DataClass
:undoc-members:
:special-members: __init__
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-autodoc-typehints-1.7.0/tests/test_sphinx_autodoc_typehints.py
new/sphinx-autodoc-typehints-1.8.0/tests/test_sphinx_autodoc_typehints.py
--- old/sphinx-autodoc-typehints-1.7.0/tests/test_sphinx_autodoc_typehints.py
2019-07-24 17:20:30.000000000 +0200
+++ new/sphinx-autodoc-typehints-1.8.0/tests/test_sphinx_autodoc_typehints.py
2019-09-12 08:34:03.000000000 +0200
@@ -10,6 +10,16 @@
from sphinx_autodoc_typehints import format_annotation, process_docstring
+try:
+ from typing import ClassVar # not available prior to Python 3.5.3
+except ImportError:
+ ClassVar = None
+
+try:
+ from typing import NoReturn # not available prior to Python 3.6.5
+except ImportError:
+ NoReturn = None
+
T = TypeVar('T')
U = TypeVar('U', covariant=True)
V = TypeVar('V', contravariant=True)
@@ -45,6 +55,12 @@
(str, ':py:class:`str`'),
(int, ':py:class:`int`'),
(type(None), '``None``'),
+ pytest.param(NoReturn, ':py:data:`~typing.NoReturn`',
+ marks=[pytest.mark.skipif(NoReturn is None,
+ reason='typing.NoReturn is not
available')]),
+ pytest.param(ClassVar[str],
':py:data:`~typing.ClassVar`\\[:py:class:`str`]',
+ marks=[pytest.mark.skipif(ClassVar is None,
+ reason='typing.ClassVar is not
available')]),
(Any, ':py:data:`~typing.Any`'),
(AnyStr, ':py:data:`~typing.AnyStr`'),
(Generic[T], ':py:class:`~typing.Generic`\\[\\~T]'),
@@ -60,12 +76,12 @@
(Dict[T, U], ':py:class:`~typing.Dict`\\[\\~T, \\+U]'),
(Dict[str, bool],
':py:class:`~typing.Dict`\\[:py:class:`str`, '
':py:class:`bool`]'),
- (Tuple, ':py:class:`~typing.Tuple`'),
- (Tuple[str, bool],
':py:class:`~typing.Tuple`\\[:py:class:`str`, '
+ (Tuple, ':py:data:`~typing.Tuple`'),
+ (Tuple[str, bool],
':py:data:`~typing.Tuple`\\[:py:class:`str`, '
':py:class:`bool`]'),
- (Tuple[int, int, int],
':py:class:`~typing.Tuple`\\[:py:class:`int`, '
+ (Tuple[int, int, int],
':py:data:`~typing.Tuple`\\[:py:class:`int`, '
':py:class:`int`, :py:class:`int`]'),
- (Tuple[str, ...],
':py:class:`~typing.Tuple`\\[:py:class:`str`, ...]'),
+ (Tuple[str, ...],
':py:data:`~typing.Tuple`\\[:py:class:`str`, ...]'),
(Union, ':py:data:`~typing.Union`'),
(Union[str, bool],
':py:data:`~typing.Union`\\[:py:class:`str`, '
':py:class:`bool`]'),
@@ -103,6 +119,12 @@
(str, ':py:class:`str`'),
(int, ':py:class:`int`'),
(type(None), '``None``'),
+ pytest.param(NoReturn, ':py:data:`typing.NoReturn`',
+ marks=[pytest.mark.skipif(NoReturn is None,
+ reason='typing.NoReturn is not
available')]),
+ pytest.param(ClassVar[str],
':py:data:`typing.ClassVar`\\[:py:class:`str`]',
+ marks=[pytest.mark.skipif(ClassVar is None,
+ reason='typing.ClassVar is not
available')]),
(Any, ':py:data:`typing.Any`'),
(AnyStr, ':py:data:`typing.AnyStr`'),
(Generic[T], ':py:class:`typing.Generic`\\[\\~T]'),
@@ -118,12 +140,12 @@
(Dict[T, U], ':py:class:`typing.Dict`\\[\\~T, \\+U]'),
(Dict[str, bool],
':py:class:`typing.Dict`\\[:py:class:`str`, '
':py:class:`bool`]'),
- (Tuple, ':py:class:`typing.Tuple`'),
- (Tuple[str, bool],
':py:class:`typing.Tuple`\\[:py:class:`str`, '
+ (Tuple, ':py:data:`typing.Tuple`'),
+ (Tuple[str, bool],
':py:data:`typing.Tuple`\\[:py:class:`str`, '
':py:class:`bool`]'),
- (Tuple[int, int, int],
':py:class:`typing.Tuple`\\[:py:class:`int`, '
+ (Tuple[int, int, int],
':py:data:`typing.Tuple`\\[:py:class:`int`, '
':py:class:`int`, :py:class:`int`]'),
- (Tuple[str, ...],
':py:class:`typing.Tuple`\\[:py:class:`str`, ...]'),
+ (Tuple[str, ...],
':py:data:`typing.Tuple`\\[:py:class:`str`, ...]'),
(Union, ':py:data:`typing.Union`'),
(Union[str, bool],
':py:data:`typing.Union`\\[:py:class:`str`, '
':py:class:`bool`]'),
@@ -169,21 +191,32 @@
assert not lines
[email protected]('always_document_param_types', [True, False])
@pytest.mark.sphinx('text', testroot='dummy')
-def test_sphinx_output(app, status, warning):
+def test_sphinx_output(app, status, warning, always_document_param_types):
test_path = pathlib.Path(__file__).parent
# Add test directory to sys.path to allow imports of dummy module.
if str(test_path) not in sys.path:
sys.path.insert(0, str(test_path))
+ app.config.always_document_param_types = always_document_param_types
app.build()
assert 'build succeeded' in status.getvalue() # Build succeeded
# There should be a warning about an unresolved forward reference
warnings = warning.getvalue().strip()
- assert 'Cannot resolve forward reference in type annotations of ' in
warnings
+ assert 'Cannot resolve forward reference in type annotations of ' in
warnings, warnings
+
+ if always_document_param_types:
+ undoc_params = '''
+
+ Parameters:
+ **x** ("int") --'''
+
+ else:
+ undoc_params = ""
text_path = pathlib.Path(app.srcdir) / '_build' / 'text' / 'index.txt'
with text_path.open('r') as f:
@@ -380,12 +413,63 @@
Return type:
"int"
+ dummy_module.function_with_typehint_comment_not_inline(x=None, *y, z,
**kwargs)
+
+ Function docstring.
+
+ Parameters:
+ * **x** ("Union"["str", "bytes", "None"]) -- foo
+
+ * **y** ("str") -- bar
+
+ * **z** ("bytes") -- baz
+
+ * **kwargs** ("int") -- some kwargs
+
+ Return type:
+ "None"
+
+ class dummy_module.ClassWithTypehintsNotInline(x=None)
+
+ Class docstring.
+
+ Parameters:
+ **x** ("Optional"["Callable"[["int", "bytes"], "int"]]) -- foo
+
+ foo(x=1)
+
+ Method docstring.
+
+ Parameters:
+ **x** ("Callable"[["int", "bytes"], "int"]) -- foo
+
+ Return type:
+ "int"
+
+ classmethod mk(x=None)
+
+ Method docstring.
+
+ Parameters:
+ **x** (*Callable**[**[**int**, **bytes**]**, **int**]*) --
+ foo
+
+ Return type:
+ ClassWithTypehintsNotInline
+
+ dummy_module.undocumented_function(x)
+
+ Hi{undoc_params}
+
+ Return type:
+ "str"
+
class dummy_module.DataClass
Class docstring.
__init__()
- ''').replace('–', '--')
+ '''.format(undoc_params=undoc_params)).replace('–', '--')
if sys.version_info < (3, 6):
expected_contents += '''
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-autodoc-typehints-1.7.0/tox.ini
new/sphinx-autodoc-typehints-1.8.0/tox.ini
--- old/sphinx-autodoc-typehints-1.7.0/tox.ini 2019-07-24 17:20:30.000000000
+0200
+++ new/sphinx-autodoc-typehints-1.8.0/tox.ini 2019-09-12 08:34:03.000000000
+0200
@@ -1,13 +1,14 @@
[tox]
-minversion = 2.5.0
+minversion = 3.3.0
envlist = py35, py36, py37, py38, flake8
skip_missing_interpreters = true
+isolated_build = true
[testenv]
-extras = test
+extras = test, type_comments
commands = python -m pytest {posargs}
[testenv:flake8]
deps = flake8
-commands = flake8 sphinx_autodoc_typehints.py
tests/test_sphinx_autodoc_typehints.py
+commands = flake8 sphinx_autodoc_typehints.py tests
skip_install = true
