reword

README.md

@@ -3,46 +3,33 @@
 
 ![](docs-static/Library.jpg)
 
-# Python project template
+# pyGitVersionHelper
 
-A nice template to start a blank python projet.
- 
-This template automate a lot of handy things and allow CI/CD automatic releases generation.
+_A tiny library to help versioning management of git python projects_ 
 
-It is also collectings data to feed Jenkins build.
+Because a good developer is a lazy developer and version management in CI/CD can be very time consuming.
 
-Checkout [Latest Documentation](https://chacha.ddns.net/mkdocs-web/chacha/pychachadummyproject/{{branch}}/latest/).
+
+Checkout [Latest Documentation](https://chacha.ddns.net/mkdocs-web/chacha/pygitversionhelper/{{branch}}/latest/).
 
 ## Features
-
-### Generic pipeline skeleton:
-    - Prepare
-    - GetCode
-    - BuildPackage
-    - Install
-    - CheckCode
-    - PlotMetrics
-    - RunUnitTests
-    - GenDOC
-    - PostRelease
+    - list tags
+    - get last tag 
+    - get last version
+    - get current version (bumped)
+    - convert / switch from SemVer to PEP440 (both ways)
+    - automatic version format detection (SemVer by default)
     
-### CI/CD Environment
-    - Jenkins
-    - Gitea (with patch for dynamic Readme variables: https://chacha.ddns.net/gitea/chacha/GiteaMarkupVariable)
-    - Docker
-    - MkDocsWeb
-    
-### CI/CD Helper libs
-    - VirtualEnv
-    - Changelog generation based on commits
-    - copier
-    - pylint + pylint_json2html
-    - mypy
-    - unittest + xmlrunner + junitparser + junit2htmlreport
-    - mkdocs
+## Options
+    - restrict to same branch
+    - both SemVer and PEP440 support
+    - custom output format
+    - configurable default bump type major, minor, patch or dev
+    - configurable default bump type: post, pre-patch, pre-minor, pre-major
+    - ignore non-version tag
+    - force version format
 
-### Python project
-    - Full .toml implementation
-    - .whl automatic generation
-    - dynamic versionning using git repository
-    - embedded unit-test
+## Process
+    - full CI/CD developpment: Gitea / Jenkins + few python libs (pytlint, coverage, unittest, mkdocs)
+    - documentation generated mkdocs and self-hosted
+    - CI/CD on Linux, manually tested in Windows environnement

docs-static/usage.md

@@ -1,16 +1,113 @@
 # Usage
 
-## Pulvinar dolor
-Donec dapibus est fermentum justo volutpat condimentum. Integer quis nunc neque. Donec dictum vehicula justo, in facilisis ex tincidunt in. 
-Vivamus sollicitudin sem dui, id mollis orci facilisis ut. Proin sed pulvinar dolor. Donec volutpat commodo urna imperdiet pulvinar. Fusce eget aliquam risus. 
-Vivamus viverra luctus ex, in finibus mi. Nullam elementum dapibus mollis. Ut suscipit volutpat ex, quis feugiat lacus consectetur eu. 
+## Installation
 
-## Condimentum faucibus
-Quisque auctor egestas sem, luctus suscipit ex maximus vitae. Duis facilisis augue et condimentum faucibus. 
-Donec cursus, enim a sagittis egestas, lectus lorem eleifend libero, at tincidunt leo magna at libero. 
-Nunc eros velit, suscipit luctus tempor vel, finibus et est. Curabitur efficitur pretium pulvinar. 
-Donec urna lectus, vulputate quis turpis sed, placerat congue urna. Phasellus aliquet fermentum quam, non auctor elit porta nec. Morbi eu ligula at nisl ultricies condimentum vitae id ante. 
+From master repository:
 
-## Aliquam lacinia
-In volutpat lorem ex, et fringilla nibh faucibus quis. Mauris et arcu elementum, auctor dui vitae, egestas arcu. Duis sit amet aliquam quam. 
-Phasellus a odio turpis. Etiam tristique mi eu enim varius, eget facilisis est vestibulum. Aliquam lacinia nec purus sed luctus. Cras at laoreet erat. 
+    python -m pip install git+https://chacha.ddns.net/gitea/chacha/pygitversionhelper.git@master
+
+From local .whl file:
+
+    python -m pip install pygitversionhelper-<VERSION>-py3-none-any.whl
+
+From public repository:
+
+    TBD
+
+## Import in your project
+
+Add this line on the top of your python script:
+
+    #from pygitversionhelper import gitversionhelper
+
+[optionnal] If you need to catch exception from this module:
+
+    #from pygitversionhelper import gitversionhelperException
+    
+## Basic API
+
+All the API commands are static so it is not needed to create instantiate any object.
+
+They are all executed in the current active directory.
+
+One easy way to change directory:
+
+    import os
+    os.chdir("<YOUR DIRECTORY>")
+
+### sublib: repository 
+
+To check if a repository is dirty:
+
+    if gitversionhelper.repository.isDirty():
+        print("repository is dirty")
+
+### sublib: tag 
+
+List all tags [default to taggerdate order]:
+
+    for tag in gitversionhelper.tag.getTags():
+        print(f"found tag: {tag}")
+        
+List all tags [using git refname order]:
+
+    for tag in gitversionhelper.tag.getTags("v:refname"):
+        print(f"found tag: {tag}")
+
+Get the last tag:
+
+    print(f"most recent repository tag: {gitversionhelper.tag.getLastTag()}")
+    
+Get the last tag [only on same branch]:
+
+    print(f"most recent repository tag: {gitversionhelper.tag.getLastTag(same_branch=True)}")
+
+
+Get the distance from HEAD to last tag:
+
+    print(f"number of commit since last tag: {gitversionhelper.tag.getDistanceFromTag()}")
+
+Get the distance from HEAD to last tag [only on same branch]:
+
+    print(f"number of commit since last tag: {gitversionhelper.tag.getDistanceFromTag(same_branch=True)}")
+    
+### sublib: version 
+
+Get the last found version in the repository [return MetaVersion object]:
+
+    print(f"most recent repository version: {gitversionhelper.tag.getLastVersion()}")
+    
+Get the last found version in the repository [return formated string]:
+
+    print(f"most recent repository version: {gitversionhelper.tag.getLastVersion(formated_output=True)}")
+
+Others kwargs available to this function:
+    - version_std: string to force a version standard for rendering ["PEP440" or "SemVer"]
+    - same_branch: boolean to force searching on same branch
+    - ignore_unknown_tags: boolean to allow unknown tag to be ignored
+
+Get the current version of the repository, automatically bump it if the last one is not tagged [returns MetaVersion object]:
+
+    print(f"most recent repository version: {gitversionhelper.tag.getCurrentVersion()}")
+    
+kwargs available to this function:
+    - All same args as getLastVersion()
+    - bump_type: if version need to be pump, allow to configure next release update type: major, minor, patch, dev
+    - bump_dev_strategy: if bump_type is dev, allow to choose dev update strategy: post, pre-patch, pre-minor, pre-major
+
+A version object can also be manually formated:
+
+    _version = gitversionhelper.tag.getCurrentVersion()
+    _version.doFormatVersion()
+    #or
+    gitversionhelper.version.doFormatVersion(_version)
+
+kwargs available to those function:
+    - output_format: string to choose a rendering format ["Auto","PEP440" or "SemVer"]
+
+## Limitations
+
+There is unfortunately some technical limitation :
+- MultiThreading and async behavior is not tested.
+- Multiple tag on the same commit is not supported.
+- Branch filter when searching for a version is only tested with -no-ff strategy

src/pygitversionhelper/gitversionhelper.py

@@ -9,19 +9,22 @@
 """
 This project try to help doing handy operations with git when 
 dealing with project versioning and tags on python project -
-or at leat for project using PEP440 versionning or SemVer.
+at leat for project using PEP440 or SemVer standards.
 
-Goal is to keep it compact and not covering too much other things.
-This is the reason it is one single file with nested classes.
-=> Design is on purpose poorly expandable to keep the scope maintainable.
+One requirement is to keep it compact and to not cover too much fancy features.
+This is the reason why it is one single file with nested classes.
+=> Design is on-purpose poorly expandable to keep the scope light.
 
 This library is maid for repository using tag as version.
+Support for non-version tags is optional and not well tested.
 
-
-This module is the main gitversionhelper file, containing all the code.
+This module is the main project file, containing all the code.
 
 Read the read me for more information.
 Check the unittest s for usage samples.
+
+Note:
+    Other Parameters are **kwargs
 """
 
 from __future__ import annotations
@@ -283,7 +286,7 @@ class gitversionhelper: # pylint: disable=too-few-public-methods
                         raise gitversionhelper.wrongArguments(f"invalid {cls.__OptDict['bump_type']} requested")
                 return BumpType
 
-            def bump(self,amount:int=1,**kwargs) -> cls | str : # pylint: disable=R0912
+            def bump(self,amount:int=1,**kwargs) -> gitversionhelper.version.MetaVersion | str : # pylint: disable=R0912
                 """
                 bump the version to the next one
                 Keyword Arguments:
@@ -338,6 +341,8 @@ class gitversionhelper: # pylint: disable=too-few-public-methods
             def doFormatVersion(self,**kwargs) -> str:
                 """
                 output a formated version string
+                Keyword Arguments:
+                    output_format: output format to render ("Auto" or "PEP440" or "SemVer")
                 Returns:
                     formated version string
                 """
@@ -368,6 +373,8 @@ class gitversionhelper: # pylint: disable=too-few-public-methods
                 version_std(str): the given version_std (can be None)
                 same_branch(bool): force searching only in the same branch
                 formated_output(bool) : output a formated version string
+                bump_type(str): the given bump_type (can be None)
+                bump_dev_strategy(str): the given bump_dev_strategy (can be None)
             Returns:
                 the last version
             """
@@ -451,6 +458,10 @@ class gitversionhelper: # pylint: disable=too-few-public-methods
 
             if not bFound :
                 raise gitversionhelper.version.noValidVersion("no valid version found in tags")  
+    
+            if pre_count > 0 and post_count > 0:
+                raise cls.PreAndPostVersionUnsupported("can not parse a version with both pre" \
+                                                       " and post release number.")
             return cls.MetaVersion(VersionStd, major, minor, patch, pre_count, post_count, tag)
 
         @classmethod
@@ -475,18 +486,18 @@ class gitversionhelper: # pylint: disable=too-few-public-methods
             _v=None
             try:
                 _v=cls._parseTag(lastTag,**kwargs)
-            except gitversionhelper.version.noValidVersion as _ex:   
+            except gitversionhelper.version.noValidVersion as _ex:
                 if ((cls.__OptDict["ignore_unknown_tags"] in kwargs) and (kwargs[cls.__OptDict["ignore_unknown_tags"]] is True)):
                     tags = gitversionhelper.tag.getTags(sort= "taggerdate",**kwargs)
-                    _v=None
+                    _v = None
                     for _tag in tags:
                         try:
                             _v=cls._parseTag(_tag,**kwargs)
-                            break;
+                            break
                         except gitversionhelper.version.noValidVersion:
                             continue
                 if _v is None:
-                    raise gitversionhelper.version.noValidVersion() from _ex  
+                    raise gitversionhelper.version.noValidVersion() from _ex
 
             if ((cls.__OptDict["formated_output"] in kwargs) and (kwargs[cls.__OptDict["formated_output"]] is True)):
                 return _v.doFormatVersion(**kwargs)
@@ -496,6 +507,8 @@ class gitversionhelper: # pylint: disable=too-few-public-methods
         def doFormatVersion(cls,inputversion:MetaVersion,**kwargs) -> str:
             """
             output a formated version string
+            Keyword Arguments:
+                output_format: output format to render ("Auto" or "PEP440" or "SemVer")
             Args:
                 inputversion: version to be rendered
             Returns:
@@ -519,7 +532,8 @@ class gitversionhelper: # pylint: disable=too-few-public-methods
             if OutputFormat is None:
                 OutputFormat = "{major}.{minor}.{patch}{revpattern}{revcount}"
                 if post_count > 0 and pre_count > 0:
-                    raise gitversionhelper.version.PreAndPostVersionUnsupported()
+                    raise gitversionhelper.version.PreAndPostVersionUnsupported("cannot output a version with both pre " \
+                                                                                "and post release number.")
                 if      VersionStd == "PEP440":
                     if post_count > 0:
                         revpattern=".post"

test/test_gitversionhelper.py

@@ -651,13 +651,32 @@ class Test_gitversionhelper(unittest.TestCase):
             pygitversionhelper.gitversionhelper.version.getCurrentVersion()
             
 
-    def test_defect__version_post_and_pre(self):
+    def test_defect__version_post_and_pre_output(self):
+        _v = pygitversionhelper.gitversionhelper.version.MetaVersion("PEP440",
+                                                                     0,
+                                                                     0,
+                                                                     1,
+                                                                     1,
+                                                                     1,
+                                                                     "0.0.1.pre1.post1")
         with self.assertRaises(pygitversionhelper.gitversionhelper.version.PreAndPostVersionUnsupported) :
-            _v=self._test_version_readback("0.1.1.pre1.post1",version_std="PEP440")
+            _v.doFormatVersion()
             
+        _v = pygitversionhelper.gitversionhelper.version.MetaVersion("SemVer",
+                                                                     0,
+                                                                     0,
+                                                                     1,
+                                                                     1,
+                                                                     1,
+                                                                     "0.0.1-pre.1+post.1")
         with self.assertRaises(pygitversionhelper.gitversionhelper.version.PreAndPostVersionUnsupported) :
-            _v=self._test_version_readback("0.1.1-pre.1+post.1",version_std="SemVer")
+            _v.doFormatVersion()
+            
+    def test_defect__version_post_and_pre_parse(self):
+        with self.assertRaises(pygitversionhelper.gitversionhelper.version.PreAndPostVersionUnsupported) :
+            pygitversionhelper.gitversionhelper.version._parseTag("0.0.1.pre1.post1")
 
+            
     def test_defect__git__wrongargument_sortargs(self):
         with self.assertRaises(pygitversionhelper.gitversionhelper.wrongArguments) :
             pygitversionhelper.gitversionhelper.tag.getTags(sort="toto")