Vilo: Simple, unopinionated Python web framework.
Project description
Vilo
Vilo is a WSGI micro-framework for building web apps with Python. Inspired by Express and Bottle, Vilo is lightweight, unopinionated, and flexible.
Quick Plug: Vilo is built by the folks at Polydojo, Inc. Effective project management is essential for building and maintaining web apps. If your team is looking for a simple project management tool, check out our latest product: BoardBell.com.
Installation
Please download vilo.py
into your project directory.
Gunicorn is recommended for running Vilo apps (in development and production), installable via pip:
pip install gunicorn
Hello, World!
Create hello.py
:
import vilo; # Import vilo
app = vilo.buildApp(); # Create app
@app.route("GET", "/") # Add route
def get_homepage (req, res):
return "Hello, World!";
wsgi = app.wsgi; # WSGI callable
Running with Gunicorn:
For development, run with Gunicorn as follows:
gunicorn hello:wsgi --reload
The above line tells Gunicorn to run wsgi
from hello.py
. Once running, visit localhost:8000
to access the app. In production, drop the --reload
flag. Consult Gunicorn's docs for more.
Vilo vs Bottle/Flask/Express
1. No Global request
or response
:
Bottle and Flask both employ global request
and response
objects. Vilo instead, like Express, supplies req
and res
as arguments to each route handler.
2. Conspicuous HTTP Method(s):
Like Bottle and Flask, Vilo relies on the decorator-based @app.route(...)
pattern for route definitions, but unlike them, Vilo encourages you to conspicuously specify the HTTP request method (or methods, as a list).
3. No Built-In Templating:
Bottle and Flask both include built-in templating engines. As an un-opinionated framework, Vilo doesn't. You may pick any templating engine you want. For illustration only, our examples will use Qree, installable via pip install qree
.
4. No Built-In Development Server:
Bottle and Flask include a development server with hot-reloads for local testing and development, but recommend against using it in production. Instead of pre-packaging a devlopment server, we recommend using Gunicorn with the --reload
flag.
Basic Routes & Static Files
Working with fixed routes is fairly straightforward. For instance, to handle the route "/foo/bar"
, just supply that path to app.route(.)
For example:
# import vilo, define app etc.
@app.route("GET", "/foo/bar")
def get_foo_bar (req, res):
return "You sent a GET request to path: /foo/bar";
@app.route("GET", "/task/1")
def get_listTasks (req, res):
return yourLogic_showTask(1);
@app.route("GET", "/task/2")
def get_listTasks (req, res):
return yourLogic_showTask(2);
@app.route("POST", "/newTask")
def post_newTask (req, res):
return "You sent a POST request at path: /newTask";
If you have static CSS, JS, image or other static files, you can use res.staticFile(filepath, [mimeType])
for serving them. For example, let's say you have the following directory structure:
- app.py
- config.py
- utils.py
- static/
- jquery.js
- logo.png
In such a case, you could serve jquery and your logo as follows:
# import vilo, define app etc.
@app.route("GET", "/static/jquery.js")
def get_jquery (req, res):
return res.staticFile("./static/jquery.js");
@app.route("GET", "/static/logo.png")
def get_bootstrap (req, res):
return res.staticFile("./static/logo.png");
Optionally, you may pass mimeType
to res.staticFile(.)
. If not passed, it'll be guessed.
DRY = Don't Repeat Yourself
You would've noticed that routes /task/1
and /task/2
, and similarly the routes /static/jquery.js
and /static/logo.png
are essentially the same. Repeating them twice not very DRY.
Right now, there seem to be just two tasks and two static files. But what if there were 10 each? 100 each? Instead of tediously repeating ourselves, we can use wildcard routes. That's next.
Wildcard Routes
The URL path has multiple slash-separated segments. Use *
for wildcard segment matching. Exclusively at the end of the URL, using **
instead of a single *
will match multiple segments, including slashes therebetween.
With the sole exception of **
at the end of the URL, each *
matches a single but complete segment. Thus, except at the end, each *
must be sandwiched between two slashes: /*/
.
The list of matched wildcards is available via req.wildcards
.
Examples:
-
/category/*/page/*/edit
-
WILL match
/category/Food/page/Pasta/edit
withreq.wildcards = ['Food', 'Pasta']
. -
but will NOT match
/category/Fo/od/page/Pasta/edit
becauseFo/od
are two separate segments.
-
-
/cart/add-item/*
-
will match
/cart/add-item/123
withreq.wildcards = ['123']
. -
but will NOT match
/cart/add-item/12/3
because12/3
are two separate segments.
-
-
/static/**
-
will match
/static/lib/js/jquery.js
withreq.wildcards = 'lib/javascript/jquery.js
-
but will NOT match
/StaTiC/lib/js/jquery.js
becauseStaTiC
won't matchstatic
.
-
Now, using wildcard routes, we could write:
# import vilo, define app etc.
@app.route("GET", "/task/*")
def get_task (req, res):
taskId = int(req.wildcards[0]);
return yourLogic_showTask(1)
@app.route("GET", "/static/**")
def get_static (req, res):
"Serves static files from the `static/` dir.";
relpath = req.wildcards[0];
return res.staticFile("./static/" + relpath);
@app.route("GET", "/category/*/season/*")
def get_category_season (req, res):
"Serve product info by category and season."
cateogry, season = req.wildcards;
productsPage = doSomething(category, season);
return productsPage;
Regular Expression Mode
Wildcard patterns are powerful, but don't necessarily cover all use cases. For greater flexibility, you can rely on regular expressions.
Let's say we want to match routes like the following:
"/show-posts/from-2018-to-2020"
"/show-posts/from-1915-to-2015"
As each *
matches an entire segment, we CANNOT use:
"/show-posts/from-*-to-*"
Instead, we can use the following regular expression:
r"/show-posts/from-(\d+)-to-(\d+)"
For using regular expression mode, pass mode="re"
to app.route(.)
. The resultant match-object is available as req.matched
. For example:
# import vilo, define app, etc.
@app.route("GET", r"/show-posts/from-(\d+)-to-(\d+)", mode="re")
def get_showPosts (req, res):
fromYear, toYear = req.matched.groups();
resultPage = yourLogic(fromYear, toYear);
return resultPage;
The mode
parameter to app.route(.)
:
Generally speaking, there's no need to explicitly pass mode
. It takes one of three values:
["re", "wildcard", "exact"]
.
"re"
: regular expression based onre.match(.)
."wildcard":
wildcard matching, as explain hereabove."exact"
: exact equality, based on==
operator.
If mode
isn't passed, Vilo makes an educated guess.
Dot-Accessible Dictionary (DotDict
)
Vilo makes heavy use of dot-accessible dictionaries. In fact, in all previous examples, app
, req
and res
are all dot-accessible dictionaries!
Sidebar: Vilo relies on
Addict
, a great library for dot-accessible dictionaries. By default,Addict
does NOT raiseKeyError
for missing keys, which can lead to hard-to-debug errors. Vilo defines and usesDotDict
, a subclass ofAddict
that raisesKeyError
properly.Philosophy: The Polydojo team strongly favours functional programming over classical OOP. As far as possible, we avoid writing classes. This is super-easy in JavaScript, especially because object properties are dot-accessible.
Addict
allows us to bring the same ease to Python.
DotDict
Usage:
>>> from vilo import DotDict
>>>
>>> dd = DotDict({})
>>> dd
{}
>>> dd.foo = "foo"
>>> dd.foo
'foo'
>>> dd
{'foo': 'foo'}
>>> dd.bar = "bar"
>>> dd.bar
'bar'
>>> dd
{'foo': 'foo', 'bar': 'bar'}
>>> dd.baz
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
... (truncated) ...
File "/...(cut).../vilo.py", line ..., in __missing__
raise KeyError(key);
KeyError: 'baz'
>>>
HTML Escaping & %s
-Formatting
Use vilo.esc(string)
for escaping HTML:
vilo.esc('foo')
=>'foo'
vilo.esc('<b> HELLO </b>')
=>'<b> HELLO </b>'
vilo.esc('<script> alert("XSS"); </script>')
=>'<script> alert("XSS"); </script>'
Use vilo.escfmt(string, data)
for escape-wrapped, %s
-based formatting.
Working With Forms
- Use
req.qdata
to access query string parameters. - Use
req.fdata
to access POSTed form data. - POSTed multipart/form-data is also available via
req.fdata
. - Both
req.qdata
andreq.fdata
are of typeDotDict
.
Here are a few examples of Vilo in action:
1. Simple Greeter, Using Wildcard:
import vilo; app = vilo.buildApp(); wsgi = app.wsgi;
@app.route("GET", "/hello/*")
def get_hello_name (req, res):
name = req.wildcards[0];
return "Hello, " + vilo.esc(name);
2. Factorial Example, Using GET
:
import vilo; app = vilo.buildApp(); wsgi = app.wsgi;
@app.route("GET", "/")
def get_homepage (req, res):
return """
<form method="GET" action="/factorial">
<input type="text" name="n" placeholder="Enter N:">
<button>Submit</button>
</form>
""";
# Factorial helper:
facto = lambda n: 1 if n == 0 else n * facto(n - 1);
@app.route("GET", "/factorial")
def get_factorial (req, res):
n = int(req.qdata.get("n") or 1);
return vilo.escfmt("""
<h2>%s! = %s</h2>
<a href="javascript: history.back();">Back</a>
""", [n, facto(n)]);
TODO [Docs]
Write documentation for:
- File handling,
- Templating with Qree,
- Cookies
- Redirects
- Error handling
- Additional examples
TestBin: In-Memory Pastebin App:
The following example creates a super-simple, in-memory pastebin app. Instead of connecting to a database or file-storage system, the app uses a dict
for (temporarily) storing pastes.
testbin.py
:
import json;
import vilo; app = vilo.buildApp(); wsgi = app.wsgi;
pasteMap = {}; # In-memory paste storage.
@app.route("GET", "/")
def get_homepage (req, res):
return vilo.escfmt("""
<h2>TestBin: In-Memory Pastebin</h2>
<p>
Visit <a href="/compose">/compose</a> to compose a new paste.
</p>
<p>
Go to /paste/{Paste-ID-here} to view a paste.
</p>
<pre>Paste IDs: %s</pre>
""", json.dumps(list(pasteMap.keys()), indent=4));
@app.route("GET", "/compose")
def get_compose (req, res):
return """
<h2>Compose Paste:</h2>
<form method="POST" style="max-width: 500px;">
<input type="text" name="title" placeholder="Title" style="width: 100%;">
<br><br>
<textarea name="body" placeholder="Body ..." rows="10" style="width: 100%;"></textarea>
<br><br>
<button>Submit</button>
</form>
<br>
<p><a href="/">< Home</a></p>
""";
@app.route("POST", "/compose")
def post_compose (req, res):
title = req.fdata.get("title") or "(Blank Title)";
body = req.fdata.get("body") or "(Blank Body)";
pasteId = len(pasteMap) + 1;
pasteMap[pasteId] = vilo.DotDict({
"id": pasteId, "title": title, "body": body,
});
assert len(pasteMap) == pasteId;
return vilo.escfmt("""
<h3>Paste Created!</h3>
<p>
Visit <a href="/paste/%s">/paste/%s</a> to view your paste,
or <a href="/compose">/compose</a> to compose another.
</p>
<hr>
<br>
<p><a href="/">< Home</a></p>
""", [pasteId, pasteId]);
@app.route("GET", "/paste/*")
def get_paste (req, res):
pid = req.wildcards[0];
if not (pid.isdigit() and int(pid) in pasteMap):
raise vilo.error("<h2>No such paste.</h2>", 404);
paste = pasteMap[int(pid)];
return vilo.escfmt("""
<pre>Paste ID: %(id)s</pre>
<h1>%(title)s</h1>
<pre>%(body)s</h1>
<hr>
<br>
<p><a href="/">< Home</a></p>
""", paste);
The module testbin.py
is included in the Github repo. You can run it as follows:
gunicorn testbin:wsgi --reload
Licensing:
The software is licensed under the Apache License 2.0; see LICENSE.txt for more.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.