[issue11776] types.MethodType() params and usage is not documented
New submission from anatoly techtonik <techtonik@gmail.com>: types.MethodType(function, instance) is used as a replacement for new.instancemethod(function, instance, class), but this usage is not documented. ---------- assignee: docs@python components: Documentation messages: 133089 nosy: docs@python, techtonik priority: normal severity: normal status: open title: types.MethodType() params and usage is not documented versions: Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Brian Curtin <brian@python.org>: ---------- stage: -> needs patch type: -> behavior _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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? ---------- nosy: +terry.reedy type: behavior -> feature request _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: Message is classified as spam. I am not sure if you see it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Terry J. Reedy <tjreedy@udel.edu>: ---------- Removed message: http://bugs.python.org/msg133353 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: For anyone curious, I removed the falsely classified as spam message after copying the links into my previous message. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Georg Brandl <georg@python.org> added the comment: When we do document types, their constructors and methods should also be documented. This is a valid request. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Guandalino <guandalino@gmail.com>: ---------- nosy: +guandalino _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +easy versions: +Python 2.7, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Mike Hoy <mhoy09@gmail.com>: ---------- nosy: +mikehoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: Still not documented.. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: Another 4 complains about missing references: http://stackoverflow.com/questions/1015307/python-bind-an-unbound-method ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Nick Coghlan added the comment: 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. ---------- nosy: +ncoghlan title: types.MethodType() params and usage is not documented -> Constructor signatures missing in types module documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Nick Coghlan added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Terry J. Reedy added the comment: "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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Mike Hoy added the comment: 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'
---------- keywords: +patch versions: -Python 2.7, Python 3.2 Added file: http://bugs.python.org/file26969/issue11776-sigs-docs-first.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Terry J. Reedy added the comment: 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 .... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Mike Hoy added the comment: Lambda Changes patch. ---------- Added file: http://bugs.python.org/file26982/issue11776-first-easy-part-lambda-.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Mike Hoy added the comment: 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. ---------- Added file: http://bugs.python.org/file27003/signatures-full-patch.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Mike Hoy added the comment: Ezio Melotti was the one that offered to change the wording on MappingProxyType doc ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
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@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Mike Hoy added the comment: 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. ---------- Added file: http://bugs.python.org/file27047/complete-patch-with-table-issue-11776.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Eric Snow <ericsnowcurrently@gmail.com>: ---------- nosy: +eric.snow _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Changes by Terry J. Reedy <tjreedy@udel.edu>: ---------- nosy: -techtonik versions: +Python 3.4, Python 3.5 -Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: @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! ---------- nosy: +cheryl.sabella versions: +Python 3.7, Python 3.8 -Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11776> _______________________________________
Emmanuel Arias <emmanuelarias30@gmail.com> added the comment:
For others, please give Mike at least a week to respond before opening a PR with his changes.
Okas! ---------- nosy: +eamanu _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11776> _______________________________________
Change by Tz a <tza0987@gmail.com>: ---------- nosy: +Tz a _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11776> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11776> _______________________________________
participants (13)
-
anatoly techtonik -
Brian Curtin
-
Cheryl Sabella
-
Emmanuel Arias
-
Eric Snow
-
Ezio Melotti
-
Georg Brandl
-
Guandalino
-
Mike Hoy
-
Nick Coghlan
-
Terry J. Reedy
-
Tz a
-
Éric Araujo