semantic_release package¶
Python Semantic Release
- exception semantic_release.CommitParseError[source]¶
Bases:
SemanticReleaseBaseError
Raised when a commit cannot be parsed by a commit parser. Custom commit parsers should also raise this Exception
- class semantic_release.CommitParser(options: _OPTS | None = None)[source]¶
Bases:
ABC
,Generic
[_TT
,_OPTS
]Abstract base class for all commit parsers. Custom commit parsers should inherit from this class.
A class-level
parser_options
attribute should be set to a subclass ofBaseParserOptions
; this will be used to provide the default options to the parser. Note that a nested class can be used directly, if preferred:>>> class MyParser(CommitParser): @dataclass class parser_options(ParserOptions): allowed_types: Tuple[str] = ("feat", "fix", "docs") major_types: Tuple[str] = ("breaking",) minor_types: Tuple[str] = ("fix", "patch") ... def __init__(self, options: parser_options) -> None: ...
- parser_options¶
alias of
ParserOptions
- exception semantic_release.InvalidConfiguration[source]¶
Bases:
SemanticReleaseBaseError
Raised when configuration is deemed invalid
- exception semantic_release.InvalidVersion[source]¶
Bases:
ValueError
,SemanticReleaseBaseError
Raised when Version.parse attempts to parse a string containing an invalid version.
- class semantic_release.LevelBump(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
Bases:
IntEnum
IntEnum representing valid types of bumps for a version. We use an IntEnum to enable ordering of levels.
- MAJOR = 4¶
- MINOR = 3¶
- NO_RELEASE = 0¶
- PATCH = 2¶
- PRERELEASE_REVISION = 1¶
- class semantic_release.ParseError(commit, error)[source]¶
Bases:
NamedTuple
- commit: Commit¶
Alias for field number 0
- error: str¶
Alias for field number 1
- property hexsha: str¶
- property message: str¶
- property short_hash: str¶
- class semantic_release.ParsedCommit(bump, type, scope, descriptions, breaking_descriptions, commit)[source]¶
Bases:
NamedTuple
- breaking_descriptions: list[str]¶
Alias for field number 4
- commit: Commit¶
Alias for field number 5
- descriptions: list[str]¶
Alias for field number 3
- property hexsha: str¶
- property message: str¶
- scope: str¶
Alias for field number 2
- property short_hash: str¶
- type: str¶
Alias for field number 1
- class semantic_release.ParserOptions(**_: Any)[source]¶
Bases:
dict
ParserOptions should accept the keyword arguments they are interested in from configuration and process them as desired, ultimately creating attributes on an instance which can be accessed by the corresponding commit parser.
For example: >>> class MyParserOptions(ParserOptions): … def __init__(self, message_prefix: str) -> None: … self.prefix = message_prefix * 2
>>> class MyCommitParser(AbstractCommitParser): ... parser_options = MyParserOptions ... ... def parse(self, Commit): ... print(self.options.prefix) ... ...
Any defaults that need to be set should also be done in this class too. Invalid options should be signalled by raising an
InvalidOptionsException
within the__init__
method of the options class.A dataclass is also well suited to this; if type-checking of input is desired, a
pydantic.dataclasses.dataclass
works well and is used internally by python-semantic-release. Parser options are not validated in the configuration and passed directly to the appropriate class to handle.
- exception semantic_release.SemanticReleaseBaseError[source]¶
Bases:
Exception
Base Exception from which all other custom Exceptions defined in semantic_release inherit
- class semantic_release.Version(major: int, minor: int, patch: int, *, prerelease_token: str = 'rc', prerelease_revision: int | None = None, build_metadata: str = '', tag_format: str = 'v{version}')[source]¶
Bases:
object
- bump(level: LevelBump) Version [source]¶
Return a new Version instance according to the level specified to bump. Note this will intentionally drop the build metadata - that should be added elsewhere for the specific build producing this version.
- property is_prerelease: bool¶
- classmethod parse(version_str: str, tag_format: str = 'v{version}', prerelease_token: str = 'rc') Version [source]¶
Parse version string to a Version instance. Inspired by semver.version:VersionInfo.parse, this implementation doesn’t allow optional minor and patch versions.
- Parameters:
prerelease_token – will be ignored if the version string is a prerelease, the parsed token from version_str will be used instead.
- property tag_format: str¶
- class semantic_release.VersionTranslator(tag_format: str = 'v{version}', prerelease_token: str = 'rc')[source]¶
Bases:
object
Class to handle translation from Git tags into their corresponding Version instances.
- from_string(version_str: str) Version [source]¶
Return a Version instance from a string. Delegates directly to Version.parse, using the translator’s own stored values for tag_format and prerelease
- from_tag(tag: str) Version | None [source]¶
Return a Version instance from a Git tag, if tag_format matches the format which would have generated the tag from a version. Otherwise return None. For example, a tag of ‘v1.2.3’ should be matched if tag_format = ‘v{version}, but not if tag_format = staging–v{version}.
- semantic_release.next_version(repo: Repo, translator: VersionTranslator, commit_parser: CommitParser[ParseResult, ParserOptions], prerelease: bool = False, major_on_zero: bool = True, allow_zero_version: bool = True) Version [source]¶
Evaluate the history within repo, and based on the tags and commits in the repo history, identify the next semantic version that should be applied to a release
- semantic_release.tags_and_versions(tags: Iterable[Tag], translator: VersionTranslator) list[tuple[Tag, Version]] [source]¶
Return a list of 2-tuples, where each element is a tuple (tag, version) from the tags in the Git repo and their corresponding Version according to Version.from_tag. The returned list is sorted according to semver ordering rules.
Tags which are not matched by translator are ignored.
Subpackages¶
- semantic_release.changelog package
- semantic_release.cli package
- semantic_release.commit_parser package
- semantic_release.hvcs package
Bitbucket
Bitbucket.DEFAULT_API_PATH_CLOUD
Bitbucket.DEFAULT_API_PATH_ONPREM
Bitbucket.DEFAULT_API_SUBDOMAIN_PREFIX
Bitbucket.DEFAULT_API_URL_CLOUD
Bitbucket.DEFAULT_DOMAIN
Bitbucket.DEFAULT_ENV_TOKEN_NAME
Bitbucket.commit_hash_url()
Bitbucket.compare_url()
Bitbucket.create_or_update_release()
Bitbucket.create_release()
Bitbucket.get_changelog_context_filters()
Bitbucket.pull_request_url()
Bitbucket.remote_url()
Bitbucket.upload_dists()
Gitea
Gitea.DEFAULT_API_PATH
Gitea.DEFAULT_DOMAIN
Gitea.DEFAULT_ENV_TOKEN_NAME
Gitea.asset_upload_url()
Gitea.commit_hash_url()
Gitea.create_or_update_release()
Gitea.create_release()
Gitea.edit_release_notes()
Gitea.get_changelog_context_filters()
Gitea.get_release_id_by_tag()
Gitea.issue_url()
Gitea.pull_request_url()
Gitea.remote_url()
Gitea.upload_dists()
Gitea.upload_release_asset()
Github
Github.DEFAULT_API_DOMAIN
Github.DEFAULT_API_PATH_CLOUD
Github.DEFAULT_API_PATH_ONPREM
Github.DEFAULT_API_SUBDOMAIN_PREFIX
Github.DEFAULT_API_URL_CLOUD
Github.DEFAULT_DOMAIN
Github.DEFAULT_ENV_TOKEN_NAME
Github.asset_upload_url()
Github.commit_hash_url()
Github.compare_url()
Github.create_or_update_release()
Github.create_release()
Github.edit_release_notes()
Github.get_changelog_context_filters()
Github.get_release_id_by_tag()
Github.issue_url()
Github.pull_request_url()
Github.remote_url()
Github.upload_dists()
Github.upload_release_asset()
Gitlab
Gitlab.DEFAULT_DOMAIN
Gitlab.DEFAULT_ENV_TOKEN_NAME
Gitlab.commit_hash_url()
Gitlab.compare_url()
Gitlab.create_or_update_release()
Gitlab.create_release()
Gitlab.edit_release_notes()
Gitlab.get_changelog_context_filters()
Gitlab.get_release_by_tag()
Gitlab.issue_url()
Gitlab.merge_request_url()
Gitlab.project
Gitlab.pull_request_url()
Gitlab.remote_url()
Gitlab.upload_dists()
HvcsBase
RemoteHvcsBase
TokenAuth
- Submodules
- semantic_release.version package
Submodules¶
- semantic_release.const module
- semantic_release.enums module
- semantic_release.errors module
AssetUploadError
BuildDistributionsError
CommitParseError
DetachedHeadGitError
GitAddError
GitCommitEmptyIndexError
GitCommitError
GitPushError
GitTagError
IncompleteReleaseError
InvalidConfiguration
InvalidVersion
MissingGitRemote
MissingMergeBaseError
NotAReleaseBranch
ParserLoadError
SemanticReleaseBaseError
UnexpectedResponse
- semantic_release.gitproject module
- semantic_release.helpers module