classification
Title: Documentation for PEP 489
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, encukou, eric.snow, ncoghlan, python-dev
Priority: normal Keywords: patch

Created on 2015-06-16 11:07 by encukou, last changed 2015-07-03 20:36 by encukou. This issue is now closed.

Files
File name Uploaded Description Edit
pep489-docs.patch encukou, 2015-06-16 11:07 review
pep489-docs.2.patch encukou, 2015-07-03 08:46 review
Messages (9)
msg245419 - (view) Author: Petr Viktorin (encukou) * Date: 2015-06-16 11:07
Hello,
Here is a patch documenting PEP 489.

I don't feel comfortable rewriting the tutorial [0] yet: before the issue with callbacks/module state [1] is solved, which is 3.6 material, multi-phase init is not suitable for all modules.
So everything in PEP 489 is described in reference-style documentation.


[0] https://docs.python.org/3/extending/extending.html
[1] https://www.python.org/dev/peps/pep-0489/#module-state-and-c-level-callbacks
msg245688 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2015-06-23 13:23
Leaving the tutorial alone until the callback problem is resolved makes sense to me.

The patch overall looks good, I sent a few more detailed comments via Rietveld.
msg246151 - (view) Author: Petr Viktorin (encukou) * Date: 2015-07-03 08:46
Thanks for the review.

I've added the explanation you suggested, and I've made the names monospace (or linked them, where it seemed appropriate). I've also marked *NULL*s like in the rest of the doc.
msg246154 - (view) Author: Roundup Robot (python-dev) Date: 2015-07-03 09:52
New changeset bad92d696866 by Nick Coghlan in branch '3.5':
Close #24458: PEP 489 documentation
https://hg.python.org/cpython/rev/bad92d696866

New changeset 86daa37c1cc9 by Nick Coghlan in branch 'default':
Merge fix for #24458 from 3.5
https://hg.python.org/cpython/rev/86daa37c1cc9
msg246155 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2015-07-03 09:54
Thanks and, as you can see, merged :)

Am I correct in thinking these docs were the only item remaining for PEP 489?
msg246156 - (view) Author: Petr Viktorin (encukou) * Date: 2015-07-03 10:02
Yes!

Aside from the callback problem, which is left for another PEP, but limits PEP 489 usefulness in the real world :(
It turns out that one is quite a rabbit hole. I'll post my findings on that soon-ish.
msg246196 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2015-07-03 17:42
Sorry I didn't get a review in before.  Since subinterpreters and multi-phase initialization are on my mind, I have a couple questions:

Should there be a note in the "Single-phase initialization" section (perhaps at the top of the section) that encourages use of multi-phase initialization?

Would it be worth demonstrating how a module might be verified to work with subinterpreters (as indicated in the multi-phase section)?  An example with a brief main function would likely be sufficient.  If it's not obvious how to do it then module authors may not consider it worth the trouble.  If all goes well then subinterpreters will be exposed in Python in 3.6 which will make such testing much easier.
msg246197 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2015-07-03 17:43
What is the level of impact of the callback problem?  Of the 4 scenarios in [1], it seems to me like #1 (C callbacks w/o a module reference) would be the most common.  However, can't that be addressed by adjusting the API, so it would only be a big problem in the case of a public C-API for the module (where backward-compatibility is a concern)?  #3 (classes have no reference to the module) sounds like the most problematic but how common a problem is it practice?

It may be worth including an explicit note in the multi-phase section on the scenarios that currently don't lend themselves well to multi-phase initialization.  It would also be great to indicate how to work around those issues (or the cases where for now it's better to just use single-phase initialization).

FWIW, the matter ties in directly to the work I'm doing with subinterpreters right now.

[1] https://mail.python.org/pipermail/import-sig/2015-April/000959.html
msg246218 - (view) Author: Petr Viktorin (encukou) * Date: 2015-07-03 20:36
Verifying modules to work ith subinterpreters is tricky. What level of assurance do you want?
Subinterpreters themselves require that you embed Python, which doesn't lend itself to an easy example. I hope 2.6 makes the situation better.
Example code is in xxmodule, which is mentioned.


The #3 problem is pretty common, unfortunately: if you define a Database class and a Record class, Database objects can't get to the Record class to instantiate it. If you define a module-level exception, methods of other classes can't easily raise it.
I think recommending workarounds/solutions needs some more discussion; I plan to summarize my thoughts on a mailing list soonish.
History
Date User Action Args
2015-07-03 20:36:27encukousetmessages: + msg246218
2015-07-03 17:43:02eric.snowsetmessages: + msg246197
2015-07-03 17:42:30eric.snowsetstatus: open -> closed
resolution: fixed
messages: + msg246196

stage: resolved
2015-07-03 10:02:18encukousetmessages: + msg246156
2015-07-03 09:54:38ncoghlansetstatus: closed -> open
resolution: fixed -> (no value)
messages: + msg246155

stage: resolved -> (no value)
2015-07-03 09:52:18python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg246154

resolution: fixed
stage: resolved
2015-07-03 08:46:10encukousetfiles: + pep489-docs.2.patch

messages: + msg246151
2015-06-23 13:23:45ncoghlansetmessages: + msg245688
2015-06-16 11:07:46encukoucreate