Inheritance diagram for tornado.web.StaticFileHandler:
Public Member Functions | |
| def | compute_etag |
| def | get |
| def | get_absolute_path |
| def | get_cache_time |
| def | get_content |
| def | get_content_size |
| def | get_content_type |
| def | get_content_version |
| def | get_modified_time |
| def | get_version |
| def | head |
| def | initialize |
| def | make_static_url |
| def | parse_url_path |
| def | reset |
| def | set_extra_headers |
| def | set_headers |
| def | should_return_304 |
| def | validate_absolute_path |
Public Attributes | |
| absolute_path | |
| default_filename | |
| modified | |
| path | |
| root | |
Static Public Attributes | |
| int | CACHE_MAX_AGE = 86400 |
Private Member Functions | |
| def | _get_cached_version |
| def | _stat |
Private Attributes | |
| _stat_result | |
Static Private Attributes | |
| tuple | _lock = threading.Lock() |
| dictionary | _static_hashes = {} |
Detailed Description
A simple handler that can serve static content from a directory.
A `StaticFileHandler` is configured automatically if you pass the
``static_path`` keyword argument to `Application`. This handler
can be customized with the ``static_url_prefix``, ``static_handler_class``,
and ``static_handler_args`` settings.
To map an additional path to this handler for a static data directory
you would add a line to your application like::
application = web.Application([
(r"/content/(.*)", web.StaticFileHandler, {"path": "/var/www"}),
])
The handler constructor requires a ``path`` argument, which specifies the
local root directory of the content to be served.
Note that a capture group in the regex is required to parse the value for
the ``path`` argument to the get() method (different than the constructor
argument above); see `URLSpec` for details.
To maximize the effectiveness of browser caching, this class supports
versioned urls (by default using the argument ``?v=``). If a version
is given, we instruct the browser to cache this file indefinitely.
`make_static_url` (also available as `RequestHandler.static_url`) can
be used to construct a versioned url.
This handler is intended primarily for use in development and light-duty
file serving; for heavy traffic it will be more efficient to use
a dedicated static file server (such as nginx or Apache). We support
the HTTP ``Accept-Ranges`` mechanism to return partial content (because
some browsers require this functionality to be present to seek in
HTML5 audio or video), but this handler should not be used with
files that are too large to fit comfortably in memory.
**Subclassing notes**
This class is designed to be extensible by subclassing, but because
of the way static urls are generated with class methods rather than
instance methods, the inheritance patterns are somewhat unusual.
Be sure to use the ``@classmethod`` decorator when overriding a
class method. Instance methods may use the attributes ``self.path``
``self.absolute_path``, and ``self.modified``.
Subclasses should only override methods discussed in this section;
overriding other methods is error-prone. Overriding
``StaticFileHandler.get`` is particularly problematic due to the
tight coupling with ``compute_etag`` and other methods.
To change the way static urls are generated (e.g. to match the behavior
of another server or CDN), override `make_static_url`, `parse_url_path`,
`get_cache_time`, and/or `get_version`.
To replace all interaction with the filesystem (e.g. to serve
static content from a database), override `get_content`,
`get_content_size`, `get_modified_time`, `get_absolute_path`, and
`validate_absolute_path`.
.. versionchanged:: 3.1
Many of the methods for subclasses were added in Tornado 3.1.
Member Function Documentation
| def tornado.web.StaticFileHandler._get_cached_version | ( | cls, | |
| abs_path | |||
| ) | [private] |
| def tornado.web.StaticFileHandler._stat | ( | self | ) | [private] |
| def tornado.web.StaticFileHandler.compute_etag | ( | self | ) |
Sets the ``Etag`` header based on static url version. This allows efficient ``If-None-Match`` checks against cached versions, and sends the correct ``Etag`` for a partial response (i.e. the same ``Etag`` as the full file). .. versionadded:: 3.1
Reimplemented from tornado.web.RequestHandler.
| def tornado.web.StaticFileHandler.get | ( | self, | |
| path, | |||
include_body = True |
|||
| ) |
Reimplemented from tornado.web.RequestHandler.
| def tornado.web.StaticFileHandler.get_absolute_path | ( | cls, | |
| root, | |||
| path | |||
| ) |
Returns the absolute location of ``path`` relative to ``root``. ``root`` is the path configured for this `StaticFileHandler` (in most cases the ``static_path`` `Application` setting). This class method may be overridden in subclasses. By default it returns a filesystem path, but other strings may be used as long as they are unique and understood by the subclass's overridden `get_content`. .. versionadded:: 3.1
| def tornado.web.StaticFileHandler.get_cache_time | ( | self, | |
| path, | |||
| modified, | |||
| mime_type | |||
| ) |
Override to customize cache control behavior. Return a positive number of seconds to make the result cacheable for that amount of time or 0 to mark resource as cacheable for an unspecified amount of time (subject to browser heuristics). By default returns cache expiry of 10 years for resources requested with ``v`` argument.
| def tornado.web.StaticFileHandler.get_content | ( | cls, | |
| abspath, | |||
start = None, |
|||
end = None |
|||
| ) |
Retrieve the content of the requested resource which is located at the given absolute path. This class method may be overridden by subclasses. Note that its signature is different from other overridable class methods (no ``settings`` argument); this is deliberate to ensure that ``abspath`` is able to stand on its own as a cache key. This method should either return a byte string or an iterator of byte strings. The latter is preferred for large files as it helps reduce memory fragmentation. .. versionadded:: 3.1
| def tornado.web.StaticFileHandler.get_content_size | ( | self | ) |
| def tornado.web.StaticFileHandler.get_content_type | ( | self | ) |
| def tornado.web.StaticFileHandler.get_content_version | ( | cls, | |
| abspath | |||
| ) |
| def tornado.web.StaticFileHandler.get_modified_time | ( | self | ) |
| def tornado.web.StaticFileHandler.get_version | ( | cls, | |
| settings, | |||
| path | |||
| ) |
Generate the version string to be used in static URLs. ``settings`` is the `Application.settings` dictionary and ``path`` is the relative location of the requested asset on the filesystem. The returned value should be a string, or ``None`` if no version could be determined. .. versionchanged:: 3.1 This method was previously recommended for subclasses to override; `get_content_version` is now preferred as it allows the base class to handle caching of the result.
| def tornado.web.StaticFileHandler.head | ( | self, | |
| path | |||
| ) |
| def tornado.web.StaticFileHandler.initialize | ( | self, | |
| path, | |||
default_filename = None |
|||
| ) |
| def tornado.web.StaticFileHandler.make_static_url | ( | cls, | |
| settings, | |||
| path, | |||
include_version = True |
|||
| ) |
Constructs a versioned url for the given path. This method may be overridden in subclasses (but note that it is a class method rather than an instance method). Subclasses are only required to implement the signature ``make_static_url(cls, settings, path)``; other keyword arguments may be passed through `~RequestHandler.static_url` but are not standard. ``settings`` is the `Application.settings` dictionary. ``path`` is the static path being requested. The url returned should be relative to the current host. ``include_version`` determines whether the generated URL should include the query string containing the version hash of the file corresponding to the given ``path``.
| def tornado.web.StaticFileHandler.parse_url_path | ( | self, | |
| url_path | |||
| ) |
| def tornado.web.StaticFileHandler.reset | ( | cls | ) |
| def tornado.web.StaticFileHandler.set_extra_headers | ( | self, | |
| path | |||
| ) |
| def tornado.web.StaticFileHandler.set_headers | ( | self | ) |
| def tornado.web.StaticFileHandler.should_return_304 | ( | self | ) |
| def tornado.web.StaticFileHandler.validate_absolute_path | ( | self, | |
| root, | |||
| absolute_path | |||
| ) |
Validate and return the absolute path. ``root`` is the configured path for the `StaticFileHandler`, and ``path`` is the result of `get_absolute_path` This is an instance method called during request processing, so it may raise `HTTPError` or use methods like `RequestHandler.redirect` (return None after redirecting to halt further processing). This is where 404 errors for missing files are generated. This method may modify the path before returning it, but note that any such modifications will not be understood by `make_static_url`. In instance methods, this method's result is available as ``self.absolute_path``. .. versionadded:: 3.1
Member Data Documentation
tuple tornado::web.StaticFileHandler::_lock = threading.Lock() [static, private] |
dictionary tornado::web.StaticFileHandler::_static_hashes = {} [static, private] |
int tornado::web.StaticFileHandler::CACHE_MAX_AGE = 86400 [static] |
The documentation for this class was generated from the following file: