From njs at pobox.com  Fri May 12 04:24:22 2017
From: njs at pobox.com (Nathaniel Smith)
Date: Fri, 12 May 2017 01:24:22 -0700
Subject: [Async-sig] [ann] sphinxcontrib-trio: make sphinx better at
 documenting functions/methods, esp. for async/await code
Message-ID: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>

Hi all,

I just released a new package, sphinxcontrib-trio:

    https://sphinxcontrib-trio.readthedocs.io/

It makes it easier to document many kinds of functions/methods in
sphinx, including async functions, abstract methods, generators, etc.

I originally wrote it for the trio [1] project, hence the name, but
don't let that put you off -- there's nothing about it that's specific
to trio, or even to async/await (except that projects that use
async/await *really need* an extension like this). Really I think this
extension ought to be a standard feature of sphinx. But in the mean
time, it's pretty handy.

-n

[1] https://trio.readthedocs.io

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

From brett at python.org  Fri May 12 12:17:31 2017
From: brett at python.org (Brett Cannon)
Date: Fri, 12 May 2017 16:17:31 +0000
Subject: [Async-sig] [ann] sphinxcontrib-trio: make sphinx better at
 documenting functions/methods, esp. for async/await code
In-Reply-To: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>
References: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>
Message-ID: <CAP1=2W7Wr=d0XseQFrjsjrCptYJd2JMnUhwsuKrD77sT09cZsA@mail.gmail.com>

So are you going to try to upstream this? ;)

On Fri, 12 May 2017 at 01:24 Nathaniel Smith <njs at pobox.com> wrote:

> Hi all,
>
> I just released a new package, sphinxcontrib-trio:
>
>     https://sphinxcontrib-trio.readthedocs.io/
>
> It makes it easier to document many kinds of functions/methods in
> sphinx, including async functions, abstract methods, generators, etc.
>
> I originally wrote it for the trio [1] project, hence the name, but
> don't let that put you off -- there's nothing about it that's specific
> to trio, or even to async/await (except that projects that use
> async/await *really need* an extension like this). Really I think this
> extension ought to be a standard feature of sphinx. But in the mean
> time, it's pretty handy.
>
> -n
>
> [1] https://trio.readthedocs.io
>
> --
> Nathaniel J. Smith -- https://vorpus.org
> _______________________________________________
> 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/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170512/e4301007/attachment.html>

From yselivanov at gmail.com  Fri May 12 12:23:44 2017
From: yselivanov at gmail.com (Yury Selivanov)
Date: Fri, 12 May 2017 09:23:44 -0700
Subject: [Async-sig] [ann] sphinxcontrib-trio: make sphinx better at
 documenting functions/methods, esp. for async/await code
In-Reply-To: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>
References: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>
Message-ID: <CAP1+-CKCMBYJp8f7Oh60oeW9wdS4HXviSHzraKKD7mUVB6ZLnA@mail.gmail.com>

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?

Yury


On May 12, 2017 at 4:24:22 AM, Nathaniel Smith (njs at pobox.com) wrote:
> Hi all,
>
> I just released a new package, sphinxcontrib-trio:
>
> https://sphinxcontrib-trio.readthedocs.io/
>
> It makes it easier to document many kinds of functions/methods in
> sphinx, including async functions, abstract methods, generators, etc.
>
> I originally wrote it for the trio [1] project, hence the name, but
> don't let that put you off -- there's nothing about it that's specific
> to trio, or even to async/await (except that projects that use
> async/await *really need* an extension like this). Really I think this
> extension ought to be a standard feature of sphinx. But in the mean
> time, it's pretty handy.
>
> -n
>
> [1] https://trio.readthedocs.io
>
> --
> Nathaniel J. Smith -- https://vorpus.org
> _______________________________________________
> 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/
>

From njs at pobox.com  Fri May 12 18:29:43 2017
From: njs at pobox.com (Nathaniel Smith)
Date: Fri, 12 May 2017 15:29:43 -0700
Subject: [Async-sig] [ann] sphinxcontrib-trio: make sphinx better at
 documenting functions/methods, esp. for async/await code
In-Reply-To: <CAP1=2W7Wr=d0XseQFrjsjrCptYJd2JMnUhwsuKrD77sT09cZsA@mail.gmail.com>
References: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>
 <CAP1=2W7Wr=d0XseQFrjsjrCptYJd2JMnUhwsuKrD77sT09cZsA@mail.gmail.com>
Message-ID: <CAPJVwBnLOBrem0buTop40ab9ghtkdVVzc9VAnfcgiCe4z4urMw@mail.gmail.com>

[dropped python-announce from CC list]

On Fri, May 12, 2017 at 9:17 AM, Brett Cannon <brett at python.org> wrote:
> So are you going to try to upstream this? ;)

Realistically, for me this is a side-project to a side-project, so it
may require someone else do the integration work, but:
 https://github.com/sphinx-doc/sphinx/issues/3743

-n

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

From njs at pobox.com  Fri May 12 19:10:52 2017
From: njs at pobox.com (Nathaniel Smith)
Date: Fri, 12 May 2017 16:10:52 -0700
Subject: [Async-sig] [ann] sphinxcontrib-trio: make sphinx better at
 documenting functions/methods, esp. for async/await code
In-Reply-To: <CAP1+-CKCMBYJp8f7Oh60oeW9wdS4HXviSHzraKKD7mUVB6ZLnA@mail.gmail.com>
References: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>
 <CAP1+-CKCMBYJp8f7Oh60oeW9wdS4HXviSHzraKKD7mUVB6ZLnA@mail.gmail.com>
Message-ID: <CAPJVwB=N8RnW8wSDzBcZG6e=Q7gb8GRLkJ0e7UAv597oG=ukkw@mail.gmail.com>

[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

From yselivanov at gmail.com  Fri May 12 20:07:02 2017
From: yselivanov at gmail.com (Yury Selivanov)
Date: Fri, 12 May 2017 17:07:02 -0700
Subject: [Async-sig] [ann] sphinxcontrib-trio: make sphinx better at
 documenting functions/methods, esp. for async/await code
In-Reply-To: <CAPJVwB=N8RnW8wSDzBcZG6e=Q7gb8GRLkJ0e7UAv597oG=ukkw@mail.gmail.com>
References: <CAPJVwBn=U4hzYDvgb31Xfg17DqJPk+kGd6SOQMCsaDraiGiqxA@mail.gmail.com>
 <CAP1+-CKCMBYJp8f7Oh60oeW9wdS4HXviSHzraKKD7mUVB6ZLnA@mail.gmail.com>
 <CAPJVwB=N8RnW8wSDzBcZG6e=Q7gb8GRLkJ0e7UAv597oG=ukkw@mail.gmail.com>
Message-ID: <CAP1+-CLYb0=pyWaCNt_WYr0BXoLUZz0GDhUwU8cOBN4jRjZ+yQ@mail.gmail.com>

On May 12, 2017 at 7:10:52 PM, Nathaniel Smith (njs at pobox.com) wrote:
> > - The signatures sphinxcontrib-trio currently renders are
> also valid
> (though unusual), so how do you think it should decide which one
> is
> meant?

Ideally, IMO, it should render it like this:

async with Connection.transaction()
await Connection.transaction()
? ? docstring

> 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 :-).

Yeah, I?m still not sure if it was a good idea :) ?asyncpg uses
this trick for a few APIs.

> - Do you have any examples in mind of sphinx rendering multiple
> signatures for the same function? I'm not sure what that looks
> like.

I *think* I saw Sphinx rendering two function signatures
one on top of another, but I can?t remember where.

Anyways, the extension looks quite useful, I?ll try it out!


Yury

From brett at python.org  Thu May 18 21:17:11 2017
From: brett at python.org (Brett Cannon)
Date: Fri, 19 May 2017 01:17:11 +0000
Subject: [Async-sig] PyCon US 2017 open space on Saturday sometime after
 lunch
Message-ID: <CAP1=2W5ODk5pTJhJtsJA-tgHYNGUhvSM9=3QsX-ywf0_eYTpKQ@mail.gmail.com>

I have not picked a time yet and I can't book it until tomorrow, but the
plan is sometime after lunch on Saturday I will book an async open space.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170519/2bb761ab/attachment.html>

From andrew.svetlov at gmail.com  Thu May 18 23:02:48 2017
From: andrew.svetlov at gmail.com (Andrew Svetlov)
Date: Fri, 19 May 2017 03:02:48 +0000
Subject: [Async-sig] PyCon US 2017 open space on Saturday sometime after
 lunch
In-Reply-To: <CAP1=2W5ODk5pTJhJtsJA-tgHYNGUhvSM9=3QsX-ywf0_eYTpKQ@mail.gmail.com>
References: <CAP1=2W5ODk5pTJhJtsJA-tgHYNGUhvSM9=3QsX-ywf0_eYTpKQ@mail.gmail.com>
Message-ID: <CAL3CFcWLnH-sfSNHig7jOCDAu2265he0urf0Qa3nLeLOQqTBgw@mail.gmail.com>

Ok

On Thu, May 18, 2017, 18:17 Brett Cannon <brett at python.org> wrote:

> I have not picked a time yet and I can't book it until tomorrow, but the
> plan is sometime after lunch on Saturday I will book an async open space.
> _______________________________________________
> 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/20170519/13b07e80/attachment.html>

From guido at python.org  Fri May 19 14:39:26 2017
From: guido at python.org (Guido van Rossum)
Date: Fri, 19 May 2017 11:39:26 -0700
Subject: [Async-sig] PyCon US 2017 open space on Saturday sometime after
 lunch
In-Reply-To: <CAL3CFcWLnH-sfSNHig7jOCDAu2265he0urf0Qa3nLeLOQqTBgw@mail.gmail.com>
References: <CAP1=2W5ODk5pTJhJtsJA-tgHYNGUhvSM9=3QsX-ywf0_eYTpKQ@mail.gmail.com>
 <CAL3CFcWLnH-sfSNHig7jOCDAu2265he0urf0Qa3nLeLOQqTBgw@mail.gmail.com>
Message-ID: <CAP7+vJJgmKRL0SiPe2jVHW0ovZdGvuMWdgy=rimhVWQe+uMagg@mail.gmail.com>

Alas I am held up until around 4pm. Go ahead without me!

On Thu, May 18, 2017 at 8:02 PM, Andrew Svetlov <andrew.svetlov at gmail.com>
wrote:

> Ok
>
> On Thu, May 18, 2017, 18:17 Brett Cannon <brett at python.org> wrote:
>
>> I have not picked a time yet and I can't book it until tomorrow, but the
>> plan is sometime after lunch on Saturday I will book an async open space.
>> _______________________________________________
>> 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/
>
>


-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170519/8f933cdb/attachment.html>

From brett at python.org  Sat May 20 12:19:22 2017
From: brett at python.org (Brett Cannon)
Date: Sat, 20 May 2017 16:19:22 +0000
Subject: [Async-sig] PyCon US 2017 open space on Saturday sometime after
 lunch
In-Reply-To: <CAP1=2W5ODk5pTJhJtsJA-tgHYNGUhvSM9=3QsX-ywf0_eYTpKQ@mail.gmail.com>
References: <CAP1=2W5ODk5pTJhJtsJA-tgHYNGUhvSM9=3QsX-ywf0_eYTpKQ@mail.gmail.com>
Message-ID: <CAP1=2W6KSyxkv4r377Y5BrdhUeO0YdGw_q6do3Jt+jTZZ5Jhew@mail.gmail.com>

This is now scheduled for 15:00/3:00pm today.

On Thu, May 18, 2017, 18:17 Brett Cannon, <brett at python.org> wrote:

> I have not picked a time yet and I can't book it until tomorrow, but the
> plan is sometime after lunch on Saturday I will book an async open space.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170520/38a8db6d/attachment.html>

From gvanrossum at gmail.com  Sat May 20 18:50:51 2017
From: gvanrossum at gmail.com (Guido van Rossum)
Date: Sat, 20 May 2017 15:50:51 -0700
Subject: [Async-sig] PyCon US 2017 open space on Saturday sometime after
 lunch
In-Reply-To: <CAP1=2W6KSyxkv4r377Y5BrdhUeO0YdGw_q6do3Jt+jTZZ5Jhew@mail.gmail.com>
References: <CAP1=2W5ODk5pTJhJtsJA-tgHYNGUhvSM9=3QsX-ywf0_eYTpKQ@mail.gmail.com>
 <CAP1=2W6KSyxkv4r377Y5BrdhUeO0YdGw_q6do3Jt+jTZZ5Jhew@mail.gmail.com>
Message-ID: <CAP7+vJLnfPiZdgH7TPEABUUiQ5yz4SRJQGoYh+Eav1Mbj4K3aw@mail.gmail.com>

Sorry I couldn't make it. Stuck in the mypy open space...

On May 20, 2017 9:19 AM, "Brett Cannon" <brett at python.org> wrote:

> This is now scheduled for 15:00/3:00pm today.
>
> On Thu, May 18, 2017, 18:17 Brett Cannon, <brett at python.org> wrote:
>
>> I have not picked a time yet and I can't book it until tomorrow, but the
>> plan is sometime after lunch on Saturday I will book an async open space.
>
>
> _______________________________________________
> 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/
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170520/ca593ceb/attachment.html>