x-browser-client 0.1.0

A Python package for interacting with X.com using Playwright-powered automation. Meant for use with AI agents. Requires a windowed environment, optimally Ubuntu or Windows.

x_browser_client

x_browser_client is a Python package that automates x.com (formerly Twitter) interactions using Playwright. This library can log in, post new tweets, scrape timelines and posts, reply, like, repost, quote, bookmark, and follow/unfollow accounts.

Features

• Automatic or manual login to x.com
• Posting and replying to tweets
• Scraping timelines, individual posts, and comment threads
• Liking, reposting, quoting, bookmarking tweets
• Following and unfollowing users
• Session management to persist cookies (via Playwright contexts)

Installation

Via PyPI

pip install x_browser_client

Via GitHub

git clone https://github.com/laelhalawani/x_browser_client
cd x_browser_client
pip install .

Note: If you have not installed Playwright browsers before, you may need to run:

playwright install chromium

This ensures that Playwright can automate the Chromium browser.

Requirements

• Python 3.7 or higher
• Playwright for Python
• (Optional) dotenv for loading environment variables

Basic Usage

Below is a minimal example of how to use x_browser_client:

from x_browser_client import XClient, PostStatusData

# Create an XClient instance
client = XClient(
    timeout=60,         # default timeout (seconds) for browser interactions
    locale="en-US",     # language/locale
    post_character_limit=280
)

# Start the client, which:
# 1) Opens the browser
# 2) Loads or creates a session context if context_name is passed
# 3) Attempts login (auto or manual)
client.start_client(context_name="my_session", accept_cookies=True, skip_notifications=True)

# Scrape some of the latest posts from the 'for_you' tab
new_posts = client.scrape_new_posts(num_posts=5, tab="for_you")

# Iterate over posts and optionally interact
for post in new_posts:
    print(post)  # shows basic info about the post
    if post.has_text():
        # Like the post
        client.post_like(post)

# Exit the client, optionally saving context so next time it can reuse login
client.exit_client(save_context=True, close_browser_after=0)

Environment Variables

You can store your X credentials (login, password, username) in environment variables (e.g., in a .env file):

X_LOGIN=myEmailOrPhone
X_PASSWORD=mySecurePassword
X_USERNAME=myActualUsername

The XClient will automatically pick them up if you do not explicitly set them:

client = XClient()
client.start_client()

Additional Examples

Refer to examples.py or the repository's examples.py file for more in-depth usage, including:

• Replying to a post with AI-generated content
• Scraping specific post threads
• Following or unfollowing a user
• Manually controlling cookies and contexts

Contributing

Contributions are welcome! To set up a development environment:

1. Clone the repository and install in editable mode:

   git clone https://github.com/laelhalawani/x_browser_client
   cd x_browser_client
   pip install -e .
   

2. (Optional) Install additional dev dependencies for linting/testing as needed.

Please open issues or submit pull requests on GitHub.

---

Disclaimer: This package is intended solely for educational and testing purposes. Be aware of any usage constraints or policies on x.com, and ensure compliance with all terms of service and legal requirements.