Metadata-Version: 2.4
Name: pyearthmc
Version: 0.3.0
Summary: A complete and type-safe Python client for EMC (EarthMC Minecraft Server)
Author: RafaCabra
License-Expression: MIT
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.5
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.14
Project-URL: Repository, https://github.com/Rafacabra/pyearthmc
Description-Content-Type: text/markdown

```
 ____           ____             ____      
/\  _`\        /\  _`\   /'\_/`\/\  _`\    
\ \ \L\ \__  __\ \ \L\_\/\      \ \ \/\_\  
 \ \ ,__/\ \/\ \\ \  _\L\ \ \__\ \ \ \/_/_ 
  \ \ \/\ \ \_\ \\ \ \L\ \ \ \_/\ \ \ \L\ \
   \ \_\ \/`____ \\ \____/\ \_\\ \_\ \____/
    \/_/  `/___/> \\/___/  \/_/ \/_/\/___/ 
             /\___/                        
             \/__/                         
```

# PyEMC

A complete Python client for the [EarthMC](https://earthmc.net/)
Minecraft server API.

PyEMC models the raw EarthMC JSON endpoints as validated [Pydantic v2](https://docs.pydantic.dev/)
objects and wraps them behind an async HTTP client. You get autocompletion,
type checking, and data validation out of the box.

## Features

- **Type-safe:** Every request and response is a Pydantic v2 model. Typos and
  malformed payloads fail fast instead of silently breaking later.
- **Async:** Built on `httpx.AsyncClient` for concurrent requests.
- **Two request modes:** `overview` (a light `GET` returning a name/UUID list)
  and `detailed` (a `POST` returning full entity data).
- **Computed fields:** Extra data is generated on top of the raw API response
  (e.g. when the response arrived, and the current vote-party vote count).

## Requirements

- Python **3.14+**
- An internet connection to reach `https://api.earthmc.net`

## Installation

```bash
pip install pyearthmc
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add pyearthmc
```

## Quickstart

```python
import asyncio

import httpx

from pyearthmc import EmcClient


async def main():
    async with httpx.AsyncClient() as client:
        emc = EmcClient(client)

        server = await emc.get_server_info()
        print(server.version)
        print(server.voteParty.numVotes)


if __name__ == "__main__":
    asyncio.run(main())
```

## Usage

### Overview mode 

Returns a plain list of `NamedEntity` (`name` and `uuid`).

```python
towns = await emc.get_towns()                 # overview (default)
nations = await emc.get_nations()
players = await emc.get_players()
```

### Detailed mode (full data)

Provide a `NamedRequest` and the result is a full response.

```python
from pyearthmc.models.common import NamedRequest

town = await emc.get_towns(
    mode="detailed",
    town_request=NamedRequest(query=["Colombia"]),
)
print(town.towns[0].mayor.name)

player = await emc.get_players(
    mode="detailed",
    player_request=NamedRequest(query=["RafaCabra"]),
)
print(player.players[0].status.isOnline)
```

> **Note:** In `detailed` mode the query accepts either a name or a UUID, and a
> request body is required, otherwise a `ValueError` is raised.

## Contributing

Contributions are welcome! See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for
development setup and conventions.

## License

[MIT](./LICENSE)
