Modules¶

`boardgamegeek.api` - Core functions¶

This module contains the core functionality needed to retrieve data from boardgamegeek.com and parse it into usable objects.

class boardgamegeek.api.BGGClient(access_token: str, cache: ~boardgamegeek.cache.CacheBackend = <boardgamegeek.cache.CacheBackendMemory object>, timeout: float = 15, retries: int = 3, retry_delay: float = 5, disable_ssl: bool = False, requests_per_minute: int = 30)[source]¶

Python client for www.boardgamegeek.com’s XML API 2.

Caching for the requests can be used by specifying a URI for the cache parameter. By default, an in-memory cache is used, with sqlite being the other currently supported option.

Parameters:: access_token (str) – BGG access token for API authentication See the BGG applications page to obtain an access token.

:param boardgamegeek.cache.CacheBackend cache: An object to be used for caching the requests :param float timeout: Timeout for network operations, in seconds :param int retries: Number of retries to perform in case the API returns HTTP 202 (retry) or in case of timeouts :param float retry_delay: Time to sleep, in seconds, between retries when the API returns HTTP 202 (retry) :param disable_ssl: ignored, left for backwards compatibility :param requests_per_minute: how many requests per minute to allow to go out to BGG (throttle prevention)

Example usage:

>>> bgg = BGGClient("<access_token_here>")
>>> game = bgg.game("Android: Netrunner")
>>> game.id
124742
>>> bgg_no_cache = BGGClient(cache=CacheBackendNone())
>>> bgg_sqlite_cache = BGGClient(cache=CacheBackendSqlite(path="/path/to/cache.db", ttl=3600))
>>> bgg_with_token = BGGClient(access_token="your_bgg_access_token")

Returns an user’s game collection

Parameters:

user_name (str) – user name to retrieve the collection for
subtype (str) – what type of items to return. One of the constants in boardgamegeek.api.BGGRestrictCollectionTo
exclude_subtype (str) – if not None (default), exclude the specified subtype. Else, one of the constants in boardgamegeek.api.BGGRestrictCollectionTo
ids (list) – if not None (default), limit the results to the specified ids.
versions (bool) – DEPRECATED use version instead
version (bool) – include item version information
own (bool) – include (if True) or exclude (if False) owned items
rated (bool) – include (if True) or exclude (if False) rated items
played (bool) – include (if True) or exclude (if False) played items
commented (bool) – include (if True) or exclude (if False) items commented on
trade (bool) – include (if True) or exclude (if False) items for trade
want (bool) – include (if True) or exclude (if False) items wanted in trade
wishlist (bool) – include (if True) or exclude (if False) items in the wishlist
wishlist_prio (int) – return only the items with the specified wishlist priority (valid values: 1 to 5)
preordered (bool) – include (if True) or exclude (if False) preordered items
want_to_play (bool) – include (if True) or exclude (if False) items wanting to play
want_to_buy (bool) – include (if True) or exclude (if False) items wanting to buy
prev_owned (bool) – include (if True) or exclude (if False) previously owned items
has_parts (bool) – include (if True) or exclude (if False) items for which there is a comment in the “Has parts” field
want_parts (bool) – include (if True) or exclude (if False) items for which there is a comment in the “Want parts” field
min_rating (float) – return items rated by the user with a minimum of min_rating
rating (float) – return items rated by the user with a maximum of rating

:param float min_bgg_rating : return items rated on BGG with a minimum of min_bgg_rating :param float bgg_rating: return items rated on BGG with a maximum of bgg_rating :param int min_plays: minimum number of recorded plays :param int max_plays: maximum number of recorded plays :param int collection_id: restrict results to the collection specified by this id :param str modified_since:

restrict results to those whose status (own, want, etc.) has been changed/added since modified_since. Format: YY-MM-DD or YY-MM-DD HH:MM:SS

Returns:: Collection object
Return type:: boardgamegeek.collection.Collection
Returns:: None if user not found
Raises:: boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)
Raises:: BGGApiRetryError if request should be retried after delay
Raises:: boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed
Raises:: boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

game(name: str | None = None, game_id: int | None = None, choose: str = 'first', versions: bool = False, videos: bool = False, historical: bool = False, marketplace: bool = False, comments: bool = False, rating_comments: bool = False, exact: bool = True) → BoardGame[source]¶

Get information about a game.

Parameters:

name (str) – If not None, get information about a game with this name
game_id (integer) – If not None, get information about a game with this id
choose (str) – method of selecting the game by name, when dealing with multiple results. Valid values are : “first”, “recent” or “best-rank”
versions (bool) – include versions information
videos (bool) – include videos
historical (bool) – include historical data
marketplace (bool) – include marketplace data
comments (bool) – include comments
rating_comments (bool) – include comments with rating (ignored in favor of comments, if that is true)
exact (bool) – limit results to items that match the name exactly

Returns:

BoardGame object

Return type:

boardgamegeek.games.BoardGame

Raises:

boardgamegeek.exceptions.BoardGameGeekError in case of invalid name or game_id

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if request should be retried after delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

game_list(game_id_list: list[int], versions: bool = False, videos: bool = False, historical: bool = False, marketplace: bool = False) → list[BoardGame][source]¶

Get list of games by from a list of ids.

Parameters:

game_id_list (list) – List of game ids
versions (bool) – include versions information
videos (bool) – include videos
historical (bool) – include historical data
marketplace (bool) – include marketplace data

Returns:

list of BoardGame objects

Return type:

list`

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

games(name: str) → list[BoardGame][source]¶

Return a list containing all games with the given name

Parameters:: name (str) – the name of the game to search for
Returns:: list of boardgamegeek.games.BoardGame
Raises:: boardgamegeek.exceptions.BoardGameGeekAPIRetryError if request should be retried after delay
Raises:: boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed
Raises:: boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

get_game_id(name: str, choose: str = 'first', exact: bool = True) → int[source]¶

Returns the BGG ID of a game, searching by name

Parameters:

name (str) – The name of the game to search for
choose (boardgamegeek.BGGChoose) – method of selecting the game by name, when dealing with multiple results.
exact (bool) – limit results to items that match the name exactly

Returns:

the game’s id

Return type:

integer

Returns:

None if game wasn’t found

Raises:

boardgamegeek.exceptions.BGGError in case of invalid name

Raises:

BGGApiRetryError if request should be retried after delay

Raises:

boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

guild(guild_id: int, members: bool = True) → Guild¶

Retrieves details about a guild

Parameters:

guild_id (integer) – the id number of the guild
members (bool) – if True, names of the guild members will be fetched

Returns:

Guild object containing the data

Returns:

None if the information couldn’t be retrieved

Return type:

boardgamegeek.guild.Guild

Raises:

BGGValueError in case of an invalid parameter(s)

Raises:

boardgamegeek.exceptions.BGGApiRetryError if request should be retried after delay

Raises:

boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

hot_items(item_type: str) → HotItems¶

Return the list of “Hot Items”

Parameters:: item_type (str) – hot item type. Valid values: “boardgame”, “rpg”, “videogame”, “boardgameperson”, “rpgperson”, “boardgamecompany”, “rpgcompany”, “videogamecompany”)
Returns:: HotItems object
Return type:: boardgamegeek.hotitems.HotItems
Returns:: None in case the hot items couldn’t be retrieved
Raises:: boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)
Raises:: boardgamegeek.exceptions.BGGApiRetryError if this request should be retried after a short delay
Raises:: boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed
Raises:: boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

plays(name: str | None = None, game_id: int | None = None, min_date: date | None = None, max_date: date | None = None, subtype: str = 'boardgame') → Plays¶

Retrieves the plays for n user (if using name) or for a game (if using game_id)

Parameters:

name (str) – username to retrieve the plays for
game_id (integer) – game id to retrieve the plays for
min_date (datetime.date) – return only plays of the specified date or later
max_date (datetime.date) – return only plays of the specified date or earlier
subtype (str) – limit plays results to the specified subtype.

Returns:

object containing all the plays

Return type:

boardgamegeek.plays.Plays

Returns:

None if the user/game couldn’t be found

Raises:

boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)

Raises:

BGGApiRetryError if request should be retried after delay

Raises:

boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

search(query: str, search_type: list[str] | None = None, exact: bool = False) → list[SearchResult]¶

Search for a game

Parameters:

query (str) – the string to search for
search_type (list) – DEPRECATED will be removed in future versions. list of boardgamegeek.api.BGGRestrictSearchResultsTo, indicating what to include in the search results.
exact (bool) – if True, try to match the name exactly

Returns:

list of SearchResult

Return type:

list of boardgamegeek.search.SearchResult

Raises:

boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)

Raises:

BGGApiRetryError if request should be retried after delay

Raises:

boardgamegeek.exceptions.BGGApiError if the API response was invalid or couldn’t be parsed

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

user(name: str, buddies: bool = True, guilds: bool = True, hot: bool = True, top: bool = True, domain: str = 'boardgame') → User¶

Retrieves details about a user

Parameters:

name (str) – user’s login name
buddies (bool) – if True, get the user’s buddies
guilds (bool) – if True, get the user’s guilds
hot (bool) – if True, get the user’s “hot” list
top (bool) – if True, get the user’s “top” list
domain (str) – restrict items on the “hot” and “top” lists to domain. One of the constants in boardgamegeek.BGGSelectDomain

Returns:

User object

Return type:

boardgamegeek.user.User

Returns:

None if the user couldn’t be found

Raises:

ValueError in case of invalid parameters

Raises:

boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)

Raises:

boardgamegeek.exceptions.BGGItemNotFoundError if the user wasn’t found

Raises:

boardgamegeek.exceptions.BGGApiRetryError if request should be retried after delay

Raises:

boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

`boardgamegeek.collection` - Collection information¶

class boardgamegeek.objects.collection.Collection(data: dict[str, Any])[source]¶

A dictionary-like object represeting a Collection

Parameters:: data (dict) – a dictionary containing the collection data
Raises:: boardgamegeek.exceptions.BoardGameGeekError in case of invalid data

add_game(game: dict[str, Any]) → None[source]¶

Add a game to the Collection

Parameters:: game (dict) – game data
Raises:: boardgamegeek.exceptions.BoardGameGeekError in case of invalid data

property items: list[CollectionBoardGame]¶

Returns the items in the collection

Returns:: the items in the collection
Return type:: list of boardgamegeek.games.CollectionBoardGame

property owner: str | None¶

Return the collection’s owner

Returns:: the collection’s owner
Return type:: str

`boardgamegeek.exceptions` - Exceptions¶

`boardgamegeek.games` - Games information¶

class boardgamegeek.objects.games.CollectionBoardGame(data: dict[str, Any])[source]¶

A boardgame retrieved from the collection information, which has less information than the one retrieved via the /thing api and which also contains some user-specific information.

property comment: str¶

Returns:: comment left by user
Return type:: str

property for_trade: bool¶

Returns:: game for trading
Return type:: bool

property last_modified: str | None¶

Returns:: last modified date
Return type:: str

property owned: bool¶

Returns:: game owned
Return type:: bool

property preordered: bool¶

Returns:: game preordered
Return type:: bool

property prev_owned: bool¶

Returns:: game previously owned
Return type:: bool

property rating: float | None¶

Returns:: user’s rating of the game
Return type:: float
Returns:: None if n/a

property want: bool¶

Returns:: game wanted
Return type:: bool

property want_to_buy: bool¶

Returns:: want to buy
Return type:: bool

property want_to_play: bool¶

Returns:: want to play
Return type:: bool

property wishlist: bool¶

Returns:: game on wishlist
Return type:: bool

class boardgamegeek.objects.games.BoardGame(data: dict[str, Any])[source]¶

Object containing information about a board game

property accessory: bool¶

Returns:: True if this item is an accessory
Return type:: bool

add_expanded_game(data: dict[str, Any]) → None[source]¶

Add a game expanded by this one

Parameters:: data (dict) – expanded game’s data
Raises:: boardgamegeek.exceptions.BoardGameGeekError if data is invalid

add_expansion(data: dict[str, Any]) → None[source]¶

Add an expansion of this game

Parameters:: data (dict) – expansion data
Raises:: boardgamegeek.exceptions.BoardGameGeekError if data is invalid

property alternative_names: list[str]¶

Returns:: alternative names
Return type:: list of str

property artists: list[str]¶

Returns:: artists
Return type:: list of str

property categories: list[str]¶

Returns:: categories
Return type:: list of str

property description: str¶

Returns:: description
Return type:: str

property designers: list[str]¶

Returns:: designers
Return type:: list of str

property expands: list[Thing]¶

Returns:: games this item expands
Return type:: list of boardgamegeek.things.Thing

property expansion: bool¶

Returns:: True if this item is an expansion
Return type:: bool

property expansions: list[Thing]¶

Returns:: expansions
Return type:: list of boardgamegeek.things.Thing

property families: list[str]¶

Returns:: families
Return type:: list of str

property implementations: list[str]¶

Returns:: implementations
Return type:: list of str

property marketplace: list[MarketplaceListing]¶

Returns:: marketplace listings of this game
Return type:: list of boardgamegeek.game.MarketplaceListing

property mechanics: list[str]¶

Returns:: mechanics
Return type:: list of str

property min_age: int | None¶

Returns:: minimum recommended age
Return type:: integer
Returns:: None if n/a

property player_suggestions: list[PlayerSuggestion]¶: :return player suggestion list with votes :rtype: list of dicts

property publishers: list[str]¶

Returns:: publishers
Return type:: list of str

property rating_average_weight: float | None¶

Returns:: average weight
Return type:: float
Returns:: None if n/a

property rating_num_weights: int | None¶

Returns:
Return type:: integer
Returns:: None if n/a

property users_commented: int | None¶

Returns:: number of user comments
Return type:: integer
Returns:: None if n/a

property users_owned: int | None¶

Returns:: number of users owning this game
Return type:: integer
Returns:: None if n/a

property users_trading: int | None¶

Returns:: number of users trading this game
Return type:: integer
Returns:: None if n/a

property users_wanting: int | None¶

Returns:: number of users wanting this game
Return type:: integer
Returns:: None if n/a

property users_wishing: int | None¶

Returns:: number of users wishing for this game
Return type:: integer
Returns:: None if n/a

property versions: list[BoardGameVersion]¶

Returns:: versions of this game
Return type:: list of boardgamegeek.game.BoardGameVersion

property videos: list[BoardGameVideo]¶

Returns:: videos of this game
Return type:: list of boardgamegeek.game.BoardGameVideo

class boardgamegeek.objects.games.BoardGameRank(data: dict[str, Any])[source]¶

class boardgamegeek.objects.games.PlayerSuggestion(data: dict[str, Any])[source]¶

Player Suggestion

property numeric_player_count: int¶: Convert player count to an int If player count contains a + symbol then add one to the player count

class boardgamegeek.objects.games.BoardGameStats(data: dict[str, Any])[source]¶

Statistics about a board game

property rating_average: float | None¶

Returns:: average rating
Return type:: float
Returns:: None if n/a

property rating_average_weight: float | None¶

Returns:: average weight
Return type:: float
Returns:: None if n/a

property rating_bayes_average: float | None¶

Returns:: bayes average rating
Return type:: float
Returns:: None if n/a

property rating_median: float | None¶

Returns:
Return type:: float
Returns:: None if n/a

property rating_num_weights: int | None¶

Returns:
Return type:: integer
Returns:: None if n/a

property rating_stddev: float | None¶

Returns:: standard deviation
Return type:: float
Returns:: None if n/a

property users_commented: int | None¶

Returns:: number of user comments
Return type:: integer
Returns:: None if n/a

property users_owned: int | None¶

Returns:: number of users owning this game
Return type:: integer
Returns:: None if n/a

property users_rated: int | None¶

Returns:: how many users rated the game
Return type:: integer
Returns:: None if n/a

property users_trading: int | None¶

Returns:: number of users trading this game
Return type:: integer
Returns:: None if n/a

property users_wanting: int | None¶

Returns:: number of users wanting this game
Return type:: integer
Returns:: None if n/a

property users_wishing: int | None¶

Returns:: number of users wishing for this game
Return type:: integer
Returns:: None if n/a

class boardgamegeek.objects.games.BoardGameComment(data: dict[str, Any])[source]¶

class boardgamegeek.objects.games.BoardGameVideo(data: dict[str, Any])[source]¶

Object containing information about a board game video

property category: str | None¶

Returns:: the category of this video
Returns:: None if n/a
Return type:: string

property language: str | None¶

Returns:: the language of this video
Returns:: None if n/a
Return type:: string

property link: str | None¶

Returns:: the link to this video
Returns:: None if n/a
Return type:: string

property post_date: datetime | None¶

Returns:: date when this video was uploaded
Return type:: datetime.datetime
Returns:: None if n/a

property uploader: str | None¶

Returns:: the name of the user which uploaded this video
Returns:: None if n/a
Return type:: string

property uploader_id: int | None¶

Returns:: id of the uploader
Return type:: integer
Returns:: None if n/a

class boardgamegeek.objects.games.BoardGameVersion(data: dict[str, Any])[source]¶

Object containing information about a board game version

property artist: str | None¶

Returns:: artist of this version
Return type:: string
Returns:: None if n/a

property depth: float | None¶

Returns:: depth of the box
Return type:: double
Returns:: 0.0 if n/a

property language: str | None¶

Returns:: language of this version
Return type:: string
Returns:: None if n/a

property length: float | None¶

Returns:: length of the box
Return type:: double
Returns:: 0.0 if n/a

property name: str¶

Returns:: name of this version
Return type:: string
Returns:: None if n/a

property product_code: str | None¶

Returns:: product code of this version
Return type:: string
Returns:: None if n/a

property publisher: str | None¶

Returns:: publisher of this version
Return type:: string
Returns:: None if n/a

property weight: float | None¶

Returns:: weight of the box
Return type:: double
Returns:: 0.0 if n/a

property width: float | None¶

Returns:: width of the box
Return type:: float
Returns:: 0.0 if n/a

property year: int | None¶

Returns:: publishing year
Return type:: integer
Returns:: None if n/a

`boardgamegeek.guild` - Guild information¶

class boardgamegeek.objects.guild.Guild(data: dict[str, Any])[source]¶

Class containing guild information

property addr1: str | None¶

Returns:: first field of the address
Return type:: str
Returns:: None if n/a

property addr2: str | None¶

Returns:: second field of the address
Return type:: str
Returns:: None if n/a

property address: str | None¶

Returns:: address (both fields concatenated)
Return type:: str
Returns:: None if n/a

property category: str | None¶

Returns:: category
Return type:: str
Returns:: None if n/a

property city: str | None¶

Returns:: city
Return type:: str
Returns:: None if n/a

property country: str | None¶

Returns:: country
Return type:: str
Returns:: None if n/a

property description: str | None¶

Returns:: description
Return type:: str
Returns:: None if n/a

property manager: str | None¶

Returns:: manager
Return type:: str
Returns:: None if n/a

property members: set[str]¶

Returns:: members of the guild
Return type:: set of str

property members_count: int¶

Returns:: number of members, as reported by the server
Return type:: int

property postalcode: int | None¶

Returns:: postal code
Return type:: integer
Returns:: None if n/a

property state: str | None¶

Returns:: state or provine
Return type:: str
Returns:: None if n/a

property website: str | None¶

Returns:: website address
Return type:: str
Returns:: None if n/a

`boardgamegeek.hotitems` - BoardGameGeek “Hot Items”¶

class boardgamegeek.objects.hotitems.HotItem(data: dict[str, Any])[source]¶

A hot item from a list. Can refer to either an item (boardgame, videogame, etc.), a person (rpgperson, boardgameperson) or even a company (boardgamecompany, videogamecompany), depending on the type of hot list retrieved.

property rank: int¶

Returns:: Ranking of this hot item
Return type:: integer

property thumbnail: str | None¶

Returns:: thumbnail URL
Return type:: str
Returns:: None if n/a

property year: int | None¶

Returns:: publishing year
Return type:: integer
Returns:: None if n/a

class boardgamegeek.objects.hotitems.HotItems(data: dict[str, Any])[source]¶

A collection of boardgamegeek.hotitems.HotItem

add_hot_item(data: dict[str, Any]) → None[source]¶

Add a new hot item to the container

Parameters:: data – dictionary containing the data

property items: list[HotItem]¶

Returns:: list of hotitems
Return type:: list of boardgamegeek.hotitems.HotItem

`boardgamegeek.plays` - BoardGameGeek “Plays”¶

class boardgamegeek.objects.plays.GamePlays(data: dict[str, Any])[source]¶

property game_id: int | None¶

Returns:: id of the game this plays list belongs to
Return type:: integer
Returns:: None if this list is that of an user

class boardgamegeek.objects.plays.UserPlays(data: dict[str, Any])[source]¶

property user: str | None¶

Returns:: name of the playlist owner
Return type:: str
Returns:: None if this is the playlist of a game (not an user’s)

property user_id: int | None¶

Returns:: id of the playlist owner
Return type:: integer
Returns:: None if this is the playlist of a game (not an user’s)

class boardgamegeek.objects.plays.PlaySession(data: dict[str, Any])[source]¶

Container for a play session information.

Parameters:: data (dict) – a dictionary containing the collection data
Raises:: boardgamegeek.exceptions.BoardGameGeekError in case of invalid data

property comment: str | None¶

Returns:: comment on the play session
Return type:: str
Returns:: None if n/a

property date: datetime | None¶

Returns:: the date of the play session
Return type:: datetime.datetime
Returns:: None if n/a

property duration: int | None¶

Returns:: duration of the play session
Return type:: integer
Returns:: None if n/a

property game_id: int | None¶

Returns:: played game id
Return type:: integer
Returns:: None if n/a

property game_name: str | None¶

Returns:: played game name
Return type:: str
Returns:: None if n/a

property id: int¶

Returns:: id
Return type:: integer
Returns:: None if n/a

property incomplete: bool¶

Returns:: incomplete session
Return type:: bool

property location: str | None¶

Returns:

property nowinstats: int | None¶

Return type:: integer
Returns:

property players: list[PlaysessionPlayer]¶

Returns:: list of players in this play session
Return type:: list of boardgamegeek.plays.PlaysessionPlayer

property quantity: int | None¶

Returns:: number of recorded plays
Return type:: integer
Returns:: None if n/a

property user_id: int | None¶

Returns:: id of the user owning this play session
Return type:: integer
Returns:: None if n/a

class boardgamegeek.objects.plays.PlaysessionPlayer(data: dict[str, Any])[source]¶

Class representing a player in a play session

Raises:: boardgamegeek.exceptions.BoardGameGeekError in case of invalid data

property color: str | None¶

Returns:: color
Return type:: str
Returns:: None if n/a

property name: str | None¶

Returns:: name
Return type:: str
Returns:: None if n/a

property new: str | None¶

Returns:: 1 or 0 (new or not)
Return type:: str
Returns:: None if n/a

property rating: str | None¶

Returns:: 1 or 0 (rated or not)
Return type:: str
Returns:: None if n/a

property score: str | None¶

Returns:: score
Return type:: str
Returns:: None if n/a

property startposition: str | None¶

Returns:: strting position
Return type:: str
Returns:: None if n/a

property user_id: int | None¶

Returns:: user id
Return type:: integer
Returns:: None if n/a

property username: str | None¶

Returns:: username
Return type:: str
Returns:: None if n/a

property win: str | None¶

Returns:: 1 or 0 (win or not)
Return type:: str
Returns:: None if n/a

`boardgamegeek.search` - Search results¶

class boardgamegeek.objects.search.SearchResult(data: dict[str, Any])[source]¶: Result of a search

`boardgamegeek.things` - Generic objects¶

class boardgamegeek.objects.things.Thing(data: dict[str, Any])[source]¶: A thing, an object with a name and an id. Base class for various objects in the library.

`boardgamegeek.user` - BoardGameGeek “Users”¶

class boardgamegeek.objects.user.User(data: dict[str, Any])[source]¶

Information about a user.

add_buddy(data: dict[str, Any]) → None[source]¶

Add a buddy to this user

Parameters:: data (dict) – buddy’s data

property avatar: str | None¶

Returns:: avatar’s URL
Return type:: str
Returns:: None if n/a

property buddies: list[Thing]¶

Returns:: user’s buddies
Return type:: list of boardgamegeek.things.Thing

property firstname: str | None¶

Returns:: user’s first name
Return type:: str
Returns:: None if n/a

property guilds: list[Thing]¶

Returns:: user’s guilds
Return type:: list of boardgamegeek.things.Thing

property hot10: list[Thing]¶

Returns:: user’s hot10
Return type:: list of boardgamegeek.things.Thing

property lastname: str | None¶

Returns:: user’s last name
Return type:: str
Returns:: None if n/a

property top10: list[Thing]¶

Returns:: user’s top10
Return type:: list of boardgamegeek.things.Thing

property total_buddies: int¶

Returns:: number of buddies
Return type:: integer

property total_guilds: int¶

Returns:: number of guilds
Return type:: integer

`boardgamegeek.utils` - Generic helper functions¶

class boardgamegeek.utils.DictObject(data: dict[str, Any])[source]¶

Just a fancy wrapper over a dictionary

data() → dict[str, Any][source]¶: Access to the internal data dictionary, for easy dumping :return: the internal data dictionary

class boardgamegeek.utils.RateLimitingAdapter(rpm: int = 30, **kwargs: Any)[source]¶

Adapter for the Requests library which makes sure there’s a delay between consecutive requests to the BGG site so that we don’t get throttled

send(request: PreparedRequest, *args: Any, **kwargs: Any) → Response[source]¶

Sends PreparedRequest object. Returns Response object.

Parameters:

request – The PreparedRequest being sent.
stream – (optional) Whether to stream the request content.
timeout (float or tuple or urllib3 Timeout object) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use
cert – (optional) Any user-provided SSL certificate to be trusted.
proxies – (optional) The proxies dictionary to apply to the request.

Return type:

requests.Response

boardgamegeek.utils.fix_url(url: str | None) → str | None[source]¶

The BGG API started returning URLs like //cf.geekdo-images.com/images/pic55406.jpg for thumbnails and images. This function fixes them.

Parameters:: url – the url to fix
Returns:: the fixed url

boardgamegeek.utils.get_link_by_type(xml_elem: Element, link_type: str, default: Any = None) → Any[source]¶

Search for a ‘link’ sub-element having a ‘type’ attribute set to the specified link_type and return its ‘value’ attribute.

Parameters:

xml_elem – search the children nodes of this element
link_type – Value of the type attribute to search for
default – default value if the subelement or attribute is not found

Returns:

value of the attribute or default value if not found

boardgamegeek.utils.request_and_parse_xml(requests_session: Session, url: str, params: dict[str, Any] | None = None, timeout: float = 15.0, retries: int = 3, retry_delay: float = 5.0, headers: dict[str, str] | None = None) → Element[source]¶

Downloads an XML from the specified url, parses it and returns the xml ElementTree.

Parameters:

requests_session – A Session of the requests library, used to fetch the url
url – the address where to get the XML from
params – dictionary containing the parameters which should be sent with the request
timeout – number of seconds after which the request times out
retries – number of retries to perform in case of timeout
retry_delay – the amount of seconds to sleep when retrying an API call that returned 202
headers – dictionary containing the headers which should be sent with the request

Returns:

xml.etree.ElementTree() corresponding to the XML

Raises:

BGGApiRetryError if this request should be retried after a short delay

Raises:

BGGApiError if the response was invalid or couldn’t be parsed

Raises:

BGGApiTimeoutError if there was a timeout

boardgamegeek.utils.xml_subelement_attr(xml_elem: Element | None, subelement: str | None, convert: Callable[[str], Any] | None = None, attribute: str = 'value', default: Any = None, quiet: bool = False) → Any[source]¶

Search for a sub-element and return the value of its attribute.

For the following XML document:

<xml_elem>
    <subelement value="THIS" />
</xml_elem>

a call to xml_subelement_attr(xml_elem, "subelement") would return "THIS"

Parameters:

xml_elem – search the children nodes of this element
subelement – Name of the sub-element to search for
convert – if not None, a callable to perform the conversion of this attribute to a certain object type
attribute – name of the attribute to get
default – default value if the subelement or attribute is not found
quiet – if True, don’t raise exception from conversions, return default instead

Returns:

value of the attribute or None in error cases

boardgamegeek.utils.xml_subelement_attr_list(xml_elem: Element | None, subelement: str | None, convert: Callable[[str], Any] | None = None, attribute: str = 'value', default: Any = None, quiet: bool = False) → list[Any] | None[source]¶

Search for sub-elements and return a list of the specified attribute.

<xml_elem>
    <subelement value="THIS" />
    <subelement value="THIS2" />
    ...
</xml_elem>

For the above document, [“THIS”, “THIS2”] will be returned

Parameters:

xml_elem – search the children nodes of this element
subelement – name of the sub-element to search for
convert – if not None, a callable used to perform the conversion of this attribute to a certain object type
attribute – name of the attribute to get
default – default value to use if an attribute is missing
quiet – if True, don’t raise exceptions from conversions, instead use the default value

Returns:

list containing the values of the attributes or None in error cases

boardgamegeek.utils.xml_subelement_text(xml_elem: Element | None, subelement: str | None, convert: Callable[[str], Any] | None = None, default: Any = None, quiet: bool = False) → Any[source]¶

Return the text of the specified subelement

For the document below:

<xml_elem>
    <subelement>text</subelement>
</xml_elem>

"text" will be returned

Parameters:

xml_elem – search the children nodes of this element
subelement – name of the subelement whose text will be retrieved
convert – if not None, a callable used to perform the conversion of the text to a certain object type
default – default value if subelement is not found
quiet – if True, don’t raise exceptions from conversions, instead use the default value

Returns:

The text associated with the sub-element or None in case of error

Modules¶

`boardgamegeek.api` - Core functions¶

`boardgamegeek.collection` - Collection information¶

`boardgamegeek.exceptions` - Exceptions¶

`boardgamegeek.games` - Games information¶

`boardgamegeek.guild` - Guild information¶

`boardgamegeek.hotitems` - BoardGameGeek “Hot Items”¶

`boardgamegeek.plays` - BoardGameGeek “Plays”¶

`boardgamegeek.search` - Search results¶

`boardgamegeek.things` - Generic objects¶

`boardgamegeek.user` - BoardGameGeek “Users”¶

`boardgamegeek.utils` - Generic helper functions¶

bgg-api

Navigation

Related Topics

Modules¶

boardgamegeek.api - Core functions¶

boardgamegeek.collection - Collection information¶

boardgamegeek.exceptions - Exceptions¶

boardgamegeek.games - Games information¶

boardgamegeek.guild - Guild information¶

boardgamegeek.hotitems - BoardGameGeek “Hot Items”¶

boardgamegeek.plays - BoardGameGeek “Plays”¶

boardgamegeek.search - Search results¶

boardgamegeek.things - Generic objects¶

boardgamegeek.user - BoardGameGeek “Users”¶

boardgamegeek.utils - Generic helper functions¶

`boardgamegeek.api` - Core functions¶

`boardgamegeek.collection` - Collection information¶

`boardgamegeek.exceptions` - Exceptions¶

`boardgamegeek.games` - Games information¶

`boardgamegeek.guild` - Guild information¶

`boardgamegeek.hotitems` - BoardGameGeek “Hot Items”¶

`boardgamegeek.plays` - BoardGameGeek “Plays”¶

`boardgamegeek.search` - Search results¶

`boardgamegeek.things` - Generic objects¶

`boardgamegeek.user` - BoardGameGeek “Users”¶

`boardgamegeek.utils` - Generic helper functions¶