Permalink
Browse files

More doc updates

  • Loading branch information...
1 parent db579da commit cdc76f2fb1d8c0925ccf227de8223667ef726f4e @bdarnell bdarnell committed Jun 17, 2011
View
@@ -14,7 +14,11 @@
# License for the specific language governing permissions and limitations
# under the License.
-"""Escaping/unescaping methods for HTML, JSON, URLs, and others."""
+"""Escaping/unescaping methods for HTML, JSON, URLs, and others.
+
+Also includes a few other miscellaneous string manipulation functions that
+have crept in over time.
+"""
import htmlentitydefs
import re
@@ -221,8 +225,8 @@ def linkify(text, shorten=False, extra_params="",
require_protocol=False, permitted_protocols=["http", "https"]):
"""Converts plain text into HTML with links.
- For example: linkify("Hello http://tornadoweb.org!") would return
- Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!
+ For example: ``linkify("Hello http://tornadoweb.org!")`` would return
+ ``Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!``
Parameters:
View
@@ -14,7 +14,15 @@
# License for the specific language governing permissions and limitations
# under the License.
-"""A non-blocking, single-threaded HTTP server."""
+"""A non-blocking, single-threaded HTTP server.
+
+Typical applications have little direct interaction with the `HTTPServer`
+class except to start a server at the beginning of the process
+(and even that is often done indirectly via `tornado.web.Application.listen`).
+
+This module also defines the `HTTPRequest` class which is exposed via
+`tornado.web.RequestHandler.request`.
+"""
import errno
import logging
@@ -418,20 +426,72 @@ def _on_request_body(self, data):
class HTTPRequest(object):
"""A single HTTP request.
- GET/POST arguments are available in the arguments property, which
- maps arguments names to lists of values (to support multiple values
- for individual names). Names and values are both unicode always.
+ .. attribute:: method
+
+ HTTP request method, e.g. "GET" or "POST"
+
+ .. attribute:: uri
+
+ The requested uri.
+
+ .. attribute:: path
+
+ The path portion of `uri`
+
+ .. attribute:: query
+
+ The query portion of `uri`
+
+ .. attribute:: version
+
+ HTTP version specified in request, e.g. "HTTP/1.1"
+
+ .. attribute:: headers
+
+ `HTTPHeader` dictionary-like object for request headers. Acts like
+ a case-insensitive dictionary with additional methods for repeated
+ headers.
+
+ .. attribute:: body
+
+ Request body, if present.
+
+ .. attribute:: remote_ip
+
+ Client's IP address as a string. If `HTTPServer.xheaders` is set,
+ will pass along the real IP address provided by a load balancer
+ in the ``X-Real-Ip`` header
+
+ .. attribute:: protocol
+
+ The protocol used, either "http" or "https". If `HTTPServer.xheaders`
+ is seet, will pass along the protocol used by a load balancer if
+ reported via an ``X-Scheme`` header.
+
+ .. attribute:: host
+
+ The requested hostname, usually taken from the ``Host`` header.
+
+ .. attribute:: arguments
+
+ GET/POST arguments are available in the arguments property, which
+ maps arguments names to lists of values (to support multiple values
+ for individual names). Names and values are both unicode always.
+
+ .. attribute:: files
+
+ File uploads are available in the files property, which maps file
+ names to list of files. Each file is a dictionary of the form
+ {"filename":..., "content_type":..., "body":...}. The content_type
+ comes from the provided HTTP header and should not be trusted
+ outright given that it can be easily forged.
- File uploads are available in the files property, which maps file
- names to list of files. Each file is a dictionary of the form
- {"filename":..., "content_type":..., "body":...}. The content_type
- comes from the provided HTTP header and should not be trusted
- outright given that it can be easily forged.
+ .. attribute:: connection
- An HTTP request is attached to a single HTTP connection, which can
- be accessed through the "connection" attribute. Since connections
- are typically kept open in HTTP/1.1, multiple requests can be handled
- sequentially on a single connection.
+ An HTTP request is attached to a single HTTP connection, which can
+ be accessed through the "connection" attribute. Since connections
+ are typically kept open in HTTP/1.1, multiple requests can be handled
+ sequentially on a single connection.
"""
def __init__(self, method, uri, version="HTTP/1.0", headers=None,
body=None, remote_ip=None, protocol=None, host=None,
View
@@ -77,6 +77,11 @@ def add(x, y):
We provide the functions escape(), url_escape(), json_encode(), and squeeze()
to all templates by default.
+
+Typical applications do not create `Template` or `Loader` instances by
+hand, but instead use the `render` and `render_string` methods of
+`tornado.web.RequestHandler`, which load templates automatically based
+on the ``template_path`` `Application` setting.
"""
from __future__ import with_statement
View
@@ -121,6 +121,7 @@ def initialize(self):
supplied as keyword arguments to initialize().
Example::
+
class ProfileHandler(RequestHandler):
def initialize(self, database):
self.database = database
@@ -136,6 +137,7 @@ def get(self, username):
@property
def settings(self):
+ """An alias for `self.application.settings`."""
return self.application.settings
def head(self, *args, **kwargs):
@@ -1086,6 +1088,12 @@ class Application(object):
keyword argument. We will serve those files from the /static/ URI
(this is configurable with the static_url_prefix setting),
and we will serve /favicon.ico and /robots.txt from the same directory.
+
+ .. attribute:: settings
+
+ Additonal keyword arguments passed to the constructor are saved in the
+ `settings` dictionary, and are often referred to in documentation as
+ "application settings".
"""
def __init__(self, handlers=None, default_host="", transforms=None,
wsgi=False, **settings):
View
@@ -1,4 +1,5 @@
-SPHINXOPTS=-d sphinx/build/doctrees sphinx
+SPHINXOPTS=-W -d sphinx/build/doctrees sphinx
+
.PHONY: sphinx
sphinx:
sphinx-build -b html $(SPHINXOPTS) sphinx/build/html
View
@@ -15,7 +15,10 @@
version = release = tornado.version
-extensions = ["sphinx.ext.autodoc", "sphinx_coverage"]
+extensions = ["sphinx.ext.autodoc", "sphinx_coverage", "sphinx.ext.viewcode"]
+
+primary_domain = 'py'
+default_role = 'py:obj'
autodoc_member_order = "bysource"
autoclass_content = "both"
View
@@ -2,4 +2,38 @@
=======================================================
.. automodule:: tornado.escape
- :members:
+
+ Escaping functions
+ ------------------
+
+ .. autofunction:: xhtml_escape
+ .. autofunction:: xhtml_unescape
+
+ .. autofunction:: url_escape
+ .. autofunction:: url_unescape
+
+ .. autofunction:: json_encode
+ .. autofunction:: json_decode
+
+ Byte/unicode conversions
+ ------------------------
+ These functions are used extensively within Tornado itself,
+ but should not be directly needed by most applications. Note that
+ much of the complexity of these functions comes from the fact that
+ Tornado supports both Python 2 and Python 3.
+
+ .. autofunction:: utf8
+ .. autofunction:: to_unicode
+ .. function:: native_str
+
+ Converts a byte or unicode string into type `str`. Equivalent to
+ `utf8` on Python 2 and `to_unicode` on Python 3.
+
+ .. autofunction:: to_basestring
+
+ .. autofunction:: recursive_unicode
+
+ Miscellaneous functions
+ -----------------------
+ .. autofunction:: linkify
+ .. autofunction:: squeeze
@@ -2,4 +2,13 @@
===================================================
.. automodule:: tornado.httpserver
- :members:
+
+ ``HTTPRequest`` objects
+ -----------------------
+ .. autoclass:: HTTPRequest
+ :members:
+
+ HTTP Server
+ -----------
+ .. autoclass:: HTTPServer
+ .. autoclass:: HTTPConnection
@@ -2,4 +2,4 @@
===================================================
.. automodule:: tornado.template
- :members:
+ :members:
View
@@ -29,6 +29,10 @@
.. automethod:: RequestHandler.get_argument
.. automethod:: RequestHandler.get_arguments
.. automethod:: RequestHandler.decode_argument
+ .. attribute:: RequestHandler.request
+
+ The `tornado.httpserver.HTTPRequest` object containing additional
+ request parameters including e.g. headers and body data.
Output
^^^^^^
@@ -61,6 +65,10 @@
Other
^^^^^
+ .. attribute:: RequestHandler.application
+
+ The `Application` object serving this request
+
.. automethod:: RequestHandler.async_callback
.. automethod:: RequestHandler.check_xsrf_cookie
.. automethod:: RequestHandler.compute_etag
@@ -72,6 +80,7 @@
.. automethod:: RequestHandler.get_user_locale
.. automethod:: RequestHandler.on_connection_close
.. automethod:: RequestHandler.require_setting
+ .. autoattribute:: RequestHandler.settings
.. automethod:: RequestHandler.static_url
.. automethod:: RequestHandler.xsrf_form_html

0 comments on commit cdc76f2

Please sign in to comment.