✨ Features

🚀 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

### 🛣️ Multi-Provider Fallback Routing

```python
from apikeyrotator import FallbackRouter, ProviderRoute, APIKeyRotator

router = FallbackRouter(routes=[
    ProviderRoute(name="Primary", rotator=APIKeyRotator(api_keys=["key1"])),
    ProviderRoute(
        name="Fallback",
        rotator=APIKeyRotator(api_keys=["key2"]),
        request_transformer=lambda m, u, k: (m, "https://api.fallback.com/data", k)
    )
])

# Automatically falls back to the second API if the first is exhausted!
response = router.get("https://api.primary.com/data")

### 🌟 Using Environment Variables

Create a `.env` file:

```bash
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

🎨 Use Cases

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...

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}")

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)))

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

📚 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

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
)

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

🧪 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 via the internal issue tracker.

📜 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

🔗 Links

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