Remote API¶
This API layer provides direct access to the Github storage layer through the remote OAuth API calls.
Main entry point for interacting with remote service APIs
-
pskb_website.remote.check_rate_limit()[source]¶ Get rate limit data
Returns: None in case of an error or raw rate limit request data
-
pskb_website.remote.commit_file_to_github(path, message, content, name, email, sha=None, branch=u'master', auto_encode=True)[source]¶ Save given file content to github
Parameters: - path – Path to file (<owner>/<repo>/<dir>/…/<filename>)
- message – Commit message to save file with
- content – Content of file
- name – Name of author who wrote file
- email – Email address of author
- sha – Optional SHA of file if it already exists on github
- branch – Name of branch to commit file to (branch must already exist)
- auto_encode – Boolean to automatically encode data as utf-8
Returns: SHA of commit or None for failure
Note that name and email can be None if you want to make a commit with the REPO_OWNER. However, name and email should both exist or both be None, which is a requirement of the underlying Github API.
-
pskb_website.remote.commit_image_to_github(path, message, file_, name, email, sha=None, branch=u'master')[source]¶ Save given image file content to github
Parameters: - path – Path to file (<owner>/<repo>/<dir>/…/<filename>)
- message – Commit message to save file with
- file – Open file object
- name – Name of author who wrote file
- email – Email address of author
- sha – Optional SHA of file if it already exists on github
- branch – Name of branch to commit file to (branch must already exist)
Returns: SHA of commit or None for failure
-
pskb_website.remote.contents_url_from_path(path)[source]¶ Get github API url for contents of file from full path
Parameters: path – Path to file (<owner>/<repo>/<dir>/…/<filename>) Returns: URL suitable for a content call with github API
-
pskb_website.remote.contributor_stats(repo_path=None)[source]¶ Get response of /repos/<repo_path>/stats/contributors from github.com
Parameters: repo_path – Default repo or repo path in owner/repo_name form Returns: Raw response of contributor stats from https://developer.github.com/v3/repos/statistics/#get-contributors-list-with-additions-deletions-and-commit-counts Note the github caches contributor results so an empty list can also be returned if the data is not available yet or there is an error
-
pskb_website.remote.create_branch(repo_path, name, sha)[source]¶ Create a new branch
Parameters: - repo_path – Path to repo that branch should be created from
- name – Name of branch to create
- sha – SHA to branch from
Returns: True if branch was created or False if branch already exists or could not be created
-
pskb_website.remote.file_contributors(path, branch=u'master')[source]¶ Get dictionary of User objects representing authors and committers to a file
Parameters: - path – Short-path to file (<dir>/…/<filename>) i.e. without repo and owner
- base – Name of branch to read contributors for
Returns: Dictionary of the following form:
{'authors': set([(name, login), (name, login), ...]),
’committers’: set([(name, login), (name, login), …])}
Note that name can be None if user doesn’t have their full name setup on github account.
-
class
pskb_website.remote.file_details(path, branch, sha, last_updated, url, text)¶ -
branch¶ Alias for field number 1
-
last_updated¶ Alias for field number 3
-
path¶ Alias for field number 0
-
sha¶ Alias for field number 2
-
text¶ Alias for field number 5
-
url¶ Alias for field number 4
-
-
pskb_website.remote.file_details_from_github(path, branch=u'master', allow_404=False)[source]¶ Get file details from github
Parameters: - path – Path to file (<owner>/<repo>/<dir>/…/<filename>)
- branch – Name of branch to read file from
- allow_404 – False to log warning for 404 or True to allow it i.e. when you’re just seeing if a file already exists
Returns: file_details namedtuple or None for error
-
pskb_website.remote.files_from_github(repo, filename, limit=None)[source]¶ Iterate through files with a specific name from github
Parameters: - repo – Path to repo to read files from
- filename – Name of filename to search for recursively
- limit – Optional limit of the number of files to return
Returns: Iterator through file_details tuples
-
pskb_website.remote.log_error(message, url, resp, **kwargs)[source]¶ Log an error from a request and include URL, response status, response data and additional error information
Params message: Message to log
Parameters: - url – URL of request that failed
- resp – Response object holding failure information
- kwargs – Additional data to put in error message
Returns: None
-
pskb_website.remote.merge_branch(repo_path, base, head, message)[source]¶ Attempt merge between two branches
Parameters: - repo_path – Path to repo <owner>/<repo_name>
- base – Name of the base branch that the head will be merged into
- head – The name of the head to merge into base
- message – Commit message to use for merge
Returns: True if merge was successful False otherwise
-
pskb_website.remote.primary_github_email_of_logged_in()[source]¶ Get primary email address of logged in user
-
pskb_website.remote.read_branch(repo_path, name)[source]¶ Read branch and get HEAD sha
Parameters: - repo_path – Path to repo of branch
- name – Name of branch to read
Returns: SHA of HEAD or None if branch is not found
-
pskb_website.remote.read_file_from_github(path, branch=u'master', rendered_text=True, allow_404=False)[source]¶ Get rendered file text from github API
Parameters: - path – Path to file (<owner>/<repo>/<dir>/…/<filename>)
- branch – Name of branch to read file from
- rendered_text – Return rendered or raw text
- allow_404 – False to log warning for 404 or True to allow it i.e. when you’re just seeing if a file already exists
Returns: file_details namedtuple or None if error
Note when requesting rendered text there will be no SHA or last_updated data available. This is a restriction from the github API (https://developer.github.com/v3/media/#repository-contents) Requesting file ‘details’ like SHA and rendered text are 2 API calls. Therefore, if you want all of that information you should call this function twice, once with rendered_text=True and one with rendered_text=False and combine the information yourself.
-
pskb_website.remote.read_repo_collaborators_from_github(owner=None, repo=None)[source]¶ Generator for collaborator login/usernames for a given repo
Parameters: - owner – Owner of repository defaults to REPO_OWNER config value
- repo – Name of repository defaults to REPO_NAME config value
Returns: Generator through login names
-
pskb_website.remote.read_user_from_github(username=None)[source]¶ Read user information from github
Parameters: username – Optional username to search for, if no username given the currently logged in user will be returned (if any) Returns: Dict of information from github API call
-
pskb_website.remote.remove_file_from_github(path, message, name, email, branch)[source]¶ Remove file from github repo
Parameters: - path – Path to file (<owner>/<repo>/<dir>/…/<filename>)
- message – Commit message to remove file with
- name – Name of author who wrote file
- email – Email address of author
- branch – Name of branch to delete file from
Returns: True if file was removed or False otherwise
Note the file is only removed from the repository, not the history of the file.
-
pskb_website.remote.rendered_markdown_from_github(path, branch=u'master', allow_404=False)[source]¶ Get rendered markdown file text from github API
Parameters: - path – Path to file (<owner>/<repo>/<dir>/…/<filename.md>)
- branch – Name of branch to read file from
- allow_404 – False to log warning for 404 or True to allow it i.e. when you’re just seeing if a file already exists
Returns: HTML file text
-
pskb_website.remote.repo_sha_from_github(repo, branch=u'master')[source]¶ Get sha from head of given repo
Parameters: - repo – Path to repo (owner/repo_name)
- branch – Name of branch to get sha for
Returns: Sha of branch
