Перейти к содержанию

Начало работы

Установка

Базовая (только синхронный клиент)

pip install steam-fetcher

С поддержкой async

pip install steam-fetcher[async]

Все опциональные зависимости

pip install steam-fetcher[all]

Включает: aiolimiter (async rate limiting), polars (Parquet-экспорт), sqlalchemy (SQL-экспорт), typer (CLI).

Обзор клиентов

steam-fetcher предоставляет четыре клиента:

Клиент Нужен API-ключ Sync/Async
SteamClient Нет Sync
AsyncSteamClient Нет Async
SteamAuthClient Да Sync
AsyncSteamAuthClient Да Async

Публичные клиенты (SteamClient, AsyncSteamClient) работают со Steam Store API — информация об играх, количество игроков, отзывы, поиск, статистика SteamSpy. API-ключ не требуется.

Клиенты с авторизацией (SteamAuthClient, AsyncSteamAuthClient) расширяют публичные клиенты эндпоинтами Steam Web API — профили пользователей, библиотеки игр, достижения. Требуется Steam Web API key.

Синхронный клиент

Все клиенты — контекстные менеджеры. Используйте with, чтобы HTTP-сессия корректно закрывалась:

from steam_fetcher import SteamClient

with SteamClient() as client:
    # Информация об игре
    game = client.get_game(730)
    if game:
        print(f"{game.name} — {game.type}")
        print(f"Бесплатная: {game.is_free}")
        print(f"Платформы: win={game.platforms.windows}, mac={game.platforms.mac}")

    # Текущее количество игроков
    players = client.get_player_count(730)
    if players:
        print(f"Онлайн: {players.player_count}")

    # Сводка по отзывам
    reviews = client.get_reviews(730)
    if reviews:
        print(f"Отзывы: {reviews.score_description} ({reviews.positive}/{reviews.total})")

    # Поиск в магазине
    results = client.search("portal")
    for entry in results.entries:
        print(f"  {entry.app_id}: {entry.name} — {entry.price}")

    # Статистика SteamSpy
    spy = client.get_steamspy_details(730)
    if spy:
        print(f"Владельцев: {spy.owners}, Пик CCU: {spy.peak_ccu}")

Все методы возвращают None, если запрашиваемый ресурс не найден (кроме search, который всегда возвращает SearchResult).

Асинхронный клиент

Асинхронный клиент имеет тот же API, но с async/await:

import asyncio
from steam_fetcher import AsyncSteamClient

async def main():
    async with AsyncSteamClient() as client:
        game = await client.get_game(730)
        players = await client.get_player_count(730)

        # Параллельная загрузка нескольких игр
        games = await asyncio.gather(
            client.get_game(730),
            client.get_game(570),
            client.get_game(440),
        )
        for g in games:
            if g:
                print(g.name)

asyncio.run(main())

Асинхронный клиент включает встроенный rate limiting (по умолчанию: 200 запросов/минуту). Настройка:

async with AsyncSteamClient(
    requests_per_minute=100,
    burst_size=5,
    time_period=60.0,
) as client:
    ...

Получение Steam Web API ключа

Некоторые эндпоинты (профили, библиотеки, достижения, друзья, баны и т.д.) требуют Steam Web API ключ.

  1. Перейдите на steamcommunity.com/dev/apikey
  2. Войдите в свой аккаунт Steam
  3. Введите любое доменное имя (например localhost)
  4. Нажмите Register
  5. Скопируйте ключ

Сохраните ключ в переменной окружения:

export STEAM_API_KEY=ваш_ключ

Ключ бесплатный и бессрочный. Rate limits общие для всех эндпоинтов Steam Web API.

Клиент с авторизацией

Для эндпоинтов, требующих Steam Web API key:

from steam_fetcher import SteamAuthClient

with SteamAuthClient(api_key="YOUR_STEAM_API_KEY") as client:
    # Профиль пользователя
    profile = client.get_user_profile("76561198000000000")
    if profile:
        print(f"{profile.username} ({profile.steam_id})")
        print(f"Страна: {profile.country_code}")
        print(f"Публичный: {profile.is_public}")

    # Библиотека игр
    library = client.get_user_library("76561198000000000")
    if library:
        print(f"Игр в библиотеке: {library.game_count}")
        for game in library.games[:5]:
            hours = game.playtime_forever / 60
            print(f"  {game.name}: {hours:.0f}ч")

    # Достижения
    achievements = client.get_user_achievements("76561198000000000", 730)
    if achievements:
        unlocked = sum(1 for a in achievements.achievements if a.achieved)
        print(f"Достижения: {unlocked}/{len(achievements.achievements)}")

API-ключ хранится как pydantic.SecretStr и не будет отображаться в логах или repr().

Асинхронная версия работает так же:

async with AsyncSteamAuthClient(api_key="YOUR_KEY") as client:
    profile = await client.get_user_profile("76561198000000000")

Настройка ретраев и таймаутов

Все клиенты принимают параметры retries и timeout:

with SteamClient(retries=5, timeout=30.0) as client:
    game = client.get_game(730)
  • retries (по умолчанию: 3) — количество повторных попыток с экспоненциальной задержкой
  • timeout (по умолчанию: 10.0) — таймаут запроса в секундах

Экспорт данных

steam-fetcher включает экспортеры для сохранения данных в файлы или базы данных:

from steam_fetcher import SteamClient
from steam_fetcher.exporters import JsonExporter, CsvExporter

with SteamClient() as client:
    game = client.get_game(730)

# JSON
JsonExporter().export([game], "games.json")

# CSV (вложенные поля сглаживаются)
CsvExporter().export([game], "games.csv")

Для Parquet и SQL установите соответствующие extras:

from steam_fetcher.exporters import ParquetExporter, SqlExporter

# Parquet (требуется: pip install steam-fetcher[parquet])
ParquetExporter(compression="zstd").export([game], "games.parquet")

# SQL (требуется: pip install steam-fetcher[sql])
SqlExporter(url="sqlite:///steam.db").export([game], "games")

Подробнее в разделе Экспортеры.

CLI

Установите CLI-зависимость:

pip install steam-fetcher[cli]

Использование:

# Информация об игре → JSON
steam-fetcher games details 730

# Поиск
steam-fetcher games search "half-life" --format csv --output results.csv

# Количество игроков
steam-fetcher games players 730

# Отзывы
steam-fetcher games reviews 730 --format json --output reviews.json

# Профиль пользователя (требуется API-ключ)
steam-fetcher users profile 76561198000000000 --api-key YOUR_KEY

# Библиотека игр
steam-fetcher users library 76561198000000000 --api-key YOUR_KEY

# Достижения
steam-fetcher users achievements 76561198000000000 730 --api-key YOUR_KEY

API-ключ также можно задать через переменную окружения STEAM_API_KEY:

export STEAM_API_KEY=your_key_here
steam-fetcher users profile 76561198000000000

Форматы вывода

Все команды, экспортирующие данные, поддерживают флаги --format (json, csv, parquet, sql) и --output:

steam-fetcher games details 730 --format csv --output game.csv
steam-fetcher games details 730 --format sql --output games_table --url sqlite:///steam.db