[Async-sig] async documentation methods

Tue Jul 4 10:40:54 EDT 2017

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