Use of assert statements

[joshtemple]

I've noticed a number of assert statements within this codebase, which aren't recommended for production code because they can be disabled by running Python in optimized mode or with __debug__ = False. This can be a security risk because it can expose code that wouldn't have otherwise run.

Is there a reason why assert is being used instead of an if statement with a raise for an exception?

[tomchristie]

Is there a reason why assert is being used instead of an if statement with a raise for an exception?

I can see some different cases here.
Let's have a look at answering your question on a case-by-case basis.

To begin with I can see some assert isinstance(..., ...) cases.
Those look to me like cases where we know the type and are making sure that mypy's type checking passes okay.
I think they can be replaced with typing.cast(...) instead?

I'd suggest a pull request that (1) initially removes all the assert isinstance(...) lines, in order to determine the status of the tests after that change, and then (2) adds them as typing.cast(...) cases instead.

We can take a look at other cases after that.

[joshtemple]

typing.cast works, you could also replace assert isinstance(..., ...) as:

if not isinstance(..., ...):
    raise TypeError(...)

That will appease mypy while also giving you the benefit of raising an error at runtime if the expectation isn't met, which possibly allows you to make the change in one step.