Metadata-Version: 2.4
Name: rone-arena
Version: 1.0.0
Summary: Community Python SDK for the Rone Arena API
Author: ridwaanhall
License: BSD-3-Clause
Project-URL: Homepage, https://arena.rone.dev
Project-URL: Documentation, https://arena.rone.dev/api/docs
Project-URL: Repository, https://github.com/ridwaanhall/rone-arena-python
Project-URL: Issues, https://github.com/ridwaanhall/rone-arena-python/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.32.0
Dynamic: license-file

# Rone Arena Python SDK

`rone-arena` is the community Python SDK for the [Rone Arena API](https://arena.rone.dev) — an
unofficial, community-maintained data API for the game Mobile Legends: Bang Bang.

- Default base: `https://arena-hv.fastapicloud.dev/api` (high-volume host)
- Standard base: `https://arena.rone.dev/api`
- API docs: `https://arena.rone.dev/api/docs`
- Client groups: `academy`, `heroes`, `user`, `addon`

## Install

```bash
pip install rone-arena
```

## Quick Start

```python
from rone_arena import RoneArena

client = RoneArena()

heroes = client.heroes.heroes(size=5, index=1, order="desc", lang="en")
academy_roles = client.academy.roles(lang="en")
win_rate = client.addon.win_rate_calculator(match_now=100, wr_now=50, wr_future=60)

print(heroes)
print(academy_roles)
print(win_rate)
```

Every SDK method returns API JSON as a Python dictionary.

## Migrating from `OpenMLBB`

This package supersedes `OpenMLBB`, which was renamed so the project's own branding no longer
uses a trademark it does not own. The method surface is unchanged — only the install, the import,
the client class, and the hero namespace differ.

| Old | New |
| --- | --- |
| `pip install OpenMLBB` | `pip install rone-arena` |
| `from OpenMLBB import OpenMLBB` | `from rone_arena import RoneArena` |
| `OpenMLBB()` | `RoneArena()` |
| `OpenMLBBError` | `RoneArenaError` |
| `MlbbClient` | `HeroesClient` |
| `client.mlbb.heroes(...)` | `client.heroes.heroes(...)` |

The default base URL also moved from `openmlbb.fastapicloud.dev` to the renamed
high-volume host `arena-hv.fastapicloud.dev`.

Versioning restarted at `1.0.0` with the rebrand, so it now tracks the Rone Arena API rather than
continuing the MLBB-era 4.x line. `rone-arena 4.2.0` was a one-off first upload under the new name
and has been yanked; pin `rone-arena>=1.0.0`.

## Endpoint Coverage

The SDK follows the same route coverage as the API routers:

- `academy`: version, heroes, roles, equipment, spells, emblems, ranks, recommendations, ratings
- `heroes`: hero list, rank, positions, details, stats, combos, trends, relations, counters, compatibility
- `user`: auth, profile, stats, privacy, season, matches, hero matches, friends
- `addon`: win-rate calculator, IP lookup

See the interactive API docs at `https://arena.rone.dev/api/docs` for endpoint-by-endpoint details.

## Common Examples

```python
from rone_arena import RoneArena

client = RoneArena()

# academy
academy_version = client.academy.meta_version(size=20, index=1, order="desc", lang="en")

# heroes
hero_list = client.heroes.heroes(size=10, index=1, order="desc", lang="en")

# addon
wr_calc = client.addon.win_rate_calculator(match_now=100, wr_now=50, wr_future=60)

print(academy_version)
print(hero_list)
print(wr_calc)
```

## Handling downtime (HTTP 503)

The API returns `503` while it is in maintenance mode or shedding load, and names a host to try
instead. The SDK raises `ServiceUnavailableError` for that case, with the suggested host already
parsed out:

```python
from rone_arena import RoneArena, RoneArenaError, ServiceUnavailableError

client = RoneArena()

try:
    heroes = client.heroes.heroes(size=5)
except ServiceUnavailableError as exc:
    print(exc)                       # includes the alternative endpoint
    print(exc.status_code)           # 503
    if exc.alternative_endpoint:     # fail over to the host the API suggested
        client = RoneArena(base_url=f"{exc.alternative_endpoint}/api")
        heroes = client.heroes.heroes(size=5)
except RoneArenaError as exc:
    print("request failed:", exc)
```

`ServiceUnavailableError` subclasses `RoneArenaError`, so existing `except RoneArenaError` blocks
keep catching it. Order the handlers as above if you want to treat downtime specially.
`alternative_endpoint` is `None` when the response body does not name one.

## Pointing at a different host

The SDK defaults to the high-volume host. To use the standard host instead:

```python
client = RoneArena(base_url="https://arena.rone.dev/api", timeout=30)
```

## User-Agent

The default `User-Agent` is:

`RoneAI-RoneArena-Python-SDK`

You can override it by passing `user_agent=` to `RoneArena(...)`.

## Disclaimer

This is an unofficial, community-maintained project. It is not affiliated with, endorsed by,
sponsored by, or associated with Shanghai Moonton Technology Co., Ltd. "Mobile Legends: Bang Bang",
"MLBB", and all related names, marks, logos, and in-game assets are trademarks of their respective
owners. Data is sourced from publicly accessible endpoints and provided for informational,
educational, and analytical purposes only.

## License

BSD 3-Clause License.
