Document graph_session.py and constants.py

Author: jobala

msgraphcore/constants.py

@@ -6,5 +6,5 @@
 BASE_URL = 'https://graph.microsoft.com/v1.0'
 SDK_VERSION = '0.0.1-0'
 
-# MiddlewareOptions
+# Used as the key for AuthMiddlewareOption in MiddlewareControl
 AUTH_MIDDLEWARE_OPTIONS = 'AUTH_MIDDLEWARE_OPTIONS'

msgraphcore/graph_session.py

@@ -2,7 +2,7 @@
 Graph Session
 """
 
-from requests import Session, Response
+from requests import Session
 
 from msgraphcore.constants import BASE_URL, SDK_VERSION
 from msgraphcore.middleware._middleware import MiddlewarePipeline, BaseMiddleware
@@ -12,8 +12,11 @@
 
 
 class GraphSession(Session):
-    """
-    Extends session object with graph functionality
+    """Extends Session with Graph functionality
+
+    Extends Session by adding support for middleware options and middleware pipeline
+
+
     """
     def __init__(self, auth_provider: AuthProviderBase, middleware: list = []):
         super().__init__()
@@ -26,33 +29,79 @@ def __init__(self, auth_provider: AuthProviderBase, middleware: list = []):
         self._register(middleware)
 
     @middleware_control.get_middleware_options
-    def get(self, url, **kwargs):
+    def get(self, url: str, **kwargs):
+        r"""Sends a GET request. Returns :class:`Response` object.
+
+        :param url: URL for the new :class:`Request` object.
+        :param \*\*kwargs: Optional arguments that ``request`` takes.
+        :rtype: requests.Response
+        """
         return super().get(self._graph_url(url))
 
     @middleware_control.get_middleware_options
     def post(self, url, data=None, json=None, **kwargs):
+        r"""Sends a POST request. Returns :class:`Response` object.
+
+        :param url: URL for the new :class:`Request` object.
+        :param data: (optional) Dictionary, list of tuples, bytes, or file-like
+            object to send in the body of the :class:`Request`.
+        :param json: (optional) json to send in the body of the :class:`Request`.
+        :param \*\*kwargs: Optional arguments that ``request`` takes.
+        :rtype: requests.Response
+        """
         return super().post(self._graph_url(url), data, json, **kwargs)
 
     @middleware_control.get_middleware_options
     def put(self, url, data=None, **kwargs):
+        r"""Sends a PUT request. Returns :class:`Response` object.
+
+        :param url: URL for the new :class:`Request` object.
+        :param data: (optional) Dictionary, list of tuples, bytes, or file-like
+            object to send in the body of the :class:`Request`.
+        :param \*\*kwargs: Optional arguments that ``request`` takes.
+        :rtype: requests.Response
+        """
         return super().put(self._graph_url(url), data, **kwargs)
 
     @middleware_control.get_middleware_options
     def patch(self, url, data=None, **kwargs):
+        r"""Sends a PATCH request. Returns :class:`Response` object.
+
+        :param url: URL for the new :class:`Request` object.
+        :param data: (optional) Dictionary, list of tuples, bytes, or file-like
+            object to send in the body of the :class:`Request`.
+        :param \*\*kwargs: Optional arguments that ``request`` takes.
+        :rtype: requests.Response
+        """
         return super().patch(self._graph_url(url), data, **kwargs)
 
     @middleware_control.get_middleware_options
     def delete(self, url, **kwargs):
+        r"""Sends a DELETE request. Returns :class:`Response` object.
+
+        :param url: URL for the new :class:`Request` object.
+        :param \*\*kwargs: Optional arguments that ``request`` takes.
+        :rtype: requests.Response
+        """
         return super().delete(url, **kwargs)
 
-    def _graph_url(self, url: str) -> Response:
+    def _graph_url(self, url: str) -> str:
+        """Appends BASE_URL to user provided path
+        
+        :param url: user provided path
+        :return: graph_url
+        """
         return self._base_url+url if (url[0] == '/') else url
 
     def _register(self, middleware: [BaseMiddleware]) -> None:
+        """Adds middleware to middleware_pipeline
+
+        :param middleware: list of middleware
+        """
         if middleware:
-            middleware_adapter = MiddlewarePipeline()
+            middleware_pipeline = MiddlewarePipeline()
 
             for ware in middleware:
-                middleware_adapter.add_middleware(ware)
+                middleware_pipeline.add_middleware(ware)
 
-            self.mount('https://', middleware_adapter)
+            self.mount('https://', middleware_pipeline)