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
On Sun, Sep 11, 2016 at 11:54 PM, Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
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:
On Mon, Sep 12, 2016 at 3:05 PM, Ned Batchelder <ned@nedbatchelder.com> 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. The history of decision changes is tracked in VCS, if that is desirable. -- Senthil
On Sep 12, 2016, at 03:12 PM, Senthil Kumaran wrote:
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
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 <ned@nedbatchelder.com> wrote:
-- --Guido van Rossum (python.org/~guido)
On Sun, Sep 11, 2016 at 11:54 PM, Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
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:
On Mon, Sep 12, 2016 at 3:05 PM, Ned Batchelder <ned@nedbatchelder.com> 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. The history of decision changes is tracked in VCS, if that is desirable. -- Senthil
On Sep 12, 2016, at 03:12 PM, Senthil Kumaran wrote:
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
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 <ned@nedbatchelder.com> wrote:
-- --Guido van Rossum (python.org/~guido)
participants (6)
-
Andrew Svetlov -
Barry Warsaw -
Guido van Rossum -
Ned Batchelder -
Senthil Kumaran -
Yury Selivanov