Source

django-recaptcha-works / README

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/

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

Public Source Code Repository:
  - https://source.codetrax.org/hgroot/django-recaptcha-works


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 protected form:

    from django import forms
    from recaptchaworks.fields import RecaptchaField
    
    class RecaptchaProtectedForm(forms.Form):
        # ... other form fields
        recaptcha = RecaptchaField(label='Human test', required=True)

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.

    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


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.