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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: github-org-manager
-Version: 0.3.1
+Version: 0.4.0
 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.0}/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.4.0/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.0/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.0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [tool.poetry]
 name = "github-org-manager"
-version = "0.3.1"
+version = "0.4.0"
 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"
+bump2version = "^1.0.1"
 
 [build-system]
 requires = ["poetry-core"]

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()