Django

Das Paket myra-eucaptcha-django stellt ein Formularfeld, ein Widget und eine Verwaltung der Konfigurationen im Administrationsbereich von Django bereit.

Voraussetzungen

Die folgenden Voraussetzungen sind erfüllt:

Voraussetzung	Wert
Python	ab Version 3.9
Django	ab Version 4.2
Paketverwaltung	pip oder uv
Zugang	Administrationsbereich von Django
Zugangsdaten	Öffentlicher Sitekey und Secret aus der Ansicht Details

Paket installieren

Um das Paket einzurichten, gehen Sie wie folgt vor:

• ► Installieren Sie das Paket:

pip install myra-eucaptcha-django

Mit der Paketverwaltung uv lautet der Befehl:

uv add myra-eucaptcha-django

• ► Tragen Sie die Anwendung in settings.py ein:

# settings.py
INSTALLED_APPS = [
    ...
    'myra_eucaptcha_django',
]

• ► Führen Sie die Migrationen aus:

python manage.py migrate

• ➔ Der Administrationsbereich zeigt den Eintrag Captcha Configurations an.

Konfiguration anlegen

Um eine Konfiguration anzulegen, gehen Sie wie folgt vor:

• ► Öffnen Sie im Administrationsbereich den Eintrag Captcha Configurations.
• ► Legen Sie eine Konfiguration mit Ihrem Sitekey und Ihrem Secret an.
• ► Markieren Sie das Kontrollkästchen Is default, damit Formulare die Konfiguration ohne Angabe eines Namens verwenden.
• ➔ Die Konfiguration steht in den Formularen zur Verfügung.

Feld in ein Formular einbauen

Ergänzen Sie das Formular um das Feld CaptchaField und um CaptchaFormMixin:

from django import forms
from myra_eucaptcha_django import CaptchaField, CaptchaFormMixin

class ContactForm(CaptchaFormMixin, forms.Form):
    name = forms.CharField()
    email = forms.EmailField()
    message = forms.CharField(widget=forms.Textarea)

    # Uses the default configuration
    captcha = CaptchaField()

Übergeben Sie in der Ansicht die Anfrage, damit das Feld die IP-Adresse des Besuchers prüfen kann:

from django.shortcuts import render, redirect
from .forms import ContactForm

def contact_view(request):
    if request.method == "POST":
        # Pass request= to enable IP validation
        form = ContactForm(request.POST, request=request)
        if form.is_valid():
            # Process the form
            return redirect("success")
    else:
        form = ContactForm()

    return render(request, "contact.html", {"form": form})

Zeichnen Sie das Formular in der Vorlage:

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Send</button>
</form>

Das Widget bringt das erforderliche JavaScript selbst mit.

Mehrere Konfigurationen verwenden

Sie legen im Administrationsbereich mehrere Konfigurationen mit eindeutigen Namen an, zum Beispiel default, contact-form und registration. Im Formular geben Sie den Namen der gewünschten Konfiguration an:

class ContactForm(CaptchaFormMixin, forms.Form):
    name = forms.CharField()
    captcha = CaptchaField("contact-form")

class RegistrationForm(CaptchaFormMixin, forms.Form):
    username = forms.CharField()
    captcha = CaptchaField("registration")

class CommentForm(CaptchaFormMixin, forms.Form):
    comment = forms.CharField()
    captcha = CaptchaField()  # Uses default configuration

Felder einer Konfiguration

Die folgenden Felder stehen zur Verfügung:

Feld	Vorgabe	Wirkung
name	erforderlich	Eindeutiger Name der Konfiguration.
description	—	Freie Notiz zur Verwendung.
sitekey	erforderlich	Öffentlicher Sitekey für das Widget.
secret	erforderlich	Geheimer Schlüssel für die serverseitige Prüfung.
is_default	False	Verwendet die Konfiguration, wenn das Formular keinen Namen angibt.
is_active	True	Gibt die Konfiguration zur Verwendung frei.

Die folgenden Felder ändern die Adressen der Dienste:

Feld	Vorgabe	Wirkung
verify_url	https://api.eu-captcha.eu/v1/verify/	Adresse des Endpunkts für die Prüfung.
widget_url	https://cdn.eu-captcha.eu/verify.js	Adresse des Skripts für das Widget.

Die folgenden Felder setzen die Zeitgrenzen in Sekunden:

Feld	Vorgabe	Wirkung
connect_timeout	3	Zeitgrenze für den Verbindungsaufbau.
read_timeout	10	Zeitgrenze für das Lesen der Antwort.
write_timeout	10	Zeitgrenze für das Senden der Anfrage.
pool_timeout	3	Zeitgrenze für eine freie Verbindung aus dem Verbindungsspeicher.

Die folgenden Felder steuern das Verhalten bei Fehlern:

Feld	Vorgabe	Wirkung
default_result_on_error	True	Gibt bei einem Netzwerkfehler ein positives Ergebnis zurück und lässt die Absendung zu.
suppress_exceptions	True	Unterdrückt Ausnahmen und gibt stattdessen das Ergebnis zurück.

Konfiguration über die Einstellungen

Statt der Datenbank verwenden Sie die Datei settings.py:

# settings.py
EUCAPTCHA_SITEKEY = "EUCAPTCHA_SITE_KEY"
EUCAPTCHA_SECRET = "EUCAPTCHA_SECRET_KEY"

# Optional
EUCAPTCHA_VERIFY_URL = "https://api.eu-captcha.eu/v1/verify/"
EUCAPTCHA_WIDGET_URL = "https://cdn.eu-captcha.eu/verify.js"
EUCAPTCHA_CONNECT_TIMEOUT = 3
EUCAPTCHA_READ_TIMEOUT = 10
EUCAPTCHA_WRITE_TIMEOUT = 10
EUCAPTCHA_POOL_TIMEOUT = 3
EUCAPTCHA_DEFAULT_RESULT_ON_ERROR = True
EUCAPTCHA_SUPPRESS_EXCEPTIONS = True

Konfigurationen aus der Datenbank haben Vorrang vor den Einstellungen.

Schnittstelle

Baustein	Verwendung
CaptchaField(config_name=None, **kwargs)	Formularfeld, das das Widget zeichnet und die Antwort prüft. Ohne config_name gilt die Standardkonfiguration.
CaptchaFormMixin	Reicht die Anfrage an die Felder weiter, damit die IP-Adresse geprüft werden kann.
CaptchaWidget	Zeichnet die Challenge. Der Baustein wird in der Regel nicht selbst verwendet.
validate_captcha(...)	Prüft ein Token unmittelbar. Bei einem Fehler löst die Funktion django.core.exceptions.ValidationError aus.
Vorlagen-Tags der Bibliothek eucaptcha	Zeichnen das Widget in einer Vorlage ohne CaptchaField: eucaptcha_script gibt den Skript-Verweis aus, eucaptcha_widget das Element des Widgets, eucaptcha_full beides. Die Tags verwenden die Standardkonfiguration. eucaptcha_widget und eucaptcha_full nehmen wahlweise einen eigenen sitekey an.

from myra_eucaptcha_django import validate_captcha

validate_captcha(
    token="captcha-response-token",
    remote_addr="client-ip",  # Optional
    config_name="my-config",  # Optional
)

Vollständiges Beispiel

Siehe HTML und Django.