Improve the pytz stubs (#2475)

Based on the pytz docs http://pytz.sourceforge.net/ and code (version
2018.5).

- Accurately model the return value of the `timezone()` function. This
  necessitates modeling the internal pytz class hierarchy which is quite
  inconsistent.

- Expose `_BaseTzInfo` as `BaseTzInfo`.

  This change is useful because this type is importable and otherwise
  there is no pytz type which can be used in type annotations, e.g. in a
  function which takes a pytz `tzinfo` with the `localize` method,
  rather than a general `datetime.tzinfo`.

- Remove the lazy.pyi stubs. The `lazy` module contains some unrelated
  general data structures. It is not a public API - it is not documented
  and the types are not included in `__all__`.

- Remove methods which are already specified by inheritance in
  `datetime.tzinfo`.

- Add several public exception classes.

- Fill in the generic type parameters of the exposed `Dict`/`List`
  constants. Also change `Dict` -> `Mapping` because it is not actually
  a proper `dict`.

- Some style/ordering improvements.

third_party/2and3/pytz/__init__.pyi

@@ -1,41 +1,40 @@
-# Stubs for pytz (Python 3.5)
-
+from typing import Optional, List, Set, Mapping, Union
 import datetime
-from typing import Optional, List, Set, Dict, Union
 
-all_timezones = ...  # type: List
-all_timezones_set = ...  # type: Set
-common_timezones = ...  # type: List
-common_timezones_set = ...  # type: Set
-country_timezones = ...  # type: Dict
-country_names = ...  # type: Dict
-
-
-class _UTCclass(datetime.tzinfo):
-    zone = ...  # type: str
-    def fromutc(self, dt: datetime.datetime) -> datetime.datetime: ...
-    def utcoffset(self, dt: Optional[datetime.datetime]) -> datetime.timedelta: ...
-    def tzname(self, dt: Optional[datetime.datetime]) -> str: ...
-    def dst(self, dt: Optional[datetime.datetime]) -> datetime.timedelta: ...
+class BaseTzInfo(datetime.tzinfo):
+    zone: str = ...
     def localize(self, dt: datetime.datetime, is_dst: bool = ...) -> datetime.datetime: ...
-    def normalize(self, dt: datetime.datetime, is_dst: bool = ...) -> datetime.datetime: ...
+    def normalize(self, dt: datetime.datetime) -> datetime.datetime: ...
+
+class _UTCclass(BaseTzInfo):
+    def tzname(self, dt: Optional[datetime.datetime]) -> str: ...
+    def utcoffset(self, dt: Optional[datetime.datetime]) -> datetime.timedelta: ...
+    def dst(self, dt: Optional[datetime.datetime]) -> datetime.timedelta: ...
+
+class _StaticTzInfo(BaseTzInfo):
+    def tzname(self, dt: Optional[datetime.datetime], is_dst: Optional[bool] = ...) -> str: ...
+    def utcoffset(self, dt: Optional[datetime.datetime], is_dst: Optional[bool] = ...) -> datetime.timedelta: ...
+    def dst(self, dt: Optional[datetime.datetime], is_dst: Optional[bool] = ...) -> datetime.timedelta: ...
+
+class _DstTzInfo(BaseTzInfo):
+    def tzname(self, dt: Optional[datetime.datetime], is_dst: Optional[bool] = ...) -> str: ...
+    def utcoffset(self, dt: Optional[datetime.datetime], is_dst: Optional[bool] = ...) -> Optional[datetime.timedelta]: ...
+    def dst(self, dt: Optional[datetime.datetime], is_dst: Optional[bool] = ...) -> Optional[datetime.timedelta]: ...
+
+class UnknownTimeZoneError(KeyError): ...
+class InvalidTimeError(Exception): ...
+class AmbiguousTimeError(InvalidTimeError): ...
+class NonExistentTimeError(InvalidTimeError): ...
 
 utc: _UTCclass
 UTC: _UTCclass
+def timezone(zone: str) -> Union[_UTCclass, _StaticTzInfo, _DstTzInfo]: ...
+
+all_timezones: List[str]
+all_timezones_set: Set[str]
+common_timezones: List[str]
+common_timezones_set: Set[str]
+country_timezones: Mapping[str, List[str]]
+country_names: Mapping[str, str]
 ZERO: datetime.timedelta
 HOUR: datetime.timedelta
-
-
-class _BaseTzInfo(datetime.tzinfo):
-    zone = ...  # type: str
-
-    def fromutc(self, dt: datetime.datetime) -> datetime.datetime: ...
-    def localize(self, dt: datetime.datetime, is_dst: Optional[bool] = ...) -> datetime.datetime: ...
-    def normalize(self, dt: datetime.datetime) -> datetime.datetime: ...
-
-
-class _StaticTzInfo(_BaseTzInfo):
-    def normalize(self, dt: datetime.datetime, is_dst: Optional[bool] = ...) -> datetime.datetime: ...
-
-
-def timezone(zone: str) -> _BaseTzInfo: ...

third_party/2and3/pytz/lazy.pyi

@@ -1,14 +0,0 @@
-from typing import Iterator, List, Set, TypeVar
-from collections import Mapping
-
-_T = TypeVar('_T')
-_KT = TypeVar('_KT')
-_VT = TypeVar('_VT')
-
-class LazyDict(Mapping[_KT, _VT]):
-    def __getitem__(self, key: _KT) -> _VT: ...
-    def __iter__(self) -> Iterator[_KT]: ...
-    def __len__(self) -> int: ...
-
-class LazyList(List[_T]): ...
-class LazySet(Set[_T]): ...