chore: remove useless data dir

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

pyproject.toml

@@ -46,7 +46,7 @@ include-package-data = true
 where = ["src"]
 
 [tool.setuptools.package-data]
-"pygitversionhelper.data" = ["*.*"]
+"pysimpleini" = ["py.typed"]
 
 [project.urls]
 Homepage        = "https://chacha.ddns.net/gitea/chacha/pygitversionhelper/"

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)