Terry J. Reedy <tjre...@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 <rep...@bugs.python.org>
<https://bugs.python.org/issue11776>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to