Add python sdk

Author: mjcuva

packages/python/.gitignore

@@ -0,0 +1,4 @@
+.eggs/*
+dist/
+*.egg-info
+build/*

packages/python/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2020, ReadMe
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

packages/python/building.md

@@ -0,0 +1,2 @@
+Building: `python3 setup.py sdist bdist_wheel`
+Uploading to pypi: `python3 -m twine upload dist/*`

packages/python/metrics/Metrics.py

@@ -0,0 +1,62 @@
+import queue
+import threading
+import requests
+import json
+from pprint import pprint
+
+from werkzeug import Request
+from pip._vendor.requests import __version__
+
+from metrics import MetricsApiConfig, ResponseInfoWrapper
+from metrics.PayloadBuilder import PayloadBuilder
+
+
+class Metrics:
+    """
+    This is the internal central controller class invoked by the WSGI middleware. It handles the creation, queueing,
+    and submission of the requests.
+    """
+    PACKAGE_NAME: str = 'readme/metrics'
+    METRICS_API: str = 'https://metrics.readme.io'
+
+    def __init__(self, config: MetricsApiConfig):
+        """
+        Constructs and initializes the ReadMe Metrics controller class with the specified configuration.
+        :param config: Running configuration
+        """
+
+        self.config = config
+        self.payload_builder = PayloadBuilder(config.BLACKLIST, config.WHITELIST, config.IS_DEVELOPMENT_MODE, config.GROUPING_FUNCTION)
+        self.queue = queue.Queue()
+
+    def process(self, request: Request, response: ResponseInfoWrapper) -> None:
+        """
+        Enqueues a request/response combination to be submitted to the ReadMe Metrics API.
+        :param request: werkzeug.Request request object
+        :param response: ResponseInfoWrapper response object
+        """
+        self.queue.put(self.payload_builder(request, response))
+
+        if(self.queue.qsize() >= self.config.BUFFER_LENGTH):
+            if(self.config.IS_BACKGROUND_MODE):
+                threading.Thread(target=self._processAll, daemon=True).start()
+            else:
+                self._processAll()
+
+    def _processAll(self) -> None:
+        result_list = []
+        while not self.queue.empty():
+            obj = self.queue.get_nowait()
+            if obj:
+                result_list.append(obj)
+
+        payload = json.dumps(result_list)
+
+        # print("Posting: " + payload)
+
+        readme_result = requests.post(self.METRICS_API + "/request", auth=(self.config.README_API_KEY, ""), data = payload, headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'readme-metrics-' + __version__
+        })
+
+        # print("Response: " + readme_result.text)

packages/python/metrics/MetricsApiConfig.py

@@ -0,0 +1,79 @@
+from typing import List
+
+
+class MetricsApiConfig:
+    """
+    ReadMe Metrics API configuration object
+
+    ...
+    Attributes
+    ----------
+    README_API_KEY: str
+        (required) Your ReadMe API key
+    GROUPING_FUNCTION = lambda
+        (required)
+        Grouping function to construct an identity object. It receives the current request as a parameter, and must
+        return a dictionary containing at least an "id" field, and optionally "label" and "email" fields.
+
+        The main purpose of the identity object is to identify the API's caller.
+    BUFFER_LENGTH: int
+        (optional, default = 10)
+        Number of requests to buffer before sending data to ReadMe.
+    IS_DEVELOPMENT_MODE: bool
+        (optional, default = False) Determines whether you are running in development mode.
+    IS_BACKGROUND_MODE: bool
+        (optional, default = True) Determines whether to issue the call to the ReadMe API in a background thread.
+    BLACKLIST: List[str]
+        (optional) An array of headers and JSON body properties to skip sending to ReadMe.
+
+        If you configure a blacklist, it will override any whitelist configuration.
+    WHITELIST: List[str]
+        (optional) An array of headers and JSON body properties to send to ReadMe.
+
+        If this option is configured, ONLY the whitelisted properties will be sent.
+    """
+    README_API_KEY: str = None
+    BUFFER_LENGTH: int = 10
+    GROUPING_FUNCTION = lambda req: None
+    IS_DEVELOPMENT_MODE: bool = False
+    IS_BACKGROUND_MODE: bool = True
+    BLACKLIST: List[str] = []
+    WHITELIST: List[str] = []
+
+    def __init__(self,
+            api_key: str,
+            grouping_function,
+            buffer_length:int = 10,
+            development_mode:bool = False,
+            background_worker_mode:bool = True,
+            blacklist:List[str] = None,
+            whitelist:List[str] = None):
+        """
+        Initializes an instance of the MetricsApiConfig object, with defaults set where possible.
+        :param api_key: (required) Your ReadMe API key
+        :param grouping_function: (required)
+            Grouping function to construct an identity object. It receives the current request as a parameter, and must
+            return a dictionary containing at least an "id" field, and optionally "label" and "email" fields.
+
+            The main purpose of the identity object is to identify the API's caller.
+        :param buffer_length: (optional, default = 10) Number of requests to buffer before sending data to ReadMe.
+        :param development_mode: (optional, default = False) Determines whether you are running in development mode.
+        :param background_worker_mode: (optional, default = True)
+            Determines whether to issue the call to the ReadMe API in a background thread.
+        :param blacklist: (optional)
+            An array of headers and JSON body properties to skip sending to ReadMe.
+
+            If you configure a blacklist, it will override any whitelist configuration.
+        :param whitelist: (optional)
+            An array of headers and JSON body properties to send to ReadMe.
+
+            If this option is configured, ONLY the whitelisted properties will be sent.
+        """
+
+        self.README_API_KEY = api_key
+        self.GROUPING_FUNCTION = grouping_function
+        self.BUFFER_LENGTH = buffer_length
+        self.IS_DEVELOPMENT_MODE = development_mode
+        self.IS_BACKGROUND_MODE = background_worker_mode
+        self.BLACKLIST = blacklist or []
+        self.WHITELIST = whitelist or []

packages/python/metrics/MetricsMiddleware.py

@@ -0,0 +1,104 @@
+from metrics.Metrics import Metrics
+from metrics.MetricsApiConfig import MetricsApiConfig
+from metrics.ResponseInfoWrapper import ResponseInfoWrapper
+from werkzeug import Request, Response
+import io
+import time
+import datetime
+
+class MetricsMiddleware:
+    """
+    Core middleware class for ReadMe Metrics
+
+    ...
+    Attributes
+    ----------
+    config : MetricsApiConfig
+        contains the configuration settings for the running middleware instance
+    """
+    def __init__(
+            self,
+            wsgi_app_reference,
+            config: MetricsApiConfig):
+        """
+        Constructs and initializes MetricsMiddleware WSGI middleware to be passed into the
+        currently running WSGI web server.
+
+        :param wsgi_app_reference: Reference to the current WSGI application, which will be wrapped
+        :param config: Instance of MetricsApiConfig object
+        """
+
+        self.config = config
+        self.app = wsgi_app_reference
+        self.metrics_core = Metrics(config)
+
+    def __call__(self, environ, start_response):
+        """
+        Method that is called by the running WSGI server.
+        You should NOT be calling this method yourself under normal circumstances.
+        """
+        response_headers = {}
+        response_status = 0
+        iterable = None
+        req = Request(environ)
+        
+        def _start_response(_status, _response_headers, *args):
+            write = start_response(_status, _response_headers, *args)
+
+            # Populate response info (headers & status)
+            nonlocal response_headers, response_status
+
+            response_headers = _response_headers
+            response_status = _status
+
+            return write
+
+        try:
+
+            req.rm_start_dt = str(datetime.datetime.now())
+            req.rm_start_ts = int(time.time() * 1000)
+
+            if req.method == 'POST':
+
+                # The next 4 lines are a workaround for a serious shortcoming in the WSGI spec.
+                # The data can only be read once, after which the socket is exhausted and cannot be read again.
+                # As such, we read the data and then repopulate the variable so that it can be used by other
+                # code down the pipeline.
+                # For more info: https://stackoverflow.com/a/13106009/643951
+
+                content_length = int(environ['CONTENT_LENGTH'])
+                content_body = environ['wsgi.input'].read(content_length)
+
+                environ['wsgi.input'].close()
+                environ['wsgi.input'] = io.BytesIO(content_body)
+
+                req.rm_content_length = content_length
+                req.rm_body = content_body
+
+
+            iterable = self.app(environ, _start_response)
+
+
+            for data in iterable:
+                res_ctype = ''
+                res_clength = 0
+
+                htype = next((h for h in response_headers if h[0] == 'Content-Type'), None)
+                hlength = next((h for h in response_headers if h[0] == 'Content-Length'), None)
+
+                if htype and hlength:
+                    res_ctype = htype[1]
+                    res_clength = int(hlength[1])
+
+                # Populate response body
+                res = ResponseInfoWrapper(response_headers, response_status, res_ctype, res_clength, data.decode('utf-8'))
+
+                # Send off data to be queued (and processed) by ReadMe
+                self.metrics_core.process(req, res)
+
+                yield data
+
+        finally:
+            # Undocumented in WSGI spec but the iterable has to be closed
+            if hasattr(iterable, 'close'):
+                iterable.close()