mythicmc-sdk 0.1.0__tar.gz

mythicmc_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+*.tgz
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+.venv/
+.env
+.DS_Store

mythicmc_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MythicMC
+
+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.

mythicmc_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: mythicmc-sdk
+Version: 0.1.0
+Summary: Official Python client for the MythicMC Public API.
+Project-URL: Documentation, https://github.com/mythicmcnetwork/mythicmc-sdk#readme
+Project-URL: Repository, https://github.com/mythicmcnetwork/mythicmc-sdk
+Author: MythicMC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,minecraft,mythicmc,sdk
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+MythicMC Public API (Python)
+======
+
+Python client for the MythicMC Public API. Python 3.10 or newer, synchronous and
+asynchronous, built on [httpx](https://www.python-httpx.org/).
+
+Create an API key in the [developer portal](https://developer.mythicmc.net/) with your MythicMC forum account. Production keys use development limits until approved.
+
+### Install
+
+```sh
+pip install mythicmc-sdk
+```
+
+### Install from source
+
+```sh
+pip install "git+https://github.com/mythicmcnetwork/mythicmc-sdk.git#subdirectory=python"
+```
+
+### Usage
+
+```python
+import os
+from mythicmc import MythicMC, NotFoundError
+
+with MythicMC(os.environ["MYTHICMC_API_KEY"]) as api:
+    player = api.get_player("Vicente_1313")  # username or UUID
+    print(player.rank.label, "unknown" if player.online is None else player.online)
+    print(player.meta.data_as_of)  # UTC cutoff this response reflects
+
+    try:
+        survival = api.get_player_stats("Vicente_1313").survival
+        print(survival.combat.kills, survival.net_worth.total if survival.net_worth else "unpublished")
+    except NotFoundError:
+        print("no published Survival statistics")
+
+    for row in api.get_leaderboard("kills", "weekly").rows:
+        print(row.rank, row.name, row.value)
+```
+
+`AsyncMythicMC` has the same methods as coroutines, for Discord bots and other
+asyncio programs:
+
+```python
+import asyncio
+import os
+from mythicmc import AsyncMythicMC
+
+async def main() -> None:
+    async with AsyncMythicMC(os.environ["MYTHICMC_API_KEY"]) as api:
+        profile, team = await asyncio.gather(api.get_player("Vicente_1313"), api.get_player_team("Vicente_1313"))
+    print(profile.rank.label, team.team.name if team.team else "no team")
+
+asyncio.run(main())
+```
+
+Both clients hold an httpx connection pool. Use them as context managers, or call
+`close()` yourself — `await api.close()` on the asynchronous one.
+
+| Method | Endpoint |
+| --- | --- |
+| `get_player(id)` | `GET /v1/players/{id}` |
+| `get_player_stats(id)` | `GET /v1/players/{id}/stats` |
+| `get_player_progression(id)` | `GET /v1/players/{id}/progression` |
+| `get_player_team(id)` | `GET /v1/players/{id}/team` |
+| `get_player_crate_keys(id)` | `GET /v1/players/{id}/crate-keys` |
+| `list_leaderboards()` | `GET /v1/leaderboards` |
+| `get_leaderboard(type, period)` | `GET /v1/leaderboards/{type}/{period}` |
+| `health()` | `GET /health` |
+
+`id` is a username, case-insensitive, or a UUID with or without dashes.
+
+The [full API reference](https://developer.mythicmc.net/#reference) includes additional endpoints you can call directly over HTTP.
+
+Replies are frozen dataclasses whose `snake_case` attributes come from the JSON's
+`camelCase` keys. Each reply also carries `meta`, parsed from the response headers,
+and `raw`, the decoded JSON body as a `dict`. Keys the models do not know about are
+ignored, so a field the API adds later reaches you through `raw` rather than breaking
+an older client.
+
+### Options
+
+| Argument | Default | |
+| --- | --- | --- |
+| `api_key` | required | Positional; the rest are keyword-only. |
+| `base_url` | `https://api.mythicmc.net` | |
+| `timeout` | `10.0` | Seconds, per attempt. |
+| `max_retries` | `2` | Retries after a `429`, each waiting for `Retry-After`, or a second when there is none. A wait over a minute raises instead. `0` disables. |
+| `transport` | `None` | An httpx transport, for tests or proxies. |
+
+### Errors
+
+Every response the client cannot turn into data raises a `MythicMCError`. `status` is
+the HTTP status; `message` is the API's `error` string, or a stand-in when the
+response carried none.
+
+| Class | Status | |
+| --- | --- | --- |
+| `BadRequestError` | 400 | Not a valid username or UUID. |
+| `AuthenticationError` | 401 | Missing or invalid key. |
+| `NotFoundError` | 404 | Unknown player or board, or no published Survival statistics. |
+| `RateLimitError` | 429 | Retries exhausted. `retry_after` is seconds, or `None`. |
+| `UnavailableError` | 503 | Not published yet, an ambiguous username, or a server fault. Retrying later can work. |
+
+Any other status, and a 2xx whose body is not the shape the model declares, raises
+`MythicMCError` itself. Network failures and timeouts raise httpx's own exceptions.
+
+### Examples
+
+[examples](examples) holds one file per group of endpoints, plus `async_lookup.py`
+for `AsyncMythicMC`.
+
+```sh
+pip install .
+MYTHICMC_API_KEY=mmc_... python examples/get_player.py Vicente_1313
+```
+
+Set `MYTHICMC_API_URL` to run them against a mock server instead of the live API.
+
+### Development
+
+```sh
+pip install -e .
+python -m unittest discover -s tests
+```

mythicmc_sdk-0.1.0/README.md

@@ -0,0 +1,126 @@
+MythicMC Public API (Python)
+======
+
+Python client for the MythicMC Public API. Python 3.10 or newer, synchronous and
+asynchronous, built on [httpx](https://www.python-httpx.org/).
+
+Create an API key in the [developer portal](https://developer.mythicmc.net/) with your MythicMC forum account. Production keys use development limits until approved.
+
+### Install
+
+```sh
+pip install mythicmc-sdk
+```
+
+### Install from source
+
+```sh
+pip install "git+https://github.com/mythicmcnetwork/mythicmc-sdk.git#subdirectory=python"
+```
+
+### Usage
+
+```python
+import os
+from mythicmc import MythicMC, NotFoundError
+
+with MythicMC(os.environ["MYTHICMC_API_KEY"]) as api:
+    player = api.get_player("Vicente_1313")  # username or UUID
+    print(player.rank.label, "unknown" if player.online is None else player.online)
+    print(player.meta.data_as_of)  # UTC cutoff this response reflects
+
+    try:
+        survival = api.get_player_stats("Vicente_1313").survival
+        print(survival.combat.kills, survival.net_worth.total if survival.net_worth else "unpublished")
+    except NotFoundError:
+        print("no published Survival statistics")
+
+    for row in api.get_leaderboard("kills", "weekly").rows:
+        print(row.rank, row.name, row.value)
+```
+
+`AsyncMythicMC` has the same methods as coroutines, for Discord bots and other
+asyncio programs:
+
+```python
+import asyncio
+import os
+from mythicmc import AsyncMythicMC
+
+async def main() -> None:
+    async with AsyncMythicMC(os.environ["MYTHICMC_API_KEY"]) as api:
+        profile, team = await asyncio.gather(api.get_player("Vicente_1313"), api.get_player_team("Vicente_1313"))
+    print(profile.rank.label, team.team.name if team.team else "no team")
+
+asyncio.run(main())
+```
+
+Both clients hold an httpx connection pool. Use them as context managers, or call
+`close()` yourself — `await api.close()` on the asynchronous one.
+
+| Method | Endpoint |
+| --- | --- |
+| `get_player(id)` | `GET /v1/players/{id}` |
+| `get_player_stats(id)` | `GET /v1/players/{id}/stats` |
+| `get_player_progression(id)` | `GET /v1/players/{id}/progression` |
+| `get_player_team(id)` | `GET /v1/players/{id}/team` |
+| `get_player_crate_keys(id)` | `GET /v1/players/{id}/crate-keys` |
+| `list_leaderboards()` | `GET /v1/leaderboards` |
+| `get_leaderboard(type, period)` | `GET /v1/leaderboards/{type}/{period}` |
+| `health()` | `GET /health` |
+
+`id` is a username, case-insensitive, or a UUID with or without dashes.
+
+The [full API reference](https://developer.mythicmc.net/#reference) includes additional endpoints you can call directly over HTTP.
+
+Replies are frozen dataclasses whose `snake_case` attributes come from the JSON's
+`camelCase` keys. Each reply also carries `meta`, parsed from the response headers,
+and `raw`, the decoded JSON body as a `dict`. Keys the models do not know about are
+ignored, so a field the API adds later reaches you through `raw` rather than breaking
+an older client.
+
+### Options
+
+| Argument | Default | |
+| --- | --- | --- |
+| `api_key` | required | Positional; the rest are keyword-only. |
+| `base_url` | `https://api.mythicmc.net` | |
+| `timeout` | `10.0` | Seconds, per attempt. |
+| `max_retries` | `2` | Retries after a `429`, each waiting for `Retry-After`, or a second when there is none. A wait over a minute raises instead. `0` disables. |
+| `transport` | `None` | An httpx transport, for tests or proxies. |
+
+### Errors
+
+Every response the client cannot turn into data raises a `MythicMCError`. `status` is
+the HTTP status; `message` is the API's `error` string, or a stand-in when the
+response carried none.
+
+| Class | Status | |
+| --- | --- | --- |
+| `BadRequestError` | 400 | Not a valid username or UUID. |
+| `AuthenticationError` | 401 | Missing or invalid key. |
+| `NotFoundError` | 404 | Unknown player or board, or no published Survival statistics. |
+| `RateLimitError` | 429 | Retries exhausted. `retry_after` is seconds, or `None`. |
+| `UnavailableError` | 503 | Not published yet, an ambiguous username, or a server fault. Retrying later can work. |
+
+Any other status, and a 2xx whose body is not the shape the model declares, raises
+`MythicMCError` itself. Network failures and timeouts raise httpx's own exceptions.
+
+### Examples
+
+[examples](examples) holds one file per group of endpoints, plus `async_lookup.py`
+for `AsyncMythicMC`.
+
+```sh
+pip install .
+MYTHICMC_API_KEY=mmc_... python examples/get_player.py Vicente_1313
+```
+
+Set `MYTHICMC_API_URL` to run them against a mock server instead of the live API.
+
+### Development
+
+```sh
+pip install -e .
+python -m unittest discover -s tests
+```

mythicmc_sdk-0.1.0/examples/async_lookup.py

@@ -0,0 +1,27 @@
+import asyncio
+import os
+import sys
+
+from mythicmc import DEFAULT_BASE_URL, AsyncMythicMC
+
+key = os.environ["MYTHICMC_API_KEY"]
+base_url = os.environ.get("MYTHICMC_API_URL", DEFAULT_BASE_URL)
+
+
+async def main(player: str) -> None:
+    async with AsyncMythicMC(key, base_url=base_url) as api:
+        profile, progression, team = await asyncio.gather(
+            api.get_player(player),
+            api.get_player_progression(player),
+            api.get_player_team(player),
+        )
+
+    print(f"[{profile.rank.label}] {profile.name}: network level {progression.level}")
+    print("team:", team.team.name if team.team else "none")
+
+    # Separate cache entries can have different cutoffs; show the oldest.
+    cutoffs = [reply.meta.data_as_of for reply in (profile, progression, team) if reply.meta.data_as_of]
+    print("data as of:", min(cutoffs) if cutoffs else "unknown")
+
+
+asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "Vicente_1313"))

mythicmc_sdk-0.1.0/examples/get_leaderboards.py

@@ -0,0 +1,22 @@
+import os
+
+from mythicmc import DEFAULT_BASE_URL, MythicMC
+
+key = os.environ["MYTHICMC_API_KEY"]
+base_url = os.environ.get("MYTHICMC_API_URL", DEFAULT_BASE_URL)
+
+with MythicMC(key, base_url=base_url) as api:
+    index = api.list_leaderboards()
+    board = api.get_leaderboard("kills", "weekly")
+
+for board_type, periods in index.boards.items():
+    print(f"{board_type}: {', '.join(periods)}")
+
+# Periods use America/New_York time; weeks start on Friday.
+print(f"\nkills / weekly, {board.window_start} to {board.window_end}")
+if board.stale:
+    print("this board is stale")
+
+# Values are formatted strings. Use player stats for calculations.
+for row in board.rows:
+    print(f"#{row.rank} {row.name}: {row.value}")

mythicmc_sdk-0.1.0/examples/get_player.py

@@ -0,0 +1,23 @@
+import os
+import sys
+from datetime import datetime, timezone
+
+from mythicmc import DEFAULT_BASE_URL, MythicMC
+
+key = os.environ["MYTHICMC_API_KEY"]
+base_url = os.environ.get("MYTHICMC_API_URL", DEFAULT_BASE_URL)
+player = sys.argv[1] if len(sys.argv) > 1 else "Vicente_1313"
+
+with MythicMC(key, base_url=base_url) as api:
+    profile = api.get_player(player)  # username or UUID
+
+print(f"[{profile.rank.label}] {profile.name} ({profile.uuid})")
+
+print("online:", "unknown" if profile.online is None else profile.online)
+print("gamemode:", profile.location.gamemode if profile.location else "unknown")
+print("network level:", profile.level if profile.level is not None else "unknown")
+print("team:", profile.team.name if profile.team else "none")
+
+last_login = profile.last_login
+print("last login:", datetime.fromtimestamp(last_login / 1000, timezone.utc) if last_login is not None else "unknown")
+print("data as of:", profile.meta.data_as_of or "unknown")

mythicmc_sdk-0.1.0/examples/get_player_crate_keys.py

@@ -0,0 +1,18 @@
+import os
+import sys
+
+from mythicmc import DEFAULT_BASE_URL, MythicMC
+
+key = os.environ["MYTHICMC_API_KEY"]
+base_url = os.environ.get("MYTHICMC_API_URL", DEFAULT_BASE_URL)
+player = sys.argv[1] if len(sys.argv) > 1 else "Vicente_1313"
+
+with MythicMC(key, base_url=base_url) as api:
+    crate_keys = api.get_player_crate_keys(player).keys
+
+# Missing crates and unpublished balances are unknown, not zero.
+for crate_key in crate_keys:
+    available = crate_key.available
+    print(f"{crate_key.crate_id} ({crate_key.key_type}): {available if available is not None else 'unknown'}")
+if not crate_keys:
+    print(f"no crate key balances are published for {player}")

mythicmc_sdk-0.1.0/examples/get_player_progression.py

@@ -0,0 +1,19 @@
+import os
+import sys
+
+from mythicmc import DEFAULT_BASE_URL, MythicMC
+
+key = os.environ["MYTHICMC_API_KEY"]
+base_url = os.environ.get("MYTHICMC_API_URL", DEFAULT_BASE_URL)
+player = sys.argv[1] if len(sys.argv) > 1 else "Vicente_1313"
+
+with MythicMC(key, base_url=base_url) as api:
+    progression = api.get_player_progression(player)
+
+print(f"level {progression.level}, {progression.experience} XP in total")
+
+# Progress and target are XP within the current level.
+print("max level" if progression.maxed else f"{progression.progress} / {progression.target} XP to the next level")
+
+achievements = progression.achievements
+print("achievements:", f"{sum(a.complete for a in achievements)} of {len(achievements)}" if achievements else "unknown")

mythicmc_sdk-0.1.0/examples/get_player_stats.py

@@ -0,0 +1,25 @@
+import os
+import sys
+
+from mythicmc import DEFAULT_BASE_URL, MythicMC, NotFoundError
+
+key = os.environ["MYTHICMC_API_KEY"]
+base_url = os.environ.get("MYTHICMC_API_URL", DEFAULT_BASE_URL)
+player = sys.argv[1] if len(sys.argv) > 1 else "Vicente_1313"
+
+try:
+    with MythicMC(key, base_url=base_url) as api:
+        survival = api.get_player_stats(player).survival
+except NotFoundError as error:
+    sys.exit(f"no Survival statistics for {player}: {error.message}")
+
+combat = survival.combat
+print(f"kills {combat.kills}, deaths {combat.deaths}, K/D {combat.kills / max(combat.deaths, 1):.2f}")
+print("blocks mined:", survival.world.blocks_mined)
+
+# Missing groups are unknown, not zero.
+net_worth = survival.net_worth
+print("net worth:", f"${net_worth.total} (#{net_worth.rank})" if net_worth else "unknown")
+print("balance:", survival.money if survival.money is not None else "unknown")
+events = survival.events
+print("events won:", events.wins.bingo + events.wins.raffle if events else "unknown")

mythicmc_sdk-0.1.0/examples/get_player_team.py

@@ -0,0 +1,17 @@
+import os
+import sys
+
+from mythicmc import DEFAULT_BASE_URL, MythicMC
+
+key = os.environ["MYTHICMC_API_KEY"]
+base_url = os.environ.get("MYTHICMC_API_URL", DEFAULT_BASE_URL)
+player = sys.argv[1] if len(sys.argv) > 1 else "Vicente_1313"
+
+with MythicMC(key, base_url=base_url) as api:
+    reply = api.get_player_team(player)
+
+team = reply.team
+if team is None:
+    print(f"{reply.name} is not in a team")
+else:
+    print(f"{reply.name} is in [{team.prefix}] {team.name}, team level {team.level}, role {team.role or 'unknown'}")

mythicmc_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+# PEP 639 license metadata requires hatchling 1.27+.
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mythicmc-sdk"
+version = "0.1.0"
+description = "Official Python client for the MythicMC Public API."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "MythicMC" }]
+dependencies = ["httpx>=0.25,<1"]
+keywords = ["mythicmc", "minecraft", "api", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://github.com/mythicmcnetwork/mythicmc-sdk#readme"
+Repository = "https://github.com/mythicmcnetwork/mythicmc-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mythicmc"]

mythicmc_sdk-0.1.0/src/mythicmc/__init__.py

@@ -0,0 +1,84 @@
+from .client import DEFAULT_BASE_URL, AsyncMythicMC, MythicMC, __version__
+from .errors import (
+    AuthenticationError,
+    BadRequestError,
+    MythicMCError,
+    NotFoundError,
+    RateLimitError,
+    UnavailableError,
+)
+from .models import (
+    Achievement,
+    AuctionStats,
+    BountyStats,
+    CombatStats,
+    Cosmetics,
+    CrateKey,
+    EventStats,
+    EventWins,
+    Health,
+    Leaderboard,
+    LeaderboardIndex,
+    LeaderboardPeriod,
+    LeaderboardRow,
+    LeaderboardType,
+    Location,
+    NetWorth,
+    PlayerCrateKeys,
+    PlayerProfile,
+    PlayerProgression,
+    PlayerStats,
+    PlayerTeam,
+    Rank,
+    ResponseMeta,
+    SelectedCosmetic,
+    Skin,
+    StatRanks,
+    SurvivalStats,
+    TeamRole,
+    TeamSummary,
+    WorldStats,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncMythicMC",
+    "MythicMC",
+    "__version__",
+    "AuthenticationError",
+    "BadRequestError",
+    "MythicMCError",
+    "NotFoundError",
+    "RateLimitError",
+    "UnavailableError",
+    "Achievement",
+    "AuctionStats",
+    "BountyStats",
+    "CombatStats",
+    "Cosmetics",
+    "CrateKey",
+    "EventStats",
+    "EventWins",
+    "Health",
+    "Leaderboard",
+    "LeaderboardIndex",
+    "LeaderboardPeriod",
+    "LeaderboardRow",
+    "LeaderboardType",
+    "Location",
+    "NetWorth",
+    "PlayerCrateKeys",
+    "PlayerProfile",
+    "PlayerProgression",
+    "PlayerStats",
+    "PlayerTeam",
+    "Rank",
+    "ResponseMeta",
+    "SelectedCosmetic",
+    "Skin",
+    "StatRanks",
+    "SurvivalStats",
+    "TeamRole",
+    "TeamSummary",
+    "WorldStats",
+]