Install & Compatibility
Where this runs
tested against v0.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.068s · 41.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.2s · import 0.973s · 43MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Prelude
✓ from prelude_python_sdk import Prelude
Main synchronous client.
AsyncPrelude
✓ from prelude_python_sdk import AsyncPrelude
Main asynchronous client.
DefaultAioHttpClient
✓ from prelude_python_sdk import DefaultAioHttpClient
Required when initializing AsyncPrelude to use aiohttp as the backend.
This quickstart initializes the synchronous Prelude client using an API token from environment variables and demonstrates how to initiate a phone number verification. For asynchronous usage, import `AsyncPrelude` and use `await` with API calls.
import os
from prelude_python_sdk import Prelude
# It's recommended to set API_TOKEN as an environment variable (e.g., export API_TOKEN="your_token")
api_token = os.environ.get("API_TOKEN", "YOUR_DEFAULT_API_TOKEN")
if api_token == "YOUR_DEFAULT_API_TOKEN":
print("Warning: Please set the API_TOKEN environment variable or replace 'YOUR_DEFAULT_API_TOKEN' with your actual Prelude API token.")
try:
client = Prelude(api_token=api_token)
# Example: Create a phone number verification
verification = client.verification.create(
target={
"type": "phone_number",
"value": "+15551234567", # Replace with a valid test phone number
},
)
print(f"Successfully initiated verification with ID: {verification.id}")
# Example: Check a verification code (uncomment and replace with actual code/target)
# check_response = client.verification.check(
# target={
# "type": "phone_number",
# "value": "+15551234567",
# },
# code="123456", # Replace with the received verification code
# )
# print(f"Verification check successful for ID: {check_response.id}, status: {check_response.status}")
except Exception as e:
print(f"An error occurred during Prelude API interaction: {e}")
Debug
Known issues
breakingWhile generally following Semantic Versioning (SemVer), the library explicitly states that certain backwards-incompatible changes may be released as minor versions. These include changes to static types, internal library implementation, or changes not expected to affect the majority of users.fixUsers relying on strict type checking or undocumented internal APIs should review changelogs carefully before updating minor versions. Consider pinning to exact minor versions to avoid unexpected changes.
affects: All versions
gotchaThe library's Pydantic models might have compatibility issues with different major versions of Pydantic in your environment. Version 0.4.0 notably included a fix for 'pydantic v1: more robust Mod'.fixEnsure your project's Pydantic version is compatible with the SDK. If encountering model-related issues, try upgrading to the latest SDK version or adjusting your Pydantic version. The SDK is generated using Stainless, which often aligns with Pydantic v2.
affects: <0.4.0 (potential for issues), All versions (general compatibility care)
gotchaWhen using the asynchronous client, while `httpx` is the default HTTP backend, choosing `aiohttp` for potentially better concurrency requires an explicit extra installation (`pip install prelude-python-sdk[aiohttp]`) and explicit client instantiation with `http_client=DefaultAioHttpClient()`.fixTo use aiohttp, install the extra and pass `http_client=DefaultAioHttpClient()` to `AsyncPrelude`. Otherwise, `httpx` will be used, or an `ImportError` might occur if `aiohttp` classes are referenced without installation.
affects: All versions
gotchaHTTP client connections are closed automatically when the client object is garbage collected. However, in long-running applications or serverless functions, it's best practice to explicitly close the client to prevent resource leaks (e.g., open sockets).fixAlways use the client within a `with` statement (`with Prelude() as client: ...`) or explicitly call `client.close()` when the client is no longer needed, especially in async contexts.
affects: All versions
gotchaIn API responses, fields that are explicitly `null` in the JSON and fields that are entirely `missing` will both appear as `None` in Python. To differentiate between these two cases, you must check the `response.model_fields_set` property.fixIf `response.my_field is None` and `'my_field' not in response.model_fields_set`, the field was missing. Otherwise, if it's in `model_fields_set`, it was explicitly `null`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prelude_python_sdk'
The `prelude-python-sdk` package has not been installed or is not accessible in the current Python environment.
fixInstall the library using pip: `pip install prelude-python-sdk`
prelude_python_sdk.AuthenticationError: Authentication failed
The API token provided is invalid, expired, or missing, resulting in a 401 Unauthorized HTTP status code from the Prelude API.
fixEnsure you are using a valid and active API token. Set it either via the `API_TOKEN` environment variable or by passing `api_token='YOUR_API_TOKEN'` when initializing the client.
Example:
```python
import os
from prelude_python_sdk import Prelude
client = Prelude(api_token=os.environ.get("API_TOKEN"))
# Or directly:
# client = Prelude(api_token="YOUR_PRELUDE_API_TOKEN")
``` prelude_python_sdk.APIConnectionError: The server could not be reached
The client was unable to establish a network connection to the Prelude API, possibly due to network issues, DNS problems, or a timeout.
fixCheck your internet connection and ensure that the Prelude API endpoint is reachable. Review any firewall or proxy settings that might be blocking the connection. You can also inspect the `__cause__` attribute of the exception for the underlying `httpx` error for more details.
prelude_python_sdk.BadRequestError: The request was malformed
The request sent to the Prelude API contained invalid or missing parameters, or the data was not in the expected format, resulting in a 400 Bad Request HTTP status code.
fixReview the API method documentation and ensure all required parameters are provided with correct data types and formats. For instance, verify phone numbers are in E.164 format or UUIDs are valid.
prelude_python_sdk.RateLimitError: A 429 status code was received
Your application has exceeded the allowed rate limits for making requests to the Prelude API, causing the API to return a 429 Too Many Requests HTTP status code.
fixImplement exponential backoff or another rate-limiting strategy in your application to reduce the frequency of API calls. The Prelude SDK automatically retries certain errors, including 429, by default, but you might need to adjust `max_retries` or your application's call pattern.
Upgrade
Version history
0.13.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
aiohttpoptionalOptional dependency for the asynchronous client to use aiohttp as the HTTP backend for improved concurrency performance. Defaults to httpx.