Rheostatic 0.0.1

Features

• A dedicated static file server.

• Emulates common behaviors of various popular servers (index files, extensionless files, index directories, etc.) See options for specifics.

• Serves custom error pages.

• Does not require the server root to be the current working directory.

• 

Options

Rheostatic currently supports the following options:

Installation

To install Rheostatic run the following command:

pip install https://github.com/waylan/rheostatic/archive/master.zip

Note that this is currently alpha software and not yet hosted on PyPI. As such, the above command downloads the source code from GitHub. Upon a stable release, the package will become available from PyPI.

Preparing your Files

Before running the server, you need some files to serve. All files must be in the root directory and its sub-directories. In fact, an error will occur if a file is requested outside of the root directory. The root directory can exist anywhere on your filesystem as long as Rheostatic has permission to read the files.

Ensure that all files are saved using the same encoding and that that encoding is being used by Rheostatic. See encoding for details.

A file’s ContentType is determined by its file extension. For best results, use common file extensions for your files. A list of known file extensions and the ContentType used for each can be found in rheostatic/utils.py.

If you would like a file to be served when the client requests a directory (for example /, or /path/to/some/dir/), then that directory needs to contain an index file. Be sure to use the file name for the index file set by the index_file option. The default for most servers (including Rheostatic) is index.html.

If a directory does not contain an index file, then Rheostatic will return a directory listing of all the files in that directory (excluding files with names that start with a dot).

For custom error pages, include files in the “root” directory named <code>.html where <code> is the HTTP error code which the error page corresponds to. For example, a file named 404.html would be returned for 404 (Not Found) errors. Supported error codes include 404 (Not Found), and 405 (Method Not Allowed). If a custom error page is not found, then Rheostatic serves a simple plain-text error page.

Use as a Command Line Tool

From the root directory of your site, run the command rheostatic:

$ cd /var/www
$ rheostatic
Starting server at http://localhost:8000/...
Serving files from /var/www
Press ctrl+c to stop.

Alternatively, pass the root directory to the rheostatic command:

$ rheostatic path/to/root
Starting server at http://localhost:8000/...
Serving files from /absolute/path/to/root
Press ctrl+c to stop.

For detailed usage instructions and options, run rheostatic --help.

If the rheostatic command cannot be found, try running python -m rheostatic instead.

Use as a Python Library

For basic usage, import the rheostatic.serve function, which accepts any and all options as keywords:

from rheostatic import serve

serve(address=('0.0.0.0', 80), root='/some/path', default_type='text/plain')

Note that address expects a tuple of the host and port. The host must be a string and the port an integer. All other keywords correspond to the available options.

Under the hood, the serve function creates an instance of the class rheostatic.base.Rheostatic and passes it to a simple wsgi server as a wsgi application. For lower level usage, an instance of the class may be created and passed to any wsgi server. When initializing the class, you may pass in any options as keywords:

from rheostatic.base import Rheostatic

app = Rheostatic(root='/some/path', index_file='README.html')

Rheostatic accepts keywords which correspond to any of the available options. All options are also stored as attributes on the class instance:

print app.root

Infrequently Asked Questions

License

Rheostatic is licensed under the MIT License as defined in LICENSE.

Change Log

Version 0.0.1 (2016/11/03)

The initial release.