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 = {} |
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.
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
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] |