Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit d2068c6

Browse files
AlexWaygoodAlexWaygood
authored
[3.12] gh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (#124480) (#124558)
1 parent ea5c650 commit d2068c6

39 files changed

+225
-181
lines changed

‎Doc/c-api/exceptions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -720,7 +720,7 @@ Exception Classes
720720
This creates a class object derived from :exc:`Exception` (accessible in C as
721721
:c:data:`PyExc_Exception`).
722722
723-
The :attr:`!__module__` attribute of the new class is set to the first part (up
723+
The :attr:`~type.__module__` attribute of the new class is set to the first part (up
724724
to the last dot) of the *name* argument, and the class name is set to the last
725725
part (after the last dot). The *base* argument can be used to specify alternate
726726
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
@@ -253,14 +253,14 @@ Object Protocol
253253
The result will be ``1`` when at least one of the checks returns ``1``,
254254
otherwise it will be ``0``.
255255
256-
If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
256+
If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to
257257
determine the subclass status as described in :pep:`3119`. Otherwise,
258258
*derived* is a subclass of *cls* if it is a direct or indirect subclass,
259-
i.e. contained in ``cls.__mro__``.
259+
i.e. contained in :attr:`cls.__mro__ <type.__mro__>`.
260260
261261
Normally only class objects, i.e. instances of :class:`type` or a derived
262262
class, are considered classes. However, objects can override this by having
263-
a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
263+
a :attr:`~type.__bases__` attribute (which must be a tuple of base classes).
264264
265265
266266
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
@@ -272,15 +272,15 @@ Object Protocol
272272
The result will be ``1`` when at least one of the checks returns ``1``,
273273
otherwise it will be ``0``.
274274
275-
If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
275+
If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to
276276
determine the subclass status as described in :pep:`3119`. Otherwise, *inst*
277277
is an instance of *cls* if its class is a subclass of *cls*.
278278
279279
An instance *inst* can override what is considered its class by having a
280-
:attr:`~instance.__class__` attribute.
280+
:attr:`~object.__class__` attribute.
281281
282282
An object *cls* can override if it is considered a class, and what its base
283-
classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
283+
classes are, by having a :attr:`~type.__bases__` attribute (which must be a tuple
284284
of base classes).
285285
286286

‎Doc/c-api/type.rst

Lines changed: 6 additions & 4 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,14 +175,15 @@ 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

‎Doc/c-api/typeobj.rst

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

590590
For :ref:`statically allocated type objects <static-types>`,
591591
the *tp_name* field should contain a dot.
592-
Everything before the last dot is made accessible as the :attr:`__module__`
592+
Everything before the last dot is made accessible as the :attr:`~type.__module__`
593593
attribute, and everything after the last dot is made accessible as the
594-
:attr:`~definition.__name__` attribute.
594+
:attr:`~type.__name__` attribute.
595595

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

11501150
.. c:macro:: Py_TPFLAGS_MANAGED_DICT
11511151
1152-
This bit indicates that instances of the class have a ``__dict__``
1152+
This bit indicates that instances of the class have a `~object.__dict__`
11531153
attribute, and that the space for the dictionary is managed by the VM.
11541154

11551155
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
@@ -1350,8 +1350,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
13501350
.. c:member:: const char* PyTypeObject.tp_doc
13511351
13521352
An optional pointer to a NUL-terminated C string giving the docstring for this
1353-
type object. This is exposed as the :attr:`__doc__` attribute on the type and
1354-
instances of the type.
1353+
type object. This is exposed as the :attr:`~type.__doc__` attribute on the
1354+
type and instances of the type.
13551355

13561356
**Inheritance:**
13571357

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

20302030
To get a list of subclasses, call the Python method
2031-
:py:meth:`~class.__subclasses__`.
2031+
:py:meth:`~type.__subclasses__`.
20322032

20332033
.. versionchanged:: 3.12
20342034

‎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
@@ -350,7 +350,7 @@ Glossary
350350
docstring
351351
A string literal which appears as the first expression in a class,
352352
function or module. While ignored when the suite is executed, it is
353-
recognized by the compiler and put into the :attr:`!__doc__` attribute
353+
recognized by the compiler and put into the :attr:`~definition.__doc__` attribute
354354
of the enclosing class, function or module. Since it is available via
355355
introspection, it is the canonical place for documentation of the
356356
object.
@@ -1201,7 +1201,7 @@ Glossary
12011201
type
12021202
The type of a Python object determines what kind of object it is; every
12031203
object has a type. An object's type is accessible as its
1204-
:attr:`~instance.__class__` attribute or can be retrieved with
1204+
:attr:`~object.__class__` attribute or can be retrieved with
12051205
``type(obj)``.
12061206

12071207
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
@@ -559,8 +559,8 @@ attribute access.
559559

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

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

‎Doc/howto/enum.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -589,7 +589,7 @@ The solution is to specify the module name explicitly as follows::
589589
the source, pickling will be disabled.
590590

591591
The new pickle protocol 4 also, in some circumstances, relies on
592-
:attr:`~definition.__qualname__` being set to the location where pickle will be able
592+
:attr:`~type.__qualname__` being set to the location where pickle will be able
593593
to find the class. For example, if the class was made available in class
594594
SomeData in the global scope::
595595

‎Doc/howto/mro.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -335,7 +335,7 @@ E is more specialized than C, even if it is in a higher level.
335335

336336
A lazy programmer can obtain the MRO directly from Python 2.2, since in
337337
this case it coincides with the Python 2.3 linearization. It is enough
338-
to invoke the .mro() method of class A:
338+
to invoke the :meth:`~type.mro` method of class A:
339339

340340
>>> A.mro() # doctest: +NORMALIZE_WHITESPACE
341341
[<class 'A'>, <class 'B'>, <class 'E'>,

‎Doc/library/abc.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
9999
that you can customize the behavior of :func:`issubclass` further without the
100100
need to call :meth:`register` on every class you want to consider a
101101
subclass of the ABC. (This class method is called from the
102-
:meth:`~class.__subclasscheck__` method of the ABC.)
102+
:meth:`~type.__subclasscheck__` method of the ABC.)
103103

104104
This method should return ``True``, ``False`` or :data:`NotImplemented`. If
105105
it returns ``True``, the *subclass* is considered a subclass of this ABC.
@@ -149,7 +149,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
149149
The :meth:`__subclasshook__` class method defined here says that any class
150150
that has an :meth:`~iterator.__iter__` method in its
151151
:attr:`~object.__dict__` (or in that of one of its base classes, accessed
152-
via the :attr:`~class.__mro__` list) is considered a ``MyIterable`` too.
152+
via the :attr:`~type.__mro__` list) is considered a ``MyIterable`` too.
153153

154154
Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
155155
even though it does not define an :meth:`~iterator.__iter__` method (it uses

‎Doc/library/collections.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -874,8 +874,8 @@ they add the ability to access fields by name instead of position index.
874874
``(1, 2)``, then ``x`` will be a required argument, ``y`` will default to
875875
``1``, and ``z`` will default to ``2``.
876876

877-
If *module* is defined, the ``__module__`` attribute of the named tuple is
878-
set to that value.
877+
If *module* is defined, the :attr:`~type.__module__` attribute of the
878+
named tuple is set to that value.
879879

880880
Named tuple instances do not have per-instance dictionaries, so they are
881881
lightweight and require no more memory than regular tuples.

‎Doc/library/email.contentmanager.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,11 +58,12 @@
5858
* the type itself (``typ``)
5959
* the type's fully qualified name (``typ.__module__ + '.' +
6060
typ.__qualname__``).
61-
* the type's qualname (``typ.__qualname__``)
62-
* the type's name (``typ.__name__``).
61+
* the type's :attr:`qualname <type.__qualname__>` (``typ.__qualname__``)
62+
* the type's :attr:`name <type.__name__>` (``typ.__name__``).
6363

6464
If none of the above match, repeat all of the checks above for each of
65-
the types in the :term:`MRO` (``typ.__mro__``). Finally, if no other key
65+
the types in the :term:`MRO` (:attr:`typ.__mro__ <type.__mro__>`).
66+
Finally, if no other key
6667
yields a handler, check for a handler for the key ``None``. If there is
6768
no handler for ``None``, raise a :exc:`KeyError` for the fully
6869
qualified name of the type.

‎Doc/library/email.headerregistry.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -317,7 +317,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
317317
class. When *use_default_map* is ``True`` (the default), the standard
318318
mapping of header names to classes is copied in to the registry during
319319
initialization. *base_class* is always the last class in the generated
320-
class's ``__bases__`` list.
320+
class's :class:`~type.__bases__` list.
321321

322322
The default mappings are:
323323

‎Doc/library/functions.rst

Lines changed: 27 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -283,9 +283,11 @@ are always available. They are listed here in alphabetical order.
283283
:func:`property`.
284284

285285
.. versionchanged:: 3.10
286-
Class methods now inherit the method attributes (``__module__``,
287-
``__name__``, ``__qualname__``, ``__doc__`` and ``__annotations__``) and
288-
have a new ``__wrapped__`` attribute.
286+
Class methods now inherit the method attributes
287+
(:attr:`~function.__module__`, :attr:`~function.__name__`,
288+
:attr:`~function.__qualname__`, :attr:`~function.__doc__` and
289+
:attr:`~function.__annotations__`) and have a new ``__wrapped__``
290+
attribute.
289291

290292
.. versionchanged:: 3.11
291293
Class methods can no longer wrap other :term:`descriptors <descriptor>` such as
@@ -1217,8 +1219,9 @@ are always available. They are listed here in alphabetical order.
12171219

12181220
.. note::
12191221

1220-
:class:`object` does *not* have a :attr:`~object.__dict__`, so you can't
1221-
assign arbitrary attributes to an instance of the :class:`object` class.
1222+
:class:`object` instances do *not* have :attr:`~object.__dict__`
1223+
attributes, so you can't assign arbitrary attributes to an instance of
1224+
:class:`object`.
12221225

12231226

12241227
.. function:: oct(x)
@@ -1831,10 +1834,11 @@ are always available. They are listed here in alphabetical order.
18311834
For more information on static methods, see :ref:`types`.
18321835

18331836
.. versionchanged:: 3.10
1834-
Static methods now inherit the method attributes (``__module__``,
1835-
``__name__``, ``__qualname__``, ``__doc__`` and ``__annotations__``),
1836-
have a new ``__wrapped__`` attribute, and are now callable as regular
1837-
functions.
1837+
Static methods now inherit the method attributes
1838+
(:attr:`~function.__module__`, :attr:`~function.__name__`,
1839+
:attr:`~function.__qualname__`, :attr:`~function.__doc__` and
1840+
:attr:`~function.__annotations__`), have a new ``__wrapped__`` attribute,
1841+
and are now callable as regular functions.
18381842

18391843

18401844
.. index::
@@ -1881,11 +1885,11 @@ are always available. They are listed here in alphabetical order.
18811885
to be searched. The search starts from the class right after the
18821886
*type*.
18831887

1884-
For example, if :attr:`~class.__mro__` of *object_or_type* is
1888+
For example, if :attr:`~type.__mro__` of *object_or_type* is
18851889
``D -> B -> C -> A -> object`` and the value of *type* is ``B``,
18861890
then :func:`super` searches ``C -> A -> object``.
18871891

1888-
The :attr:`~class.__mro__` attribute of the class corresponding to
1892+
The :attr:`~type.__mro__` attribute of the class corresponding to
18891893
*object_or_type* lists the method resolution search order used by both
18901894
:func:`getattr` and :func:`super`. The attribute is dynamic and can change
18911895
whenever the inheritance hierarchy is updated.
@@ -1957,28 +1961,30 @@ are always available. They are listed here in alphabetical order.
19571961

19581962
With one argument, return the type of an *object*. The return value is a
19591963
type object and generally the same object as returned by
1960-
:attr:`object.__class__ <instance.__class__>`.
1964+
:attr:`object.__class__`.
19611965

19621966
The :func:`isinstance` built-in function is recommended for testing the type
19631967
of an object, because it takes subclasses into account.
19641968

1965-
19661969
With three arguments, return a new type object. This is essentially a
19671970
dynamic form of the :keyword:`class` statement. The *name* string is
1968-
the class name and becomes the :attr:`~definition.__name__` attribute.
1971+
the class name and becomes the :attr:`~type.__name__` attribute.
19691972
The *bases* tuple contains the base classes and becomes the
1970-
:attr:`~class.__bases__` attribute; if empty, :class:`object`, the
1973+
:attr:`~type.__bases__` attribute; if empty, :class:`object`, the
19711974
ultimate base of all classes, is added. The *dict* dictionary contains
19721975
attribute and method definitions for the class body; it may be copied
1973-
or wrapped before becoming the :attr:`~object.__dict__` attribute.
1974-
The following two statements create identical :class:`type` objects:
1976+
or wrapped before becoming the :attr:`~type.__dict__` attribute.
1977+
The following two statements create identical :class:`!type` objects:
19751978

19761979
>>> class X:
19771980
... a = 1
19781981
...
19791982
>>> X = type('X', (), dict(a=1))
19801983

1981-
See also :ref:`bltin-type-objects`.
1984+
See also:
1985+
1986+
* :ref:`Documentation on attributes and methods on classes <class-attrs-and-methods>`.
1987+
* :ref:`bltin-type-objects`
19821988

19831989
Keyword arguments provided to the three argument form are passed to the
19841990
appropriate metaclass machinery (usually :meth:`~object.__init_subclass__`)
@@ -1988,18 +1994,18 @@ are always available. They are listed here in alphabetical order.
19881994
See also :ref:`class-customization`.
19891995

19901996
.. versionchanged:: 3.6
1991-
Subclasses of :class:`type` which don't override ``type.__new__`` may no
1997+
Subclasses of :class:`!type` which don't override ``type.__new__`` may no
19921998
longer use the one-argument form to get the type of an object.
19931999

19942000
.. function:: vars()
19952001
vars(object)
19962002

19972003
Return the :attr:`~object.__dict__` attribute for a module, class, instance,
1998-
or any other object with a :attr:`~object.__dict__` attribute.
2004+
or any other object with a :attr:`!__dict__` attribute.
19992005

20002006
Objects such as modules and instances have an updateable :attr:`~object.__dict__`
20012007
attribute; however, other objects may have write restrictions on their
2002-
:attr:`~object.__dict__` attributes (for example, classes use a
2008+
:attr:`!__dict__` attributes (for example, classes use a
20032009
:class:`types.MappingProxyType` to prevent direct dictionary updates).
20042010

20052011
Without an argument, :func:`vars` acts like :func:`locals`. Note, the

0 commit comments

Comments
 (0)