django-registration 1.0 documentation¶

Installing django-registration¶

There are several ways to install django-registration:

• Automatically, via a package manager.
• Manually, by downloading a copy of the release package and installing it yourself.
• Manually, by performing a Mercurial checkout of the latest code.

It is also highly recommended that you learn to use virtualenv for development and deployment of Python software; virtualenv provides isolated Python environments into which collections of software (e.g., a copy of Django, and the necessary settings and applications for deploying a site) can be installed, without conflicting with other installed software. This makes installation, testing, management and deployment far simpler than traditional site-wide installation of Python packages.

pip install django-registration

python setup.py install

hg clone http://bitbucket.org/ubernostrum/django-registration/

hg clone -r v|version| http://bitbucket.org/ubernostrum/django-registration/

Basic configuration and use¶

Once installed, you can add django-registration to any Django-based project you’re developing. The default setup will enable user registration with the following workflow:

1. A user signs up for an account by supplying a username, email address and password.
2. From this information, a new User object is created, with its is_active field set to False. Additionally, an activation key is generated and stored, and an email is sent to the user containing a link to click to activate the account.
3. Upon clicking the activation link, the new account is made active (the is_active field is set to True); after this, the user can log in.

Note that the default workflow requires django.contrib.auth to be installed, and it is recommended that django.contrib.sites be installed as well. You will also need to have a working mail server (for sending activation emails), and provide Django with the necessary settings to make use of this mail server (consult Django’s email-sending documentation for details).

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.sites',
    'registration',
    # ...other installed applications...
)

ACCOUNT_ACTIVATION_DAYS = 7 # One-week activation window; you may, of course, use a different value.

(r'^accounts/', include('registration.backends.default.urls')),

The backend system¶

The largest overall change is that in place of the monolithic backend classes and function-based views found in django-registration 0.8, in 1.0 all views are class-based. A “backend” now consists of, typically, one or two subclasses of the built-in base views.

Implementing these as class-based views allows for far simpler configuration and customization, without the overhead involved in supporting large numbers of optional keyword arguments to function-based views, or the need to provide a separate class-based infrastructure for implementing the logic of registration.

Notably, this implementation is also completely backwards-compatible for users of django-registration 0.8 who simply used the recommended default URLConf for one of the supplied backends; those URLConfs exist in the same locations, and have been rewritten to point to the appropriate class-based views with the appropriate options.

Django version requirement¶

As of 1.0, django-registration requires Django 1.4 or newer; older Django releases may work, but are officially unsupported.

Backwards-incompatible changes¶

The entire codebase was rewritten for 1.0, switching from function-based views accepting keyword arguments to class-based views with overridable attributes. Whether this affects you will depend on how you were using django-registration previously:

• If you’re upgrading from an older release of django-registration, and if you were using the default setup (i.e., the included default URLconf and no custom URL patterns or custom arguments to views), you do not need to make any changes.
• If you had customized django-registration by writing your own backend, you will now need to implement that backend by subclassing the built-in views and overriding or implementing your customizations appropriately. Much of this is similar to previous backend class implementations, so minimal changes to existing code should be required; the primary change is that the backend classes now are the views, so if you had multiple views (e.g., one for signup and one for activation) your backend will now consist of multiple classes – one class per view – rather than one class total.

Default behavior and configuration¶

To make use of this backend, simply include the URLConf registration.backends.default.urls at whatever location you choose in your URL hierarchy.

This backend makes use of the following settings:

ACCOUNT_ACTIVATION_DAYS

This is the number of days users will have to activate their accounts after registering. Failing to activate during that period will leave the account inactive (and possibly subject to deletion). This setting is required, and must be an integer.

REGISTRATION_OPEN

A boolean (either True or False) indicating whether registration of new accounts is currently permitted. This setting is optional, and a default of True will be assumed if it is not supplied.

By default, this backend uses registration.forms.RegistrationForm as its form class for user registration; this can be overridden by passing the keyword argument form_class to the register() view.

Two views are provided: registration.backends.default.views.RegistrationView and registration.backends.default.views.ActivationView. These views subclass django-registration’s base RegistrationView and ActivationView, respectively, and implement the two-step registration/activation process.

Upon successful registration – not activation – the default redirect is to the URL pattern named registration_complete; this can be overridden in subclasses by changing success_url or implementing get_success_url()

Upon successful activation, the default redirect is to the URL pattern named registration_activation_complete; this can be overridden in subclasses by implementing get_success_url().

How account data is stored for activation¶

During registration, a new instance of django.contrib.auth.models.User is created to represent the new account, with the is_active field set to False. An email is then sent to the email address of the account, containing a link the user must click to activate the account; at that point the is_active field is set to True, and the user may log in normally.

Activation is handled by generating and storing an activation key in the database, using the following model:

class registration.models.RegistrationProfile¶

A simple representation of the information needed to activate a new user account. This is not a user profile; it simply provides a place to temporarily store the activation key and determine whether a given account has been activated.

Has the following fields:

user¶

A ForeignKey to django.contrib.auth.models.User, representing the user account for which activation information is being stored.

activation_key¶

A 40-character CharField, storing the activation key for the account. Initially, the activation key is the hexdigest of a SHA1 hash; after activation, this is reset to ACTIVATED.

Additionally, one class attribute exists:

ACTIVATED¶

A constant string used as the value of activation_key for accounts which have been activated.

And the following methods:

activation_key_expired()¶

Determines whether this account’s activation key has expired, and returns a boolean (True if expired, False otherwise). Uses the following algorithm:

1. If activation_key is ACTIVATED, the account has already been activated and so the key is considered to have expired.
2. Otherwise, the date of registration (obtained from the date_joined field of user) is compared to the current date; if the span between them is greater than the value of the setting ACCOUNT_ACTIVATION_DAYS, the key is considered to have expired.

Return type:	bool

send_activation_email(site)¶

Sends an activation email to the address of the account.

The activation email will make use of two templates: registration/activation_email_subject.txt and registration/activation_email.txt, which are used for the subject of the email and the body of the email, respectively. Each will receive the following context:

activation_key

The value of activation_key.

expiration_days

The number of days the user has to activate, taken from the setting ACCOUNT_ACTIVATION_DAYS.

site

An object representing the site on which the account was registered; depending on whether django.contrib.sites is installed, this may be an instance of either django.contrib.sites.models.Site (if the sites application is installed) or django.contrib.sites.models.RequestSite (if not). Consult the documentation for the Django sites framework for details regarding these objects’ interfaces.

Because email subjects must be a single line of text, the rendered output of registration/activation_email_subject.txt will be forcibly condensed to a single line.

Parameters:	site (django.contrib.sites.models.Site or django.contrib.sites.models.RequestSite) – An object representing the site on which account was registered.
Return type:	None

Additionally, RegistrationProfile has a custom manager (accessed as RegistrationProfile.objects):

class registration.models.RegistrationManager¶

This manager provides several convenience methods for creating and working with instances of RegistrationProfile:

activate_user(activation_key)¶

Validates activation_key and, if valid, activates the associated account by setting its is_active field to True. To prevent re-activation of accounts, the activation_key of the RegistrationProfile for the account will be set to RegistrationProfile.ACTIVATED after successful activation.

Returns the User instance representing the account if activation is successful, False otherwise.

Parameters:	activation_key (string, a 40-character SHA1 hexdigest) – The activation key to use for the activation.
Return type:	User or bool

delete_expired_users()¶

Removes expired instances of RegistrationProfile, and their associated user accounts, from the database. This is useful as a periodic maintenance task to clean out accounts which registered but never activated.

Accounts to be deleted are identified by searching for instances of RegistrationProfile with expired activation keys and with associated user accounts which are inactive (have their is_active field set to False). To disable a user account without having it deleted, simply delete its associated RegistrationProfile; any User which does not have an associated RegistrationProfile will not be deleted.

A custom management command is provided which will execute this method, suitable for use in cron jobs or other scheduled maintenance tasks: manage.py cleanupregistration.

Return type:	None

create_inactive_user(username, email, password, site[, send_email])¶

Creates a new, inactive user account and an associated instance of RegistrationProfile, sends the activation email and returns the new User object representing the account.

Parameters:

username (string) – The username to use for the new account. email (string) – The email address to use for the new account. password (string) – The password to use for the new account. site (django.contrib.sites.models.Site or django.contrib.sites.models.RequestSite) – An object representing the site on which the account is being registered. send_email (bool) – If True, the activation email will be sent to the account (by calling RegistrationProfile.send_activation_email()). If False, no email will be sent (but the account will still be inactive)

Return type:

User

create_profile(user)¶

Creates and returns a RegistrationProfile instance for the account represented by user.

The RegistrationProfile created by this method will have its activation_key set to a SHA1 hash generated from a combination of the account’s username and a random salt.

Parameters:	user (User) – The user account; an instance of django.contrib.auth.models.User.
Return type:	RegistrationProfile

Configuration¶

To use this backend, simply include the URLconf registration.backends.simple.urls somewhere in your site’s own URL configuration. For example:

(r'^accounts/', include('registration.backends.simple.urls')),

No additional settings are required, but one optional setting is supported:

REGISTRATION_OPEN

A boolean (either True or False) indicating whether registration of new accounts is currently permitted. A default of True will be assumed if this setting is not supplied.

Upon successful registration, the default redirect is to the URL specified by the get_absolute_url() method of the newly-created User object; by default, this will be /users/<username>/, although it can be overridden by implementing get_success_url() on a subclass of registration.backends.simple.views.RegistrationView.

The default form class used for account registration will be registration.forms.RegistrationForm, although this can be overridden by supplying a custom URL pattern for the registration view and passing the keyword argument form_class, or by subclassing registration.backends.simple.views.RegistrationView and either overriding form_class or implementing get_form_class().

General¶

What license is django-registration under?

django-registration is offered under a three-clause BSD-style license; this is an OSI-approved open-source license, and allows you a large degree of freedom in modifiying and redistributing the code. For the full terms, see the file LICENSE which came with your copy of django-registration; if you did not receive a copy of this file, you can view it online at <http://bitbucket.org/ubernostrum/django-registration/src/tip/LICENSE>.

Why are the forms and models for the default backend not in the default backend?

The model and manager used by the default backend are in registration.models, and the default form class (and various subclasses) are in registration.forms; logically, they might be expected to exist in registration.backends.default, but there are several reasons why that’s not such a good idea:

1. Older versions of django-registration made use of the model and form classes, and moving them would create an unnecessary backwards incompatibility: import statements would need to be changed, and some database updates would be needed to reflect the new location of the RegistrationProfile model.
2. Due to the design of Django’s ORM, the RegistrationProfile model would end up with an app_label of default, which isn’t particularly descriptive and may conflict with other applications. By keeping it in registration.models, it retains an app_label of registration, which more accurately reflects what it does and is less likely to cause problems.
3. Although the RegistrationProfile model and the various form classes are used by the default backend, they can and are meant to be reused as needed by other backends. Any backend which uses an activation step should feel free to reuse the RegistrationProfile model, for example, and the registration form classes are in no way tied to a specific backend (and cover a number of common use cases which will crop up regardless of the specific backend logic in use).

Installation and setup¶

How do I install django-registration?

Full instructions are available in the quick start guide.

Do I need to put a copy of django-registration in every project I use it in?

No; putting applications in your project directory is a very bad habit, and you should stop doing it. If you followed the instructions mentioned above, django-registration was installed into a location that’s on your Python import path, so you’ll only ever need to add registration to your INSTALLED_APPS setting (in any project, or in any number of projects), and it will work.

Does django-registration come with any sample templates I can use right away?

No, for two reasons:

1. Providing default templates with an application is generally hard to impossible, because different sites can have such wildly different design and template structure. Any attempt to provide templates which would work with all the possibilities would probably end up working with none of them.
2. A number of things in django-registration depend on the specific registration backend you use, including the variables which end up in template contexts. Since django-registration has no way of knowing in advance what backend you’re going to be using, it also has no way of knowing what your templates will need to look like.

Fortunately, however, django-registration has good documentation which explains what context variables will be available to templates, and so it should be easy for anyone who knows Django’s template system to create templates which integrate with their own site.

Configuration¶

Do I need to rewrite the views to change the way they behave?

Not always. Any behavior controlled by an attribute on a class-based view can be changed by passing a different value for that attribute in the URLConf. See Django’s class-based view documentation for examples of this.

For more complex or fine-grained control, you will likely want to subclass RegistrationView or ActivationView, or both, add your custom logic to your subclasses, and then create a URLConf which makes use of your subclasses.

I don’t want to write my own URLconf because I don’t want to write patterns for all the auth views!

You’re in luck, then; django-registration provides a URLconf which only contains the patterns for the auth views, and which you can include in your own URLconf anywhere you’d like; it lives at registration.auth_urls.

I don’t like the names you’ve given to the URL patterns!

In that case, you should feel free to set up your own URLconf which uses the names you want.

I’m using Django 1.5 and a custom user model; how do I make that work?

Although the two built-in backends supplied with django-registration both assume Django’s default User model, the base view classes are deliberately user-model-agnostic. Simply subclass them, and implement logic for your custom user model.

Troubleshooting¶

I’ve got functions listening for the registration/activation signals, but they’re not getting called!

The most common cause of this is placing django-registration in a sub-directory that’s on your Python import path, rather than installing it directly onto the import path as normal. Importing from django-registration in that case can cause various issues, including incorrectly connecting signal handlers. For example, if you were to place django-registration inside a directory named django_apps, and refer to it in that manner, you would end up with a situation where your code does this:

from django_apps.registration.signals import user_registered

But django-registration will be doing:

from registration.signals import user_registered

From Python’s point of view, these import statements refer to two different objects in two different modules, and so signal handlers connected to the signal from the first import will not be called when the signal is sent using the second import.

To avoid this problem, follow the standard practice of installing django-registration directly on your import path and always referring to it by its own module name: registration (and in general, it is always a good idea to follow normal Python practices for installing and using Django applications).

Tips and tricks¶

How do I log a user in immediately after registration or activation?

Take a look at the implementation of the simple backend, which logs a user in immediately after registration.

How do I re-send an activation email?

Assuming you’re using the default backend, a custom admin action is provided for this; in the admin for the RegistrationProfile model, simply click the checkbox for the user(s) you’d like to re-send the email for, then select the “Re-send activation emails” action.

How do I manually activate a user?

In the default backend, a custom admin action is provided for this. In the admin for the RegistrationProfile model, click the checkbox for the user(s) you’d like to activate, then select the “Activate users” action.