From: Georg Brandl <georg@python.org>
Date: Wed, 14 Apr 2010 21:34:44 +0000 (+0000)
Subject: #5250: document __instancecheck__ and __subclasscheck__.  I hope the part about the... 
X-Git-Tag: v2.7b2~278
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=710a5dbc4a3f2eca2e9ec115b978d4c4cf5a8aea;p=python

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

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 2dcaed2f5b..9b187150ae 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1762,6 +1762,48 @@ property creation, proxies, frameworks, and automatic resource
 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