ValvePython steam: talking to the Steam network from Python

Seven interfaces behind one import

ValvePython/steam is a Python module for interacting with the Steam network, published on PyPI as steam and hosted on Read the Docs. It is not a thin wrapper around one endpoint. The README lists seven distinct interfaces, and each one maps to a different part of Valve's infrastructure.

SteamClient handles communication with the Steam network itself and is built on gevent, which is why it is an optional extra. CDNClient gives access to Steam content depots, the servers games are downloaded from. WebAuth authenticates against store.steampowered.com and steamcommunity.com, the web front ends rather than the client protocol. WebAPI is a thin layer over the Steam Web API that populates the interface list automatically. SteamAuthenticator enables, disables and manages two factor authentication for an account, which is what generates the Steam Guard codes. SteamID converts between the various representations Valve uses for a player identifier. The Master Server Query Protocol support can query master servers directly or through a client.

The audience is a developer building tools around Steam: chat and inventory bots, server browsers, depot mirrors, account managers. The licence is MIT, the author is listed as Rossen Georgiev, and the README points to a separate command line project, steamctl, for people who want the same capabilities from a shell.

Installing the package and choosing the client extra

PyPI carries the release, and the choice is between the full package and the base one:

# with SteamClient dependecies
pip install -U "steam[client]"

# without (only when using parts that do no rely on gevent, and protobufs)
pip install -U steam

The comments in the README are worth reading as written. The base install omits gevent and the protobuf support, which is fine if you only need WebAuth, the Web API wrapper, SteamID conversion or the authenticator, and wrong if you intend to open a SteamClient connection or speak the client protocol.

For the newest version straight from the repository, the README gives a second form:

# cutting edge from master
pip install "git+https://github.com/ValvePython/steam#egg=steam"

# specific version tag (e.g. v1.0.0)
pip install "git+https://github.com/ValvePython/[email protected]#egg=steam[client]"
# without SteamClient extras
pip install "git+https://github.com/ValvePython/[email protected]#egg=steam"

Pinning a tag rather than tracking master is the saner choice for anything running in production, since master is where protocol changes land first.

What the dependency list says about the age of the code

The base requirements are declared in setup.py and are short:

install_requires = [
    'six>=1.10',
    'pycryptodomex>=3.7.0',
    'requests>=2.9.1',
    'urllib3<2',
    'vdf>=3.3',
    'cachetools>=3.0.0',
]

The client extra is where the weight is:

'client': [
    'gevent>=1.3.0',
    'protobuf~=3.0; python_version >= "3"',
    'protobuf<3.18.0; python_version < "3"',
    'gevent-eventemitter~=2.1',
],

Two details deserve attention. The urllib3 pin is urllib3<2, which is a direct consequence of the requests version the package supports, so a modern environment that has already moved to urllib3 2 will need an environment of its own. The protobuf pin is split on Python version, with a 3.18 ceiling on Python 2 only, and the requirement is protobuf~=3.0.

The README also states that the package supports Python 2.7+ and 3.4+, while the classifiers in setup.py list 2.7, 3.5 and 3.6. The gap between those two statements is the clearest signal of the project's vintage, and it is the first thing to check before committing to it in a new codebase.

The protobuf workflow that keeps the client protocol current

The Steam client protocol is defined by Valve in protobuf files, and the repository treats those files as something fetched rather than checked in. The Makefile exposes a four step workflow for that:

make pb_fetch   - fetch protobufs from SteamRE
make pb_compile - compile with protoc
make pb_clear   - removes *.proto
make pb_update  - pb_fetch + pb_compile

pb_fetch downloads from a list of URLs held in protobuf_list.txt, and the target renames the downloaded files, rewrites the syntax line to proto2 and renames the cc_generic_services option to py_generic_services with sed. pb_compile then runs protoc over the result. The repository also carries generate_enums_from_proto.py, which produces Python enums from the same definitions, and a recipes/ directory.

This is the mechanism that explains how a pure Python client keeps up with a protocol Valve changes without notice. It is also a maintenance obligation: the definitions are not vendored, so a client that has to run offline, or one that must reproduce a specific protocol state, depends on a fetch step that a Valve side change can break. The generated enums are then used across the package, and the Makefile also has a webauth_gen target that regenerates the recorded web authentication cassettes.

Testing with recorded cassettes and the local toolchain

The repository has a vcr/ directory, a tests/ directory, a tox.ini and a Makefile whose test target runs the suite with coverage:

test:
	coverage erase
	PYTHONHASHSEED=0 pytest --tb=short $(COVOPTS) tests

Recording is done through the VCR pattern, which captures real HTTP interactions and replays them in tests. That is how a package that talks to a login protected web service can have a test suite at all, and the webauth_gen target that regenerates those recordings is the hook for updating them when Valve changes the login flow.

The rest of the toolchain is conventional: make init installs the development requirements, make pylint runs the linter, make docs builds the Sphinx documentation, and make build runs all three in sequence. There is also a Vagrantfile that provisions an Ubuntu 16.04 virtual machine with virtualenv environments for Python 2 and Python 3, which is a dated but still working way to reproduce the supported version range.

The project also documents a manual test path using virtualenv, which is the route to take if you need to check behaviour on a version your current interpreter no longer supports.

The plain requests alternative and the steamctl tool

The Web API half of this package is a convenience, not a necessity. The store data and public Web API endpoints are ordinary HTTPS calls, and since requests is already a dependency of the package, a small script can talk to them without any of the Steam specific code. The difference is that the WebAPI class populates the interface list automatically and returns structured data, whereas direct calls mean handling the request shape yourself.

The protocol half is different. Talking to the Steam client network, serving depot content, or handling the authenticator requires the protobuf definitions, the gevent event loop and the shared key handling that Valve's client uses, and writing that from scratch is not a reasonable project. Here the package earns its keep, and the cost is a dependency on gevent plus a protocol that Valve can change at any time.

For shell users, the README points to steamctl, a separate command line project by the same organisation for the same capabilities without writing Python. For a one-off inspection of a profile or an inventory, that is the smaller commitment.

A last practical note on scope: this is an account and client protocol library, not a game server SDK. Server registration and Steamworks integration are a different set of interfaces, and the Master Server Query Protocol support here is for querying, not for hosting.

Editorial conclusion

The steam package suits Python projects that need to log into Steam, serve depot content or read store data without writing protocol code. It does not suit a fresh project that only needs the public Web API, where requests is enough. Before adopting it, check that your Python version is supported by the classifiers in setup.py, since the package still carries Python 2.7 entries.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. ValvePython/steam on GitHub