twitterx-api 0.1.0
A Python library for interacting with Twitter (X) private API
License: MIT
Requires Python: >=3.9
Keywords: twitter, api, x, social-media, web-scraping

# TwitterX API Client

A Python client for interacting with Twitter's unofficial API, allowing you to search tweets, manage profiles, and perform various tweet operations.

## Installation

```bash
pip install twitterx-api
```

## Authentication

The client requires Twitter authentication cookies to function. You can provide cookies in several formats:

```python
from twitterx_api import TwitterXClient

# Using cookie string
client = TwitterXClient(cookies="your_cookie_string")

# Using cookie dictionary
client = TwitterXClient(cookies=[
    {"name": "cookie_name", "value": "cookie_value"},
    # ... more cookies
])

# Using cookie header format
client = TwitterXClient(cookies={"cookie": "your_full_cookie_header"})
```

## Profile Operations

### Get User Profile

Retrieve information about a Twitter user by their screen name:

```python
profile = client.get_pfoile("username")
print(profile)
```

## Tweet Operations

### Get User Tweets

Retrieve tweets from a specific user:

```python
user_id = "123456789"
cursor = None  # For initial request
size = 20  # Number of tweets to retrieve

tweets_data = client.get_tweets(user_id, cursor, size)
tweets = tweets_data["lists"]
top_cursor = tweets_data["top_cursor"]
bottom_cursor = tweets_data["bottom_cursor"]

# For pagination, use the bottom_cursor for next request
next_tweets_data = client.get_tweets(user_id, bottom_cursor, size)
```

### Post a New Tweet

Post a new tweet with optional media attachments:

```python
# Simple text tweet
response = client.post_tweet("Hello, Twitter!")

# Tweet with media
from twitterx_api.types.types import MediaFile

media_files = [
    MediaFile(data=b"image_bytes", media_type="image/jpeg"),
    # Add up to 4 media files
]

response = client.post_tweet("Check out this image!", media_files)
```

### Reply to a Tweet

Reply to an existing tweet:

```python
tweet_id = "987654321"
response = client.reply_to_tweet(tweet_id, "This is my reply!")
```

### Like a Tweet

Like a tweet by its ID:

```python
tweet_id = "987654321"
client.like_tweet(tweet_id)
```

### Retweet

Retweet a tweet by its ID:

```python
tweet_id = "987654321"
response = client.retweet(tweet_id)
```

## Search Operations

### Search Latest Tweets

Find the most recent tweets matching a query:

```python
results = client.search_latest_tweets("python programming", count=20)
tweets = results["tweets"]
top_cursor = results["top_cursor"]
bottom_cursor = results["bottom_cursor"]

# For pagination
more_results = client.search_latest_tweets("python programming", count=20, cursor=bottom_cursor)
```

### Search Top Tweets

Find the most popular tweets matching a query:

```python
results = client.search_top_tweets("python programming", count=20)
tweets = results["tweets"]
top_cursor = results["top_cursor"]
bottom_cursor = results["bottom_cursor"]
```

### Search People/Users

Find users matching a query:

```python
results = client.search_people("python developer", count=20)
users = results["users"]
top_cursor = results["top_cursor"]
bottom_cursor = results["bottom_cursor"]
```

### Search Lists

Find Twitter lists matching a query:

```python
results = client.search_lists("python", count=20)
lists = results["lists"]
top_cursor = results["top_cursor"]
bottom_cursor = results["bottom_cursor"]
```

## Cookie Management

Export your cookies for later use:

```python
# Export as header string
cookie_header = client.export_header_cookies()

# Export as dictionary list
cookie_dict_list = client.export_dict_cookies()
```

## Error Handling

The client raises exceptions for various error conditions:

```python
try:
    profile = client.get_pfoile("nonexistent_user")
except Exception as e:
    print(f"Error retrieving profile: {e}")
```

## Pagination

Most methods that return lists support pagination through cursor-based navigation:

```python
# Initial request
results = client.search_latest_tweets("query")
tweets = results["tweets"]
bottom_cursor = results["bottom_cursor"]

# Next page
if bottom_cursor:
    next_results = client.search_latest_tweets("query", cursor=bottom_cursor)
    more_tweets = next_results["tweets"]
```

## Media Support

When posting tweets or replies with media, you can attach up to 4 media files:
- Up to 4 images
- Or 1 video and up to 3 images

```python
from twitterx_api.types.types import MediaFile

# Create media files from bytes
image_data = open("image.jpg", "rb").read()
media_files = [
    MediaFile(data=image_data, media_type="image/jpeg")
]

# Attach to tweet
client.post_tweet("Check this out!", media_files)
```

## Rate Limits

Be aware that Twitter enforces rate limits on API usage. If you exceed these limits, you may experience temporary blocks or restrictions on your account.

## License

MIT License

---

**Disclaimer**: This library interacts with Twitter's unofficial API and may break if Twitter changes their internal API endpoints. Use responsibly and at your own risk.