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