django-recaptcha429 2.1.0
Django recaptcha form field/widget app.
License: BSD
Keywords: django,reCAPTCHA,reCAPTCHA v2,reCAPTCHA v3

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

.. image:: https://github.com/noripyt/django-cachalot/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/noripyt/django-cachalot/actions/workflows/ci.yml
.. image:: https://coveralls.io/repos/github/praekelt/django-recaptcha/badge.svg?branch=main
    :target: https://coveralls.io/github/Andrew-Chen-Wang/django-recaptcha429?branch=main
.. image:: https://badge.fury.io/py/django-recaptcha.svg
    :target: https://badge.fury.io/py/django-recaptcha429
.. image:: https://img.shields.io/pypi/pyversions/django-recaptcha.svg
    :target: https://pypi.python.org/pypi/django-recaptcha429
.. image:: https://img.shields.io/pypi/djversions/django-recaptcha.svg
    :target: https://pypi.python.org/pypi/django-recaptcha429

.. contents:: Contents
    :depth: 5

.. note::
   django-recaptcha supports Google reCAPTCHA V2 - Checkbox (Default), Google reCAPTCHA V2 - Invisible and Google reCAPTCHA V3 please look at the widgets section for more information.

   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: 3.7, 3.8, 3.9, 3.10
* Django: 2.2, 3.2, 4.0
* You can view the `Python-Django support matrix here <https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django>`_

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

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

#. Install with ``pip install django-recaptcha429``.

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

    .. code-block:: python

        INSTALLED_APPS = [
            ...,
            'captcha',
            ...
        ]

#. Add the Google reCAPTCHA keys generated in step 1 to your Django production settings with ``RECAPTCHA_PUBLIC_KEY`` and ``RECAPTCHA_PRIVATE_KEY``. Note that omitting these settings will default to a set of test keys refer to `Local Development and Functional Testing <Local Development and Functional Testing_>`_ for more information.

    For example:

    .. code-block:: python

        RECAPTCHA_PUBLIC_KEY = 'MyRecaptchaKey123'
        RECAPTCHA_PRIVATE_KEY = 'MyRecaptchaPrivateKey456'

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

#. (OPTIONAL) If you require a proxy, add a ``RECAPTCHA_PROXY`` setting (dictionary of proxies), for example:

    .. code-block:: python

        RECAPTCHA_PROXY = {'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'}

#. (OPTIONAL) In the event ``www.google.com`` is not accessible the ``RECAPTCHA_DOMAIN`` setting can be changed to ``www.recaptcha.net`` as per the `reCAPTCHA FAQ <https://developers.google.com/recaptcha/docs/faq#can-i-use-recaptcha-globally>`_:

    .. code-block:: python

        RECAPTCHA_DOMAIN = 'www.recaptcha.net'

This will change the Google JavaScript api domain as well as the client side field verification domain.

Usage
-----

Fields
~~~~~~

The quickest way to add reCAPTCHA to a form is to use the included
``ReCaptchaField`` field class. A ``ReCaptchaV2Checkbox`` will be rendered by default. For example:

.. code-block:: python

    from django import forms
    from captcha.fields import ReCaptchaField

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

Be sure to include the captcha field in your forms. There are many ways to add fields to forms in Django. We recommend you refer to the `form rendering options <https://docs.djangoproject.com/en/dev/topics/forms/#form-rendering-options>`_ and `rendering fields manually <https://docs.djangoproject.com/en/dev/topics/forms/#rendering-fields-manually>`_ sections of the `official Django documentation for forms <https://docs.djangoproject.com/en/dev/topics/forms>`_.

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.

Widgets
~~~~~~~

There are three widgets that can be used with the ``ReCaptchaField`` class:

    ``ReCaptchaV2Checkbox`` for `Google reCAPTCHA V2 - Checkbox <https://developers.google.com/recaptcha/docs/display>`_

    ``ReCaptchaV2Invisible`` for `Google reCAPTCHA V2 - Invisible <https://developers.google.com/recaptcha/docs/invisible>`_

    ``ReCaptchaV3`` for `Google reCAPTCHA V3 <https://developers.google.com/recaptcha/docs/v3>`_

To make use of widgets other than the default Google reCAPTCHA V2 - Checkbox widget, simply replace the ``ReCaptchaField`` widget. For example:

.. code-block:: python

    from django import forms
    from captcha.fields import ReCaptchaField
    from captcha.widgets import ReCaptchaV2Invisible

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

The reCAPTCHA widget supports several `data attributes
<https://developers.google.com/recaptcha/docs/display#render_param>`_ that
customize the behaviour of the widget, such as ``data-theme``, ``data-size``, etc. You can
forward these options to the widget by passing an ``attrs`` parameter to the
widget, containing a dictionary of options. For example:

.. code-block:: python

    captcha = fields.ReCaptchaField(
        widget=widgets.ReCaptchaV2Checkbox(
            attrs={
                'data-theme': 'dark',
                'data-size': 'compact',
            }
        )
    )
    # The ReCaptchaV2Invisible widget
    # ignores the "data-size" attribute in favor of 'data-size="invisible"'

The reCAPTCHA api supports several `parameters
<https://developers.google.com/recaptcha/docs/display#js_param>`_. To customise
the parameters that get sent along pass an ``api_params`` paramater to the
widget, containing a dictionary of options. For example:

.. code-block:: python

    captcha = fields.ReCaptchaField(
        widget=widgets.ReCaptchaV2Checkbox(
            api_params={'hl': 'cl', 'onload': 'onLoadFunc'}
        )
    )
    # The dictionary is urlencoded and appended to the reCAPTCHA api url.

By default, the widgets provided only supports a single form with a single widget on each page.

The language can be set with the 'h1' parameter, look at `language codes
<https://developers.google.com/recaptcha/docs/language>`_ for the language code options. Note that translations need to be added to this package for the errors to be shown correctly. Currently the package has error translations for the following language codes: es, fr, nl, pl, pt_BR, ru, zh_CN, zh_TW

However, the JavaScript used by the widgets can easily be overridden in the templates.

The templates are located in:

    ``captcha/includes/js_v2_checkbox.html`` for overriding the reCAPTCHA V2 - Checkbox template

    ``captcha/includes/js_v2_invisible.html`` for overriding the reCAPTCHA V2 - Invisible template

    ``captcha/includes/js_v3.html`` for overriding the reCAPTCHA V3 template

 For more information about overriding templates look at `Django's template override <https://docs.djangoproject.com/en/2.1/howto/overriding-templates/>`_

reCAPTCHA v3 Score
~~~~~~~~~~~~~~~~~~

As of version 3, reCAPTCHA also returns a score value. This can be used to determine the likelihood of the page interaction being a bot. See the Google `documentation <https://developers.google.com/recaptcha/docs/v3#score>`_ for more details.

To set a project wide score limit use the ``RECAPTCHA_REQUIRED_SCORE`` setting.

    For example:

    .. code-block:: python

        RECAPTCHA_REQUIRED_SCORE = 0.85

For per field, runtime, specification the attribute can also be passed to the widget:

    .. code-block:: python

        captcha = fields.ReCaptchaField(
            widget=ReCaptchaV3(
                attrs={
                    'required_score':0.85,
                    ...
                }
            )
        )

In the event the score does not meet the requirements, the field validation will fail as expected and an error message will be logged.

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.

To bypass the security check that prevents the test keys from being used unknowingly add ``SILENCED_SYSTEM_CHECKS = [..., 'captcha.recaptcha_test_key_error', ...]`` to your settings, here is an example:

    .. code-block:: python

        SILENCED_SYSTEM_CHECKS = ['captcha.recaptcha_test_key_error']

Credits
-------
Current Maintainer is `Andrew Chen Wang <https://github.com/Andrew-Chen-Wang>`_

Originally developed by `Praekelt Consulting <https://github.com/praekelt/django-recaptcha>`_

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
=======

Current Maintainer
------------------

* `Andrew Chen Wang <https://github.com/Andrew-Chen-Wang>`_

Praekelt Consulting
-------------------
* Shaun Sephton
* Peter Pistorius
* Hedley Roos
* Altus Barry
* Cilliers Blignaut

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>`_
* `Rob Charlwood <https://github.com/robcharlwood>`_


Changelog
=========

2.1.0
-----

#. Added testing for Django 3.2 and 4.0
#. Removed support for Django 1.11 and Python 2
#. Removed upper Django dependency constraint

2.0.6
-----
#. Added testing for Django 3 (no code changes needed).

2.0.5
-----
#. Added settings and kwargs that allow for the validation of reCAPTCHA v3 score values.

2.0.4
-----
#. Fixed travis tests for django 2.2

2.0.3
-----
#. Added testing for Django 2.2 (no code changes needed).

2.0.2
-----
#. Moved field based Google dev key check to an app ready registered security check.

2.0.1
-----

#. Bugfix: Remove extra div in widget_v3 template

2.0.0
-----

#. ReCAPTCHA v3 support added.
#. Remove all mention of the V1 reCAPTCHA endpoint.
#. Refactor client, fields and widgets code.
#. Added widgets for each type of reCAPTCHA: ``V2 Checkbox``, ``V2 Invisible``, ``V3``
#. Remove the need for the widget template to be selected based on certain settings values, each widget has its own template.
#. Introduced a large number of new unit tests, update tests to make use of tox venvs.
#. Regenerated po and mo files.

1.5.0 (2019-01-09)
------------------

#. Added testing for Django 2.1 (no code changes needed).
#. Update the unit tests to no longer make use of reCAPTCHA v1.
#. Added deprecation warnings for reCAPTCHA v1 support.
#. Remove the need for RECAPTCHA_TESTING environment variable during unit testing.
#. Added Invisible reCAPTCHA V2 support.

1.4.0 (2018-02-08)
------------------

#. Dropped support for Django < 1.11.
#. Added testing for Django 2.0 (no code changes needed).

1.3.1 (2017-06-27)
------------------

#. Fixed widget attributes regression for Django < 1.10.

1.3.0 (2017-04-10)
------------------

#. Support Django 1.11 in addition to 1.8, 1.9, and 1.10.


1.2.1 (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.