Merged revisions 59822-59841 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r59822 | georg.brandl | 2008-01-07 17:43:47 +0100 (Mon, 07 Jan 2008) | 2 lines

  Restore "somenamedtuple" as the "class" for named tuple attrs.
........
  r59824 | georg.brandl | 2008-01-07 18:09:35 +0100 (Mon, 07 Jan 2008) | 2 lines

  Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode.
........
  r59827 | georg.brandl | 2008-01-07 18:25:53 +0100 (Mon, 07 Jan 2008) | 2 lines

  patch #1668: clarify envvar docs; rename THREADDEBUG to PYTHONTHREADDEBUG.
........
  r59830 | georg.brandl | 2008-01-07 19:16:36 +0100 (Mon, 07 Jan 2008) | 2 lines

  Make Python compile with --disable-unicode.
........
  r59831 | georg.brandl | 2008-01-07 19:23:27 +0100 (Mon, 07 Jan 2008) | 2 lines

  Restructure urllib doc structure.
........
  r59833 | georg.brandl | 2008-01-07 19:41:34 +0100 (Mon, 07 Jan 2008) | 2 lines

  Fix #define ordering.
........
  r59834 | georg.brandl | 2008-01-07 19:47:44 +0100 (Mon, 07 Jan 2008) | 2 lines

  #467924, patch by Alan McIntyre: Add ZipFile.extract and ZipFile.extractall.
........
  r59835 | raymond.hettinger | 2008-01-07 19:52:19 +0100 (Mon, 07 Jan 2008) | 1 line

  Fix inconsistent title levels -- it made the whole doc build crash horribly.
........
  r59836 | georg.brandl | 2008-01-07 19:57:03 +0100 (Mon, 07 Jan 2008) | 2 lines

  Fix two further doc build warnings.
........
  r59837 | georg.brandl | 2008-01-07 20:17:10 +0100 (Mon, 07 Jan 2008) | 2 lines

  Clarify metaclass docs and add example.
........
  r59838 | vinay.sajip | 2008-01-07 20:40:10 +0100 (Mon, 07 Jan 2008) | 1 line

  Added section about adding contextual information to log output.
........
  r59839 | christian.heimes | 2008-01-07 20:58:41 +0100 (Mon, 07 Jan 2008) | 1 line

  Fixed indention problem that caused the second TIPC test to run on systems without TIPC
........
  r59840 | raymond.hettinger | 2008-01-07 21:07:38 +0100 (Mon, 07 Jan 2008) | 1 line

  Cleanup named tuple subclassing example.
........

1 files changed, 18 insertions, 3 deletions

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 92fece1..e6cba75 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1086,7 +1086,8 @@ Basic customization
    :meth:`__init__` method will not be invoked.
 
    :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
-   int, str, or tuple) to customize instance creation.
+   int, str, or tuple) to customize instance creation.  It is also commonly
+   overridden in custom metaclasses in order to customize class creation.
 
 
 .. method:: object.__init__(self[, ...])
@@ -1527,7 +1528,7 @@ read into a separate namespace and the value of class name is bound to the
 result of ``type(name, bases, dict)``.
 
 When the class definition is read, if *__metaclass__* is defined then the
-callable assigned to it will be called instead of :func:`type`. The allows
+callable assigned to it will be called instead of :func:`type`. This allows
 classes or functions to be written which monitor or alter the class creation
 process:
 
@@ -1536,7 +1537,21 @@ process:
 * Returning an instance of another class -- essentially performing the role of a
   factory function.
 
-.. XXX needs to be updated for the "new metaclasses" PEP
+These steps will have to be performed in the metaclass's :meth:`__new__` method
+-- :meth:`type.__new__` can then be called from this method to create a class
+with different properties.  This example adds a new element to the class
+dictionary before creating the class::
+
+  class metacls(type):
+      def __new__(mcs, name, bases, dict):
+          dict['foo'] = 'metacls was here'
+          return type.__new__(mcs, name, bases, dict)
+
+You can of course also override other class methods (or add new methods); for
+example defining a custom :meth:`__call__` method in the metaclass allows custom
+behavior when the class is called, e.g. not always creating a new instance.
+
+
 .. data:: __metaclass__
 
    This variable can be any callable accepting arguments for ``name``, ``bases``,