Quick Start

We have two varieties of “quick start” instructions:

From Generated Code

Note that this section describes an app based on WuttaWeb (i.e. not just WuttJamaican). We’ll name it “Poser” for sake of example.

Make a parent folder for all source code:

mkdir -p ~/src

Make and activate a new virtual environment for your project:

cd /path/to/envs
python3 -m venv poser
source poser/bin/activate

Make a new e.g. poser database in PostgreSQL (or MySQL). Nothing special here but for instructions see Create the Database.

Install and run cookiecutter with wuttaweb template:

pip install cookiecutter
cookiecutter -o ~/src git+https://forgejo.wuttaproject.org/wutta/cookiecutter-wuttaweb

Assuming you now have project code at ~/src/poser then install that and run the app installer. Note the 2nd command name will depend on your project:

pip install -e ~/src/poser
poser install

If all goes well, you can run the web app with:

cd /path/to/envs/poser
bin/pserve --reload file+ini:app/web.conf

And browse it at http://localhost:9080

From Scratch

This shows the minimum use case, basically how to make/use the config object and app handler.

(See next section for Database Setup.)

You should have already made a virtual environment. Install the package with:

pip install WuttJamaican[db]

Create a config file, e.g. my.conf:

[foo]
bar = A
baz = 2
feature = true
words = the quick brown fox

In code, load the config and reference its values as needed, and/or invoke other app/handler logic:

from wuttjamaican.conf import make_config

config = make_config('/path/to/my.conf')

# this call..                        ..returns this value

config.get('foo.bar')                # 'A'

config.get('foo.baz')                # '2'
config.get_int('foo.baz')            # 2

config.get('foo.feature')            # 'true'
config.get_bool('foo.feature')       # True

config.get('foo.words')              # 'the quick brown fox'
config.get_list('foo.words')         # ['the', 'quick', 'brown', 'fox']

# now for the app handler..and interacting with DB
app = config.get_app()
model = app.model
session = app.make_session()

# invoke secondary handler to make new user account
auth = app.get_auth_handler()
user = auth.make_user(session=session, username='barney')

# commit changes to DB
session.add(user)
session.commit()

For more info see:

Database Setup

You should already have the package installed (see previous section).

Next you must create the database, as well as any user account needed, within the DB backend. This is pretty routine but for instructions see Create the Database.

Now add the DB info to your config file (e.g. my.conf as shown above). Contents for this will look something like (using poserdb as the DB name):

[wutta.db]

# postgres
default.url = postgresql://USERNAME:PASSWORD@localhost/poserdb

# mysql
default.url = mysql+mysqlconnector://USERNAME:PASSWORD@localhost/poserdb

You also must add some Alembic config, needed for DB schema migrations:

[alembic]
script_location = wuttjamaican.db:alembic
version_locations = wuttjamaican.db:alembic/versions

With config file updated you can run the Alembic command to migrate schema:

alembic -c /path/to/my.conf upgrade heads

Now you should have all the tables required for a WuttJamaican app database.

If you wish to store config settings in the DB, don’t forget to add to your config file (see also Where Values Come From):

[wutta.config]
usedb = true
preferdb = true