botpage 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- botpage-1.0.0/.gitignore +5 -0
- botpage-1.0.0/LICENSE +21 -0
- botpage-1.0.0/PKG-INFO +265 -0
- botpage-1.0.0/README.md +243 -0
- botpage-1.0.0/pyproject.toml +36 -0
- botpage-1.0.0/src/botpage/__init__.py +6 -0
- botpage-1.0.0/src/botpage/_client.py +271 -0
- botpage-1.0.0/src/botpage/_clock.py +7 -0
- botpage-1.0.0/src/botpage/_errors.py +17 -0
- botpage-1.0.0/src/botpage/py.typed +0 -0
- botpage-1.0.0/tests/__init__.py +0 -0
- botpage-1.0.0/tests/conftest.py +49 -0
- botpage-1.0.0/tests/test_cache.py +160 -0
- botpage-1.0.0/tests/test_client_options.py +24 -0
- botpage-1.0.0/tests/test_duplicate_merging.py +91 -0
- botpage-1.0.0/tests/test_errors.py +75 -0
- botpage-1.0.0/tests/test_rate_limiting.py +81 -0
- botpage-1.0.0/tests/test_requests.py +78 -0
- botpage-1.0.0/tests/test_session.py +86 -0
botpage-1.0.0/.gitignore
ADDED
botpage-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BotPage
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
botpage-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: botpage
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: The official async Python SDK for accessing your BotPage dashboard configurations.
|
|
5
|
+
Project-URL: Homepage, https://botpage.xyz
|
|
6
|
+
Project-URL: Documentation, https://botpage.xyz/docs
|
|
7
|
+
Author: BotPage
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: botpage,dashboard,discord,discord-bot,sdk
|
|
11
|
+
Classifier: Framework :: AsyncIO
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Typing :: Typed
|
|
14
|
+
Requires-Python: >=3.10
|
|
15
|
+
Requires-Dist: aiohttp>=3.9
|
|
16
|
+
Provides-Extra: dev
|
|
17
|
+
Requires-Dist: aiohttp<3.14; extra == 'dev'
|
|
18
|
+
Requires-Dist: aioresponses>=0.7.6; extra == 'dev'
|
|
19
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
|
|
20
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# botpage
|
|
24
|
+
|
|
25
|
+
The official async Python SDK for [BotPage](https://botpage.xyz). Use it to read and update each server's dashboard settings from your Discord bot.
|
|
26
|
+
|
|
27
|
+
The developer API is available to Premium bots. Full documentation: https://botpage.xyz/docs
|
|
28
|
+
|
|
29
|
+
## Installation
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pip install botpage
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Requires **Python 3.10+**. The only dependency is [aiohttp](https://docs.aiohttp.org/), which discord.py already uses, so installing the SDK adds nothing new to a discord.py bot.
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
import asyncio
|
|
41
|
+
from botpage import BotpageClient
|
|
42
|
+
|
|
43
|
+
async def main() -> None:
|
|
44
|
+
async with BotpageClient("your-api-key") as botpage:
|
|
45
|
+
# Read all settings for a Discord server
|
|
46
|
+
config = await botpage.get_guild_data("123456789012345678")
|
|
47
|
+
|
|
48
|
+
# Read a single field (None if it isn't set)
|
|
49
|
+
welcome_channel = await botpage.get_guild_field("123456789012345678", "welcomeChannel")
|
|
50
|
+
|
|
51
|
+
# Update a single field
|
|
52
|
+
await botpage.update_guild_field("123456789012345678", "prefix", "?")
|
|
53
|
+
|
|
54
|
+
asyncio.run(main())
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Guild IDs can be strings or ints, so you can pass discord.py's `guild.id` as it is.
|
|
58
|
+
|
|
59
|
+
## Using it with discord.py
|
|
60
|
+
|
|
61
|
+
Create the client at module level, read settings in your handlers, and close the client when the bot shuts down:
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
import os
|
|
65
|
+
|
|
66
|
+
import discord
|
|
67
|
+
from botpage import BotpageClient, BotpageError
|
|
68
|
+
|
|
69
|
+
intents = discord.Intents.default()
|
|
70
|
+
intents.message_content = True
|
|
71
|
+
|
|
72
|
+
botpage = BotpageClient(os.environ["BOTPAGE_API_KEY"])
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
class Bot(discord.Client):
|
|
76
|
+
async def close(self) -> None:
|
|
77
|
+
await botpage.close()
|
|
78
|
+
await super().close()
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
bot = Bot(intents=intents)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
@bot.event
|
|
85
|
+
async def on_message(message: discord.Message) -> None:
|
|
86
|
+
if message.author.bot or message.guild is None:
|
|
87
|
+
return
|
|
88
|
+
|
|
89
|
+
try:
|
|
90
|
+
prefix = await botpage.get_guild_field(message.guild.id, "prefix") or "!"
|
|
91
|
+
except BotpageError:
|
|
92
|
+
prefix = "!"
|
|
93
|
+
|
|
94
|
+
if message.content == f"{prefix}ping":
|
|
95
|
+
await message.reply("Pong!")
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
bot.run(os.environ["DISCORD_TOKEN"])
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Reads are cached for a few seconds, so calling `get_guild_field` in every message handler is fine. See https://botpage.xyz/docs for a full example bot.
|
|
102
|
+
|
|
103
|
+
## API reference
|
|
104
|
+
|
|
105
|
+
### `BotpageClient(api_key, *, ...)`
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
BotpageClient(
|
|
109
|
+
api_key,
|
|
110
|
+
*,
|
|
111
|
+
base_url="https://botpage.xyz/api/v1",
|
|
112
|
+
cache_ttl_seconds=5,
|
|
113
|
+
max_requests_per_minute=100,
|
|
114
|
+
auto_wait_on_rate_limit=False,
|
|
115
|
+
session=None,
|
|
116
|
+
)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
| Option | Default | Description |
|
|
120
|
+
| --- | --- | --- |
|
|
121
|
+
| `api_key` | (required) | Your developer API key from the BotPage dashboard. An empty key raises `ValueError`. |
|
|
122
|
+
| `base_url` | `"https://botpage.xyz/api/v1"` | The API's base URL. Change it to test against a staging or local instance. A trailing slash is ignored. |
|
|
123
|
+
| `cache_ttl_seconds` | `5` | How long reads are cached, per server. `0` turns the cache off. Negative values count as `0`. |
|
|
124
|
+
| `max_requests_per_minute` | `100` | The local rate limit. Values below `1` count as `1`. |
|
|
125
|
+
| `auto_wait_on_rate_limit` | `False` | When `True`, the client sleeps until it may send again instead of raising `BotpageRateLimitError`. |
|
|
126
|
+
| `session` | `None` | An `aiohttp.ClientSession` to use instead of one the client creates. The client never closes it. |
|
|
127
|
+
|
|
128
|
+
Creating the client doesn't open a connection, so you can create it at module level before the event loop starts.
|
|
129
|
+
|
|
130
|
+
### `await get_guild_data(guild_id, *, force=False) -> dict`
|
|
131
|
+
|
|
132
|
+
Returns all of a server's dashboard values as a dict.
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
config = await botpage.get_guild_data("123456789012345678")
|
|
136
|
+
# {"prefix": "!", "welcomeEnabled": True, "logsChannel": "987654321098765432"}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`force=True` skips the cache and fetches the latest values.
|
|
140
|
+
|
|
141
|
+
### `await get_guild_field(guild_id, field, *, force=False) -> Any`
|
|
142
|
+
|
|
143
|
+
Returns one value, or `None` if it isn't set. It uses the same cache as `get_guild_data`.
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
prefix = await botpage.get_guild_field("123456789012345678", "prefix")
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### `await update_guild_data(guild_id, updates) -> dict`
|
|
150
|
+
|
|
151
|
+
Updates several fields in one request and returns all of the server's values after the update.
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
updated = await botpage.update_guild_data(
|
|
155
|
+
"123456789012345678",
|
|
156
|
+
{"prefix": "?", "welcomeEnabled": False},
|
|
157
|
+
)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### `await update_guild_field(guild_id, field, value) -> dict`
|
|
161
|
+
|
|
162
|
+
Updates one field and returns all of the server's values after the update.
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
await botpage.update_guild_field("123456789012345678", "logsChannel", "987654321098765432")
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### `clear_cache(guild_id=None) -> None`
|
|
169
|
+
|
|
170
|
+
Forgets one server's cached values, or every server's when called with no ID. Use it after settings change somewhere else, such as on the dashboard, and you need the next read to fetch them. It isn't async.
|
|
171
|
+
|
|
172
|
+
```python
|
|
173
|
+
botpage.clear_cache("123456789012345678") # one server
|
|
174
|
+
botpage.clear_cache() # every server
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### `await close() -> None`
|
|
178
|
+
|
|
179
|
+
Closes the HTTP session the client created. Call it when your bot shuts down to avoid "Unclosed client session" warnings. A session passed through `session=` is left open. Calling `close()` more than once is safe, and a request made after `close()` opens a new session.
|
|
180
|
+
|
|
181
|
+
Every dict the client returns is a copy, so adding, removing or replacing its keys never affects the cache. The copy is shallow: nested lists and dicts are shared, so don't change those in place.
|
|
182
|
+
|
|
183
|
+
## Errors
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
from botpage import BotpageError, BotpageRateLimitError
|
|
187
|
+
|
|
188
|
+
try:
|
|
189
|
+
await botpage.update_guild_field(guild_id, "prefix", "?")
|
|
190
|
+
except BotpageRateLimitError as err:
|
|
191
|
+
print(f"Rate limited, retry in {err.retry_after:.1f}s")
|
|
192
|
+
except BotpageError as err:
|
|
193
|
+
print(f"BotPage request failed ({err.status}): {err}")
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
- **`BotpageError`** is raised for every SDK failure, so one `except BotpageError` catches them all. `status` is the HTTP status, or `None` for a network failure. The message includes the API's error text, for example an unknown field or a bot that isn't a Premium bot.
|
|
197
|
+
- **`BotpageRateLimitError`** is a subclass of `BotpageError` with `status` set to `429`. `retry_after` is how long to wait **in seconds** (a float).
|
|
198
|
+
|
|
199
|
+
## Caching
|
|
200
|
+
|
|
201
|
+
- Reads are cached in memory per server for `cache_ttl_seconds` (5 seconds by default). A read within that time makes no HTTP request.
|
|
202
|
+
- After an update, the cache holds the values the API returned, so your next read sees what you just wrote.
|
|
203
|
+
- Concurrent reads for the same server share one HTTP request, so a burst of events doesn't send a burst of identical calls.
|
|
204
|
+
- The cache holds at most 1000 servers. When it's full, expired entries are dropped first, then the oldest one.
|
|
205
|
+
- Use `force=True` to skip the cache for one read, `clear_cache()` to empty it, or `cache_ttl_seconds=0` to turn it off.
|
|
206
|
+
|
|
207
|
+
## Rate limiting
|
|
208
|
+
|
|
209
|
+
The client limits itself so it stops you before the API rejects you:
|
|
210
|
+
|
|
211
|
+
- At most `max_requests_per_minute` requests (100 by default) in any 60-second window. Cached reads don't count.
|
|
212
|
+
- When the API answers with a 429, the client respects its `Retry-After` header (10 seconds if missing) and sends nothing until then.
|
|
213
|
+
- When the API reports no remaining quota (`x-ratelimit-remaining: 0`), the client holds back for 5 seconds.
|
|
214
|
+
|
|
215
|
+
A request the API answers with a 429 always raises `BotpageRateLimitError`. After that, and whenever the local limit is reached, later calls raise `BotpageRateLimitError` without touching the network until the limit resets. With `auto_wait_on_rate_limit=True`, those later calls sleep until the limit resets and then send the request.
|
|
216
|
+
|
|
217
|
+
## Closing the client
|
|
218
|
+
|
|
219
|
+
Three ways to manage the HTTP session:
|
|
220
|
+
|
|
221
|
+
```python
|
|
222
|
+
# 1. Long-running bot: create once, close on shutdown.
|
|
223
|
+
botpage = BotpageClient(api_key)
|
|
224
|
+
...
|
|
225
|
+
await botpage.close()
|
|
226
|
+
|
|
227
|
+
# 2. Script: `async with` closes the session on exit.
|
|
228
|
+
async with BotpageClient(api_key) as botpage:
|
|
229
|
+
config = await botpage.get_guild_data(guild_id)
|
|
230
|
+
|
|
231
|
+
# 3. Your own aiohttp session: the client uses it and never closes it.
|
|
232
|
+
async with aiohttp.ClientSession() as session:
|
|
233
|
+
botpage = BotpageClient(api_key, session=session)
|
|
234
|
+
config = await botpage.get_guild_data(guild_id)
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The client reuses one session for all its requests, so connections are pooled.
|
|
238
|
+
|
|
239
|
+
## Type hints
|
|
240
|
+
|
|
241
|
+
The package ships type hints (`py.typed`), so editors autocomplete it and type checkers check your calls.
|
|
242
|
+
|
|
243
|
+
## Releasing
|
|
244
|
+
|
|
245
|
+
For maintainers. Publishing is done by hand.
|
|
246
|
+
|
|
247
|
+
1. Bump `version` in `pyproject.toml`.
|
|
248
|
+
2. Run the tests: `pip install -e ".[dev]"`, then `pytest`.
|
|
249
|
+
3. Build the wheel and sdist from this folder:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
pip install --upgrade build twine
|
|
253
|
+
rm -rf dist # PowerShell: Remove-Item -Recurse -Force dist
|
|
254
|
+
python -m build
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
4. Upload with a PyPI API token (create one at https://pypi.org/manage/account/token/). Twine reads the token from the environment:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... twine upload dist/*
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
## License
|
|
264
|
+
|
|
265
|
+
MIT
|
botpage-1.0.0/README.md
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# botpage
|
|
2
|
+
|
|
3
|
+
The official async Python SDK for [BotPage](https://botpage.xyz). Use it to read and update each server's dashboard settings from your Discord bot.
|
|
4
|
+
|
|
5
|
+
The developer API is available to Premium bots. Full documentation: https://botpage.xyz/docs
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install botpage
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Requires **Python 3.10+**. The only dependency is [aiohttp](https://docs.aiohttp.org/), which discord.py already uses, so installing the SDK adds nothing new to a discord.py bot.
|
|
14
|
+
|
|
15
|
+
## Quick start
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
import asyncio
|
|
19
|
+
from botpage import BotpageClient
|
|
20
|
+
|
|
21
|
+
async def main() -> None:
|
|
22
|
+
async with BotpageClient("your-api-key") as botpage:
|
|
23
|
+
# Read all settings for a Discord server
|
|
24
|
+
config = await botpage.get_guild_data("123456789012345678")
|
|
25
|
+
|
|
26
|
+
# Read a single field (None if it isn't set)
|
|
27
|
+
welcome_channel = await botpage.get_guild_field("123456789012345678", "welcomeChannel")
|
|
28
|
+
|
|
29
|
+
# Update a single field
|
|
30
|
+
await botpage.update_guild_field("123456789012345678", "prefix", "?")
|
|
31
|
+
|
|
32
|
+
asyncio.run(main())
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Guild IDs can be strings or ints, so you can pass discord.py's `guild.id` as it is.
|
|
36
|
+
|
|
37
|
+
## Using it with discord.py
|
|
38
|
+
|
|
39
|
+
Create the client at module level, read settings in your handlers, and close the client when the bot shuts down:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import os
|
|
43
|
+
|
|
44
|
+
import discord
|
|
45
|
+
from botpage import BotpageClient, BotpageError
|
|
46
|
+
|
|
47
|
+
intents = discord.Intents.default()
|
|
48
|
+
intents.message_content = True
|
|
49
|
+
|
|
50
|
+
botpage = BotpageClient(os.environ["BOTPAGE_API_KEY"])
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class Bot(discord.Client):
|
|
54
|
+
async def close(self) -> None:
|
|
55
|
+
await botpage.close()
|
|
56
|
+
await super().close()
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
bot = Bot(intents=intents)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@bot.event
|
|
63
|
+
async def on_message(message: discord.Message) -> None:
|
|
64
|
+
if message.author.bot or message.guild is None:
|
|
65
|
+
return
|
|
66
|
+
|
|
67
|
+
try:
|
|
68
|
+
prefix = await botpage.get_guild_field(message.guild.id, "prefix") or "!"
|
|
69
|
+
except BotpageError:
|
|
70
|
+
prefix = "!"
|
|
71
|
+
|
|
72
|
+
if message.content == f"{prefix}ping":
|
|
73
|
+
await message.reply("Pong!")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
bot.run(os.environ["DISCORD_TOKEN"])
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Reads are cached for a few seconds, so calling `get_guild_field` in every message handler is fine. See https://botpage.xyz/docs for a full example bot.
|
|
80
|
+
|
|
81
|
+
## API reference
|
|
82
|
+
|
|
83
|
+
### `BotpageClient(api_key, *, ...)`
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
BotpageClient(
|
|
87
|
+
api_key,
|
|
88
|
+
*,
|
|
89
|
+
base_url="https://botpage.xyz/api/v1",
|
|
90
|
+
cache_ttl_seconds=5,
|
|
91
|
+
max_requests_per_minute=100,
|
|
92
|
+
auto_wait_on_rate_limit=False,
|
|
93
|
+
session=None,
|
|
94
|
+
)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
| Option | Default | Description |
|
|
98
|
+
| --- | --- | --- |
|
|
99
|
+
| `api_key` | (required) | Your developer API key from the BotPage dashboard. An empty key raises `ValueError`. |
|
|
100
|
+
| `base_url` | `"https://botpage.xyz/api/v1"` | The API's base URL. Change it to test against a staging or local instance. A trailing slash is ignored. |
|
|
101
|
+
| `cache_ttl_seconds` | `5` | How long reads are cached, per server. `0` turns the cache off. Negative values count as `0`. |
|
|
102
|
+
| `max_requests_per_minute` | `100` | The local rate limit. Values below `1` count as `1`. |
|
|
103
|
+
| `auto_wait_on_rate_limit` | `False` | When `True`, the client sleeps until it may send again instead of raising `BotpageRateLimitError`. |
|
|
104
|
+
| `session` | `None` | An `aiohttp.ClientSession` to use instead of one the client creates. The client never closes it. |
|
|
105
|
+
|
|
106
|
+
Creating the client doesn't open a connection, so you can create it at module level before the event loop starts.
|
|
107
|
+
|
|
108
|
+
### `await get_guild_data(guild_id, *, force=False) -> dict`
|
|
109
|
+
|
|
110
|
+
Returns all of a server's dashboard values as a dict.
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
config = await botpage.get_guild_data("123456789012345678")
|
|
114
|
+
# {"prefix": "!", "welcomeEnabled": True, "logsChannel": "987654321098765432"}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`force=True` skips the cache and fetches the latest values.
|
|
118
|
+
|
|
119
|
+
### `await get_guild_field(guild_id, field, *, force=False) -> Any`
|
|
120
|
+
|
|
121
|
+
Returns one value, or `None` if it isn't set. It uses the same cache as `get_guild_data`.
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
prefix = await botpage.get_guild_field("123456789012345678", "prefix")
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### `await update_guild_data(guild_id, updates) -> dict`
|
|
128
|
+
|
|
129
|
+
Updates several fields in one request and returns all of the server's values after the update.
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
updated = await botpage.update_guild_data(
|
|
133
|
+
"123456789012345678",
|
|
134
|
+
{"prefix": "?", "welcomeEnabled": False},
|
|
135
|
+
)
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### `await update_guild_field(guild_id, field, value) -> dict`
|
|
139
|
+
|
|
140
|
+
Updates one field and returns all of the server's values after the update.
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
await botpage.update_guild_field("123456789012345678", "logsChannel", "987654321098765432")
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### `clear_cache(guild_id=None) -> None`
|
|
147
|
+
|
|
148
|
+
Forgets one server's cached values, or every server's when called with no ID. Use it after settings change somewhere else, such as on the dashboard, and you need the next read to fetch them. It isn't async.
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
botpage.clear_cache("123456789012345678") # one server
|
|
152
|
+
botpage.clear_cache() # every server
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### `await close() -> None`
|
|
156
|
+
|
|
157
|
+
Closes the HTTP session the client created. Call it when your bot shuts down to avoid "Unclosed client session" warnings. A session passed through `session=` is left open. Calling `close()` more than once is safe, and a request made after `close()` opens a new session.
|
|
158
|
+
|
|
159
|
+
Every dict the client returns is a copy, so adding, removing or replacing its keys never affects the cache. The copy is shallow: nested lists and dicts are shared, so don't change those in place.
|
|
160
|
+
|
|
161
|
+
## Errors
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
from botpage import BotpageError, BotpageRateLimitError
|
|
165
|
+
|
|
166
|
+
try:
|
|
167
|
+
await botpage.update_guild_field(guild_id, "prefix", "?")
|
|
168
|
+
except BotpageRateLimitError as err:
|
|
169
|
+
print(f"Rate limited, retry in {err.retry_after:.1f}s")
|
|
170
|
+
except BotpageError as err:
|
|
171
|
+
print(f"BotPage request failed ({err.status}): {err}")
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- **`BotpageError`** is raised for every SDK failure, so one `except BotpageError` catches them all. `status` is the HTTP status, or `None` for a network failure. The message includes the API's error text, for example an unknown field or a bot that isn't a Premium bot.
|
|
175
|
+
- **`BotpageRateLimitError`** is a subclass of `BotpageError` with `status` set to `429`. `retry_after` is how long to wait **in seconds** (a float).
|
|
176
|
+
|
|
177
|
+
## Caching
|
|
178
|
+
|
|
179
|
+
- Reads are cached in memory per server for `cache_ttl_seconds` (5 seconds by default). A read within that time makes no HTTP request.
|
|
180
|
+
- After an update, the cache holds the values the API returned, so your next read sees what you just wrote.
|
|
181
|
+
- Concurrent reads for the same server share one HTTP request, so a burst of events doesn't send a burst of identical calls.
|
|
182
|
+
- The cache holds at most 1000 servers. When it's full, expired entries are dropped first, then the oldest one.
|
|
183
|
+
- Use `force=True` to skip the cache for one read, `clear_cache()` to empty it, or `cache_ttl_seconds=0` to turn it off.
|
|
184
|
+
|
|
185
|
+
## Rate limiting
|
|
186
|
+
|
|
187
|
+
The client limits itself so it stops you before the API rejects you:
|
|
188
|
+
|
|
189
|
+
- At most `max_requests_per_minute` requests (100 by default) in any 60-second window. Cached reads don't count.
|
|
190
|
+
- When the API answers with a 429, the client respects its `Retry-After` header (10 seconds if missing) and sends nothing until then.
|
|
191
|
+
- When the API reports no remaining quota (`x-ratelimit-remaining: 0`), the client holds back for 5 seconds.
|
|
192
|
+
|
|
193
|
+
A request the API answers with a 429 always raises `BotpageRateLimitError`. After that, and whenever the local limit is reached, later calls raise `BotpageRateLimitError` without touching the network until the limit resets. With `auto_wait_on_rate_limit=True`, those later calls sleep until the limit resets and then send the request.
|
|
194
|
+
|
|
195
|
+
## Closing the client
|
|
196
|
+
|
|
197
|
+
Three ways to manage the HTTP session:
|
|
198
|
+
|
|
199
|
+
```python
|
|
200
|
+
# 1. Long-running bot: create once, close on shutdown.
|
|
201
|
+
botpage = BotpageClient(api_key)
|
|
202
|
+
...
|
|
203
|
+
await botpage.close()
|
|
204
|
+
|
|
205
|
+
# 2. Script: `async with` closes the session on exit.
|
|
206
|
+
async with BotpageClient(api_key) as botpage:
|
|
207
|
+
config = await botpage.get_guild_data(guild_id)
|
|
208
|
+
|
|
209
|
+
# 3. Your own aiohttp session: the client uses it and never closes it.
|
|
210
|
+
async with aiohttp.ClientSession() as session:
|
|
211
|
+
botpage = BotpageClient(api_key, session=session)
|
|
212
|
+
config = await botpage.get_guild_data(guild_id)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
The client reuses one session for all its requests, so connections are pooled.
|
|
216
|
+
|
|
217
|
+
## Type hints
|
|
218
|
+
|
|
219
|
+
The package ships type hints (`py.typed`), so editors autocomplete it and type checkers check your calls.
|
|
220
|
+
|
|
221
|
+
## Releasing
|
|
222
|
+
|
|
223
|
+
For maintainers. Publishing is done by hand.
|
|
224
|
+
|
|
225
|
+
1. Bump `version` in `pyproject.toml`.
|
|
226
|
+
2. Run the tests: `pip install -e ".[dev]"`, then `pytest`.
|
|
227
|
+
3. Build the wheel and sdist from this folder:
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
pip install --upgrade build twine
|
|
231
|
+
rm -rf dist # PowerShell: Remove-Item -Recurse -Force dist
|
|
232
|
+
python -m build
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
4. Upload with a PyPI API token (create one at https://pypi.org/manage/account/token/). Twine reads the token from the environment:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... twine upload dist/*
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
## License
|
|
242
|
+
|
|
243
|
+
MIT
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "botpage"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "The official async Python SDK for accessing your BotPage dashboard configurations."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
authors = [{ name = "BotPage" }]
|
|
14
|
+
keywords = ["botpage", "discord", "discord-bot", "dashboard", "sdk"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Framework :: AsyncIO",
|
|
18
|
+
"Typing :: Typed",
|
|
19
|
+
]
|
|
20
|
+
dependencies = ["aiohttp>=3.9"]
|
|
21
|
+
|
|
22
|
+
[project.optional-dependencies]
|
|
23
|
+
# aioresponses 0.7.9 breaks on aiohttp 3.14 (ClientResponse gained stream_writer), so tests pin below it.
|
|
24
|
+
dev = ["pytest>=8", "pytest-asyncio>=0.23", "aioresponses>=0.7.6", "aiohttp<3.14"]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://botpage.xyz"
|
|
28
|
+
Documentation = "https://botpage.xyz/docs"
|
|
29
|
+
|
|
30
|
+
[tool.hatch.build.targets.wheel]
|
|
31
|
+
packages = ["src/botpage"]
|
|
32
|
+
|
|
33
|
+
[tool.pytest.ini_options]
|
|
34
|
+
asyncio_mode = "auto"
|
|
35
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
36
|
+
testpaths = ["tests"]
|