Why is `assert isinstance(...)` an unsafe way to narrow types in shipped code?

**What `assert` compiles to.** `assert cond, msg` is equivalent to `if __debug__ and not cond: raise AssertionError(msg)`. `__debug__` is a compile-time constant: it is `True` normally and `False` when the interpreter is started with `-O` or `-OO`, or with the `PYTHONOPTIMIZE` environment variable set. Under those flags the compiler emits *no bytecode whatsoever* for the statement — the guard is not slow, it does not exist. `sys.flags.optimize` reports the level in effect. `-OO` additionally strips docstrings. **Why that interacts badly with narrowing.** A static checker treats `assert isinstance(chunk, str)` as a proof: for the rest of the block, `chunk` is a `str`, and it will happily let you call `.encode()` or slice it. That proof is only as good as the check that produced it. Run the same module under `-O` and the proof rests on nothing. There is no error, no warning, and no way for the checker to know how the process will be launched — the two facts live in different files, often in different repositories. **How it fails in practice.** A log-ingest pipeline reads frames, decodes them, and asserts the result is `str` before handing it to a parser. A producer starts emitting a different encoding, decoding yields `bytes` somewhere upstream, and with assertions active the pipeline stops at the boundary with a clear `AssertionError` naming the stage. Under `-O` — a flag someone added to the container entry point years ago to "speed things up" — nothing stops. The `bytes` object travels several stages further and surfaces as an `AttributeError` on `.strip()`, or worse as records written with mojibake that nobody notices until a downstream consumer complains. The distance between the bug and its symptom is the whole cost. **The forms that keep the check.** ```python def to_text(chunk: object) -> str: if not isinstance(chunk, (str, bytes)): raise TypeError(f"expected str or bytes, got {type(chunk).__name__}") return chunk if isinstance(chunk, str) else chunk.decode("utf-8") ``` A checker narrows this exactly as it narrows the assert version: the `raise` ends the branch, so everything after the guard sees the narrowed type. The behaviour is unconditional, the exception type is one callers can handle meaningfully, and the message names what actually arrived. An early `return` guard has the same property. Neither is any more verbose than the assert once you count the failure you avoided. **Where `cast` fits.** `typing.cast(str, chunk)` tells the checker to believe you and does nothing at runtime beyond returning its second argument. That is the right tool when you genuinely know something the checker cannot derive — a value round-tripped through a dynamic loader, say — and you accept that there is no check. Its virtue is honesty: nobody reading a `cast` thinks a validation happened. Using it to silence a checker over unvalidated external data is the same bug as the stripped assert, only more deliberate. **When `assert` is still right.** Inside tests it is the natural idiom. Inside a module, it is reasonable for invariants that are *impossible* rather than merely unexpected — a state your own code just established two lines earlier — where the only reader is a developer and the only consequence of the check disappearing is losing a debugging aid. Even then, know whether your deployment runs with `-O`; many do not, but the ones that do rarely advertise it. The dividing line to state in an interview is simple: assertions document the program's own assumptions, while data arriving from a socket, a file, a queue or a database must be validated by code that always runs. **How the flag actually arrives.** Almost nobody types `-O` at a prompt. It reaches production through a container entry point, a process-manager command line, a `PYTHONOPTIMIZE=1` value in a deployment environment, or a base image that sets it for everyone. The code that assumes assertions run and the configuration that removes them are typically owned by different people, which is why the failure survives review. One consequence worth knowing: optimised bytecode caches are written alongside the normal ones with an `opt-1` or `opt-2` tag in their `__pycache__` filenames, so a directory can hold both variants of the same module and switching the flag does not silently reuse the wrong one. **Detecting the situation.** A module that genuinely depends on its assertions can notice at import time, because `__debug__` is readable like any name: warning once when it is `False` turns an invisible deployment choice into a log line. `sys.flags.optimize` gives the level if you need to distinguish `-O` from `-OO`. Neither is a substitute for writing the guard properly; both are useful when you inherit a codebase whose assumptions you have not audited yet.