bouillon

.. Copyright (c) 2020, Janus Heide. .. All rights reserved. .. .. Distributed under the "BSD 3-Clause License", see LICENSE.rst.

Bouillon

.. image:: https://github.com/janusheide/bouillon/actions/workflows/unittests.yml/badge.svg :target: https://github.com/janusheide/bouillon/actions/workflows/unittests.yml :alt: Unit tests

.. image:: https://img.shields.io/pypi/pyversions/bouillon :alt: PyPI - Python Version

.. image:: https://img.shields.io/librariesio/github/janusheide/bouillon :alt: Libraries.io dependency status for GitHub repo

A Tool for releasing machine learning model and service projects and other fast paced python projects. The base module can also be used as a basis for a custom cli.

Bouillon contains; a) a project structure, b) a Command Line Interface (CLI) for releasing etc., that is easy to adapt and, c) a couple of modules that provides helper functionality if your writing your own cli.

The idea is that you together with your project ship a program that assist the developers to release the project, and other tedious tasks, helping you to;

• Reduce time spent on repetetive tasks.
• Guareentee a well defined development environement, reducing human error.
• Simplify setup of CI/CD, as the same commands locally and remotely.

Getting Started

Will pip install packages (a venv is recommended)::

pip install bouillon[standard]
bouillon --help

usage: bouillon [-h]
                [-i INFILE]
                [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICIAL}]
                [--log-file LOG_FILE]
                [--dry-run]
                {build,clean,release} ...

Bouillon

positional arguments:
{build,clean,release}
                        available sub commands
    build               build.
    clean               clean temp files.
    release             release me.

options:
    -h, --help            show this help message and exit
    -i INFILE, --infile INFILE
                          path to input file (default: pyproject.toml)
    --log-level {DEBUG,INFO,WARNING,ERROR,CRITICIAL}
                          set log level. (default: WARNING)
    --log-file LOG_FILE   set log file. (default: None)
    --dry-run             perform a dry run, its helpfull to also set the log-level. (default: False)

Print help for the release command::

bouillon release --help
usage: bouillon release [-h]
                        [--check-branch]
                        [--releaseable-branch RELEASEABLE_BRANCH]
                        [--distribution-dir DISTRIBUTION_DIR]
                        [--news-files NEWS_FILES [NEWS_FILES ...]]
                        [--build-steps BUILD_STEPS [BUILD_STEPS ...]]
                        [--lint-steps LINT_STEPS [LINT_STEPS ...]]
                        [--test-steps TEST_STEPS [TEST_STEPS ...]]
                        version

The following checks and actions will be performed:

    1. Check that the choosen tag does not already exists.
    2. Check that we are releasing from the default_branch.
    3. Check that there are no unstaged changes on the current branch.
    4. Cleans the distribution folder.
    5. Run all linters.
    6. Run tests.
    7. Opens all news files for editing.
    8. Add and commit all news files.
    9. Creates the tag.
    10. Build the project.
    11. Uploads to pypi.
    12. Push the commit and tag to the origin.

Note that precedence of settings in decreasing order is as follows:
    commandline arguments -> project file (pyproject.toml) -> defaults.

positional arguments:
version               release version (e.g. '1.2.3').

options:
-h, --help              show this help message and exit
--check-branch          check that the branch is clean and up to date with remote. (default: True)
--releaseable-branch RELEASEABLE_BRANCH
                        branches from which release is allowed ('*' for any branch) (default: main)
--distribution-dir DISTRIBUTION_DIR
                        distribution directory. (default: dist)
--news-files NEWS_FILES [NEWS_FILES ...]
                        news files to open for edits. (default: ['NEWS.rst'])
--build-steps BUILD_STEPS [BUILD_STEPS ...]
                        build steps. (default: [['python', '-m', 'build']])
--lint-steps LINT_STEPS [LINT_STEPS ...]
                        lint steps. (default: [['brundle'], ['licensecheck']])
--test-steps TEST_STEPS [TEST_STEPS ...]
                        test steps. (default: [['pytest']])

.. note::

If the upload to pypi fails for any reason the tag will be deleted and the
release commit will be rolled back.

Usage::

bouillon release 0.0.1

Settings

The following settings (with defaults) can be overwritten in pyproject.toml::

[tool.bouillon]
check_branch = true
releaseable_branch = the git default branch
distribution_dir = "dist"
news_files = ["NEWS.rst",]
build_steps = [["python", "-m", "build"],]
lint_steps = [["brundle"],]
test_steps = [["pytest"],]

.. note::

releaseable_branch defaults to the git default branch, but can be set to a
static branch name like "dev" or "*" if all branches are permitted.

Logging

Supports standard log levels; DEBUG, INFO, WARNING, ERROR, CRITICAL, and writing log to a file.

Set the log level to DEBUG::

bouillon --log-level=DEBUG test

Set the log level to DEBUG and redirect output from executed commands to bar.log::

bouillon --log-level=DEBUG test >> bar.log

Set the log level to DEBUG and redirect output from executed commands to bar.log and log information to foo.log::

bouillon --log-level=DEBUG --log-file=foo.log test >> bar.log

Set the log level to DEBUG and redirect output from executed commands and log information to foo.log::

bouillon --log-level=DEBUG --log-file=foo.log test >> foo.log

Customize CLI

The standard bouillon command relies on varios other tools, e.g. pytest, twine and various linters, if you want to use some other tools you can install the base dependencies only, install the tools you like and configure bouillon according or make you own cli altogheter.::

pip install bouillon

You can get the base cli by downloading this git repository, e.g.::

git clone [e-mail]:janusheide/bouillon.git
cd src/bouillon

Start A New Project

You can use this repository as a template, use repository as a template guide. <https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template>__

Alternatively a more manual approach could be something like the following, where new_project is a empty git repository.

Clone the repository and remove the history::

git clone [e-mail]:janusheide/bouillon.git
cd bouillon
rm -rf .git

Copy the project structure into your existing (empty) git repository::

cp -r * ../new_project
cd ../new_project/
git add .
git commit -m 'Initial commit'
git push

You should now have a project with the following structure, and should modify as indicated below::

├── LICENSE.txt (replace)
├── NEWS.rst (replace)
├── pyproject.toml (modify)
├── README.rst (replace)
├── src (replace)
│   ├── bouillon
│   │   ├── bouillon.py
│   │   ├── cli.py (optinally copy and modify)
│   │   ├── git.py
│   │   └── __init__.py
└── test (replace)
    └── bouillon
        ├── test_bouillon.py
        ├── test_cli.py
        └── test_git.py

At some point it might be convenient to fork this repository, make any changes you need and use that as your template repository.

Goals

The primary use is intended for, but not limited to, projects with frequently releases, e.g. ML models and services. The goal is to make it quick and easy to set up a new project with the basic testing and releasing functionality.

User Friendliness .................

• Make the life of the user easier.
• Use plain Python and modules that many are familiar with.
• Quick and easy to setup and run repetitive tasks.
• All tasks should be equally easy to rin locally as in a CI/CD environement.

Reproducibility ................

• Results and builds should be easy to reproduce.
• All dependencies must be hard (versioned).
• The main branch should always be green.

Simplicity ..........

• Simplicity over features.
• Components should be easy to replace.

Automation ..........

• Reduce maintenance, repetitive tasks, and human errors.
• Easy to upgrade dependencies.
• Use merge policies and triggered and scheduled events.