from .api import (
player_search, player_data, player_achievements, player_data_uid,
player_sign_in, extend_player_sign_in, player_sign_out, clan_search,
clan_details, player_clan_data, clan_glossary, crew_info, vehicle_info,
packages_info, equipment_consumable_info, achievement_info,
tankopedia_info, types_of_ratings, dates_with_ratings, player_ratings,
adjacent_positions_in_ratings, top_players, player_tank_statistics,
player_tank_achievements
)
[docs]class WOTXSession(object):
r"""
API session wrapper that can be setup once in order to handle certain
explicit parameters without needing to pass them in for every method call.
.. note:: You may override settings by passing in the appropriate parameter
at each function call
:param str application_id: Your application key (generated by WG)
:param str language: Localized language
:param str realm: Platform API. "xbox" or "ps4"
"""
def __init__(self, application_id='demo', language='en', api_realm='xbox'):
self.application_id = application_id
self.language = language
if api_realm is None:
self.api_realm = 'xbox'
elif api_realm.lower() not in ('xbox', 'ps4'):
raise ValueError('Parameter "api_realm" is invalid!')
else:
self.api_realm = api_realm.lower()
def player_search(self, search, application_id=None, **kwargs):
r"""
Search for a player by name
:param str search: Player name to search for. Maximum length is 24
symbols
:param str application_id: Your application key (generated by WG)
:param fields: Reponse fields to exclude or _only_ include. To exclude
a field, use "-" in front of its name
:type fields: list(str)
:param limit: Number of returned entries. Default is 100; values less
than 1 or greater than 100 are ignored
:type limit: int or str
:param str stype: Search type. Defines minimum length and type of
search. Default value is "startswith". Valid values:
* "startswith" - search by initial characters of
player name. Minimum length: 3 characters.
Case-insensitive.
* "exact" - Search by exact match of player name.
Minimum length: 1 character. Case-insensitive
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_search(search, application_id, **kwargs)
def player_data(self, account_id, application_id=None, **kwargs):
r"""
Retrieve information on one or more players, including statistics.
Private data requires an access token from a valid, active login.
:param account_id: Player ID(s)
:type account_id: int str or iterable
:param str application_id: Your application key (generated by WG)
:param str access_token: Authentication token from active session
:param str fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_data(account_id, application_id, **kwargs)
def player_achievements(self, account_id, application_id=None, **kwargs):
r"""
View player's achievements, such as mastery badges and battle
commendations
:param account_id: Player account ID(s). Max limit is 100
:type account_id: int or str or iterable
:param str application_id: Your application key (generated by WG)
:param str fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_achievements(account_id, application_id, **kwargs)
def player_data_uid(self, uid, application_id=None, **kwargs):
r"""
Retrieve player info using Microsoft XUID or PlayStation PSNID.
.. note:: Only *one* realm may be called at a time using this method!
:param uid: Player UID(s). Max limit is 100
:type uid: int or str or iterable
:param str application_id: Your application key (generated by WG)
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_data_uid(uid, application_id, **kwargs)
def player_sign_in(self, application_id=None, **kwargs):
r"""
Log in a player, receiving an access token once completed successfully.
:param str application_id: Your application key (generated by WG)
:param str display: Layout for mobile applications.
Valid values:
* "page" - Page
* "popup" - Popup window
* "touch" - Touch
:param int expires_at: UNIX POSIX timestamp or delta in seconds.
Maximum expiration time is 2 weeks
:param int nofollow: If set to 1, the user is not redirected. A URL is
returned in response. Default is 0. Max is 1, Min
is 0
:param HTTP redirect_uri: URL where user is redirected to
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_sign_in(application_id, **kwargs)
def extend_player_sign_in(self, access_token, application_id=None,
**kwargs):
r"""
Extend the active session of a user when the current session is about
to expire
:param str access_token: Current user active session token
:param str application_id: Your application key (generated by WG)
:param int expires_at: UNIX POSIX timestamp or delta in seconds.
Maximum expiration time is 2 weeks
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return extend_player_sign_in(access_token, application_id, **kwargs)
def player_sign_out(self, access_token, application_id=None, **kwargs):
r"""
Terminate the user's active session. Once successful, the access token
will no longer be valid
:param str access_token: Session token for the user
:param str application_id: Your application key (generated by WG)
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_sign_out(access_token, application_id, **kwargs)
def clan_search(self, application_id=None, **kwargs):
r"""
Search for clan(s)
Specifying a clan is _optional._ If you do not specify one, the API
will simply return a listing of clans in order of highest member count
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param int limit: Maximum number of clans to return. Max is 100
:param int page_no: Page number to start listing on. Default is 1
:param str search: Clan name to search for
:param str language: Localized language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return clan_search(application_id, **kwargs)
def clan_details(self, clan_id, application_id=None, **kwargs):
r"""
Retrieve detailed information on one or more clans.
May also be used for retrieving a list of players in a clan.
:param clan_id: Clan ID(s). Max limit 100. Min value is 1
:type clan_id: int or iter(int)
:param str application_id: Your application key (generated by WG)
:param extra: Extra fields to be included in the response
:type extra: list(str)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Localized language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return clan_details(clan_id, application_id, **kwargs)
def player_clan_data(self, account_id, application_id=None, **kwargs):
r"""
Retrieve clan relationship for one or more players
:param str account_id: Player ID number(s)
:param str application_id: Your application key (generated by WG)
:param extra: Additional fields to retrieve
:type extra: list(str)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Localized language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_clan_data(account_id, application_id, **kwargs)
def clan_glossary(self, application_id=None, **kwargs):
r"""
Retrieve general information regarding clans (_not_ clan-specific info)
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return clan_glossary(application_id, **kwargs)
def crew_info(self, application_id=None, **kwargs):
r"""
Retrieve information about crews
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return crew_info(application_id, **kwargs)
def vehicle_info(self, application_id=None, **kwargs):
r"""
Retrieve information on one or more tanks
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param nation: Nation(s) to filter tanks to
:type nation: list(str)
:param tank_id: All desired tanks (limit 100)
:type tank_id: list(int or str)
:param tier: Tiers to filter to
:type tier: list(int)
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: Tank information
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return vehicle_info(application_id, **kwargs)
def packages_info(self, tank_id, application_id=None, **kwargs):
r"""
Retrieve package characteristics and their interdependence
:param tank_id: Vehicle(s) to retireve information for. Max limit is
100
:type tank_id: list(int)
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return packages_info(tank_id, application_id, **kwargs)
def equipment_consumable_info(
self, tank_id, application_id=None, **kwargs):
r"""
Retrieve vehicle equipment and consumables
:param tank_id: Vehicle(s) to retireve information for. Max limit is
100
:type tank_id: list(int)
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return equipment_consumable_info(tank_id, application_id, **kwargs)
def achievement_info(self, application_id=None, **kwargs):
r"""
Retrieve list of awards, medals, and ribbons
:param str application_id: Your application key (generated by WG)
:param category: Filter by award category. Valid values:
* "achievements" - Achievements
* "ribbons" - Ribbons
Max limit is 100
:type category: list(str)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return achievement_info(application_id, **kwargs)
def tankopedia_info(self, application_id=None, **kwargs):
r"""
Retrieve information regarding the Tankopeida itself
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return tankopedia_info(application_id, **kwargs)
def types_of_ratings(self, application_id=None, **kwargs):
r"""
Retrieve dictionary of rating periods and ratings details
:param str application_id: Your application key (generated by WG)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param str platform: Console platform. Default is "default" (all
consoles). Valid responses:
* "default" - All platforms (default)
* "xbox" - XBOX
* "ps4" - PlayStation 4
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return types_of_ratings(application_id, **kwargs)
def dates_with_ratings(self, rating, application_id=None, **kwargs):
r"""
Retrieve dates with available rating data
:param str rating: Rating period
:param str application_id: Your application key (generated by WG)
:param account_id: Player account ID. Max limit is 100
:type account_id: list(int)
:param str language: Response language
:param str platform: Console platform. Default is "default" (all
consoles). Valid responses:
* "default" - All platforms (default)
* "xbox" - XBOX
* "ps4" - PlayStation 4
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return dates_with_ratings(rating, application_id, **kwargs)
def player_ratings(self, rating, account_id,
application_id=None, **kwargs):
r"""
Retrieve player ratings by specified IDs
:param str rating: Rating period
:param account_id: Player account ID. Max limit is 100
:type account_id: list(int)
:param str application_id: Your application key (generated by WG)
:param date: Ratings calculation date. Up to 7 days before the current
date. Default value: yesterday. Date in UNIX timestamp or
ISO 8601 format. E.g. 1376542800 or 2013-08-15T00:00:00
:type date: str or int or datetime.datetime
:param str language: Response language
:param str platform: Console platform. Default is "default" (all
consoles). Valid responses:
* "default" - All platforms (default)
* "xbox" - XBOX
* "ps4" - PlayStation 4
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_ratings(rating, application_id, **kwargs)
def adjacent_positions_in_ratings(self, account_id, rank_field, rating,
application_id=None, **kwargs):
r"""
Retrieve list of adjacent positions in specified rating
:param account_id: Player account ID. Max limit is 100
:type account_id: list(int)
:param str rank_field: Rating category
:param str rating: Rating period
:param str application_id: Your application key (generated by WG)
:param date: Ratings calculation date. Up to 7 days before the current
date. Default value: yesterday. Date in UNIX timestamp or
ISO 8601 format. E.g. 1376542800 or 2013-08-15T00:00:00
:type date: str or int or datetime.datetime
:param str language: Response language
:param int limit: Number of returned entries. Default is 5. Max limit
is 50
:param str platform: Console platform. Default is "default" (all
consoles). Valid responses:
* "default" - All platforms (default)
* "xbox" - XBOX
* "ps4" - PlayStation 4
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return adjacent_positions_in_ratings(
account_id, rank_field, rating, application_id, **kwargs)
def top_players(self, rank_field, rating, application_id=None, **kwargs):
r"""
Retrieve the list of top players by specified parameter
:param str rank_field: Rating category
:param str rating: Rating period
:param str application_id: Your application key (generated by WG)
:param date: Ratings calculation date. Up to 7 days before the current
date. Default value: yesterday. Date in UNIX timestamp or
ISO 8601 format. E.g. 1376542800 or 2013-08-15T00:00:00
:type date: str or int or datetime.datetime
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str language: Response language
:param int limit: Number of returned entries. Default is 10. Max limit
is 1000
:param int page_no: Result page number. Default is 1. Min is 1
:param str platform: Console platform. Default is "default" (all
consoles). Valid responses:
* "default" - All platforms (default)
* "xbox" - XBOX
* "ps4" - PlayStation 4
:param str api_realm: Platform API. "xbox" or "ps4"
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return top_players(rank_field, rating, application_id, **kwargs)
def player_tank_statistics(self, account_id, application_id=None,
**kwargs):
r"""
Retrieve information on all tanks that a player has owned and/or used
:param int account_id: target player ID
:param str application_id: Your application key (generated by WG)
:param str access_token: Authentication token from player login (if
accessing private data)
:param str in_garage: Filter ('0') for tanks absent from garage, or
('1') available
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str api_realm: Platform API. "xbox" or "ps4"
:param str language: Response language
:param tank_id: Limit statistics to vehicle(s). Max limit is 100
:type tank_id: list(int)
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_tank_statistics(account_id, application_id, **kwargs)
def player_tank_achievements(self, account_id, application_id=None,
**kwargs):
r"""
Retrieve players' achievement details
:param int account_id: target player ID
:param str application_id: Your application key (generated by WG)
:param str access_token: Authentication token from player login (if
accessing private data)
:param fields: Fields to filter or explicitly include. To exclude,
prepend the field with a "-"
:type fields: list(str)
:param str in_garage: Filter ('0') for tanks absent from garage, or
('1') available
:param tank_id: Limit statistics to vehicle(s). Max limit is 100
:type tank_id: list(int)
:param str api_realm: Platform API. "xbox" or "ps4"
:param str language: Response language
:param int timeout: Maximum allowed time to wait for response from
servers
:return: API response
:rtype: WOTXResponse
:raises WOTXResponseError: If the API returns with an "error" field
"""
if application_id is None:
application_id = self.application_id
if 'language' not in kwargs:
kwargs['language'] = self.language
if 'api_realm' not in kwargs:
kwargs['api_realm'] = self.api_realm
return player_tank_achievements(account_id, application_id, **kwargs)