init: mirror a project folder onto the bot's application emojis for discord.py

Signed-off-by: disqualifier <dev@disqualifier.me>
2026-07-02 19:59:13 -04:00
commit 77cfc6a10a
2 changed files with 87 additions and 0 deletions
@@ -0,0 +1,72 @@
+# 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`).