A python interface to the boardgamegeek.com API and boardgame utils.
Project description
libBGG
======
A python interface to boardgamegeek.com. Pulls information from BGG and
creates appropriate python objects for the data.
Supports Python 3
It contains three parts:
* BGGAPI - for retriving information from BGG and parsing it into python objects
* the boardgame objects: Boardgame, Guild, etc.
* A caching API for writing retrieved XML queries to the local filesystem.
Example python usage:
--------------------------------
> from libBGG.BGGAPI import BGGAPI
> api = BGGAPI()
> bg = api.fetch_boardgame('YINSH')
> print 'Yinsh was created in %s by %s' % (bg.year, ', '.join(bg.designers))
Yinsh was created in 2003 by Kris Burm
> guild = api.fetch_guild('1920') # BGG only supports guild fetch by ID.
> print 'BGG Guild %s has %d members.' % (guild.name, len(guild.members))
BGG Guild "Paradox" has 2 members.
> collection = api.fetch_collection('philsstein')
> print 'philsstein rated yinsh: %s out of 10' % collection.rating['YINSH'].userrating
philsstein rated yinsh: 8 out of 10
---------------------------------
There are a few example scripts included that use libBGG: "bgg_query", which queries BGG
and dumps the information it finds and "top_rated", which takes a Guild ID
and dumps the top rated games and ratings of members of the guild.
Usage:
--------------------------------
$ ./bin/top_rated --help
usage: top_rated [-h] [-g GUILD] [-n NUMBER] [-C CACHE] [-f] [-H HTMLOUT]
[-w WIKIOUT]
[-l {none,all,debug,info,warning,error,critical}]
Show top ratings for a given guild.
optional arguments:
-h, --help show this help message and exit
-g GUILD, --guild GUILD
ID of guild. (bgg does not support guild by name
search.
-n NUMBER, --number NUMBER
How many games to show. (Default=100)
-C CACHE, --cache CACHE
Path to cache. If given look in cache first, then
fetch from BGG. Otherwise always fetch from BGG.
collection. If --forcefetch is given, force a fetch
into the cache.
-f, --forcefetch If given, force a refetch of any data. This argument
does nothing if a cache is not given.
-H HTMLOUT, --htmlout HTMLOUT
If given, write an HTML table of the data to the given
file.
-w WIKIOUT, --wikiout WIKIOUT
If given, write a wiki formatted version of the data
to the given file.
-l {none,all,debug,info,warning,error,critical}, --loglevel {none,all,debug,info,warning,error,critical}
The level at which to log. Must be one of none, debug,
info, warning, error, or critical. Default is none.
(This is mostly used for debugging.)
$ ./bin/bgg_query --help
usage: bgg_query [-h] [-g GAME] [-G GUILD] [-u USER] [-c COLLECTION]
[-C CACHE] [-f]
[-l {none,all,debug,info,warning,error,critical}]
Query BGG for boardgames and related information. All arguments may be given
and given multiple times.
optional arguments:
-h, --help show this help message and exit
-g GAME, --game GAME Name of game.
-G GUILD, --guild GUILD
ID of guild. (bgg does not support guild by name
search.
-u USER, --user USER Name of BGG user.
-c COLLECTION, --collection COLLECTION
User's collection
-C CACHE, --cache CACHE
Path to cache. If given look in cache first, then
fetch from BGG. Otherwise always fetch from BGG.
collection. If --forcefetch is given, force a fetch
into the cache.
-f, --forcefetch If given, force a refetch of any data. This argument
does nothing if a cache is not given.
-l {none,all,debug,info,warning,error,critical}, --loglevel {none,all,debug,info,warning,error,critical}
The level at which to log. Must be one of none, debug,
info, warning, error, or critical. Default is none.
(This is mostly used for debugging.)
Script sample runs:
-------------------------
# Yes, there is a "yinsh" user at BGG.
$ ./bin/bgg_query --user yinsh --collection yinsh --game yinsh
yinsh's collection has 2 games: Monopoly: Deluxe Edition (1995) rated: 5, Scrabble (1948) rated: 6,
yinsh:
bggid: 83873
country: Malaysia
firstname: Yin
hot10:
lastname: Swee Heng
name: yinsh
top10:
traderating: 0
yearregistered: 2006
YINSH:
artists: lu'cifer
bgid: 7854
categories: Abstract Strategy
designers: Kris Burm
families: Mensa Select, Project GIPF
maxplayers: 2
mechanics: Grid Movement, Pattern Building
minplayers: 2
names: YINSH
playingtime: 30
publishers: Don & Co., Rio Grande Games, Smart Toys and Games, Inc.
year: 2003
$ ./bin/bgg_query.py --guild 1291
Guild r/boardgames:
bggid: 1291
members: caitlinsquared, DistinctlyBenign, jdclewis, magdalencox, Schnubby, zetaceti
name: r/boardgames
$ ./bin/bgg_query -g qwirkle -g notexists -g "Prêt-à-Porter"
Qwirkle:
artists: b''
bgid: b'25669'
categories: b'Abstract Strategy'
designers: b'Susan McKinley Ross'
families: b'Mensa Select, Qwirkle'
maxplayers: b'4'
mechanics: b'Hand Management, Pattern Building, Tile Placement'
minplayers: b'2'
names: b'Qwirkle, Qwirkle \xc3\xa9dition voyage, Qwirkle Travel, \xed\x81\x90\xec\x9c\x84\xed\x81\xb4'
playingtime: b'45'
publishers: b'MindWare, 999 Games, ADC Blackfire Entertainment, Compaya.hu - Gamer Caf\xc3\xa9 Kft., Competo / Marektoy, Corfix, cutia.ro, \xc3\x89veil & Jeux, G3, Green Board Game Co., IELLO, Outset Media, Productief BV, Schmidt Spiele'
year: b'2006'
notexists: not found. No connection or not in cache if given.
Prêt-à-Porter:
artists: b'Mariusz Gandzel, Tomasz Jedruszek, Micha\xc5\x82 Oracz, Darek Zabrocki'
bgid: b'87890'
categories: b'Economic, Industry / Manufacturing'
designers: b'Piotr Haraszczak, Ignacy Trzewiczek'
families: b''
maxplayers: b'4'
mechanics: b'Card Drafting, Set Collection, Worker Placement'
minplayers: b'2'
names: b'Pr\xc3\xaat-\xc3\xa0-Porter'
playingtime: b'90'
publishers: b'Portal Games'
year: b'2010'
$ ./bin/top_rated -C ~/bgg_cache -g 1291 -n 15
Fetched member information for guild "r/boardgames"
Fetching 6 member collections.......Fetched 6 collections totalling 1083 games and 1062 ratings.
Computing ratings...
Ratings for guild r/boardgames:
===============================
Rank Rating Rated Stddev Name
---- ------ ----- ------ ----
1. 10.00 1 0.00 Kemet
2. 10.00 1 0.00 Dune
3. 10.00 1 0.00 Survive: Escape from Atlantis!
4. 10.00 1 0.00 Galaxy Trucker: Anniversary Edition
5. 10.00 1 0.00 Rex: Final Days of an Empire
6. 10.00 1 0.00 Discworld: Ankh-Morpork
7. 10.00 1 0.00 The Great Zimbabwe
8. 10.00 1 0.00 Theseus: The Dark Orbit
9. 10.00 1 0.00 Dice Town
10. 9.50 1 0.00 Chicago Express
11. 9.00 1 0.00 Glory to Rome
12. 9.00 1 0.00 Terra Mystica
13. 9.00 1 0.00 Coloretto
14. 9.00 1 0.00 Hansa Teutonica
15. 9.00 1 0.00 London
Computed at: Mon Apr 28 17:45:22 2014
Using 1062 ratings from 6 guild members.
Version history
---------------
0.1.3 - Minor updates for top_rated
0.1.2 - bin/top_rated works. added local filesystem caching.
0.1.1 - data caching added
0.1.0 - inital checkin
======
A python interface to boardgamegeek.com. Pulls information from BGG and
creates appropriate python objects for the data.
Supports Python 3
It contains three parts:
* BGGAPI - for retriving information from BGG and parsing it into python objects
* the boardgame objects: Boardgame, Guild, etc.
* A caching API for writing retrieved XML queries to the local filesystem.
Example python usage:
--------------------------------
> from libBGG.BGGAPI import BGGAPI
> api = BGGAPI()
> bg = api.fetch_boardgame('YINSH')
> print 'Yinsh was created in %s by %s' % (bg.year, ', '.join(bg.designers))
Yinsh was created in 2003 by Kris Burm
> guild = api.fetch_guild('1920') # BGG only supports guild fetch by ID.
> print 'BGG Guild %s has %d members.' % (guild.name, len(guild.members))
BGG Guild "Paradox" has 2 members.
> collection = api.fetch_collection('philsstein')
> print 'philsstein rated yinsh: %s out of 10' % collection.rating['YINSH'].userrating
philsstein rated yinsh: 8 out of 10
---------------------------------
There are a few example scripts included that use libBGG: "bgg_query", which queries BGG
and dumps the information it finds and "top_rated", which takes a Guild ID
and dumps the top rated games and ratings of members of the guild.
Usage:
--------------------------------
$ ./bin/top_rated --help
usage: top_rated [-h] [-g GUILD] [-n NUMBER] [-C CACHE] [-f] [-H HTMLOUT]
[-w WIKIOUT]
[-l {none,all,debug,info,warning,error,critical}]
Show top ratings for a given guild.
optional arguments:
-h, --help show this help message and exit
-g GUILD, --guild GUILD
ID of guild. (bgg does not support guild by name
search.
-n NUMBER, --number NUMBER
How many games to show. (Default=100)
-C CACHE, --cache CACHE
Path to cache. If given look in cache first, then
fetch from BGG. Otherwise always fetch from BGG.
collection. If --forcefetch is given, force a fetch
into the cache.
-f, --forcefetch If given, force a refetch of any data. This argument
does nothing if a cache is not given.
-H HTMLOUT, --htmlout HTMLOUT
If given, write an HTML table of the data to the given
file.
-w WIKIOUT, --wikiout WIKIOUT
If given, write a wiki formatted version of the data
to the given file.
-l {none,all,debug,info,warning,error,critical}, --loglevel {none,all,debug,info,warning,error,critical}
The level at which to log. Must be one of none, debug,
info, warning, error, or critical. Default is none.
(This is mostly used for debugging.)
$ ./bin/bgg_query --help
usage: bgg_query [-h] [-g GAME] [-G GUILD] [-u USER] [-c COLLECTION]
[-C CACHE] [-f]
[-l {none,all,debug,info,warning,error,critical}]
Query BGG for boardgames and related information. All arguments may be given
and given multiple times.
optional arguments:
-h, --help show this help message and exit
-g GAME, --game GAME Name of game.
-G GUILD, --guild GUILD
ID of guild. (bgg does not support guild by name
search.
-u USER, --user USER Name of BGG user.
-c COLLECTION, --collection COLLECTION
User's collection
-C CACHE, --cache CACHE
Path to cache. If given look in cache first, then
fetch from BGG. Otherwise always fetch from BGG.
collection. If --forcefetch is given, force a fetch
into the cache.
-f, --forcefetch If given, force a refetch of any data. This argument
does nothing if a cache is not given.
-l {none,all,debug,info,warning,error,critical}, --loglevel {none,all,debug,info,warning,error,critical}
The level at which to log. Must be one of none, debug,
info, warning, error, or critical. Default is none.
(This is mostly used for debugging.)
Script sample runs:
-------------------------
# Yes, there is a "yinsh" user at BGG.
$ ./bin/bgg_query --user yinsh --collection yinsh --game yinsh
yinsh's collection has 2 games: Monopoly: Deluxe Edition (1995) rated: 5, Scrabble (1948) rated: 6,
yinsh:
bggid: 83873
country: Malaysia
firstname: Yin
hot10:
lastname: Swee Heng
name: yinsh
top10:
traderating: 0
yearregistered: 2006
YINSH:
artists: lu'cifer
bgid: 7854
categories: Abstract Strategy
designers: Kris Burm
families: Mensa Select, Project GIPF
maxplayers: 2
mechanics: Grid Movement, Pattern Building
minplayers: 2
names: YINSH
playingtime: 30
publishers: Don & Co., Rio Grande Games, Smart Toys and Games, Inc.
year: 2003
$ ./bin/bgg_query.py --guild 1291
Guild r/boardgames:
bggid: 1291
members: caitlinsquared, DistinctlyBenign, jdclewis, magdalencox, Schnubby, zetaceti
name: r/boardgames
$ ./bin/bgg_query -g qwirkle -g notexists -g "Prêt-à-Porter"
Qwirkle:
artists: b''
bgid: b'25669'
categories: b'Abstract Strategy'
designers: b'Susan McKinley Ross'
families: b'Mensa Select, Qwirkle'
maxplayers: b'4'
mechanics: b'Hand Management, Pattern Building, Tile Placement'
minplayers: b'2'
names: b'Qwirkle, Qwirkle \xc3\xa9dition voyage, Qwirkle Travel, \xed\x81\x90\xec\x9c\x84\xed\x81\xb4'
playingtime: b'45'
publishers: b'MindWare, 999 Games, ADC Blackfire Entertainment, Compaya.hu - Gamer Caf\xc3\xa9 Kft., Competo / Marektoy, Corfix, cutia.ro, \xc3\x89veil & Jeux, G3, Green Board Game Co., IELLO, Outset Media, Productief BV, Schmidt Spiele'
year: b'2006'
notexists: not found. No connection or not in cache if given.
Prêt-à-Porter:
artists: b'Mariusz Gandzel, Tomasz Jedruszek, Micha\xc5\x82 Oracz, Darek Zabrocki'
bgid: b'87890'
categories: b'Economic, Industry / Manufacturing'
designers: b'Piotr Haraszczak, Ignacy Trzewiczek'
families: b''
maxplayers: b'4'
mechanics: b'Card Drafting, Set Collection, Worker Placement'
minplayers: b'2'
names: b'Pr\xc3\xaat-\xc3\xa0-Porter'
playingtime: b'90'
publishers: b'Portal Games'
year: b'2010'
$ ./bin/top_rated -C ~/bgg_cache -g 1291 -n 15
Fetched member information for guild "r/boardgames"
Fetching 6 member collections.......Fetched 6 collections totalling 1083 games and 1062 ratings.
Computing ratings...
Ratings for guild r/boardgames:
===============================
Rank Rating Rated Stddev Name
---- ------ ----- ------ ----
1. 10.00 1 0.00 Kemet
2. 10.00 1 0.00 Dune
3. 10.00 1 0.00 Survive: Escape from Atlantis!
4. 10.00 1 0.00 Galaxy Trucker: Anniversary Edition
5. 10.00 1 0.00 Rex: Final Days of an Empire
6. 10.00 1 0.00 Discworld: Ankh-Morpork
7. 10.00 1 0.00 The Great Zimbabwe
8. 10.00 1 0.00 Theseus: The Dark Orbit
9. 10.00 1 0.00 Dice Town
10. 9.50 1 0.00 Chicago Express
11. 9.00 1 0.00 Glory to Rome
12. 9.00 1 0.00 Terra Mystica
13. 9.00 1 0.00 Coloretto
14. 9.00 1 0.00 Hansa Teutonica
15. 9.00 1 0.00 London
Computed at: Mon Apr 28 17:45:22 2014
Using 1062 ratings from 6 guild members.
Version history
---------------
0.1.3 - Minor updates for top_rated
0.1.2 - bin/top_rated works. added local filesystem caching.
0.1.1 - data caching added
0.1.0 - inital checkin
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
libBGG-0.1.3.tar.gz
(12.7 kB
view hashes)