Skip to content

gh-111746: Doc: Format built-in function's attributes #113574

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.

Sign up for GitHub

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

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
Open

gh-111746: Doc: Format built-in function's attributes #113574

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
d2bd9fa
Doc: Fix the array.fromfile method doc
adorilson Sep 1, 2020
57b4ca3
gh-106320: Remove private _PyInterpreterState functions (#106335)
vstinner Jul 2, 2023
af75429
Added header to instance methods' attributes table
adorilson Dec 27, 2023
1a43871
Doc: Format built-in function's attributes
adorilson Dec 29, 2023
d0d42d4
Doc: Replace a regular text by a clickable reference
adorilson Dec 29, 2023
37ea418
Doc: minor change
adorilson Dec 30, 2023
6d3808a
Doc: Rename builtin function attributes' label
adorilson Dec 30, 2023
a1a8231
Doc: Add builtin_function.__qualname__ attribute
adorilson Dec 30, 2023
c6ed4e6
Doc: Put builtin functions' attributes in alphabetic order
adorilson Dec 30, 2023
da72b09
Doc: Add builtin_function.__class__ attribute
adorilson Dec 30, 2023
3051d0c
Doc: Add builtin_function.__text_signature__ attribute
adorilson Dec 31, 2023
18d148c
Doc: Improve builtin_function.__self__ definition
adorilson Dec 31, 2023
4fdb837
Merge branch 'main' into gh111746_fix_list_attr_datamodel_doc
AlexWaygood Jan 3, 2025
e207114
Update Doc/reference/datamodel.rst
adorilson Dec 1, 2025
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
1 change: 0 additions & 1 deletion Doc/library/array.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,4 +266,3 @@ Examples::

`NumPy <https://numpy.org/>`_
The NumPy package defines another array type.

41 changes: 32 additions & 9 deletions Doc/reference/datamodel.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -666,9 +666,14 @@ callable object (normally a user-defined function).
single: __name__ (method attribute)
single: __module__ (method attribute)

Special read-only attributes:
Special read-only attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Copy link
Member

@AlexWaygood AlexWaygood Dec 30, 2023

Choose a reason for hiding this comment

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

I don't think it really makes sense to make this a separate subsection, since there are no other subsections inside the datamodel section on instance methods. I'd just keep this as a sentence ending with a colon, personally


.. list-table::
:header-rows: 1

* - Attribute
- Meaning

* - .. attribute:: method.__self__
- Refers to the class instance object to which the method is
Expand Down Expand Up @@ -804,16 +809,34 @@ Built-in functions
A built-in function object is a wrapper around a C function. Examples of
built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
standard built-in module). The number and type of the arguments are
determined by the C function. Special read-only attributes:
determined by the C function.

Special read-only attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Copy link
Member

@AlexWaygood AlexWaygood Dec 30, 2023

Choose a reason for hiding this comment

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

Same here, I'm not sure it really makes sense to make this a distinct subsection when there aren't any other subsections inside the datamodel section on builtin functions

Copy link
Contributor Author

@adorilson adorilson Dec 30, 2023

Choose a reason for hiding this comment

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

I thought about that, and I decided by subsection because:

  1. consistency with other sections (e.g., the one you highlighted above and Code Objects). In this case, I would fix some other sections, too.
  2. personally, I like that (although it is a unique section).
  3. if I see the summary, I immediately know the element has or does not have special attributes. More explicit.

Actually, when I opened the issue, I thought about a unique table for both attributes with a column to identify the kind, as the User-defined functions section was before your recent changes.

Copy link
Member

@AlexWaygood AlexWaygood Dec 31, 2023

Choose a reason for hiding this comment

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

Those are all reasonable points! I don't mind the new subsection in the section on builtin functions too much; I'm happy for that to stay.

I do think the new subsection in the section on instance methods makes it more confusing, however. It implies that the entirety of the section on instance methods is about their special read-only attributes, except for the first paragraph. This isn't true: the final paragraph in section 3.2.8.2 has nothing to do with the special read-only methods of instance methods:

Note that the transformation from function object to instance method object happens each time the attribute is retrieved from the instance. In some cases, a fruitful optimization is to assign the attribute to a local variable and call that local variable. Also notice that this transformation only happens for user-defined functions; other callable objects (and all non-callable objects) are retrieved without transformation. It is also important to note that user-defined functions which are attributes of a class instance are not converted to bound methods; this only happens when the function is an attribute of the class.

Copy link
Contributor Author

@adorilson adorilson Dec 31, 2023

Choose a reason for hiding this comment

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

What if do we move this paragraph to the second paragraph? This seems an explanation for the first one.

Copy link
Member

@AlexWaygood AlexWaygood Dec 31, 2023

Choose a reason for hiding this comment

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

Well, what about these two paragraphs?

When an instance method object is created by retrieving a classmethod object from a class or instance, its __self__ attribute is the class itself, and its __func__ attribute is the function object underlying the class method.

When an instance method object is called, the underlying function (__func__) is called, inserting the class instance (__self__) in front of the argument list. For instance, when C is a class which contains a definition for a function f(), and x is an instance of C, calling x.f(1) is equivalent to calling C.f(x, 1).

The first paragraph is about the special read-only attributes of method objects; the second one isn't (it's about a broader topic to do with the semantics of Python methods). So maybe we should move the second paragraph out of the section about the special read-only attributes -- but that would make no sense; it's much more logical to talk about how the self reference is inserted at the beginning of the argument list after we've talked about the special __self__ attribute. The two paragraphs belong together.

For the section on instance methods, I think the existing structure -- where the special read-only attributes are discussed at the same time as other details on method semantics -- makes most sense. Unless you want to propose reworking the whole section on instance methods (which should go into a separate PR, IMO), I don't think we should add a subsection just for the read-only attributes.

Copy link
Contributor Author

@adorilson adorilson Jan 1, 2024

Choose a reason for hiding this comment

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

it's about a broader topic to do with the semantics of Python methods

Despite this, I think that we can consider all these paragraphs as about the attributes. They talk about how the attributes work together to element (object, class, method..) to work as well. The attributes are cited a lot of time.

In first look, I understand this paragraph under attributes this way. However, I also noted some paragraphs didn't are about the attribute, but about the element. I would propose moving these paragraphs to the introduction of the section, probrably.

Another two idea are:

  1. Adding a new section something like "More details", "How it works" about extra content.
  2. Removing all attribute's subsection mark in the chapter

I prefer first option (although more work), but the second one also provide consistence.

Unless you want to propose reworking the whole section on instance methods (which should go into a separate PR, IMO),

Shall we do this together. Some details about it can scape me. :) I think what I told above is in this direction.

(Sorry for any confused thought. It is a brainstorm)

Copy link
Member

@AlexWaygood AlexWaygood Jan 3, 2025

Choose a reason for hiding this comment

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

I'm sorry, but I still disagree that using a subsection for the Instance methods section is the right way to go there, at least the way you've currently done it in this PR :/ I'd be happy to look at a broader rewrite of that section, because I agree that consistency between the different sections is nice. But unfortunately I don't really have time to push forward on that right now (and I doubt I will until PyCon).


.. list-table::
:header-rows: 1

* - Attribute
- Meaning

* - .. attribute:: function.__doc__
:noindex:
- The function's documentation string, or ``None`` if unavailable.
See :attr:`function.__doc__`.

* - .. attribute:: function.__name__
:noindex:
- The function's name.
See :attr:`function.__name__`.

* :attr:`!__doc__` is the function's documentation string, or ``None`` if
unavailable. See :attr:`function.__doc__`.
* :attr:`!__name__` is the function's name. See :attr:`function.__name__`.
* :attr:`!__self__` is set to ``None`` (but see the next item).
* :attr:`!__module__` is the name of
the module the function was defined in or ``None`` if unavailable.
See :attr:`function.__module__`.
* - .. attribute:: function.__self__
- It is set to ``None`` (but see :ref:`built-in methods <builtin-methods>`).

* - .. attribute:: function.__module__
:noindex:
- The name of the module the function was defined in,
or ``None`` if unavailable. See :attr:`function.__module__`.

.. _builtin-methods:

Expand Down