[issue11776] Constructor signatures missing in types module documentation

[Terry J. Reedy]

Terry J. Reedy  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Tz a]

Change by Tz a :


--
nosy: +Tz a

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Emmanuel Arias]

Emmanuel Arias  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Cheryl Sabella]

Cheryl Sabella  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Terry J. Reedy]

Changes by Terry J. Reedy tjre...@udel.edu:


--
nosy:  -techtonik
versions: +Python 3.4, Python 3.5 -Python 3.3

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Eric Snow]

Changes by Eric Snow ericsnowcurren...@gmail.com:


--
nosy: +eric.snow

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Mike Hoy]

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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Mike Hoy]

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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Mike Hoy]

Mike Hoy added the comment:

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

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[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
CodeTypecode 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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Mike Hoy]

Mike Hoy added the comment:

Lambda Changes patch.

--
Added file: 
http://bugs.python.org/file26982/issue11776-first-easy-part-lambda-.diff

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Ezio Melotti]

Changes by Ezio Melotti ezio.melo...@gmail.com:


--
nosy: +ezio.melotti

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Mike Hoy]

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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Terry J. Reedy]

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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Nick Coghlan]

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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Nick Coghlan]

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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11776] Constructor signatures missing in types module documentation

[Terry J. Reedy]

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 rep...@bugs.python.org
http://bugs.python.org/issue11776
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com