From 8893976df18349af79bde446656f58f850772fc7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niko=20F=C3=B6hr?= Date: Thu, 15 Feb 2024 00:29:58 +0200 Subject: [PATCH 1/4] fix 'Alias for field number X' problem with NamedTuples --- numpydoc/docscrape.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 4fbbe63c..fb3a0b63 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -706,6 +706,7 @@ def properties(self): for name, func in inspect.getmembers(self._cls) if ( not name.startswith("_") + and not self._should_skip_member(name, self._cls) and ( func is None or isinstance(func, (property, cached_property)) @@ -715,6 +716,19 @@ def properties(self): ) ] + @staticmethod + def _should_skip_member(name, klass): + if ( + # Namedtuples should skip everything in their ._fields as the + # docstrings for each of the members is: "Alias for field number X" + issubclass(klass, tuple) + and hasattr(klass, "_asdict") + and hasattr(klass, "_fields") + and name in klass._fields + ): + return True + return False + def _is_show_member(self, name): if self.show_inherited_members: return True # show all class members From 67f6b4cc99791387b53a340a6397289d8d6b8f57 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 Feb 2024 22:14:06 -0800 Subject: [PATCH 2/4] TST: Add test for duplicated attrs w/ namedtuples. --- numpydoc/tests/test_docscrape.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 5077c425..9fce09c5 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -1641,6 +1641,21 @@ def val(self): assert class_docstring["Attributes"][0].name == "val" +def test_named_tuple_no_duplicate_attributes(): + """ + Ensure that attributes of namedtuples are not duplicated in the docstring. + + See gh-257 + """ + from collections import namedtuple + + foo = namedtuple("Foo", ("bar", "baz")) + + # Create the SphinxClassDoc object via get_doc_object + sds = get_doc_object(foo) + assert sds["Attributes"] == [] + + if __name__ == "__main__": import pytest From 1fad9fb9637a8c4eec0f5560f2186e8180b658b0 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Fri, 16 Feb 2024 12:11:11 -0800 Subject: [PATCH 3/4] TST: Add test of explicitly documented namedtuple params. --- numpydoc/tests/test_docscrape.py | 42 +++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 9fce09c5..7a71414a 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -1641,7 +1641,7 @@ def val(self): assert class_docstring["Attributes"][0].name == "val" -def test_named_tuple_no_duplicate_attributes(): +def test_namedtuple_no_duplicate_attributes(): """ Ensure that attributes of namedtuples are not duplicated in the docstring. @@ -1656,6 +1656,46 @@ def test_named_tuple_no_duplicate_attributes(): assert sds["Attributes"] == [] +def test_namedtuple_class_docstring(): + """Ensure that class docstring is preserved when inheriting from namedtuple. + + See gh-257 + """ + from collections import namedtuple + + foo = namedtuple("Foo", ("bar", "baz")) + + class MyFoo(foo): + """MyFoo's class docstring""" + + # Create the SphinxClassDoc object via get_doc_object + sds = get_doc_object(MyFoo) + assert sds["Summary"] == ["MyFoo's class docstring"] + + # Example dataclass where constructor params are documented explicit. + # Parameter names/descriptions should be included in the docstring, but + # should not result in a duplicated `Attributes` section + class MyFooWithParams(foo): + """ + MyFoo's class docstring + + Parameters + ---------- + bar : str + The bar attribute + baz : str + The baz attribute + """ + + bar: str + baz: str + + sds = get_doc_object(MyFooWithParams) + assert "MyFoo's class docstring" in sds["Summary"] + assert len(sds["Attributes"]) == 0 + assert len(sds["Parameters"]) == 2 + + if __name__ == "__main__": import pytest From 6d67dc617c7f71fa6f4d00979ae1c73faa981b3f Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Mon, 19 Feb 2024 21:24:58 -0800 Subject: [PATCH 4/4] TST: Make test for namedtuple params more specific. --- numpydoc/tests/test_docscrape.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 7a71414a..8bbcdc53 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -1694,6 +1694,8 @@ class MyFooWithParams(foo): assert "MyFoo's class docstring" in sds["Summary"] assert len(sds["Attributes"]) == 0 assert len(sds["Parameters"]) == 2 + assert sds["Parameters"][0].desc[0] == "The bar attribute" + assert sds["Parameters"][1].desc[0] == "The baz attribute" if __name__ == "__main__":