Skip to content
This repository
Browse code

Rename WebSocketConnect to websocket_connect.

Add docs for undocumented functions and modules.
  • Loading branch information...
commit 059f0e8dbe7ea459a5bc6a7d4dbd3b1afd40a7f8 1 parent 6e3c288
bdarnell authored
5  docs/concurrent.rst
Source Rendered
... ...
@@ -0,0 +1,5 @@
  1
+``tornado.concurrent`` --- Work with threads and futures
  2
+========================================================
  3
+
  4
+.. automodule:: tornado.concurrent
  5
+    :members:
2  docs/ioloop.rst
Source Rendered
@@ -14,6 +14,8 @@
14 14
    .. automethod:: IOLoop.instance
15 15
    .. automethod:: IOLoop.initialized
16 16
    .. automethod:: IOLoop.install
  17
+   .. automethod:: IOLoop.current
  18
+   .. automethod:: IOLoop.make_current
17 19
    .. automethod:: IOLoop.start
18 20
    .. automethod:: IOLoop.stop
19 21
    .. automethod:: IOLoop.run_sync
1  docs/networking.rst
Source Rendered
@@ -7,3 +7,4 @@ Asynchronous networking
7 7
    iostream
8 8
    httpclient
9 9
    netutil
  10
+   tcpserver
2  docs/releases/next.rst
Source Rendered
@@ -430,6 +430,6 @@ Multiple modules
430 430
 ~~~~~~~~~~~~~~~~~~~
431 431
 
432 432
 * Client-side WebSocket support is now available:
433  
-  `tornado.websocket.WebSocketConnect`
  433
+  `tornado.websocket.websocket_connect`
434 434
 * `WebSocketHandler` has new methods `ping` and `on_pong` to send pings
435 435
   to the browser (not supported on the ``draft76`` protocol)
5  docs/tcpserver.rst
Source Rendered
... ...
@@ -0,0 +1,5 @@
  1
+``tornado.tcpserver`` --- Basic `IOStream`-based TCP server
  2
+===========================================================
  3
+
  4
+.. automodule:: tornado.tcpserver
  5
+    :members:
1  docs/utilities.rst
Source Rendered
@@ -4,6 +4,7 @@ Utilities
4 4
 .. toctree::
5 5
 
6 6
    autoreload
  7
+   concurrent
7 8
    gen
8 9
    httputil
9 10
    log
8  docs/websocket.rst
Source Rendered
@@ -31,3 +31,11 @@
31 31
    .. automethod:: WebSocketHandler.async_callback
32 32
    .. automethod:: WebSocketHandler.ping
33 33
    .. automethod:: WebSocketHandler.on_pong
  34
+
  35
+
  36
+   Client-side support
  37
+   -------------------
  38
+
  39
+   .. autofunction:: websocket_connect
  40
+   .. autoclass:: WebSocketClientConnection
  41
+       :members:
6  tornado/concurrent.py
@@ -132,6 +132,11 @@ def submit(self, fn, *args, **kwargs):
132 132
 
133 133
 
134 134
 def run_on_executor(fn):
  135
+    """Decorator to run a synchronous method asynchronously on an executor.
  136
+
  137
+    The decorated method may be called with a ``callback`` keyword
  138
+    argument and returns a future.
  139
+    """
135 140
     @functools.wraps(fn)
136 141
     def wrapper(self, *args, **kwargs):
137 142
         callback = kwargs.pop("callback", None)
@@ -165,6 +170,7 @@ def return_future(f):
165 170
     `gen.engine` function, or passing it to `IOLoop.add_future`).
166 171
 
167 172
     Usage::
  173
+
168 174
         @return_future
169 175
         def future_func(arg1, arg2, callback):
170 176
             # Do stuff (possibly asynchronous)
5  tornado/httpserver.py
@@ -191,6 +191,11 @@ def __init__(self, stream, address, request_callback, no_keep_alive=False,
191 191
         self._close_callback = None
192 192
 
193 193
     def set_close_callback(self, callback):
  194
+        """Sets a callback that will be run when the connection is closed.
  195
+
  196
+        Use this instead of accessing `HTTPConnection.stream.set_close_callback`
  197
+        directly (which was the recommended approach prior to Tornado 3.0).
  198
+        """
194 199
         self._close_callback = stack_context.wrap(callback)
195 200
         self.stream.set_close_callback(self._on_connection_close)
196 201
 
19  tornado/ioloop.py
@@ -163,12 +163,31 @@ def install(self):
163 163
 
164 164
     @staticmethod
165 165
     def current():
  166
+        """Returns the current thread's `IOLoop`.
  167
+
  168
+        If an `IOLoop` is currently running or has been marked as current
  169
+        by `make_current`, returns that instance.  Otherwise returns
  170
+        `IOLoop.instance()`, i.e. the main thread's `IOLoop`.
  171
+
  172
+        In general you should use `IOLoop.current` as the default when
  173
+        constructing an asynchronous object, and use `IOLoop.instance`
  174
+        when you mean to communicate to the main thread from a different
  175
+        one.
  176
+        """
166 177
         current = getattr(IOLoop._current, "instance", None)
167 178
         if current is None:
168 179
             return IOLoop.instance()
169 180
         return current
170 181
 
171 182
     def make_current(self):
  183
+        """Makes this the `IOLoop` for the current thread.
  184
+
  185
+        An `IOLoop` automatically becomes current for its thread
  186
+        when it is started, but it is sometimes useful to call
  187
+        `make_current` explictly before starting the `IOLoop`,
  188
+        so that code run at startup time can find the right
  189
+        instance.
  190
+        """
172 191
         IOLoop._current.instance = self
173 192
 
174 193
     @staticmethod
32  tornado/netutil.py
@@ -160,6 +160,22 @@ def is_valid_ip(ip):
160 160
 
161 161
 
162 162
 class Resolver(Configurable):
  163
+    """Configurable asynchronous DNS resolver interface.
  164
+
  165
+    By default, a blocking implementation is used (which simply
  166
+    calls `socket.getaddrinfo`).  An alternative implementation
  167
+    can be chosen with the `Resolver.configure` class method::
  168
+
  169
+        Resolver.configure('tornado.netutil.ThreadedResolver')
  170
+
  171
+    The implementations of this interface included with Tornado are
  172
+
  173
+    * `tornado.netutil.BlockingResolver`
  174
+    * `tornado.netutil.ThreadedResolver`
  175
+    * `tornado.netutil.OverrideResolver`
  176
+    * `tornado.platform.twisted.TwistedResolver`
  177
+    * `tornado.platform.caresresolver.CaresResolver`
  178
+    """
163 179
     @classmethod
164 180
     def configurable_base(cls):
165 181
         return Resolver
@@ -199,11 +215,27 @@ def resolve(self, host, port, family=socket.AF_UNSPEC):
199 215
 
200 216
 
201 217
 class BlockingResolver(ExecutorResolver):
  218
+    """Default `Resolver` implementation, using `socket.getaddrinfo`.
  219
+
  220
+    The `IOLoop` will be blocked during the resolution, although the
  221
+    callback will not be run until the next `IOLoop` iteration.
  222
+    """
202 223
     def initialize(self, io_loop=None):
203 224
         super(BlockingResolver, self).initialize(io_loop=io_loop)
204 225
 
205 226
 
206 227
 class ThreadedResolver(ExecutorResolver):
  228
+    """Multithreaded non-blocking `Resolver` implementation.
  229
+
  230
+    Requires the `concurrent.futures` package to be installed
  231
+    (available in the standard library since Python 3.2,
  232
+    installable with ``pip install futures`` in older versions).
  233
+
  234
+    The thread pool size can be configured with::
  235
+
  236
+        Resolver.configure('tornado.netutil.ThreadedResolver',
  237
+                           num_threads=10)
  238
+    """
207 239
     def initialize(self, io_loop=None, num_threads=10):
208 240
         from concurrent.futures import ThreadPoolExecutor
209 241
         super(ThreadedResolver, self).initialize(
6  tornado/test/websocket_test.py
... ...
@@ -1,6 +1,6 @@
1 1
 from tornado.testing import AsyncHTTPTestCase, gen_test
2 2
 from tornado.web import Application
3  
-from tornado.websocket import WebSocketHandler, WebSocketConnect
  3
+from tornado.websocket import WebSocketHandler, websocket_connect
4 4
 
5 5
 
6 6
 class EchoHandler(WebSocketHandler):
@@ -16,7 +16,7 @@ def get_app(self):
16 16
 
17 17
     @gen_test
18 18
     def test_websocket_gen(self):
19  
-        ws = yield WebSocketConnect(
  19
+        ws = yield websocket_connect(
20 20
             'ws://localhost:%d/echo' % self.get_http_port(),
21 21
             io_loop=self.io_loop)
22 22
         ws.write_message('hello')
@@ -24,7 +24,7 @@ def test_websocket_gen(self):
24 24
         self.assertEqual(response, 'hello')
25 25
 
26 26
     def test_websocket_callbacks(self):
27  
-        WebSocketConnect(
  27
+        websocket_connect(
28 28
             'ws://localhost:%d/echo' % self.get_http_port(),
29 29
             io_loop=self.io_loop, callback=self.stop)
30 30
         ws = self.wait().result()
21  tornado/websocket.py
@@ -718,7 +718,8 @@ def close(self):
718 718
                 self.stream.io_loop.time() + 5, self._abort)
719 719
 
720 720
 
721  
-class _WebSocketClientConnection(simple_httpclient._HTTPConnection):
  721
+class WebSocketClientConnection(simple_httpclient._HTTPConnection):
  722
+    """WebSocket client connection."""
722 723
     def __init__(self, io_loop, request):
723 724
         self.connect_future = Future()
724 725
         self.read_future = None
@@ -735,7 +736,7 @@ def __init__(self, io_loop, request):
735 736
             'Sec-WebSocket-Version': '13',
736 737
         })
737 738
 
738  
-        super(_WebSocketClientConnection, self).__init__(
  739
+        super(WebSocketClientConnection, self).__init__(
739 740
             io_loop, None, request, lambda: None, lambda response: None,
740 741
             104857600, Resolver(io_loop=io_loop))
741 742
 
@@ -759,9 +760,17 @@ def _handle_1xx(self, code):
759 760
         self.connect_future.set_result(self)
760 761
 
761 762
     def write_message(self, message, binary=False):
  763
+        """Sends a message to the WebSocket server."""
762 764
         self.protocol.write_message(message, binary)
763 765
 
764 766
     def read_message(self, callback=None):
  767
+        """Reads a message from the WebSocket server.
  768
+
  769
+        Returns a future whose result is the message, or None
  770
+        if the connection is closed.  If a callback argument
  771
+        is given it will be called with the future when it is
  772
+        ready.
  773
+        """
765 774
         assert self.read_future is None
766 775
         future = Future()
767 776
         if self.read_queue:
@@ -783,13 +792,17 @@ def on_pong(self, data):
783 792
         pass
784 793
 
785 794
 
786  
-def WebSocketConnect(url, io_loop=None, callback=None):
  795
+def websocket_connect(url, io_loop=None, callback=None):
  796
+    """Client-side websocket support.
  797
+
  798
+    Takes a url and returns a Future whose result is a `WebSocketConnection`.
  799
+    """
787 800
     if io_loop is None:
788 801
         io_loop = IOLoop.current()
789 802
     request = httpclient.HTTPRequest(url)
790 803
     request = httpclient._RequestProxy(
791 804
         request, httpclient.HTTPRequest._DEFAULTS)
792  
-    conn = _WebSocketClientConnection(io_loop, request)
  805
+    conn = WebSocketClientConnection(io_loop, request)
793 806
     if callback is not None:
794 807
         io_loop.add_future(conn.connect_future, callback)
795 808
     return conn.connect_future

0 notes on commit 059f0e8

Please sign in to comment.
Something went wrong with that request. Please try again.