Skip to main content

Django recaptcha form field/widget app.

Project description

Django reCAPTCHA
================
**Django reCAPTCHA form field/widget integration app.**

.. image:: https://travis-ci.org/praekelt/django-recaptcha.svg?branch=develop
:target: https://travis-ci.org/praekelt/django-recaptcha

.. contents:: Contents
:depth: 5

django-recaptcha uses a modified version of the `Python reCAPTCHA client <http://pypi.python.org/pypi/recaptcha-client>`_ which is included in the package as ``client.py``.


Installation
------------

#. Install or add ``django-recaptcha`` to your Python path.

#. Add ``captcha`` to your ``INSTALLED_APPS`` setting.

#. Add a ``RECAPTCHA_PUBLIC_KEY`` setting to the project's ``settings.py`` file. This is your public API key as provided by reCAPTCHA, i.e.::

RECAPTCHA_PUBLIC_KEY = '76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh'

This can be seperately specified at runtime by passing a ``public_key`` parameter when constructing the ``ReCaptchaField``, see field usage below.

#. Add a ``RECAPTCHA_PRIVATE_KEY`` setting to the project's ``settings.py`` file. This is your private API key as provided by reCAPTCHA, i.e.::

RECAPTCHA_PRIVATE_KEY = '98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs'

This can be seperately specified at runtime by passing a ``private_key`` parameter when constructing the ``ReCaptchaField``, see field usage below.

#. Optionally add a ``RECAPTCHA_USE_SSL`` setting to the project's ``settings.py`` file. This causes reCAPTCHA validation submits to be made over SSL, i.e.::

RECAPTCHA_USE_SSL = True

If you don't add this setting the default behaviour is to **NOT** use SSL.
This can be seperately specified at runtime by passing a ``use_ssl`` parameter when constructing the ``ReCaptchaField``, see field usage below.

Usage
-----

Field
~~~~~
The quickest way to add reCAPTHCA to a form is to use the included ``ReCaptchaField`` field type. A ``ReCaptcha`` widget will be rendered with the field validating itself without any further action required from you. For example::

from django import forms
from captcha.fields import ReCaptchaField

class FormWithCaptcha(forms.Form):
captcha = ReCaptchaField()

To allow for runtime specification of keys and SSL usage you can optionally pass ``private_key``, ``public_key`` or ``use_ssl`` parameters to the constructor, i.e.::

captcha = ReCaptchaField(
public_key='76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh',
private_key='98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs',
use_ssl=True
)

If specified these parameters will be used instead of your reCAPCTHA project settings.

The reCAPTCHA widget supports several `Javascript options variables <https://code.google.com/apis/recaptcha/docs/customization.html>`_ customizing the behaviour of the widget, such as ``theme`` and ``lang``. You can forward these options to the widget by passing an ``attr`` parameter containing a dictionary of options to ``ReCaptchaField``, i.e.::

captcha = ReCaptchaField(attrs={'theme' : 'clean'})

The captcha client takes the key/value pairs and writes out the RecaptchaOptions value in JavaScript.


Unit Testing
~~~~~~~~~~~~

django-recaptcha introduces an environmental variable `RECAPTCHA_TESTING` which
helps facilitate tests. The environmental variable should be set to `"True"`,
and cleared, using the `setUp()` and `tearDown()` methods in your test classes.

Setting `RECAPTCHA_TESTING` to `True` causes django-recaptcha to accept
`"PASSED"` as the `recaptcha_response_field` value.

Example:::

import os
os.environ['RECAPTCHA_TESTING'] = 'True'

form_params = {'recaptcha_response_field': 'PASSED'}
form = RegistrationForm(form_params) # assuming only one ReCaptchaField
form.is_valid() # True

os.environ['RECAPTCHA_TESTING'] = 'False'
form.is_valid() # False

Passing any other values will cause django-recaptcha to continue normal processing
and return a form error.

Check `tests.py` for a full example.


AJAX
~~~~~

To make Recapcha work in ajax-loaded forms:

#. import recaptcha_ajax.js on your page (not in the loaded template):

<script type="text/javascript" src="http://www.google.com/recaptcha/api/js/recaptcha_ajax.js"></script>

#. settings.py

CAPTCHA_AJAX = True


Credits
-------
Inspired Marco Fucci's blogpost titled `Integrating reCAPTCHA with Django <http://www.marcofucci.com/tumblelog/26/jul/2009/integrating-recaptcha-with-django>`_


``client.py`` taken from `recaptcha-client <http://pypi.python.org/pypi/recaptcha-client>`_ licenced MIT/X11 by Mike Crawford.

reCAPTCHA copyright 2012 Google.

.. |travis| image:: https://travis-ci.org/praekelt/device-recaptcha.png?branch=develop
.. _travis: https://travis-ci.org/praekelt/device-recaptcha
Authors
=======

Praekelt Foundation
-------------------
* Shaun Sephton
* Peter Pistorius
* Hedley Roos

bTaylor Design
--------------
* `Brandon Taylor <http://btaylordesign.com/>`_

Other
-----
* Brooks Travis
* `Denis Mishchishin <https://github.com/denz>`_
* `Joshua Peper <https://github.com/zout>`_
* `Rodrigo Primo <https://github.com/rodrigoprimo>`_
* `snnwolf <https://github.com/snnwolf>`_
* `Adriano Orioli <https://github.com/Aorioli>`_
* `cdvv7788 <https://github.com/cdvv7788>`_

Changelog
=========

1.0.3 (2015-01-13)
------------------

#. Added nocaptcha recaptcha support

1.0.2 (2014-09-16)
------------------

#. Fixed Russian translations
#. Added Spanish translations

1.0.1 (2014-09-11)
------------------

#. Added Django 1.7 suport
#. Added Russian translations
#. Added multi dependancy support
#. Cleanup

1.0 (2014-04-23)
----------------

#. Added Python 3 support
#. Added French, Dutch and Brazilian Portuguese translations

0.0.9 (2014-02-14)
------------------
#. Bugfix: release master and not develop. This should fix the confusion due to master having been the default branch on Github.

0.0.8 (2014-02-13)
------------------
#. Bugfix: remove reference to options.html.

0.0.7 (2014-02-12)
------------------
#. Make it possible to load the widget via ajax.

0.0.6 (2013-01-31)
------------------
#. Added an extra parameter `lang` to bypass Google's language bug. See http://code.google.com/p/recaptcha/issues/detail?id=133#c3
#. widget.html no longer includes options.html. Options are added directly to widget.html

0.0.5 (2013-01-17)
------------------
#. Removed django-registration dependency
#. Changed testing mechanism to environmental variable `RECAPTCHA_TESTING`

0.0.4
-----
#. Handle missing REMOTE_ADDR request meta key. Thanks Joe Jasinski.
#. Added checks for settings.DEBUG to facilitate tests. Thanks Victor Neo.
#. Fix for correct iframe URL in case of no javascript. Thanks gerdemb.

0.0.3 (2011-09-20)
------------------
#. Don't force registration version thanks kshileev.
#. Render widget using template, thanks denz.

0.0.2 (2011-08-10)
------------------
#. Use remote IP when validating.
#. Added SSL support, thanks Brooks Travis.
#. Added support for Javascript reCAPTCHA widget options, thanks Brandon Taylor.
#. Allow for key and ssl specification at runtime, thanks Evgeny Fadeev.

0.0.1 (2010-06-17)
------------------
#. Initial release.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-recaptcha-1.0.3.tar.gz (9.4 kB view hashes)

Uploaded Source

Built Distribution

django_recaptcha-1.0.3-py2.7.egg (17.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page