From: Ben Darnell Date: Fri, 17 Jun 2011 05:36:33 +0000 (-0700) Subject: More doc updates X-Git-Tag: v2.0.0~13 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cdc76f2fb1d8c0925ccf227de8223667ef726f4e;p=thirdparty%2Ftornado.git More doc updates --- diff --git a/tornado/escape.py b/tornado/escape.py index 14039a689..fd686bb4d 100644 --- a/tornado/escape.py +++ b/tornado/escape.py @@ -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 http://tornadoweb.org! + For example: ``linkify("Hello http://tornadoweb.org!")`` would return + ``Hello http://tornadoweb.org!`` Parameters: diff --git a/tornado/httpserver.py b/tornado/httpserver.py index cbecfce19..dcaff6429 100644 --- a/tornado/httpserver.py +++ b/tornado/httpserver.py @@ -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 @@ class HTTPConnection(object): 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, diff --git a/tornado/template.py b/tornado/template.py index 243b04cee..018a954eb 100644 --- a/tornado/template.py +++ b/tornado/template.py @@ -77,6 +77,11 @@ functions in to your template just like any other variable:: 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 diff --git a/tornado/web.py b/tornado/web.py index 13f2a204a..ec2f2a77c 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -121,6 +121,7 @@ class RequestHandler(object): supplied as keyword arguments to initialize(). Example:: + class ProfileHandler(RequestHandler): def initialize(self, database): self.database = database @@ -136,6 +137,7 @@ class RequestHandler(object): @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): diff --git a/website/Makefile b/website/Makefile index d763dba31..6357830db 100644 --- a/website/Makefile +++ b/website/Makefile @@ -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 diff --git a/website/sphinx/conf.py b/website/sphinx/conf.py index 4710be6b9..fd7c5db93 100644 --- a/website/sphinx/conf.py +++ b/website/sphinx/conf.py @@ -15,7 +15,10 @@ copyright = "2011, Facebook" 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" diff --git a/website/sphinx/escape.rst b/website/sphinx/escape.rst index 6a434f3f1..54f1ca9d2 100644 --- a/website/sphinx/escape.rst +++ b/website/sphinx/escape.rst @@ -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 diff --git a/website/sphinx/httpserver.rst b/website/sphinx/httpserver.rst index 41f7e1d33..b38bb4971 100644 --- a/website/sphinx/httpserver.rst +++ b/website/sphinx/httpserver.rst @@ -2,4 +2,13 @@ =================================================== .. automodule:: tornado.httpserver - :members: + + ``HTTPRequest`` objects + ----------------------- + .. autoclass:: HTTPRequest + :members: + + HTTP Server + ----------- + .. autoclass:: HTTPServer + .. autoclass:: HTTPConnection diff --git a/website/sphinx/template.rst b/website/sphinx/template.rst index 11c2ea574..bb546d104 100644 --- a/website/sphinx/template.rst +++ b/website/sphinx/template.rst @@ -2,4 +2,4 @@ =================================================== .. automodule:: tornado.template - :members: + :members: diff --git a/website/sphinx/web.rst b/website/sphinx/web.rst index 5ea2927b4..3cd91aec3 100644 --- a/website/sphinx/web.rst +++ b/website/sphinx/web.rst @@ -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