ABSTRACT
I propose that every asyncio function that is a coroutine gets a
highly visible marker at the top of its entry in the documentation.
For example the entry for StreamWriter.drain() [1] should read:
drain() -> {{coroutine}}
Let the write buffer of the underlying transport ...
This is
Hi,
2015-02-12 12:51 GMT+01:00 Luciano Ramalho :
> This is more visible than a sentence like "This method is a
> coroutine." buried somewhere in its description.
We should keep this sentence *and* add the return type in the doc.
I tried to add " -> coroutine":
.. method:: BaseEventLoop.create_c
I like to have simple markup for coroutines but -1 for using return
annotation for that.
Return annotation is for return value description, not for function itself.
On Thu, Feb 12, 2015 at 6:06 PM, Victor Stinner
wrote:
> Hi,
>
> 2015-02-12 12:51 GMT+01:00 Luciano Ramalho :
>> This is more visibl
On Thu, Feb 12, 2015 at 2:12 PM, Andrew Svetlov
wrote:
> I like to have simple markup for coroutines but -1 for using return
> annotation for that.
> Return annotation is for return value description, not for function itself.
Perhaps we need a variation of the return value notation for generator
2015-02-12 17:12 GMT+01:00 Andrew Svetlov :
> I like to have simple markup for coroutines but -1 for using return
> annotation for that.
> Return annotation is for return value description, not for function itself.
A coroutine function returns a coroutine object. So the annotation "->
coroutine" i
On Thu, Feb 12, 2015 at 11:31 AM, Victor Stinner
wrote:
> 2015-02-12 17:12 GMT+01:00 Andrew Svetlov :
> > I like to have simple markup for coroutines but -1 for using return
> > annotation for that.
> > Return annotation is for return value description, not for function
> itself.
>
> A coroutine
Victor, ok.
Coroutine call returns generator.
But usually I want to know what is return type of that generator object.
I'm with Ben Darnell: coroutine decorator is more like classmethod
than return type.
On Thu, Feb 12, 2015 at 6:35 PM, Ben Darnell wrote:
> On Thu, Feb 12, 2015 at 11:31 AM, Vict
On Thu, Feb 12, 2015 at 2:35 PM, Ben Darnell wrote:
> But then the coroutine object has a return type as well, which needs to be
> represented somehow. I think it's better to let the "return type" portion of
> the docs represent the eventual return value of the coroutine. The coroutine
> aspect of
I'm not a sphinx expert, but if somebody is working on a solution, isn't
could more generic to handle any Python decorator, instead of
coroutines only ?
--
Ludovic Gasc
On Thu, Feb 12, 2015 at 6:24 PM, Luciano Ramalho
wrote:
> On Thu, Feb 12, 2015 at 2:35 PM, Ben Darnell wrote:
> > But then th
On Thu, Feb 12, 2015 at 6:30 PM, Ludovic Gasc wrote:
> I'm not a sphinx expert, but if somebody is working on a solution, isn't
> could more generic to handle any Python decorator, instead of coroutines
> only ?
Good idea. But are *all* asyncio coroutines are decorated as such?
The asyncio code
> On Feb 12, 2015, at 8:39 AM, Andrew Svetlov wrote:
>
> I'm with Ben Darnell: coroutine decorator is more like classmethod
> than return type.
For what it's worth, I disagree; a coroutine is something that a method either
returns or doesn't return, so it is more like return type than classmet
> On Feb 12, 2015, at 12:38 PM, Luciano Ramalho wrote:
>
> The asyncio code often uses the inspect module to determine the kind
> of function, right?
From the caller's perspective (i.e. the reader of the documentation), though,
isn't a method that returns an asyncio Future more or less the sam
On Thu, Feb 12, 2015 at 11:30 PM, Ludovic Gasc wrote:
> I'm not a sphinx expert, but if somebody is working on a solution, isn't
> could more generic to handle any Python decorator, instead of coroutines
> only ?
This patch is quite trivial: need to add coroutine object type to
sphinx.domains.pyt
Hi,
I added :py:coroutinefunction: and :py:coroutinemethod: commands in
the pyspecifics.py extensions of CPython documentation. I modified the
asyncio documentation to annotate all coroutines.
Changeset:
https://hg.python.org/cpython/rev/430a2b541709
The HTML doc will be regenerated in one hour:
Thank you Victor for your reactivity, it's ok for me.
Ludovic Gasc (GMLudo)
On 12 Feb 2015 23:00, "Victor Stinner" wrote:
> Hi,
>
> I added :py:coroutinefunction: and :py:coroutinemethod: commands in
> the pyspecifics.py extensions of CPython documentation. I modified the
> asyncio documentation
15 matches
Mail list logo
