Skip to main content

Safely creating releases when you change the version number.

Project description

CircleCI

Carthorse

Safely creating releases when you change the version number.

The intention is to only create the release tag when the release is good to go. No more brown bag releases, where a tag is cut only to find there’s a continuous integration or build failure that means you immediately need to cut another tag.

You use it by adding configuration to a yaml or toml file, and then adding the following to your continuous integration pipeline:

pip install -U carthorse
carthorse

What does it do?

  • Extract your project’s version from its source code.

  • Format a tag based on the version.

  • Perform a number of checks, if any of those fail, stop.

  • Perform any actions you specify, which usually includes creating and pushing the version tag.

TOML Configuration

Your file should contain a section such as the following:

[tool.carthorse]
version-from = "poetry"
tag-format = "v{version}"
when = [
  "version-not-tagged"
]
actions = [
   { run="poetry publish --build"},
   { name="create-tag"},
]

This is designed so that it can be included as part of a pyproject.toml file.

YAML Configuration

Your file should contain a section such as the following:

carthorse:
  version-from: poetry
  tag-format: v{version}
  when:
    - version-not-tagged
  actions:
    - run: "poetry publish --build"
    - create-tag

Version extraction

The following methods of extracting the version of a project are currently supported:

pyproject.toml

This will parse a project’s pyproject.toml and use the standard version key as the version for the project.

setup.py

This will run python setup.py --version and use the version returned.

poetry

This will parse a project’s pyproject.toml and use the tool.poetry.version key as the version for the project.

flit

This will extract the version from a flit-style __version__ without importing the package. For example, if your module is called foobar, this will look in either foobar/__init__.py or foobar.py. The config for that would be:

[tool.carthorse]
version-from = { name="flit", module="foobar" }
file

This will extract the version from a specified file. By default, this will be the stripped contents of the whole file, but a pattern can be specified. This can be useful to extract the version from a setup.py without executing it. The config for that would be:

[tool.carthorse]
version-from = { name="file", path="setup.py", pattern="version=['\"](?P<version>[^'\"]+)" }

This extracts only the first version it encounters in a file, so it can also be used for extracting the version from a CHANGELOG:

[tool.carthorse]
version-from = { name="file", path="CHANGELOG.md", pattern='## (?P<version>\d+\.\d+\.\d+)' }
none

This will return an empty string as the version. This is useful if you’re using carthorse as a way of managing git tags or timestamped releases.

env

This will extract the version from the specified environment variable. For example, if you have constructed the version in $VERSION you could extract it with:

[tool.carthorse]
version-from = { name="env" }

If you need to extract it from an environment variable with a different name, for example $MYVERSION, you could extract it with:

[tool.carthorse]
version-from = { name="env", variable="MYVERSION" }

Tag formatting

The tag-format configuration option lets you control the format of the version tag by specifying a python format string into which the version will be interpolated. The default is v{version}.

The names available to use in this are:

version

The version returned by the version extraction.

now

A python datetime for the current date and time.

Performing checks

Each check in the when configuration section will be performed in order. If any fail then no actions will be performed.

The following checks are currently available:

version_not_tagged

This will pass if no current git tag exists for the version extracted from the poject.

never

A safety net and testing helper, this check will never pass.

always

Useful if you basically want to skip the checking phase.

Actions

If all the checks pass, then the actions listed are executed in order. If an error occurs during the execution of an action, no further actions will be executed.

The following actions are currently available:

run

Run the specified command in a shell. The full environment will be passed through and $TAG will contain the tag computed from the tag format.

create_tag

This will create a git tag for the computed tag based on the extracted version and push it to the specified remote. By default, the origin remote is used.

If you are using carthorse to manage tags per environment, for example, you can ask for existing tags to be updated as follows:

[tool.carthorse]
actions = [
   { name="create-tag", update=true},
]
update_major_tag

This will create or update a major version tag based on the extracted version and force-push it to the specified remote. By default, the origin remote is used.

The major version is extracted from tag computed using the tag-format using a regular expression.

By default, the pattern used is 'v[0-9]+', but this can be configured.

Here’s how you could use a different pattern and push to a different remote:

[tool.carthorse]
actions = [
   { name="update-major-tag", pattern='v\d\.\d', remote='upstream'},
]

Project details


Download files

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

Source Distribution

carthorse-2.0.3.tar.gz (13.5 kB view details)

Uploaded Source

Built Distribution

carthorse-2.0.3-py3-none-any.whl (8.6 kB view details)

Uploaded Python 3

File details

Details for the file carthorse-2.0.3.tar.gz.

File metadata

  • Download URL: carthorse-2.0.3.tar.gz
  • Upload date:
  • Size: 13.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for carthorse-2.0.3.tar.gz
Algorithm Hash digest
SHA256 a3167633259b567a1a11d980ad6c03ceedf1f6e92530b1a6c04d9ef1baab4e2d
MD5 1e00e999539348f101d850e106c2784e
BLAKE2b-256 753dc5eddb1fda0b572edb225060a620e41e40b11085abb1abdcb32706bcd5ac

See more details on using hashes here.

File details

Details for the file carthorse-2.0.3-py3-none-any.whl.

File metadata

  • Download URL: carthorse-2.0.3-py3-none-any.whl
  • Upload date:
  • Size: 8.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for carthorse-2.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 d293d832aeec203441b8a8922326484676bc1758cc8b724e2358185d0e2e6024
MD5 c9804816d0aab6efcbc9594778f30e37
BLAKE2b-256 e924bfa0ef47efffe02464e967bb507c9a6e35b2724c638e504a9141f1d6781e

See more details on using hashes here.

Supported by

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