Merge branch 'release/0.9.2'

[philo.git] / philo / contrib / waldo / forms.py

diff --git a/philo/contrib/waldo/forms.py b/philo/contrib/waldo/forms.py
index 2ee64d0..8e14ba5 100644 (file)
--- a/philo/contrib/waldo/forms.py
+++ b/philo/contrib/waldo/forms.py
@@ -1,4 +1,5 @@
 from datetime import date
+
 from django import forms
 from django.conf import settings
 from django.contrib.auth import authenticate
@@ -6,14 +7,23 @@ from django.contrib.auth.forms import AuthenticationForm, UserCreationForm
 from django.contrib.auth.models import User
 from django.core.exceptions import ValidationError
 from django.utils.translation import ugettext_lazy as _
+
 from philo.contrib.waldo.tokens import REGISTRATION_TIMEOUT_DAYS
 
 
 class EmailInput(forms.TextInput):
+       """Displays an HTML5 email input on browsers which support it and a normal text input on other browsers."""
        input_type = 'email'
 
 
 class RegistrationForm(UserCreationForm):
+       """
+       Handles user registration. If :mod:`recaptcha_django` is installed on the system and :class:`recaptcha_django.middleware.ReCaptchaMiddleware` is in :setting:`settings.MIDDLEWARE_CLASSES`, then a recaptcha field will automatically be added to the registration form.
+       
+       .. seealso:: `recaptcha-django <http://code.google.com/p/recaptcha-django/>`_
+       
+       """
+       #: An :class:`EmailField` using the :class:`EmailInput` widget.
        email = forms.EmailField(widget=EmailInput)
        try:
                from recaptcha_django import ReCaptchaField
@@ -55,6 +65,7 @@ class RegistrationForm(UserCreationForm):
 
 
 class UserAccountForm(forms.ModelForm):
+       """Handles a user's account - by default, :attr:`auth.User.first_name`, :attr:`auth.User.last_name`, :attr:`auth.User.email`."""
        first_name = User._meta.get_field('first_name').formfield(required=True)
        last_name = User._meta.get_field('last_name').formfield(required=True)
        email = User._meta.get_field('email').formfield(required=True, widget=EmailInput)
@@ -63,12 +74,37 @@ class UserAccountForm(forms.ModelForm):
                kwargs['instance'] = user
                super(UserAccountForm, self).__init__(*args, **kwargs)
        
+       def email_changed(self):
+               """Returns ``True`` if the email field changed value and ``False`` if it did not, or if there is no email field on the form. This method must be supplied by account forms used with :mod:`~philo.contrib.waldo`."""
+               return 'email' in self.changed_data
+       
+       def reset_email(self):
+               """
+               ModelForms modify their instances in-place during :meth:`_post_clean`; this method resets the email value to its initial state and returns the altered value. This is a method on the form to allow unusual behavior such as storing email on a :class:`UserProfile`.
+               
+               """
+               email = self.instance.email
+               self.instance.email = self.initial['email']
+               self.cleaned_data.pop('email')
+               return email
+       
+       @classmethod
+       def set_email(cls, user, email):
+               """
+               Given a valid instance and an email address, correctly set the email address for that instance and save the changes. This is a class method in order to allow unusual behavior such as storing email on a :class:`UserProfile`.
+               
+               """
+               user.email = email
+               user.save()
+               
+       
        class Meta:
                model = User
                fields = ('first_name', 'last_name', 'email')
 
 
 class WaldoAuthenticationForm(AuthenticationForm):
+       """Handles user authentication. Checks that the user has not mistakenly entered their email address (like :class:`django.contrib.admin.forms.AdminAuthenticationForm`) but does not require that the user be staff."""
        ERROR_MESSAGE = _("Please enter a correct username and password. Note that both fields are case-sensitive.")
        
        def clean(self):
@@ -92,11 +128,4 @@ class WaldoAuthenticationForm(AuthenticationForm):
                        elif not self.user_cache.is_active:
                                raise ValidationError(message)
                self.check_for_test_cookie()
-               return self.cleaned_data
-       
-       def check_for_test_cookie(self):
-               # This method duplicates the Django 1.3 AuthenticationForm method.
-               if self.request and not self.request.session.test_cookie_worked():
-                       raise forms.ValidationError(
-                               _("Your Web browser doesn't appear to have cookies enabled. "
-                                 "Cookies are required for logging in."))
\ No newline at end of file
+               return self.cleaned_data
\ No newline at end of file