[Python-Dev] Documentation for __new__

[Greg Ward]

On 05 March 2005, Nick Coghlan said:
> Steven Bethard has put together some text to add __new__ to the list of 
> Basic Customisation methods in the language reference. Would one of the 
> documentation folks care to take a look at it?

I've tried to tighten up the text there and hopefully make it a smidgeon
clearer and more accurate.  Here's my best effort:

  __new__(cls[, ...])

  Called to create a new instance of class 'cls'.  __new__()
  is a static method (special-cased so you need not declare it
  as such) that takes the class to create an instance of as
  the first argument.  The remaining arguments are those
  passed to the object constructor expression.  The return
  value of __new__() should be the new object instance.

  Typical usage is to create a new instance of the class by
  invoking the superclass's __new__() method using
  "super(currentclass, cls).__new__([...])" with appropriate
  arguments, modifying the returned instance if necessary, and
  then returning it.  If the returned value is an instance of
  'cls', its __init__() will be invoked like
  "__init__(self[, ...])", where the extra arguments are the
  same as were passed to __new__().

  You do need not to return an instance of 'cls', but if you
  do not, the new instance's __init__() method will not be
  invoked.

  __new__() is intended mainly to allow subclasses of
  immutable types (like int, str, or tuple) to customize
  instance creation.

Feedback welcome.  Has anyone volunteered to render this in LaTeX yet?
If not, I might.

        Greg
-- 
Greg Ward <gward at python.net>                         http://www.gerg.ca/
I hope something GOOD came in the mail today so I have a REASON to live!!