Migration Guide¶

# ❌ Old (v1.x)
x = Xeepy()
await x.scrape.replies(url)
await x.close()

# ✅ New (v2.x)
async with Xeepy() as x:
    await x.scrape.replies(url)

# ❌ Old (v1.x)
replies = await x.get_replies(url)  # Returns List[Tweet]
for reply in replies:
    print(reply.text)

# ✅ New (v2.x)
result = await x.scrape.replies(url)  # Returns ScrapeResult[Tweet]
print(f"Found {result.count} replies")
for reply in result.items:
    print(reply.text)

# ❌ Old (v1.x)
x = Xeepy(browser="chromium", headless=True)

# ✅ New (v2.x)
x = Xeepy(
    headless=True,
    config_path="xeepy.yml"  # Optional external config
)

# ❌ Old (v1.x) - Manual delays
import asyncio
for user in users:
    await x.follow_user(user)
    await asyncio.sleep(5)

# ✅ New (v2.x) - Automatic rate limiting
for user in users:
    await x.follow.user(user)  # Automatic delays

# ❌ Tweepy
import tweepy
auth = tweepy.OAuth1UserHandler(
    consumer_key, consumer_secret,
    access_token, access_token_secret
)
api = tweepy.API(auth)

# ✅ Xeepy
from xeepy import Xeepy
async with Xeepy() as x:
    await x.auth.login()  # Browser-based auth

# ❌ Tweepy (v1 API - deprecated)
# No native method, requires search workarounds

# ✅ Xeepy
async with Xeepy() as x:
    replies = await x.scrape.replies("https://x.com/user/status/123")

# ❌ Tweepy
tweets = api.user_timeline(screen_name="username", count=100)

# ✅ Xeepy
async with Xeepy() as x:
    result = await x.scrape.tweets("username", limit=100)
    tweets = result.items

# ❌ Tweepy
followers = tweepy.Cursor(api.get_followers, screen_name="username").items(1000)

# ✅ Xeepy
async with Xeepy() as x:
    result = await x.scrape.followers("username", limit=1000)
    followers = result.items

# ❌ Tweepy
api.create_favorite(tweet_id)

# ✅ Xeepy
async with Xeepy() as x:
    await x.engage.like("https://x.com/user/status/123")

# ❌ Tweepy
api.create_friendship(screen_name="username")

# ✅ Xeepy
async with Xeepy() as x:
    await x.follow.user("username")

# ❌ Tweepy
tweets = api.search_tweets(q="python", count=100)

# ✅ Xeepy
async with Xeepy() as x:
    result = await x.scrape.search("python", limit=100)
    tweets = result.items

# ❌ Snscrape
import snscrape.modules.twitter as sntwitter
tweets = []
for tweet in sntwitter.TwitterUserScraper("username").get_items():
    tweets.append(tweet)
    if len(tweets) >= 100:
        break

# ✅ Xeepy
async with Xeepy() as x:
    result = await x.scrape.tweets("username", limit=100)
    tweets = result.items

# ❌ Snscrape
for tweet in sntwitter.TwitterSearchScraper("python").get_items():
    print(tweet.content)

# ✅ Xeepy
async with Xeepy() as x:
    result = await x.scrape.search("python")
    for tweet in result.items:
        print(tweet.text)

# Twitter API v2 Tweet
{
    "id": "123456789",
    "text": "Hello world",
    "created_at": "2024-01-01T12:00:00.000Z",
    "author_id": "987654321",
    "public_metrics": {
        "like_count": 100,
        "retweet_count": 50
    }
}

# Xeepy Tweet
Tweet(
    id="123456789",
    text="Hello world",
    created_at=datetime(2024, 1, 1, 12, 0, 0),
    author=User(id="987654321", ...),
    likes=100,
    retweets=50
)

# Twitter API v2 User
{
    "id": "987654321",
    "username": "johndoe",
    "name": "John Doe",
    "public_metrics": {
        "followers_count": 1000,
        "following_count": 500
    }
}

# Xeepy User
User(
    id="987654321",
    username="johndoe",
    name="John Doe",
    followers_count=1000,
    following_count=500
)

# ❌ Wrong
replies = x.scrape.replies(url)

# ✅ Correct
replies = await x.scrape.replies(url)

# Clear old session and re-authenticate
async with Xeepy() as x:
    await x.auth.login()  # Opens browser for manual login
    await x.auth.save_cookies("session.json")

# Customize rate limits if needed
from xeepy.core.config import Config

config = Config()
config.rate_limits.actions_per_hour = 50
config.rate_limits.scrapes_per_hour = 200

async with Xeepy(config=config) as x:
    ...