Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Autosummary additional links for inherited methods and attributes #11712

Open
wants to merge 44 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
e62a37c
Add links for inherited methods and attributes
satr-cowi Aug 22, 2023
4e71d5b
Docs update for additional autosummary inherited options
satr-cowi Oct 6, 2023
6a2b58a
Merge branch 'sphinx-doc:master' into Autosummary_additional_links_fo…
satr-cowi Oct 6, 2023
2f4d125
Formatting update for linter
satr-cowi Oct 6, 2023
bee1d6b
Review comment changes
satr-cowi Oct 9, 2023
4302a97
Autosummary documentation improvements
satr-cowi Oct 9, 2023
092f706
Docs linter updates
satr-cowi Oct 9, 2023
063d33f
Update autosummary.rst
satr-cowi Oct 9, 2023
b8dff3f
Change inherited_members into ordered list
satr-cowi Oct 9, 2023
697be33
Added unittest to existing tests for inherited methods and attributes
satr-cowi Oct 9, 2023
76c0194
Merge branch 'Autosummary_additional_links_for_inherited_methods_and_…
satr-cowi Oct 9, 2023
192ad95
lint formatting
satr-cowi Oct 9, 2023
e9edee7
Removed use of __dict__
satr-cowi Oct 9, 2023
b7a0049
Test shouldn't depend on Python version or os. Includes attributes in…
satr-cowi Oct 9, 2023
0901005
docs updated
satr-cowi Oct 9, 2023
de412e0
Linting corrections
satr-cowi Oct 9, 2023
4f3aa01
correction
satr-cowi Oct 9, 2023
8e62aed
another linting correction
satr-cowi Oct 9, 2023
71c1729
Refactor to minimise _get_class_members calls
satr-cowi Oct 13, 2023
89adbd9
Merge branch 'sphinx-doc:master' into Autosummary_additional_links_fo…
satr-cowi Nov 30, 2023
2d56014
Merge remote-tracking branch 'upstream/master' into Autosummary_addit…
satr-cowi Jan 10, 2024
bff342f
Merge remote-tracking branch 'upstream/master' into Autosummary_addit…
satr-cowi Feb 5, 2024
13895a9
Merge branch 'master' into Autosummary_additional_links_for_inherited…
satr-cowi Feb 15, 2024
7f06fcb
Merge branch 'master' into Autosummary_additional_links_for_inherited…
satr-cowi Mar 28, 2024
8ea3cba
Merge branch 'master' into Autosummary_additional_links_for_inherited…
satr-cowi Jun 13, 2024
219cc23
Merge remote-tracking branch 'upstream/master' into Autosummary_addit…
satr-cowi Sep 23, 2024
3199fe0
ruff format
satr-cowi Sep 25, 2024
9884579
Only return the first instance of inheritance
satr-cowi Sep 25, 2024
5421b26
Additional tests for more conditions
satr-cowi Sep 25, 2024
a34b648
Clarification on members including private and template example
satr-cowi Sep 25, 2024
6f3fbc3
ruff format
satr-cowi Sep 25, 2024
9037a22
lint corrections
satr-cowi Sep 25, 2024
224076b
Merge branch 'master' into Autosummary_additional_links_for_inherited…
satr-cowi Sep 25, 2024
065a1a0
Merge branch 'master' into Autosummary_additional_links_for_inherited…
satr-cowi Oct 28, 2024
58ff1e3
add in version dependent attributes
satr-cowi Oct 29, 2024
3c9b0bb
ruff
satr-cowi Oct 29, 2024
336d3e3
update for 3_11 and remove extra term
satr-cowi Oct 29, 2024
ceb2b99
add in members too
satr-cowi Oct 29, 2024
479ff7d
Simplify way to add new builtin members
satr-cowi Oct 29, 2024
4987598
tweak for 3_14 test
satr-cowi Oct 29, 2024
a3adf19
fix 3_14
satr-cowi Oct 29, 2024
d6abcbe
correct order of members2
satr-cowi Oct 29, 2024
73827e2
Improved comment
satr-cowi Oct 29, 2024
242f21a
Improved docstring for inherited_qualnames
satr-cowi Oct 29, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions doc/usage/extensions/autosummary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,27 @@ The following variables are available in the templates:

.. versionadded:: 1.8.0

.. data:: inherited_methods

List containing names of only inherited methods. Only available for
classes.

.. versionadded:: 7.2.7
picnixz marked this conversation as resolved.
Show resolved Hide resolved

.. data:: inherited_attributes

List containing names of only inherited attributes. Only available for
classes.

.. versionadded:: 7.2.7

.. data:: inherited_paths
satr-cowi marked this conversation as resolved.
Show resolved Hide resolved

List containing the full path inherited members. Will only return the closest
picnixz marked this conversation as resolved.
Show resolved Hide resolved
parent from which this class was inherited. Only available for classes.

.. versionadded:: 7.2.7

.. data:: functions

List containing names of "public" functions in the module. Here, "public"
Expand Down
23 changes: 23 additions & 0 deletions sphinx/ext/autosummary/generate.py
Original file line number Diff line number Diff line change
Expand Up @@ -320,11 +320,34 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
ns['members'] = dir(obj)
ns['inherited_members'] = \
set(dir(obj)) - set(obj.__dict__.keys())

ns['methods'], ns['all_methods'] = \
_get_members(doc, app, obj, {'method'}, include_public={'__init__'})
ns['attributes'], ns['all_attributes'] = \
_get_members(doc, app, obj, {'attribute', 'property'})

method_string = [m.split(".")[-1] for m in ns['methods']]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps it's better to have use ns['all_methods'] since otherwise you'll only include public ones.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@satr-cowi Have you addressed this issue?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think my preference is for ns['inherited_methods'] would be to only return the public methods (and therefore be consistent with ns['methods'])

We could introduce ns['all_inherited_methods'] as well, but the documentation doesn't include anything about ns['all_methods'] at the moment so we should probably include that too if we do this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, I want us to be consistent without breaking previous changes.

AFAIU the current behaviour is "ns[C] returns public members for category C" and "ns[all_C] returns all members for category C (including private ones)". I don't mind not documenting "all_*" for now, but I would like the documentation for ns["members"] & co. to be updated then. Currently it says (for "members"):

List containing names of all members of the module or class. Only available
for modules and classes.

In addition, your "inherited_qualnames" documentation tells me about:

  • members returns a list with many built in methods/attributes and
    ['__init__', '_i_am_private', 'do_something', 'do_something_else', 'foo_attr']

So now your members also include private members.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Current behaviour (as in the example) is:

  • methods and attributes returns just public methods/attributes
  • members and inherited members return all members including private
  • all_methods and all_attributes returns all methods/attributes including private, but these are not documented so most users won't know they exist

I've updated the "members" documentation to make it clear that this and "inherited members" do include private members. It was already clear that methods/attributes were only public.

The proposed additions are just that:

  • inherited_methods and inherited_attributes returns just public inherited methods/attributes
  • inherited_qualnames is the same as inherited_members (includes private), but just with the fully qualified names

Think this is pretty clear from the documentation now

attr_string = [m.split(".")[-1] for m in ns['attributes']]

# Find the first link for this attribute in higher classes
ns['inherited_paths'] = []
ns['inherited_methods'] = []
ns['inherited_attributes'] = []

for i in (set(dir(obj)) - set(obj.__dict__.keys())):
picnixz marked this conversation as resolved.
Show resolved Hide resolved
for cl in obj.__mro__:
local = set(cl.__dict__.keys())
if i in local:
cl_str = cl.__module__ + "." + cl.__name__ + "." + i
satr-cowi marked this conversation as resolved.
Show resolved Hide resolved
if i[0] != "_":
picnixz marked this conversation as resolved.
Show resolved Hide resolved
ns['inherited_paths'].append(cl_str)

if i in method_string:
ns['inherited_methods'].append(cl_str)
elif i in attr_string:
ns['inherited_attributes'].append(cl_str)
break

if modname is None or qualname is None:
modname, qualname = _split_full_qualified_name(name)

Expand Down
Loading