No type or annotation for parameter 'channel'

[llucax]

Description of the bug

When building docs for files generated via protobuf/grpc/mypy-protobuf, griffe complains about No type or annotation for parameter 'channel'. This generates a .py file that has docstrings with no type hints (code or docstrings), plus a .pyi file that has no docstrings but the code has type hints.

This used to work with griffe==1.14.0 and fails with griffe==1.15.0.

This is just a warning, but since we use strict=true it fails the build. We are working around it by using the option:

            docstring_options:
              warn_missing_types: false

To Reproduce

You can have a look at the CI builds above, or just checkout the code before we added the fix: frequenz-floss/frequenz-api-dispatch@99ca855.

Here you also have a minimal project with protobuf-generated files with this issue:
frequenz-api-test.tar.gz

Something like:

uv venv --python 3.13 venv
 . venv/bin/activate
SETUPTOOLS_SCM_PRETEND_VERSION=1.0.0 uv pip install .[dev]
mkdocs build

Should work, but you would need to have a working docker installation too 😬 because the build process will try to use docker to generate docs from the proto files too.

Environment information

• System: Linux-6.12.63+deb13-amd64-x86_64-with-glibc2.42
• Python: cpython 3.13.5 (/tmp/pytest-of-luca/pytest-4/test_generation_RepositoryType0/frequenz-api-test/venv/bin/python3)
• Environment variables:
• Installed packages:
• griffe v1.15.0

[pawamoy]

Thanks for the report @llucax! You have a lot of references to locally available packages in pyproject.toml (@ file://) 🙂 Anyway I'll manage to run it. Could you otherwise share the generate py and pyi code? The probable cause of the regression is #422 (discussion in mkdocstrings/mkdocstrings#803).

[llucax]

Oh, sorry about that. It is actually on one dependency repeated several times, that was extracted from some tests for a project template that replaces the dependency for a local one to make sure we are testing the new code. Anyways, you can just replace the @ file:// with == 0.14.0.

Here is the fixed file in case it is useful: pyproject.toml.txt (.txt appended because of damn GH doesn't support uploading .toml).

Here are the offending .py and .pyi files (they are also in the tar.gz:

• test_pb2_grpc.py
• test_pb2_grpc.pyi.txt (again .txt appended because of GH).

[pawamoy]

Sorry, for some reason I'm getting this error:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

I guess I'm not in the Docker group, and I'd prefer keeping things that way.

Could you build a minimal reproduction example? My own attempt is this:

class TestStub(object):
    """A simple test service.
    """

    def __init__(self, channel):
        """Constructor.

        Args:
            channel: A grpc.Channel.
        """
        self.SayHello = channel.unary_unary()

# stub
import grpc
import grpc.aio
import typing

class HelloWorld: ...

_TestSayHelloType = typing.TypeVar(
    '_TestSayHelloType',
    grpc.UnaryUnaryMultiCallable[
        HelloWorld,
        HelloWorld,
    ],
    grpc.aio.UnaryUnaryMultiCallable[
        HelloWorld,
        HelloWorld,
    ],
    default=grpc.UnaryUnaryMultiCallable[
        HelloWorld,
        HelloWorld,
    ],
)

class TestStub(typing.Generic[_TestSayHelloType]):
    """A simple test service."""

    @typing.overload
    def __init__(self: TestStub[
        grpc.UnaryUnaryMultiCallable[
            HelloWorld,
            HelloWorld,
        ],
    ], channel: grpc.Channel) -> None: ...

    @typing.overload
    def __init__(self: TestStub[
        grpc.aio.UnaryUnaryMultiCallable[
            HelloWorld,
            HelloWorld,
        ],
    ], channel: grpc.aio.Channel) -> None: ...

    SayHello: _TestSayHelloType
    """Says hello."""

...but both Griffe 1.14 and 1.15 warn about channel not having a type annotation.

[llucax]

I guess I'm not in the Docker group, and I'd prefer keeping things that way.

Yeah, I know that's less than ideal too. Technical debt we hope to get rid off eventually 🙄

Could you build a minimal reproduction example?

I'll try.

...but both Griffe 1.14 and 1.15 warn about channel not having a type annotation.

Isn't this a bug already though? Type information is there in the .pyi file.

[pawamoy]

The thing is, your __init__ implementation doesn't have type annotations. We could consider somehow merging annotations for a given parameter from all overloads. For example channel would get grpc.Channel | grpc.aio.Channel as annotation when merging stubs. I wonder how trivial/complex it is to merge type annotations correctly though.

[llucax]

The thing is, your __init__ implementation doesn't have type annotations.

Isn't is the case for all modules providing a .pyi. Isn't that the whole purpose of shipping .pyi files (to have the type hints separated from the actual code)?

We could consider somehow merging annotations for a given parameter from all overloads.

Oh, so the issue here is that you don't have a 1-1 mapping between the .py __init__ and the .pyi overloaded __init__? Although it only makes sense to declare overloads in the .pyi files, it seems like everytime there are overloads and a .pyi the same will happen, right?

For example channel would get grpc.Channel | grpc.aio.Channel as annotation when merging stubs. I wonder how trivial/complex it is to merge type annotations correctly though.

This seems to make sense to me, this is what you have to do then using type hints natively, right? For the main function with the implementation you need to use union of all possibilities, right?

In any case, and if it fails on both, I guess the regression was somewhere else. Looking at other dependencies that changed (we really need to start pinning all our transitional dependencies, speaking of technical debt), I see there is also a change in mypy-protobuf (3.6.0 (works) -> 3.7.0 (fail)), so probably the regression comes from there. The changelog mentions "Support client stub async typing overloads", so probably the overloading is new and what triggers the issue. I will remove regression from the issue title.

[llucax]

And thinking more about it, I guess the .pyi file should have the non-overloaded version of __init__ with the type union, right? So:

# stub
import grpc
import grpc.aio
import typing

class HelloWorld: ...

_TestSayHelloType = typing.TypeVar(
    '_TestSayHelloType',
    grpc.UnaryUnaryMultiCallable[
        HelloWorld,
        HelloWorld,
    ],
    grpc.aio.UnaryUnaryMultiCallable[
        HelloWorld,
        HelloWorld,
    ],
    default=grpc.UnaryUnaryMultiCallable[
        HelloWorld,
        HelloWorld,
    ],
)

class TestStub(typing.Generic[_TestSayHelloType]):
    """A simple test service."""

    @typing.overload
    def __init__(self: TestStub[
        grpc.UnaryUnaryMultiCallable[
            HelloWorld,
            HelloWorld,
        ],
    ], channel: grpc.Channel) -> None: ...

    @typing.overload
    def __init__(self: TestStub[
        grpc.aio.UnaryUnaryMultiCallable[
            HelloWorld,
            HelloWorld,
        ],
    ], channel: grpc.aio.Channel) -> None: ...

    def __init__(self: TestStub[
        grpc.UnaryUnaryMultiCallable[
            HelloWorld,
            HelloWorld,
        ] |TestStub[
        grpc.aio.UnaryUnaryMultiCallable[
            HelloWorld,
            HelloWorld,
        ],
    ], channel: channel: grpc.Channel | grpc.aio.Channel) -> None: ...

    SayHello: _TestSayHelloType
    """Says hello."""

Would that fix the issue on the griffe side?

Although mypy seems to handle the version with only overloads gracefully, so I'm not sure if mypy-protobuf people will accept this as a bug just because griffe fails to deal with it. 🤔

[pawamoy]

Yeah type-checkers handle that fine, but they implement the whole typing logic, while Griffe does not, so Griffe always lags a bit (if not a lot) behind 🙂 I was able to draft some code to support that, will open a PR, but this will have to wait for #434 to be merged.