🔄 APIKeyRotator

🚀 Quick Start • 📚 Documentation • 💡 Examples • 🔒 Security • 📝 Changelog

---

✨ Features

🔄 Automatic Key Rotation Seamlessly cycles through API keys Bypasses rate limits effortlessly Removes invalid keys automatically	🔁 Smart Retry Logic Exponential backoff strategy Intelligent error classification Configurable retry attempts	🛡️ Anti-Bot Evasion User-Agent rotation Random delays between requests Proxy support
⚡ Dual Mode Support Synchronous (requests) Asynchronous (aiohttp) Drop-in replacement	🧠 Intelligent Headers Auto-detects auth patterns Learns successful configs Persistent configuration

🚀 Quick Start

📦 Installation

pip install apikeyrotator

⚡ Basic Usage

from apikeyrotator import APIKeyRotator

# Initialize with API keys
rotator = APIKeyRotator(api_keys=["key1", "key2", "key3"])

# Make requests - it's that simple!
response = rotator.get("https://api.example.com/data")
print(response.json())

# The rotator automatically:
# ✅ Rotates keys on rate limits
# ✅ Retries on failures
# ✅ Manages headers intelligently

🌟 Using Environment Variables

Create a .env file:

API_KEYS=key1,key2,key3

Then use without explicit keys:

from apikeyrotator import APIKeyRotator

# Automatically loads from .env
rotator = APIKeyRotator()

response = rotator.get("https://api.example.com/data")

🔥 Advanced Configuration

from apikeyrotator import APIKeyRotator

rotator = APIKeyRotator(
    api_keys=["key1", "key2", "key3"],
    
    # Retry & Timeout
    max_retries=5,              # Retry up to 5 times per key
    base_delay=1.0,             # Start with 1s delay
    timeout=15.0,               # 15s request timeout
    
    # Anti-Bot Features
    user_agents=[               # Rotate User-Agents
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
    ],
    random_delay_range=(1.0, 3.0),  # Random 1-3s delays
    proxy_list=[                # Rotate proxies
        "http://proxy1.com:8080",
        "http://proxy2.com:8080"
    ]
)

# Now make requests with all these features active!
response = rotator.get("https://api.example.com/data")

🌐 Asynchronous Usage

import asyncio
from apikeyrotator import AsyncAPIKeyRotator

async def main():
    async with AsyncAPIKeyRotator(api_keys=["key1", "key2"]) as rotator:
        # Make async requests
        response = await rotator.get("https://api.example.com/data")
        data = await response.json()
        print(data)

asyncio.run(main())

🎯 Why APIKeyRotator?

┌────────────────────────────────────────────────────────────────┐
│  ✓ Effortless API key management                              │
│  ✓ Automatic rate limit handling                              │
│  ✓ Smart retry logic with exponential backoff                 │
│  ✓ Anti-bot evasion (User-Agents, delays, proxies)            │
│  ✓ Both sync and async support                                │
│  ✓ Intelligent header detection and persistence               │
│  ✓ Clean, modern Python with full type hints                  │
└────────────────────────────────────────────────────────────────┘

📊 Comparison

Feature	Manual Management	APIKeyRotator
Key rotation	❌ Manual	✅ Automatic
Retry logic	❌ Custom code	✅ Built-in
Rate limit handling	❌ Manual	✅ Automatic
Error classification	❌ Status codes	✅ Intelligent
Anti-bot features	❌ Not included	✅ Complete
Session management	❌ Manual	✅ Optimized
Code complexity	❌ High	✅ Minimal

🎨 Use Cases

🕷️ Web Scraping

from apikeyrotator import APIKeyRotator
from bs4 import BeautifulSoup

# Configure for web scraping
rotator = APIKeyRotator(
    api_keys=["key1", "key2", "key3"],
    user_agents=[
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
    ],
    random_delay_range=(1.0, 3.0),
    max_retries=5
)

# Scrape multiple pages
for page in range(1, 11):
    response = rotator.get(f"https://example.com/products?page={page}")
    soup = BeautifulSoup(response.content, 'html.parser')
    # Process data...

📊 Data Collection

from apikeyrotator import APIKeyRotator

rotator = APIKeyRotator(api_keys=["key1", "key2", "key3"])

# Collect data from multiple endpoints
endpoints = ["/users", "/posts", "/comments", "/analytics"]

data = {}
for endpoint in endpoints:
    response = rotator.get(f"https://api.example.com{endpoint}")
    data[endpoint] = response.json()
    print(f"✓ Collected {endpoint}")

🔄 High-Volume Requests

import asyncio
from apikeyrotator import AsyncAPIKeyRotator

async def fetch_all_items(item_ids):
    async with AsyncAPIKeyRotator(api_keys=["key1", "key2", "key3"]) as rotator:
        tasks = [
            rotator.get(f"https://api.example.com/items/{id}")
            for id in item_ids
        ]
        responses = await asyncio.gather(*tasks)
        return [await r.json() for r in responses]

# Fetch 1000 items concurrently
items = asyncio.run(fetch_all_items(range(1000)))

🛠️ Production API Client

from apikeyrotator import APIKeyRotator, AllKeysExhaustedError
from typing import Dict, List

class APIClient:
    def __init__(self, api_keys: List[str]):
        self.rotator = APIKeyRotator(
            api_keys=api_keys,
            max_retries=5,
            base_delay=2.0
        )
    
    def get_user(self, user_id: int) -> Dict:
        try:
            response = self.rotator.get(f"https://api.example.com/users/{user_id}")
            return response.json()
        except AllKeysExhaustedError:
            # Fallback to cache or alternative source
            return self._get_cached_user(user_id)

client = APIClient(api_keys=["key1", "key2", "key3"])
user = client.get_user(123)

🔧 Configuration Options

Parameter	Type	Default	Description
api_keys	List[str] or str	None	API keys to rotate
env_var	str	"API_KEYS"	Environment variable name
max_retries	int	3	Max retry attempts per key
base_delay	float	1.0	Base delay for exponential backoff
timeout	float	10.0	Request timeout in seconds
user_agents	List[str]	None	User-Agent strings to rotate
random_delay_range	Tuple[float, float]	None	Random delay range (min, max)
proxy_list	List[str]	None	Proxy URLs to rotate
error_classifier	ErrorClassifier	None	Custom error classifier

📚 View Complete API Reference →

🛡️ Error Handling

from apikeyrotator import (
    APIKeyRotator,
    NoAPIKeysError,
    AllKeysExhaustedError
)

try:
    rotator = APIKeyRotator(api_keys=["key1", "key2"])
    response = rotator.get("https://api.example.com/data")
    
except NoAPIKeysError:
    print("❌ No API keys provided or found")
    
except AllKeysExhaustedError:
    print("❌ All keys failed after maximum retries")
    # Implement fallback strategy
    
except Exception as e:
    print(f"❌ Unexpected error: {e}")

Error Classification System:

• RATE_LIMIT (429): Switches to next key immediately
• TEMPORARY (5xx): Retries with exponential backoff
• PERMANENT (401, 403): Removes invalid key from pool
• NETWORK: Connection errors, retries or switches key

📖 Learn More About Error Handling →

🎯 Advanced Features

🎭 Custom Retry Logic def custom_retry(response): if response.status_code == 429: return True try: return 'error' in response.json() except: return False rotator = APIKeyRotator( api_keys=["key1"], should_retry_callback=custom_retry )

🔑 Dynamic Headers def header_callback(key, headers): return { "Authorization": f"Bearer {key}", "X-Client-Version": "2.0" }, {} rotator = APIKeyRotator( api_keys=["key1"], header_callback=header_callback )

🚀 Explore Advanced Features →

📚 Documentation

Resource	Description
📖 Documentation Index	Complete documentation hub
🚀 Getting Started	Quick start guide
📋 API Reference	Complete API documentation
💡 Examples	Real-world code examples
🔧 Advanced Usage	Power features & customization
🚨 Error Handling	Comprehensive error management
❓ FAQ	Frequently asked questions
🔒 Security	Security best practices

🧪 Testing

# Install test dependencies
pip install pytest pytest-asyncio requests-mock aioresponses

# Run all tests
pytest

# Run with coverage
pytest --cov=apikeyrotator --cov-report=html

# Run specific test file
pytest tests/test_rotator.py -v

🤝 Contributing

Contributions are what make the open-source community amazing! We welcome:

• 🐛 Bug reports
• 💡 Feature suggestions
• 📝 Documentation improvements
• 🔧 Code contributions

📖 Read Contributing Guidelines →

Quick Contribution Steps

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📈 Performance

APIKeyRotator is optimized for production use:

• ⚡ Connection Pooling: Reuses TCP connections
• 🧠 Smart Caching: Caches successful header configurations
• 🔄 Async Support: Handle thousands of concurrent requests
• 📊 Memory Efficient: Minimal memory footprint

Benchmarks

# Synchronous: ~100 requests/second
# Asynchronous: ~1000 requests/second (10x faster)

🔒 Security

Security is a top priority. Please review our Security Policy for:

• 🔐 Best practices for API key management
• 🛡️ Reporting vulnerabilities
• 📜 Security features
• ✅ Security audit checklist

Found a security issue? Please report it privately to develop@eclips-team.ru

📜 License

Distributed under the MIT License. See LICENSE for more information.

🌟 Star History

💖 Support

If you find this project helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 📢 Sharing with others

📞 Contact & Support

• GitHub Issues: Report bugs
• GitHub Discussions: Ask questions
• Email: develop@eclips-team.ru

🔗 Links

• PyPI: pypi.org/project/apikeyrotator
• GitHub: github.com/PrimeevolutionZ/apikeyrotator
• Documentation: Full Documentation
• Changelog: What's New

---

Made with 🔄 and ❤️ by Eclips Team

⬆️ Back to top