boardgamegeek documentation - read the docs · 2019. 4. 2. · boardgamegeek documentation, release...

41
boardgamegeek Documentation Release 0.11.1 Cosmin Luta July 21, 2015

Upload: others

Post on 20-Jan-2021

6 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek DocumentationRelease 0.11.1

Cosmin Luta

July 21, 2015

Page 2: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at
Page 3: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

Contents

1 Introduction 3

2 Table of Contents 52.1 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Features 21

4 Quick Install 23

5 Usage 25

6 To Do 27

7 Contributions 29

8 Indices and tables 31

Python Module Index 33

i

Page 4: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

ii

Page 5: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

Warning: The documentation is a work in progress. You can check out the unit tests for how to use the library.

Contents 1

Page 6: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

2 Contents

Page 7: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 1

Introduction

boardgamegeek is a Python library which makes it easy to access data from BoardGameGeek using their officialXML API.

It’s an almost completely rewritten fork of libBGG.

Warning: The module’s API is still considered unstable at this point and it might change in the future, especiallyif wanting to add support for the other sites.

3

Page 8: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

4 Chapter 1. Introduction

Page 9: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 2

Table of Contents

2.1 Changelog

2.1.1 0.11.1

Changes

• Documentation fixups

2.1.2 0.11.0

Changes

• URLs for images and thumbnails are converted to proper URLs (the API returns them as “//cf.geekdo-images.com/images/...”)

Features

• The boardgamegeek.games.BoardGame has a new integer property (None if missing), boardgame_rank

• The boardgamegeek tool: added -i, which allows querying by game id

• The boardgamegeek tool: added –most-recent (default) and –most-popular which allow the -g option to giveinformation on a different game when the “search-by-name” returns multiple results.

2.1.3 0.10.1

Changes

• Reduced default requests_per_minute to 30, for safety

2.1.4 0.10.0

Features

• Added a mechanism which makes sure the library doesn’t send requests too fast to BGG, triggering their protec-tion (HTTP error 503). It does this by serializing all the requests and making sure there’s enough waiting timebetween them so that the configured requests_per_minute is respected.

Fixes

5

Page 10: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

• Fixed the retry mechanism, allowing retries=0 (meaning no retries at all). Before, the code would fail if the userspecified retires=0

2.1.5 0.9.0

Changes

• Since the BoardGameGeek API and site support HTTPS along with HTTP (and will be fully transitioned toHTTPS in the future), this library now uses HTTPS by default. To disable this behaviour, pass disable_ssl=Truewhen creating a boardgamegeek.api.BoardGameGeek

2.1.6 0.8.1

Fixes

• Infinite recursion when unpickling objects

2.1.7 0.8.0

Features

• Fetching plays has support for min_date, max_date (thanks tomusher!)

2.1.8 0.7.1

Fixes

• Not expecting the score of a player to be a number anymore (using the string as returned by the BGG API)

2.1.9 0.7.0

Changes

• The XML API2 seems to throttle requests by returning HTTP 503 ; added a delay and retry in the code to try todeal with this

Features

• When retrieving the plays, players are also returned, along with their data.

2.1.10 0.6.0

Changes

• Improved code in an attempt to prevent exceptions when trying to deal with invalid data coming from the remoteXML data

Fixes

• Fixed issue #12 (an edge case which lead to comparing None to int)

6 Chapter 2. Table of Contents

Page 11: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

2.1.11 0.5.0

Features

• Added a new function boardgamegeek.api.BoardGameGeek.games() which takes a name as argu-ment and returns a list of boardgamegeek.games.BoardGame with all the games with that name.

2.1.12 0.4.3

Changes

• When calling boardgamegeek.api.BoardGameGeek.game() with a name, return the most recentlypublished result instead of the first one, in case of multiple results.

2.1.13 0.4.2

Changes

• Increased default number of retries and timeout

2.1.14 0.4.0

Changes

• The calls to the BGG API will be automatically retried two times, with a timeout of 10 seconds. This behaviourcan be controlled via the retries=, timeout= and retry_delay= parameters.

Features

• Added patch from philsstein to automatically increase timeout and retry request on timeout

2.1.15 0.3.0

Changes

• Added a property to boardgamegeek.games.BoardGame, expansion which indicates if this item is anexpansion or not

• Changed the expansions property of boardgamegeek.games.BoardGame, now it returns a list ofboardgamegeek.things.Thing for each expansion the game has

• Added a property to boardgamegeek.games.BoardGame, extends which returns a list ofboardgamegeek.things.Thing for each item this game is an extension to

2.1.16 0.2.0 (unreleased)

Changes

• Changed the object hierarchy, replaced BasicUser, BasicGuild, BasicGame with aboardgamegeek.things.Thing which has a name and an id

Features

• Added support for retrieving the hot lists

2.1. Changelog 7

Page 12: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

2.1.17 0.1.0

Features

• Allowing the user to specify timeouts for the requests library

2.1.18 0.0.14

Changes

• The .last_login property of an boardgamegeek.user.User object now returns adatetime.datetime

Features

• Added support for an user’s top and hot lists

Bugfixes

• Exceptions raised from get_parsed_xml_response() where not properly propagated to the calling code

2.1.19 0.0.13

Features

• Improved code for fetching an user’s buddies and guilds

• Improved code for fetching guild members

• Added support for listing Plays by user and by game

2.1.20 0.0.12

Features

• Added some basic argument validation to prevent pointless calls to BGG’s API

• When some object (game, user name, etc.) is not found, the functions return None instead of raising an exception

2.1.21 0.0.11

Features

• Collections and Guilds are now iterable

Bugfixes

• Fixed __str__ for Collection

2.1.22 0.0.10

Features

• Updated documentation

• Improved Python 3.x compatibility (using unicode_literals)

• Added Travis integration

8 Chapter 2. Table of Contents

Page 13: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

Bugfixes

• Fixed float division for Python 3.x

2.1.23 0.0.9

Features

• Added support for retrieving an user’s buddy and guild lists

• Started implementing some basic unit tests

Bugfixes

• Fixed handling of non-existing user names

• Properly returning the maximum number of players for a game

2.2 Modules

2.2.1 boardgamegeek.api - Core functions

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

class boardgamegeek.api.BoardGameGeek(cache=u’memory:///?ttl=3600’, timeout=15, re-tries=3, retry_delay=5, disable_ssl=False, re-quests_per_minute=30)

Python interface for www.boardgamegeek.com’s XML API.

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

Example usage:

>>> bgg = BoardGameGeek()>>> game = bgg.game("Android: Netrunner")>>> game.id124742>>> bgg_no_cache = BoardGameGeek(cache=None)>>> bgg_sqlite_cache = BoardGameGeek(cache="sqlite:///path/to/cache.db?ttl=3600")

game(name=None, game_id=None)Get information about a game.

WARNING: it can happen that there are multiple games with the same name, and this func-tion might not always pick up the one you’re interested in. As a workaround, call theboardgamegeek.api.BoardGame.search function to get the exact id, then use it here.

Parameters

• name – If not None, get information about a game with this name

• game_id – If not None, get information about a game with this id

Returns boardgamegeek.games.BoardGame

Returns None if the game wasn’t found

2.2. Modules 9

Page 14: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

Raises boardgamegeek.exceptions.BoardGameGeekError in case of invalid nameand id

Raises boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this re-quest should be retried after a short delay

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if the responsecouldn’t be parsed

Raises boardgamegeek.exceptions.BoardGameGeekTimeoutError if there wasa timeout

games(name)Return a list containing all games with the given name

Parameters name – The name of the game to search for

Returns list of boardgamegeek.games.BoardGame

Raises boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this re-quest should be retried after a short delay

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if the responsecouldn’t be parsed

Raises boardgamegeek.exceptions.BoardGameGeekTimeoutError if there wasa timeout

get_game_id(name)Returns the BGG ID of a game, searching by name

Parameters

• name – The name of the game to search for

• game_type – the game type: “rpgitem”, “videogame”, “boardgame”, “boardgameex-pansion”

• first – if true, return the first result, otherwise return the most recent (by year published)

Returns None if game wasn’t found

Returns integer value of the game’s id

class boardgamegeek.api.BoardGameGeekNetworkAPI(api_endpoint, cache, timeout, retries,retry_delay, requests_per_minute)

SEARCH_BOARD_GAME = 4

SEARCH_BOARD_GAME_EXPANSION = 8

SEARCH_RPG_ITEM = 1

SEARCH_VIDEO_GAME = 2

collection(user_name)Returns the user’s game collection

Parameters user_name – user name to retrieve the collection for

Returns boardgamegeek.collection.Collection

Returns None if user not found

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if there was aproblem getting the collection

10 Chapter 2. Table of Contents

Page 15: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

Raises boardgamegeek.exceptions.BoardGameGeekError in case of invalid pa-rameters

Raises boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this re-quest should be retried after a short delay

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if the responsecouldn’t be parsed

Raises boardgamegeek.exceptions.BoardGameGeekTimeoutError if there wasa timeout

guild(guild_id, progress=None)Retrieves details about a guild

Parameters

• guild_id – The ID of the guild

• progress – Optional progress callback for member fetching

Returns boardgamegeek.guild.Guild object containing the details

hot_items(item_type)Return the list of “Hot Items”

Parameters item_type – hot item type (valid values: “boardgame”, “rpg”, “videogame”,“boardgameperson”, “rpgperson”, “boardgamecompany”, “rpgcompany”, “videogamecom-pany”)

Returns boardgamegeek.hotitems.HotItems containing the hot items

Raises boardgamegeek.exceptions.BoardGameGeekError if the parameter is in-valid

Raises boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this re-quest should be retried after a short delay

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if the responsecouldn’t be parsed

Raises boardgamegeek.exceptions.BoardGameGeekTimeoutError if there wasa timeout

plays(name=None, game_id=None, progress=None, min_date=None, max_date=None)Retrieves the user’s play list

Parameters

• name – user name to retrieve the plays for

• game_id – game id to retrieve the plays for

• min_date – return only plays of the specified date or later.

• max_date (datetime.date) – return only plays of the specified date or earlier.

Returns boardgamegeek.plays.Plays object containing all the plays

Raises boardgamegeek.exceptions.BoardGameGeekError on errors

Raises boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this re-quest should be retried after a short delay

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if the responsecouldn’t be parsed

2.2. Modules 11

Page 16: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

Raises boardgamegeek.exceptions.BoardGameGeekTimeoutError if there wasa timeout

search(query, search_type=None, exact=False)Search for a game

Parameters

• query – the string to search for

• search_type – integer indicating what to search for. Oneor more of BoardGameGeekNetworkAPI.SEARCH_RPG_ITEM ,BoardGameGeekNetworkAPI.SEARCH_VIDEO_GAME,BoardGameGeekNetworkAPI.SEARCH_BOARD_GAME orBoardGameGeekNetworkAPI.SEARCH_BOARD_GAME_EXPANSION , OR’dtogether

• exact – if True, try to match the name exactly

Returns list of boardgamegeek.search.SearchResult objects

Raises boardgamegeek.exceptions.BoardGameGeekError in case of invalid query

Raises boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this re-quest should be retried after a short delay

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if the responsecouldn’t be parsed

Raises boardgamegeek.exceptions.BoardGameGeekTimeoutError if there wasa timeout

user(name, progress=None)Retrieves details about an user

Parameters name – user’s login name

Returns boardgamegeek.user.User

Raises boardgamegeek.exceptions.BoardGameGeekError in case of invalid username

Raises boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this re-quest should be retried after a short delay

Raises boardgamegeek.exceptions.BoardGameGeekAPIError if the responsecouldn’t be parsed

Raises boardgamegeek.exceptions.BoardGameGeekTimeoutError if there wasa timeout

class boardgamegeek.collection.Collection(data)

add_game(game)

items

owner

exception boardgamegeek.exceptions.BoardGameGeekAPIError

exception boardgamegeek.exceptions.BoardGameGeekAPINonXMLError

exception boardgamegeek.exceptions.BoardGameGeekAPIRetryError

12 Chapter 2. Table of Contents

Page 17: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

exception boardgamegeek.exceptions.BoardGameGeekError

exception boardgamegeek.exceptions.BoardGameGeekTimeoutError

class boardgamegeek.games.BoardGame(data)An object containing the core information about a game.

expands

Returns list of games this item expands

expansion

Returns True if this item is an expansion to some other item

expansions

Returns list of expansions for this item

class boardgamegeek.games.CollectionBoardGame(data)A boardgame retrieved from the collection information, which has less information than the one retrieved viathe /thing api and which also contains some user-specific information

2.2.2 boardgamegeek.guild - Classes for storing guild information

class boardgamegeek.guild.Guild(data)

addr1

addr2

address

Returns Both address fields concatenated

category

city

country

description

manager

members

postalcode

state

website

2.2.3 boardgamegeek.hotitems - BoardGameGeek “Hot Items”

class boardgamegeek.hotitems.HotItem(data)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 onthe type of hot list retrieved.

rank

Returns Ranking of this hot item

2.2. Modules 13

Page 18: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

thumbnail

Returns url of the thumbnail corresponding to this item

yearYear this item was published

Returns integer representing the year

Returns None if object doesn’t refer to a game

class boardgamegeek.hotitems.HotItems(data)A container for boardgamegeek.hotitems.HotItem

add_hot_item(data)Add a new hot item to the container

Parameters data – dictionary containing the data

items

Returns the list of boardgamegeek.hotitems.HotItem

2.2.4 boardgamegeek.plays - BoardGameGeek “Plays”

class boardgamegeek.plays.PlaySession(data)Container for a play session information.

comment

Returns comment on the play session

date

Returns the date when this play session was recorded

duration

Returns duration of the play session

game_id

Returns id of the game played

game_name

Returns name of the game played

id

Returns the play session id

incomplete

Returns whether the session was incomplete or not

nowinstats

Returns

quantity

Returns

user_id

Returns user ID whom this play session belongs to

14 Chapter 2. Table of Contents

Page 19: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

class boardgamegeek.plays.Plays(data)A list of play sessions, associated either to an user or to a game.

add_play(data)

game_id

Returns id of the game this plays list belongs to

Returns None if this list is that of an user

plays

Returns list of PlaySession

user

Returns account name of the user owning this list of plays

Returns None if this list is that of a game and not an user’s

user_id

Returns id of the user owning this list of plays

Returns None if this list is that of a game and not an user’s

class boardgamegeek.plays.PlaysessionPlayer(data)

name

new

rating

score

startposition

user_id

username

win

class boardgamegeek.search.SearchResult(data)

type

year

2.2.5 boardgamegeek.things - Generic objects

class boardgamegeek.things.Thing(data)A thing, an object with a name and an id. Base class for various objects in the library.

id

name

2.2. Modules 15

Page 20: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

2.2.6 boardgamegeek.user - BoardGameGeek “Users”

class boardgamegeek.user.User(data)Information about an user on BGG.

add_buddy(data)

add_guild(data)

add_hot_item(data)

add_top_item(data)

avatar

Returns link to user’s avatar image

buddies

Returns list of Thing with all the buddies (name and id) this user has

country

firstname

Returns user’s first name

guilds

Returns list of Thing with all the guilds (name and id) this user is a member of

homepage

hot10

last_login

lastname

Returns user’s last name

psn_account

state

steam_account

top10

total_buddies

Returns number of buddies this user has

total_guilds

Returns number of guilds this user is a member of

trade_rating

wii_account

xbox_account

16 Chapter 2. Table of Contents

Page 21: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

2.2.7 boardgamegeek.utils - Generic helper functions

class boardgamegeek.utils.DictObject(data)Just a fancy wrapper over a dictionary

data()Access to the internal data dictionary, for easy dumping :return: the internal data dictionary

class boardgamegeek.utils.RateLimitingAdapter(rpm=30, **kw)Adapter for the Requests library which makes sure there’s a delay between consecutive requests to the BGG siteso that we don’t get throttled

send(request, **kw)

boardgamegeek.utils.fix_url(url)The BGG API started returning URLs like //cf.geekdo-images.com/images/pic55406.jpg for thumbnails andimages. This function fixes them.

Parameters url – the url to fix

Returns the fixed url

boardgamegeek.utils.get_cache_session_from_uri(uri)Returns a requests-cache session using caching specified in the URI. Valid uris are:

•memory:///?ttl=<seconds>

•sqlite:///path/to/sqlite.db?ttl=<seconds>&fast_save=<0|1>

Parameters uri – URI specifying the type of cache to use and its parameters

Returns CachedSession instance, which can be used as a regular requests session.

Raises BoardGameGeekError in case of error

boardgamegeek.utils.get_parsed_xml_response(requests_session, url, params=None, time-out=15, retries=3, retry_delay=5)

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 returned202

Returns xml.etree.ElementTree() corresponding to the XML

Raises BoardGameGeekAPINonXMLError if the API response wasn’t XML

Raises BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises BoardGameGeekAPIError if the response couldn’t be parsed

Raises BoardGameGeekTimeoutError if there was a timeout

2.2. Modules 17

Page 22: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

boardgamegeek.utils.xml_subelement_attr(xml_elem, subelement, convert=None, at-tribute=u’value’, default=None, quiet=False)

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 certainobject 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=u’value’, default=None,quiet=False)

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 acertain 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, de-fault=None, quiet=False)

Return the text of the specified subelement

For the document below:

18 Chapter 2. Table of Contents

Page 23: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

<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 certainobject 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

2.2. Modules 19

Page 24: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

20 Chapter 2. Table of Contents

Page 25: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 3

Features

This library exposes (as Python objects with properties) the following BoardGameGeek entities:

• Users

• Games

• User collections

• Player guilds

• Plays

• Hot items

requests-cache is used for locally caching replies in order to reduce the amount of requests sent to the server.

Note: The cache is enabled by default and it’s configured to use memory only. It’s also possible to use SQLite for apersistent cache.

21

Page 26: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

22 Chapter 3. Features

Page 27: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 4

Quick Install

To install boardgamegeek, just use pip:

> pip install boardgamegeek

23

Page 28: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

24 Chapter 4. Quick Install

Page 29: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 5

Usage

Here’s a quick usage example:

>>> from boardgamegeek import BoardGameGeek>>> bgg = BoardGameGeek()>>> g = bgg.game("Android: Netrunner")>>> g.name'Android: Netrunner'>>> g.id124742>>> for n in g.alternative_names: print n.encode("utf-8")...

25

Page 30: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

26 Chapter 5. Usage

Page 31: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 6

To Do

• Not all the information exposed by the official API is stored into the Python objects. Need to improve this.

• Try to support the other sites from the boardgamegeek’s family

• Allow better control for configuring the cache

• Improve documentation :)

Contributions/suggestions are welcome!

27

Page 32: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

28 Chapter 6. To Do

Page 33: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 7

Contributions

• Phil S. Stein (philsstein) (libBGG inspired this fork)

• Tom Usher (tomusher)

29

Page 34: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

30 Chapter 7. Contributions

Page 35: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

CHAPTER 8

Indices and tables

• genindex

• modindex

• search

31

Page 36: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

32 Chapter 8. Indices and tables

Page 37: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

Python Module Index

bboardgamegeek (Unix, Windows), 9boardgamegeek.api (Unix, Windows), 9boardgamegeek.collection, 12boardgamegeek.exceptions, 12boardgamegeek.games, 13boardgamegeek.guild (Unix, Windows), 13boardgamegeek.hotitems (Unix, Windows), 13boardgamegeek.plays (Unix, Windows), 14boardgamegeek.search, 15boardgamegeek.things (Unix, Windows), 15boardgamegeek.user (Unix, Windows), 16boardgamegeek.utils (Unix, Windows), 17

33

Page 38: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

34 Python Module Index

Page 39: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

Index

Aadd_buddy() (boardgamegeek.user.User method), 16add_game() (boardgamegeek.collection.Collection

method), 12add_guild() (boardgamegeek.user.User method), 16add_hot_item() (boardgamegeek.hotitems.HotItems

method), 14add_hot_item() (boardgamegeek.user.User method), 16add_play() (boardgamegeek.plays.Plays method), 15add_top_item() (boardgamegeek.user.User method), 16addr1 (boardgamegeek.guild.Guild attribute), 13addr2 (boardgamegeek.guild.Guild attribute), 13address (boardgamegeek.guild.Guild attribute), 13avatar (boardgamegeek.user.User attribute), 16

BBoardGame (class in boardgamegeek.games), 13BoardGameGeek (class in boardgamegeek.api), 9boardgamegeek (module), 9boardgamegeek.api (module), 9boardgamegeek.collection (module), 12boardgamegeek.exceptions (module), 12boardgamegeek.games (module), 13boardgamegeek.guild (module), 13boardgamegeek.hotitems (module), 13boardgamegeek.plays (module), 14boardgamegeek.search (module), 15boardgamegeek.things (module), 15boardgamegeek.user (module), 15, 16boardgamegeek.utils (module), 16, 17BoardGameGeekAPIError, 12BoardGameGeekAPINonXMLError, 12BoardGameGeekAPIRetryError, 12BoardGameGeekError, 12BoardGameGeekNetworkAPI (class in

boardgamegeek.api), 10BoardGameGeekTimeoutError, 13buddies (boardgamegeek.user.User attribute), 16

Ccategory (boardgamegeek.guild.Guild attribute), 13city (boardgamegeek.guild.Guild attribute), 13Collection (class in boardgamegeek.collection), 12collection() (boardgamegeek.api.BoardGameGeekNetworkAPI

method), 10CollectionBoardGame (class in boardgamegeek.games),

13comment (boardgamegeek.plays.PlaySession attribute),

14country (boardgamegeek.guild.Guild attribute), 13country (boardgamegeek.user.User attribute), 16

Ddata() (boardgamegeek.utils.DictObject method), 17date (boardgamegeek.plays.PlaySession attribute), 14description (boardgamegeek.guild.Guild attribute), 13DictObject (class in boardgamegeek.utils), 17duration (boardgamegeek.plays.PlaySession attribute), 14

Eexpands (boardgamegeek.games.BoardGame attribute),

13expansion (boardgamegeek.games.BoardGame attribute),

13expansions (boardgamegeek.games.BoardGame at-

tribute), 13

Ffirstname (boardgamegeek.user.User attribute), 16fix_url() (in module boardgamegeek.utils), 17

Ggame() (boardgamegeek.api.BoardGameGeek method), 9game_id (boardgamegeek.plays.Plays attribute), 15game_id (boardgamegeek.plays.PlaySession attribute),

14game_name (boardgamegeek.plays.PlaySession at-

tribute), 14

35

Page 40: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

games() (boardgamegeek.api.BoardGameGeek method),10

get_cache_session_from_uri() (in moduleboardgamegeek.utils), 17

get_game_id() (boardgamegeek.api.BoardGameGeekmethod), 10

get_parsed_xml_response() (in moduleboardgamegeek.utils), 17

Guild (class in boardgamegeek.guild), 13guild() (boardgamegeek.api.BoardGameGeekNetworkAPI

method), 11guilds (boardgamegeek.user.User attribute), 16

Hhomepage (boardgamegeek.user.User attribute), 16hot10 (boardgamegeek.user.User attribute), 16hot_items() (boardgamegeek.api.BoardGameGeekNetworkAPI

method), 11HotItem (class in boardgamegeek.hotitems), 13HotItems (class in boardgamegeek.hotitems), 14

Iid (boardgamegeek.plays.PlaySession attribute), 14id (boardgamegeek.things.Thing attribute), 15incomplete (boardgamegeek.plays.PlaySession attribute),

14items (boardgamegeek.collection.Collection attribute), 12items (boardgamegeek.hotitems.HotItems attribute), 14

Llast_login (boardgamegeek.user.User attribute), 16lastname (boardgamegeek.user.User attribute), 16

Mmanager (boardgamegeek.guild.Guild attribute), 13members (boardgamegeek.guild.Guild attribute), 13

Nname (boardgamegeek.plays.PlaysessionPlayer attribute),

15name (boardgamegeek.things.Thing attribute), 15new (boardgamegeek.plays.PlaysessionPlayer attribute),

15nowinstats (boardgamegeek.plays.PlaySession attribute),

14

Oowner (boardgamegeek.collection.Collection attribute),

12

Pplays (boardgamegeek.plays.Plays attribute), 15Plays (class in boardgamegeek.plays), 14

plays() (boardgamegeek.api.BoardGameGeekNetworkAPImethod), 11

PlaySession (class in boardgamegeek.plays), 14PlaysessionPlayer (class in boardgamegeek.plays), 15postalcode (boardgamegeek.guild.Guild attribute), 13psn_account (boardgamegeek.user.User attribute), 16

Qquantity (boardgamegeek.plays.PlaySession attribute), 14

Rrank (boardgamegeek.hotitems.HotItem attribute), 13RateLimitingAdapter (class in boardgamegeek.utils), 17rating (boardgamegeek.plays.PlaysessionPlayer at-

tribute), 15

Sscore (boardgamegeek.plays.PlaysessionPlayer attribute),

15search() (boardgamegeek.api.BoardGameGeekNetworkAPI

method), 12SEARCH_BOARD_GAME

(boardgamegeek.api.BoardGameGeekNetworkAPIattribute), 10

SEARCH_BOARD_GAME_EXPANSION(boardgamegeek.api.BoardGameGeekNetworkAPIattribute), 10

SEARCH_RPG_ITEM (boardgamegeek.api.BoardGameGeekNetworkAPIattribute), 10

SEARCH_VIDEO_GAME(boardgamegeek.api.BoardGameGeekNetworkAPIattribute), 10

SearchResult (class in boardgamegeek.search), 15send() (boardgamegeek.utils.RateLimitingAdapter

method), 17startposition (boardgamegeek.plays.PlaysessionPlayer at-

tribute), 15state (boardgamegeek.guild.Guild attribute), 13state (boardgamegeek.user.User attribute), 16steam_account (boardgamegeek.user.User attribute), 16

TThing (class in boardgamegeek.things), 15thumbnail (boardgamegeek.hotitems.HotItem attribute),

13top10 (boardgamegeek.user.User attribute), 16total_buddies (boardgamegeek.user.User attribute), 16total_guilds (boardgamegeek.user.User attribute), 16trade_rating (boardgamegeek.user.User attribute), 16type (boardgamegeek.search.SearchResult attribute), 15

Uuser (boardgamegeek.plays.Plays attribute), 15

36 Index

Page 41: boardgamegeek Documentation - Read the Docs · 2019. 4. 2. · boardgamegeek Documentation, Release 0.11.1 •Fixed the retry mechanism, allowing retries=0 (meaning no retries at

boardgamegeek Documentation, Release 0.11.1

User (class in boardgamegeek.user), 16user() (boardgamegeek.api.BoardGameGeekNetworkAPI

method), 12user_id (boardgamegeek.plays.Plays attribute), 15user_id (boardgamegeek.plays.PlaySession attribute), 14user_id (boardgamegeek.plays.PlaysessionPlayer at-

tribute), 15username (boardgamegeek.plays.PlaysessionPlayer at-

tribute), 15

Wwebsite (boardgamegeek.guild.Guild attribute), 13wii_account (boardgamegeek.user.User attribute), 16win (boardgamegeek.plays.PlaysessionPlayer attribute),

15

Xxbox_account (boardgamegeek.user.User attribute), 16xml_subelement_attr() (in module boardgamegeek.utils),

17xml_subelement_attr_list() (in module

boardgamegeek.utils), 18xml_subelement_text() (in module boardgamegeek.utils),

18

Yyear (boardgamegeek.hotitems.HotItem attribute), 14year (boardgamegeek.search.SearchResult attribute), 15

Index 37