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

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=[], timeout=15)

Get product info for apps and packages

Parameters:
  • apps (list) – items in the list should be either just app_id, or (app_id, access_token)
  • packages (list) – items in the list should be either just package_id, or (package_id, access_token)
Returns:

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

Return type:

dict, None

{'apps':     {570: {...}, ...},
 'packages': {123: {...}, ...}
}
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_depot_key(depot_id, app_id=0)

Get depot decryption key

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

CMsgClientGetDepotDecryptionKeyResponse

Return type:

proto message

get_cdn_auth_token(app_id, hostname)

Get CDN authentication token

Parameters:
  • app_id (int) – app id
  • hostname (str) – cdn hostname
Returns:

CMsgClientGetCDNAuthTokenResponse

Return type:

proto message

get_product_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: 'token', ...},
 'packages': {456: 'token', ...}
}
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}

Account

class steam.client.builtins.account.Account(*args, **kwargs)

Bases: object

create_account(account_name, password, email='')

Create a new Steam account

Parameters:
  • account_name (str) – desired account name
  • password (str) – desired password
  • email (str) – desired email
Returns:

(EResult, SteamID)

Return type:

tuple

request_validation_mail()

Request validation email

Returns:result
Return type:EResult
request_password_change_mail(password)

Request password change mail

Parameters:password (str) – current account password
Returns:result
Return type:EResult
change_password(password, new_password, email_code)

Change account’s password

Parameters:
  • password (str) – current account password
  • new_password (str) – new account password
  • email_code (str) – confirmation code from email
Returns:

result

Return type:

EResult

Note

First request change mail via request_password_change_mail() to get the email code

change_email(password, email, code='')

Change account’s email address

Parameters:
  • password (str) – current account password
  • email (str) – new email address
  • code (str) – email code
Returns:

result

Return type:

EResult

Note

To change email, first call without code and then with, to finalize the change

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 = <EPersonaState.Online: 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/Offlane/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.

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

SteamUnifiedMessages provides a simply API to send and receive unified messages.

Example code:

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

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

# i know what im doing, alright?
message = client.unified_message.get('Player.GetGameBadgeLevels#1')
message.something = 1
response = client.unified_message.send_and_wait(message)
class steam.client.builtins.unified_messages.UnifiedMessages(*args, **kwargs)

Bases: object

unified_messages = None

instance of SteamUnifiedMessages

class steam.client.builtins.unified_messages.SteamUnifiedMessages(steam, logger_name=None)

Bases: eventemitter.EventEmitter

Simple API for send/recv of unified messages

Incoming messages are emitted as events once with their jobid and once with their method name (e.g. Player.GetGameBadgeLevels#1)

emit(event, *args)
get(method_name)

Get request proto instance for given methed name

Parameters:method_name (str) – name for the method (e.g. Player.GetGameBadgeLevels#1)
Returns:proto message instance, or None if not found
send(message, params=None)

Send service method request

Parameters:
  • message (str, proto message instance) – proto message instance (use SteamUnifiedMessages.get()) or method name (e.g. Player.GetGameBadgeLevels#1)
  • params (dict) – message parameters
Returns:

jobid event identifier

Return type:

str

Listen for jobid on this object to catch the response.

Note

If you listen for jobid on the client instance you will get the encapsulated message

send_and_wait(message, params=None, timeout=None, raises=False)

Send service method request and wait for response

Parameters:
  • message (str, proto message instance) – proto message instance (use SteamUnifiedMessages.get()) or 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 proto message instance

Return type:

proto message, None

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)

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

Friends = <ELeaderboardDataRequest.Friends: 2>
Global = <ELeaderboardDataRequest.Global: 0>
GlobalAroundUser = <ELeaderboardDataRequest.GlobalAroundUser: 1>
Users = <ELeaderboardDataRequest.Users: 3>
class SteamLeaderboard.ELeaderboardSortMethod

Bases: steam.enums.base.SteamIntEnum

Ascending = <ELeaderboardSortMethod.Ascending: 1>
Descending = <ELeaderboardSortMethod.Descending: 2>
NONE = <ELeaderboardSortMethod.NONE: 0>
class SteamLeaderboard.ELeaderboardDisplayType

Bases: steam.enums.base.SteamIntEnum

NONE = <ELeaderboardDisplayType.NONE: 0>
Numeric = <ELeaderboardDisplayType.Numeric: 1>
TimeMilliSeconds = <ELeaderboardDisplayType.TimeMilliSeconds: 3>
TimeSeconds = <ELeaderboardDisplayType.TimeSeconds: 2>
SteamLeaderboard.name = ''

leaderboard name

SteamLeaderboard.id = 0

leaderboard id

SteamLeaderboard.entry_count = 0
SteamLeaderboard.data_request = <ELeaderboardDataRequest.Global: 0>

steam.enums.common.ELeaderboardDataRequest

SteamLeaderboard.app_id = 0
SteamLeaderboard.sort_method = <ELeaderboardSortMethod.NONE: 0>

steam.enums.common.ELeaderboardSortMethod

SteamLeaderboard.display_type = <ELeaderboardDisplayType.NONE: 0>

steam.enums.common.ELeaderboardDisplayType

SteamLeaderboard.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

SteamLeaderboard.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

Game Servers related functionality

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, **kwargs)

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
  • 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', 'server_port': 27015},
 {'auth_players': 6, 'server_ip': '1.2.3.4', 'server_port': 27016},
 ...
]
get_server_list(filter_text, max_servers=10)

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
Returns:

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

Return type:

list, None

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_steamid(server_steam_ids)

Resolve IPs from SteamIDs

Parameters:server_steam_ids (list) – a list of steamids
Returns:map of ips to steamids
Return type:dict

Sample response:

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

Resolve SteamIDs from IPs

Parameters:steam_ids (list) – a list of ips (e.g. ['1.2.3.4:27015',...])
Returns:map of steamids to ips
Return type:dict

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