Metadata-Version: 2.4
Name: blizzardapi2
Version: 2.1.3
Summary: A Python wrapper for Blizzard API
Author-email: lostcol0ny <c098os0k@4wrd.cc>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.32.3
Requires-Dist: black<25.0.0,>=24.4.2
Requires-Dist: pytest<9.0.0,>=8.2.2
Requires-Dist: pytest-mock<4.0.0,>=3.14.0
Requires-Dist: ruff<1.0.0,>=0.3.0
Requires-Dist: pydantic>=2.11.6
Requires-Dist: aiohttp>=3.12.12
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.2.2; extra == "dev"
Requires-Dist: pytest-mock<4.0.0,>=3.14.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0.0,>=0.23.5; extra == "dev"
Requires-Dist: black<25.0.0,>=24.4.2; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.3.0; extra == "dev"
Dynamic: license-file

# Blizzard API 2

[![PyPI version](https://badge.fury.io/py/blizzardapi2.svg)](https://badge.fury.io/py/blizzardapi2)
[![Python Versions](https://img.shields.io/pypi/pyversions/blizzardapi2.svg)](https://pypi.org/project/blizzardapi2/)
[![Downloads](https://img.shields.io/pypi/dm/blizzardapi2.svg)](https://pypi.org/project/blizzardapi2/)
[![Build Status](https://github.com/lostcol0ny/python-blizzardapi2/actions/workflows/python-package.yml/badge.svg)](https://github.com/lostcol0ny/python-blizzardapi2/actions/workflows/python-package.yml)

![GitHub](https://img.shields.io/github/license/lostcol0ny/python-blizzardapi2)[![Dependabot](https://github.com/lostcol0ny/blizzardapi2/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/lostcol0ny/blizzardapi2/actions/workflows/dependabot/dependabot-updates)[![CodeQL](https://github.com/lostcol0ny/python-blizzardapi2/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/lostcol0ny/python-blizzardapi2/actions/workflows/github-code-scanning/codeql)[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

blizzardapi2 is a client library for Blizzard's APIs. It's a fork of [the original library](https://github.com/trevorphillipscoding/python-blizzardapi/).

Current supported features include:

- Battle.net User
- WoW Profile
- WoW Game Data
- WoW Classic Game Data
- Diablo 3 Community
- Diablo 3 Game Data
- Hearthstone Game Data
- Starcraft 2 Community
- Starcraft 2 Game Data

Modern features:

- Full type hints support
- Async/await support for better performance
- Enum-based region and locale validation
- Structured response types using dataclasses
- Improved error handling and logging

To gain access to Blizzard's API please register [here](https://develop.battle.net/access/) to obtain a client id and client secret.

For more information on Blizzard's API visit:

[Official Documentation](https://develop.battle.net/documentation)  
[Official API Forum](https://us.forums.blizzard.com/en/blizzard/c/api-discussion)

# Requirements

Python (3.11+)

# Installing

`pip install blizzardapi2`

# Examples

**Basic Usage**

```python
from blizzardapi2 import BlizzardApi
from blizzardapi2.wow.wow_profile_api import Region, Locale

api_client = BlizzardApi("client_id", "client_secret")

# Unprotected API endpoint
categories_index = api_client.wow.game_data.get_achievement_categories_index(
    Region.US,
    Locale.EN_US
)

# Protected API endpoint
summary = api_client.wow.profile.get_account_profile_summary(
    Region.US,
    Locale.EN_US,
    "access_token"
)

# Wow Classic endpoint
connected_realms_index = api_client.wow.game_data.get_connected_realms_index(
    Region.US,
    Locale.EN_US,
    is_classic=True
)
```

**Async Usage**

```python
import asyncio
from blizzardapi2 import BlizzardApi
from blizzardapi2.wow.wow_profile_api import Region, Locale

async def main():
    api_client = BlizzardApi("client_id", "client_secret")

    # Async API calls
    profile = await api_client.wow.profile.get_account_profile_summary(
        Region.US,
        Locale.EN_US,
        "access_token"
    )

    # Multiple concurrent requests
    tasks = [
        api_client.wow.profile.get_character_profile_summary(
            Region.US,
            Locale.EN_US,
            "realm-slug",
            "character-name"
        ),
        api_client.wow.profile.get_character_achievements_summary(
            Region.US,
            Locale.EN_US,
            "realm-slug",
            "character-name"
        )
    ]
    results = await asyncio.gather(*tasks)

asyncio.run(main())
```

# Access token vs Client ID/Client Secret

You can pass in a `client_id` and `client_secret` and use almost any endpoint except for a few that require an `access_token` obtained via OAuth authorization code flow. You can find more information at https://develop.battle.net/documentation/guides/using-oauth/authorization-code-flow.

Here is the list of endpoints, specified by Blizzard, that require an OAuth token:

```
GET /oauth/userinfo
GET /profile/user/wow
GET /profile/user/wow/protected-character/{realm-id}-{character-id}
GET /profile/user/wow/collections
GET /profile/user/wow/collections/pets
GET /profile/user/wow/collections/mounts
```

# Documentation

For detailed documentation on each game's API, see the following README files:

- [WoW API Documentation](docs/wow/README.md)
- [Diablo 3 API Documentation](docs/diablo3/README.md)
- [Hearthstone API Documentation](docs/hearthstone/README.md)
- [Starcraft 2 API Documentation](docs/starcraft2/README.md)
