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:	steam_ids (`list`) – list of steam ids state_flags (`EClientPersonaStateFlag`) – client state flags

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:	start (`int`) – start entry, not index (e.g. rank 1 is `start=1`) end (`int`) – end entry, not index (e.g. only one entry then `start=1,end=1`) data_request (`steam.enums.common.ELeaderboardDataRequest`) – data being requested steam_ids – list of steam ids when using `ELeaderboardDataRequest.Users`
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:	eresult (`EResult`) – result steam_id (`SteamID`) – steam id

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`