Tutorial

This tutorial will explain the course to create a simple Hello world application with Anuket.

Introduction

Anuket is a python application based on the Pyramid web framework. Anuket is intended to provide features not bundled by Pyramid. The main features provided by Anuket are:

  • Twitter Bootstrap template
  • Form management
  • Flash messages
  • Database based users & groups
  • Database migrations
  • Admin tools backend

The main objective of Anuket, is to be used for relational database driven applications. For example, application with web forms, or wikis.

During this tutorial, we will create a very simple Hello world application. You can browse the code of this example application in our Git repository: https://github.com/lazaret/anuket-example

Install Anuket and the prerequistes

Anuket require the Python language (2.7 version), and a SQL database engine. In this tutorial we will use SQLite.

For this tutorial we will asume than they are already installed on your computer. If it’s not the case, please install them first.

Prepare the isolated environment

To avoid messing with your working Python environment during this tutorial, we will create first an an isolated environment:

$ easy_install virtualenv
$ virtualenv --no-site-packages tutorial
$ source tutorial/bin/activate

This have:

  • installed the virtualenv and pip packages
  • activated the tutorial isolated environment

When you will have finished the tutorial, you can get rid of everything we done by just deleting the /tutorial directory.

Install Anuket

You can simply install Anuket from PyPI by using pip, a Python packages installer witch have been installed with virtualenv :

(tutorial)$ pip install anuket

This will install Anuket and all the required Python packages (Pyramid, SQLAlchemy, Mako, alembic, etc.). You can display the list of all the installed packages with pip:

(tutorial)$ pip freeze

Note

As today, Anuket require the cracklib module with serve to test the security of the user password. If you have probelm during the install it’s probably because you need to install the cracklib developement libraries. (probably crackib-devel or libcrack2-dev depending on your OS)

Create the example application

Now we have a working environment with Anuket, Pyramid ans all the other prerequistes installed. It’s time now to create ou example application.

Create the application

We need first to create a Pyramid application with the starter scafold:

(tutorial)$ pcreate -t starter anuket-example

This create a minimalistic Pyramid application with all the default files. We will edit this file to create our example application. In a future release we will add ou own anuket scafold to start with.

Configure the application

We need now to edit three files to tell the application to use Anuket as a base:

  • setup.py
  • development.ini
  • anuketexample/__init__.py

If your are lazy you can download them directly from http://github.com/lazaret/anuket-example

First we need to tell to the setup.py file than anuket is a prerequiste for our application:

1
2
3
requires = [
    'anuket',
    ]

Secondly we have to edit the development.ini file to add the options required by Anyket:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
[app:main]
use = egg:anuket-example

pyramid.reload_templates = true
pyramid.debug_authorization = false
pyramid.debug_notfound = false
pyramid.debug_routematch = false
pyramid.default_locale_name = en
pyramid.available_languages = en fr
pyramid.includes =
    pyramid_debugtoolbar
    pyramid_tm

# mako template settings
mako.directories =
    anuket:templates
    anuketexample:templates
mako.module_directory = %(here)s/var/templates
mako.imports = from markupsafe import escape_silent
mako.default_filters = escape_silent

# pyramid_beaker settings
session.type = file
session.data_dir = %(here)s/var/sessions/data
session.lock_dir = %(here)s/var/sessions/lock
session.key = anuketkey
session.secret = anuketexamplesecret
session.timeout = 3600

# database connection string
sqlalchemy.url = sqlite:///%(here)s/anuket-example.db

anuket.backup_directory = %(here)s/var/backups
anuket.brand_name = Example

Most notabily we have setup this options:

  • The SQLAlchemy database type and name
  • The Mako template engine options
  • The Beaker session options
  • Anuket options

Finaly we need to tell imperatively to our application than we will use Anuket. For this will have to edit the __init__.py file inside the anuketexample directory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
from pyramid.config import Configurator
from pyramid_beaker import session_factory_from_settings

from sqlalchemy import engine_from_config

import anuket
from anuket.models import DBSession
from anuket.models.rootfactory import RootFactory
from anuket.security import get_auth_user


def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    # configure SQLAlchemy
    engine = engine_from_config(settings, 'sqlalchemy.')
    DBSession.configure(bind=engine)

    config = Configurator(settings=settings)
    # configure the root factory (used for Auth & Auth)
    root_factory = RootFactory
    config.set_root_factory(root_factory)
    # configure session
    session_factory = session_factory_from_settings(settings)
    config.set_session_factory(session_factory)
    # configure auth & auth
    config.include(anuket.add_authorization)
    # set an auth_user object
    config.set_request_property(get_auth_user, 'auth_user', reify=True)
    # configure subscribers
    config.include(anuket.subscribers)
    # configure static views
    config.include(anuket.add_static_views)
    # configure routes
    config.include(anuket.views.root)
    config.include(anuket.views.tools)
    config.include(anuket.views.user)
    from anuketexample import views
    config.include(views)
    # configure views
    config.scan('anuket')
    config.scan()

    config.add_translation_dirs('anuket:locale')
    config.set_locale_negotiator('anuket.lib.i18n.locale_negotiator')

    return config.make_wsgi_app()

In this file we have configured the database, the authentification, the session, the routes, the view and even the translation system. And as you can see, most of them comme from Anuket.

Initialize the application

We need now to initialize the database for our application. For this we will use the initialize_anuket_db script.

(tutorial)$ initialize_anuket_db development.ini

The script read the sqlalchemy.url option and our database model, then create the database, and finaly fill it with default values.

As we use SQLite the script have normaly created a anuket-example.db file witch is our database.

Serve the application

At this point we have now a working application than we can serve:

(tutorial)$ pserve develpment.ini

You can access to the application with a web browser at http://0.0.0.0:6543/

For now, the application only offer the base application from Anuket. You can already login to the aplication with the default admin credentials: admin/admin.

Add the hello_world views

Our starter application is ready. We now need to add features by extending the application. We will add a wonderfull Hello World feature. For this you have to edit the views.py file inside the anuketexample directory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
from pyramid.view import view_config


def includeme(config):
    """ Configure the Hello World routes."""
    config.add_route('hello', '/hello')
    config.add_route('hello_admin', '/hello/admin')


@view_config(route_name='hello', renderer='hello.mako')
def hello_world(request):
    """ Render the `Hello world` view."""
    hello = u"Hello World!"
    return dict(hello=hello)


@view_config(route_name='hello_admin', permission='admin',
             renderer='hello.mako')
def hello_admin(request):
    """ Render the `Hello admin` view."""
    hello = u"Hello Admin!"
    return dict(hello=hello)

This will create:

Add the hello.mako template

Our two views need a template to be rendered:

## -*- coding:utf-8 -*-
##
<%inherit file="anuket:templates/base.mako" />

<h2>${hello}</h2>


## Page title
<%def name="page_title()">
${_(u"Hello")}
</%def>

We use here a Mako template witch inherit from the default templates of Anuket. The template itsef just display the hello variable witch is returned by the views.

Connect to the views

Now the application can serve the Anuket views and our two new views:

(tutorial)$ pserve develpment.ini

You can for example connect with your browser to:

Adress View name Application
http://0.0.0.0:6543/ home anuket
http://0.0.0.0:6543/hello hello anuket-example
http://0.0.0.0:6543/login login anuket
http://0.0.0.0:6543/hello/admin hello_admin anuket-example

Note than the hello_admin require an user with admin permission. If you try to access to it without login first the application will redirect you to the login view.