[Async-sig] async documentation methods

Tue Jul 4 10:55:55 EDT 2017

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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170704/65058d70/attachment.html>