Merge pull request #2 from lampajr/python_lib

Setup Python client 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,54 @@
+# 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
+      - run: git --no-pager diff
+      - name: Create Pull Request
+        uses: gr2m/create-or-update-pull-request-action@v1
+        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

.github/workflows/publish.yaml

@@ -0,0 +1,41 @@
+# This workflow will build the python distribution and it will publish to Pypi
+# This is going to be triggered on on every tag `v*`, e.g., `v0.13`.
+# TODO: trigger tests once implemented, to ensure everything is working before publishing
+name: Publish Horreum library
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  test:
+    name: ${{ matrix.session }} ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    env:
+      FORCE_COLOR: "1"
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install development dependencies
+        run: pip install -r dev-requirements.txt
+      - name: Check version coherence
+        run: |
+          PROJECT_VERSION=$(poetry version | cut -d' ' -f2)
+          GIT_TAG=$(git describe --tags --match="v*")
+          if [[ "${GIT_TAG:1}" =~ $PROJECT_VERSION ]]; then
+            echo "::error title='$GIT_TAG tag does not match project version'::"
+            exit 1
+          fi
+      - name: Build python library
+        run: make generate && poetry build --ansi
+      - name: Publish package on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+          print-hash: true
+          packages-dir: ./dist/

.gitignore

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

GET_STARTED.md

@@ -0,0 +1,52 @@
+<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.
+
+Right now the library is not published anywhere, therefore the only way to install it is from source.
+
+---
+## Prerequisites
+
+* 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
+
+```bash
+>>> import asyncio
+
+# Import the constructor function
+>>> from horreum.horreum_client import new_horreum_client
+
+# Initialize the client
+>>> client = await new_horreum_client(base_url="http://localhost:8080", username="..", password="..")
+
+# Call the api using the underlying raw client, in this case retrieve the Horreum server version
+>>> await client.raw_client.api.config.version.get()
+VersionInfo(additional_data={}, privacy_statement=None, start_timestamp=1710864862253, version='0.13.0')
+```
+
+The previous api call is equivalent to the following `cURL`:
+```bash
+curl --silent -X 'GET' 'http://localhost:8080/api/config/version' -H 'accept: application/json' | jq '.'
+```

Makefile

@@ -0,0 +1,67 @@
+# useful paths
+MKFILE_PATH := $(abspath $(lastword $(MAKEFILE_LIST)))
+PROJECT_PATH := $(patsubst %/,%,$(dir $(MKFILE_PATH)))
+PROJECT_BIN := $(PROJECT_PATH)/bin
+PROJECT_DIST := $(PROJECT_PATH)/dist
+
+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"
+GENERATED_CLIENT_PATH = "${PROJECT_PATH}/src/horreum/raw_client"
+
+.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} ${GENERATED_CLIENT_PATH}/api ${GENERATED_CLIENT_PATH}/models ${GENERATED_CLIENT_PATH}/horreum_raw_client.py ${GENERATED_CLIENT_PATH}/kiota-lock.json
+
+.PHONY: kiota
+kiota: ${PROJECT_BIN}/kiota ## Install kiota tool under ${PROJECT_PATH}/bin
+
+${PROJECT_BIN}/kiota:
+	@{\
+		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 ${OS_NAME}-${OS_ARCH}.zip ;\
+		mv kiota ${PROJECT_BIN}/ ;\
+		rm -rf ${PROJECT_BIN}/kiota-installation ;\
+	}
+
+.PHONY: tools
+tools: kiota ## Install external tools.
+
+.PHONY: generate
+generate: tools ## 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 ${GENERATED_CLIENT_PATH} ;\
+	}