Metadata-Version: 2.4
Name: stalcraft-api
Version: 2.0.1
Summary: stalcraft api unofficial python library
Author-email: onejeuu <mail@66rk.ru>
License-Expression: MIT
Project-URL: Homepage, https://github.com/onejeuu/stalcraft-api
Project-URL: Repository, https://github.com/onejeuu/stalcraft-api
Project-URL: Documentation, https://sc-api.readthedocs.io
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0.0,>=3.13.0
Requires-Dist: aiofiles<26.0.0,>=25.1.0
Requires-Dist: pydantic<3.0.0,>=2.12.0
Requires-Dist: strenum<1.0.0,>=0.4.0
Requires-Dist: cachetools<7.0.0,>=6.2.0
Dynamic: license-file

# scapi: Python Client for STALCRAFT API

<!-- Links -->

[pypi]: https://pypi.org/project/stalcraft-api
[license]: https://opensource.org/licenses/MIT
[tests]: https://github.com/onejeuu/stalcraft-api/actions/workflows/tests.yml
[issues]: https://github.com/onejeuu/stalcraft-api/issues
[docs]: https://sc-api.readthedocs.io
[docs-api]: https://sc-api.readthedocs.io/lib
[docs-guides]: https://sc-api.readthedocs.io/guides
[stalcraft-docs]: https://eapi.stalcraft.net
[stalcraft-app]: https://eapi.stalcraft.net/registration.html

<!-- Badges -->

[badge-pypi]: https://img.shields.io/pypi/v/stalcraft-api.svg
[badge-license]: https://img.shields.io/github/license/onejeuu/stalcraft-api
[badge-python]: https://img.shields.io/pypi/pyversions/stalcraft-api.svg
[badge-docs]: https://img.shields.io/readthedocs/sc-api
[badge-tests]: https://img.shields.io/github/actions/workflow/status/onejeuu/stalcraft-api/tests.yml?label=tests
[badge-issues]: https://img.shields.io/github/issues/onejeuu/stalcraft-api

[![PyPI][badge-pypi]][pypi] [![Python][badge-python]][pypi] [![License][badge-license]][license] [![Docs][badge-docs]][docs] [![Tests][badge-tests]][tests] [![Issues][badge-issues]][issues]

**scapi** is an unofficial asynchronous wrapper for **external [STALCRAFT API][stalcraft-docs]**.\
It provides access to read-only game endpoints including auction, emissions, clans, profiles, and etc.

## ✨ Features

- `AppClient` and `UserClient` for API requests
- `OAuthClient` for OAuth 2.0 authorization flows
- `DatabaseLookup` for items search
- Typed Pydantic model responses
- Configurable default parameters
- Rate limit information access

## 📌 Before You Start

To use the API, you must **[register an application][stalcraft-app]** and receive approval. Use **App tokens** for public resources or **User tokens** (via OAuth) for player-specific resources like character friends. Demo API is available at `https://dapi.stalcraft.net` for testing without registration.

## 🛠️ Installation

```bash
pip install stalcraft-api -U
```

## 🚀 Quick Start

```python
from scapi import AppClient, Region
import asyncio
import os

# Initialize app client with your credentials
client = AppClient(client_id=os.getenv("CLIENT_ID"), client_secret=os.getenv("CLIENT_SECRET"))

# OR use generated token from OAuthClient
client = AppClient(token=os.getenv("APP_TOKEN"))

async def main():
    # Get emission status for current region
    emission = await client.emission()
    print(f"Last emission ended at: {emission.previous_end}")

    # Get public character information
    profile = await client.profile("ZIV")
    print("Character profile:", profile)

    # Fetch last 3 auction lots for item with id "zyv9"
    lots = await client.auction("zyv9").lots(limit=3)
    print("Actual lots:", lots)

    # Other methods can be know in docs:
    # https://sc-api.rtfd.io

asyncio.run(main())
```

## 📚 Documentation

Complete documentation is available at **[sc-api.readthedocs.io][docs]**, including:

- [Guides][docs-guides]: clients, oauth, database lookup
- [Library API Reference][docs-api]
