Metadata-Version: 2.4
Name: SteamCommunityKit
Version: 0.1.1
Summary: A professional Python client for Steam Web API and Steam Community flows.
Author: jayden
License: MIT
Project-URL: Homepage, https://github.com/SteamCommunityKit/SteamCommunityKit
Project-URL: Repository, https://github.com/SteamCommunityKit/SteamCommunityKit
Project-URL: Issues, https://github.com/SteamCommunityKit/SteamCommunityKit/issues
Project-URL: Documentation, https://github.com/SteamCommunityKit/SteamCommunityKit/tree/main/docs
Keywords: steam,steamcommunity,steam-api,steam-web-api,steam-market,steam-workshop
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rsa>=4.9
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Dynamic: license-file

# SteamCommunityKit

[![PyPI version](https://img.shields.io/pypi/v/SteamCommunityKit.svg)](https://pypi.org/project/SteamCommunityKit/)
[![Python versions](https://img.shields.io/pypi/pyversions/SteamCommunityKit.svg)](https://pypi.org/project/SteamCommunityKit/)
[![License](https://img.shields.io/pypi/l/SteamCommunityKit.svg)](LICENSE)

`SteamCommunityKit` is a Python client for real Steam user workflows. It covers public Steam Web API reads, no-key Steam Community reads, and authenticated community actions such as profile management, privacy updates, trade URL helpers, market lookups, inventory helpers, and group workflows.

The library is built around features normal users can actually access. It intentionally avoids Steamworks publisher-only administration endpoints that require partner permissions.

## Installation

Install from PyPI:

```bash
python -m pip install SteamCommunityKit
```

Upgrade an existing installation:

```bash
python -m pip install --upgrade SteamCommunityKit
```

Install from a local checkout for development:

```bash
python -m pip install -e .[dev]
```

Python `3.8+` is supported.

## Quick Start

Use the client without login or API keys for public community data:

```python
from steamcommunitykit import SteamClient

client = SteamClient()

steam_id = client.resolve_steam_id("gaben")
summary = client.get_player_summary("https://steamcommunity.com/id/gaben/")
price = client.get_market_price_overview(730, "AK-47 | Redline (Field-Tested)")

print(steam_id)
print(summary["personaname"])
print(price["lowest_price"])
```

Provide a normal `steamcommunity.com/dev` key when you need Web API methods:

```python
from steamcommunitykit import SteamClient

client = SteamClient(api_key="YOUR_WEB_API_KEY")

summary = client.get_player_summary("gaben")
games = client.get_owned_games_for_user("https://steamcommunity.com/id/gaben/")
news = client.get_news_summary(570, count=2)

print(summary["personaname"])
print(games.get("game_count"))
print(news["items"][0]["title"])
```

Login only when you need account-backed community actions:

```python
from steamcommunitykit import SteamClient

client = SteamClient()
client.login_to_community("YOUR_USERNAME", "YOUR_PASSWORD")

print(client.get_account_info())
print(client.get_trade_offer_url())
print(client.get_group_membership_state("Valve"))
```

If Steam Guard is required, interactive terminal logins prompt automatically. For non-interactive environments, you can still pass a `steam_guard_code` explicitly.

## Common Workflows

Save and restore a logged-in community session:

```python
from steamcommunitykit import SteamClient

client = SteamClient()
client.login_to_community("YOUR_USERNAME", "YOUR_PASSWORD")
client.save_community_session_bundle("steam_session.json")

restored = SteamClient()
restored.load_community_session_bundle("steam_session.json")
print(restored.get_community_session_state())
```

Reuse the authenticated session with raw `requests` calls:

```python
from steamcommunitykit import SteamClient

client = SteamClient()
client.login_to_community("YOUR_USERNAME", "YOUR_PASSWORD")

session = client.build_community_requests_session()
response = session.get("https://steamcommunity.com/my/edit/")
print(response.status_code)
```

Build a market snapshot from a full listing URL:

```python
from steamcommunitykit import SteamClient

client = SteamClient()
snapshot = client.get_market_price_snapshot_by_url(
    "https://steamcommunity.com/market/listings/730/AK-47%20%7C%20Redline%20%28Field-Tested%29"
)

print(snapshot["price_overview"]["lowest_price"])
print(snapshot["listing_summary"]["listing_count"])
```

## Feature Overview

### Authentication and sessions

- Username and password login with Steam Guard support
- Refresh-token reuse helpers
- Cookie string, cookie dict, and JSON session import/export
- File-based session save and restore helpers
- Authenticated `requests.Session` handoff for custom workflows

### Community account tools

- Account and profile state reads
- Profile edits for persona name, vanity URL, summary, real name, and location
- Privacy reads and updates
- Avatar upload
- Trade offer URL read and rotation helpers
- Web API key status parsing

### Groups

- Group name, URL, and tag availability checks
- Group detail and member reads
- Multi-page member aggregation helpers
- Logged-in membership state parsing
- Group creation with validation and limited-account error handling

### Market

- Market search and exact-match helpers
- Price overview and listing summaries
- Item name ID, order histogram, order summary, and price history
- Multi-page aggregation helpers
- Full URL-based helper variants

### Inventory

- Raw and normalized inventory reads
- Pagination helpers
- Item search and filtering helpers
- Asset ID lookups and URL-based inventory helpers

### Workshop and collections

- Published file detail helpers
- Collection detail and child item helpers
- Query helpers with cursor pagination
- Exact-match and normalized map helpers

### Steam Web API

- Users, friends, bans, badges, and levels
- Owned games and recently played games
- App, news, and utility endpoints
- Trade and econ summary helpers that work with normal user-accessible keys

## Documentation

- [Installation Guide](docs/installation.md)
- [Authentication Guide](docs/authentication.md)
- [Community Guide](docs/community.md)
- [Groups Guide](docs/groups.md)
- [Market Guide](docs/market.md)
- [Inventory Guide](docs/inventory.md)
- [Workshop Guide](docs/workshop.md)
- [Web API Guide](docs/webapi.md)
- [Testing Guide](docs/testing.md)
- [Security Policy](SECURITY.md)

## Testing

Run the unit suite:

```bash
python -m pytest -q
```

Run public smoke tests with an API key:

```bash
python examples/smoke_test.py --api-key YOUR_WEB_API_KEY --public-only
```

Run community smoke tests with a Steam account:

```bash
python examples/smoke_test.py --username YOUR_USERNAME --password YOUR_PASSWORD --community-only
```

## Notes

- Web API methods require a normal Steam Web API key from `steamcommunity.com/dev`.
- Community write actions require a logged-in Steam session.
- Some actions depend on Steam account state, including limited accounts, Family View, and privacy restrictions.
- When authentication or input requirements are missing, the library raises explicit errors instead of silently failing.

## Disclaimer

This project is not affiliated with Valve or Steam. Steam pages and community response shapes can change over time, so community-backed helpers may require maintenance when Steam updates its web flows.
