Skip to content

Commit 342c656

Browse files
bdarnellbdarnell
committed
Merge branch 'docs'
2 parents 0af13b0 + 678d2eb commit 342c656

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+884
-225
lines changed

‎tornado/auth.py

Lines changed: 158 additions & 157 deletions
Large diffs are not rendered by default.

‎tornado/database.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ class Connection(object):
2828
"""A lightweight wrapper around MySQLdb DB-API connections.
2929
3030
The main value we provide is wrapping rows in a dict/object so that
31-
columns can be accessed by name. Typical usage:
31+
columns can be accessed by name. Typical usage::
3232
3333
db = database.Connection("localhost", "mydatabase")
3434
for article in db.query("SELECT * FROM articles"):

‎tornado/escape.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,11 +211,15 @@ def linkify(text, shorten=False, extra_params="",
211211
Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!
212212
213213
Parameters:
214+
214215
shorten: Long urls will be shortened for display.
216+
215217
extra_params: Extra text to include in the link tag,
216218
e.g. linkify(text, extra_params='rel="nofollow" class="external"')
219+
217220
require_protocol: Only linkify urls which include a protocol. If this is
218221
False, urls such as www.facebook.com will also be linkified.
222+
219223
permitted_protocols: List (or set) of protocols which should be linkified,
220224
e.g. linkify(text, permitted_protocols=["http", "ftp", "mailto"]).
221225
It is very unsafe to include protocols such as "javascript".

‎tornado/httpclient.py

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
class HTTPClient(object):
1414
"""A blocking HTTP client.
1515
16-
Typical usage looks like this:
16+
Typical usage looks like this::
1717
1818
http_client = httpclient.HTTPClient()
1919
try:
@@ -51,7 +51,7 @@ def callback(response):
5151
class AsyncHTTPClient(object):
5252
"""An non-blocking HTTP client.
5353
54-
Example usage:
54+
Example usage::
5555
5656
import ioloop
5757
@@ -208,13 +208,21 @@ class HTTPResponse(object):
208208
"""HTTP Response object.
209209
210210
Attributes:
211+
211212
* request: HTTPRequest object
213+
212214
* code: numeric HTTP status code, e.g. 200 or 404
215+
213216
* headers: httputil.HTTPHeaders object
217+
214218
* buffer: cStringIO object for response body
219+
215220
* body: respose body as string (created on demand from self.buffer)
221+
216222
* error: Exception object, if any
223+
217224
* request_time: seconds from request start to finish
225+
218226
* time_info: dictionary of diagnostic timing information from the request.
219227
Available data are subject to change, but currently uses timings
220228
available from http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html,
@@ -266,8 +274,10 @@ class HTTPError(Exception):
266274
"""Exception thrown for an unsuccessful HTTP request.
267275
268276
Attributes:
277+
269278
code - HTTP error integer error code, e.g. 404. Error code 599 is
270279
used when no HTTP response was received, e.g. for a timeout.
280+
271281
response - HTTPResponse object, if any.
272282
273283
Note that if follow_redirects is False, redirects become HTTPErrors,

‎tornado/httpserver.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,14 +64,14 @@ def _cpu_count():
6464

6565

6666
class HTTPServer(object):
67-
"""A non-blocking, single-threaded HTTP server.
67+
r"""A non-blocking, single-threaded HTTP server.
6868
6969
A server is defined by a request callback that takes an HTTPRequest
7070
instance as an argument and writes a valid HTTP response with
7171
request.write(). request.finish() finishes the request (but does not
7272
necessarily close the connection in the case of HTTP/1.1 keep-alive
7373
requests). A simple example server that echoes back the URI you
74-
requested:
74+
requested::
7575
7676
import httpserver
7777
import ioloop
@@ -105,7 +105,7 @@ def handle_request(request):
105105
HTTPServer can serve HTTPS (SSL) traffic with Python 2.6+ and OpenSSL.
106106
To make this server serve SSL traffic, send the ssl_options dictionary
107107
argument with the arguments required for the ssl.wrap_socket() method,
108-
including "certfile" and "keyfile":
108+
including "certfile" and "keyfile"::
109109
110110
HTTPServer(applicaton, ssl_options={
111111
"certfile": os.path.join(data_dir, "mydomain.crt"),
@@ -114,7 +114,7 @@ def handle_request(request):
114114
115115
By default, listen() runs in a single thread in a single process. You
116116
can utilize all available CPUs on this machine by calling bind() and
117-
start() instead of listen():
117+
start() instead of listen()::
118118
119119
http_server = httpserver.HTTPServer(handle_request)
120120
http_server.bind(8888)
@@ -503,7 +503,8 @@ def get_ssl_certificate(self):
503503
"""Returns the client's SSL certificate, if any.
504504
505505
To use client certificates, the HTTPServer must have been constructed
506-
with cert_reqs set in ssl_options, e.g.:
506+
with cert_reqs set in ssl_options, e.g.::
507+
507508
server = HTTPServer(app,
508509
ssl_options=dict(
509510
certfile="foo.crt",

‎tornado/ioloop.py

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ class IOLoop(object):
4949
connections, you should use Linux and either compile our epoll module or
5050
use Python 2.6+ to get epoll support.
5151
52-
Example usage for a simple TCP server:
52+
Example usage for a simple TCP server::
5353
5454
import errno
5555
import functools
@@ -132,7 +132,7 @@ def instance(cls):
132132
133133
A common pattern for classes that depend on IOLoops is to use
134134
a default argument to enable programs with multiple IOLoops
135-
but not require the argument for simpler applications:
135+
but not require the argument for simpler applications::
136136
137137
class MyClass(object):
138138
def __init__(self, io_loop=None):
@@ -296,10 +296,12 @@ def stop(self):
296296
will return immediately.
297297
298298
To use asynchronous methods from otherwise-synchronous code (such as
299-
unit tests), you can start and stop the event loop like this:
299+
unit tests), you can start and stop the event loop like this::
300+
300301
ioloop = IOLoop()
301302
async_method(ioloop=ioloop, callback=ioloop.stop)
302303
ioloop.start()
304+
303305
ioloop.start() will return after async_method has run its callback,
304306
whether that callback was invoked before or after ioloop.start.
305307
"""

‎tornado/iostream.py

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
ssl = None
3535

3636
class IOStream(object):
37-
"""A utility class to write to and read from a non-blocking socket.
37+
r"""A utility class to write to and read from a non-blocking socket.
3838
3939
We support three methods: write(), read_until(), and read_bytes().
4040
All of the methods take callbacks (since writing and reading are
@@ -48,7 +48,7 @@ class IOStream(object):
4848
and may either be connected before passing it to the IOStream or
4949
connected with IOStream.connect.
5050
51-
A very simple (and broken) HTTP client using this class:
51+
A very simple (and broken) HTTP client using this class::
5252
5353
from tornado import ioloop
5454
from tornado import iostream
@@ -414,8 +414,10 @@ class SSLIOStream(IOStream):
414414
"""A utility class to write to and read from a non-blocking socket.
415415
416416
If the socket passed to the constructor is already connected,
417-
it should be wrapped with
417+
it should be wrapped with::
418+
418419
ssl.wrap_socket(sock, do_handshake_on_connect=False, **kwargs)
420+
419421
before constructing the SSLIOStream. Unconnected sockets will be
420422
wrapped when IOStream.connect is finished.
421423
"""

‎tornado/locale.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,14 @@
1616

1717
"""Translation methods for generating localized strings.
1818
19-
To load a locale and generate a translated string:
19+
To load a locale and generate a translated string::
2020
2121
user_locale = locale.get("es_LA")
2222
print user_locale.translate("Sign out")
2323
2424
locale.get() returns the closest matching locale, not necessarily the
2525
specific locale you requested. You can support pluralization with
26-
additional arguments to translate(), e.g.:
26+
additional arguments to translate(), e.g.::
2727
2828
people = [...]
2929
message = user_locale.translate(
@@ -78,7 +78,7 @@ def set_default_locale(code):
7878

7979

8080
def load_translations(directory):
81-
"""Loads translations from CSV files in a directory.
81+
u"""Loads translations from CSV files in a directory.
8282
8383
Translations are strings with optional Python-style named placeholders
8484
(e.g., "My name is %(name)s") and their associated translations.
@@ -100,8 +100,8 @@ def load_translations(directory):
100100
Example translation es_LA.csv:
101101
102102
"I love you","Te amo"
103-
"%(name)s liked this","A %(name)s les gust\xf3 esto","plural"
104-
"%(name)s liked this","A %(name)s le gust\xf3 esto","singular"
103+
"%(name)s liked this","A %(name)s les gust\u00f3 esto","plural"
104+
"%(name)s liked this","A %(name)s le gust\u00f3 esto","singular"
105105
106106
"""
107107
global _translations

‎tornado/options.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
"""A command line parsing module that lets modules define their own options.
1818
19-
Each module defines its own options, e.g.,
19+
Each module defines its own options, e.g.::
2020
2121
from tornado.options import define, options
2222
@@ -31,14 +31,14 @@ def connect():
3131
The main() method of your application does not need to be aware of all of
3232
the options used throughout your program; they are all automatically loaded
3333
when the modules are loaded. Your main() method can parse the command line
34-
or parse a config file with:
34+
or parse a config file with::
3535
3636
import tornado.options
3737
tornado.options.parse_config_file("/etc/server.conf")
3838
tornado.options.parse_command_line()
3939
4040
Command line formats are what you would expect ("--myoption=myvalue").
41-
Config files are just Python files. Global names become options, e.g.,
41+
Config files are just Python files. Global names become options, e.g.::
4242
4343
myoption = "myvalue"
4444
myotheroption = "myothervalue"
@@ -77,7 +77,7 @@ def define(name, default=None, type=None, help=None, metavar=None,
7777
turns into range(x, y) - very useful for long integer ranges.
7878
7979
help and metavar are used to construct the automatically generated
80-
command line help string. The help message is formatted like:
80+
command line help string. The help message is formatted like::
8181
8282
--name=METAVAR help string
8383

‎tornado/stack_context.py

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@
2929
that transfer control from one context to another (e.g. AsyncHTTPClient
3030
itself, IOLoop, thread pools, etc).
3131
32-
Example usage:
32+
Example usage::
33+
3334
@contextlib.contextmanager
3435
def die_on_error():
3536
try:
@@ -65,9 +66,12 @@ def __init__(self, context_factory):
6566
6667
Note that the parameter is a callable that returns a context
6768
manager, not the context itself. That is, where for a
68-
non-transferable context manager you would say
69+
non-transferable context manager you would say::
70+
6971
with my_context():
70-
StackContext takes the function itself rather than its result:
72+
73+
StackContext takes the function itself rather than its result::
74+
7175
with StackContext(my_context):
7276
'''
7377
self.context_factory = context_factory

‎tornado/template.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,19 +16,19 @@
1616

1717
"""A simple template system that compiles templates to Python code.
1818
19-
Basic usage looks like:
19+
Basic usage looks like::
2020
2121
t = template.Template("<html>{{ myvalue }}</html>")
2222
print t.generate(myvalue="XXX")
2323
2424
Loader is a class that loads templates from a root directory and caches
25-
the compiled templates:
25+
the compiled templates::
2626
2727
loader = template.Loader("/home/btaylor")
2828
print loader.load("test.html").generate(myvalue="XXX")
2929
3030
We compile all templates to raw Python. Error-reporting is currently... uh,
31-
interesting. Syntax for the templates
31+
interesting. Syntax for the templates::
3232
3333
### base.html
3434
<html>
@@ -57,15 +57,15 @@
5757
5858
Unlike most other template systems, we do not put any restrictions on the
5959
expressions you can include in your statements. if and for blocks get
60-
translated exactly into Python, do you can do complex expressions like:
60+
translated exactly into Python, do you can do complex expressions like::
6161
6262
{% for student in [p for p in people if p.student and p.age > 23] %}
6363
<li>{{ escape(student.name) }}</li>
6464
{% end %}
6565
6666
Translating directly to Python means you can apply functions to expressions
6767
easily, like the escape() function in the examples above. You can pass
68-
functions in to your template just like any other variable:
68+
functions in to your template just like any other variable::
6969
7070
### Python code
7171
def add(x, y):

‎tornado/testing.py

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,13 @@
22
"""Support classes for automated testing.
33
44
This module contains three parts:
5+
56
* AsyncTestCase/AsyncHTTPTestCase: Subclasses of unittest.TestCase
67
with additional support for testing asynchronous (IOLoop-based) code.
8+
79
* LogTrapTestCase: Subclass of unittest.TestCase that discards log output
810
from tests that pass and only produces output for failing tests.
11+
912
* main(): A simple test runner (wrapper around unittest.main()) with support
1013
for the tornado.autoreload module to rerun the tests when code changes.
1114
@@ -56,7 +59,8 @@ class AsyncTestCase(unittest.TestCase):
5659
returned from self.wait. It is possible to have multiple
5760
wait/stop cycles in the same test.
5861
59-
Example:
62+
Example::
63+
6064
# This test uses an asynchronous style similar to most async
6165
# application code.
6266
class MyTestCase(AsyncTestCase):
@@ -196,7 +200,8 @@ class AsyncHTTPTestCase(AsyncTestCase):
196200
Tests will typically use the provided self.http_client to fetch
197201
URLs from this server.
198202
199-
Example:
203+
Example::
204+
200205
class MyHTTPTest(AsyncHTTPTestCase):
201206
def get_app(self):
202207
return Application([('/', MyHandler)...])
@@ -303,16 +308,19 @@ def run(self, result=None):
303308
def main():
304309
"""A simple test runner with autoreload support.
305310
306-
The easiest way to run a test is via the command line:
311+
The easiest way to run a test is via the command line::
312+
307313
python -m tornado.testing --autoreload tornado.test.stack_context_test
314+
308315
See the standard library unittest module for ways in which tests can
309316
be specified.
310317
311318
Projects with many tests may wish to define a test script like
312319
tornado/test/runtests.py. This script should define a method all()
313320
which returns a test suite and then call tornado.testing.main().
314321
Note that even when a test script is used, the all() test suite may
315-
be overridden by naming a single test on the command line.
322+
be overridden by naming a single test on the command line::
323+
316324
# Runs all tests
317325
tornado/test/runtests.py --autoreload
318326
# Runs one test

0 commit comments

Comments
 (0)