Form classes

Several form classes are provided with django-registration, covering common cases for gathering account information and implementing common constraints for user registration. These forms were designed with django-registration’s built-in registration workflows in mind, but may also be useful in other situations.

class django_registration.forms.RegistrationForm(*args, **kwargs)[source]

A form for registering a new user account.

This is the default form class used by all included views in django-registration, and is designed to be able to work with a wide variety of user models.

If you’re using Django’s default User model, this form will work automatically. If you’re using a custom user model, this form can work with it so long as your user model meets certain requirements.

This form is a ModelForm which will derive fields and basic validation from your user model’s field definitions, though it will also perform additional validation steps on certain fields. As a ModelForm, calling save() will create an instance of the user model from the validated data, save it to the database, and return it.

In general you should use this form as-is, and only subclass it if you want to remove one or more of the additional validators applied here (if you want to supply extra validators, you can do so via subclassing, but you can also declare them on your user model and have them automatically picked up by this form).

If you do find yourself needing to remove validators from this form, it may be better to instead write and use a subclass of BaseRegistrationForm, which is a more minimal base class that does not implement any of the field or validation handling of this form.

Using a custom user model

Custom user models are supported, but you will need to ensure a few attributes are set on your custom user model to allow this form to work with it:

  • EMAIL_FIELD: a str specifying the name of the field containing the user’s email address.

  • USERNAME_FIELD: a str specifying the name of the field containing the user’s “username”. If you use the email address as the primary “username”/identifier, set this to the same field name as EMAIL_FIELD.

  • REQUIRED_FIELDS: a list of names of fields on your user model which must be included in the form.

Django’s AbstractUser, which is what many custom user models will inherit from and also what the default Django user model inherits from, sets all three of these, and generally for a custom model you would only need to override REQUIRED_FIELDS in order to specify any additional custom fields of your model which should be included in the form.

However, if you have a custom user model which inherits from Django’s AbstractBaseUser (which is an even more minimal base class than AbstractUser), or which does not inherit from any of Django’s abstract base user classes, you will need to set all three of the above attributes on your custom user model for it to be usable with this form.

Additionally, if you use a registration workflow which sends an email to the newly-registered user, your user model must implement the email_user() method, with the same API as Django’s implementation. If your user model inherits from AbstractUser, this method is implemented for you automatically.

Fields defined on this form

Django’s AbstractBaseUser does not include its username field in REQUIRED_FIELDS. To work around that, this form will include all fields listed in your user model’s REQUIRED_FIELDS and will also include the field named in your user model’s USERNAME_FIELD if it is not included in REQUIRED_FIELDS.

If your user model’s email address field is also its username field, set both EMAIL_FIELD and USERNAME_FIELD to that field’s name, as noted above; the field will be included in the form only once.

This form will also include two password fields, with field names password1 and password2, which will be used to set the user account’s password. Two fields are used in order to implement the common UI pattern of requiring the user to enter the password twice and check that both entries match.

Validation on this form

In addition to any validation requirements or validators defined on your user model and its fields, this form will apply the following validation checks:

  • The values entered into the password1 and password2 fields match. If they do not match, the validation error will be attached to the password2 field.

  • The value entered into the password fields passes all password validators configured in your Django settings. If the password fails validation, the error will be attached to the password2 field.

  • The value entered into the username field is not a case-insensitive match for any existing username value.

  • The value entered into the username field is not a reserved name. To override the default set of reserved names, subclass this form and set the attribute reserved_names to the list of names you wish to reserve.

  • The value entered into the username field is not a “confusable” value (see the documentation on preventing homograph attacks for an explanation).

  • The field named in your user model’s EMAIL_FIELD attribute will have required=True (Django’s default AbstractBaseUser sets blank=True on the email field, making it optional in any form which does not override this).

  • The value entered into the email address field conforms to the HTML5 email validation rule. Note that this validation rule is automatically enforced client-side by HTML5-compliant browsers as part of the implementation of input type="email", but is also significantly stricter than what the email RFCs allow in an address. Many unusual syntactic constructs which are permitted by the email RFCs are disallowed by HTML5’s email validation and will be rejected by django-registration.

  • The value entered into the email address field does not contain a “confusable” value in its local-part or in its domain, though the combination of the local-part and domain together is allowed to be “confusable”.

clean()[source]

Django form hook implementing form-wide validation logic, including logic that must check multiple fields simultaneously. Here, this hook is used to check the two password fields to ensure they match.

save(commit=True)[source]

Django ModelForm hook for creating and returning the new user model instance. If commit=True, the instance will be saved to the database; if commit=False, the instance will not be saved before being returned.

class django_registration.forms.RegistrationFormTermsOfService(*args, **kwargs)[source]

A subclass of RegistrationForm which adds one extra required field: a checkbox named tos indicating agreement to a site’s terms of service.

class django_registration.forms.RegistrationFormUniqueEmail(*args, **kwargs)[source]

A subclass of RegistrationForm which enforces uniqueness of email addresses.

class django_registration.forms.BaseRegistrationForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, instance=None, use_required_attribute=None, renderer=None)[source]

Minimal user registration form class.

In most cases, this form should not be used directly, and RegistrationForm should be used instead as the base class of user-registration forms. The primary difference between this class and RegistrationForm is that RegistrationForm makes some additional assumptions about which fields to include and includes significant custom validation logic, while this form attempts to be as minimal as possible with respect to included fields.

In general, you should be using RegistrationForm unless you are absolutely certain that you need to build your own custom registration form without using RegistrationForm’s additional validation or fields.

Using a custom user model

Custom user models are supported, but you will need to ensure a few attributes are set on your custom user model to allow this form to work with it:

  • EMAIL_FIELD: a str specifying the name of the field containing the user’s email address.

  • USERNAME_FIELD: a str specifying the name of the field containing the user’s “username”. If you use the email address as the primary “username”/identifier, set this to the same field name as EMAIL_FIELD.

  • REQUIRED_FIELDS: a list of names of fields on your user model which must be included in the form.

Django’s AbstractUser, which is what many custom user models will inherit from and also what the default Django user model inherits from, sets all three of these, and generally for a custom model you would only need to override REQUIRED_FIELDS in order to specify any additional custom fields of your model which should be included in the form.

However, if you have a custom user model which inherits from Django’s AbstractBaseUser (which is an even more minimal base class than AbstractUser), or which does not inherit from any of Django’s abstract base user classes, you will need to set all three of the above attributes on your custom user model for it to be usable with this form.

Additionally, if you use a registration workflow which sends an email to the newly-registered user, your user model must implement the email_user() method, with the same API as Django’s implementation. If your user model inherits from AbstractUser, this method is implemented for you automatically.

Fields defined on this form

The set of fields on this form will be all and only the fields listed in your user model’s REQUIRED_FIELDS attribute. If you are using the default Django user model, or a subclass of AbstractUser without overriding REQUIRED_FIELDS, this will not include the username field. It also will not include any fields or logic related to setting/validating a password. It is assumed, if you are using this minimal base class, that you will either find this acceptable or be providing your own custom logic in a subclass to handle your particular needs.