A production-ready template for Python projects that use HashiCorp Vault for secrets management.

• Overview
• Features
• Quick Start
• Project Structure
• Technology Stack
• Development Workflow
• Configuration
• Testing
• Code Quality
• Troubleshooting
• Contributing

This template provides a complete, production-ready foundation for Python applications that require secure secrets management using HashiCorp Vault. It includes automated testing, code quality checks, and a streamlined development workflow with git hooks.

• 🔐 Secure: Vault integration for secrets management (no hardcoded credentials)
• 🚀 Production-Ready: Pinned dependencies, security scanning, automated quality checks
• ✅ Quality-First: Automated linting, type checking, formatting, and testing via pre-commit hooks
• 📦 Template-Based: Easy to customize and adapt for new projects
• 🛠️ Developer-Friendly: Interactive setup, comprehensive documentation, Makefile commands

• ✅ HashiCorp Vault integration for secure secrets storage
• ✅ Automatic secret fetching and environment variable injection
• ✅ Security vulnerability scanning with Bandit
• ✅ No hardcoded credentials in codebase

• ✅ Interactive setup script with guided configuration
• ✅ Git pre-commit hooks for automated quality checks
• ✅ Makefile for common development tasks
• ✅ Virtual environment management
• ✅ Hot-reload development workflow

• ✅ Ruff - Fast Python linter and formatter
• ✅ mypy - Static type checking
• ✅ pytest - Comprehensive testing framework
• ✅ Bandit - Security issue detection

• ✅ Automated secret injection via bin/run script
• ✅ Production-ready configuration
• ✅ Pinned dependencies for reproducible builds

• Python 3.13+ (Download)
• Vault CLI (Download)

1. Clone or copy this template to your project directory:

   git clone <repository-url> my-project
   cd my-project

2. Run the interactive setup script:

   chmod +x bin/setup
   ./bin/setup

   The installer will:

   • Initialize git repository (if needed)
   • Configure git user settings (interactive)
   • Create Python virtual environment
   • Install all dependencies
   • Set up pre-commit hooks
   • Configure Vault settings (interactive)

3. Run your application:

   ./bin/run python main.py

   Or use the Makefile:

   make run

python-vault/
├── .agent/                    # Antigravity AI assistant configuration
│   ├── prompts/              # Custom prompts for code generation
│   │   ├── README.md
│   │   ├── readme-blueprint-generator.prompt.md
│   │   └── vault-secret-documenter.prompt.md
│   └── workflows/            # Development workflows
├── bin/                       # Executable scripts
│   ├── setup                 # Interactive project setup
│   └── run                   # Vault-integrated command runner
├── config/                    # Configuration files
│   └── vault.conf            # Vault mount point and secret name
├── hooks/                     # Git hooks
│   └── pre-commit            # Automated quality checks
├── tests/                     # Test files (pytest)
│   ├── __init__.py
│   └── test_main.py
├── .bandit                   # Bandit security scanner config
├── .gitignore                # Git ignore patterns
├── main.py                   # Main application entry point
├── Makefile                  # Common development commands
├── requirements.txt          # Production dependencies (pinned)
├── requirements-dev.txt      # Development dependencies
├── LICENSE                   # MIT License
└── README.md                 # This file

• Python 3.13+ - Primary programming language
• HashiCorp Vault - Secrets management and secure storage
• Bash - Automation scripts and tooling

• requests (≥2.32.0, <3.0.0) - HTTP library for API calls

• ruff (≥0.14.0, <1.0.0) - Fast Python linter and formatter
• mypy (≥1.19.0, <2.0.0) - Static type checker
• pytest (≥9.0.0, <10.0.0) - Testing framework
• bandit (≥1.9.0, <2.0.0) - Security vulnerability scanner

• Git - Version control with automated hooks
• Make - Build automation and task runner

1. Write code in main.py (or create additional .py files as needed)
2. Write tests in tests/ following the test_*.py naming convention
3. Run your code with Vault integration:

   ./bin/run python main.py
   # or
   make run

4. Run tests:

   ./bin/run python -m pytest
   # or
   make test

5. Commit changes - pre-commit hook runs automatically:
   • Linting with auto-fix (ruff)
   • Code formatting (ruff)
   • Type checking (mypy)
   • Security scanning (bandit)
   • All tests (pytest)

make help         # Show all available commands
make setup        # Run initial project setup
make run          # Run the application (with Vault)
make test         # Run all tests
make lint         # Run linting checks
make format       # Format code
make clean        # Remove venv, caches, and temporary files

Production dependencies:

echo "package-name>=1.0.0,<2.0.0" >> requirements.txt
./bin/run pip install -r requirements.txt

Development dependencies:

echo "dev-package>=1.0.0,<2.0.0" >> requirements-dev.txt
./bin/run pip install -r requirements-dev.txt

The project uses config/vault.conf to specify Vault settings:

VAULT_MOUNT="python-vault"
VAULT_SECRET_NAME="demo"

Option 1: Interactive (Recommended)

./bin/setup

Follow the prompts to configure your Vault mount point and secret name.

Option 2: Manual

# Edit config/vault.conf directly
vim config/vault.conf

The bin/run script uses these environment variables:

• VAULT_ADDR - Vault server address (default: http://127.0.0.1:8200)
• VAULT_TOKEN - Authentication token (default: root for dev)

Add secrets to Vault:

vault kv put python-vault/demo \
  api_key="your-api-key" \
  db_pass="your-password" \
  region="us-west-2"

Access secrets in Python:

import os

api_key = os.environ.get("api_key")
db_pass = os.environ.get("db_pass")
region = os.environ.get("region")

The bin/run script automatically:

1. Starts Vault dev server (if not running)
2. Enables the KV mount point
3. Fetches all secrets from the configured path
4. Exports them as environment variables
5. Runs your command with secrets available

# Run all tests
./bin/run python -m pytest

# Run specific test file
./bin/run python -m pytest tests/test_main.py

# Run with verbose output
./bin/run python -m pytest -v

# Run with coverage
./bin/run python -m pytest --cov=src

Or use the Makefile:

make test

Create test files in tests/ following the test_*.py naming convention:

# tests/test_my_feature.py
from main import main

def test_main():
    """Test the main function."""
    # Your test code here
    assert True

tests/
├── __init__.py
├── test_main.py           # Tests for main.py
├── test_integration.py    # Integration tests
└── fixtures/              # Test fixtures and data
    └── sample_data.json

The pre-commit hook automatically runs:

1. Ruff Linting - Fast Python linter with auto-fix
2. Ruff Formatting - Consistent code style
3. mypy - Static type checking
4. Bandit - Security vulnerability scanning
5. pytest - All tests must pass

# Linting
./bin/run python -m ruff check .
./bin/run python -m ruff check --fix .  # Auto-fix issues

# Formatting
./bin/run python -m ruff format .

# Type checking
./bin/run python -m mypy .

# Security scanning
./bin/run python -m bandit -r .

# All tests
./bin/run python -m pytest

Or use Makefile shortcuts:

make lint     # Run linting
make format   # Format code

• Type hints - Use type annotations for all functions
• Docstrings - Document all public functions and classes
• Error handling - Use proper exception handling
• Security - Never hardcode secrets or credentials
• Testing - Write tests for all new features

Solution: Install Vault from https://www.vaultproject.io/downloads

# macOS
brew install vault

# Linux
wget https://releases.hashicorp.com/vault/1.15.0/vault_1.15.0_linux_amd64.zip
unzip vault_1.15.0_linux_amd64.zip
sudo mv vault /usr/local/bin/

Solution: Configure git:

git config user.name "Your Name"
git config user.email "[email protected]"

Solution: Ensure:

1. Vault is running: vault status
2. Mount point exists: vault secrets list
3. Secret exists: vault kv get python-vault/demo
4. Token has read permissions

Debug steps:

# Check Vault status
vault status

# List secret engines
vault secrets list

# Read secret directly
vault kv get python-vault/demo

# Check token capabilities
vault token capabilities python-vault/demo

Solution: Run checks manually to see detailed errors:

./bin/run python -m pytest
./bin/run python -m ruff check .
./bin/run python -m mypy .
./bin/run python -m bandit -r .

Solution: Recreate the virtual environment:

rm -rf venv/
python3 -m venv venv
./bin/run pip install -r requirements-dev.txt

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run quality checks: make lint && make test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

• Follow existing code style (enforced by ruff)
• Add tests for new features
• Update documentation as needed
• Ensure all quality checks pass
• Keep commits atomic and well-described

All submissions require review. We use GitHub pull requests for this purpose:

1. Automated checks must pass (linting, tests, security)
2. Code review by at least one maintainer
3. Documentation must be updated if needed
4. Tests must cover new functionality

This project is licensed under the MIT License - see the LICENSE file for details.

• HashiCorp Vault - Secrets management
• Ruff - Fast Python linter
• pytest - Testing framework
• mypy - Static type checker

• Vault Documentation
• Python Best Practices
• Git Hooks Guide
• Ruff Documentation