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 idReturns: number of players Return type: int
,EResult
-
get_product_info
(apps=[], packages=[], timeout=15)¶ Get product info for apps and packages
Parameters: Returns: dict with
apps
andpackages
containing their info, see example belowReturn type: dict
,None
{'apps': {570: {...}, ...}, 'packages': {123: {...}, ...} }
When a token is needed to access the full info (e.g. branches and depots) the
_missing_token
will be set toTrue
. The token can be obtained by callingget_access_tokens()
if the account has a license.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] })
-
get_changes_since
(change_number, app_changes=True, package_changes=False)¶ Get changes since a change number
Parameters: Returns: Return type: proto message instance, or
None
on timeout
-
get_app_ticket
(app_id)¶ Get app ownership ticket
Parameters: app_id ( int
) – app idReturns: 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: Returns: 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: Returns: Return type: proto message
-
get_access_tokens
(app_ids=[], package_ids=[])¶ Get access tokens
Parameters: Returns: dict with
apps
andpackages
containing their access tokens, see example belowReturn type: dict
,None
{'apps': {123: 8888888886, ...}, 'packages': {456: 6666666666, ...} }
-
register_product_key
(key)¶ Register/Redeem a CD-Key
Parameters: key ( str
) – CD-KeyReturns: 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}
-
User¶
-
class
steam.client.builtins.user.
User
(*args, **kwargs)¶ Bases:
object
-
EVENT_CHAT_MESSAGE
= 'chat_message'¶ On new private chat message
Parameters:
-
persona_state
= 1¶ current persona state
-
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
- persona_state (
-
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
- steam_ids (
-
get_user
(steam_id, fetch_persona_state=True)¶ Get
SteamUser
instance forsteam id
Parameters: Returns: SteamUser instance
Return type:
-
games_played
(app_ids)¶ Set the apps being played by the user
Parameters: app_ids ( list
) – a list of application idsThese 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 integerThese 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 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 useNote
Auth cookies will only be send to
(help|store).steampowered.com
andsteamcommunity.com
domainsNote
The session is valid only while
SteamClient
instance is logged on.Parameters: language ( str
) – localization language for steam pagesReturns: 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: Returns: job_id
identifierReturn type: 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 ifFalse
returnNone
, else raisegevent.Timeout
Returns: response message
Return type: proto message instance
Raises: - method_name (
-
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: Returns: leaderboard instance
Return type: 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 alist
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¶
-
app_id
= 0¶
-
sort_method
= 0¶
-
display_type
= 0¶
-
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 isstart=1
) - end (
int
) – end entry, not index (e.g. only one entry thenstart=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: Raises: LookupError
on message timeout or error- start (
-
get_iter
(times, seconds, chunk_size=2000)¶ Make a iterator over the entries
See
steam.util.throttle.ConstantRateLimit
fortimes
andseconds
parameters.Parameters: chunk_size ( int
) – number of entries per requestReturns: 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 usesget_iter(1, 1, 2000)
-
class
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: 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, timeout=20)¶ Get list of servers. Works similiarly to
query()
, but the response has more details.Parameters: Returns: list of servers, see below. (
None
is returned steam doesn’t respond)Return type: list
,None
Raises: 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: Returns: map of ips to steamids
Return type: Raises: 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: Returns: map of steamids to ips
Return type: Raises: 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
ofSteamUser
. You can iterate over it, check if it contains a particularsteam id
, or getSteamUser
for asteam 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 emailNote
Adding by email doesn’t not work. It’s only mentioned for the sake of completeness.
-