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::
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*.
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
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::
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::
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.)
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::
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
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.
---------------------------
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
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).
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.
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:
>>> 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:
-----------------------
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)``.
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__``
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.
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
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:
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.
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:
'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
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)``.
'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::
)
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::
>>> 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
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
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`::
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
>>> 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
>>> [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):
.. 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
---------
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.
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
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
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:
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::
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.
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::
.. 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::
.. 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.
^^^^^^^^^^^^
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
^^^^^^^^^^^^
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
- 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
<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()
<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):
.. 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::
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):
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):
projects / thirdparty / Python / cpython.git / commitdiff
