Module Interface and Client

Relevant source files

• rudderstack/analytics/client.py
• rudderstack/analytics/consumer.py
• rudderstack/analytics/request.py
• rudderstack/analytics/test/test_consumer.py
• rudderstack/analytics/test/test_utils.py

This page provides a detailed technical reference for the RudderStack Python SDK's primary interface. It covers the Client class, the global singleton proxy, and the lifecycle management of event data from method call to internal queuing.

Overview

The SDK is designed around a layered architecture where the top layer consists of a public API (the Client) that validates and enqueues events. These events are then processed by a background Consumer thread for batched delivery to the RudderStack Data Plane.

Code Entity Map: Module to Client

The following diagram illustrates how the top-level module functions interact with the underlying Client singleton and its configuration.

Interface to Entity Mapping

Sources: rudderstack/analytics/client.py21-37 rudderstack/analytics/client.py216-224

---

The Client Class

The Client class is the engine of the SDK. It manages the internal state, the message queue, and the lifecycle of consumer threads.

Configuration and Constructor

The Client is initialized with a variety of parameters, many of which default to values defined in DefaultConfig.

Parameter	Default	Description
write_key	None	Required. The RudderStack project write key.
host	TEST_DATA_PLANE_URL	The Data Plane URL (formerly dataPlaneUrl).
sync_mode	False	If True, events are sent synchronously (blocking).
max_queue_size	10000	Maximum number of unsent messages in the queue.
upload_size	100	Number of messages to include in a single batch.
upload_interval	0.5	Seconds to wait before uploading a partial batch.
thread	1	Number of consumer threads to spawn.

Sources: rudderstack/analytics/client.py22-36 rudderstack/analytics/client.py40-54

Data Plane URL vs Host

While the internal variable is named host, it represents the dataPlaneUrl. The SDK ensures trailing slashes are removed before appending the /v1/batch endpoint rudderstack/analytics/request.py21

---

Event Methods

The SDK supports six primary event types. Each method validates input types using the require helper rudderstack/analytics/client.py273-281 and passes a constructed dictionary to the internal _enqueue logic.

1. Identify

Used to associate a user with their traits.

• Behavior: Traits are automatically nested inside the context object rudderstack/analytics/client.py101
• Requirements: Either user_id or anonymous_id must be provided rudderstack/analytics/client.py103

2. Track

Records actions performed by a user.

• Requirements: event (string) and either user_id or anonymous_id rudderstack/analytics/client.py125-127

3. Page & Screen

page records website page views, while screen records mobile app screen views.

• Implementation: Both accept optional name and category strings rudderstack/analytics/client.py195-198

4. Group & Alias

• Group: Associates a user with a group (e.g., an organization). Requires group_id rudderstack/analytics/client.py169
• Alias: Merges two identities. Requires previous_id and user_id rudderstack/analytics/client.py147-148

Sources: rudderstack/analytics/client.py96-117 rudderstack/analytics/client.py119-141 rudderstack/analytics/client.py143-160 rudderstack/analytics/client.py162-184 rudderstack/analytics/client.py186-214

---

Internal Logic and Data Flow

The Enqueue Process (_enqueue)

Every event call ends in _enqueue(msg). This method handles:

1. Timestamping: If no timestamp is provided, it generates one using datetime.now() rudderstack/analytics/client.py221-222
2. ID Generation: Assigns a UUID4 messageId if missing rudderstack/analytics/client.py226-227
3. Cleaning: Coerces types (e.g., Decimals to floats) via utils.clean() rudderstack/analytics/client.py231
4. Queueing:
   • In sync_mode, it calls post() immediately rudderstack/analytics/client.py234-235
   • In async mode (default), it attempts a non-blocking put_nowait() into the queue.Queue rudderstack/analytics/client.py239

Data Flow Diagram

Sources: rudderstack/analytics/client.py216-250 rudderstack/analytics/consumer.py56-75

---

Lifecycle Management

The SDK provides mechanisms to ensure data is sent before the application terminates.

Flush

The flush() method blocks until the internal queue is empty. It calls queue.join() to wait for all tasks marked as task_done() by the consumer rudderstack/analytics/client.py252-256

Join and Shutdown

• join(): Iterates through all consumer threads and calls consumer.pause() followed by consumer.join() rudderstack/analytics/client.py258-264
• shutdown(): A convenience method that first calls flush() and then join() to ensure a clean exit rudderstack/analytics/client.py266-271
• Atexit: The SDK registers self.join with the Python atexit handler to prevent messy shutdowns when the interpreter exits, though this does not guarantee a full flush rudderstack/analytics/client.py81

Error Handling

The on_error callback can be provided to the constructor. If the Consumer encounters a non-retryable error or exhausts retries, it executes this callback with the exception and the failed batch rudderstack/analytics/consumer.py69-70

Sources: rudderstack/analytics/client.py252-271 rudderstack/analytics/consumer.py63-75 rudderstack/analytics/client.py74-81