Overloads on `__init__` raises

[haakonvt]

We have some trouble with overloads on __init__ methods. We get DOC105: ... for what we think should be supported/correct code:

DOC105: Method `FooWrite.__init__`: Argument names match, but type hints in these args do not match: bar, baz

Here is the offending code:

class FooWrite(SomeObject):
    """
    The Foo write class.

    Args:
        bar (str | None): Description of bar.
        baz (int | None): Description of baz.
    """

    @overload
    def __init__(self, bar: None, baz: None) -> NoReturn: ...

    @overload
    def __init__(self, bar: str | None, baz: int | None) -> None: ...

    def __init__(self, bar: str | None, baz: int | None) -> None:
        if bar is None and baz is None:
            raise ValueError

If we instead do the exact same on a different method, everything works as expected:

class FooWrite(SomeObject):
    @overload
    def method(self, bar: None, baz: None) -> NoReturn: ...

    @overload
    def method(self, bar: str | None, baz: int | None) -> None: ...

    def method(self, bar: str | None, baz: int | None) -> None:
        """
        The method method

        Args:
            bar (str | None): Description of bar.
            baz (int | None): Description of baz.
        """
        if bar is None and baz is None:
            raise ValueError

Any idea? I suspect there's something going wrong since we look for/demand the docstring be place on the class instead of the method.

Some more info: We run pydoclint as part of pre-commit, here is the config we use:

  - repo: https://github.com/jsh9/pydoclint
    rev: 0.6.7
    hooks:
      - id: pydoclint
        require_serial: true
        args:
          - --style=google
          - --exclude=tests/|scripts/
          - --quiet
          - --skip-checking-raises=true
          - --check-class-attributes=false

[jsh9]

Hi @haakonvt ,

This seems like an expected behavior (I'm not saying it's the best behavior though).

What's happening under the hood (for your class constructor example) is: pydoclint is checking all 3 class constructors against the class docstring, and it's expecting all 3 constructors to have arg type hints consistent with the docstring.

That explains why your 2nd example passes without violations.

The solution I can think of is to write separate docstrings for those class constructors, and set --allow-init-docstring to True:

class FooWrite(SomeObject):
    """
    The Foo write class.
    """

    @overload
    def __init__(self, bar: str, baz: str) -> NoReturn:
        """
        Something

        Args:
            bar (str): Description of bar.
            baz (str): Description of baz.
        """
        ...

    @overload
    def __init__(self, bar: list, baz: list) -> None:
        """
        Something

        Args:
            bar (list): Description of bar.
            baz (list): Description of baz.
        """
        ...

    def __init__(self, bar: dict, baz: dict) -> None:
        """
        Something

        Args:
            bar (dict): Description of bar.
            baz (dict): Description of baz.
        """
        if bar is None and baz is None:
            raise ValueError

[haakonvt]

Thanks for the quick reply @jsh9 .

I must admit I don't understand this statement:

What's happening under the hood (for your class constructor example) is: pydoclint is checking all 3 class constructors against the class docstring, and it's expecting all 3 constructors to have arg type hints consistent with the docstring.

That explains why your 2nd example passes without violations.

Regarding my example; in my mind, there are no differences between the ordinary method and the init-method so I don't understand why the first signature with overloads is accepted but the second one is not 🤔

I mean, if this is consistent with the docstring:

    @overload
    def method(self, bar: None, baz: None) -> NoReturn: ...

...then this should also:

    @overload
    def __init__(self, bar: None, baz: None) -> NoReturn: ...

...or am I having a stroke here? 😆

[jsh9]

There are 3 class constructors with different signature. If you are tasked to write only one docstring for all 3 of them, how would you write it? You can't.

That's why I suggested writing 3 docstrings for each one of them.

[haakonvt]

I disagree - there is one class init/constructor method, and then several typing.overloads are necessary to indicate that passing both parameters as None will raise (i.e. typing.NoReturn).

If it works for a generic method it should work for __init__ (...or both should not work).

[jsh9]

I see what you mean now.

In the eyes of pydoclint, it sees 3 class constructors, just as it sees 3 method() methods.

Is the correct fix to tell pydoclint to only consider the very last __init__() and ignore others above it?

[haakonvt]

I think so, it would be the type checker's job to verify the overloads right.

How is this done today for e.g. def some_method with overloads? It seems to work already which is nice

[haakonvt]

Hey again! Do you think this is something you could find time for in the next couple of months @jsh9 ? Would be very happy if so 😄

[jsh9]

Hi @haakonvt , yes, I'll fix it soon (in the next few weeks).

I'll take this approach mentioned above, unless you have other suggestions:

Is the correct fix to tell pydoclint to only consider the very last init() and ignore others above it?

As to this question of yours, I can't answer from the top of my head. Maybe I'll have an answer when I'm fixing this issue.

How is this done today for e.g. def some_method with overloads?