Merged revisions 81365,81367 via svnmerge from

svn+ssh://svn.python.org/python/branches/py3k

................
  r81365 | georg.brandl | 2010-05-19 22:57:08 +0200 (Mi, 19 Mai 2010) | 77 lines

  Merged revisions 80030,80067,80069,80080-80081,80084,80432-80433,80465-80470,81059,81065-81067 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r80030 | georg.brandl | 2010-04-13 08:43:54 +0200 (Di, 13 Apr 2010) | 1 line

    Get rid of multi-row cells.
  ........
    r80067 | georg.brandl | 2010-04-14 10:53:38 +0200 (Mi, 14 Apr 2010) | 1 line

    #5341: typo.
  ........
    r80069 | georg.brandl | 2010-04-14 15:50:31 +0200 (Mi, 14 Apr 2010) | 1 line

    Add an x-ref to where the O_ constants are documented and move the SEEK_ constants after lseek().
  ........
    r80080 | georg.brandl | 2010-04-14 21:16:38 +0200 (Mi, 14 Apr 2010) | 1 line

    #8399: add note about Windows and O_BINARY.
  ........
    r80081 | georg.brandl | 2010-04-14 23:34:44 +0200 (Mi, 14 Apr 2010) | 1 line

    #5250: document __instancecheck__ and __subclasscheck__.  I hope the part about the class/metaclass distinction is understandable.
  ........
    r80084 | georg.brandl | 2010-04-14 23:46:45 +0200 (Mi, 14 Apr 2010) | 1 line

    Fix missing.
  ........
    r80432 | georg.brandl | 2010-04-24 10:56:58 +0200 (Sa, 24 Apr 2010) | 1 line

    Markup fixes.
  ........
    r80433 | georg.brandl | 2010-04-24 11:08:10 +0200 (Sa, 24 Apr 2010) | 1 line

    #7507: quote "!" in pipes.quote(); it is a special character for some shells.
  ........
    r80465 | georg.brandl | 2010-04-25 12:29:17 +0200 (So, 25 Apr 2010) | 1 line

    Remove LaTeXy index entry syntax.
  ........
    r80466 | georg.brandl | 2010-04-25 12:54:42 +0200 (So, 25 Apr 2010) | 1 line

    Patch from Tim Hatch: Better cross-referencing in socket and winreg docs.
  ........
    r80467 | georg.brandl | 2010-04-25 12:55:16 +0200 (So, 25 Apr 2010) | 1 line

    Patch from Tim Hatch: Remove reference to winreg being the fabled high-level registry interface.
  ........
    r80468 | georg.brandl | 2010-04-25 12:55:58 +0200 (So, 25 Apr 2010) | 1 line

    Patch from Tim Hatch: Minor spelling changes to _winreg docs.
  ........
    r80469 | georg.brandl | 2010-04-25 12:56:41 +0200 (So, 25 Apr 2010) | 1 line

    Fix code example to have valid syntax so that it can be highlighted.
  ........
    r80470 | georg.brandl | 2010-04-25 12:57:15 +0200 (So, 25 Apr 2010) | 1 line

    Patch from Tim Hatch: Make socket setblocking <-> settimeout examples symmetric.
  ........
    r81059 | georg.brandl | 2010-05-10 23:02:51 +0200 (Mo, 10 Mai 2010) | 1 line

    #8642: fix wrong function name.
  ........
    r81065 | georg.brandl | 2010-05-10 23:46:50 +0200 (Mo, 10 Mai 2010) | 1 line

    Fix reference direction.
  ........
    r81066 | georg.brandl | 2010-05-10 23:50:57 +0200 (Mo, 10 Mai 2010) | 1 line

    Consolidate deprecation messages.
  ........
    r81067 | georg.brandl | 2010-05-10 23:51:33 +0200 (Mo, 10 Mai 2010) | 1 line

    Fix typo.
  ........
................
  r81367 | georg.brandl | 2010-05-19 23:03:51 +0200 (Mi, 19 Mai 2010) | 21 lines

  Recorded merge of revisions 80466-80469 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r80466 | georg.brandl | 2010-04-25 12:54:42 +0200 (So, 25 Apr 2010) | 1 line

    Patch from Tim Hatch: Better cross-referencing in socket and winreg docs.
  ........
    r80467 | georg.brandl | 2010-04-25 12:55:16 +0200 (So, 25 Apr 2010) | 1 line

    Patch from Tim Hatch: Remove reference to winreg being the fabled high-level registry interface.
  ........
    r80468 | georg.brandl | 2010-04-25 12:55:58 +0200 (So, 25 Apr 2010) | 1 line

    Patch from Tim Hatch: Minor spelling changes to _winreg docs.
  ........
    r80469 | georg.brandl | 2010-04-25 12:56:41 +0200 (So, 25 Apr 2010) | 1 line

    Fix code example to have valid syntax so that it can be highlighted.
  ........
................

8 files changed, 136 insertions, 81 deletions

diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index aaff852..e21c1ed 100644
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -8,8 +8,8 @@
 
 
 .. index::
-   pair: UNIX@Unix; file control
-   pair: UNIX@Unix; I/O control
+   pair: UNIX; file control
+   pair: UNIX; I/O control
 
 This module performs file control and I/O control on file descriptors. It is an
 interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index bd35728..9a3b305 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -46,14 +46,6 @@ The module defines the following items:
    connection attempt (if is not specified, the global default timeout setting
    will be used).
 
-   .. attribute:: all_errors
-
-      The set of all exceptions (as a tuple) that methods of :class:`FTP`
-      instances may raise as a result of problems with the FTP connection (as
-      opposed to programming errors made by the caller).  This set includes the
-      four exceptions listed below as well as :exc:`socket.error` and
-      :exc:`IOError`.
-
 
 .. exception:: error_reply
 
@@ -76,6 +68,15 @@ The module defines the following items:
    with a digit in the range 1--5.
 
 
+.. data:: all_errors
+
+   The set of all exceptions (as a tuple) that methods of :class:`FTP`
+   instances may raise as a result of problems with the FTP connection (as
+   opposed to programming errors made by the caller).  This set includes the
+   four exceptions listed above as well as :exc:`socket.error` and
+   :exc:`IOError`.
+
+
 .. seealso::
 
    Module :mod:`netrc`
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index e9cae7c..8bbd6cb 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -235,7 +235,7 @@ I/O Base Classes
 
       Flush and close this stream. This method has no effect if the file is
       already closed. Once the file is closed, any operation on the file
-      (e.g. reading or writing) will raise an :exc:`ValueError`.
+      (e.g. reading or writing) will raise a :exc:`ValueError`.
 
       As a convenience, it is allowed to call this method more than once;
       only the first call, however, will have an effect.
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index 6ad95b2..e1f5cf2 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -209,7 +209,7 @@ Basic Usage
    specified.  Encodings that are not ASCII based (such as UCS-2) are not
    allowed and should be decoded to :class:`str` first.
 
-   The other arguments have the same meaning as in :func:`dump`.
+   The other arguments have the same meaning as in :func:`load`.
 
 
 Encoders and decoders
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index b14dc92..28d8c53 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -584,6 +584,14 @@ by file descriptors.
    Availability: Unix, Windows.
 
 
+.. data:: SEEK_SET
+          SEEK_CUR
+          SEEK_END
+
+   Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
+   respectively. Availability: Windows, Unix.
+
+
 .. function:: open(file, flags[, mode])
 
    Open the file *file* and set various flags according to *flags* and possibly
@@ -593,7 +601,8 @@ by file descriptors.
 
    For a description of the flag and mode values, see the C run-time documentation;
    flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
-   this module too (see below).
+   this module too (see :ref:`open-constants`).  In particular, on Windows adding
+   :const:`O_BINARY` is needed to open files in binary mode.
 
    Availability: Unix, Windows.
 
@@ -681,6 +690,12 @@ by file descriptors.
       :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
       :meth:`~file.write` method.
 
+
+.. _open-constants:
+
+``open()`` flag constants
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The following constants are options for the *flags* parameter to the
 :func:`~os.open` function.  They can be combined using the bitwise OR operator
 ``|``.  Some of them are not available on all platforms.  For descriptions of
@@ -732,14 +747,6 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
    the C library.
 
 
-.. data:: SEEK_SET
-          SEEK_CUR
-          SEEK_END
-
-   Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
-   respectively. Availability: Windows, Unix.
-
-
 .. _os-file-dir:
 
 Files and Directories
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 60dc02e..75454cb 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -90,8 +90,9 @@ All errors raise exceptions.  The normal exceptions for invalid argument types
 and out-of-memory conditions can be raised; errors related to socket or address
 semantics raise the error :exc:`socket.error`.
 
-Non-blocking mode is supported through :meth:`setblocking`.  A generalization of
-this based on timeouts is supported through :meth:`settimeout`.
+Non-blocking mode is supported through :meth:`~socket.setblocking`.  A
+generalization of this based on timeouts is supported through
+:meth:`~socket.settimeout`.
 
 The module :mod:`socket` exports the following constants and functions:
 
@@ -553,7 +554,9 @@ correspond to Unix system calls applicable to sockets.
    :platform: Windows
 
    The :meth:`ioctl` method is a limited interface to the WSAIoctl system
-   interface. Please refer to the MSDN documentation for more information.
+   interface.  Please refer to the `Win32 documentation
+   <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
+   information.
 
    On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
    functions may be used; they accept a socket object as their first argument.
@@ -656,7 +659,7 @@ correspond to Unix system calls applicable to sockets.
    blocking mode.  In non-blocking mode, if a :meth:`recv` call doesn't find any
    data, or if a :meth:`send` call can't immediately dispose of the data, a
    :exc:`error` exception is raised; in blocking mode, the calls block until they
-   can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
+   can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``;
    ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
 
 
@@ -685,21 +688,21 @@ the system returns an error (such as connection timed out).  In
 non-blocking mode, operations fail (with an error that is unfortunately
 system-dependent) if they cannot be completed immediately.  In timeout mode,
 operations fail if they cannot be completed within the timeout specified for the
-socket or if the system returns an error.  The :meth:`setblocking` method is simply
-a shorthand for certain :meth:`settimeout` calls.
+socket or if the system returns an error.  The :meth:`~socket.setblocking`
+method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
 
 Timeout mode internally sets the socket in non-blocking mode.  The blocking and
 timeout modes are shared between file descriptors and socket objects that refer
 to the same network endpoint.  A consequence of this is that file objects
-returned by the :meth:`makefile` method must only be used when the socket is in
-blocking mode; in timeout or non-blocking mode file operations that cannot be
-completed immediately will fail.
+returned by the :meth:`~socket.makefile` method must only be used when the
+socket is in blocking mode; in timeout or non-blocking mode file operations
+that cannot be completed immediately will fail.
 
-Note that the :meth:`connect` operation is subject to the timeout setting, and
-in general it is recommended to call :meth:`settimeout` before calling
-:meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
-The system network stack may return a connection timeout error
-of its own regardless of any Python socket timeout setting.
+Note that the :meth:`~socket.connect` operation is subject to the timeout
+setting, and in general it is recommended to call :meth:`~socket.settimeout`
+before calling :meth:`~socket.connect` or pass a timeout parameter to
+:meth:`create_connection`.  The system network stack may return a connection
+timeout error of its own regardless of any Python socket timeout setting.
 
 
 .. method:: socket.setsockopt(level, optname, value)
@@ -721,8 +724,8 @@ of its own regardless of any Python socket timeout setting.
    are disallowed.  If *how* is :const:`SHUT_RDWR`, further sends and receives are
    disallowed.
 
-Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
-and :meth:`send` without *flags* argument instead.
+Note that there are no methods :meth:`read` or :meth:`write`; use
+:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
 
 Socket objects also have these (read-only) attributes that correspond to the
 values given to the :class:`socket` constructor.
@@ -751,11 +754,12 @@ Example
 Here are four minimal example programs using the TCP/IP protocol: a server that
 echoes all data that it receives back (servicing only one client), and a client
 using it.  Note that a server must perform the sequence :func:`socket`,
-:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
-:meth:`accept` to service more than one client), while a client only needs the
-sequence :func:`socket`, :meth:`connect`.  Also note that the server does not
-:meth:`send`/:meth:`recv` on the  socket it is listening on but on the new
-socket returned by :meth:`accept`.
+:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
+repeating the :meth:`~socket.accept` to service more than one client), while a
+client only needs the sequence :func:`socket`, :meth:`~socket.connect`.  Also
+note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the
+socket it is listening on but on the new socket returned by
+:meth:`~socket.accept`.
 
 The first two examples support IPv4 only. ::
 
diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst
index cc0313f..bd7e8d4 100644
--- a/Doc/library/winreg.rst
+++ b/Doc/library/winreg.rst
@@ -8,21 +8,23 @@
 
 
 These functions expose the Windows registry API to Python.  Instead of using an
-integer as the registry handle, a handle object is used to ensure that the
-handles are closed correctly, even if the programmer neglects to explicitly
-close them.
+integer as the registry handle, a :ref:`handle object <handle-object>` is used
+to ensure that the handles are closed correctly, even if the programmer neglects
+to explicitly close them.
 
 This module offers the following functions:
 
 
 .. function:: CloseKey(hkey)
 
-   Closes a previously opened registry key. The hkey argument specifies a
+   Closes a previously opened registry key.  The *hkey* argument specifies a
    previously opened key.
 
    .. note::
-      If *hkey* is not closed using this method (or via :meth:`hkey.Close() <PyHKEY.Close>`),
-      it is closed when the *hkey* object is destroyed by Python.
+
+      If *hkey* is not closed using this method (or via :meth:`hkey.Close()
+      <PyHKEY.Close>`), it is closed when the *hkey* object is destroyed by
+      Python.
 
 
 .. function:: ConnectRegistry(computer_name, key)
@@ -123,13 +125,15 @@ This module offers the following functions:
    |       | registry type                              |
    +-------+--------------------------------------------+
    | ``2`` | An integer that identifies the type of the |
-   |       | value data                                 |
+   |       | value data (see table in docs for          |
+   |       | :meth:`SetValueEx`)                        |
    +-------+--------------------------------------------+
 
 
 .. function:: ExpandEnvironmentStrings(str)
 
-   Expands environment strings %NAME% in unicode string like :const:`REG_EXPAND_SZ`::
+   Expands environment variable placeholders ``%NAME%`` in strings like
+   :const:`REG_EXPAND_SZ`::
 
       >>> ExpandEnvironmentStrings('%windir%')
       'C:\\Windows'
@@ -163,23 +167,20 @@ This module offers the following functions:
    *key* is a handle returned by :func:`ConnectRegistry` or one of the constants
    :const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`.
 
-   *sub_key* is a string that identifies the sub_key to load.
+   *sub_key* is a string that identifies the subkey to load.
 
    *file_name* is the name of the file to load registry data from. This file must
    have been created with the :func:`SaveKey` function. Under the file allocation
    table (FAT) file system, the filename may not have an extension.
 
-   A call to LoadKey() fails if the calling process does not have the
-   :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than
+   A call to :func:`LoadKey` fails if the calling process does not have the
+   :const:`SE_RESTORE_PRIVILEGE` privilege.  Note that privileges are different
    from permissions -- see the `RegLoadKey documentation
    <http://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx>`__ for
    more details.
 
    If *key* is a handle returned by :func:`ConnectRegistry`, then the path
-   specified in *fileName* is relative to the remote computer.
-
-   The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or
-   :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
+   specified in *file_name* is relative to the remote computer.
 
 
 .. function:: OpenKey(key, sub_key[, res[, sam]])
@@ -194,8 +195,8 @@ This module offers the following functions:
    *res* is a reserved integer, and must be zero.  The default is zero.
 
    *sam* is an integer that specifies an access mask that describes the desired
-   security access for the key.  Default is :const:`KEY_READ`.  See
-   :ref:`Access Rights <access-rights>` for other allowed values.
+   security access for the key.  Default is :const:`KEY_READ`.  See :ref:`Access
+   Rights <access-rights>` for other allowed values.
 
    The result is a new handle to the specified key.
 
@@ -267,7 +268,8 @@ This module offers the following functions:
    | ``0`` | The value of the registry item.         |
    +-------+-----------------------------------------+
    | ``1`` | An integer giving the registry type for |
-   |       | this value.                             |
+   |       | this value (see table in docs for       |
+   |       | :meth:`SetValueEx`)                     |
    +-------+-----------------------------------------+
 
 
@@ -278,10 +280,10 @@ This module offers the following functions:
    *key* is an already open key, or one of the predefined
    :ref:`HKEY_* constants <hkey-constants>`.
 
-   *file_name* is the name of the file to save registry data to. This file cannot
-   already exist. If this filename includes an extension, it cannot be used on file
-   allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey`
-   or :meth:`RestoreKey` methods.
+   *file_name* is the name of the file to save registry data to.  This file
+   cannot already exist. If this filename includes an extension, it cannot be
+   used on file allocation table (FAT) file systems by the :meth:`LoadKey`
+   method.
 
    If *key* represents a key on a remote computer, the path described by
    *file_name* is relative to the remote computer. The caller of this method must
@@ -351,16 +353,16 @@ This module offers the following functions:
 .. function:: DisableReflectionKey(key)
 
    Disables registry reflection for 32-bit processes running on a 64-bit
-   Operating System.
+   operating system.
 
-   *key* is an already open key, or one of the predefined
-   :ref:`HKEY_* constants <hkey-constants>`.
+   *key* is an already open key, or one of the predefined :ref:`HKEY_* constants
+   <hkey-constants>`.
 
-   Will generally raise :exc:`NotImplemented` if executed on a 32-bit
-   Operating System.
+   Will generally raise :exc:`NotImplemented` if executed on a 32-bit operating
+   system.
 
    If the key is not on the reflection list, the function succeeds but has no
-   effect. Disabling reflection for a key does not affect reflection of any
+   effect.  Disabling reflection for a key does not affect reflection of any
    subkeys.
 
 
@@ -368,11 +370,11 @@ This module offers the following functions:
 
    Restores registry reflection for the specified disabled key.
 
-   *key* is an already open key, or one of the predefined
-   :ref:`HKEY_* constants <hkey-constants>`.
+   *key* is an already open key, or one of the predefined :ref:`HKEY_* constants
+   <hkey-constants>`.
 
-   Will generally raise :exc:`NotImplemented` if executed on a 32-bit
-   Operating System.
+   Will generally raise :exc:`NotImplemented` if executed on a 32-bit operating
+   system.
 
    Restoring reflection for a key does not affect reflection of any subkeys.
 
@@ -387,7 +389,7 @@ This module offers the following functions:
    Returns ``True`` if reflection is disabled.
 
    Will generally raise :exc:`NotImplemented` if executed on a 32-bit
-   Operating System.
+   operating system.
 
 
 .. _constants:
@@ -586,7 +588,7 @@ Registry Handle Objects
 
 This object wraps a Windows HKEY object, automatically closing it when the
 object is destroyed.  To guarantee cleanup, you can call either the
-:meth:`Close` method on the object, or the :func:`CloseKey` function.
+:meth:`~PyHKEY.Close` method on the object, or the :func:`CloseKey` function.
 
 All registry functions in this module return one of these objects.
 
@@ -606,8 +608,8 @@ true if they both reference the same underlying Windows handle value.
 
 Handle objects can be converted to an integer (e.g., using the built-in
 :func:`int` function), in which case the underlying Windows handle value is
-returned.  You can also use the :meth:`Detach` method to return the integer
-handle, and also disconnect the Windows handle from the handle object.
+returned.  You can also use the :meth:`~PyHKEY.Detach` method to return the
+integer handle, and also disconnect the Windows handle from the handle object.
 
 
 .. method:: PyHKEY.Close()
@@ -632,11 +634,12 @@ handle, and also disconnect the Windows handle from the handle object.
 .. method:: PyHKEY.__enter__()
             PyHKEY.__exit__(\*exc_info)
 
-   The HKEY object implements :meth:`__enter__` and :meth:`__exit__` and thus
-   supports the context protocol for the :keyword:`with` statement::
+   The HKEY object implements :meth:`~object.__enter__` and
+   :meth:`~object.__exit__` and thus supports the context protocol for the
+   :keyword:`with` statement::
 
       with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
-          # ... work with key ...
+          ...  # work with key
 
    will automatically close *key* when control leaves the :keyword:`with` block.
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index d2f8c16..a32a84d 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1588,6 +1588,46 @@ the new type and it saves the ordered dictionary keys in an attribute
 called *members*.
 
 
+Customizing instance and subclass checks
+----------------------------------------
+
+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 are 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