Metadata-Version: 2.4
Name: mcapitr
Version: 0.1.0
Summary: Official zero-dependency Python client for the MCAPI.TR Minecraft Server Status API
Author: MCAPI.TR
License: MIT
Project-URL: Homepage, https://mcapi.tr
Project-URL: Documentation, https://mcapi.tr/api-docs
Project-URL: OpenAPI, https://mcapi.tr/openapi.json
Project-URL: Issues, https://github.com/Rynix01/mcapitr/issues
Keywords: minecraft,minecraft-api,minecraft-server,server-status,java-edition,bedrock-edition,motd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MCAPI.TR Python SDK

The official, typed and zero-dependency Python client for the
[MCAPI.TR Minecraft Server Status API](https://mcapi.tr/api-docs).

It supports Minecraft Java, legacy Java and Bedrock servers, synchronous and
asynchronous applications, discovery endpoints, generated banners, icons and
embeddable widgets.

## Installation

```bash
pip install mcapitr
```

For local development:

```bash
pip install -e .
```

Python 3.9 or newer is required. The package has no runtime dependencies.

## Quick start

```python
from mcapitr import MCAPIClient

with MCAPIClient() as client:
    status = client.server_status("mc.hypixel.net")

print(status["online"])
if status.get("players"):
    print(status["players"]["online"])
```

Bedrock and legacy Java queries use explicit flags:

```python
bedrock = client.server_status("play.example.net:19132", bedrock=True)
legacy = client.server_status("old.example.net", legacy=True)
```

## Async usage

The async client provides the same API without blocking the event loop:

```python
import asyncio

from mcapitr import AsyncMCAPIClient


async def main() -> None:
    async with AsyncMCAPIClient() as client:
        status = await client.server_status("mc.hypixel.net")
        print(status["version"]["name"])


asyncio.run(main())
```

## Discovery and platform statistics

```python
with MCAPIClient() as client:
    first_page = client.trends(limit=20)
    statistics = client.stats()

    for server in first_page["data"]:
        print(server["address"], server["players_online"])

    if first_page["meta"].get("hasNext"):
        next_page = client.trends(
            limit=20,
            cursor=first_page["meta"]["nextCursor"],
        )
```

## Media URLs and downloads

URL helpers do not perform a network request:

```python
icon_url = client.server_icon_url("mc.hypixel.net", size=128, image_format="webp")
banner_url = client.server_banner_url("mc.hypixel.net", size="large")
widget_url = client.widget_url("mc.hypixel.net", size="large", theme="dark")
motd_url = client.motd_banner_url("&aWelcome to &bMy Server!")
```

The matching download methods return `bytes`:

```python
icon = client.server_icon("mc.hypixel.net", size=128)
with open("server-icon.png", "wb") as image_file:
    image_file.write(icon)
```

## Errors

HTTP and connection failures use dedicated exceptions:

```python
from mcapitr import MCAPIClient, RateLimitError, ServerNotFoundError

try:
    status = MCAPIClient().server_status("offline.example.net")
except ServerNotFoundError as error:
    print("Server is offline or unreachable:", error)
except RateLimitError as error:
    print("Retry after:", error.retry_after)
```

Available exception classes are `MCAPIError`, `NetworkError`, `APIError`,
`BadRequestError`, `ServerNotFoundError`, `RateLimitError` and
`ResponseDecodeError`.

## Client options

```python
client = MCAPIClient(
    base_url="https://mcapi.tr/api/v1",
    timeout=10.0,
    user_agent="my-discord-bot/1.0",
)
```

## Development

```bash
python -m unittest discover -s tests -v
python -m compileall -q src
```

## License

MIT

