A modern, opinionated Python project template for data science and scientific computing projects.
This template creates a fully-featured Python project with modern tooling and best practices built-in. It's designed for data science, scientific computing, and research projects that need robust development workflows.
- Modular design with separate modules for CLI, models, preprocessing, schemas, and utilities
- Source layout with proper package structure
- Comprehensive testing setup with pytest and coverage
- Documentation with MkDocs and Material theme
- Marimo notebooks for reactive exploratory work
- Pixi for fast, reliable dependency management
- Typer for beautiful CLI interfaces
- Pre-commit for code quality hooks
- Ruff for formatting, linting, and import sorting
- Interrogate for documentation coverage
- Data Science Stack: pandas, numpy, scikit-learn, matplotlib, seaborn
- Scientific Computing: scipy, pymc, jax
- Development Tools: typer, python-dotenv, pyprojroot
- Optional CUDA Support for GPU acceleration
- Automatic Git setup with GitHub integration
- Pre-commit hooks for code quality
- Environment variable management
- Multiple Pixi environments for different use cases
Before using this template, ensure you have:
- Pixi installed: https://pixi.sh
- GitHub CLI installed:
pixi global install gh - GitHub authentication:
gh auth login
# Install cookiecutter if you haven't already
pip install cookiecutter
# Generate a new project
cookiecutter https://github.com/your-username/cookiecutter-python-project
# Follow the prompts to customize your projectWhen you run the template, you'll be prompted for:
- project_name: The full name of your project (e.g., "My Awesome Analysis")
- short_description: A brief description of what your project does
The following are inferred automatically from your environment (no prompts):
- github_username: From
gh api user - full_name: From
git config user.name - email: From
git config user.email
The template automatically generates:
- __project_kebabcase: URL-friendly version (e.g., "my-awesome-analysis")
- __project_snakecase: Python-friendly version (e.g., "my_awesome_analysis")
- __module_name: Python module name
- __package_name: PyPI package name
- __repo_name: GitHub repository name
your-project/
├── src/
│ └── your_project/
│ ├── __init__.py
│ ├── cli.py # Command-line interface
│ ├── models.py # Data models and ML models
│ ├── preprocessing.py # Data preprocessing utilities
│ ├── schemas.py # Data validation schemas
│ └── utils.py # General utilities
├── tests/
│ ├── __init__.py
│ ├── test_cli.py
│ ├── test_models.py
│ └── ...
├── docs/
│ ├── index.md
│ ├── api.md
│ └── ...
├── pyproject.toml # Project configuration (Hatchling build + Ruff)
├── README.md # Project documentation
├── .env # Environment variables (gitignored)
└── .gitignore
After project generation, the template automatically:
- Creates a
.envfile for environment variables - Installs Pixi environment with all dependencies
- Sets up Git repository with proper remote
- Installs pre-commit hooks for code quality
- Makes initial commit
# Default environment (tests, devtools, notebook, setup)
pixi shell
# Documentation environment
pixi shell --feature docs
# Testing environment
pixi shell --feature tests
# CUDA environment (for GPU acceleration)
pixi shell --feature cuda# Run tests
pixi run test
# Format code
pixi run lint
# Build documentation
pixi run build-docs
# Serve documentation locally
pixi run serve-docs
# Update pre-commit hooks
pixi run updateThe template includes a basic CLI structure using Typer:
# src/your_project/cli.py
import typer
app = typer.Typer()
@app.command()
def hello():
"""Echo the project's name."""
typer.echo("This project's name is Your Project")
@app.command()
def describe():
"""Describe the project."""
typer.echo("Your project description")Your CLI will be available as your-project-name after installation.
Edit pyproject.toml to add or remove dependencies:
[project]
dependencies = [
"pandas",
"numpy",
# Add your dependencies here
]
[tool.pixi.dependencies]
# Add conda-forge packages hereUse the .env file for configuration:
# .env
export API_KEY="your-secret-key"
export DATABASE_URL="your-database-url"The template includes pre-commit hooks for:
- Formatting and linting (Ruff, including import sorting via the
Irules) - Documentation coverage (Interrogate)
# Build and publish
python -m build
python -m twine upload dist/*Documentation is automatically built and can be deployed to GitHub Pages:
# Build docs
pixi run build-docs
# Deploy to GitHub Pages (if configured)
mkdocs gh-deploy- Create new files in
src/your_project/ - Add imports to
__init__.py - Update tests in
tests/
The template uses Jinja2 templating. Key variables:
{{ cookiecutter.project_name }}: Full project name{{ cookiecutter.__module_name }}: Python module name{{ cookiecutter.__package_name }}: Package name
The template includes pre and post-generation hooks:
- pre_gen_project.sh: Checks for required tools (GitHub CLI, pre-commit)
- post_gen_project.sh: Sets up Git, Pixi environment, and initial commit
- Keep models in
models.py - Put data preprocessing in
preprocessing.py - Define schemas in
schemas.py - General utilities go in
utils.py - CLI commands in
cli.py
- Write tests for all public functions
- Use pytest fixtures for common setup
- Aim for high test coverage
- Use hypothesis for property-based testing
- Document all public functions and classes
- Keep README.md up to date
- Use type hints for better IDE support
- Write docstrings in Google or NumPy style
Pixi not found: Install from https://pixi.sh
GitHub CLI not authenticated: Run gh auth login
Pre-commit hooks failing: Run pixi run update to update hooks
CUDA not working: Ensure you have CUDA 12 installed and use pixi shell --feature cuda
- Check the Pixi documentation
- Review Typer documentation
- See MkDocs Material documentation
To contribute to this template:
- Fork the repository
- Make your changes
- Test with a sample project
- Submit a pull request
This template is licensed under the MIT License.