Scaffold Python
Create a new Python project scaffold with consistent structure and tooling.
Input Parsing
Accept input as: PROJECT_NAME
Examples:
$scaffold-python my-tool
If no project name is provided, ask the user for one before proceeding.
Preference Policy
- Prefer
uvfor initialization and environment management. - If
uvis missing:- warn the user that
uvis preferred, - remind them to install
uv, - ask for approval before using a fallback bootstrap path.
- warn the user that
- Fallback only after explicit user approval.
Recommended install reminder:
curl -LsSf https://astral.sh/uv/install.sh | sh
Steps (Preferred: uv)
- Create the project directory in the current working directory.
- Run:
uv init --name <project_name> --package - Ensure structure exists:
<project_name>/ src/ <package_name>/ __init__.py main.py tests/ __init__.py conftest.py .gitignore README.md pyproject.toml - Ensure
pyproject.tomlincludes:- Python
>=3.11 - dev dependencies:
pytest,ruff,mypy - Ruff config (line length 88, 4-space indent)
- mypy strict mode
- Python
- Write
src/<package_name>/__init__.pywith:__version__ = "0.1.0" - Write
src/<package_name>/main.pywith a minimalmain()entry point. - Write test stubs (
tests/__init__.py,tests/conftest.py). - Write
.gitignorefor Python artifacts. - Write
README.mdwith basic usage:uv run python -m <package_name> - Run:
uv sync - Report created files and next commands.
Fallback Steps (Only If Approved)
Use only when uv is unavailable and user explicitly approves fallback.
- Create the same project structure.
- Write/adjust
pyproject.tomlwith the same project and tool configuration. - Initialize a virtual environment:
python3 -m venv .venv .venv/bin/python -m pip install --upgrade pip - Install developer tools:
.venv/bin/pip install pytest ruff mypy - Report fallback usage and remind user to install
uvfor future scaffolds.
Output Requirements
- Report final directory tree.
- Report whether preferred (
uv) or fallback path was used. - If fallback was used, include the
uvinstall reminder at the end.