Skip to content

🛠️ INITpy

A Bare-Bone Python Monorepo Template

release: 0.9.4 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: Tooling and dependencies are declared in one pyproject.toml.
  • Native Monorepo Support: Built-in logic for managing multiple packages (pkg1, shared_utils).
  • AI-Powered Commits: Integration with Ollama to generate Conventional Commit messages based on your staged changes.
  • 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).

🚀 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:

```bash

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

text INITpy/ ├── bin/ # Tooling shell scripts ├── configs/ # Tooling & Linting configurations ├── packages/ # Your Python packages (Monorepo) │ ├── docs/ # Documentation configuration │ ├── 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
Active make runAct Enters the virtual environment shell.
Quality make runChecks Runs ruff, pyrefly, and other pre-commit hooks.
Test make runTests Runs the test suite via tox.
Docs make serveDocs Previews documentation at localhost:$DOC_PORT.
Release make runBump Bumps version and updates CHANGELOG.
Git make commit Generates AI commit message (via Ollama) or opens cz.

🧠 Smart Commits

The make commit target checks if an Ollama server is reachable.

  • If Ollama is up: It sends your git diff to the model, generates a message, and opens vim for you to edit.
  • If Ollama is down: It falls back to standard commitizen prompts.

đź“š Documentation

The API documentation is built with Zensical.

  • Build: make runDocs
  • Serve: make serveDocs

đź“ś License

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

Why the CONTAINER=container guard?

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

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:

python 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:

```bash

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

```bash

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

python 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.