Prelude Python SDK

0.11.0 · active · verified Sat Apr 11

The `prelude-python-sdk` is the official Python library for interacting with the Prelude API. It provides convenient access to Prelude's REST API from any Python 3.9+ application, offering type definitions for all request parameters and response fields. The library supports both synchronous and asynchronous clients, powered by httpx, and is generated with Stainless. Currently at version 0.11.0, it maintains a rapid release cadence with updates typically every 1-3 months.

Warnings

breaking While 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.
Fix: Users 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.
gotcha The 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'.
Fix: Ensure 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.
gotcha When 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()`.
Fix: To 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.
gotcha HTTP 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).
Fix: Always 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.
gotcha In 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.
Fix: If `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`.

Install

pip install prelude-python-sdk Default installation
pip install prelude-python-sdk[aiohttp] Install with aiohttp for improved async performance

Imports

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.

Quickstart

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}")

view raw JSON →