bottle-fdsend

This package implements functions for constructing bottle's HTTPResponse objects from file handles. Unlike the bottle.static_file() function, functions in this package allow for serving files constructed in memory, or unpacked from compressed archives into memory.

Installation

To install bottle-fdsend, you can use pip or easy_install commands:

pip install bottle-fdsend

easy_install bottle-fdsend

Basic usage

The function we will be using most of the time is the fdsend.send_file() function. At it's simplest, we simply pass a file-like object to this function and it will return a bottle.HTTPResponse object.

For example:

from StringIO import StringIO
from fdsend import send_file

def my_request_handler():
    s = StringIO('foo')
    return send_file(s)

Because we are working with in-memory files and not physical files, however, none of the common response headers are set if we don't supply additional metadata about the file. In order to set Content-Type, Content-Length and similar headers, we need to pass a few optional arguments.

Note that send_file() merely constructs a response object. We have to return it in order to have bottle serve it. We also need to keep in mind that the returned response object is a brand new one and anything we do to bottle.response is not reflected on it. If we need to set additional headers and such, we must do so on the returned response object, not the global bottle.response object.

Content type

There are two ways to set the Content-Type header. One is to pass the ctype argument:

def my_request_handler():
    ....
    return send_file(s, ctype='text/html')

Another method is to specify a filename with extension:

def my_request_handler():

... return send_file(s, filename='foo.html')

If you pass both arguments, the ctype argument takes precedence when it comes to Content-Type header.

Character set and encoding

When we set the Content-Type header by means of passing a filename, the content type is automatically calculated based on file extension. In case of files whose MIME type (content type) starts with 'test/' (e.g., 'text/html', 'text/plain', and so on), character set is appended to the Content-Type header.

For example, send_file(s, filename='foo.html') results in a Content-Type header that looks like this:

Content-Type: text/html; charset=UTF-8

The 'UTF-8' character set is the default. If our data is using a different character set, we need to explicitly specify it.

def my_request_handler():
    ...
    return send_file(s, filename='foo.html', charset='ascii')

With above snippet, we get a different Content-Type header:

Content-Type: text/html; charset=ascii

Another header gets automatically added depending on file extension, and that is the Content-Encoding header. This applies to compressed files. For example:

def my_request_handler():
    ...
    return send_file(s, filename='foo.html.gz')

The above snippet generates the following headers:

Content-Type: text/html; charset=UTF-8 Content-Encoding: gzip

The Content-Encoding header cannot be set manually, but it can be omitted by manually passing the ctype argument.

File size and byte serving

Because it would be wasteful to read from the file handle just to obtain the file size, it is our responsibility to know in advance the size of our file and tell send_file() what size it should use. This is done by using the aptly named size parameter.

def my_request_handler():

... return send_file(s, size=2000)

The size is in bytes, and when it is passed, two headers are added:

Content-Length: 20000
Accept-Range: bytes

The first header tells the client the size of the payload, and the second header announces we are able to do byte serving_. Byte serving is especially useful when browsers want to retrieve portions of the files (e.g., resume a download, load files in stages, like in video players, PDF extensions, etc).

As programmers, we don't really need to do anything to take advantage of byte serving techniques: send_file() takes care of it. However, we do need to know the total size of the file and pass it.

Note that response when doing byte serving is 206, not 200.

File timestamp and 304 Not Modified responses

If you want the Last-Modified header to be set, you must pass the timestamp argument. The timestamp must be in seconds since Unix epoch.

def my_request_handler():
    ...
    return send_file(s, timestamp=1429458831)

The above timestamp will generate the following Last-Modified header:

Last-Modified: Sun, 19 Apr 2015 15:53:51 GMT

Passing the timestamp also causes send_file() to automatically return a HTTP 304 Not Modified response when client includes a valid If-Modified-Since request header.

Content-Disposition

When Content-Disposition header is set to a value of 'attachment', most modern browsers will offer the user to download the file (by opening a download dialog, for instance) instead of trying to display the contents in the browser window. To set this header, we need to pass both the filename and the attachment argument:

def my_request_handler():
    ...
    return send_file(s, filename='foo.html', attachment=True)

Byte serving wrappers

Lastly, we can control how the ranges are returned from the file-like object in byte serving.

The simplest wrapper we can use is the bottle's own bottle._file_iter_range generator function. This wrapper allows us to iterate over the desired range and return file data in chunks (1MB by default).

While this works in most cases, it does not work for some types of file-like objects, such as file handles for ZIP file contents using DEFLATE compression which do not allow seek() to be called on them. (Not the mention the fact that bottle._file_iter_range is not a public API and therefore subject to change).

This package provides two alternatives. One is fdsend.rangewrapper.range_iter generator function and another is fdsend.rangewrapper.RangeWrapper class.

The generator function is similar to bottle's generator function, but specifically designed to work around file-like objects that do not support seek().

The RangeWrapper is a bit different and it returns a file-like object that has its own read() method which is restricted to the requested range.

The primary difference between the two is whether wsgi.file_wrapper feature is used on not. This feature requires a file-like object to be passed in order to be used.

The default wrapper is fdsend.rangewrapper.range_iter.

It is also possible to write your own wrapper. The wrapper must be a callable (function, class, etc) and must accept the following positional arguments:

• file handle
• offset (in bytes from the start of the file)
• length (size of the range in bytes)

The return value must be a valid WSGI response body (string, iterable, file-like object).

Feature requests and bug reports

Please report all feature requests and bugs to our issue tracker.