github-org-manager 0.3.1__tar.gz → 0.4.1__tar.gz

{github_org_manager-0.3.1 → github_org_manager-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: github-org-manager
-Version: 0.3.1
+Version: 0.4.1
 Summary: Manage a GitHub Organization, its teams, repository permissions, and more
 Home-page: https://github.com/OpenRailAssociation/github-org-manager
 License: Apache-2.0
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Version Control :: Git
 Classifier: Topic :: Utilities
 Requires-Dist: pygithub (>=2.3.0,<3.0.0)
+Requires-Dist: python-slugify (>=8.0.4,<9.0.0)
 Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Project-URL: Repository, https://github.com/OpenRailAssociation/github-org-manager
@@ -77,11 +78,16 @@ You may also be interested in the [live configuration of the OpenRail Associatio
 
 You can execute the program using the command `gh-org-mgr`. `gh-org-mgr --help` shows all available arguments and options.
 
-Some examples:
+Synchronisation examples:
 
-* `gh-org-mgr -c myorgconf`: synchronize the settings of the GitHub organization with your local configuration in the given configuration path (`myorgconf`). This may create new teams, remove/add members, and change permissions.
-* `gh-org-mgr -c myorgconf --dry`: as above, but do not make any modification. Perfect for testing your local configuration and see its potential effects.
-* `gh-org-mgr -c myorgconf --debug`: the first example, but show full debugging information.
+* `gh-org-mgr sync -c myorgconf`: synchronize the settings of the GitHub organization with your local configuration in the given configuration path (`myorgconf`). This may create new teams, remove/add members, and change permissions.
+* `gh-org-mgr sync -c myorgconf --dry`: as above, but do not make any modification. Perfect for testing your local configuration and see its potential effects.
+* `gh-org-mgr sync -c myorgconf --debug`: the first example, but show full debugging information.
+
+Setup team examples:
+
+* `gh-org-mgr setup-team -n "My Team Name" -c myorgconf`: Bootstrap a team configuration for this team name. Will create a file `myorgconf/teams/my-team-name.yaml`, or provide options if this file already exists.
+* `gh-org-mgr setup-team -n "My Team Name" -f path/to/myteam.yaml`: Bootstrap a team configuration for this team name and will force to write it in the given file. If the file already exists, offer some options.
 
 ## License
 

{github_org_manager-0.3.1 → github_org_manager-0.4.1}/README.md

@@ -50,11 +50,16 @@ You may also be interested in the [live configuration of the OpenRail Associatio
 
 You can execute the program using the command `gh-org-mgr`. `gh-org-mgr --help` shows all available arguments and options.
 
-Some examples:
+Synchronisation examples:
 
-* `gh-org-mgr -c myorgconf`: synchronize the settings of the GitHub organization with your local configuration in the given configuration path (`myorgconf`). This may create new teams, remove/add members, and change permissions.
-* `gh-org-mgr -c myorgconf --dry`: as above, but do not make any modification. Perfect for testing your local configuration and see its potential effects.
-* `gh-org-mgr -c myorgconf --debug`: the first example, but show full debugging information.
+* `gh-org-mgr sync -c myorgconf`: synchronize the settings of the GitHub organization with your local configuration in the given configuration path (`myorgconf`). This may create new teams, remove/add members, and change permissions.
+* `gh-org-mgr sync -c myorgconf --dry`: as above, but do not make any modification. Perfect for testing your local configuration and see its potential effects.
+* `gh-org-mgr sync -c myorgconf --debug`: the first example, but show full debugging information.
+
+Setup team examples:
+
+* `gh-org-mgr setup-team -n "My Team Name" -c myorgconf`: Bootstrap a team configuration for this team name. Will create a file `myorgconf/teams/my-team-name.yaml`, or provide options if this file already exists.
+* `gh-org-mgr setup-team -n "My Team Name" -f path/to/myteam.yaml`: Bootstrap a team configuration for this team name and will force to write it in the given file. If the file already exists, offer some options.
 
 ## License
 

{github_org_manager-0.3.1 → github_org_manager-0.4.1}/gh_org_mgr/_gh_org.py

@@ -182,16 +182,16 @@ class GHorg:  # pylint: disable=too-many-instance-attributes
         self._get_org_members()
 
         # Get open invitations
-        open_invitations = [user.login for user in self.org.invitations()]
+        open_invitations = [user.login.lower() for user in self.org.invitations()]
 
         for team, team_attrs in self.current_teams.items():
             # Update current team members with dict[NamedUser, str (role)]
             team_attrs["members"] = self._get_current_team_members(team)
 
             # For the rest of the function however, we use just the login name
-            # for each current user
+            # for each current user. All lower-case
             current_team_members = {
-                user.login: role for user, role in team_attrs["members"].items()
+                user.login.lower(): role for user, role in team_attrs["members"].items()
             }
 
             # Handle the team not being configured locally
@@ -209,16 +209,17 @@ class GHorg:  # pylint: disable=too-many-instance-attributes
             else:
                 team_configuration = {}
 
-            # Analog to team_attrs["members"], add members and maintainers to shared
-            # dict with respective role, while maintainer role dominates
+            # Analog to team_attrs["members"], add members and maintainers to
+            # shared dict with respective role, while maintainer role dominates.
+            # All user names shall be lower-case to ease comparison
             configured_users: dict[str, str] = {}
             for config_role in ("member", "maintainer"):
                 team_members = self._get_configured_team_members(
                     team_configuration, team.name, config_role
                 )
                 for team_member in team_members:
-                    # Add user with role to dict
-                    configured_users.update({team_member: config_role})
+                    # Add user with role to dict, in lower-case
+                    configured_users.update({team_member.lower(): config_role})
 
             # Consider all GitHub organisation team maintainers if they are member of the team
             # This is because GitHub API returns them as maintainers even if they are just members
@@ -227,7 +228,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes
                     logging.debug(
                         "Overriding role of organisation owner '%s' to maintainer", user.login
                     )
-                    configured_users[user.login] = "maintainer"
+                    configured_users[user.login.lower()] = "maintainer"
 
             # Only make edits to the team membership if the current state differs from config
             if configured_users == current_team_members:
@@ -278,8 +279,11 @@ class GHorg:  # pylint: disable=too-many-instance-attributes
             # Loop through all current members. Remove them if they are not configured
             for current_user in current_team_members:
                 if current_user not in configured_users:
+                    logging.debug("User '%s' not found within configured users", current_user)
                     # Turn user to GitHub object, trying to find them
                     if not (gh_user := self._resolve_gh_username(current_user, team.name)):
+                        # If the user cannot be found for some reason, log an
+                        # error and skip this loop
                         continue
                     if team.has_in_members(gh_user):
                         logging.info(
@@ -471,7 +475,13 @@ class GHorg:  # pylint: disable=too-many-instance-attributes
         """Combine multiple lists into one while removing duplicates"""
         complete = []
         for single_list in lists:
-            complete.extend(single_list)
+            if single_list is not None:
+                complete.extend(single_list)
+            else:
+                logging.debug(
+                    "A list that we attempted to extend to another was None. "
+                    "This probably happened because a 'member:' or 'maintainer:' key was left empty"
+                )
 
         return list(set(complete))
 
@@ -561,7 +571,7 @@ class GHorg:  # pylint: disable=too-many-instance-attributes
                             )
                         )
                     else:
-                        self.configured_repos_collaborators[repo][team_member] = perm
+                        self.configured_repos_collaborators[repo][team_member.lower()] = perm
 
     def _convert_graphql_perm_to_rest(self, permission: str) -> str:
         """Convert a repo permission coming from the GraphQL API to the ones
@@ -627,12 +637,12 @@ class GHorg:  # pylint: disable=too-many-instance-attributes
 
         # Extract relevant data
         for collaborator in collaborators:
-            login = collaborator["node"]["login"]
+            login: str = collaborator["node"]["login"]
             # Skip entry if collaborator is org owner, which is "admin" anyway
-            if login in [user.login for user in self.org_owners]:
+            if login.lower() in [user.login.lower() for user in self.org_owners]:
                 continue
             permission = self._convert_graphql_perm_to_rest(collaborator["permission"])
-            self.current_repos_collaborators[repo][login] = permission
+            self.current_repos_collaborators[repo][login.lower()] = permission
 
     def _get_current_repos_and_user_perms(self):
         """Get all repos, their current collaborators and their permissions"""

github_org_manager-0.4.1/gh_org_mgr/_setup_team.py

@@ -0,0 +1,118 @@
+# SPDX-FileCopyrightText: 2024 DB Systel GmbH
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Functions to help with setting up new team"""
+
+import logging
+from os.path import isfile, join
+from string import Template
+
+from slugify import slugify
+
+TEAM_TEMPLATE = """
+${team_name}:
+  # parent:
+  # repos:
+  # maintainer:
+  member:
+"""
+
+
+def _sanitize_two_exclusive_options(option1: str | None, option2: str | None) -> bool:
+    """Only of of these two options must be provided (not None, empty string is
+    OK). Returns True if no error ocourred"""
+    # There must not be a file_path and config_path provided at the same time
+    if option1 is not None and option2 is not None:
+        logging.critical("The two options must not be provided at the same time. Choose only one.")
+        return False
+    # There must at least be config_path or file_path configured
+    if option1 is None and option2 is None:
+        logging.critical("One of the two options must be provided")
+        return False
+
+    return True
+
+
+def _fill_template(template: str, **fillers) -> str:
+    """Fill a template using a dicts with keys and their values. The function
+    looks for the keys starting with '$' characters"""
+    return Template(template).substitute(fillers).lstrip()
+
+
+def _ask_user_action(question: str, *options: str) -> str:
+    """Ask the user a question and for an action. Return the chosen action."""
+    option_dict: dict[str, str] = {}
+    option_questions: list[str] = []
+    for option in options:
+        # Get first unique characters from the option
+        short = ""
+        i = 0
+        while not short:
+            i += 1
+            short_try = option[:i]
+            if short_try not in option_dict:
+                short = short_try
+                option_questions.append(option.replace(short, f"[{short}]", 1))
+                option_dict[option] = option
+                option_dict[short] = option
+
+    response = ""
+    while response not in option_dict:
+        response = input(f"{question} ({'/'.join(option_questions)}): ")
+
+    return option_dict[response]
+
+
+def write_file(file: str, content: str, append: bool = False) -> None:
+    """Write to a file. Overrides by default, but can also append"""
+    mode = "a" if append else "w"
+    try:
+        with open(file, mode=mode, encoding="UTF-8") as writer:
+            # Add linebreak if using append mode
+            if mode == "a":
+                writer.write("\n")
+
+            # Add content to file
+            writer.write(content)
+    except FileNotFoundError as exc:
+        logging.critical("File %s could not be written: %s", file, exc)
+
+
+def setup_team(
+    team_name: str, config_path: str | None = None, file_path: str | None = None
+) -> None:
+    """Set up a new team inside the config dir with a given name"""
+    _sanitize_two_exclusive_options(config_path, file_path)
+
+    # Come up with file name based on team name in the given config directory
+    if not file_path:
+        # Combine config dir and file name
+        file_path = join(config_path, "teams", slugify(team_name) + ".yaml")  # type: ignore
+        logging.debug("Derived file path: %s", file_path)
+
+    # Fill template
+    yaml_content = _fill_template(TEAM_TEMPLATE, team_name=team_name)
+
+    # If file already exists, ask if file should be extended or overridden, or abort
+    if isfile(file_path):
+        options = ("override", "append", "print", "skip")
+        action = _ask_user_action(
+            f"The file {file_path} exists, what would you like to do?", *options
+        )
+
+        logging.debug("Chosen action: %s", action)
+
+        if action == "skip":
+            print("No action taken")
+        elif action == "print":
+            print()
+            print(yaml_content)
+        elif action in ("override", "append"):
+            append = action == "append"
+            write_file(file=file_path, content=yaml_content, append=append)
+
+    # File does not exist, write file
+    else:
+        print(f"Writing team configuration into {file_path}")
+        write_file(file=file_path, content=yaml_content)

github_org_manager-0.4.1/gh_org_mgr/manage.py

@@ -0,0 +1,131 @@
+# SPDX-FileCopyrightText: 2024 DB Systel GmbH
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Manage a GitHub Organization, its teams, repository permissions, and more"""
+
+import argparse
+import logging
+import sys
+
+from . import __version__, configure_logger
+from ._config import parse_config_files
+from ._gh_org import GHorg
+from ._setup_team import setup_team
+
+# Main parser with root-level flags
+parser = argparse.ArgumentParser(
+    description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter
+)
+parser.add_argument(
+    "--version", action="version", version="GitHub Organization Manager " + __version__
+)
+
+# Initiate first-level subcommands
+subparsers = parser.add_subparsers(dest="command", help="Available commands", required=True)
+
+# Common flags, usable for all effective subcommands
+common_flags = argparse.ArgumentParser(add_help=False)  # No automatic help to avoid duplication
+common_flags.add_argument("--debug", action="store_true", help="Get verbose logging output")
+
+# Sync commands
+parser_sync = subparsers.add_parser(
+    "sync",
+    help="Synchronise GitHub organization settings and teams",
+    parents=[common_flags],
+)
+parser_sync.add_argument(
+    "-c",
+    "--config",
+    required=True,
+    help="Path to the directory in which the configuration of an GitHub organisation is located",
+)
+parser_sync.add_argument("--dry", action="store_true", help="Do not make any changes at GitHub")
+parser_sync.add_argument(
+    "-A",
+    "--ignore-archived",
+    action="store_true",
+    help="Do not take any action in ignored repositories",
+)
+
+# Setup Team
+parser_create_team = subparsers.add_parser(
+    "setup-team",
+    help="Helps with setting up a new team using a base template",
+    parents=[common_flags],
+)
+parser_create_team.add_argument(
+    "-n",
+    "--name",
+    required=True,
+    help="Name of the team that shall be created",
+)
+parser_create_team_file = parser_create_team.add_mutually_exclusive_group(required=True)
+parser_create_team_file.add_argument(
+    "-c",
+    "--config",
+    help=(
+        "Path to the directory in which the configuration of an GitHub organisation is located. "
+        "If this option is used, the tool will automatically come up with a file name"
+    ),
+)
+parser_create_team_file.add_argument(
+    "-f",
+    "--file",
+    help="Path to the file in which the team shall be added",
+)
+# parser_create_team.add_argument(
+#     "-a",
+#     "--file-exists-action",
+#     help="Define which action shall be taken when the requested output file already exists",
+#     choices=["override", "extend", "skip"]
+# )
+
+
+def main():
+    """Main function"""
+
+    # Process arguments
+    args = parser.parse_args()
+
+    configure_logger(args.debug)
+
+    # Sync command
+    if args.command == "sync":
+        if args.dry:
+            logging.info("Dry-run mode activated, will not make any changes at GitHub")
+
+        org = GHorg()
+
+        # Parse configuration folder, and do sanity check
+        cfg_org, cfg_app, org.configured_teams = parse_config_files(args.config)
+        if not cfg_org.get("org_name"):
+            logging.critical(
+                "No GitHub organisation name configured in organisation settings. Cannot continue"
+            )
+            sys.exit(1)
+
+        # Login to GitHub with token, get GitHub organisation
+        org.login(cfg_org.get("org_name", ""), cfg_app.get("github_token", ""))
+        # Get current rate limit
+        org.ratelimit()
+
+        # Create teams that aren't present at Github yet
+        org.create_missing_teams(dry=args.dry)
+        # Synchronise the team memberships
+        org.sync_teams_members(dry=args.dry)
+        # Report about organisation members that do not belong to any team
+        org.get_members_without_team()
+        # Synchronise the permissions of teams for all repositories
+        org.sync_repo_permissions(dry=args.dry, ignore_archived=args.ignore_archived)
+        # Remove individual collaborator permissions if they are higher than the one
+        # from team membership (or if they are in no configured team at all)
+        org.sync_repo_collaborator_permissions(dry=args.dry)
+
+        # Debug output
+        logging.debug("Final dataclass:\n%s", org.df2json())
+        org.ratelimit()
+
+    # Setup Team command
+    elif args.command == "setup-team":
+        setup_team(team_name=args.name, config_path=args.config, file_path=args.file)

{github_org_manager-0.3.1 → github_org_manager-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [tool.poetry]
 name = "github-org-manager"
-version = "0.3.1"
+version = "0.4.1"
 description = "Manage a GitHub Organization, its teams, repository permissions, and more"
 authors = ["Max Mehl <max.mehl@deutschebahn.com>"]
 readme = "README.md"
@@ -30,6 +30,7 @@ python = "^3.10"
 pygithub = "^2.3.0"
 pyyaml = "^6.0.1"
 requests = "^2.32.3"
+python-slugify = "^8.0.4"
 
 [tool.poetry.group.dev.dependencies]
 black = "^24.3.0"
@@ -38,6 +39,7 @@ mypy = "^1.9.0"
 pylint = "^3.1.0"
 types-pyyaml = "^6.0.12.20240311"
 types-requests = "^2.32.0.20240712"
+bump-my-version = "^0.26.0"
 
 [build-system]
 requires = ["poetry-core"]
@@ -58,3 +60,16 @@ files = ["gh_org_mgr/*.py"]
 # Pylint
 [tool.pylint.'MESSAGES CONTROL']
 disable = "fixme"
+
+# Bump-My-Version
+[tool.bumpversion]
+commit = true
+tag = true
+allow_dirty = false
+tag_name = "v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+regex = true
+search = "^version = \"{current_version}\""
+replace = "version = \"{new_version}\""

github_org_manager-0.3.1/gh_org_mgr/manage.py

@@ -1,75 +0,0 @@
-# SPDX-FileCopyrightText: 2024 DB Systel GmbH
-#
-# SPDX-License-Identifier: Apache-2.0
-
-"""Manage a GitHub Organization, its teams, repository permissions, and more"""
-
-import argparse
-import logging
-import sys
-
-from . import __version__, configure_logger
-from ._config import parse_config_files
-from ._gh_org import GHorg
-
-parser = argparse.ArgumentParser(
-    description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter
-)
-parser.add_argument(
-    "-c",
-    "--config",
-    required=True,
-    help="Path to the directory in which the configuration of an GitHub organisation is located",
-)
-parser.add_argument("--debug", action="store_true", help="Get verbose logging output")
-parser.add_argument("--dry", action="store_true", help="Do not make any changes at GitHub")
-parser.add_argument(
-    "-A",
-    "--ignore-archived",
-    action="store_true",
-    help="Do not take any action in ignored repositories",
-)
-parser.add_argument("--version", action="version", version="GitHub Team Manager " + __version__)
-
-
-def main():
-    """Main function"""
-
-    # Process arguments
-    args = parser.parse_args()
-
-    configure_logger(args.debug)
-
-    if args.dry:
-        logging.info("Dry-run mode activated, will not make any changes at GitHub")
-
-    org = GHorg()
-
-    # Parse configuration folder, and do sanity check
-    cfg_org, cfg_app, org.configured_teams = parse_config_files(args.config)
-    if not cfg_org.get("org_name"):
-        logging.critical(
-            "No GitHub organisation name configured in organisation settings. Cannot continue"
-        )
-        sys.exit(1)
-
-    # Login to GitHub with token, get GitHub organisation
-    org.login(cfg_org.get("org_name", ""), cfg_app.get("github_token", ""))
-    # Get current rate limit
-    org.ratelimit()
-
-    # Create teams that aren't present at Github yet
-    org.create_missing_teams(dry=args.dry)
-    # Synchronise the team memberships
-    org.sync_teams_members(dry=args.dry)
-    # Report about organisation members that do not belong to any team
-    org.get_members_without_team()
-    # Synchronise the permissions of teams for all repositories
-    org.sync_repo_permissions(dry=args.dry, ignore_archived=args.ignore_archived)
-    # Remove individual collaborator permissions if they are higher than the one
-    # from team membership (or if they are in no configured team at all)
-    org.sync_repo_collaborator_permissions(dry=args.dry)
-
-    # Debug output
-    logging.debug("Final dataclass:\n%s", org.df2json())
-    org.ratelimit()