Flask Github Proxy¶

What ?¶

Flask Github proxy is a flask extension to provide saving resources to GitHub. To use this service, you will need a github token (Generate token : https://github.com/settings/tokens )

Installation¶

To install it, simply do : pip3 install flask_github_proxy or

git clone https://github.com/ponteineptique/flask-github-proxy.git
cd flask-github-proxy
python3 setup.py install

Example¶

from flask import Flask
from flask_github_proxy import GithubProxy
from flask_github_proxy.models import Author

app = Flask("name")
proxy = GithubProxy(
    "/proxy",
    "ponteineptique/dummy1",
    "alpheios-project/dummy1",
    secret="something",
    token="Github Token",
    app=app,
    origin_branch="master",
    default_author=Author(
        "Github Proxy",
        "anonymous@github.com"
    )
)
app.run()

Funding and original development¶

This python software has originally been developed in the context of the Syriaca Project, under the funding of NEH.

Index :

Flask Github Proxy API Documentation¶

Extension¶

class flask_github_proxy.GithubProxy(prefix, origin, upstream, secret, token, default_branch=None, master_upstream='master', master_fork='master', app=None, default_author=None, logger=None, json_log_formatting=True)[source]¶

Provides routes to push files to github and open pull request as a service

Generate token : https://github.com/settings/tokens

You can use GithubProxy.DEFAULT_BRANCH.NO and GithubProxy.DEFAULT_BRANCH.AUTO_SHA to build branch name automatically.

Default user is GithubProxy.DEFAULT_AUTHOR

Parameters:

prefix – URI Prefix
origin – Origin Repository (Repository to Pull Request From)
upstream – Upstream Repository (Repository to Pull Request To)
secret – Secret Key. Used to check provenance of data
token – Github Authentification User Token
default_branch (str) – Default Branch to push to
pull_req – Origin Branch to build on
master_fork – Origin Repository Master Branch Name (Branch to update on the fork using the finale repositoru)
master_upstream – Upstream Repository Master Branch Name (Branch to Pull Request to)
app – Flask Application to connect to
default_author (Author) – Default Author for Commit and Modification

Variables:

URLS – URLS routes of the proxy
DEFAULT_AUTHOR – Default Author
blueprint – Flask Blueprint Instance for the Extension
prefix – Prefix of the Blueprint
name – Name of the Blueprint
origin – Git Repository to pull request from
upstream – Git Repository to pull request to
default_author – Default Author
secret – Secret / Salt used to check provenance of data to be pushed

class DEFAULT_BRANCH[source]¶

Parameter Constant for the default_branch parameter

Variables:	NO – Default Branch is equal to origin branch AUTO_SHA – Generate a sha based on the file to create the branch

class GithubProxy.ProxyError(code, message, step=None, context=None)¶

Carries information for errors

Parameters:	code (int) – HTTP Code Error message (str or tuple) – Message to display or a dict and its key
Variables:	code – HTTP Code Error message – Message to display

static AdvancedJsonify(data, status_code)¶

Advanced Jsonify Response Maker

Parameters:	data – Data status_code – Status_code
Returns:	Response

response(callback=None)¶

View representation of the object

Parameters:	callback (function) – Function to represent the error in view. Default : flask.jsonify
Returns:	View

GithubProxy.check_sha(sha, content)[source]¶

Check sent sha against the salted hash of the content

Parameters:	sha – SHA sent through fproxy-secure-hash header content – Base 64 encoded Content
Returns:	Boolean indicating equality

GithubProxy.default_branch(file)[source]¶

Decide the name of the default branch given the file and the configuration

Parameters:	file – File with informations about it
Returns:	Branch Name

GithubProxy.get(file)[source]¶

Check on github if a file exists

Parameters:	file – File to check status of
Returns:	File with new information, including blob, or Error
Return type:	File or self.ProxyError

GithubProxy.get_ref(branch, origin=None)[source]¶

Check if a reference exists

Parameters:	branch – The branch to check if it exists
Returns:	Sha of the branch if it exists, False if it does not exist, self.ProxyError if it went wrong

GithubProxy.init_app(app)[source]¶

Initialize the application and register the blueprint

Parameters:	app – Flask Application
Returns:	Blueprint of the current nemo app
Return type:	flask.Blueprint

GithubProxy.make_ref(branch)[source]¶

Make a branch on github

Parameters:	branch – Name of the branch to create
Returns:	Sha of the branch or self.ProxyError

GithubProxy.patch_ref(sha)[source]¶

Patch reference on the origin master branch

Parameters:	sha – Sha to use for the branch
Returns:	Status of success
Return type:	str or self.ProxyError

GithubProxy.pull_request(file)[source]¶

Create a pull request

Parameters:	file – File to push through pull request
Returns:	URL of the PullRequest or Proxy Error

GithubProxy.put(file)[source]¶

Create a new file on github

Parameters:	file – File to create
Returns:	File or self.ProxyError

GithubProxy.r_main()[source]¶

Main Route of the API

Returns:	Response

GithubProxy.r_receive(filename)[source]¶

Function which receives the data from Perseids

Check the branch does not exist

Make the branch if needed

Receive PUT from Perseids

Check if content exist

Update/Create content

Open Pull Request

Return PR link to Perseids

It can take a “branch” URI parameter for the name of the branch

Parameters:	filename – Path for the file
Returns:	JSON Response with status_code 201 if successful.

GithubProxy.r_update()[source]¶

Updates a fork Master

Check the ref of the origin repository

Patch reference of fork repository

Return status to Perseids

Returns:	JSON Response with status_code 201 if successful.

GithubProxy.request(method, url, **kwargs)[source]¶

Unified method to make request to the Github API

Parameters:	method – HTTP Method to use url – URL to reach kwargs – dictionary of arguments (params for URL parameters, data for post/put data)
Returns:	Response

GithubProxy.update(file)[source]¶

Make an update query on Github API for given file

Parameters:	file – File to update, with its content
Returns:	File with new information, including success (or Error)

Models¶

class flask_github_proxy.models.File(path, content, author, date, logs)[source]¶

File Representation

Parameters:	path (str) – Path of the file on the repository content (byte) – Base64 encoded content of the file author (Author) – Author of the file date (str) – Date of the modification logs (str) – Message about the modification (Usually for commit message)
Variables:	path – Path of the file on the repository content – Content of the file base64 – Base64 Encoded Content of the file author – Author of the file date – Date of the modification sha – Sha hash of the content

dict()[source]¶

Builds a dictionary representation of the object (eg: for JSON)

Returns:	Dictionary representation of the object

class flask_github_proxy.models.Author(name, email)[source]¶

The author models carries information about committer and data modifiers.

Note

It behaves as a “static” object : its variables are private one and only getters are registered.

Parameters:	name (str) – Name of the user email (str) – Email of the user
Variables:	name – Name of the user email – Email of the user