⚡ quickforge

Modern Python project bootstrapper with 2025's best toolchain.

Zero Config • Modern Tools • One Command

Installation • Quick Start • Project Types • Commands

---

✨ What quickforge Does

One command creates a complete Python project with modern tooling:

quickforge new myproject

That's it! Your project is ready with all the best practices built in.

⚡ Modern Toolchain

• uv - Blazing fast package manager (10-100x faster than pip)
• ruff - Linting & formatting (replaces black, isort, flake8)
• basedpyright - Strict type checking
• pytest - Testing with coverage
• pre-commit - Automated code quality

📦 Everything Configured

• ✅ Proper package structure (src layout)
• ✅ pyproject.toml with all tools configured
• ✅ Pre-commit hooks ready to go
• ✅ GitHub Actions CI/CD
• ✅ VS Code settings optimized
• ✅ Type checking enabled from day one
• ✅ Test skeleton with pytest + coverage
• ✅ Full-text LICENSE file for any of six licenses (MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, Unlicense, Proprietary)

🔄 Migration Tools

• Upgrade legacy projects to modern tooling
• Migrate from Poetry, pip, pipenv, or setuptools
• Convert black/isort/flake8/mypy to ruff/basedpyright

---

📦 Installation

# Using uv (recommended)
uv tool install quickforge

# Using pip
pip install quickforge

# Using pipx
pipx install quickforge

---

🚀 Quick Start

Interactive Mode (Default)

quickforge new myproject

Prompts you for project type, Python version, license, author info, and features.

Non-Interactive Mode

# Quick library with defaults
quickforge new mylib --type library --yes

# CLI with strict type checking
quickforge new mycli --type cli --strict

# FastAPI project
quickforge new myapi --type api --yes

# Specify everything
quickforge new myproject \
    --type library \
    --python 3.12 \
    --license MIT \
    --author "Jane Doe" \
    --email "jane@example.com"

After Creating a Project

cd myproject
uv sync                    # Install dependencies
uv run pytest              # Run tests
uv run ruff check .        # Lint code
uv run ruff format .       # Format code
uv run basedpyright        # Type check
uv run pre-commit install  # Setup git hooks

---

📁 Project Types

Type	Description	Use Case
library	PyPI-publishable package	Reusable code, open source packages
cli	Command-line tool with Typer	Terminal applications, dev tools
api	FastAPI web service	REST APIs, microservices
app	Standalone application	Scripts that need structure
script	Single-file with inline deps	Quick automation, one-off tasks

---

📂 Generated Structure

myproject/
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── py.typed           # PEP 561 marker
│       └── main.py            # or cli.py for CLI projects
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── .github/
│   └── workflows/
│       └── ci.yml             # GitHub Actions
├── .vscode/
│   ├── settings.json
│   └── extensions.json
├── pyproject.toml             # All configuration
├── .pre-commit-config.yaml
├── .gitignore
├── README.md
└── LICENSE

---

🛠️ Commands

quickforge new

Create a new project:

quickforge new myproject [OPTIONS]

Option	Short	Description
--type	-t	Project type: library, app, cli, api, script
--python	-p	Python version: 3.11, 3.12, 3.13
--license	-l	License: MIT, Apache-2.0, GPL-3.0-only, BSD-3-Clause, Unlicense, Proprietary
--author	-a	Author name
--email	-e	Author email
--output	-o	Output directory
--strict		Enable strict type checking
--yes	-y	Skip prompts, use defaults
--no-git		Skip git initialization
--no-github-actions		Skip GitHub Actions
--no-pre-commit		Skip pre-commit config
--no-vscode		Skip VS Code settings
--with-docker		Include Docker configuration
--with-docs		Include MkDocs documentation

quickforge audit

Analyze existing projects for modernization opportunities:

quickforge audit ./my-project

Shows detected tooling, project health score, and recommendations.

quickforge upgrade

Migrate from legacy tooling to modern stack:

quickforge upgrade .              # Auto-detect and upgrade
quickforge upgrade . --from poetry  # Specify source tool
quickforge upgrade . --dry-run      # Preview changes

Migration	From	To
Package Manager	Poetry, pip, pipenv, setuptools	uv
Formatter	black	ruff format
Import Sorting	isort	ruff (I rules)
Linter	flake8	ruff lint
Type Checker	mypy	basedpyright

quickforge add

Add features to existing projects:

quickforge add github-actions   # CI/CD workflow
quickforge add docker           # Dockerfile + docker-compose.yml
quickforge add docs             # MkDocs with Material theme
quickforge add pre-commit       # Pre-commit hooks
quickforge add vscode           # VS Code settings
quickforge add devcontainer     # Dev container config

---

⚡ Why These Tools?

uv over pip/poetry/pipenv

Metric	pip	poetry	uv
Install Speed	1x	2x	10-100x
Written In	Python	Python	Rust
Lockfile	❌	✅	✅
Workspaces	❌	❌	✅

ruff over black/isort/flake8

Metric	black + isort + flake8	ruff
Speed	1x	10-100x
Config Files	3	1
Rules	~500	800+
Auto-fix	Limited	Extensive

basedpyright over mypy

Metric	mypy	basedpyright
Speed	1x	3-5x
Error Messages	Basic	Detailed
VSCode Integration	Good	Excellent
Strictness	Configurable	Stricter defaults

---

🧪 Development

# Clone and setup
git clone https://github.com/Technical-1/quickforge.git
cd quickforge
uv sync --extra dev
uv run pre-commit install

# Run tests
uv run pytest

# Run linters
uv run ruff check .
uv run ruff format .
uv run basedpyright

---

💡 Philosophy

1. Convention over configuration - Sensible defaults for 90% of projects
2. Modern by default - 2025's best tools, not legacy compatibility
3. Type-safe - Full type annotations from day one
4. Fast - Rust-based tools for instant feedback
5. Single source of truth - All config in pyproject.toml

---

📄 License

MIT License - see LICENSE for details.

---

Made by Jacob Kanfer