Adds client token age fetching, plus all related documentation (#106)

Author: alexgolec

docs/auth.rst

@@ -120,6 +120,29 @@ pip's executable locations to your ``$PATH``. If you're having a hard time, feel
 free to ask for help on our `Discord server <https://discord.gg/BEr6y6Xqyv>`__.
 
 
+-------------------------
+Notes on Token Expiration
+-------------------------
+
+Tokens are only good for seven days. Under the hood, each token is actually good 
+for *thirty minutes*, but the library transparently issues a request to Schwab 
+to fetch a new token when it's time to do so. (This means the "token file" would 
+more accurately be called the "file containing the specifications required to 
+generate new tokens," but "token file" is simpler.) Once seven days have passed 
+since the token was originally created, they will refuse to grant new thirty 
+minute tokens, and you need to delete your old token file and create a new one 
+by following your preferred token creation flow.
+
+In practice, this means most users will want to adopt some sort of proactive 
+token refreshing method. For instance, if you trade during the weekdays, you may 
+want to delete and recreate your token on Sunday before the markets open. 
+
+For users wanting to craft more custom workflows, the client :meth:`exposes the 
+age of the token <schwab.client.Client.token_age>`. Note, however, that the 
+seven day token age restriction is implemented by Schwab, and so the token may 
+become expired sooner *or* later than seven days.
+
+
 ----------------------
 Advanced Functionality
 ----------------------
@@ -138,6 +161,7 @@ instead.
 
 .. autofunction:: schwab.auth.client_from_access_functions
 
+
 ---------------
 Troubleshooting
 ---------------

docs/client.rst

@@ -185,6 +185,13 @@ specification can be set using this method:
 .. automethod:: schwab.client.Client.set_timeout
 
 
++++++++++
+Token Age
++++++++++
+
+.. automethod:: schwab.client.Client.token_age
+
+
 ++++++++++++
 Account Info
 ++++++++++++

schwab/auth.py

@@ -85,6 +85,11 @@ def from_loaded_token(cls, token, unwrapped_token_write_func):
                 token['creation_timestamp'],
                 unwrapped_token_write_func)
 
+    def token_age(self):
+        '''Returns the number of second elapsed since this token was initially 
+        created.'''
+        return int(time.time()) - self.creation_timestamp
+
     def wrapped_token_write_func(self):
         '''
         Returns a version of the unwrapped write function which wraps the token 

schwab/client/base.py

@@ -116,6 +116,16 @@ def set_timeout(self, timeout):
                         examples.'''
         self.session.timeout = timeout
 
+    def token_age(self):
+        '''Get the age of the token used to create this client, in seconds. For 
+        users who prefer to proactively delete their token files before the 
+        become expired, this method can offer a hint for when to do so.
+
+        Note that the actual expiration is governed by Schwab's internal 
+        implementation, and the token might become expired sooner *or* later 
+        than the documented seven day term.'''
+        return self.token_metadata.token_age()
+
 
     ##########################################################################
     # Accounts

tests/auth_test.py

@@ -447,3 +447,14 @@ def test_reject_tokens_without_creation_timestamp(self):
         with self.assertRaisesRegex(ValueError, 'token format has changed'):
             metadata = auth.TokenMetadata.from_loaded_token(
                     {'token': 'yes'}, lambda t: None)
+
+
+    @no_duplicates
+    @patch('time.time', unittest.mock.MagicMock(return_value=MOCK_NOW))
+    def test_token_age(self):
+        token = {'token': 'yes', 'creation_timestamp': TOKEN_CREATION_TIMESTAMP}
+
+        metadata = auth.TokenMetadata.from_loaded_token(
+                token, unwrapped_token_write_func=None)
+        self.assertEqual(metadata.token_age(),
+                         MOCK_NOW - TOKEN_CREATION_TIMESTAMP)

tests/client_test.py

@@ -96,6 +96,16 @@ def test_set_timeout(self):
         self.assertEqual(timeout, self.client.session.timeout)
 
 
+    def test_token_age(self):
+        token_metadata = MagicMock()
+        token_metadata.token_age.return_value = 1000
+        client = self.client_class(
+                API_KEY, self.mock_session, token_metadata=token_metadata)
+
+        self.assertEqual(client.token_age(), 1000)
+
+
+
     # get_account