From: Ben Darnell Date: Sat, 16 Mar 2013 03:09:49 +0000 (-0400) Subject: Fix dangling references in recently-revised docs. X-Git-Tag: v3.0.0~28 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b166bdf44257345578f2558f82e43bc10e9c2c3a;p=thirdparty%2Ftornado.git Fix dangling references in recently-revised docs. --- diff --git a/docs/index.rst b/docs/index.rst index 11477fc9d..c0badcd35 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -87,7 +87,7 @@ features may require one of the following libraries: `~tornado.netutil.ThreadedResolver`. It is needed only on Python 2; Python 3 includes this package in the standard library. * `pycurl `_ is used by the optional - `tornado.curl_httpclient`. Libcurl version 7.18.2 or higher is required; + ``tornado.curl_httpclient``. Libcurl version 7.18.2 or higher is required; version 7.21.1 or higher is recommended. * `Twisted `_ may be used with the classes in `tornado.platform.twisted`. diff --git a/tornado/auth.py b/tornado/auth.py index c9b008beb..aa62540d4 100644 --- a/tornado/auth.py +++ b/tornado/auth.py @@ -266,7 +266,7 @@ class OpenIdMixin(object): future.set_result(user) def get_auth_http_client(self): - """Returns the `AsyncHTTPClient` instance to be used for auth requests. + """Returns the `.AsyncHTTPClient` instance to be used for auth requests. May be overridden by subclasses to use an HTTP client other than the default. @@ -445,14 +445,15 @@ class OAuthMixin(object): """Subclasses must override this to get basic information about the user. - Should return a `Future` whose result is a dictionary containing - information about the user, which may have been retrieved by - using ``access_token`` to make a request to the service. + Should return a `~concurrent.futures.Future` whose result is a + dictionary containing information about the user, which may + have been retrieved by using ``access_token`` to make a + request to the service. The access token will be added to the returned dictionary to make the result of `get_authenticated_user`. - For backwards compatibility, the callback-based `_oauth_get_user` + For backwards compatibility, the callback-based ``_oauth_get_user`` method is also supported. """ # By default, call the old-style _oauth_get_user, but new code @@ -502,7 +503,7 @@ class OAuthMixin(object): return base_args def get_auth_http_client(self): - """Returns the `AsyncHTTPClient` instance to be used for auth requests. + """Returns the `.AsyncHTTPClient` instance to be used for auth requests. May be overridden by subclasses to use an HTTP client other than the default. @@ -528,7 +529,7 @@ class OAuth2Mixin(object): Some providers require that you register a redirect URL with your application instead of passing one via this method. You should call this method to log the user in, and then call - `get_authenticated_user()` in the handler for your + ``get_authenticated_user`` in the handler for your redirect URL to complete the authorization process. """ args = { @@ -579,9 +580,9 @@ class TwitterMixin(OAuthMixin): else: self.authorize_redirect() - The user object returned by `get_authenticated_user()` includes the - attributes ``username``, ``name``, ``access_token``, and all of the - custom Twitter user attributes described at + The user object returned by `~OAuthMixin.get_authenticated_user` + includes the attributes ``username``, ``name``, ``access_token``, + and all of the custom Twitter user attributes described at https://dev.twitter.com/docs/api/1.1/get/users/show """ _OAUTH_REQUEST_TOKEN_URL = "http://api.twitter.com/oauth/request_token" @@ -822,10 +823,10 @@ class GoogleMixin(OpenIdMixin, OAuthMixin): Google implements both OpenID and OAuth in a hybrid mode. If you just need the user's identity, use - `~OpenIDMixin.authenticate_redirect`. If you need to make + `~OpenIdMixin.authenticate_redirect`. If you need to make requests to Google on behalf of the user, use `authorize_redirect`. On return, parse the response with - `~OpenIDMixin.get_authenticated_user()`. We send a dict containing + `~OpenIdMixin.get_authenticated_user`. We send a dict containing the values for the user, including ``email``, ``name``, and ``locale``. @@ -1081,7 +1082,7 @@ class FacebookMixin(object): return hashlib.md5(body).hexdigest() def get_auth_http_client(self): - """Returns the `AsyncHTTPClient` instance to be used for auth requests. + """Returns the `.AsyncHTTPClient` instance to be used for auth requests. May be overridden by subclasses to use an HTTP client other than the default. @@ -1228,7 +1229,7 @@ class FacebookGraphMixin(OAuth2Mixin): callback(escape.json_decode(response.body)) def get_auth_http_client(self): - """Returns the `AsyncHTTPClient` instance to be used for auth requests. + """Returns the `.AsyncHTTPClient` instance to be used for auth requests. May be overridden by subclasses to use an HTTP client other than the default. diff --git a/tornado/autoreload.py b/tornado/autoreload.py index 5d4c524e0..05754299a 100644 --- a/tornado/autoreload.py +++ b/tornado/autoreload.py @@ -14,7 +14,7 @@ # License for the specific language governing permissions and limitations # under the License. -"""Automatically restart the server when a source file is modified. +"""xAutomatically restart the server when a source file is modified. Most applications should not access this module directly. Instead, pass the keyword argument ``debug=True`` to the `tornado.web.Application` constructor. @@ -30,8 +30,8 @@ This combination is encouraged as the wrapper catches syntax errors and other import-time failures, while debug mode catches changes once the server has started. -This module depends on `IOLoop`, so it will not work in WSGI applications -and Google App Engine. It also will not work correctly when `HTTPServer`'s +This module depends on `.IOLoop`, so it will not work in WSGI applications +and Google App Engine. It also will not work correctly when `.HTTPServer`'s multi-process mode is used. Reloading loses any Python interpreter command-line arguments (e.g. ``-u``) @@ -103,7 +103,7 @@ _io_loops = weakref.WeakKeyDictionary() def start(io_loop=None, check_time=500): - """Begins watching source files for changes using the given `IOLoop`. """ + """Begins watching source files for changes using the given `.IOLoop`. """ io_loop = io_loop or ioloop.IOLoop.current() if io_loop in _io_loops: return @@ -142,8 +142,8 @@ def add_reload_hook(fn): Note that for open file and socket handles it is generally preferable to set the ``FD_CLOEXEC`` flag (using `fcntl` or - `tornado.platform.auto.set_close_exec`) instead of using a reload - hook to close them. + ``tornado.platform.auto.set_close_exec``) instead + of using a reload hook to close them. """ _reload_hooks.append(fn) diff --git a/tornado/concurrent.py b/tornado/concurrent.py index b71e1546e..e5a6ade79 100644 --- a/tornado/concurrent.py +++ b/tornado/concurrent.py @@ -101,7 +101,8 @@ else: class TracebackFuture(Future): - """Subclass of `Future` which can store a traceback with exceptions. + """Subclass of `~concurrent.futures.Future` which can store a traceback + with exceptions. The traceback is automatically available in Python 3, but in the Python 2 futures backport this information is discarded. @@ -114,7 +115,9 @@ class TracebackFuture(Future): return self.__exc_info def set_exc_info(self, exc_info): - """Traceback-aware replacement for `Future.set_exception`.""" + """Traceback-aware replacement for + `~concurrent.futures.Future.set_exception`. + """ self.__exc_info = exc_info self.set_exception(exc_info[1]) @@ -158,22 +161,23 @@ _NO_RESULT = object() def return_future(f): - """Decorator to make a function that returns via callback return a `Future`. + """Decorator to make a function that returns via callback return a + `~concurrent.futures.Future`. The wrapped function should take a ``callback`` keyword argument and invoke it with one argument when it has finished. To signal failure, the function can simply raise an exception (which will be - captured by the `stack_context` and passed along to the `Future`). + captured by the `.StackContext` and passed along to the ``Future``). From the caller's perspective, the callback argument is optional. If one is given, it will be invoked when the function is complete - with `Future.result()` as an argument. If the function fails, - the callback will not be run and an exception will be raised into - the surrounding `StackContext`. + with `Future.result() ` as an + argument. If the function fails, the callback will not be run and + an exception will be raised into the surrounding `.StackContext`. - If no callback is given, the caller should use the `Future` to + If no callback is given, the caller should use the ``Future`` to wait for the function to complete (perhaps by yielding it in a - `gen.engine` function, or passing it to `IOLoop.add_future`). + `.gen.engine` function, or passing it to `.IOLoop.add_future`). Usage::