Package: carthorse
CarthorseSafely creating releases when you change the version number.You use it by adding configuration to a yaml or toml file, and then adding the following
to your continuous integration pipeline:pipinstall-UcarthorsecarthorseTOML ConfigurationYour 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 apyproject.tomlfile.YAML ConfigurationYour file should contain a section such as the following:carthorse:version-from:poetrytag-format:v{version}when:-version-not-taggedactions:-run:"poetrypublish--build"-create-tagWhat does it do?Roughly speaking:Extract your project’s version from its source code.Format a tag based on the versionPerform a number of checks, if any of those fail, stop.Perform any actions you specify.Version extractionThe following methods of extracting the version of a project are currently supported:setup.pyThis will runpython setup.py--versionand use the version returned.poetryThis will parse a project’spyproject.tomland use thetool.poetry.versionkey as the version for the project.flitThis will extract the version from a flit-style__version__without importing
the package. For example, if your module is calledfoobar, this will look in eitherfoobar/__init__.pyorfoobar.py. The config for that would be:[tool.carthorse]version-from={name="flit",module="foobar"}fileThis 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 asetup.pywithout executing it. The config would that would be:[tool.carthorse]version-from={name="file",path="setup.py",pattern="version='(?P<version>[^']+)"}noneThis 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.envThis will extract the version from the specified environment variable. For example,
if you have constructed the version in$VERSIONyou 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 formattingThetag-formatconfiguration 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 isv{version}.The names available to use in this are:versionThe version returned by the version extraction.nowA pythondatetimefor the current date and time.Performing checksEach check in thewhenconfiguration section will be performed in order. If any fail
then no actions will be performed.The following checks are currently available:version_not_taggedThis will pass if no current git tag exists for the version extracted from the poject.neverA safety net and testing helper, this check will never pass.alwaysUseful if you basically want to skip the checking phase.ActionsIf 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:runRun the specified command in a shell. The full environment will be passed through and$TAGwill contain the tag computed from the tag format.create_tagThis will create a git tag for the computed tag based on the extracted version and push
it to the specified remote. By default, theoriginremote 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},]Changes1.4.0 (4 Oct 2022)Fix documentation bugs.Implementcarthorse--dry-run.1.3.0 (4 Feb 2020)Changes such that carthorse can cover the same use cases asansible-role-createtagwithout
needing ansible.Addedwhenofalways.Added skipping of version extraction usingnone.Support extracting the project version from an environment variable.Make the current datetime available when building the tag.Add support for updating existing git tags.1.2.0 (12 Sep 2019)Support extracting the project version fromflit-style project.Support extracting the project version from a file, or part of a file by regex.1.1.0 (1 Mar 2019)Support extracting the project version from asetup.py.Support for other packages providingversion-from,whenandactionscallables.1.0.1 (27 Feb 2019)Better PyPI metadata.1.0.0 (27 Feb 2019)First release, supporting poetry and git tagging.