def get_game(self,
game_ids=None,
comments=False,
comments_page=1,
stats=False,
historical=False,
historical_start=None,
historical_end=None,
marketplace=False):
"""
Gets info on a particular game or games. game_ids can be either
an integer id, a string id ("12345"), or an iterable of ids.
game_ids:(str|int|list[int|str]) The id or ids to get info for
comments:bool Get user comments. Can be paginated with
comments_page
comments_page:int The page of comments to retrieve
stats:bool Retrieve game stats
historical:bool Include historical game stats
historical_start:datetime.date The start date for historical stats
historical_end:datetime.date The end date for historical stats
marketplace:bool Also return the marketplace information for the
game
"""
if isinstance(game_ids, (str, int)):
game_ids = [int(game_ids)]
else:
game_ids = [int(gid) for gid in game_ids]
d = {'stats': int(stats)}
if comments:
# Set the comments options
d['comments'] = 1
d['comments_page'] = comments_page
if historical:
# Set the historical options
d['historical'] = 1
if isinstance(historical_start, date):
d['from'] = str(historical_start)
elif historical_start is not None:
raise InvalidInputError('"historical_start" must be of type '
'datetime.date, not {}'.format(
type(historical_start)))
if isinstance(historical_end, date):
d['to'] = str(historical_end)
elif historical_end is not None:
raise InvalidInputError('"historical_end" must be of type '
'datetime.date, not {}'.format(
type(historical_end)))
# retrieve marketplace data if specified
d['marketplace'] = int(marketplace)
return self.call(
'boardgame/{}'.format(','.join([str(gid) for gid in game_ids])), d)
def get_guilds(self, gid, members=False, sort='username', page=1):
"""
Gets the guild(s) for the given guild id(s).
gid:int|list[int] The guild id(s) to retrieve
members:bool Include the member roster in the results.
Default: False
sort:str How the results should be sorted when returned.
Default: username
page:int The page number to retrieve. Page size is 25
"""
if isinstance(gid, (list, tuple)):
gid = ','.join([str(i) for i in gid])
if sort not in self.guild_sorts:
raise InvalidInputError('Guild sort types must be one of '
'{}'.format(', '.join(self.guild_sorts)))
d = {
'id': gid,
'members': int(members),
'sort': sort,
'page': int(page),
}
return self.call('guild', d)
def get_user(self,
username,
buddies=False,
guilds=False,
hot=False,
top=False,
domain='boardgame',
page=1):
"""
Get information about a user.
username:str The username to get the info about
buddies:bool Get buddies reports too. Default: False
guilds:bool Get guilds reports too. Default: False
hot:bool Include the user's hot 10 list. Default: False
top:bool Include the user's top 10 list. Default: False
domain:str Controls the domain for the user's hot/top 10
Default: boardgame
page:int The page of items to return. Page size is 100
"""
if domain is not None and domain not in self.user_domains:
raise InvalidInputError('User domain must be one of {}'.format(
', '.join(self.user_domains)))
d = {
'name': username,
'buddies': int(buddies),
'guilds': int(guilds),
'hot': int(hot),
'top': int(top),
'domain': domain,
'page': int(page),
}
return self.call('user', d)
def get_plays(self,
username=None,
gid=None,
play_type='thing',
min_date=None,
max_date=None,
subtype='boardgame',
page=1):
"""
Gets the plays for a particular username, or game id and play type.
The default play type is "thing" and you must specify either a
game id or a username.
username:str The BGG username to retrieve plays for
gid:int The ID of the game to get the plays for
play_type:str The type of item to retrieve. Default: thing
min_date:str The starting date for the plays to retrieve.
Should be in the form of YYYY-MM-DD
max_date:str The ending date for the plays to retrieve.
Should be in the form of YYYY-MM-DD
subtype:str The subtype to get plays for. Default: boardgame
page:int The page to retrieve for this. Page size is 100
"""
if play_type not in self.play_types:
raise InvalidInputError('play_type must be one of {}'.format(
', '.join(self.play_types)))
if subtype not in self.play_subtypes:
raise InvalidInputError('play_subtype must be one of {}'.format(
', '.join(self.play_subtypes)))
if username is None and gid is None:
raise InvalidInputError('You must specify either a username or '
'a game id (gid)')
d = {
'username': username,
'id': int(gid) if gid is not None else gid,
'type': play_type,
'mindate': min_date,
'maxdate': max_date,
'subtype': subtype,
'page': int(page),
}
return self.call('plays', d)
def get_hotness(self, hot_type='boardgame'):
"""
Gets the list of hot items by type.
hot_type:str Gets a list of hot items for the given type
"""
if hot_type not in self.hot_types:
raise InvalidInputError('hot_type must be one of {}'.format(
', '.join(self.hot_types)))
d = {'type': hot_type}
return self.call('hot', d)
def get_thread_messages(self, thr_id, start=0, count=100, username=None):
"""
Gets messages from a forum/game thread.
thr_id:int The thread id
start:int The start article, increment this for pagination
count:int Number of messages to return, the default and
max are 100
username:str The username to filter for
"""
thr_id = int(thr_id)
d = {'start': int(start), 'count': int(count)}
if d['count'] > 100:
raise InvalidInputError(f'The maximum value for "count" is 100, '
f'and you requested {count}')
if username is not None:
d['username'] = username
return self.call(f'thread/{thr_id}', d)
def get_forum_lists(self, fid, ftype='thing'):
"""
Get a list of forums for a particular type.
fid:int Specifies the id of the type of database entry you want
the forum list for. This is the id that appears in the
address of the page when visiting a particular game in
the database.
ftype:str The forum list type. Default: thing
"""
if ftype not in self.forum_list_types:
raise InvalidInputError('Forum type must be either "thing" or '
'"family"')
d = {
'id': int(fid),
'type': ftype,
}
return self.call('forumlist', d)
def search(self, search_str, qtype='boardgame', exact=False):
"""
Search for board games by string. If exact is true, only exact
matches will be returned
search_str:str The string to search for
qtype:str|list[str] One of the "things"
exact:bool Match the string exactly
"""
if not isinstance(qtype, (list, tuple)):
qtype = [qtype]
invalid_types = set(qtype) - set(self.search_types)
if invalid_types:
raise InvalidInputError(f'The qtypes must be one of {self.search_types}, '
f'invalid item(s) submitted: ({", ".join(invalid_types)})')
d = {'query': search_str, 'type': ','.join(qtype),
'exact': int(exact)}
return self.call('search', d)