Skip to content

Contributing

Jump to bottom
cbyte edited this page Jul 19, 2026 · 1 revision

Contributing

Contributions welcome. This page covers the workflow for the H47R15 fork.

Setup

git clone https://github.com/H47R15/steam.git
cd steam

# Install the steam package with dev deps and the gevent client extra
# — using your Python 3.13.11+ environment.
poetry install --with dev --extras client

Running tests

Run from the repo root (where Setup leaves you):

poetry run pytest           # all tests, ~83 items, ~1s
poetry run pytest -k webauth
poetry run pytest tests/test_steamid.py
poetry run pytest --tb=short -q

No internet required — web-facing tests replay VCR cassettes from vcr/*.yaml in RecordMode.NONE.

Regenerating VCR cassettes

The webapi.yaml cassette pins a real Steam API response and needs a real key to refresh:

  1. Copy .env.example to .env and fill in STEAM_API_KEY. Get a key from steamcommunity.com/dev/apikey — the account needs a purchase history, Steam Guard, and a verified phone number.

  2. Follow the regen recipe at the top of tests/test_webapi.py — swap RecordMode.NONE for RecordMode.NEW_EPISODES, run the affected test, then revert.

The webauth_*.yaml cassettes need real credentials at run time. Regenerate them via tests/generete_webauth_vcr.py — run interactively when the anonymized replay drifts from live behavior.

Linting and type checking

poetry run pylint steam              # optional lint pass
poetry run pyright steam             # if you have pyright installed

VS Code's Pylance extension picks up [tool.pyright] from pyproject.toml — see Type Checking.

Commit style

Use imperative commit subjects (Fix …, Add …, Remove … — not "Fixed" or "Fixes"). We follow conventional commits loosely; the [tool.semantic_release] block in pyproject.toml recognises these tags:

  • feat: — new feature, triggers a minor bump.
  • fix: / perf: — bug fix / performance, triggers a patch bump.
  • BREAKING CHANGE: — major bump.
  • chore: / docs: / refactor: / style: / test: / ci: / build: — no version bump.

Examples:

fix: hexlify(None) crash when avatar URL is missing
feat: expose CDNClient.get_manifest_for_workshop_item
docs: add worked example for send_um_and_wait

Branch naming

Anything descriptive works — the fork doesn't enforce a strict prefix scheme. A useful convention:

  • fix/ for bug fixes.
  • feat/ for new features.
  • docs/ for documentation changes.
  • chore/ for tooling / config.

Example: feat/cdn-workshop-manifest, fix/webauth-cookie-iteration.

Pull requests

Open PRs against master on H47R15/steam. Include:

  • A one-line summary of the intent.
  • Before/after behaviour if it's a bug fix.
  • Any test coverage (or a note explaining why the change is untestable).
  • If touching protobufs, note whether you ran poetry run pb-update and whether any generated files changed.

Issue templates

.github/ISSUE_TEMPLATE/ has:

  • bug_report.md — for reproducible bugs.
  • feature_request.md — for new functionality.
  • config.yml — controls the "open a new issue" chooser page.

Both templates are lightweight — fill in what you can, delete what doesn't apply.

Adding a new proto file

If upstream Steam ships a new .proto you want to consume:

  1. Add its raw GitHub URL to protobuf_list.txt.
  2. Run poetry run pb-update.
  3. Verify the new _pb2.py / _pb2.pyi appear under steam/protobufs/.
  4. Run the test suite.
  5. Commit the .proto, the generated files, and any downstream additions to steam/enums/proto.py / steam/core/msg/unified.py.

Full workflow on Regenerating Protobufs.

Adding tests

Tests live at tests/. Unittest style is fine — pytest runs both.

VCR-recorded tests:

from vcr.record_mode import RecordMode
import vcr

test_vcr = vcr.VCR(
    record_mode=RecordMode.NONE,   # NEW_EPISODES when recording
    serializer='yaml',
    cassette_library_dir='vcr',
)

class TCwebapi(unittest.TestCase):
    @test_vcr.use_cassette('webapi.yaml')
    def test_something(self):
        ...

Bumping the version

Version is managed by python-semantic-release in CI — you don't hand-bump. Just write conventional-commit messages and the release job handles it.

If you need to bump manually for testing:

poetry run python-semantic-release version

Where to go next

H47R15/steam — maintained fork of ValvePython/steam. MIT licensed.

Clone this wiki locally