Stub out our universal base class

sigmavirus24 · sigmavirus24 · commit da2989cab960 · 2018-03-15T06:56:34.000-05:00
Experiment with Generics for the refresh method. And see how far that
gets us.
diff --git a/github3/github.pyi b/github3/github.pyi
@@ -1,86 +1,90 @@
 """This module contains the type stubs for github3.github."""
-from typing import Dict, List, Union, Optional
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    TypeVar,
+    Union,
+)
 
 from . import auths
 from . import events
-from .gists import gist
-from .issues import issue
+from . import models
 from . import orgs
-from .repos import repo
 from . import structs
 from . import users
+from .gists import gist
+from .issues import issue
+from .repos import repo
 
-AuthorizationsIterator = structs.GitHubIterator[auths.Authorization]
-EventsIterator = structs.GitHubIterator[events.Event]
-OrganizationsIterator = structs.GitHubIterator[orgs.ShortOrganization]
-RepositoriesIterator = structs.GitHubIterator[repo.ShortRepository]
-UsersIterator = structs.GitHubIterator[users.ShortUser]
+T = TypeVar('T', bound='GitHub')
 
 
-class GitHub:
+class GitHub(models.GitHubCore):
     def __init__(
-        self,
+        self: T,
         username: str='',
         password: str='',
         token: str='',
     ) -> None:
         ...
 
     def add_email_addresses(
-        self,
+        self: T,
         addresses: List[str]=[],
     ) -> List[users.Email]:
         ...
 
     def all_events(
-        self,
+        self: T,
         number: int=-1,
         etag: Optional[str]=None,
-    ) -> EventsIterator:
+    ) -> structs.GitHubIterator[events.Event]:
         ...
 
     def all_organizations(
-        self,
+        self: T,
         number: int=-1,
         since: Optional[int]=None,
         etag: Optional[str]=None,
         per_page: Optional[int]=None,
-    ) -> OrganizationsIterator:
+    ) -> structs.GitHubIterator[orgs.ShortOrganization]:
         ...
 
     def all_repositories(
-        self,
+        self: T,
         number: int=-1,
         since: Optional[int]=None,
         etag: Optional[str]=None,
         per_page: Optional[int]=None,
-    ) -> RepositoriesIterator:
+    ) -> structs.GitHubIterator[repo.ShortRepository]:
         ...
 
     def all_users(
-        self,
+        self: T,
         number: int=-1,
         etag: Optional[str]=None,
         per_page: Optional[int]=None,
         since: Optional[int]=None,
-    ) -> UsersIterator:
+    ) -> structs.GitHubIterator[users.ShortUser]:
         ...
 
     def authorization(
-        self,
+        self: T,
         id_num: Union[int, str],
-    ) -> AuthorizationsIterator:
+    ) -> auths.Authorization:
         ...
 
     def authorizations(
-        self,
+        self: T,
         number: int=-1,
         etag: Optional[str]=None,
-    ) -> AuthorizationsIterator:
+    ) -> structs.GitHubIterator[auths.Authorization]:
         ...
 
     def authorize(
-        self,
+        self: T,
         username: str,
         password: str,
         scopes: Optional[List[str]]=None,
@@ -92,21 +96,21 @@ class GitHub:
         ...
 
     def check_authorization(
-        self,
+        self: T,
         access_token: str,
     ) -> bool:
         ...
 
     def create_gist(
-        self,
+        self: T,
         description: str,
         files: Dict[str, Dict[str, str]],
         public: bool=True,
     ) -> gist.Gist:
         ...
 
     def create_issue(
-        self,
+        self: T,
         owner: str,
         repository: str,
         title: str,
@@ -117,3 +121,57 @@ class GitHub:
         assignees: Optional[List[str]]=None,
     ) -> issue.ShortIssue:
         ...
+
+    def create_key(
+        self: T,
+        title: str,
+        key: str,
+        read_only: bool=False,
+    ) -> users.Key:
+        ...
+
+    def create_repository(
+        self: T,
+        name: str,
+        description: str='',
+        homepage: str='',
+        private: bool=False,
+        has_issues: bool=True,
+        has_wiki: bool=True,
+        auto_init: bool=False,
+        gitignore_template: str='',
+    ) -> repo.Repository:
+        ...
+
+    def delete_email_addresses(
+        self: T,
+        addresses: List[str],
+    ) -> bool:
+        ...
+
+    def emails(
+        self: T,
+        number: int=-1,
+        etag: Optional[str]=None,
+    ) -> structs.GitHubIterator[users.Email]:
+        ...
+
+    def emojis(self: T) -> Dict[str, str]:
+        ...
+
+    def feeds(self: T) -> Dict[str, Any]:
+        ...
+
+    def follow(
+        self: T,
+        username: str
+    ) -> bool:
+        ...
+
+    def followed_by(
+        self: T,
+        username: str,
+        number: int=-1,
+        etag: Optional[str]=None,
+    ) -> structs.GitHubIterator[users.ShortUser]:
+        ...
diff --git a/github3/models.pyi b/github3/models.pyi
@@ -0,0 +1,62 @@
+from typing import (
+    Any,
+    Dict,
+    Generic,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+)
+
+from . import session
+
+
+Subclass = TypeVar('Subclass', bound='GitHubCore')
+Core = TypeVar('Core', bound='GitHubCore')
+Sessionish = Union[session.GitHubSession, GitHubCore]
+FullClass = TypeVar('FullClass')
+
+class GitHubCore(Generic[FullClass]):
+    _refresh_to = None # type: Optional[FullClass]
+
+    def __init__(
+        self: Core,
+        json: Dict[str, Any],
+        session: Sessionish,
+    ) -> None:
+        ...
+
+    def as_dict(self: Core) -> Dict[str, Any]:
+        ...
+
+    def as_json(self: Core) -> str:
+        ...
+
+    @classmethod
+    def from_dict(
+        cls: Type[Subclass],
+        json_dict: Dict[str, Any],
+        session: Sessionish,
+    ) -> Subclass:
+        ...
+
+    @classmethod
+    def from_json(
+        cls: Type[Subclass],
+        json_dict: str,
+        session: Sessionish,
+    ) -> Subclass:
+        ...
+
+    @property
+    def ratelimit_remaining(self: Core) -> int:
+        ...
+
+    def refresh(
+        self: Core,
+        conditional: bool,
+    ) -> Union[Core, FullClass]:
+        ...
+
+    def new_session(self: Core) -> session.GitHubSession:
+        ...
diff --git a/github3/users.pyi b/github3/users.pyi
@@ -1,15 +1,17 @@
-class _User:
-    ...
-
+from . import models
 
-class ShortUser(_User):
+class _User(models.GitHubCore):
     ...
 
 
 class User(_User):
     ...
 
 
+class ShortUser(_User):
+    _refresh_to = User
+
+
 class Contributor(_User):
     ...
 
@@ -18,5 +20,9 @@ class AuthenticatedUser(User):
     ...
 
 
-class Email:
+class Email(models.GitHubCore):
+    ...
+
+
+class Key(models.GitHubCore):
     ...
