docs: improve docstrings, plus logging

osm_login_python/core.py

@@ -1,5 +1,8 @@
+"""Core logic for OSM OAuth."""
+
 import base64
 import json
+import logging
 
 from itsdangerous import BadSignature, SignatureExpired
 from itsdangerous.url_safe import URLSafeSerializer
@@ -8,9 +11,14 @@
 
 from . import Login, Token
 
+log = logging.getLogger(__name__)
+
 
 class Auth:
+    """Main class for OSM login."""
+
     def __init__(self, osm_url, client_id, client_secret, secret_key, login_redirect_uri, scope):
+        """Set object params and get OAuth2 session."""
         self.osm_url = osm_url
         self.client_secret = client_secret
         self.secret_key = secret_key
@@ -22,22 +30,31 @@ def __init__(self, osm_url, client_id, client_secret, secret_key, login_redirect
 
     def login(
         self,
-    ):
-        """Provides login URL using the session created by osm client id and redirect uri supplied."""
+    ) -> dict:
+        """Generate login URL from OSM session.
+
+        Provides a login URL using the session created by osm
+        client id and redirect uri supplied.
+
+        Returns:
+            dict: {'login_url': 'URL'}
+        """
         authorize_url = f"{self.osm_url}/oauth2/authorize/"
         login_url, _ = self.oauth.authorization_url(authorize_url)
         return json.loads(Login(login_url=login_url).json())
 
-    def callback(self, callback_url: str):
-        """Performs token exchange between OpenStreetMap and the Application supplied.
+    def callback(self, callback_url: str) -> str:
+        """Performs token exchange between OSM and the callback website.
 
         Core will use Oauth secret key from configuration while deserializing token,
         provides access token that can be used for authorized endpoints.
 
-        Parameters: callback_url : Absolute URL should be passed which is catched from login_redirect_uri
+        Args:
+            callback_url(str): Absolute URL should be passed which
+                is catched from login_redirect_uri.
 
         Returns:
-        - access_token (json)
+            access_token(str): The decoded access token.
         """
         token_url = f"{self.osm_url}/oauth2/token"
         self.oauth.fetch_token(
@@ -61,18 +78,31 @@ def callback(self, callback_url: str):
         token = Token(access_token=access_token)
         return json.loads(token.json())
 
-    def deserialize_access_token(self, access_token: str):
-        """Returns the userdata as json from access token , Can be used for login required decorator or to check the access token provided."""
+    def deserialize_access_token(self, access_token: str) -> dict:
+        """Returns the userdata as JSON from access token.
+
+        Can be used for login required decorator or to check
+        the access token provided.
+
+        Args:
+            access_token(str): The access token from Auth.callback()
+
+        Returns:
+            user_data(dict): A JSON of user data from OSM.
+        """
         deserializer = URLSafeSerializer(self.secret_key)
 
         try:
             decoded_token = base64.b64decode(access_token)
-        except Exception:
-            raise ValueError("Could not decode token")
+        except Exception as e:
+            log.error(e)
+            log.error(f"Could not decode token: {access_token}")
+            raise ValueError("Could not decode token") from e
 
         try:
             user_data = deserializer.loads(decoded_token)
-        except (SignatureExpired, BadSignature):
-            raise ValidationError("Invalid token")
+        except (SignatureExpired, BadSignature) as e:
+            log.error(e)
+            raise ValidationError("Invalid token") from e
 
         return user_data