Merge pull request #82 from microsoftgraph/feat/graph-client-factory

Feat/graph client factory

Author: samwelkanda

.github/workflows/ci.yml

@@ -38,6 +38,6 @@ jobs:
           pipenv run pylint msgraphcore --disable=W --rcfile=.pylintrc
       - name: Test with unittest
         run: |
-          pipenv run coverage run -m unittest discover tests/unit
-          pipenv run coverage run -m unittest discover tests/integration
+          pipenv run coverage run -m pytest tests/unit
+          pipenv run coverage run -m pytest tests/integration
           pipenv run coverage html

.pre-commit-config.yaml

@@ -23,3 +23,17 @@ repos:
         language: system
         entry: pipenv run pylint msgraphcore --disable=W --rcfile=.pylintrc
         types: [python]
+
+      - id: pytest-unit
+        name: pytest-unit
+        stages: [commit]
+        language: system
+        entry: pipenv run coverage run -m pytest tests/unit
+        types: [python]
+
+      - id: pytest-integration
+        name: pytest-integration
+        stages: [commit]
+        language: system
+        entry: pipenv run coverage run -m pytest tests/integration
+        types: [python]

Pipfile

@@ -9,10 +9,11 @@ pre-commit = "==2.10.1"
 
 [dev-packages] # Packages required to develop the application
 coverage = "==5.0.3"
-pylint = "==2.6.0"
 responses = "==0.10.12"
 flit = "==2.2.0"
 azure-identity = "==1.5.0"
 isort = "==5.7.0"
 yapf = "==0.30.0"
 mypy = "==0.800"
+pylint = "==2.7.4"
+pytest = "*"

Pipfile.lock

@@ -0,0 +1,46 @@
+@startuml ClientFactory
+enum NationalClouds {
+  +GERMANY
+  +PUBLIC
+  +US_GOV
+  +CHINA
+}
+
+class HttpClientFactory {
+  -TIMEOUT: string
+  -SDK_VERSION: string
+  -BASE_URL: string
+  -pipeline: MiddlewarePipeline
+
+  +__init__(session: Session, cloud: NationalClouds)
+  +with_default_middleware(auth_provider: TokenCredential): Session
+  +with_user_middleware(middleware: [Middleware]): Session
+}
+
+
+class Session {}
+
+class GraphClient {
+  -session: Session
+
+  +__init__(session: Session, credential: TokenCredential,
+   version: ApiVersion, cloud: NationalClouds)
+  +get()
+  +post()
+  +put()
+  +patch()
+  +delete()
+}
+
+package "middleware" {
+  class MiddlewarePipeline {}
+}
+
+HttpClientFactory --> NationalClouds
+HttpClientFactory -right-> middleware
+HttpClientFactory --> Session
+
+GraphClient -right-> HttpClientFactory
+
+note right of Session: HTTPClient imported from requests
+@enduml

docs/design/client_factory.puml

@@ -1,7 +1,3 @@
-"""msgraph-core"""
-
-from msgraphcore.graph_session import GraphSession
-
 from .constants import SDK_VERSION
 
 __version__ = SDK_VERSION

msgraphcore/__init__.py

@@ -0,0 +1,87 @@
+import functools
+from typing import Optional
+
+from requests import Session
+
+from msgraphcore.constants import CONNECTION_TIMEOUT, REQUEST_TIMEOUT
+from msgraphcore.enums import APIVersion, NationalClouds
+from msgraphcore.middleware.abc_token_credential import TokenCredential
+from msgraphcore.middleware.authorization import AuthorizationHandler
+from msgraphcore.middleware.middleware import BaseMiddleware, MiddlewarePipeline
+
+
+class HTTPClientFactory:
+    """Constructs native HTTP Client(session) instances configured with either custom or default
+    pipeline of middleware.
+
+    :func: Class constructor accepts a user provided session object and kwargs to configure the
+        request handling behaviour of the client
+    :keyword enum api_version: The Microsoft Graph API version to be used, for example
+        `APIVersion.v1` (default). This value is used in setting the base url for all requests for
+        that session.
+        :class:`~msgraphcore.enums.APIVersion` defines valid API versions.
+    :keyword enum cloud: a supported Microsoft Graph cloud endpoint.
+        Defaults to `NationalClouds.Global`
+        :class:`~msgraphcore.enums.NationalClouds` defines supported sovereign clouds.
+    :keyword tuple timeout: Default connection and read timeout values for all session requests.
+        Specify a tuple in the form of Tuple(connect_timeout, read_timeout) if you would like to set
+        the values separately. If you specify a single value for the timeout, the timeout value will
+        be applied to both the connect and the read timeouts.
+    :keyword obj session: A custom Session instance from the python requests library
+    """
+    def __init__(self, **kwargs):
+        """Class constructor that accepts a user provided session object and kwargs
+        to configure the request handling behaviour of the client"""
+        self.api_version = kwargs.get('api_version', APIVersion.v1)
+        self.endpoint = kwargs.get('cloud', NationalClouds.Global)
+        self.timeout = kwargs.get('timeout', (CONNECTION_TIMEOUT, REQUEST_TIMEOUT))
+        self.session = kwargs.get('session', Session())
+
+        self._set_base_url()
+        self._set_default_timeout()
+
+    def create_with_default_middleware(self, credential: TokenCredential, **kwargs) -> Session:
+        """Applies the default middleware chain to the HTTP Client
+
+        :param credential: TokenCredential used to acquire an access token for the Microsoft
+            Graph API. Created through one of the credential classes from `azure.identity`
+        """
+        middleware = [
+            AuthorizationHandler(credential, **kwargs),
+        ]
+        self._register(middleware)
+        return self.session
+
+    def create_with_custom_middleware(self, middleware: [BaseMiddleware]) -> Session:
+        """Applies a custom middleware chain to the HTTP Client
+
+        :param list middleware: Custom middleware(HTTPAdapter) list that will be used to create
+            a middleware pipeline. The middleware should be arranged in the order in which they will
+            modify the request.
+        """
+        if not middleware:
+            raise ValueError("Please provide a list of custom middleware")
+        self._register(middleware)
+        return self.session
+
+    def _set_base_url(self):
+        """Helper method to set the base url"""
+        base_url = self.endpoint + '/' + self.api_version
+        self.session.base_url = base_url
+
+    def _set_default_timeout(self):
+        """Helper method to set a default timeout for the session
+        Reference: https://github.com/psf/requests/issues/2011
+        """
+        self.session.request = functools.partial(self.session.request, timeout=self.timeout)
+
+    def _register(self, middleware: [BaseMiddleware]) -> None:
+        """
+        Helper method that constructs a middleware_pipeline with the specified middleware
+        """
+        if middleware:
+            middleware_pipeline = MiddlewarePipeline()
+            for ware in middleware:
+                middleware_pipeline.add_middleware(ware)
+
+            self.session.mount('https://', middleware_pipeline)

msgraphcore/client_factory.py

@@ -0,0 +1,19 @@
+#pylint: disable=invalid-name
+
+from enum import Enum
+
+
+class APIVersion(str, Enum):
+    """Enumerated list of supported API Versions"""
+    beta = 'beta'
+    v1 = 'v1.0'
+
+
+class NationalClouds(str, Enum):
+    """Enumerated list of supported sovereign clouds"""
+
+    China = 'https://microsoftgraph.chinacloudapi.cn'
+    Germany = 'https://graph.microsoft.de'
+    Global = 'https://graph.microsoft.com'
+    US_DoD = 'https://dod-graph.microsoft.us'
+    US_GOV = 'https://graph.microsoft.us'

msgraphcore/enums.py

@@ -0,0 +1,121 @@
+from typing import List, Optional
+
+from requests import Session
+
+from msgraphcore.client_factory import HTTPClientFactory
+from msgraphcore.middleware.abc_token_credential import TokenCredential
+from msgraphcore.middleware.middleware import BaseMiddleware
+from msgraphcore.middleware.options.middleware_control import middleware_control
+
+
+class GraphClient:
+    """Constructs a custom HTTPClient to be used for requests against Microsoft Graph
+
+    :keyword credential: TokenCredential used to acquire an access token for the Microsoft
+        Graph API. Created through one of the credential classes from `azure.identity`
+    :keyword list middleware: Custom middleware(HTTPAdapter) list that will be used to create
+        a middleware pipeline. The middleware should be arranged in the order in which they will
+        modify the request.
+    :keyword enum api_version: The Microsoft Graph API version to be used, for example
+        `APIVersion.v1` (default). This value is used in setting the base url for all requests for
+        that session.
+        :class:`~msgraphcore.enums.APIVersion` defines valid API versions.
+    :keyword enum cloud: a supported Microsoft Graph cloud endpoint.
+        Defaults to `NationalClouds.Global`
+        :class:`~msgraphcore.enums.NationalClouds` defines supported sovereign clouds.
+    :keyword tuple timeout: Default connection and read timeout values for all session requests.
+        Specify a tuple in the form of Tuple(connect_timeout, read_timeout) if you would like to set
+        the values separately. If you specify a single value for the timeout, the timeout value will
+        be applied to both the connect and the read timeouts.
+    :keyword obj session: A custom Session instance from the python requests library
+    """
+    __instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if not GraphClient.__instance:
+            GraphClient.__instance = object.__new__(cls)
+        return GraphClient.__instance
+
+    def __init__(self, **kwargs):
+        """
+        Class constructor that accepts a session object and kwargs to
+        be passed to the HTTPClientFactory
+        """
+        self.graph_session = self.get_graph_session(**kwargs)
+
+    @middleware_control.get_middleware_options
+    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 self.graph_session.get(self._graph_url(url), **kwargs)
+
+    @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 self.graph_session.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 self.graph_session.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 self.graph_session.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 self.graph_session.delete(self._graph_url(url), **kwargs)
+
+    def _graph_url(self, url: str) -> str:
+        """Appends BASE_URL to user provided path
+        :param url: user provided path
+        :return: graph_url
+        """
+        return self.graph_session.base_url + url if (url[0] == '/') else url
+
+    @staticmethod
+    def get_graph_session(**kwargs):
+        """Method to always return a single instance of a HTTP Client"""
+
+        credential = kwargs.get('credential')
+        middleware = kwargs.get('middleware')
+
+        if credential and middleware:
+            raise ValueError(
+                "Invalid parameters! Both TokenCredential and middleware cannot be passed"
+            )
+        if not credential and not middleware:
+            raise ValueError("Invalid parameters!. Missing TokenCredential or middleware")
+
+        if credential:
+            return HTTPClientFactory(**kwargs).create_with_default_middleware(credential)
+        return HTTPClientFactory(**kwargs).create_with_custom_middleware(middleware)