added basic implementation

.gitignore

@@ -60,3 +60,10 @@ target/
 
 #Ipython Notebook
 .ipynb_checkpoints
+
+# Flask
+flask
+
+# IntelliJ
+*.iml
+.idea

README.md

@@ -0,0 +1,42 @@
+#Python Beacon
+
+##Contents
+
+* [What it is](#what-it-is)
+* [System requirements](#system-requirements)
+* [How to run it](#how-to-run-it)
+* [How it works](#how-it-works)
+* [Technologies](#technologies)
+
+##What it is
+This project contains BDK (beacon development kit) for Python developers. It provides a skeleton of a simple beacon allowing the developers to plug in their own data/functionality. The API makes sure the response produced is compatible with what the Beacon of Beacons can consume.
+
+##System requirements
+All you need to build this project is Python and Flask web framework. If you're running Linux, OS X or Windows with cygwin support, the following commands should be enough to set up Flask (the process is a bit different with the native version of Python on Windows):
+
+    $ cd todo-api
+    $ virtualenv flask
+    $ flask/bin/pip install flask
+
+##How to run it
+Launch beacon.py:
+
+    $ chmod a+x beacon.py
+    $ ./beacon.py
+
+This starts an embedded server. By default, the application will be available at <http://127.0.0.1:5000>
+
+##How it works
+In order to implement a beacon, simply override beacon details and query function in beacon.py (marked with TODO in the source code).
+
+The API takes care of the rest and provides the following endpoints when you start your beacon:
+
+    http://127.0.0.1:5000/beacon-python/info - information about your beacon
+    http://127.0.0.1:5000/beacon-python/query - access to query service
+
+Query example:
+
+    GET http://127.0.0.1:5000/beacon-python/query?chrom=15&pos=41087870&allele=A&ref=hg19
+
+##Technologies
+Python, Flask.

beacon.py

@@ -0,0 +1,213 @@
+#!flask/bin/python
+
+'''
+The MIT License
+
+Copyright 2014 DNAstack.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+'''
+
+from flask import Flask, jsonify, request
+
+
+class IncompleteQuery(Exception):
+    status_code = 400
+
+    def __init__(self, message, status_code=None, payload=None, ErrorResource=None, query=None, beacon_id=None):
+        Exception.__init__(self)
+        self.message = message
+        if status_code is not None:
+            self.status_code = status_code
+        self.payload = payload
+        self.ErrorResource = ErrorResource
+        self.query = query
+        self.beacon_id = beacon_id
+
+    def to_dict(self):
+        rv = dict(self.payload or ())
+        rv["beacon"] = self.beacon_id
+        rv["query"] = self.query
+        rv['error'] = self.ErrorResource
+        return rv
+
+
+app = Flask(__name__)
+
+# --------------- Information endpont (start) --------------------#
+
+# TODO: override with the details of your beacon
+
+########### DataSetResource for beacon details ############
+
+# required field(s): name
+DataUseRequirementResource = {
+    'name': u'example name',
+    'description': u'example description'
+}
+
+# required field(s): variants
+DataSizeResource = {
+    'variants': 1,  # integer
+    'samples': 1  # integer
+}
+
+# required field(s): category
+DataUseResource = {
+    'category': u'example use category',
+    'description': u'example description',
+    'requirements': [
+        DataUseRequirementResource
+    ]
+}
+
+# required field(s): id
+DataSetResource = {
+    'id': u'example Id',
+    'description': u'dataset description',
+    'reference': u'reference genome',
+    'size': DataSizeResource,  # Dimensions of the data set (required if the beacon reports allele frequencies)
+    'data_uses': [
+        DataUseResource  # Data use limitations
+    ]
+}
+
+########### QueryResource for beacon details ###############
+
+# required field(s): allele, chromosome, position, reference
+QueryResource = {
+    'allele': u'allele string',
+    'chromosome': u'chromosome Id',
+    'position': 1,  # integer
+    'reference': u'genome Id',
+    'dataset_id': u'dataset Id'
+}
+
+################### Beacon details #########################
+
+# required field(s): id, name, organization, api
+beacon = {
+    'id': u'foo',
+    'name': u'bar',
+    'organization': u'org',
+    'api': u'0.1/0.2',
+    'description': u'beacon description',
+    'datasets': [
+        DataSetResource  # Datasets served by the beacon
+    ],
+    'homepage': u'http://dnastack.com/ga4gh/bob/',
+    'email': u'[email protected]',
+    'auth': u'oauth2',  # OAUTH2, defaults to none
+    'queries': [
+        QueryResource  # Examples of interesting queries
+    ]
+}
+
+
+# --------------- Information endpoint (end) ----------------------#
+
+# info function
+@app.route('/beacon-python/info', methods=['GET'])
+def info():
+    return jsonify(beacon)
+
+
+# query function
+# TODO: plug in the functionality of your beacon
+@app.route('/beacon-python/query', methods=['GET'])
+def query():
+    # parse query
+    chromosome = request.args.get('chrom')
+    position = long(request.args.get('pos'))
+    allele = request.args.get('allele')
+    reference = request.args.get('ref')
+    dataset = request.args.get('dataset') if 'dataset' in request.args else beacon['datasets'][0]['id']
+
+    # ---- TODO: override with the necessary response details  ----#
+
+    ############## AlleleResource for response ###############
+
+    # required field(s): allele
+    AlleleResource = {
+        'allele': allele,
+        'frequency': 0.5  # double between 0 & 1
+    }
+
+    ############# ErrorResource for response #################
+
+    # required field(s): name
+    ErrorResource = {
+        'name': u'error name/code',
+        'description': u'error message'
+    }
+
+    ################### Response object #########################
+
+    # generate response
+    # required field(s): exists
+    response = {
+        'exists': True,
+        'observed': 0,  # integer, min 0
+        'alleles': [
+            AlleleResource
+        ],
+        'info': u'response information',
+    }
+
+    query = {
+        'chromosome': chromosome,
+        'position': position,
+        'allele': allele,
+        'reference': reference,
+        'dataset_id': dataset
+    }
+
+    if query['chromosome'] is None or query['position'] is None or query['allele'] is None or query[
+        'reference'] is None:
+        ErrorResource['description'] = 'Required parameters are missing'
+        ErrorResource['name'] = 'Incomplete Query'
+        raise IncompleteQuery('IncompleteQuery', status_code=410, ErrorResource=ErrorResource, query=query,
+                              beacon_id=beacon["id"])
+
+    # --------------------------------------------------------------#
+
+    return jsonify({"beacon": beacon['id'], "query": query, "response": response})
+
+
+# info function
+@app.route('/beacon-python/', methods=['GET'])
+def welcome():
+    return 'WELCOME!!! Beacon of Beacons Project (BoB) provides a unified REST API to publicly available GA4GH Beacons. BoB standardizes the way beacons are accessed and aggregates their results, thus addressing one of the missing parts of the Beacon project itself. BoB was designed with ease of programmatic access in mind. It provides XML, JSON and plaintext responses to accommodate needs of all the clients across all the programming languages. The API to use is determined using the header supplied by the client in its GET request, e.g.: "Accept: application/json".'
+
+
+# required parameters missing
+@app.errorhandler(IncompleteQuery)
+def handle_invalid_usage(error):
+    response = jsonify(error.to_dict())
+    return response
+
+
+# page not found
+@app.errorhandler(404)
+def not_found(error):
+    return 'Page not found (Bad URL)', 404
+
+
+if __name__ == '__main__':
+    app.run()