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 uv (Recommended)¶
The recommended way to install Athena Client for production use:
uv add athena-client
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.
Clone the repository:
git clone <repository-url> cd athena-client
Install dependencies with uv:
uv sync --dev
This installs all dependencies including development tools like pytest, ruff, pyright, and pre-commit.
Install git hooks for code quality:
pre-commit install
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:
Check the installation:
import resolver_athena_client print(resolver_athena_client.__version__)
Run the test suite:
pytest
Verify type checking:
pyright
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:
Read the Examples guide to see usage patterns
Check the Authentication guide for setup instructions
Browse the API Reference documentation for detailed API reference
Review the Development Guide guide for contribution guidelines
For questions or issues:
Check the project’s GitHub Issues
Review the Contributing to Athena Client guide
See the examples in the
examples/
directory