Provided by: python3-semantic-release_7.32.2-1_all 
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:
<!--next-version-placeholder-->
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:
<tag>(<scope>): <subject>
<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:
<tag>: <subject>
<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:
┌──────────┬──────────────────────────────────┐
│Variable │ Contents │
├──────────┼──────────────────────────────────┤
│{version} │ The new version number in the │
│ │ format X.Y.Z. │
└──────────┴──────────────────────────────────┘
Default: {version}
commit_message
Git commit message body. Accepts the following variables as format fields:
┌──────────┬──────────────────────────────────┐
│Variable │ Contents │
├──────────┼──────────────────────────────────┤
│{version} │ The new version number in the │
│ │ format X.Y.Z. │
└──────────┴──────────────────────────────────┘
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:
┌───────────────────┬──────────────────────────────────┐
│changelog │ A dictionary with section names │
│ │ such as feature as keys, and the │
│ │ values are lists of (SHA, │
│ │ message) tuples. There is a │
│ │ special section named breaking │
│ │ for breaking changes, where the │
│ │ same commit can appear more than │
│ │ once with a different message. │
├───────────────────┼──────────────────────────────────┤
│changelog_sections │ A list of sections from │
│ │ changelog which the user has set │
│ │ to be displayed. │
├───────────────────┼──────────────────────────────────┤
│version │ The current version number in │
│ │ the format X.X.X, or the new │
│ │ version number when publishing. │
├───────────────────┼──────────────────────────────────┤
│previous_version │ The previous version number. │
│ │ Only present when publishing, │
│ │ None otherwise. │
└───────────────────┴──────────────────────────────────┘
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: <!--next-version-placeholder-->.
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:
┌──────────┬──────────────────────────────────┐
│Variable │ Contents │
├──────────┼──────────────────────────────────┤
│{version} │ The new version number in the │
│ │ format X.Y.Z. │
└──────────┴──────────────────────────────────┘
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.
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.
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:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
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.
1. Create a virtualenv:
virtualenv semantic_release -p `which python3`
2. 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>
4. 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.
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.
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:
<tag>(<scope>): <subject>
<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:
<tag>: <subject>
<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
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()
semantic_release.errors module
Custom Errors
exception semantic_release.errors.CiVerificationError
Bases: semantic_release.errors.SemanticReleaseBaseError
exception semantic_release.errors.GitError
Bases: semantic_release.errors.SemanticReleaseBaseError
exception semantic_release.errors.HvcsRepoParseError
Bases: semantic_release.errors.SemanticReleaseBaseError
exception semantic_release.errors.ImproperConfigurationError
Bases: semantic_release.errors.SemanticReleaseBaseError
exception semantic_release.errors.SemanticReleaseBaseError
Bases: Exception
exception semantic_release.errors.UnknownCommitMessageStyleError
Bases: semantic_release.errors.SemanticReleaseBaseError
semantic_release.helpers module
class semantic_release.helpers.LoggedFunction(logger)
Bases: object
Decorator which adds debug logging to a function.
The input arguments are logged before the function is called, and the return value
is logged once it has completed.
Parameters
logger -- Logger to send output to.
semantic_release.helpers.build_requests_session(raise_for_status=True, retry: Union[bool,
int, urllib3.util.retry.Retry] = True) -> requests.sessions.Session
Create a requests session. :param raise_for_status: If True, a hook to invoke
raise_for_status be installed :param retry: If true, it will use default Retry
configuration. if an integer, it will use default Retry configuration with given
integer as total retry count. if Retry instance, it will use this instance.
:return: configured requests Session
semantic_release.helpers.format_arg(value)
semantic_release.hvcs module
HVCS
class semantic_release.hvcs.Base
Bases: object
static api_url() -> str
static check_build_status(owner: str, repo: str, ref: str) -> bool
static domain() -> str
classmethod post_release_changelog(owner: str, repo: str, version: str, changelog:
str) -> bool
static token() -> Optional[str]
classmethod upload_dists(owner: str, repo: str, version: str, path: str) -> bool
class semantic_release.hvcs.Gitea
Bases: semantic_release.hvcs.Base
Gitea helper class
DEFAULT_API_PATH = '/api/v1'
DEFAULT_DOMAIN = 'gitea.com'
static api_url() -> str
Gitea api_url property
Returns
The Gitea API URL
static auth() -> Optional[semantic_release.hvcs.TokenAuth]
Gitea token property
Returns
The Gitea token environment variable (GITEA_TOKEN) value
static check_build_status(owner: str, repo: str, ref: str) -> bool
Check build status
https://gitea.com/api/swagger#/repository/repoCreateStatus
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• ref -- The sha1 hash of the commit ref
Returns
Was the build status success?
classmethod create_release(owner: str, repo: str, tag: str, changelog: str) -> bool
Create a new release
https://gitea.com/api/swagger#/repository/repoCreateRelease
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• tag -- Tag to create release for
• changelog -- The release notes for this version
Returns
Whether the request succeeded
static domain() -> str
Gitea domain property
Returns
The Gitea domain
classmethod edit_release(owner: str, repo: str, id: int, changelog: str) -> bool
Edit a release with updated change notes
https://gitea.com/api/swagger#/repository/repoEditRelease
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• id -- ID of release to update
• changelog -- The release notes for this version
Returns
Whether the request succeeded
classmethod get_release(owner: str, repo: str, tag: str) -> Optional[int]
Get a release by its tag name
https://gitea.com/api/swagger#/repository/repoGetReleaseByTag
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• tag -- Tag to get release for
Returns
ID of found release
classmethod post_release_changelog(owner: str, repo: str, version: str, changelog:
str) -> bool
Post release changelog
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• version -- The version number
• changelog -- The release notes for this version
Returns
The status of the request
static session(raise_for_status=True, retry: Union[urllib3.util.retry.Retry, bool,
int] = True) -> requests.sessions.Session
static token() -> Optional[str]
Gitea token property
Returns
The Gitea token environment variable (GITEA_TOKEN) value
classmethod upload_asset(owner: str, repo: str, release_id: int, file: str, label:
str = None) -> bool
Upload an asset to an existing release
https://gitea.com/api/swagger#/repository/repoCreateReleaseAttachment
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• release_id -- ID of the release to upload to
• file -- Path of the file to upload
• label -- Custom label for this file
Returns
The status of the request
classmethod upload_dists(owner: str, repo: str, version: str, path: str) -> bool
Upload distributions to a release
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• version -- Version to upload for
• path -- Path to the dist directory
Returns
The status of the request
class semantic_release.hvcs.Github
Bases: semantic_release.hvcs.Base
Github helper class
DEFAULT_DOMAIN = 'github.com'
static api_url() -> str
Github api_url property
Returns
The Github API URL
static auth() -> Optional[semantic_release.hvcs.TokenAuth]
Github token property
Returns
The Github token environment variable (GH_TOKEN) value
static check_build_status(owner: str, repo: str, ref: str) -> bool
Check build status
https://docs.github.com/rest/reference/repos#get-the-combined-status-for-a-specific-reference
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• ref -- The sha1 hash of the commit ref
Returns
Was the build status success?
classmethod create_release(owner: str, repo: str, tag: str, changelog: str) -> bool
Create a new release
https://docs.github.com/rest/reference/repos#create-a-release
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• tag -- Tag to create release for
• changelog -- The release notes for this version
Returns
Whether the request succeeded
static domain() -> str
Github domain property
Returns
The Github domain
classmethod edit_release(owner: str, repo: str, id: int, changelog: str) -> bool
Edit a release with updated change notes
https://docs.github.com/rest/reference/repos#update-a-release
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• id -- ID of release to update
• changelog -- The release notes for this version
Returns
Whether the request succeeded
classmethod get_asset_upload_url(owner: str, repo: str, release_id: str) ->
Optional[str]
Get the correct upload url for a release
https://docs.github.com/en/enterprise-server@3.5/rest/releases/releases#get-a-release
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• release_id -- ID of the release to upload to
Returns
URL found to upload for a release
classmethod get_release(owner: str, repo: str, tag: str) -> Optional[int]
Get a release by its tag name
https://docs.github.com/rest/reference/repos#get-a-release-by-tag-name
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• tag -- Tag to get release for
Returns
ID of found release
classmethod post_release_changelog(owner: str, repo: str, version: str, changelog:
str) -> bool
Post release changelog
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• version -- The version number
• changelog -- The release notes for this version
Returns
The status of the request
static session(raise_for_status=True, retry: Union[urllib3.util.retry.Retry, bool,
int] = True) -> requests.sessions.Session
static token() -> Optional[str]
Github token property
Returns
The Github token environment variable (GH_TOKEN) value
classmethod upload_asset(owner: str, repo: str, release_id: int, file: str, label:
str = None) -> bool
Upload an asset to an existing release
https://docs.github.com/rest/reference/repos#upload-a-release-asset
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• release_id -- ID of the release to upload to
• file -- Path of the file to upload
• label -- Custom label for this file
Returns
The status of the request
classmethod upload_dists(owner: str, repo: str, version: str, path: str) -> bool
Upload distributions to a release
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• version -- Version to upload for
• path -- Path to the dist directory
Returns
The status of the request
class semantic_release.hvcs.Gitlab
Bases: semantic_release.hvcs.Base
Gitlab helper class
static api_url() -> str
Gitlab api_url property
Returns
The Gitlab instance API url
static check_build_status(owner: str, repo: str, ref: str) -> bool
Check last build status
Parameters
• owner -- The owner namespace of the repository. It includes all
groups and subgroups.
• repo -- The repository name
• ref -- The sha1 hash of the commit ref
Returns
the status of the pipeline (False if a job failed)
static domain() -> str
Gitlab domain property
Returns
The Gitlab instance domain
classmethod post_release_changelog(owner: str, repo: str, version: str, changelog:
str) -> bool
Post release changelog
Parameters
• owner -- The owner namespace of the repository
• repo -- The repository name
• version -- The version number
• changelog -- The release notes for this version
Returns
The status of the request
static token() -> Optional[str]
Gitlab token property
Returns
The Gitlab token environment variable (GL_TOKEN) value
class semantic_release.hvcs.TokenAuth(token)
Bases: requests.auth.AuthBase
requests Authentication for token based authorization
semantic_release.hvcs.check_build_status(owner: str, repository: str, ref: str) -> bool
Checks the build status of a commit on the api from your hosted version control
provider.
Parameters
• owner -- The owner of the repository
• repository -- The repository name
• ref -- Commit or branch reference
Returns
A boolean with the build status
semantic_release.hvcs.check_token() -> bool
Checks whether there exists a token or not.
Returns
A boolean telling if there is a token.
semantic_release.hvcs.get_domain() -> Optional[str]
Returns the domain for the current VCS
Returns
The domain in string form
semantic_release.hvcs.get_hvcs() -> semantic_release.hvcs.Base
Get HVCS helper class
Raises ImproperConfigurationError -- if the hvcs option provided is not valid
semantic_release.hvcs.get_token() -> Optional[str]
Returns the token for the current VCS
Returns
The token in string form
semantic_release.hvcs.post_changelog(owner: str, repository: str, version: str, changelog:
str) -> bool
Posts the changelog to the current hvcs release API
Parameters
• owner -- The owner of the repository
• repository -- The repository name
• version -- A string with the new version
• changelog -- A string with the changelog in correct format
Returns
a tuple with success status and payload from hvcs
semantic_release.hvcs.upload_to_release(owner: str, repository: str, version: str, path:
str) -> bool
Upload distributions to the current hvcs release API
Parameters
• owner -- The owner of the repository
• repository -- The repository name
• version -- A string with the version to upload for
• path -- Path to dist directory
Returns
Status of the request
semantic_release.pre_commit module
Run commands prior to the release commit
semantic_release.pre_commit.run_pre_commit()
semantic_release.pre_commit.should_run_pre_commit()
semantic_release.repository module
Helper for using Twine to upload to an artifact repository.
class semantic_release.repository.ArtifactRepo(dist_path: dataclasses.InitVar[Path],
repository_name: str = 'pypi', repository_url: Optional[str] = None, username:
Optional[str] = None, password: Optional[str] = None)
Bases: object
Object that manages the configuration and execution of upload using Twine.
This object needs only one shared argument to be instantiated.
dist_path: dataclasses.InitVar[Path]
dists: List[str]
password: Optional[str] = None
repository_name: str = 'pypi'
repository_url: Optional[str] = None
upload(noop: bool, verbose: bool, skip_existing: bool, **additional_kwargs) -> bool
Upload artifact to repository using Twine.
For known repositories (like PyPI), the web URLs of successfully uploaded
packages will be displayed.
Parameters
• noop -- Do not apply any changes..
• verbose -- Show verbose output for Twine.
• skip_existing -- Continue uploading files if one already exists.
(May not work, check your repository for support.)
Raises ImproperConfigurationError -- The upload failed due to a
configuration error.
:returns True if successful, False otherwise.
static upload_enabled() -> bool
Check if artifact repository upload is enabled
:returns True if upload is enabled, False otherwise.
username: Optional[str] = None
semantic_release.repository.get_env_var(name: str) -> Optional[str]
Resolve variable name from config and return matching environment variable
Parameters
name -- Variable name to retrieve from environment
:returns Value of environment variable or None if not set.
semantic_release.settings module
Helpers to read settings from setup.cfg or pyproject.toml
semantic_release.settings.current_changelog_components() -> List[Callable]
Get the currently-configured changelog components
Raises ImproperConfigurationError -- if ImportError or AttributeError is raised
Returns
List of component functions
semantic_release.settings.current_commit_parser() -> Callable
Get the currently-configured commit parser
Raises ImproperConfigurationError -- if ImportError or AttributeError is raised
Returns
Commit parser
semantic_release.settings.overload_configuration(func)
This decorator gets the content of the "define" array and edits "config" according
to the pairs of key/value.
semantic_release.vcs_helpers module
VCS Helpers
semantic_release.vcs_helpers.checkout(branch: str)
Check out the given branch in the local repository.
Parameters
branch -- The branch to checkout.
semantic_release.vcs_helpers.commit_new_version(version: str)
Commit the file containing the version number variable.
The commit message will be generated from the configured template.
Parameters
version -- Version number to be used in the commit message.
semantic_release.vcs_helpers.get_changed_files(repo: git.repo.base.Repo) -> List[str]
Get untracked / dirty files in the given git repo().
Parameters
repo -- Git repo to check.
Returns
A list of filenames.
semantic_release.vcs_helpers.get_commit_log(from_rev=None, to_rev=None)
Yield all commit messages from last to first.
semantic_release.vcs_helpers.get_current_head_hash() -> str
Get the commit hash of the current HEAD.
Returns
The commit hash.
semantic_release.vcs_helpers.get_formatted_commit(version: str) -> str
semantic_release.vcs_helpers.get_formatted_tag(version)
Get the version, formatted with tag_format config option
semantic_release.vcs_helpers.get_last_version(pattern, skip_tags=None) -> Optional[str]
Find the latest version using repo tags.
Returns
A string containing a version number.
semantic_release.vcs_helpers.get_repository_owner_and_name() -> Tuple[str, str]
Check the 'origin' remote to get the owner and name of the remote repository.
Returns
A tuple of the owner and name.
semantic_release.vcs_helpers.push_new_version(auth_token: str = None, owner: str = None,
name: str = None, branch: str = 'master', domain: str = 'github.com')
Run git push and git push --tags.
Parameters
• auth_token -- Authentication token used to push.
• owner -- Organisation or user that owns the repository.
• name -- Name of repository.
• branch -- Branch to push to
• server_url -- Name of the server. Will be used to identify a gitlab
instance.
Raises GitError -- if GitCommandError is raised
semantic_release.vcs_helpers.repo()
semantic_release.vcs_helpers.tag_new_version(version: str)
Create a new tag with the version number, prefixed with v by default.
Parameters
version -- The version number used in the tag as a string.
semantic_release.vcs_helpers.update_additional_files()
Add specified files to VCS, if they've changed.
semantic_release.vcs_helpers.update_changelog_file(version: str, content_to_add: str)
Update changelog file with changelog for the release.
Parameters
• version -- The release version number, as a string.
• content_to_add -- The release notes for the version.
AUTHOR
Rolf Erik Lekang
COPYRIGHT
2022, Rolf Erik Lekang