cleanup: 30 `except Exception:` handlers have no comment, against the documented rule

[LeyckerS]

Context

CONTRIBUTING.md states the rule:

No blanket except: — name the exception, or except Exception: with a comment when the swallow is deliberate.

The rule is right. 30 handlers in the codebase do not follow it, swallowing everything with no comment saying why.

These numbers were recounted against main on 1 August 2026, after #54 annotated its five. An earlier version of this issue said 25, which was wrong in both directions — moon_extract.py alone has 23, and three of the files #54 touched still have unannotated handlers elsewhere.

File	Count	Lines
moon_extract.py	23	101, 188, 378, 391, 471, 537, 556, 653, 713, 735, 781, 796, 802, 806, 943, 1025, 1077, 1088, 1095, 1098, 1179, 1219, 1249
moon_engine.py	3	265, 371, 505
moon_bridge.py	2	170, 297
moon_cli.py	1	207
moon_download.py	1	564

Most are almost certainly deliberate — this is a codebase that talks to a browser over CDP and to hosts that change behaviour without notice, so defensive swallowing is often the correct call. That is exactly why the rule asks for a comment: from the outside, a deliberate swallow and a forgotten one look identical, and the next person cannot tell which is which.

The moon_extract.py ones matter most. Several of them currently mean a broken selector is indistinguishable from a dead link, which is the class of bug that costs someone an afternoon of debugging the wrong thing.

Take a slice — four people can work in parallel

Claim one slice by commenting which you are taking. Do not take two.

Slice	Scope	Handlers
A	moon_extract.py lines 101–556	7
B	moon_extract.py lines 653–943	8
C	moon_extract.py lines 1025–1249	8
D	moon_engine.py, moon_bridge.py, moon_cli.py, moon_download.py	7

Slice D touches four files but is the smallest and most self-contained — a good one if it is your first PR here.

What to do

For each handler in your slice:

• If a narrower exception is obviously right — name it. except (OSError, asyncio.TimeoutError): says far more than except Exception:. refactor(cleanup): annotate exception swallows in moon_bridge.py and … #54 narrowed native_dialog to (subprocess.TimeoutExpired, OSError) and that is the standard to follow.
• If the swallow is deliberate and has to stay broad — add a one-line comment saying what is expected to fail and why continuing is correct. State a specific fact. "Best-effort cleanup during shutdown" is a reason; "just in case" is not.
• If you cannot work out why it is there — leave it and say so in the PR. A # unclear note from a contributor is more useful than a confident guess, and I can fill it in.

Do not change behaviour beyond narrowing an exception set you are confident about. No new logging, no refactoring, no reordering.

Acceptance criteria

• Every handler in the claimed slice is either narrowed or carries a one-line reason
• No comment restates the code (# catch exception is not a reason)
• pytest tests/ -q passes
• Nothing outside the claimed slice is modified
• The PR says which slice it covers

Notes for the contributor

No Windows needed. pytest tests/ -q stubs Chrome and the network at the moon_extract boundary, so the suite runs on Linux and macOS.

The useful skill here is reading a defensive handler and working out what it is actually defending against. That is worth more than the diff, and it is why a PR that says "these four are deliberate, this fifth one I could not explain" is a better PR than one that comments all five confidently.

Comment with your slice letter before you start.

[AdvaitVarhade]

I'd like to help out with this, I can start by tackling the 5 handlers across moon_bridge.py and moon_cli.py as my first PR to keep the review small.

[LeyckerS]

@AdvaitVarhade has taken the first slice of this in #54 — 5 handlers across moon_bridge.py, moon_cli.py and moon_download.py, reviewed and waiting on CI. Assigning him for that portion.

This issue stays open and is splittable — anyone can take a file. The remaining handlers are in moon_extract.py and moon_engine.py, and they are the more interesting half. Some of them are not just undocumented, they're hiding real failures: an extraction path that swallows a broken selector looks identical to a dead link from the outside, which is exactly the class of bug that wastes an afternoon.

If you're picking this up, the standard set by #54 is the one to follow:

1. Where the exception set is knowable, narrow it (except (subprocess.TimeoutExpired, OSError):) rather than commenting a bare except Exception:.
2. Where it genuinely has to stay broad, say why in one line — "best-effort cleanup during shutdown" is a reason, "ignore errors" is not.
3. Keep it to one or two files per PR so review stays small.

Comment with the file you're taking so two people don't land on moon_extract.py at once.

[LeyckerS]

First slice merged: #54 covered 5 handlers across moon_bridge.py, moon_cli.py and moon_download.py (@AdvaitVarhade).

Still open, and this is the half that matters. Remaining:

File	Handlers
moon_extract.py	17
moon_engine.py	3

The moon_extract.py ones are worth doing properly rather than quickly. That file talks to a real Chrome over CDP and to hosts that change their markup without notice, so some swallows are correct — but several of them currently mean a broken selector is indistinguishable from a dead link from the user's point of view. Narrowing those changes what people see when something breaks, which is a real improvement and not a comment-only patch.

The bar set by #54:

1. Narrow the exception set where it is knowable, rather than commenting a bare except Exception:
2. Where it must stay broad, state why in one line — a specific fact, not "just in case"
3. One or two files per PR

Comment with the file you're taking. moon_extract.py is large enough that two people could split it by line range if you coordinate here first.

[AdvaitVarhade]

I would like to take the next slice of this and tackle the handlers in moon_extract.py. I will focus on narrowing the exceptions around the CDP/browser extraction logic and selector lookups where applicable.

[LeyckerS]

Correcting my own numbers above. I wrote that 17 handlers remain in moon_extract.py. That was wrong, and anyone who took the issue on that basis would have found a third more work than advertised.

Counted against main, moon_extract.py has 24 except Exception handlers, at lines:

71, 101, 188, 378, 391, 471, 537, 556, 653, 713, 735, 781, 796, 802, 806,
943, 1025, 1077, 1088, 1095, 1098, 1179, 1219, 1249

The number could not have dropped: #54 touched moon_bridge.py, moon_cli.py and moon_download.py, and never opened moon_extract.py. I miscounted, nothing changed underneath it.

moon_engine.py is confirmed at 3 — lines 265, 371 and 505.

A second thing the recount exposed: the slice ranges in #39 miss a handler. Slice A was 101–556, so line 71 falls outside A, B and C and would never have been claimed by anyone. Slice A now starts at 71.

Corrected split, which is what #39 now shows:

Slice	Scope	Handlers
A	moon_extract.py lines 71–556	8
B	moon_extract.py lines 653–943	8
C	moon_extract.py lines 1025–1249	8
D	moon_engine.py lines 265, 371, 505	3

Slice D is now the small one: three handlers in one file, and the engine is the easiest of these to reason about because it does not talk to Chrome.

Everything I said above about how to do the work still stands — narrow where the exception set is knowable, and where it must stay broad say why in one specific line. That part didn't depend on the count.

@AdvaitVarhade — this is the moon_extract.py work you asked for on the 31st. Take A, B or C by letter; they no longer overlap and they now cover the whole file.

[Moferanoluwa]

I'll take slice D — the 3 handlers in moon_engine.py (lines 265, 371, 505). Will follow the #54 standard: narrow the exception set where it's knowable, otherwise state why it must stay broad in one specific line.