pyturnstile 0.3.0

A Python library for validating Cloudflare Turnstile tokens with async and sync support

PyTurnstile

A Python library for validating Cloudflare Turnstile tokens with both async and sync support.

Features

• 🔄 Async & Sync Support
• 🚀 Simple API
• 📦 Lightweight - Only requires httpx

What is PyTurnstile?

PyTurnstile simplifies Cloudflare Turnstile token validation. It handles all communication with Cloudflare's API.

Learn more at: https://developers.cloudflare.com/turnstile/

Installation

Install the package using your preferred dependency manager.

uv

uv add pyturnstile

pip

pip install pyturnstile

Usage

💡 TIP

You can follow this documentation and create your own Turnstile secret key at the Cloudflare Turnstile dashboard.

Quick Start

PyTurnstile provides two ways to validate tokens:

1. Using the Turnstile class (Recommended)

from pyturnstile import Turnstile

turnstile = Turnstile(secret="your-secret-key")

response = await turnstile.async_validate(token="user-token-from-frontend")

# or validate synchronously
# response = turnstile.validate(token="user-token-from-frontend")

if response.success:
    print("✅ Token is valid!")

2. Using functions directly

from pyturnstile import validate, async_validate

response = await async_validate(
    token="user-token-from-frontend",
    secret="your-secret-key"
)

# or validate synchronously
# response = validate(
#     token="user-token-from-frontend",
#     secret="your-secret-key"
# )

if response.success:
    print("✅ Token is valid!")

Optional Parameters

ℹ️ NOTE

For more details on all available parameters, see the Cloudflare documentation

response = turnstile.validate(
    token="user-token",               # The token from the client-side widget
    idempotency_key="unique-uuid",    # Optional: UUID for retry protection
    expected_remoteip="203.0.113.1",  # Optional: The visitor's IP address that the challenge response must match
    expected_hostname="example.com",  # Optional: The hostname that the challenge response must match
    expected_action="submit_form",    # Optional: The action identifier that the challenge must match
    timeout=10                        # Optional: request timeout in seconds
)

Response Object

ℹ️ NOTE

For more details on all response fields, see the Cloudflare documentation

The TurnstileResponse object contains:

response.success                   # bool: Whether validation succeeded
response.error_codes               # list[TurnstileErrorCodes]: Error codes (if any)
response.challenge_ts              # str: ISO timestamp of challenge completion
response.hostname                  # str: Hostname where challenge was served
response.action                    # str: Custom action identifier
response.cdata                     # str: Custom data payload from client-side
response.metadata["ephemeral_id"]  # Device fingerprint ID (Enterprise only)

Contributing

Any contributions are greatly appreciated. If you have a suggestion that would make this project better, please fork the repo and create a Pull Request. You can also open an issue.

License

Published under the MIT License.