Welcome to python-valve’s documentation!¶

python-valve is a Python library which aims to provide the ability to interface with various Valve services and products, including: the Steam web API, locally installed Steam clients, Source servers and the Source master server.

Contents:

Interacting with Source Servers¶

Source provides the “A2S” protocol for querying game servers. This protocol is used by the Steam and in-game server browsers to list information about servers such as their name, player count and whether or not they’re password protected. valve.source.a2s provides a client implementation of A2S.

class valve.source.a2s.ServerQuerier(address, timeout=5.0)¶

Implements the A2S Source server query protocol.

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

Note

Instantiating this class creates a socket. Be sure to close the querier once finished with it. See valve.source.BaseQuerier.

info()¶

Retreive information about the server state

This returns the response from the server which implements __getitem__ for accessing response fields. For example:

with ServerQuerier(...) as server:
    print(server.info()["server_name"])

The following fields are available on the response:

Field	Description
response_type	Always `0x49`
server_name	The name of the server
map	The name of the map being ran by the server
folder	The gamedir if the modification being ran by the server. E.g. `tf`, `cstrike`, `csgo`.
game	A string identifying the game being ran by the server
app_id	The numeric application ID of the game ran by the server. Note that this is the app ID of the client, not the server. For example, for Team Fortress 2 `440` is returned instead of `232250` which is the ID of the server software.
player_count	Number of players currently connected. See `players()` for caveats about the accuracy of this field.
max_players	The number of player slots available. Note that `player_count` may exceed this value under certain circumstances. See `players()`.
bot_count	The number of AI players present
server_type	A `util.ServerType` instance representing the type of server. E.g. Dedicated, non-dedicated or Source TV relay.
platform	A `util.Platform` instances represneting the platform the server is running on. E.g. Windows, Linux or Mac OS X.
password_protected	Whether or not a password is required to connect to the server.
vac_enabled	Whether or not Valve anti-cheat (VAC) is enabled
version	The version string of the server software

Currently the extra data field (EDF) is not supported.

ping()¶

Ping the server, returning the round-trip latency in milliseconds

The A2A_PING request is deprecated so this actually sends a A2S_INFO request and times that. The time difference between the two should be negligble.

players()¶

Retrive a list of all players connected to the server

The following fields are available on the response:

Field	Description
response_type	Always `0x44`
player_count	The number of players listed
players	A list of player entries

The players field is a list that contains player_count number of messages.PlayerEntry instances which have the same interface as the top-level response object that is returned.

The following fields are available on each player entry:

Field	Description
name	The name of the player
score	Player’s score at the time of the request. What this relates to is dependant on the gamemode of the server.
duration	Number of seconds the player has been connected as a float

Note

Under certain circumstances, some servers may return a player list which contains empty name fields. This can lead to player_count being misleading.

Filtering out players with empty names may yield a more accurate enumeration of players:

with ServerQuerier(...) as query:
    players = []
    for player in query.players()["players"]:
        if player["name"]:
            players.append(player)
    player_count = len(players)

rules()¶

Retreive the server’s game mode configuration

This method allows you capture a subset of a server’s console variables (often referred to as ‘cvars’,) specifically those which have the FCVAR_NOTIFY flag set on them. These cvars are used to indicate game mode’s configuration, such as the gravity setting for the map or whether friendly fire is enabled or not.

The following fields are available on the response:

Field	Description
response_type	Always `0x56`
rule_count	The number of rules
rules	A dictionary mapping rule names to their corresponding string value

Example¶

In this example we will query a server, printing out it’s name and the number of players currently conected. Then we’ll print out all the players sorted score-decesending.

import valve.source.a2s

SERVER_ADDRESS = (..., ...)

with valve.source.a2s.ServerQuerier(SERVER_ADDRESS) as server:
    info = server.info()
    players = server.players()

print("{player_count}/{max_players} {server_name}".format(**info))
for player in sorted(players["players"],
                     key=lambda p: p["score"], reverse=True):
    print("{score} {name}".format(**player))

Queriers and Exceptions¶

Both valve.source.a2s.ServerQuerier and valve.source.master_server.MasterServerQuerier are based on a common querier interface. They also raise similar exceptions. All of these live in the valve.source module.

class valve.source.BaseQuerier(address, timeout=5.0)¶

Base class for implementing source server queriers.

When an instance of this class is initialised a socket is created. It’s important that, once a querier is to be discarded, the associated socket be closed via close(). For example:

querier = valve.source.BaseQuerier(('...', 27015))
try:
    querier.request(...)
finally:
    querier.close()

When server queriers are used as context managers, the socket will be cleaned up automatically. Hence it’s preferably to use the with statement over the try-finally pattern described above:

with valve.source.BaseQuerier(('...', 27015)) as querier:
    querier.request(...)

Once a querier has been closed, any attempts to make additional requests will result in a QuerierClosedError to be raised.

Variables:	host – Host requests will be sent to. port – Port number requests will be sent to. timeout – How long to wait for a response to a request.

close()¶

Close the querier’s socket.

It is safe to call this multiple times.

get_response()¶

Wait for a response to a request.

Raises:	NoResponseError – If the configured `timeout` is reached before a response is received. QuerierClosedError – If the querier has been closed.
Returns:	The raw response as a `bytes`.

request(*request)¶

Issue a request.

The given request segments will be encoded and combined to form the final message that is sent to the configured address.

Parameters:	request (valve.source.messages.Message) – Request message segments.
Raises:	QuerierClosedError – If the querier has been closed.

exception valve.source.NoResponseError¶: Raised when a server querier doesn’t receive a response.

exception valve.source.QuerierClosedError¶: Raised when attempting to use a querier after it’s closed.

Identifying Server Platforms¶

valve.source.util provides a handful of utility classes which are used when querying Source servers.

class valve.source.util.Platform(value)¶

A Source server platform identifier

This class provides utilities for representing Source server platforms as returned from a A2S_INFO request. Each platform is ultimately represented by one of the following integers:

ID	Platform
76	Linux
108	Linux
109	Mac OS X
111	Mac OS X
119	Windows

Note

Starbound uses 76 instead of 108 for Linux in the old GoldSource style.

__eq__(other)¶

Check for equality between two platforms

If other is not a Platform instance then an attempt is made to convert it to one using same approach as __init__(). This means platforms can be compared against integers and strings. For example:

>>>Platform(108) == "linux"
True
>>>Platform(109) == 109
True
>>>Platform(119) == "w"
True

Despite the fact there are two numerical identifers for Mac (109 and 111) comparing either of them together will yield True.

>>>Platform(109) == Platform(111)
True

__init__(value)¶

Initialise the platform identifier

The given value will be mapped to a numeric identifier. If the value is already an integer it must then it must exist in the table above else ValueError is returned.

If value is a one character long string then it’s ordinal value as given by ord() is used. Alternately the string can be either of the following:

Linux
Mac OS X
Windows

__weakref__¶: list of weak references to the object (if defined)

os_name¶: Convenience mapping to names returned by os.name

class valve.source.util.ServerType(value)¶

A Source server platform identifier

This class provides utilities for representing Source server types as returned from a A2S_INFO request. Each server type is ultimately represented by one of the following integers:

ID	Server type
68	Dedicated
100	Dedicated
108	Non-dedicated
112	SourceTV

Note

Starbound uses 68 instead of 100 for a dedicated server in the old GoldSource style.

__eq__(other)¶

Check for equality between two server types

If other is not a ServerType instance then an attempt is made to convert it to one using same approach as __init__(). This means server types can be compared against integers and strings. For example:

>>>Server(100) == "dedicated"
True
>>>Platform(108) == 108
True
>>>Platform(112) == "p"
True

__init__(value)¶

Initialise the server type identifier

The given value will be mapped to a numeric identifier. If the value is already an integer it must then it must exist in the table above else ValueError is returned.

If value is a one character long string then it’s ordinal value as given by ord() is used. Alternately the string can be either of the following:

Dedicated
Non-Dedicated
SourceTV

__weakref__¶: list of weak references to the object (if defined)

Querying the Source Master Server¶

When a Source server starts it can optionally add it self to an index of live servers to enable players to find the server via matchmaking and the in-game server browsers. It does this by registering it self with the “master server”. The master server is hosted by Valve but the protocol used to communicate with it is reasonably well documented.

Clients can request a list of server addresses from the master server for a particular region. Optionally, they can also specify a filtration criteria to restrict what servers are returned. valve.source.master_server provides an interface for interacting with the master server.

Note

Although “master server” is used in a singular context there are in fact multiple servers. By default valve.source.master_server.MasterServerQuerier will lookup hl2master.steampowered.com which, at the time of writing, has three A entries.

class valve.source.master_server.MasterServerQuerier(address=('hl2master.steampowered.com', 27011), timeout=10.0)¶

Implements the Source master server query protocol

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

Note

Instantiating this class creates a socket. Be sure to close the querier once finished with it. See valve.source.BaseQuerier.

__iter__()¶

An unfitlered iterator of all Source servers

This will issue a request for an unfiltered set of server addresses for each region. Addresses are received in batches but returning a completely unfiltered set will still take a long time and be prone to timeouts.

Note

If a request times out then the iterator will terminate early. Previous versions would propagate a NoResponseError.

See find() for making filtered requests.

find(region='all', duplicates=<Duplicates.SKIP: 'skip'>, **filters)¶

Find servers for a particular region and set of filtering rules

This returns an iterator which yields (host, port) server addresses from the master server.

region spcifies what regions to restrict the search to. It can either be a REGION_ constant or a string identifying the region. Alternately a list of the strings or REGION_ constants can be used for specifying multiple regions.

The following region identification strings are supported:

String	Region(s)
na-east	East North America
na-west	West North America
na	East North American, West North America
sa	South America
eu	Europe
as	Asia, the Middle East
oc	Oceania/Australia
af	Africa
rest	Unclassified servers
all	All of the above

Note

“rest” corresponds to all servers that don’t fit with any other region. What causes a server to be placed in this region by the master server isn’t entirely clear.

The region strings are not case sensitive. Specifying an invalid region identifier will raise a ValueError.

As well as region-based filtering, alternative filters are supported which are documented on the Valve developer wiki.

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

This method accepts keyword arguments which are used for building the filter string that is sent along with the request to the master server. Below is a list of all the valid keyword arguments:

Filter	Description
type	Server type, e.g. “dedicated”. This can be a `ServerType` instance or any value that can be converted to a `ServerType`.
secure	Servers using Valve anti-cheat (VAC). This should be a boolean.
gamedir	A string specifying the mod being ran by the server. For example: `tf`, `cstrike`, `csgo`, etc..
map	Which map the server is running.
linux	Servers running on Linux. Boolean.
empty	Servers which are not empty. Boolean.
full	Servers which are full. Boolean.
proxy	SourceTV relays only. Boolean.
napp	Servers not running the game specified by the given application ID. E.g. `440` would exclude all TF2 servers.
noplayers	Servers that are empty. Boolean
white	Whitelisted servers only. Boolean.
gametype	Server which match all the tags given. This should be set to a list of strings.
gamedata	Servers which match all the given hidden tags. Only applicable for L4D2 servers.
gamedataor	Servers which match any of the given hidden tags. Only applicable to L4D2 servers.

Note

Your mileage may vary with some of these filters. There’s no real guarantee that the servers returned by the master server will actually satisfy the filter. Because of this it’s advisable to explicitly check for compliance by querying each server individually. See valve.source.a2s.

The master server may return duplicate addresses. By default, these duplicates are excldued from the iterator returned by this method. See Duplicates for controller this behaviour.

class valve.source.master_server.Duplicates¶

Bases: enum.Enum

Behaviour for duplicate addresses.

These values are intended to be used with MasterServerQuerier.find() to control how duplicate addresses returned by the master server are treated.

Variables:	KEEP – All addresses are returned, even duplicates. SKIP – Skip duplicate addresses. STOP – Stop returning addresses when a duplicate is encountered.

Example¶

In this example we will list all unique European and Asian Team Fortress 2 servers running the map ctf_2fort.

import valve.source.master_server

with valve.source.master_server.MasterServerQuerier() as msq:
    servers = msq.find(
        region=["eu", "as"],
        duplicates="skip",
        gamedir="tf",
        map="ctf_2fort",
    )
    for host, port in servers:
        print "{0}:{1}".format(host, port)

SteamIDs¶

SteamID are used in many places within Valve services to identify entities such as users, groups and game servers. SteamIDs have many different representations which all need to be handled so the valve.steam.id module exists to provide an mechanism for representing these IDs in a usable fashion.

The `SteamID` Class¶

Rarely will you ever want to instantiate a SteamID directly. Instead it is best to use the SteamID.from_community_url() and SteamID.from_text() class methods for creating new instances.

class valve.steam.id.SteamID(account_number, instance, type, universe)¶

Represents a SteamID

A SteamID is broken up into four components: a 32 bit account number, a 20 bit “instance” identifier, a 4 bit account type and an 8 bit “universe” identifier.

There are 10 known accounts types as listed below. Generally you won’t encounter types other than “individual” and “group”.

Type	Numeric value	Can be mapped to URL	Constant
Invalid	0	No	`TYPE_INVALID`
Individual	1	Yes	`TYPE_INDIVIDUAL`
Multiseat	2	No	`TYPE_MULTISEAT`
Game server	3	No	`TYPE_GAME_SERVER`
Anonymous game server	4	No	`TYPE_ANON_GAME_SERVER`
Pending	5	No	`TYPE_PENDING`
Content server	6	No	`TYPE_CONTENT_SERVER`
Group	7	Yes	`TYPE_CLAN`
Chat	8	No	`TYPE_CHAT`
“P2P Super Seeder”	9	No	`TYPE_P2P_SUPER_SEEDER`
Anonymous user	10	No	`TYPE_ANON_USER`

TYPE_-prefixed constants are provided by the valve.steam.id module for the numerical values of each type.

All SteamIDs can be represented textually as well as by their numerical components. This is typically in the STEAM_X:Y:Z form where X, Y, Z are the “universe”, “instance” and the account number respectively. There are two special cases however. If the account type if invalid then “UNKNOWN” is the textual representation. Similarly “STEAM_ID_PENDING” is used when the type is pending.

As well as the the textual representation of SteamIDs there are also the 64 and 32 bit versions which contain the SteamID components encoded into integers of corresponding width. However the 32-bit representation also includes a letter to indicate account type.

__int__()¶

The 64 bit representation of the SteamID

64 bit SteamIDs are only valid for those with the type TYPE_INDIVIDUAL or TYPE_CLAN. For all other types SteamIDError will be raised.

The 64 bit representation is calculated by multiplying the account number by two then adding the “instance” and then adding another constant which varies based on the account type.

For TYPE_INDIVIDUAL the constant is 0x0110000100000000, whereas for TYPE_CLAN it’s 0x0170000000000000.

__str__()¶

The textual representation of the SteamID

This is in the STEAM_X:Y:Z form and can be parsed by from_text() to produce an equivalent instance. Alternately STEAM_ID_PENDING or UNKNOWN may be returned if the account type is TYPE_PENDING or TYPE_INVALID respectively.

Note

from_text() will still handle the STEAM_ID_PENDING and UNKNOWN cases.

__weakref__¶: list of weak references to the object (if defined)

as_32()¶

Returns the 32 bit community ID as a string

This is only applicable for TYPE_INDIVIDUAL, TYPE_CLAN and TYPE_CHAT types. For any other types, attempting to generate the 32-bit representation will result in a SteamIDError being raised.

as_64()¶

Returns the 64 bit representation as a string

This is only possible if the ID type is TYPE_INDIVIDUAL or TYPE_CLAN, otherwise SteamIDError is raised.

community_url(id64=True)¶

Returns the full URL to the Steam Community page for the SteamID

This can either be generate a URL from the 64 bit representation (the default) or the 32 bit one. Generating community URLs is only supported for IDs of type TYPE_INDIVIDUAL and TYPE_CLAN. Attempting to generate a URL for any other type will result in a SteamIDError being raised.

classmethod from_community_url(id, universe=0)¶

Parse a Steam community URL into a SteamID instance

This takes a Steam community URL for a profile or group and converts it to a SteamID. The type of the ID is infered from the type character in 32-bit community urls ([U:1:1] for example) or from the URL path (/profile or /groups) for 64-bit URLs.

As there is no way to determine the universe directly from URL it must be expliticly set, defaulting to UNIVERSE_INDIVIDUAL.

Raises SteamIDError if the URL cannot be parsed.

classmethod from_text(id, type=1)¶

Parse a SteamID in the STEAM_X:Y:Z form

Takes a teaxtual SteamID in the form STEAM_X:Y:Z and returns a corresponding SteamID instance. The X represents the account’s ‘universe,’ Z is the account number and Y is either 1 or 0.

As the account type cannot be directly inferred from the SteamID it must be explicitly specified, defaulting to TYPE_INDIVIDUAL.

The two special IDs STEAM_ID_PENDING and UNKNOWN are also handled returning SteamID instances with the appropriate types set (TYPE_PENDING and TYPE_INVALID respectively) and with all other components of the ID set to zero.

type_name¶: The account type as a string

Exceptions¶

exception valve.steam.id.SteamIDError¶

Bases: ValueError

Raised when parsing or building invalid SteamIDs

Useful Constants¶

As well as providing the SteamID class, the valve.steam.id module also contains numerous constants which relate to the contituent parts of a SteamID. These constants map to their numeric equivalent.

Account Types¶

The following are the various account types that can be encoded into a SteamID. Many of them are seemingly no longer in use – at least not in public facing services – and you’re only likely to come across TYPE_INDIVIDUAL, TYPE_CLAN and possibly TYPE_GAME_SERVER.

valve.steam.id.TYPE_INVALID = 0¶