Skip to content

gh-101100: fix sphinx warnings in reference/datamodel.rst #114280

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

Closed
wants to merge 4 commits into from
Closed

gh-101100: fix sphinx warnings in reference/datamodel.rst #114280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0046711
gh-101100: fix sphinx warnings in reference/datamodel.rst
skirpichev Dec 25, 2023
d1fd6e8
address review: revert set.add
skirpichev Jan 19, 2024
4adf825
Update Doc/reference/datamodel.rst
skirpichev Jan 19, 2024
befdd61
Merge branch 'master' into datamodel.rst-101100
skirpichev Jan 23, 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
1 change: 1 addition & 0 deletions Doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,7 @@
('py:meth', '__missing__'),
('py:attr', '__wrapped__'),
('py:meth', 'index'), # list.index, tuple.index, etc.
('py:meth', 'set.add'),
]

# gh-106948: Copy standard C types declared in the "c:type" domain to the
Expand Down
11 changes: 11 additions & 0 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5492,6 +5492,17 @@ types, where they are relevant. Some of these are not reported by the
The tuple of base classes of a class object.


.. attribute:: definition.__module__
Copy link
Member

@AlexWaygood AlexWaygood Jan 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

In my opinion, the attributes listed here should only be attributes such as __dict__ and __class__ that appear on all Python objects (I'm aware that's not currently the case, but that's a problem, in my opinion).

We already have a dedicated reference for the __module__ attribute on function objects; I think we should do the same for the __module__ attribute on class objects: https://docs.python.org/3/reference/datamodel.html#function.__module__ (ditto for __doc__)


The name of the module in which the class or function was defined.


.. attribute:: definition.__doc__

The documentation string of the class, function, method, descriptor,
generator instance, or ``None`` if undefined.


.. attribute:: definition.__name__

The name of the class, function, method, descriptor, or
Expand Down
14 changes: 7 additions & 7 deletions Doc/reference/datamodel.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -885,7 +885,7 @@ Predefined (writable) attributes:
:attr:`__name__`
The module's name.

:attr:`__doc__`
:attr:`~definition.__doc__`
Copy link
Member

@AlexWaygood AlexWaygood Jan 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I'd prefer to fix these warnings by creating a single canonical table in the datamodel docs, and removing duplicated documentation elsewhere: see #101100 (comment) (and see PRs where I did similar things for other lists like this in this document: #112781, #112735, #112832, #112933)

The module's documentation string, or ``None`` if
unavailable.

Expand Down Expand Up @@ -976,7 +976,7 @@ Special attributes:
:attr:`~definition.__name__`
The class name.

:attr:`__module__`
:attr:`~definition.__module__`
The name of the module in which the class was defined.

:attr:`~object.__dict__`
Expand All @@ -986,7 +986,7 @@ Special attributes:
A tuple containing the base classes, in the order of
their occurrence in the base class list.

:attr:`__doc__`
:attr:`~definition.__doc__`
The class's documentation string, or ``None`` if undefined.

:attr:`__annotations__`
Expand All @@ -996,7 +996,7 @@ Special attributes:
working with :attr:`__annotations__`, please see
:ref:`annotations-howto`.

:attr:`__type_params__`
:attr:`~definition.__type_params__`
A tuple containing the :ref:`type parameters <type-params>` of
a :ref:`generic class <generic-classes>`.

Expand Down Expand Up @@ -1563,8 +1563,8 @@ When implementing a class that emulates any built-in type, it is important that
the emulation only be implemented to the degree that it makes sense for the
object being modelled. For example, some sequences may work well with retrieval
of individual elements, but extracting a slice may not make sense. (One example
of this is the :class:`~xml.dom.NodeList` interface in the W3C's Document
Object Model.)
of this is the class ``NodeList`` interface in the W3C's Document
Object Model, see :ref:`dom-nodelist-objects`.)


.. _customization:
Expand Down Expand Up @@ -2334,7 +2334,7 @@ class defining the method.
.. versionadded:: 3.6


When a class is created, :meth:`type.__new__` scans the class variables
When a class is created, :meth:`!type.__new__` scans the class variables
and makes callbacks to those with a :meth:`~object.__set_name__` hook.

.. method:: object.__set_name__(self, owner, name)
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,6 @@ Doc/library/xmlrpc.client.rst
Doc/library/xmlrpc.server.rst
Doc/library/zlib.rst
Doc/reference/compound_stmts.rst
Doc/reference/datamodel.rst
Doc/reference/import.rst
Doc/tutorial/datastructures.rst
Doc/using/windows.rst
Expand Down