impl

This module provides a comprehensive system for working with semantic git branch names. Semantic branches follow a structured naming convention that helps indicate the purpose and type of work being done on a branch, enabling both developers and CI/CD systems to understand and process branches appropriately.

Semantic Git Branch Name Format

semantic git branch name format:

${semantic_name}-${optional_marker}/${description}/${more_slash_is_ok}

Sample valid semantic git branch name syntax:

main
feature
feature/add-this-feature
feature-123/description
release/1.2.3

Usage example:

import fixa.semantic_branch as sem_branch

_ = sem_branch.InvalidSemanticNameError
_ = sem_branch.SemanticBranchEnum
_ = is_valid_semantic_name
_ = ensure_is_valid_semantic_name
_ = sem_branch.is_certain_semantic_branch
_ = sem_branch.is_main_branch
_ = sem_branch.is_feature_branch
_ = sem_branch.is_build_branch
_ = sem_branch.is_doc_branch
_ = sem_branch.is_fix_branch
_ = sem_branch.is_release_branch
_ = sem_branch.is_cleanup_branch
_ = sem_branch.is_sandbox_branch
_ = sem_branch.is_develop_branch
_ = sem_branch.is_test_branch
_ = sem_branch.is_int_branch
_ = sem_branch.is_staging_branch
_ = sem_branch.is_qa_branch
_ = sem_branch.is_preprod_branch
_ = sem_branch.is_prod_branch
_ = sem_branch.is_blue_branch
_ = sem_branch.is_green_branch
_ = sem_branch.SemanticBranchRule

exception semantic_branch.impl.InvalidSemanticNameError

Exception raised when a semantic name doesn’t meet validation requirements.

semantic_branch.impl.is_valid_semantic_name(name: str) → bool

Check if a name is a valid semantic name.

A valid semantic name must:

1. Not be empty

2. Start with a lowercase letter (a-z)

3. Contain only lowercase letters and digits

Parameters:

name – The name to validate

Examples:

# Valid semantic names
assert is_valid_semantic_name("feature") is True
assert is_valid_semantic_name("feat") is True
assert is_valid_semantic_name("test123") is True
assert is_valid_semantic_name("build2") is True

# Invalid semantic names
assert is_valid_semantic_name("") is False  # Empty
assert is_valid_semantic_name("Feature") is False  # Uppercase
assert is_valid_semantic_name("123test") is False  # Starts with digit
assert is_valid_semantic_name("feature-123") is False  # Contains dash:return: True if the name is valid, False otherwise

semantic_branch.impl.ensure_is_valid_semantic_name(name: str) → str

Validate a semantic name and raise an exception if invalid.

This function performs the same validation as is_valid_semantic_name() but raises an InvalidSemanticNameError if the name is invalid, otherwise returns the name unchanged.

semantic_branch.impl.is_certain_semantic_branch(name: str, stubs: List[str]) → bool

Test if a branch name matches any of the provided semantic stubs.

This function extracts the semantic portion from a branch name by removing everything after the first occurrence of separators (-, _, @, +, /), then checks if it matches any of the provided semantic stubs.

The matching is case-insensitive and handles leading/trailing whitespace. All provided stubs must be valid semantic names (validated automatically).

Parameters:

• name – The git branch name to test

• stubs – List of valid semantic stub names to match against

Returns:

True if the branch name matches any stub, False otherwise

Raises:

InvalidSemanticNameError – If any stub in the list is invalid

Examples:

# Basic matching
assert is_certain_semantic_branch("feature", ["feat", "feature"]) is True
assert is_certain_semantic_branch("feat", ["feat", "feature"]) is True

# Case insensitive matching
assert is_certain_semantic_branch("FEATURE", ["feat", "feature"]) is True
assert is_certain_semantic_branch("Feat", ["feat", "feature"]) is True

# Separator handling
assert is_certain_semantic_branch("feature-123", ["feat", "feature"]) is True
assert is_certain_semantic_branch("feature/add-login", ["feat", "feature"]) is True
assert is_certain_semantic_branch("feature_test", ["feat", "feature"]) is True
assert is_certain_semantic_branch("feature@urgent", ["feat", "feature"]) is True
assert is_certain_semantic_branch("feature+new", ["feat", "feature"]) is True

# Combined separators (processed in order)
assert is_certain_semantic_branch("feature-123/description", ["feat", "feature"]) is True

# Whitespace handling
assert is_certain_semantic_branch(" feature ", ["feat", "feature"]) is True

# No match
assert is_certain_semantic_branch("main", ["feat", "feature"]) is False

# Invalid stub raises exception
try:
    is_certain_semantic_branch("feature", ["Feature"])  # Invalid: uppercase
except InvalidSemanticNameError:
    print("Invalid stub provided")

class semantic_branch.impl.SemanticStubEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of all supported semantic branch stub names.

This enum defines all the standard semantic stub names that can be used to identify different types of branches. Each stub is a short, lowercase string that represents a specific branch purpose or environment.

class semantic_branch.impl.SemanticBranch(name: str, stubs: list[str])

Data class representing a semantic branch type with its associated stub names.

This class encapsulates a semantic branch type by combining a canonical name with a list of stub names that can be used to identify branches of this type. It provides a convenient interface for testing whether a given branch name matches this semantic branch type.

Parameters:

• name – The canonical name of this semantic branch type

• stubs – List of semantic stub names that identify this branch type

is_match(git_branch_name: str) → bool

Test if a git branch name matches this semantic branch type.

This method uses the is_certain_semantic_branch() function to determine if the provided branch name matches any of the stubs associated with this semantic branch type.

Parameters:

git_branch_name – The git branch name to test

Returns:

True if the branch name matches this semantic type, False otherwise

Raises:

InvalidSemanticNameError – If any of the stubs are invalid

class semantic_branch.impl.SemanticBranchEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enumeration of all standard semantic branch types.

This enum provides pre-configured SemanticBranch instances for all standard semantic branch types. Each enum value contains a SemanticBranch object with the appropriate canonical name and list of semantic stubs.

This enum serves as the primary interface for semantic branch detection, providing a convenient way to access standardized semantic branch configurations without having to manually create SemanticBranch instances.