Python SDK
Use RudderStack’s Python SDK to send server-side events to various destinations.
RudderStack’s Python SDK lets you track and send the events from your Python applications to the specified destinations.
Refer to the SDK’s GitHub codebase for the implementation-specific details.
SDK setup requirements
- Sign up to RudderStack Cloud.
- Set up a Python source in your dashboard. You should be able to see a write key for this source.
You will also need a data plane URL. Refer to the Dashboard Overview guide for more information on the data plane URL and where to find it.
The Setup tab in the RudderStack dashboard has the SDK installation snippet containing both the write key and the data plane URL. Use it to integrate the Python SDK into your application.
Installing the Python SDK
To install the RudderStack Python SDK using pip, run the following command:
pip install rudder-sdk-python
Initializing the SDK
To initialize the SDK, run the following code snippet:
import rudderstack.analytics as rudder_analytics
rudder_analytics.write_key = WRITE_KEY
rudder_analytics.dataPlaneUrl = DATA_PLANE_URL
Initialization options
Parameter | Description | Default value |
---|
on_error | Callback for exception thrown while uploading the messages. | None |
debug | The SDK prints the logs if set to True . | False |
send | The SDK does not send the data to the RudderStack backend if set to False . | True |
sync_mode | The SDK sends the data immediately instead of queueing it, if set to True . | False |
max_queue_size | Maximum queue size the SDK uses to enqueue the events. | 10000 |
gzip | The SDK disables gzipping the event data if set to False . | True |
timeout | The timeout for sending POST requests to the RudderStack backend. | 15 |
max_retries | Maximum number of retry requests the SDK makes to the RudderStack backend. | 10 |
upload_interval | Maximum duration between two upload (flush) activities. | 0.5s |
upload_size | Number of events in the queue that triggers a flush. | 100 |
Sending events
RudderStack does not store or persist the user state in any of the server-side SDKs.
Unlike the client-side SDKs that deal with only a single user at a given time, the server-side SDKs deal with multiple users simultaneously. Therefore, you must specify either the user_id
or anonymous_id
every time while making any API calls supported by the Python SDK.
Identify
The identify
call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.
A sample identify
call made using the Python SDK is shown below:
rudder_analytics.identify('1hKOmRA4GRlm', {
'email': 'alex@example.com',
'name': 'John Doe',
'friends': 16
})
The identify
method parameters are as shown:
Field | Type | Description |
---|
user_id Required, if anonymous_id is absent. | String | Unique identifier for a user in your database. |
anonymous_id Required, if user_id is absent. | String | Use this field to set an identifier in cases where there is no unique user identifier. |
traits Required | Object | An optional dictionary of the user’s traits like name or email . |
context | Object | An optional dictionary of information that provides context about the event. It is not directly related to the API call. |
integrations | Object | An optional dictionary containing the destinations to be either enabled or disabled. |
timestamp | Timestamp in ISO 8601 format | The timestamp of the event’s arrival. |
message_id | String | A unique identifier for the event. The SDK generates this field automatically. It is highly recommended to not send this field unless there is a specific requirement or use case. |
Track
The track
call lets you record the user actions along with their associated properties. Each user action is called an event.
A sample track
call is shown below:
rudder_analytics.track('123456', 'Article Read', {
'title': 'The Independence',
'subtitle': 'Story of the Weak',
'author': 'John Doe'
})
The track
method parameters are as shown:
Field | Type | Description |
---|
user_id Required, if anonymous_id is absent. | String | Unique identifier for a user in your database. |
anonymous_id Required, if user_id is absent. | String | Use this field to set an identifier in cases where there is no unique user identifier. |
event Required | String | Name of the event. |
properties Required | Object | An optional dictionary of the properties associated with the event. |
context | Object | An optional dictionary of information that provides context about the event. It is not directly related to the API call. |
integrations | Object | An optional dictionary containing the destinations to be either enabled or disabled. |
timestamp | Timestamp in ISO 8601 format | The timestamp of the event’s arrival. |
message_id | String | A unique identifier for the event. The SDK generates this field automatically. It is highly recommended to not send this field unless there is a specific requirement or use case. |
Page
The page
call lets you record the page views on your application along with the other relevant information about the page.
A sample page
call is as shown:
rudder_analytics.page('userid', 'Documentation', 'Sample Doc', {
'url': 'http://rudderstack.com'
})
The page
method parameters are as shown:
Field | Type | Description |
---|
user_id Required, if anonymous_id is absent. | String | Unique identifier for a user in your database. |
anonymous_id Required, if user_id is absent. | String | Use this field to set an identifier in cases where there is no unique user identifier. |
name Required | String | Name of the viewed page. |
category Required | String | Category of the viewed page. |
properties Required | Object | An optional dictionary of the properties associated with the event. |
context | Object | An optional dictionary of information that provides context about the event. It is not directly related to the API call. |
integrations | Object | An optional dictionary containing the destinations to be either enabled or disabled. |
timestamp | Timestamp in ISO 8601 format | The timestamp of the event’s arrival. |
message_id | String | A unique identifier for the event. The SDK generates this field automatically. It is highly recommended to not send this field unless there is a specific requirement or use case. |
Screen
The screen
call is the mobile equivalent of the page
call. It lets you record the screen views on your mobile app along with other relevant information about the screen.
A sample screen
call is as shown:
rudder_analytics.screen('userid', 'Settings', 'Brightness', {
'from': 'Settings Screen'
})
The screen
method parameters are as shown:
Field | Type | Description |
---|
user_id Required, if anonymous_id is absent. | String | Unique identifier for a user in your database. |
anonymous_id Required, if user_id is absent. | String | Use this field to set an identifier in cases where there is no unique user identifier. |
name Required | String | Name of the viewed screen. |
category Required | String | Category of the viewed screen. |
properties Required | Object | An optional dictionary of the properties associated with the event. |
context | Object | An optional dictionary of information that provides context about the event. It is not directly related to the API call. |
integrations | Object | An optional dictionary containing the destinations to be either enabled or disabled. |
timestamp | Timestamp in ISO 8601 format | The timestamp of the event’s arrival. |
message_id | String | A unique identifier for the event. The SDK generates this field automatically. It is highly recommended to not send this field unless there is a specific requirement or use case. |
Group
The group
call lets you link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits or properties associated with that group.
A sample group
call made using the Python SDK is shown below:
rudder_analytics.group('1hKOmRA4GRlm', '12', {
'name': 'Company',
'domain': 'IT'
})
The group
method parameters are as shown:
Field | Type | Description |
---|
user_id Required, if anonymous_id is absent. | String | Unique identifier for a user in your database. |
anonymous_id Required, if user_id is absent. | String | Use this field to set an identifier in cases where there is no unique user identifier. |
group_id Required | String | Unique identifier of the group in your database. |
traits | Object | An optional dictionary of the group’s traits like name or email . |
integrations | Object | An optional dictionary containing the destinations to be either enabled or disabled. |
context | Object | An optional dictionary of information that provides context about the event. It is not directly related to the API call. |
timestamp | Timestamp in ISO 8601 format | The timestamp of the event’s arrival. |
message_id | String | A unique identifier for the event. The SDK generates this field automatically. It is highly recommended to not send this field unless there is a specific requirement or use case. |
Alias
The alias
call lets you merge different identities of a known user. It is an advanced method that lets you change the tracked user’s ID explicitly. You can use alias
for managing the user’s identity in some of the downstream destinations.
A sample alias
call is as shown:
rudder_analytics.alias('previous_id', 'user_id')
The alias
method parameters are as shown:
Field | Type | Description |
---|
user_id Required, if anonymous_id is absent. | String | Unique identifier for a user in your database. |
previous_id Required | String | The previous unique identifier of the user. |
integrations | Object | An optional dictionary containing the destinations to be either enabled or disabled. |
context | Object | An optional dictionary of information that provides context about the event. It is not directly related to the API call. |
timestamp | Timestamp in ISO 8601 format | The timestamp of the event’s arrival. |
message_id | String | A unique identifier for the event. The SDK generates this field automatically. It is highly recommended to not send this field unless there is a specific requirement or use case. |
Gzipping requests
The Python SDK automatically gzips requests. However, you can disable this feature by setting the gzip
parameter to false
while initializing the SDK:
import rudderstack.analytics as rudder_analytics
rudder_analytics.write_key = WRITE_KEY
rudder_analytics.dataPlaneUrl = DATA_PLANE_URL
rudder_analytics.gzip = False
Gzip requires
rudder-server v1.4 or higher. Otherwise, your events might fail.
Flushing events
The Python SDK batches the events and flushes them in the background, for faster and more efficient operation. By default, the SDK flushes a batch of 100 events every 0.5 seconds since the last flush.
You can control the event flushing by tweaking the following parameters:
Parameter | Description | Default value |
---|
max_queue_size | Maximum queue size the SDK uses to enqueue the events. | 10000 |
upload_interval | Maximum duration between two upload (flush) activities. | 0.5s |
You can also flush the events explicitly by using the SDK’s flush()
method to make sure no events are left in the queue.
A sample flush call is shown below:
The SDK blocks the calling thread until all messages are flushed from the queue. Hence, avoid using it as a part of your request lifecycle.
Error handling
To handle errors that may occur when sending the events via the Python SDK, you can declare a callback called on_error
.
def on_error(error, events):
print("Error response:", error)
rudder_analytics.on_error = on_error
The on_error
callback function takes the following objects:
Object | Type |
---|
error | APIError type. |
events | List of events that failed while being sent to the RudderStack data plane (backend). It is the raw events data which gets buffered in the SDK. Also, each event contains all the fields you have sent. |
This callback only returns the errors that occur with the HTTP requests to the gateway. It will not return any errors that occur while sending data to your downstream destinations.
Some of the common request responses are listed in the following table:
Status | Code |
---|
OK | 200 |
Request has neither anonymousId nor userId | 400 |
Invalid write key | 401 |
Invalid JSON | 400 |
FAQ
How does the Python SDK handle events larger than 32KB?
The Python SDK drops any events greater than 32KB.
Does the Python SDK support event ordering?
The Python SDK does not support event ordering by default.
Questions? Contact us by email or on
Slack