Make configparser.RawConfigParser use SectionProxy where appropriate (#1527)

* Make configparser.RawConfigParser.__getitem__ return a SectionProxy

This reflects the code in the cpython tree and makes the following
(valid) code type-check correctly:

```
from configparser import ConfigParser

config = ConfigParser()
config.read_dict({'section': {'key': 'false'}})
assert config['section'].getboolean('key') is False
```

* RawConfigParser.items() returns SectionProxys not mappings

Because .items() uses __getitem__ to produce second item in each tuple.

* section argument to RawConfigParser.items is Optional

* Add comment explaining the status of RawConfigParser.items

TL;DR, we're hitting https://github.com/python/mypy/issues/3805 when
implemented correctly as an override, and
https://github.com/python/mypy/issues/1855 when we try to work around
that with a union.

* Correctly implement RawConfigParser.items overloading

* RawConfigParser.items(str) returns a List not an Iterable

stdlib/3/configparser.pyi

@@ -2,9 +2,9 @@
 # reading configparser.py.
 
 import sys
-from typing import (MutableMapping, Mapping, Dict, Sequence, List, Union,
-                    Iterable, Iterator, Callable, Any, IO, overload, Optional,
-                    Pattern, TypeVar)
+from typing import (AbstractSet, MutableMapping, Mapping, Dict, Sequence, List,
+                    Union, Iterable, Iterator, Callable, Any, IO, overload,
+                    Optional, Pattern, TypeVar)
 # Types only used in type comments only
 from typing import Optional, Tuple  # noqa
 
@@ -70,7 +70,7 @@ class RawConfigParser(_parser):
 
     def __len__(self) -> int: ...
 
-    def __getitem__(self, section: str) -> _section: ...
+    def __getitem__(self, section: str) -> SectionProxy: ...
 
     def __setitem__(self, section: str, options: _section) -> None: ...
 
@@ -112,8 +112,11 @@ class RawConfigParser(_parser):
     def get(self, section: str, option: str, *, raw: bool = ..., vars: _section = ..., fallback: str = ...) -> str:  # type: ignore
         ...
 
-    # This is incompatible with Mapping so we ignore the type.
-    def items(self, section: str = ..., raw: bool = ..., vars: _section = ...) -> Iterable[Tuple[str, _section]]: ...  # type: ignore
+    @overload
+    def items(self, *, raw: bool = ..., vars: _section = ...) -> AbstractSet[Tuple[str, SectionProxy]]: ...
+
+    @overload
+    def items(self, section: str, raw: bool = ..., vars: _section = ...) -> List[Tuple[str, str]]: ...
 
     def set(self, section: str, option: str, value: str) -> None: ...