Installation Guide

This guide will walk you through installing and setting up the Athena Client library for both development and production use.

Prerequisites

Before installing Athena Client, ensure you have:

  • Python 3.10 or higher

  • uv package manager (recommended)

  • Git (for development installation)

Production Installation

Using pip

Alternatively, you can install using pip:

pip install athena-client

Development Installation

For development, you’ll need to clone the repository and install with development dependencies.

  1. Clone the repository:

    git clone <repository-url>
    cd athena-client
    
  2. Install dependencies with uv:

    uv sync --dev
    

    This installs all dependencies including development tools like pytest, ruff, pyright, and pre-commit.

  3. Install git hooks for code quality:

    pre-commit install
    
  4. Compile protocol buffers (required for development):

    bash scripts/compile_proto.sh
    

Development Commands

Once installed for development, you can use these commands:

Build and Test

# Build the package
uv build

# Run the full test suite
pytest

# Run specific tests
pytest path/to/test.py

# Run tests by pattern
pytest -k "test_name"

# Run tests with coverage
pytest --cov=src/athena_client

Code Quality

# Type check code
pyright

# Format code
ruff format

# Lint code
ruff check

# Fix auto-fixable lint issues
ruff check --fix

Documentation

# Build documentation
cd docs && make clean && make html

# View documentation locally
open docs/_build/html/index.html

Verification

To verify your installation works correctly:

  1. Check the installation:

    import resolver_athena_client
    print(resolver_athena_client.__version__)
    
  2. Run the test suite:

    pytest
    
  3. Verify type checking:

    pyright
    
  4. Check code formatting:

    ruff check
    

Environment Setup

For development and testing, you’ll typically need these environment variables:

# OAuth credentials
export OAUTH_CLIENT_ID="your-client-id"
export OAUTH_CLIENT_SECRET="your-client-secret"

# Athena service configuration
export ATHENA_HOST="your-athena-host"

# Optional OAuth configuration
export OAUTH_AUTH_URL="https://crispthinking.auth0.com/oauth/token"
export OAUTH_AUDIENCE="crisp-athena-live"

You can create a .env file in the project root with these variables, and the examples will automatically load them using python-dotenv.

Troubleshooting

Common Installation Issues

uv not found:

Install uv following the official installation guide.

Python version mismatch:

Ensure you have Python 3.10 or higher. Check with:

python --version
Protocol buffer compilation fails:

Ensure you have the required dependencies and run:

uv sync --dev
bash scripts/compile_proto.sh
Pre-commit hooks failing:

The hooks will automatically format and check your code. If they fail:

# Fix formatting issues
ruff format

# Fix lint issues
ruff check --fix

# Run type checking
pyright

Development Dependencies

The development installation includes these key tools:

  • pytest: Testing framework with async support and coverage

  • ruff: Fast linting and formatting

  • pyright: Type checking

  • pre-commit: Git hooks for code quality

  • sphinx: Documentation generation

  • mypy-protobuf: Type hints for protocol buffers

Next Steps

Once installed, you can:

For questions or issues: