Python SDK upgrade (v0.x to v1.0)
This guide will help you upgrade from the previous Knock Python SDK to the new v1.0 Python SDK.
Basic Changes#
Client Initialization#
New Features in v1.0#
-
Async Support: First-class async/await support
-
Strong Type Checking: Improved type hints with TypedDict and Pydantic models
-
Auto-pagination: Easily iterate through paginated resources
-
Enhanced Error Handling: More specific error classes
-
Configurable Timeouts and Retries: Fine-tune request behavior
-
Access to Raw Response Data: More control over HTTP interactions
Breaking Changes#
-
Client Design: The new SDK has a cleaner interface with direct method calls
- The old approach of passing all parameters as keyword arguments is replaced with specific method signatures
- Parameters that were previously named keyword arguments may now be positional arguments
-
Method Naming Changes:
client.users.identify()
→client.users.update()
client.users.get_user()
→client.users.get()
- Client-level
.notify()
shorthand is removed, useclient.workflows.trigger()
instead
-
Method Parameters: Parameters are now passed differently
- Most methods now take the ID(s) as positional parameter(s), followed by named parameters
- The
data
wrapper is removed for user properties (they're now top-level parameters) - Parameter names have changed in some cases (e.g.,
id
→user_id
) - Preference methods require an explicit preference set ID parameter
-
Response Types:
- The new SDK returns typed Pydantic model instances instead of dictionaries
- Use
.model_dump()
to get a dictionary representation of a response object - Pagination is handled via cursor-based pagination instead of page-based
-
Bulk Operations:
- Bulk operations are now organized in their own namespaces:
client.users.bulk.*
,client.objects.bulk.*
- Bulk operations are now organized in their own namespaces:
Common Operations#
Triggering Workflows#
Old SDK:
New SDK:
Identifying Users#
Old SDK:
New SDK:
Working with Preferences#
Old SDK:
New SDK:
Working with Objects#
Old SDK:
New SDK:
Support#
If you encounter any issues during migration, please reach out to our support team or open an issue on GitHub.