Constructor signatures missing in types module documentation

[techtonik]

BPO	11776
Nosy	@birkenfeld, @terryjreedy, @ncoghlan, @ezio-melotti, @merwok, @ericsnowcurrently, @eamanu, @csabella, @tza0987
Files	issue11776-sigs-docs-first.diff issue11776-first-easy-part-lambda-.diff signatures-full-patch.diff complete-patch-with-table-issue-11776.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2011-04-05.20:53:24.787>
labels = ['easy', '3.8', 'type-feature', '3.7', 'docs']
title = 'Constructor signatures missing in types module documentation'
updated_at = <Date 2019-02-24.23:42:44.704>
user = 'https://bugs.python.org/techtonik'

bugs.python.org fields:

activity = <Date 2019-02-24.23:42:44.704>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2011-04-05.20:53:24.787>
creator = 'techtonik'
dependencies = []
files = ['26969', '26982', '27003', '27047']
hgrepos = []
issue_num = 11776
keywords = ['patch', 'easy']
message_count = 22.0
messages = ['133089', '133352', '133354', '133365', '133366', '133374', '133376', '166149', '166152', '168864', '168866', '168901', '168933', '168947', '168992', '169156', '169158', '169159', '169397', '336475', '336478', '336491']
nosy_count = 12.0
nosy_names = ['georg.brandl', 'terry.reedy', 'ncoghlan', 'ezio.melotti', 'eric.araujo', 'docs@python', 'guandalino', 'eric.snow', 'mikehoy', 'eamanu', 'cheryl.sabella', 'Tza0987']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue11776'
versions = ['Python 3.7', 'Python 3.8']

[techtonik]

types.MethodType(function, instance) is used as a replacement for new.instancemethod(function, instance, class), but this usage is not documented.

[terryjreedy]

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?

[techtonik]

Message is classified as spam. I am not sure if you see it.

[terryjreedy]

Messages that only consist of links are classified that way. To refer to other issues, use #xxxxx, as with bpo-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.

[terryjreedy]

For anyone curious, I removed the falsely classified as spam message after copying the links into my previous message.

[techtonik]

Nevermind about bpo-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

[birkenfeld]

When we do document types, their constructors and methods should also be documented. This is a valid request.

[techtonik]

Still not documented..

[techtonik]

Another 4 complains about missing references: http://stackoverflow.com/questions/1015307/python-bind-an-unbound-method

[ncoghlan]

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.

[ncoghlan]

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.

[terryjreedy]

"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.

[mikehoy]

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'

[terryjreedy]

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 ....

[mikehoy]

Lambda Changes patch.

[mikehoy]

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.

[mikehoy]

Ezio Melotti was the one that offered to change the wording on MappingProxyType doc

[ezio-melotti]

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.

[mikehoy]

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.

[csabella]

@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!

[eamanu]

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

Okas!

[terryjreedy]

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.