Add initial type hints

gkeepapi/__init__.py

@@ -9,6 +9,7 @@
 import re
 import time
 import random
+from typing import List, Tuple, Union
 
 from uuid import getnode as get_mac
 
@@ -653,7 +654,7 @@ class Keep(object):
     """
     OAUTH_SCOPES = 'oauth2:https://www.googleapis.com/auth/memento https://www.googleapis.com/auth/reminders'
 
-    def __init__(self):
+    def __init__(self) -> None:
         self._keep_api = KeepAPI()
         self._reminders_api = RemindersAPI()
         self._media_api = MediaAPI()
@@ -675,7 +676,7 @@ def _clear(self):
         root_node = _node.Root()
         self._nodes[_node.Root.ID] = root_node
 
-    def login(self, email, password, state=None, sync=True, device_id=None):
+    def login(self, email: str, password: str, state: Union[dict, None] = None, sync=True, device_id: Union[int, None] = None):
         """Authenticate to Google with the provided credentials & sync.
 
         Args:
@@ -690,13 +691,12 @@ def login(self, email, password, state=None, sync=True, device_id=None):
         if device_id is None:
             device_id = get_mac()
 
-        ret = auth.login(email, password, device_id)
-        if ret:
-            self.load(auth, state, sync)
+        auth.login(email, password, device_id)
+        self.load(auth, state, sync)
 
-        return ret
+        return True
 
-    def resume(self, email, master_token, state=None, sync=True, device_id=None):
+    def resume(self, email: str, master_token: str, state: Union[dict, None] = None, sync=True, device_id: Union[int, None] = None):
         """Authenticate to Google with the provided master token & sync.
 
         Args:
@@ -711,21 +711,20 @@ def resume(self, email, master_token, state=None, sync=True, device_id=None):
         if device_id is None:
             device_id = get_mac()
 
-        ret = auth.load(email, master_token, device_id)
-        if ret:
-            self.load(auth, state, sync)
+        auth.load(email, master_token, device_id)
+        self.load(auth, state, sync)
 
-        return ret
+        return True
 
-    def getMasterToken(self):
+    def getMasterToken(self) -> str:
         """Get master token for resuming.
 
         Returns:
             str: The master token.
         """
         return self._keep_api.getAuth().getMasterToken()
 
-    def load(self, auth, state=None, sync=True):
+    def load(self, auth: APIAuth, state: Union[dict, None] = None, sync=True) -> None:
         """Authenticate to Google with a prepared authentication object & sync.
         Args:
             auth (APIAuth): Authentication object.
@@ -742,7 +741,7 @@ def load(self, auth, state=None, sync=True):
         if sync:
             self.sync(True)
 
-    def dump(self):
+    def dump(self) -> dict:
         """Serialize note data.
 
         Returns:
@@ -761,7 +760,7 @@ def dump(self):
             'nodes': [node.save(False) for node in nodes]
         }
 
-    def restore(self, state):
+    def restore(self, state: dict) -> None:
         """Unserialize saved note data.
 
         Args:
@@ -772,7 +771,7 @@ def restore(self, state):
         self._parseNodes(state['nodes'])
         self._keep_version = state['keep_version']
 
-    def get(self, node_id):
+    def get(self, node_id: str) -> _node.TopLevelNode:
         """Get a note with the given ID.
 
         Args:
@@ -785,7 +784,7 @@ def get(self, node_id):
             self._nodes[_node.Root.ID].get(node_id) or \
             self._nodes[_node.Root.ID].get(self._sid_map.get(node_id))
 
-    def add(self, node):
+    def add(self, node: _node.Node) -> None:
         """Register a top level node (and its children) for syncing up to the server. There's no need to call this for nodes created by
         :py:meth:`createNote` or :py:meth:`createList` as they are automatically added.
 
@@ -794,7 +793,7 @@ def add(self, node):
             node (gkeepapi.node.Node): The node to sync.
 
         Raises:
-            Invalid: If the parent node is not found.
+            InvalidException: If the parent node is not found.
         """
         if node.parent_id != _node.Root.ID:
             raise exception.InvalidException('Not a top level node')
@@ -845,7 +844,7 @@ def find(self, query=None, func=None, labels=None, colors=None, pinned=None, arc
             (trashed is None or node.trashed == trashed)
         )
 
-    def createNote(self, title=None, text=None):
+    def createNote(self, title: str = None, text: str = None) -> _node.Node:
         """Create a new managed note. Any changes to the note will be uploaded when :py:meth:`sync` is called.
 
         Args:
@@ -863,7 +862,7 @@ def createNote(self, title=None, text=None):
         self.add(node)
         return node
 
-    def createList(self, title=None, items=None):
+    def createList(self, title: Union[str, None] = None, items: List[Tuple[str, bool]] = None) -> _node.List:
         """Create a new list and populate it. Any changes to the note will be uploaded when :py:meth:`sync` is called.
 
         Args:
@@ -887,7 +886,7 @@ def createList(self, title=None, items=None):
         self.add(node)
         return node
 
-    def createLabel(self, name):
+    def createLabel(self, name: str) -> _node.Label:
         """Create a new label.
 
         Args:
@@ -930,7 +929,7 @@ def findLabel(self, query, create=False):
 
         return self.createLabel(name) if create and is_str else None
 
-    def getLabel(self, label_id):
+    def getLabel(self, label_id: str) -> Union[_node.Label, None]:
         """Get an existing label.
 
         Args:
@@ -941,7 +940,7 @@ def getLabel(self, label_id):
         """
         return self._labels.get(label_id)
 
-    def deleteLabel(self, label_id):
+    def deleteLabel(self, label_id: str) -> None:
         """Deletes a label.
 
         Args:
@@ -955,15 +954,15 @@ def deleteLabel(self, label_id):
         for node in self.all():
             node.labels.remove(label)
 
-    def labels(self):
+    def labels(self) -> List[_node.Label]:
         """Get all labels.
 
         Returns:
             List[gkeepapi.node.Label]: Labels
         """
         return self._labels.values()
 
-    def getMediaLink(self, blob):
+    def getMediaLink(self, blob: _node.Blob) -> str:
         """Get the canonical link to media.
 
         Args:
@@ -974,15 +973,15 @@ def getMediaLink(self, blob):
         """
         return self._media_api.get(blob)
 
-    def all(self):
+    def all(self) -> List[_node.TopLevelNode]:
         """Get all Notes.
 
         Returns:
             List[gkeepapi.node.TopLevelNode]: Notes
         """
         return self._nodes[_node.Root.ID].children
 
-    def sync(self, resync=False):
+    def sync(self, resync=False) -> None:
         """Sync the local Keep tree with the server. If resyncing, local changes will be destroyed. Otherwise, local changes to notes, labels and reminders will be detected and synced up.
 
         Args:
@@ -1001,7 +1000,7 @@ def sync(self, resync=False):
         if _node.DEBUG:
             self._clean()
 
-    def _sync_reminders(self, resync=False):
+    def _sync_reminders(self, resync=False) -> None:
         # Fetch updates until we reach the newest version.
         while True:
             logger.debug('Starting reminder sync: %s', self._reminder_version)