🛠️ INITpy

A Bare-Bone Python Monorepo Template

INITpy is a minimal, opinionated project layout designed for modern Python development. It leverages uv for lightning-fast environment management, tox for testing, and zensical for documentation.

---

✨ Key Features

• Single-Source Truth: Python dependencies managed via uv in pyproject.toml.
• Native Monorepo Support: Built-in logic for managing multiple packages (pkg1, shared_utils).
• Conventional Commits: Uses commitizen with vim for editing commit messages.
• Strict Consistency: A Docker-based Dev Container ensures every contributor uses the exact same tool versions.
• Robust CI/CD: Ready-to-go workflows for testing, linting (ruff), and static analysis (pyrefly).
• Documentation: Built with zensical (Python) and deployed via GitHub Pages.

---

🚀 Quick Start

If you are using VS Code and have the Dev Containers extension, simply open the folder and click "Reopen in Container".

Alternatively, via CLI:

# 1. Clone the template
git clone https://github.com/artdotlis/INITpy.git && cd INITpy

# 2. Spin up the environment (Requires Docker)
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

# 3. Bootstrap the project (Inside the container)
make dev
make runAct

---

🏗️ Project Structure

INITpy/
├── bin/                # Tooling shell scripts
├── configs/            # Tooling & Linting configurations
├── packages/           # Your Python packages (Monorepo)
│   ├── docs/  
│   ├── pkg1/
│   └── shared_utils/
├── pyproject.toml      # The heart of the project
└── Makefile            # Command automation (requires CONTAINER=container)

---

🛠️ Development Workflow

Makefile Command Reference

All commands must be run within the Dev Container or by passing CONTAINER=container.

Category	Command	Action
Setup	make dev	Installs lefthook, syncs all dependencies
Active	make runAct	Enters the virtual environment shell.
Quality	make runChecks	Runs lefthook pre-commit hooks (includes ruff, pyrefly)
Test	make runTests	Runs the test suite via tox.
Docs	make serveDocs	Previews documentation at http://localhost:8000 (configurable via .env - DOC_PORT).
Release	make runBump	Bumps version and updates CHANGELOG.
Git	make commit, make com	Generates commit message with commitizen or opens vim for editing, then commits.

✍️ Commit Messages

The make commit/make com target:

• If .commit_msg exists and is non-empty: opens it in vim for editing, then commits
• Else: runs cz commit --write-message-to-file to generate a commit message, commits using that message

Note: The Makefile removes .commit_msg after committing (temp file cleanup).

---

📚 Documentation

The API documentation is built with Zensical.

• Build: make runDocs
• Serve: make serveDocs
• Port: Configured via DOC_PORT in .env (default: 9191)

---

📜 License

Released into the public domain via the Unlicense. No strings attached.

---

Why the CONTAINER=container guard?

To prevent accidental execution on your host, Makefile uses a mandatory CONTAINER constraint. This safety gate ensures the code runs exclusively in the intended containerized environment.

---

✏️ Note: This project uses AI tools for code generation, review, and documentation. All AI-generated content is human-reviewed.