0
# pypresence
1

2
A comprehensive Discord RPC client library for Python that enables applications to integrate with Discord's Rich Presence system. Pypresence provides both synchronous and asynchronous implementations for displaying rich status information including activity names, details, timestamps, and custom images in users' Discord profiles.
3

4
## Package Information
5

6
- **Package Name**: pypresence
7
- **Language**: Python
8
- **Installation**: `pip install pypresence`
9
- **Python Requirements**: Python 3.8+
10
- **Cross-platform**: Windows, Linux, macOS
11

12
## Core Imports
13

14
```python
15
import pypresence
16
```
17

18
Common imports for specific functionality:
19

20
```python
21
from pypresence import Presence, AioPresence
22
from pypresence import Client, AioClient
23
from pypresence import PyPresenceException, DiscordNotFound
24
```
25

26
## Basic Usage
27

28
### Simple Rich Presence
29

30
```python
31
from pypresence import Presence
32
import time
33

34
# Connect to Discord
35
RPC = Presence("your_client_id_here")
36
RPC.connect()
37

38
# Update presence
39
RPC.update(state="Playing Solo", details="In Main Menu")
40

41
# Keep alive
42
while True:
43
    time.sleep(15)
44
```
45

46
### Async Rich Presence
47

48
```python
49
import asyncio
50
from pypresence import AioPresence
51

52
async def main():
53
    RPC = AioPresence("your_client_id_here")
54
    await RPC.connect()
55
    
56
    await RPC.update(
57
        state="In Game",
58
        details="Level 5 - Forest",
59
        large_image="game_logo",
60
        large_text="My Amazing Game",
61
        start=int(time.time())
62
    )
63
    
64
    # Keep alive
65
    while True:
66
        await asyncio.sleep(15)
67

68
asyncio.run(main())
69
```
70

71
## Architecture
72

73
Pypresence provides a layered architecture:
74

75
- **Presence/AioPresence**: Simplified clients focused on Rich Presence activities
76
- **Client/AioClient**: Full-featured RPC clients with Discord API access
77
- **BaseClient**: Core IPC communication and connection management
78
- **Payload**: Structured message builders for Discord RPC protocol
79
- **Exception Hierarchy**: Comprehensive error handling for all Discord integration scenarios
80

81
The library handles cross-platform IPC communication automatically, discovering Discord's pipe/socket connections on Windows, Linux, and macOS.
82

83
## Capabilities
84

85
### Rich Presence Management
86

87
Simple interface for updating Discord Rich Presence with activity information, timestamps, images, and party details.
88

89
```python { .api }
90
class Presence(BaseClient):
91
    def __init__(self, client_id: str, **kwargs): ...
92
    def connect(self): ...
93
    def update(self, pid: int = None, state: str = None, details: str = None,
94
               start: int = None, end: int = None,
95
               large_image: str = None, large_text: str = None,
96
               small_image: str = None, small_text: str = None,
97
               party_id: str = None, party_size: list = None,
98
               join: str = None, spectate: str = None,
99
               match: str = None, buttons: list = None,
100
               instance: bool = True, payload_override: dict = None): ...
101
    def clear(self, pid: int = None): ...
102
    def close(self): ...
103
```
104

105
```python { .api }
106
class AioPresence(BaseClient):
107
    def __init__(self, client_id: str, **kwargs): ...
108
    async def connect(self): ...
109
    async def update(self, pid: int = None, state: str = None, details: str = None,
110
                     start: int = None, end: int = None,
111
                     large_image: str = None, large_text: str = None,
112
                     small_image: str = None, small_text: str = None,
113
                     party_id: str = None, party_size: list = None,
114
                     join: str = None, spectate: str = None,
115
                     match: str = None, buttons: list = None,
116
                     instance: bool = True): ...
117
    async def clear(self, pid: int = None): ...
118
    def close(self): ...
119
```
120

121
[Rich Presence](./rich-presence.md)
122

123
### Discord RPC Client
124

125
Full Discord RPC client with support for authentication, guild/channel operations, voice settings, and event subscriptions.
126

127
```python { .api }
128
class Client(BaseClient):
129
    def __init__(self, client_id: str, **kwargs): ...
130
    def start(self): ...
131
    def authorize(self, client_id: str, scopes: list): ...
132
    def authenticate(self, token: str): ...
133
    def set_activity(self, pid: int = None, state: str = None, details: str = None, **kwargs): ...
134
    def get_guilds(self): ...
135
    def get_voice_settings(self): ...
136
    def register_event(self, event: str, func: callable, args: dict = None): ...
137
    def close(self): ...
138
```
139

140
```python { .api }
141
class AioClient(BaseClient):
142
    def __init__(self, client_id: str, **kwargs): ...
143
    async def start(self): ...
144
    async def authorize(self, client_id: str, scopes: list): ...
145
    async def authenticate(self, token: str): ...
146
    async def set_activity(self, pid: int = None, state: str = None, details: str = None, **kwargs): ...
147
    async def get_guilds(self): ...
148
    async def get_voice_settings(self): ...
149
    async def register_event(self, event: str, func: callable, args: dict = None): ...
150
    def close(self): ...
151
```
152

153
[Discord RPC Client](./discord-rpc-client.md)
154

155
### Exception Handling
156

157
Comprehensive exception hierarchy for handling Discord integration errors.
158

159
```python { .api }
160
class PyPresenceException(Exception):
161
    def __init__(self, message: str = None): ...
162

163
class DiscordNotFound(PyPresenceException): ...
164
class InvalidPipe(PyPresenceException): ...
165
class InvalidArgument(PyPresenceException): ...
166
class ServerError(PyPresenceException): ...
167
class DiscordError(PyPresenceException): ...
168
class InvalidID(DiscordError): ...
169
class PipeClosed(PyPresenceException): ...
170
class ResponseTimeout(PyPresenceException): ...
171
class ConnectionTimeout(PyPresenceException): ...
172
```
173

174
[Exception Handling](./exceptions.md)
175

176
## Types
177

178
```python { .api }
179
class BaseClient:
180
    """Base client for Discord RPC communication"""
181
    def __init__(self, client_id: str, loop=None, handler=None, 
182
                 pipe=None, isasync: bool = False,
183
                 connection_timeout: int = 30, response_timeout: int = 10): ...
184
    
185
    def update_event_loop(self, loop): ...
186
    async def read_output(self): ...
187
    def send_data(self, op: int, payload): ...
188
    async def handshake(self): ...
189
```
190

191
```python { .api }
192
class Payload:
193
    """Discord RPC payload builder"""
194
    def __init__(self, data: dict, clear_none: bool = True): ...
195
    
196
    @staticmethod
197
    def time() -> float: ...
198
    
199
    @classmethod
200
    def set_activity(cls, pid: int = None, state: str = None, 
201
                     details: str = None, **kwargs) -> 'Payload': ...
202
```