The four `register_*` registrars promise `RegistryError` for a non-class input and raise `TypeError` instead

[JarryShaw]

All four registrar docstrings on main carry a Raises: clause whose first branch the code cannot reach:

• pcapkit/foundation/extraction.py:397 — "If dumper is not a class, or not a Dumper subclass."
• :438 — the same for engine / EngineBase
• :483 — reassembly / ReassemblyBase
• :524 — traceflow / TraceFlowBase

Each guard is a bare if not issubclass(x, Base):. A non-class never reaches the raise — it is rejected first. Measured, with the raise site read off the traceback rather than inferred from the message:

register_dumper      -> TypeError: issubclass() arg 1 must be a class | extraction.py:400
register_engine      -> TypeError: issubclass() arg 1 must be a class | <frozen abc>:123
register_reassembly  -> TypeError: issubclass() arg 1 must be a class | <frozen abc>:123
register_traceflow   -> TypeError: issubclass() arg 1 must be a class | <frozen abc>:123
register_protocol    -> TypeError: issubclass() arg 1 must be a class | <frozen abc>:123

register_protocol is affected too, so this is five registrars rather than four — pcapkit/foundation/registry/protocols.py:216. Its own Raises: clause makes no "not a class" claim, so its prose is accurate; the clause above covers the other four.

Two mechanisms, not one, which is why the identical message is misleading. Dumper's metaclass is plain type, so the builtin issubclass raises in place at the guard line. EngineBase, ReassemblyBase, TraceFlowBase and ProtocolBase all have ABCMeta-derived metaclasses (EngineMeta, ReassemblyMeta, TraceFlowMeta, ProtocolMeta), so the builtin delegates to ABCMeta.__subclasscheck__ and the raise happens inside abc. CPython emits the same string either way.

Two ways to close it, and the choice is a real one:

1. Prose follows code — drop the "is not a class" branch from the four clauses, and if the TypeError is worth documenting, document it as a TypeError.
2. Code follows prose — add an explicit isinstance(x, type) check ahead of each issubclass so callers get the promised RegistryError. A behaviour change on an error path, so it wants a changelog entry, and it would apply to all five for consistency.

Option 2 is the better contract — a registry rejecting bad input should raise the registry's own exception rather than leaking one from abc — but it is not a docs fix, so I am not assuming it.

The four clauses were introduced by #1015; the underlying guards predate it. Related: #1016, #1020.

[JarryShaw]

Option 2

[JarryShaw]

Option 2 taken — code follows prose. The guards get an explicit class check so callers get the registry's own exception instead of one leaking out of abc.

Scope, with the measurement that fixes the issue body's own error. It is five registrars, not four: register_dumper, register_engine, register_reassembly, register_traceflow in pcapkit/foundation/extraction.py and register_protocol in pcapkit/foundation/registry/protocols.py. Each gets an isinstance(x, type) test ahead of its issubclass, raising RegistryError. register_protocol's prose never made the "not a class" claim, so its docstring needs no edit even though its code does — which is why the fix is five and the prose fix is four.

This is a behaviour change on an error path: a caller currently catching TypeError would stop seeing it. So it earns a 1.5.0 entry, and breaking applies by the pack-path-or-public-contract test. Dropping needs: decision, adding breaking and wip.

[JarryShaw]

Correcting myself: this is not breaking, and I claimed it was. I wrote that a caller catching TypeError would stop seeing it. That is wrong — RegistryError subclasses TypeError:

RegistryError MRO: ['RegistryError', 'BaseError', 'TypeError', 'Exception', 'BaseException', 'object']
issubclass(RegistryError, TypeError) = True
raise RegistryError('probe')  ->  caught by `except TypeError`

BaseError mixes in TypeError for this family (pcapkit/utilities/exceptions.py, alongside IOObjError, InfoError, IPError, EnumError). So except TypeError keeps working across the change, and the contract "a non-class raises TypeError" is preserved and narrowed to the registry's own subclass. Only code matching the exact type, or matching on the old message text, is affected.

That is a strictly-compatible refinement, not a break, so I am removing the breaking label I added — it was my own inference, not part of your ruling. The changelog entry stays, under Fixed rather than as a breaking change. Flagging it rather than quietly relabelling, since I had already told you the opposite.

Your ruling is implemented and the work is verified: all five registrars gain an isinstance(x, type) test ahead of their issubclass, placed after the ModuleDescriptor unwrap so a descriptor naming a non-class attribute reaches it too — that path previously produced the same leaked TypeError. On pristine main the new tests fail with 20 errors, every one TypeError: issubclass() arg 1 must be a class, split 16 from extraction.py and 4 from register_protocol, which matches the two-mechanism split exactly.

One thing I had wrong in the brief, which the work corrected: I said the prose fix was four clauses. It is zero. The four Raises: clauses already read "is not a class, or not a X subclass", and with code now following prose they are simply true — no edit needed. The issue was a code defect throughout, not a code-and-prose one.

Raising the PR shortly. No guard's target class changed; that stays #1016's question.