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.
To install bottle-fdsend, you can use pip or easy_install commands::
pip install bottle-fdsend
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.
from StringIO import StringIO
from fdsend import send_file
s = StringIO('foo')
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.
There are two ways to set the Content-Type header. One is to pass the ctype
return send_file(s, ctype='text/html')
Another method is to specify a filename with extension:
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. ::
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::
return send_file(s, filename='foo.html.gz')
The above snippet generates the following headers:
Content-Type: text/html; charset=UTF-8
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.
return send_file(s, size=2000)
The size is in bytes, and when it is passed, two headers are added::
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. ::
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.
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
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
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
This package provides two alternatives. One is
``fdsend.rangewrapper.range_iter`` generator function and another is
The generator function is similar to bottle's generator function, but
specifically designed to work around file-like objects that do not support
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,
Feature requests and bug reports
Please report all feature requests and bugs to our `issue tracker`_.
.. _byte serving: https://en.wikipedia.org/wiki/Byte_serving
.. _issue tracker: https://github.com/Outernet-Project/bottle-fdsend/issues
TODO: Brief introduction on what you do with files - including link to relevant help section.