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(cache=<boardgamegeek.cache.CacheBackendMemory object>, timeout=15, retries=3, retry_delay=5, disable_ssl=False, requests_per_minute=30)[source]¶

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

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

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

collection(user_name, subtype='boardgame', exclude_subtype=None, ids=None, versions=None, version=None, own=None, rated=None, played=None, commented=None, trade=None, want=None, wishlist=None, wishlist_prio=None, preordered=None, want_to_play=None, want_to_buy=None, prev_owned=None, has_parts=None, want_parts=None, min_rating=None, rating=None, min_bgg_rating=None, bgg_rating=None, min_plays=None, max_plays=None, collection_id=None, modified_since=None)¶

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 (double) – return items rated by the user with a minimum of min_rating
rating (double) – return items rated by the user with a maximum of rating

:param double min_bgg_rating : return items rated on BGG with a minimum of min_bgg_rating :param double bgg_rating: return items rated on BGG with a maximum of bgg_rating :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=None, game_id=None, choose='first', versions=False, videos=False, historical=False, marketplace=False, comments=False, rating_comments=False, exact=True)[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, versions=False, videos=False, historical=False, marketplace=False)[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)[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, choose='first', exact=True)[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, members=True)¶

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

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=None, game_id=None, min_date=None, max_date=None, subtype='boardgame')¶

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

Parameters:

name (str) – user name 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, search_type=None, exact=False)¶

Search for a game

Parameters:

query (str) – the string to search for
search_type (list) – list of boardgamegeek.api.BGGRestrictItemTypeTo, 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, buddies=True, guilds=True, hot=True, top=True, domain='boardgame')¶

Retrieves details about an 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)[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)[source]¶

Add a game to the Collection

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

property items¶

Returns the items in the collection

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

property owner¶

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

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

property for_trade¶

Returns:: game for trading
Return type:: bool

property last_modified¶

Returns:: last modified date
Return type:: str

property owned¶

Returns:: game owned
Return type:: bool

property preordered¶

Returns:: game preordered
Return type:: bool

property prev_owned¶

Returns:: game previously owned
Return type:: bool

property rating¶

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

property want¶

Returns:: game wanted
Return type:: bool

property want_to_buy¶

Returns:: want to buy
Return type:: bool

property want_to_play¶

Returns:: want to play
Return type:: bool

property wishlist¶

Returns:: game on wishlist
Return type:: bool

class boardgamegeek.objects.games.BoardGame(data)[source]¶

Object containing information about a board game

property accessory¶

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

add_expanded_game(data)[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)[source]¶

Add an expansion of this game

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

property alternative_names¶

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

property artists¶

Returns:: artists
Return type:: list of str

property categories¶

Returns:: categories
Return type:: list of str

property description¶

Returns:: description
Return type:: str

property designers¶

Returns:: designers
Return type:: list of str

property expands¶

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

property expansion¶

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

property expansions¶

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

property families¶

Returns:: families
Return type:: list of str

property implementations¶

Returns:: implementations
Return type:: list of str

property marketplace¶

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

property mechanics¶

Returns:: mechanics
Return type:: list of str

property min_age¶

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

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

property publishers¶

Returns:: publishers
Return type:: list of str

property rating_average_weight¶

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

property rating_num_weights¶

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

property users_commented¶

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

property users_owned¶

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

property users_trading¶

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

property users_wanting¶

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

property users_wishing¶

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

property versions¶

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

property videos¶

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

class boardgamegeek.objects.games.BoardGameRank(data)[source]¶

class boardgamegeek.objects.games.PlayerSuggestion(data)[source]¶

Player Suggestion

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

class boardgamegeek.objects.games.BoardGameStats(data)[source]¶

Statistics about a board game

property rating_average¶

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

property rating_average_weight¶

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

property rating_bayes_average¶

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

property rating_median¶

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

property rating_num_weights¶

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

property rating_stddev¶

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

property users_commented¶

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

property users_owned¶

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

property users_rated¶

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

property users_trading¶

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

property users_wanting¶

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

property users_wishing¶

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

class boardgamegeek.objects.games.BoardGameComment(data)[source]¶

class boardgamegeek.objects.games.BoardGameVideo(data)[source]¶

Object containing information about a board game video

property category¶

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

property language¶

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

property link¶

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

property post_date¶

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

property uploader¶

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

property uploader_id¶

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

class boardgamegeek.objects.games.BoardGameVersion(data)[source]¶

Object containing information about a board game version

property artist¶

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

property depth¶

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

property language¶

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

property length¶

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

property name¶

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

property product_code¶

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

property publisher¶

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

property weight¶

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

property width¶

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

property year¶

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

`boardgamegeek.guild` - Guild information¶

class boardgamegeek.objects.guild.Guild(data)[source]¶

Class containing guild information

property addr1¶

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

property addr2¶

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

property address¶

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

property category¶

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

property city¶

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

property country¶

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

property description¶

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

property manager¶

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

property members¶

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

property members_count¶

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

property postalcode¶

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

property state¶

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

property website¶

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

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

class boardgamegeek.objects.hotitems.HotItem(data)[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¶

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

property thumbnail¶

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

property year¶

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

class boardgamegeek.objects.hotitems.HotItems(data)[source]¶

A collection of boardgamegeek.hotitems.HotItem

add_hot_item(data)[source]¶

Add a new hot item to the container

Parameters:: data – dictionary containing the data

property items¶

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

`boardgamegeek.plays` - BoardGameGeek “Plays”¶

class boardgamegeek.objects.plays.GamePlays(data)[source]¶

property game_id¶

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)[source]¶

property user¶

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¶

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

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

property date¶

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

property duration¶

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

property game_id¶

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

property game_name¶

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

property id¶

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

property incomplete¶

Returns:: incomplete session
Return type:: bool

property location¶

Returns:

property nowinstats¶

Returns:

property quantity¶

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

property user_id¶

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

class boardgamegeek.objects.plays.PlaysessionPlayer(data)[source]¶

Class representing a player in a play session

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

property color¶

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

property name¶

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

property new¶

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

property rating¶

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

property score¶

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

property startposition¶

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

property user_id¶

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

property username¶

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

property win¶

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

`boardgamegeek.search` - Search results¶

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

`boardgamegeek.things` - Generic objects¶

class boardgamegeek.objects.things.Thing(data)[source]¶

A thing, an object with a name and an id. Base class for various objects in the library.

property id¶

Returns:: id
Return type:: integer

property name¶

Returns:: name
Return type:: str

`boardgamegeek.user` - BoardGameGeek “Users”¶

class boardgamegeek.objects.user.User(data)[source]¶

Information about an user.

add_buddy(data)[source]¶

Add a buddy to this user

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

property avatar¶

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

property buddies¶

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

property firstname¶

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

property guilds¶

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

property hot10¶

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

property lastname¶

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

property top10¶

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

property total_buddies¶

Returns:: number of buddies
Return type:: integer

property total_guilds¶

Returns:: number of guilds
Return type:: integer

`boardgamegeek.utils` - Generic helper functions¶

class boardgamegeek.utils.DictObject(data)[source]¶

Just a fancy wrapper over a dictionary

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

class boardgamegeek.utils.RateLimitingAdapter(rpm=30, **kw)[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, **kw)[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)[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.request_and_parse_xml(requests_session, url, params=None, timeout=15, retries=3, retry_delay=5)[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

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, subelement, convert=None, attribute='value', default=None, quiet=False)[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_by_attr(xml_elem, subelement, filter_attr, filter_value, convert=None, attribute='value', default=None, quiet=False)[source]¶

Search for a sub-element having an attribute filter_attr set to filter_value

For the following XML document:

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

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

Parameters:

xml_elem – search the children nodes of this element
subelement – Name of the sub-element to search for
filter_attr – Name of the attribute the sub-element must contain
filter_value – Value of the attribute
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, subelement, convert=None, attribute='value', default=None, quiet=False)[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, subelement, convert=None, default=None, quiet=False)[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¶