classification
Title: asyncio.BaseEventLoop is documented, but only exported via asyncio.base_events
Type: Stage:
Components: asyncio Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: gvanrossum, martin.panter, python-dev, vstinner, yselivanov
Priority: normal Keywords: patch

Created on 2014-12-13 07:13 by martin.panter, last changed 2015-01-26 14:22 by vstinner. This issue is now closed.

Files
File name Uploaded Description Edit
base_event_loop.patch vstinner, 2014-12-17 00:17 review
Messages (12)
msg232598 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2014-12-13 07:13
The documentation mentions BaseEventLoop as an attribute of the “asyncio” module, but it is not actually there (at least in v3.4.2). I have to import it specially from “asyncio.base_events”. Is this an oversight in the documentation, or am I relying on undocumented internals? I find the BaseEventLoop class is somewhat helpful for implementing my own event loops.
msg232771 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-12-16 23:45
I'm in favor of exposing BaseEventLoop in the asyncio namespace directly (asyncio.BaseEventLoop) because I'm using it in various asyncio projects, and I don't like having to use submodules. I consider asyncio.base_events as the private API.
msg232776 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2014-12-16 23:51
OK, fine to expose the BaseEventLoop class.

On Tue, Dec 16, 2014 at 3:45 PM, STINNER Victor <report@bugs.python.org>
wrote:
>
>
> STINNER Victor added the comment:
>
> I'm in favor of exposing BaseEventLoop in the asyncio namespace directly
> (asyncio.BaseEventLoop) because I'm using it in various asyncio projects,
> and I don't like having to use submodules. I consider asyncio.base_events
> as the private API.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue23046>
> _______________________________________
>
msg232781 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-12-17 00:17
Here is a patch to expose BaseEventLoop. It removes Server from base_events.__all__, which means that "from asyncio.base_events import *" will no import Server anymore. Can it break real applications?
msg232783 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2014-12-17 00:21
Sounds unlikely. If they write "from asyncio.base_events import Server" it
will still work. Only if they wrote "from asyncio.base_events import *"
will they be broken, and that sounds not worth worrying about. So LGTM on
the patch. (But why was Server there at all? Tests?

On Tue, Dec 16, 2014 at 4:17 PM, STINNER Victor <report@bugs.python.org>
wrote:
>
>
> STINNER Victor added the comment:
>
> Here is a patch to expose BaseEventLoop. It removes Server from
> base_events.__all__, which means that "from asyncio.base_events import *"
> will no import Server anymore. Can it break real applications?
>
> ----------
> keywords: +patch
> Added file: http://bugs.python.org/file37475/base_event_loop.patch
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue23046>
> _______________________________________
>
msg232785 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-12-17 00:27
> why was Server there at all? Tests?

If you cannot answer, who can answer? :-)
https://code.google.com/p/tulip/source/detail?r=f136c04d82c0 (You
added Server to __all__.)

I don't see any use case which needs to create explicitly a Server
class. There are the create_server() method and start_server()
function for that.

By the way, the Server class *is* documented as asyncio.Server, which
is the same mistake than asyncio.BaseEventLoop:
https://docs.python.org/dev/library/asyncio-eventloop.html#asyncio.Server

I propose to update the doc for Server, replace asyncio.Server with
asyncio.base_events.Server.
msg232787 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2014-12-17 00:39
Heh. Well I don't remember why I did that any more, and it doesn't seem to
matter now.

However the doc issue seems different than for BaseEventLoop -- Server is
the *concrete* class (it actually gets instantiated, not a subclass). We
could instead document the AbstractServer class, but it doesn't have the
'sockets' instance variable. Maybe we should document both --
AbstractServer as the minimal interface that create_server() returns,
Server as the actual class that the default event loops (Unix and Windows)
create. With a warning that 'sockets' attribute may not be available if the
event loop has been configured differently.

On Tue, Dec 16, 2014 at 4:27 PM, STINNER Victor <report@bugs.python.org>
wrote:
>
>
> STINNER Victor added the comment:
>
> > why was Server there at all? Tests?
>
> If you cannot answer, who can answer? :-)
> https://code.google.com/p/tulip/source/detail?r=f136c04d82c0 (You
> added Server to __all__.)
>
> I don't see any use case which needs to create explicitly a Server
> class. There are the create_server() method and start_server()
> function for that.
>
> By the way, the Server class *is* documented as asyncio.Server, which
> is the same mistake than asyncio.BaseEventLoop:
> https://docs.python.org/dev/library/asyncio-eventloop.html#asyncio.Server
>
> I propose to update the doc for Server, replace asyncio.Server with
> asyncio.base_events.Server.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue23046>
> _______________________________________
>
msg233481 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-01-05 21:44
What do you think of my first change, base_event_loop.patch, which exposes BaseEventLoop? I'm going to commit it if nobody reviews it.
msg233482 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-01-05 23:05
Sure. I already said LGTM on the patch (http://bugs.python.org/issue23046#msg232783).
msg233489 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-01-06 00:05
New changeset ddf6b78faed9 by Victor Stinner in branch '3.4':
Issue #23046: Expose the BaseEventLoop class in the asyncio namespace
https://hg.python.org/cpython/rev/ddf6b78faed9
msg233757 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-01-09 15:02
See also the "Documentation: document AbstractServer, Server.sockets is specific to asyncio event loops" issue:
https://code.google.com/p/tulip/issues/detail?id=188
msg234748 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-01-26 14:22
Since there is already an open issue suggesting to document AbstractServer (and Server), I close this issue.

The original bug was fixed: BaseEventLoop is now part of the asyncio namespace.
History
Date User Action Args
2015-01-26 14:22:18vstinnersetstatus: open -> closed
resolution: fixed
messages: + msg234748
2015-01-09 15:02:06vstinnersetmessages: + msg233757
2015-01-06 00:05:52python-devsetnosy: + python-dev
messages: + msg233489
2015-01-05 23:05:38gvanrossumsetmessages: + msg233482
2015-01-05 21:44:38vstinnersetmessages: + msg233481
2014-12-17 00:39:30gvanrossumsetmessages: + msg232787
2014-12-17 00:27:58vstinnersetmessages: + msg232785
2014-12-17 00:21:40gvanrossumsetmessages: + msg232783
2014-12-17 00:17:54vstinnersetfiles: + base_event_loop.patch
keywords: + patch
messages: + msg232781
2014-12-16 23:51:31gvanrossumsetmessages: + msg232776
2014-12-16 23:45:12vstinnersetmessages: + msg232771
2014-12-13 07:13:12martin.pantercreate