semantic_branch#

Semantic branch is a git branch naming convention to indicate what you are trying to do on the git branch. Also, CI system can use branch name to figure out what to do.

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 aws_ops_alpha.vendor.semantic_branch.InvalidSemanticNameError[source]#: Raised when the semantic branch name is invalid.

class aws_ops_alpha.vendor.semantic_branch.SemanticBranchEnum(value)[source]#: Semantic branch name enumeration.

aws_ops_alpha.vendor.semantic_branch.is_valid_semantic_name(name: str)[source]#: Valid semantic name should only contain lowercase letters and digits.

aws_ops_alpha.vendor.semantic_branch.ensure_is_valid_semantic_name(name: str) → str[source]#: Raise an exception if the name is not a valid semantic name. Otherwise, return it as it is.

aws_ops_alpha.vendor.semantic_branch.is_certain_semantic_branch(name: str, words: List[str]) → bool[source]#

Test if a branch name meet certain semantic rules.

Below is an example to check if the branch name start with the keyword “feature”:

>>> is_certain_semantic_branch(
...     name="feature/add-this-feature",
...     stub=["feat", "feature"],
... )
True

Parameters:

name – branch name
words – semantic words

Returns:

a boolean value

class aws_ops_alpha.vendor.semantic_branch.SemanticBranchRule(rules: ~typing.Dict[str, ~typing.List[str]], preprocessor: ~typing.Callable[[str], str] = <function _default_preprocessor>, _parse_semantic_name_cache: ~typing.Dict[str, str] = <factory>)[source]#

A pre-defined semantic branch rule that only accept certain semantic branch names.

Example:

>>> semantic_branch_rule = SemanticBranchRule(
...     rules={
...         "main": ["main", "master"],
...         "feature": ["feat", "feature"],
...     }
... )

Parameters:

rules – a python dictionary that the key is the valid semantic name in this rule, the value is a list of keywords that can be used to identify this semantic name
preprocessor – a function that can transform the git branch name before sending to SemanticBranchRulel.is_certain_semantic_branch`() method
_parse_semantic_name_cache – an internal cache to store the result of SemanticBranchRulel.parse_semantic_name() method. End user should not use it.

is_certain_semantic_branch(git_branch_name: str, semantic_name: str) → bool[source]#

Test if a branch name meet certain semantic name rules.

Example:

>>> semantic_branch_rule = SemanticBranchRule(
...     rules={
...         "main": ["main", "master"],
...         "feature": ["feat", "feature"],
...     }
... )
>>> semantic_branch_rule.is_certain_semantic_branch(git_branch_name="main", semantic_name="main")
True
>>> semantic_branch_rule.is_certain_semantic_branch(git_branch_name="major", semantic_name="main")
False
>>> semantic_branch_rule.is_certain_semantic_branch(git_branch_name="feature/description", semantic_name="feature")
True
>>> semantic_branch_rule.is_certain_semantic_branch(git_branch_name="feature-123/description", semantic_name="feature")
True
>>> semantic_branch_rule.is_certain_semantic_branch(git_branch_name="release", semantic_name="release")
InvalidSemanticNameError: semantic name 'major' doesn't match any semantic name in ['main', 'feature']

parse_semantic_name(git_branch_name: str) → str[source]#

Parse a branch name to a semantic name. If the branch name doesn’t match any rules, raise an exception.

Example:

>>> semantic_branch_rule = SemanticBranchRule(
...     rules={
...         "main": ["main", "master"],
...         "feature": ["feat", "feature"],
...     }
... )
>>> semantic_branch_rule.parse_semantic_name("main")
'main'
>>> semantic_branch_rule.parse_semantic_name("feature/123")
'feature'
>>> semantic_branch_rule.parse_semantic_name("feature-123/123")
'feature'
>>> semantic_branch_rule.parse_semantic_name("release")
InvalidSemanticNameError: branch 'major' doesn't match any semantic name in ['main', 'feature']