[Async-sig] [ann] sphinxcontrib-trio: make sphinx better at documenting functions/methods, esp. for async/await code

[Nathaniel Smith]

[dropped python-announce from CC list]

On Fri, May 12, 2017 at 9:23 AM, Yury Selivanov <yselivanov at gmail.com> wrote:
> I like it!
>
> Do you have support for hybrid iterators/context managers:
>
>   async with con.transaction() as tr
>   # or
>   tr = await con.transaction()
>
> and
>
>   async for row in con.cursor(’SELECT …')
>   # or
>   cur = await con.cursor(‘SELECT …’)
>
> I.e. if I annotate `con.transaction` with both `:async:` and
> `:async-with:`, will it render two signatures?

Right now if you combine those options then you'll get something like
"async with await con.transaction() as tr" and "async for row in await
con.cursor(sql_query)". Of course, the code generating this is
trivial; just some if statements to construct strings, so it wouldn't
be hard to make it do something different. But two questions:

- The signatures sphinxcontrib-trio currently renders are also valid
(though unusual), so how do you think it should decide which one is
meant? I can see why your API looks like that, but it is a bit
clever... as you know my personal style guide is that functions should
either support being called like 'await foo()' or 'foo()' but never
both :-).

- Do you have any examples in mind of sphinx rendering multiple
signatures for the same function? I'm not sure what that looks like.
Keep in mind that this is the actual signature at the top of the docs
for the function, not like example code or something... so it would
never say 'SELECT ...' anyway, it would have a list of the
args+kwargs.

-n

-- 
Nathaniel J. Smith -- https://vorpus.org