update from last project template

fix: correct function doc (Google docstrings)
fix: add py.tyed to dist

Jenkinsfile

@@ -426,9 +426,17 @@ pipeline {
             }
             post {
                 always {      
-                    dir("gitrepo") {       
-                        publishCoverage adapters: [cobertura(mergeToOneReport: true, path: "helpers-results/cl_types_check/cobertura.xml")]
-                        junit 'helpers-results/cl_types_check/junit.xml'           
+                    dir("gitrepo") { 
+                        //publish coverage
+                        recordCoverage( sourceDirectories: [[path: 'src']],
+                                        tools: [[parser: 'COBERTURA', pattern: 'helpers-results/cl_types_check/cobertura.xml']],
+                                        id: 'COBERTURA', name: 'COBERTURA Coverage',
+                                        sourceCodeRetention: 'EVERY_BUILD',)
+                        
+                        //add type check to junit result set
+                        junit 'helpers-results/cl_types_check/junit.xml'    
+                        
+                        //publish html reports files
                         publishHTML([
                                     reportDir:              "helpers-results/cl_quality_check",
                                     reportFiles:            "report.html",

RUN_quality.launch

@@ -10,7 +10,7 @@
     <stringAttribute key="org.eclipse.debug.ui.ATTR_CONSOLE_ENCODING" value="UTF-8"/>
     <stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:pygitversionhelper/helpers_proxy}"/>
     <stringAttribute key="org.eclipse.ui.externaltools.ATTR_OTHER_WORKING_DIRECTORY" value=""/>
-    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_TOOL_ARGUMENTS" value="--typecheck --qualitycheck"/>
+    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_TOOL_ARGUMENTS" value="--qualitycheck"/>
     <stringAttribute key="org.python.pydev.debug.ATTR_INTERPRETER" value="__default"/>
     <stringAttribute key="org.python.pydev.debug.ATTR_PROJECT" value="pygitversionhelper"/>
     <stringAttribute key="process_factory_id" value="org.python.pydev.debug.processfactory.PyProcessFactory"/>

RUN_types.launch

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<launchConfiguration type="org.python.pydev.debug.regularLaunchConfigurationType">
+    <booleanAttribute key="org.eclipse.debug.core.ATTR_FORCE_SYSTEM_CONSOLE_ENCODING" value="false"/>
+    <listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_PATHS">
+        <listEntry value="/pygitversionhelper/helpers_proxy"/>
+    </listAttribute>
+    <listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_TYPES">
+        <listEntry value="2"/>
+    </listAttribute>
+    <stringAttribute key="org.eclipse.debug.ui.ATTR_CONSOLE_ENCODING" value="UTF-8"/>
+    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:pygitversionhelper/helpers_proxy}"/>
+    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_OTHER_WORKING_DIRECTORY" value=""/>
+    <stringAttribute key="org.eclipse.ui.externaltools.ATTR_TOOL_ARGUMENTS" value="--typecheck"/>
+    <stringAttribute key="org.python.pydev.debug.ATTR_INTERPRETER" value="__default"/>
+    <stringAttribute key="org.python.pydev.debug.ATTR_PROJECT" value="pygitversionhelper"/>
+    <stringAttribute key="process_factory_id" value="org.python.pydev.debug.processfactory.PyProcessFactory"/>
+</launchConfiguration>

mkdocs.yml

@@ -67,7 +67,7 @@ plugins:
     verbose: false
     exclude_pages:
     - LICENSE
-    output_path: C:\Users\chacha\git\pygitversionhelper\helpers-results\doc_gen\site\pdf\manual.pdf
+    output_path: C:\Users\chacha\git\pygitversionhelper\helpers-results\cl_doc_gen\site\pdf\manual.pdf
 markdown_extensions:
 - def_list
 - tables
@@ -114,8 +114,8 @@ markdown_extensions:
 - footnotes
 - pymdownx.superfences
 - pymdownx.emoji:
-    emoji_index: !!python/name:materialx.emoji.twemoji
-    emoji_generator: !!python/name:materialx.emoji.to_svg
+    emoji_index: !!python/name:materialx.emoji.twemoji ''
+    emoji_generator: !!python/name:materialx.emoji.to_svg ''
 extra:
   branch: master
   repository: pygitversionhelper

pyproject.toml

@@ -46,7 +46,21 @@ include-package-data = true
 where = ["src"]
 
 [tool.setuptools.package-data]
-"pygitversionhelper.data" = ["*.*"]
+"pysimpleini" = ["py.typed"]
+
+# [[tool.mypy.overrides]]
+# module = ""
+# ignore_missing_imports = true
+
+[tool.coverage.run]
+cover_pylib = false
+branch = true
+data_file="helpers-results/cl_unit_test_raw_coverage/.coverage"
+# debug = ["config","multiproc","process"]
+parallel = true
+concurrency = [
+    'thread'
+]
 
 [project.urls]
 Homepage        = "https://chacha.ddns.net/gitea/chacha/pygitversionhelper/"
@@ -54,12 +68,12 @@ Documentation   = "https://chacha.ddns.net/mkdocs-web/chacha/pygitversionhelper/
 Tracker         = "https://chacha.ddns.net/gitea/chacha/pygitversionhelper/issues"
 
 [project.optional-dependencies]
-test              = ["chacha_cicd_helper@git+https://chacha.ddns.net/gitea/chacha/chacha_cicd_helper.git@master"]
-coverage-check    = ["chacha_cicd_helper@git+https://chacha.ddns.net/gitea/chacha/chacha_cicd_helper.git@master"]
-complexity-check  = ["chacha_cicd_helper@git+https://chacha.ddns.net/gitea/chacha/chacha_cicd_helper.git@master"]
-quality-check     = ["chacha_cicd_helper@git+https://chacha.ddns.net/gitea/chacha/chacha_cicd_helper.git@master"]
-type-check        = ["chacha_cicd_helper@git+https://chacha.ddns.net/gitea/chacha/chacha_cicd_helper.git@master"]
-doc-gen           = ["chacha_cicd_helper@git+https://chacha.ddns.net/gitea/chacha/chacha_cicd_helper.git@master"]
+test              = ["chacha_cicd_helper"]
+coverage-check    = ["chacha_cicd_helper"]
+complexity-check  = ["chacha_cicd_helper"]
+quality-check     = ["chacha_cicd_helper"]
+type-check        = ["chacha_cicd_helper"]
+doc-gen           = ["chacha_cicd_helper"]
 
 # [project.scripts]
 # my-script = "my_package.module:function"

src/pygitversionhelper/data/__init__.py

@@ -1,7 +0,0 @@
-# pygitversionhelper (c) by chacha
-#
-# pygitversionhelper  is licensed under a
-# Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Unported License.
-#
-# You should have received a copy of the license along with this
-# work.  If not, see <https://creativecommons.org/licenses/by-nc-sa/4.0/>.

src/pygitversionhelper/gitversionhelper.py

@@ -65,10 +65,12 @@ if TYPE_CHECKING:
 
 def _exec(cmd: str, root: Optional[str | os.PathLike[str]] = None, raw: bool = False) -> str | List[str]:
     """helper function to handle system cmd execution
+
     Args:
         cmd: command line to be executed
         root: root directory where the command need to be executed
         raw: return bytes if True, str if False or None
+
     Returns:
         a list of command's return lines or the raw output
 
@@ -134,8 +136,10 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def isDirty(cls) -> bool:
             """check if the repository is in dirty state
+
             Returns:
                 True if it is dirty
+
             """
             return bool(_exec("git status --short"))
 
@@ -151,16 +155,19 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getMessagesSinceTag(cls, tag: str, **kwargs: Unpack[TKwargs]) -> str | List[str]:
             """Retrieve a commits message history from repository.
-
             Start from Latest found commit until the given tag.
+
             Args:
-                tag: tag of the commit where search will stop
+                tag (str): tag of the commit where search will stop
+
             Keyword Arguments:
                 kwargs/merged_output (bool): Output one single merged string
                 kwargs/same_branch (bool): Force searching only in the same branch
                 kwargs/ignore_merged (bool): ignore merged commits
+
             Returns:
                 the commit message
+
             """
             current_commit_id = cls.getLast(**kwargs)
             tag_commit_id = cls.getFromTag(tag)
@@ -190,10 +197,13 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getMessage(cls, commit_hash: str) -> str:
             """retrieve a commit message from repository
+
             Args:
                 commit_hash: id of the commit
+
             Returns:
                 the commit message
+
             """
             try:
                 res = _exec(
@@ -210,10 +220,13 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getFromTag(cls, tag: str) -> str:
             """retrieve a commit from repository associated to a tag
+
             Args:
                 tag: tag of the commit
+
             Returns:
                 the commit Id
+
             """
             try:
                 res = _exec(f"git rev-list -n 1 {tag}")  # ok
@@ -227,11 +240,14 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getLast(cls, **kwargs: Unpack[TKwargs]) -> str:
             """retrieve last commit from repository
+
             Keyword Arguments:
                 kwargs/same_branch (bool): force searching only in the same branch
                 kwargs/ignore_merged (bool): ignore merged commits
+
             Returns:
                 the commit Id
+
             """
             str_cmd: str
             if ("same_branch" in kwargs) and (kwargs["same_branch"] is True):
@@ -276,12 +292,16 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getTags(cls, Sort: str = "taggerdate", **kwargs: Unpack[TKwargs]) -> List[str]:
             """retrieve all tags from a repository
+
             Args:
                 Sort: sorting constraints (git format)
+
             Keyword Arguments:
                 kwargs/same_branch (bool): force searching only in the same branch
+
             Returns:
                 the tags list
+
             """
 
             if Sort not in cls.__validGitTagSort:
@@ -295,10 +315,13 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getLastTag(cls, **kwargs: Unpack[TKwargs]) -> str:
             """retrieve the Latest tag from a repository
+
             Keyword Arguments:
                 kwargs/same_branch (bool): force searching only in the same branch
+
             Returns:
                 the tag
+
             """
             if ("same_branch" in kwargs) and (kwargs["same_branch"] is True):
                 res = _exec("git describe --tags --first-parent --abbrev=0")
@@ -316,12 +339,16 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getDistanceFromTag(cls, tag: Optional[str] = None, **kwargs: Unpack[TKwargs]) -> int:
             """retrieve the distance between Latest commit and tag in the repository
+
             Arguments:
                 tag: reference tag, if None the most recent one will be used
+
             Keyword Arguments:
                 kwargs/same_branch (bool): force searching only in the same branch
+
             Returns:
                 the tag
+
             """
             if tag is None:
                 tag = cls.getLastTag(**kwargs)
@@ -397,10 +424,13 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
             @classmethod
             def _getBumpDevStrategy(cls, **kwargs: Unpack[TKwargs]) -> str:
                 """get selected bump_dev_strategy
+
                 Keyword Arguments:
                     kwargs/bump_dev_strategy (str): the given bump_dev_strategy (can be None)
+
                 Returns:
                     Kwargs given bump_dev_strategy or the default one.
+
                 """
                 BumpDevStrategy: str = cls.DefaultBumpDevStrategy
 
@@ -414,10 +444,13 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
             @classmethod
             def _getBumpType(cls, **kwargs: Unpack[TKwargs]) -> str:
                 """get selected bump_type
+
                 Keyword Arguments:
                     kwargs/bump_type (str): the given bump_type (can be None)
+
                 Returns:
                     Kwargs given bump_type or the default one.
+
                 """
                 BumpType: str = cls.DefaultBumpType
                 if "bump_type" in kwargs:
@@ -431,13 +464,17 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
                 self, amount: int = 1, **kwargs: Unpack[TKwargs]
             ) -> gitversionhelper.version.MetaVersion | str:
                 """bump the version to the next one
+
                 Args:
                     amount: number of revision to bump
+
                 Keyword Arguments:
                     kwargs/bump_type (str): the given bump_type (can be None)
                     kwargs/bump_dev_strategy (str): the given bump_dev_strategy (can be None)
+
                 Returns:
                     the bumped version
+
                 """
 
                 BumpType: str = self._getBumpType(**kwargs)
@@ -488,20 +525,26 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
 
             def doFormatVersion(self, **kwargs: Unpack[TKwargs]) -> str:
                 """output a formated version string
+
                 Keyword Arguments:
                     kwargs/output_format: output format to render ("Auto" or "PEP440" or "SemVer")
+
                 Returns:
                     formated version string
+
                 """
                 return gitversionhelper.version.doFormatVersion(self, **kwargs)
 
         @classmethod
         def _getVersionStd(cls, **kwargs: Unpack[TKwargs]) -> gitversionhelper.version.MetaVersion.TVersionStd:
             """get selected version_std
+
             Keyword Arguments:
                 kwargs/version_std (str): the given version_std (can be None)
+
             Returns:
                 Kwargs given version_std or the default one.
+
             """
             VersionStd: str = cls.DefaultInputFormat
             if "version_std" in kwargs:
@@ -514,6 +557,7 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getCurrentVersion(cls, **kwargs: Unpack[TKwargs]) -> gitversionhelper.version.MetaVersion | str:
             """get the current version or bump depending of repository state.
+
             Keyword Arguments:
                 kwargs/version_std (str): the given version_std (can be None)
                 kwargs/same_branch (bool): force searching only in the same branch
@@ -521,8 +565,10 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
                 kwargs/bump_type (str): the given bump_type (can be None)
                 kwargs/bump_dev_strategy (str): the given bump_dev_strategy (can be None)
                 kwargs/output_format (str): output format to render ("Auto" or "PEP440" or "SemVer")
+
             Returns:
                 the last version
+
             """
             if gitversionhelper.repository.isDirty() is not False:
                 raise gitversionhelper.repository.repositoryDirty("The repository is dirty and a current version can not be generated.")
@@ -544,14 +590,17 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getCurrentFormatedVersion(cls, **kwargs: Unpack[TKwargs]) -> str:
             """same as getCurrentVersion() with formated_output kwarg forced activated.
+
             Keyword Arguments:
                 kwargs/version_std (str): the given version_std (can be None)
                 kwargs/same_branch (bool): force searching only in the same branch
                 kwargs/bump_type (str): the given bump_type (can be None)
                 kwargs/bump_dev_strategy (str): the given bump_dev_strategy (can be None)
                 kwargs/output_format (str): output format to render ("Auto" or "PEP440" or "SemVer")
+
             Returns:
                 the last version
+
             """
             kwargs["formated_output"] = True
             return cast(str, cls.getCurrentVersion(**kwargs))
@@ -561,12 +610,16 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
             cls, tag: str, **kwargs: Unpack[TKwargs]
         ) -> gitversionhelper.version.MetaVersion:
             """get version from tags.
+
             Arguments:
                 tag: the tag to be parsed
+
             Keyword Arguments:
                 kwargs/version_std (str): the given version_std (can be None)
+
             Returns:
                 MetaVersion object
+
             """
             _m: Optional[re.Match[str]]
             VersionStd: gitversionhelper.version.MetaVersion.TVersionStd = cls._getVersionStd(**kwargs)
@@ -639,13 +692,16 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def getLastVersion(cls, **kwargs: Unpack[TKwargs]) -> gitversionhelper.version.MetaVersion | str:  # pylint: disable=R1260
             """get the last version from tags
+
             Keyword Arguments:
                 kwargs/version_std (str): the given version_std (can be None)
                 kwargs/same_branch (bool): force searching only in the same branch
                 kwargs/formated_output (bool): output a formated version string
                 kwargs/ignore_unknown_tags (bool): skip tags with not decoded versions (default to False)
+
             Returns:
                 the last version in MetaVersion object or string
+
             """
             lastTag: str = cls.MetaVersion.raw
             cls.__versionReseted = False
@@ -678,12 +734,16 @@ class gitversionhelper:  # pylint: disable=too-few-public-methods
         @classmethod
         def doFormatVersion(cls, inputversion: MetaVersion, **kwargs: Unpack[TKwargs]) -> str:
             """output a formated version string from a MetaVersion object
+
             Keyword Arguments:
                 kwargs/output_format (str): output format to render ("Auto" or "PEP440" or "SemVer")
+
             Args:
                 inputversion: version to be rendered
+
             Returns:
                 formated version string
+
             """
 
             VersionStd = cls._getVersionStd(**kwargs)