feat: Rework the Python SDK

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+
+[*.{json,yaml,yml,tmpl}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -0,0 +1 @@
+**/*_gen.py linguist-generated=true

.github/workflows/actionlint.yaml

@@ -11,6 +11,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request_target' && github.head_ref || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   actionlint:
     runs-on: ubuntu-latest

.github/workflows/check-pr.yaml

@@ -2,8 +2,8 @@ name: check/pr
 
 on:
   pull_request:
-    types: [ opened, synchronize, reopened ]
-    branches: [ prod-staging ]
+    types: [opened, synchronize, reopened]
+    branches: [prod-staging]
 
 permissions:
   contents: read
@@ -12,70 +12,70 @@ jobs:
   commits:
     runs-on: ubuntu-latest
     steps:
-    - name: format
-      if: always()
-      uses: taskmedia/action-conventional-commits@v1.1.20
-      with:
-        types: "build|ci|docs|feat|fix|perf|refactor|style|test|revert|chore|sync"
-        token: ${{ secrets.GH_PAT }}
+      - name: format
+        if: always()
+        uses: taskmedia/action-conventional-commits@v1.1.20
+        with:
+          types: "build|ci|docs|feat|fix|perf|refactor|style|test|revert|gomod|chore|sync"
+          token: ${{ secrets.GH_PAT }}
 
-    - name: length
-      if: ${{ github.actor != 'dependabot' && github.actor != 'dependabot[bot]' }}
-      uses: gsactions/commit-message-checker@v2
-      with:
-        pattern: '((^(?=(?:.|\n)*(?:^|\n)\[\d\]: .{69,}(?:$|\n)(?:.|\n)*)(?:.|\n)*$)|(^(?!(?:.|\n)*(?:^|\n).{74,}(?:$|\n)(?:.|\n)*)(?:.|\n)*$))'
-        flags: ''
-        error: 'The maximum line length of 74 characters is exceeded.'
-        excludeDescription: 'true'
-        excludeTitle: 'true'
-        checkAllCommitMessages: 'true'
-        accessToken: ${{ secrets.GH_PAT }}
+      - name: length
+        if: ${{ github.actor != 'dependabot' && github.actor != 'dependabot[bot]' }}
+        uses: gsactions/commit-message-checker@v2
+        with:
+          pattern: '((^(?=(?:.|\n)*(?:^|\n)\[\d\]: .{69,}(?:$|\n)(?:.|\n)*)(?:.|\n)*$)|(^(?!(?:.|\n)*(?:^|\n).{74,}(?:$|\n)(?:.|\n)*)(?:.|\n)*$))'
+          flags: ''
+          error: 'The maximum line length of 74 characters is exceeded.'
+          excludeDescription: 'true'
+          excludeTitle: 'true'
+          checkAllCommitMessages: 'true'
+          accessToken: ${{ secrets.GH_PAT }}
 
-    - name: signed-off-by
-      if: always()
-      uses: gsactions/commit-message-checker@v2
-      with:
-        pattern: '^Signed-off-by: .+ \<.+\@.+\..+\>$'
-        error: 'Signed-off-by line is missing.'
-        excludeDescription: 'true'
-        excludeTitle: 'true'
-        checkAllCommitMessages: 'true'
-        accessToken: ${{ secrets.GH_PAT }}
+      - name: signed-off-by
+        if: always()
+        uses: gsactions/commit-message-checker@v2
+        with:
+          pattern: '^Signed-off-by: .+ \<.+\@.+\..+\>$'
+          error: 'Signed-off-by line is missing.'
+          excludeDescription: 'true'
+          excludeTitle: 'true'
+          checkAllCommitMessages: 'true'
+          accessToken: ${{ secrets.GH_PAT }}
 
   pr:
     runs-on: ubuntu-latest
     steps:
-    - name: title-format
-      if: always()
-      uses: gsactions/commit-message-checker@v2
-      with:
-        pattern: '^(build|ci|docs|feat|fix|perf|refactor|style|test|revert|chore|sync)(\([\w\-\_\d]+\))?!?: '
-        error: 'The PR title must follow the conventional commits format.'
-        excludeDescription: 'true'
-        excludeTitle: 'false'
-        checkAllCommitMessages: 'false'
-        accessToken: ${{ secrets.GH_PAT }}
+      - name: title-format
+        if: always()
+        uses: gsactions/commit-message-checker@v2
+        with:
+          pattern: '^(build|ci|docs|feat|fix|perf|refactor|style|test|revert|gomod|chore|sync)(\([\w\-\_\d]+\))?!?: '
+          error: 'The PR title must follow the conventional commits format.'
+          excludeDescription: 'true'
+          excludeTitle: 'false'
+          checkAllCommitMessages: 'false'
+          accessToken: ${{ secrets.GH_PAT }}
 
-    - name: title-length
-      if: ${{ github.actor != 'dependabot' && github.actor != 'dependabot[bot]' }}
-      uses: gsactions/commit-message-checker@v2
-      with:
-        pattern: '^(?!.{75,}).*'
-        flags: ''
-        error: 'The maximum line length of 75 characters is exceeded.'
-        excludeDescription: 'true'
-        excludeTitle: 'false'
-        checkAllCommitMessages: 'false'
-        accessToken: ${{ secrets.GH_PAT }}
+      - name: title-length
+        if: ${{ github.actor != 'dependabot' && github.actor != 'dependabot[bot]' }}
+        uses: gsactions/commit-message-checker@v2
+        with:
+          pattern: '^(?!.{75,}).*'
+          flags: ''
+          error: 'The maximum line length of 75 characters is exceeded.'
+          excludeDescription: 'true'
+          excludeTitle: 'false'
+          checkAllCommitMessages: 'false'
+          accessToken: ${{ secrets.GH_PAT }}
 
-    - name: description
-      if: ${{ github.actor != 'dependabot' && github.actor != 'dependabot[bot]' }}
-      uses: gsactions/commit-message-checker@v2
-      with:
-        pattern: '^\S+( \S+)*$'
-        error: 'The PR description must not be empty.'
-        flags: 'gm'
-        excludeDescription: 'false'
-        excludeTitle: 'true'
-        checkAllCommitMessages: 'false'
-        accessToken: ${{ secrets.GH_PAT }}
+      - name: description
+        if: ${{ github.actor != 'dependabot' && github.actor != 'dependabot[bot]' }}
+        uses: gsactions/commit-message-checker@v2
+        with:
+          pattern: '^\S+( \S+)*$'
+          error: 'The PR description must not be empty.'
+          flags: 'gm'
+          excludeDescription: 'false'
+          excludeTitle: 'true'
+          checkAllCommitMessages: 'false'
+          accessToken: ${{ secrets.GH_PAT }}

.github/workflows/ci.yaml

@@ -0,0 +1,54 @@
+name: ci
+
+on:
+  pull_request:
+    branches: [prod-staging, prod-stable]
+  push:
+    branches: [prod-staging]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --locked
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Type-check
+        run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Run the test suite
+        run: uv run --python ${{ matrix.python-version }} pytest

.github/workflows/publish-pypi.yaml

@@ -0,0 +1,73 @@
+name: publish-pypi
+
+# Publish to PyPI via Trusted Publishing (OIDC) when a version tag is pushed,
+# e.g. `git tag v0.1.0 && git push origin v0.1.0`. No API token is stored; the
+# `pypi` GitHub Environment must be configured as a trusted publisher for the
+# `unikraft-cloud` project on PyPI.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Check the tag and the package agree on the version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          # The version is static in `pyproject.toml`, so a tag pushed without
+          # bumping it would build, and try to publish, the previous release.
+          version="$(uv version --short)"
+          if [ "${TAG#v}" != "${version}" ]; then
+            echo "::error::Tag ${TAG} does not match the packaged version ${version}." \
+              "Bump the version and retag."
+            exit 1
+          fi
+          exported="$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/unikraft_cloud/__init__.py)"
+          if [ "${exported}" != "${version}" ]; then
+            echo "::error::The package reports __version__ ${exported}, but it is built as ${version}."
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/unikraft-cloud
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/release-stable.yaml

@@ -2,7 +2,8 @@ name: release-stable
 
 on:
   push:
-    branches: [prod-staging]
+    branches:
+    - prod-staging
 
 permissions:
   deployments: write

.github/workflows/sync.yaml

@@ -25,8 +25,15 @@ jobs:
       with:
         ref: ${{ inputs.channel }}
 
+    - name: Install Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: stable
+
     - name: Install uv
-      uses: astral-sh/setup-uv@v7
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
 
     - name: Generate
       shell: bash
@@ -56,5 +63,7 @@ jobs:
         branch: ${{ steps.id.outputs.name }}
         committer: Unikraft Bot <monkey@unikraft.io>
         author: Unikraft Bot <monkey@unikraft.io>
-        add-paths: controlplane,platform
+        # The whole generated package, so a module the spec drops is removed and
+        # a tag it adds is not left out of the pull request.
+        add-paths: src/unikraft_cloud/api
         signoff: true