pyBotB API

class pybotb.botb.BotB(app_name=None)

Bases: object

BotB API class.

Exposes access to the official BotB API, documented on the Lyceum (https://battleofthebits.com/lyceum/View/BotB+API+v1).

Parameters:

app_name (str | None)

property app_name: str

Custom app name; added to the user agent.

Setting this is highly recommended.

botbr_load(botbr_id)

Load a BotBr’s info by their ID.

Api:

/api/v1/botbr/load

Parameters:

botbr_id (int) – ID of the botbr to load.

Return type:

Optional[BotBr]

Returns:

BotBr object representing the user, or None if the user is not found.

Raises:

ConnectionError – On connection error.

botbr_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for BotBrs that match the given query.

For a list of supported filter/condition properties, see BotBr.

Api:

/api/v1/botbr/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[BotBr]

Returns:

PaginatedList of BotBr objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
botbr_random()

Get a random BotBr.

Api:

/api/v1/botbr/random

Return type:

BotBr

Returns:

BotBr object representing the user.

Raises:

ConnectionError – On connection error.

Search for BotBrs that match the given query.

Api:

/api/v1/botbr/search

Parameters:

  • query (str) – Search query for the search.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[BotBr]

Returns:

PaginatedList of BotBr objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:

ConnectionError – On connection error.

property botbr_levels: List[int]

List of level-up steps for a BotBr, from level 0 to 34 (the maximum).

Api:

/api/v1/botbr/levels

botbr_get_id_for_username(username)

Get the ID of a BotBr by their username.

Parameters:

username (str) – Username of the BotBr to find the ID of.

Return type:

Optional[int]

Returns:

int containing the ID, or None if the user is not found.

Raises:

ConnectionError – On connection error.

botbr_load_for_username(username)

Load BotBr info by username.

Parameters:

username (str) – Username of the BotBr to fetch the information of.

Return type:

Optional[BotBr]

Returns:

BotBr object representing the user, or None if the user is not found.

Raises:

ConnectionError – On connection error.

botbr_get_entries(botbr_id, submitted_only=False, desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

List all entries which the BotBr authored (i.e. both entries submitted by the BotBr and entries where they were tagged as a collaborator).

For only entries submitted by the BotBr, set submitted_only to True.

Api:

/api/v1/entry/botbr_favorites_playlist

Parameters:

  • botbr_id (int) – ID of the BotBr to get favorites for.

  • submitted_only (bool) – If True, returns only entries submitted by this BotBr directly, excluding collaborations.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Entry]

Returns:

PaginatedList of Entry objects representing the list results. If the search returned no results, the list will be empty.

Raises:

ConnectionError – On connection error.

botbr_get_favorite_entries(botbr_id, desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

List all entries favorited by the BotBr with the given ID.

Parameters:

  • botbr_id (int) – ID of the BotBr to get favorites for.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Entry]

Returns:

List of Entry objects representing the list results. If the search returned no results, the list will be empty.

Raises:

ConnectionError – On connection error.

botbr_get_palettes(botbr_id, desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

List all palettes created by the BotBr with the given ID.

Convinience shorthand for :py:method:.BotB.palette_list which pre-fills the filters to search for the entry and automatically aggregates all results pages.

Parameters:

  • botbr_id (int) – ID of the BotBr to get palettes for.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum number of items to return; set to 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Palette]

Returns:

List of Palette objects representing the search results. If the search returned no results, the list will be empty.

Raises:

ConnectionError – On connection error.

botbr_get_badge_progress(botbr_id)

Get the badge progress for the BotBr with the given ID.

This is the same as the list in the Badges tab of a BotBr’s profile; if you’re only interested in which badges a BotBr has earned and which level they’re at, use the regular BotBr load/list/etc. endpoints - this information is returned by the API.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Parameters:

botbr_id (int) – ID of the BotBr to get badge progress for.

Return type:

Dict[str, int]

Returns:

Dictionary with badge token as the key and progress as the value. Dict will be empty if the BotBr was not found.

Raises:

ConnectionError – On connection error.

botbr_get_tags_given(botbr_id)

List tags given by the BotBr.

This is the same as the list in the Tags tab of a BotBr’s profile.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Parameters:

botbr_id (int) – ID of the BotBr to get given tags for.

Return type:

List[str]

Returns:

List of given tags. List will be empty if the BotBr was not found.

Raises:

ConnectionError – On connection error.

botbr_get_tags_received(botbr_id)

List tags received by the BotBr.

This is the same as the list in the Tags tab of a BotBr’s profile.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Parameters:

botbr_id (int) – ID of the BotBr to get received tags for.

Return type:

List[str]

Returns:

List of given tags. List will be empty if the BotBr was not found.

Raises:

ConnectionError – On connection error.

botbr_get_avatars(botbr_id)

List the URLs of the current and all past avatars of the BotBr.

This is the same as the list in the Avatars tab of a BotBr’s profile.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Parameters:

botbr_id (int) – ID of the BotBr to get avatars for.

Return type:

List[str]

Returns:

List of avatar URLs. List will be empty if the BotBr was not found or had no avatars or has avatar history disabled.

Raises:

ConnectionError – On connection error.

botbr_get_battles_hosted(botbr_id, submitted_only=False, desc=True, sort='id', filters=None, conditions=None, max_items=0, offset=0)

Get a list of battles hosted by the BotBr with the given ID.

This is the same as the list in the Battles Hosted tab of a BotBr’s profile (so, it includes battles both directly hosted and co-hosted by the BotBr).

This is an unofficial method; it uses parsed data from the site, not an API endpoint. A similar endpoint could be implemented with just API methods; in which case, one would have to combine the following queries:

  • “botbr_id” matches the ID of the botbr;

  • If there’s a + sign in “hosts_names” (and the BotBr hosting the battle doesn’t simply have a + in their username), it’s a cohosted battle. Names are joined by + signs; you’ll likely need to perform three “hosts_names LIKE” conditions to get them correctly: “{name} +%”, “%+ {name} +%” and “%+ {name}”.

Since this is a lot of work and cannot be easily combined into one iterable (not with our tools, anyways! Maybe in the future…), we just parse the site instead.

Parameters:

  • botbr_id (int) – ID of the BotBr to get avatars for.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

  • submitted_only (bool)

Return type:

Iterable[Battle]

Returns:

PaginatedList of battles that the BotBr hosted/co-hosted.

Raises:

ConnectionError – On connection error.

botbr_get_country_code(botbr_id)

Get the two-letter country code of the BotBr.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Parameters:

botbr_id (int) – ID of the BotBr to get the country code for.

Return type:

Optional[str]

Returns:

String containing the two-letter country code, or None if the user was not found.

Raises:

ConnectionError – On connection error.

botbr_get_points(botbr_id, desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Get full points data (BotBrPoints objects) for the BotBr with the given ID.

Parameters:

  • botbr_id (int) – ID of the BotBr to get points data for.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[BotBrPoints]

Returns:

List of Entry objects representing the list results. If the search returned no results, the list will be empty.

Raises:

ConnectionError – On connection error.

botbr_points_load(botbr_points_id)

Load a BotBr’s points info by the ID of the points object.

To get points for a BotBr, see :py:method:.BotB.botbr_get_points.

Api:

/api/v1/botbr_points/load

Parameters:

botbr_points_id (int) – ID of the botbr_points object to load.

Return type:

Optional[BotBrPoints]

Returns:

BotBrPoints object representing the user’s points, or None if the user is not found.

Raises:

ConnectionError – On connection error.

botbr_points_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for botbr_points objects that match the given query.

For a list of supported filter/condition properties, see BotBrPoints.

Api:

/api/v1/botbr_points/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[BotBrPoints]

Returns:

PaginatedList of BotBrPoints objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
botbr_points_random()

Get a random botbr_points object.

Api:

/api/v1/botbr_points/random

Return type:

BotBrPoints

Returns:

BotBrPoints object representing the result.

Raises:

ConnectionError – On connection error.

battle_load(battle_id)

Load a battle’s info by its ID.

Api:

/api/v1/battle/load

Parameters:

battle_id (int) – ID of the battle to load.

Return type:

Optional[Battle]

Returns:

Battle object representing the battle, or None if the battle is not found.

Raises:

ConnectionError – On connection error.

battle_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for battles that match the given query.

For a list of supported filter/condition properties, see Battle.

Api:

/api/v1/battle/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Battle]

Returns:

PaginatedList of Battle objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
battle_random()

Get a random battle.

Api:

/api/v1/battle/random

Return type:

Battle

Returns:

Battle object representing the battle.

Raises:

ConnectionError – On connection error.

Search for battles that match the given query.

Api:

/api/v1/battle/search

Parameters:

  • query (str) – Search query for the search.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Battle]

Returns:

PaginatedList of Battle objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:

ConnectionError – On connection error.

battle_current()

Get a list of upcoming and ongoing battles.

Api:

/api/v1/battle/current

Return type:

List[Battle]

Returns:

List of Battle objects representing the battles. If there are no upcoming/ongoing battles, the list will be empty.

Raises:

ConnectionError – On connection error.

battle_list_by_date(date)

List all battles that happened/were ongoing on this year-month-day date (EST timezone).

Api:

/api/v1/battle/list_by_date

Parameters:

date (Union[str, date, datetime]) – Date to look for; either a string in “YYYY-MM-DD” format or a datetime.date or datetime.datetime object.

Return type:

List[Battle]

Returns:

List of Battle objects representing the battles. If there are no matching battles, the list will be empty.

Raises:

ConnectionError – On connection error.

battle_list_by_month(date='')

List all battles that happened/were ongoing on the specified month in the specified year (EST timezone).

Api:

/api/v1/battle/list_by_month

Parameters:

  • date (str) – Date as a YYYY-MM string.

  • year – Year to look for.

  • month – Month to look for.

Return type:

List[Battle]

Returns:

List of Battle objects representing the battles. If there are no matching battles, the list will be empty.

Raises:

ConnectionError – On connection error.

battle_get_entries(battle_id, desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Get the entries submitted to this battle.

Shorthand for .entry_list with a condition to match for the battle ID.

For a list of supported filter/condition properties, see Entry.

Api:

/api/v1/entry/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

  • battle_id (int)

Return type:

List[Entry]

Returns:

PaginatedList of Entry objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
battle_get_description(battle_id)

Get the description of a major battle.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Return type:

Optional[str]

Returns:

HTML representation of battle description as a string or None if the battle is not a major.

Raises:

ConnectionError – On connection error

Parameters:

battle_id (int)

battle_get_voting_categories(battle_id)

Get the voting categories of a major battle.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Return type:

Optional[List[str]]

Returns:

List of strings representing voting category names or None if the battle is not a major.

Raises:

ConnectionError – On connection error

Parameters:

battle_id (int)

battle_get_bitpacks(battle_id)

Get a list of bitpack URLs for the battle.

Bitpacks are ordered by period, from earliest to latest. OHBs only have an entry period, so this list will only have one item. Majors usually only have an entry period and thus only one item; there are also majors with a bit period (e.g. Detroit series), although the bit period does not have its own bitpack; and the Advent Calendar majors, which have a separate period for each day, each with its own bitpack. Some majors, like Winter Chip/Summer Chip, have no bitpack.

This is an unofficial method; it uses parsed data from the site, not an API endpoint.

Return type:

List[str]

Returns:

List of strings representing voting category names or None if the battle is not a major.

Raises:

ConnectionError – On connection error

Parameters:

battle_id (int)

entry_load(entry_id)

Load a entry’s info by their ID.

Api:

/api/v1/entry/load

Parameters:

entry_id (int) – ID of the entry to load.

Return type:

Optional[Entry]

Returns:

Entry object representing the entry, or None if the entry is not found.

Raises:

ConnectionError – On connection error.

entry_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for entries that match the given query.

For a list of supported filter/condition properties, see Entry.

Api:

/api/v1/entry/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Entry]

Returns:

PaginatedList of Entry objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
entry_random()

Get a random entry.

Api:

/api/v1/entry/random

Return type:

Entry

Returns:

Entry object representing the entry.

Raises:

ConnectionError – On connection error.

Search for entries that match the given query.

Api:

/api/v1/entry/search

Parameters:

  • query (str) – Search query for the search.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Entry]

Returns:

PaginatedList of Entry objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:

ConnectionError – On connection error.

entry_get_tags(entry_id, desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

List all tags given to entry with the given ID.

Convinience shorthand for :py:method:.BotB.tag_list which pre-fills the filters to search for the entry and automatically aggregates all results pages.

Parameters:

  • entry_id (int) – ID of the entry to get tags for.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum number of items to return; set to 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Tag]

Returns:

List of Tag objects representing the search results. If the search returned no results, the list will be empty.

Raises:

ConnectionError – On connection error.

entry_get_playlist_ids(entry_id, max_items=0, offset=0)

Get a list containing the playlist IDs of playlists that this entry has been added to.

To get a list of Playlist objects, see :method:.BotBr.entry_get_playlists.

Parameters:

  • entry_id (int) – ID of the entry to load the playlists of.

  • max_items (int) – Maximum number of items to return; set to 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

List[int]

Returns:

List of playlist IDs.

Raises:

ConnectionError – On connection error.

entry_get_playlists(entry_id, max_items=0, offset=0)

Get a list of playlists that this entry has been added to.

Parameters:

  • entry_id (int) – ID of the playlist to load the entries of.

  • max_items (int) – Maximum number of items to return; set to 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Playlist]

Returns:

List of Playlist objects.

Raises:

ConnectionError – On connection error.

entry_get_favorites(entry_id, desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

List all favorites for the entry with the given ID.

Convinience shorthand for :py:method:.BotB.favorite_list which pre-fills the filters to search for the entry and automatically aggregates all results pages.

Parameters:

  • entry_id (int) – ID of the entry to get favorites for.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum number of items to return; set to 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Favorite]

Returns:

List of Favorite objects representing the search results. If the search returned no results, the list will be empty.

Raises:

ConnectionError – On connection error.

favorite_load(favorite_id)

Load a favorite’s info by their ID.

Api:

/api/v1/favorite/load

Parameters:

favorite_id (int) – ID of the favorite to load.

Return type:

Optional[Favorite]

Returns:

Favorite object representing the favorite, or None if the favorite is not found.

Raises:

ConnectionError – On connection error.

favorite_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for favorites that match the given query.

For a list of supported filter/condition properties, see Favorite.

Api:

/api/v1/favorite/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Favorite]

Returns:

PaginatedList of Favorite objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
favorite_random()

Get a random favorite.

Api:

/api/v1/favorite/random

Return type:

Favorite

Returns:

Favorite object representing the favorite.

Raises:

ConnectionError – On connection error.

format_load(format_id)

Load a format’s info by their ID.

Api:

/api/v1/format/load

Parameters:

format_id (int) – ID of the format to load.

Return type:

Optional[Format]

Returns:

Format object representing the format, or None if the format is not found.

Raises:

ConnectionError – On connection error.

format_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for formats that match the given query.

For a list of supported filter/condition properties, see Format.

Api:

/api/v1/format/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Format]

Returns:

PaginatedList of Format objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
format_random()

Get a random format.

Api:

/api/v1/format/random

Return type:

Format

Returns:

Format object representing the format.

Raises:

ConnectionError – On connection error.

group_thread_load(group_thread_id)

Load a group thread’s info by their ID.

Api:

/api/v1/group_thread/load

Parameters:

group_thread_id (int) – ID of the group thread to load.

Return type:

Optional[GroupThread]

Returns:

GroupThread object representing the group thread, or None if the group thread is not found.

Raises:

ConnectionError – On connection error.

group_thread_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for group threads that match the given query.

For a list of supported filter/condition properties, see GroupThread.

Api:

/api/v1/group_thread/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[GroupThread]

Returns:

PaginatedList of GroupThread objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
group_thread_random()

Get a random group thread.

Api:

/api/v1/group_thread/random

Return type:

GroupThread

Returns:

GroupThread object representing the group thread.

Raises:

ConnectionError – On connection error.

Search for group threads that match the given query.

Api:

/api/v1/group_thread/search

Parameters:

  • query (str) – Search query for the search.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[GroupThread]

Returns:

PaginatedList of GroupThread objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:

ConnectionError – On connection error.

lyceum_article_load(lyceum_article_id)

Load a lyceum article’s info by their ID.

Api:

/api/v1/lyceum_article/load

Parameters:

lyceum_article_id (int) – ID of the lyceum article to load.

Return type:

Optional[LyceumArticle]

Returns:

LyceumArticle object representing the lyceum article, or None if the lyceum article is not found.

Raises:

ConnectionError – On connection error.

lyceum_article_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for lyceum articles that match the given query.

For a list of supported filter/condition properties, see LyceumArticle.

Api:

/api/v1/lyceum_article/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[LyceumArticle]

Returns:

PaginatedList of LyceumArticle objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
lyceum_article_random()

Get a random lyceum article.

Api:

/api/v1/lyceum_article/random

Return type:

LyceumArticle

Returns:

LyceumArticle object representing the lyceum article.

Raises:

ConnectionError – On connection error.

lyceum_article_search(query, max_items=0, offset=0)

Search for lyceum articles that match the given query.

Api:

/api/v1/lyceum_article/search

Parameters:

  • query (str) – Search query for the search.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[LyceumArticle]

Returns:

PaginatedList of LyceumArticle objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:

ConnectionError – On connection error.

palette_load(palette_id)

Load a palette’s info by their ID.

Api:

/api/v1/palette/load

Parameters:

palette_id (int) – ID of the palette to load.

Return type:

Optional[Palette]

Returns:

Palette object representing the palette, or None if the palette is not found.

Raises:

ConnectionError – On connection error.

palette_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for palettes that match the given query.

For a list of supported filter/condition properties, see Palette.

Api:

/api/v1/palette/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Palette]

Returns:

PaginatedList of Palette objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
palette_random()

Get a random palette.

Api:

/api/v1/palette/random

Return type:

Palette

Returns:

Palette object representing the palette.

Raises:

ConnectionError – On connection error.

palette_current_default()

Get the current default on-site palette.

Api:

/api/v1/palette/current_default

Return type:

Palette

Returns:

Palette object representing the current default palette.

Raises:

ConnectionError – On connection error.

playlist_load(playlist_id)

Load a playlist’s info by their ID.

Api:

/api/v1/playlist/load

Parameters:

playlist_id (int) – ID of the playlist to load.

Return type:

Optional[Playlist]

Returns:

Playlist object representing the playlist, or None if the playlist is not found.

Raises:

ConnectionError – On connection error.

playlist_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for playlists that match the given query.

For a list of supported filter/condition properties, see Playlist.

Api:

/api/v1/playlist/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Playlist]

Returns:

PaginatedList of Playlist objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
playlist_random()

Get a random playlist.

Api:

/api/v1/playlist/random

Return type:

Playlist

Returns:

Playlist object representing the playlist.

Raises:

ConnectionError – On connection error.

Search for playlists that match the given query.

Api:

/api/v1/playlist/search

Parameters:

  • query (str) – Search query for the search.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Playlist]

Returns:

PaginatedList of Playlist objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:

ConnectionError – On connection error.

playlist_get_entry_ids(playlist_id, max_items=0, offset=0)

Get a list containing the entry IDs of the playlist with the given ID, in the order that they appear in the playlist.

To get a list of entry objects, see :method:.BotBr.playlist_get_entries.

Parameters:

  • playlist_id (int) – ID of the playlist to load the entries of.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

List[int]

Returns:

List of entry IDs.

Raises:

ConnectionError – On connection error.

playlist_get_entries(playlist_id)

Get a list containing a the entries in the playlist with the given ID, in the order that they appear in the playlist.

Api:

/api/v1/entry/playlist_playlist

Parameters:

playlist_id (int) – ID of the playlist to load the entries of.

Return type:

List[Entry]

Returns:

List of entry IDs.

Raises:

ConnectionError – On connection error.

tag_load(tag_id)

Load a tag’s info by their ID.

Api:

/api/v1/tag/load

Parameters:

tag_id (int) – ID of the tag to load.

Return type:

Optional[Tag]

Returns:

Tag object representing the tag, or None if the tag is not found.

Raises:

ConnectionError – On connection error.

tag_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for tags that match the given query.

For a list of supported filter/condition properties, see Tag.

Api:

/api/v1/tag/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Tag]

Returns:

PaginatedList of Tag objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
tag_random()

Get a random tag.

Api:

/api/v1/tag/random

Return type:

Tag

Returns:

Tag object representing the tag.

Raises:

ConnectionError – On connection error.

Search for tags that match the given query.

Api:

/api/v1/tag/search

Parameters:

  • query (str) – Search query for the search.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Tag]

Returns:

PaginatedList of Tag objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:

ConnectionError – On connection error.

tag_cloud_by_substring_html(substring)

Get the HTML representation of a tag cloud for tags matching the substring.

:method:`.tag_cloud_by_substring` parses the HTML data into a dict of tag: size pairs for convenience.

Api:

/api/v1/tag/cloud_by_substring

Parameters:

substring (str) – String to pass as the search substring.

Return type:

str

Returns:

String containing the HTML representation of the tag cloud.

Raises:

ConnectionError – On connection error.

tag_cloud_by_substring(substring)

Get a tag cloud by the given substring; returns a dict of tag: size pairs.

Api:

/api/v1/tag/cloud_by_substring

Parameters:

substring (str) – String to pass as the search substring.

Return type:

Dict[str, int]

Returns:

Dict with tag name as the key and size in pixels as the value.

Raises:

ConnectionError – On connection error.

tag_get_entry_ids(tag)

Get a list of entry IDs which have this tag.

Parameters:

tag (str) – Tag to fetch entries for.

Return type:

List[int]

Returns:

PaginatedList of entries which have the given tag.

Raises:

ConnectionError – On connection error.

tag_get_entries(tag, desc=True, sort='id', filters=None, conditions=None, max_items=0, offset=0)

Get a PaginatedList of entries which have this tag.

Parameters:

  • tag (str) – Tag to fetch entries for.

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[Entry]

Returns:

PaginatedList of entries which have the given tag.

Raises:

ConnectionError – On connection error.

botbr_stats_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for BotBr stats that match the given query.

For a list of supported filter/condition properties, see BotBrStats.

Api:

/api/v1/botbr_stats/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[BotBrStats]

Returns:

PaginatedList of BotBrStats objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
botbr_stats_by_botbr_id(botbr_id)

Get a list of BotBrStats objects representing all of the BotBr’s stats.

Returns an empty list for nonexistent BotBrs.

Api:

/api/v1/botbr_stats/by_botbr_id

Return type:

List[BotBrStats]

Returns:

List of BotBrStats objects representing the BotBr stats.

Raises:

ConnectionError – On connection error.

Parameters:

botbr_id (int)

botbr_stats_days_back(botbr_id, n_days)

Get a list of BotBrStats objects representing the BotBr’s stats from the last {n_days} days.

Returns an empty list for nonexistent BotBrs.

Api:

/api/v1/botbr_stats/days_back

Return type:

List[BotBrStats]

Returns:

List of BotBrStats objects representing the BotBr stats.

Raises:

ConnectionError – On connection error.

Parameters:
botbr_stats_random()

Get a random BotBr stat.

Api:

/api/v1/botbr_stats/random

Return type:

BotBrStats

Returns:

BotBrStats object representing the stats.

Raises:

ConnectionError – On connection error.

daily_stats_load(daily_stats_id)

Load a daily stat’s info by their ID.

Api:

/api/v1/daily_stats/load

Parameters:

daily_stats_id (int) – ID of the daily_stats to load.

Return type:

Optional[DailyStats]

Returns:

DailyStats object representing the stats, or None if the object is not found.

Raises:

ConnectionError – On connection error.

daily_stats_list(desc=False, sort=None, filters=None, conditions=None, max_items=0, offset=0)

Search for daily stats that match the given query.

For a list of supported filter/condition properties, see DailyStats.

Api:

/api/v1/daily_stats/list

Parameters:

  • desc (bool) – If True, returns items in descending order. Requires sort key to be set.

  • sort (Optional[str]) – Object property to sort by.

  • filters (Optional[Dict[str, Any]]) – Dictionary with object property as the key and filter value as the value. Note that filters are deprecated; conditions should be used instead.

  • conditions (Optional[List[Condition]]) – List of Condition objects containing list conditions.

  • max_items (int) – Maximum amount of items to return; 0 for no limit.

  • offset (int) – Skip the first N items.

Return type:

Iterable[DailyStats]

Returns:

PaginatedList of DailyStats objects representing the search results. If the search returned no results, the resulting iterable will return no results.

Raises:
daily_stats_random()

Get a random daily stat.

Api:

/api/v1/daily_stats/random

Return type:

DailyStats

Returns:

DailyStats object representing the stats.

Raises:

ConnectionError – On connection error.

firki_interpret(firki)

Interpret a Firki markup string into HTML.

Api:

/api/v1/firki/interpret

Parameters:

firki (str) – Firki markup input string.

Return type:

str

Returns:

String containing HTML output.

Raises:

ConnectionError – On connection error.

spriteshit_version()

Return the current version of the BotB spritesheet (affectionately named the spriteshit).

This version string can be used to fetch the spriteshit PNG from BotB’s assets (https://battleofthebits.com/styles/spriteshit/{version}.png).

Api:

/api/v1/spriteshit/version

Return type:

str

Returns:

The API version.

Raises:

ConnectionError – On connection error.

Helper classes

class pybotb.botb.Condition(property, operator, operand)

Bases: object

Represents a condition passed to a “list” API query.

Parameters:
property: str

Property that the condition applies to.

operator: str

Operator for the condition.

operand: Union[int, str, bool, List[Any], Tuple[Any]]

Operand for the condition.

class pybotb.botb.PaginatedList(func, max_items=0, offset=0, *args, **kwargs)

Bases: object

Iterable implementation for paginated API requests.

Automatically handles progressing to the next page, etc. Fetches as many objects as possible (500 per page), unless max_items is set to a lower value.

Parameters: