Athena API / Client Library - Basics (#1)

* Adds the GRPC codegen and co-routine wrappers
* CI pipeline for build and test 
* pre-commit-config.yaml

Author: snus-kin

.gitattributes

@@ -0,0 +1 @@
+src/athena_client/generated/* linguist-generated=true

.github/workflows/build_and_test.yml

@@ -16,6 +16,14 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
+      - name: Initialize submodules
+        env:
+          GIT_ASKPASS: /bin/echo
+          GH_PAT: ${{ secrets.GH_PAT }}
+        run: |
+          git config --global url."https://${GH_PAT}@github.com/".insteadOf "https://github.com/"
+          git submodule update --init --recursive
+
       - name: Install uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -29,18 +37,43 @@ jobs:
 
       - name: Ensure no differences in generated code
         run: |
-          cp -r src/athena_client/generated src/athena_client/generated_backup
-          ./scripts/compile_proto.sh
-          diff -r src/athena_client/generated src/athena_client/generated_backup || (echo "Generated code differs. Please commit the changes after running compile_proto.sh." && exit 1)
+          source .venv/bin/activate
+          GENERATED_DIR="src/athena_client/generated"
+          BACKUP_DIR="src/athena_client/generated_backup"
+
+          cp -r $GENERATED_DIR $BACKUP_DIR
+
+          ./scripts/compile_proto.sh || (echo "Protobuf compilation failed. Ensure submodules are initialized and the proto file exists." && exit 1)
+
+          # Fix imports in generated files
+          if [[ -f "$GENERATED_DIR/athena/athena_pb2_grpc.py" && -f "$GENERATED_DIR/athena/athena_pb2.py" ]]; then
+            sed -i "$GENERATED_DIR/athena/athena_pb2_grpc.py" -e 's/^from athena /from athena_client.generated.athena /'
+            sed -i "$GENERATED_DIR/athena/athena_pb2.py" -e 's/^from athena /from athena_client.generated.athena /'
+          else
+            echo "Error: Expected files not found in $GENERATED_DIR/athena"
+            exit 1
+          fi
+
+          diff -r $GENERATED_DIR $BACKUP_DIR || (echo "Generated code differs. Please commit the changes after running compile_proto.sh." && exit 1)
+
+          rm -rf $BACKUP_DIR
 
       - name: Run linter
         run: |
           uv run ruff check
 
+      - name: Run code formatting check
+        run: |
+          uv run ruff format --check
+
       - name: Run type checking
         run: |
           uv run pyright
 
       - name: Run tests
         run: |
           uv run pytest
+
+      - name: Build package
+        run: |
+          uv build

.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "athena-protobufs"]
+	path = athena-protobufs
+	url = https://github.com/crispthinking/athena-protobufs.git

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.7
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.7.15
+    hooks:
+      - id: uv-lock
+  - repo: https://github.com/fsouza/mirrors-pyright
+    rev: v1.1.403
+    hooks:
+      - id: pyright
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: mixed-line-ending
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -0,0 +1,46 @@
+# Athena Client Library
+
+This is a Python library for interacting with the Athena API (Resolver Unknown
+CSAM Detection).
+
+
+## Development
+This package uses [uv](https://docs.astral.sh/uv/) to manage its packages.
+
+To install dependencies, run:
+
+```bash
+uv sync --dev
+```
+
+To build the package, run:
+
+```bash
+uv build
+```
+
+To run the tests, run:
+
+```bash
+pytest
+```
+
+To lint and format the code, run:
+
+```bash
+ruff check
+ruff format
+```
+
+There are pre-commit hooks that will lint, format, and type check the code.
+Install them with:
+
+```bash
+pre-commit install
+```
+
+To re-compile the protobuf files, run from the repository's root directory:
+
+```bash
+bash scripts/compile_proto.sh
+```

athena-protobufs

@@ -0,0 +1,38 @@
+[project]
+name = "athena_client"
+version = "0.1.0"
+description = "Athena Client Library"
+readme = "README.md"
+authors = [{ name = "Resolver Global", email = "opensource@kroll.com" }]
+requires-python = ">=3.10"
+dependencies = ["grpcio-tools>=1.74.0"]
+
+[dependency-groups]
+dev = [
+    "mypy-protobuf>=3.6.0",
+    "pre-commit>=4.2.0",
+    "pyright>=1.1.403",
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.1.0",
+    "ruff>=0.12.7",
+    "types-protobuf>=6.30.2.20250703",
+]
+
+[build-system]
+requires = ["uv_build>=0.7.19,<0.8.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 80
+exclude = ["src/athena_client/generated/*"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812", "D213", "D211", "D203", "S101"]
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore doc lint rules in tests.
+"tests/**" = ["D"]
+
+[tool.pyright]
+exclude = ["src/athena_client/generated/*", ".venv"]

pyproject.toml

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# Define paths
+PROTO_DIR="athena-protobufs"
+OUT_DIR="src/athena_client/generated"
+
+# Ensure output directory exists
+mkdir -p "$OUT_DIR"
+
+# Compile .proto files
+if [ ! -f "$PROTO_DIR/athena/athena.proto" ]; then
+  echo "Error: Protobuf file not found at $PROTO_DIR/athena/athena.proto. Ensure the submodule is initialized and updated."
+  exit 1
+fi
+
+python -m grpc_tools.protoc \
+  --proto_path="$PROTO_DIR" \
+  --python_out="$OUT_DIR" \
+  --grpc_python_out="$OUT_DIR" \
+  --mypy_out="$OUT_DIR" \
+  "$PROTO_DIR/athena/athena.proto"
+
+# Fix imports in generated files
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  sed -i '' -e 's/^from athena /from athena_client.generated.athena /' "$OUT_DIR/athena/athena_pb2_grpc.py"
+  sed -i '' -e 's/^from athena /from athena_client.generated.athena /' "$OUT_DIR/athena/athena_pb2.py"
+else
+  sed -i -e 's/^from athena /from athena_client.generated.athena /' "$OUT_DIR/athena/athena_pb2_grpc.py"
+  sed -i -e 's/^from athena /from athena_client.generated.athena /' "$OUT_DIR/athena/athena_pb2.py"
+fi
+
+if [ ! -f "$OUT_DIR/athena/athena_pb2.py" ] || [ ! -f "$OUT_DIR/athena/athena_pb2_grpc.py" ]; then
+  echo "Error: Protobuf files were not generated successfully in $OUT_DIR."
+  exit 1
+fi
+
+echo "Compilation complete. Files generated in $OUT_DIR"