homepage

This issue tracker has been migrated to GitHub , and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

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 2022年04月11日 14:57 by admin.

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: Alyssa 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: Alyssa 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
2022年04月11日 14:57:15adminsetgithub: 55985
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

AltStyle によって変換されたページ (->オリジナル) /