Python

Detailed technical documentation on using RudderStack’s Python SDK to send events to various destinations.

RudderStack’s Python SDK lets you track events from your Python application. Once enabled, the event requests hit the RudderStack servers. RudderStack then transforms and routes these events to your specified destination platforms.

Find this SDK in our GitHub repository.

Installing the RudderStack Python SDK

To install the RudderStack Python SDK using pip, run the following command:

pip install rudder-sdk-python

Initializing the RudderStack Client

To initialize the RudderStack client, run the following code snippet:

import rudder_analytics
rudder_analytics.write_key = <SOURCE_WRITE_KEY>
rudder_analytics.data_plane_url = <YOUR_DATA_PLANE_URL>
  • For more information on how to get the source write key, refer to this section.

  • For more information on how to get your data plane URL, refer to this section.

Sending Events from RudderStack

Once the RudderStack client is initialized, you can use it to send your customer events.

A sample track call is as shown:

rudder_analytics.track('developer_user_id', 'Simple Track Event', {
'key1': 'val1'
})

Identify

The identify call lets you identify a visiting user and associate them to their actions.

For more information on the identify call, refer to the RudderStack Events Specification guide.

An example identify call is as shown:

rudder_analytics.identify('123456', {
'email': '[email protected]',
'name': 'John Doe',
'friends': 16
})

The identify method parameters are as described below:

Field

Type

Presence

Description

anonymous_id

String

Optional

Sets the user ID for cases where there is no unique identifier for the user. Either user_id or anonymous_id is required.

user_id

String

Required, if anonymous_id is not present.

Unique identifier for a user in your database.

context

Object

Optional

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

Object

Optional

A dictionary containing the destinations to be either enabled or disabled.

timestamp

Date

Optional

The timestamp of the message's arrival.

traits

Object

Optional

Dictionary of the traits associated with the user, such as nameor email.

Track

The track call lets you record the customer events, i.e. the actions that they perform, along with any properties associated with them.

For more information on the track call, refer to the RudderStack Events Specification guide.

An example track call is as shown:

rudder_analytics.track('123456', 'Article Read', {
'title': 'The Independence',
'subtitle': 'Story of the Weak',
'author': 'John Doe'
})

The track method parameters are as described below:

Name

Type

Presence

Description

user_id

String

Required, if anonymous_id is not present.

Unique identifier for a user in your database.

event

String

Required

Name of the user event.

properties

Object

Optional

Dictionary of the properties associated with the event.

context

Object

Optional

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

timestamp

Date

Optional

The timestamp of the message's arrival.

anonymous_id

String

Optional

Sets the user ID for cases where there is no unique identifier for the user. Either user_id or anonymous_id is required.

integrations

Object

Optional

A dictionary containing the destinations to be either enabled or disabled.

Page

The page call lets you record your page views with any additional relevant information about the viewed page.

For more information on the page call, refer to the RudderStack Events Specification guide.

An example page call is as shown:

rudder_analytics.page('user_id', 'Documentation', 'Sample Doc', {
'url': 'http://rudderstack.com'
})

The page method parameters are as described below:

Field

Type

Presence

Description

anonymous_id

String

Optional

Sets the user ID for cases where there is no unique identifier for the user. Either user_id or anonymous_id is required.

user_id

String

Required, if anonymous_id is not present.

Unique identifier for the user in your database.

context

Object

Optional

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

Object

Optional

A dictionary containing the destinations to be either enabled or disabled.

name

String

Required

Name of the viewed page.

properties

Object

Optional

Dictionary of the properties associated with the page being viewed, such as url and referrer

timestamp

Date

Optional

The timestamp of the message's arrival.

Screen

The screen call lets you record whenever your user views their mobile screen with any additional relevant information about the screen.

For more information on the screen call, refer to the RudderStack Events Specification guide.

An example screen call is as shown:

rudder_analytics.screen('user_id', 'Settings', 'Brightness', {
'from': 'Settings Screen'
})

The screen method parameters are as described below:

Field

Type

Presence

Description

anonymous_id

String

Optional

Sets the user ID for cases where there is no unique identifier for the user. Either user_id or anonymous_id is required.

user_id

String

Required, if anonymous_id is not present.

Unique identifier for a the user in your database.

context

Object

Optional

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

Object

Optional

A dictionary containing the destinations to be either enabled or disabled.

name

String

Required

Name of the viewed screen.

properties

Object

Optional

Dictionary of the properties associated with the screen, such as url and referrer

timestamp

Date

Optional

The timestamp of the message's arrival.

Group

The group call allows you to link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits associated with that group, such as the name of the company, the number of employees, etc.

For more information on the group call, refer to the RudderStack Events Specification guide.

An example group call is as shown:

rudder_analytics.group('user_id', 'group_id', {
'name': 'Company',
'domain': 'IT'
})

The group method parameters are as follows:

Field

Type

Presence

Description

anonymous_id

String

Optional

Sets the user ID for cases where there is no unique identifier for the user. Either user_id or anonymous_id is required.

user_id

String

Required, if anonymous_id is not present

Unique identifier for a the user in your database.

context

Object

Optional

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

Object

Optional

A dictionary containing the destinations to be either enabled or disabled.

groupId

String

Required

Unique identifier of the group, as present in your database.

traits

Object

Optional

Dictionary of the properties or traits associated with the group, such as email or name.

timestamp

Date

Optional

The timestamp of the message's arrival.

Alias

The alias call lets you merge different identities of a known user.

alias is an advanced method. However, it is required when managing user identities in some destinations.

The following downstream destinations support the alias call:

For more information on the alias call, refer to the RudderStack Events Specification guide.

A sample alias call is as shown:

rudder_analytics.alias('previous_id', 'user_id')

The alias method parameters are as mentioned below:

Field

Type

Presence

Description

user_id

String

Required, if anonymous_id is not present.

Unique identifier for a the user in your database.

context

Object

Optional

Dictionary of information that provides context about a message. However, it is not directly related to the API call.

integrations

Object

Optional

A dictionary containing the destinations to be either enabled or disabled.

previous_id

String

Required

The previous unique identifier of the user.

traits

Object

Optional

Dictionary of the properties or traits associated with the group, such as email or name.

timestamp

Date

Optional

The timestamp of the message's arrival.

Error Handling

To handle the errors that may occur while sending events using the RudderStack client, you can declare a callback called on_error.

def on_error(error, events):
print("Error response:", error)
rudder_analytics.on_error = on_error

This callback will only return the errors that may occur with the HTTP requests to RudderStack. Any errors that occur downstream will not be returned.

The common request responses from the RudderStack server are listed below:

Status

Code

Ok

200

Request neither has anonymous_id nor user_id

400

Invalid source write key

401

Invalid JSON

400

Contact Us

For more information on the RudderStack Python SDK, you can contact us or start a conversation on our Slack channel.