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

Warning

Disabled by Valve

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

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

An enumeration.

Friends = <ELeaderboardDataRequest.Friends: 2>¶

Global = <ELeaderboardDataRequest.Global: 0>¶

GlobalAroundUser = <ELeaderboardDataRequest.GlobalAroundUser: 1>¶

Users = <ELeaderboardDataRequest.Users: 3>¶

class SteamLeaderboard.ELeaderboardSortMethod¶

Bases: steam.enums.base.SteamIntEnum

An enumeration.

Ascending = <ELeaderboardSortMethod.Ascending: 1>¶

Descending = <ELeaderboardSortMethod.Descending: 2>¶

NONE = <ELeaderboardSortMethod.NONE: 0>¶

class SteamLeaderboard.ELeaderboardDisplayType¶

Bases: steam.enums.base.SteamIntEnum

An enumeration.

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:	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 :prop:`.ELeaderboardDataRequest.Users`
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¶

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, **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:	eresult (`EResult`) – result steam_id (`SteamID`) – steam id

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