Kraken wrapper
krakenw
is the CLi for interacting with Kraken-powered projects.
- It acts as a wrapper around the
kraken
CLI, so everything you read in the Command-line documentation applies tokrakenw
as well. - It adds various quality of life features to building projects with Kraken, such as being able to run it from inside sub-directories and resolving task names relative to the current directory.
- It ensures reproducible builds by installing Kraken and its dependencies into its own Python virtual environment and locking the versions of all dependencies in a
.kraken.lock
file. - It manages credentials keyed by host name for use in authenticating with Python package indexes when using an alternative
index_url
in your build script's requirements (see below). These credentials can also be read at build time by the Kraken build system to authenticate with the same hosts.
Installation
To use krakenw
, you need to have Python 3.10 or newer installed. You can install krakenw
using pipx
:
Usage
To use krakenw
with your project, you first need to define the requirements for your build script in the .kraken.py
file at the root of your project. This allows krakenw
to understand the Python packages to install in the isolated build environment to successfully run the build script. [See buildscript()
for more information on how to do this.]
Once you've defined the requirements, you can use the krakenw
command as a drop-in replacement for kraken
and it will ensure to install the required dependencies into a virtual environment before evaluating your build script and executing the build. The only exception to this are commands that are added by the krakenw
CLI itself, such as krakenw lock
and krakenw auth
.
Your typical use of the krakenw
CLI will look like this:
$ krakenw auth <hostname> -u <username> -p <password>
$ krakenw --upgrade lock
$ krakenw run <task-name> [<task-name> ...]
$ krakenw query tree --all
Note that all options accepted by krakenw
itself (such as --upgrade
) must be specified before the first positional argument. All arguments including the first positional argument are passed to the kraken
CLI. This includes the -v,--verbose
flag that is supported separately by krakenw
and kraken
; hence the following two commands have different semantics:
Build environments and lock files
Kraken-wrapper creates a Python virtual environment at the project's top-level directory in a folder called build/.kraken/venv
. This virtual environment is where the dependencies defined with the buildscript()
function are installed.
The krakenw lock
command creates a .kraken.lock
file that contains the details of your current build environment. Note that this file is always created based on the currently installed packages in the build environment. If you updated the requirements in the buildscript()
function call in .kraken.py
, you need to run krakenw --upgrade lock
to first upgrade the build environment before running krakenw lock
to update the lock file.
The build environment, lock file and .kraken.py
file may run out of sync. You can check the current status of all three using the krakenw --status
command:
$ krakenw --status
Key Source Value
--------------------- ----------------------------------------------- ----------------------------------------------------------------
Requirements /home/niklas/git/kraken/.kraken.py 653652d98e5ae05d045dc0348db23bfad63ed0224c82d0c835047a7afe1ff4dc
Lockfile /home/niklas/git/kraken/.kraken.lock -
Requirements hash 653652d98e5ae05d045dc0348db23bfad63ed0224c82d0c835047a7afe1ff4dc
Pinned hash a71eab8ae7fd3e3f2059fb272598682c159d86e8c97a941da2cd44ec8179c9c5
Environment /home/niklas/git/kraken/build/.kraken/venv VENV
Metadata /home/niklas/git/kraken/build/.kraken/venv.meta -
Created at 2024-02-15T22:25:53.903815
Requirements hash a71eab8ae7fd3e3f2059fb272598682c159d86e8c97a941da2cd44ec8179c9c5
This output tells you the following:
- The source of the build script requirements (your
.kraken.py
file) and the hash sum of these requirements. - The path to the lock file and the hash sum of
- (1) the pinned requirements, which must match with the hash sum of the requirements in the build script, and
- (2) the hash sum of the pinned requirements, which must match with the hash sum of the installed packages in the build environment.
- The path to the build environment and the hash sum of the installed packages in the build environment, as well as the installer that was used for the build environment. For more information on available installers, see below.
Installers
Kraken-wrapper supports different installers that can materialize your build environment. The default is VENV
which uses the venv
module from the Python standard library to create a virtual environment and then pip
to install requirements.
Since v0.34.0
, Kraken-wrapper also supports the UV
installer which uses uv to create the virtual environment and install requirements. Uv is a new project in its early stages, but is generally faster than the VENV
installer by a factor of 10-20x. To use the UV
installer, you have the following options:
- Set the
KRAKENW_USE=UV
environment variable. - Pass the
--use=UV
option to thekrakenw
command when installing your environment. - Run
krakenw config --installer=UV
to set UV as the default installer in~/.config/krakenw/config.toml
.
Credentials managment
The krakenw auth
command can be used to store credentials for a given hostname in the system keyring. Any index_url
or extra_index_url
in your build script's requirements that matches the hostname will use these credentials to authenticate with the package index.
Note
If no backend for the keyring
package is available, kraken-wrapper will fall back to writing the password as plain text into the ~/.config/krakenw/config.toml
configuration file. A warning will be printed to inform you about this.
Building subprojects
The kraken
CLI supports running in a sub project, but requires that you point it to the root of your project using
the -p,--project-dir
option. The krakenw
CLI will automatically find the root of your project and pass it to the
kraken
CLI for you. This means that you can run krakenw
from anywhere in your project and it will behave as if you
had run it from the root of your project but in the context of the current directory. Relative addresses passed to the
CLI will be considered relative to the Kraken project of the current directory.
For example, if you have a project with the following structure:
.
├── .kraken.py
└── sub-project
└── .kraken.py
And you have a task :t
in the sub-project, you can run it from the root of your project or the sub-project with
the kraken
CLI like thisL
(.) $ kraken run sub-project:t
(sub-project) $ kraken run t -p ..
And with the krakenw
CLI like this:
(.) $ krakenw run sub-project:t
(sub-project) $ krakenw run t
If you want to stop krakenw
from crawling up the directories until it finds the .git
project's top level directory
and the top-most Kraken build script, you can add # ::krakenw-root
as a comment to the top of your build script in
a sub-directory. This allows you to effectively treat a sub-directory as a separate Kraken project.
Environment variables
Krakenw considers the following environment variables:
Variable | Effect |
---|---|
KRAKENW_USE |
The installer to use for the build environment. Can be VENV or UV . |
KRAKENW_REINSTALL |
If set to 1 , the build environment will be reinstalled. This is analogous to passing --reinstall on the CLI. |
KRAKENW_INCREMENTAL |
If set to 1 , the latest requirements will be installed into the existing environment without first deleting it. This is analogous to passing --incremental on the CLI. |
KRAKENW_NO_KEYRING |
If set to 1 , the keyring package will not be used to store credentials. This is analogous to passing --no-keyring on the CLI. |
krakenw --help
usage: krakenw [-h] [-V] [-v] [-q] [--use {VENV,UV}] [--status] [--upgrade] [--reinstall] [--uninstall] [--incremental]
[--show-install-logs] [--no-keyring]
[cmd ...] ...
This is kraken-wrapper v0.34.1.
krakenw is a thin wrapper around the kraken cli that executes builds in an isolated
build environment. This ensures that builds are reproducible (especially when using
lock files).
To learn more about kraken, visit https://github.com/kraken-build/kraken-core.
positional arguments:
cmd {auth,list-pythons,lock} or a kraken command
args additional arguments
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
logging options:
-v increase the log level (can be specified multiple times)
-q decrease the log level (can be specified multiple times)
build environment:
--use {VENV,UV} use the specified environment type. If the environment type changes it will trigger a reinstall.
Defaults to the value of the KRAKENW_USE environment variable. If that variable is unset, and
if a build environment already exists, that environment's type will be used. The default
environment type that is used for new environments is VENV. [env: KRAKENW_USE=...]
--status print the status of the build environment and exit
--upgrade reinstall the build environment from the original requirements
--reinstall reinstall the build environment from the lock file [env: KRAKENW_REINSTALL=1]
--uninstall uninstall the build environment
--incremental re-use an existing build environment. Improves installation time after an update to the buildscript
dependencies, but does not upgrade all packages to latest. [env: KRAKENW_INCREMENTAL=1]
--show-install-logs show Pip install logs instead of piping them to the build/.venv.log/ directory.
[env: KARKENW_SHOW_INSTALL_LOGS=1]
authentication:
--no-keyring disable the use of the keyring package for loading and storing credentials. [env: KRAKENW_NO_KEYRING=1]
This is kraken-wrapper's help. To show kraken's help instead, run krakenw -- --help
API Documentation
kraken.common.buildscript
Use this function to the dependencies and additional install options for the build environment of your Kraken
build script that is installed and managed by Kraken-wrapper. This function must be called at the very beginning
of your .kraken.py
build script at the root of your project.
Example:
from kraken.common import buildscript
buildscript(
requirements=["kraken-build"],
)
from kraken.std import ...
You can depend on local dependencies and Python packages from URLs by prefixing them with <package name> @
:
buildscript(requirements=[
"kraken-build @ git+https://github.com/kraken-build/kraken.git@nr/python-project#subdirectory=kraken-build"
])
Parameters:
Name | Type | Description | Default |
---|---|---|---|
index_url |
str | None
|
The index URL for Python packages to install from. If this is a private package registry, the
credentials can be configured with the |
None
|
extra_index_urls |
Sequence[str] | None
|
Additional index URLs for Python packages to install from. |
None
|
requirements |
Sequence[str] | None
|
A list of Python package requirements to install. This usually contains at least |
None
|
additional_sys_paths |
Sequence[str] | None
|
Additional system paths to add to the Python environment. |
None
|
interpreter_constraint |
str | None
|
Constraints for the Python interpreter that the build must be run with. |
None
|