adding formatting function for branches (#13)

* adding formatting function for branches

Co-authored-by: Georges Faye <[email protected]>
Co-authored-by: Martynov Maxim <[email protected]>

Author: 3 people

README.md

@@ -281,7 +281,7 @@ setuptools.setup(
 
 When you'll try to get current version in non-master branch, the content of this file will be returned instead.
 
-### Development releases (prereleases) from another branch
+### Development releases (prereleases) from `dev` branch
 
 For example, current repo state is:
 ```
@@ -334,6 +334,79 @@ Then you decided to release new version:
 - `N` in `.devN` suffix is a number of commits since the last change of a certain file.
 - **Note: every change of this file in the `dev` branch will lead to this `N` suffix to be reset to `0`. Update this file only in the case when you've setting up the next release version!**
 
+
+### Development releases (prereleases) from any branch (`feature`/`bugfix`/`preview`/`beta`/etc)
+
+Just like previous example, but you want to make development releases (prereleases) with a branch name present in the version number.
+
+In case of branch names which are PEP-440 compatible, you can just use `{branch}` substitution in a version template.
+
+For example, if the branch name is something like `alpha`, `beta`, `preview` or `rc`:
+```python
+setuptools.setup(
+    ...
+    version_config={
+        "count_commits_from_version_file": True,
+        "dev_template": "{tag}.{branch}{ccount}",
+        "dirty_template": "{tag}.{branch}{ccount}",
+        "version_file": VERSION_FILE
+    },
+    setup_requires=['setuptools-git-versioning'],
+    ...
+)
+```
+Adding a commit to the `alpha` branch will generate a version number like `1.2.3.alpha4`, new commit to the `beta` branch will generate a version number like `1.2.3.beta5` and so on.
+
+It is also possible to use branch names prefixed with a major version number, like `1.0-alpha` or `1.1.beta`:
+```python
+setuptools.setup(
+    ...
+    version_config={
+        "count_commits_from_version_file": True,
+        "dev_template": "{branch}{ccount}",
+        "dirty_template": "{branch}{ccount}",
+        "version_file": VERSION_FILE
+    },
+    setup_requires=['setuptools-git-versioning'],
+    ...
+)
+```
+Adding a commit to the `1.0-alpha` branch will generate a version number like `1.0.alpha2`, new commit to the `1.2.beta` branch will generate a version number like `1.2.beta3` and so on.
+
+But if branch name is not PEP-440 compatible at all, like `feature/ABC-123` or `bugfix/ABC-123`, you'll get version number which `pip` cannot understand.
+
+To fix that you can define a callback which will receive current branch name and return a propery formatted one:
+```python
+import re
+
+def format_branch_name(name):
+    # If branch has name like "bugfix/issue-1234-bug-title", take only "1234" part
+    pattern = re.compile('^(bugfix|feature)\/issue-([0-9]+)-\S+')
+    
+    match = pattern.search(name)
+    if not match:
+        return match.group(2)
+    
+    # function is called even if branch name is not used in a current template
+    # just left properly named branches intact
+    if name == "master":
+        return name
+
+    # fail in case of wrong branch names like "bugfix/issue-title"
+    raise ValueError(f"Wrong branch name: {name}")
+
+setuptools.setup(
+    ...
+    version_config={
+        "dev_template": "{branch}.dev{ccount}",
+        "dirty_template": "{branch}.dev{ccount}",
+        "branch_formatter": format_branch_name
+    },
+    setup_requires=['setuptools-git-versioning'],
+    ...
+)
+```
+
 ## Options
 
 Default options are:
@@ -348,7 +421,8 @@ setuptools.setup(
         "starting_version": "0.0.1",
         "version_callback": None,
         "version_file": None,
-        "count_commits_from_version_file": False
+        "count_commits_from_version_file": False,
+        "branch_formatter": None
     },
     ...
     setup_requires=['setuptools-git-versioning'],
@@ -370,6 +444,8 @@ setuptools.setup(
 
 - `count_commits_from_version_file`: `True` to fetch `version_file` last commit instead of tag commit, `False` otherwise
 
+- `branch_formatter`: callback to be used for formatting a branch name before template substitution
+
 ### Substitions
 
 You can use these substitutions in `template`, `dev_template` or `dirty_template` options:

setuptools_git_versioning.py

@@ -109,6 +109,7 @@ def parse_config(dist, _, value):  # type: (Distribution, Any, Any) -> None
     version_callback = value.get('version_callback', None)
     version_file = value.get('version_file', None)
     count_commits_from_version_file = value.get('count_commits_from_version_file', False)
+    branch_formatter = value.get('branch_formatter', None)
 
     version = version_from_git(
         template=template,
@@ -117,7 +118,8 @@ def parse_config(dist, _, value):  # type: (Distribution, Any, Any) -> None
         starting_version=starting_version,
         version_callback=version_callback,
         version_file=version_file,
-        count_commits_from_version_file=count_commits_from_version_file
+        count_commits_from_version_file=count_commits_from_version_file,
+        branch_formatter=branch_formatter
     )
     dist.metadata.version = version
 
@@ -133,8 +135,10 @@ def version_from_git(template=DEFAULT_TEMPLATE,
                      starting_version=DEFAULT_STARTING_VERSION,
                      version_callback=None,
                      version_file=None,
-                     count_commits_from_version_file=False
-                     ):  # type: (str, str, str, str, Optional[Any, Callable], Optional[str], bool) -> str
+                     count_commits_from_version_file=False,
+                     branch_formatter=None,
+                     ):
+    # type: (str, str, str, str, Optional[Any, Callable], Optional[str], bool, Optional[Callable[[str], str]]) -> str
 
     # Check if PKG-INFO exists and return value in that if it does
     if os.path.exists('PKG-INFO'):
@@ -171,7 +175,7 @@ def version_from_git(template=DEFAULT_TEMPLATE,
     full_sha = head_sha if head_sha is not None else ''
     ccount = count_since(tag_sha)
     on_tag = head_sha is not None and head_sha == tag_sha and not from_file
-    branch = get_branch()
+    branch = get_branch() if branch_formatter is None else branch_formatter(get_branch())
 
     if dirty:
         t = dirty_template