mcpy-core 1.0.0__py3-none-any.whl

mcpy_core-1.0.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: mcpy-core
+Version: 1.0.0
+Summary: Professional async-first Minecraft Java Edition protocol framework (1.20.2 – 1.21.11)
+Author: McPy-Core Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/mcpy-core
+Project-URL: Documentation, https://github.com/your-org/mcpy-core/blob/main/docs/quickstart.md
+Project-URL: Issues, https://github.com/your-org/mcpy-core/issues
+Project-URL: Changelog, https://github.com/your-org/mcpy-core/blob/main/CHANGELOG.md
+Keywords: minecraft,protocol,client,bot,async,asyncio,java-edition,mc,framework
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Dynamic: license-file
+
+# McPy-Core
+
+**Professional async-first Minecraft Java Edition protocol library.**
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![Protocol](https://img.shields.io/badge/MC%20protocol-764–775-green.svg)](https://wiki.vg/Protocol)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+McPy-Core is a clean, scalable, production-quality Minecraft protocol framework for Python 3.12+. Build bots, automation tools, custom clients, protocol research tools, and servers with a modern async API.
+
+```python
+import asyncio
+from mcpycore import MinecraftClient
+
+async def main():
+    client = MinecraftClient("play.example.com", username="BotName")
+
+    @client.event
+    async def on_chat(message, sender):
+        print(f"[{sender}] {message}")
+        if message == "ping":
+            await client.send_chat("pong!")
+
+    await client.start()
+
+asyncio.run(main())
+```
+
+---
+
+## Features
+
+| Feature | Details |
+|---|---|
+| **Async-first** | Built on `asyncio` — no threads, no blocking calls |
+| **Event-driven API** | `@client.event` decorators or `client.on(event, handler)` |
+| **Multi-version** | Minecraft 1.20.2 → 1.21.11 (protocols 764–775 + snapshots) |
+| **Packet system** | Typed packets with `@packet` decorator + auto-registration |
+| **Encryption** | AES-128-CFB8 (online & offline mode) |
+| **Compression** | zlib with configurable threshold |
+| **Reconnect policies** | Fixed delay, exponential back-off, infinite retry |
+| **Extension system** | Plugin modules with `setup()` / `teardown()` |
+| **Packet inspector** | Real-time `[RECV]`/`[SEND]` logging + hex dump |
+| **Metrics** | Latency tracking, packet counters, uptime |
+| **NBT parser** | All 13 tag types, nested compounds, `nbt_to_dict()` |
+| **Strong typing** | Full type hints throughout |
+| **Test suite** | 200+ tests with zero external dependencies |
+
+---
+
+## Installation
+
+```bash
+pip install mcpy-core
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/your-org/mcpy-core.git
+cd mcpy-core
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python 3.12+, `cryptography`
+
+---
+
+## Quick Examples
+
+### Server status ping (no login required)
+
+```python
+from examples.server_status import ping
+import asyncio
+
+data = asyncio.run(ping("play.hypixel.net"))
+print(data["version"]["name"])        # "Paper 1.21.1"
+print(data["players"]["online"])      # 45000
+print(f"{data['latency_ms']}ms")
+```
+
+### Position + movement
+
+```python
+@client.event
+async def on_spawn(x, y, z):
+    print(f"Spawned at ({x:.1f}, {y:.1f}, {z:.1f})")
+    await client.move(x + 5, y, z)
+    await client.look(yaw=90.0, pitch=-20.0)
+```
+
+### Auto-reconnect
+
+```python
+from mcpycore.client.reconnect import ExponentialBackoff
+
+client = MinecraftClient(
+    "play.example.com",
+    reconnect_policy=ExponentialBackoff(base_delay=1.0, max_delay=60.0),
+)
+```
+
+### Custom packets
+
+```python
+from mcpycore import Packet, packet, PacketBuffer, State
+from mcpycore.protocol.registry.registry import Direction
+
+@packet(packet_id=0x05, state=State.PLAY, direction=Direction.SERVERBOUND)
+class ChatMessage(Packet):
+    message: str = ""
+
+    def encode(self) -> bytes:
+        buf = PacketBuffer()
+        buf.write_string(self.message)
+        return buf.flush()
+```
+
+### Extensions / plugins
+
+```python
+# greet_extension.py
+async def setup(client):
+    @client.on("spawn")
+    async def on_spawn(x, y, z):
+        await client.send_chat("Hello from my extension!")
+
+async def teardown(client):
+    print("Extension unloaded")
+```
+
+```python
+client.load_extension("greet_extension")
+client.unload_extension("greet_extension")
+```
+
+---
+
+## Project Structure
+
+```
+mcpycore/
+├── client/
+│   ├── client.py       ← MinecraftClient — high-level async API
+│   ├── connection.py   ← TCP handshake → login → play lifecycle
+│   └── reconnect.py    ← Reconnect policy hierarchy
+├── protocol/
+│   ├── packets/
+│   │   └── base.py     ← Packet base + @packet decorator
+│   ├── serializers/
+│   │   ├── buffer.py   ← PacketBuffer (all primitives)
+│   │   └── nbt.py      ← NBT parser
+│   ├── registry/
+│   │   └── registry.py ← PacketRegistry (version-aware)
+│   ├── states/
+│   │   └── machine.py  ← Protocol state machine
+│   ├── handlers/
+│   │   └── dispatcher.py ← PacketDispatcher + middleware
+│   └── versions/
+│       ├── base.py     ← VersionAdapter + version constants
+│       ├── v1_20/      ← ID tables for protocols 764–766
+│       └── v1_21/      ← ID tables for protocols 767–775
+├── network/
+│   └── stream.py       ← AsyncStream (framing/crypto/compression)
+├── events/
+│   └── emitter.py      ← AsyncEventEmitter + Events constants
+├── crypto/
+│   └── encryption.py   ← EncryptionManager (AES-128-CFB8)
+├── compression/
+│   └── compression.py  ← CompressionManager (zlib)
+├── debug/
+│   └── inspector.py    ← PacketInspector (debug logging)
+├── extensions/
+│   └── loader.py       ← ExtensionLoader (plugin system)
+└── utils/
+    ├── logging.py      ← Structured colour logging
+    └── metrics.py      ← MetricsCollector
+tests/                  ← pytest suite (200+ tests)
+examples/               ← Runnable example scripts
+docs/                   ← quickstart.md, architecture.md
+```
+
+---
+
+## Supported Versions
+
+| Minecraft Version | Protocol |
+|---|---|
+| 1.20.2 | 764 |
+| 1.20.4 | 765 |
+| 1.20.6 | 766 |
+| 1.21 / 1.21.1 | 767 |
+| 1.21.2 / 1.21.3 | 768 |
+| 1.21.4 | 769 |
+| 1.21.5–1.21.11 | 770–775 |
+| Snapshots | Auto-fallback to nearest stable |
+
+---
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+The suite covers: `PacketBuffer`, NBT, events, compression, encryption, state machine, registry, dispatcher, client, and metrics.
+
+---
+
+## Documentation
+
+- [`docs/quickstart.md`](docs/quickstart.md) — getting started guide
+- [`docs/architecture.md`](docs/architecture.md) — design overview and layer diagram
+
+---
+
+## License
+
+MIT

mcpy_core-1.0.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+mcpy_core-1.0.0.dist-info/licenses/LICENSE,sha256=4p7bNMCZN8XNXVZDUkvC-D-EID9iF1A3vl_wNExzCeA,1078
+mcpycore/__init__.py,sha256=TTR0cVdGCp77PTdPVgKr032izaVlts9gAFlQcsyKPMU,3704
+mcpycore/client/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/client/client.py,sha256=tr2_Iq2mztXN_nApcoZ3GMS8hCGMF7-mToGwROU_Kmw,24596
+mcpycore/client/connection.py,sha256=XxJAhd9w3nDSS9SCBD26VBs62dvi76onFu6aBJKNpRE,9960
+mcpycore/client/reconnect.py,sha256=i9KLFXgidkAOy2VA1a-23L0CMnPtFNHuKglsvDP89Es,3394
+mcpycore/compression/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/compression/compression.py,sha256=75ASfrAUNWc2s7nF_O_hslXbD4RXEEcPpG5gflQghkk,3787
+mcpycore/crypto/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/crypto/encryption.py,sha256=gAENVFu4OJy5QMPDedb1EDEM6kn8RBbutsIwn5_GZi8,3745
+mcpycore/debug/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/debug/inspector.py,sha256=guY2DHlb6lb4WPUnsIJWXOT7bZAzImaofT9wht6jWyQ,4245
+mcpycore/events/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/events/emitter.py,sha256=Rb0WIVRXYsCgw12kWdRne1RyzOJD7CrbtnrMAzsFAWA,8714
+mcpycore/extensions/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/extensions/loader.py,sha256=k4OkzIn0DTMIr9L0L_C8aL4jYBtDQca2dpKyYoGbdwY,5071
+mcpycore/network/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/network/stream.py,sha256=PDmAKyhlc2JheRWcuYmIR_n9OsSk8PdxoKpc-USV0oQ,8376
+mcpycore/protocol/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/protocol/handlers/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/protocol/handlers/dispatcher.py,sha256=3q-ObXxauloEk0iY9SEhbI6nfPmqSjVK8s4w3q8uB7A,4990
+mcpycore/protocol/packets/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/protocol/packets/base.py,sha256=83r8O0IkwMdZPE8CDBAgRVxmxFlKQizu2dDIs1ahnFE,5846
+mcpycore/protocol/registry/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/protocol/registry/registry.py,sha256=54i0JRYheN4INWFjQeWz7GreHP1vE2bGZz9GN7mOq2I,4370
+mcpycore/protocol/serializers/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/protocol/serializers/buffer.py,sha256=xANJCoPVFH3I4Tmaz0QNA_nc2ZlZYd_Pfp-zeFu_LM8,12035
+mcpycore/protocol/serializers/nbt.py,sha256=vncDFBZwVOiA6yzfYfJk9xbpROPIgqqIjw1hHS1bdLo,7655
+mcpycore/protocol/states/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/protocol/states/machine.py,sha256=9YD6_AuFBdc8oojL68rw4rT4pJit_xXbPqoGhUPiXUA,3233
+mcpycore/protocol/versions/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/protocol/versions/base.py,sha256=_sTVJRYclo9veFfH7IsbAdGLmdJUnk16Orz2-AeV5r4,3757
+mcpycore/protocol/versions/adapters/__init__.py,sha256=64q3m7ZpZuWgWm0Lk_4anLqwjriCL7eT9Wb_PoAXdW8,1144
+mcpycore/protocol/versions/v1_20/__init__.py,sha256=oWTWfDnoQ4eMsNUSDCCXQe2XKbbmYhtr8aDyLXI-YpU,154
+mcpycore/protocol/versions/v1_20/packets.py,sha256=TNQg2_l_ahMuF-lZhcFLfr3897uKMnBpkSorywXeews,5434
+mcpycore/protocol/versions/v1_21/__init__.py,sha256=f9IxXPTmrMGKulF2baGq1UrERYMcm21xAlRUiE5Cq8M,154
+mcpycore/protocol/versions/v1_21/packets.py,sha256=8r86hPQrCfcJCdIBhGSSUW1MpmUAO4HuwxA4K6ElsGw,9220
+mcpycore/utils/__init__.py,sha256=BO7NcF4lYLwY2YgmLedwSHiCAHb841k8kxozhVZEjb8,29
+mcpycore/utils/logging.py,sha256=daejyFmI1ygR4wuLucFWKuNC4c6XQ73s7J_1eM2upF0,2518
+mcpycore/utils/metrics.py,sha256=yTJImUjp2orCmoM43dx75wGNrl1v0xOlE8yU1cigI3c,4619
+mcpy_core-1.0.0.dist-info/METADATA,sha256=3fepkhLOUMakYK64FpQbDk33zJb5NQ_E0CsVIJWdVrE,7874
+mcpy_core-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcpy_core-1.0.0.dist-info/top_level.txt,sha256=CCDfYa1t1mLjk7o-Vp0HaDcJyHWDUXm6129PG2yshks,9
+mcpy_core-1.0.0.dist-info/RECORD,,

mcpy_core-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcpy_core-1.0.0.dist-info/licenses/LICENSE

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

mcpy_core-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcpycore

mcpycore/__init__.py

@@ -0,0 +1,127 @@
+"""
+McPy-Core — Professional async-first Minecraft Java Edition protocol library.
+
+Supports Minecraft 1.20.2 → 1.21.11 (protocols 764–775) + snapshot builds.
+
+Quick start::
+
+    import asyncio
+    from mcpycore import MinecraftClient
+    from mcpycore.events.emitter import Events
+
+    async def main():
+        client = MinecraftClient(
+            host="play.example.com",
+            username="BotName",
+            debug=True,
+        )
+
+        @client.event
+        async def on_connect(c):
+            print(f"Connected! version={c.version_name}")
+
+        @client.event
+        async def on_chat(message, sender):
+            print(f"[{sender}] {message}")
+            await client.send_chat(f"Echo: {message}")
+
+        @client.event
+        async def on_disconnect(reason):
+            print(f"Disconnected: {reason}")
+
+        await client.start()
+
+    asyncio.run(main())
+"""
+
+from mcpycore.client.client import MinecraftClient
+from mcpycore.client.connection import (
+    PlayerProfile, OfflineProfile, LoginError, ConnectionError,
+)
+from mcpycore.client.reconnect import (
+    ReconnectPolicy, NoReconnect, FixedDelay,
+    ExponentialBackoff, InfiniteRetry,
+)
+from mcpycore.events.emitter import AsyncEventEmitter, Events
+from mcpycore.protocol.packets.base import Packet, packet
+from mcpycore.protocol.registry.registry import PacketRegistry, Direction, global_registry
+from mcpycore.protocol.serializers.buffer import PacketBuffer
+from mcpycore.protocol.serializers.nbt import (
+    parse_nbt, nbt_to_dict,
+    NBTTag, NBTCompound, NBTList, NBTInt, NBTString,
+    TAG_COMPOUND, TAG_INT, TAG_STRING,
+)
+from mcpycore.protocol.states.machine import State, ProtocolStateMachine
+from mcpycore.protocol.versions.base import (
+    VersionAdapter,
+    PROTOCOL_1_20_2, PROTOCOL_1_20_4, PROTOCOL_1_20_6,
+    PROTOCOL_1_21, PROTOCOL_1_21_1, PROTOCOL_1_21_2, PROTOCOL_1_21_4,
+    PROTOCOL_1_21_5, PROTOCOL_1_21_11,
+    PROTOCOL_LATEST, SNAPSHOT_BASE,
+    version_name, is_snapshot, nearest_stable, ALL_STABLE_PROTOCOLS,
+)
+from mcpycore.crypto.encryption import EncryptionManager
+from mcpycore.compression.compression import CompressionManager
+from mcpycore.debug.inspector import PacketInspector
+from mcpycore.utils.logging import setup_logging, get_logger
+from mcpycore.utils.metrics import MetricsCollector
+
+__version__      = "1.0.0"
+__author__       = "McPy-Core Contributors"
+__license__      = "MIT"
+__mc_versions__  = "1.20.2 – 1.21.11"
+__protocols__    = "764 – 775 + snapshots"
+__python_min__   = "3.12"
+
+__all__ = [
+    # Client
+    "MinecraftClient",
+    "PlayerProfile",
+    "OfflineProfile",
+    "LoginError",
+    "ConnectionError",
+    # Reconnect policies
+    "ReconnectPolicy",
+    "NoReconnect",
+    "FixedDelay",
+    "ExponentialBackoff",
+    "InfiniteRetry",
+    # Events
+    "AsyncEventEmitter",
+    "Events",
+    # Packets
+    "Packet",
+    "packet",
+    "PacketBuffer",
+    "PacketRegistry",
+    "Direction",
+    "global_registry",
+    # NBT
+    "parse_nbt",
+    "nbt_to_dict",
+    "NBTTag",
+    "NBTCompound",
+    "NBTList",
+    "NBTInt",
+    "NBTString",
+    "TAG_COMPOUND",
+    "TAG_INT",
+    "TAG_STRING",
+    # State machine
+    "State",
+    "ProtocolStateMachine",
+    # Versions
+    "VersionAdapter",
+    "PROTOCOL_1_20_2", "PROTOCOL_1_20_4", "PROTOCOL_1_20_6",
+    "PROTOCOL_1_21", "PROTOCOL_1_21_1", "PROTOCOL_1_21_2",
+    "PROTOCOL_1_21_4", "PROTOCOL_1_21_5", "PROTOCOL_1_21_11",
+    "PROTOCOL_LATEST", "SNAPSHOT_BASE",
+    "version_name", "is_snapshot", "nearest_stable", "ALL_STABLE_PROTOCOLS",
+    # Infrastructure
+    "EncryptionManager",
+    "CompressionManager",
+    "PacketInspector",
+    "setup_logging",
+    "get_logger",
+    "MetricsCollector",
+]

mcpycore/client/__init__.py

@@ -0,0 +1 @@
+"""McPy-Core sub-package."""