[Python-checkins] r80081 - python/trunk/Doc/reference/datamodel.rst

[georg.brandl]

Author: georg.brandl
Date: Wed Apr 14 23:34:44 2010
New Revision: 80081

Log:
#5250: document __instancecheck__ and __subclasscheck__.  I hope the part about the class/metaclass distinction is understandable.

Modified:
   python/trunk/Doc/reference/datamodel.rst

Modified: python/trunk/Doc/reference/datamodel.rst
==============================================================================
--- python/trunk/Doc/reference/datamodel.rst	(original)
+++ python/trunk/Doc/reference/datamodel.rst	Wed Apr 14 23:34:44 2010
@@ -1762,6 +1762,48 @@
 locking/synchronization.
 
 
+Customizing instance and subclass checks
+----------------------------------------
+
+.. versionadded:: 2.6
+
+The following methods are used to override the default behavior of the
+:func:`isinstance` and :func:`issubclass` built-in functions.
+
+In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
+order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
+classes" to any class or type (including built-in types), and including to other
+ABCs.
+
+.. method:: class.__instancecheck__(self, instance)
+
+   Return true if *instance* should be considered a (direct or indirect)
+   instance of *class*. If defined, called to implement ``isinstance(instance,
+   class)``.
+
+
+.. method:: class.__subclasscheck__(self, subclass)
+
+   Return true if *subclass* should be considered a (direct or indirect)
+   subclass of *class*.  If defined, called to implement ``issubclass(subclass,
+   class)``.
+
+
+Note that these methods are looked up on the type (metaclass) of a class.  They
+cannot be defined as class methods in the actual class.  This is consistent with
+the lookup of special methods that called on instances, only that in this case
+the instance is itself a class.
+
+.. seealso::
+
+   :pep:`3119` - Introducing Abstract Base Classes
+      Includes the specification for customizing :func:`isinstance` and
+      :func:`issubclass` behavior through :meth:`__instancecheck__` and
+      :meth:`__subclasscheck__`, with motivation for this functionality in the
+      context of adding Abstract Base Classes (see the :mod:`abc` module) to the
+      language.
+
+
 .. _callable-types:
 
 Emulating callable objects