diff --git a/disagreement/__init__.py b/disagreement/__init__.py index fc44bfd..3c88eab 100644 --- a/disagreement/__init__.py +++ b/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", diff --git a/disagreement/object.py b/disagreement/object.py new file mode 100644 index 0000000..f4d6dfc --- /dev/null +++ b/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"" diff --git a/docs/caching.md b/docs/caching.md index 98bcc7d..f1add20 100644 --- a/docs/caching.md +++ b/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) diff --git a/tests/test_object.py b/tests/test_object.py new file mode 100644 index 0000000..03e60f0 --- /dev/null +++ b/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)