Configuration Reference
This section provides detailed information about how each tool in this template is configured. Understanding these configurations will help you customize the environment to match your project's specific needs.
Configuration Files
| File | Tool | Purpose | Reference |
|---|---|---|---|
pyproject.toml, .devcontainer/devcontainer.json |
uv, Project | Dependencies, project metadata, Dev Container and VS Code settings | uv |
ruff.toml |
Ruff | Linting and formatting rules | Ruff |
ty.toml |
ty | Type checking configuration | ty |
.sqruff |
sqruff | SQL linting and formatting rules | sqruff |
pytest.ini |
pytest | Testing and coverage settings | Test |
.pre-commit-config.yaml |
pre-commit | Hook definitions | pre-commit |
noxfile.py |
nox | Task automation | Task Automation with nox |
.env, .env.local |
Settings |
Environment variables | Configuration Management |
Customizing for Your Project
Update project metadata:
1 2 3 4 5 6 | |
To change linting rules, coverage requirements, or type checking targets, edit the file listed above; each reference page explains its options.
Configuration Best Practices
1. Start with Defaults
The default configurations are production-tested. Only modify when you have a specific need.
2. Document Changes
If you modify configurations, document why:
1 2 3 4 5 | |
3. Keep Configurations Consistent
Ensure configurations work together:
- Ruff's line length should match your formatting preferences
- Type checking directories in ty.toml should match your project structure
- Test patterns should align with your file structure
4. Version Control
Commit configuration files to git. .env is ignored by git, so put secrets there; .env.local is committed (see Configuration Management).
5. Team Alignment
Configuration changes affect the entire team. Discuss before making major changes: - Changing coverage requirements - Modifying linting rules - Updating Python version requirements
Troubleshooting
Conflicts Between Tools
Ruff and other formatters: The template is configured to avoid conflicts. If you add other formatters, they may conflict with Ruff.
Solution: Use Ruff exclusively (it replaces Black, isort, etc.)
VSCode Not Picking Up Changes
After modifying configurations:
- Reload the VSCode window:
Cmd/Ctrl+Shift+P→ "Developer: Reload Window" - Ensure the Dev Container rebuilt if you changed
devcontainer.json
Pre-commit Hooks Failing
If hooks fail after configuration changes:
1 2 3 4 5 6 | |
Migration Guide
From pip to uv
If migrating from pip:
1 2 3 4 5 6 7 8 | |
From Black/isort to Ruff
Ruff replaces both. Remove old configs:
1 2 3 4 | |
Next Steps
- Customize your setup: Read the detailed configuration guides
- Understand the tools: Check the Development Guides
- See it in action: Browse Use Cases
Getting Help
- uv: Official Documentation
- Ruff: Official Documentation
- ty: Official Documentation
- pytest: Official Documentation
- pre-commit: Official Documentation