Commits

James Bennett committed 50fc629

MOAR DOCUMENTATION

Comments (0)

Files changed (7)

docs/backend-api.rst

 ``**kwargs``
     A dictionary of any additional arguments (e.g., information
     captured from the URL, such as an activation key) received by the
-    activation view. The combination of the ``HttpRequest`` and this
-    additional information must be sufficient to identify the account
-    which will be activated.
+    :func:`~registration.views.activate` view. The combination of the
+    ``HttpRequest`` and this additional information must be sufficient
+    to identify the account which will be activated.
 
 If the account cannot be successfully activated (for example, in the
 default backend if the activation period has expired), this method
     The Django ``HttpRequest`` object in which a new user is
     attempting to register.
 
-If this method returns ``False``, the registration view will not
-display a form for account creation; instead, it will issue a redirect
-to a URL explaining that registration is not permitted.
+If this method returns ``False``, the
+:func:`~registration.views.register` view will not display a form for
+account creation; instead, it will issue a redirect to a URL
+explaining that registration is not permitted.
 
 
 get_form_class(self, request)

docs/default-backend.rst

+.. _default-backend:
+.. module:: registration.backends.default
+
+The default backend
+===================
+
+A default :ref:`registration backend <backend-api>` is bundled with
+django-registration in the module ``registration.backend.default``,
+and implements a simple two-step workflow in which a new user first
+registers, then confirms and activates the new account by following a
+link sent to the email address supplied during registration.
+
+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
+:class:`registration.forms.RegistrationForm` as its form class for
+user registration; this can be overridden by passing the keyword
+argument ``form_class`` to the :func:`~registration.views.register`
+view.
+
+Upon successful registration -- not activation -- the default redirect
+is to the URL pattern named ``registration_complete``; this can be
+overridden by passing the keyword argument ``success_url`` to the
+:func:`~registration.views.register` view.
+
+During registration, a new user account is created, 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 a storing an activation key in the
+database, using the following model:
+
+
+.. currentmodule:: registration.models
+
+.. class:: 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:
+
+   .. attribute:: user
+
+      A ``ForeignKey`` to ``django.contrib.auth.models.User``,
+      representing the user account for which activation information
+      is being stored.
+
+   .. attribute:: activation_key
+
+      A 40-character ``CharField``, storing the activation key for the
+      account. Initially, the activation key is a SHA1 hash generated
+      from combining the username of the account with a
+      randomly-generated salt; after activation, this is reset to
+      :attr:`ACTIVATED`.
+
+   Additionally, one class attribute exists:
+
+   .. attribute:: ACTIVATED
+
+      A constant string used as the value of :attr:`activation_key`
+      for accounts which have been activated.
+
+   And the following methods:
+
+   .. method:: 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 :attr:`activation_key` is :attr:`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 :attr:`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.
+
+   .. method:: 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 :attr:`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
+          <http://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_
+          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.
+
+      :param site: An object representing the site on which account
+         was registered; an instance of either
+         ``django.contrib.sites.models.Site`` or
+         ``django.contrib.sites.models.RequestSite``.
+
+
+Additionally, :class:`RegistrationProfile` has a custom manager
+(accessed as ``RegistrationProfile.objects``):
+
+
+.. class:: RegistrationManager
+
+   This manager provides several convenience methods for creating and
+   working with instances of :class:`RegistrationProfile`:
+
+   .. method:: 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
+      :attr:`~RegistrationProfile.activation_key` of the
+      :class:`RegistrationProfile` for the account will be set to
+      :attr:`RegistrationProfile.ACTIVATED` after successful
+      activation.
+
+      Returns the ``User`` instance representing the account if
+      activation is successful, ``False`` otherwise.
+
+   .. method:: delete_expired_users
+
+      Removes expired instances of :class:`RegistrationProfile`, and
+      their associated user accounts, from the database. This is
+      useful as a periodic maintenance task to clean out account which
+      registered by never activated.
+
+      Accounts to be deleted are identified by searching for instances
+      of :class:`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
+      :class:`RegistrationProfile`; any ``User`` which does not have
+      an associated :class:`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``.
+
+   .. method:: create_inactive_user(username, email, password, site, send_email=True)
+
+      Creates a new, inactive user account and an associated instance
+      of :class:`RegistrationProfile`, sends the activation email and
+      returns the new ``User`` object representing the account.
+
+      :param username: The username to use for the new account.
+      :param email: The email address to use for the new account.
+      :param password: The password to use for the new account.
+      :param site: An object representing the site on which the
+         account is being registered; an instance of either
+         ``django.contrib.sites.models.Site`` or
+         ``django.contrib.sites.models.RequestSite``.
+      :param send_email: If ``True``, the activation email will be
+         sent to the account (by calling
+         :meth:`RegistrationProfile.send_activation_email`). If
+         ``False``, no email will be sent (but the account will still
+         be inactive)
+
+   .. method:: create_profile(user)
+
+      Creates and returns a :class:`RegistrationProfile` instance for
+      the account represented by ``user``.
+
+      :param user: The user account; an instance of
+         ``django.contrib.auth.models.User``.
+.. _forms:
+.. module:: registration.forms
+
+Forms for user registration
+===========================
+
+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 :ref:`default backend <default-backend>` in
+mind, but may also be useful in other situations.
+
+
+.. class:: RegistrationForm
+
+   A simple form for registering an account. Has the following fields,
+   all of which are required:
+
+   ``username``
+       The username to use for the new account. This is represented as
+       a text input which validates that the username is unique,
+       consists entirely of alphanumeric characters and underscores
+       and is at most 30 characters in length.
+
+   ``email``
+      The email address to use for the new account. This is
+      represented as a text input which accepts email addresses up to
+      75 characters in length.
+
+   ``password1``
+      The password to use for the new account. This represented as a
+      password input (``input type="password"`` in the rendered HTML).
+
+   ``password2``
+      The password to use for the new account. This represented as a
+      password input (``input type="password"`` in the rendered HTML).
+
+   The constraints on usernames and email addresses match those
+   enforced by Django's default authentication backend for instances
+   of ``django.contrib.auth.models.User``. The repeated entry of the
+   password serves to catch typos.
+
+   Because it does not apply to any single field of the form, the
+   validation error for mismatched passwords is attached to the form
+   itself, and so must be accessed via the form's
+   ``non_field_errors()`` method.
+
+
+.. class:: RegistrationFormTermsOfService
+
+   A subclass of :class:`RegistrationForm` which adds one additional,
+   required field:
+
+   ``tos``
+       A checkbox indicating agreement to the site's terms of
+       service/user agreement.
+
+
+.. class:: RegistrationFormUniqueEmail
+
+   A subclass of :class:`RegistrationForm` which enforces uniqueness
+   of email addresses in addition to uniqueness of usernames.
+
+
+.. class:: RegistrationFormNoFreeEmail
+
+   A subclass of :class:`RegistrationForm` which disallows
+   registration using addresses from some common free email
+   providers. This can, in some cases, cut down on automated
+   registration by spambots.
+
+   By default, the following domains are disallowed for email
+   addresses:
+
+   * ``aim.com``
+
+   * ``aol.com``
+
+   * ``email.com``
+
+   * ``gmail.com``
+
+   * ``googlemail.com``
+
+   * ``hotmail.com``
+
+   * ``hushmail.com``
+
+   * ``msn.com``
+
+   * ``mail.ru``
+
+   * ``mailinator.com``
+
+   * ``live.com``
+
+   * ``yahoo.com``
+
+   To change this, subclass this form and set the class attribute
+   ``bad_domains`` to a list of domains you wish to disallow.
    :maxdepth: 1
    
    quickstart
+   upgrade
    backend-api
+   default-backend
+   forms
+   views
    signals
-   views
-   upgrade

docs/quickstart.rst

 ~~~~~~~~~~~~~~~
 
 The default backend includes a Django ``URLConf`` which sets up URL
-patterns for the views in django-registration, as well as several
-useful views in ``django.contrib.auth`` (e.g., login, logout, password
-change/reset). This ``URLConf`` can be found at
+patterns for :ref:`the views in django-registration <views>`, as well
+as several useful views in ``django.contrib.auth`` (e.g., login,
+logout, password change/reset). This ``URLConf`` can be found at
 ``registration.backends.default.urls``, and so can simply be included
 in your project's root URL configuration. For example, to place the
 URLs under the prefix ``/accounts/``, you could add the following to
     If activation was successful, the ``User`` object representing the
     account which was just activated. If activation was unsuccessful,
     the boolean value ``False``; this may be because the activation
-    period has expired, or the activation view was accessed with an
-    invalid or nonexistent activation key. In such cases, an
-    appropriate error message should be displayed.
+    period has expired, or the :func:`~registration.views.activate`
+    view was accessed with an invalid or nonexistent activation
+    key. In such cases, an appropriate error message should be
+    displayed.
 
 **registration/activation_email_subject.txt**
 
 .. _signals:
-.. module: registration.signals
+.. module:: registration.signals
 
 
 Custom signals used by django-registration
 signals.
 
 
-.. data:: registration.signals.user_activated
+.. data:: user_activated
 
    Sent when a user account is activated (not applicable to all
    backends). Provides the following arguments:
        The ``HttpRequest`` in which the account was activated.
 
 
-.. data:: registration.signals.user_registered
+.. data:: user_registered
 
    Sent when a new user account is registered. Provides the following
    arguments:
 Changes to registration views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The views used to handle user registration have changed significantly
-as of django-registration |version|. Both views now require the
-keyword argument ``backend``, which specifies the :ref:`registration
-backend <backend-api>` to use, and so any URL pattern for these views
-must supply that argument.
+:ref:`The views used to handle user registration <views>` have changed
+significantly as of django-registration |version|. Both views now
+require the keyword argument ``backend``, which specifies the
+:ref:`registration backend <backend-api>` to use, and so any URL
+pattern for these views must supply that argument.
 
 The ``profile_callback`` argument of the ``register`` view has been
 removed; the functionality it provided can now be implemented easily