Orcoursetrion API Docs¶

For convenient reference in development, here are the Orcoursetrion API docs.

Actions¶

The actions that are available to use.

Action library access

orcoursetrion.actions.create_export_repo(course, term, description=None)¶

Creates a studio based course repo at ORC_GH_API_URL with key ORC_GH_OAUTH2_TOKEN, at organization ORC_STUDIO_ORG, and with collabarator ORC_STUDIO_DEPLOY_TEAM

Raises:	`requests.RequestException` `orcoursetrion.lib.GitHubUnknownError` `orcoursetrion.lib.GitHubNoTeamFound` `orcoursetrion.lib.GitHubRepoExists`
Parameters:	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) description (str) – Optional description for repo to show up on github
Returns:	Github dictionary of a repo (https://developer.github.com/v3/repos/#create)
Return type:	dict

orcoursetrion.actions.rerun_studio(course, term, new_term, description=None)¶

Run any actions needed to re-run a Studio course.

This will remove the hooks from the specified term, and then create a new export repo for the new_term. It finds the repo based on ORC_STUDIO_ORG as the organization, ORC_COURSE_PREFIX as the prefix, replacing all the dots in course and appending “-term”.

Parameters:	course (str) – Course name to be used to name repo (i.e. 6.004r) term (str) – Term the course is last run (i.e. 2015_Spring) new_term (str) – Term the course is expected to run again (i.e. 2018_Spring) description (str) – Optional description for repo to show up on github
Raises:	`requests.RequestException` `orcoursetrion.lib.GitHubRepoDoesNotExist` `orcoursetrion.lib.GitHubUnknownError`
Returns:	Github dictionary of the newly created repo (https://developer.github.com/v3/repos/#create)
Return type:	dict

orcoursetrion.actions.release_studio(course, term)¶

Moves a studio course to be ready for production.

Currently this will just add a hook to the production server, but it will eventually take care of everything else needed for a transfer as well.

Parameters:	course (str) – Course name of the repo to release to production (i.e. 6.001) term (str) – Term the course is currently running in (i.e. 2015_Spring)
Raises:	`requests.RequestException` `orcoursetrion.lib.GitHubUnknownError`
Returns:	Nothing returned, raises on failure
Return type:	None

orcoursetrion.actions.create_xml_repo(course, term, team=None, members=None, description=None)¶

Creates a course repo at ORC_GH_API_URL with key ORC_GH_OAUTH2_TOKEN and at organization ORC_XML_ORG, and with team as a collaborator (Along with ORC_XML_DEPLOY_TEAM).

If team is not provided, then it will be generated with ORC_COURSE_PREFIX, course, and term

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 server via ORC_STAGING_GITRELOAD.

Raises:	`requests.RequestException` `orcoursetrion.lib.GitHubUnknownError` `orcoursetrion.lib.GitHubNoTeamFound` `orcoursetrion.lib.GitHubRepoExists`
Parameters:	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:	Github dictionary of a repo (https://developer.github.com/v3/repos/#create)
Return type:	dict

orcoursetrion.actions.rerun_xml(course, term)¶

Run any actions needed to re-run an XML course.

Currently this only deletes the Web hooks, but eventually it will also copy the repo to a history clean one, and setup up that new one with hooks. It finds the repo based on ORC_XML_ORG as the organization, ORC_COURSE_PREFIX as the prefix, replacing all the dots in course and appending “-term”.

Parameters:	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)
Raises:	`requests.RequestException` `orcoursetrion.lib.GitHubUnknownError`
Returns:	Number of hooks removed
Return type:	int

orcoursetrion.actions.release_xml(course, term)¶

Moves an XML course to be ready for production.

Currently this will just add a hook to the production server, but it will eventually take care of everything else needed for a transfer as well (i.e. making live branch, import it to lms...).

Parameters:	course (str) – Course name of the repo to release to production (i.e. 6.001) term (str) – Term the course is currently running in (i.e. 2015_Spring)
Raises:	`requests.RequestException` `orcoursetrion.lib.GitHubUnknownError`
Returns:	Nothing returned, raises on failure
Return type:	None

orcoursetrion.actions.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.

Parameters:	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:	Github team dictionary (https://developer.github.com/v3/orgs/teams/#response-1)
Return type:	dict

Library¶

API libraries.

Orchestrion library

class orcoursetrion.lib.GitHub(api_url, oauth2_token)¶

Bases: object

API class for handling calls to github

Initialize a requests session for use with this class by specifying the base API endpoint and key.

Parameters:	api_url (str) – Github API URL such as https://api.github.com/ oauth2_token (str) – Github OAUTH2 token for v3

add_repo_file(org, repo, committer, message, path, contents)¶

Adds the contents provided to the path in the repo specified and committed by the commiter parameters provided.

https://developer.github.com/v3/repos/contents/#create-a-file

Note

This commits directly to the default branch of the repo.

Parameters:	org (str) – Organization the repo lives in. repo (str) – The name of the repo. committer (dict) – {‘name’: ..., ‘email’: ...} for the name and e-mail to use in the initial commit of the destination repo. message (str) – Commit message to use for the addition. path (str) – The content path, i.e. `docs/.gitignore` contents (str) – The actual string Contents of the file.
Raises:	`requests.exceptions.RequestException` `GitHubRepoDoesNotExist` `GitHubUnknownError`
Returns:	None

add_team_repo(org, repo, team)¶

Add a repo to an existing team (by name) in the specified org.

We first look up the team to get its ID (https://developer.github.com/v3/orgs/teams/#list-teams), and then add the repo to that team (https://developer.github.com/v3/orgs/teams/#add-team-repo).

Parameters:	org (str) – Organization to create the repo in. repo (str) – Name of the repo to create. team (str) – Name of team to add.
Raises:	`GitHubNoTeamFound` `GitHubUnknownError` `requests.exceptions.RequestException`

add_web_hook(org, repo, url)¶

Adds an active hook to a github repository.

This utilizes https://developer.github.com/v3/repos/hooks/#create-a-hook to create a form type Web hook that responds to push events (basically all the defaults).

Parameters:	org (str) – Organization to create the repo in. repo (str) – Name of the repo the hook will live in. url (str) – URL of the hook to add.
Raises:	`GitHubUnknownError` `requests.exceptions.RequestException`
Returns:	Github dictionary of a hook (https://developer.github.com/v3/repos/hooks/#response-2)
Return type:	dict

create_repo(org, repo, description)¶

Creates a new github repository or raises exceptions

Parameters:	org (str) – Organization to create the repo in. repo (str) – Name of the repo to create. description (str) – Description of repo to use.
Raises:	`GitHubRepoExists` `GitHubUnknownError` `requests.exceptions.RequestException`
Returns:	Github dictionary of a repo (https://developer.github.com/v3/repos/#create)
Return type:	dict

delete_web_hooks(org, repo)¶

Delete all the Web hooks for a repository

Uses https://developer.github.com/v3/repos/hooks/#list-hooks to get a list of all hooks, and then runs https://developer.github.com/v3/repos/hooks/#delete-a-hook to remove each of them. :param org: Organization to create the repo in. :type org: str :param repo: Name of the repo to remove hooks from. :type repo: str

Raises:	`GitHubUnknownError` `GitHubRepoDoesNotExist` `requests.exceptions.RequestException`
Returns:	Number of hooks removed
Return type:	int

put_team(org, team_name, read_only, members)¶

Create a team in a github organization.

Utilize https://developer.github.com/v3/orgs/teams/#list-teams, https://developer.github.com/v3/orgs/teams/#create-team, https://developer.github.com/v3/orgs/teams/#list-team-members, https://developer.github.com/v3/orgs/teams/#add-team-membership, and https://developer.github.com/v3/orgs/teams/#remove-team-membership. to create a team and/or replace an existing team’s membership with the members list.

Parameters:	org (str) – Organization to create the repo in. team_name (str) – Name of team to create. read_only (bool) – If false, read/write, if true read_only. members (list) – List of github usernames to add to the team. If none, membership changes won’t occur
Raises:	`GitHubUnknownError` `requests.RequestException`
Returns:	The team dictionary (https://developer.github.com/v3/orgs/teams/#response-1)
Return type:	dict

static shallow_copy_repo(src_repo, dst_repo, committer, branch=None)¶

Copies one branch repo’s contents to a new repo in the same organization without history.

Danger

This will overwrite the destination repo’s default branch and rewrite its history.

The basic workflow is:

Clone source repo
Remove source repo .git folder
Initialize as new git repo
Set identity
Add everything and commit
Force push to destination repo

Parameters:	src_repo (str) – Full git url to source repo. dst_repo (str) – Full git url to destination repo. committer (dict) – {‘name’: ..., ‘email’: ...} for the name and e-mail to use in the initial commit of the destination repo. branch (str) – Option branch, if not specified default is used.
Raises:	`sh.ErrorReturnCode`
Returns:	None

exception orcoursetrion.lib.GitHubException¶

Bases: exceptions.Exception

Base exception class others inherit.

exception orcoursetrion.lib.GitHubRepoExists¶

Bases: orcoursetrion.lib.github.GitHubException

Repo exists, and thus cannot be created.

exception orcoursetrion.lib.GitHubRepoDoesNotExist¶

Bases: orcoursetrion.lib.github.GitHubException

Repo does not exist, and therefore actions can’t be taken on it.

exception orcoursetrion.lib.GitHubUnknownError¶

Bases: orcoursetrion.lib.github.GitHubException

Unexpected status code exception

exception orcoursetrion.lib.GitHubNoTeamFound¶

Bases: orcoursetrion.lib.github.GitHubException

Name team not found in list

Configuration¶

Configuration options

Configuration needed for Orchestrion to function (i.e. API keys)

config.ORC_GH_OAUTH2_TOKEN = GitHub OAUTH2 Token¶

config.ORC_GH_API_URL = GitHub API URL¶

config.ORC_GH_NAME = Git committer name to use.¶

config.ORC_GH_EMAIL = Git committer e-mail to use¶

config.ORC_COURSE_PREFIX = Prefix to use in repository name¶

config.ORC_STUDIO_ORG = Organization to use for Studio export repos¶

config.ORC_STUDIO_DEPLOY_TEAM = Deployment team for Studio Export repos¶

config.ORC_XML_ORG = Organization to use for XML/latex2edx courses¶

config.ORC_XML_DEPLOY_TEAM = Deployment team for XML/latex2edx courses¶

config.ORC_STAGING_GITRELOAD = `gitreload <https://github.com/mitodl/gitreload>`_ server URL (including username and password) for the course development LMS.¶

config.ORC_PRODUCTION_GITRELOAD = `gitreload <https://github.com/mitodl/gitreload>`_ server URL (including username and password) for the course production LMS.¶