An exciting opportunity to update PEP 3156
Guido and I are looking for help with PEP 3156. Currently it's out of sync with the docs. It would be cool if someone could volunteer and update it (at least make sure that all APIs are up to date). Yury
Should Task.current_task() be declared as a part of supported public API?
Should we declare that every asyncio coroutine is executed in a task
context?
On Mon, Sep 12, 2016 at 4:53 AM Yury Selivanov
Guido and I are looking for help with PEP 3156. Currently it's out of sync with the docs. It would be cool if someone could volunteer and update it (at least make sure that all APIs are up to date).
Yury _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov
On Sun, Sep 11, 2016 at 11:54 PM, Andrew Svetlov
Should Task.current_task() be declared as a part of supported public API?
Sure.
Should we declare that every asyncio coroutine is executed in a task context?
What importance does this have? Task.get_current_task() can return None. -- --Guido van Rossum (python.org/~guido)
I'm curious why it's important to update the PEP? I would think the docs should be the official source of truth about the library, and the PEP should be a record of the decisions that lead to the library. Trying to keep both in sync just seems like extra work. Why not put a notice at the top of the PEP indicating that it was accurate when it was accepted, but that changed have happened since then, see the docs for details? --Ned. On 9/11/16 9:53 PM, Yury Selivanov wrote:
Guido and I are looking for help with PEP 3156. Currently it's out of sync with the docs. It would be cool if someone could volunteer and update it (at least make sure that all APIs are up to date).
Yury _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
On Mon, Sep 12, 2016 at 3:05 PM, Ned Batchelder
Why not put a notice at the top of the PEP indicating that it was accurate when it was accepted, but that changed have happened since then, see the docs for details?
I see PEP as the design document and docs as user-friendly documentation. It helps to keep both of them up to date and in sync. If an "Accepted" PEP is not updated, then folks landing on it will feel misguided or confused if the read the docs later. Presenting a cohesive story here is probably more work than simply keeping them in sync. The history of decision changes is tracked in VCS, if that is desirable. -- Senthil
Part of it is that the official docs often aren't all that precise
compared to the PEP. Part of it is that the PEP is still marked
provisional, and we wish to declare it final as of 3.6.0 (or as of
3.6b1, depending on who you talk to). So I'd like to see the "final"
version correspond with the API as of that point.
But I agree it's not super important.
On Mon, Sep 12, 2016 at 3:05 PM, Ned Batchelder
I'm curious why it's important to update the PEP? I would think the docs should be the official source of truth about the library, and the PEP should be a record of the decisions that lead to the library. Trying to keep both in sync just seems like extra work. Why not put a notice at the top of the PEP indicating that it was accurate when it was accepted, but that changed have happened since then, see the docs for details?
--Ned.
On 9/11/16 9:53 PM, Yury Selivanov wrote:
Guido and I are looking for help with PEP 3156. Currently it's out of sync with the docs. It would be cool if someone could volunteer and update it (at least make sure that all APIs are up to date).
Yury _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido)
On Sep 12, 2016, at 03:12 PM, Senthil Kumaran wrote:
I see PEP as the design document and docs as user-friendly documentation. It helps to keep both of them up to date and in sync. If an "Accepted" PEP is not updated, then folks landing on it will feel misguided or confused if the read the docs later. Presenting a cohesive story here is probably more work than simply keeping them in sync.
It's probably appropriate, once a PEP is accepted, implemented, and documented, to include a link from the PEP to the definitive documentation. That could be done in lieu of keeping the PEP strictly in sync as the feature changes.
The history of decision changes is tracked in VCS, if that is desirable.
Not just desirable, an explicit purpose of PEPs! :) https://www.python.org/dev/peps/pep-0001/ Cheers, -Barry
participants (6)
-
Andrew Svetlov -
Barry Warsaw -
Guido van Rossum -
Ned Batchelder -
Senthil Kumaran -
Yury Selivanov