protobuf: Annotate well_known_types.pyi

[ikonst]

google.protobuf.struct_pb2.Struct and .List offer high-level methods which we are partially blind to, making things like list(list_value) fail.

The methods return either JSON primitive types (numbers are always floats!), Struct or List, and accept that along with plain sequences and mappings of the above. python/typing#182 comes handy in that we can now rely on recursive type aliases.

[AlexWaygood]

You may need to invent a fictional __iter__ method to get the type checkers to accept that ListValue is iterable 🙂 We do that in a few other places.

Type checkers aren't very good at understanding that classes with __getitem__ are also iterable.

[ikonst]

Thanks, I was just wondering why it "passes" in mypy...

[AlexWaygood]

You'll need to add an entry to https://github.com/python/typeshed/blob/main/stubs/protobuf/%40tests/stubtest_allowlist.txt to get stubtest to shut up about the fictional __iter__ method.

[AlexWaygood]

No idea what's going on with pytype, that might need some investigation.

[AlexWaygood]

Ahh, I'm guessing this breaks pytype because you're importing from one of the files that we exclude from the pytype check: https://github.com/python/typeshed/blob/main/tests/pytype_exclude_list.txt

I guess if need be, we could maybe just add more files to that excludelist. Hopefully that will fix it.

[AlexWaygood]

Thanks! A few comments:

[AlexWaygood]

LGTM

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉