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

[3.12] gh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (#124480) #124558

Merged
merged 3 commits into from
Sep 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion Doc/c-api/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -720,7 +720,7 @@ Exception Classes
This creates a class object derived from :exc:`Exception` (accessible in C as
:c:data:`PyExc_Exception`).

The :attr:`!__module__` attribute of the new class is set to the first part (up
The :attr:`~type.__module__` attribute of the new class is set to the first part (up
to the last dot) of the *name* argument, and the class name is set to the last
part (after the last dot). The *base* argument can be used to specify alternate
base classes; it can either be only one class or a tuple of classes. The *dict*
Expand Down
12 changes: 6 additions & 6 deletions Doc/c-api/object.rst
Original file line number Diff line number Diff line change
Expand Up @@ -253,14 +253,14 @@ Object Protocol
The result will be ``1`` when at least one of the checks returns ``1``,
otherwise it will be ``0``.

If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to
determine the subclass status as described in :pep:`3119`. Otherwise,
*derived* is a subclass of *cls* if it is a direct or indirect subclass,
i.e. contained in ``cls.__mro__``.
i.e. contained in :attr:`cls.__mro__ <type.__mro__>`.

Normally only class objects, i.e. instances of :class:`type` or a derived
class, are considered classes. However, objects can override this by having
a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
a :attr:`~type.__bases__` attribute (which must be a tuple of base classes).


.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
Expand All @@ -272,15 +272,15 @@ Object Protocol
The result will be ``1`` when at least one of the checks returns ``1``,
otherwise it will be ``0``.

If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to
determine the subclass status as described in :pep:`3119`. Otherwise, *inst*
is an instance of *cls* if its class is a subclass of *cls*.

An instance *inst* can override what is considered its class by having a
:attr:`~instance.__class__` attribute.
:attr:`~object.__class__` attribute.

An object *cls* can override if it is considered a class, and what its base
classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
classes are, by having a :attr:`~type.__bases__` attribute (which must be a tuple
of base classes).


Expand Down
10 changes: 6 additions & 4 deletions Doc/c-api/type.rst
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@ Type Objects
.. c:function:: PyObject* PyType_GetDict(PyTypeObject* type)

Return the type object's internal namespace, which is otherwise only
exposed via a read-only proxy (``cls.__dict__``). This is a
exposed via a read-only proxy (:attr:`cls.__dict__ <type.__dict__>`).
This is a
replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly.
The returned dictionary must be treated as read-only.

Expand Down Expand Up @@ -140,7 +141,7 @@ Type Objects
Return true if *a* is a subtype of *b*.

This function only checks for actual subtypes, which means that
:meth:`~class.__subclasscheck__` is not called on *b*. Call
:meth:`~type.__subclasscheck__` is not called on *b*. Call
:c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
would do.

Expand Down Expand Up @@ -174,14 +175,15 @@ Type Objects

.. c:function:: PyObject* PyType_GetName(PyTypeObject *type)

Return the type's name. Equivalent to getting the type's ``__name__`` attribute.
Return the type's name. Equivalent to getting the type's
:attr:`~type.__name__` attribute.

.. versionadded:: 3.11

.. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)

Return the type's qualified name. Equivalent to getting the
type's ``__qualname__`` attribute.
type's :attr:`~type.__qualname__` attribute.

.. versionadded:: 3.11

Expand Down
14 changes: 7 additions & 7 deletions Doc/c-api/typeobj.rst
Original file line number Diff line number Diff line change
Expand Up @@ -589,12 +589,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)

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

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

.. c:macro:: Py_TPFLAGS_MANAGED_DICT

This bit indicates that instances of the class have a ``__dict__``
This bit indicates that instances of the class have a `~object.__dict__`
attribute, and that the space for the dictionary is managed by the VM.

If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
Expand Down Expand Up @@ -1350,8 +1350,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: const char* PyTypeObject.tp_doc

An optional pointer to a NUL-terminated C string giving the docstring for this
type object. This is exposed as the :attr:`__doc__` attribute on the type and
instances of the type.
type object. This is exposed as the :attr:`~type.__doc__` attribute on the
type and instances of the type.

**Inheritance:**

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

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

.. versionchanged:: 3.12

Expand Down
2 changes: 1 addition & 1 deletion Doc/extending/newtypes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -296,7 +296,7 @@ An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table
descriptors that are used at runtime is that any attribute defined this way can
have an associated doc string simply by providing the text in the table. An
application can use the introspection API to retrieve the descriptor from the
class object, and get the doc string using its :attr:`!__doc__` attribute.
class object, and get the doc string using its :attr:`~type.__doc__` attribute.

As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
of ``NULL`` is required.
Expand Down
2 changes: 1 addition & 1 deletion Doc/extending/newtypes_tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ only used for variable-sized objects and should otherwise be zero.
If you want your type to be subclassable from Python, and your type has the same
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
inheritance. A Python subclass of your type will have to list your type first
in its :attr:`~class.__bases__`, or else it will not be able to call your type's
in its :attr:`~type.__bases__`, or else it will not be able to call your type's
:meth:`~object.__new__` method without getting an error. You can avoid this problem by
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
base type does. Most of the time, this will be true anyway, because either your
Expand Down
2 changes: 1 addition & 1 deletion Doc/faq/programming.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1614,7 +1614,7 @@ method too, and it must do so carefully. The basic implementation of
...

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


Expand Down
4 changes: 2 additions & 2 deletions Doc/glossary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -350,7 +350,7 @@ Glossary
docstring
A string literal which appears as the first expression in a class,
function or module. While ignored when the suite is executed, it is
recognized by the compiler and put into the :attr:`!__doc__` attribute
recognized by the compiler and put into the :attr:`~definition.__doc__` attribute
of the enclosing class, function or module. Since it is available via
introspection, it is the canonical place for documentation of the
object.
Expand Down Expand Up @@ -1201,7 +1201,7 @@ Glossary
type
The type of a Python object determines what kind of object it is; every
object has a type. An object's type is accessible as its
:attr:`~instance.__class__` attribute or can be retrieved with
:attr:`~object.__class__` attribute or can be retrieved with
``type(obj)``.

type alias
Expand Down
8 changes: 4 additions & 4 deletions Doc/howto/annotations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,9 @@ Your code will have to have a separate code path if the object
you're examining is a class (``isinstance(o, type)``).
In that case, best practice relies on an implementation detail
of Python 3.9 and before: if a class has annotations defined,
they are stored in the class's ``__dict__`` dictionary. Since
they are stored in the class's :attr:`~type.__dict__` dictionary. Since
the class may or may not have annotations defined, best practice
is to call the ``get`` method on the class dict.
is to call the :meth:`~dict.get` method on the class dict.

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

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


Manually Un-Stringizing Stringized Annotations
Expand Down
4 changes: 2 additions & 2 deletions Doc/howto/descriptor.rst
Original file line number Diff line number Diff line change
Expand Up @@ -559,8 +559,8 @@ attribute access.

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

The details of invocation depend on whether ``obj`` is an object, class, or
instance of super.
Expand Down
2 changes: 1 addition & 1 deletion Doc/howto/enum.rst
Original file line number Diff line number Diff line change
Expand Up @@ -589,7 +589,7 @@ The solution is to specify the module name explicitly as follows::
the source, pickling will be disabled.

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

Expand Down
2 changes: 1 addition & 1 deletion Doc/howto/mro.rst
Original file line number Diff line number Diff line change
Expand Up @@ -335,7 +335,7 @@ E is more specialized than C, even if it is in a higher level.

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

>>> A.mro() # doctest: +NORMALIZE_WHITESPACE
[<class 'A'>, <class 'B'>, <class 'E'>,
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/abc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
that you can customize the behavior of :func:`issubclass` further without the
need to call :meth:`register` on every class you want to consider a
subclass of the ABC. (This class method is called from the
:meth:`~class.__subclasscheck__` method of the ABC.)
:meth:`~type.__subclasscheck__` method of the ABC.)

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

Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
even though it does not define an :meth:`~iterator.__iter__` method (it uses
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/collections.rst
Original file line number Diff line number Diff line change
Expand Up @@ -874,8 +874,8 @@ they add the ability to access fields by name instead of position index.
``(1, 2)``, then ``x`` will be a required argument, ``y`` will default to
``1``, and ``z`` will default to ``2``.

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

Named tuple instances do not have per-instance dictionaries, so they are
lightweight and require no more memory than regular tuples.
Expand Down
7 changes: 4 additions & 3 deletions Doc/library/email.contentmanager.rst
Original file line number Diff line number Diff line change
Expand Up @@ -58,11 +58,12 @@
* the type itself (``typ``)
* the type's fully qualified name (``typ.__module__ + '.' +
typ.__qualname__``).
* the type's qualname (``typ.__qualname__``)
* the type's name (``typ.__name__``).
* the type's :attr:`qualname <type.__qualname__>` (``typ.__qualname__``)
* the type's :attr:`name <type.__name__>` (``typ.__name__``).

If none of the above match, repeat all of the checks above for each of
the types in the :term:`MRO` (``typ.__mro__``). Finally, if no other key
the types in the :term:`MRO` (:attr:`typ.__mro__ <type.__mro__>`).
Finally, if no other key
yields a handler, check for a handler for the key ``None``. If there is
no handler for ``None``, raise a :exc:`KeyError` for the fully
qualified name of the type.
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/email.headerregistry.rst
Original file line number Diff line number Diff line change
Expand Up @@ -317,7 +317,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
class. When *use_default_map* is ``True`` (the default), the standard
mapping of header names to classes is copied in to the registry during
initialization. *base_class* is always the last class in the generated
class's ``__bases__`` list.
class's :class:`~type.__bases__` list.

The default mappings are:

Expand Down
48 changes: 27 additions & 21 deletions Doc/library/functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -283,9 +283,11 @@ are always available. They are listed here in alphabetical order.
:func:`property`.

.. versionchanged:: 3.10
Class methods now inherit the method attributes (``__module__``,
``__name__``, ``__qualname__``, ``__doc__`` and ``__annotations__``) and
have a new ``__wrapped__`` attribute.
Class methods now inherit the method attributes
(:attr:`~function.__module__`, :attr:`~function.__name__`,
:attr:`~function.__qualname__`, :attr:`~function.__doc__` and
:attr:`~function.__annotations__`) and have a new ``__wrapped__``
attribute.

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

.. note::

:class:`object` does *not* have a :attr:`~object.__dict__`, so you can't
assign arbitrary attributes to an instance of the :class:`object` class.
:class:`object` instances do *not* have :attr:`~object.__dict__`
attributes, so you can't assign arbitrary attributes to an instance of
:class:`object`.


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

.. versionchanged:: 3.10
Static methods now inherit the method attributes (``__module__``,
``__name__``, ``__qualname__``, ``__doc__`` and ``__annotations__``),
have a new ``__wrapped__`` attribute, and are now callable as regular
functions.
Static methods now inherit the method attributes
(:attr:`~function.__module__`, :attr:`~function.__name__`,
:attr:`~function.__qualname__`, :attr:`~function.__doc__` and
:attr:`~function.__annotations__`), have a new ``__wrapped__`` attribute,
and are now callable as regular functions.


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

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

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

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

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


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

>>> class X:
... a = 1
...
>>> X = type('X', (), dict(a=1))

See also :ref:`bltin-type-objects`.
See also:

* :ref:`Documentation on attributes and methods on classes <class-attrs-and-methods>`.
* :ref:`bltin-type-objects`

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

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

.. function:: vars()
vars(object)

Return the :attr:`~object.__dict__` attribute for a module, class, instance,
or any other object with a :attr:`~object.__dict__` attribute.
or any other object with a :attr:`!__dict__` attribute.

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

Without an argument, :func:`vars` acts like :func:`locals`. Note, the
Expand Down
Loading
Loading