diff --git a/pyproject.toml b/pyproject.toml index 207b7db..32815a9 100644 --- a/pyproject.toml +++ b/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/" diff --git a/src/pygitversionhelper/data/.keep b/src/pygitversionhelper/data/.keep deleted file mode 100644 index e69de29..0000000 diff --git a/src/pygitversionhelper/data/__init__.py b/src/pygitversionhelper/data/__init__.py deleted file mode 100644 index 5858865..0000000 --- a/src/pygitversionhelper/data/__init__.py +++ /dev/null @@ -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 . diff --git a/src/pygitversionhelper/gitversionhelper.py b/src/pygitversionhelper/gitversionhelper.py index a190d9d..0b33b72 100644 --- a/src/pygitversionhelper/gitversionhelper.py +++ b/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)