[issue11776] Constructor signatures missing in types module documentation

[Ezio Melotti]

Ezio Melotti added the comment:

> We decided to leave it to the review process to determine the exact wording.

The problem with the current wording is that it explain how to use it (in case it's used to create a new mapping proxy), but doesn't say much about the object itself (in case it's used for isinstance/issubclass checks).

This consideration can also be applied to the rest of the patch.  Currently the types are documented as if they were only useful for isinstance/issuclass checks and the arguments are omitted from the doc.  Given that this is the main use case IMHO, it makes sense having a lightweight list of types with a short description of what they are.
OTOH these types can also be used to create new objects, so for this use case the arguments should be listed and documented.

I'm not sure if these two use cases should be kept separate or not though.  One possible way to do this is to have a table, followed by the full doc with arguments and explanation.  The table will also be useful as an index to jump to the full doc, and as a quick overview of the available types.

Something like:

The following table summarizes the types defined in the types module.  
Typical use is of these names is for isinstance() or issubclass() checks.

----------- ------------------------------------------------
Type Name   Type of
----------- ------------------------------------------------
MethodType  methods of user-defined instances
CodeType    code objects such as returned by :func:`compile`
...         ...
----------- ------------------------------------------------


These types can also be used to create new objects:

.. class:: MethodType(function, instance)

   Create a bound instance method object.

.. class:: CodeType(argcount, kwonlyargcount, nlocals, stacksize, flags, codestring, constants, names, varnames, filename, name, firstlineno, lnotab)

   Create a code object. Not for the faint of heart.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11776>
_______________________________________