classification
Title: Constructor signatures missing in types module documentation
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Tza0987, cheryl.sabella, docs@python, eamanu, eric.araujo, eric.snow, ezio.melotti, georg.brandl, guandalino, mikehoy, ncoghlan, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2011-04-05 20:53 by techtonik, last changed 2019-02-24 23:42 by terry.reedy.

Files
File name Uploaded Description Edit
issue11776-sigs-docs-first.diff mikehoy, 2012-08-23 10:36 review
issue11776-first-easy-part-lambda-.diff mikehoy, 2012-08-24 10:02 review
signatures-full-patch.diff mikehoy, 2012-08-26 04:01 review
complete-patch-with-table-issue-11776.diff mikehoy, 2012-08-29 17:03 review
Messages (22)
msg133089 - (view) Author: anatoly techtonik (techtonik) Date: 2011-04-05 20:53
types.MethodType(function, instance) is used as a replacement for new.instancemethod(function, instance, class), but this usage is not documented.
msg133352 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-04-08 23:10
All the types in the types module are, being types, potentially callable to produce instances of that type. But they are in types rather than builtins precisely because it is not expected that they be called directly. They are bound to names in types primarily for isinstance checks, and possibly issubclass checks. So none of their signatures are documented in types. It would be an anomaly to add something special for MethodType. So my first impulse is to close this. Do you have a source for your statement?
msg133354 - (view) Author: anatoly techtonik (techtonik) Date: 2011-04-08 23:21
Message is classified as spam. I am not sure if you see it.
msg133365 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-04-09 01:00
Messages that only consist of links are classified that way. To refer to other issues, use #xxxxx, as with #6040, but I have no idea which of the many messages you were referring to, so use msgxxxxxx.

The stack overflow link
http://stackoverflow.com/questions/972/adding-a-method-to-an-existing-object
which should be allowed given surrounding text, answers my question:
types.MethodType can be used as a replacement for 2.x new.instancemethod.

The question is where that should be mentioned. The types doc still seems like the wrong place. Perhaps somewhere in the language ref section on classes, if that is where bound methods are discussed.
msg133366 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-04-09 01:01
For anyone curious, I removed the falsely classified as spam message after copying the links into my previous message.
msg133374 - (view) Author: anatoly techtonik (techtonik) Date: 2011-04-09 06:00
Nevermind about #6040 - I just used the same technique to provide a workaround and then remembered I've seen this recipe on StackOverflow.

To me types is the right place, because that's exactly where are you sent from the docs of new module:

  Deprecated since version 2.6: The new module has been removed in Python 3.0. Use the types module’s classes instead.

http://docs.python.org/library/new.html
msg133376 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-04-09 07:43
When we do document types, their constructors and methods should also be documented.  This is a valid request.
msg166149 - (view) Author: anatoly techtonik (techtonik) Date: 2012-07-22 16:53
Still not documented..
msg166152 - (view) Author: anatoly techtonik (techtonik) Date: 2012-07-22 17:24
Another 4 complains about missing references: http://stackoverflow.com/questions/1015307/python-bind-an-unbound-method
msg168864 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-08-22 10:02
Clarifying the request: the constructor signatures for internal types should be documented in http://docs.python.org/dev/library/types, rather than just listing the types.

If creation of new instances from Python is not supported, that should also be documented explicitly.

Some of the items are currently missing docstrings as well.
msg168866 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-08-22 10:20
The first easy part of this patch is to document the signatures for types in that module where that info is available in the docstring:

CodeType
FunctionType
LambdaType
SimpleNamespace
MethodType

The second easy part is that the following need to be documented as not supporting direct creation from Python code:

BuiltinFunctionType
BuiltinMethodType
FrameType
GeneratorType
GetSetDescriptorType
MemberDescriptorType
TracebackType 

This type does support direct creation and should be documented appropriately, but the docs should also direct readers to the preferred API in the imp module:

ModuleType (imp.new_module)


Finally, this one is missing both a docstring *and* signature documentation:
MappingProxyType

It's a simple API that accepts a single parameter (which must be a mapping) and returns a read-only view of the original mapping.
msg168901 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-08-22 17:44
"class types.MappingProxyType(mapping) 
Read-only proxy of a mapping. ..."

is the only class in 7.11.2. Standard Interpreter Types that *does* have a signature given in the text. However, the extra word 'class' here and for SimpleNamespace confuses me (I do not understand what it is intended to convey) and seems unnecessary. The two entries with signatures in 7.11.1 do not have that.

Once parenthesized signatures are given, perhaps one statement at the top like "Classes listed without a signature cannot be directly created from Python code." would be sufficient.
msg168933 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-23 10:36
I used the following for:

>>CodeType
>>FunctionType
>>LambdaType
>>SimpleNamespace
>>MethodType

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

>>> print(CodeType.__doc__)
code(argcount, kwonlyargcount, nlocals, stacksize, flags, codestring,
      constants, names, varnames, filename, name, firstlineno,
      lnotab[, freevars[, cellvars]])

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

>>> print(FunctionType.__doc__)
function(code, globals[, name[, argdefs[, closure]]])

Create a function object from a code object and a dictionary.
The optional name string overrides the name from the code object.
The optional argdefs tuple specifies the default argument values.
The optional closure tuple supplies the bindings for free variables.

>>> print(LambdaType.__doc__)
function(code, globals[, name[, argdefs[, closure]]])

Create a function object from a code object and a dictionary.
The optional name string overrides the name from the code object.
The optional argdefs tuple specifies the default argument values.
The optional closure tuple supplies the bindings for free variables.

>>> print(SimpleNamespace.__doc__) 
A simple attribute-based namespace.

namespace(**kwargs)

>>> print(MethodType.__doc__)
method(function, instance)

Create a bound instance method object.

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

I left out the [] arguments.

I've stopped here and uploaded a patch for the 

>>'first easy part'. 

Despite that name I suspect I will have to change quite a few things. Once this part is done then I will move on the the 

>>'second easy part'
msg168947 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-08-23 16:14
LambdaType is a synonym for FunctionType. There should be just one entry, as currently, but perhaps make that a bit clearer, as one could misread the current line as saying that FunctionType is the type of def statements and LambdaType is the type of lambda expressions. This misunderstanding appears in python-list discussions occasionally. So I think I would write

types.FunctionType(sig....)
types.LambdaType synonym for FunctionType

Create a function ....
msg168992 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-24 10:02
Lambda Changes patch.
msg169156 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-26 04:01
I've added a completed patch for review. There was some talk on IRC that the wording for MappingProxyType should be changed to: "Return a read-only view of the given mapping."

We decided to leave it to the review process to determine the exact wording.
msg169158 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-26 04:04
Ezio Melotti was the one that offered to change the wording on MappingProxyType doc
msg169159 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-08-26 04:24
> 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.
msg169397 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-29 17:03
This should be all the requested changes. I've gone over the table entries (at least the first one, CodeType, with bitdancer on IRC). I've removed the descriptive language from below the table and added it to the table. Leaving the text below the table to deal with args and some descriptive text that was just too large to really fit into the right column of the table.

One question though, do you want:
BuiltinFunctionType
BuiltinMethodType
FrameType
GeneratorType
GetSetDescriptorType
MemberDescriptorType
TracebackType 

To be in the table as well. I'm a bit confused on this part. Just let me know.
msg336475 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-02-24 15:51
@mikehoy, would you be interested in converting your patch to a GitHub pull request?  

For others, please give Mike at least a week to respond before opening a PR with his changes.  

Thank you!
msg336478 - (view) Author: Emmanuel Arias (eamanu) * Date: 2019-02-24 16:17
> For others, please give Mike at least a week to respond before opening a PR with his changes.  

Okas!
msg336491 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-02-24 23:42
I agree that we should properly document all of the types, even if belately.

A PR is premature until we agree in more detail what 'properly' means.  The most recent patch 'complete-patch...' has multiple errors and needs major revision, to the point that a new patch will be 'based on' rather than 'an edit' of Hoy's work.

1. The table needs to be explained.  It should not just duplicate explanation elsewhere in the doc.  Currently it only lists classes with Python signatures that can be instantiated from Python.  It might make more sense to have a table of types that cannot be instantiated, and not list them elsewhere.

The table seems to be a response to an unreferenced and incomplete (and therefore non-authoritative) suggestion.  We should do what seems best now.

Perhaps there should be two tables for non-callable and callable (from Python) types.  The former without individual entries, the latter with, and with links thereto in the table.

Or perhaps skip tables and just make two subsections for the two groups of types/classes.  There are not currently alphabetical anyway.

2. The types that cannot be instantiated have wrong doc.
"+   This does support direct creation."
This seems to be Nick's
"This type does support direct creation "
However, 'this' referred to ModuleType, not to the 'do not call' type he listed previously.

Correct would be "This type cannot be instantiated by calling it." and I would prefer saying this just once and listing the modules in a table with short explanation.  Table intro might be
"The following types cannot be instantiated by calling them from Python.  Hence no argument signature is given."

3. The wrong initial comments are followed by the wrong 
"Please see :class:`XyzType` (imp.new_module).
Again, these are derived from Nick's comment that only applies to callable ModuleType.

The reference to imp is obsolete as imp is deprecated.  The imp.new_module(name) entry says to use importlib.util.module_from_spec(spec), but a name is not spec.  We don't need to add this; see below.

4. The patch does not touch the ModuleType entry, currently (3.7 online):

 class types.ModuleType(name, doc=None)
    The type of modules. Constructor takes the name of the module to be created and optionally its docstring.

    Note
    Use importlib.util.module_from_spec() to create a new module if you wish to set the various import-controlled attributes.

This looks fine.  The only thing we might change is the awkward 'Constructor takes' to 'A call takes' or something.
History
Date User Action Args
2019-02-24 23:42:44terry.reedysetmessages: + msg336491
2019-02-24 17:25:23Tza0987setnosy: + Tza0987
2019-02-24 16:17:20eamanusetnosy: + eamanu
messages: + msg336478
2019-02-24 15:51:24cheryl.sabellasetnosy: + cheryl.sabella

messages: + msg336475
versions: + Python 3.7, Python 3.8, - Python 3.4, Python 3.5
2014-07-02 22:12:28terry.reedysetnosy: - techtonik

versions: + Python 3.4, Python 3.5, - Python 3.3
2012-11-13 05:47:29eric.snowsetnosy: + eric.snow
2012-08-29 17:03:56mikehoysetfiles: + complete-patch-with-table-issue-11776.diff

messages: + msg169397
2012-08-26 04:24:47ezio.melottisetmessages: + msg169159
2012-08-26 04:04:06mikehoysetmessages: + msg169158
2012-08-26 04:01:53mikehoysetfiles: + signatures-full-patch.diff

messages: + msg169156
2012-08-24 10:02:27mikehoysetfiles: + issue11776-first-easy-part-lambda-.diff

messages: + msg168992
2012-08-23 16:14:53terry.reedysetmessages: + msg168947
2012-08-23 10:36:11mikehoysetfiles: + issue11776-sigs-docs-first.diff
keywords: + patch
messages: + msg168933

versions: - Python 2.7, Python 3.2
2012-08-23 08:56:33ezio.melottisetnosy: + ezio.melotti
2012-08-22 17:44:10terry.reedysetmessages: + msg168901
2012-08-22 10:20:32ncoghlansetmessages: + msg168866
2012-08-22 10:02:29ncoghlansetnosy: + ncoghlan

messages: + msg168864
title: types.MethodType() params and usage is not documented -> Constructor signatures missing in types module documentation
2012-07-22 17:24:57techtoniksetmessages: + msg166152
2012-07-22 16:53:11techtoniksetmessages: + msg166149
2011-10-16 21:34:17mikehoysetnosy: + mikehoy
2011-10-10 15:31:56eric.araujosetkeywords: + easy
versions: + Python 2.7, Python 3.3
2011-10-10 10:00:23guandalinosetnosy: + guandalino
2011-04-15 17:09:30eric.araujosetnosy: + eric.araujo
2011-04-09 07:43:09georg.brandlsetnosy: + georg.brandl
messages: + msg133376
2011-04-09 06:00:19techtoniksetmessages: + msg133374
2011-04-09 01:01:16terry.reedysetmessages: + msg133366
2011-04-09 01:00:09terry.reedysetmessages: - msg133353
2011-04-09 01:00:03terry.reedysetmessages: + msg133365
2011-04-08 23:21:31techtoniksetmessages: + msg133354
2011-04-08 23:20:42techtoniksetmessages: + msg133353
2011-04-08 23:10:18terry.reedysettype: behavior -> enhancement

messages: + msg133352
nosy: + terry.reedy
2011-04-05 20:55:41brian.curtinsettype: behavior
stage: needs patch
2011-04-05 20:53:24techtonikcreate