mirror of
https://github.com/python/cpython.git
synced 2025-08-04 17:08:35 +00:00
gh-101100: Fix sphinx warnings in howto/* (#127084)
This commit is contained in:
Yuki Kobayashi
GitHub
parent
4fd9eb2aca
commit
733fe59206
3 changed files with 101 additions and 102 deletions
|
|
@ -42,7 +42,7 @@ add new capabilities one by one.
|
|||
Simple example: A descriptor that returns a constant
|
||||
----------------------------------------------------
|
||||
|
||||
The :class:`Ten` class is a descriptor whose :meth:`__get__` method always
|
||||
The :class:`!Ten` class is a descriptor whose :meth:`~object.__get__` method always
|
||||
returns the constant ``10``:
|
||||
|
||||
.. testcode::
|
||||
|
|
@ -120,10 +120,10 @@ different, updated answers each time::
|
|||
2
|
||||
|
||||
Besides showing how descriptors can run computations, this example also
|
||||
reveals the purpose of the parameters to :meth:`__get__`. The *self*
|
||||
reveals the purpose of the parameters to :meth:`~object.__get__`. The *self*
|
||||
parameter is *size*, an instance of *DirectorySize*. The *obj* parameter is
|
||||
either *g* or *s*, an instance of *Directory*. It is the *obj* parameter that
|
||||
lets the :meth:`__get__` method learn the target directory. The *objtype*
|
||||
lets the :meth:`~object.__get__` method learn the target directory. The *objtype*
|
||||
parameter is the class *Directory*.
|
||||
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ Managed attributes
|
|||
A popular use for descriptors is managing access to instance data. The
|
||||
descriptor is assigned to a public attribute in the class dictionary while the
|
||||
actual data is stored as a private attribute in the instance dictionary. The
|
||||
descriptor's :meth:`__get__` and :meth:`__set__` methods are triggered when
|
||||
descriptor's :meth:`~object.__get__` and :meth:`~object.__set__` methods are triggered when
|
||||
the public attribute is accessed.
|
||||
|
||||
In the following example, *age* is the public attribute and *_age* is the
|
||||
|
|
@ -215,9 +215,9 @@ Customized names
|
|||
When a class uses descriptors, it can inform each descriptor about which
|
||||
variable name was used.
|
||||
|
||||
In this example, the :class:`Person` class has two descriptor instances,
|
||||
*name* and *age*. When the :class:`Person` class is defined, it makes a
|
||||
callback to :meth:`__set_name__` in *LoggedAccess* so that the field names can
|
||||
In this example, the :class:`!Person` class has two descriptor instances,
|
||||
*name* and *age*. When the :class:`!Person` class is defined, it makes a
|
||||
callback to :meth:`~object.__set_name__` in *LoggedAccess* so that the field names can
|
||||
be recorded, giving each descriptor its own *public_name* and *private_name*:
|
||||
|
||||
.. testcode::
|
||||
|
|
@ -253,8 +253,8 @@ be recorded, giving each descriptor its own *public_name* and *private_name*:
|
|||
def birthday(self):
|
||||
self.age += 1
|
||||
|
||||
An interactive session shows that the :class:`Person` class has called
|
||||
:meth:`__set_name__` so that the field names would be recorded. Here
|
||||
An interactive session shows that the :class:`!Person` class has called
|
||||
:meth:`~object.__set_name__` so that the field names would be recorded. Here
|
||||
we call :func:`vars` to look up the descriptor without triggering it:
|
||||
|
||||
.. doctest::
|
||||
|
|
@ -294,10 +294,10 @@ The two *Person* instances contain only the private names:
|
|||
Closing thoughts
|
||||
----------------
|
||||
|
||||
A :term:`descriptor` is what we call any object that defines :meth:`__get__`,
|
||||
:meth:`__set__`, or :meth:`__delete__`.
|
||||
A :term:`descriptor` is what we call any object that defines :meth:`~object.__get__`,
|
||||
:meth:`~object.__set__`, or :meth:`~object.__delete__`.
|
||||
|
||||
Optionally, descriptors can have a :meth:`__set_name__` method. This is only
|
||||
Optionally, descriptors can have a :meth:`~object.__set_name__` method. This is only
|
||||
used in cases where a descriptor needs to know either the class where it was
|
||||
created or the name of class variable it was assigned to. (This method, if
|
||||
present, is called even if the class is not a descriptor.)
|
||||
|
|
@ -337,7 +337,7 @@ any data, it verifies that the new value meets various type and range
|
|||
restrictions. If those restrictions aren't met, it raises an exception to
|
||||
prevent data corruption at its source.
|
||||
|
||||
This :class:`Validator` class is both an :term:`abstract base class` and a
|
||||
This :class:`!Validator` class is both an :term:`abstract base class` and a
|
||||
managed attribute descriptor:
|
||||
|
||||
.. testcode::
|
||||
|
|
@ -360,8 +360,8 @@ managed attribute descriptor:
|
|||
def validate(self, value):
|
||||
pass
|
||||
|
||||
Custom validators need to inherit from :class:`Validator` and must supply a
|
||||
:meth:`validate` method to test various restrictions as needed.
|
||||
Custom validators need to inherit from :class:`!Validator` and must supply a
|
||||
:meth:`!validate` method to test various restrictions as needed.
|
||||
|
||||
|
||||
Custom validators
|
||||
|
|
@ -369,13 +369,13 @@ Custom validators
|
|||
|
||||
Here are three practical data validation utilities:
|
||||
|
||||
1) :class:`OneOf` verifies that a value is one of a restricted set of options.
|
||||
1) :class:`!OneOf` verifies that a value is one of a restricted set of options.
|
||||
|
||||
2) :class:`Number` verifies that a value is either an :class:`int` or
|
||||
2) :class:`!Number` verifies that a value is either an :class:`int` or
|
||||
:class:`float`. Optionally, it verifies that a value is between a given
|
||||
minimum or maximum.
|
||||
|
||||
3) :class:`String` verifies that a value is a :class:`str`. Optionally, it
|
||||
3) :class:`!String` verifies that a value is a :class:`str`. Optionally, it
|
||||
validates a given minimum or maximum length. It can validate a
|
||||
user-defined `predicate
|
||||
<https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)>`_ as well.
|
||||
|
|
@ -501,8 +501,8 @@ Definition and introduction
|
|||
---------------------------
|
||||
|
||||
In general, a descriptor is an attribute value that has one of the methods in
|
||||
the descriptor protocol. Those methods are :meth:`__get__`, :meth:`__set__`,
|
||||
and :meth:`__delete__`. If any of those methods are defined for an
|
||||
the descriptor protocol. Those methods are :meth:`~object.__get__`, :meth:`~object.__set__`,
|
||||
and :meth:`~object.__delete__`. If any of those methods are defined for an
|
||||
attribute, it is said to be a :term:`descriptor`.
|
||||
|
||||
The default behavior for attribute access is to get, set, or delete the
|
||||
|
|
@ -534,8 +534,8 @@ That is all there is to it. Define any of these methods and an object is
|
|||
considered a descriptor and can override default behavior upon being looked up
|
||||
as an attribute.
|
||||
|
||||
If an object defines :meth:`__set__` or :meth:`__delete__`, it is considered
|
||||
a data descriptor. Descriptors that only define :meth:`__get__` are called
|
||||
If an object defines :meth:`~object.__set__` or :meth:`~object.__delete__`, it is considered
|
||||
a data descriptor. Descriptors that only define :meth:`~object.__get__` are called
|
||||
non-data descriptors (they are often used for methods but other uses are
|
||||
possible).
|
||||
|
||||
|
|
@ -545,9 +545,9 @@ has an entry with the same name as a data descriptor, the data descriptor
|
|||
takes precedence. If an instance's dictionary has an entry with the same
|
||||
name as a non-data descriptor, the dictionary entry takes precedence.
|
||||
|
||||
To make a read-only data descriptor, define both :meth:`__get__` and
|
||||
:meth:`__set__` with the :meth:`__set__` raising an :exc:`AttributeError` when
|
||||
called. Defining the :meth:`__set__` method with an exception raising
|
||||
To make a read-only data descriptor, define both :meth:`~object.__get__` and
|
||||
:meth:`~object.__set__` with the :meth:`~object.__set__` raising an :exc:`AttributeError` when
|
||||
called. Defining the :meth:`~object.__set__` method with an exception raising
|
||||
placeholder is enough to make it a data descriptor.
|
||||
|
||||
|
||||
|
|
@ -574,7 +574,7 @@ Invocation from an instance
|
|||
|
||||
Instance lookup scans through a chain of namespaces giving data descriptors
|
||||
the highest priority, followed by instance variables, then non-data
|
||||
descriptors, then class variables, and lastly :meth:`__getattr__` if it is
|
||||
descriptors, then class variables, and lastly :meth:`~object.__getattr__` if it is
|
||||
provided.
|
||||
|
||||
If a descriptor is found for ``a.x``, then it is invoked with:
|
||||
|
|
@ -719,12 +719,12 @@ a pure Python equivalent:
|
|||
>>> object_getattribute(u2, 'x') == u2.x == (D1, u2, U2)
|
||||
True
|
||||
|
||||
Note, there is no :meth:`__getattr__` hook in the :meth:`__getattribute__`
|
||||
code. That is why calling :meth:`__getattribute__` directly or with
|
||||
``super().__getattribute__`` will bypass :meth:`__getattr__` entirely.
|
||||
Note, there is no :meth:`~object.__getattr__` hook in the :meth:`~object.__getattribute__`
|
||||
code. That is why calling :meth:`~object.__getattribute__` directly or with
|
||||
``super().__getattribute__`` will bypass :meth:`~object.__getattr__` entirely.
|
||||
|
||||
Instead, it is the dot operator and the :func:`getattr` function that are
|
||||
responsible for invoking :meth:`__getattr__` whenever :meth:`__getattribute__`
|
||||
responsible for invoking :meth:`~object.__getattr__` whenever :meth:`~object.__getattribute__`
|
||||
raises an :exc:`AttributeError`. Their logic is encapsulated in a helper
|
||||
function:
|
||||
|
||||
|
|
@ -776,8 +776,8 @@ Invocation from a class
|
|||
-----------------------
|
||||
|
||||
The logic for a dotted lookup such as ``A.x`` is in
|
||||
:meth:`type.__getattribute__`. The steps are similar to those for
|
||||
:meth:`object.__getattribute__` but the instance dictionary lookup is replaced
|
||||
:meth:`!type.__getattribute__`. The steps are similar to those for
|
||||
:meth:`!object.__getattribute__` but the instance dictionary lookup is replaced
|
||||
by a search through the class's :term:`method resolution order`.
|
||||
|
||||
If a descriptor is found, it is invoked with ``desc.__get__(None, A)``.
|
||||
|
|
@ -789,7 +789,7 @@ The full C implementation can be found in :c:func:`!type_getattro` and
|
|||
Invocation from super
|
||||
---------------------
|
||||
|
||||
The logic for super's dotted lookup is in the :meth:`__getattribute__` method for
|
||||
The logic for super's dotted lookup is in the :meth:`~object.__getattribute__` method for
|
||||
object returned by :func:`super`.
|
||||
|
||||
A dotted lookup such as ``super(A, obj).m`` searches ``obj.__class__.__mro__``
|
||||
|
|
@ -806,21 +806,21 @@ The full C implementation can be found in :c:func:`!super_getattro` in
|
|||
Summary of invocation logic
|
||||
---------------------------
|
||||
|
||||
The mechanism for descriptors is embedded in the :meth:`__getattribute__`
|
||||
The mechanism for descriptors is embedded in the :meth:`~object.__getattribute__`
|
||||
methods for :class:`object`, :class:`type`, and :func:`super`.
|
||||
|
||||
The important points to remember are:
|
||||
|
||||
* Descriptors are invoked by the :meth:`__getattribute__` method.
|
||||
* Descriptors are invoked by the :meth:`~object.__getattribute__` method.
|
||||
|
||||
* Classes inherit this machinery from :class:`object`, :class:`type`, or
|
||||
:func:`super`.
|
||||
|
||||
* Overriding :meth:`__getattribute__` prevents automatic descriptor calls
|
||||
* Overriding :meth:`~object.__getattribute__` prevents automatic descriptor calls
|
||||
because all the descriptor logic is in that method.
|
||||
|
||||
* :meth:`object.__getattribute__` and :meth:`type.__getattribute__` make
|
||||
different calls to :meth:`__get__`. The first includes the instance and may
|
||||
* :meth:`!object.__getattribute__` and :meth:`!type.__getattribute__` make
|
||||
different calls to :meth:`~object.__get__`. The first includes the instance and may
|
||||
include the class. The second puts in ``None`` for the instance and always
|
||||
includes the class.
|
||||
|
||||
|
|
@ -835,16 +835,16 @@ Automatic name notification
|
|||
Sometimes it is desirable for a descriptor to know what class variable name it
|
||||
was assigned to. When a new class is created, the :class:`type` metaclass
|
||||
scans the dictionary of the new class. If any of the entries are descriptors
|
||||
and if they define :meth:`__set_name__`, that method is called with two
|
||||
and if they define :meth:`~object.__set_name__`, that method is called with two
|
||||
arguments. The *owner* is the class where the descriptor is used, and the
|
||||
*name* is the class variable the descriptor was assigned to.
|
||||
|
||||
The implementation details are in :c:func:`!type_new` and
|
||||
:c:func:`!set_names` in :source:`Objects/typeobject.c`.
|
||||
|
||||
Since the update logic is in :meth:`type.__new__`, notifications only take
|
||||
Since the update logic is in :meth:`!type.__new__`, notifications only take
|
||||
place at the time of class creation. If descriptors are added to the class
|
||||
afterwards, :meth:`__set_name__` will need to be called manually.
|
||||
afterwards, :meth:`~object.__set_name__` will need to be called manually.
|
||||
|
||||
|
||||
ORM example
|
||||
|
|
@ -873,7 +873,7 @@ care of lookups or updates:
|
|||
conn.execute(self.store, [value, obj.key])
|
||||
conn.commit()
|
||||
|
||||
We can use the :class:`Field` class to define `models
|
||||
We can use the :class:`!Field` class to define `models
|
||||
<https://en.wikipedia.org/wiki/Database_model>`_ that describe the schema for
|
||||
each table in a database:
|
||||
|
||||
|
|
@ -1140,7 +1140,7 @@ to wrap access to the value attribute in a property data descriptor:
|
|||
self.recalc()
|
||||
return self._value
|
||||
|
||||
Either the built-in :func:`property` or our :func:`Property` equivalent would
|
||||
Either the built-in :func:`property` or our :func:`!Property` equivalent would
|
||||
work in this example.
|
||||
|
||||
|
||||
|
|
@ -1187,7 +1187,7 @@ roughly equivalent to:
|
|||
return self
|
||||
|
||||
To support automatic creation of methods, functions include the
|
||||
:meth:`__get__` method for binding methods during attribute access. This
|
||||
:meth:`~object.__get__` method for binding methods during attribute access. This
|
||||
means that functions are non-data descriptors that return bound methods
|
||||
during dotted lookup from an instance. Here's how it works:
|
||||
|
||||
|
|
@ -1231,19 +1231,19 @@ The function has a :term:`qualified name` attribute to support introspection:
|
|||
'D.f'
|
||||
|
||||
Accessing the function through the class dictionary does not invoke
|
||||
:meth:`__get__`. Instead, it just returns the underlying function object::
|
||||
:meth:`~object.__get__`. Instead, it just returns the underlying function object::
|
||||
|
||||
>>> D.__dict__['f']
|
||||
<function D.f at 0x00C45070>
|
||||
|
||||
Dotted access from a class calls :meth:`__get__` which just returns the
|
||||
Dotted access from a class calls :meth:`~object.__get__` which just returns the
|
||||
underlying function unchanged::
|
||||
|
||||
>>> D.f
|
||||
<function D.f at 0x00C45070>
|
||||
|
||||
The interesting behavior occurs during dotted access from an instance. The
|
||||
dotted lookup calls :meth:`__get__` which returns a bound method object::
|
||||
dotted lookup calls :meth:`~object.__get__` which returns a bound method object::
|
||||
|
||||
>>> d = D()
|
||||
>>> d.f
|
||||
|
|
@ -1268,7 +1268,7 @@ Kinds of methods
|
|||
Non-data descriptors provide a simple mechanism for variations on the usual
|
||||
patterns of binding functions into methods.
|
||||
|
||||
To recap, functions have a :meth:`__get__` method so that they can be converted
|
||||
To recap, functions have a :meth:`~object.__get__` method so that they can be converted
|
||||
to a method when accessed as attributes. The non-data descriptor transforms an
|
||||
``obj.f(*args)`` call into ``f(obj, *args)``. Calling ``cls.f(*args)``
|
||||
becomes ``f(*args)``.
|
||||
|
|
@ -1671,7 +1671,7 @@ by member descriptors:
|
|||
'Emulate member_repr() in Objects/descrobject.c'
|
||||
return f'<Member {self.name!r} of {self.clsname!r}>'
|
||||
|
||||
The :meth:`type.__new__` method takes care of adding member objects to class
|
||||
The :meth:`!type.__new__` method takes care of adding member objects to class
|
||||
variables:
|
||||
|
||||
.. testcode::
|
||||
|
|
@ -1722,7 +1722,7 @@ Python:
|
|||
)
|
||||
super().__delattr__(name)
|
||||
|
||||
To use the simulation in a real class, just inherit from :class:`Object` and
|
||||
To use the simulation in a real class, just inherit from :class:`!Object` and
|
||||
set the :term:`metaclass` to :class:`Type`:
|
||||
|
||||
.. testcode::
|
||||
|
|
|
|||
|
|
@ -64,12 +64,12 @@ The *type* of an enumeration member is the enum it belongs to::
|
|||
>>> isinstance(Weekday.FRIDAY, Weekday)
|
||||
True
|
||||
|
||||
Enum members have an attribute that contains just their :attr:`name`::
|
||||
Enum members have an attribute that contains just their :attr:`!name`::
|
||||
|
||||
>>> print(Weekday.TUESDAY.name)
|
||||
TUESDAY
|
||||
|
||||
Likewise, they have an attribute for their :attr:`value`::
|
||||
Likewise, they have an attribute for their :attr:`!value`::
|
||||
|
||||
|
||||
>>> Weekday.WEDNESDAY.value
|
||||
|
|
@ -77,17 +77,18 @@ Likewise, they have an attribute for their :attr:`value`::
|
|||
|
||||
Unlike many languages that treat enumerations solely as name/value pairs,
|
||||
Python Enums can have behavior added. For example, :class:`datetime.date`
|
||||
has two methods for returning the weekday: :meth:`weekday` and :meth:`isoweekday`.
|
||||
has two methods for returning the weekday:
|
||||
:meth:`~datetime.date.weekday` and :meth:`~datetime.date.isoweekday`.
|
||||
The difference is that one of them counts from 0-6 and the other from 1-7.
|
||||
Rather than keep track of that ourselves we can add a method to the :class:`Weekday`
|
||||
enum to extract the day from the :class:`date` instance and return the matching
|
||||
Rather than keep track of that ourselves we can add a method to the :class:`!Weekday`
|
||||
enum to extract the day from the :class:`~datetime.date` instance and return the matching
|
||||
enum member::
|
||||
|
||||
@classmethod
|
||||
def from_date(cls, date):
|
||||
return cls(date.isoweekday())
|
||||
|
||||
The complete :class:`Weekday` enum now looks like this::
|
||||
The complete :class:`!Weekday` enum now looks like this::
|
||||
|
||||
>>> class Weekday(Enum):
|
||||
... MONDAY = 1
|
||||
|
|
@ -110,7 +111,7 @@ Now we can find out what today is! Observe::
|
|||
|
||||
Of course, if you're reading this on some other day, you'll see that day instead.
|
||||
|
||||
This :class:`Weekday` enum is great if our variable only needs one day, but
|
||||
This :class:`!Weekday` enum is great if our variable only needs one day, but
|
||||
what if we need several? Maybe we're writing a function to plot chores during
|
||||
a week, and don't want to use a :class:`list` -- we could use a different type
|
||||
of :class:`Enum`::
|
||||
|
|
@ -128,7 +129,7 @@ of :class:`Enum`::
|
|||
We've changed two things: we're inherited from :class:`Flag`, and the values are
|
||||
all powers of 2.
|
||||
|
||||
Just like the original :class:`Weekday` enum above, we can have a single selection::
|
||||
Just like the original :class:`!Weekday` enum above, we can have a single selection::
|
||||
|
||||
>>> first_week_day = Weekday.MONDAY
|
||||
>>> first_week_day
|
||||
|
|
@ -203,7 +204,7 @@ If you want to access enum members by *name*, use item access::
|
|||
>>> Color['GREEN']
|
||||
<Color.GREEN: 2>
|
||||
|
||||
If you have an enum member and need its :attr:`name` or :attr:`value`::
|
||||
If you have an enum member and need its :attr:`!name` or :attr:`!value`::
|
||||
|
||||
>>> member = Color.RED
|
||||
>>> member.name
|
||||
|
|
@ -284,7 +285,7 @@ If the exact value is unimportant you can use :class:`auto`::
|
|||
>>> [member.value for member in Color]
|
||||
[1, 2, 3]
|
||||
|
||||
The values are chosen by :func:`_generate_next_value_`, which can be
|
||||
The values are chosen by :func:`~Enum._generate_next_value_`, which can be
|
||||
overridden::
|
||||
|
||||
>>> class AutoName(Enum):
|
||||
|
|
@ -303,7 +304,7 @@ overridden::
|
|||
|
||||
.. note::
|
||||
|
||||
The :meth:`_generate_next_value_` method must be defined before any members.
|
||||
The :meth:`~Enum._generate_next_value_` method must be defined before any members.
|
||||
|
||||
Iteration
|
||||
---------
|
||||
|
|
@ -424,18 +425,18 @@ Then::
|
|||
The rules for what is allowed are as follows: names that start and end with
|
||||
a single underscore are reserved by enum and cannot be used; all other
|
||||
attributes defined within an enumeration will become members of this
|
||||
enumeration, with the exception of special methods (:meth:`__str__`,
|
||||
:meth:`__add__`, etc.), descriptors (methods are also descriptors), and
|
||||
variable names listed in :attr:`_ignore_`.
|
||||
enumeration, with the exception of special methods (:meth:`~object.__str__`,
|
||||
:meth:`~object.__add__`, etc.), descriptors (methods are also descriptors), and
|
||||
variable names listed in :attr:`~Enum._ignore_`.
|
||||
|
||||
Note: if your enumeration defines :meth:`__new__` and/or :meth:`__init__`,
|
||||
Note: if your enumeration defines :meth:`~object.__new__` and/or :meth:`~object.__init__`,
|
||||
any value(s) given to the enum member will be passed into those methods.
|
||||
See `Planet`_ for an example.
|
||||
|
||||
.. note::
|
||||
|
||||
The :meth:`__new__` method, if defined, is used during creation of the Enum
|
||||
members; it is then replaced by Enum's :meth:`__new__` which is used after
|
||||
The :meth:`~object.__new__` method, if defined, is used during creation of the Enum
|
||||
members; it is then replaced by Enum's :meth:`~object.__new__` which is used after
|
||||
class creation for lookup of existing members. See :ref:`new-vs-init` for
|
||||
more details.
|
||||
|
||||
|
|
@ -544,7 +545,7 @@ from that module.
|
|||
nested in other classes.
|
||||
|
||||
It is possible to modify how enum members are pickled/unpickled by defining
|
||||
:meth:`__reduce_ex__` in the enumeration class. The default method is by-value,
|
||||
:meth:`~object.__reduce_ex__` in the enumeration class. The default method is by-value,
|
||||
but enums with complicated values may want to use by-name::
|
||||
|
||||
>>> import enum
|
||||
|
|
@ -580,7 +581,7 @@ values. The last two options enable assigning arbitrary values to
|
|||
enumerations; the others auto-assign increasing integers starting with 1 (use
|
||||
the ``start`` parameter to specify a different starting value). A
|
||||
new class derived from :class:`Enum` is returned. In other words, the above
|
||||
assignment to :class:`Animal` is equivalent to::
|
||||
assignment to :class:`!Animal` is equivalent to::
|
||||
|
||||
>>> class Animal(Enum):
|
||||
... ANT = 1
|
||||
|
|
@ -891,7 +892,7 @@ simple to implement independently::
|
|||
pass
|
||||
|
||||
This demonstrates how similar derived enumerations can be defined; for example
|
||||
a :class:`FloatEnum` that mixes in :class:`float` instead of :class:`int`.
|
||||
a :class:`!FloatEnum` that mixes in :class:`float` instead of :class:`int`.
|
||||
|
||||
Some rules:
|
||||
|
||||
|
|
@ -905,32 +906,32 @@ Some rules:
|
|||
additional type, all the members must have values of that type, e.g.
|
||||
:class:`int` above. This restriction does not apply to mix-ins which only
|
||||
add methods and don't specify another type.
|
||||
4. When another data type is mixed in, the :attr:`value` attribute is *not the
|
||||
4. When another data type is mixed in, the :attr:`~Enum.value` attribute is *not the
|
||||
same* as the enum member itself, although it is equivalent and will compare
|
||||
equal.
|
||||
5. A ``data type`` is a mixin that defines :meth:`__new__`, or a
|
||||
5. A ``data type`` is a mixin that defines :meth:`~object.__new__`, or a
|
||||
:class:`~dataclasses.dataclass`
|
||||
6. %-style formatting: ``%s`` and ``%r`` call the :class:`Enum` class's
|
||||
:meth:`__str__` and :meth:`__repr__` respectively; other codes (such as
|
||||
:meth:`~object.__str__` and :meth:`~object.__repr__` respectively; other codes (such as
|
||||
``%i`` or ``%h`` for IntEnum) treat the enum member as its mixed-in type.
|
||||
7. :ref:`Formatted string literals <f-strings>`, :meth:`str.format`,
|
||||
and :func:`format` will use the enum's :meth:`__str__` method.
|
||||
and :func:`format` will use the enum's :meth:`~object.__str__` method.
|
||||
|
||||
.. note::
|
||||
|
||||
Because :class:`IntEnum`, :class:`IntFlag`, and :class:`StrEnum` are
|
||||
designed to be drop-in replacements for existing constants, their
|
||||
:meth:`__str__` method has been reset to their data types'
|
||||
:meth:`__str__` method.
|
||||
:meth:`~object.__str__` method has been reset to their data types'
|
||||
:meth:`~object.__str__` method.
|
||||
|
||||
.. _new-vs-init:
|
||||
|
||||
When to use :meth:`__new__` vs. :meth:`__init__`
|
||||
------------------------------------------------
|
||||
When to use :meth:`~object.__new__` vs. :meth:`~object.__init__`
|
||||
----------------------------------------------------------------
|
||||
|
||||
:meth:`__new__` must be used whenever you want to customize the actual value of
|
||||
:meth:`~object.__new__` must be used whenever you want to customize the actual value of
|
||||
the :class:`Enum` member. Any other modifications may go in either
|
||||
:meth:`__new__` or :meth:`__init__`, with :meth:`__init__` being preferred.
|
||||
:meth:`~object.__new__` or :meth:`~object.__init__`, with :meth:`~object.__init__` being preferred.
|
||||
|
||||
For example, if you want to pass several items to the constructor, but only
|
||||
want one of them to be the value::
|
||||
|
|
@ -969,11 +970,11 @@ Finer Points
|
|||
Supported ``__dunder__`` names
|
||||
""""""""""""""""""""""""""""""
|
||||
|
||||
:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member``
|
||||
:attr:`~enum.EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
|
||||
items. It is only available on the class.
|
||||
|
||||
:meth:`__new__`, if specified, must create and return the enum members; it is
|
||||
also a very good idea to set the member's :attr:`_value_` appropriately. Once
|
||||
:meth:`~object.__new__`, if specified, must create and return the enum members; it is
|
||||
also a very good idea to set the member's :attr:`~Enum._value_` appropriately. Once
|
||||
all the members are created it is no longer used.
|
||||
|
||||
|
||||
|
|
@ -989,9 +990,9 @@ Supported ``_sunder_`` names
|
|||
from the final class
|
||||
- :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
|
||||
an enum member; may be overridden
|
||||
- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
|
||||
- :meth:`~EnumType._add_alias_` -- adds a new name as an alias to an existing
|
||||
member.
|
||||
- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
|
||||
- :meth:`~EnumType._add_value_alias_` -- adds a new value as an alias to an
|
||||
existing member. See `MultiValueEnum`_ for an example.
|
||||
|
||||
.. note::
|
||||
|
|
@ -1009,7 +1010,7 @@ Supported ``_sunder_`` names
|
|||
.. versionadded:: 3.7 ``_ignore_``
|
||||
.. versionadded:: 3.13 ``_add_alias_``, ``_add_value_alias_``
|
||||
|
||||
To help keep Python 2 / Python 3 code in sync an :attr:`_order_` attribute can
|
||||
To help keep Python 2 / Python 3 code in sync an :attr:`~Enum._order_` attribute can
|
||||
be provided. It will be checked against the actual order of the enumeration
|
||||
and raise an error if the two do not match::
|
||||
|
||||
|
|
@ -1027,7 +1028,7 @@ and raise an error if the two do not match::
|
|||
|
||||
.. note::
|
||||
|
||||
In Python 2 code the :attr:`_order_` attribute is necessary as definition
|
||||
In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
|
||||
order is lost before it can be recorded.
|
||||
|
||||
|
||||
|
|
@ -1216,12 +1217,12 @@ Enum Classes
|
|||
^^^^^^^^^^^^
|
||||
|
||||
The :class:`EnumType` metaclass is responsible for providing the
|
||||
:meth:`__contains__`, :meth:`__dir__`, :meth:`__iter__` and other methods that
|
||||
:meth:`~object.__contains__`, :meth:`~object.__dir__`, :meth:`~object.__iter__` and other methods that
|
||||
allow one to do things with an :class:`Enum` class that fail on a typical
|
||||
class, such as ``list(Color)`` or ``some_enum_var in Color``. :class:`EnumType` is
|
||||
responsible for ensuring that various other methods on the final :class:`Enum`
|
||||
class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`,
|
||||
:meth:`__str__` and :meth:`__repr__`).
|
||||
class are correct (such as :meth:`~object.__new__`, :meth:`~object.__getnewargs__`,
|
||||
:meth:`~object.__str__` and :meth:`~object.__repr__`).
|
||||
|
||||
Flag Classes
|
||||
^^^^^^^^^^^^
|
||||
|
|
@ -1236,7 +1237,7 @@ Enum Members (aka instances)
|
|||
|
||||
The most interesting thing about enum members is that they are singletons.
|
||||
:class:`EnumType` creates them all while it is creating the enum class itself,
|
||||
and then puts a custom :meth:`__new__` in place to ensure that no new ones are
|
||||
and then puts a custom :meth:`~object.__new__` in place to ensure that no new ones are
|
||||
ever instantiated by returning only the existing member instances.
|
||||
|
||||
Flag Members
|
||||
|
|
@ -1284,7 +1285,7 @@ is. There are several ways to define this type of simple enumeration:
|
|||
- use instances of :class:`auto` for the value
|
||||
- use instances of :class:`object` as the value
|
||||
- use a descriptive string as the value
|
||||
- use a tuple as the value and a custom :meth:`__new__` to replace the
|
||||
- use a tuple as the value and a custom :meth:`~object.__new__` to replace the
|
||||
tuple with an :class:`int` value
|
||||
|
||||
Using any of these methods signifies to the user that these values are not
|
||||
|
|
@ -1320,7 +1321,7 @@ Using :class:`object` would look like::
|
|||
<Color.GREEN: <object object at 0x...>>
|
||||
|
||||
This is also a good example of why you might want to write your own
|
||||
:meth:`__repr__`::
|
||||
:meth:`~object.__repr__`::
|
||||
|
||||
>>> class Color(Enum):
|
||||
... RED = object()
|
||||
|
|
@ -1348,10 +1349,10 @@ Using a string as the value would look like::
|
|||
<Color.GREEN: 'go'>
|
||||
|
||||
|
||||
Using a custom :meth:`__new__`
|
||||
""""""""""""""""""""""""""""""
|
||||
Using a custom :meth:`~object.__new__`
|
||||
""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
Using an auto-numbering :meth:`__new__` would look like::
|
||||
Using an auto-numbering :meth:`~object.__new__` would look like::
|
||||
|
||||
>>> class AutoNumber(Enum):
|
||||
... def __new__(cls):
|
||||
|
|
@ -1397,8 +1398,8 @@ to handle any extra arguments::
|
|||
|
||||
.. note::
|
||||
|
||||
The :meth:`__new__` method, if defined, is used during creation of the Enum
|
||||
members; it is then replaced by Enum's :meth:`__new__` which is used after
|
||||
The :meth:`~object.__new__` method, if defined, is used during creation of the Enum
|
||||
members; it is then replaced by Enum's :meth:`~object.__new__` which is used after
|
||||
class creation for lookup of existing members.
|
||||
|
||||
.. warning::
|
||||
|
|
@ -1504,7 +1505,7 @@ Supports having more than one value per member::
|
|||
Planet
|
||||
^^^^^^
|
||||
|
||||
If :meth:`__new__` or :meth:`__init__` is defined, the value of the enum member
|
||||
If :meth:`~object.__new__` or :meth:`~object.__init__` is defined, the value of the enum member
|
||||
will be passed to those methods::
|
||||
|
||||
>>> class Planet(Enum):
|
||||
|
|
@ -1535,7 +1536,7 @@ will be passed to those methods::
|
|||
TimePeriod
|
||||
^^^^^^^^^^
|
||||
|
||||
An example to show the :attr:`_ignore_` attribute in use::
|
||||
An example to show the :attr:`~Enum._ignore_` attribute in use::
|
||||
|
||||
>>> from datetime import timedelta
|
||||
>>> class Period(timedelta, Enum):
|
||||
|
|
|
|||
|
|
@ -13,8 +13,6 @@ Doc/c-api/type.rst
|
|||
Doc/c-api/typeobj.rst
|
||||
Doc/extending/extending.rst
|
||||
Doc/glossary.rst
|
||||
Doc/howto/descriptor.rst
|
||||
Doc/howto/enum.rst
|
||||
Doc/library/ast.rst
|
||||
Doc/library/asyncio-extending.rst
|
||||
Doc/library/asyncio-subprocess.rst
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue