Adapter (#3)

* Added adapter for handling of search results * Adapter comes from an interface * Extracted processing into separate functions * Fixed branching * check for missing installations * added comment to the adapter usage * Tools are dependencies * Testing with https * Fixed toml * Updated documentation * remove unused file; check if Adapter class exists * fixed pylint error --------- Co-authored-by: jkerpe <[email protected]>
NewTec-GmbH · Jun 28, 2024 · 6ea6924 · 6ea6924
1 parent 6ec8d44
commit 6ea6924
Show file tree

Hide file tree

Showing 11 changed files with 932 additions and 21 deletions.
diff --git a/.gitignore b/.gitignore
@@ -167,4 +167,6 @@ cython_debug/
 #.idea/
 
 # Development Scripts
-dev/
+dev/
+
+temp/
diff --git a/README.md b/README.md
@@ -7,7 +7,6 @@ pyMetricCli is a collection of scripts and API implementations for generating an
 - [Installation](#installation)
 - [Overview](#overview)
 - [Usage](#usage)
-- [Commands](#commands)
 - [Examples](#examples)
 - [Used Libraries](#used-libraries)
 - [Issues, Ideas And Bugs](#issues-ideas-and-bugs)
@@ -16,29 +15,69 @@ pyMetricCli is a collection of scripts and API implementations for generating an
 
 ## Installation
 
-WIP
+```cmd
+git clone https://github.com/NewTec-GmbH/pyMetricCli.git
+cd pyMetricCli
+pip install .
+```
+
+This will also install the latest version of [pyJiraCli](https://github.com/NewTec-GmbH/pyJiraCli), [pyPolarionCli](https://github.com/NewTec-GmbH/pyPolarionCli), and [pySupersetCli](https://github.com/NewTec-GmbH/pySupersetCli) in your Python environment.
 
 ## Overview
 
-WIP
+pyMetricCli requires an adapter file to be supplied by the user. This shall contain the credentials and result-handling logic for the seach results. Please **DO NOT** commit this file into any public repository as your credentials might be exposed.
+
+An example adapter can be found [here](examples/adapter/adapter.py).
 
 ## Usage
 
-WIP
+Show help information:
+
+```cmd
+pyJiraCli --help
+```
+
+Usage:
+
+```cmd
+usage: pyMetricCli [-h] -a <adapter_file> [--version] [-v]
+
+Collection of scripts and API implementations for generating and playing with metrics.
+
+options:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  -v, --verbose         Print full command details before executing the command. Enables logs of type INFO and WARNING.
+
+required arguments:
+  -a <adapter_file>, --adapter_file <adapter_file>
+                        Adapter file to be used.
+```
+
+Example:
+
+```cmd
+pyJiraCli --verbose --adapter_file "examples\adapter\adapter.py"
+```
+
+### Adapter
 
-## Commands
+The adapter file must contain the `Adapter` Class derived from the `AdapterInterface`, including all the methods and members defined in the interface.
 
-WIP
+The `***_config` dictionaries must be filled with the user credentials for each service. The `output` dictionary defines the columns of the table that will be sent to Superset, and this cannot be changed after the first time the script is ran. If you are receiving an Error 422 from Superset, a change in this dictionary may be the reason and you should contact your administrator so resolve the issue.
 
 ## Examples
 
-Check out the all the [Examples](./examples).
+Check out the [Examples](./examples) in the corresponding folder.
 
 ## Used Libraries
 
 Used 3rd party libraries which are not part of the standard Python package:
 
 - [toml](https://github.com/uiri/toml) - Parsing [TOML](https://en.wikipedia.org/wiki/TOML) - MIT License
+- [pyJiraCli](https://github.com/NewTec-GmbH/pyJiraCli) - Interfacing with Jira - BSD-3 License
+- [pyPolarionCli](https://github.com/NewTec-GmbH/pyPolarionCli) - Interfacing with Polarion - BSD-3 License
+- [pySupersetCli](https://github.com/NewTec-GmbH/pySupersetCli) - Interfacing with Superset - BSD-3 License
 
 ## Issues, Ideas And Bugs
 

diff --git a/examples/README.md b/examples/README.md
@@ -1 +1,7 @@
-# Examples
+# Examples
+
+## Adapter
+
+Each project must provide an `Adapter` class with the methods `handle_jira` and `handle_polarion` to pack the data from the search results into the output dictionary.
+Additionally, the dictionaries `output`, `jira_config`, `polarion_config` and `superset_config` must also be supplied.
+The declaration, arguments and name of the methods must remain the same as in `examples\adapter\adapter.py`, otherwise the program will not work correctly.
diff --git a/examples/adapter/adapter.py b/examples/adapter/adapter.py
@@ -0,0 +1,129 @@
+
+"""Project-Specific Adapter Module"""
+
+# BSD 3-Clause License
+#
+# Copyright (c) 2024, NewTec GmbH
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+#    list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICU5LAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+################################################################################
+# Imports
+################################################################################
+
+import logging
+from pyMetricCli.adapter_interface import AdapterInterface
+
+################################################################################
+# Variables
+################################################################################
+
+LOG = logging.getLogger(__name__)
+
+################################################################################
+# Classes
+################################################################################
+
+
+class Adapter(AdapterInterface):
+    """
+    Adapter class for handling different search results.
+    """
+
+    # Define the output dictionary
+    # Must include all possible values.
+    # Please make sure that the keys of the output dictionary are unique, regardless of their case.
+    # In this example, Polarion Status has 2 possible values: "open" and "closed".
+    output: dict = {
+        "status_open": 0,
+        "status_closed": 0
+    }
+
+    # Set "filter": "", if you don't want to search in Jira.
+    jira_config = {
+        "server": "https://jira.example.com",
+        "token": "",
+        "filter": "",
+        "max": "0",  # 0 gets all issues that match the filter.
+        "fields": [],
+        "full": False
+    }
+
+    # Set "query": "", if you don't want to search in Polarion.
+    polarion_config = {
+        "username": "",
+        "password": "",
+        "server": "http://polarion.example.com/polarion",
+        "project": "",
+        "query": "HAS_VALUE:status",  # Query to get all work items with a status
+        "fields": ["status"]  # Fields to include in the query
+    }
+
+    superset_config = {
+        "server": "http://superset.example.com",
+        "user": "",
+        "password": "",
+        "database": 0,  # Primary key of the database
+        "table": "",
+        "basic_auth": False,
+        "no_ssl": False
+    }
+
+    def handle_jira(self, search_results: dict) -> bool:
+        """
+        Handles the JIRA search results.
+
+        Args:
+            search_results: The search results from the JIRA API.
+
+        Returns:
+            bool: True if the search results were handled successfully, False otherwise.
+        """
+        LOG.info("Handling JIRA search results...")
+        LOG.info(search_results)
+        return True
+
+    def handle_polarion(self, search_results: dict) -> bool:
+        """
+        Handles the Polarion search results.
+
+        Args:
+            search_results: The search results from the Polarion API.
+
+        Returns:
+            bool: True if the search results were handled successfully, False otherwise.
+        """
+        LOG.info("Handling Polarion search results...")
+        LOG.info(search_results)
+        return True
+
+################################################################################
+# Functions
+################################################################################
+
+################################################################################
+# Main
+################################################################################
diff --git a/pyproject.toml b/pyproject.toml
@@ -22,7 +22,10 @@ classifiers = [
 ]
 
 dependencies = [
-    "toml>=0.10.2"
+    "toml>=0.10.2",
+    "pyJiraCli@git+https://github.com/NewTec-GmbH/pyJiraCli",
+    "pyPolarionCli@git+https://github.com/NewTec-GmbH/pyPolarionCli",
+    "pySupersetCli@git+https://github.com/NewTec-GmbH/pySupersetCli"
 ]
 
 [project.optional-dependencies]
-Original file line number
+Diff line change
@@ Expand Up / @@ -167,4 +167,6 @@ cython_debug/ @@
     #.idea/
     # Development Scripts
-    dev/
+    dev/
+    temp/