Document middleware

Author: jobala

msgraphcore/graph_session.py

@@ -25,6 +25,7 @@ def __init__(self, auth_provider: AuthProviderBase, middleware: list = []):
 
         auth_handler = AuthorizationHandler(auth_provider)
 
+        # The authorization handler should be the first middleware in the pipeline.
         middleware.insert(0, auth_handler)
         self._register(middleware)
 
@@ -87,7 +88,7 @@ def delete(self, url, **kwargs):
 
     def _graph_url(self, url: str) -> str:
         """Appends BASE_URL to user provided path
-        
+
         :param url: user provided path
         :return: graph_url
         """

msgraphcore/middleware/_middleware.py

@@ -5,6 +5,11 @@
 
 
 class MiddlewarePipeline(HTTPAdapter):
+    """MiddlewarePipeline, entry point of middleware
+
+    The pipeline is implemented as a linked-list, read more about
+    it here https://buffered.dev/middleware-python-requests/
+    """
     def __init__(self):
         super().__init__()
         self._middleware = None
@@ -27,6 +32,12 @@ def _middleware_present(self):
 
 
 class BaseMiddleware(HTTPAdapter):
+    """Base class for middleware
+
+    Handles moving a Request to the next middleware in the pipeline.
+    If the current middleware is the last one in the pipeline, it
+    makes a network request
+    """
     def __init__(self):
         super().__init__()
         self.next = None

msgraphcore/middleware/authorization.py

@@ -11,14 +11,17 @@ def __init__(self, auth_provider: AuthProviderBase):
         self.retry_count = 0
 
     def send(self, request, **kwargs):
+        # Checks if there're any options for this middleware
         options = self._get_middleware_options()
+        # If there is, get the scopes from the options
         if options:
             self.auth_provider.scopes = options.scopes
 
         token = self.auth_provider.get_access_token()
         request.headers.update({'Authorization': 'Bearer {}'.format(token)})
         response = super().send(request, **kwargs)
 
+        # Token might have expired just before transmission, retry the request
         if response.status_code == 401 and self.retry_count < 2:
             self.retry_count += 1
             return self.send(request, **kwargs)