django-registration / docs / models.txt

Full commit
Models and managers

Because the two-step process of registration and activation requires
some means of temporarily storing activation key and retrieving it for
verification, a simple model --
``registration.models.RegistrationProfile`` -- is provided in this
application, and a custom manager --
``registration.models.RegistrationManager`` -- is included and defines
several useful methods for interacting with ``RegistrationProfile``.

Both the ``RegistrationProfile`` model and the ``RegistrationManager``
are found in ``registration.models``.

The ``RegistrationProfile`` model

A simple profile which stores an activation key for use during user
account registration.

Generally, you will not want to interact directly with instances of
this model; the provided manager includes methods for creating and
activating new accounts, as well as for cleaning out accounts which
have never been activated.

While it is possible to use this model as the value of the
``AUTH_PROFILE_MODULE`` setting, it's not recommended that you do
so. This model's sole purpose is to store data temporarily during
account registration and activation, and a mechanism for automatically
creating an instance of a site-specific profile model is provided via
the ``create_inactive_user`` on ``RegistrationManager``.
``RegistrationProfile`` objects have the following fields:

    A SHA1 hash used as an account's activation key.

    The ``User`` object for which activation information is being

``RegistrationProfile`` also has one custom method defined:

    Determines whether this ``RegistrationProfile``'s activation key
    has expired.
    Returns ``True`` if the key has expired, ``False`` otherwise.
    Key expiration is determined by the setting
    ``ACCOUNT_ACTIVATION_DAYS``, which should be the number of days a
    key should remain valid after an account is registered.

The ``RegistrationManager``

Custom manager for the ``RegistrationProfile`` model.
The methods defined here provide shortcuts for account creation and
activation (including generation and emailing of activation keys), and
for cleaning out expired inactive accounts.

    Validates an activation key and activates the corresponding
    ``User`` if valid.
    If the key is valid and has not expired, returns the ``User``
    after activating.
    If the key is not valid or has expired, returns ``False``.
    If the key is valid but the ``User`` is already active, returns
    the ``User``.

``create_inactive_user(username, password, email, send_email=True, profile_callback=None)``
    Creates a new, inactive ``User``, generates a
    ``RegistrationProfile`` and emails its activation key to the
    ``User``. Returns the new ``User``.
    To disable the email, call with ``send_email=False``.
    To enable creation of a custom user profile along with the
    ``User`` (e.g., the model specified in the ``AUTH_PROFILE_MODULE``
    setting), define a function which knows how to create and save an
    instance of that model with appropriate default values, and pass
    it as the keyword argument ``profile_callback``. This function
    should accept one keyword argument:
        The ``User`` to relate the profile to.

    Creates a ``RegistrationProfile`` for a given ``User``. Returns
    the ``RegistrationProfile``.
    The activation key for the ``RegistrationProfile`` will be a SHA1
    hash, generated from a combination of the ``User``'s username and
    a random salt.

    Removes expired instances of ``RegistrationProfile`` and their
    associated ``User`` objects.
    Accounts to be deleted are identified by searching for instances
    of ``RegistrationProfile`` with expired activation keys, and then
    checking to see if their associated ``User`` instances have the
    field ``is_active`` set to ``False``; any ``User`` who is both
    inactive and has an expired activation key will be deleted.
    It is recommended that this method be executed regularly as part
    of your routine site maintenance; the file
    ``bin/`` in this application provides a
    standalone script, suitable for use as a cron job, which will call
    this method.
    Regularly clearing out accounts which have never been activated
    serves two useful purposes:
    1. It alleviates the ocasional need to reset a
       ``RegistrationProfile`` and/or re-send an activation email when
       a user does not receive or does not act upon the initial
       activation email; since the account will be deleted, the user
       will be able to simply re-register and receive a new activation
    2. It prevents the possibility of a malicious user registering one
       or more accounts and never activating them (thus denying the
       use of those usernames to anyone else); since those accounts
       will be deleted, the usernames will become available for use
    If you have a troublesome ``User`` and wish to disable their
    account while keeping it in the database, simply delete the
    associated ``RegistrationProfile``; an inactive ``User`` which
    does not have an associated ``RegistrationProfile`` will not be