Python Project Scaffolding (Windows batch)

A tiny, batteries-included Windows batch script to bootstrap a minimal, modern Python project in seconds.

What it does

1. Asks for a project name and converts it to a safe, lowercase folder name (e.g., "My App" → "my-app").
2. Creates folders: docs/, src/<name>/, tests/, and a virtual environment venv/.
3. Initializes a Git repository (if Git is installed) on branch main.
4. Generates essential files: .gitignore, README.md, requirements.txt, pyproject.toml, setup.py, pytest.ini, VS Code settings, and a tiny sample module + CLI.
5. Activates the new virtual environment at the very end and stops (no commands run after activation).

Why batch + PowerShell?

cmd.exe makes multi-line file generation tricky. The script calls PowerShell only to write file contents reliably. You don't need to learn PowerShell to use this.

Usage

From cmd in the repository root:

python_project_scaffolding.bat

• Type your project name when prompted.

• You'll be asked for a destination parent folder (press Enter to use the current folder).

• When it finishes, the virtual environment will be active in your current shell and you'll see:

  [Done] Virtual environment activated. Next: pip install -e . -r requirements.txt

Note: requirements.txt starts empty. It's fine to run pip install -e . by itself; add -r requirements.txt only after you've added dependencies to that file.

Next steps inside your new project:

pip install -U pip
pip install -e .
REM optional: after you add dependencies
pip install -r requirements.txt
pytest -q
python -m <your-project-name>.cli

Clone this repository

Use Git to clone the scaffolder locally.

Now run the script:

python_project_scaffolding.bat

Notes:

• If you double-click the .bat from Explorer, Windows opens a temporary cmd window; the venv activates there but the window closes when the script ends. To keep the venv active, run the script from an existing cmd window.
• The script uses PowerShell only to write file contents; no admin rights required.

CI

• Minimal GitHub Actions workflow runs on push to main and smoke‑tests the scaffolder on Windows (multiple Python versions).

Prerequisites

• Windows 10/11
• Python 3.10+ available as py -3 or python
• Git (optional, for repository initialization)

Generated project layout

<your-project-name>/
  docs/
  src/
    <your-project-name>/
  tests/
  venv/            # created by the script
  .git/            # if Git was available
  .gitignore
  README.md
  requirements.txt
  pyproject.toml
  setup.py
  pytest.ini
  .editorconfig
  .gitattributes
  .vscode/

FAQ

• What are .editorconfig, .gitattributes, and pytest.ini?
  • .editorconfig: Keeps editor settings consistent (UTF-8, end-of-line, trimming whitespace, 4-space Python indents).
  • .gitattributes: Normalizes line endings in Git and keeps .bat files as CRLF on Windows.
  • pytest.ini: Points pytest to tests/ and sets quiet mode -q by default.