From 047e032e1ade2988351d3b3a69fe4260c16f85d2 Mon Sep 17 00:00:00 2001 From: longhuan1999 <43313501+longhuan1999@users.noreply.github.com> Date: Mon, 25 Jan 2021 14:14:07 +0800 Subject: [PATCH 1/6] Upload Chinese Readme --- README_zh.md | 224 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 README_zh.md diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 0000000..b8fcbaa --- /dev/null +++ b/README_zh.md @@ -0,0 +1,224 @@ +# Django reCaptcha v3 [![Build Status](https://travis-ci.org/kbytesys/django-recaptcha3.svg?branch=master)](https://travis-ci.org/kbytesys/django-recaptcha2) +---- + +This integration app implements a recaptcha field for Google reCaptcha v3. + +**Warning:** this package is **not** compatible with django-recaptcha2 + +---- + +## How to install + +Install the required package from pip (or take the source and install it by yourself): + +```bash +pip install django-recaptcha3 +``` + +Then add django-recaptcha3 to your installed apps: + +```python +INSTALLED_APPS = ( + ... + 'snowpenguin.django.recaptcha3', + ... +) +``` + +And add your reCaptcha private and public key to your django settings.py and the default action name, recaptcha score threshold: + +```python +RECAPTCHA_PRIVATE_KEY = 'your private key' +RECAPTCHA_PUBLIC_KEY = 'your public key' +RECAPTCHA_DEFAULT_ACTION = 'generic' +RECAPTCHA_SCORE_THRESHOLD = 0.5 +# If you require reCaptcha to be loaded from somewhere other than https://google.com +# (e.g. to bypass firewall restrictions), you can specify what proxy to use. +# RECAPTCHA_FRONTEND_PROXY_HOST = 'https://recaptcha.net' + +``` + +If you have to create the apikey for the domains managed by your django project, you can visit this website. + +## Usage +### Form and Widget +You can simply create a reCaptcha enabled form with the field provided by this app: + +```python +from snowpenguin.django.recaptcha3.fields import ReCaptchaField + +class ExampleForm(forms.Form): + [...] + captcha = ReCaptchaField() + [...] +``` + +You can set the private key on the "private_key" argument of the field contructor if you want to override the one inside +your configuration. + +### Templating +You can use some template tags to simplify the reCaptcha adoption: + +* recaptcha_init: add the script tag for reCaptcha api. You have to put this tag somewhere in your "head" element +* recaptcha_ready: call the execute function when the api script is loaded +* recaptcha_execute: start the reCaptcha check and set the token from the api in your django forms. Token is valid for 120s, after this time it is automatically regenerated. +* recaptcha_key: if you want to use reCaptcha manually in your template, you will need the sitekey (a.k.a. public api key). + This tag returns a string with the configured public key. + +You can use the form as usual. + +### Samples +#### Simple + +Just create a form with the reCaptcha field and follow this template example: + +```django +{% load recaptcha3 %} + + + {% recaptcha_init %} + {% recaptcha_ready action_name='homepage' %} + + +
+ {% csrf_token %} + {{ form }} + +
+ + +``` + +#### Custom callback + +The callback can be used to allow to use the token received from the api in ajax calls or whatever + +```django +{% load recaptcha3 %} + + + + {% recaptcha_init %} + {% recaptcha_ready action_name='homepage' custom_callback='alertToken' %} + + +
+ {% csrf_token %} + {{ form }} + +
+ + +``` + +#### Multiple render example + +You can render multiple reCaptcha without any extra effort: + +```django +{% load recaptcha3 %} + + + {% recaptcha_init %} + {% recaptcha_ready action_name='homepage' %} + + +
+ {% csrf_token %} + {{ form1 }} + +
+
+ {% csrf_token %} + {{ form2 }} + +
+ + +``` + +#### Bare metal! + +You can use the plain javascript, just remember to set the correct value for the hidden field in the form + +```django + + + + + + +
+ {% csrf_token %} + {{ form }} + +
+ + +``` + + +## Settings + +If you want to use recaptcha's score you need to adjust the bot score threshold. + +django-recaptcha3 can adjust the bot score threshold as follows. The default value for the threshold is 0. + +```python +from snowpenguin.django.recaptcha3.fields import ReCaptchaField + +class ExampleForm(forms.Form): + [...] + captcha = ReCaptchaField(score_threshold=0.5) + [...] +``` + +## Testing +### Test unit support +You can't simulate api calls in your test, but you can disable the recaptcha field and let your test works. + +Just set the RECAPTCHA_DISABLE env variable in your test: + +```python +os.environ['RECAPTCHA_DISABLE'] = 'True' +``` + +Warning: you can use any word in place of "True", the clean function will check only if the variable exists. + +### Test unit with recaptcha3 disabled +```python +import os +import unittest + +from yourpackage.forms import MyForm + +class TestCase(unittest.TestCase): + def setUp(self): + os.environ['RECAPTCHA_DISABLE'] = 'True' + + def test_myform(self): + form = MyForm({ + 'field1': 'field1_value' + }) + self.assertTrue(form.is_valid()) + + def tearDown(self): + del os.environ['RECAPTCHA_DISABLE'] +``` From 5d9cce0890f20143e93523f7bf6c0aa625a1e21b Mon Sep 17 00:00:00 2001 From: longhuan1999 <43313501+longhuan1999@users.noreply.github.com> Date: Mon, 25 Jan 2021 15:27:00 +0800 Subject: [PATCH 2/6] Update README_zh.md --- README_zh.md | 74 ++++++++++++++++++++++++++-------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/README_zh.md b/README_zh.md index b8fcbaa..6949ca0 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,21 +1,21 @@ # Django reCaptcha v3 [![Build Status](https://travis-ci.org/kbytesys/django-recaptcha3.svg?branch=master)](https://travis-ci.org/kbytesys/django-recaptcha2) ---- -This integration app implements a recaptcha field for Google reCaptcha v3. +这个集成应用在Django上为 Google reCaptcha v3 实现了一个 recaptcha 字段。 -**Warning:** this package is **not** compatible with django-recaptcha2 +**警告：** 此软件包与 django-recaptcha2 **不兼容** ---- -## How to install +## 如何安装 -Install the required package from pip (or take the source and install it by yourself): +通过 pip 安装所需的软件包 （或下载源码自行安装）： ```bash pip install django-recaptcha3 ``` -Then add django-recaptcha3 to your installed apps: +然后将 django-recaptcha3 添加到你 Django 项目配置文件的 installed apps 中： ```python INSTALLED_APPS = ( @@ -25,24 +25,24 @@ INSTALLED_APPS = ( ) ``` -And add your reCaptcha private and public key to your django settings.py and the default action name, recaptcha score threshold: +并将您的 reCaptcha 私钥和公钥添加到你 Django 项目的 settings.py 中并设置 RECAPTCHA_DEFAULT_ACTION （recaptcha默认操作名）和 RECAPTCHA_SCORE_THRESHOLD （recaptcha分数阈值）： ```python RECAPTCHA_PRIVATE_KEY = 'your private key' RECAPTCHA_PUBLIC_KEY = 'your public key' RECAPTCHA_DEFAULT_ACTION = 'generic' RECAPTCHA_SCORE_THRESHOLD = 0.5 -# If you require reCaptcha to be loaded from somewhere other than https://google.com -# (e.g. to bypass firewall restrictions), you can specify what proxy to use. +# 如果您需要从其它地方加载 reCaptcha，而不是 https://google.com +# （比如：绕过防火墙限制）， 你可以指定要使用的代理。 # RECAPTCHA_FRONTEND_PROXY_HOST = 'https://recaptcha.net' ``` -If you have to create the apikey for the domains managed by your django project, you can visit this website. +如果你需要为你的 django 项目所用到的的域名创建 apikey ，则可以访问此网站。 -## Usage -### Form and Widget -You can simply create a reCaptcha enabled form with the field provided by this app: +## 用法 +### 表单和控件 +您可以使用此应用程序提供的字段便捷地创建一个包含 reCaptcha 的表单： ```python from snowpenguin.django.recaptcha3.fields import ReCaptchaField @@ -53,24 +53,22 @@ class ExampleForm(forms.Form): [...] ``` -You can set the private key on the "private_key" argument of the field contructor if you want to override the one inside -your configuration. +如果你不想用 settings.py 中设置的私钥，可以在字段中添加 "private_key" 参数来指定私钥。 -### Templating -You can use some template tags to simplify the reCaptcha adoption: +### 使用模板 +您可以使用一些模板标签来简化 reCaptcha 的使用： -* recaptcha_init: add the script tag for reCaptcha api. You have to put this tag somewhere in your "head" element -* recaptcha_ready: call the execute function when the api script is loaded -* recaptcha_execute: start the reCaptcha check and set the token from the api in your django forms. Token is valid for 120s, after this time it is automatically regenerated. -* recaptcha_key: if you want to use reCaptcha manually in your template, you will need the sitekey (a.k.a. public api key). - This tag returns a string with the configured public key. +* recaptcha_init: ：为 reCaptcha api 添加 script 标签，您必须将此标签放在 "head" 元素中的某个位置 +* recaptcha_ready: ：api script 加载完毕时执行函数 +* recaptcha_execute: 启动 reCaptcha 检查，并从 django forms 中的 api 设置 token 。 token 有效时间为120秒，此时间过后会自动重新生成。 +* recaptcha_key: 如果要在模板中手动使用 reCaptcha 而不通过 forms ，则需要 sitekey（又名 public api key）。此标签将返回带有配置公钥的字符串。 -You can use the form as usual. +您可以照常使用该表单。 -### Samples +### 示例 #### Simple -Just create a form with the reCaptcha field and follow this template example: +只需使用 reCaptcha 字段创建一个表单，然后遵循以下模板示例： ```django {% load recaptcha3 %} @@ -91,7 +89,7 @@ Just create a form with the reCaptcha field and follow this template example: #### Custom callback -The callback can be used to allow to use the token received from the api in ajax calls or whatever +The callback 可用于允许通过 ajax calls 或其他方式使用从 api 获得的 token ```django {% load recaptcha3 %} @@ -108,7 +106,7 @@ The callback can be used to allow to use the token received from the api in ajax
{% csrf_token %} - {{ form }} + {{ form }} // 表单中的 reCaptcha 字段
@@ -117,7 +115,7 @@ The callback can be used to allow to use the token received from the api in ajax #### Multiple render example -You can render multiple reCaptcha without any extra effort: +不需要额外的设置您便可以渲染多个 reCaptcha ： ```django {% load recaptcha3 %} @@ -129,12 +127,12 @@ You can render multiple reCaptcha without any extra effort:
{% csrf_token %} - {{ form1 }} + {{ form1 }} // 表单1中的 reCaptcha 字段
{% csrf_token %} - {{ form2 }} + {{ form2 }} // 表单2中的 reCaptcha 字段
@@ -143,7 +141,7 @@ You can render multiple reCaptcha without any extra effort: #### Bare metal! -You can use the plain javascript, just remember to set the correct value for the hidden field in the form +您可以直接使用 javascript ，只需记得为表单中的隐藏字段设置正确的值 ```django @@ -175,11 +173,13 @@ You can use the plain javascript, just remember to set the correct value for the ``` -## Settings +## 设置 + +如果要设置 recaptcha 的 score ，则需要调整 bot score 阈值。 -If you want to use recaptcha's score you need to adjust the bot score threshold. +django-recaptcha3 可以按照下方示例调整 bot score 阈值。阈值的取值区间为 0~1，默认值为 0。 -django-recaptcha3 can adjust the bot score threshold as follows. The default value for the threshold is 0. +1 表示有极大可能是人类，0 则表示很可能是机器人，当用户访问时被评分的值小于您设置的值时用户将被拦截，谷歌建议设置 0.5。 ```python from snowpenguin.django.recaptcha3.fields import ReCaptchaField @@ -190,17 +190,17 @@ class ExampleForm(forms.Form): [...] ``` -## Testing +## 测试 ### Test unit support -You can't simulate api calls in your test, but you can disable the recaptcha field and let your test works. +您无法在测试中模拟 api 调用，但是可以禁用 recaptcha 字段来进行测试工作。 -Just set the RECAPTCHA_DISABLE env variable in your test: +只需在测试中设置 RECAPTCHA_DISABLE env 变量即可： ```python os.environ['RECAPTCHA_DISABLE'] = 'True' ``` -Warning: you can use any word in place of "True", the clean function will check only if the variable exists. +警告：您可以使用任何单词代替 "True" ，clean 函数将仅检查变量是否存在。 ### Test unit with recaptcha3 disabled ```python From 1dda728fc7a77a4bc2dcb74d0c88779d24deabe3 Mon Sep 17 00:00:00 2001 From: longhuan1999 <43313501+longhuan1999@users.noreply.github.com> Date: Mon, 25 Jan 2021 15:30:24 +0800 Subject: [PATCH 3/6] Update README_zh.md --- README_zh.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README_zh.md b/README_zh.md index 6949ca0..eb8615b 100644 --- a/README_zh.md +++ b/README_zh.md @@ -15,7 +15,7 @@ pip install django-recaptcha3 ``` -然后将 django-recaptcha3 添加到你 Django 项目配置文件的 installed apps 中： +然后将 django-recaptcha3 添加到您 Django 项目配置文件的 installed apps 中： ```python INSTALLED_APPS = ( @@ -25,7 +25,7 @@ INSTALLED_APPS = ( ) ``` -并将您的 reCaptcha 私钥和公钥添加到你 Django 项目的 settings.py 中并设置 RECAPTCHA_DEFAULT_ACTION （recaptcha默认操作名）和 RECAPTCHA_SCORE_THRESHOLD （recaptcha分数阈值）： +并将您的 reCaptcha 私钥和公钥添加到您 Django 项目的 settings.py 中并设置 RECAPTCHA_DEFAULT_ACTION （recaptcha默认操作名）和 RECAPTCHA_SCORE_THRESHOLD （recaptcha分数阈值）： ```python RECAPTCHA_PRIVATE_KEY = 'your private key' @@ -38,7 +38,7 @@ RECAPTCHA_SCORE_THRESHOLD = 0.5 ``` -如果你需要为你的 django 项目所用到的的域名创建 apikey ，则可以访问此网站。 +如果需要为您的 django 项目所用到的的域名创建 apikey ，则可以访问此网站。 ## 用法 ### 表单和控件 @@ -53,7 +53,7 @@ class ExampleForm(forms.Form): [...] ``` -如果你不想用 settings.py 中设置的私钥，可以在字段中添加 "private_key" 参数来指定私钥。 +如果您不想用 settings.py 中设置的私钥，可以在字段中添加 "private_key" 参数来指定私钥。 ### 使用模板 您可以使用一些模板标签来简化 reCaptcha 的使用： From 903e8014cd6dd6f3e9b77e314bbf5ce69095df4f Mon Sep 17 00:00:00 2001 From: longhuan1999 <43313501+longhuan1999@users.noreply.github.com> Date: Mon, 25 Jan 2021 20:45:17 +0800 Subject: [PATCH 4/6] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index b8fcbaa..f06b1c7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Django reCaptcha v3 [![Build Status](https://travis-ci.org/kbytesys/django-recaptcha3.svg?branch=master)](https://travis-ci.org/kbytesys/django-recaptcha2) +##### [Chinese README](https://github.com/longhuan1999/django-recaptcha3/blob/master/README_zh.md) ---- This integration app implements a recaptcha field for Google reCaptcha v3. From f49af7fa83e7e70a1a4b39ac4b57d6ff4cda308f Mon Sep 17 00:00:00 2001 From: longhuan1999 <43313501+longhuan1999@users.noreply.github.com> Date: Mon, 25 Jan 2021 22:53:17 +0800 Subject: [PATCH 5/6] Update README_zh.md --- README_zh.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/README_zh.md b/README_zh.md index eb8615b..e5a1df2 100644 --- a/README_zh.md +++ b/README_zh.md @@ -33,11 +33,31 @@ RECAPTCHA_PUBLIC_KEY = 'your public key' RECAPTCHA_DEFAULT_ACTION = 'generic' RECAPTCHA_SCORE_THRESHOLD = 0.5 # 如果您需要从其它地方加载 reCaptcha，而不是 https://google.com -# （比如：绕过防火墙限制）， 你可以指定要使用的代理。 +# （比如：绕过防火墙限制）， 你可以指定要使用的代理，此处设置仅会修改前端加载 reCaptcha。 # RECAPTCHA_FRONTEND_PROXY_HOST = 'https://recaptcha.net' ``` +**如果你的服务器在国内，则还需要修改 django-recaptcha3 的源码：** + + 1. 请先 pip uninstall django-recaptcha3 进行卸载， 然后下载 release 中的源码压缩包。 + + 2. 修改 django-recaptcha3-master\snowpenguin\django\recaptcha3\fields.py#38 : + +```python + try: + r = requests.post( + 'https://www.google.com/recaptcha/api/siteverify', // https://www.recaptcha.net/recaptcha/api/siteverify + { + 'secret': self._private_key, + 'response': response_token + }, + timeout=5 + ) +``` + + 3. 在 django-recaptcha3-master 目录下执行 pip install . 。 + 如果需要为您的 django 项目所用到的的域名创建 apikey ，则可以访问此网站。 ## 用法 From 5010dc3eb03978eea5630e5a5585c93d499baea2 Mon Sep 17 00:00:00 2001 From: longhuan1999 <43313501+longhuan1999@users.noreply.github.com> Date: Mon, 25 Jan 2021 22:56:33 +0800 Subject: [PATCH 6/6] Update README_zh.md --- README_zh.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README_zh.md b/README_zh.md index e5a1df2..852f024 100644 --- a/README_zh.md +++ b/README_zh.md @@ -33,7 +33,7 @@ RECAPTCHA_PUBLIC_KEY = 'your public key' RECAPTCHA_DEFAULT_ACTION = 'generic' RECAPTCHA_SCORE_THRESHOLD = 0.5 # 如果您需要从其它地方加载 reCaptcha，而不是 https://google.com -# （比如：绕过防火墙限制）， 你可以指定要使用的代理，此处设置仅会修改前端加载 reCaptcha。 +# （比如：绕过防火墙限制）， 你可以通过以下设置指定要使用的代理，但此设置仅会修改前端加载 reCaptcha 的途径。 # RECAPTCHA_FRONTEND_PROXY_HOST = 'https://recaptcha.net' ``` @@ -47,7 +47,7 @@ RECAPTCHA_SCORE_THRESHOLD = 0.5 ```python try: r = requests.post( - 'https://www.google.com/recaptcha/api/siteverify', // https://www.recaptcha.net/recaptcha/api/siteverify + 'https://www.google.com/recaptcha/api/siteverify', // 此处域名改为 www.recaptcha.net { 'secret': self._private_key, 'response': response_token