py-boiler-tools 2.0.3

A fast and flexible scaffolding tool for Python applications.

Py_Boil 🔥

A lightweight Python package that helps developers quickly bootstrap projects by generating ready-to-use boilerplate code. With py_boil, you can scaffold Python applications in seconds — from simple scripts to full-featured project structures.

---

📋 Table of Contents

• About the Project

• Built With

• Getting Started

  • Prerequisites
  • Installation
  • Installing Dev Dependencies

• Usage

• Versioning

• Roadmap

• Contributing

• License

• Contact

---

📖 About The Project

Stop wasting time setting up the same boilerplate code for every project. py_boil takes care of scaffolding your Python application, letting you focus on writing actual business logic.

Features

• 📦 Generate project scaffolds instantly
• ⚡ Ready-to-use templates (from Hello World to package structures)
• 🛠️ Customizable templates planned in future versions
• 🚀 Helps maintain consistency across projects

---

🏗️ Built With

• Python 3.10+
• uv for dependency management and reproducible environments
• bumpver for automated semantic versioning
• GitHub Actions for CI/CD pipeline
• pytest for testing framework
• Ruff for linting and formatting

---

🚀 Getting Started

---

👤 For Users

Installation

Install the latest release from PyPI:

pip install py-boiler-tools

Quick Usage

After installation, you can use the CLI to scaffold a new project:

# Simple Hello World App
pyboiler new basic

This will create a new files in the current project folder, including starter files.

For more options, run:

pyboiler --help

---

Prerequisites

Make sure you have Python 3.10+ and uv installed:

python3 --version
curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

Install dependencies and create a virtual environment with uv:

uv sync

This will:

• Create a .venv/ automatically
• Install dependencies listed in pyproject.toml
• Pin them exactly via a local uv.lock file

Installing Dev Dependencies

To install optional or development packages (like testing or formatting tools):

uv sync --dev

This will install your main dependencies plus all packages listed under [project.optional-dependencies.dev] in your pyproject.toml.

---

📝 Usage

Generate a simple Hello World project:

uv run py_boil new basic

Example output (placeholder):

project/
├── main.py
└── README.md

---

🏷 Versioning

py_boil uses bumpver for semantic versioning:

• Patch: bug fixes (0.1.0 → 0.1.1)
• Minor: new backward-compatible features (0.1.1 → 0.2.0)
• Major: breaking changes (0.2.0 → 1.0.0)

Bumping a version

bumpver patch   # 0.1.0 -> 0.1.1
bumpver minor   # 0.1.1 -> 0.2.0
bumpver major   # 0.2.0 -> 1.0.0

This updates the version in both pyproject.toml and src/py_boil/__init__.py and optionally creates a Git commit and tag.

---

🔄 CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment:

Automated Workflows

• 🧪 Test Suite: Runs on Python 3.10, 3.11, 3.12 across Ubuntu, Windows, and macOS
• 🎨 Code Quality: Linting and formatting with Ruff
• 📦 Build: Automated package building and validation
• 🚀 Release: Automated PyPI publishing when you create a GitHub release

Quality Metrics

• Test Coverage: 97% code coverage
• Code Quality: Automated linting and formatting
• Multi-Platform: Tests on Ubuntu, Windows, and macOS
• Multi-Version: Tests on Python 3.10, 3.11, and 3.12

Local Development

Run the same checks locally:

# Install development dependencies
uv sync --dev

# Run tests
pytest tests/ -v --cov=py_boiler

# Run linting
ruff check src/ tests/
ruff format src/ tests/

# Build package
python -m build
twine check dist/*

---

🗺️ Roadmap

• Basic Hello World template
• Package scaffold with setup files
• CLI options for customization
• User-defined templates

See the open issues for a full list of proposed features (and known issues).

---

🤝 Contributing

We use uv for dependency management. To set up the development environment:

uv sync --dev

To contribute:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📜 License

Distributed under the Apache 2.0 License. See LICENSE for more information.

---

📬 Contact

Delali Funani – [e-mail]

Project Link: https://github.com/dfunani/py_boiler

Notes - PYPI

To upload your package to PyPI, follow these steps:

Ensure your package is ready for distribution (source code, metadata, etc.).

Install Twine and Build if not already installed:

pip install twine build

Build your package:

python -m build

Upload to PyPI:

twine upload --repository pypi dist/*

After uploading, you can install your package from PyPI using: pip install --index-url https://test.pypi.org/simple/ your-package-name