mcapitr 0.1.0__tar.gz

mcapitr-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 MCAPI.TR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

mcapitr-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+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
+

mcapitr-0.1.0/README.md

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

mcapitr-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcapitr"
+version = "0.1.0"
+description = "Official zero-dependency Python client for the MCAPI.TR Minecraft Server Status API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "MCAPI.TR" }]
+keywords = [
+  "minecraft",
+  "minecraft-api",
+  "minecraft-server",
+  "server-status",
+  "java-edition",
+  "bedrock-edition",
+  "motd",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://mcapi.tr"
+Documentation = "https://mcapi.tr/api-docs"
+OpenAPI = "https://mcapi.tr/openapi.json"
+Issues = "https://github.com/Rynix01/mcapitr/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mcapitr = ["py.typed"]
+

mcapitr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcapitr-0.1.0/src/mcapitr/__init__.py

@@ -0,0 +1,47 @@
+from ._version import __version__
+from .client import AsyncMCAPIClient, MCAPIClient
+from .exceptions import (
+    APIError,
+    BadRequestError,
+    MCAPIError,
+    NetworkError,
+    RateLimitError,
+    ResponseDecodeError,
+    ServerNotFoundError,
+)
+from .models import (
+    HealthResponse,
+    Motd,
+    PlatformStatistics,
+    Players,
+    Query,
+    ServerStatus,
+    TrendMeta,
+    TrendResponse,
+    TrendServer,
+    Version,
+)
+
+__all__ = [
+    "__version__",
+    "MCAPIClient",
+    "AsyncMCAPIClient",
+    "MCAPIError",
+    "NetworkError",
+    "APIError",
+    "BadRequestError",
+    "ServerNotFoundError",
+    "RateLimitError",
+    "ResponseDecodeError",
+    "HealthResponse",
+    "Query",
+    "Players",
+    "Version",
+    "Motd",
+    "ServerStatus",
+    "TrendServer",
+    "TrendMeta",
+    "TrendResponse",
+    "PlatformStatistics",
+]
+

mcapitr-0.1.0/src/mcapitr/_transport.py

@@ -0,0 +1,30 @@
+from typing import Callable, Mapping, Tuple
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .exceptions import NetworkError
+
+
+TransportResponse = Tuple[int, Mapping[str, str], bytes]
+Transport = Callable[[str, float, Mapping[str, str]], TransportResponse]
+
+
+def default_transport(
+    url: str,
+    timeout: float,
+    headers: Mapping[str, str],
+) -> TransportResponse:
+    request = Request(url, headers=dict(headers), method="GET")
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            return (
+                int(getattr(response, "status", 200)),
+                dict(response.headers.items()),
+                response.read(),
+            )
+    except HTTPError as error:
+        return error.code, dict(error.headers.items()), error.read()
+    except (URLError, TimeoutError, OSError) as error:
+        reason = getattr(error, "reason", error)
+        raise NetworkError("Could not reach MCAPI.TR: {}".format(reason)) from error
+

mcapitr-0.1.0/src/mcapitr/_version.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+

mcapitr-0.1.0/src/mcapitr/client.py

@@ -0,0 +1,341 @@
+import asyncio
+import json
+from typing import Any, Dict, Mapping, Optional, Tuple, Type, TypeVar, cast
+from urllib.parse import quote, urlencode, urlparse
+
+from ._transport import Transport, default_transport
+from ._version import __version__
+from .exceptions import (
+    APIError,
+    BadRequestError,
+    RateLimitError,
+    ResponseDecodeError,
+    ServerNotFoundError,
+)
+from .models import HealthResponse, JSONDict, PlatformStatistics, ServerStatus, TrendResponse
+
+
+DEFAULT_BASE_URL = "https://mcapi.tr/api/v1"
+_BANNER_SIZES = ("small", "normal", "large")
+_BANNER_STYLES = ("modern", "classic")
+_WIDGET_THEMES = ("dark", "light")
+_IMAGE_FORMATS = ("png", "webp")
+
+ExceptionType = TypeVar("ExceptionType", bound=APIError)
+
+
+def _address(value: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("address must be a non-empty string")
+    return value.strip()
+
+
+def _choice(name: str, value: str, allowed: Tuple[str, ...]) -> str:
+    if value not in allowed:
+        raise ValueError("{} must be one of: {}".format(name, ", ".join(allowed)))
+    return value
+
+
+def _edition_params(legacy: bool, bedrock: bool) -> Dict[str, str]:
+    if legacy and bedrock:
+        raise ValueError("legacy and bedrock cannot both be true")
+    params: Dict[str, str] = {}
+    if legacy:
+        params["legacy"] = "true"
+    if bedrock:
+        params["bedrock"] = "true"
+    return params
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    wanted = name.lower()
+    for key, value in headers.items():
+        if key.lower() == wanted:
+            return value
+    return None
+
+
+class MCAPIClient:
+    """Synchronous client for the public MCAPI.TR API."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        user_agent: Optional[str] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        normalized_base_url = str(base_url).strip().rstrip("/")
+        parsed = urlparse(normalized_base_url)
+        if parsed.scheme not in ("http", "https") or not parsed.netloc:
+            raise ValueError("base_url must be an absolute HTTP or HTTPS URL")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+
+        self.base_url = normalized_base_url
+        self.timeout = float(timeout)
+        self.user_agent = user_agent or "mcapitr-python/{}".format(__version__)
+        self._transport = transport or default_transport
+
+    def __enter__(self) -> "MCAPIClient":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        return None
+
+    def _url(self, path: str, params: Optional[Mapping[str, Any]] = None) -> str:
+        url = "{}/{}".format(self.base_url, path.lstrip("/"))
+        if params:
+            normalized = {
+                key: str(value).lower() if isinstance(value, bool) else str(value)
+                for key, value in params.items()
+                if value is not None
+            }
+            if normalized:
+                url = "{}?{}".format(url, urlencode(normalized))
+        return url
+
+    def _error_message(self, status_code: int, body: bytes) -> str:
+        try:
+            payload = json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            payload = None
+        if isinstance(payload, dict):
+            for key in ("message", "error", "status"):
+                if payload.get(key):
+                    return str(payload[key])
+        return "MCAPI.TR returned HTTP {}".format(status_code)
+
+    def _raise_api_error(
+        self,
+        status_code: int,
+        headers: Mapping[str, str],
+        body: bytes,
+    ) -> None:
+        message = self._error_message(status_code, body)
+        common = {
+            "status_code": status_code,
+            "response_body": body,
+            "headers": headers,
+        }
+        if status_code == 400:
+            raise BadRequestError(message, **common)
+        if status_code == 404:
+            raise ServerNotFoundError(message, **common)
+        if status_code == 429:
+            raise RateLimitError(
+                message,
+                retry_after=_header(headers, "Retry-After"),
+                **common,
+            )
+        raise APIError(message, **common)
+
+    def _request_bytes(self, url: str) -> bytes:
+        status_code, headers, body = self._transport(
+            url,
+            self.timeout,
+            {
+                "Accept": "*/*",
+                "User-Agent": self.user_agent,
+            },
+        )
+        if status_code < 200 or status_code >= 300:
+            self._raise_api_error(status_code, headers, body)
+        return body
+
+    def _request_json(self, path: str, params: Optional[Mapping[str, Any]] = None) -> JSONDict:
+        body = self._request_bytes(self._url(path, params))
+        try:
+            payload = json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ResponseDecodeError("MCAPI.TR returned invalid JSON") from error
+        if not isinstance(payload, dict):
+            raise ResponseDecodeError("MCAPI.TR returned JSON with an unexpected shape")
+        return cast(JSONDict, payload)
+
+    def health(self) -> HealthResponse:
+        return cast(HealthResponse, self._request_json("status"))
+
+    def server_status(
+        self,
+        address: str,
+        *,
+        legacy: bool = False,
+        bedrock: bool = False,
+    ) -> ServerStatus:
+        server_address = quote(_address(address), safe="")
+        params = _edition_params(legacy, bedrock)
+        return cast(ServerStatus, self._request_json("status/{}".format(server_address), params))
+
+    def trends(self, *, limit: int = 10, cursor: Optional[str] = None) -> TrendResponse:
+        if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 50:
+            raise ValueError("limit must be an integer between 1 and 50")
+        return cast(
+            TrendResponse,
+            self._request_json("trends", {"limit": limit, "cursor": cursor}),
+        )
+
+    def stats(self) -> PlatformStatistics:
+        return cast(PlatformStatistics, self._request_json("stats"))
+
+    def server_icon_url(
+        self,
+        address: str,
+        *,
+        size: int = 80,
+        image_format: str = "png",
+        legacy: bool = False,
+        bedrock: bool = False,
+    ) -> str:
+        if isinstance(size, bool) or not isinstance(size, int) or not 16 <= size <= 256:
+            raise ValueError("size must be an integer between 16 and 256")
+        image_format = _choice("image_format", image_format, _IMAGE_FORMATS)
+        params: Dict[str, Any] = {
+            "address": _address(address),
+            "size": size,
+            "format": image_format,
+        }
+        params.update(_edition_params(legacy, bedrock))
+        return self._url("icon/dynamic", params)
+
+    def rounded_icon_url(
+        self,
+        address: str,
+        *,
+        size: int = 128,
+        legacy: bool = False,
+        bedrock: bool = False,
+    ) -> str:
+        if isinstance(size, bool) or not isinstance(size, int) or not 32 <= size <= 512:
+            raise ValueError("size must be an integer between 32 and 512")
+        params: Dict[str, Any] = {"address": _address(address), "size": size}
+        params.update(_edition_params(legacy, bedrock))
+        return self._url("icon/sharp", params)
+
+    def server_banner_url(
+        self,
+        address: str,
+        *,
+        size: str = "normal",
+        style: str = "modern",
+    ) -> str:
+        size = _choice("size", "normal" if size == "medium" else size, _BANNER_SIZES)
+        style = _choice("style", style, _BANNER_STYLES)
+        return self._url(
+            "banner/{}".format(quote(_address(address), safe="")),
+            {"size": size, "style": style},
+        )
+
+    def motd_banner_url(
+        self,
+        motd: str,
+        *,
+        text_color: Optional[str] = None,
+        accent_color: Optional[str] = None,
+    ) -> str:
+        if not isinstance(motd, str) or not motd.strip():
+            raise ValueError("motd must be a non-empty string")
+        if len(motd) > 300:
+            raise ValueError("motd cannot be longer than 300 characters")
+        return self._url(
+            "banner/motd",
+            {
+                "motd": motd,
+                "textColor": text_color,
+                "accentColor": accent_color,
+            },
+        )
+
+    def widget_url(
+        self,
+        address: str,
+        *,
+        size: str = "large",
+        theme: str = "dark",
+    ) -> str:
+        size = _choice("size", "normal" if size == "medium" else size, _BANNER_SIZES)
+        theme = _choice("theme", theme, _WIDGET_THEMES)
+        return self._url(
+            "widget/{}/{}".format(size, quote(_address(address), safe="")),
+            {"theme": theme},
+        )
+
+    def server_icon(self, address: str, **options: Any) -> bytes:
+        return self._request_bytes(self.server_icon_url(address, **options))
+
+    def rounded_icon(self, address: str, **options: Any) -> bytes:
+        return self._request_bytes(self.rounded_icon_url(address, **options))
+
+    def server_banner(self, address: str, **options: Any) -> bytes:
+        return self._request_bytes(self.server_banner_url(address, **options))
+
+    def motd_banner(self, motd: str, **options: Any) -> bytes:
+        return self._request_bytes(self.motd_banner_url(motd, **options))
+
+    def widget(self, address: str, **options: Any) -> str:
+        body = self._request_bytes(self.widget_url(address, **options))
+        try:
+            return body.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise ResponseDecodeError("MCAPI.TR returned invalid widget HTML") from error
+
+
+class AsyncMCAPIClient:
+    """Async wrapper with the same behavior as :class:`MCAPIClient`."""
+
+    def __init__(self, **options: Any) -> None:
+        self._client = MCAPIClient(**options)
+
+    @property
+    def base_url(self) -> str:
+        return self._client.base_url
+
+    async def __aenter__(self) -> "AsyncMCAPIClient":
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        return None
+
+    async def health(self) -> HealthResponse:
+        return await asyncio.to_thread(self._client.health)
+
+    async def server_status(self, address: str, **options: Any) -> ServerStatus:
+        return await asyncio.to_thread(self._client.server_status, address, **options)
+
+    async def trends(self, *, limit: int = 10, cursor: Optional[str] = None) -> TrendResponse:
+        return await asyncio.to_thread(self._client.trends, limit=limit, cursor=cursor)
+
+    async def stats(self) -> PlatformStatistics:
+        return await asyncio.to_thread(self._client.stats)
+
+    def server_icon_url(self, address: str, **options: Any) -> str:
+        return self._client.server_icon_url(address, **options)
+
+    def rounded_icon_url(self, address: str, **options: Any) -> str:
+        return self._client.rounded_icon_url(address, **options)
+
+    def server_banner_url(self, address: str, **options: Any) -> str:
+        return self._client.server_banner_url(address, **options)
+
+    def motd_banner_url(self, motd: str, **options: Any) -> str:
+        return self._client.motd_banner_url(motd, **options)
+
+    def widget_url(self, address: str, **options: Any) -> str:
+        return self._client.widget_url(address, **options)
+
+    async def server_icon(self, address: str, **options: Any) -> bytes:
+        return await asyncio.to_thread(self._client.server_icon, address, **options)
+
+    async def rounded_icon(self, address: str, **options: Any) -> bytes:
+        return await asyncio.to_thread(self._client.rounded_icon, address, **options)
+
+    async def server_banner(self, address: str, **options: Any) -> bytes:
+        return await asyncio.to_thread(self._client.server_banner, address, **options)
+
+    async def motd_banner(self, motd: str, **options: Any) -> bytes:
+        return await asyncio.to_thread(self._client.motd_banner, motd, **options)
+
+    async def widget(self, address: str, **options: Any) -> str:
+        return await asyncio.to_thread(self._client.widget, address, **options)
+

mcapitr-0.1.0/src/mcapitr/exceptions.py

@@ -0,0 +1,60 @@
+from typing import Mapping, Optional
+
+
+class MCAPIError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class NetworkError(MCAPIError):
+    """The API could not be reached."""
+
+
+class ResponseDecodeError(MCAPIError):
+    """The API returned a response that could not be decoded."""
+
+
+class APIError(MCAPIError):
+    """The API returned a non-success HTTP response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        response_body: bytes = b"",
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+        self.headers = dict(headers or {})
+
+
+class BadRequestError(APIError):
+    """A request parameter was rejected by the API."""
+
+
+class ServerNotFoundError(APIError):
+    """The requested Minecraft server is offline or unreachable."""
+
+
+class RateLimitError(APIError):
+    """The API request limit has been exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        response_body: bytes = b"",
+        headers: Optional[Mapping[str, str]] = None,
+        retry_after: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            response_body=response_body,
+            headers=headers,
+        )
+        self.retry_after = retry_after
+

mcapitr-0.1.0/src/mcapitr/models.py

@@ -0,0 +1,104 @@
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+JSONDict = Dict[str, Any]
+
+
+class HealthResponse(TypedDict, total=False):
+    status: str
+    timestamp: str
+    service: str
+    version: str
+
+
+class Query(TypedDict, total=False):
+    host: str
+    port: int
+    legacy: bool
+    bedrock: bool
+
+
+class PlayerSample(TypedDict, total=False):
+    name: str
+    id: str
+
+
+class Players(TypedDict, total=False):
+    online: int
+    max: int
+    sample: List[PlayerSample]
+
+
+class Version(TypedDict, total=False):
+    name: str
+    protocol: int
+    name_clean: str
+
+
+class Motd(TypedDict, total=False):
+    raw: str
+    clean: str
+    html: str
+    raw_lines: List[str]
+    clean_lines: List[str]
+    html_lines: List[str]
+
+
+class ServerStatus(TypedDict, total=False):
+    query: Query
+    server_id: Optional[str]
+    ip_address: Optional[str]
+    icmp: Optional[bool]
+    online: bool
+    error: Optional[str]
+    version: Optional[Version]
+    players: Optional[Players]
+    motd: Optional[Motd]
+    favicon: Optional[str]
+    roundTripLatency: Optional[float]
+    stale: bool
+    checked_at: str
+
+
+class TrendServer(TypedDict, total=False):
+    server_id: str
+    hostname: str
+    address: str
+    port: int
+    edition: str
+    trend_score: float
+    daily_growth: float
+    is_online: bool
+    stale: bool
+    checked_at: str
+    players_online: int
+    players_max: int
+    version: Optional[str]
+    favicon: Optional[str]
+    record_players: int
+    uptime_percentage: float
+
+
+class TrendMeta(TypedDict, total=False):
+    nextCursor: Optional[str]
+    hasNext: bool
+    limit: int
+
+
+class TrendResponse(TypedDict, total=False):
+    success: bool
+    data: List[TrendServer]
+    meta: TrendMeta
+
+
+class PlatformStatistics(TypedDict, total=False):
+    totalRequests: int
+    apiRequests: int
+    serverQueries: int
+    totalChecks: int
+    onlineServers: int
+    offlineServers: int
+    activePlayers: int
+    recentChecks: List[JSONDict]
+    onlineRate: float
+

mcapitr-0.1.0/src/mcapitr/py.typed

@@ -0,0 +1 @@
+

mcapitr-0.1.0/src/mcapitr.egg-info/PKG-INFO

@@ -0,0 +1,165 @@
+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
+

mcapitr-0.1.0/src/mcapitr.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/mcapitr/__init__.py
+src/mcapitr/_transport.py
+src/mcapitr/_version.py
+src/mcapitr/client.py
+src/mcapitr/exceptions.py
+src/mcapitr/models.py
+src/mcapitr/py.typed
+src/mcapitr.egg-info/PKG-INFO
+src/mcapitr.egg-info/SOURCES.txt
+src/mcapitr.egg-info/dependency_links.txt
+src/mcapitr.egg-info/top_level.txt
+tests/test_client.py

mcapitr-0.1.0/src/mcapitr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcapitr-0.1.0/src/mcapitr.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcapitr

mcapitr-0.1.0/tests/test_client.py

@@ -0,0 +1,148 @@
+import asyncio
+import json
+import sys
+import unittest
+from pathlib import Path
+from typing import Mapping, Tuple
+
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from mcapitr import (  # noqa: E402
+    AsyncMCAPIClient,
+    MCAPIClient,
+    RateLimitError,
+    ResponseDecodeError,
+    ServerNotFoundError,
+)
+
+
+class StubTransport:
+    def __init__(
+        self,
+        status: int = 200,
+        payload: object = None,
+        headers: Mapping[str, str] = None,
+        raw_body: bytes = None,
+    ) -> None:
+        self.status = status
+        self.payload = {} if payload is None else payload
+        self.headers = dict(headers or {})
+        self.raw_body = raw_body
+        self.calls = []
+
+    def __call__(
+        self,
+        url: str,
+        timeout: float,
+        headers: Mapping[str, str],
+    ) -> Tuple[int, Mapping[str, str], bytes]:
+        self.calls.append((url, timeout, dict(headers)))
+        body = self.raw_body
+        if body is None:
+            body = json.dumps(self.payload).encode("utf-8")
+        return self.status, self.headers, body
+
+
+class ClientTests(unittest.TestCase):
+    def test_server_status_encodes_address_and_flags(self) -> None:
+        transport = StubTransport(payload={"online": True, "query": {}})
+        client = MCAPIClient(transport=transport)
+
+        response = client.server_status(" play.example.net:19132 ", bedrock=True)
+
+        self.assertTrue(response["online"])
+        self.assertEqual(
+            transport.calls[0][0],
+            "https://mcapi.tr/api/v1/status/play.example.net%3A19132?bedrock=true",
+        )
+
+    def test_health_and_stats_use_v1_routes(self) -> None:
+        transport = StubTransport(payload={"status": "OK"})
+        client = MCAPIClient(transport=transport)
+
+        client.health()
+        client.stats()
+
+        self.assertEqual(transport.calls[0][0], "https://mcapi.tr/api/v1/status")
+        self.assertEqual(transport.calls[1][0], "https://mcapi.tr/api/v1/stats")
+
+    def test_trends_validates_and_builds_cursor_query(self) -> None:
+        transport = StubTransport(payload={"success": True, "data": [], "meta": {}})
+        client = MCAPIClient(transport=transport)
+
+        client.trends(limit=25, cursor="4ce8f89c-463f-44e9-a757-b6d540a53038")
+
+        self.assertEqual(
+            transport.calls[0][0],
+            "https://mcapi.tr/api/v1/trends?limit=25&cursor=4ce8f89c-463f-44e9-a757-b6d540a53038",
+        )
+        with self.assertRaises(ValueError):
+            client.trends(limit=0)
+
+    def test_edition_flags_are_mutually_exclusive(self) -> None:
+        client = MCAPIClient(transport=StubTransport())
+        with self.assertRaisesRegex(ValueError, "cannot both be true"):
+            client.server_status("mc.example.net", legacy=True, bedrock=True)
+
+    def test_media_urls_are_validated_and_encoded(self) -> None:
+        client = MCAPIClient(transport=StubTransport())
+
+        self.assertEqual(
+            client.server_icon_url("mc.example.net", size=128, image_format="webp"),
+            "https://mcapi.tr/api/v1/icon/dynamic?address=mc.example.net&size=128&format=webp",
+        )
+        self.assertEqual(
+            client.server_banner_url("mc.example.net", size="medium"),
+            "https://mcapi.tr/api/v1/banner/mc.example.net?size=normal&style=modern",
+        )
+        with self.assertRaises(ValueError):
+            client.widget_url("mc.example.net", theme="blue")
+
+    def test_not_found_response_has_specific_exception(self) -> None:
+        transport = StubTransport(status=404, payload={"error": "Server unreachable"})
+        client = MCAPIClient(transport=transport)
+
+        with self.assertRaises(ServerNotFoundError) as raised:
+            client.server_status("offline.example.net")
+
+        self.assertEqual(raised.exception.status_code, 404)
+        self.assertEqual(str(raised.exception), "Server unreachable")
+
+    def test_rate_limit_includes_retry_after(self) -> None:
+        transport = StubTransport(
+            status=429,
+            payload={"message": "Too many requests"},
+            headers={"retry-after": "12"},
+        )
+        client = MCAPIClient(transport=transport)
+
+        with self.assertRaises(RateLimitError) as raised:
+            client.stats()
+
+        self.assertEqual(raised.exception.retry_after, "12")
+
+    def test_invalid_json_raises_decode_error(self) -> None:
+        client = MCAPIClient(transport=StubTransport(raw_body=b"not-json"))
+        with self.assertRaises(ResponseDecodeError):
+            client.health()
+
+    def test_binary_download_returns_bytes(self) -> None:
+        transport = StubTransport(raw_body=b"\x89PNG\r\n")
+        client = MCAPIClient(transport=transport)
+        self.assertEqual(client.server_icon("mc.example.net"), b"\x89PNG\r\n")
+
+    def test_async_client_matches_sync_behavior(self) -> None:
+        transport = StubTransport(payload={"online": True, "query": {}})
+
+        async def run() -> None:
+            async with AsyncMCAPIClient(transport=transport) as client:
+                result = await client.server_status("mc.example.net")
+                self.assertTrue(result["online"])
+
+        asyncio.run(run())
+
+
+if __name__ == "__main__":
+    unittest.main()
+