[Python-checkins] cpython (3.3): Issue20467: clarify __init__'s role

[ethan.furman]

https://hg.python.org/cpython/rev/94696e457461
changeset:   94149:94696e457461
branch:      3.3
parent:      94019:d1af6f3a8ce3
user:        Ethan Furman <ethan at stoneleaf.us>
date:        Wed Jan 14 21:56:10 2015 -0800
summary:
  Issue20467: clarify __init__'s role

files:
  Doc/reference/datamodel.rst |  18 +++++++++++-------
  1 files changed, 11 insertions(+), 7 deletions(-)


diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1081,13 +1081,17 @@
 
    .. index:: pair: class; constructor
 
-   Called when the instance is created.  The arguments are those passed to the
-   class constructor expression.  If a base class has an :meth:`__init__` method,
-   the derived class's :meth:`__init__` method, if any, must explicitly call it to
-   ensure proper initialization of the base class part of the instance; for
-   example: ``BaseClass.__init__(self, [args...])``.  As a special constraint on
-   constructors, no value may be returned; doing so will cause a :exc:`TypeError`
-   to be raised at runtime.
+   Called after the instance has been created (by :meth:`__new__`), but before
+   it is returned to the caller.  The arguments are those passed to the
+   class constructor expression.  If a base class has an :meth:`__init__`
+   method, the derived class's :meth:`__init__` method, if any, must explicitly
+   call it to ensure proper initialization of the base class part of the
+   instance; for example: ``BaseClass.__init__(self, [args...])``.
+
+   Because :meth:`__new__` and :meth:`__init__` work together in constructing
+   objects (:meth:`__new__` to create it, and :meth:`__init__` to customise it),
+   no non-``None`` value may be returned by :meth:`__init__`; doing so will
+   cause a :exc:`TypeError` to be raised at runtime.
 
 
 .. method:: object.__del__(self)

-- 
Repository URL: https://hg.python.org/cpython