# 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
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:
# 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
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,
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
supplied as keyword arguments to initialize().
Example::
+
class ProfileHandler(RequestHandler):
def initialize(self, database):
self.database = database
@property
def settings(self):
+ """An alias for `self.application.settings`."""
return self.application.settings
def head(self, *args, **kwargs):
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):
-SPHINXOPTS=-d sphinx/build/doctrees sphinx
+SPHINXOPTS=-W -d sphinx/build/doctrees sphinx
+
.PHONY: sphinx
sphinx:
sphinx-build -b html $(SPHINXOPTS) sphinx/build/html
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"
=======================================================
.. 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
===================================================
.. automodule:: tornado.httpserver
- :members:
+
+ ``HTTPRequest`` objects
+ -----------------------
+ .. autoclass:: HTTPRequest
+ :members:
+
+ HTTP Server
+ -----------
+ .. autoclass:: HTTPServer
+ .. autoclass:: HTTPConnection
===================================================
.. automodule:: tornado.template
- :members:
+ :members:
.. 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
^^^^^^
Other
^^^^^
+ .. attribute:: RequestHandler.application
+
+ The `Application` object serving this request
+
.. automethod:: RequestHandler.async_callback
.. automethod:: RequestHandler.check_xsrf_cookie
.. automethod:: RequestHandler.compute_etag
.. 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
projects / thirdparty / tornado.git / commitdiff
