Add Object class and partial docs (#113)

disagreement/__init__.py

@@ -40,6 +40,7 @@ from .models import (
     Container,
     Guild,
 )
+from .object import Object
 from .voice_client import VoiceClient
 from .audio import AudioSource, FFmpegAudioSource
 from .typing import Typing
@@ -148,6 +149,7 @@ __all__ = [
     "MediaGallery",
     "MediaGalleryItem",
     "Container",
+    "Object",
     "VoiceClient",
     "AudioSource",
     "FFmpegAudioSource",

disagreement/object.py

@@ -0,0 +1,19 @@
+class Object:
+    """A minimal wrapper around a Discord snowflake ID."""
+
+    __slots__ = ("id",)
+
+    def __init__(self, object_id: int) -> None:
+        self.id = int(object_id)
+
+    def __int__(self) -> int:
+        return self.id
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Object) and self.id == other.id
+
+    def __repr__(self) -> str:
+        return f"<Object id={self.id}>"

docs/caching.md

@@ -28,6 +28,13 @@ The cache can be cleared manually if needed:
 client.cache.clear()
 ```
 
+## Partial Objects
+
+Some events only include minimal data for related resources. When only an ``id``
+is available, Disagreement represents the resource using :class:`~disagreement.Object`.
+These objects can be compared and used in sets or dictionaries and can be passed
+to API methods to fetch the full data when needed.
+
 ## Next Steps
 
 - [Components](using_components.md)

tests/test_object.py

@@ -0,0 +1,15 @@
+from disagreement.object import Object
+
+
+def test_object_int():
+    obj = Object(123)
+    assert int(obj) == 123
+
+
+def test_object_equality_and_hash():
+    a = Object(1)
+    b = Object(1)
+    c = Object(2)
+    assert a == b
+    assert a != c
+    assert hash(a) == hash(b)