Public Member Functions | Public Attributes | Static Public Attributes | Private Member Functions | Private Attributes | Static Private Attributes
tornado.web.StaticFileHandler Class Reference
Inheritance diagram for tornado.web.StaticFileHandler:
Inheritance graph
[legend]

List of all members.

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.

Definition at line 2024 of file web.py.


Member Function Documentation

def tornado.web.StaticFileHandler._get_cached_version (   cls,
  abs_path 
) [private]

Definition at line 2463 of file web.py.

def tornado.web.StaticFileHandler._stat (   self) [private]

Definition at line 2346 of file web.py.

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.

Definition at line 2176 of file web.py.

def tornado.web.StaticFileHandler.get (   self,
  path,
  include_body = True 
)

Reimplemented from tornado.web.RequestHandler.

Definition at line 2104 of file web.py.

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

Definition at line 2234 of file web.py.

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.

Definition at line 2389 of file web.py.

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

Definition at line 2292 of file web.py.

Retrieve the total size of the resource at the given path.

This method may be overridden by subclasses.

.. versionadded:: 3.1

.. versionchanged:: 4.0
   This method is now always called, instead of only when
   partial results are requested.

Definition at line 2351 of file web.py.

Returns the ``Content-Type`` header to be used for this request.

.. versionadded:: 3.1

Definition at line 2377 of file web.py.

Returns a version string for the resource at the given path.

This class method may be overridden by subclasses.  The
default implementation is a hash of the file's contents.

.. versionadded:: 3.1

Definition at line 2329 of file web.py.

Returns the time that ``self.absolute_path`` was last modified.

May be overridden in subclasses.  Should return a `~datetime.datetime`
object or None.

.. versionadded:: 3.1

Definition at line 2365 of file web.py.

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.

Definition at line 2446 of file web.py.

def tornado.web.StaticFileHandler.head (   self,
  path 
)

Definition at line 2100 of file web.py.

def tornado.web.StaticFileHandler.initialize (   self,
  path,
  default_filename = None 
)

Definition at line 2091 of file web.py.

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``.

Definition at line 2403 of file web.py.

def tornado.web.StaticFileHandler.parse_url_path (   self,
  url_path 
)
Converts a static URL path into a filesystem path.

``url_path`` is the path component of the URL with
``static_url_prefix`` removed.  The return value should be
filesystem path relative to ``static_path``.

This is the inverse of `make_static_url`.

Definition at line 2432 of file web.py.

Definition at line 2096 of file web.py.

For subclass to add extra headers to the response

Definition at line 2385 of file web.py.

Sets the content and caching headers on the response.

.. versionadded:: 3.1

Definition at line 2190 of file web.py.

Returns True if the headers indicate that we should return 304.

.. versionadded:: 3.1

Definition at line 2213 of file web.py.

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

Definition at line 2250 of file web.py.


Member Data Documentation

tuple tornado::web.StaticFileHandler::_lock = threading.Lock() [static, private]

Definition at line 2089 of file web.py.

Definition at line 2346 of file web.py.

dictionary tornado::web.StaticFileHandler::_static_hashes = {} [static, private]

Definition at line 2088 of file web.py.

Definition at line 2104 of file web.py.

Definition at line 2086 of file web.py.

Definition at line 2091 of file web.py.

Definition at line 2104 of file web.py.

Definition at line 2104 of file web.py.

Definition at line 2091 of file web.py.


The documentation for this class was generated from the following file:


rosbridge_server
Author(s): Jonathan Mace
autogenerated on Thu Aug 27 2015 14:50:40