How does an isinstance check narrow a `str | bytes` value for a type checker?

## Declared type versus narrowed type When you write `def as_text(chunk: str | bytes) -> str:`, `str | bytes` is the **declared** type of `chunk` — it is what the parameter may hold on entry. A static type checker does not stop there: it walks the function's control-flow graph and, at every point, computes the **narrowed** type, the smallest type it can prove given the branches taken to reach that point. Narrowing is entirely a compile-time artefact. Nothing about the object changes at runtime, no cast happens, and no annotation is consulted while the program runs. ## What each branch gets `isinstance` is one of the handful of checks every checker understands. - In the **positive branch** of `if isinstance(chunk, bytes):`, the union is filtered to the members that could be instances of `bytes`, leaving `bytes`. - In the **negative branch** the checker subtracts: a member is removed only when the tested class is a supertype of it. `str` is not a `bytes` subclass, so the else branch is exactly `str`. Subtraction does not always remove something. `isinstance(x, object)` removes nothing, and testing an `int`-typed value against `bool` leaves `int` in the negative branch, because a non-`bool` `int` is still possible there. Narrowing that *fails* to shrink anything is a common source of "why is this still Optional?" confusion. ## isinstance is a subclass test `isinstance(True, int)` is `True`, because `bool` subclasses `int`; narrowing to `int` therefore still admits `bool`. If you need the exact class — for example to reject `bool` where only a real integer makes sense — `type(x) is int` is the check, and checkers narrow it to exactly that class. - **Abstract base classes** work too: `isinstance(x, collections.abc.Sequence)` succeeds for registered virtual subclasses, and checkers narrow accordingly. - A `typing.Protocol` may only be used with `isinstance` when it is decorated `@runtime_checkable`, and then the runtime check only verifies that the named members exist, not that their signatures match — the static narrowing is stricter than the runtime test. ## Forms of the second argument - A tuple such as `isinstance(x, (str, bytes))` narrows to the union of those classes. - Since Python 3.10 (PEP 604) a union object works directly: `isinstance(x, str | bytes)`. Both are equivalent for narrowing purposes; the tuple form is what you need if you must still run on 3.9. ## How long narrowing lasts The narrowed type is bound to an *expression*, and it survives only while the checker can be sure the expression's value has not changed. - Rebinding the name discards it; so does the top of a loop, where the checker must widen back to whatever the variable can be on any iteration. - Narrowing a simple local name is the reliable case. - Narrowing an attribute like `self.chunk` or a subscript like `frame[0]` is supported only in limited ways and varies between checkers, because another call could mutate the object in between. The idiomatic workaround is to bind the value to a local first (`chunk = self.chunk`) and narrow that. ## Why it matters in an ingest path A log-ingest pipeline reads frames from a socket or a file opened in binary mode and gets `bytes`; configuration and JSON payloads arrive as `str`. Calling `.decode()` on a `str` or `.encode()` on `bytes` is the classic **encoding mismatch**, and at runtime both are an `AttributeError` raised somewhere far from the mistake. Declaring the union honestly and branching on `isinstance` lets the checker catch that before deploy. The better shape still is to **normalise at the boundary** — decode each frame once with an explicit codec and an explicit `errors=` policy — so that everything downstream is `str` and no narrowing is needed at all. A union type that persists deep into a codebase is usually a design smell rather than a typing problem. **Other checks in the same family.** `is None` comparisons, `assert` statements, early `return`/`raise`, and `match`/`case` class patterns all narrow through the same machinery. They differ in what they prove, not in how the checker records it. ## The class-object cousin: `issubclass` `isinstance` narrows a value; `issubclass` narrows a *class object*. If a registry holds handlers typed `type[Handler]`, then inside `if issubclass(cls, TextHandler):` the checker narrows `cls` to `type[TextHandler]`, so class-level attributes and the constructor signature of the subclass become visible. The two are easy to confuse in a plugin loader, and confusing them is not a quiet mistake: `issubclass` requires a class as its first argument and raises `TypeError` when handed an instance, so the wrong one fails immediately rather than narrowing incorrectly. **A quick way to see what the checker sees.** `typing.reveal_type(x)` is understood by type checkers as a request to print the narrowed type at that point, and `reveal_type` also exists at runtime in `typing` since 3.11, where it prints the runtime type and returns its argument. Dropping one into each branch is the fastest way to settle an argument about what a given check proved.