async documentation methods
Hi all, I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst: """ ... It [lock] has two basic methods, `acquire()` and `release()`. ... """ In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous: Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`. This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice. Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else? If there's a good example already Python docs or in some 3rd party docs, please tell. Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers? Cheers, d.
I like "two methods, `async acquire()` and `release()`" Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp [2] itself We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions. Additional markup for methods that could be used as async context managers: .. comethod:: delete(url, **kwargs) :async-with: :coroutine: and `:async-for:` for async iterators. 1. https://github.com/aio-libs/sphinxcontrib-asyncio 2. https://github.com/aio-libs/aiohttp On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Hi all,
I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous:
Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice.
Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else?
If there's a good example already Python docs or in some 3rd party docs, please tell.
Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers?
Cheers, d. _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov
Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition. On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions.
Additional markup for methods that could be used as async context managers:
.. comethod:: delete(url, **kwargs) :async-with: :coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio 2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Hi all,
I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous:
Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice.
Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else?
If there's a good example already Python docs or in some 3rd party docs, please tell.
Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers?
Cheers, d. _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
If we're citing curio and sphinxcontrib-asyncio I guess I'll also mention sphinxcontrib-trio [1], which was inspired by both of them (and isn't in any way specific to trio). I don't know if the python docs can use third-party sphinx extensions, though, and it is a bit opinionated (in particular it calls async functions async functions instead of coroutines). For the original text, I'd probably write something like:: You acquire a lock by calling ``await lock.acquire()``, and release it with ``lock.release()``. -n [1] https://sphinxcontrib-trio.readthedocs.io/en/latest/ On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote:
Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition.
On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions.
Additional markup for methods that could be used as async context managers:
.. comethod:: delete(url, **kwargs) :async-with: :coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio 2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Hi all,
I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous:
Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice.
Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else?
If there's a good example already Python docs or in some 3rd party docs, please tell.
Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers?
Cheers, d. _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Nathaniel J. Smith -- https://vorpus.org
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while? Nathaniel Smith kirjoitti 01.07.2017 klo 13:35:
If we're citing curio and sphinxcontrib-asyncio I guess I'll also mention sphinxcontrib-trio [1], which was inspired by both of them (and isn't in any way specific to trio). I don't know if the python docs can use third-party sphinx extensions, though, and it is a bit opinionated (in particular it calls async functions async functions instead of coroutines).
For the original text, I'd probably write something like::
You acquire a lock by calling ``await lock.acquire()``, and release it with ``lock.release()``.
-n
[1] https://sphinxcontrib-trio.readthedocs.io/en/latest/
On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote:
Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition.
On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions.
Additional markup for methods that could be used as async context managers:
.. comethod:: delete(url, **kwargs) :async-with: :coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio 2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Hi all,
I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous:
Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice.
Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else?
If there's a good example already Python docs or in some 3rd party docs, please tell.
Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers?
Cheers, d. _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/ -- Thanks, Andrew Svetlov
Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while?
It looks like this is the issue (which Brett filed in Nov. 2015): https://github.com/sphinx-doc/sphinx/issues/2105 --Chris
Nathaniel Smith kirjoitti 01.07.2017 klo 13:35:
If we're citing curio and sphinxcontrib-asyncio I guess I'll also mention sphinxcontrib-trio [1], which was inspired by both of them (and isn't in any way specific to trio). I don't know if the python docs can use third-party sphinx extensions, though, and it is a bit opinionated (in particular it calls async functions async functions instead of coroutines).
For the original text, I'd probably write something like::
You acquire a lock by calling ``await lock.acquire()``, and release it with ``lock.release()``.
-n
[1] https://sphinxcontrib-trio.readthedocs.io/en/latest/
On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote:
Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition.
On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions.
Additional markup for methods that could be used as async context managers:
.. comethod:: delete(url, **kwargs) :async-with: :coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio 2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Hi all,
I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous:
Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice.
Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else?
If there's a good example already Python docs or in some 3rd party docs, please tell.
Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers?
Cheers, d. _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
Yeah, but that doesn't answer my question :) Chris Jerdonek kirjoitti 04.07.2017 klo 10:02:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while? It looks like this is the issue (which Brett filed in Nov. 2015): https://github.com/sphinx-doc/sphinx/issues/2105
--Chris
Nathaniel Smith kirjoitti 01.07.2017 klo 13:35:
If we're citing curio and sphinxcontrib-asyncio I guess I'll also mention sphinxcontrib-trio [1], which was inspired by both of them (and isn't in any way specific to trio). I don't know if the python docs can use third-party sphinx extensions, though, and it is a bit opinionated (in particular it calls async functions async functions instead of coroutines).
For the original text, I'd probably write something like::
You acquire a lock by calling ``await lock.acquire()``, and release it with ``lock.release()``.
-n
[1] https://sphinxcontrib-trio.readthedocs.io/en/latest/
On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote:
Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition.
On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions.
Additional markup for methods that could be used as async context managers:
.. comethod:: delete(url, **kwargs) :async-with: :coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio 2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Hi all,
I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous:
Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice.
Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else?
If there's a good example already Python docs or in some 3rd party docs, please tell.
Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers?
Cheers, d. _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/ -- Thanks, Andrew Svetlov
Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
Come to think of it, what sane tests need is a custom event loop or clever mocks around asyncio.sleep, asyncio.Condition.wait, etc. So that code under test never sleeps. In simple cases actual delay in the event loop would raise an exception. A full solution would synchronise asyncio.sleep and friends with time.time, time.monotonic and friends, so that a if the loop were to delay, it would advance global/virtual time instead. I think I saw such library for synchronous code, probably with limitations... In any case you should not have to add delays in your mocks or fixtures to hack specific order of task execution by the event loop. My 2c, D. On Jul 4, 2017 9:34 AM, "Alex Grönholm" <alex.gronholm@nextday.fi> wrote:
Yeah, but that doesn't answer my question :)
Chris Jerdonek kirjoitti 04.07.2017 klo 10:02:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while?
It looks like this is the issue (which Brett filed in Nov. 2015): https://github.com/sphinx-doc/sphinx/issues/2105
--Chris
Nathaniel Smith kirjoitti 01.07.2017 klo 13:35:
If we're citing curio and sphinxcontrib-asyncio I guess I'll also mention sphinxcontrib-trio [1], which was inspired by both of them (and isn't in any way specific to trio). I don't know if the python docs can use third-party sphinx extensions, though, and it is a bit opinionated (in particular it calls async functions async functions instead of coroutines).
For the original text, I'd probably write something like::
You acquire a lock by calling ``await lock.acquire()``, and release it with ``lock.release()``.
-n
[1] https://sphinxcontrib-trio.readthedocs.io/en/latest/
On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote:
Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition.
On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions.
Additional markup for methods that could be used as async context managers:
.. comethod:: delete(url, **kwargs) :async-with: :coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio 2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
> Hi all, > > I'm working to improve async docs, and I wonder if/how async methods > ought to be marked in the documentation, for example > library/async-sync.rst: > > """ ... It [lock] has two basic methods, `acquire()` and `release()`. > ... > """ > > In fact, these methods are not symmetric, the earlier is asynchronous > and the latter synchronous: > > Definitions are `async def acquire()` and `def release()`. > Likewise user is expected to call `await .acquire()` and > `.release()`. > > This is user-facing documentation, IMO it should be clearer. > Although there are examples for this specific case, I'm concerned > with > general documentation best practice. > > Should this example read, e.g.: > * two methods, `async acquire()` and `release()` > or perhaps > * two methods, used `await x.acquire()` and `x.release()` > or something else? > > If there's a good example already Python docs or in some 3rd party > docs, please tell. > > Likewise, should there be marks on iterators? async generators? > things > that ought to be used as context managers? > > Cheers, > d. > _______________________________________________ > Async-sig mailing list > Async-sig@python.org > https://mail.python.org/mailman/listinfo/async-sig > Code of Conduct: https://www.python.org/psf/codeofconduct/ > -- Thanks, Andrew Svetlov _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
Did you look on https://github.com/python/cpython/blob/master/Lib/asyncio/test_utils.py#L265 ? On Tue, Jul 4, 2017 at 1:04 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Come to think of it, what sane tests need is a custom event loop or clever mocks around asyncio.sleep, asyncio.Condition.wait, etc. So that code under test never sleeps.
In simple cases actual delay in the event loop would raise an exception.
A full solution would synchronise asyncio.sleep and friends with time.time, time.monotonic and friends, so that a if the loop were to delay, it would advance global/virtual time instead. I think I saw such library for synchronous code, probably with limitations...
In any case you should not have to add delays in your mocks or fixtures to hack specific order of task execution by the event loop.
My 2c, D.
On Jul 4, 2017 9:34 AM, "Alex Grönholm" <alex.gronholm@nextday.fi> wrote:
Yeah, but that doesn't answer my question :)
Chris Jerdonek kirjoitti 04.07.2017 klo 10:02:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while?
It looks like this is the issue (which Brett filed in Nov. 2015): https://github.com/sphinx-doc/sphinx/issues/2105
--Chris
Nathaniel Smith kirjoitti 01.07.2017 klo 13:35:
If we're citing curio and sphinxcontrib-asyncio I guess I'll also mention sphinxcontrib-trio [1], which was inspired by both of them (and isn't in any way specific to trio). I don't know if the python docs can use third-party sphinx extensions, though, and it is a bit opinionated (in particular it calls async functions async functions instead of coroutines).
For the original text, I'd probably write something like::
You acquire a lock by calling ``await lock.acquire()``, and release it with ``lock.release()``.
-n
[1] https://sphinxcontrib-trio.readthedocs.io/en/latest/
On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote:
Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition.
On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com > wrote:
> I like "two methods, `async acquire()` and `release()`" > > Regarding to extra markups -- I created sphinxcontrib-asyncio [1] > library > for it. Hmm, README is pretty empty but we do use the library for > documenting aio-libs and aiohttp [2] itself > > We use ".. comethod:: connect(request)" for method and "cofunction" > for > top level functions. > > Additional markup for methods that could be used as async context > managers: > > .. comethod:: delete(url, **kwargs) > :async-with: > :coroutine: > > and `:async-for:` for async iterators. > > > 1. https://github.com/aio-libs/sphinxcontrib-asyncio > 2. https://github.com/aio-libs/aiohttp > > On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> > wrote: > >> Hi all, >> >> I'm working to improve async docs, and I wonder if/how async methods >> ought to be marked in the documentation, for example >> library/async-sync.rst: >> >> """ ... It [lock] has two basic methods, `acquire()` and >> `release()`. >> ... >> """ >> >> In fact, these methods are not symmetric, the earlier is >> asynchronous >> and the latter synchronous: >> >> Definitions are `async def acquire()` and `def release()`. >> Likewise user is expected to call `await .acquire()` and >> `.release()`. >> >> This is user-facing documentation, IMO it should be clearer. >> Although there are examples for this specific case, I'm concerned >> with >> general documentation best practice. >> >> Should this example read, e.g.: >> * two methods, `async acquire()` and `release()` >> or perhaps >> * two methods, used `await x.acquire()` and `x.release()` >> or something else? >> >> If there's a good example already Python docs or in some 3rd party >> docs, please tell. >> >> Likewise, should there be marks on iterators? async generators? >> things >> that ought to be used as context managers? >> >> Cheers, >> d. >> _______________________________________________ >> Async-sig mailing list >> Async-sig@python.org >> https://mail.python.org/mailman/listinfo/async-sig >> Code of Conduct: https://www.python.org/psf/codeofconduct/ >> > -- > Thanks, > Andrew Svetlov > _______________________________________________ > Async-sig mailing list > Async-sig@python.org > https://mail.python.org/mailman/listinfo/async-sig > Code of Conduct: https://www.python.org/psf/codeofconduct/ >
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov
That's good start, looks like it would satisfy asyncio-only code :) I haven't noticed that earlier. On 4 July 2017 at 16:40, Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
Did you look on https://github.com/python/cpython/blob/master/Lib/asyncio/test_utils.py#L265 ?
On Tue, Jul 4, 2017 at 1:04 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Come to think of it, what sane tests need is a custom event loop or clever mocks around asyncio.sleep, asyncio.Condition.wait, etc. So that code under test never sleeps.
In simple cases actual delay in the event loop would raise an exception.
A full solution would synchronise asyncio.sleep and friends with time.time, time.monotonic and friends, so that a if the loop were to delay, it would advance global/virtual time instead. I think I saw such library for synchronous code, probably with limitations...
In any case you should not have to add delays in your mocks or fixtures to hack specific order of task execution by the event loop.
My 2c, D.
On Jul 4, 2017 9:34 AM, "Alex Grönholm" <alex.gronholm@nextday.fi> wrote:
Yeah, but that doesn't answer my question :)
Chris Jerdonek kirjoitti 04.07.2017 klo 10:02:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while?
It looks like this is the issue (which Brett filed in Nov. 2015): https://github.com/sphinx-doc/sphinx/issues/2105
--Chris
Nathaniel Smith kirjoitti 01.07.2017 klo 13:35:
If we're citing curio and sphinxcontrib-asyncio I guess I'll also mention sphinxcontrib-trio [1], which was inspired by both of them (and isn't in any way specific to trio). I don't know if the python docs can use third-party sphinx extensions, though, and it is a bit opinionated (in particular it calls async functions async functions instead of coroutines).
For the original text, I'd probably write something like::
You acquire a lock by calling ``await lock.acquire()``, and release it with ``lock.release()``.
-n
[1] https://sphinxcontrib-trio.readthedocs.io/en/latest/
On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote: > > Curio uses `.. asyncfunction:: acquire` and it renders as `await > acquire()` > at least in the function definition. > > On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov > <andrew.svetlov@gmail.com> > wrote: >> >> I like "two methods, `async acquire()` and `release()`" >> >> Regarding to extra markups -- I created sphinxcontrib-asyncio [1] >> library >> for it. Hmm, README is pretty empty but we do use the library for >> documenting aio-libs and aiohttp [2] itself >> >> We use ".. comethod:: connect(request)" for method and "cofunction" >> for >> top level functions. >> >> Additional markup for methods that could be used as async context >> managers: >> >> .. comethod:: delete(url, **kwargs) >> :async-with: >> :coroutine: >> >> and `:async-for:` for async iterators. >> >> >> 1. https://github.com/aio-libs/sphinxcontrib-asyncio >> 2. https://github.com/aio-libs/aiohttp >> >> On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> >> wrote: >>> >>> Hi all, >>> >>> I'm working to improve async docs, and I wonder if/how async >>> methods >>> ought to be marked in the documentation, for example >>> library/async-sync.rst: >>> >>> """ ... It [lock] has two basic methods, `acquire()` and >>> `release()`. >>> ... >>> """ >>> >>> In fact, these methods are not symmetric, the earlier is >>> asynchronous >>> and the latter synchronous: >>> >>> Definitions are `async def acquire()` and `def release()`. >>> Likewise user is expected to call `await .acquire()` and >>> `.release()`. >>> >>> This is user-facing documentation, IMO it should be clearer. >>> Although there are examples for this specific case, I'm concerned >>> with >>> general documentation best practice. >>> >>> Should this example read, e.g.: >>> * two methods, `async acquire()` and `release()` >>> or perhaps >>> * two methods, used `await x.acquire()` and `x.release()` >>> or something else? >>> >>> If there's a good example already Python docs or in some 3rd party >>> docs, please tell. >>> >>> Likewise, should there be marks on iterators? async generators? >>> things >>> that ought to be used as context managers? >>> >>> Cheers, >>> d. >>> _______________________________________________ >>> Async-sig mailing list >>> Async-sig@python.org >>> https://mail.python.org/mailman/listinfo/async-sig >>> Code of Conduct: https://www.python.org/psf/codeofconduct/ >> >> -- >> Thanks, >> Andrew Svetlov >> _______________________________________________ >> Async-sig mailing list >> Async-sig@python.org >> https://mail.python.org/mailman/listinfo/async-sig >> Code of Conduct: https://www.python.org/psf/codeofconduct/ > > > _______________________________________________ > Async-sig mailing list > Async-sig@python.org > https://mail.python.org/mailman/listinfo/async-sig > Code of Conduct: https://www.python.org/psf/codeofconduct/ >
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov
I'm an author of this code but I can confirm -- usage experience is terrible. Mostly because the loop don't advance virtual time only but tries to control every loop sleep. On Tue, Jul 4, 2017 at 5:50 PM Dima Tisnek <dimaqq@gmail.com> wrote:
That's good start, looks like it would satisfy asyncio-only code :)
I haven't noticed that earlier.
On 4 July 2017 at 16:40, Andrew Svetlov <andrew.svetlov@gmail.com> wrote:
Did you look on
?
On Tue, Jul 4, 2017 at 1:04 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Come to think of it, what sane tests need is a custom event loop or
clever
mocks around asyncio.sleep, asyncio.Condition.wait, etc. So that code under test never sleeps.
In simple cases actual delay in the event loop would raise an exception.
A full solution would synchronise asyncio.sleep and friends with time.time, time.monotonic and friends, so that a if the loop were to delay, it would advance global/virtual time instead. I think I saw such
synchronous code, probably with limitations...
In any case you should not have to add delays in your mocks or fixtures to hack specific order of task execution by the event loop.
My 2c, D.
On Jul 4, 2017 9:34 AM, "Alex Grönholm" <alex.gronholm@nextday.fi> wrote:
Yeah, but that doesn't answer my question :)
Chris Jerdonek kirjoitti 04.07.2017 klo 10:02:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while?
It looks like this is the issue (which Brett filed in Nov. 2015): https://github.com/sphinx-doc/sphinx/issues/2105
--Chris
Nathaniel Smith kirjoitti 01.07.2017 klo 13:35: > > If we're citing curio and sphinxcontrib-asyncio I guess I'll also > mention sphinxcontrib-trio [1], which was inspired by both of them > (and isn't in any way specific to trio). I don't know if the python > docs can use third-party sphinx extensions, though, and it is a bit > opinionated (in particular it calls async functions async functions > instead of coroutines). > > For the original text, I'd probably write something like:: > > You acquire a lock by calling ``await lock.acquire()``, and > release > it with ``lock.release()``. > > -n > > [1] https://sphinxcontrib-trio.readthedocs.io/en/latest/ > > On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> > wrote: >> >> Curio uses `.. asyncfunction:: acquire` and it renders as `await >> acquire()` >> at least in the function definition. >> >> On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov >> <andrew.svetlov@gmail.com> >> wrote: >>> >>> I like "two methods, `async acquire()` and `release()`" >>> >>> Regarding to extra markups -- I created sphinxcontrib-asyncio [1] >>> library >>> for it. Hmm, README is pretty empty but we do use the library for >>> documenting aio-libs and aiohttp [2] itself >>> >>> We use ".. comethod:: connect(request)" for method and
"cofunction"
>>> for >>> top level functions. >>> >>> Additional markup for methods that could be used as async context >>> managers: >>> >>> .. comethod:: delete(url, **kwargs) >>> :async-with: >>> :coroutine: >>> >>> and `:async-for:` for async iterators. >>> >>> >>> 1. https://github.com/aio-libs/sphinxcontrib-asyncio >>> 2. https://github.com/aio-libs/aiohttp >>> >>> On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> >>> wrote: >>>> >>>> Hi all, >>>> >>>> I'm working to improve async docs, and I wonder if/how async >>>> methods >>>> ought to be marked in the documentation, for example >>>> library/async-sync.rst: >>>> >>>> """ ... It [lock] has two basic methods, `acquire()` and >>>> `release()`. >>>> ... >>>> """ >>>> >>>> In fact, these methods are not symmetric, the earlier is >>>> asynchronous >>>> and the latter synchronous: >>>> >>>> Definitions are `async def acquire()` and `def release()`. >>>> Likewise user is expected to call `await .acquire()` and >>>> `.release()`. >>>> >>>> This is user-facing documentation, IMO it should be clearer. >>>> Although there are examples for this specific case, I'm concerned >>>> with >>>> general documentation best practice. >>>> >>>> Should this example read, e.g.: >>>> * two methods, `async acquire()` and `release()` >>>> or perhaps >>>> * two methods, used `await x.acquire()` and `x.release()` >>>> or something else? >>>> >>>> If there's a good example already Python docs or in some 3rd
https://github.com/python/cpython/blob/master/Lib/asyncio/test_utils.py#L265 library for party
>>>> docs, please tell. >>>> >>>> Likewise, should there be marks on iterators? async generators? >>>> things >>>> that ought to be used as context managers? >>>> >>>> Cheers, >>>> d. >>>> _______________________________________________ >>>> Async-sig mailing list >>>> Async-sig@python.org >>>> https://mail.python.org/mailman/listinfo/async-sig >>>> Code of Conduct: https://www.python.org/psf/codeofconduct/ >>> >>> -- >>> Thanks, >>> Andrew Svetlov >>> _______________________________________________ >>> Async-sig mailing list >>> Async-sig@python.org >>> https://mail.python.org/mailman/listinfo/async-sig >>> Code of Conduct: https://www.python.org/psf/codeofconduct/ >> >> >> _______________________________________________ >> Async-sig mailing list >> Async-sig@python.org >> https://mail.python.org/mailman/listinfo/async-sig >> Code of Conduct: https://www.python.org/psf/codeofconduct/ >> > _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov
-- Thanks, Andrew Svetlov
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while?
Because no-one's sent them a PR, I assume. They're pretty swamped AFAICT. One of the maintainers has at least expressed interest in integrating something like sphinxcontrib-trio if someone does the work: https://github.com/sphinx-doc/sphinx/issues/3743 -n -- Nathaniel J. Smith -- https://vorpus.org
I'm somewhat reluctant to send them any PRs anymore since I sent them a couple of one liner fixes (with tests) which took around 5 months to get merged in spite of me repeatedly reminding them on the Google group. Nathaniel Smith kirjoitti 04.07.2017 klo 10:55:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while? Because no-one's sent them a PR, I assume. They're pretty swamped AFAICT.
One of the maintainers has at least expressed interest in integrating something like sphinxcontrib-trio if someone does the work: https://github.com/sphinx-doc/sphinx/issues/3743
-n
If no one is willing to take the time to send them a PR then the situation is simply not going to change until the project maintainers have both the time and inclination to add async/await markup support to Sphinx, and if they personally aren't doing any async coding then that won't change anytime soon. Probably the best way forward is to reach consensus on the appropriate issue on how the solution should look in a PR they would accept, and then create the PR. But as project maintainer myself I'm not about to hold it against them for having not taken care of this. On Tue, 4 Jul 2017 at 01:57 Alex Grönholm <alex.gronholm@nextday.fi> wrote:
I'm somewhat reluctant to send them any PRs anymore since I sent them a couple of one liner fixes (with tests) which took around 5 months to get merged in spite of me repeatedly reminding them on the Google group.
Nathaniel Smith kirjoitti 04.07.2017 klo 10:55:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while? Because no-one's sent them a PR, I assume. They're pretty swamped AFAICT.
One of the maintainers has at least expressed interest in integrating something like sphinxcontrib-trio if someone does the work: https://github.com/sphinx-doc/sphinx/issues/3743
-n
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
I think the code itself is not beg deal (I could commit on the task if needed) but we need an agreement about markup and output formatting. On Tue, Jul 4, 2017 at 7:48 PM Brett Cannon <brett@python.org> wrote:
If no one is willing to take the time to send them a PR then the situation is simply not going to change until the project maintainers have both the time and inclination to add async/await markup support to Sphinx, and if they personally aren't doing any async coding then that won't change anytime soon.
Probably the best way forward is to reach consensus on the appropriate issue on how the solution should look in a PR they would accept, and then create the PR. But as project maintainer myself I'm not about to hold it against them for having not taken care of this.
On Tue, 4 Jul 2017 at 01:57 Alex Grönholm <alex.gronholm@nextday.fi> wrote:
I'm somewhat reluctant to send them any PRs anymore since I sent them a couple of one liner fixes (with tests) which took around 5 months to get merged in spite of me repeatedly reminding them on the Google group.
Nathaniel Smith kirjoitti 04.07.2017 klo 10:55:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm < alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of support for async functions which have been part of the language for quite a while? Because no-one's sent them a PR, I assume. They're pretty swamped AFAICT.
One of the maintainers has at least expressed interest in integrating something like sphinxcontrib-trio if someone does the work: https://github.com/sphinx-doc/sphinx/issues/3743
-n
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
_______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
-- Thanks, Andrew Svetlov
Hi Dima, Have you seen https://github.com/asyncio-docs? I'm trying to get some work going there to improve asyncio docs in 3.7. Will start committing more of my time there soon. Thanks, Yury On Jun 30, 2017, 6:11 AM -0400, Dima Tisnek <dimaqq@gmail.com>, wrote:
Hi all,
I'm working to improve async docs, and I wonder if/how async methods ought to be marked in the documentation, for example library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
In fact, these methods are not symmetric, the earlier is asynchronous and the latter synchronous:
Definitions are `async def acquire()` and `def release()`. Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer. Although there are examples for this specific case, I'm concerned with general documentation best practice.
Should this example read, e.g.: * two methods, `async acquire()` and `release()` or perhaps * two methods, used `await x.acquire()` and `x.release()` or something else?
If there's a good example already Python docs or in some 3rd party docs, please tell.
Likewise, should there be marks on iterators? async generators? things that ought to be used as context managers?
Cheers, d. _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
participants (7)
-
Alex Grönholm -
Andrew Svetlov -
Brett Cannon -
Chris Jerdonek -
Dima Tisnek -
Nathaniel Smith -
Yury Selivanov