builtins

All high level features of steam.client.SteamClient are implemented here in separate submodules.

Apps

class steam.client.builtins.apps.Apps(*args, **kwargs)

Bases: object

licenses = None

dict Accounts’ package licenses

get_player_count(app_id, timeout=5)

Get numbers of players for app id

Parameters:app_id (int) – app id
Returns:number of players
Return type:int, EResult
get_product_info(apps=[], packages=[], meta_data_only=False, raw=False, auto_access_tokens=True, timeout=15)

Get product info for apps and packages

Parameters:
  • apps (list) – items in the list should be either just app_id, or dict
  • packages (list) – items in the list should be either just package_id, or dict
  • meta_data_only (bool) – only meta data will be returned in the reponse (e.g. change number, missing_token, sha1)
  • raw (bool) – Data buffer for each app is returned as bytes in its’ original form. Apps buffer is text VDF, and package buffer is binary VDF
  • auto_access_token (bool) – automatically request and fill access tokens
Returns:

dict with apps and packages containing their info, see example below

Return type:

dict, None

{'apps':     {570: {...}, ...},
 'packages': {123: {...}, ...}
}

Access token is needed to access full information for certain apps, and also package info. Each app and package has its’ own access token. If a token is required then _missing_token=True in the response.

App access tokens are obtained by calling get_access_tokens(), and are returned only when the account has a license for the specified app. Example code:

result = client.get_product_info(apps=[123])

if result['apps'][123]['_missing_token']:
    tokens = client.get_access_token(apps=[123])

    result = client.get_product_info(apps=[{'appid': 123,
                                            'access_token': tokens['apps'][123]
                                            }])

Note

It is best to just request access token for all apps, before sending a product info request.

Package tokens are located in the account license list. See licenses

result = client.get_product_info(packages=[{'packageid': 123,
                                            'access_token': client.licenses[123].access_token,
                                            }])
get_changes_since(change_number, app_changes=True, package_changes=False)

Get changes since a change number

Parameters:
  • change_number (int) – change number to use as stating point
  • app_changes (bool) – whether to inclued app changes
  • package_changes (bool) – whether to inclued package changes
Returns:

CMsgClientPICSChangesSinceResponse

Return type:

proto message instance, or None on timeout

get_app_ticket(app_id)

Get app ownership ticket

Parameters:app_id (int) – app id
Returns:CMsgClientGetAppOwnershipTicketResponse
Return type:proto message
get_encrypted_app_ticket(app_id, userdata)

Gets the encrypted app ticket :param app_id: app id :type app_id: int :param userdata: userdata :type userdata: bytes :return: EncryptedAppTicket <https://github.com/ValvePython/steam/blob/39627fe883feeed2206016bacd92cf0e4580ead6/protobufs/encrypted_app_ticket.proto>_ :rtype: proto message

get_depot_key(app_id, depot_id)

Get depot decryption key

Parameters:
  • app_id (int) – app id
  • depot_id (int) – depot id
Returns:

CMsgClientGetDepotDecryptionKeyResponse

Return type:

proto message

get_cdn_auth_token(depot_id, hostname)

Get CDN authentication token

Note

This token is no longer needed for access to CDN files

Parameters:
  • depot_id (int) – depot id
  • hostname (str) – cdn hostname
Returns:

CMsgClientGetCDNAuthTokenResponse

Return type:

proto message

get_access_tokens(app_ids=[], package_ids=[])

Get access tokens

Parameters:
  • app_ids (list) – list of app ids
  • package_ids (list) – list of package ids
Returns:

dict with apps and packages containing their access tokens, see example below

Return type:

dict, None

{'apps':     {123: 8888888886, ...},
 'packages': {456: 6666666666, ...}
}
register_product_key(key)

Register/Redeem a CD-Key

Parameters:key (str) – CD-Key
Returns:format (eresult, result_details, receipt_info)
Return type:tuple

Example receipt_info:

{'BasePrice': 0,
  'CurrencyCode': 0,
  'ErrorHeadline': '',
  'ErrorLinkText': '',
  'ErrorLinkURL': '',
  'ErrorString': '',
  'LineItemCount': 1,
  'PaymentMethod': 1,
  'PurchaseStatus': 1,
  'ResultDetail': 0,
  'Shipping': 0,
  'Tax': 0,
  'TotalDiscount': 0,
  'TransactionID': UINT_64(111111111111111111),
  'TransactionTime': 1473000000,
  'lineitems': {'0': {'ItemDescription': 'Half-Life 3',
    'TransactionID': UINT_64(11111111111111111),
    'packageid': 1234}},
  'packageid': -1}
request_free_license(app_ids)

Request license for free app(s)

Parameters:app_ids (list) – list of app ids
Returns:format (EResult, result_details, receipt_info)
Return type:tuple

User

class steam.client.builtins.user.User(*args, **kwargs)

Bases: object

EVENT_CHAT_MESSAGE = 'chat_message'

On new private chat message

Parameters:
  • user (SteamUser) – steam user
  • message (str) – message text
persona_state = 1

current persona state

user = None

SteamUser instance once logged on

current_games_played = []

list of app ids currently being played

change_status(**kwargs)

Set name, persona state, flags

Note

Changing persona state will also change persona_state

Parameters:
  • persona_state (EPersonaState) – persona state (Online/Offline/Away/etc)
  • player_name (str) – profile name
  • persona_state_flags (EPersonaStateFlag) – persona state flags
request_persona_state(steam_ids, state_flags=863)

Request persona state data

Parameters:
get_user(steam_id, fetch_persona_state=True)

Get SteamUser instance for steam id

Parameters:
  • steam_id (int, SteamID) – steam id
  • fetch_persona_state (bool) – whether to request person state when necessary
Returns:

SteamUser instance

Return type:

SteamUser

games_played(app_ids)

Set the apps being played by the user

Parameters:app_ids (list) – a list of application ids

These app ids will be recorded in current_games_played.

set_ui_mode(uimode)

Set UI mode. Show little icon next to name in friend list. (e.g phone, controller, other)

Parameters:uimode (EClientUIMode) – UI mode integer

These app ids will be recorded in current_games_played.

Web

Web related features

class steam.client.builtins.web.Web(*args, **kwargs)

Bases: object

get_web_session_cookies()

Get web authentication cookies via WebAPI’s AuthenticateUser

Note

The cookies are valid only while SteamClient instance is logged on.

Returns:dict with authentication cookies
Return type:dict, None
get_web_session(language='english')

Get a requests.Session that is ready for use

See get_web_session_cookies()

Note

Auth cookies will only be send to (help|store).steampowered.com and steamcommunity.com domains

Note

The session is valid only while SteamClient instance is logged on.

Parameters:language (str) – localization language for steam pages
Returns:authenticated Session ready for use
Return type:requests.Session, None

Unified Messages

Methods to call service methods, also known as unified messages

Example code:

# the easy way
response = client.send_um_and_wait('Player.GetGameBadgeLevels#1', {
    'property': 1,
    'something': 'value',
    })

print(response.body)

# the other way
jobid = client.send_um('Player.GetGameBadgeLevels#1', {'something': 1})
response = client.wait_event(jobid)

The backend might error out, but we still get response. Here is how to check for error:

if response.header.eresult != EResult.OK:
    print(response.header.error_message)
class steam.client.builtins.unified_messages.UnifiedMessages(*args, **kwargs)

Bases: object

send_um(method_name, params=None)

Send service method request

Parameters:
  • method_name (str) – method name (e.g. Player.GetGameBadgeLevels#1)
  • params (dict) – message parameters
Returns:

job_id identifier

Return type:

str

Listen for jobid on this object to catch the response.

send_um_and_wait(method_name, params=None, timeout=10, raises=False)

Send service method request and wait for response

Parameters:
  • method_name (str) – method name (e.g. Player.GetGameBadgeLevels#1)
  • params (dict) – message parameters
  • timeout (int) – (optional) seconds to wait
  • raises (bool) – (optional) On timeout if False return None, else raise gevent.Timeout
Returns:

response message

Return type:

proto message instance

Raises:

gevent.Timeout

Leaderboards

Reading the leaderboards with SteamLeaderboard is as easy as iterating over a list.

class steam.client.builtins.leaderboards.Leaderboards(*args, **kwargs)

Bases: object

get_leaderboard(app_id, name)

New in version 0.8.2.

Find a leaderboard

Parameters:
  • app_id (int) – application id
  • name (str) – leaderboard name
Returns:

leaderboard instance

Return type:

SteamLeaderboard

Raises:

LookupError on message timeout or error

class steam.client.builtins.leaderboards.SteamLeaderboard(steam, app_id, name, data=None)

Bases: object

New in version 0.8.2.

Steam leaderboard object. Generated via Leaderboards.get_leaderboard() Works more or less like a list to access entries.

Note

Each slice will produce a message to steam. Steam and protobufs might not like large slices. Avoid accessing individual entries by index and instead use iteration or well sized slices.

Example usage:

lb = client.get_leaderboard(...)

for entry in lb[:100]:  # top 100
    print entry
class ELeaderboardDataRequest

Bases: steam.enums.base.SteamIntEnum

An enumeration.

Friends = 2
Global = 0
GlobalAroundUser = 1
Users = 3
class ELeaderboardSortMethod

Bases: steam.enums.base.SteamIntEnum

An enumeration.

Ascending = 1
Descending = 2
NONE = 0
class ELeaderboardDisplayType

Bases: steam.enums.base.SteamIntEnum

An enumeration.

NONE = 0
Numeric = 1
TimeMilliSeconds = 3
TimeSeconds = 2
name = ''

leaderboard name

id = 0

leaderboard id

entry_count = 0
data_request = 0

steam.enums.common.ELeaderboardDataRequest

app_id = 0
sort_method = 0

steam.enums.common.ELeaderboardSortMethod

display_type = 0

steam.enums.common.ELeaderboardDisplayType

get_entries(start=0, end=0, data_request=None, steam_ids=None)

Get leaderboard entries.

Parameters:
Returns:

a list of entries, see CMsgClientLBSGetLBEntriesResponse

Return type:

list

Raises:

LookupError on message timeout or error

get_iter(times, seconds, chunk_size=2000)

Make a iterator over the entries

See steam.util.throttle.ConstantRateLimit for times and seconds parameters.

Parameters:chunk_size (int) – number of entries per request
Returns:generator object
Return type:generator

The iterator essentially buffers chuck_size number of entries, and ensures we are not sending messages too fast. For example, the __iter__ method on this class uses get_iter(1, 1, 2000)

Game Servers

Listing and information about game servers through Steam

Filters

Note

Multiple filters can be joined to together (Eg. \app\730\white\1\empty\1)

Filter code What it does
\nor\[x] A special filter, specifies that servers matching any of the following [x] conditions should not be returned
\nand\[x] A special filter, specifies that servers matching all of the following [x] conditions should not be returned
\dedicated\1 Servers running dedicated
\secure\1 Servers using anti-cheat technology (VAC, but potentially others as well)
\gamedir\[mod] Servers running the specified modification (ex. cstrike)
\map\[map] Servers running the specified map (ex. cs_italy)
\linux\1 Servers running on a Linux platform
\password\0 Servers that are not password protected
\empty\1 Servers that are not empty
\full\1 Servers that are not full
\proxy\1 Servers that are spectator proxies
\appid\[appid] Servers that are running game [appid]
\napp\[appid] Servers that are NOT running game [appid] (This was introduced to block Left 4 Dead games from the Steam Server Browser)
\noplayers\1 Servers that are empty
\white\1 Servers that are whitelisted
\gametype\[tag,…] Servers with all of the given tag(s) in sv_tags
\gamedata\[tag,…] Servers with all of the given tag(s) in their ‘hidden’ tags (L4D2)
\gamedataor\[tag,…] Servers with any of the given tag(s) in their ‘hidden’ tags (L4D2)
\name_match\[hostname] Servers with their hostname matching [hostname] (can use * as a wildcard)
\version_match\[version] Servers running version [version] (can use * as a wildcard)
\collapse_addr_hash\1 Return only one server for each unique IP address matched
\gameaddr\[ip] Return only servers on the specified IP address (port supported and optional)
class steam.client.builtins.gameservers.GameServers(*args, **kwargs)

Bases: object

gameservers = None

instance of SteamGameServers

class steam.client.builtins.gameservers.SteamGameServers(steam)

Bases: object

query(filter_text, max_servers=10, timeout=30, **kw)

Query game servers

https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol

Note

When specifying filter_text use raw strings otherwise python won’t treat backslashes as literal characters (e.g. query(r'\appid\730\white\1'))

Parameters:
  • filter_text (str) – filter for servers
  • max_servers (int) – (optional) number of servers to return
  • timeout (int) – (optional) timeout for request in seconds
  • app_id (int) – (optional) app id
  • geo_location_ip (str) – (optional) ip (e.g. ‘1.2.3.4’)
Returns:

list of servers, see below. (None is returned steam doesn’t respond)

Return type:

list, None

Sample response:

[{'auth_players': 0, 'server_ip': '1.2.3.4', 'query_port': 27015},
 {'auth_players': 6, 'server_ip': '1:2:3:4::5', 'query_port': 27016},
 ...
]
get_server_list(filter_text, max_servers=10, timeout=20)

Get list of servers. Works similiarly to query(), but the response has more details.

Parameters:
  • filter_text (str) – filter for servers
  • max_servers (int) – (optional) number of servers to return
  • timeout (int) – (optional) timeout for request in seconds
Returns:

list of servers, see below. (None is returned steam doesn’t respond)

Return type:

list, None

Raises:

SteamError

Sample response:

[{'addr': '1.2.3.4:27067',
  'appid': 730,
  'bots': 0,
  'dedicated': True,
  'gamedir': 'csgo',
  'gameport': 27067,
  'gametype': 'valve_ds,empty,secure',
  'map': 'de_dust2',
  'max_players': 10,
  'name': 'Valve CS:GO Asia Server (srcdsXXX.XXX.XXX)',
  'os': 'l',
  'players': 0,
  'product': 'csgo',
  'region': 5,
  'secure': True,
  'steamid': SteamID(id=3279818759, type='AnonGameServer', universe='Public', instance=7011),
  'version': '1.35.4.0'}
]
get_ips_from_steamids(server_steam_ids, timeout=30)

Resolve IPs from SteamIDs

Parameters:
  • server_steam_ids (list) – a list of steamids
  • timeout (int) – (optional) timeout for request in seconds
Returns:

map of ips to steamids

Return type:

dict

Raises:

SteamError

Sample response:

{SteamID(id=123456, type='AnonGameServer', universe='Public', instance=1234): '1.2.3.4:27060'}
get_steamids_from_ips(server_ips, timeout=30)

Resolve SteamIDs from IPs

Parameters:
  • steam_ids (list) – a list of ips (e.g. ['1.2.3.4:27015',...])
  • timeout (int) – (optional) timeout for request in seconds
Returns:

map of steamids to ips

Return type:

dict

Raises:

SteamError

Sample response:

{'1.2.3.4:27060': SteamID(id=123456, type='AnonGameServer', universe='Public', instance=1234)}

Friends

class steam.client.builtins.friends.Friends(*args, **kwargs)

Bases: object

friends = None

SteamFriendlist instance

class steam.client.builtins.friends.SteamFriendlist(client, logger_name='SteamFriendList')

Bases: eventemitter.EventEmitter

SteamFriendlist is an object that keeps state of user’s friend list. It’s essentially a list of SteamUser. You can iterate over it, check if it contains a particular steam id, or get SteamUser for a steam id.

EVENT_READY = 'ready'

Friend list is ready for use

EVENT_FRIEND_INVITE = 'friend_invite'

New or existing friend invite

Parameters:user (SteamUser) – steam user instance
EVENT_FRIEND_NEW = 'friend_new'

Friendship established (after being accepted, or accepting)

Parameters:user (SteamUser) – steam user instance
EVENT_FRIEND_REMOVED = 'friend_removed'

No longer a friend (removed by either side)

Parameters:user (SteamUser) – steam user instance
EVENT_FRIEND_ADD_RESULT = 'friend_add_result'

Result response after adding a friend

Parameters:
ready = False

indicates whether friend list is ready for use

emit(event, *args)

Emit event with some arguments

Parameters:
  • event (any type) – event identifier
  • args – any or no arguments
add(steamid_or_accountname_or_email)

Add/Accept a steam user to be your friend. When someone sends you an invite, use this method to accept it.

Parameters:steamid_or_accountname_or_email (int, SteamID, SteamUser, str) – steamid, account name, or email

Note

Adding by email doesn’t not work. It’s only mentioned for the sake of completeness.

remove(steamid)

Remove a friend

Parameters:steamid (int, SteamID, SteamUser) – their steamid
block(steamid)

Block Steam user

Parameters:steamid (int, SteamID, SteamUser) – their steamid
Returns:result
Return type:EResult
unblock(steamid)

Unblock Steam user

Parameters:steamid (int, SteamID, SteamUser) – their steamid
Returns:result
Return type:EResult