Metadata-Version: 2.4
Name: steam-game-query
Version: 1.0.0
Summary: Query detailed information for any Steam game - no login required
Project-URL: Homepage, https://github.com/carton/steam-query
Project-URL: Repository, https://github.com/carton/steam-query
Project-URL: Issues, https://github.com/carton/steam-query/issues
Author-email: Carton He <cartonhe@gmail.com>
Maintainer-email: Carton He <cartonhe@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,cli,games,gaming,steam
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: colorlog>=6.8.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Description-Content-Type: text/markdown

# Steam Query

Query detailed information for any game on the Steam store - no login required, no API key needed!

## Features

- 🔍 **Search Games** - Search the Steam store by game name
- 📋 **Detailed Info** - Get release date, developer, genres, ratings, and more
- 💰 **Price Info** - Display current price and discount information
- 💻 **Platform Support** - Show Windows/Mac/Linux support
- 📊 **Batch Queries** - Query multiple games at once
- 🎯 **Exact Match** - Direct query by App ID
- ⏱️ **Rate Limiting** - Built-in rate limiter, respects API rules
- 📄 **JSON Output** - Export results as JSON

## Quick Start

### Installation

```bash
# Clone repository
git clone https://github.com/carton/steam-query.git
cd steam-query

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Install with uv
pip install uv
uv pip install -e .

# Or with pip
pip install -e .
```

### Basic Usage

#### 1. Search Games

```bash
# Search games
steam-query search "Elden Ring"

# Limit results
steam-query search "Hollow Knight" -l 5

# Save search results
steam-query search "Stardew Valley" -o results.json
```

#### 2. Lookup Game Details

```bash
# Lookup by App ID
steam-query lookup 1245620

# Lookup by game name (auto-search)
steam-query lookup -q "Elden Ring"

# Query with specific country pricing
steam-query lookup 1245620 --country US
steam-query lookup 1245620 --country KR
steam-query lookup 1245620 --country JP

# JSON format output
steam-query lookup -q "Hollow Knight" --json

# Save details
steam-query lookup 1245620 -o elden-ring.json
```

#### 3. Batch Queries

```bash
# Query multiple games
steam-query batch "Elden Ring" "Hollow Knight" "Stardew Valley" -o results.json

# From text file (one game name per line)
steam-query batch -i games.txt -o results.json

# With specific country pricing
steam-query batch "Elden Ring" "Hollow Knight" -o results.json --country CN
```

## Output Example

```
🎮 ============================================================
  Elden Ring
🎮 ============================================================

📋 Basic Info:
   App ID:      1245620
   Release Date: 2022-02-25
   Free:        No
   Developer:  FromSoftware Inc.
   Publisher:  BANDAI NAMCO Entertainment Inc.
   Genres:     Action RPG, Adventure
   Metascore:  🟢 96/100

💻 Supported Platforms:
   • Windows
   • Steam Deck

💰 Price: 59.99 USD

📝 Description:
   A new action RPG developed by FromSoftware Inc. and BANDAI NAMCO...

🔗 Store Link: https://store.steampowered.com/app/1245620/
```


## Library Usage

You can also use `steam-query` as a Python library in your own projects!

### Quick Start

```python
from steam_query import SteamQuery

# Create client
client = SteamQuery(country_code="US")

# Search games
results = client.search("Elden Ring", limit=5)
for game in results:
    print(f"{game.name}: ${game.price.final if game.price else 'Free'}")

# Get game details
game = client.get(1245620)  # Elden Ring
print(f"{game.name}")
print(f"Genres: {', '.join(game.genres)}")
print(f"Metacritic: {game.metacritic_score}/100")

# Batch query
games = client.get_batch([1245620, 1091500, 1593500])
for app_id, game in games.items():
    print(f"{app_id}: {game.name}")

# Find first match
game = client.find("Hades")
if game:
    print(f"Found: {game.name}")
```

### Caching and Rate Limiting

The `SteamQuery` client includes built-in LRU cache with TTL, and supports custom rate limits:

```python
# Custom cache and rate limit settings
client = SteamQuery(
    cache_size=256,             # Cache up to 256 items
    cache_ttl=600,              # Cache for 10 minutes (600 seconds)
    requests_per_second=2.0,    # Allow 2 requests per second (default is 1.0)
)

# First call - hits API
game1 = client.get(1245620)

# Second call - hits cache (much faster!)
game2 = client.get(1245620)
```

### Error Handling

```python
from steam_query import SteamQuery
from steam_query.exceptions import GameNotFoundError, NetworkError, APIError

client = SteamQuery()

try:
    game = client.get(999999999)
except GameNotFoundError as e:
    print(f"Game not found: {e.app_id}")
except NetworkError as e:
    print(f"Network error: {e}")
except APIError as e:
    print(f"API error (status {e.status_code}): {e}")
```

### High-Level API Functions

For simple use cases, you can use the high-level functions:

```python
from steam_query import search_games, get_game_info, get_games_info

# Search games
results = search_games("Elden Ring", limit=3, requests_per_second=2.0)

# Get single game
game = get_game_info(1245620)
if game:
    print(f"{game.name}: {game.genres}")

# Get multiple games
games = get_games_info([1245620, 1091500, 1593500])
```

### Type Hints

The library includes complete type hints for better IDE support:

```python
from steam_query import SteamQuery, Game, SearchResult

client: SteamQuery = SteamQuery()
results: list[SearchResult] = client.search("Elden Ring")
game: Game = client.get(1245620)
```

## Configuration

### Country/Region Settings

Steam prices vary by region. You can specify which country's pricing to use:

**1. Command-line parameter (highest priority):**
```bash
steam-query lookup 1245620 --country US
steam-query search "Elden Ring" --country KR
```

**2. Environment variable:**
```bash
export STEAM_QUERY_COUNTRY=JP
steam-query lookup 1245620
```

**3. Config file:**
```bash
# Create config directory
mkdir -p ~/.steam-query

# Create config file
cat > ~/.steam-query/config.toml << EOF
[steam-query]
country = "US"
EOF
```

**Priority:** CLI parameter > Environment variable > Config file > Default (US)

**Supported country codes:** US, CN, KR, JP, GB, DE, FR, RU, BR, AU, CA, etc.
See [Steam Country Codes](https://partner.steamgames.com/doc/store/localization) for complete list.

### Environment Variables

```bash
# Set default country for pricing
export STEAM_QUERY_COUNTRY=US

# Set log level
export STEAM_QUERY_LOG_LEVEL=DEBUG
```

Default: 1 request/second (follows Steam recommendations)

You can modify in code:
```python
from steam_query import SteamStoreClient

client = SteamStoreClient(requests_per_second=2.0)  # 2 req/sec
```

## Project Structure

```
steam-query/
├── steam_query/
│   ├── __init__.py       # Package initialization
│   ├── steam_client.py   # Steam API client
│   └── cli.py           # Command-line interface
├── pyproject.toml        # Project configuration
└── README.md            # This file
```

## Use Cases

### Use Case 1: Find Game Release Date

```bash
steam-query lookup -q "Hollow Knight" --json | jq '.game.release_date'
```

### Use Case 2: Batch Query Game List

```bash
# Create game list
cat > games.txt << EOF
Elden Ring
Hollow Knight
Stardew Valley
Celeste
EOF

# Batch query
steam-query batch -i games.txt -o results.json
```

## Limitations

1. **Rate Limiting** - Steam Store API has no official rate limit, but 1 request/second is recommended
2. **Search Accuracy** - Uses Steam store search, may not always be exact
3. **Availability** - Depends on Steam store API availability

## API Reference

### SteamStoreClient

```python
from steam_query import SteamStoreClient

# Initialize with country/region settings
async with SteamStoreClient(country_code="US") as client:
    # Search games
    results = await client.search_games_by_name("Elden Ring", limit=10)

    # Get details
    game = await client.get_app_details(1245620)

    # Batch query
    games = await client.get_games_details_batch([1245620, 571860])

# Parameters:
# - requests_per_second: Rate limit (default: 1.0)
# - country_code: Country code for pricing (e.g., "US", "CN", "KR", "JP")
# - language: Language for results (default: "english")
```

### Configuration Priority

When calling `SteamStoreClient(country_code="...")`:

1. **Explicit parameter** - `SteamStoreClient(country_code="JP")`
2. **Environment variable** - `STEAM_QUERY_COUNTRY=US`
3. **Config file** - `~/.steam-query/config.toml`
4. **Default** - `US`

## Contributing

Issues and pull requests are welcome!

## License

MIT License
