fix: normalize construction-channel fetch errors; reject wrong-type channel objects at setup (dpylogger-7/8)

initialize() previously let a bad construction channel id leak raw
discord.errors.NotFound/Forbidden/HTTPException past the documented
ValueError-only setup contract, and let an already-resolved non-TextChannel
object (Thread/VoiceChannel/ForumChannel) pass silently, later misrouting or
blackholing every send. Wrap the construction-channel fetch in the same
try/except as the settings path and type-check the resolved-object channel
path, mirroring the existing int-path guard.

Widened the normalization tuple to also catch discord.ClientException
(covers InvalidData), fixing dpylogger-9 opportunistically since it's the
same pattern.

Bump to v0.1.5.

Signed-off-by: disqualifier <dev@disqualifier.me>

.gitignore

@@ -1,5 +1,5 @@
 # claude
-CLAUDE.md
+.claude/
 
 # python
 __pycache__/

README.md

@@ -10,17 +10,19 @@ 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.0
+dpy_logger @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_logger.git@v0.1.5
 ```
 
 Direct:
 
 ```bash
-pip install "dpy_logger @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_logger.git@v0.1.0"
+pip install "dpy_logger @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_logger.git@v0.1.5"
 ```
 
 Requires `discord.py` (pulled transitively).
 
+Drop the `@v0.1.4` suffix from the line above to install the latest unpinned.
+
 ## Usage
 
 ```python
@@ -28,11 +30,11 @@ from dpy_logger import DPYLogger
 
 bot.log = DPYLogger(
     bot, guild_id, channel_id,
-    colors=cfg.log_colors,        # optional; merged over sensible defaults
+    colors=log_colors,            # optional; merged over sensible defaults
-    pings=cfg.authorized_devs,    # mentioned on critical()
+    pings=authorized_devs,        # mentioned on critical()
-    timezone=cfg.timezone,
+    timezone=tz,
-    footer=cfg.bot_footer,
+    footer=bot_footer,
-    avatar=cfg.bot_avatar,
+    avatar=bot_avatar,
 )
 await bot.log.initialize()        # resolves ids -> objects, call once
 
@@ -70,10 +72,15 @@ await bot.log.debug("noisy", log_to_file=False)   # -> Discord only
 
 ## Errors
 
-Resolution failures (unresolvable guild/channel, bad config) raise `ValueError` at
+Resolution failures (unresolvable guild/channel, bad config, a non-text channel — whether
-`initialize`/call time — a misconfigured logger should fail loudly at setup. Per-call
+passed as an id or as an already-resolved object) raise `ValueError` from `initialize()` —
-**send** failures do **not** propagate: they fall back to the stdlib logger so a
+a misconfigured logger should fail loudly at setup. Underlying `discord` exceptions
-transient Discord failure never breaks the caller's command.
+(`NotFound` / `Forbidden` / `HTTPException` / `InvalidData` and other `ClientException`
+subclasses) from `fetch_guild`/`fetch_channel` are normalized to that `ValueError` on every
+resolution path (construction channel, per-guild settings lookup) so callers see one error
+type. On a **per-call** send, neither resolution nor send failures propagate: they fall
+back to the stdlib logger so a transient Discord failure (or a per-call `guild=` that
+doesn't resolve) never breaks the caller's command.
 
 ## Construction contract
 
@@ -136,4 +143,4 @@ class FeedLogger(DPYLogger):
 
 ## Versioning
 
-Tagged `vX.Y.Z`. Pin the tag in `requirements.txt`.
+Releases are tagged `vX.Y.Z`. The install line above pins a release; drop the `@vX.Y.Z` suffix to install the latest unpinned. Pin deliberately for reproducible installs.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dpy_logger"
-version = "0.1.0"
+version = "0.1.5"
 description = "Leveled Discord channel logger for discord.py — config-free, injectable, installable."
 requires-python = ">=3.10"
 dependencies = [

src/dpy_logger/dpy_logger.py

@@ -12,11 +12,11 @@ command that mutates bot.settings changes routing without a restart.
 
     bot.log = DPYLogger(
         bot, guild_id, channel_id,
-        colors=cfg.log_colors,        # optional, falls back to defaults
+        colors=log_colors,            # optional, falls back to defaults
-        pings=cfg.authorized_devs,    # mentioned on critical()
+        pings=authorized_devs,        # mentioned on critical()
-        timezone=cfg.timezone,
+        timezone=tz,
-        footer=cfg.bot_footer,
+        footer=bot_footer,
-        avatar=cfg.bot_avatar,
+        avatar=bot_avatar,
     )
     await bot.log.initialize()        # resolves ids -> objects
     await bot.log.success("user promoted", action="promote", actor=ctx.author)
@@ -40,10 +40,15 @@ happens before the discord send, so the record survives even if discord fails.
 extending: this base has no feed/announcement method by design. a project
 that wants one subclasses DPYLogger and adds it, reusing _resolve.
 
-errors: resolution failures (unresolvable guild/channel, bad config) raise
+errors: resolution failures (unresolvable guild/channel, bad config, a
-ValueError at initialize/call time — a misconfigured logger should fail loudly.
+non-text channel passed as either an id or an already-resolved object) raise
-per-call send failures do NOT propagate: they fall back to the stdlib logger so
+ValueError from `initialize()` — a misconfigured logger should fail loudly at
-a transient discord failure never breaks the caller's command.
+setup. underlying discord exceptions (NotFound/Forbidden/HTTPException/
+InvalidData and other ClientException subclasses) are normalized to that
+ValueError on every resolution path. on a per-call send, resolution AND send
+failures do NOT propagate: they fall back to the stdlib logger so a transient
+discord failure (or a per-call `guild=` that doesn't resolve) never breaks the
+caller's command.
 """
 
 import logging
@@ -110,15 +115,35 @@ 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 object passed with no guild (e.g. bot.get_channel(id)) would pass
+        # setup silently but then fail every send at _get_guild(None) — swallowed, so
+        # nothing reaches discord. derive the guild from the channel it already carries,
+        # or fail loud at setup (matching the int-channel guard above) 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 resolved wrong-type object (Thread/VoiceChannel/ForumChannel) would also pass
+        # setup silently — _get_channel only recognizes TextChannel/int, so anything else
+        # falls through to the bot.settings lookup at send time and misroutes or blackholes
+        # the sink. fail loud here, mirroring the int-path check in _get_channel.
+        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")
 
     async def _get_guild(self, guild):
         """resolve a guild from id-or-object, raising if unresolvable"""
         if guild:
             if isinstance(guild, int):
-                resolved = self.bot.get_guild(guild) or await self.bot.fetch_guild(guild)
+                resolved = self.bot.get_guild(guild)
-                if not resolved:
+                if resolved is not None:
-                    raise ValueError(f"[dpy_logger] failed to fetch guild {guild}")
                     return resolved
+                # fetch_guild never returns None — it raises NotFound/Forbidden/
+                # HTTPException; normalize those to the lib's ValueError so callers see
+                # one error type at setup
+                try:
+                    return await self.bot.fetch_guild(guild)
+                except discord.HTTPException as error:
+                    raise ValueError(f"[dpy_logger] failed to fetch guild {guild}: {error}") from error
             if isinstance(guild, discord.Guild):
                 return guild
         raise ValueError("[dpy_logger] no guild available for logging")
@@ -128,20 +153,38 @@ class DPYLogger:
         if not guild:
             raise ValueError("[dpy_logger] cannot resolve channel without a guild")
 
-        if not override and guild == self.guild:
+        if not override and getattr(guild, "id", guild) == getattr(self.guild, "id", self.guild):
             if isinstance(self.channel, discord.TextChannel):
                 return self.channel
             if isinstance(self.channel, int):
-                return await guild.fetch_channel(self.channel)
+                # fetch_channel raises NotFound/Forbidden/HTTPException/InvalidData (a
+                # ClientException, not an HTTPException); normalize all of those to the
+                # lib's ValueError so a bad construction channel id fails loud with one
+                # error type, matching the settings path below
+                try:
+                    channel = await guild.fetch_channel(self.channel)
+                except (discord.HTTPException, discord.ClientException) as error:
+                    raise ValueError(f"[dpy_logger] could not fetch channel {self.channel}: {error}") from error
+                if not isinstance(channel, discord.TextChannel):
+                    # fetch_channel can return a Voice/Category/Forum channel; fail loud
+                    # at setup like the settings path, not later via an AttributeError on .send
+                    raise ValueError(f"[dpy_logger] channel {self.channel} is not a text channel")
+                return channel
 
         try:
             channel_id = self.bot.settings[guild.id]["channels"]["logs"]
+        except KeyError:
+            raise ValueError(f"[dpy_logger] no log channel configured for guild {guild.id}")
+        try:
             channel = await guild.fetch_channel(channel_id)
+        except (discord.HTTPException, discord.ClientException) as error:
+            # fetch_channel raises NotFound/Forbidden/HTTPException/InvalidData (a
+            # ClientException, not an HTTPException); normalize all of those to the
+            # lib's ValueError so a bad configured id fails loud with one error type
+            raise ValueError(f"[dpy_logger] could not fetch channel {channel_id}: {error}") from error
         if not isinstance(channel, discord.TextChannel):
             raise ValueError(f"[dpy_logger] configured channel {channel_id} is not a text channel")
         return channel
-        except KeyError:
-            raise ValueError(f"[dpy_logger] no log channel configured for guild {guild.id}")
 
     def build_embed(self, level, action, actor, details):
         """build the embed for a log call
@@ -154,11 +197,19 @@ 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])
-        if action:
+        # test `is not None` so a falsy-but-valid value (0, False) still renders; only a
+        # genuinely absent field (None) or an empty string is dropped/substituted below
+        if action is not None and str(action) != "":
             em.add_field(name="Action", value=f"`{action}`", inline=True)
-        if actor:
+        if actor is not None and str(actor) != "":
             em.add_field(name="Actor", value=f"`{actor}`", inline=True)
-        em.add_field(name="Log", value=details, inline=False)
+        # discord rejects an empty field value (50035) and truncates nothing itself, so
+        # an empty or >1024-char message would 400 the send; substitute + cap to keep
+        # every logging call producing a valid embed
+        log_value = str(details) if details is not None and str(details) != "" else "(no message)"
+        if len(log_value) > 1024:
+            log_value = log_value[:1021] + "..."
+        em.add_field(name="Log", value=log_value, inline=False)
         em.timestamp = datetime.now(self.timezone)
         em.set_footer(text=f"{self.footer} Logging".strip(), icon_url=self.avatar)
         return em
@@ -169,20 +220,28 @@ class DPYLogger:
 
     def _emit_stdlib(self, level, action, actor, log_msg):
         """mirror the log line to the stdlib logger (routed to file/console by the app)"""
-        parts = [p for p in (action, str(actor) if actor else None, log_msg) if p]
+        # render falsy-but-valid parts (0, False); drop only genuinely-absent (None) ones
+        raw = (action, str(actor) if actor is not None else None, log_msg)
+        parts = [str(p) for p in raw if p is not None and str(p) != ""]
         _log.log(LEVEL_MAP.get(level, logging.INFO), f"[{level}] " + " | ".join(parts))
 
-    async def _send(self, level, log_msg, action=None, actor=None, guild=None, log_to_file=None):
+    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 even if the discord send fails.
         a failed send falls back to stdlib rather than propagating into the caller.
+        `content` carries the critical-level ping/@here text (None for the other levels),
+        so every level shares this one send/error contract.
         """
         if self.log_to_file if log_to_file is None else log_to_file:
             self._emit_stdlib(level, action, actor, log_msg)
         try:
             channel = await self._resolve(guild)
-            return await channel.send(embed=self.build_embed(level, action, actor, log_msg))
+            return await channel.send(
+                content=content,
+                embed=self.build_embed(level, action, actor, log_msg),
+            )
         except Exception:
             _log.exception(f"[dpy_logger] failed to send {level} log: {log_msg}")
             return None
@@ -205,26 +264,24 @@ class DPYLogger:
 
     failure = fail
 
-    async def task(self, log, action=None, guild=None, log_to_file=None):
+    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"""
+        """log a task-level message with SYSTEM/TASK as the actor
+
+        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)
 
     async def critical(self, log, action=None, actor=None, guild=None, log_to_file=None):
-        """log a critical-level message and ping configured devs"""
+        """log a critical-level message and ping configured devs
-        if self.log_to_file if log_to_file is None else log_to_file:
+
-            self._emit_stdlib("critical", action, actor, log)
+        delegates to _send with the ping/@here content so the send + error contract has a
+        single source of truth; critical only adds the alert `content`.
+        """
         if self.pings:
             content = "alert: " + " ".join(f"<@{u}>" for u in self.pings)
         elif self.alert_here:
             content = "alert: @here"
         else:
             content = None
-        try:
+        return await self._send("critical", log, action, actor, guild, log_to_file, content)
-            channel = await self._resolve(guild)
-            return await channel.send(
-                content=content,
-                embed=self.build_embed("critical", action, actor, log),
-            )
-        except Exception:
-            _log.exception(f"[dpy_logger] failed to send critical log: {log}")
-            return None