IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Support type comments in `PropertyDocumenter` (#11298)

Browse Source
This commit is contained in:
picnixz 2023-04-06 23:56:17 +02:00 committed by GitHub
parent 26eb2ef7c4
commit aba392d87f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 115 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGES
View File

@ -27,6 +27,8 @@ Deprecated
Features added
--------------
* #11277: :rst:dir:`autoproperty` allows the return type to be specified as
a type comment (e.g., ``# type: () -> int``). Patch by Bénédikt Tran
* #10811: Autosummary: extend ``__all__`` to imported members for template rendering
when option ``autosummary_ignore_module_all`` is set to ``False``. Patch by
Clement Pinard

59
sphinx/ext/autodoc/__init__.py
View File

@ -2706,6 +2706,16 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): #
self.isclassmethod = False
return ret
def format_args(self, **kwargs: Any) -> str | None:
func = self._get_property_getter()
if func is None:
return None
# update the annotations of the property getter
self.env.app.emit('autodoc-before-process-signature', func, False)
# correctly format the arguments for a property
return super().format_args(**kwargs)
def document_members(self, all_members: bool = False) -> None:
pass
@ -2721,30 +2731,33 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): #
if self.isclassmethod:
self.add_line(' :classmethod:', sourcename)
if safe_getattr(self.object, 'fget', None): # property
func = self.object.fget
elif safe_getattr(self.object, 'func', None): # cached_property
func = self.object.func
else:
func = None
func = self._get_property_getter()
if func is None or self.config.autodoc_typehints == 'none':
return
if func and self.config.autodoc_typehints != 'none':
try:
signature = inspect.signature(func,
type_aliases=self.config.autodoc_type_aliases)
if signature.return_annotation is not Parameter.empty:
if self.config.autodoc_typehints_format == "short":
objrepr = stringify_annotation(signature.return_annotation, "smart")
else:
objrepr = stringify_annotation(signature.return_annotation,
"fully-qualified-except-typing")
self.add_line(' :type: ' + objrepr, sourcename)
except TypeError as exc:
logger.warning(__("Failed to get a function signature for %s: %s"),
self.fullname, exc)
pass
except ValueError:
pass
try:
signature = inspect.signature(func,
type_aliases=self.config.autodoc_type_aliases)
if signature.return_annotation is not Parameter.empty:
if self.config.autodoc_typehints_format == "short":
objrepr = stringify_annotation(signature.return_annotation, "smart")
else:
objrepr = stringify_annotation(signature.return_annotation,
"fully-qualified-except-typing")
self.add_line(' :type: ' + objrepr, sourcename)
except TypeError as exc:
logger.warning(__("Failed to get a function signature for %s: %s"),
self.fullname, exc)
pass
except ValueError:
pass
def _get_property_getter(self):
if safe_getattr(self.object, 'fget', None): # property
return self.object.fget
if safe_getattr(self.object, 'func', None): # cached_property
return self.object.func
return None
def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:

5
tests/roots/test-ext-autodoc/target/cached_property.py
View File

@ -5,3 +5,8 @@ class Foo:
@cached_property
def prop(self) -> int:
return 1
@cached_property
def prop_with_type_comment(self):
# type: () -> int
return 1

11
tests/roots/test-ext-autodoc/target/properties.py
View File

@ -9,3 +9,14 @@ class Foo:
@property
def prop2(self) -> int:
"""docstring"""
@property
def prop1_with_type_comment(self):
# type: () -> int
"""docstring"""
@classmethod
@property
def prop2_with_type_comment(self):
# type: () -> int
"""docstring"""

5
tests/test_ext_autodoc.py
View File

@ -1089,6 +1089,11 @@ def test_autodoc_cached_property(app):
' :module: target.cached_property',
' :type: int',
'',
'',
' .. py:property:: Foo.prop_with_type_comment',
' :module: target.cached_property',
' :type: int',
'',
]

15
tests/test_ext_autodoc_autoclass.py
View File

@ -213,6 +213,13 @@ def test_properties(app):
' docstring',
'',
'',
' .. py:property:: Foo.prop1_with_type_comment',
' :module: target.properties',
' :type: int',
'',
' docstring',
'',
'',
' .. py:property:: Foo.prop2',
' :module: target.properties',
' :classmethod:',
@ -220,6 +227,14 @@ def test_properties(app):
'',
' docstring',
'',
'',
' .. py:property:: Foo.prop2_with_type_comment',
' :module: target.properties',
' :classmethod:',
' :type: int',
'',
' docstring',
'',
]

41
tests/test_ext_autodoc_autoproperty.py
View File

@ -38,6 +38,35 @@ def test_class_properties(app):
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_properties_with_type_comment(app):
actual = do_autodoc(app, 'property', 'target.properties.Foo.prop1_with_type_comment')
assert list(actual) == [
'',
'.. py:property:: Foo.prop1_with_type_comment',
' :module: target.properties',
' :type: int',
'',
' docstring',
'',
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_class_properties_with_type_comment(app):
actual = do_autodoc(app, 'property', 'target.properties.Foo.prop2_with_type_comment')
assert list(actual) == [
'',
'.. py:property:: Foo.prop2_with_type_comment',
' :module: target.properties',
' :classmethod:',
' :type: int',
'',
' docstring',
'',
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_cached_properties(app):
actual = do_autodoc(app, 'property', 'target.cached_property.Foo.prop')
@ -48,3 +77,15 @@ def test_cached_properties(app):
' :type: int',
'',
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_cached_properties_with_type_comment(app):
actual = do_autodoc(app, 'property', 'target.cached_property.Foo.prop_with_type_comment')
assert list(actual) == [
'',
'.. py:property:: Foo.prop_with_type_comment',
' :module: target.cached_property',
' :type: int',
'',
]