Equipment: Python Project Scaffolding Framework

Equipment is a scaffolding framework for starting Python applications with a ready-to-use project layout. It creates a project that already has configuration loading, dependency injection, logging, storage, SQLAlchemy database access, queues, scheduling, tests, and optional FastAPI and MCP server entry points.

Use Equipment when you want a practical application skeleton instead of a blank directory. It is most useful for scripts that may grow, backend services, queue workers, scheduled jobs, internal tools, and web APIs that need consistent structure from day one.

Requirements

• Python 3.13, 3.14, or 3.15.
• Windows, macOS, or Linux.
• pip for installation.
• Optional external services depending on features: Redis for the Redis queue driver, S3-compatible storage for the S3 driver, and database drivers for MySQL or PostgreSQL.

Install

python -m pip install equipment

For an isolated command-line install, pipx install equipment also works when pipx is available.

Create A Project

equipment new my-app
cd my-app
python -m pip install .
python main.py

On Windows, the Python launcher is also supported:

py -3.14 -m pip install equipment
equipment new my-app
cd my-app
py -3.14 -m pip install .
py -3.14 main.py

Generated Project Structure

my-app/
├── app/                  # Application services and scheduler definitions
│   ├── __init__.py       # App container and custom service registration
│   ├── Inspire.py        # Example service
│   └── Scheduler.py      # Example scheduled tasks
├── config/               # YAML and JSON configuration files
│   ├── app.yaml
│   ├── database.yaml
│   ├── inspiring.json
│   ├── log.yaml
│   ├── mcp.yaml
│   ├── queue.yaml
│   ├── storage.yaml
│   └── web.yaml
├── database/             # SQLite file location and Alembic migrations
├── storage/              # Local storage and log directories
├── tests/                # unittest base class and example tests
├── .env.example          # Environment variable template
├── main.py               # Script entry point and feature examples
├── mcpserver.py         # MCP server entry point
├── queues.py             # Redis queue worker entry point
├── scheduler.py          # Scheduler process entry point
├── web.py                # FastAPI entry point
├── pyproject.toml        # Generated project metadata and dependencies
└── README.md             # Generated project guide

Common Workflows

Run the generated script:

python main.py

Run the generated tests:

python -m unittest discover -s tests

Run the scheduler:

python scheduler.py

Run the Redis worker after setting QUEUE_CONNECTION=redis and starting Redis:

python queues.py

Run the FastAPI example:

python web.py

Expose application services to MCP clients such as Claude Code, Claude Desktop, Cursor, or VS Code. With the default stdio transport, the client starts the server from the project root:

claude mcp add my-app -- python mcpserver.py

Set MCP_TRANSPORT=http to serve it over HTTP on http://127.0.0.1:8001/mcp with python mcpserver.py.

Compile a project into bytecode and runtime assets:

equipment compile dist
cd dist
python main.pyc

Configuration Model

Equipment loads .env from the project root, then reads config/*.ini, config/*.yaml, and config/*.json. Configuration values can use ${NAME:default} interpolation.

Important generated settings:

Development And Maintenance

Install the repository dependencies and run tests:

python -m pip install -r requirements.txt
python -m pip install coverage runtype faker
python -m coverage run -m unittest discover -s tests
python -m coverage report

Build the documentation site:

cd website
npm ci
npm run build

Windows helper scripts use the PYTHON environment variable when set, otherwise python:

set PYTHON=py -3.14
test.bat

Cross-Platform Notes

• Prefer python -m ... commands because they work consistently in virtual environments.
• On Windows, use py -3.14 or python depending on how Python is installed.
• Do not rely on Unix-only commands such as rm, cp, or sed inside generated projects.
• Path handling in the current CLI uses pathlib so generated and compiled paths follow the active operating system.

Limitations And Assumptions

• equipment new downloads the template from the main branch of the Equipment GitHub repository, so project creation needs network access.
• Redis queue processing requires a running Redis service.
• S3 storage requires compatible credentials and bucket configuration.
• MySQL and PostgreSQL require optional database driver dependencies in the generated project.
• Local validation in this repository depends on the Python interpreters installed on the machine; CI is configured for Python 3.13, 3.14, and 3.15 on Ubuntu, Windows, and macOS.

Documentation

• Website: https://equipment-python.vercel.app
• LLM summary: https://equipment-python.vercel.app/llms.txt
• Full LLM manual: https://equipment-python.vercel.app/llms-full.txt

License

This project is open-sourced software licensed under the MIT license.

Equipment icons created by Freepik - Flaticon.

Author

Roger Vilà