Note: This code is part of a collection of various starter examples. See more at: https://github.com/seedifferently/starters
This is an opinionated Python web application. It utilizes a "full-stack" Python web development framework comprised of the following packages:
- Pyramid
- A small, fast, down-to-earth Python web framework.
- SQLAlchemy
- A SQL toolkit and Object Relational Mapper that gives application developers the full power and flexibility of SQL.
- Jinja2
- A modern and designer-friendly templating language.
- FormEncode
- A validation and form generation package.
- WebHelpers2
- A library of helper functions intended to make writing web applications easier.
It is recommended that you use a Python environment manager such as pyenv or virtualenvwrapper to manage your Python development environment.
Once you have correctly set up and activated your Python environment, you should initialize the project and its dependencies by running this command in the project's root directory:
pip install -r requirements_dev.txt -e .
Note
If you are using pyenv to manage your Python environment
(recommended), you may need to subsequently run pyenv rehash.
Before starting the app, you'll want to execute the database initialization script by running:
initialize_starter_db development.ini
This will set up the initial database structure, as well as create a few example users with the following email/password combinations:
[email protected]/user[email protected]/superuser[email protected]/admin
You can start the application with Pyramid's pserve command, specifying
the <environment>.ini configuration that you would like it to load.
In the root directory of the project, simply run:
pserve development.ini
You may also want to specify the --reload option to monitor for changes, or
the --daemon option to run in daemon (background) mode. Type pserve -h
for more information.
Pyramid's interactive shell can be run using the pshell command, and will
take advantage of IPython's enhancements if you have IPython installed:
pip install ipython pshell development.ini
The Starter project provides shortcut access to its models via the m object
within the interactive shell, e.g.:
>>> user = m.User.first() >>> user.email [email protected] >>> m.User.all() [<User: [email protected]>, <User: [email protected]>, <User: [email protected]>, <User: [email protected]>]
The application's test suite can be found in the tests directory. It is
broken into three parts:
| functional: | Functional tests use the WebTest package to test the application in its "fully-loaded" state. These tests run and check pieces of the application as if it were being accessed by a user with a web browser. |
|---|---|
| model: | Model tests relate to the application's model classes. |
| unit: | The unit test directory is meant for tests that don't necessarily fit
into the other two categories (e.g. for testing helpers or other small
"units" of code). |
You can run the tests by typing:
python setup.py test
This will run the full test suite in basic output mode. For more advanced testing, see the next section about nose.
nose is a package which extends Python's basic testing functionality in various ways. You can run nose by typing:
nosetests
With nose, you can also "focus" on individual tests by referencing them via
their "dotted Python name" with nose's --tests option.
For example, the following would only run the "test_index" test from the "TestRoot" functional test class:
nosetests --tests starter.tests.functional.test_root:TestRoot.test_index
Type nosetests -h for more options.
The application's documentation can be found in the docs directory. The
docs are written in reStructuredText and use Sphinx for documentation
generation.
First you'll need to initialize the git submodule containing the documentation's output theme by running:
git submodule init git submodule update
Then, cd into the docs directory and run:
make html
You should now be able to browse the full documentation by opening
./docs/_build/html/index.html in your web browser.