gitflow-manager 1.0.1__tar.gz

gitflow_manager-1.0.1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: gitflow_manager
+Version: 1.0.1
+Summary: This package contains the Anacision Git Manager.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: gitpython>=3.1.24
+Requires-Dist: pystache>=0.6.0
+Requires-Dist: requests>=2.27.1
+Requires-Dist: toml>=0.10.2
+
+# Anacision Gitflow Manager
+
+## Description
+
+The gitflow manager is a tool that helps maintaining clean versioning and documentation in code projects.
+By using the gitflow manager one can make sure to stick to the 
+[GitFlow](https://nvie.com/posts/a-successful-git-branching-model) rules. Furthermore, it helps maintain a good
+changelog and documentation.
+Whenever you want to start a new branch or merging it back to dev/main run the `gfm` command.
+It uses a dialog to define the type of new branch (feature, bugfix, hotfix, release) or merge option as well as setting 
+the required changelog messages.
+It then automatically updates version numbers, checks out corresponding branches and commits/merges according to the 
+GitFlow.
+Changes are also pushed to the Git Host via ssh or https and for protected branches merge requests are initialized.
+Currently, the gitflow manager supports Gitlab and Bitbucket as hosting platforms.
+
+### Versioning
+
+- Utilize the gitflow manager in projects to make sure that you easily stick to these rules:
+  - Versions are defined in the format *Major.Minor.Hotfix*. New versions are created when opening the hotfix or release 
+  branch.
+  - The hotfix branch is only allowed to be started from main branch, to increase the Hotfix version digit only and to 
+  be merged into main (+ dev thereafter).
+  - The release branch is only allowed to be started from dev, to increase the minor or major version digit and to be 
+  merged into main (+ dev thereafter). In case of a new major version, the minor and hotfix digit is reset to 0. In case
+  of a new minor version, the hotfix digit is reset to 0.
+  - The bugfix and feature branches are only allowed to be started from dev, increase no version number and are merged 
+  back to dev.
+  - All new branches need a description in the change log, which has separate "Added", "Changed" and "Fixed" sections.
+
+### Supported branches with gitflow manager
+
+- **main**: Permanent, stable, (normally) protected branch used for deployment. Each commit has a new version. Merge 
+requests only come from release or hotfix branch.
+- **dev**: Permanent development branch. Gets merge requests from feature, hotfix and release branch.
+- **release/vX.X.X**: Release branch. Branched off from dev branch with new minor or major version. When the branch is
+finished, it is merged into main and dev branch. Intermediate merges into dev are allowed, too. Merges from dev into 
+release branch are not allowed.
+- **feature/xxxxxx**: For features to be developed. Branched off from dev branch and will be merged back into dev after 
+finishing feature.
+- **bugfix/xxxxxx**: For bugs to be fixed. Branched off from dev branch and will be merged back into dev after 
+finishing the fix.
+- **hotfix/vX.X.X**: Hotfix branch for fixes from deployed code. Branched off from main branch with new hotfix 
+version. When done, is merged into main and dev branch.
+
+### Tagging
+
+- Currently, tagging is not done automatically. You can configure yourself a CI pipeline, that does the job for you.
+
+## Getting started
+
+### Installation
+
+1. Install gitflow manager with pip: `pip install gitflow-manager`
+2. Restart terminal
+
+### Usage
+
+- When using the first time, run `gfm --init` in the root of the project.
+- Subsequently, just type `gfm` each time you need to branch or merge (or add change log information), and follow the 
+dialog

gitflow_manager-1.0.1/README.md

@@ -0,0 +1,61 @@
+# Anacision Gitflow Manager
+
+## Description
+
+The gitflow manager is a tool that helps maintaining clean versioning and documentation in code projects.
+By using the gitflow manager one can make sure to stick to the 
+[GitFlow](https://nvie.com/posts/a-successful-git-branching-model) rules. Furthermore, it helps maintain a good
+changelog and documentation.
+Whenever you want to start a new branch or merging it back to dev/main run the `gfm` command.
+It uses a dialog to define the type of new branch (feature, bugfix, hotfix, release) or merge option as well as setting 
+the required changelog messages.
+It then automatically updates version numbers, checks out corresponding branches and commits/merges according to the 
+GitFlow.
+Changes are also pushed to the Git Host via ssh or https and for protected branches merge requests are initialized.
+Currently, the gitflow manager supports Gitlab and Bitbucket as hosting platforms.
+
+### Versioning
+
+- Utilize the gitflow manager in projects to make sure that you easily stick to these rules:
+  - Versions are defined in the format *Major.Minor.Hotfix*. New versions are created when opening the hotfix or release 
+  branch.
+  - The hotfix branch is only allowed to be started from main branch, to increase the Hotfix version digit only and to 
+  be merged into main (+ dev thereafter).
+  - The release branch is only allowed to be started from dev, to increase the minor or major version digit and to be 
+  merged into main (+ dev thereafter). In case of a new major version, the minor and hotfix digit is reset to 0. In case
+  of a new minor version, the hotfix digit is reset to 0.
+  - The bugfix and feature branches are only allowed to be started from dev, increase no version number and are merged 
+  back to dev.
+  - All new branches need a description in the change log, which has separate "Added", "Changed" and "Fixed" sections.
+
+### Supported branches with gitflow manager
+
+- **main**: Permanent, stable, (normally) protected branch used for deployment. Each commit has a new version. Merge 
+requests only come from release or hotfix branch.
+- **dev**: Permanent development branch. Gets merge requests from feature, hotfix and release branch.
+- **release/vX.X.X**: Release branch. Branched off from dev branch with new minor or major version. When the branch is
+finished, it is merged into main and dev branch. Intermediate merges into dev are allowed, too. Merges from dev into 
+release branch are not allowed.
+- **feature/xxxxxx**: For features to be developed. Branched off from dev branch and will be merged back into dev after 
+finishing feature.
+- **bugfix/xxxxxx**: For bugs to be fixed. Branched off from dev branch and will be merged back into dev after 
+finishing the fix.
+- **hotfix/vX.X.X**: Hotfix branch for fixes from deployed code. Branched off from main branch with new hotfix 
+version. When done, is merged into main and dev branch.
+
+### Tagging
+
+- Currently, tagging is not done automatically. You can configure yourself a CI pipeline, that does the job for you.
+
+## Getting started
+
+### Installation
+
+1. Install gitflow manager with pip: `pip install gitflow-manager`
+2. Restart terminal
+
+### Usage
+
+- When using the first time, run `gfm --init` in the root of the project.
+- Subsequently, just type `gfm` each time you need to branch or merge (or add change log information), and follow the 
+dialog

gitflow_manager-1.0.1/gitflow_manager/__init__.py

@@ -0,0 +1 @@
+__version__="1.0.1"

gitflow_manager-1.0.1/gitflow_manager/changelog.py

@@ -0,0 +1,280 @@
+import json
+import os
+from copy import deepcopy
+from datetime import datetime
+from enum import Enum
+
+import pystache
+
+
+class Sections(Enum):
+    """
+    Enumerator to define possible change log sections
+    """
+
+    added = "Added"
+    changed = "Changed"
+    fixed = "Fixed"
+
+
+class ChangeLog:
+    """
+    A class to create a formatted markdown change log from a mustache template and the changes as json
+    """
+
+    def __init__(
+        self,
+        file: str = "docs/source/change_log.rst",
+        template_file: str = "docs/source/change_log.tpl",
+        compare_url=None,
+        version_prefix: str = "",
+    ):
+        """
+
+        :param file: File name of the change log file. Has to have the rst ending
+        :param template_file:  File name of the change log template. Has to be in mustache format
+        :param compare_url: Git url that is used to compare commits/branches with each other. Mostly ends with /compare/
+        :param version_prefix: Optional prefix that will be added to the version string before creating the log data
+        """
+        assert file.endswith(".rst"), 'Change log file name has to end with ".rst"'
+        self.file_name = file
+        self.data = {}
+        if not os.path.isfile(self.file_name.replace(".rst", ".json")):
+            self.create_empty_json()
+        if not os.path.isfile(template_file):
+            self.create_default_tpl(template_file)
+        self.read_json()
+        self.compare_url = compare_url
+        self.version_prefix = version_prefix
+        with open(template_file) as fh:
+            self.template = fh.read()
+        self.renderer = pystache.Renderer()
+
+    @staticmethod
+    def create_default_tpl(template_file):
+        with open(template_file, "w") as fh:
+            fh.write(
+                "{{#general}}\n"
+                "{{{title}}}\n"
+                "------------------\n"
+                "{{{description}}}\n"
+                "{{/general}}\n\n"
+                "{{#versions}}\n"
+                "{{{version}}}\n"
+                "-------------\n"
+                "**Release Date:** {{{date}}}\n\n"
+                "{{#sections}}\n"
+                "{{{label}}}\n"
+                "~~~~~~~~~~~~~\n"
+                "{{#entries}}\n"
+                "- {{{message}}} [{{{author}}}]\n"
+                "{{/entries}}\n\n"
+                "{{/sections}}\n"
+                "{{/versions}}\n\n"
+                "Changes comparison\n"
+                "------------------\n"
+                "{{#version_comparison}}\n"
+                "- **[{{version}}]**: `<{{{url}}}>`_\n"
+                "{{/version_comparison}}\n"
+            )
+
+    def create_empty_json(self):
+        json_path = self.file_name.replace(".rst", ".json")
+        os.makedirs(os.path.dirname(json_path), exist_ok=True)
+        with open(json_path, "w") as fh:
+            json.dump({"versions": []}, fh, indent=4)
+
+    def read_json(self):
+        """
+        Read JSON data from a file and ensure version info is sorted in descending date order.
+
+        """
+        with open(self.file_name.replace(".rst", ".json")) as fh:
+            data = json.load(fh)
+        # assert version info sorted in descending date order
+        data["versions"] = sorted(
+            data["versions"],
+            key=lambda x: x["date"] if x["date"] != "" else "Z",
+            reverse=True,
+        )
+        self.data = data
+
+    def write_json(self):
+        with open(self.file_name.replace(".rst", ".json"), "w") as fh:
+            json.dump(self.data, fh, indent=4)
+
+    def get_version(self, version: str) -> None | dict:
+        """
+        Returns a copy of the change log for the requested version
+
+        :param version: The requested version as string
+        :return: The version's change log as dict
+        """
+        for version_dict in self.data["versions"]:
+            if version_dict["version"] == self.version_prefix + version:
+                return deepcopy(version_dict)
+        return None
+
+    @staticmethod
+    def ask_for_changes(user: str, sections: list[Sections], app_specific_changes, app_specific_text) -> list:
+        """
+        This method asks interactively for changes and returns a section list ready to be handed over to ChangeLog
+
+        :param user: Name of the user, who did the changes. Should be the git user name if possible
+        :param sections: A list of sections that should be added
+        :param app_specific_changes:
+        :param app_specific_text:
+        :return: A list of sections and changes to add into ChangeLog.
+        """
+        section_list = []
+        for section in sections:
+            assert isinstance(section, Sections), 'List entries have to be values from the Enum "Sections"!'
+            sec_string = section.value
+            entries = []
+            while True:
+                if not app_specific_changes:
+                    answer = input(
+                        f"Any (more) changes to document for section \n'{sec_string}'\n? "
+                        f"(Type the change or enter nothing for continuing)\n"
+                    )
+                else:
+                    app_specific_text = app_specific_text.format(sec_string)
+                    answer = input(app_specific_text)
+                if answer == "":
+                    break
+                else:
+                    entries.append({"author": user, "message": answer})
+            if entries:
+                section_list.append({"label": sec_string, "entries": entries})
+        return section_list
+
+    @staticmethod
+    def _add_sections(version_dict: dict, sections: dict) -> dict:
+        """
+        Add sections and their entries to an existing version dictionary.
+
+        :param version_dict: The versions as a dictionary to which sections and entries will be added.
+        :param sections: A dictionary containing sections and their entries to be added to the versions.
+        :return: The updated version dictionary with sections and entries.
+        """
+        label_dict = {}
+        for n, section in enumerate(version_dict["sections"]):
+            label_dict[section["label"]] = n
+        for section in sections:
+            label = section["label"]
+            if label not in label_dict:
+                # create section
+                version_dict["sections"].append({"label": label, "entries": []})
+                label_dict[label] = len(version_dict["sections"]) - 1
+            # add all messages of unrel_dicts section to this section
+            version_dict["sections"][label_dict[label]]["entries"].extend(section["entries"])
+        return version_dict
+
+    def create_new_version(self, new_version: str, new_sections=None):
+        """
+        Adds a new version to the change log
+
+        :param new_version: String of the new version, such as v0.5.2 . If the changes are still for an unreleased \
+        state, use None!
+        :param new_sections: A formatted list of new_sections, obtained from method ask_for_changes
+        """
+        if new_version is None or new_version=="Unreleased":
+            new_version = "Unreleased"
+        else:
+            new_version = self.version_prefix + new_version
+        date_ = datetime.now().strftime("%Y-%m-%d %H:%M") if new_version != "Unreleased" else ""
+
+        found = False
+        # search for existing version with same string (forbidden) or Unreleased tag (will be moved into new version)
+        for version_dict in self.data["versions"]:
+            # remember, self.data is a dict (i.e. mutable) so all changes directly apply to it
+            if version_dict["version"] == new_version and new_version != "Unreleased":
+                raise Exception(
+                    f"Version {new_version} already exists! Use method add_to_version if you want to add "
+                    f"sections to an existing version!"
+                )
+            elif version_dict["version"] == "Unreleased":
+                found = True
+                version_dict["version"] = new_version
+                version_dict["date"] = date_
+                if new_sections is not None:
+                    # add new sections. No need to get result as dicts are mutable
+                    self._add_sections(version_dict, new_sections)
+
+        if not found:
+            if new_sections is None:
+                raise Exception(
+                    "No entry found for Unreleased version and no new version information added. "
+                    "Adding empty new version is not allowed!"
+                )
+            else:
+                self.data["versions"].insert(0, {"version": new_version, "date": date_, "sections": new_sections})
+
+        # update the json file
+        self.write_json()
+
+    def add_to_version(self, version: str | None, new_sections):
+        """
+        Adds change logs to an existing version
+
+        :param version: String of the version to add changes to, such as v0.5.2 . If the changes are still for an \
+        unreleased state, use None!
+        :param new_sections: A formatted list of new_sections, obtained from method ask_for_changes
+        """
+        if version is None or version=="Unreleased":
+            version = "Unreleased"
+        else:
+            version = self.version_prefix + version
+        found = False
+        for version_dict in self.data["versions"]:
+            # remember, self.data is a dict (i.e. mutable) so all changes directly apply to it
+            if version_dict["version"] == version:
+                found = True
+                # add new sections. No need to get result as dicts are mutable
+                self._add_sections(version_dict, new_sections)
+
+        if not found:
+            if version == "Unreleased":
+                self.create_new_version(new_version=version, new_sections=new_sections)
+            else:
+                raise Exception(
+                    f"No entry found for version {version}! If you want to create a new version, use method "
+                    "create_new_version!"
+                )
+
+        # update the json file
+        self.write_json()
+
+    def _add_branch_comparison(self, data: dict):
+        """
+        Add a list of comparisons between commits/branches in data dictionary.
+        :param data: The dictionary to which the comparison info will be added, also contains the version info
+        :return: The updated data dictionary with branch comparison information.
+        """
+        if self.compare_url is not None:
+            if "version_comparison" in data:
+                data.pop("version_comparison")
+            # assumes the dict is ordered by date!!
+            newer_version = None
+            comparison_list = []
+            for version_dict in data["versions"]:
+                if newer_version is None:
+                    newer_version = version_dict["version"]
+                else:
+                    comparison_list.append(
+                        {
+                            "version": newer_version,
+                            "url": f"{self.compare_url}/diff?targetBranch=tags/{version_dict['version']}&sourceBranch="
+                            f"{'tags/'+newer_version if newer_version != 'Unreleased' else 'heads/dev'}",
+                        }
+                    )
+            data["version_comparison"] = comparison_list
+        return data
+
+    def write_log(self):
+        """
+        Write changes to the ChangeLog file.
+        """
+        extended_data = self._add_branch_comparison(self.data)
+        with open(self.file_name, "w") as fh:
+            fh.write(self.renderer.render(self.template, extended_data))

gitflow_manager-1.0.1/gitflow_manager/errors.py

@@ -0,0 +1,2 @@
+class GitFlowManagerError(Exception):
+    pass

gitflow_manager-1.0.1/gitflow_manager/file_utils.py

@@ -0,0 +1,35 @@
+import toml
+
+
+def read_file(path: str):
+    """Read a file and return the content.
+
+    :param path: _description_
+    :type path: str
+    """
+    with open(path, encoding="utf8") as file:
+        file_content = file.read()
+    return file_content
+
+
+def write_to_file(path: str, content):
+    """Write given content to the path.
+
+    :param path: _description_
+    :type path: str
+    :param content: _description_
+    :type content: _type_
+    """
+    with open(path, "w", encoding="utf8") as fhh:
+        fhh.write(content)
+
+
+def read_toml(path):
+    with open(path, encoding="utf8") as file:
+        content = toml.load(file)
+    return content
+
+
+def write_to_toml(path: str, content):
+    with open(path, "w", encoding="utf8") as file:
+        toml.dump(content, file)