Designing the Truthlocks Python SDK: Async Verification and Type Safety

We are building the Truthlocks Python SDK from the ground up for Python 3.12 with native async/await support, comprehensive type hints, batch operations, and a clean API surface. This post walks through the design decisions behind the SDK and shows what the developer experience will look like for Python teams integrating with the Truthlocks API.

Installation

Install the SDK from PyPI:

pip install truthlocks>=2.0.0

The SDK requires Python 3.10 or later, with full support for 3.12's latest features including improved error messages and performance optimizations.

Async/Await Support

The headline feature is first-class async support. Every API method is available in both synchronous and asynchronous variants. The async client uses httpx under the hood for connection pooling and HTTP/2 support.

import asyncio
from truthlocks import AsyncTruthlockClient

async def verify_credential():
    client = AsyncTruthlockClient(api_key="your-api-key")

    result = await client.attestations.verify(
        attestation_id="att_8f3k2n4m5p6q"
    )

    print(f"Valid: {result.valid}")
    print(f"Issuer: {result.issuer.name}")
    print(f"Trust Level: {result.issuer.trust_level}")

    await client.close()

asyncio.run(verify_credential())

For synchronous usage, the familiar blocking client remains available:

from truthlocks import TruthlockClient

client = TruthlockClient(api_key="your-api-key")
result = client.attestations.verify(attestation_id="att_8f3k2n4m5p6q")

Type Hints Throughout

Every method, parameter, and return type is fully annotated. This means your IDE can provide autocompletion, inline documentation, and type checking without any additional configuration. We also ship a py.typed marker file so that type checkers like mypy and pyright recognize the SDK as fully typed.

from truthlocks.types import AttestationResult, Issuer

# Your IDE will autocomplete all fields on result
result: AttestationResult = client.attestations.verify(
    attestation_id="att_8f3k2n4m5p6q"
)

issuer: Issuer = result.issuer
# issuer.name, issuer.did, issuer.trust_level, etc.

Batch Verification

Verifying credentials one at a time is fine for interactive flows, but background jobs often need to verify hundreds or thousands of attestations. The new verify_batch method accepts up to 1,000 attestation IDs per call and returns results in a single round trip.

results = await client.attestations.verify_batch(
    attestation_ids=[
        "att_8f3k2n4m5p6q",
        "att_2j5l7n9p1r3t",
        "att_4k6m8o0q2s4u",
    ]
)

for result in results:
    print(f"{result.attestation_id}: {'valid' if result.valid else 'invalid'}")

Batch verification uses server-side parallelism to verify all attestations concurrently, so the total time is roughly the same as a single verification — not N times a single verification.

Error Handling

The SDK uses a typed exception hierarchy that makes error handling explicit:

from truthlocks.exceptions import (
    TruthlockError,
    AuthenticationError,
    RateLimitError,
    AttestationNotFoundError,
)

try:
    result = await client.attestations.verify(attestation_id="att_invalid")
except AttestationNotFoundError:
    print("Attestation does not exist")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except AuthenticationError:
    print("Invalid API key")
except TruthlockError as e:
    print(f"Unexpected error: {e}")

What Comes Next

The Python SDK is under active development. We are focused on getting the core verification and attestation workflows right before expanding to more advanced features like webhook management and transparency log queries.

If you are a Python developer interested in early access, reach out through the enterprise contact page or follow the documentation for updates. In the meantime, all Truthlocks functionality is available through the REST API, which you can call from any Python HTTP client.