Add basic type annotations

CHANGELOG.md

@@ -12,6 +12,7 @@ While this is unreleased, please only add v3 features here. Rebasing master onto
 ### Added
 
 * `Scope` - An enum which contains all of the authorization scopes (see [here](https://github.com/plamere/spotipy/issues/652#issuecomment-797461311)).
+* Add basic type annotations.
 
 ### Changed
 

setup.py

@@ -26,6 +26,7 @@
     author_email="[email protected]",
     url='https://spotipy.readthedocs.org/',
     install_requires=[
+        'typing_extensions>=3.10.0',
         'requests>=2.25.0',
         'six>=1.15.0',
         'urllib3>=1.26.0'

spotipy/cache_handler.py

@@ -1,16 +1,33 @@
 # -*- coding: utf-8 -*-
 
-__all__ = ['CacheHandler', 'CacheFileHandler', 'MemoryCacheHandler']
+__all__ = ['CacheHandler', 'CacheFileHandler', 'MemoryCacheHandler', 'TokenInfo']
 
 import errno
 import json
 import logging
 import os
-from spotipy.util import CLIENT_CREDS_ENV_VARS
+import sys
 from abc import ABC, abstractmethod
+from typing import Optional
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from spotipy.util import CLIENT_CREDS_ENV_VARS
 
 logger = logging.getLogger(__name__)
 
+TokenInfo = TypedDict("TokenInfo", {
+    "access_token": str,
+    "token_type": str,
+    "scope": str,
+    "expires_in": int,
+    "refresh_token": str,
+    "expires_at": int
+})
+
 
 class CacheHandler(ABC):
     """
@@ -23,13 +40,13 @@ class CacheHandler(ABC):
     """
 
     @abstractmethod
-    def get_cached_token(self):
+    def get_cached_token(self) -> Optional[TokenInfo]:
         """
         Get and return a token_info dictionary object.
         """
 
     @abstractmethod
-    def save_token_to_cache(self, token_info):
+    def save_token_to_cache(self, token_info: TokenInfo) -> None:
         """
         Save a token_info dictionary object to the cache and return None.
         """
@@ -42,8 +59,8 @@ class CacheFileHandler(CacheHandler):
     """
 
     def __init__(self,
-                 cache_path=None,
-                 username=None):
+                 cache_path: Optional[str] = None,
+                 username: Optional[str] = None):
         """
         Parameters:
              * cache_path: May be supplied, will otherwise be generated
@@ -61,7 +78,7 @@ def __init__(self,
                 cache_path += "-" + str(username)
             self.cache_path = cache_path
 
-    def get_cached_token(self):
+    def get_cached_token(self) -> Optional[TokenInfo]:
         token_info = None
 
         try:
@@ -78,7 +95,7 @@ def get_cached_token(self):
 
         return token_info
 
-    def save_token_to_cache(self, token_info):
+    def save_token_to_cache(self, token_info: TokenInfo) -> None:
         try:
             f = open(self.cache_path, "w")
             f.write(json.dumps(token_info))
@@ -95,15 +112,15 @@ class MemoryCacheHandler(CacheHandler):
     instance is freed.
     """
 
-    def __init__(self, token_info=None):
+    def __init__(self, token_info: Optional[TokenInfo] = None):
         """
         Parameters:
             * token_info: The token info to store in memory. Can be None.
         """
         self.token_info = token_info
 
-    def get_cached_token(self):
+    def get_cached_token(self) -> Optional[TokenInfo]:
         return self.token_info
 
-    def save_token_to_cache(self, token_info):
+    def save_token_to_cache(self, token_info: TokenInfo) -> None:
         self.token_info = token_info