or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdform-integration.mdindex.mdmodels-validation.mdrest-framework.mdviews-urls.md
tile.json

tessl/pypi-django-simple-captcha

A very simple, yet powerful, Django captcha application for adding CAPTCHA image challenges to forms

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/django-simple-captcha@0.6.x

To install, run

npx @tessl/cli install tessl/pypi-django-simple-captcha@0.6.0

index.mddocs/

Django Simple Captcha

A comprehensive Django captcha system that enables developers to add CAPTCHA image challenges to any Django form for enhanced security and spam prevention. Provides extensive customization options including custom challenge types, configurable image generation with noise and filter functions, text-to-speech audio output for accessibility compliance, and Ajax refresh capabilities.

Package Information

  • Package Name: django-simple-captcha
  • Language: Python
  • Framework: Django
  • Installation: pip install django-simple-captcha

Core Imports

from captcha.fields import CaptchaField

For package version information:

import captcha
print(captcha.VERSION)          # (0, 6, 2)
print(captcha.get_version())    # "0.6.2"

For models and validation:

from captcha.models import CaptchaStore
from captcha.validators import captcha_validate

For Django REST Framework integration:

from captcha.serializers import CaptchaSerializer, CaptchaModelSerializer

Basic Usage

# Add to INSTALLED_APPS in settings.py
INSTALLED_APPS = [
    # ... other apps
    'captcha',
]

# Include captcha URLs in your main urls.py
from django.urls import path, include

urlpatterns = [
    # ... other patterns
    path('captcha/', include('captcha.urls')),
]

# Add captcha field to any Django form
from django import forms
from captcha.fields import CaptchaField

class ContactForm(forms.Form):
    name = forms.CharField(max_length=100)
    email = forms.EmailField()
    message = forms.TextField()
    captcha = CaptchaField()

# In your view
def contact_view(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            # Process the form - captcha was validated automatically
            pass
    else:
        form = ContactForm()
    return render(request, 'contact.html', {'form': form})

Architecture

Django Simple Captcha uses a multi-layered architecture:

  • Form Fields & Widgets: CaptchaField and CaptchaTextInput provide Django form integration with automatic validation
  • Database Storage: CaptchaStore model manages captcha challenges, responses, and expiration
  • View Layer: Dedicated views serve captcha images, audio files, and AJAX refresh functionality
  • Challenge Generation: Pluggable system for creating different types of challenges (math, random text, dictionary words)
  • Image Processing: Configurable image generation with noise functions, filters, and styling options
  • REST Framework Integration: Serializers for API-based captcha validation

Capabilities

Package Version Information

Package-level version constants and utility functions for version checking and display.

VERSION = (0, 6, 2)               # tuple, semantic version components

def get_version():
    """
    Return the version as a human-format string.
    
    Returns:
    str: Version string like "0.6.2"
    """

Form Integration

Core Django form integration with CaptchaField for automatic captcha validation, customizable widgets, and seamless form processing.

class CaptchaField(MultiValueField):
    def __init__(*args, **kwargs): ...
    def clean(value): ...

class CaptchaTextInput(BaseCaptchaTextInput):
    def __init__(attrs=None, id_prefix=None, generator=None): ...
    def render(name, value, attrs=None, renderer=None): ...

Form Integration

Models and Validation

Database model for captcha storage with expiration management, validation functions, and pool generation for performance optimization.

class CaptchaStore(models.Model):
    challenge = models.CharField(max_length=32)
    response = models.CharField(max_length=32)
    hashkey = models.CharField(max_length=40, unique=True)
    expiration = models.DateTimeField()
    
    @classmethod
    def generate_key(generator=None): ...
    @classmethod
    def create_pool(count=1000): ...

def captcha_validate(hashkey, response): ...

Models and Validation

Views and URLs

View functions for serving captcha images with customizable scaling, audio output for accessibility, and AJAX refresh functionality.

def captcha_image(request, key, scale=1): ...
def captcha_audio(request, key): ...  
def captcha_refresh(request): ...

Views and URLs

Configuration and Customization

Comprehensive configuration system for customizing captcha appearance, challenge generation, noise functions, filters, and behavior.

# Configuration constants
CAPTCHA_FONT_SIZE: int
CAPTCHA_LETTER_ROTATION: tuple
CAPTCHA_BACKGROUND_COLOR: str
CAPTCHA_CHALLENGE_FUNCT: str
CAPTCHA_NOISE_FUNCTIONS: tuple
CAPTCHA_TIMEOUT: int

# Challenge generators
def math_challenge(): ...
def random_char_challenge(): ...
def word_challenge(): ...

# Noise and filter functions  
def noise_arcs(draw, image): ...
def noise_dots(draw, image): ...
def post_smooth(image): ...

Configuration and Customization

Django REST Framework Integration

Serializers for API-based captcha validation with both standalone and model-integrated serializers for REST API endpoints.

class CaptchaSerializer(serializers.Serializer):
    captcha_code = serializers.CharField(max_length=32, write_only=True, required=True)
    captcha_hashkey = serializers.CharField(max_length=40, write_only=True, required=True)
    
    def run_validation(data=empty): ...

class CaptchaModelSerializer(serializers.ModelSerializer):
    captcha_code = serializers.CharField(max_length=32, write_only=True, required=True)
    captcha_hashkey = serializers.CharField(max_length=40, write_only=True, required=True)

Django REST Framework Integration

Management Commands

Django management commands for captcha maintenance and optimization tasks.

class Command(BaseCommand):
    # captcha_clean command
    def handle(**options):
        """
        Clean up expired captcha records from database.
        
        Parameters:
        - options: dict, command options including verbosity
        
        Returns:
        None
        """

class Command(BaseCommand):
    # captcha_create_pool command  
    def handle(**options):
        """
        Create pool of captcha challenges for performance optimization.
        
        Parameters:
        - options: dict, including pool_size (int) and cleanup_expired (bool)
        
        Returns:
        None
        """
        
    def add_arguments(parser):
        """
        Add command-line arguments.
        
        Parameters:
        - parser: ArgumentParser instance
        """

# Usage examples:
# python manage.py captcha_clean
# python manage.py captcha_create_pool --pool-size=1000 --cleanup-expired