From e41ae8d5a5fd9c204711a36b47e0593312da8c75 Mon Sep 17 00:00:00 2001 From: Joerg Jaspert Date: Sun, 7 Dec 2014 13:48:12 +0100 Subject: [PATCH] Instead of doing our own (bad) help, simply use existing epydoc foo and redirect there And to have that in useful, rework the whole docstrings of the dakweb/ foo, to give useful epydoc output. Signed-off-by: Joerg Jaspert --- dakweb/__init__.py | 6 +++++ dakweb/dakwebserver.py | 21 +++++++++++----- dakweb/queries/archive.py | 16 ++++++++---- dakweb/queries/madison.py | 27 +++++++++++++++----- dakweb/queries/source.py | 51 +++++++++++++++++++++++++++++--------- dakweb/queries/suite.py | 52 +++++++++++++++++++++++++++++---------- dakweb/webregister.py | 10 ++++++-- 7 files changed, 139 insertions(+), 44 deletions(-) mode change 100644 => 100755 dakweb/queries/archive.py diff --git a/dakweb/__init__.py b/dakweb/__init__.py index e69de29b..a6eed9ed 100644 --- a/dakweb/__init__.py +++ b/dakweb/__init__.py @@ -0,0 +1,6 @@ +""" +The Debian Archive Kit web api. + +@contact: Debian FTPMaster +@license: GNU General Public License version 2 or later +""" diff --git a/dakweb/dakwebserver.py b/dakweb/dakwebserver.py index 6102f84b..0f70d72b 100755 --- a/dakweb/dakwebserver.py +++ b/dakweb/dakwebserver.py @@ -1,34 +1,43 @@ #!/usr/bin/python -# Main script to run the dakweb server and also -# to provide the list_paths and path_help functions +""" Main script to run the dakweb server and also +to provide the list_paths and path_help functions + +@contact: Debian FTPMaster +@copyright: 2014 Mark Hymers +@license: GNU General Public License version 2 or later +""" -from sqlalchemy import or_ import bottle -from daklib.dbconn import DBConn, DBSource, Suite, DSCFile, PoolFile +from bottle import redirect +from daklib.dbconn import DBConn import json from dakweb.webregister import QueryRegister + @bottle.route('/') def root_path(): """Returns a useless welcome message""" return json.dumps('Use the /list_paths path to list all available paths') QueryRegister().register_path('/', root_path) + @bottle.route('/list_paths') def list_paths(): """Returns a list of available paths""" return json.dumps(QueryRegister().get_paths()) QueryRegister().register_path('/list_paths', list_paths) + @bottle.route('/path_help/') def path_help(path=None): - + """Redirects to the API description containing the path_help""" if path is None: return bottle.HTTPError(503, 'Path not specified.') - return json.dumps(QueryRegister().get_path_help(path)) + redirect("https://ftp-master.debian.org/epydoc/%s-module.html#%s" % + (QueryRegister().get_path_help(path), path)) QueryRegister().register_path('/path_help', list_paths) # Import our other methods diff --git a/dakweb/queries/archive.py b/dakweb/queries/archive.py old mode 100644 new mode 100755 index 2ed4031e..6d891b9a --- a/dakweb/queries/archive.py +++ b/dakweb/queries/archive.py @@ -1,19 +1,26 @@ #!/usr/bin/python +""" Archive related queries + +@contact: Debian FTPMaster +@copyright: 2014 Mark Hymers +@license: GNU General Public License version 2 or later +""" + import bottle import json from daklib.dbconn import DBConn, Archive from dakweb.webregister import QueryRegister + @bottle.route('/archives') def archives(): """ - archives() - - returns: list of dictionaries - Give information about all known archives (sets of suites) + + @rtype: dict + return: list of dictionaries """ s = DBConn().session() @@ -29,4 +36,3 @@ def archives(): return json.dumps(ret) QueryRegister().register_path('/archives', archives) - diff --git a/dakweb/queries/madison.py b/dakweb/queries/madison.py index 9678a36e..023f67d0 100644 --- a/dakweb/queries/madison.py +++ b/dakweb/queries/madison.py @@ -1,3 +1,11 @@ +""" "Madison" interface + +@contact: Debian FTPMaster +@copyright: 2014 Ansgar Burchardt +@copyright: 2014 Joerg Jaspert +@license: GNU General Public License version 2 or later +""" + import bottle import json @@ -7,13 +15,20 @@ from dakweb.webregister import QueryRegister @bottle.route('/madison') def madison(): """ - Display information about packages. + Display information about B{package(s)}. + + @since: December 2014 + + @keyword package: Space seperated list of packages. + @keyword b: only show info for a binary type. I{deb/udeb/dsc} + @keyword c: only show info for specified component(s). I{main/contrib/non-free} + @keyword s: only show info for this suite. + @keyword S: show info for the binary children of source pkgs. I{true/false} + @keyword f: output json format. I{json} + @see: L{I{suites}} on how to receive a list of valid suites. - b=TYPE only show info for binary TYPE - c=COMPONENT only show info for COMPONENT(s) - s=SUITE only show info for this suite - S=true show info for the binary children of source pkgs - f=json output json format + @rtype: text/plain or application/json + @return: Text or Json format of the data """ r = bottle.request diff --git a/dakweb/queries/source.py b/dakweb/queries/source.py index 91448e5d..957cb0cc 100755 --- a/dakweb/queries/source.py +++ b/dakweb/queries/source.py @@ -1,4 +1,10 @@ -#!/usr/bin/python +""" Queries related to source packages + +@contact: Debian FTPMaster +@copyright: 2014 Mark Hymers +@copyright: 2014 Joerg Jaspert +@license: GNU General Public License version 2 or later +""" from sqlalchemy import or_ import bottle @@ -7,14 +13,28 @@ import json from daklib.dbconn import DBConn, DBSource, Suite, DSCFile, PoolFile from dakweb.webregister import QueryRegister + @bottle.route('/dsc_in_suite//') def dsc_in_suite(suite=None, source=None): """ - dsc_in_suite(suite, source) + Find all dsc files for a given source package name in a given suite. - returns: list of dictionaries + @since: December 2014 - Find all dsc files for a given source package name in a given suite. + @type suite: string + @param suite: Name of the suite. + @see: L{I{suites}} on how to receive a list of valid suites. + + @type source: string + @param source: Source package to query for. + + @rtype: list of dictionaries + @return: Dictionaries made out of + - version + - component + - filename + - filesize + - sha256sum """ if suite is None: return bottle.HTTPError(503, 'Suite not specified.') @@ -45,13 +65,19 @@ QueryRegister().register_path('/dsc_in_suite', dsc_in_suite) @bottle.route('/sources_in_suite/') def sources_in_suite(suite=None): """ - sources_in_suite(suite) + Returns all source packages and their versions in a given suite. - returns: list of dictionaries + @since: December 2014 - Returns all source packages and their versions in a given suite. - """ + @type suite: string + @param suite: Name of the suite. + @see: L{I{suites}} on how to receive a list of valid suites. + @rtype: list of dictionaries + @return: Dictionaries made out of + - source + - version + """ if suite is None: return bottle.HTTPError(503, 'Suite not specified.') @@ -73,12 +99,13 @@ QueryRegister().register_path('/sources_in_suite', sources_in_suite) @bottle.route('/all_sources') def all_sources(): """ - all_sources() - - returns: list of dictionaries - Returns all source packages and their versions known to the archive (this includes NEW). + + @rtype: list of dictionaries + @return: Dictionaries made out of + - source + - version """ s = DBConn().session() diff --git a/dakweb/queries/suite.py b/dakweb/queries/suite.py index 245b879c..5446f699 100644 --- a/dakweb/queries/suite.py +++ b/dakweb/queries/suite.py @@ -1,4 +1,11 @@ -#!/usr/bin/python +""" Suite related queries + +@contact: Debian FTPMaster +@copyright: 2014 Mark Hymers +@license: GNU General Public License version 2 or later + +@newfield maps: Mapping, Mappings +""" import bottle import json @@ -6,18 +13,25 @@ import json from daklib.dbconn import DBConn, Suite from dakweb.webregister import QueryRegister + @bottle.route('/suites') def suites(): """ - suites() + Give information about all known suites. - returns: list of dictionaries + @maps: name maps to Suite: in the release file + @maps: codename maps to Codename: in the release file. + @maps: dakname is an internal name and should not be relied upon. - Give information about all known suites. + @rtype: list of dictionaries + @return: Dictionaries made out of + - name + - codename + - dakname + - archive + - architectures + - components - name maps to Suite: in the release file - codename maps to Codename: in the release file. - dakname is an internal name and should not be relied upon. """ s = DBConn().session() @@ -41,14 +55,27 @@ QueryRegister().register_path('/suites', suites) @bottle.route('/suite/') def suite(suite=None): """ - suite(suite) - - returns: dictionary - Gives information about a single suite. Note that this routine will look up a suite first by the main suite_name, but then also by codename if no suite is initially found. It can therefore be used to canonicalise suite - names + names. + + @type suite: string + @param suite: Name or codename of the suite. + @see: L{I{suites}} on how to receive a list of valid suites. + + @maps: name maps to Suite: in the release file + @maps: codename maps to Codename: in the release file. + @maps: dakname is an internal name and should not be relied upon. + + @rtype: dictionary + @return: A dictionary of + - name + - codename + - dakname + - archive + - architectures + - components """ if suite is None: @@ -90,4 +117,3 @@ def suite(suite=None): return json.dumps(so) QueryRegister().register_path('/suite', suite) - diff --git a/dakweb/webregister.py b/dakweb/webregister.py index d7e7990d..e4606f69 100644 --- a/dakweb/webregister.py +++ b/dakweb/webregister.py @@ -1,3 +1,9 @@ +""" +@contact: Debian FTPMaster +@copyright: 2014 Mark Hymers +@license: GNU General Public License version 2 or later +""" + class QueryRegister(object): __shared_state = {} @@ -11,7 +17,7 @@ class QueryRegister(object): self.queries = {} def register_path(self, path, func): - self.queries[path] = func.__doc__ + self.queries[path] = func.__module__ def get_paths(self): return sorted(self.queries.keys()) @@ -20,6 +26,6 @@ class QueryRegister(object): # We always register with the leading / if not path.startswith('/'): path = '/' + path - return self.queries.get(path, 'Unknown path') + return self.queries.get(path, '/') __all__ = ['QueryRegister'] -- 2.39.2