diff --git a/README.md b/README.md index b1868ab..c7e01d3 100644 --- a/README.md +++ b/README.md @@ -10,18 +10,18 @@ live from `bot.settings` so it can change at runtime via a command. `requirements.txt`: ``` -dpy_logger @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_logger.git@v0.1.6 +dpy_logger @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_logger.git@v0.1.7 ``` Direct: ```bash -pip install "dpy_logger @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_logger.git@v0.1.6" +pip install "dpy_logger @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_logger.git@v0.1.7" ``` Requires `discord.py` (pulled transitively). -Drop the `@v0.1.6` suffix from the line above to install the latest unpinned. +Drop the `@v0.1.7` suffix from the line above to install the latest unpinned. ## Usage diff --git a/pyproject.toml b/pyproject.toml index 0c0db46..69b2ec3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "dpy_logger" -version = "0.1.6" +version = "0.1.7" description = "Leveled Discord channel logger for discord.py — config-free, injectable, installable." requires-python = ">=3.10" dependencies = [ diff --git a/src/dpy_logger/dpy_logger.py b/src/dpy_logger/dpy_logger.py index 592fd47..a4da150 100644 --- a/src/dpy_logger/dpy_logger.py +++ b/src/dpy_logger/dpy_logger.py @@ -19,31 +19,22 @@ read live from bot.settings at call time (no restart needed). await bot.log.initialize() # resolves ids -> objects await bot.log.success("user promoted", action="promote", actor=ctx.author) -levels: debug, info, success, fail (alias failure), task, critical. +levels: debug, info, success, fail (alias failure), task, critical. a per-call +guild= argument routes to that guild's bot.settings[guild.id]['channels']['logs'] +instead of the construction channel. pass embed_builder=fn(logger, level, action, +actor, details) -> discord.Embed to restyle without subclassing, or override +build_embed in a subclass for complex cases. no feed/announcement method by +design; subclass and reuse _resolve for project-specific log types. -dynamic routing: a per-call guild= argument logs to that guild's configured -channel via bot.settings[guild.id]['channels']['logs']; omit it to use the -construction channel. - -custom embeds: pass embed_builder=fn(logger, level, action, actor, details) --> discord.Embed to restyle without subclassing; every level routes through -it. for complex cases override build_embed in a subclass instead. - -dual sink: every call also mirrors to the stdlib logger (getLogger(__name__)); -the stdlib emit happens before the discord send, so the record survives even -if discord fails. set log_to_file=False at construction, or per call, to -disable. - -extending: no feed/announcement method by design; subclass and reuse -_resolve for project-specific log types. +dual sink: every call also mirrors to the stdlib logger (getLogger(__name__)) +before the discord send, so the record survives even if discord fails. set +log_to_file=False at construction, or per call, to disable. errors: setup raises, sends swallow. resolution failures (unresolvable guild/channel, bad config, a non-text channel, an invalid timezone) raise -ValueError from `initialize()`. underlying discord exceptions (NotFound/ -Forbidden/HTTPException/InvalidData and other ClientException subclasses) -are normalized to that same ValueError. on a per-call send, resolution and -send failures never propagate — they fall back to the stdlib logger so a -transient discord failure never breaks the caller's command. +ValueError from `initialize()`, with underlying discord exceptions normalized +to it. per-call send failures never propagate - they fall back to the stdlib +logger so a transient discord failure never breaks the caller's command. """ import logging @@ -114,14 +105,10 @@ class DPYLogger: if not self.guild: raise ValueError(f"[dpy_logger] cannot resolve channel {self.channel} without a guild") self.channel = await self._get_channel(self.guild) - # a channel with no guild would otherwise blackout every send silently; derive - # the guild from it, or fail loud here rather than later if self.guild is None and isinstance(self.channel, discord.TextChannel): self.guild = self.channel.guild if self.guild is None and self.channel is not None: raise ValueError("[dpy_logger] channel provided without a resolvable guild") - # a wrong-type channel object (Thread/VoiceChannel/ForumChannel) would also pass - # silently and misroute/blackhole later; fail loud here instead if self.channel is not None and not isinstance(self.channel, (discord.TextChannel, int)): raise ValueError(f"[dpy_logger] channel {self.channel!r} is not a text channel") @@ -183,7 +170,6 @@ class DPYLogger: if self._embed_builder is not None: return self._embed_builder(self, level, action, actor, details) em = discord.Embed(color=self.colors[level]) - # is-not-None keeps falsy-but-valid values (0, False) rendering if action is not None and str(action) != "": em.add_field(name="Action", value=f"`{action}`", inline=True) if actor is not None and str(actor) != "": @@ -209,12 +195,7 @@ class DPYLogger: async def _send(self, level, log_msg, action=None, actor=None, guild=None, log_to_file=None, content=None): - """resolve channel and dispatch a leveled embed; mirror to stdlib unless opted out - - stdlib emit happens first so the record survives a failed discord send, which - falls back to stdlib rather than propagating. `content` carries the critical-level - ping/@here text (None for other levels), so every level shares this one contract. - """ + """resolve channel and dispatch a leveled embed; mirror to stdlib unless opted out""" if self.log_to_file if log_to_file is None else log_to_file: self._emit_stdlib(level, action, actor, log_msg) try: @@ -248,7 +229,7 @@ class DPYLogger: async def task(self, log, action=None, actor=None, guild=None, log_to_file=None): """log a task-level message with SYSTEM/TASK as the actor - actor is accepted for caller compatibility and ignored — task actions are + actor is accepted for caller compatibility and ignored - task actions are always attributed to SYSTEM/TASK regardless of the caller-supplied actor """ return await self._send("task", log, action, "SYSTEM/TASK", guild, log_to_file)