Skip to content
This repository has been archived by the owner on Nov 23, 2017. It is now read-only.

Documentation: document AbstractServer, Server.sockets is specific to asyncio event loops #188

Open
GoogleCodeExporter opened this issue Apr 10, 2015 · 5 comments

Comments

@GoogleCodeExporter
Copy link

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 victor.s...@gmail.com on 11 Jul 2014 at 10:05

@GoogleCodeExporter
Copy link
Author

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

@GoogleCodeExporter
Copy link
Author

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 gvanrossum@gmail.com on 11 Jul 2014 at 10:38

@GoogleCodeExporter
Copy link
Author

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 victor.s...@gmail.com on 12 Jul 2014 at 1:35

@GoogleCodeExporter
Copy link
Author

Original comment by victor.s...@gmail.com on 17 Jul 2014 at 10:59

  • Changed title: Documentation: document AbstractServer, Server.sockets is specific to asyncio event loops

@GoogleCodeExporter
Copy link
Author

See also:
http://bugs.python.org/issue23046#msg232787

Original comment by victor.s...@gmail.com on 9 Jan 2015 at 3:01

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

1 participant