Introduction – Getting Started¶
Klein is a micro-framework for developing production-ready web services with Python, built off Werkzeug and Twisted. The purpose of this introduction is to show you how to install, use, and deploy Klein-based web applications.
This introduction is meant as a general introduction to Klein concepts.
Everything should be as self-contained, but not everything may be runnable (for example, code that shows only a specific function).
Klein is available on PyPI. Run this to install it:
pip install klein
Since Twisted is a Klein dependency, you need to have the requirements to install that as well.
You will need the Python development headers and a working compiler - installing
build-essential on Debian, Mint, or Ubuntu should be all you need.
The following example implements a web server that will respond with “Hello, world!” when accessing the root directory.
from klein import run, route @route('/') def home(request): return 'Hello, world!' run("localhost", 8080)
route from the Klein package, and uses them directly.
It then starts a Twisted Web server on port 8080, listening on the loopback address.
This works fine for basic applications.
However, by creating a Klein instance, then calling the
route methods on it, you are able to make your routing not global.
from klein import Klein app = Klein() @app.route('/') def home(request): return 'Hello, world!' app.run("localhost", 8080)
By not using the global Klein instance, you can have different Klein routers, each having different routes, if your application requires that in the future.
Add more decorated functions to add more routes to your Klein applications.
from klein import Klein app = Klein() @app.route('/') def pg_root(request): return 'I am the root page!' @app.route('/about') def pg_about(request): return 'I am a Klein application!' app.run("localhost", 8080)
You can also make variable routes. This gives your functions extra arguments which match up with the parts of the routes that you have specified. By using this, you can implement pages that change depending on this – for example, by displaying users on a site, or documents in a repository.
from klein import Klein app = Klein() @app.route('/user/<username>') def pg_user(request, username): return 'Hi %s!' % (username,) app.run("localhost", 8080)
If you start the server and then visit
http://localhost:8080/user/bob, you should get
Hi bob! in return.
You can also define what types it should match.
The three available types are
from klein import Klein app = Klein() @app.route('/<string:arg>') def pg_string(request, arg): return 'String: %s!' % (arg,) @app.route('/<float:arg>') def pg_float(request, arg): return 'Float: %s!' % (arg,) @app.route('/<int:arg>') def pg_int(request, arg): return 'Int: %s!' % (arg,) app.run("localhost", 8080)
If you run this example and visit
http://localhost:8080/somestring, it will be routed by
http://localhost:8080/1.0 will be routed by
http://localhost:8080/1 will be routed by
Route Order Matters¶
But remember: order matters! This becomes very important when you are using variable paths. You can have a general, variable path, and then have hard coded paths over the top of it, such as in the following example.
from klein import Klein app = Klein() @app.route('/user/<username>') def pg_user(request, username): return 'Hi %s!' % (username,) @app.route('/user/bob') def pg_user_bob(request): return 'Hello there bob!' app.run("localhost", 8080)
The later applying route for bob will overwrite the variable routing in
Any other username will be routed to
pg_user as normal.
To serve static files from a directory, set the
branch keyword argument on the route you’re serving them from to
True, and return a t.w.static.File with the path you want to serve.
from twisted.web.static import File from klein import Klein app = Klein() @app.route('/', branch=True) def pg_index(request): return File('./') app.run("localhost", 8080)
If you run this example and then visit
http://localhost:8080/, you will get a directory listing.
Since it’s all just Twisted underneath, you can return Deferreds, which then fire with a result.
import treq from klein import Klein app = Klein() @app.route('/', branch=True) def google(request): d = treq.get('https://www.google.com' + request.uri) d.addCallback(treq.content) return d app.run("localhost", 8080)
This example here uses treq (think Requests, but using Twisted) to implement a Google proxy.
Klein tries to do the right thing with what you return.
You can return a result (which can be regular text, a Resource, or a Renderable) synchronously (via
return) or asynchronously (via
Just remember not to give Klein any
unicode, you have to encode it into
That covers most of the general Klein concepts.
The next chapter is about deploying your Klein application using Twisted’s