DevStart

A zero-config Python project scaffolder. One command, and you get a production-ready project with linting, type checking, tests, Docker, CI, pre-commit hooks, and a dev container — all wired up, all consistent with each other, all ready to use.

Why DevStart?

Starting a Python project is repetitive and error-prone. You pick a directory layout, write pyproject.toml from scratch, configure ruff and mypy and pytest individually, write a Dockerfile and docker-compose.yml, set up GitHub Actions, add a devcontainer, and then spend an hour making sure all of those agree with each other.

DevStart does it in one command. The result is a project that:

• Runs make check (the full pre-commit suite: lint + format + type-check + secret scan + security scan + spell check + tests) cleanly the moment it's created.
• Uses one source of truth for tool config (pyproject.toml) and one source of truth for code-quality checks (pre-commit, which CI also runs — no version drift).
• Follows modern Python packaging conventions: src/ layout, hatch dynamic versioning, PEP 561 typed marker.

Installation

Recommended:

uv tool install devstart

Or with pip:

pip install devstart

DevStart itself requires Python 3.14+. Generated projects can target 3.12, 3.13, or 3.14.

Quick Start

# Interactive — prompts for missing values
devstart new myproject

# Non-interactive — skip prompts, use defaults
devstart new myproject -y

# Scaffold into the current directory
mkdir myproject && cd myproject
devstart new . -y

After scaffolding:

cd myproject
make setup        # install uv, sync deps, register git hooks
make check        # run the full pre-commit suite (canonical quality gate)
make dev          # run the project: uv run python -m myproject

That's it — the project is fully configured and ready to develop in.

CLI Reference

devstart new [NAME] [OPTIONS]
devstart --version

Project name rules

• Must be a valid Python identifier (letters, digits, underscores; cannot start with a digit).
• Cannot be a Python keyword (class, def, …), a dunder name (__init__), or a stdlib module name (json, re, …).
• Hyphens are not allowed in explicit names — devstart new my-project is rejected.
• When using devstart new ., the directory name is kept verbatim for things that depend on the host path (devcontainer mount, compose volume target). Non-identifier characters are converted to underscores for the Python package name. Example: in test-proj/, you get src/test_proj/ and the devcontainer still binds to /workspaces/test-proj.

What You Get

Every generated project has this layout:

myproject/
├── src/myproject/
│   ├── __init__.py            # __version__ + __app_name__ (single source of truth)
│   ├── __main__.py            # `python -m myproject` entry point
│   ├── main.py
│   └── py.typed               # PEP 561 marker — package ships type info
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   └── test_main.py
├── docker/
│   ├── Dockerfile             # uv-based, multi-stage layer caching
│   ├── docker-compose.yml         # dev compose
│   └── docker-compose.prod.yml    # prod overrides
├── docs/diagrams/
│   └── class_diagram.puml         # PlantUML starter
├── .vscode/
│   ├── launch.json            # debugpy: "Debug Module" + "Debug Current File"
│   └── settings.json          # format-on-save (ruff), mypy strict, pytest
├── .devcontainer/
│   ├── devcontainer.json
│   └── docker-compose.yml
├── .github/workflows/
│   └── ci.yml                 # runs pre-commit/action
├── .githooks/
│   └── pre-commit             # executable wrapper, registered by `make setup`
├── .pre-commit-config.yaml
├── pyproject.toml             # all tool config lives here
├── Makefile                   # `make help` lists every target
├── README.md
├── .gitignore
├── .dockerignore
├── .env / .env.example
└── .python-version

Pre-configured tooling

Pre-commit is the single source of truth for code-quality checks; CI just runs it. No version drift between your laptop and the build server.

Test coverage

make test-cov runs pytest with coverage and writes two reports:

• a terminal summary (term-missing) showing which lines are uncovered, and
• lcov.info at the project root, consumed by the Coverage Gutters VS Code extension (included in the recommended extensions).

After running it once, open any source file and run Coverage Gutters: Display Coverage (or click Watch in the status bar) to render covered/uncovered lines in the gutter. lcov.info is git-ignored.

Makefile targets

make help prints every target grouped by section. The full list:

Environment

Application

Quality

Docker (dev)

Docker (prod)

Release

Diagrams

Cleanup

Design Principles

• One source of truth, twice.
  • For tool configuration: pyproject.toml. No .ruff.toml, mypy.ini, setup.cfg, or tox.ini.
  • For code-quality checks: pre-commit. CI runs the exact same hooks — what passes locally passes in CI.
• src/ layout, always. Keeps tests honest by preventing accidental imports from the project root.
• Hatch dynamic versioning. __version__ in src/<project>/__init__.py is the only place a version number lives. pyproject.toml reads from it.
• Modern Python. Generated projects target Python 3.12+ and use modern type hints (PEP 695, type statements, | unions).
• No raw print. Generated code uses Rich for styled CLI output and structured logging.
• Devcontainer parity. The devcontainer's mounted workspace path matches the host directory name even when the host path contains hyphens — so VS Code's "Reopen in Container" just works.

Contributing

git clone https://github.com/AymanKastali/DevStart.git
cd DevStart
make setup
make check

Issues and PRs welcome at https://github.com/AymanKastali/DevStart/issues.

License

MIT