[](https://github.com/somiona/django_cap/actions/workflows/test.yml)
[](https://github.com/somiona/django_cap/actions)
[](https://github.com/Somiona/django_cap/releases)
[](https://pypi.org/project/django_cap/)
[](https://pypi.org/project/django-cap/)
## Django Cap
This is a implementation of [Cap.js](https://capjs.js.org/) Server for Django, which provides challenge generation and verification for PoW (Proof of Work) captcha. See
## Usage
### Installation
To install the package, simply run:
```bash
pip install django-cap
```
If you want to use the Django Ninja integration, you can install it with:
```bash
pip install django-cap[ninja]
```
Or if you want to use the Django Rest Framework integration, you can install it with:
```bash
pip install django-cap[drf]
```
**TODO**: only ninja integration and vanilla Django Json views are implemented, DRF integration will be added in the future.
### Configuration
To use this package, you need to add `django_cap` to your `INSTALLED_APPS` in your Django settings file:
```python
INSTALLED_APPS = [
...
'django_cap',
'django_cap.ninja', # Add this if you want enable ninja integration
]
```
You need to configure the url patterns in your Django project's `urls.py` file:
```python
from django_cap.example_views import urls as example_views_urls
# import examples if you want to see them
urlpatterns = [
...
path("cap/", include("django_cap.urls")),
path("cap/examples/", include(example_views_urls)), # add this if you want to see examples
...
]
```
You can access the api at `/cap/v1/[challenge|redeem|validate]` endpoints. This is compatible with Cap.js/widgets. If your frontend is not hosted by Django, you need to refer Cap.js documentation for the installation, and simply configure the api endpoint as following:
```html
<cap-widget id="cap" data-cap-api-endpoint="https://your-api-site/cap/v1/"></cap-widget>
```
By default, ninja doc will be avaliable at `/cap/v1/docs/` and `/cap/v1/openapi.json`. If you want to disable the ninja doc, you can disable it in your Django settings file:
```python
#django_settings.py
...
CAP_NINJA_API_ENABLE_DOCS = False
...
```
### Use with Django Templates and Forms
This package provides comprehensive Django form integration for CAP verification. You can easily add CAP verification to any Django form:
#### Basic Form Integration
1. Add `CapField` to your form:
```python
from django import forms
from django_cap.forms import CapField
class MyForm(forms.Form):
name = forms.CharField(max_length=100)
email = forms.EmailField()
# Add CapField for CAP verification
cap_token = CapField(help_text="Please retry the verification challenge.")
```
2. In your template, render the form as usual:
```html
<form method="post">
{% csrf_token %}
{{ form.name.label_tag }} {{ form.name }}
{{ form.email.label_tag }} {{ form.email }}
{{ form.cap_token.label_tag }} {{ form.cap_token }}
{% if form.cap_token.errors %}
<div class="form-errors">
{% for error in form.cap_token.errors %}<div class="error">{{ error }}</div>{% endfor %}
</div>
{% endif %}
<button type="submit">Submit</button>
</form>
```
That's it! The `CapField` will automatically handle the CAP verification process, including generating the challenge and validating the response.
### Configuration Options
- `CAP_NINJA_API_ENABLE_DOCS`: Enable or disable the ninja API docs. Default is `True`.
- `CAP_CHALLENGE_COUNT`: The number of answer required for one challenge. Default is 50.
- `CAP_CHALLENGE_SIZE`: The size of the challenge string. Default is 32.
- `CAP_CHALLENGE_DIFFICULTY`: The difficulty of the challenge, Default is 4
- `CAP_CHALLENGE_EXPIRES_S`: The expiration time of the challenge in seconds. Default is 30 seconds.
- `CAP_TOKEN_EXPIRES_S`: The expiration time of the token in seconds. Default is 10 minutes.
- `CAP_CLEANUP_INTERVAL_S`: The interval for cleaning up expired challenges and tokens in seconds. Default is 60 seconds.
## Dev environment setup
1. Clone this repository.
2. Make sure you have python 3.13 installed.
```bash
python --version
```
3. Make sure you have uv installed.
```bash
# for MacOS, recommend using homebrew
brew install uv
```
```bash
# for Linux, recommend using their installer
# curl
curl -LsSf https://astral.sh/uv/install.sh | sh
# wget
wget -qO- https://astral.sh/uv/install.sh | sh
```
```powershell
# for Windows, recommend using WinGet
winget install --id=astral-sh.uv -e
# you can also use scoop
scoop install main/uv
```
4. Install the dependencies:
```bash
uv sync
```
5. Activate the virtual environment:
```bash
# for linux/macOS
source .venv/bin/activate
```
```powershell
# for windows
.\.venv\Scripts\Activate.ps1
```
6. Run tests:
```bash
uv run pytest
```
7. Run linting and formatting:
```bash
# Check code quality
uv run ruff check
# Format code
uv run ruff format
```
8. Build the package:
```bash
uv run pdm build
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## Links
- [GitHub Repository](https://github.com/somiona/django-cap)
- [PyPI Package](https://pypi.org/project/django-cap/)
- [Cap.js Project](https://capjs.js.org/)
Raw data
{
"_id": null,
"home_page": null,
"name": "django-cap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "django, captcha, proof-of-work, cap, security",
"author": null,
"author_email": "Somiona <somionat@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/4a/8441a11d922d8a0c059b55f7a0fc5ed4bc7b50b0524bec478a3d7f8e2ef1/django_cap-0.2.0.tar.gz",
"platform": null,
"description": "[](https://github.com/somiona/django_cap/actions/workflows/test.yml)\n[](https://github.com/somiona/django_cap/actions)\n[](https://github.com/Somiona/django_cap/releases)\n[](https://pypi.org/project/django_cap/)\n[](https://pypi.org/project/django-cap/)\n## Django Cap\nThis is a implementation of [Cap.js](https://capjs.js.org/) Server for Django, which provides challenge generation and verification for PoW (Proof of Work) captcha. See\n\n## Usage\n### Installation\nTo install the package, simply run:\n```bash\npip install django-cap\n```\n\nIf you want to use the Django Ninja integration, you can install it with:\n```bash\npip install django-cap[ninja]\n```\n\nOr if you want to use the Django Rest Framework integration, you can install it with:\n```bash\npip install django-cap[drf]\n```\n\n**TODO**: only ninja integration and vanilla Django Json views are implemented, DRF integration will be added in the future.\n\n### Configuration\nTo use this package, you need to add `django_cap` to your `INSTALLED_APPS` in your Django settings file:\n```python\nINSTALLED_APPS = [\n ...\n 'django_cap',\n 'django_cap.ninja', # Add this if you want enable ninja integration\n]\n```\n\nYou need to configure the url patterns in your Django project's `urls.py` file:\n```python\nfrom django_cap.example_views import urls as example_views_urls\n# import examples if you want to see them\n\n\nurlpatterns = [\n ...\n path(\"cap/\", include(\"django_cap.urls\")),\n path(\"cap/examples/\", include(example_views_urls)), # add this if you want to see examples\n ...\n]\n```\n\nYou can access the api at `/cap/v1/[challenge|redeem|validate]` endpoints. This is compatible with Cap.js/widgets. If your frontend is not hosted by Django, you need to refer Cap.js documentation for the installation, and simply configure the api endpoint as following:\n```html\n<cap-widget id=\"cap\" data-cap-api-endpoint=\"https://your-api-site/cap/v1/\"></cap-widget>\n```\n\nBy default, ninja doc will be avaliable at `/cap/v1/docs/` and `/cap/v1/openapi.json`. If you want to disable the ninja doc, you can disable it in your Django settings file:\n\n```python\n#django_settings.py\n...\nCAP_NINJA_API_ENABLE_DOCS = False\n...\n```\n\n### Use with Django Templates and Forms\n\nThis package provides comprehensive Django form integration for CAP verification. You can easily add CAP verification to any Django form:\n\n#### Basic Form Integration\n\n1. Add `CapField` to your form:\n\n```python\nfrom django import forms\nfrom django_cap.forms import CapField\nclass MyForm(forms.Form):\n name = forms.CharField(max_length=100)\n email = forms.EmailField()\n # Add CapField for CAP verification\n cap_token = CapField(help_text=\"Please retry the verification challenge.\")\n```\n\n2. In your template, render the form as usual:\n\n```html\n<form method=\"post\">\n {% csrf_token %}\n {{ form.name.label_tag }} {{ form.name }}\n {{ form.email.label_tag }} {{ form.email }}\n {{ form.cap_token.label_tag }} {{ form.cap_token }}\n {% if form.cap_token.errors %}\n <div class=\"form-errors\">\n {% for error in form.cap_token.errors %}<div class=\"error\">{{ error }}</div>{% endfor %}\n </div>\n {% endif %}\n <button type=\"submit\">Submit</button>\n</form>\n```\nThat's it! The `CapField` will automatically handle the CAP verification process, including generating the challenge and validating the response.\n\n### Configuration Options\n- `CAP_NINJA_API_ENABLE_DOCS`: Enable or disable the ninja API docs. Default is `True`.\n- `CAP_CHALLENGE_COUNT`: The number of answer required for one challenge. Default is 50.\n- `CAP_CHALLENGE_SIZE`: The size of the challenge string. Default is 32.\n- `CAP_CHALLENGE_DIFFICULTY`: The difficulty of the challenge, Default is 4\n- `CAP_CHALLENGE_EXPIRES_S`: The expiration time of the challenge in seconds. Default is 30 seconds.\n- `CAP_TOKEN_EXPIRES_S`: The expiration time of the token in seconds. Default is 10 minutes.\n- `CAP_CLEANUP_INTERVAL_S`: The interval for cleaning up expired challenges and tokens in seconds. Default is 60 seconds.\n\n\n## Dev environment setup\n1. Clone this repository.\n2. Make sure you have python 3.13 installed.\n ```bash\n python --version\n ```\n3. Make sure you have uv installed.\n ```bash\n # for MacOS, recommend using homebrew\n brew install uv\n ```\n ```bash\n # for Linux, recommend using their installer\n # curl\n curl -LsSf https://astral.sh/uv/install.sh | sh\n # wget\n wget -qO- https://astral.sh/uv/install.sh | sh\n ```\n ```powershell\n # for Windows, recommend using WinGet\n winget install --id=astral-sh.uv -e\n # you can also use scoop\n scoop install main/uv\n ```\n4. Install the dependencies:\n ```bash\n uv sync\n ```\n\n5. Activate the virtual environment:\n ```bash\n # for linux/macOS\n source .venv/bin/activate\n ```\n ```powershell\n # for windows\n .\\.venv\\Scripts\\Activate.ps1\n ```\n\n6. Run tests:\n ```bash\n uv run pytest\n ```\n\n7. Run linting and formatting:\n ```bash\n # Check code quality\n uv run ruff check\n\n # Format code\n uv run ruff format\n ```\n\n8. Build the package:\n ```bash\n uv run pdm build\n ```\n\n## Contributing\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Links\n- [GitHub Repository](https://github.com/somiona/django-cap)\n- [PyPI Package](https://pypi.org/project/django-cap/)\n- [Cap.js Project](https://capjs.js.org/)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Django implementation of Cap.js Server for Proof of Work captcha",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/somiona/django-cap/issues",
"Documentation": "https://github.com/somiona/django-cap#readme",
"Homepage": "https://github.com/somiona/django-cap",
"Repository": "https://github.com/somiona/django-cap"
},
"split_keywords": [
"django",
" captcha",
" proof-of-work",
" cap",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e11b3ae0399773487dff51a1e6ba3ec8cb4766677dd0fa5b802f5037ae8e4ff8",
"md5": "9d128fdfafc2adf0a22723056d4f16bd",
"sha256": "340000135585c0bfffd52595f0bbddc448d9ae531bec355f2629d94cb3c4d6df"
},
"downloads": -1,
"filename": "django_cap-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d128fdfafc2adf0a22723056d4f16bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 31100,
"upload_time": "2025-07-12T11:09:03",
"upload_time_iso_8601": "2025-07-12T11:09:03.024271Z",
"url": "https://files.pythonhosted.org/packages/e1/1b/3ae0399773487dff51a1e6ba3ec8cb4766677dd0fa5b802f5037ae8e4ff8/django_cap-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f94a8441a11d922d8a0c059b55f7a0fc5ed4bc7b50b0524bec478a3d7f8e2ef1",
"md5": "0f57aa1b9e1e5b9dd014ee1799a5f287",
"sha256": "1c6694884882469e00d5d14a5aaa696d1c8230f1c34978361a1ada52cfaa9a32"
},
"downloads": -1,
"filename": "django_cap-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "0f57aa1b9e1e5b9dd014ee1799a5f287",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 25868,
"upload_time": "2025-07-12T11:09:04",
"upload_time_iso_8601": "2025-07-12T11:09:04.454973Z",
"url": "https://files.pythonhosted.org/packages/f9/4a/8441a11d922d8a0c059b55f7a0fc5ed4bc7b50b0524bec478a3d7f8e2ef1/django_cap-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 11:09:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "somiona",
"github_project": "django-cap",
"github_not_found": true,
"lcname": "django-cap"
}
JSON
