Skip to main content

Hatch plugin for ci system versioning

Project description

hatch-ci

PyPI version Python versions License - MIT

Build codecov

Black Mypy Ruff

NOTE This is a beta branch!

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

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

Borrowed ideas/code

License

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

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hatch-ci-0.1.4b68.tar.gz (29.1 kB view hashes)

Uploaded Source

Built Distribution

hatch_ci-0.1.4b68-py3-none-any.whl (22.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page