Development Setup¶
Guide for setting up grai.build for local development.
Prerequisites¶
- Python 3.11+
- Git
- Neo4j (for testing, optional)
Initial Setup¶
1. Clone the Repository¶
2. Create Virtual Environment¶
# Create venv
python -m venv venv
# Activate (macOS/Linux)
source venv/bin/activate
# Activate (Windows)
venv\Scripts\activate
3. Install Dependencies¶
# Install with development dependencies
pip install -e ".[dev]"
# Or manually install dev tools
pip install pytest pytest-cov black ruff mypy pre-commit
4. Install Pre-commit Hooks¶
Running Tests¶
# Run all tests
pytest
# With coverage
pytest --cov=grai --cov-report=html
# Specific test file
pytest tests/test_validator.py
# Verbose output
pytest -v
# Stop on first failure
pytest -x
Code Quality¶
Formatting¶
Linting¶
Type Checking¶
Documentation¶
Build Docs Locally¶
# Install docs dependencies
pip install -r requirements-docs.txt
# Serve locally
mkdocs serve
# Open http://localhost:8000
Build Static Site¶
Testing with Neo4j¶
Using Docker¶
# Start Neo4j
docker run -d \
--name neo4j-dev \
-p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=neo4j/devpassword \
neo4j:latest
# Stop Neo4j
docker stop neo4j-dev
# Remove container
docker rm neo4j-dev
Connection Details¶
- URI:
bolt://localhost:7687
- User:
neo4j
- Password:
devpassword
- Browser:
http://localhost:7474
Project Structure¶
grai.build/
├── grai/ # Main package
│ ├── __init__.py
│ ├── cli/ # CLI commands
│ ├── core/ # Core functionality
│ │ ├── models.py # Pydantic models
│ │ ├── parser/ # YAML parsing
│ │ ├── validator/ # Schema validation
│ │ ├── compiler/ # Cypher generation
│ │ ├── loader/ # Neo4j & data loading
│ │ ├── lineage/ # Lineage tracking
│ │ └── visualizer/ # Visualizations
│ └── templates/ # Project templates
├── tests/ # Test suite
├── docs/ # MkDocs documentation
├── pyproject.toml # Project config
└── README.md
Common Tasks¶
Create a New Feature¶
# Create branch
git checkout -b feat/my-feature
# Make changes
# ...
# Run tests
pytest
# Format and lint
black grai/ tests/
ruff check --fix grai/ tests/
# Commit
git add .
git commit -m "feat: Add my feature"
# Push
git push origin feat/my-feature
Add a New Test¶
# tests/test_myfeature.py
import pytest
from grai.core.mymodule import my_function
def test_my_function():
"""Test that my_function works correctly."""
result = my_function("input")
assert result == "expected output"
Update Documentation¶
# Edit docs
vim docs/my-page.md
# Preview locally
mkdocs serve
# Commit changes
git add docs/
git commit -m "docs: Update my-page documentation"
Troubleshooting¶
Import Errors¶
Pre-commit Hook Failures¶
# Run hooks manually to see errors
pre-commit run --all-files
# Fix issues and try again
black grai/ tests/
ruff check --fix grai/ tests/
Test Failures¶
# Run with verbose output
pytest -v
# Run specific failing test
pytest tests/test_file.py::test_name -v
IDE Setup¶
VS Code¶
Recommended extensions:
- Python
- Pylance
- Black Formatter
- Ruff
Settings (.vscode/settings.json
):
{
"python.formatting.provider": "black",
"python.linting.enabled": true,
"python.linting.ruffEnabled": true,
"[python]": {
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": true
}
}
}
PyCharm¶
- Set Python interpreter to venv
- Enable Black as formatter
- Configure Ruff for linting
Getting Help¶
- Read the Contributing Guide
- Ask on GitHub Discussions
- Check Troubleshooting
Code of Conduct¶
This project follows the Contributor Covenant Code of Conduct. Please be respectful and inclusive.