asyncio
asyncio copied to clipboard
python
Documentation: document AbstractServer, Server.sockets is specific to asyncio event loops
I just fixed the issue #180 which documents the Server.sockets attribute.
AbstractServer has no sockets attribute nor constructor. Should we add a
sockets attribute to AbstractServer? Here is a patch:
http://codereview.appspot.com/113040043
Or maybe we should drop this abstract server class? I like the idea of an
interface for event loop. I'm not sure that an interface for server is useful.
The class is exported in the asyncio namespace, but it is not documented.
By the way, I replaced AbstractServer with Server in the documentation. For
event loops, BaseEventLoop is documented, not AbstractEventLoop.
Original issue reported on code.google.com by [email protected] on 11 Jul 2014 at 10:05
What if a loop doesn't use actual Python sockets? I haven't updated Rose in a
while, but when I get to it, the Server class won't have socket objects, since
it doesn't use them, I use pyuv "handles".
Original comment by saghul on 11 Jul 2014 at 10:26
AbstractServer is an interface, Server is one implementation. I think the
contract is that no matter which event loop implementation you use, the thing
returned by create_server() implements the abstract interface; only some
specific implementations return a Server instance. If you are using the sockets
attribute you are restricting yourself to certain event loop implementations --
but there are other aspects of the event loop interface that refer to sockets,
and those may not be implemented. (E.g. create_server() takes an optional sock
argument.)
So code that wants to be independent from the loop implementation should not
use the sockets attribute. But that's part of PEP 3156 interop -- there is a
minimal set of supported interfaces, and extensions for certain platforms
(subprocesses are also not supported by all loop implementations).
Original comment by [email protected] on 11 Jul 2014 at 10:38
Ok, so the problem is more on the documentation side. I changed the
documentation to say that create_server() returns a Server object, because
AbstractServer is not documented and I like adding links to the definition of
the class.
For the new create_task() method, I mentionned explicitly in the documentation
that create_task() may return an instance of a subclass of Task instance in
third-party projects, instead of an instance of Task.
The documentation should mention explain better the concept of
interface/abstract class in asyncio: document AbstractEventLoop and
AbstractServer at least.
For example, we can say that create_server() return type is AbstractServer, and
the default implementation returns a Server object. Or something like that.
Original comment by [email protected] on 12 Jul 2014 at 1:35
Original comment by [email protected] on 17 Jul 2014 at 10:59
- Changed title: Documentation: document AbstractServer, Server.sockets is specific to asyncio event loops
See also:
http://bugs.python.org/issue23046#msg232787
Original comment by [email protected] on 9 Jan 2015 at 3:01