[Python-Dev] Re: Documentation for __new__

[Steve Holden]

Greg Ward wrote:
> 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.
> 
Just to offer alternatives:

   __new__(cls[, ...])

    __new__() is a static method (special-cased so you need
   not declare it as such) whose fist argumen is the class
   of which a new instance is required. The remaining arguments
   are those passed to the object constructor expression (the
   call to the class).  The return value of __new__() should be
   the new instance object, which is not constrained to be of
   type 'cls'.


>   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__().
> 
   Typical usage creates a new instance of the required
   class by invoking the superclass's __new__() method
   using "super(currentclass, cls).__new__(...)" with
   appropriate argumnents and then modifying the newly-
   created instance as necessary before returning it.

   If __new__() returns an instance of 'cls' then the new
   instance's __init__() method will be called with the
   instance itself as the first argument and the remaining
   arguments being the second and subsequent arguments 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.
> 
   If __new__() does not return an instance of 'cls' then 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

I decided some time ago that documenting Python in LaTex wasn't my forte ...

regards
  Steve