[issue25749] asyncio.Server class documented but not exported

[STINNER Victor]

STINNER Victor added the comment:

Yeah, I recall this point. The doc points to Server, but Guido didn't
want to expose "implementation details" of Server like sockets.
Different implementations of event loops (Yury gave the good example
of uvloop based on libuv) don't give (direct) access to sockets.

The problem is maybe that we try to document two different things at
the same place: asyncio "portable" API (the PEP 3156), and the
implementation of "default" event loops.

Even if it's not possible to directly use server sockets, it's kind of
useful to get them. What do you think?

Server.sockets is documented at:
https://docs.python.org/dev/library/asyncio-eventloop.html#asyncio.Server.sockets

Server.sockets is explicitly documented at:
https://docs.python.org/dev/library/asyncio-eventloop.html#asyncio.BaseEventLoop.create_server

I would prefer to keep the Server.sockets doc, but explain better that
it's an "implementation detail". We already have something similar for
"CPython" implementation details in the doc. Examples:
- https://docs.python.org/dev/library/sys.html#sys._debugmallocstats
- https://docs.python.org/dev/library/sys.html#sys._getframe
- https://docs.python.org/dev/library/dis.html#module-dis
- etc.

What do you think of reusing the ".. impl-detail:" markup? Or do you
prefer to write a different kind of box for asyncio? Or just not box
and a simple sentence?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue25749>
_______________________________________