/python-bottle-skeleton

A skeleton with examples for creating a bottle application.

Primary LanguagePython

Python Bottle Skeleton

This is a skeleton web application using the bottle framework.

While bottle is an extremely simple framework, there are many things that you probably will need to figure out if developing even fairly simple websites using it. This provides many examples to get you started quickly with bottle.

It includes examples of things you need to create a web application using bottle:

  • Form processing.

  • SQLAlchemy for Database.

  • Testing.

  • WSGI interface to Apache and standalone test server.

  • Templating including standard site page template.

It does not include user session handling, as that varies widely by application.

Quickstart Bottle Tutorial

If you just want to understand Bottle, this is probably a pretty good choice. It is as simple as possible, while also covering all the things you are likely need to build a (fairly) complex Bottle-powered site.

To use this as a tutorial:

  • View and run simple-example. This is a small program with a single dynamic page using the date and time via a template.

  • Optional, requires SQLAlchemy and wtforms to be installed:

    • Install python-sqlalchemy python-sqlalchemy-ext python-wtforms

    • Run: DBCREDENTIALSTR=sqlite:///:memory: PYTHONPATH=lib python app-controller test-server

    • In your browser go to http://127.0.0.1:8080/ and click around the site to understand what it does.

  • Look at the code in website.py, particularly the sections marked by "XXX" .

  • Look at the tests in tests/test_web.py to see how tests can be performed against the web application.

  • Review model.py to see how to define a database with "SQLAlchemy declarative". Particularly review the sections marked with "XXX".

  • Look at the tests in tests/test_model.py for examples of testing the database model.

  • Review app-controller if you want to understand how the site integrates with WSGI servers, CGI servers, or the standalone test server.

Quickstart Building Your Own Site

If you would like to use this skeleton to create a website, which is why I initially created this git repository:

  • If you are going to be using a database, you will need the following files:

    • model.py is the database model. Copy it and modify the sections marked with "XXX".

    • tests/test_model.py has tests of the model, you will need to modify it to test your model, then you can run it to make sure your model is as you expect.

  • If you are not going to be using a database:

    • Delete model.py, tests/test_model.py, and lib/bottledbwrap.py.

    • In website.py remove the "dbwrap" line.

  • Modify website.py to customize your routes, page processing code, and form validation and processing.

  • Modify and create HTML template files in the views subdirectory.

  • Run make to test the code.

  • Run: DBCREDENTIALSTR=sqlite:///:memory: PYTHONPATH=lib python app-controller test-server

  • Go to http://127.0.0.1:8080/ to test your application.

  • Deploy it using either the CGI or WSGI methods (discussed below).

Setting Up Apache

  • Install mod_wsgi and Apache (Ubuntu:sudo apt-get install libapache2-mod-wsgi).

  • Rename "conf/application.conf", update places where it has "XXX", and put it on your Apache config directory ("/etc/apache2/sites-enabled", "/etc/httpd/conf.d").

To run tests:

  • Run "make" in the top-level directory.

Structure of Project

There are the following components to the project:

  • simple-example: This is the simplest example, a small stand-alone program.

  • app-controller: This is a both a WSGI app and a shell script. It can be used as your WSGI application, but it also can be run with:

    • "test-server" to start a stand-alone server.

    • "initdb" to load your base database schema,

    • "load-test-data" to to populate any test data you have defined in your model.

  • model.py: Your database model definition, via SQLAlchemy.

  • website.py: The website controller code. This is where most of the site programming happens, this includes the URL routing, form processing, and other code for the site.

  • static: Any files put in here are served as static content, such as your favicon. You need to define routes to these static files in website.py

  • views: These are your website pages. There is a site template in layout.html, and an example of form processing in user-new.html.

  • lib: Library files used by the site.

    • bottle.py: This is a version of bottle that I used to develop this skeleton, mostly as a "batteries included" move. You may want to pick up a newer copy, but this skeleton is tested against the version here.

    • bottledbwrap.py: See below in the "About bottledbwrap" section.

  • tests: Tests of the web application code, hitting it through the routed URLs in "website.py". Other code tests can be done in the normal way, see my python-unittest-skeleton project for more code testing examples.

  • conf/application.conf: An Apache config file for serving the application.

About bottledbwrap

This is a library I've developed over the years for some of my database applications. It's mostly a thin layer on top of SQLAlchemy that can pull database credentials from one of several files, or some environment variables.

Largely it's about storing database credentials outside of your project, so they don't get checked in to your version control or published on github.

You can provide database credentials in the following ways:

  • In a file called "dbcredentials" in the current directory or the "conf" sub-directory.

  • In the file specified by the environment variable "DBCREDENTIALS".

  • Directly in the environment variable "DBCREDENTIALSSTR".

License

This code, with the exception of lib/bottle.py is entirely in the public domain.

lib/bottle.py is a convenience copy of the Bottle library. Details on its license are available at: http://bottlepy.org/docs/dev/