PyBrawlStars 1.0.4

An asynchronous Python wrapper for the Brawl Stars API

PyBrawlStars

An asynchronous Python API wrapper for the Brawl Stars API that provides easy access to player statistics, club information, battle logs, and more.

🚀 Features

• Fully Asynchronous: Built with httpx for high-performance async operations
• Type Hints: Complete type annotations for better IDE support and code reliability
• Comprehensive Models: Rich data models for all Brawl Stars entities
• Error Handling: Proper exception handling with custom error types
• Auto Tag Parsing: Automatic handling of Brawl Stars player/club tags
• Session Management: Efficient HTTP session management with connection pooling
• Rate Limiting Ready: Built to handle API rate limits gracefully
• Easy Installation: Available on PyPI for simple pip installation

📦 Installation

Install the package from PyPI:

pip install pybrawlstars

🔑 Getting Started

1. Get Your API Key

First, obtain your API key from the Brawl Stars Developer Portal.

2. Basic Usage

import asyncio
from pybrawlstars import BSClient

async def main():
    # Initialize the client with your API key
    client = BSClient("YOUR_API_KEY")
    
    try:
        # Get player information
        player = await client.get_player("2PPQVUQ8J")
        print(f"Player: {player.name}")
        print(f"Trophies: {player.trophies}")
        
        # Get club information
        club = await client.get_club("2L90CG289")
        print(f"Club: {club.name}")
        print(f"Members: {len(club.members)}")
        
    finally:
        # Always close the client when done
        await client.close()

# Run the async function
asyncio.run(main())

3. Using Context Manager (Recommended)

import asyncio
from pybrawlstars import BSClient

async def main():
    async with BSClient("YOUR_API_KEY") as client:
        player = await client.get_player("2PPQVUQ8J")
        print(f"Player: {player.name}")
        # Client automatically closes when exiting the context

asyncio.run(main())

📚 API Reference

BSClient

The main client class for interacting with the Brawl Stars API.

Note: Due to Brawl Stars API limitations, only the following 7 routes are supported:

• get_player - Get player profile
• get_battlelog - Get player battle log
• get_club - Get club information
• get_club_members - Get club members
• get_brawlers - Get all brawlers
• get_brawler - Get specific brawler by ID
• get_event_rotation - Get current event rotation

Constructor

BSClient(
    api_key: str,
    base_url: str = "https://api.brawlstars.com",
    version: int = 1,
    timeout: int = 10
)

Methods

Player Methods

# Get player profile
await client.get_player(tag: str)

# Get player battle log
await client.get_battlelog(tag: str)

Club Methods

# Get club information
await client.get_club(tag: str)

# Get club members
await client.get_club_members(tag: str)

Brawler Methods

# Get all brawlers
await client.get_brawlers()

# Get specific brawler by ID
await client.get_brawler(id: int)

Event Methods

# Get current event rotation
await client.get_event_rotation()

💡 Examples

Get Player Statistics

import asyncio
from pybrawlstars import BSClient

async def get_player_stats():
    async with BSClient("YOUR_API_KEY") as client:
        player = await client.get_player("PLAYER_TAG")
        
        print(f"🏆 {player.name}")
        print(f"Trophies: {player.trophies}")
        print(f"Experience Level: {player.exp_level}")
        print(f"3v3 Victories: {player.victories_3vs3}")
        print(f"Solo Victories: {player.solo_victories}")
        print(f"Duo Victories: {player.duo_victories}")
        
        if player.club:
            print(f"Club: {player.club.name}")

asyncio.run(get_player_stats())

Analyze Club Members

import asyncio
from pybrawlstars import BSClient

async def analyze_club():
    async with BSClient("YOUR_API_KEY") as client:
        club = await client.get_club("CLUB_TAG")
        
        print(f"📊 Club Analysis: {club.name}")
        print(f"Description: {club.description}")
        print(f"Total Members: {len(club.members)}")
        print(f"Required Trophies: {club.required_trophies}")
        
        # Group members by role
        roles = {}
        for member in club.members:
            role = member.role.name
            roles[role] = roles.get(role, 0) + 1
        
        print("\n👥 Member Roles:")
        for role, count in roles.items():
            print(f"  {role}: {count}")

asyncio.run(analyze_club())

Track Battle History

import asyncio
from pybrawlstars import BSClient

async def analyze_battles():
    async with BSClient("YOUR_API_KEY") as client:
        battles = await client.get_battlelog("PLAYER_TAG")
        
        wins = sum(1 for battle in battles if battle.battle.result == "victory")
        total = len(battles)
        win_rate = (wins / total) * 100 if total > 0 else 0
        
        print(f"⚔️ Recent Battle Performance")
        print(f"Total Battles: {total}")
        print(f"Victories: {wins}")
        print(f"Win Rate: {win_rate:.1f}%")
        
        # Analyze game modes
        modes = {}
        for battle in battles:
            mode = battle.event.mode
            modes[mode] = modes.get(mode, 0) + 1
        
        print("\n🎮 Game Modes Played:")
        for mode, count in sorted(modes.items(), key=lambda x: x[1], reverse=True):
            print(f"  {mode}: {count} battles")

asyncio.run(analyze_battles())

Browse All Brawlers

import asyncio
from pybrawlstars import BSClient

async def list_brawlers():
    async with BSClient("YOUR_API_KEY") as client:
        brawlers = await client.get_brawlers()
        
        print(f"🤖 Available Brawlers ({len(brawlers)}):")
        
        for brawler in sorted(brawlers, key=lambda b: b.name):
            print(f"\n{brawler.name} (ID: {brawler.id})")
            
            if brawler.star_powers:
                print("  Star Powers:")
                for sp in brawler.star_powers:
                    print(f"    - {sp.name}")
            
            if brawler.gadgets:
                print("  Gadgets:")
                for gadget in brawler.gadgets:
                    print(f"    - {gadget.name}")

asyncio.run(list_brawlers())

🏗️ Data Models

The library provides rich data models for all API responses:

• Player: Complete player profile with statistics and brawler progression
• Club: Club information including members and settings
• Battle: Individual battle results with participants and outcomes
• Brawler: Brawler information including star powers and gadgets
• Event: Current and upcoming game events
• And many more! Explore all available models in the library

⚠️ Error Handling

The library provides specific exception types for different error scenarios:

import asyncio
from pybrawlstars import BSClient
from pybrawlstars.models.errors import APIError, NetworkError, ClientError

async def safe_api_call():
    async with BSClient("YOUR_API_KEY") as client:
        try:
            player = await client.get_player("INVALID_TAG")
        except APIError as e:
            print(f"API Error {e.status_code}: {e.message}")
        except NetworkError as e:
            print(f"Network Error: {e}")
        except ValueError as e:
            print(f"Invalid input: {e}")
        except TimeoutError as e:
            print(f"Request timed out: {e}")

asyncio.run(safe_api_call())

🏷️ Tag Formats

Player and club tags can be provided in multiple formats:

• With hashtag: #2PPQVUQ8J
• Without hashtag: 2PPQVUQ8J

The library automatically handles tag parsing and URL encoding.

📋 Requirements

• Python 3.8+
• httpx: For async HTTP requests
• typing-extensions: For enhanced type hints (Python < 3.10)

🔄 Version History

Latest Release

Check PyPI for the latest version and changelog.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# Clone the repository
git clone https://github.com/yourusername/pybrawlstars.git
cd pybrawlstars

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• PyPI Package
• Brawl Stars API Documentation
• Brawl Stars Developer Portal
• Report Issues

⚡ Performance Tips

1. Use Context Managers: Always use async with BSClient() for automatic resource cleanup
2. Batch Requests: Group related API calls together when possible
3. Cache Results: Consider caching frequently accessed data like brawler lists
4. Handle Rate Limits: The API has rate limits; implement appropriate delays if needed
5. Reuse Client: Create one client instance and reuse it for multiple requests

🆘 Support

• 📖 Check the documentation for detailed guides
• 🐛 Report bugs on GitHub Issues
• 💬 Join discussions on GitHub Discussions

---

Note: This is an unofficial API wrapper. Brawl Stars is a trademark of Supercell Oy.