mafw.devtools.release.versioning

Version parsing, classification, and bumping utilities for MAFw releases.

This module contains the business logic for version string parsing, classification, validation, and the Hatch-based version bumping workflow.

Module Attributes

`VALID_HATCH_SEGMENTS`	Allowed Hatch version segments supported by this script.
`VERSION_PATTERN`	Regular expression used to parse local version strings (stable/alpha/beta/rc).
`STABLE_TAG_PATTERN`	Regular expression used to identify stable git tags in the form `vX.Y.Z`.
`ABOUT_FILE`	Path to the version source file managed by `hatch version`.
`NOTICE_FILE`	Path to the notice file containing the public project version.
`NOTICE_VERSION_PATTERN`	Pattern used to update the version block in `NOTICE.txt`.
`DOC_TARGET_VERSION_PATTERN`	Pattern used to validate documentation target version strings.
`VersionKind`	Supported release kinds used to drive changelog and release-note behavior.

Functions

`bump_version`(segment, *, dry_run)	Compute or execute the version bump depending on dry-run mode.
`classify_version`(version)	Classify a version string into stable/rc/alpha/beta.
`compute_doc_target_version`(version, segments)	Determine the new documentation target version for a release.
`next_minor_version`(version)	Compute the next `major.minor` target from a release version.
`normalize_hatch_segments`(segments)	Normalize the user-provided segment selector to a Hatch-compatible token list.
`parse_version`(version)	Parse a version string in the form `X.Y.Z` or with a pre-release suffix.
`read_current_version`()	Read the project version using `hatch version`.
`update_doc_target_version`(version, dry_run)	Update the documentation target version in `src/mafw/__about__.py`.
`update_notice_version`(version, dry_run)	Update the version in `NOTICE.txt` to match the release version.
`validate_doc_target_version`(version)	Validate a documentation target version string.

Classes

DocTargetVersionPrompt(*args[, min_version])

Prompt that validates documentation target versions in major.minor form.

class mafw.devtools.release.versioning.DocTargetVersionPrompt(*args: Any, min_version: str | None = None, **kwargs: Any)[source]

Bases: Prompt

Prompt that validates documentation target versions in major.minor form.

Initialize the prompt with an optional minimum allowed version.

Parameters:: min_version (str | None) – Lowest allowed documentation target version in major.minor form.

process_response(value: str) → str[source]

Validate and normalize the documentation target version entered by the user.

Parameters:: value (str) – Raw user input.
Returns:: Normalized version string.
Return type:: str
Raises:: InvalidResponse – If the value does not match major.minor or is below the minimum.

validate_error_message = 'Please enter a version in major.minor form, for example 2.4.': Message shown when the entered documentation target version is invalid.

mafw.devtools.release.versioning._parse_major_minor(version: str) → tuple[int, int][source]

Parse a version string in major.minor form.

Parameters:: version (str) – Version string to parse.
Returns:: Parsed major and minor components.
Return type:: tuple[int, int]
Raises:: DevtoolsError – If the version format is invalid.

mafw.devtools.release.versioning.bump_version(segment: str, *, dry_run: bool) → str[source]

Compute or execute the version bump depending on dry-run mode.

Hatch is used as single source of truth for the resolved target version. In dry-run mode, the __about__.py file is temporarily rewritten by Hatch and restored afterwards so the git worktree remains unchanged.

Parameters:

segment (str) – Hatch selector segments (comma-separated).
dry_run (bool) – Whether command execution is disabled.

Returns:

New version string.

Return type:

str

mafw.devtools.release.versioning.classify_version(version: str) → Literal['stable', 'rc', 'alpha', 'beta'][source]

Classify a version string into stable/rc/alpha/beta.

Parameters:: version (str) – Version string to classify.
Returns:: Classified version kind.
Return type:: str
Raises:: DevtoolsError – If the version cannot be parsed.

mafw.devtools.release.versioning.compute_doc_target_version(version: str, segments: str, override: str | None = None) → str[source]

Determine the new documentation target version for a release.

Parameters:

version (str) – Bumped release version.
segments (str) – Normalized Hatch selector used for the release.
override (str | None) – Optional explicit documentation target override.

Returns:

Documentation target version in major.minor form.

Return type:

str

mafw.devtools.release.versioning.next_minor_version(version: str) → str[source]

Compute the next major.minor target from a release version.

Parameters:: version (str) – Release version in major.minor.micro form.
Returns:: Next documentation target version.
Return type:: str

mafw.devtools.release.versioning.normalize_hatch_segments(segments: str) → str[source]

Normalize the user-provided segment selector to a Hatch-compatible token list.

The selector supports comma-separated segments and follows Hatch semantics. Examples:

minor,rc: bump minor and create/reset an RC suffix.
rc: increment the release-candidate counter only.
alpha / beta: create alpha/beta pre-release suffix.
release: remove any pre-release suffix (stable release).

Parameters:: segments (str) – Raw selector as passed on the command line.
Returns:: Normalized Hatch selector (comma-separated, lowercase, no whitespace).
Return type:: str
Raises:: DevtoolsError – If the selector is empty or contains unsupported segments.

mafw.devtools.release.versioning.parse_version(version: str) → tuple[int, int, int, int | None][source]

Parse a version string in the form X.Y.Z or with a pre-release suffix.

Supported suffixes follow Hatch/PEP 440 conventions:

Release candidates: X.Y.ZrcN
Alpha releases: X.Y.ZaN
Beta releases: X.Y.ZbN

Parameters:: version (str) – Version string to parse.
Returns:: Parsed major, minor, micro, and optional pre-release index.
Return type:: tuple[int, int, int, int | None]
Raises:: DevtoolsError – If the version format is unsupported.

mafw.devtools.release.versioning.read_current_version() → str[source]

Read the project version using hatch version.

Returns:: Current project version string.
Return type:: str
Raises:: DevtoolsError – If the version cannot be extracted.

mafw.devtools.release.versioning.update_doc_target_version(version: str, dry_run: bool) → None[source]

Update the documentation target version in src/mafw/__about__.py.

Parameters:

version (str) – Target documentation version in major.minor form.
dry_run (bool) – Whether filesystem changes are disabled.

mafw.devtools.release.versioning.update_notice_version(version: str, dry_run: bool) → None[source]

Update the version in NOTICE.txt to match the release version.

Parameters:

version (str) – Target release version.
dry_run (bool) – Whether filesystem changes are disabled.

Raises:

DevtoolsError – If NOTICE.txt is missing or has unexpected format.

mafw.devtools.release.versioning.validate_doc_target_version(version: str) → str[source]

Validate a documentation target version string.

Parameters:: version (str) – Version string to validate.
Returns:: Normalized version string.
Return type:: str
Raises:: DevtoolsError – If the version format is invalid.

mafw.devtools.release.versioning.ABOUT_FILE = PosixPath('src/mafw/__about__.py'): Path to the version source file managed by hatch version.

mafw.devtools.release.versioning.DOC_TARGET_VERSION_PATTERN = re.compile('^\\d+\\.\\d+$'): Pattern used to validate documentation target version strings.

mafw.devtools.release.versioning.NOTICE_FILE = PosixPath('NOTICE.txt'): Path to the notice file containing the public project version.

mafw.devtools.release.versioning.NOTICE_VERSION_PATTERN = re.compile('MAFw - Modular Analysis Framework\\n\\nversion:\\s*V[0-9]+\\.[0-9]+\\.[0-9]+(?:[-a-zA-Z0-9\\.\\-_]+)?', re.MULTILINE): Pattern used to update the version block in NOTICE.txt.

mafw.devtools.release.versioning.STABLE_TAG_PATTERN = re.compile('^v(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<micro>\\d+)$'): Regular expression used to identify stable git tags in the form vX.Y.Z.

mafw.devtools.release.versioning.VALID_HATCH_SEGMENTS: Final[tuple[str, ...]] = ('major', 'minor', 'micro', 'rc', 'alpha', 'beta', 'release'): Allowed Hatch version segments supported by this script.

mafw.devtools.release.versioning.VERSION_PATTERN = re.compile('^(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<micro>\\d+)(?:(?P<suffix>rc|a|b)(?P<suffix_num>\\d+))?$'): Regular expression used to parse local version strings (stable/alpha/beta/rc).

mafw.devtools.release.versioning.VersionKind

Supported release kinds used to drive changelog and release-note behavior.

alias of Literal[‘stable’, ‘rc’, ‘alpha’, ‘beta’]