protobuf: Annotate well_known_types.pyi (#9323)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

stubs/protobuf/google/protobuf/internal/well_known_types.pyi

@@ -1,5 +1,10 @@
+from _typeshed import SupportsItems
+from collections.abc import Iterable, Iterator, KeysView, Mapping, Sequence
 from datetime import datetime, timedelta, tzinfo
 from typing import Any as tAny
+from typing_extensions import TypeAlias
+
+from google.protobuf import struct_pb2
 
 class Any:
     type_url: tAny = ...
@@ -63,29 +68,34 @@ class _FieldMaskTree:
     def AddLeafNodes(self, prefix: tAny, node: tAny) -> None: ...
     def MergeMessage(self, source: tAny, destination: tAny, replace_message: tAny, replace_repeated: tAny) -> None: ...
 
+_StructValue: TypeAlias = struct_pb2.Struct | struct_pb2.ListValue | str | float | bool | None
+_StructValueArg: TypeAlias = _StructValue | Mapping[str, _StructValueArg] | Sequence[_StructValueArg]
+
 class Struct:
-    def __getitem__(self, key: tAny): ...
-    def __contains__(self, item: tAny): ...
-    def __setitem__(self, key: tAny, value: tAny) -> None: ...
-    def __delitem__(self, key: tAny) -> None: ...
+    def __getitem__(self, key: str) -> _StructValue: ...
+    def __contains__(self, item: object) -> bool: ...
+    def __setitem__(self, key: str, value: _StructValueArg) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
     def __len__(self) -> int: ...
-    def __iter__(self): ...
-    def keys(self): ...
-    def values(self): ...
-    def items(self): ...
-    def get_or_create_list(self, key: tAny): ...
-    def get_or_create_struct(self, key: tAny): ...
-    def update(self, dictionary: tAny) -> None: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def keys(self) -> KeysView[str]: ...
+    def values(self) -> list[_StructValue]: ...
+    def items(self) -> list[tuple[str, _StructValue]]: ...
+    def get_or_create_list(self, key: str) -> struct_pb2.ListValue: ...
+    def get_or_create_struct(self, key: str) -> struct_pb2.Struct: ...
+    def update(self, dictionary: SupportsItems[str, _StructValueArg]) -> None: ...
 
 class ListValue:
     def __len__(self) -> int: ...
-    def append(self, value: tAny) -> None: ...
-    def extend(self, elem_seq: tAny) -> None: ...
-    def __getitem__(self, index: tAny): ...
-    def __setitem__(self, index: tAny, value: tAny) -> None: ...
-    def __delitem__(self, key: tAny) -> None: ...
-    def items(self) -> None: ...
-    def add_struct(self): ...
-    def add_list(self): ...
+    def append(self, value: _StructValue) -> None: ...
+    def extend(self, elem_seq: Iterable[_StructValue]) -> None: ...
+    def __getitem__(self, index: int) -> _StructValue: ...
+    def __setitem__(self, index: int, value: _StructValueArg) -> None: ...
+    def __delitem__(self, key: int) -> None: ...
+    # Doesn't actually exist at runtime; needed so type checkers understand the class is iterable
+    def __iter__(self) -> Iterator[_StructValue]: ...
+    def items(self) -> Iterator[_StructValue]: ...
+    def add_struct(self) -> struct_pb2.Struct: ...
+    def add_list(self) -> struct_pb2.ListValue: ...
 
 WKTBASES: dict[str, type[tAny]]