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 of BaseParserOptions; 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:
            ...
get_default_options() → _OPTS[source]
abstract parse(commit: Commit) → _TT[source]
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
classmethod from_string(val: str) → LevelBump[source]

Get the level from string representation. For backwards-compatibility, dashes are replaced with underscores so that: >>> LevelBump.from_string(“no-release”) == LevelBump.NO_RELEASE Equally, >>> LevelBump.from_string(“minor”) == LevelBump.MINOR

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
raise_error() → NoReturn[source]
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

bump: LevelBump

Alias for field number 0

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

as_semver_tag() → str[source]
as_tag() → str[source]
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.

finalize_version() → Version[source]
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
to_prerelease(token: str | None = None, revision: int | None = None) → Version[source]
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}.

str_to_tag(version_str: str) → str[source]

Formats a version string into a tag name

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

Submodules