wuttjamaican/docs/narr/install/quickstart.rst

Quick Start
===========

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

(See next section for :ref:`db-setup`.)

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

.. code-block:: sh

   pip install wuttjamaican

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

.. code-block:: ini

   [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:

* :func:`~wuttjamaican.conf.make_config()`
* :class:`~wuttjamaican.conf.WuttaConfig` and especially
  :meth:`~wuttjamaican.conf.WuttaConfig.get()`


.. _db-setup:

Database Setup
==============

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

You also must install some package(s) for the particular database
backend you wish to use.  PostgreSQL is recommended although MySQL
etc. should also work.  For instance:

.. code-block:: sh

   # postgres
   pip install psycopg2

   # mysql
   pip install mysql-connector-python

Next you must create the database, as well as any user account needed,
within the DB backend.

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

.. code-block:: ini

   [wutta.db]

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

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

See :doc:`/narr/db/app` for more about that.

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

.. code-block:: ini

   [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:

.. code-block:: sh

   cd /path/to/env
   bin/alembic -c /path/to/my.conf upgrade heads

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