hatch-ci

hatch-ci

Introduction

This is a hatch-vcs heavily inspired plugin: it captures values from the build environment (eg. github, pyproject.toml etc.) and it uses these to process files during the build/packaging process.

In a typical project (let's call it foobar):

└── foobar-project
    ├── pyproject.toml
    └── src
        └── foobar
            └── __init__.py <- __version__ and __hash__ are update during build

With the pyproject.toml set like:

[build-system]
requires = ["hatchling", "hatch-ci"]
build-backend = "hatchling.build"

[project]
dynamic = ["version"]

# the version-file needs to be repeated twice here
[tool.hatch.version]
version-file = "src/package/__init__.py"

[tool.hatch.build.hooks.ci]
version-file = "src/{name}/__init__.py"

# performs these string replacements
process-replace = [
    ["re:(replace-me)", "[\\\\1]"],
    ["string-to-replace", "replacement-string"]
]

# before jinja process these
process-paths = [
    "src/project/template.jinja2"
]

Building the sdist/wheel package will have the __version__ and __hash__ set depending on the branch and current commit.

wheel version

During the wheel build the version is dynamically updated with information taken from the version-file field (see "Version source options").

Two variables will be overwritten/modified in version-file: the version containing the semgrep version and hash with the git commit for the build.

The version information is augmented with:

• a bNNN build number in creating the package foobar-1.0.0bNNNN (this can be sent to PyPi)
• if there's a tag v1.0.0 on the repo, it will build foobar-1.0.0 release (this can be sent to PyPi)

The last two steps are mean to be managed in a CI/CD system (github at the moment), to ensure hands-off releases.

In essence this pluging:

• manages the version information
• allows version replacement in text files using build information

Table of Contents

• Global dependency
• Version source
  • Version source options
• License

Global dependency

Ensure hatch-ci is defined within the build-system.requires field in your pyproject.toml file.

[build-system]
requires = ["hatchling", "hatch-ci"]
build-backend = "hatchling.build"

Version source

The version source plugin name is ci.

This will enable the hatch-ci pluging:

• pyproject.toml

  [project]
  ..
  dynamic = ["version"]  # this rerieves the version dynamically
  ..
  
  

Version source options

• pyproject.toml

  [tool.hatch.version]
  source = "ci"  # this pulls the version using the hatch-ci hook
  
  # this will put/update __version__ and __hash__ info in version-file
  version-file = "src/hatch_ci/__init__.py"
  
  # these files will be jinja2 processed, the environment will
  # contains variables as: branch, build, current, ref, runid, 
  # sha, version, workflow etc.
  paths = [ "README.md" ]
  
  # the listed paths will undergo replacement before jinja2 processing and
  # the variables 'a' & 'b' listed below wil be replaced with ctx attributes.
  fixers = [
      { 'a': '{ctx.workflows}' },
      { 'd': '{ctx.branch}' }
  ]
  

  The complete list of attributes is available here TEMPLATE.md.

Option	Type	Default	Description
version-file	str	None	A file where to write version/hash variables
paths	`list[str]	str`	None
fixers	list[dict[str,str]]	None	A list of dict, each key is a string to replace with the value

License

hatch-ci is distributed under the terms of the MIT license.