README.md

---

Installation

# Install with httpx support
pip install "lanyard.py[httpx]"
# or (To work with WebSocket, select aiohttp)
pip install "lanyard.py[aiohttp]"

Quick Start

REST API

import asyncio
import logging
import sys

from lanyard import LanyardClient, LanyardData, HttpxProvider


async def main():
    async with LanyardClient(HttpxProvider()) as client:
        data: LanyardData = await client.get_user(338718840873811979)
        print(data["discord_user"]["username"])


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    asyncio.run(main())

WebSocket

import asyncio
import logging
import sys

from lanyard import LanyardClient, AiohttpProvider


async def main():
    async with LanyardClient(AiohttpProvider()) as client:
        async for data in client.subscribe(338718840873811979):
            print(data["discord_user"]["username"])


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    asyncio.run(main())

Available Methods

REST

Method	Description	Auth Required
get_user(user_id)	Retrieve presence data for a specific user.	No
get_me()	Retrieve presence data for the authenticated user.	Yes
set_kv(user_id, key, value)	Set a single key-value pair in Lanyard KV.	Yes
update_kv(user_id, data)	Bulk update/merge multiple KV pairs.	Yes
delete_kv(user_id, key)	Delete a key from Lanyard KV.	Yes

WebSocket

Method	Description
subscribe(*user_ids)	Subscribe to one or more user IDs.
subscribe(subscribe_to_all=True)	Subscribe to all users monitored by Lanyard.

Error Handling

The library uses a hierarchy of exceptions for granular error management:

• LanyardError: Base exception for all library-related errors.
• LanyardAPIError: Raised when the API returns an error or a non-200 status code.
• LanyardProviderError: Raised for network-related issues (timeouts, connection failures).
• LanyardUnauthorizedError: Raised when a token is missing or invalid.
• LanyardSocketError: Base class for WebSocket-related errors.
• LanyardSocketCloseError: Raised when the server closes the WebSocket with a specific error code.

Examples

Detailed implementation examples are available in the example/ directory:

• Basic REST usage
• Real-time monitoring via WebSockets

---