githubhandler¶
Wrappers for Github Web-API Bindings
Functions
|
Creates ISO 8601 timestamp in format |
Classes
|
GitHubHandler using Aiohttp for HTTP requests |
|
ContentType for Project Cards |
|
Conclusion of Github Check Run |
State of Github Check Run |
|
|
Adds get(path) method to Github Webhook event |
|
Handles interaction with Github as App |
|
Handles interaction with GitHub |
|
State for Github Issues |
|
Merge method |
|
Pull request review state |
Documentation
- class bioconda_utils.githubhandler.IssueState(value)¶
State for Github Issues
- bioconda_utils.githubhandler.CheckRunStatus¶
State of Github Check Run
- class bioconda_utils.githubhandler.CheckRunConclusion(value)¶
Conclusion of Github Check Run
- class bioconda_utils.githubhandler.MergeMethod(value)¶
Merge method
- class bioconda_utils.githubhandler.ReviewState(value)¶
Pull request review state
- class bioconda_utils.githubhandler.CardContentType(value)¶
ContentType for Project Cards
- bioconda_utils.githubhandler.iso_now()[source]¶
Creates ISO 8601 timestamp in format
YYYY-MM-DDTHH:MM:SSZ
as required by Github- Return type:
- class bioconda_utils.githubhandler.GitHubHandler(token=None, dry_run=False, to_user='bioconda', to_repo='bioconda-recipes', installation=None)[source]¶
Handles interaction with GitHub
- Parameters:
- STATE¶
alias of
IssueState
- token¶
API Bearer Token
- dry_run¶
If set, no actual modifying actions are taken
- installation¶
The installation ID if this instance is connected to an App
- user¶
Owner of the Repo
- repo¶
Name of the Repo
- var_default¶
Default variables for API calls
- api: GitHubAPI¶
Gidgethub API object
- property rate_limit: RateLimit¶
Last recorded rate limit data
- Return type:
RateLimit
- get_file_relurl(path, branch_name='master')[source]¶
Format domain relative url for path on branch_name
- Return type:
- async iter_teams()[source]¶
List organization teams
- Return type:
AsyncIterator
[Dict
[str
,Any
]]- Returns:
Async iterator over dicts, containing id, name, slug, description, etc.
- async get_team_id(team_slug=None, team_name=None)[source]¶
Get the Team ID from the Team slug
If both are set, team_slug is tried first.
- async search_issues(author=None, pr=False, issue=False, sha=None, closed=None)[source]¶
Search issues/PRs on our repos
- Parameters:
author – login name of user to search
sha – SHA of commit to search for
pr – whether to consider only PRs
issue – whether to consider only non-PR issues
closed – search only closed if true, only open if false
- async get_pr_count(user)[source]¶
Get the number of PRs opened by user
- Parameters:
user – login of user to query
- Return type:
- Returns:
Number of PRs that user has opened so far
- async get_prs_from_sha(head_sha, only_open=False)[source]¶
Searches for PRs matching head_sha
- Parameters:
head_sha (
str
) – The head checksum to search foronly_open – If true, return only open PRs
- Result:
List of PR numbers.
- get_prs(from_branch=None, from_user=None, to_branch=None, number=None, state=None)[source]¶
Retrieve list of PRs matching parameters
- Parameters:
- Return type:
- async create_pr(title, from_branch, from_user=None, to_branch='master', body=None, maintainer_can_modify=True, draft=False)[source]¶
Create new PR
- Parameters:
title (
str
) – Title of new PRfrom_branch (
str
) – Name of branch from which PR asks to pull (aka head)from_user (
Optional
[str
]) – Name of user/org in from which to pullto_branch (
Optional
[str
]) – Name of branch into which to pull (aka base, default: master)maintainer_can_modify (
bool
) – Whether to allow maintainer to modify from_branchdraft (
bool
) – whether PR is draft
- Return type:
- async merge_pr(number, title=None, message=None, sha=None, method=MergeMethod.squash)[source]¶
Merge a PR
- Parameters:
- Returns:
True if successful and message
- Return type:
Tuple
- async pr_is_merged(number)[source]¶
Checks whether a PR has been merged
- Parameters:
number – PR Number
- Return type:
- Returns:
True if the PR has been merged.
- async pr_update_branch(number)[source]¶
Updates PR branch
Merges changes to “base” into “head”
- Return type:
- async modify_issue(number, labels=None, title=None, body=None)[source]¶
Modify existing issue (PRs are issues)
- async create_check_run(name, head_sha, details_url=None, external_id=None)[source]¶
Create a check run
- async modify_check_run(number, status=None, conclusion=None, output_title=None, output_summary=None, output_text=None, output_annotations=None, actions=None)[source]¶
Modify a check runs
- Parameters:
number (
int
) – id number of check runstatus (
Optional
[CheckRunState
]) – current statusconclusion (
Optional
[CheckRunConclusion
]) – result of check run, needed if status is completedoutput_title (
Optional
[str
]) – title string for result windowoutput_summary (
Optional
[str
]) – subtitle/summary string for result window (reqired if title given)output_text (
Optional
[str
]) – Markdown text for result windowannotations – List of annotated code pieces, each has to have
path
,start_line
andend_line
,annotation_level
(notice
,warning
,failure
), and amessage
. May also have may havestart_column
andend_column
(if only one line),title
andraw_details
.actions (
Optional
[List
[Dict
]]) – List of up to three “actions” as dict oflabel
,description
andidentifier
- Return type:
- Returns:
Check run “object” as dict.
- async get_branch_protection(branch='master')[source]¶
Retrieve protection settings for branch
- Parameters:
branch (
str
) – Branch for which to get protection settings- Return type:
- Returns:
Deep dict as example below. Protections not in place will not be present in dict.
required_status_checks: # require status checks to pass strict: False # require PR branch to be up to date with base contexts: # list of status checks required - bioconda-test enforce_admins: # admins, too, must follow rules - enabled: True required_pull_request_reviews: # require approving review required_approving_review_count: 1 # 1 - 6 valid dismiss_stale_reviews: False # auto dismiss approval after push require_code_owner_reviews: False dismissal_restrictions: # specify who may dismiss reviews users: - login: bla teams: - id: 1 - name: Bl Ub - slug: bl-ub restrictions: # specify who may push users: - login: bla teams: - id: 1 enforce_admins: enabled: True # apply to admins also
- async check_protections(pr_number, head_sha=None)[source]¶
Check whether PR meets protection requirements
- async create_project_card(column_id, note=None, content_id=None, content_type=None, number=None)[source]¶
Create a new project card
In addition to column_id, you must provide either:
The note parameter for a free text note card
The content_type specifying whether the card references a PR or an Issue, and the content_id with the id field from the PR or Issue. Note that PRs have two IDs, once as their issue baseclass and once as PR. You must use the latter for PRs.
The number giving either PR or Issue number. Will trigger one or two extra API calls to fill in the content_type and content_id fields.
- Parameters:
- Return type:
- Returns:
Dict describing newly created card. Empty if no card.
- class bioconda_utils.githubhandler.AiohttpGitHubHandler(token=None, dry_run=False, to_user='bioconda', to_repo='bioconda-recipes', installation=None)[source]¶
GitHubHandler using Aiohttp for HTTP requests
- Parameters:
session – Aiohttp Client Session object
requester – Identify self (e.g. user agent)
- api: GitHubAPI¶
Gidgethub API object
- class bioconda_utils.githubhandler.Event(data, *, event, delivery_id)[source]¶
Adds get(path) method to Github Webhook event
- class bioconda_utils.githubhandler.GitHubAppHandler(session, app_name, app_key, app_id, client_id, client_secret)[source]¶
Handles interaction with Github as App
- Parameters:
session (
ClientSession
) – Use this session to make calls to the Github APIapp_name (
str
) – The name of the App. This is also used as HTTP user agent identifier.app_key (
str
) – A PEM key used to sign JWT to obtain temporary bearer tokens for accessing the Github API.app_id (
str
) – This number identifies our App at Github.client_id (
str
) – This number identifies our App at Github when logging in on behalf of users via OAUTH.client_secret (
str
) – The secret authenticating us when logging in on behalf of users via OAUTH
- INSTALLATION_TOKEN = '/app/installations/{installation_id}/access_tokens'¶
Github API url for creating an access token for a specific installation of an app.
- INSTALLATION = '/repos/{owner}/{repo}/installation'¶
Get installation info
- JWT_RENEW_PERIOD = 600¶
Lifetime of JWT in seconds
- DOMAIN = 'https://github.com'¶
Base URL for calls to oauth login
- AUTHORIZE = '/login/oauth/authorize{?client_id,client_secret,redirect_uri,state,login}'¶
URL template for calls to OAUTH authorize
- ACCESS_TOKEN = '/login/oauth/access_token'¶
URL templete for calls to OAUTH access_token
- name¶
Name of app
- app_id¶
ID of app
- app_key¶
Authorization key
- client_id¶
OAUTH client ID
- client_secret¶
OAUTH client secret
- static parse_isotime(timestr)[source]¶
Converts UTC ISO 8601 time stamp to seconds in epoch
- Return type:
- async get_installation_token(installation, name=None)[source]¶
Returns OAUTH token for installation referenced in event
- Return type:
- async get_github_api(dry_run, to_user, to_repo, installation=None)[source]¶
Returns the GitHubHandler for the installation the event came from
- Return type:
- async get_github_user_api(token)[source]¶
Returns the GitHubHandler for a user given a token
- Return type:
- static generate_nonce(nbytes=16)[source]¶
Generates a random string
Fetches nbytes of random data from
os.urandom
and passes them through base64 encoding.
- async oauth_github_user(redirect, session, params)[source]¶
Acquires
AiohttpGitHubHandler
for user via OAuthThis must be called from an
aiohttp.web
server with theaiohttp-session
active for session management.If the user was not yet logged in (has no token in the session), this will raise a
web.HTTPFound
exception to redirect the user’s browser to Github where the app can be authorized to act on the users behalf. If the user OKs this, Github redirects the user back to the URL given in redirect. The code behind that URL should call this function again, passing the parameters from Github. Using those parameters, an OAUTH token is acquired, used to create anAiohttpGitHubHandler
object and that object initilized to fetch the users details (callinglogin
to acquire user name and avatar).- Details:
Two parameters are passed through the redirect calls. The state parameter is a nonce generated to avoid cross-site request forgery. It is stored in the users session and must be passed back identically on the second call. The code parameter is the secret used to acquire the OAUTH token on the second call to this method.
Two values are stored in the user’s session. The nonce mentioned above and the OAUTH token. A short path attempts to use an existing token to re-authenticate an already logged in user.
- Parameters:
redirect – URL to redirect to for authentication callback. Usually, this is the URL from which you called this function, so that it gets called again with the parameters send by GitHub.
session – Session for making calls to Github API
params – URL parameters that were sent by GitHub.
- Returns:
The API client object with the user logged in.