Change token() method to property

- Add lots of type hints
- Add docs about how to get serialized token value
- More docs

Author: davidolrik

doc/source/index.rst

@@ -65,8 +65,28 @@ Creating and signing new tokens
   token.set_claim('sub', 42)
   token.set_claim('foo', 'bar')
 
-  # Sign token with private key
-  token.sign()
+  # Sign token with private key, and get serialized token back
+  token_str = token.sign()
+
+  # You can also get the serialized token from the token objectt by accessing
+  # the token_str property
+  token_str = token.token_str
+
+As a convenience, if you use the token object in string or boolean context it
+will do *the right thing™*.
+
+.. code:: python
+
+  # Token in string context gives you the serialized token
+  token_str = str(token)
+
+  # Token in boolean context gives you the validity of the token
+  is_valid = bool(token)
+
+  # Parse token from string, and do stuff with it, if it is valid
+  token = MySWT(http_header_value)
+  if token:
+      # Do stuff with the valid token
 
 API Reference
 -------------

src/swt/__init__.py

@@ -20,21 +20,21 @@ class SWT:
     extend the algorithm specific sub class. Currently only RSA SHA256 is implemented.
     """
     # Supported algorithm constants
-    ALGORITHM_RSA_SHA256  = 'RSASHA256'
-    ALGORITHM_HMAC_SHA256 = 'HMACSHA256'
+    ALGORITHM_RSA_SHA256 : str = 'RSASHA256'
+    ALGORITHM_HMAC_SHA256: str = 'HMACSHA256'
 
     # Internals to override Selected algorithm
-    default_ttl = 3600
+    default_ttl: int = 3600
 
     # Standard claim names
-    iss_claim = 'Issuer'
-    exp_claim = 'ExpiresOn'
-    aud_claim = 'Audience'
+    iss_claim: str = 'Issuer'
+    exp_claim: str = 'ExpiresOn'
+    aud_claim: str = 'Audience'
 
     # Extra claim names modeled after JWT claim names
-    sub_claim = 'sub'
-    iat_claim = 'iat'
-    sid_claim = 'sid'
+    sub_claim: str = 'sub'
+    iat_claim: str = 'iat'
+    sid_claim: str = 'sid'
 
     def __init__(self, token_str: typing.Optional[str] = None):
         """Create new SWT"""
@@ -47,16 +47,24 @@ def __init__(self, token_str: typing.Optional[str] = None):
 
         # If called with a token, set and verify
         if token_str is not None:
-            self.token(token_str)
+            self.token_str = token_str
 
     @property
     def is_valid(self):
-        """Check if the SWT is both sign and not expired"""
+        """Check if the SWT is both sign and not expired
+
+        Returns:
+            bool: token validity
+        """
         return self.is_signed and not self.is_expired
 
     @property
     def is_expired(self):
-        """Check if the SWT is expired"""
+        """Check if the SWT is expired
+
+        Returns:
+            bool: is expired
+        """
         if not self.is_signed:
             return True
         return int(self._token_claims.get(self.__class__.exp_claim, 0)) < int(time.time())
@@ -89,22 +97,29 @@ def __bool__(self):
     def __str__(self):
         return self._token_str
 
-    def get_public_key(self):
+    def get_public_key(self) -> str:
         """Implement this in your own subclass to find and load the public key by issuer"""
         raise NotImplementedError("Please implement your own get_public_key() method")
 
-    def get_private_key(self):
+    def get_private_key(self) -> str:
         """Implement this in your own subclass to find and load the private key by issuer"""
         raise NotImplementedError("Please implement your own get_public_key() method")
 
-    def set_claim(self, claim, value):
+    def set_claim(self, claim: str, value: str):
         self._token_claims[claim] = value
 
-    def get_claim(self, claim):
+    def get_claim(self, claim: str) -> str:
         return self._token_claims[claim]
 
-    def token(self, token: str):
-        """Set token from string"""
+    @property
+    def token_str(self) -> str:
+        """Token as serialized string"""
+        return self._token_str
+
+    @token_str.setter
+    def token_str(self, token: str):
+        """Token as string"""
+
         # Allow caller to take http header and parse it directly to us
         self._token_str = str(token).replace('Bearer ', '')
 
@@ -128,13 +143,21 @@ def algorithm(self):
         """The algorithm used for the SWT"""
         raise NotImplementedError("Please implement algorithm specific algorithm @property method")
 
-    def sign(self):
-        """Algorithm specific sign() method"""
+    def sign(self) -> str:
+        """Algorithm specific sign() method
+
+        Returns:
+            str: signed token
+        """
         raise NotImplementedError("Please implement algorithm specific sign() method")
 
     @property
     def is_signed(self):
-        """Algorithm specific is_signed() property"""
+        """Algorithm specific is_signed() property
+
+        Returns:
+            bool: signed status
+        """
         raise NotImplementedError("Please implement algorithm specific is_signed @property method")
 
 class SWT_RSA_SHA256(SWT):
@@ -156,8 +179,9 @@ def sign(self):
         self._token_signature_str = quote(b64encode(self._token_signature))
         self._token_str = self._token_claims_str + f'&{self.algorithm}=' + self._token_signature_str
 
+
     @property
-    def is_signed(self):
+    def is_signed(self) -> bool:
         # Give on beforehand if we don't have a signature
         if not self._token_signature:
             return False

tests/test_swt_rsa_sha256.py

@@ -75,14 +75,14 @@ def test_valid_swt_from_string():
     assert token.is_valid, "Token is valid (both signed and not expired)"
     assert bool(token) == True, "Token with valid signature has a boolean value of True"
     assert token.get_claim('foo') == 'bar', "Token has claim foo with value of bar"
-
+    assert token.token_str == str(token), "Token has string value"
 
 def test_swt_broken_signature():
     # Remove one character from token signature
     broken_token_str = pytest.test_token_str[0:len(pytest.test_token_str)-5] + pytest.test_token_str[-4:]
 
     token = MySWT()
-    token.token(broken_token_str)
+    token.token_str = broken_token_str
     assert token.is_signed == False, "Token has broken signed (we broke it on purpose)"
     assert bool(token) == False, "Token with invalid signature has a boolean value of False"
     assert token.is_expired == True, "Token is expired, even if date is ok"
@@ -92,7 +92,7 @@ def test_swt_no_signature():
     # Remove signature from valid token, and create new invalid token
     token = MySWT()
     broken_token_str, _ = pytest.test_token_str.rsplit(f'&{token.algorithm}=')
-    token.token(broken_token_str)
+    token.token_str = broken_token_str
 
     assert token.is_signed == False, "Token has broken signed (we broke it on purpose)"
     assert bool(token) == False, "Token with invalid signature has a boolean value of False"