pyearthmc 0.2.0__tar.gz

pyearthmc-0.2.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: pyearthmc
+Version: 0.2.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
+Description-Content-Type: text/markdown
+
+# 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)

pyearthmc-0.2.0/README.md

@@ -0,0 +1,102 @@
+# 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)

pyearthmc-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "pyearthmc"
+version = "0.2.0"
+description = "A complete and type-safe Python client for EMC (EarthMC Minecraft Server)"
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+    "rich>=15.0.0",
+]
+
+[[project.authors]]
+name = "RafaCabra"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.16",
+    "pyright>=1.1.0",
+    "pytest>=8.0",
+    "pytest-asyncio>=1.0",
+    "pyfiglet>=1.0.4",
+    "ruff>=0.11",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.14"
+files = ["src"]
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py314"
+line-length = 160
+src = [
+    "src",
+    "tests",
+    "examples",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"

pyearthmc-0.2.0/pyproject.toml.orig

@@ -0,0 +1,48 @@
+[project]
+name = "pyearthmc"
+version = "0.2.0"
+description = "A complete and type-safe Python client for EMC (EarthMC Minecraft Server)"
+license = "MIT"
+readme = "README.md"
+authors = [
+    { name = "RafaCabra" },
+]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+    "rich>=15.0.0",
+]
+
+
+[dependency-groups]
+dev = [
+    "mypy>=1.16",
+    "pyright>=1.1.0",
+    "pytest>=8.0",
+    "pytest-asyncio>=1.0",
+    "pyfiglet>=1.0.4",
+    "ruff>=0.11",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+
+[tool.mypy]
+python_version = "3.14"
+files = ["src"]
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py314"
+line-length = 160
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"

pyearthmc-0.2.0/src/pyearthmc/__init__.py

@@ -0,0 +1,6 @@
+
+from .client import EmcClient
+
+__version__ = "0.2.0"
+
+__all__ = ["EmcClient", "__version__"]

pyearthmc-0.2.0/src/pyearthmc/client.py

@@ -0,0 +1,288 @@
+
+from typing import Literal, overload
+
+import httpx
+from rich.progress import track
+
+from pyearthmc.models.common import NamedEntity, NamedRequest, RequestMode
+from pyearthmc.models.nations import Nation, NationResponse
+from pyearthmc.models.players import Player, PlayerResponse
+from pyearthmc.models.server import ServerResponse
+from pyearthmc.models.towns import Town, TownResponse
+
+
+class EmcClient:
+    """
+    Main client for interacting with the EarthMC API.
+    It coordinates requests and responses.
+    All the requests begin with `get_` and return a response model.
+    Every single request and response is handled via pydantic models
+    providing type safety and validation. Feel free to check the docs for each function
+    and the models to know exactly what each response contains.
+
+    Args:
+        client (httpx.AsyncClient): The async HTTP client to use for requests.
+
+    Examples:
+        ```python
+        with httpx.AsyncClient() as client:
+            emc_client = EmcClient(client)
+        ```
+
+    Notes:
+        recommended to use `async with EmcClient(httpx.AsyncClient()) as client:`
+
+        As always, contributions will be appreciated, even if only to improve the documentation.
+    """
+
+
+    def __init__(self, client: httpx.AsyncClient | None = None):
+        if client is None:
+            client = httpx.AsyncClient()
+        self.client: httpx.AsyncClient = client
+
+    async def get_server_info(self) -> ServerResponse:
+        """
+        Examples:
+            ```python
+            with httpx.AsyncClient() as client:
+                emc_client = EmcClient(client)
+                server_info = await emc_client.get_server_info()
+                print(server_info)
+            ```
+
+        Get the core server information.
+        It includes the server version, moon phase, timestamps, status, stats and voteparty status.
+        Check the API documentation for more details.
+
+        Args:
+            None
+
+        Note:
+            Replaces a GET request to https://api.earthmc.net/v4/
+
+        Returns:
+            ServerResponse: The server information including voteparty status, version and others.
+        """
+
+        response = await self.client.get("https://api.earthmc.net/v4/")
+
+        if response.status_code != 200:
+            raise httpx.HTTPStatusError(f"Unexpected status code: {response.status_code, response.text}", request=response.request, response=response)
+
+
+        return ServerResponse.model_validate(response.json())
+
+    @overload
+    async def get_towns(self, mode: Literal["overview"] = "overview", town_request: None = None) -> list[NamedEntity]: ...
+
+    @overload
+    async def get_towns(self, mode: Literal["detailed"], town_request: NamedRequest | None = None) -> TownResponse: ...
+
+    async def get_towns(self, mode: RequestMode = "overview", town_request: NamedRequest | None = None) -> list[NamedEntity] | TownResponse:  # type: ignore[misc]
+        """
+        Get information about towns in the server.
+        Depends on the request mode. If you want to query a specific town,
+        use 'detailed' mode and provide the town request parameters.
+        You can provide either the town name or UUID.
+
+        Note:
+            The 'overview' mode replaces a GET request to https://api.earthmc.net/v4/towns.
+            The 'detailed' mode replaces a POST request to https://api.earthmc.net/v4/towns.
+
+        Args:
+            mode (RequestMode): The request mode, either 'overview' or 'detailed'.
+            town_request (NamedRequest | None): The town request parameters, if mode is 'detailed'.
+
+        Returns:
+            list[NamedEntity] | TownResponse:
+                It returns a list of NamedEntity when using 'overview' mode,
+                and a TownResponse when using 'detailed' mode.
+
+        Raises:
+            ValueError: If mode is 'detailed' and town_request is None.
+            httpx.HTTPStatusError: If the request fails.
+
+        Examples:
+            ```python
+            with httpx.AsyncClient() as client:
+                emc_client = EmcClient(client)
+                towns = await emc_client.get_towns()
+                print(towns)
+            ```
+
+            ```python
+            with httpx.AsyncClient() as client:
+                emc_client = EmcClient(client)
+                town_request = NamedRequest(query=["Colombia"])
+                towns = await emc_client.get_towns(mode="detailed", town_request=town_request)
+                print(towns)
+            ```
+        """
+
+        if mode == "overview":
+            payload = None
+            response = await self.client.get("https://api.earthmc.net/v4/towns")
+
+
+        elif mode == "detailed":
+            if town_request is None:
+                raise ValueError("town must be provided when mode is 'detailed'")
+
+            payload = town_request.model_dump(exclude_none=True)
+            response = await self.client.post("https://api.earthmc.net/v4/towns", json=payload)
+
+        if response.status_code != 200:
+            raise httpx.HTTPStatusError(f"Unexpected status code: {response.status_code, response.text} to request {payload}",
+                request=response.request, response=response)
+
+        if mode == "overview":
+            overview_towns: list[NamedEntity] = [NamedEntity.model_validate(town) for town in track(response.json(),
+                description="Loading and validating overview towns...")]
+            return overview_towns
+
+        elif mode == "detailed":
+            detailed_towns: list[Town] = [Town.model_validate(town) for town in track(response.json(),
+                description="Loading and validating detailed towns...")]
+            return TownResponse(towns=detailed_towns)
+
+
+    @overload
+    async def get_nations(self, mode: Literal["overview"] = "overview", nation_request: None = None) -> list[NamedEntity]: ...
+
+    @overload
+    async def get_nations(self, mode: Literal["detailed"], nation_request: NamedRequest | None = None) -> NationResponse: ...
+
+    async def get_nations(self, mode: RequestMode = "overview", nation_request: NamedRequest | None = None) -> list[NamedEntity] | NationResponse:  # type: ignore[misc]
+        """
+        Get information about nations in the server.
+        Depends on the request mode. If you want to query a specific nation,
+        use `detailed` mode and provide the nation request parameters.
+        You can provide either the nation name or UUID.
+
+        Note:
+            The 'overview' mode makes a GET request to https://api.earthmc.net/v4/nations,
+            while the 'detailed' mode makes a POST request to https://api.earthmc.net/v4/nations
+
+        Args:
+            mode (RequestMode): The request mode, either 'overview' or 'detailed'.
+            nation_request (NamedRequest | None): The nation request parameters, required for 'detailed' mode.
+
+        Returns:
+            list[NamedEntity] | NationResponse:
+                It returns a list of NamedEntity when using 'overview' mode,
+                and a NationResponse when using 'detailed' mode.
+
+        Raises:
+            ValueError: If 'detailed' mode is used without providing nation_request.
+            httpx.HTTPStatusError: If the request fails.
+
+        Examples:
+            ```python
+            with httpx.AsyncClient() as client:
+                emc_client = EmcClient(client)
+                nations = await emc_client.get_nations()
+                print(nations)
+            ```
+
+            ```python
+            with httpx.AsyncClient() as client:
+                emc_client = EmcClient(client)
+                nation_request = NamedRequest(query=["Amazon"])
+                nations = await emc_client.get_nations(mode="detailed", nation_request=nation_request)
+                print(nations)
+            ```
+
+        """
+        if mode == "overview":
+            response = await self.client.get("https://api.earthmc.net/v4/nations")
+
+
+        elif mode == "detailed":
+            if nation_request is None:
+                raise ValueError("nation_request is required for detailed mode")
+
+            payload = nation_request.model_dump()
+            response = await self.client.post("https://api.earthmc.net/v4/nations", json=payload)
+
+        if response.status_code != 200:
+            raise httpx.HTTPStatusError(f"Unexpected status code: {response.status_code, response.text}", request=response.request, response=response)
+
+        if mode == "overview":
+            overview_nations: list[NamedEntity] = [NamedEntity.model_validate(nation) for nation in track(response.json(),
+            description="Fetching overview nations")]
+            return overview_nations
+
+        elif mode == "detailed":
+            detailed_nations: list[Nation] = [Nation.model_validate(nation) for nation in track(response.json(),
+                description="Fetching detailed nations")]
+            return NationResponse(nations=detailed_nations)
+
+    @overload
+    async def get_players(self, mode: Literal["overview"] = "overview", player_request: None = None) -> list[NamedEntity]: ...
+
+    @overload
+    async def get_players(self, mode: Literal["detailed"], player_request: NamedRequest | None = None) -> PlayerResponse: ...
+
+    async def get_players(self, mode: RequestMode = "overview", player_request: NamedRequest | None = None) -> list[NamedEntity] | PlayerResponse:  # type: ignore[misc]
+        """
+        Get information about players.
+        Depends on the `mode` parameter. If you want to query a specific player,
+        use `detailed` mode and provide a `player_request`.
+        You can provide either the player name or UUID.
+
+        Note:
+            `overview mode`: Replaces a GET request to https://api.earthmc.net/v4/players
+            `detailed mode`: Replaces a POST request to https://api.earthmc.net/v4/players
+
+        Args:
+            mode (RequestMode): The mode to use for the request. Defaults to `overview`.
+            player_request (NamedRequest | None): The player request to use for `detailed` mode. Defaults to `None`.
+
+        Returns:
+            list[NamedEntity] | PlayerResponse: The players when using `overview` mode.
+            PlayerResponse: The players when using `detailed` mode.
+
+        Raises:
+            ValueError: If `player_request` is not provided for `detailed` mode.
+            httpx.HTTPStatusError: If the request fails.
+
+        Examples:
+            ```python
+            with httpx.AsyncClient() as client:
+                emc_client = EmcClient(client)
+                players = await emc_client.get_players("overview")
+            print(players)
+            ```
+
+            ```python
+            with httpx.AsyncClient() as client:
+                emc_client = EmcClient(client)
+                player_request = NamedRequest(query=["RafaCabra"])
+                players = await emc_client.get_players("detailed", player_request=player_request)
+            print(players)
+            ```
+        """
+        if mode == "overview":
+            response = await self.client.get("https://api.earthmc.net/v4/players")
+
+
+        elif mode == "detailed":
+            if player_request is None:
+                raise ValueError("player_request is required for detailed mode")
+
+            payload = player_request.model_dump()
+            response = await self.client.post("https://api.earthmc.net/v4/players", json=payload)
+
+        if response.status_code != 200:
+            raise httpx.HTTPStatusError(f"Unexpected status code: {response.status_code, response.text}", request=response.request, response=response)
+
+        if mode == "overview":
+            overview_players: list[NamedEntity] = [NamedEntity.model_validate(player) for player in track(response.json(),
+                description="Fetching overview players")]
+            return overview_players
+
+        elif mode == "detailed":
+            detailed_players: list[Player] = [Player.model_validate(player) for player in track(response.json(),
+                description="Fetching detailed players")]
+            return PlayerResponse(players=detailed_players)

pyearthmc-0.2.0/src/pyearthmc/models/README.md

@@ -0,0 +1,51 @@
+# Models
+
+This directory contains the **Pydantic v2 data models** used by PyEMC.
+
+They define the structure of the data exchanged between the client and the
+EarthMC API. Every request and response in the library is handled through these
+models, providing validation, serialization, autocompletion, and type checking.
+
+Because everything is a typed model, you get IDE autocompletion and static
+type-checking out of the box, you don't need to re-check the raw API docs for
+every field.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `common.py` | Shared building blocks used by all endpoints |
+| `server.py` | `ServerResponse` and its nested server/status/stats/vote-party models |
+| `towns.py` | `Town`, `TownResponse` and town-specific models |
+| `nations.py` | `Nation`, `NationResponse` and nation-specific models |
+| `players.py` | `Player`, `PlayerResponse` and player-specific models |
+
+## Shared primitives (`common.py`)
+
+- `RequestMode`, `Literal["overview", "detailed"]`, controls the request method
+  and the shape of the response.
+- `NamedRequest`, the `detailed` request body: `query: list[str]` of names or
+  UUIDs to look up.
+- `NamedEntity`, the minimal `{name, uuid}` pair returned by `overview` mode and
+  used to reference related entities (mayor, nation, residents, etc.).
+- `UnnamedEntity`, an entity identified by `uuid` only.
+- `Metadata`, adds a computed `response_arrived` timestamp to every response.
+- `DefaultResponse`, base for all typed detailed responses; carries `metadata`.
+
+## Computed fields
+
+Some fields are generated on top of the raw API response via
+`@computed_field`. These add value without altering the underlying data:
+
+- `Metadata.response_arrived`, a Unix timestamp recorded when the model was
+  constructed, so you know how stale the data is.
+- `VotepartyStatus.numVotes`, the current vote-party vote count, derived from
+  `target - numRemaining`.
+
+## Conventions
+
+- Field names mirror the raw EarthMC API (camelCase, e.g. `isOnline`,
+  `numTownBlocks`), so the JSON maps 1:1 onto the models.
+- Optional fields that the API may omit are typed `Optional` / `None`.
+- When a new endpoint is added, create a matching module here following the
+  `server.py` / `towns.py` pattern and export its response via the client.

pyearthmc-0.2.0/src/pyearthmc/models/common.py

@@ -0,0 +1,54 @@
+
+import datetime
+from typing import Literal
+
+from pydantic import BaseModel, computed_field
+
+RequestMode = Literal['overview', 'detailed']
+type UnnamedCoordinates = tuple[int, int]
+
+
+
+class NamedRequest(BaseModel):
+    # I absolutely hate doing this without type safety,
+    # but the API expects a list of strings and I don't want to write a custom validator
+    # Let me know if you have a better solution.
+    query: list[str]
+
+class Metadata(BaseModel):
+    @computed_field
+    def response_arrived(self) -> int:
+        return int(datetime.datetime.now(datetime.UTC).timestamp())
+
+class SimpleTimestamp(BaseModel):
+    registered: int
+
+class NamedEntity(BaseModel):
+    name: str | None = None
+    uuid: str | None = None
+
+class SimpleQuery(BaseModel):
+    query: NamedEntity
+
+class UnnamedEntity(BaseModel):
+    uuid: str
+
+class SimpleCoordinates(BaseModel):
+    x: float
+    z: float
+
+class WorldCoordinates(SimpleCoordinates):
+    world: str
+    y: int
+    pitch: float
+    yaw: float
+
+
+class NamedResponse(NamedEntity):
+    metadata: Metadata = Metadata()
+
+class UnnamedResponse(UnnamedEntity):
+    metadata: Metadata = Metadata()
+
+class DefaultResponse(BaseModel):
+    metadata: Metadata = Metadata()

pyearthmc-0.2.0/src/pyearthmc/models/nations.py

@@ -0,0 +1,52 @@
+from pydantic.main import BaseModel
+
+from pyearthmc.models.common import (
+    DefaultResponse,
+    NamedEntity,
+    SimpleTimestamp,
+    WorldCoordinates,
+)
+
+
+class NationStats(BaseModel):
+    numTownBlocks: int
+    numResidents: int
+    numTowns: int
+    numAllies: int
+    numEnemies: int
+    balance: int
+
+class NationStatus(BaseModel):
+    isPublic: bool
+    isOpen: bool
+    isNeutral: bool
+
+class NationCoordinates(BaseModel):
+    spawn: WorldCoordinates
+
+class NationRanks(BaseModel):
+    Chancellor: list[NamedEntity] | None = None
+    Colonist: list[NamedEntity] | None = None
+    Diplomat: list[NamedEntity] | None = None
+
+
+class Nation(NamedEntity):
+    board: str
+    dynmapColour: str
+    dynmapOutline: str
+    wiki: str | None = None
+    king: NamedEntity
+    capital: NamedEntity
+    timestamps: SimpleTimestamp
+    status: NationStatus
+    stats: NationStats
+    coordinates: NationCoordinates
+    residents: list[NamedEntity]
+    towns: list[NamedEntity]
+    allies: list[NamedEntity] | None = None
+    enemies: list[NamedEntity] | None = None
+    sanctions: list[NamedEntity] | None = None
+    ranks: NationRanks
+
+class NationResponse(DefaultResponse):
+    nations: list[Nation]

pyearthmc-0.2.0/src/pyearthmc/models/nearby.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class NearbyQuery(BaseModel):
+    target_type: str
+    target: str | list[int]
+    search_type: str
+    radius: int

pyearthmc-0.2.0/src/pyearthmc/models/online.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+from pyearthmc.models.common import NamedEntity
+
+
+class OnlinePlayersResponse(BaseModel):
+    count: int
+    players: list[NamedEntity]

pyearthmc-0.2.0/src/pyearthmc/models/players.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel
+
+from pyearthmc.models.common import DefaultResponse, NamedEntity
+
+
+class PlayerTimestamp(BaseModel):
+    registered: int
+    joinedTownAt: int | None = None
+    lastOnline: int
+
+class PlayerStats(BaseModel):
+    balance: int
+    numFriends: int
+
+class PlayerStatus(BaseModel):
+    isOnline: bool
+    isNPC: bool
+    isMayor: bool
+    isKing: bool
+    hasTown: bool
+    hasNation: bool
+
+class PlayerRanks(BaseModel):
+    townRanks: list[str]
+    nationRanks: list[str]
+
+class Player(NamedEntity):
+    title: str | None = None
+    surname: str | None = None
+    formatted_name: str | None = None
+    about: str | None = None
+    town: NamedEntity | None = None
+    nation: NamedEntity | None = None
+    timestamps: PlayerTimestamp
+    status: PlayerStatus
+    stats: PlayerStats
+    ranks: PlayerRanks | None = None
+    friends: list[NamedEntity]
+    discord: int | None = None
+
+class PlayerResponse(DefaultResponse):
+    players: list[Player]

pyearthmc-0.2.0/src/pyearthmc/models/server.py

@@ -0,0 +1,45 @@
+from pydantic import BaseModel
+from pydantic.fields import computed_field
+
+from pyearthmc.models.common import DefaultResponse
+
+
+class ServerTimestamp(BaseModel):
+    newDayTime: int
+    serverTimeOfDay: int
+
+
+class ServerStatus(BaseModel):
+    hasStorm: bool
+    isThundering: bool
+
+class ServerStats(BaseModel):
+    time: int
+    fullTime: int
+    maxPlayers: int
+    numOnlinePlayers: int
+    numOnlineNomads: int
+    numResidents: int
+    numNomads: int
+    numTowns: int
+    numTownBlocks: int
+    numNations: int
+    numQuarters: int
+    numCuboids: int
+
+class VotepartyStatus(BaseModel):
+    target: int
+    numRemaining: int
+
+    @computed_field
+    def numVotes(self) -> int:
+        return self.target - self.numRemaining
+
+
+class ServerResponse(DefaultResponse):
+    version: str
+    moonPhase: str
+    timestamps: ServerTimestamp
+    status: ServerStatus
+    stats: ServerStats
+    voteParty: VotepartyStatus

pyearthmc-0.2.0/src/pyearthmc/models/towns.py

@@ -0,0 +1,74 @@
+
+from pydantic import BaseModel
+
+from pyearthmc.models.common import (
+    DefaultResponse,
+    NamedEntity,
+    UnnamedCoordinates,
+    UnnamedEntity,
+    WorldCoordinates,
+)
+
+
+class TownTimestamp(BaseModel):
+    registered: int
+    joinedNationAt: int | None = None
+    ruinedAt: int | None = None
+
+class TownStats(BaseModel):
+    numTownBlocks: int
+    maxTownBlocks: int
+    numResidents: int
+    numTrusted: int
+    numOutlaws: int
+    balance: int
+    forSalePrice: int | None
+
+class TownStatus(BaseModel):
+    isPublic: bool
+    isOpen: bool
+    isNeutral: bool
+    isCapital: bool
+    isOverclaimed: bool | None = None
+    isRuined: bool
+    isForSale: bool
+    hasNation: bool
+    hasOverclaimShield: bool | None = None
+    canOutsiderSpawn: bool | None = None
+
+
+class TownRanks(BaseModel):
+    Councilor: list[NamedEntity] | None = None
+    Builder: list[NamedEntity] | None = None
+    Recruiter: list[NamedEntity] | None = None
+    Police: list[NamedEntity] | None = None
+    Tax_exempt: list[NamedEntity] | None = None
+    Treasurer: list[NamedEntity] | None = None
+    Realtor: list[NamedEntity] | None = None
+    Settler: list[NamedEntity] | None = None
+
+class TownCoordinates(BaseModel):
+    spawn: WorldCoordinates
+    homeBlock: UnnamedCoordinates
+    townBlocks: list[UnnamedCoordinates]
+
+
+class Town(NamedEntity):
+    board: str
+    founder: str
+    wiki: str | None = None
+    mayor: NamedEntity
+    nation: NamedEntity
+    timestamps: TownTimestamp
+    status: TownStatus
+    stats: TownStats
+    coordinates: TownCoordinates
+    residents: list[NamedEntity]
+    trusted: list[NamedEntity] | None = None
+
+    outlaws: list[NamedEntity] | None = None
+    quarters: list[UnnamedEntity] | None = None
+    ranks: TownRanks
+
+class TownResponse(DefaultResponse):
+    towns: list[Town]