feat: print the change report, either nicely formatted or JSON

Author: mxmehl

gh_org_mgr/_gh_org.py

@@ -27,7 +27,7 @@
 from ._helpers import (
     compare_two_dicts,
     compare_two_lists,
-    pretty_print_dict,
+    dict_to_pretty_string,
     sluggify_teamname,
 )
 from ._stats import OrgChanges
@@ -122,7 +122,7 @@ def ratelimit(self):
 
     def pretty_print_dataclass(self) -> str:
         """Convert this dataclass to a pretty-printed output"""
-        return pretty_print_dict(asdict(self), sensible_keys=["gh_token", "gh_app_private_key"])
+        return dict_to_pretty_string(asdict(self), sensible_keys=["gh_token", "gh_app_private_key"])
 
     def _resolve_gh_username(self, username: str, teamname: str) -> NamedUser | None:
         """Turn a username into a proper GitHub user object"""
@@ -418,7 +418,7 @@ def sync_current_teams_settings(self, dry: bool = False) -> None:
                         logging.critical(
                             "Team '%s' settings could not be edited. Error: \n%s",
                             team.name,
-                            pretty_print_dict(exc.data),
+                            dict_to_pretty_string(exc.data),
                         )
                         sys.exit(1)
             else:

gh_org_mgr/_helpers.py

@@ -66,7 +66,7 @@ def compare_two_dicts(dict1: dict, dict2: dict) -> dict[str, dict[str, str | int
     return differences
 
 
-def pretty_print_dict(dictionary: dict, sensible_keys: None | list[str] = None) -> str:
+def dict_to_pretty_string(dictionary: dict, sensible_keys: None | list[str] = None) -> str:
     """Convert a dict to a pretty-printed output"""
 
     # Censor sensible fields
@@ -99,7 +99,7 @@ def pretty(d, indent=0):
 
 def pretty_print_dataclass(dc):
     """Convert dataclass to a pretty-printed output"""
-    pretty_print_dict(asdict(dc))
+    dict_to_pretty_string(asdict(dc))
 
 
 def implement_changes_into_class(dc_object, **changes: bool | str | list[str]):

gh_org_mgr/_stats.py

@@ -4,8 +4,11 @@
 
 """Dataclasses and functions for statistics"""
 
+import json
 from dataclasses import dataclass, field
 
+from ._helpers import implement_changes_into_class
+
 
 @dataclass
 class TeamChanges:  # pylint: disable=too-many-instance-attributes
@@ -35,12 +38,13 @@ class RepoChanges:  # pylint: disable=too-many-instance-attributes
 class OrgChanges:  # pylint: disable=too-many-instance-attributes
     """Dataclass holding general statistics about the changes made to the organization"""
 
+    dry: bool = False
     added_owners: list[str] = field(default_factory=list)
     degraded_owners: list[str] = field(default_factory=list)
-    teams: dict[str, TeamChanges] = field(default_factory=dict)
-    repos: dict[str, RepoChanges] = field(default_factory=dict)
     members_without_team: list[str] = field(default_factory=list)
     removed_members: list[str] = field(default_factory=list)
+    teams: dict[str, TeamChanges] = field(default_factory=dict)
+    repos: dict[str, RepoChanges] = field(default_factory=dict)
 
     # --------------------------------------------------------------------------
     # Owners
@@ -62,7 +66,7 @@ def update_team(self, team_name: str, **changes: bool | str | list[str]) -> None
         if team_name not in self.teams:
             self.teams[team_name] = TeamChanges()
 
-        implement_changes(dc_object=self.teams[team_name], **changes)
+        implement_changes_into_class(dc_object=self.teams[team_name], **changes)
 
     def create_team(self, team: str) -> None:
         """Team has been created"""
@@ -110,7 +114,7 @@ def update_repo(self, repo_name: str, **changes: bool | str | list[str]) -> None
         if repo_name not in self.teams:
             self.repos[repo_name] = RepoChanges()
 
-        implement_changes(dc_object=self.repos[repo_name], **changes)
+        implement_changes_into_class(dc_object=self.repos[repo_name], **changes)
 
     def change_repo_team_permissions(self, repo: str, team: str, perm: str) -> None:
         """Team permissions have been changed for a repo"""
@@ -128,21 +132,127 @@ def remove_repo_collaborator(self, repo: str, user: str) -> None:
         """Remove collaborator"""
         self.update_repo(repo_name=repo, removed_collaborators=user)
 
-
-def implement_changes(dc_object, **changes: bool | str | list[str]):
-    """Smartly add changes to a dataclass object"""
-    for attribute, value in changes.items():
-        current_value = getattr(dc_object, attribute)
-        # attribute is list
-        if isinstance(current_value, list):
-            # input change is list
-            if isinstance(value, list):
-                current_value.extend(value)
-            # input change is not list
-            else:
-                current_value.append(value)
-        # All other cases, bool
+    # --------------------------------------------------------------------------
+    # Output
+    # --------------------------------------------------------------------------
+    def changes_into_dict(self) -> dict:
+        """Convert dataclass to dict, and only use classes that are not empty/False"""
+        changes_dict: dict[str, list[str] | dict] = {
+            key: value  # type: ignore
+            for key, value in {
+                "dry": self.dry,
+                "added_owners": self.added_owners,
+                "degraded_owners": self.degraded_owners,
+                "members_without_team": self.members_without_team,
+                "removed_members": self.removed_members,
+                "teams": self.teams,
+                "repos": self.repos,
+            }.items()
+            if value  # Exclude empty values
+        }
+
+        team_changes: dict[str, TeamChanges] = changes_dict.get("teams", {})  # type: ignore
+        repo_changes: dict[str, RepoChanges] = changes_dict.get("repos", {})  # type: ignore
+
+        for team, tchanges in team_changes.items():
+            new_changes = {
+                key: value
+                for key, value in tchanges.__dict__.items()
+                if value  # Exclude empty values
+            }
+            team_changes[team] = new_changes  # type: ignore
+        changes_dict["teams"] = team_changes
+
+        for repo, rchanges in repo_changes.items():
+            new_changes = {
+                key: value
+                for key, value in rchanges.__dict__.items()
+                if value  # Exclude empty values
+            }
+            repo_changes[repo] = new_changes  # type: ignore
+        changes_dict["repos"] = repo_changes
+
+        return changes_dict
+
+    def print_changes(  # pylint: disable=too-many-branches, too-many-statements
+        self, orgname: str, output: str, dry: bool
+    ) -> None:
+        """Print the changes, either in pretty format or as JSON"""
+
+        # Add dry run information to stats dataclass
+        self.dry = dry
+
+        # Output in the requested format
+        if output == "json":
+            changes_dict = self.changes_into_dict()
+            print(json.dumps(changes_dict, indent=2))
         else:
-            setattr(dc_object, attribute, value)
-
-    return dc_object
+            output = (
+                f"#-------------------------------------{len(orgname)*'-'}\n"
+                f"# Changes made to GitHub organisation {orgname}\n"
+                f"#-------------------------------------{len(orgname)*'-'}\n\n"
+            )
+            if dry:
+                output += "⚠️ Dry-run mode, no changes executed\n\n"
+            if self.added_owners:
+                output += f"➕ Added owners: {', '.join(self.added_owners)}\n"
+            if self.degraded_owners:
+                output += f"🔻 Degraded owners: {', '.join(self.degraded_owners)}\n"
+            if self.members_without_team:
+                output += f"⚠️ Members without team: {', '.join(self.members_without_team)}\n"
+            if self.removed_members:
+                output += (
+                    f"❌ Members removed from organisation: {', '.join(self.removed_members)}\n"
+                )
+            if self.teams:
+                output += "\n🤝 Team Changes:\n"
+                for team, tchanges in self.teams.items():
+                    output += f"  🔹 {team}:\n"
+                    if tchanges.unconfigured:
+                        output += "    ⚠️ Is/was unconfigured\n"
+                    if tchanges.newly_created:
+                        output += "    🆕 Has been created\n"
+                    if tchanges.deleted:
+                        output += "    ❌ Has been deleted\n"
+                    if tchanges.changed_config:
+                        output += "    🔧 Changed config:\n"
+                        for item in tchanges.changed_config:
+                            output += f"      - {item}\n"
+                    if tchanges.added_members:
+                        output += "    ➕ Added members:\n"
+                        for item in tchanges.added_members:
+                            output += f"      - {item}\n"
+                    if tchanges.changed_members_role:
+                        output += '    🔄 Changed members role:"'
+                        for item in tchanges.changed_members_role:
+                            output += f"      - {item}\n"
+                    if tchanges.removed_members:
+                        output += "    ❌ Removed members:\n"
+                        for item in tchanges.removed_members:
+                            output += f"      - {item}\n"
+                    if tchanges.pending_members:
+                        output += "    ⏳ Pending members:\n"
+                        for item in tchanges.pending_members:
+                            output += f"      - {item}\n"
+            if self.repos:
+                output += "\n📂 Repository Changes:\n"
+                for repo, rchanges in self.repos.items():
+                    output += f"  🔹 {repo}:\n"
+                    if rchanges.changed_permissions_for_teams:
+                        output += "    🔧 Changed permissions for teams:\n"
+                        for item in rchanges.changed_permissions_for_teams:
+                            output += f"      - {item}\n"
+                    if rchanges.removed_teams:
+                        output += "    ❌ Removed teams:\n"
+                        for item in rchanges.removed_teams:
+                            output += f"      - {item}\n"
+                    if rchanges.unconfigured_teams_with_permissions:
+                        output += "    ⚠️ Unconfigured teams with permissions:\n"
+                        for item in rchanges.unconfigured_teams_with_permissions:
+                            output += f"      - {item}\n"
+                    if rchanges.removed_collaborators:
+                        output += "    ❌ Removed collaborators:\n"
+                        for item in rchanges.removed_collaborators:
+                            output += f"      - {item}\n"
+
+            print(output.strip())

gh_org_mgr/manage.py

@@ -40,6 +40,13 @@
     required=True,
     help="Path to the directory in which the configuration of an GitHub organisation is located",
 )
+parser_sync.add_argument(
+    "-o",
+    "--output",
+    help="Output format for report",
+    choices=["json", "text"],
+    default="text",
+)
 parser_sync.add_argument("--dry", action="store_true", help="Do not make any changes at GitHub")
 parser_sync.add_argument(
     "-A",
@@ -149,7 +156,9 @@ def main():
         logging.debug("Final dataclass:\n%s", org.pretty_print_dataclass())
         org.ratelimit()
 
-        print(org.stats)
+        org.stats.print_changes(
+            orgname=cfg_org.get("org_name", ""), output=args.output, dry=args.dry
+        )
 
     # Setup Team command
     elif args.command == "setup-team":