Python library poc

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+
+A clear and concise description of what the bug is.
+
+Feel free to attach screenshots as well.
+
+**To Reproduce**
+
+Steps to reproduce the behavior.
+
+Any sample data would help greatly.
+
+**Version**
+
+What is the version of Horreum python client ?
+
+If you are using a development branch; what is the commit id ?
+
+```
+git rev-parse HEAD
+```
+
+What is the version of Horreum ?
+
+If you are using a development branch; what is the commit id ?
+
+```
+git rev-parse HEAD
+```
+
+**Java**
+
+What is the version of Python ?
+
+```
+python --version
+```
+
+**Tip**
+
+Use \`\`\` before and after the text to keep the output as is.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: feature
+assignees: ''
+
+---
+
+**Feature idea.**
+
+A clear and concise description of what the feature is.
+
+**Describe the solution you'd like**
+
+A clear and concise description of what you want to happen.
+
+**Additional information**
+
+Any additional information you can provide, like an overall design description

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+<!-- If your PR fixes an open issue, use `Closes #435` to link your PR with the issue. #435 stands for the issue number you are fixing -->
+
+## Fixes Issue
+
+<!-- Remove this section if not applicable -->
+
+<!-- Example: Closes #31 -->
+
+## Changes proposed
+
+<!-- List all the proposed changes in your PR -->
+
+<!-- Mark all the applicable boxes. To mark the box as done follow the following conventions -->
+<!--
+[x] - Correct; marked as done
+[X] - Correct; marked as done
+
+[ ] - Not correct; marked as **not** done-->
+
+## Check List (Check all the applicable boxes) <!-- Follow the above conventions to check the box -->
+
+- [ ] My code follows the code style of this project.
+- [ ] My change requires changes to the documentation.
+- [ ] I have updated the documentation accordingly.
+- [ ] All new and existing tests passed.

.github/workflows/ci.yaml

@@ -0,0 +1,33 @@
+# This workflow will run the full CI for the Horreum python library including the build and the tests execution
+# This is going to be triggered on every pull request as well as on main branch.
+# TODO: trigger tests once implemented
+name: Python client ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.session }} ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [ "3.9", "3.10", "3.11" ]
+    env:
+      FORCE_COLOR: "1"
+      PRE_COMMIT_COLOR: "always"
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install development dependencies
+        run: pip install -r dev-requirements.txt
+      - name: Build python library
+        run: poetry build

.github/workflows/generate-client.yaml

@@ -0,0 +1,56 @@
+# This workflow will fetch the new openapi from the provided branch of https://github.com/Hyperfoil/Horreum and based on
+# that it will re-generate the Horreum raw client and creates a new pull request against the corresponding branch here.
+# It could be tested running `gh act workflow_dispatch -e ./test/workflow_dispatch_event_example.json`. Remember to
+# comment out the pull request creation :)
+name: Autogenerate Horreum client
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: Branch or tag of https://github.com/Hyperfoil/Horreum
+        required: true
+  repository_dispatch:
+    types: [ generate-horreum-client ]
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch branch
+        id: fetch-branch
+        run: |
+          if [ "${{ github.event_name }}" = "repository_dispatch" ]; then
+            # Generated by peter-evans/repository-dispatch@v3
+            echo "HORREUM_BRANCH=${{ github.event.client_payload.branch }}" >> $GITHUB_OUTPUT
+          elif [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "HORREUM_BRANCH=${{ github.event.inputs.branch }}" >> $GITHUB_OUTPUT
+          else
+            echo "Unknown event: ${{ github.event_name }}"
+            exit 1
+          fi
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Install development dependencies
+        run: pip install -r dev-requirements.txt
+      - name: Generate horreum client
+        run: make HORREUM_BRANCH=${{ steps.fetch-branch.outputs.HORREUM_BRANCH }} generate
+      - name: Run poetry build
+        run: poetry build
+      - run: git --no-pager diff
+      - name: Create Pull Request
+        uses: gr2m/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          title: Generate Horreum client from github.com/Hyperfoil/Horreum:${{ steps.fetch-branch.outputs.HORREUM_BRANCH }}
+          body: |
+            There is a new change in the openapi spec of Horreum in branch ${{ steps.fetch-branch.outputs.HORREUM_BRANCH }}.
+            Verify that there are no breaking changes.
+          branch: horreum-openapi-${{ steps.fetch-branch.outputs.HORREUM_BRANCH }}
+          commit-message: Horreum openapi client updated

.gitignore

@@ -0,0 +1,12 @@
+# IDE configs
+.idea
+
+# Dist
+dist/
+bin/
+
+# Py cache
+**/__pycache__
+
+# Kiota
+**/.kiota.log

GET_STARTED.md

@@ -0,0 +1,60 @@
+<div align="center">
+
+# Get Started Guide
+
+</div>
+
+In this document you can find all information to get started using the Horreum python library from scratch.
+
+---
+## Prerequisites
+
+TODO: Start Horreum
+
+* Python environment, e.g., `pyenv` or `miniconda` with all development dependencies installed:
+```bash
+pip install -r dev-requirements.txt
+```
+
+## Installation
+
+Once all dependencies are installed simply build the `whl` by running:
+
+```bash
+poetry build
+```
+
+Now you can install the local build of `horreum` python client:
+
+```bash
+pip install dist/horreum-*.dev0-py3-none-any.whl --force-reinstall
+```
+
+## Usage
+
+TODO: simple usage examples
+
+## Development
+
+TODO: how to build the project, run test etc.
+TODO: Do we want to put this dev section into main README.md?
+
+### Tests
+
+Run:
+```bash
+pytest test/
+```
+
+> **_NOTE_**: Horreum backend must be running in the background
+
+### TODOs
+
+Here the list of TODOs
+
+- [X] Automate pull request creation with autogenerated code whenever openapi changes on horreum
+- [ ] Implement high level api (right now we can use the raw api)
+- [X] Setup simple integration tests
+- [ ] Automate Horreum startup for ITs
+- [X] PR checks (build)
+- [ ] PR checks (test)

Makefile

@@ -0,0 +1,70 @@
+# useful paths
+MKFILE_PATH := $(abspath $(lastword $(MAKEFILE_LIST)))
+PROJECT_PATH := $(patsubst %/,%,$(dir $(MKFILE_PATH)))
+PROJECT_BIN := $(PROJECT_PATH)/bin
+PROJECT_DIST := $(PROJECT_PATH)/dist
+
+# add tools bin directory
+PATH := $(PROJECT_BIN):$(PATH)
+
+OS_NAME := $(shell uname -s | tr A-Z a-z)
+OS_ARCH := $(shell uname -m | tr A-Z a-z)
+
+ifeq ($(OS_NAME),linux)
+	OS_NAME = "linux"
+endif
+ifeq ($(OS_NAME),darwin)
+	OS_NAME = "osx"
+endif
+
+ifeq ($(OS_ARCH),x86_64)
+	OS_ARCH = x64
+endif
+ifneq ($(filter %86,$(OS_ARCH)),)
+	OS_ARCH = x86
+endif
+ifneq ($(filter arm%,$(OS_ARCH)),)
+	OS_ARCH = arm64
+endif
+
+# env variables
+KIOTA_VERSION ?= "v1.12.0"
+HORREUM_BRANCH ?= "master"
+HORREUM_OPENAPI_PATH ?= "https://raw.githubusercontent.com/Hyperfoil/Horreum/${HORREUM_BRANCH}/docs/site/content/en/openapi/openapi.yaml"
+
+.PHONY: help
+help: ## Display this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+##@ Development
+
+.PHONY: clean
+clean: ## Clean external tools and output dirs
+	rm -rf ${PROJECT_BIN} ${PROJECT_DIST}
+
+bin-folder:
+	mkdir -p ${PROJECT_BIN}
+
+.PHONY: kiota
+kiota: bin-folder ## Install kiota tool under ${PROJECT_PATH}/bin
+	@{\
+		set -e ;\
+		echo "installing kiota version ${KIOTA_VERSION}" ;\
+		mkdir -p ${PROJECT_BIN}/kiota-installation ;\
+		cd ${PROJECT_BIN}/kiota-installation ;\
+		curl -sLO https://github.com/microsoft/kiota/releases/download/${KIOTA_VERSION}/${OS_NAME}-${OS_ARCH}.zip ;\
+		unzip -o linux-x64.zip ;\
+		mv kiota ${PROJECT_BIN}/ ;\
+		rm -rf ${PROJECT_BIN}/kiota-installation ;\
+	}
+
+.PHONY: tools
+tools: kiota ## Install external tools.
+
+.PHONY: generate
+generate: kiota ## Generate the Horreum client
+	@{\
+		set -e ;\
+		curl -sSfL -o ${PROJECT_PATH}/openapi/openapi.yaml ${HORREUM_OPENAPI_PATH} ;\
+		${PROJECT_BIN}/kiota generate -l python -c HorreumRawClient -n raw_client -d ${PROJECT_PATH}/openapi/openapi.yaml -o ./src/horreum/raw_client ;\
+	}

README.md

@@ -11,6 +11,13 @@
 </div>
 
 ---
+## What is Horreum Python Client?
+
+Horreum python client is a high-level python library to interact with [Horreum](#what-is-horreum-) web server.
+
+The raw client is generated using [kiota](https://github.com/microsoft/kiota) openapi generator tool starting from 
+the [Horreum OpenAPI spec](https://github.com/Hyperfoil/Horreum/blob/master/docs/site/content/en/openapi/openapi.yaml).
+
 ## What is Horreum ?
 
 [Horreum](https://github.com/Hyperfoil/Horreum) is a service for storing performance data and regression analysis.

dev-requirements.txt

@@ -0,0 +1,3 @@
+poetry==1.8.2
+pytest==8.1.1
+pytest-asyncio==0.23.6