python-semantic-release(1)

python-semantic-release Documentation

Section 1 python3-semantic-release bookworm source

Description

PYTHON-SEMANTIC-RELEASE

NAME

python-semantic-release - python-semantic-release Documentation

Automatic Semantic Versioning for Python projects. This is a Python implementation of semantic-release for JS by Stephan BÃ¶nnemann. If you find this topic interesting you should check out his talk from JSConf Budapest.

The general idea is to be able to detect what the next version of the project should be based on the commits. This tool will use that to automate the whole release, upload to an artifact repository and post changelogs to GitHub. You can run the tool on a CI service, or just run it locally.

INSTALLATION

python3 -m pip install python-semantic-release
semantic-release --help

Python Semantic Release is also available from conda-forge or as a GitHub Action. Read more about the setup and configuration in our getting started guide.

GETTING STARTED

If you haven't done so already, install Python Semantic Release following the instructions above.

There is no strict requirement to have it installed locally if you intend on using a CI service, however running with --noop can be useful to test your configuration.

Setting up version numbering

Create a variable set to the current version number. This could be anywhere in your project, for example setup.py:

from setuptools import setup

__version__ = "0.0.0"

setup(
name="my-package",
version=__version__,
# And so on...
)

Python Semantic Release is configured using setup.cfg or pyproject.toml. Set version_variable to the location of your version variable inside any Python file:

setup.cfg:

[semantic_release]
version_variable = setup.py:__version__

pyproject.toml:

[tool.semantic_release]
version_variable = "setup.py:__version__"

SEE ALSO:

	•		version_toml - use tomlkit to read and update the version number in a TOML file.
	•		version_pattern - use regular expressions to keep the version number in a different format.
	•		version_source - store the version using Git tags.

Setting up commit parsing

We rely on commit messages to detect when a version bump is needed. By default, Python Semantic Release uses the Angular style. You can find out more about this on Parsing of commit logs.

SEE ALSO:

	•		branch - change the default branch.
	•		commit_parser - use a different parser for commit messages. For example, there is an emoji parser.
	•		upload_to_repository - disable uploading the package to an artifact repository.
	•		hvcs - change this if you are using GitLab.

Setting up the changelog

If you already have a CHANGELOG.md, you will need to insert a placeholder tag so we know where to write new versions:

If you don't have a changelog file then one will be set up like this automatically.

SEE ALSO:

	•		changelog_file - use a file other than CHANGELOG.md.
	•		config-changelog_placeholder - use a different placeholder.

Releasing on GitHub / GitLab

Some options and environment variables need to be set in order to push release notes and new versions to GitHub / GitLab:

	•		hvcs - change this if you are using GitLab.
	•		GH_TOKEN - GitHub personal access token.
	•		GL_TOKEN - GitLab personal access token.
	•		GITEA_TOKEN - Gitea personal access token.

Distributing release on PyPI or custom repository

Unless you disable upload_to_repository (or upload_to_pypi), Python Semantic Release will publish new versions to Pypi. Customization is supported using a ˜/.pypirc file or config setting and environment variables for username and password/token or a combination of both. Publishing is done using twine.

	•		repository - use repository and/or credentials from ˜/.pypirc file
	•		repository_url - set custom repository url
	•		Artifact Repository - provide credentials using environment variables
	•		Configuring distribution upload - configuring CI distribution upload

Commands

semantic-release changelog

Print the changelog to stdout.

If the option --post is used and there is an authentication token configured for your vcs provider (GH_TOKEN for GitHub, GL_TOKEN for GitLab, GITEA_TOKEN for Gitea), the changelog will be posted there too.

semantic-release version

Figure out the new version number, update and commit it, and create a tag.

This will not push anything to any remote. All changes are local.

semantic-release print-version

Print to standard output the new version number.

If the option --current is used, it will display the current version number.

It can be used to retrieve the next version number in a shell script during the build, before running the effective release, ie. to rename a distribution binary with the effective version:

VERSION=$(semantic-release print-version)

semantic-release publish

Publish will do a sequence of things:

	1.		Update changelog file.
	2.		Run semantic-release version.
	3.		Push changes to git.
	4.		Run build_command and upload the distribution file to your repository.
	5.		Run semantic-release changelog and post to your vcs provider.
	6.		Attach the files created by build_command to GitHub releases.

Some of these steps may be disabled based on your configuration.

Common Options

Every command understands these flags:

--patch

Force a patch release, ignoring the version bump determined from commit messages.

--minor

Force a minor release, ignoring the version bump determined from commit messages.

--major

Force a major release, ignoring the version bump determined from commit messages.

--prerelease

Makes the next release a prerelease, version bumps are still determined or can be forced, but the prerelease_tag (see prerelease_tag) will be appended to version number.

--noop

No operations mode. Do not take any actions, only print what will be done.

--retry

Retry the same release, do not bump.

--define

Override a configuration value. Takes an argument of the format setting="value".

--verbosity

Change the verbosity of Python Semantic Release's logging. See Showing debug output.

Running from setup.py

Add the following hook to your setup.py and you will be able to run python setup.py <command> as you would semantic-release <command>:

try:
from semantic_release import setup_hook
setup_hook(sys.argv)
except ImportError:
pass

Running on CI

Getting a fully automated setup with releases from CI can be helpful for some projects. See Automatic releases.

DOCUMENTATION CONTENTS

Configuration

Configuration options can be given in three ways:

	•		setup.cfg file in a [semantic_release] section
	•		pyproject.toml file in a [tool.semantic_release] section
	•		-D option, like so:

semantic-release <command> -D <option_name>=<option_value>

Each location has priority over the ones listed above it.

Releases

branch

The branch to run releases from.

Default: master

version_variable

The file and variable name of where the version number is stored, for example:

semantic_release/__init__.py:__version__

You can specify multiple version variables (i.e. in different files) by providing comma-separated list of such strings:

semantic_release/__init__.py:__version__,docs/conf.py:version

In pyproject.toml specifically, you can also use the TOML list syntax to specify multiple versions:

[tool.semantic_release]
version_variable = [
'semantic_release/__init__.py:__version__',
'docs/conf.py:version',
]

version_toml

Similar to version_variable, but allows the version number to be identified safely in a toml file like pyproject.toml, using a dotted notation to the key path:

pyproject.toml:tool.poetry.version

version_pattern

Similar to version_variable, but allows the version number to be identified using an arbitrary regular expression:

README.rst:VERSION (\d+\.\d+\.\d+)

The regular expression must contain a parenthesized group that matches the version number itself. Anything outside that group is just context. For example, the above specifies that there is a version number in README.rst preceded by the string "VERSION".

If the pattern contains the string {version}, it will be replaced with the regular expression used internally by python-semantic-release to match semantic version numbers. So the above example would probably be better written as:

README.rst:VERSION {version}

As with version_variable, it is possible to specify multiple version patterns in pyproject.toml.

version_source

The way we get and set the new version. Can be commit or tag.

	•		If set to tag, will get the current version from the latest tag matching vX.Y.Z. This won't change the source defined in version_variable.
	•		If set to commit, will get the current version from the source defined in version_variable, edit the file and commit it.
	•		If set to tag_only, then version_variable is ignored and no changes are made or committed to local config files. The current version from the latest tag matching vX.Y.Z. This won't change the source defined in version_variable.

Default: commit

prerelease_tag

Defined the prerelease marker appended to the version when doing a prerelease.

•

The format of a prerelease version will be {tag_format}-{prerelease_tag}.<prerelease_number>, e.g. 1.0.0-beta.0 or 1.1.0-beta.1

Default: beta

tag_commit

Whether to create a tag for each new release.

Default: true

patch_without_tag

If this is set to true, semantic-release will create a new patch release even if there is no tag in any commits since the last release.

Default: false

major_on_zero

If this is set to false, semantic-release will create a new minor release instead of major release when current major version is zero.

Quote from Semantic Versioning Specification:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

If you do not want to bump version to 1.0.0 from 0.y.z automatically, you can set this option to false.

Default: true.

pre_commit_command

If this command is provided, it will be run prior to the creation of the release commit.

include_additional_files

A comma-separated list of files to be included within the release commit. This can include any files created/modified by the pre_commit_command.

Commit Parsing

commit_parser

Import path of a Python function that can parse commit messages and return information about the commit as described in Parsing of commit logs.

The following parsers are built in to Python Semantic Release:

•

semantic_release.history.angular_parser()

The default parser, which uses the Angular commit style with the following differences:

	•		Multiple BREAKING CHANGE: paragraphs are supported
	•		revert is not currently supported
	•

semantic_release.history.emoji_parser()

Parser for commits using one or more emojis as tags in the subject line.

If a commit contains multiple emojis, the one with the highest priority (major, minor, patch, none) or the one listed first is used as the changelog section for that commit. Commits containing no emojis go into an "Other" section.

See major_emoji, minor_emoji and patch_emoji. The default settings are for Gitmoji.

•

semantic_release.history.tag_parser()

The original parser from v1.0.0 of Python Semantic Release. Similar to the emoji parser above, but with less features.

•

semantic_release.history.scipy_parser()

A parser for scipy-style commits with the following differences:

	•		Beginning a paragraph inside the commit with BREAKING CHANGE declares a breaking change. Multiple BREAKING CHANGE paragraphs are supported.
	•		A scope (following the tag in parentheses) is supported

See scipy_parser for details.

major_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create major releases.

Default: :boom:

minor_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create minor releases.

Default: :sparkles:, :children_crossing:, :lipstick:, :iphone:, :egg:, :chart_with_upwards_trend:

patch_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create patch releases.

Default: :ambulance:, :lock:, :bug:, :zap:, :goal_net:, :alien:, :wheelchair:, :speech_balloon:, :mag:, :apple:, :penguin:, :checkered_flag:, :robot:, :green_apple:

use_textual_changelog_sections

If this is set to true with using the semantic_release.history.emoji_parser(), semantic-release will use human readable ASCII section headings in the changelog instead of the configured emoji.

Default: false

scipy_parser

Parses commit messages using scipy tags of the form:

<body>

The elements <tag>, <scope> and <body> are optional. If no tag is present, the commit will be added to the changelog section "None" and no version increment will be performed.

While <scope> is supported here it isn't actually part of the scipy style. If it is missing, parentheses around it are too. The commit should then be of the form:

<body>

To communicate a breaking change add "BREAKING CHANGE" into the body at the beginning of a paragraph. Fill this paragraph with information how to migrate from the broken behavior to the new behavior. It will be added to the "Breaking" section of the changelog.

Supported Tags:

API, DEP, ENH, REV, BUG, MAINT, BENCH, BLD,
DEV, DOC, STY, TST, REL, FEAT, TEST

Supported Changelog Sections:

breaking, feature, fix, Other, None

Commits

commit_version_number

Whether or not to commit changes when bumping version.

Default: True if version_source is commit, False for other values of version_source.

commit_subject

Git commit subject line. Accepts the following variables as format fields:

Image grohtml-69523-1.png

Default: {version}

commit_message

Git commit message body. Accepts the following variables as format fields:

Image grohtml-69523-2.png

Default: Automatically generated by python-semantic-release

commit_author

Author used in commits in the format name <email>.

Default: semantic-release <semantic-release>

NOTE:

If you are using the built-in GitHub Action, this is always set to github-actions <actions@github.com>.

Changelog

changelog_sections

Comma-separated list of sections to display in the changelog. They will be displayed in the order they are given.

The available options depend on the commit parser used.

Default: feature, fix, breaking, documentation, performance plus all the default emojis for semantic_release.history.emoji_parser.

changelog_components

A comma-separated list of the import paths of components to include in the changelog.

The following components are included in Python Semantic Release:

•

semantic_release.changelog.changelog_headers()

Only component displayed by default.

List of commits between this version and the previous one, with sections and headings for each type of change present in the release.

•

semantic_release.changelog.changelog_table()

List of commits between this version and the previous one, dsplayed in a table.

•

semantic_release.changelog.compare_url()

Link to view a comparison between this release and the previous one on GitHub. Only appears when running through semantic-release publish.

If you are using a different HVCS, the link will not be included.

It is also possible to create your own components. Each component is simply a function which returns a string, or None if it should be skipped, and may take any of the following values as keyword arguments:

Image grohtml-69523-3.png

You can should use **kwargs to capture any arguments you don't need.

changelog_file

The name of the file where the changelog is kept, relative to the root of the repo.

If this file doesn't exist, it will be created.

Default: CHANGELOG.md.

changelog_placeholder

A placeholder used to inject the changelog of the current release in the changelog_file.

If the placeholder isn't present in the file, a warning will be logged and nothing will be updated.

Default: .

changelog_scope

If set to false, **scope:** (when scope is set for a commit) will not be prepended to the description when generating the changelog.

Default: True.

changelog_capitalize

If set to false commit messages will not be automatically capitalized when generating the changelog.

Default: True.

Distributions

upload_to_pypi

Deprecated since version 7.20.0: Please use upload_to_repository instead

If set to false the pypi uploading will be disabled.

See Artifact Repository which must also be set for this to work.

Default: true

upload_to_repository

If set to false the artifact uploading to repository will be disabled.

See Artifact Repository which must also be set for this to work.

Default: true

upload_to_pypi_glob_patterns

Deprecated since version 7.20.0: Please use dist_glob_patterns instead

A comma , separated list of glob patterns to use when uploading to pypi.

Default: *

dist_glob_patterns

A comma , separated list of glob patterns to use when uploading dist files to artifact repository.

Default: *

repository

The repository (package index) name to upload to. Should be a section in ˜/.pypirc. The repositories pypi and testpypi are preconfigured.

Default: pypi

SEE ALSO:

•

The .pypirc file - ˜/.pypirc documentation

repository_url

The repository (package index) URL to upload the package to.

See Configuring distribution upload for more about uploads to custom repositories.

upload_to_release

If set to false, do not upload distributions to GitHub releases. If you are not using GitHub, this will be skipped regardless.

dist_path

The relative path to the folder for dists configured for setuptools. This allows for customized setuptools processes.

Default: dist/

remove_dist

Flag for whether the dist folder should be removed after a release.

Default: true

build_command

Command to build dists. Build output should be stored in the directory configured in dist_path. If necessary, multiple commands can be specified using &&, e.g. pip install -m flit && flit build. If set to false, build command is disabled and files should be placed manually in the directory configured in dist_path.

Default: python setup.py sdist bdist_wheel

HVCS

hvcs

The name of your hvcs. Currently only github and gitlab are supported.

Default: github

hvcs_domain

The domain url (without https://) of your custom vcs server.

hvcs_api_domain

The api url (without https://) of your custom vcs server.

check_build_status

If enabled, the status of the head commit will be checked and a release will only be created if the status is success.

Default: false

tag_format

Git tag format. Accepts the following variables as format fields:

Image grohtml-69523-4.png

Default: v{version}

ignore_token_for_push

Do not use the default auth token to push changes to the repository. Use the system configured method. This is useful if the auth token does not have permission to push, but the system method (an ssh deploy key for instance) does.

Default: false

Environment Variables

DEBUG

Set to * to get a lot of debug information. See Showing debug output for more.

CI

See Environment checks.

CIRCLECI

Used to check if this is a Circle CI environment.

FRIGG

Used to check if this is a Frigg environment.

SEMAPHORE

Used to check if this is a Semaphore environment.

TRAVIS

Used to check if this is a Travis CI environment.

GITLAB_CI

Used to check if this is a GitLab CI environment.

JENKINS_URL

Used to check if this is a Jenkins CI environment.

CI_SERVER_HOST

Host component of the GitLab instance URL, without protocol and port. Example: gitlab.example.com

NOTE:

Automatically set in a GitLab CI environment from version 12.1.

HVCS Authentication

GH_TOKEN

A personal access token from GitHub. This is used for authenticating when pushing tags, publishing releases etc. See Configuring push to Github for usage.

To generate a token go to https://github.com/settings/tokens and click on Personal access token.

GL_TOKEN

A personal access token from GitLab. This is used for authenticating when pushing tags, publishing releases etc.

GITEA_TOKEN

A personal access token from Gitea. This is used for authenticating when pushing tags, publishing releases etc.

Artifact Repository

PYPI_TOKEN

Deprecated since version 7.20.0: Please use REPOSITORY_PASSWORD instead

Set an API token for publishing to https://pypi.org/.

PYPI_PASSWORD

Deprecated since version 7.20.0: Please use REPOSITORY_PASSWORD instead

Used together with PYPI_USERNAME when publishing to https://pypi.org/.

PYPI_USERNAME

Deprecated since version 7.20.0: Please use REPOSITORY_USERNAME instead

Used together with PYPI_PASSWORD when publishing to https://pypi.org/.

REPOSITORY_USERNAME

Used together with REPOSITORY_PASSWORD when publishing artifact.

NOTE:

If you use token authentication with pypi set this to __token__

REPOSITORY_PASSWORD

Used together with REPOSITORY_USERNAME when publishing artifact. Also used for token when using token authentication.

WARNING:

You should use token authentication instead of username and password authentication for the following reasons:

	•		It is strongly recommended by PyPI.
	•		Tokens can be given access to only a single project, which reduces the possible damage if it is compromised.
	•		You can change your password without having to update it in CI settings.
	•		If your PyPI username is the same as your GitHub and you have it set as a secret in a CI service, they will likely scrub it from the build output. This can break things, for example repository links.
	•		Find more information on how to obtain a token.

REPOSITORY_URL

Custom repository (package index) URL to upload the package to. Takes precedence over repository_url

See Configuring distribution upload for more about uploads to custom repositories.

Commands

semantic-release changelog

Print the changelog to stdout.

semantic-release version

Figure out the new version number, update and commit it, and create a tag.

This will not push anything to any remote. All changes are local.

semantic-release print-version

Print to standard output the new version number.

If the option --current is used, it will display the current version number.

It can be used to retrieve the next version number in a shell script during the build, before running the effective release, ie. to rename a distribution binary with the effective version:

VERSION=$(semantic-release print-version)

semantic-release publish

Publish will do a sequence of things:

	1.		Update changelog file.
	2.		Run semantic-release version.
	3.		Push changes to git.
	4.		Run build_command and upload the distribution file to your repository.
	5.		Run semantic-release changelog and post to your vcs provider.
	6.		Attach the files created by build_command to GitHub releases.

Some of these steps may be disabled based on your configuration.

Common Options

Every command understands these flags:

--patch

Force a patch release, ignoring the version bump determined from commit messages.

--minor

Force a minor release, ignoring the version bump determined from commit messages.

--major

Force a major release, ignoring the version bump determined from commit messages.

--prerelease

Makes the next release a prerelease, version bumps are still determined or can be forced, but the prerelease_tag (see prerelease_tag) will be appended to version number.

--noop

No operations mode. Do not take any actions, only print what will be done.

--retry

Retry the same release, do not bump.

--define

Override a configuration value. Takes an argument of the format setting="value".

--verbosity

Change the verbosity of Python Semantic Release's logging. See Showing debug output.

Parsing of commit logs

The semver level that should be bumped on a release is determined by the commit messages since the last release. In order to be able to decide the correct version and generate the changelog, the content of those commit messages must be parsed. By default this package uses a parser for the Angular commit message style:

The body or footer can begin with BREAKING CHANGE: followed by a short description to create a major release.

NOTE:

Python Semantic Release is able to parse more than just the body and footer sections (in fact, they are processed in a loop so you can write as many paragraphs as you need). It also supports having multiple breaking changes in one commit.

However, other tools may not do this, so if you plan to use any similar programs then you should try to stick to the official format.

More information about the style can be found in the angular commit guidelines.

Available parsers

See commit_parser.

Writing your own parser

If you think this is all well and cool, but the angular style is not for you, no need to worry because custom parsers are supported.

A parser is basically a Python function that takes the commit message as the only argument and returns the information extracted from the commit. The format of the output should be a semantic_release.history.parser_helpers.ParsedCommit object with the following parameters:

ParsedCommit(
version level to bump: major=3 minor=2 patch=1 none=0,
changelog section (see: :ref:`config-changelog_sections`),
scope of change: can be None,
(subject, descriptions...),
(breaking change descriptions...)
)

The breaking change descriptions will be added to the changelog in full. They can and should also be included within the regular list of description paragraphs. The presence of a breaking change description will not implicitly trigger a major release.

If your parser is unable to parse a commit then it should raise semantic_release.UnknownCommitMessageStyleError.

The parser can be set with the commit_parser configuration option.

Automatic releases

The key point with using this package is to automate your releases and stop worrying about version numbers. Different approaches to automatic releases and publishing with the help of this package can be found below. Using a CI is the recommended approach.

Environment checks

On publish, a few environment checks will run. Below are descriptions of what the different checks do and under what condition they will run.

frigg

Condition: Environment variable FRIGG is 'true'

Checks for frigg to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that frigg said it checked out, not the current branch.

semaphore

Condition: Environment variable SEMAPHORE is 'true'

Checks for semaphore to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that semaphore said it checked out, not the current branch. It also checks that the thread state is not failure.

travis

Condition: Environment variable TRAVIS is 'true'

Checks for travis to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that travis said it checked out, not the current branch.

CircleCI

Condition: Environment variable CIRCLECI is 'true'

Checks for circle-ci to ensure that the build is not a pull-request and on the correct branch. The branch check, checks against the branch that circle-ci said it checked out, not the current branch.

GitLab CI

Condition: Environment variable GITLAB_CI is 'true'

Checks for gitlab-ci to ensure that the build is on the correct branch. The branch check, checks against the branch that gitlab-ci said it checked out, not the current branch.

Jenkins

Condition: Environment variable JENKINS_URL is set.

Determines the branch name from either the environment variable BRANCH_NAME or the environment variable GIT_BRANCH, and checks to ensure that the build is on the correct branch. Also, if CHANGE_ID is set, meaning it is a PR from a multi-branch pipeline, the build will not be automatically released.

Publish with CI

Add python setup.py publish or semantic-release publish as an after success task on your preferred Continuous Integration service. Ensure that you have configured the CI so that it can upload to an artifact repository and push to git and it should be ready to roll.

Configuring distribution upload

In order to upload to an artifact repository, Python Semantic Release needs credentials to access the project. You will need to set the environment variables REPOSITORY_USERNAME and REPOSITORY_PASSWORD. Use repository_url or REPOSITORY_URL to set a custom repository url. As an alternative the repository and/or credentials can be configured using the ˜/.pypirc file.

WARNING:

Make sure to protect any environment variable containing secrets on your CI service.

SEE ALSO:

	•		GitLab pypi-repository - GitLab example configuration
	•		The .pypirc file - ˜/.pypirc documentation

Configuring push to Github

In order to push to Github and post the changelog to Github the environment variable GH_TOKEN has to be set. It needs access to the public_repo scope for public repositories and repo for private repositories.

Guides

	•		Setting up python-semantic-release on Travis CI
	•		Setting up python-semantic-release on GitHub Actions

Publish with cronjobs

This is for you if for some reason you cannot publish from your CI or you would like releases to drop at a certain interval. Before you start, answer this: Are you sure you do not want a CI to release for you? (high version numbers are not a bad thing).

The guide below is for setting up scheduled publishing on a server. It requires that the user that runs the cronjob has push access to the repository and upload access to an artifact repository.

Create a virtualenv:

virtualenv semantic_release -p `which python3`

Install python-semantic-release:

pip install python-semantic-release

3. Clone the repositories you want to have scheduled publishing. 3. Put the following in publish:

VENV=semantic_release/bin

$VENV/pip install -U pip python-semantic-release > /dev/null

publish() {
cd $1
git stash -u # ensures that there is no untracked files in the directory
git fetch && git reset --hard origin/master
$VENV/semantic-release publish
cd ..
}

publish <package1>
publish <package2>

Add cronjob:

/bin/bash -c "cd <path> && source semantic_release/bin/activate && ./publish 2>&1 >> releases.log"

Troubleshooting

Things to check...

	•		Check setup.cfg for Configuration
	•		Check all applicable Environment Variables
	•		Git tags beginning with v. This is, depending on configuration, used for getting the last version.

Showing debug output

If you are having trouble with semantic-release there is a way to get more information during it's work.

By setting the --verbosity option to DEBUG you can display information from the inner workings of semantic-release.

NOTE:

Debug output is always enabled on GitHub Actions using the built-in action.

semantic-release changelog --verbosity=DEBUG

WARNING:

The = symbol is required between --verbosity and its argument, but not when using the short form of -v:

semantic-release changelog -v DEBUG

See #227.

semantic_release

semantic_release package

Semantic Release
semantic_release.setup_hook(argv: list)

A hook to be used in setup.py to enable python setup.py publish.
Parameters

argv -- sys.argv

Subpackages

semantic_release.changelog package

semantic_release.changelog.markdown_changelog(owner: str, repo_name: str,
version: str, changelog: dict, header: bool = False, previous_version: str
= None) -> str

Generate a markdown version of the changelog.
Parameters

	•		owner -- The repo owner.
	•		repo_name -- The repo name.
	•		version -- A string with the version number.
	•		previous_version -- A string with the last version number, to use for the comparison URL. If omitted, the URL will not be included.
	•		changelog -- A parsed changelog dict from generate_changelog.
	•		header -- A boolean that decides whether a version number header should be included.

Returns

The markdown formatted changelog.

Submodules

semantic_release.changelog.changelog module

semantic_release.changelog.changelog.add_pr_link(owner: str, repo_name:
str, message: str) -> str

GitHub release notes automagically link to the PR, but changelog markdown doesn't. Replace (#123) at the end of a message with a markdown link.

semantic_release.changelog.changelog.changelog_headers(owner: str,
repo_name: str, changelog: dict, changelog_sections: list, **kwargs) ->
Optional[str]
semantic_release.changelog.changelog.changelog_table(owner: str, repo_name:
str, changelog: dict, changelog_sections: list, **kwargs) -> str
semantic_release.changelog.changelog.get_changelog_sections(changelog:
dict, changelog_sections: list) -> Iterable[str]

Generator which yields each changelog section to be included

semantic_release.changelog.changelog.get_hash_link(owner: str, repo_name:
str, hash_: str) -> str

Generate the link for commit hash

semantic_release.changelog.compare module

semantic_release.changelog.compare.compare_url(version: str,
previous_version: Optional[str] = None, **kwargs) -> Optional[str]
semantic_release.changelog.compare.get_github_compare_url(from_version:
str, to_version: str) -> str

Get the GitHub comparison link between two version tags.
Parameters

	•		from_version -- The older version to compare.
	•		to_version -- The newer version to compare.

Returns

Link to view a comparison between the two versions.

semantic_release.history package

History
class semantic_release.history.PatternVersionDeclaration(path: str,
pattern: str)

Bases: semantic_release.history.VersionDeclaration

Represent a version number in a particular file.

The version number is identified by a regular expression. Methods are provided both the read the version number from the file, and to update the file with a new version number. Use the load_version_patterns() factory function to create the version patterns specified in the config files.
parse() -> Set[str]

Return the versions matching this pattern.

Because a pattern can match in multiple places, this method returns a set of matches. Generally, there should only be one element in this set (i.e. even if the version is specified in multiple places, it should be the same version in each place), but it falls on the caller to check for this condition.

replace(new_version: str)

Update the versions matching this pattern.

This method reads the underlying file, replaces each occurrence of the matched pattern, then writes the updated file.
Parameters

new_version -- The new version number as a string

class semantic_release.history.TomlVersionDeclaration(path, key)

Bases: semantic_release.history.VersionDeclaration
parse() -> Set[str]

Return the versions.

Because a source can match in multiple places, this method returns a set of matches. Generally, there should only be one element in this set (i.e. even if the version is specified in multiple places, it should be the same version in each place), but it falls on the caller to check for this condition.

replace(new_version: str) -> None

Update the versions.

This method reads the underlying file, replaces each occurrence of the matched pattern, then writes the updated file.
Parameters

new_version -- The new version number as a string

class semantic_release.history.VersionDeclaration(path: Union[str,
pathlib.Path])

Bases: abc.ABC
static from_pattern(config_str: str)

Instantiate a PatternVersionDeclaration from a string specifying a path and a regular expression matching the version number.

static from_toml(config_str: str)

Instantiate a TomlVersionDeclaration from a string specifying a path and a key matching the version number.

static from_variable(config_str: str)

Instantiate a PatternVersionDeclaration from a string specifying a path and a variable name.

abstract parse() -> Set[str]

Return the versions.

abstract replace(new_version: str)

Update the versions.

This method reads the underlying file, replaces each occurrence of the matched pattern, then writes the updated file.
Parameters

new_version -- The new version number as a string

semantic_release.history.get_commit_release_version_pattern()
semantic_release.history.get_current_release_version() -> str

Get current release version from tag or commit message (no going back in config file), depending on configuration. This will return the current release version (NOT prerelease), instead of just the current version
Returns

A string with the current version number

semantic_release.history.get_current_release_version_by_commits() -> str

Return the current release version (NOT prerelease) version.
Returns

A string with the current version number.

semantic_release.history.get_current_release_version_by_tag() -> str

Find the current version of the package in the current working directory using git tags.
Returns

A string with the version number or 0.0.0 on failure.

semantic_release.history.get_current_version() -> str

Get current version from tag or version variable, depending on configuration. This can be either a release or prerelease version
Returns

A string with the current version number

semantic_release.history.get_current_version_by_config_file() -> str

Get current version from the version variable defined in the configuration.
Returns

A string with the current version number

Raises

ImproperConfigurationError -- if either no versions are found, or

multiple versions are found.

semantic_release.history.get_current_version_by_tag() -> str

Find the current version of the package in the current working directory using git tags.
Returns

A string with the version number or 0.0.0 on failure.

semantic_release.history.get_new_version(current_version: str,
current_release_version: str, level_bump: str, prerelease: bool = False,
prerelease_patch: bool = True) -> str

Calculate the next version based on the given bump level with semver.
Parameters

	•		current_version -- The version the package has now.
	•		level_bump -- The level of the version number that should be bumped. Should be 'major', 'minor' or 'patch'.
	•		prerelease -- Should the version bump be marked as a prerelease

Returns

A string with the next version number.

semantic_release.history.get_pattern_with_commit_subject(pattern)
semantic_release.history.get_prerelease_pattern()
semantic_release.history.get_previous_release_version(version: str) ->
Optional[str]

Return the version prior to the given version.
Parameters

version -- A string with the version number.

Returns

A string with the previous version number.

semantic_release.history.get_previous_version(version: str) ->
Optional[str]

Return the version prior to the given version.
Parameters

version -- A string with the version number.

Returns

A string with the previous version number.

semantic_release.history.get_release_version_pattern()
semantic_release.history.get_version_pattern()
semantic_release.history.load_version_declarations() -> List[-
semantic_release.history.VersionDeclaration]

Create the VersionDeclaration objects specified by the config file.

semantic_release.history.set_new_version(new_version: str) -> bool

Update the version number in each configured location.
Parameters

new_version -- The new version number as a string.

Returns

True if it succeeded.

Submodules

semantic_release.history.logs module

Logs
semantic_release.history.logs.evaluate_version_bump(current_version: str,
force: str = None) -> Optional[str]

Read git log since the last release to decide if we should make a major, minor or patch release.
Parameters

	•		current_version -- A string with the current version number.
	•		force -- A string with the bump level that should be forced.

Returns

A string with either major, minor or patch if there should be a release. If no release is necessary, None will be returned.

semantic_release.history.logs.generate_changelog(from_version:
Optional[str], to_version: Optional[str] = None) -> dict

Parse a changelog dictionary for the given version.
Parameters

	•		from_version -- The version before where the changelog starts. The changelog will be generated from the commit after this one.
	•		to_version -- The last version included in the changelog.

Returns

A dict with changelog sections and commits

semantic_release.history.parser_angular module

Angular commit style parser

https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines
semantic_release.history.parser_angular.parse_commit_message(message: str)
-> semantic_release.history.parser_helpers.ParsedCommit

Parse a commit message according to the angular commit guidelines specification.
Parameters

message -- A string of a commit message.

Returns

A tuple of (level to bump, type of change, scope of change, a tuple with descriptions)

Raises

UnknownCommitMessageStyleError -- if regular expression matching fails

semantic_release.history.parser_emoji module

Commit parser which looks for emojis to determine the type of commit
semantic_release.history.parser_emoji.parse_commit_message(message: str) ->
semantic_release.history.parser_helpers.ParsedCommit

Parse a commit using an emoji in the subject line.

When multiple emojis are encountered, the one with the highest bump level is used. If there are multiple emojis on the same level, the we use the one listed earliest in the configuration.

If the message does not contain any known emojis, then the level to bump will be 0 and the type of change "Other". This parser never raises UnknownCommitMessageStyleError.

Emojis are not removed from the description, and will appear alongside the commit subject in the changelog.
Parameters

message -- A string of a commit message.

Returns

A tuple of (level to bump, type of change, scope of change, a tuple with descriptions)

semantic_release.history.parser_helpers module

Commit parser helpers
class semantic_release.history.parser_helpers.ParsedCommit(bump, type,
scope, descriptions, breaking_descriptions)

Bases: tuple
breaking_descriptions

Alias for field number 4

bump

Alias for field number 0

descriptions

Alias for field number 3

	scope		Alias for field number 2
	type		Alias for field number 1

semantic_release.history.parser_helpers.parse_paragraphs(text: str) ->
List[str]

This will take a text block and return a tuple containing each paragraph with single line breaks collapsed into spaces.
Parameters

text -- The text string to be divided.

Returns

A tuple of paragraphs.

semantic_release.history.parser_scipy module

Parses commit messages using scipy tags of the form:

<body>

The elements <tag>, <scope> and <body> are optional. If no tag is present, the commit will be added to the changelog section "None" and no version increment will be performed.

While <scope> is supported here it isn't actually part of the scipy style. If it is missing, parentheses around it are too. The commit should then be of the form:

<body>

Supported Tags:

API, DEP, ENH, REV, BUG, MAINT, BENCH, BLD,
DEV, DOC, STY, TST, REL, FEAT, TEST

Supported Changelog Sections:

breaking, feature, fix, Other, None

class semantic_release.history.parser_scipy.Breaking(tag, section)

Bases: semantic_release.history.parser_scipy.ChangeType

class semantic_release.history.parser_scipy.ChangeType(tag, section)

Bases: object
make_breaking()

class semantic_release.history.parser_scipy.Compatible(tag, section)

Bases: semantic_release.history.parser_scipy.ChangeType

class semantic_release.history.parser_scipy.Ignore(tag, section)

Bases: semantic_release.history.parser_scipy.ChangeType

class semantic_release.history.parser_scipy.Patch(tag, section)

Bases: semantic_release.history.parser_scipy.ChangeType

semantic_release.history.parser_scipy.parse_commit_message(message: str) ->
semantic_release.history.parser_helpers.ParsedCommit

Parse a scipy-style commit message
Parameters

message -- A string of a commit message.

Returns

A tuple of (level to bump, type of change, scope of change, a tuple

with descriptions) :raises UnknownCommitMessageStyleError: if regular expression matching fails

semantic_release.history.parser_tag module

Legacy commit parser from Python Semantic Release 1.0
semantic_release.history.parser_tag.parse_commit_message(message: str) ->
semantic_release.history.parser_helpers.ParsedCommit

Parse a commit message according to the 1.0 version of python-semantic-release.

It expects a tag of some sort in the commit message and will use the rest of the first line as changelog content.
Parameters

message -- A string of a commit message.

Raises

UnknownCommitMessageStyleError -- If it does not recognise the commit style

Returns

A tuple of (level to bump, type of change, scope of change, a tuple with descriptions)

Submodules

semantic_release.ci_checks module

CI Checks
semantic_release.ci_checks.bitbucket(*args, **kwargs)
semantic_release.ci_checks.check(branch: str = 'master')

Detects the current CI environment, if any, and performs necessary environment checks.
Parameters

branch -- The branch that should be the current branch.

semantic_release.ci_checks.checker(func: Callable) -> Callable

A decorator that will convert AssertionErrors into CiVerificationError.
Parameters

func -- A function that will raise AssertionError

Returns

The given function wrapped to raise a CiVerificationError on AssertionError

semantic_release.ci_checks.circle(*args, **kwargs)
semantic_release.ci_checks.frigg(*args, **kwargs)
semantic_release.ci_checks.gitlab(*args, **kwargs)
semantic_release.ci_checks.jenkins(*args, **kwargs)
semantic_release.ci_checks.semaphore(*args, **kwargs)
semantic_release.ci_checks.travis(*args, **kwargs)

semantic_release.cli module

CLI
semantic_release.cli.bump_version(new_version, level_bump)

Set the version to the given new_version.

Edit in the source code, commit and create a git tag.

semantic_release.cli.changelog(*, unreleased=False, noop=False, post=False,
prerelease=False, **kwargs)

Generate the changelog since the last release.
Raises

ImproperConfigurationError -- if there is no current version

semantic_release.cli.common_options(func)

Decorator that adds all the options in COMMON_OPTIONS

semantic_release.cli.entry()
semantic_release.cli.filter_output_for_secrets(message)

Remove secrets from cli output.

semantic_release.cli.print_version(*, current=False, force_level=None,
prerelease=False, prerelease_patch=True, **kwargs)

Print the current or new version to standard output.

semantic_release.cli.publish(retry: bool = False, noop: bool = False,
prerelease: bool = False, prerelease_patch=True, **kwargs)

Run the version task, then push to git and upload to an artifact repository / GitHub Releases.

semantic_release.cli.should_bump_version(*, current_version,
current_release_version, new_version, prerelease, retry=False, noop=False)
semantic_release.cli.version(*, retry=False, noop=False, force_level=None,
prerelease=False, prerelease_patch=True, **kwargs)

Detect the new version according to git log and semver.

Write the new version number and commit it, unless the noop option is True.

semantic_release.dist module

Build and manage distributions
semantic_release.dist.build_dists()
semantic_release.dist.remove_dists(path: str)
semantic_release.dist.should_build()
semantic_release.dist.should_remove_dist()