How to use typing.Never to indicate a subclass method with zero arguments cannot be called?

[Dr-Irv]

Let's suppose I have a base class Base with a method foo(), and a subclass Sub that raises an Exception if foo() is called. I'd like it so that the type checker flags an error on Sub.foo(), but not Base.foo(), so I tried this:

from typing_extensions import Never


class Base:
    def __init__(self):
        pass

    def foo(self) -> None:
        print("foo")
        
    def goo(self, x: int) -> None;
        print("goo ", x)


class Sub(Base):
    def foo(self: Never) -> None:
        raise Exception("never")
    
    def goo(self, x: Never) -> None:
        raise Exception("never")


x = Sub()
x.foo()
x.goo(3)

With pyright 1.1.294 and python 3.10, I get the following:

neversub.py:16:19 - error: Type of parameter "self" must be a supertype of its class "Sub" (reportGeneralTypeIssues)
neversub.py:24:3 - error: Could not bind method "foo" because "Sub" is not assignable to parameter "self"
    Type "Sub" cannot be assigned to type "Never" (reportGeneralTypeIssues)
neversub.py:25:7 - error: Argument of type "Literal[3]" cannot be assigned to parameter "x" of type "Never" in function "goo"
    Type "Literal[3]" cannot be assigned to type "Never" (reportGeneralTypeIssues)```

The last two errors are exactly what I want. But while the first error makes sense, aside from using a #pyright: ignore, I'm not sure how this should be declared to avoid having to use #pyright: ignore. In other words, what is the right way to indicate that a method with zero parameters is not valid to call in a subclass?

I should note that with the method goo(), since it has a required argument, I can use the Never declaration to show that this is invalid. What's not clear is how do you indicate that a method with no arguments is invalid without having to use #pyright: ignore ?

[erictraut]

I think that's a reasonable use of Never. I've added logic to exempt the self "must be subclass" check if the annotated parameter type is Never. This will be included in the next release.

[Dr-Irv]

I think that's a reasonable use of Never. I've added logic to exempt the self "must be subclass" check if the annotated parameter type is Never. This will be included in the next release.

Cool! Same issue happens with mypy, so I'll open an issue there as well.

[Sammymullern]

To indicate that a method with zero parameters is not valid to call in a subclass, you can use the NoReturn type from the typing module. NoReturn is a special type that indicates that a function will never return normally, either because it raises an exception or because it enters an infinite loop.

Here's how you can use NoReturn to annotate Sub.foo():

from typing import NoReturn

class Sub(Base):
def foo(self) -> NoReturn:
raise Exception("never")

This tells the type checker that Sub.foo() will never return normally, and will always raise an exception. The type checker will flag an error if you try to call Sub.foo(). This way, you can avoid using #pyright: ignore to suppress the error.

Note that NoReturn is a subtype of Never, so you could also use Never in place of NoReturn in the above example. However, it's better to use NoReturn in this case, since it more clearly expresses the intent of the code. Never is better suited for cases where a function is expected to raise an exception, but it's not clear what the exception will be.

[erictraut]

@Sammymullern, that's incorrect. A NoReturn return type does not mean that the call is invalid. It means that the call will never return control back to the caller.

The type checker will flag an error if you try to call Sub.foo()

No, it's perfectly fine to call a function that returns NoReturn. This is not a type violation, and no error will be generated in such a case.

Note that NoReturn is a subtype of Never

Never is actually an alias for NoReturn. They mean the same thing in the type system, so one is not a subtype of the other.

Never is better suited for cases where a function is expected to raise an exception, but it's not clear what the exception will be.

I don't agree with that advice. Never should generally be used for input parameters, whereas NoReturn should be used for return types.

[erictraut]

This is addressed in pyright 1.1.295, which I just published. It will also be included in a future release of pylance.