1.2.1.1 Function Reference

1.2.1.1 Function Reference

The web.auth.start() function has the following parameters:

start( session[, storage='database'][, cursor=None][, expire=0][, idle=0][, signInForm=None][, autoSignIn=False][, autoRedirect=False][, redirect=None][, includeQuery=False][, stickyData=][, reminderForm=None][, email=None][, app=None][, accessDenied=None][, emailMessage=None][, htmlPage=None][, encryption=None][, table='Auth'][, dir=None][, debug=False][, checkSignInAttempt=False])

Warning: Because more options may be specified in future versions of this function you should not rely on the order of these parameters. Instead they should be specified with the parameter name and an = sign as is used in the examples in this documentation.

session

A valid web.session object

storage

The storage driver to use for the auth user, level and app information. storage can be 'database' or 'file'.

If storage is 'database' you must also specify cursor to be a valid web.database cursor. By default the necessary database tables beign with 'Auth'. If you want them to begin with something else, perhaps if you want two lots of auth storage in the same database, you can specify the table prepend string using table. For example table='Auth2' would create the tables Auth2Level, Auth2User and Auth2App.

If storage is 'file' you must also specify a directory dir which allows read and write access where the auth information is stored.

expire

An integer specifying the number of seconds before the user is signed out. A value of 0 disables the expire functionality and the user will be signed in until they sign out. Note: If the underlying session expires, the cookie is removed or the sign in idles before the expire time specified in expire the user will be signed out.

idle

An integer specifying the maximum number of seconds between requests before the user is automatically signed out. A value of 0 disables the idle functionality allowing an unlimited amount of time between user requests. Note: If the underlying session expires, the cookie is removed or the sign in expires before the idle time specified in idle the user will be signed out.

app

The name of the application.

encryption

Can be None to disable encryption of the stored passwords or 'md5' to generate md5 checksums of the passwords.

autoSignIn

If True will automatically display a signInForm if the user is not signed in. Note: If this is set to False you will need to implement your own sign in form system or no information will be displayed and the browser will show an empty page or think you are trying to download a file.

signInForm

A tuple or list of the form [templateType, templateString] where templateType can be any template type supported by web.template, for example 'python', 'cheetah' etc. templateString should be a string containing the template text for the sign in form. The template should contain the keys name for the form name, action for the form action, method for the form method, stickyData for hidden fields specified in stickyData, username which is the current username, message for the error message and error for the error code which will be displayed in comments if debug is True. If not specified the template web.auth.template.signForm is used. The sign in form must have a hidden field named signIn with a value True for the module to work.

reminderInForm

A tuple or list of the form [templateType, templateString] where templateType can be any template type supported by web.template, for example 'python', 'cheetah' etc. templateString should be a string containing the template text for the password email reminder form. The template should contain the keys name for the form name, action for the form action, method for the form method and stickyData for hidden fields specified in stickyData. If not specified the template web.auth.template.reminderForm is used.

htmlPage

A tuple or list of the form [templateType, templateString] where templateType can be any template type supported by web.template, for example 'python', 'cheetah' etc. templateString should be a string containing html page. The template should contain the keys title for the page title and content for the position where the sign in form should be displayed. If not specified the template web.auth.template.htmlPage is used.

errorCodes

A dictionary of error keys and the message to be displayed when those errors occur. The default is web.auth.templates.errorCodes:

errorCodes = {     
    'LOGIN'             : ['Please Sign In',''],
    'REMINDER'          : ['Enter Email Address',''],
    'EXPIRED'           : ['Please Sign In','The session expired and you have been signed out.'],
    'IDLED'             : ['Please Sign In','The session has been left idle for too long and you have been signed out.'],
    'NO_USER'           : ['Please Sign In','The username specified in your session does not exist. Try signing in again.'],
    'NO_SESSION'        : ['Please Sign In','There is no session information for the username you are using. This may be because you have been signed out.'],
    'WRONG_USERNAME'    : ['Please Sign In','The username you have specified does not exist.'],
    'WRONG_PASSWORD'    : ['Please Sign In','The password is incorrect.'],
    'NO_USER_ENTERED'   : ['Please Sign In','Please enter a username.'],
    'PASS_REMINDER_SENT': ['Reminder Sent','A password reminder has been sent. Please check your email.'],
    'ACCESS_DENIED'     : ['Please Sign In','You do not have access rights to use this application.'],
    'EMAIL_NOT_FOUND'   : ['Enter Email Address','Email address not found. Please enter the email address your account was registered with.'],
    'NO_PASSWORD'       : ['Please Sign In','No password entered.'],
    'NO_AUTO_SIGN_IN'   : ['Please Sign In','The user is not signed in and autoSignIn mode is not enabled.'], 
}

email

If specified, enables the user to be emailed a password if they forget theirs.

email should be a dictionary with the keys: 'system' which should be a string containing the name of the website, 'sender' which is the name of the person the email should come from, 'reply' which is the email address of the sender, 'method' can be 'sendmail' or 'smtp' depending on how you want the mail delivered, 'sendmail' is the path to sendmail and is only needed if 'method' is 'sendmail', 'smtp' is the SMTP server to use and is only needed if 'method' is 'smtp', 'template' is the template for the email message and 'type' is the type of the template.

For example:

email = {
    'system':'Python Web Login System',
    'sender':'System Administrator',
    'reply':'sysadmin@example.com',
    'method':'sendmail',
    'sendmail':'/usr/bin/sendmail',
    'smtp':'smtp.ntlworld.com',
    'type':'python',
    'template':"""
Dear %(firstname)s,
                    
Your password for the %(system)s is shown below.
                    
%(password)s
                    
You should be able to use this password to sign in.

Best wishes,

%(sender)s
"""
}

autoRedirect

If specified as True will automatically redirect the user to the page they tried to visit before they signed in. If redirect and includeQuery are not specified the browser will redirect to the page for the sign in script without any query arguments.

Note: Doesn't work with the test webserver distributed with the web modules.

redirect

Only used if autoRedirect is True. If specified, redirect is the URL to redirect to.

includeQuery

Only used if autoRedirect is True. If includeQuery is True the browser will redirect to the URL which was visited.

stickyData

A dictionary of key, value pairs to be stored as hidden fields in the sign in and reminder forms.

debug

If debug is True then the error code will be displayed in HTML comments in the source of each screen from the auth system.

checkSignInAttempt

If checkSignInAttempt is True the code will check to see if a user is attempting to sign in before checking to see if a valid user is already signed in. This means that a user can sign in with a different username without first having to sign out. If checkSignInAttempt is False the module would not notice a user was signing in and would display the page ignoring the sign in attempt.

The module makes the check by looking for the cgi key username. This means that you can't use username as a cgi key if checkSignInAttempt is True as the module will think a user is attempting to sign in.

htmlPageRegions

Specifies what the page regions in the template specified by htmlPage are called so that your template doesn't have to have editable regions named content and title.

htmlPageRegions = {'content':'customContentRegion','title':'customTitleRegion'}

The Auth object returned by the start() function has the following methods and attributes:

class AuthDatabase, AuthFile( )

check( ): Checks to see if the current user is signed in. Returns True if they are. Does not provide any sign in functionality.

valid( ): Checks to see if the current user is signed in. Returns True if they are. If the user is not signed in and autoSignIn is True, this function prints a sign in page and will handle subsequent sign in attempts automatically.

signOut( ): Signs out the current user.

signInForm( [error=''][,username=''][,stickyData={}]): Return a string for a sign in form specifying the error error, the username username and creating hidden fields for the key:value pairs in stickyData.

reminderForm( [error=''][,stickyData={}]): Return a string for a reminder form specifying the error error, the username username and creating hidden fields for the key:value pairs in stickyData.

firstname: The firstname of the user or None if there is no user.

surname: The surname of the user or None if there is no user.

username: The username of the user or None if there is no user.

password: The user's password or None if there is no user. If encryption is being used, this is the encrypted password.

email: The email address of the user or None if there is no user.

app: The name of the application using this session object

accessLevel: The access level of this user for this application or None if there is no user.

level: A dictionary where the keys are the application names and the values are the access levels of this user for the particular application. For example user.level[user.app] is the same as user.accessLevel

expire: The expire length in seconds

idle: The idle length in seconds

signedIn: True if a user is signed in, False otherwise.

error: The current error code

See About this document... for information on suggesting changes.