chore(typing): Add _typing_compat.assert_never

[dangotbanned]

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• Mentioned in docs: is_between doesn't show ClosedInterval values. Remove type aliases #2715 (comment)
• Kinda related chore: review AssertionError internally #1894

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes

If you have comments or can explain your changes, please do so below

[FBruzzesi]

Thanks @dangotbanned - should we replace all the other "unreachable" code paths as well (search)?

One nice thing that we are losing is the suggestion "Please report an issue at https://github.com/narwhals-dev/narwhals/issues/new". I wonder if it's worth it to have our version of assert_never independently of the python version

[dangotbanned]

Thanks @dangotbanned

Thanks for peeking @FBruzzesi

should we replace all the other "unreachable" code paths as well (search)?

If you can find any (besides db14ab1) that both pyright and mypy agree are unreachable - I'm happy for those to use assert_never as well 🙂

We can only use it when we can prove that every case has been checked, like this

It isn't just limited to Literal, this one is handling some pretty complex types

Here for example, the type hasn't been narrowed to Never - so if we used assert_never it'd produce an error during type checking

---

One nice thing that we are losing is the suggestion "Please report an issue at narwhals-dev/narwhals/issues/new". I wonder if it's worth it to have our version of assert_never independently of the python version

I'm open to using a custom message - only caveat is it has to be the same for every use.

We need to have the signature as this to be able to link whatever we use back to typing.assert_never

def assert_never(arg: Never, /) -> Never:

I was playing around with the idea of different runtime behavior than the stdlib in (#2705).
We'd basically need to do something like this here though:

from __future__ import annotations

import sys
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from typing import assert_never

    if sys.version_info >= (3, 11):
        from typing import Never
    else:
        from typing_extensions import Never

else:
    def assert_never(arg: Never, /) -> Never:
        msg = "Hello"
        raise AssertionError(msg)

[FBruzzesi]

If you can find any (besides db14ab1) that both pyright and mypy agree are unreachable - I'm happy for those to use assert_never as well 🙂

I will give it a shot 🤗

I'm open to using a custom message - only caveat is it has to be the same for every use.

We need to have the signature as this to be able to link whatever we use back to typing.assert_never

I would suggest to simply append the link at the end of the message:

def assert_never(arg: Never, /) -> Never:
    value = repr(arg)
    if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH:
        value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + "..."
    
    msg = (
        f"Expected code to be unreachable, but got: {value}.\n"
        "Please report an issue at [narwhals-dev/narwhals/issues/new](https://github.com/narwhals-dev/narwhals/issues/new)"
    )

    raise AssertionError(msg)

[dangotbanned]

#2717 (comment)

@FBruzzesi I tried using the link you gave first, but I think this one might be more handy?

• https://github.com/narwhals-dev/narwhals/issues/new
• https://github.com/narwhals-dev/narwhals/issues/new?template=bug_report.yml

[FBruzzesi]

Yes nice one! Thank you 👌

[MarcoGorelli]

cool, thanks @dangotbanned !