Add comment explaining the status of RawConfigParser.items

TL;DR, we're hitting python/mypy#3805 when implemented correctly as an override, and python/mypy#1855 when we try to work around that with a union.
python · ambv · Aug 21, 2017 · Aug 6, 2017 · Aug 7, 2017 · Aug 7, 2017
commit 7c80d55faf009747e66d73eb6a5ebac8c055ab7b
diff --git a/stdlib/3/configparser.pyi b/stdlib/3/configparser.pyi
@@ -113,6 +113,11 @@ class RawConfigParser(_parser):
         ...
 
     # This is incompatible with Mapping so we ignore the type.
+    # This should really be an override with the following line added.  See
+    # https://github.com/python/mypy/issues/3805 for why it isn't.
+    # def items(self, section: str = ..., raw: bool = ..., vars: _section = ...) -> Iterable[Tuple[str, str]]: ...
+    # (It could be a union of the two in the meantime, to improve matters
+    # slightly, but then we hit https://github.com/python/mypy/issues/1855.)
     def items(self, section: Optional[str] = ..., raw: bool = ..., vars: _section = ...) -> Iterable[Tuple[str, SectionProxy]]: ...  # type: ignore
 
     def set(self, section: str, option: str, value: str) -> None: ...