Metadata-Version: 2.0
Name: django-recaptcha
Version: 1.2.1
Summary: Django recaptcha form field/widget app.
Home-page: http://github.com/praekelt/django-recaptcha
Author: Praekelt Foundation
Author-email: dev@praekelt.com
License: BSD
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django :: 1.10
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: django

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``.


Requirements
------------

Tested with:

* Python: 2.7, 3.5
* Django: 1.8, 1.9, 1.10

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

#. `Sign up for reCAPTCHA <https://www.google.com/recaptcha/intro/index.html>`_.

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

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

#. Add the keys reCAPTCHA have given you to your Django production settings (leave development settings blank to use the default test keys) as
   ``RECAPTCHA_PUBLIC_KEY`` and ``RECAPTCHA_PRIVATE_KEY``. For example:

   .. code-block:: python

       RECAPTCHA_PUBLIC_KEY = 'MyRecaptchaKey123'
       RECAPTCHA_PRIVATE_KEY = 'MyRecaptchaPrivateKey456'

   These can also be specificied per field by passing the ``public_key`` or
   ``private_key`` parameters to ``ReCaptchaField`` - see field usage below.

#. If you would like to use the new No Captcha reCaptcha add the setting
   ``NOCAPTCHA = True``. For example:

   .. code-block:: python

       NOCAPTCHA = True

#. If you require a proxy, add a ``RECAPTCHA_PROXY`` setting, for example:

   .. code-block:: python

       RECAPTCHA_PROXY = 'http://127.0.0.1:8000'

Usage
-----

Field
~~~~~

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

.. code-block:: python

    from django import forms
    from captcha.fields import ReCaptchaField

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

To allow for runtime specification of keys you can optionally pass the
``private_key`` or ``public_key`` parameters to the constructor. For example:

.. code-block:: python

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

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

The reCAPTCHA widget supports several `Javascript options variables
<https://developers.google.com/recaptcha/docs/display#js_param>`_ that
customize the behaviour of the widget, such as ``theme`` and ``lang``. You can
forward these options to the widget by passing an ``attr`` parameter to the
field, containing a dictionary of options. For example:

.. code-block:: python

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

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


Local Development and Functional Testing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Google provides test keys which are set as the default for ``RECAPTCHA_PUBLIC_KEY`` and ``RECAPTCHA_PRIVATE_KEY``. These cannot be used in production since they always validate to true and a warning will be shown on the reCAPTCHA.


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

Django reCAPTCHA introduces an environment variable ``RECAPTCHA_TESTING`` which
helps facilitate tests. The environment 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. Note that if you are
using the new No Captcha reCaptcha (ie. with ``NOCAPTCHA = True`` in your
settings) the response field is called ``g-recaptcha-response``.

Example:

.. code-block:: python

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

    form_params = {'recaptcha_response_field': 'PASSED'} # use 'g-recaptcha-response' param name if using NOCAPTCHA
    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 reCAPTCHA work in ajax-loaded forms:

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

   .. code-block:: html

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

#. Add to your Django settings:

   .. code-block:: python

       CAPTCHA_AJAX = True


Disabling SSL
~~~~~~~~~~~~~

This library used to not use SSL by default, but now it does. You can disable
this if required, but you should think long and hard about it before you do so!

You can disable it by setting ``RECAPTCHA_USE_SSL = False`` in your Django
settings, or by passing ``use_ssl=False`` to the constructor of
``ReCaptchaField``.


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.


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>`_
* `Daniel Gatis Carrazzoni <https://github.com/danielgatis>`_
* `pbf <https://github.com/pbf>`_
* `Alexey Subbotin <https://github.com/dotsbb>`_
* `Sean Stewart <https://github.com/mindcruzer>`_


Changelog
=========

Pending
-------

#. New release notes go here

1.2.0 (2017-01-23)
------------------

#. Made reCAPTCHA test keys the default keys for easy use in development. The
   captcha doesn't require any interaction, has a warning label that it's for
   testing purposes only, and always validates.

1.2.0 (2016-12-19)
------------------

#. Pass options as HTML data attributes instead of the ``RecaptchaOptions``
   JavaScript object in the default template. Custom templates using
   ``RecaptchaOptions`` should migrate to using HTML data attributes.

1.1.0 (2016-10-28)
------------------

#. Dropped support for old Django versions. Only the upstream supported
   versions are now supported, currently 1.8, 1.9, and 1.10.
#. Made recaptcha checking use SSL by default. This can be disabled by setting
   ``RECAPTCHA_USE_SSL = False`` in your Django settings or passing
   ``use_ssl=False`` to the constructor of ``ReCaptchaField``.
#. Made ReCaptchaField respect required=False

1.0.6 (2016-10-05)
------------------

#. Confirmed tests pass on Django 1.10. Older versions should still work.
#. Fixed a bug where the widget was always rendered in the first used language
   due to ``attrs`` being a mutable default argument.

1.0.5 (2016-01-04)
------------------
#. Chinese translation (kz26).
#. Syntax fix (zvin).
#. Get tests to pass on Django 1.9.

1.0.4 (2015-04-16)
------------------
#. Fixed Python 3 support
#. Added Polish translations
#. Update docs

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.


