Skip to content

Commit da4d4d4

Browse files
ja7den2006ja7den2006
committed
Add release docs and packaging metadata
1 parent 4b2f460 commit da4d4d4

14 files changed

Lines changed: 1064 additions & 1 deletion

File tree

‎.github/workflows/tests.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: tests
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
9+
jobs:
10+
pytest:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
fail-fast: false
14+
matrix:
15+
python-version: ["3.8", "3.11", "3.12"]
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Set up Python
21+
uses: actions/setup-python@v5
22+
with:
23+
python-version: ${{ matrix.python-version }}
24+
25+
- name: Install package
26+
run: |
27+
python -m pip install --upgrade pip
28+
pip install -e .[dev]
29+
30+
- name: Run tests
31+
run: python -m pytest -q

‎.gitignore‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.pyo
4+
*.pyd
5+
.pytest_cache/
6+
.coverage
7+
htmlcov/
8+
.venv/
9+
venv/
10+
build/
11+
dist/
12+
*.egg-info/
13+
*.log
14+
*.tmp
15+
*.session
16+
*.cookies
17+
*.bundle.json
18+

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
MIT License
2+
3+
Copyright (c) 2026 jayden
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
22+

‎README.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# SteamCommunityKit
2+
3+
`SteamCommunityKit` is a Python library for real Steam user workflows:
4+
5+
- public Steam Web API reads with a normal `steamcommunity.com/dev` key
6+
- public no-key community reads such as profile XML, market data, inventory URLs, and group URLs
7+
- logged-in Steam Community actions such as profile edits, privacy updates, avatar upload, trade URL management, and group creation checks
8+
- session persistence helpers for refresh tokens, cookies, JSON bundles, and external `requests.Session` reuse
9+
10+
This package is built around the workflows normal users can actually use. It does not try to wrap Steamworks publisher-only administration endpoints that require partner permissions.
11+
12+
## Install
13+
14+
```bash
15+
pip install SteamCommunityKit
16+
```
17+
18+
For local development:
19+
20+
```bash
21+
pip install -e .[dev]
22+
```
23+
24+
## Choose The Right Mode
25+
26+
Use no key when you only need public community data:
27+
28+
```python
29+
from steamcommunitykit import SteamClient
30+
31+
client = SteamClient()
32+
print(client.resolve_steam_id("gaben"))
33+
print(client.get_player_summary("https://steamcommunity.com/id/gaben/"))
34+
print(client.get_market_price_overview(730, "AK-47 | Redline (Field-Tested)"))
35+
```
36+
37+
Use a normal Steam Web API key when you need Web API calls:
38+
39+
```python
40+
from steamcommunitykit import SteamClient
41+
42+
client = SteamClient(api_key="YOUR_WEB_API_KEY")
43+
summary = client.get_player_summary("gaben")
44+
games = client.get_owned_games_for_user("https://steamcommunity.com/id/gaben/")
45+
news = client.get_news_summary(570, count=2)
46+
47+
print(summary["personaname"])
48+
print(games["game_count"])
49+
print(news["items"][0]["title"])
50+
```
51+
52+
Use community login when you need account-backed actions:
53+
54+
```python
55+
from steamcommunitykit import SteamClient
56+
57+
client = SteamClient()
58+
client.login_to_community("YOUR_USERNAME", "YOUR_PASSWORD")
59+
60+
print(client.get_account_info())
61+
print(client.get_trade_offer_url())
62+
print(client.get_group_membership_state("Valve"))
63+
```
64+
65+
## Verified Workflow Examples
66+
67+
### Save and restore a logged-in session
68+
69+
```python
70+
from steamcommunitykit import SteamClient
71+
72+
client = SteamClient()
73+
client.login_to_community("YOUR_USERNAME", "YOUR_PASSWORD")
74+
client.save_community_session_bundle("steam_session.json")
75+
76+
restored = SteamClient()
77+
restored.load_community_session_bundle("steam_session.json")
78+
print(restored.get_community_session_state())
79+
```
80+
81+
### Reuse Steam Community auth with raw requests
82+
83+
```python
84+
from steamcommunitykit import SteamClient
85+
86+
client = SteamClient()
87+
client.login_to_community("YOUR_USERNAME", "YOUR_PASSWORD")
88+
89+
session = client.build_community_requests_session()
90+
response = session.get("https://steamcommunity.com/my/edit/")
91+
print(response.status_code)
92+
```
93+
94+
### Market snapshot from a full listing URL
95+
96+
```python
97+
from steamcommunitykit import SteamClient
98+
99+
client = SteamClient()
100+
snapshot = client.get_market_price_snapshot_by_url(
101+
"https://steamcommunity.com/market/listings/730/AK-47%20%7C%20Redline%20%28Field-Tested%29"
102+
)
103+
print(snapshot["price_overview"]["lowest_price"])
104+
print(snapshot["listing_summary"]["listing_count"])
105+
```
106+
107+
## Major Features
108+
109+
### Authentication and session management
110+
111+
- credential login with Steam Guard support
112+
- refresh-token login reuse
113+
- cookie string, cookie mapping, and JSON bundle import/export
114+
- file-based session save/load helpers
115+
- ready-to-use authenticated `requests.Session`
116+
117+
### Community account features
118+
119+
- account/profile bundle reads
120+
- profile edits for persona name, vanity URL, summary, real name, and location
121+
- privacy reads and writes
122+
- avatar upload
123+
- trade offer URL read/rotate
124+
- Web API key status page parsing
125+
126+
### Groups
127+
128+
- name, URL, and tag availability checks
129+
- group details, members, and multi-page member aggregation
130+
- group member summaries and indexed maps
131+
- group membership state parsing for the logged-in account
132+
- group creation with validation and clear limited-account errors
133+
134+
### Market
135+
136+
- search, normalized results, and exact-match helpers
137+
- price overview
138+
- listing summaries, maps, filtered lookups, and multi-page aggregation
139+
- item name ID, order histogram, order summary, and price history
140+
- one-shot market snapshots
141+
- full URL-based helper variants
142+
143+
### Inventory
144+
145+
- raw and normalized inventory reads
146+
- full pagination helpers
147+
- item search/filtering
148+
- item counts, asset ID lookup, and URL-based inventory helpers
149+
150+
### Workshop and collections
151+
152+
- published file detail helpers
153+
- collection details and child item helpers
154+
- query helpers with cursor pagination
155+
- normalized maps and exact-match finders
156+
- full workshop URL helper variants
157+
158+
### Web API reads
159+
160+
- users, friends, bans, owned games, recently played games, badges, levels
161+
- apps, news, user stats, trade/econ summaries, store searches, and utility endpoints
162+
163+
## Documentation
164+
165+
- [Authentication Guide](docs/authentication.md)
166+
- [Community Guide](docs/community.md)
167+
- [Groups Guide](docs/groups.md)
168+
- [Market Guide](docs/market.md)
169+
- [Inventory Guide](docs/inventory.md)
170+
- [Workshop Guide](docs/workshop.md)
171+
- [Web API Guide](docs/webapi.md)
172+
- [Testing Guide](docs/testing.md)
173+
- [Security Policy](SECURITY.md)
174+
175+
## Testing
176+
177+
Run the unit suite:
178+
179+
```bash
180+
python -m pytest -q
181+
```
182+
183+
Run the public smoke suite with an API key:
184+
185+
```bash
186+
python examples/smoke_test.py --api-key YOUR_WEB_API_KEY --public-only
187+
```
188+
189+
Run the community smoke suite with a Steam account:
190+
191+
```bash
192+
python examples/smoke_test.py --username YOUR_USERNAME --password YOUR_PASSWORD --community-only
193+
```
194+
195+
## Notes
196+
197+
- Some Web API features require a normal Steam Web API key.
198+
- Some community features require a logged-in session.
199+
- Some actions are restricted by Steam account state, such as limited accounts, Family View, or profile privacy.
200+
- When a feature requires more auth than the current client state provides, the package raises explicit `SteamAuthenticationError` or `SteamValidationError` messages instead of failing silently.
201+
202+
## Disclaimer
203+
204+
This project is not affiliated with Valve or Steam. Steam pages and response shapes can change over time, so some community-backed helpers may need maintenance if Steam updates its HTML or request flows.
205+

‎SECURITY.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
Security fixes are applied to the latest public version on `main`.
6+
7+
## Sensitive Data
8+
9+
SteamCommunityKit can work with:
10+
11+
- Steam usernames and passwords
12+
- Steam Guard codes
13+
- Steam Web API keys
14+
- refresh tokens
15+
- `steamLoginSecure` cookies
16+
- saved session bundle files
17+
18+
Treat all of those as secrets.
19+
20+
## Safe Usage Guidelines
21+
22+
- never commit session bundle files, cookie files, API keys, or credentials
23+
- prefer test accounts when exercising profile writes or group flows
24+
- rotate credentials if they are pasted into logs, terminals, or screenshots
25+
- store exported session files outside version-controlled directories when possible
26+
27+
The provided `.gitignore` covers common local artifacts, but it cannot protect secrets that are deliberately committed.
28+
29+
## Reporting A Vulnerability
30+
31+
If you discover a security issue in this repository:
32+
33+
1. do not open a public issue with live credentials or exploit details
34+
2. contact the maintainer privately first
35+
3. include a minimal reproduction, affected version, and impact summary
36+
37+
## Scope Notes
38+
39+
This library intentionally supports account-backed community flows. That means the biggest security risk is usually operational misuse rather than a remote code execution class issue.
40+
41+
Focus first on:
42+
43+
- credential leakage
44+
- cookie or refresh-token leakage
45+
- unsafe persistence of exported session bundles
46+
- missing validation around destructive account actions
47+

0 commit comments

Comments
 (0)