Documentation for PEP 489

[encukou]

BPO	24458
Nosy	@brettcannon, @ncoghlan, @encukou, @ericsnowcurrently
Files	pep489-docs.patch pep489-docs.2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2015-07-03.17:42:30.175>
created_at = <Date 2015-06-16.11:07:45.903>
labels = ['docs']
title = 'Documentation for PEP 489'
updated_at = <Date 2015-07-03.20:36:27.659>
user = 'https://github.com/encukou'

bugs.python.org fields:

activity = <Date 2015-07-03.20:36:27.659>
actor = 'petr.viktorin'
assignee = 'docs@python'
closed = True
closed_date = <Date 2015-07-03.17:42:30.175>
closer = 'eric.snow'
components = ['Documentation']
creation = <Date 2015-06-16.11:07:45.903>
creator = 'petr.viktorin'
dependencies = []
files = ['39715', '39851']
hgrepos = []
issue_num = 24458
keywords = ['patch']
message_count = 9.0
messages = ['245419', '245688', '246151', '246154', '246155', '246156', '246196', '246197', '246218']
nosy_count = 6.0
nosy_names = ['brett.cannon', 'ncoghlan', 'petr.viktorin', 'docs@python', 'python-dev', 'eric.snow']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue24458'
versions = ['Python 3.5', 'Python 3.6']

[encukou]

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

[ncoghlan]

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.

[encukou]

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.

[python-dev]

New changeset bad92d696866 by Nick Coghlan in branch '3.5':
Close bpo-24458: PEP-489 documentation
https://hg.python.org/cpython/rev/bad92d696866

New changeset 86daa37c1cc9 by Nick Coghlan in branch 'default':
Merge fix for bpo-24458 from 3.5
https://hg.python.org/cpython/rev/86daa37c1cc9

[ncoghlan]

Thanks and, as you can see, merged :)

Am I correct in thinking these docs were the only item remaining for PEP-489?

[encukou]

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.

[ericsnowcurrently]

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.

[ericsnowcurrently]

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

[encukou]

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.