From 0e49dbb1c5db62f13c9b9d50ac61da5868e128ba Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Tue, 12 Mar 2019 14:31:44 +0100 Subject: Doxygen-commenting the main parts. --- talersurvey/survey/survey.py | 61 ++++++++++++++++++++++++++++++++++++++++++-- talersurvey/tests.py | 21 +++++++++++++++ 2 files changed, 80 insertions(+), 2 deletions(-) diff --git a/talersurvey/survey/survey.py b/talersurvey/survey/survey.py index 717e3a2..c5313b5 100644 --- a/talersurvey/survey/survey.py +++ b/talersurvey/survey/survey.py @@ -1,3 +1,4 @@ +## # This file is part of GNU TALER. # Copyright (C) 2017 Taler Systems SA # @@ -13,6 +14,7 @@ # GNU TALER; see the file COPYING. If not, see # # @author Marcello Stanisci +# @brief Minimal Website to tip users who fill the survey. import os import base64 @@ -36,6 +38,13 @@ app.config.from_object(__name__) LOGGER = logging.getLogger(__name__) +## +# Helper function that returns a HTTP response with +# a prettified version of a backend error response. +# +# @param requests_response the error response coming from +# the merchant backend. +# @return a flask-native response object. def backend_error(requests_response): LOGGER.error("Backend error: status code: " + str(requests_response.status_code)) @@ -47,6 +56,8 @@ def backend_error(requests_response): return flask.jsonify(dict(error="Backend died, no JSON got from it")), 502 +## +# Make the environment available into templates. @app.context_processor def utility_processor(): def env(name, default=None): @@ -54,11 +65,24 @@ def utility_processor(): return dict(env=env) +## +# Return a error response to the client. +# +# @param abort_status_code status code to return along the response. +# @param params _kw_ arguments to passed verbatim to the templating engine. def err_abort(abort_status_code, **params): t = flask.render_template("templates/error.html", **params) flask.abort(flask.make_response(t, abort_status_code)) +## +# POST a request to the backend, and return a error +# response if any error occurs. +# +# @param endpoint the backend endpoint where to POST +# this request. +# @param json the POST's body. +# @return the backend response (JSON format). def backend_post(endpoint, json): headers = {"Authorization": "ApiKey " + APIKEY} try: @@ -76,6 +100,13 @@ def backend_post(endpoint, json): return response_json +## +# Issue a GET request to the backend. +# +# @param endpoint the backend endpoint where to issue the request. +# @param params (dict type of) URL parameters to append to the request. +# @return the JSON response from the backend, or a error response +# if something unexpected happens. def backend_get(endpoint, params): headers = {"Authorization": "ApiKey " + APIKEY} try: @@ -92,24 +123,47 @@ def backend_get(endpoint, params): return response_json +## +# Exception handler to capture all the unmanaged errors. +# +# @param e the Exception object, currently unused. +# @return flask-native response object carrying the error message +# (and execution stack!). @app.errorhandler(Exception) def internal_error(e): return flask.render_template("templates/error.html", message="Internal error", stack=traceback.format_exc()) + +## +# Serve the /favicon.ico requests. +# +# @return the favicon.ico file. @app.route("/favicon.ico") def favicon(): print("will look into: " + os.path.join(app.root_path, 'static')) return flask.send_from_directory(os.path.join(app.root_path, 'static'), "favicon.ico", mimetype="image/vnd.microsoft.ico") +## +# Give information about the tip reserve status. +# +# @return the backend response to a /tip-query request, +# in a prettified format. @app.route("/survey-stats", methods=["GET"]) def survey_stats(): stats = backend_get("tip-query", dict(instance="default")) return flask.render_template("templates/survey_stats.html", stats=stats) - +## +# Tell the backend to 'authorize' a tip; this means that +# the backend will allocate a certain amount to be later +# picked up by the wallet. +# +# @return the URL where to redirect the browser, in order +# for the wallet to pick the tip up, or a error page +# otherwise. @app.route("/submit-survey", methods=["POST"]) def submit_survey(): tip_spec = dict(amount=CURRENCY + ":1.0", @@ -124,7 +178,10 @@ def submit_survey(): err_abort(500, message="Tipping failed, unexpected backend response", json=resp) - +## +# Serve the main index page. +# +# @return response object of the index page. @app.route("/", methods=["GET"]) def index(): return flask.render_template("templates/index.html", merchant_currency=CURRENCY) diff --git a/talersurvey/tests.py b/talersurvey/tests.py index 7dc2446..d25da48 100644 --- a/talersurvey/tests.py +++ b/talersurvey/tests.py @@ -1,3 +1,21 @@ +## +# This file is part of GNU TALER. +# Copyright (C) 2017 Taler Systems SA +# +# TALER is free software; you can redistribute it and/or modify it under the +# terms of the GNU Lesser General Public License as published by the Free Software +# Foundation; either version 2.1, or (at your option) any later version. +# +# TALER is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +# A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public License along with +# GNU TALER; see the file COPYING. If not, see +# +# @author Marcello Stanisci +# @brief Test cases for the Survey site. + #!/usr/bin/env python3 import os @@ -9,6 +27,9 @@ from talersurvey.talerconfig import TalerConfig TC = TalerConfig.from_env() CURRENCY = TC["taler"]["currency"].value_string(required=True) + +## +# Main class that gathers all the tests. class SurveyTestCase(unittest.TestCase): def setUp(self): survey.app.testing = True -- cgit v1.2.3