Let me suggest then that the SC not try to micro-manage this one. The people in favor of this are happy to accept whatever namespace the SC would like. That’s about the higher-level view of how the language should evolve.
The docs aren’t at all a focus of this PEP, and IMO the PEP would be better off not even mentioning them. And so would the SC. They got just dragged in. As @skirpichev said, doc improvements would follow from the adoption, but as “an additional bonus”. Why? Because doc changes would be necessary, and part of the work of implementation. We already have years of empirical evidence saying that nobody is willing to devote time to that as-is. They’ll talk without end, but not volunteer the work.
It should, I think, be all but obvious that adopting the PEP would have scant chance of making the docs worse. Good enough! It’s not a “doc PEP” at heart to begin with.
I expect that the docstrings for the functions will be the same in a separate namespace to what they are now (except for the module name, obviously).
By “separated”, do you necessarily mean in a separate page, or would more distinction in the current page be sufficient? There could be one section about floating point functions, and one section about integer function in the same page, and I don’t think that it would get too much pushback. The documentation pages for each module are already not uniform at all.
To be explicit, I’m not against creating a submodule for integer functions, but I argue that the documentation is not a good motivation in this case.
Discussion threads are here to help authors to make proposals as much clear and solid technically, right?
For my humble opinion, it’s authors job to keep PEP content up to date with discussion thread and arguments raised here. Anyone is free to comment on PEP edit PRs. Of course, there are always risks to miss something in discussion, but in principle PEP content should be enough to make decisions.
I think that problems of current documentation are good to mention as illustration that the current module scope is too broad.
I’ll think on how to better rephrase/cut-off the Motivation section, but don’t see obvious way right now, all paragraphs seems relevant. But currently, I would rather add some paragraph to show how module context could be used in docstrings to make them descriptive, helpful and compact.
IIUIC, SC now have strong preference for submodule variant with a specific name (math.integer).
Is this correct, @barry, other options already loose? If so, I can update PEP to use submodule scheme.
And this will fix many (if not all) problems with existing docstrings, as new namespace will provide a specific context for users: they will expect certain behavior from functions and a specific API.
But the question was: what we should do without a new namespace?
If the new module name is math.integer, would not it be the first precedence of nested extension module and the first precedence of using an extension module as a package? I’m not sure if this will cause any problems.
Because there are many subtle differences between Python and extension functions, classes and modules. And since this is our first time of doing this (creating an extension submodule of an extension module), we may discover more differences, whether they matter or not. This is an unknown territory.
On behalf of the Steering Council, I’m very happy to say that we have accepted PEP 791. Thank you for updating the PEP to reflect our feedback, and congratulations @skirpichev. Thank you to @vstinner for your sponsorship of the PEP.
The PEP title was updated, but it looks like there is one residual mention of intmath worth fixing. When you change the Status, please also fix the PEP’s mention of intmath → math.integer in the Specification section.
I managed to fix Argument Clinic. Then there were problems with configure, I somehow managed to fix them too (this may not be the final solution). But now the problem is that math is not a package. How to import a submodule of the extension module? BTW, import sys.monitoring does not work either.
This section mention the intmath PyPI package. I don’t see good reasons to change naming here, it’s just a way to provide same namespace for old releases:
import intmath
import math
math.integer = intmath
vs
import math.integer
I see only one place in the section, related to isqrt. Will fix.