Skip to content

Commit 9f2e6ca

Browse files
AlexWaygoodAlexWaygood
authored
[3.13] gh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (#124480) (#124556)
1 parent 068e734 commit 9f2e6ca

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+247
-205
lines changed

‎Doc/c-api/exceptions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -733,7 +733,7 @@ Exception Classes
733733
This creates a class object derived from :exc:`Exception` (accessible in C as
734734
:c:data:`PyExc_Exception`).
735735
736-
The :attr:`!__module__` attribute of the new class is set to the first part (up
736+
The :attr:`~type.__module__` attribute of the new class is set to the first part (up
737737
to the last dot) of the *name* argument, and the class name is set to the last
738738
part (after the last dot). The *base* argument can be used to specify alternate
739739
base classes; it can either be only one class or a tuple of classes. The *dict*

‎Doc/c-api/object.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -367,14 +367,14 @@ Object Protocol
367367
The result will be ``1`` when at least one of the checks returns ``1``,
368368
otherwise it will be ``0``.
369369
370-
If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
370+
If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to
371371
determine the subclass status as described in :pep:`3119`. Otherwise,
372372
*derived* is a subclass of *cls* if it is a direct or indirect subclass,
373-
i.e. contained in ``cls.__mro__``.
373+
i.e. contained in :attr:`cls.__mro__ <type.__mro__>`.
374374
375375
Normally only class objects, i.e. instances of :class:`type` or a derived
376376
class, are considered classes. However, objects can override this by having
377-
a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
377+
a :attr:`~type.__bases__` attribute (which must be a tuple of base classes).
378378
379379
380380
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
@@ -386,15 +386,15 @@ Object Protocol
386386
The result will be ``1`` when at least one of the checks returns ``1``,
387387
otherwise it will be ``0``.
388388
389-
If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
389+
If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to
390390
determine the subclass status as described in :pep:`3119`. Otherwise, *inst*
391391
is an instance of *cls* if its class is a subclass of *cls*.
392392
393393
An instance *inst* can override what is considered its class by having a
394-
:attr:`~instance.__class__` attribute.
394+
:attr:`~object.__class__` attribute.
395395
396396
An object *cls* can override if it is considered a class, and what its base
397-
classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
397+
classes are, by having a :attr:`~type.__bases__` attribute (which must be a tuple
398398
of base classes).
399399
400400

‎Doc/c-api/type.rst

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ Type Objects
5353
.. c:function:: PyObject* PyType_GetDict(PyTypeObject* type)
5454
5555
Return the type object's internal namespace, which is otherwise only
56-
exposed via a read-only proxy (``cls.__dict__``). This is a
56+
exposed via a read-only proxy (:attr:`cls.__dict__ <type.__dict__>`).
57+
This is a
5758
replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly.
5859
The returned dictionary must be treated as read-only.
5960
@@ -140,7 +141,7 @@ Type Objects
140141
Return true if *a* is a subtype of *b*.
141142
142143
This function only checks for actual subtypes, which means that
143-
:meth:`~class.__subclasscheck__` is not called on *b*. Call
144+
:meth:`~type.__subclasscheck__` is not called on *b*. Call
144145
:c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
145146
would do.
146147
@@ -174,29 +175,30 @@ Type Objects
174175
175176
.. c:function:: PyObject* PyType_GetName(PyTypeObject *type)
176177
177-
Return the type's name. Equivalent to getting the type's ``__name__`` attribute.
178+
Return the type's name. Equivalent to getting the type's
179+
:attr:`~type.__name__` attribute.
178180
179181
.. versionadded:: 3.11
180182
181183
.. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
182184
183185
Return the type's qualified name. Equivalent to getting the
184-
type's ``__qualname__`` attribute.
186+
type's :attr:`~type.__qualname__` attribute.
185187
186188
.. versionadded:: 3.11
187189
188190
.. c:function:: PyObject* PyType_GetFullyQualifiedName(PyTypeObject *type)
189191
190192
Return the type's fully qualified name. Equivalent to
191-
``f"{type.__module__}.{type.__qualname__}"``, or ``type.__qualname__`` if
192-
``type.__module__`` is not a string or is equal to ``"builtins"``.
193+
``f"{type.__module__}.{type.__qualname__}"``, or :attr:`type.__qualname__`
194+
if :attr:`type.__module__` is not a string or is equal to ``"builtins"``.
193195
194196
.. versionadded:: 3.13
195197
196198
.. c:function:: PyObject* PyType_GetModuleName(PyTypeObject *type)
197199
198-
Return the type's module name. Equivalent to getting the ``type.__module__``
199-
attribute.
200+
Return the type's module name. Equivalent to getting the
201+
:attr:`type.__module__` attribute.
200202
201203
.. versionadded:: 3.13
202204

‎Doc/c-api/typeobj.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -567,12 +567,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)
567567

568568
For :ref:`statically allocated type objects <static-types>`,
569569
the *tp_name* field should contain a dot.
570-
Everything before the last dot is made accessible as the :attr:`__module__`
570+
Everything before the last dot is made accessible as the :attr:`~type.__module__`
571571
attribute, and everything after the last dot is made accessible as the
572-
:attr:`~definition.__name__` attribute.
572+
:attr:`~type.__name__` attribute.
573573

574574
If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the
575-
:attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined
575+
:attr:`~type.__name__` attribute, and the :attr:`~type.__module__` attribute is undefined
576576
(unless explicitly set in the dictionary, as explained above). This means your
577577
type will be impossible to pickle. Additionally, it will not be listed in
578578
module documentations created with pydoc.
@@ -1131,7 +1131,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
11311131

11321132
.. c:macro:: Py_TPFLAGS_MANAGED_DICT
11331133
1134-
This bit indicates that instances of the class have a ``__dict__``
1134+
This bit indicates that instances of the class have a `~object.__dict__`
11351135
attribute, and that the space for the dictionary is managed by the VM.
11361136

11371137
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
@@ -1335,8 +1335,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
13351335
.. c:member:: const char* PyTypeObject.tp_doc
13361336
13371337
An optional pointer to a NUL-terminated C string giving the docstring for this
1338-
type object. This is exposed as the :attr:`__doc__` attribute on the type and
1339-
instances of the type.
1338+
type object. This is exposed as the :attr:`~type.__doc__` attribute on the
1339+
type and instances of the type.
13401340

13411341
**Inheritance:**
13421342

@@ -2036,7 +2036,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
20362036
A collection of subclasses. Internal use only. May be an invalid pointer.
20372037

20382038
To get a list of subclasses, call the Python method
2039-
:py:meth:`~class.__subclasses__`.
2039+
:py:meth:`~type.__subclasses__`.
20402040

20412041
.. versionchanged:: 3.12
20422042

‎Doc/extending/newtypes.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -296,7 +296,7 @@ An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table
296296
descriptors that are used at runtime is that any attribute defined this way can
297297
have an associated doc string simply by providing the text in the table. An
298298
application can use the introspection API to retrieve the descriptor from the
299-
class object, and get the doc string using its :attr:`!__doc__` attribute.
299+
class object, and get the doc string using its :attr:`~type.__doc__` attribute.
300300

301301
As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
302302
of ``NULL`` is required.

‎Doc/extending/newtypes_tutorial.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ only used for variable-sized objects and should otherwise be zero.
144144
If you want your type to be subclassable from Python, and your type has the same
145145
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
146146
inheritance. A Python subclass of your type will have to list your type first
147-
in its :attr:`~class.__bases__`, or else it will not be able to call your type's
147+
in its :attr:`~type.__bases__`, or else it will not be able to call your type's
148148
:meth:`~object.__new__` method without getting an error. You can avoid this problem by
149149
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
150150
base type does. Most of the time, this will be true anyway, because either your

‎Doc/faq/programming.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1614,7 +1614,7 @@ method too, and it must do so carefully. The basic implementation of
16141614
...
16151615

16161616
Most :meth:`!__setattr__` implementations must modify
1617-
:meth:`self.__dict__ <object.__dict__>` to store
1617+
:attr:`self.__dict__ <object.__dict__>` to store
16181618
local state for self without causing an infinite recursion.
16191619

16201620

‎Doc/glossary.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,7 @@ Glossary
342342
docstring
343343
A string literal which appears as the first expression in a class,
344344
function or module. While ignored when the suite is executed, it is
345-
recognized by the compiler and put into the :attr:`!__doc__` attribute
345+
recognized by the compiler and put into the :attr:`~definition.__doc__` attribute
346346
of the enclosing class, function or module. Since it is available via
347347
introspection, it is the canonical place for documentation of the
348348
object.
@@ -1231,7 +1231,7 @@ Glossary
12311231
type
12321232
The type of a Python object determines what kind of object it is; every
12331233
object has a type. An object's type is accessible as its
1234-
:attr:`~instance.__class__` attribute or can be retrieved with
1234+
:attr:`~object.__class__` attribute or can be retrieved with
12351235
``type(obj)``.
12361236

12371237
type alias

‎Doc/howto/annotations.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,9 @@ Your code will have to have a separate code path if the object
102102
you're examining is a class (``isinstance(o, type)``).
103103
In that case, best practice relies on an implementation detail
104104
of Python 3.9 and before: if a class has annotations defined,
105-
they are stored in the class's ``__dict__`` dictionary. Since
105+
they are stored in the class's :attr:`~type.__dict__` dictionary. Since
106106
the class may or may not have annotations defined, best practice
107-
is to call the ``get`` method on the class dict.
107+
is to call the :meth:`~dict.get` method on the class dict.
108108

109109
To put it all together, here is some sample code that safely
110110
accesses the ``__annotations__`` attribute on an arbitrary
@@ -121,8 +121,8 @@ the type of ``ann`` using :func:`isinstance` before further
121121
examination.
122122

123123
Note that some exotic or malformed type objects may not have
124-
a ``__dict__`` attribute, so for extra safety you may also wish
125-
to use :func:`getattr` to access ``__dict__``.
124+
a :attr:`~type.__dict__` attribute, so for extra safety you may also wish
125+
to use :func:`getattr` to access :attr:`!__dict__`.
126126

127127

128128
Manually Un-Stringizing Stringized Annotations

‎Doc/howto/descriptor.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -562,8 +562,8 @@ attribute access.
562562

563563
The expression ``obj.x`` looks up the attribute ``x`` in the chain of
564564
namespaces for ``obj``. If the search finds a descriptor outside of the
565-
instance ``__dict__``, its :meth:`__get__` method is invoked according to the
566-
precedence rules listed below.
565+
instance :attr:`~object.__dict__`, its :meth:`~object.__get__` method is
566+
invoked according to the precedence rules listed below.
567567

568568
The details of invocation depend on whether ``obj`` is an object, class, or
569569
instance of super.

0 commit comments

Comments
 (0)