[ python-Bugs-1100368 ] Wrong "type()" syntax in docs

[SourceForge.net]

Bugs item #1100368, was opened at 2005-01-11 14:03
Message generated for change (Settings changed) made by rhettinger
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1100368&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.4
>Status: Closed
>Resolution: Fixed
Priority: 5
Submitted By: Facundo Batista (facundobatista)
Assigned to: Raymond Hettinger (rhettinger)
Summary: Wrong "type()" syntax in docs

Initial Comment:
>From the current docs:

  type(object):
      Return the type of an object. The return value
      is a type object. 

>From the interpreter:

>>> help(type)
Help on class type in module __builtin__:

class type(object)
 |  type(object) -> the object's type
 |  type(name, bases, dict) -> a new type

In the documentation is missing the second syntax form.



----------------------------------------------------------------------

Comment By: Steven Bethard (bediviere)
Date: 2005-08-13 18:32

Message:
Logged In: YES 
user_id=945502

I was going to file this as a new bug report, but I changed
my mind and decided to post it as a followup to this bug
instead.  It's basically a first draft at some documentation
for the behavior of the type type.

----------
The type object documentation is limited and hard to find. 
The call type(obj) is defined in
http://docs.python.org/lib/built-in-funcs.html and the call
type(name, bases, dict) is briefly mentioned in
http://docs.python.org/ref/metaclasses.html.  Confusingly,
the section on Type Objects
(http://www.python.org/dev/doc/devel/lib/bltin-type-objects.html)
is not about the type object at all; it's about *instances*
of type, e.g. int or str.

I'd like to add a section on the type object itself,
something like:

"""
type(name, bases, dict)
    Return a new type object.  This is essentially a
functional form of the class statement: the "name" string is
the class name and becomes the __name__ attribute, the
"bases" tuple is the class bases and becomes the __bases__
attribute, the "dict" dict is the namespace defined by the
class body, and becomes the __dict__ attribute.  For
example, the following two statements create identical
"type" objects: 

>>> class X(object):
...     a = 1
...     
>>> X = type('X', (object,), dict(a=1))

    Just like type objects created by class statements, type
objects created by type() are callable, and when called
create new instances of their type.  The __call__() method
of type objects accepts any number of positional and keyword
arguments, and passes these to the type object's __new__()
method to create a new instance.  If __new__() returns an
instance of the same type, that instance's __init__() method
is then called with the same arguments.  In either case, the
__call__() method then returns the new instance.
"""

I don't know where this should go, but I'd certainly like to
see something like this put in, and linked under the type()
function, the Type Objects section and the Customizing class
creation (metaclasses) section.

----------------------------------------------------------------------

Comment By: Michael Chermside (mcherm)
Date: 2005-01-25 16:31

Message:
Logged In: YES 
user_id=99874

cjwhrh's comment doesn't seem relevent. It is generally true 
of ALL builtins that they  can be shadowed by local variables.

Facundo is probably right that the newer use of type() should 
be documented.

----------------------------------------------------------------------

Comment By: Colin J. Williams (cjwhrh)
Date: 2005-01-18 17:03

Message:
Logged In: YES 
user_id=285587

The accuracy of the above depends partly on the context.

Within a function or method which has "type" as a parameter
the type function described above is no longer accessible.

Colin W.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1100368&group_id=5470