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 müssen erfüllt sein:

Voraussetzung	Wert
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 die Konfiguration als Default, damit Formulare sie 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.

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.