Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(11)

Unified Diff: Doc/reference/datamodel.rst

Issue 25958: Implicit ABCs have no means of "anti-registration"
Patch Set: Created 3 years, 6 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « Doc/library/collections.abc.rst ('k') | Lib/_collections_abc.py » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
--- a/Doc/reference/datamodel.rst Mon Aug 15 03:23:23 2016 -0400
+++ b/Doc/reference/datamodel.rst Mon Aug 15 23:52:53 2016 +0200
@@ -1063,6 +1063,12 @@
operation raise an exception when no appropriate method is defined (typically
:exc:`AttributeError` or :exc:`TypeError`).
+Setting a special method to ``None`` indicates that the corresponding
+operation is not available. For example, if a class sets
+:meth:`__iter__` to ``None``, the class is not iterable, so calling
+:func:`iter` on its instances will raise a :exc:`TypeError` (without
+falling back to :meth:`__getitem__`). [#]_
+
When implementing a class that emulates any built-in type, it is important that
the emulation only be implemented to the degree that it makes sense for the
object being modelled. For example, some sequences may work well with retrieval
@@ -2113,7 +2119,7 @@
(``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`,
:func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected
(swapped) operands. These functions are only called if the left operand does
- not support the corresponding operation and the operands are of different
+ not support the corresponding operation [#]_ and the operands are of different
types. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
an instance of a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)``
is called if ``x.__sub__(y)`` returns *NotImplemented*.
@@ -2529,6 +2535,17 @@
controlled conditions. It generally isn't a good idea though, since it can
lead to some very strange behaviour if it is handled incorrectly.
+.. [#] The :meth:`__hash__`, :meth:`__iter__`, :meth:`__reversed__`, and
+ :meth:`__contains__` methods have special handling for this; others
+ will still raise a :exc:`TypeError`, but may do so by relying on
+ the behavior that ``None`` is not callable.
+
+.. [#] "Does not support" here means that the class has no such method, or
+ the method returns ``NotImplemented``. Do not set the method to
+ ``None`` if you want to force fallback to the right operand's reflected
+ method--that will instead have the opposite effect of explicitly
+ *blocking* such fallback.
+
.. [#] For operands of the same type, it is assumed that if the non-reflected method
(such as :meth:`__add__`) fails the operation is not supported, which is why the
reflected method is not called.
« no previous file with comments | « Doc/library/collections.abc.rst ('k') | Lib/_collections_abc.py » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+