1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
===================
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:
``activation_key``
A SHA1 hash used as an account's activation key.
``user``
The ``User`` object for which activation information is being
stored.
``RegistrationProfile`` also has one custom method defined:
``activation_key_expired()``
Determines whether this ``RegistrationProfile``'s activation key
has expired.
Returns ``True`` if the key has expired, ``False`` otherwise.
Key expiration is determined by a two-step process:
1. If the user has already activated, the key will have been reset
to the string ``ALREADY_ACTIVATED``. Re-activating is not
permitted, and so this method returns ``True`` in this case.
2. Otherwise, the date the user signed up is incremented by the
number of days specified in the setting
``ACCOUNT_ACTIVATION_DAYS`` (which should be the number of days
after signup during which a user is allowed to activate their
account); if the result is less than or equal to the current
date, the key has expired and this method returns ``True``.
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.
Methods:
``activate_user(activation_key)``
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
``False``.
To prevent reactivation of an account which has been deactivated
by site administrators, the activation key is reset to the string
``ALREADY_ACTIVATED`` after successful activation.
``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``.
The activation email will make use of two templates:
``registration/activation_email_subject.txt``
This template will be used for the subject line of the
email. It receives one context variable, ``site``, which is
the currently-active ``django.contrib.sites.models.Site``
instance. Because it is used as the subject line of an email,
this template's output **must** be only a single line of text;
output longer than one line will be forcibly joined into only
a single line.
``registration/activation_email.txt``
This template will be used for the body of the email. It will
receive three context variables: ``activation_key`` will be
the user's activation key (for use in constructing a URL to
activate the account), ``expiration_days`` will be the number
of days for which the key will be valid and ``site`` will be
the currently-active ``django.contrib.sites.models.Site``
instance.
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:
``user``
The ``User`` to relate the profile to.
``create_profile(user)``
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.
``deleted_expired_users()``
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; this application provides a
custom management command which will call this method, accessible
as ``manage.py cleanupregistration``.
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
key.
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
again.
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
deleted.
|
