Release and Git Repository Automation¶

A Python project release with Git integration. This program uses a configuration file (relpo.yaml) to create a pyproject.toml file to maintain projects with pixi.

Features:

Track versions using Git tags rather than having to keep versions in files in sync with the repository
Create Sphinx API documentation with dependent project inventories
Create, increment and update Git tags
Validate the change log and Git tag versions are in sync.
Incorporate custom jinja2 templates to amend the pyproject.toml file creation (see Templating).
Render templates using the project’s build information.
Environment distribution feature to shore up some of the limitations of pixi-pack.

Documentation¶

See the full documentation. The API reference is also available.

Obtaining¶

The library can be installed with pip from the pypi repository:

pip3 install zensols.relpo

Usage¶

The program is standalone, but needs template files to create the pyproject.toml file. The easiest way to do that is to use zenbuild, which has them. This process needs GNU make for build automation.

Create a relpo.yml file (see Configuration File and example relpo.yml).
Add source to src/<organization name>/<project name>
Add unit tests to tests
Add a makefile (see makefile)
Add git: git init .
Add the build sub: git submodule add https://github.com/plandes/zenbuild
Add a minimal change log: echo "## [0.0.1] - $(date +%Y-%m-%d)" > CHANGELOG.md (see Keep a Changelog)
Write the README.md or a placeholder: touch README.md
Create the pyproject.toml file and pixi environments: make pyinit

Configuration File¶

A minimal relpo.yml file is given below. The file has everything needed to create the standard project section of a pyproject.toml file, and the sections needed by pixi. Additional build and doc top level mappings can add to the pyproject.toml file creation and Sphinx API documentation (see example relpo.yml).

# author full name and email
author:
  name: <first> <last>
  email: email@example.com
# GitHub user name
github:
  user: exghuser
# 'project' section metadata
project:
  # company or organization name
  domain: acme
  # project name
  name: anvil
  # project documentation
  short_description: A short description
  long_description: >-
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
    tempor incididunt ut labore et dolore magna aliqua.
  # keywords used in the package metadata
  keywords:
    - file
    - utility
  # Python version and dependencies
  python:
    # Python interpreter versions
    version:
      # constraint on install eligibility
      required: '>=3.11,<3.13'
      # last supported version of Python supported for the project
      previous: '3.11.12'
      # Python version supported for current development
      current: '3.12.10'
      # version of Python used to build/link specific to the host
      package_host: '3.11.6'
    # pypi dependencies added to 'project'
    dependencies:
      # cli
      - plac

Makefile¶

Project makefiles that use zenbuild have the minimal form:

## Build system
#
#
# type of project
PROJ_TYPE =         python
PROJ_MODULES =      python/doc git


## Includes
#
include ./zenbuild/main.mk

Templating¶

Build automation tasks often use the project’s configuration. You can retrieve project info using the program with jinja2 templates. For example, to output the author’s name as configured in the relpo.yml file:

cmd="relpo template --config relpo.yml,zenbuild/src/template/relpo/build.yml"
echo "author: {{ config.author.name }}" | $cmd

Environemnt¶

The envdist action of the program to create an environment distribution tar ball was added because pixi-pack currently lacks the functionality to deal with PyPi source distributions. The envdist feature creates a distribution file that is deployed to a new environment and then installed as an environment. To create one, first add the following entry to the relpo.yml file:

envdist:
  # the directory to cache conda and PyPi library files (usually '~/.cache/relpo')
  cache_dir: ~/.cache/relpo
  # the Pixi lock file (usually 'pixi.lock')
  pixi_lock_file: pixi.lock
  # the environment to export (i.e. 'default', 'testcur')
  environment: build-env
  # the platforms to export, or all if not provided (i.e. 'linux-64')
  #platforms: [linux-64, osx-64]
  # local files to add to the distribution
  injects:
    all:
      - pypi: target/dist/*.whl

Then compile the wheel in target/dist, which is done with the pywheel target when using zenbuild. Next create the environment tarball:

relpo envdist --config relpo.yml -o someproj.tar

Upload the tarball to the target machine and install it.

conda env create -f <arch>-environment.yml

By default, this will install only the local artifacts taken from the pixi.lock file and install them. However, some versions of conda and/or channels might have dependency version changes. In these cases it may be necessary to remove the nodefaults item from the channels item in the <arch>-environment.yml file.

Changelog¶

An extensive changelog is available here.

Community¶

Please star this repository and let me know how and where you use this API. Contributions as pull requests, feedback and any input is welcome.

License¶

MIT License