[issue24458] Documentation for PEP 489
New submission from Petr Viktorin: 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 ---------- assignee: docs@python components: Documentation files: pep489-docs.patch keywords: patch messages: 245419 nosy: brett.cannon, docs@python, encukou, eric.snow, ncoghlan priority: normal severity: normal status: open title: Documentation for PEP 489 versions: Python 3.5, Python 3.6 Added file: http://bugs.python.org/file39715/pep489-docs.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Nick Coghlan added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Petr Viktorin added the comment: 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. ---------- Added file: http://bugs.python.org/file39851/pep489-docs.2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Nick Coghlan added the comment: Thanks and, as you can see, merged :) Am I correct in thinking these docs were the only item remaining for PEP 489? ---------- resolution: fixed -> stage: resolved -> status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Petr Viktorin added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Eric Snow added the comment: 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. ---------- resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Eric Snow added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
Petr Viktorin added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24458> _______________________________________
participants (4)
-
Eric Snow -
Nick Coghlan
-
Petr Viktorin
-
Roundup Robot