Use a NamedTuple for Slot data

- Cache the classes for FixedBitset
- Create an `AdvancementFrame` IntEnum
- Use attrs' validators and convertors

Author: LiteApplication

changes/297.feature.md

@@ -1,4 +1,5 @@
 - Added more types to the implementation:
+
   - `Angle`: Represents an angle.
   - `BitSet`: Represents a set of bits of variable length.
   - `FixedBitSet`: Represents a set of bits of fixed length.
@@ -10,4 +11,7 @@
   - `Vec3`: Represents a 3D vector.
   - `Position`: Represents a position with packed integers.
   - `EntityMetadata`: Represents metadata for an entity.
-  > There are **A LOT** of different entity metadata types, so I'm not going to list them all here.
+    > There are **A LOT** of different entity metadata types, so I'm not going to list them all here.
+
+- Removed the `validate` method from most `Serializable` classes.
+  - Make use of validators and convertors from the `attrs` library instead.

docs/api/types/general.rst

@@ -7,5 +7,5 @@ Here are documented the general types used throughout the Minecraft protocol.
     :no-undoc-members:
     :exclude-members: NBTag, StringNBT, CompoundNBT, EndNBT, EntityMetadata, UUID
 
-.. autoclass:: mcproto.types.UUID
-    :class-doc-from: class
+    .. autoclass:: mcproto.types.UUID
+        :class-doc-from: class

docs/conf.py

@@ -17,7 +17,7 @@
 from packaging.version import parse as parse_version
 from typing_extensions import override
 
-from mcproto.types.entity.metadata import _ProxyEntityMetadataEntry, _DefaultEntityMetadataEntry
+from mcproto.types.entity.metadata import _DefaultEntityMetadataEntry, _ProxyEntityMetadataEntry
 
 if sys.version_info >= (3, 11):
     from tomllib import load as toml_parse

mcproto/packets/handshaking/handshake.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from enum import IntEnum
-from typing import ClassVar, cast, final
+from typing import ClassVar, final
 
 from attrs import define
 from typing_extensions import Self, override
@@ -42,19 +42,11 @@ class Handshake(ServerBoundPacket):
     protocol_version: int
     server_address: str
     server_port: int
-    next_state: NextState | int
-
-    @override
-    def __attrs_post_init__(self) -> None:
-        if not isinstance(self.next_state, NextState):
-            self.next_state = NextState(self.next_state)
-
-        super().__attrs_post_init__()
+    next_state: NextState
 
     @override
     def serialize_to(self, buf: Buffer) -> None:
         """Serialize the packet."""
-        self.next_state = cast(NextState, self.next_state)  # Handled by the __attrs_post_init__ method
         buf.write_varint(self.protocol_version)
         buf.write_utf(self.server_address)
         buf.write_value(StructFormat.USHORT, self.server_port)
@@ -67,5 +59,5 @@ def _deserialize(cls, buf: Buffer, /) -> Self:
             protocol_version=buf.read_varint(),
             server_address=buf.read_utf(),
             server_port=buf.read_value(StructFormat.USHORT),
-            next_state=buf.read_varint(),
+            next_state=NextState(buf.read_varint()),
         )

mcproto/packets/login/login.py

@@ -2,7 +2,7 @@
 
 from typing import ClassVar, cast, final
 
-from attrs import define
+from attrs import define, field
 from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
 from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat, load_der_public_key
@@ -71,16 +71,9 @@ class LoginEncryptionRequest(ClientBoundPacket):
     PACKET_ID: ClassVar[int] = 0x01
     GAME_STATE: ClassVar[GameState] = GameState.LOGIN
 
-    public_key: RSAPublicKey
-    verify_token: bytes
-    server_id: str | None = None
-
-    @override
-    def __attrs_post_init__(self) -> None:
-        if self.server_id is None:
-            self.server_id = " " * 20
-
-        super().__attrs_post_init__()
+    public_key: RSAPublicKey = field()
+    verify_token: bytes = field()
+    server_id: str | None = field(default=" " * 20)
 
     @override
     def serialize_to(self, buf: Buffer) -> None:
@@ -243,7 +236,7 @@ class LoginPluginResponse(ServerBoundPacket):
     GAME_STATE: ClassVar[GameState] = GameState.LOGIN
 
     message_id: int
-    data: bytes | None
+    data: bytes | None = None
 
     @override
     def serialize_to(self, buf: Buffer) -> None:

mcproto/packets/status/status.py

@@ -3,7 +3,7 @@
 import json
 from typing import Any, ClassVar, final
 
-from attrs import define
+from attrs import define, field
 from typing_extensions import Self, override
 
 from mcproto.buffer import Buffer
@@ -43,7 +43,7 @@ class StatusResponse(ClientBoundPacket):
     PACKET_ID: ClassVar[int] = 0x00
     GAME_STATE: ClassVar[GameState] = GameState.STATUS
 
-    data: dict[str, Any]  # JSON response data sent back to the client.
+    data: dict[str, Any] = field(validator=lambda self, _, value: json.dumps(value))
 
     @override
     def serialize_to(self, buf: Buffer) -> None:
@@ -56,11 +56,3 @@ def _deserialize(cls, buf: Buffer, /) -> Self:
         s = buf.read_utf()
         data_ = json.loads(s)
         return cls(data_)
-
-    @override
-    def validate(self) -> None:
-        # Ensure the data is serializable to JSON
-        try:
-            json.dumps(self.data)
-        except TypeError as exc:
-            raise ValueError("Data is not serializable to JSON.") from exc

mcproto/types/__init__.py

@@ -1,52 +1,57 @@
 from __future__ import annotations
 
 from mcproto.types.abc import MCType, Serializable
-from mcproto.types.advancement import Advancement, AdvancementProgress, AdvancementDisplay, AdvancementCriterion
+from mcproto.types.advancement import (
+    Advancement,
+    AdvancementCriterion,
+    AdvancementDisplay,
+    AdvancementFrame,
+    AdvancementProgress,
+)
 from mcproto.types.angle import Angle
 from mcproto.types.bitset import Bitset, FixedBitset
 from mcproto.types.block_entity import BlockEntity
 from mcproto.types.chat import JSONTextComponent, TextComponent
 from mcproto.types.entity import EntityMetadata
 from mcproto.types.identifier import Identifier
-from mcproto.types.map_icon import MapIcon, IconType
+from mcproto.types.map_icon import IconType, MapIcon
 from mcproto.types.modifier import ModifierData, ModifierOperation
-from mcproto.types.nbt import NBTag, CompoundNBT
+from mcproto.types.nbt import CompoundNBT, NBTag
 from mcproto.types.particle_data import ParticleData
 from mcproto.types.quaternion import Quaternion
 from mcproto.types.recipe import (
-    Recipe,
     ArmorDyeRecipe,
     BannerDuplicateRecipe,
     BlastingRecipe,
     BookCloningRecipe,
-    ShulkerBoxColoringRecipe,
     CampfireRecipe,
-    ShapedRecipe,
     DecoratedPotRecipe,
     FireworkRocketRecipe,
+    FireworkStarFadeRecipe,
+    FireworkStarRecipe,
+    Ingredient,
     MapCloningRecipe,
     MapExtendingRecipe,
+    Recipe,
     RepairItemRecipe,
+    ShapedRecipe,
     ShapelessRecipe,
     ShieldDecorationRecipe,
-    SmokingRecipe,
-    FireworkStarRecipe,
-    FireworkStarFadeRecipe,
-    Ingredient,
+    ShulkerBoxColoringRecipe,
     SmeltingRecipe,
     SmithingTransformRecipe,
     SmithingTrimRecipe,
-    TippedArrowRecipe,
+    SmokingRecipe,
     StoneCuttingRecipe,
     SuspiciousStewRecipe,
+    TippedArrowRecipe,
 )
-from mcproto.types.slot import Slot
 from mcproto.types.registry_tag import RegistryTag
+from mcproto.types.slot import Slot, SlotData
 from mcproto.types.trade import Trade
 from mcproto.types.uuid import UUID
 from mcproto.types.vec3 import Position, Vec3
 
-
 __all__ = [
     "MCType",
     "Serializable",
@@ -60,6 +65,7 @@
     "CompoundNBT",
     "Quaternion",
     "Slot",
+    "SlotData",
     "RegistryTag",
     "UUID",
     "Position",
@@ -74,6 +80,7 @@
     "AdvancementProgress",
     "AdvancementDisplay",
     "AdvancementCriterion",
+    "AdvancementFrame",
     "ModifierData",
     "ModifierOperation",
     "Recipe",

mcproto/types/advancement.py

@@ -1,24 +1,25 @@
 from __future__ import annotations
 
+from enum import IntEnum
 from typing import final
-from attrs import define
 
+from attrs import define
 from typing_extensions import override
 
 from mcproto.buffer import Buffer
 from mcproto.protocol import StructFormat
-from mcproto.types.identifier import Identifier
+from mcproto.types.abc import MCType
 from mcproto.types.chat import TextComponent
+from mcproto.types.identifier import Identifier
 from mcproto.types.slot import Slot
-from mcproto.types.abc import MCType
 
 
 @final
 @define
 class Advancement(MCType):
     """Represents an advancement in the game.
 
-    https://wiki.vg/Protocol#Update_Advancements
+    Non-standard type, see: `<https://wiki.vg/Protocol#Update_Advancements>`
 
     :param parent: The parent advancement.
     :type parent: :class:`~mcproto.types.identifier.Identifier`, optional
@@ -56,6 +57,14 @@ def deserialize(cls, buf: Buffer) -> Advancement:
         return cls(parent=parent, display=display, requirements=requirements, telemetry=telemetry)
 
 
+class AdvancementFrame(IntEnum):
+    """Represents the shape of the frame of an advancement in the GUI."""
+
+    TASK = 0
+    CHALLENGE = 1
+    GOAL = 2
+
+
 @final
 @define
 class AdvancementDisplay(MCType):
@@ -67,7 +76,8 @@ class AdvancementDisplay(MCType):
     :type description: :class:`~mcproto.types.chat.TextComponent`
     :param icon: The icon of the advancement.
     :type icon: :class:`~mcproto.types.slot.Slot`
-    :param frame: The frame of the advancement (0: task, 1: challenge, 2: goal).
+    :param frame: The frame of the advancement.
+    :type frame: :class:`AdvancementFrame`
     :param background: The background texture of the advancement.
     :type background: :class:`~mcproto.types.identifier.Identifier`, optional
     :param show_toast: Whether to show a toast notification.
@@ -83,7 +93,7 @@ class AdvancementDisplay(MCType):
     title: TextComponent
     description: TextComponent
     icon: Slot
-    frame: int
+    frame: AdvancementFrame
     background: Identifier | None
     show_toast: bool
     hidden: bool
@@ -95,7 +105,7 @@ def serialize_to(self, buf: Buffer) -> None:
         self.title.serialize_to(buf)
         self.description.serialize_to(buf)
         self.icon.serialize_to(buf)
-        buf.write_varint(self.frame)
+        buf.write_varint(self.frame.value)
 
         flags = (self.background is not None) << 0 | self.show_toast << 1 | self.hidden << 2
         buf.write_value(StructFormat.BYTE, flags)
@@ -110,7 +120,7 @@ def deserialize(cls, buf: Buffer) -> AdvancementDisplay:
         title = TextComponent.deserialize(buf)
         description = TextComponent.deserialize(buf)
         icon = Slot.deserialize(buf)
-        frame = buf.read_varint()
+        frame = AdvancementFrame(buf.read_varint())
         flags = buf.read_value(StructFormat.BYTE)
         background = Identifier.deserialize(buf) if flags & 0x1 else None
         show_toast = bool(flags & 0x2)
@@ -166,7 +176,7 @@ class AdvancementCriterion(MCType):
     :type date: int, optional
     """
 
-    date: int | None
+    date: int | None = None
 
     @override
     def serialize_to(self, buf: Buffer) -> None:

mcproto/types/angle.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from typing import final
 import math
-from attrs import define
+from typing import final
 
+from attrs import define, field
 from typing_extensions import override
 
 from mcproto.buffer import Buffer
@@ -18,9 +18,12 @@ class Angle(MCType):
     """Represents a rotation angle for an entity.
 
     :param value: The angle value in 1/256th of a full rotation.
+    :type value: int
+
+    .. note:: The angle is stored as a byte, so the value is in the range [0, 255].
     """
 
-    angle: int
+    angle: int = field(converter=lambda x: int(x) % 256)
 
     @override
     def serialize_to(self, buf: Buffer) -> None:
@@ -36,11 +39,6 @@ def deserialize(cls, buf: Buffer) -> Angle:
         payload = buf.read_value(StructFormat.BYTE)
         return cls(angle=int(payload * 360 / 256))
 
-    @override
-    def validate(self) -> None:
-        """Constrain the angle to the range [0, 256)."""
-        self.angle %= 256
-
     def in_direction(self, base: Vec3, distance: float) -> Vec3:
         """Calculate the position in the direction of the angle in the xz-plane.