From f6b365158d9c4d84f3ef730093a37027d458804e Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Fri, 10 Jun 2011 00:13:20 -0700 Subject: [PATCH] More autodoc fixes --- tornado/escape.py | 4 ++++ tornado/httpclient.py | 14 ++++++++++++-- tornado/httpserver.py | 11 ++++++----- tornado/ioloop.py | 8 +++++--- tornado/iostream.py | 4 ++-- tornado/locale.py | 4 ++-- tornado/template.py | 10 +++++----- website/sphinx/escape.rst | 1 + website/sphinx/httpclient.rst | 1 + website/sphinx/httpserver.rst | 1 + website/sphinx/ioloop.rst | 1 + website/sphinx/iostream.rst | 1 + website/sphinx/locale.rst | 1 + website/sphinx/template.rst | 1 + 14 files changed, 43 insertions(+), 19 deletions(-) diff --git a/tornado/escape.py b/tornado/escape.py index 74a1caa7..3fa602be 100644 --- a/tornado/escape.py +++ b/tornado/escape.py @@ -211,11 +211,15 @@ def linkify(text, shorten=False, extra_params="", Hello http://tornadoweb.org! Parameters: + shorten: Long urls will be shortened for display. + extra_params: Extra text to include in the link tag, e.g. linkify(text, extra_params='rel="nofollow" class="external"') + require_protocol: Only linkify urls which include a protocol. If this is False, urls such as www.facebook.com will also be linkified. + permitted_protocols: List (or set) of protocols which should be linkified, e.g. linkify(text, permitted_protocols=["http", "ftp", "mailto"]). It is very unsafe to include protocols such as "javascript". diff --git a/tornado/httpclient.py b/tornado/httpclient.py index 781ce6e3..0b77c480 100644 --- a/tornado/httpclient.py +++ b/tornado/httpclient.py @@ -13,7 +13,7 @@ from tornado.util import import_object, bytes_type class HTTPClient(object): """A blocking HTTP client. - Typical usage looks like this: + Typical usage looks like this:: http_client = httpclient.HTTPClient() try: @@ -51,7 +51,7 @@ class HTTPClient(object): class AsyncHTTPClient(object): """An non-blocking HTTP client. - Example usage: + Example usage:: import ioloop @@ -208,13 +208,21 @@ class HTTPResponse(object): """HTTP Response object. Attributes: + * request: HTTPRequest object + * code: numeric HTTP status code, e.g. 200 or 404 + * headers: httputil.HTTPHeaders object + * buffer: cStringIO object for response body + * body: respose body as string (created on demand from self.buffer) + * error: Exception object, if any + * request_time: seconds from request start to finish + * time_info: dictionary of diagnostic timing information from the request. Available data are subject to change, but currently uses timings available from http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html, @@ -266,8 +274,10 @@ class HTTPError(Exception): """Exception thrown for an unsuccessful HTTP request. Attributes: + code - HTTP error integer error code, e.g. 404. Error code 599 is used when no HTTP response was received, e.g. for a timeout. + response - HTTPResponse object, if any. Note that if follow_redirects is False, redirects become HTTPErrors, diff --git a/tornado/httpserver.py b/tornado/httpserver.py index 04a7157b..cbecfce1 100644 --- a/tornado/httpserver.py +++ b/tornado/httpserver.py @@ -64,14 +64,14 @@ def _cpu_count(): class HTTPServer(object): - """A non-blocking, single-threaded HTTP server. + r"""A non-blocking, single-threaded HTTP server. A server is defined by a request callback that takes an HTTPRequest instance as an argument and writes a valid HTTP response with request.write(). request.finish() finishes the request (but does not necessarily close the connection in the case of HTTP/1.1 keep-alive requests). A simple example server that echoes back the URI you - requested: + requested:: import httpserver import ioloop @@ -105,7 +105,7 @@ class HTTPServer(object): HTTPServer can serve HTTPS (SSL) traffic with Python 2.6+ and OpenSSL. To make this server serve SSL traffic, send the ssl_options dictionary argument with the arguments required for the ssl.wrap_socket() method, - including "certfile" and "keyfile": + including "certfile" and "keyfile":: HTTPServer(applicaton, ssl_options={ "certfile": os.path.join(data_dir, "mydomain.crt"), @@ -114,7 +114,7 @@ class HTTPServer(object): By default, listen() runs in a single thread in a single process. You can utilize all available CPUs on this machine by calling bind() and - start() instead of listen(): + start() instead of listen():: http_server = httpserver.HTTPServer(handle_request) http_server.bind(8888) @@ -503,7 +503,8 @@ class HTTPRequest(object): """Returns the client's SSL certificate, if any. To use client certificates, the HTTPServer must have been constructed - with cert_reqs set in ssl_options, e.g.: + with cert_reqs set in ssl_options, e.g.:: + server = HTTPServer(app, ssl_options=dict( certfile="foo.crt", diff --git a/tornado/ioloop.py b/tornado/ioloop.py index 4eef01af..0e0892a8 100644 --- a/tornado/ioloop.py +++ b/tornado/ioloop.py @@ -49,7 +49,7 @@ class IOLoop(object): connections, you should use Linux and either compile our epoll module or use Python 2.6+ to get epoll support. - Example usage for a simple TCP server: + Example usage for a simple TCP server:: import errno import functools @@ -132,7 +132,7 @@ class IOLoop(object): A common pattern for classes that depend on IOLoops is to use a default argument to enable programs with multiple IOLoops - but not require the argument for simpler applications: + but not require the argument for simpler applications:: class MyClass(object): def __init__(self, io_loop=None): @@ -296,10 +296,12 @@ class IOLoop(object): will return immediately. To use asynchronous methods from otherwise-synchronous code (such as - unit tests), you can start and stop the event loop like this: + unit tests), you can start and stop the event loop like this:: + ioloop = IOLoop() async_method(ioloop=ioloop, callback=ioloop.stop) ioloop.start() + ioloop.start() will return after async_method has run its callback, whether that callback was invoked before or after ioloop.start. """ diff --git a/tornado/iostream.py b/tornado/iostream.py index 4b005f62..d9c8b7dc 100644 --- a/tornado/iostream.py +++ b/tornado/iostream.py @@ -34,7 +34,7 @@ except ImportError: ssl = None class IOStream(object): - """A utility class to write to and read from a non-blocking socket. + r"""A utility class to write to and read from a non-blocking socket. We support three methods: write(), read_until(), and read_bytes(). All of the methods take callbacks (since writing and reading are @@ -48,7 +48,7 @@ class IOStream(object): and may either be connected before passing it to the IOStream or connected with IOStream.connect. - A very simple (and broken) HTTP client using this class: + A very simple (and broken) HTTP client using this class:: from tornado import ioloop from tornado import iostream diff --git a/tornado/locale.py b/tornado/locale.py index b16a9000..f4b0b630 100644 --- a/tornado/locale.py +++ b/tornado/locale.py @@ -16,14 +16,14 @@ """Translation methods for generating localized strings. -To load a locale and generate a translated string: +To load a locale and generate a translated string:: user_locale = locale.get("es_LA") print user_locale.translate("Sign out") locale.get() returns the closest matching locale, not necessarily the specific locale you requested. You can support pluralization with -additional arguments to translate(), e.g.: +additional arguments to translate(), e.g.:: people = [...] message = user_locale.translate( diff --git a/tornado/template.py b/tornado/template.py index 648621ed..44814bd7 100644 --- a/tornado/template.py +++ b/tornado/template.py @@ -16,19 +16,19 @@ """A simple template system that compiles templates to Python code. -Basic usage looks like: +Basic usage looks like:: t = template.Template("{{ myvalue }}") print t.generate(myvalue="XXX") Loader is a class that loads templates from a root directory and caches -the compiled templates: +the compiled templates:: loader = template.Loader("/home/btaylor") print loader.load("test.html").generate(myvalue="XXX") We compile all templates to raw Python. Error-reporting is currently... uh, -interesting. Syntax for the templates +interesting. Syntax for the templates:: ### base.html @@ -57,7 +57,7 @@ interesting. Syntax for the templates Unlike most other template systems, we do not put any restrictions on the expressions you can include in your statements. if and for blocks get -translated exactly into Python, do you can do complex expressions like: +translated exactly into Python, do you can do complex expressions like:: {% for student in [p for p in people if p.student and p.age > 23] %}
  • {{ escape(student.name) }}
    • @@ -65,7 +65,7 @@ translated exactly into Python, do you can do complex expressions like: Translating directly to Python means you can apply functions to expressions easily, like the escape() function in the examples above. You can pass -functions in to your template just like any other variable: +functions in to your template just like any other variable:: ### Python code def add(x, y): diff --git a/website/sphinx/escape.rst b/website/sphinx/escape.rst index 0c35cf05..d67ec589 100644 --- a/website/sphinx/escape.rst +++ b/website/sphinx/escape.rst @@ -2,3 +2,4 @@ ====================== .. automodule:: tornado.escape + :members: diff --git a/website/sphinx/httpclient.rst b/website/sphinx/httpclient.rst index 14eb643f..4022a63f 100644 --- a/website/sphinx/httpclient.rst +++ b/website/sphinx/httpclient.rst @@ -2,3 +2,4 @@ ====================== .. automodule:: tornado.httpclient + :members: diff --git a/website/sphinx/httpserver.rst b/website/sphinx/httpserver.rst index 85c2b1a0..11e5c3ef 100644 --- a/website/sphinx/httpserver.rst +++ b/website/sphinx/httpserver.rst @@ -2,3 +2,4 @@ ====================== .. automodule:: tornado.httpserver + :members: diff --git a/website/sphinx/ioloop.rst b/website/sphinx/ioloop.rst index 2cf69d98..03f9072c 100644 --- a/website/sphinx/ioloop.rst +++ b/website/sphinx/ioloop.rst @@ -2,3 +2,4 @@ ====================== .. automodule:: tornado.ioloop + :members: diff --git a/website/sphinx/iostream.rst b/website/sphinx/iostream.rst index e43671a3..e65ca27e 100644 --- a/website/sphinx/iostream.rst +++ b/website/sphinx/iostream.rst @@ -2,3 +2,4 @@ ====================== .. automodule:: tornado.iostream + :members: diff --git a/website/sphinx/locale.rst b/website/sphinx/locale.rst index cb7ce77c..41b8bf27 100644 --- a/website/sphinx/locale.rst +++ b/website/sphinx/locale.rst @@ -2,3 +2,4 @@ ====================== .. automodule:: tornado.locale + :members: diff --git a/website/sphinx/template.rst b/website/sphinx/template.rst index 34a8a4b0..d9d54940 100644 --- a/website/sphinx/template.rst +++ b/website/sphinx/template.rst @@ -2,3 +2,4 @@ ====================== .. automodule:: tornado.template + :members: