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

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

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.3.tar.gz (54.1 kB view details)

Uploaded Source

Built Distribution

hatch_ci-0.1.3-py3-none-any.whl (22.3 kB view details)

Uploaded Python 3

File details

Details for the file hatch_ci-0.1.3.tar.gz.

File metadata

  • Download URL: hatch_ci-0.1.3.tar.gz
  • Upload date:
  • Size: 54.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for hatch_ci-0.1.3.tar.gz
Algorithm Hash digest
SHA256 317e875304ae13f12a44e9cf450f3efc3cdfc2111bf2f7b0279b7e73d267d25e
MD5 d9f8b078a0974391620b173972523abd
BLAKE2b-256 d7cba7498f6d3789c734313d4b62169ce5a86d199cc0bfefeb7678a5424f6f75

See more details on using hashes here.

File details

Details for the file hatch_ci-0.1.3-py3-none-any.whl.

File metadata

  • Download URL: hatch_ci-0.1.3-py3-none-any.whl
  • Upload date:
  • Size: 22.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for hatch_ci-0.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 840f036ca1e9687f86ec05cc9baa06ddf8ea4956c96a16f699e6a7ea7ff490a3
MD5 72b234ad608af1c0001ccf970c928eea
BLAKE2b-256 45fc6b76aba87527968be169f878f83fa7dc29d8dbd64c098ddf413c9ba6c49a

See more details on using hashes here.

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