73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
# dpy_appemojis
|
||
|
||
Mirror a project folder onto your bot's **application emojis** (bot-owned, usable in any
|
||
guild the app is in — not guild emojis) for discord.py. Drop an image in `assets/emojis`,
|
||
call `refresh()`, and it becomes an application emoji named after the file. The folder is the
|
||
source of truth: a file removed means its emoji is deleted.
|
||
|
||
## Install
|
||
|
||
```
|
||
dpy_appemojis @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_appemojis.git@v0.1.0
|
||
```
|
||
|
||
## Usage
|
||
|
||
```python
|
||
from dpy_appemojis import DPYAppEmojis
|
||
|
||
appmojis = DPYAppEmojis(bot)
|
||
await appmojis.refresh() # e.g. in setup_hook / on_ready
|
||
|
||
await ctx.send(f"done {appmojis.get.success_mark}") # dot-access -> discord.Emoji
|
||
appmojis.emoji("success_mark").url # explicit accessor
|
||
appmojis.list() # ["success_mark", ...]
|
||
```
|
||
|
||
`refresh()` makes the app's emoji set **mirror** `assets/emojis`:
|
||
|
||
- a **new file** → the emoji is created (name = filename stem)
|
||
- a **removed file** → its emoji is deleted server-side
|
||
- a **same-name** emoji → left alone (this lib does **not** diff image content; to replace an
|
||
image, rename the file or delete + re-add)
|
||
|
||
Call `refresh()` at startup, or from a command, to re-sync on demand — the lib adds no
|
||
commands of its own.
|
||
|
||
## Dot-access vs `emoji()`
|
||
|
||
`self.get` is a namespace whose attribute lookup returns the emoji by name. It lives apart
|
||
from the methods, so an emoji named `list` or `refresh` can't shadow them. For names that
|
||
aren't valid Python identifiers, use `emoji("name")`. `.url` comes free — `get.x` /
|
||
`emoji("x")` return a real `discord.Emoji`.
|
||
|
||
## Fixed constants (not configurable)
|
||
|
||
| | |
|
||
|---|---|
|
||
| Folder | `assets/emojis` (relative to cwd) |
|
||
| Extensions | `.png .jpg .jpeg .gif .webp` |
|
||
| Max file size | 256 KB (Discord's emoji limit) |
|
||
| Name rules | 2–32 chars, `[A-Za-z0-9_]` |
|
||
| App emoji cap | 2000 |
|
||
|
||
## What you inject
|
||
|
||
Your `discord.Client` / `commands.Bot`. Application-emoji methods live on the client
|
||
(`fetch_application_emojis` / `create_application_emoji`, added in discord.py 2.5), so this
|
||
targets **`discord.py>=2.5`**.
|
||
|
||
## Contract (fail-loud)
|
||
|
||
The module docstring (`help(dpy_appemojis)` / IDE hover) is the source of truth. Nothing is
|
||
swallowed: an invalid emoji name from a bad filename or an oversized file raises `ValueError`
|
||
naming the file; exceeding the 2000 cap raises `DPYAppEmojisError` **before** any create; a
|
||
discord API error (`Forbidden` / `HTTPException`) propagates **unwrapped** so a partial sync
|
||
never hides behind a silent success. `emoji(name)` / `get.<name>` for a name that wasn't
|
||
synced raise `KeyError` / `AttributeError` (call `refresh()` first).
|
||
|
||
## Versioning
|
||
|
||
Tagged `vX.Y.Z`; pin a tag in your install line. Targets `discord.py>=2.5` (not
|
||
`discord.py-self`).
|