brawlstars.py

Installation

Python 3.8 or higher is required.

To install the stable version, do the following:

# Unix / macOS
python3 -m pip install "brawlstars.py"

# Windows
py -m pip install "brawlstars.py"

To install the development version, do the following:

$ git clone https://github.com/Ombucha/brawlstars.py

Make sure you have the latest version of Python installed, or if you prefer, a Python version of 3.8 or greater.

If you have have any other issues feel free to search for duplicates and then create a new issue on GitHub with as much detail as possible. Include the output in your terminal, your OS details and Python version.

Client

class brawlstars.Client(token: str, *, session: Session | None = None)

A class that represents a client.

Parameters:

  • token (str) – The Brawl Stars API token.

  • session (Optional[requests.Session]) – The session to use.

get_brawler(brawler_id: str) → BrawlStarsObject

Gets a list of brawlers.

Parameters:

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

get_brawler_rankings(country: str, brawler_id: int, *, before: str | None = None, after: str | None = None, limit: int | None = None) → PlayerRanking

Gets global brawler rankings or those for a specific country.

Parameters:

  • country (str) – The two-letter country code, or ‘global’ for global rankings.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_brawlers(*, before: str | None = None, after: str | None = None, limit: int | None = None) → List[BrawlStarsObject]

Gets a list of brawlers.

Parameters:

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_club(tag: str) → BrawlStarsObject

Gets information about a single club.

Parameters:

tag (str) – The tag of the club.

get_club_members(tag: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → ClubMemberList

Gets a list of club members.

Parameters:

  • tag (str) – The tag of the club.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_club_rankings(country: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → ClubRanking

Gets global club rankings or those for a specific country.

Parameters:

  • country (str) – The two-letter country code, or ‘global’ for global rankings.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

get_event_rotation() → EventList

Gets the event rotation.

get_player(tag: str) → Player

Gets information about a single player.

Parameters:

tag (str) – The tag of the player.

get_player_battlelog(tag: str) → Battlelog

Gets a list of recent battle results for a player.

Note

It may take up to 30 minutes for a new battle to appear in the battlelog.

Parameters:

tag (str) – The tag of the player.

get_player_rankings(country: str, *, before: str | None = None, after: str | None = None, limit: int | None = None) → PlayerRanking

Gets global player rankings or those for a specific country.

Parameters:

  • country (str) – The two-letter country code, or ‘global’ for global rankings.

  • before (Optional[str]) – The marker to return items before.

  • after (Optional[str]) – The marker to return items after.

  • limit (Optional[int]) – The maximum number of items to be returned.

Note

If both before and after are provided, a ValueError is raised.

on_battlelog_update(tag: str, repeat_duration: float | None = 60)

Event that is called when a player’s battlelog is updated.

Parameters:

  • tag (str) – The tag of the player.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_member_join(tag: str, *, repeat_duration: float | None = 60)

Event that is called when a member joins a club.

Parameters:

  • tag (str) – The tag of the club.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

on_member_leave(tag: str, repeat_duration: float | None = 60)

Event that is called when a member leaves a club.

Parameters:

  • tag (str) – The tag of the club.

  • repeat_duration (Optional[float]) – The time to sleep for between every check.

Models

class brawlstars.Battlelog(_data: dict)

A class that represents a player’s battlelog.

class brawlstars.BrawlStarsObject(_data: dict | list | tuple)

A class that represents a custom object for the library.

class brawlstars.ClubMemberList(_data: dict)

A class that represents a list of club members.

class brawlstars.ClubRanking(_data: dict)

A class that represents a club’s rank.

class brawlstars.EventList(_data: dict)

A class that represents a list of events.

class brawlstars.Player(_data: dict)

A class that represents a player.

class brawlstars.PlayerRanking(_data: dict)

A class that represents a player’s rank.

Exceptions

class brawlstars.BrawlStarsException

Base exception class for this library.

class brawlstars.ForbiddenError

An exception that is raised when access is denied, either because of missing/incorrect credentials or used API token does not grant access to the requested resource.

class brawlstars.MaintenanceError

An exception that is raised when the service is temporarily unavailable because of maintenance.

class brawlstars.RateLimitError

An exception that is raised when the amount of requests was above the threshold defined for the used API token.

class brawlstars.UncallableError

An exception that is raised when a function is not callable.

class brawlstars.UnknownError

An exception that is raised when an unknown error occurs while handling the request.