kapla project manager

kapla-cli is a packaging and build system for Python codebases. It can be used to develop several python packages in a single repository, and easily manage shared dependencies accross the packages.

It relies on:

• venv
• pip
• poetry
• poetry-core

poetry and pip usage

poetry is used in order to manage packages dependencies:

• A pyproject.toml must exist at the root of the monorepo.
• This pyproject.toml file use dependency groups to keep track of each package dependencies.
• A single lock file is thus used to pin dependency versions accross all packages. It avoids resolving dependency lock for each package, and shorten time required to update dependencies accross all packages.
• Each package in the monorepo must have a valid project.yml file.
• project.yml files are written according to a well known schema (KProjectSpec).
• At build or install time, pyproject.toml files are generated in each package directory from both the content of project.yml and the monorepo pyproject.toml file.
• Packages are either built using poetry build.
• Or installed using pip install -e /path/to/package (aka editable install). (See PEP 660 -- Editable installs for pyproject.toml based builds)

Packages are not installed using Poetry. Instead, pip is used to install packages in editable mode. This is possible using the master branch of poetry-core (not released yet) which supports PEP 660 as build system for the editable install.

Why poetry ?

Poetry is really powerful when it comes to declaring and resolving dependencies in a consistent manner. Without it, it would be difficult to ensure that all dependencies versions are compatible together.

Why pip and editable install ?

Even though poetry provides an install feature out of the box, things can become quite slow when working with dozens of project.

Moreover, poetry provide some support for local dependencies, the experience is far from optimal.

By using pip to install packages, it's possible to install several local dependencies in parallel without messing with .venv/lib/pythonX.X/site-packages/ directory.

Quick Start

Virtual environment

• Ensure a virtual environment exists at the root of a monorepo:

k venv

• Update pip toolkit within a virtual environment

k venv update

• Run a command within the virtual environment

k run python -c "import sys; print(sys.executable)"

Global actions

• Install all projects:

k install

• Install only two projects (and their dependencies)

k install pkg1 pkg2

• Build all projects

k build

• Build only two projects

k build pkg1 pkg2

Projects actions

• Add a project dependency (run the command from the package directory)

k project add package@version  # @version is optional

• Install the current project

k project install

• Show project dependencies

k project show [--latest] [--outdated] [--tree]

Configuration

Respects the use of venv environment variable VIRTUAL_ENV for the location of the virtual env should it be different from <project_roo>/.venv