Commits

George Notaras committed 804bf00

Updated documentation

Comments (0)

Files changed (3)

-"""
-An easy-to-use Django forms integration of the reCaptcha service.
+django-recaptcha-works
+======================
+django-recaptcha-works provides a Django form field that integrates the
+reCaptcha service. It is released under the terms of the BSD License.
 
+The app is based on the code snippet #1644 as published by Chris Beaven
+(aka SmileyChris) on:
+  - http://djangosnippets.org/snippets/1644/
 
-To use, simply base your form off the ``RecaptchaForm`` class. This class adds
-a new argument that must be provided to the form, ``remote_ip``.
+The original code has been further modified by George Notaras in order to
+implement the following:
+  * prepare a Django application release
+  * SSL support
+  * migration to the Google hosted reCAPTCHA API
+  * extension of the available application settings
+  * addition of a decorator that adds the remote IP to the submitted form
+ 
+Development Web Site:
+  - http://www.codetrax.org/projects/django-recaptcha-works
 
-Two settings which must be set in your project's ``settings`` module are 
-``RECAPTCHA_PUBLIC_KEY`` and ``RECAPTCHA_PRIVATE_KEY``, the public and private
-keys for your domain, respectively. 
+Public Source Code Repository:
+  - https://source.codetrax.org/hgroot/django-recaptcha-works
 
-Following is an example of creating a basic comment form class and then
-using an instance of the form in a view::
+
+reCaptcha Service
+=================
+In order to use this app you need a valid reCaptcha key pair, which can
+be obtained for free from:
+
+  http://www.google.com/recaptcha
+
+ 
+Installation
+============
+
+Add it to the INSTALLED_APPS in settings.py:
+
+INSTALLED_APPS = (
+    ...
+    'recaptchaworks',
+)
+
+
+Configuration
+=============
+The recaptchaworks app accepts the following configuration options:
+
+RECAPTCHA_PUBLIC_KEY: The public key as obtained from google.com/recaptcha
+
+RECAPTCHA_PRIVATE_KEY: The private key as obtained from google.com/recaptcha
+
+RECAPTCHA_USE_SSL: True/False -- Enables/disables secure communication with
+the recaptcha servers.
+
+RECAPTCHA_OPTIONS: A dictionary with the recaptcha customization options.
+Read the following page for more information:
+  - http://code.google.com/apis/recaptcha/docs/customization.html
+
+Example configuration:
+
+RECAPTCHA_PUBLIC_KEY  = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+RECAPTCHA_PRIVATE_KEY = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+RECAPTCHA_USE_SSL = True
+RECAPTCHA_OPTIONS = {
+    'theme': 'white',
+    'lang': 'en',
+    'tabindex': 0,
+}
+
+
+Usage
+=====
+recaptchaworks provides a form field which can be attached to your forms.
+Implementing a reCaptcha protected form is a two step process.
+
+Step 1: Create the reCaptcha preotected form:
 
     from django import forms
-    from mysite.utils import recaptcha
+    from recaptchaworks.fields import RecaptchaField
+    
+    class RecaptchaProtectedForm(forms.Form):
+        # ... other form fields
+        recaptcha = RecaptchaField(label='Human test', required=True)
 
-    class CommentForm(recaptcha.RecaptchaForm):
-        name = forms.CharField()
-        comment = forms.CharField(widget=Textarea())
-        captcha = recaptcha.RecaptchaField()
+Step 2: Use the ``fix_recaptcha_remote_ip`` decorator around the view that
+processes the form data. This is required because the remote IP is a mandatory
+argument for the verification of the information the user has submitted in the
+reCaptcha field, but it cannot be added to the form field automatically due to
+limitations of the Django framework.
 
-    def comment(request):
-        comment_form = CommentForm(remote_ip=request.META['REMOTE_ADDR'])
-        ...
+    from recaptchaworks.decorators import fix_recaptcha_remote_ip
+    
+    @fix_recaptcha_remote_ip
+    def view(request, *args, **kwargs):
+        if request.method == 'POST':
+            # ... process the form data here
 
-If you need to use a different base form (such as ``ModelForm``), use multiple
-inheritance like so::
 
-    class MyModelForm(BaseRecaptchaForm, ModelForm):
-        ...
-"""
+License
+=======
+
+Copyright (c) 2009-2010 Chris Beaven (SmileyChris), http://smileychris.com/
+Copyright (c) 2010 George Notaras <gnot@g-loaded.eu>, http://www.g-loaded.eu/
+
+Licensed under the BSD License.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice, 
+       this list of conditions and the following disclaimer.
+      
+    2. Redistributions in binary form must reproduce the above copyright 
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Django nor the names of its contributors may be used
+       to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
         maintainer = 'George Notaras',
         maintainer_email = 'gnot@g-loaded.eu',
         url = 'http://www.codetrax.org/projects/django-recaptcha-works',
-        description = 'django-recaptcha-works is an easy-to-use Django forms integration of the reCaptcha service.',
-        long_description = 'django-recaptcha-works is an easy-to-use Django forms integration of the reCaptcha service.',
+        description = 'django-recaptcha-works provides a Django form field that integrates the reCaptcha service.',
+        long_description = 'django-recaptcha-works provides a Django form field that integrates the reCaptcha service.',
         download_url = 'https://source.codetrax.org/hgroot/django-recaptcha-works',
         classifiers = [
             'Development Status :: 4 - Beta',

src/recaptchaworks/decorators.py

 
 def fix_recaptcha_remote_ip(view_func):
     """
-    Modifies a view function so that its request's POST payload contains
-    a ``recaptcha_remote_ip_field`` field.
-
+    Modifies a view function so that its request object's POST payload
+    contains a ``recaptcha_remote_ip_field`` field, which required for
+    proper reCaptcha functionality.
+    
     """
     def wrapped_view(*args, **kwargs):
         args = list(args)