Skip to content

🛠️ INITpy#

A Bare-Bone Python Monorepo Template#

release: 0.11.0 The Unlicense Documentation Status

main

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.

shared_utils#

Shared utility library for all the packages in this repository.

📦 About#

shared_utils is a lightweight, internal library that provides a common set of helper functions, data‑structures, and utilities used across the various top‑level packages in the repository. It is private – not intended to be uploaded to PyPI – and is bundled with the main project via the uv monorepo build system.

đź“š Installation#

The library is automatically built and packaged when you run make runBuild from the repository root. There is no separate installation step required for consuming code in this mono‑repo.

If you need to add dependencies to the shared library, add them under the [project.dependencies] section of the root pyproject.toml or in this sub‑module’s pyproject.toml.

⚙️ Usage#

Import the module from your packages:

from shared_utils import <function_or_class>

pkg1#

An example package that lives inside the INITpy monorepo.

📦 About#

pkg1 is one of the first‑level projects bundled in the repository.
It demonstrates how a standalone application can depend on the internal shared_utils library and expose a console script entry point (pkg1).

Because it is part of a monorepo, the package is private – it should not be published to PyPI – and is built along with the other packages via the uv build system.

đź“š Installation & Build#

The package is automatically built when you run:

# From the repository root
make runBuild

There is no separate pip install step for consuming pkg1 from outside this repo; it is included in the repository’s wheel distribution.

If you add external dependencies, declare them in the root pyproject.toml or in this sub‑module’s [project.dependencies].

⚙️ Usage#

Console script#

# From the repository root (or any virtual‑env that has the repo’s
# packages on `sys.path`):
pkg1

Running the script will execute pkg1.main:run.

Importing in code#

from pkg1.main import run

đź“š Modules#

Module Description
pkg1.main The application’s main entry point; it coordinates the work performed by pkg1 and pulls in helpers from shared_utils.