Skip to main content

​
Subpackages

​
Submodules

​
Module contents

XDK Python SDK. A Python SDK for the X API that provides convenient access to the X API endpoints with type safety and authentication support.

​
class xdk.Client

Client for interacting with the X API.

​
Parameters

​
path.base_url
str
default:"'https://api.x.com'"
​
path.bearer_token
str or None
default:"None"
​
path.access_token
str or None
default:"None"
​
path.client_id
str or None
default:"None"
​
path.client_secret
str or None
default:"None"
​
path.redirect_uri
str or None
default:"None"
​
path.token
Dict[str, Any] or None
default:"None"
​
path.scope
str or List[str] or None
default:"None"
​
path.authorization_base_url
str
default:"'https://x.com/i'"
​
path.auth
OAuth1

​
__init__

Initialize the X API client.

​
Parameters

​
path.base_url
str
default:"'https://api.x.com'"
The base URL for the X API (defaults to https://api.x.com).
​
path.bearer_token
str or None
default:"None"
The bearer token for the X API (app-only authentication).
​
path.access_token
str or None
default:"None"
The OAuth2 access token for user context (can be used directly as bearer token).
​
path.client_id
str or None
default:"None"
The client ID for the X API (required for OAuth2 PKCE flow).
​
path.client_secret
str or None
default:"None"
The client secret for the X API.
​
path.redirect_uri
str or None
default:"None"
The redirect URI for OAuth2 authorization.
​
path.token
Dict[str, Any] or None
default:"None"
An existing OAuth2 token dictionary (if available). If provided, access_token will be extracted.
​
path.scope
str or List[str] or None
default:"None"
Space-separated string or list of strings for OAuth2 authorization scopes.
​
path.authorization_base_url
str
default:"'https://x.com/i'"
The base URL for OAuth2 authorization (defaults to https://x.com/i).
​
path.auth
OAuth1
OAuth1 instance for OAuth1.0a authentication.

​
exchange_code

Exchange authorization code for tokens (matches TypeScript API).

​
Parameters

​
path.code
Any
The authorization code from the callback.
​
path.code_verifier
Any
default:"None"
Optional code verifier (uses stored verifier if not provided).

​
fetch_token

Fetch token using authorization response URL (legacy method).

​
Parameters

​
path.authorization_response
Any
The full callback URL received after authorization.

​
get_authorization_url

Get the authorization URL for the OAuth2 PKCE flow.

​
Parameters

​
path.state
Any
default:"None"
Optional state parameter for security.

​
is_token_expired

Check if the OAuth2 token is expired.

​
refresh_token

Refresh the OAuth2 token.

​
class xdk.Cursor

[ResponseType]

​
Parameters

​
path.method
PaginatableMethod

​
__init__

Initialize the cursor.

​
Parameters

​
path.method
PaginatableMethod
The API method to call for each page (must support pagination)

​
items

Iterate over individual items from paginated responses.

​
Parameters

​
path.limit
int or None
default:"None"
Maximum number of items to return (None for unlimited)

​
Returns

IteratorAny

​
pages

Iterate over pages of responses.

​
Parameters

​
path.limit
int or None
default:"None"
Maximum number of pages to return (None for unlimited)

​
Returns

IteratorResponseType

​
class xdk.StreamConfig

Configuration for streaming connections with retry behavior.

​
Parameters

​
path.max_retries
int
default:"10"
​
path.initial_backoff
float
default:"1.0"
​
path.max_backoff
float
default:"64.0"
​
path.backoff_multiplier
float
default:"2.0"
​
path.jitter
bool
default:"True"
​
path.timeout
float or None
default:"None"
​
path.chunk_size
int
default:"1024"
​
path.on_connect
Callable[[], None] or None
default:"None"
​
path.on_disconnect
Callable[[Exception or None], None] or None
default:"None"
​
path.on_reconnect
Callable[[int, float], None] or None
default:"None"
​
path.on_error
Callable[[[StreamError

​
__init__

​
Parameters

​
path.max_retries
int
default:"10"
​
path.initial_backoff
float
default:"1.0"
​
path.max_backoff
float
default:"64.0"
​
path.backoff_multiplier
float
default:"2.0"
​
path.jitter
bool
default:"True"
​
path.timeout
float or None
default:"None"
​
path.chunk_size
int
default:"1024"
​
path.on_connect
Callable[[], None] or None
default:"None"
​
path.on_disconnect
Callable[[Exception or None], None] or None
default:"None"
​
path.on_reconnect
Callable[[int, float], None] or None
default:"None"
​
path.on_error
Callable[[[StreamError

​
on_error : Callable[[[StreamError]

​
exception xdk.StreamError

Exception raised for streaming errors with classification.

​
Parameters

​
path.message
str
​
path.error_type
StreamErrorType

​
__init__

​
Parameters

​
path.message
str
​
path.error_type
StreamErrorType

​
class xdk.StreamErrorType

Classification of streaming errors for retry decisions.

​
Parameters

​
path.value
Any

​
class xdk.StreamState

Internal state for a streaming connection.

​
Parameters

​
path.retry_count
int
default:"0"
​
path.current_backoff
float
default:"1.0"
​
path.is_connected
bool
default:"False"
​
path.total_items_received
int
default:"0"
​
path.last_error
StreamError

​
__init__

​
Parameters

​
path.retry_count
int
default:"0"
​
path.current_backoff
float
default:"1.0"
​
path.is_connected
bool
default:"False"
​
path.total_items_received
int
default:"0"
​
path.last_error
StreamError

​
last_error : [StreamError]

​
xdk.cursor

Create a cursor with proper type inference and validation. This factory function helps with type inference so you get proper type hints for the response type, and validates that the method supports pagination at both static analysis and runtime.

​
Parameters

​
path.method
PaginatableMethod
The API method to wrap (must support pagination)