Complete python bottle template for web applications or API servers.
bottleplate is a bottle template for
python
3.3+ web applications or API servers. The files structure is very
similar to that of a Ruby on Rails application and
thus follows a model-view-controller (MVC) pattern. It provides a simple way to
have development, test and production environments. The structure for
functional and unit testing is also already in place. It is very common for
bottle
applications to define routes using the bottle
route decorator.
However, I find it more convenient to have all routes defined in a file. This
template uses bottleplate/config/routes.py
for that. SQLAlchemy
is used as
the object relational mapping (ORM) tool. It supports a broad range of database
backends (MySQL, PostgreSQL, SQLite, ...) and is usually the ORM of choice when
it comes to python
. alembic
is used to handle database migrations so it
takes care of the changes regarding the database schemas.
Sounds interesting? If you still have questions after having read this readme file, feel free to contact me (either by email or IRC at #gwcomputingnet on Freenode).
Need to have a look at a concrete examples? Have a look at pydeo to see a usage of this template for a web application and devmine-core to see an example usage of this template for an API server.
Not much actually since this is not a framework but just a template. However, it assumes some choices such as:
python
webOf course, nothing is written into stone and you can adapt the template to your needs.
The root directory contains two folders and some files:
alembic.ini.sample
: this is a template file for alembic.ini
. It is copiedalembic.ini
when invoke setup
is run.bottleplate
: this is where lays your bottle application.env
: this folder is used for the python virtual environment.requirements.txt
: this file defines the prerequisite packages to run therequirements_dev.txt
: this file defines the prerequisite packages needed torun.py
: this script is used to run the application.tasks.py
: this is where you can define tasks. In some ways, this is similarapp
: is used to organize your application contents such as controllers,app/controllers
: this is where lay the application controllers.app/helpers
: this is where helper classes are defined.app/models
: this is where the application models are defined, usingapp/views
: this is where the HTML template files are. The basicbottleplate
uses the SimpleTemplate
, which is a very simple templatebottle
but of course, other template engines such asapp/views/layouts
: this is where you define the base layout templates to beconfig
: the configuration files lay there.config/environments
: this is where you define the specific environmentconfig/routes.py
: this is where you define your routes and associate them todb
: if you use a SQLite database, you will find the database file here.alembic
to store the database migrationlib
: if you need to write libraries, you would place them here.log
: this is where the log files should go.test
: this folder is meant to hold the test files.test/functional
: this is where you write functional tests.test/unit
: this is where you write unit tests.Some tasks are already defined in the tasks.py
file.
set_settings
: this task is used to copy the default configuration file fromsettings-{environment}.py
filesettings.py
where {environment}
is one of development | production | test
.invoke set_settings --environment=production
dev
: run the application.test_func
: run the functional tests.test_unit
: run the unit tests.test
: run both the functional and unit tests.setup
: copy the setting files and alembic sample files from their templates.pep8
: check source code compliance to PEP8.flake8
: check source code for errors.check
run both the pep8
and flake8
tasks.clean
: clean any python generated files and folders.clean_env
: run the clean
tasks and reinitializes the python environment.rename
: this is supposed to be used only once. It rename the bottleplate
bottleplate
and Bottleplate
names in python sourcesmy awesome app
,bottleplate
will be replaced by myawesomeapp
and occurencesBottleplate
by MyAwesomeApp
.Make sure you have python
3.3 or above and virtualenv
. Follow these steps:
virtualenv -p python3 env
source env/bin/activate
pip
:pip install -r requirements.txt -r requirements_dev.txt
From now on, you also need to choose which web server backend you are willing to
use with bottle. Have a look
here
for the full list of servers supported by bottle
but keep in mind that not all
of them are compatible with python3
. Let's assume that your choice is
cherrypy
(which is the server set by default in this template but you can
easily change that). Then, what you would do is make sure that in
bottleplate/config/environments/(development|production|test).py
, server
is
set to cherrypy
: server = 'cherrypy'
. Maybe, it is OK to keep the simple
wsgiref
server for testing so you would simple set it to this wsgiref
for
the test environment.
Of course, you then need to install the server backend: pip install cherrypy
.
Now that you have a web server backend, you also need to choose a database
backend. Let's assume that you choose to use sqlite
as test and
development databases and postgresql
for production. The you need to change
db_url
in the respective files like, for instance:
development.py
: db_url = 'sqlite:///bottleplate/db/dev.db'
production.py
: db_url = 'postgresql://user:pass@localhost/dbname'
test.py
: db_url = 'sqlite:///:memory:'
Of course, you might need additional packages to support the database backend.
For instance, if you use postgresql
, you need psycopg2
.
To use the migration, you also need to provide the appropriate database URL in
the alembic.ini
file. Have a look at
alembic documentation for more information.
Once all of this is setup, you can rename the template using this command:
invoke rename --name='my awesome app name'
.
Of course, replace the name by the appropriate one. You may want to remove the
template under views if you are creating an API server.
Considering all has been setup, you can run your application using this command:
python run.py
Or using invoke
:
invoke dev
You can now navigate to http://localhost:8080
(considering you haven't changed
the default port) and see a sample home page.