INITpy – A Bare‑Bone Python Project Template#

A minimal, opinionated, and fully‑automated Python project layout.

🛠️ Development Workflow#

1. Dev Container (Optional)#

The project ships with a Docker‑Compose powered dev container. It automatically installs all dev dependencies - ideal for a consistent and sandboxed development environment.

Inside the container you can use the make targets as below.

Prerequisites#

GNU/Linux
Docker
Docker Compose
Dev Container CLI

Steps#

Clone the repository:

git clone https://github.com/artdotlis/INITpy.git
cd INITpy

If using Docker, start the development container manually or use VSCode:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

Create and activate a virtual environment (inside docker the container):
```
make dev
make runAct
```

2. Makefile Targets#

Target	Purpose
`dev`	Sets up the development environment, installs the frozen dependency set, and installs the git hooks.
`tests`	Synchronises the test‑only dependency set.
`build`	Synchronises the build‑time dependency set.
`docs`	Synchronises the docs‑only dependency set.
`setup`	Installs uv, the specified Python version, creates a relocatable virtual environment, and upgrades pip.
`runAct`	Activates the `.venv` and cleans a temporary file.
`runChecks`	Runs the pre‑commit hook suite (`lefthook run pre-commit`).
`runDocs`	Builds the MkDocs site (using the dev configuration).
`serveDocs`	Serves the MkDocs site locally.
`runTests`	Executes the test suite via tox.
`runBuild`	Builds the declared packages (`pkg1`, `shared_utils`).
`runBump`	Bumps the version with cz and commits the change.
`runUV`	Executes an arbitrary `uv` command passed in `CMD`.
`runLock / runUpdate`	Exports the frozen dependency set to `requirements.txt` files for each package/group and locks the environment. Also updates the dependencies in `runUpdate`.
`com commit`	Generates a Conventional Commit message (via ollama or `cz`), validates it, and commits.
`recom recommit`	Commits the previously generated message (again validating with `cz`).

Important – the Makefile is guarded by ifeq ($(CONTAINER),container); if CONTAINER is not set to container the make process aborts with an error.
To run the targets, set the variable on the command line, e.g. make CONTAINER=container dev, or run it from inside the dev container.

📚 Documentation#

The full API documentation is built with MkDocs and automatically deployed to GitHub Pages.

# Build the site into the `public/` folder
make runDocs

You can preview the documentation locally while you work:

# Start a lightweight development server
make serveDocs

Open http://localhost:8000 to explore.

🚀 Features#

Zero‑configuration – All tooling, dependencies, and build settings are declared in a single pyproject.toml file.
Monorepo‑friendly – The layout supports multiple packages in a single repository, making it ideal for mono‑repo workflows.
Modern tooling – Linting, formatting, static analysis, and security checks are handled by black, ruff, and mypy.
Testing – Automated tests run with tox, and coverage reports are generated automatically.
Packaging – Distribution follows PEP 621; the project can be built and published via uv or pip.
Documentation – MkDocs generates a fully‑static site from Markdown; it can be previewed locally or published to GitHub Pages.
Containerised development – A Docker‑Compose dev container replicates the CI environment, ensuring consistent tool versions.
License – The project is released into the public domain under the Unlicense.

📜 License#

This project is licensed under the Unlicense.
Feel free to use, modify, and distribute it without any restrictions.

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