Upgrade guide

The 0.8 release of django-registration represents a complete rewrite of the previous codebase, and introduces several new features which greatly enhance the customizability and extensibility of django-registration. Whenever possible, changes were made in ways which preserve backwards compatibility with previous releases, but some changes to existing installations will still be required in order to upgrade to 0.8. This document provides a summary of those changes, and of the new features available in the 0.8 release.

Django version requirement

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

Backwards-incompatible changes

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), most things will continue to work as normal (although you will need to create one new template; see the section on views below). However, the old default URLconf has been deprecated and will be removed in version 1.0 of django-registration, so it is recommended that you begin migrating now. To do so, change any use of registration.urls to registration.backends.default.urls. For example, if you had the following in your root URLconf:

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

you should change it to:

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

The older include will continue to work until django-registration 1.0; in 0.8 it raises a PendingDeprecationWarning (which is ignored by default in Python), in 0.9 it will raise DeprecationWarning (which will begin printing warning messages on import) and in 1.0 it will be removed entirely.

Changes to registration views

The views used to handle user registration have changed significantly as of django-registration 0.8. Both views now require the keyword argument backend, which specifies the registration backend to use, and so any URL pattern for these views must supply that argument. The URLconf provided with the default backend properly passes this argument.

The profile_callback argument of the register() view has been removed; the functionality it provided can now be implemented easily via a custom backend, or by connecting listeners to the signals sent during the registration process.

The activate() view now issues a redirect upon successful activation; in the default backend this is to the URL pattern named registration_activation_complete; in the default setup, this will redirect to a view which renders the template registration/activation_complete.html, and so this template should be present when using the default backend and default configuration. Other backends can specify the location to redirect to through their post_activation_redirect() method, and this can be overridden on a case-by-case basis by passing the (new) keyword argument success_url to the activate() view. On unsuccessful activation, the activate() view still displays the same template, but its context has changed: the context will simply consist of any keyword arguments captured in the URL and passed to the view.

Changes to registration forms

Previously, the form used to collect data during registration was expected to implement a save() method which would create the new user account. This is no longer the case; creating the account is handled by the backend, and so any custom logic should be moved into a custom backend, or by connecting listeners to the signals sent during the registration process.

Changes to the RegistrationProfile model

The create_inactive_user() method of RegistrationManager now has an additional required argument: site. This allows django-registration to easily be used regardless of whether django.contrib.sites is installed, since a RequestSite object can be passed in place of a regular Site object.

The user_registered signal is no longer sent by create_inactive_user(), and the user_activated signal is no longer sent by activate_user(); these signals are now sent by the backend after these methods have been called. Note that these signals were added after the django-registration 0.7 release but before the refactoring which introduced the backend API, so only installations which were tracking the in-development codebase will have made use of them.

The sending of activation emails has been factored out of create_inactive_user(), and now exists as the method send_activation_email() on instances of RegistrationProfile.