Merge pull request #22 from mitodl/feature/create_team

Add library function and action to manage a team

README.rst

@@ -30,9 +30,9 @@ just install directory from github.com with ``pip install
 git+https://github.com/mitodl/orcoursetrion``.
 
 Once installed, create or acquire an `OAUTH2 token from github
-<https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. That
-at least has the ``repo``, ``write:repo_hook``, and ``write:org``
-permissions.
+<https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
+That at least has the ``repo``, ``write:repo_hook``, ``admin:org``,
+and ``write:org`` permissions.
 
 Add the environment variable ``ORC_GH_OAUTH2_TOKEN=<your token>``
 to your environment, and run ``orcoursetrion --help`` for available

docs/command.rst

@@ -16,7 +16,7 @@ repo that it just created for you.
 
 
 Available Actions
-=================
+~~~~~~~~~~~~~~~~~
 
 :create_export_repo:
 
@@ -30,4 +30,14 @@ Available Actions
    :py:attr:`~orcoursetrion.config.ORC_XML_DEPLOY_TEAM` and a command
    line specified team added to repository.  It will also set up a git
    hook to the URL specified with
-   :py:attr:`~orcoursetrion.config.ORC_STAGING_GITRELOAD`.
+   :py:attr:`~orcoursetrion.config.ORC_STAGING_GITRELOAD`. The
+   membership of the team can also be specified, and will replace the
+   existing membership of the team if it already exists.
+
+:put_team:
+
+   This will create or update a team specified in the specified
+   organization.  If the team doesn't exist, there is an option to
+   give the team either push or pull access, otherwise the
+   ``read_only`` flag is ignored.  It optionally takes a list of
+   members of the team that should replace the existing team.

orcoursetrion/actions/__init__.py

@@ -4,11 +4,13 @@
 """
 from orcoursetrion.actions.github import (
     create_export_repo,
-    create_xml_repo
+    create_xml_repo,
+    put_team
 )
 
 
 __all__ = [
     'create_export_repo',
     'create_xml_repo',
+    'put_team',
 ]

orcoursetrion/actions/github.py

@@ -15,6 +15,11 @@ def create_export_repo(course, term, description=None):
     and with collabarator
     :py:const:`~orcoursetrion.config.ORC_STUDIO_DEPLOY_TEAM`
 
+    Raises:
+        requests.RequestException
+        orcoursetrion.lib.GitHubUnknownError
+        orcoursetrion.lib.GitHubNoTeamFound
+        orcoursetrion.lib.GitHubRepoExists
     Args:
         course (str): Course name to be used to name repo (i.e. 6.004r)
         term (str): Term the course is expected to run (i.e. 2015_Spring)
@@ -40,24 +45,34 @@ def create_export_repo(course, term, description=None):
     return repo
 
 
-def create_xml_repo(course, term, team, description=None):
+def create_xml_repo(course, term, team, members=None, description=None):
     """Creates a course repo at
     :py:const:`~orcoursetrion.config.ORC_GH_API_URL` with key
     :py:const:`~orcoursetrion.config.ORC_GH_OAUTH2_TOKEN` and at
     organization :py:const:`~orcoursetrion.config.ORC_XML_ORG`, and
     with ``team`` as a collaborator (Along with
     :py:const:`~orcoursetrion.config.ORC_XML_DEPLOY_TEAM`).
 
+    If ``members`` is provided, the ``team`` membership will be
+    *replaced* with the members listed.  It will also create the team if
+    it doesn't already exist regardless of the value of ``members``.
+
     This also adds a github Web hook to the course development
     environment `gitreload <https://github.com/mitodl/gitreload>`_
     server via
     :py:const:`~orcoursetrion.config.ORC_STAGING_GITRELOAD`.
 
+    Raises:
+        requests.RequestException
+        orcoursetrion.lib.GitHubUnknownError
+        orcoursetrion.lib.GitHubNoTeamFound
+        orcoursetrion.lib.GitHubRepoExists
     Args:
         course (str): Course name to be used to name repo (i.e. 6.004r)
         term (str): Term the course is expected to run (i.e. 2015_Spring)
         team (str): Name of an organizational team that already exists to
                     add read/write access to this repo.
+        members (list): Exclusive list of usernames that should be on the team.
         description (str): Optional description for repo to show up on github
     Returns:
         dict: Github dictionary of a repo
@@ -72,12 +87,41 @@ def create_xml_repo(course, term, team, description=None):
         term=term
     )
     repo = github.create_repo(config.ORC_XML_ORG, repo_name, description)
-    github.add_team_repo(config.ORC_XML_ORG, repo_name, team)
+    # Add to the deployment team
     github.add_team_repo(
         config.ORC_XML_ORG, repo_name, config.ORC_XML_DEPLOY_TEAM
     )
+    # Setup the passed in team
+    github.put_team(config.ORC_XML_ORG, team, False, members)
+    github.add_team_repo(config.ORC_XML_ORG, repo_name, team)
 
+    # Add the hook
     github.add_web_hook(
         config.ORC_XML_ORG, repo_name, config.ORC_STAGING_GITRELOAD
     )
     return repo
+
+
+def put_team(org, team, read_only, members):
+    """Create or update a team with the list of ``members``.
+
+    If ``members`` is None, the team will be created if it doesn't
+    exist, but membership will not be changed.
+
+    Args:
+        org (str): Organization that owns/should own the team.
+        team (str): Name of the team.
+        read_only (bool): True if pull access, False if push access
+        members (list): Exclusive list of usernames that should be on the team.
+    Raises:
+        requests.RequestException
+        orcoursetrion.lib.GitHubUnknownError
+        orcoursetrion.lib.GitHubRepoExists
+    Returns:
+        dict: Github team dictionary
+                (https://developer.github.com/v3/orgs/teams/#response-1)
+
+    """
+    github = GitHub(config.ORC_GH_API_URL, config.ORC_GH_OAUTH2_TOKEN)
+    team = github.put_team(org, team, read_only, members)
+    return team

orcoursetrion/cmd.py

@@ -22,7 +22,7 @@ def run_create_export_repo(args):
 def run_create_xml_repo(args):
     """Run the create_xml_repo action using args"""
     repo = actions.create_xml_repo(
-        args.course, args.term, args.team, args.description
+        args.course, args.term, args.team, args.member, args.description
     )
     print(
         'Newly created repository for XML course created at {0}'.format(
@@ -31,6 +31,14 @@ def run_create_xml_repo(args):
     )
 
 
+def run_put_team(args):
+    """Run the put_teams action using args"""
+    actions.put_team(
+        args.org, args.team, args.read_only, args.member
+    )
+    print('Team successfully modified/created.')
+
+
 def execute():
     """Execute command line orcoursetrion actions.
     """
@@ -81,12 +89,39 @@ def execute():
         '-g', '--team', type=str, required=True,
         help='Name of team in organization that should have access'
     )
+    create_xml_repo.add_argument(
+        '-m', '--member', nargs='*', type=str,
+        help='One or more usernames to replace the membership of the team'
+    )
     create_xml_repo.add_argument(
         '-d', '--description', type=str,
         help='Description string to set for repository'
     )
     create_xml_repo.set_defaults(func=run_create_xml_repo)
 
+    # Create/Modify Team
+    put_team = subparsers.add_parser(
+        'put_team',
+        help='Create or modify a team in an organization'
+    )
+    put_team.add_argument(
+        '-o', '--org', type=str, required=True,
+        help='Organization for the team'
+    )
+    put_team.add_argument(
+        '-g', '--team', type=str, required=True,
+        help='Name of team in organization that should have access'
+    )
+    put_team.add_argument(
+        '-r', '--read_only', dest='read_only', action='store_true',
+        help='Team should only have pull access to repositories'
+    )
+    put_team.add_argument(
+        '-m', '--member', nargs='*', type=str,
+        help='One or more usernames to replace the membership of the team'
+    )
+    put_team.set_defaults(func=run_put_team)
+
     # Run the action
     args = parser.parse_args()
     args.func(args)