1.2.3 The Environment

Environments are described in the documentation for the web.environment module but are effectively groups of applications which share users and sessions. Specifically the name specified in environment parameter of the web.auth.driver() function is the name prepended to all database tables using that environment so that multiple environments can be used in the same database (useful if you are using a shared web host and only have access to one database). It is also the name used to identify the session ID in any cookies the web.session module uses.

In order to use the web.auth module the environment must be setup correctly. In the case of database drivers this simply means the relevant session tables must exist. If you intend to use the web.session module you can setup the environments for the web.auth and web.session modules at the same time using the web.environment module. If you just want to setup an auth environment you can so do through the Driver object.

Our Driver object from the previous section is named driver and we have already created a web.database cursor named cursor. Have a look at this example:

if not driver.completeAuthEnvironment():
    driver.removeAuthEnvironment(ignoreErrors=True)
    errors = driver.createAuthEnvironment()
    if errors:
        raise Exception('The environment was not sucessfully created')
connection.commit()

If none or only some of the tables are present we drop all the existing tables (ignoring errors produced because of missing tables) losing any information they contain and recreate all the tables.

Note: We need to check to see if any errors occured since they are not automatically raised.

We also need to commit our changes to the database so that they are saved using connection.commit().