[dak/master] 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 <joerg@debian.org>
---
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 e69de29..a6eed9e 100644
--- a/dakweb/__init__.py
+++ b/dakweb/__init__.py
@@ -0,0 +1,6 @@
+"""
+The Debian Archive Kit web api.
+
+@contact: Debian FTPMaster <ftpmaster@debian.org>
+@license: GNU General Public License version 2 or later
+"""
diff --git a/dakweb/dakwebserver.py b/dakweb/dakwebserver.py
index 6102f84..0f70d72 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 <ftpmaster@debian.org>
+@copyright: 2014 Mark Hymers <mhy@debian.org>
+@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/<path>')
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 2ed4031..6d891b9
--- a/dakweb/queries/archive.py
+++ b/dakweb/queries/archive.py
@@ -1,19 +1,26 @@
#!/usr/bin/python
+""" Archive related queries
+
+@contact: Debian FTPMaster <ftpmaster@debian.org>
+@copyright: 2014 Mark Hymers <mhy@debian.org>
+@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 9678a36..023f67d 100644
--- a/dakweb/queries/madison.py
+++ b/dakweb/queries/madison.py
@@ -1,3 +1,11 @@
+""" "Madison" interface
+
+@contact: Debian FTPMaster <ftpmaster@debian.org>
+@copyright: 2014 Ansgar Burchardt <ansgar@debian.org>
+@copyright: 2014 Joerg Jaspert <joerg@debian.org>
+@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}<dakweb.queries.suite.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 91448e5..957cb0c 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 <ftpmaster@debian.org>
+@copyright: 2014 Mark Hymers <mhy@debian.org>
+@copyright: 2014 Joerg Jaspert <joerg@debian.org>
+@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/<suite>/<source>')
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}<dakweb.queries.suite.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/<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}<dakweb.queries.suite.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 245b879..5446f69 100644
--- a/dakweb/queries/suite.py
+++ b/dakweb/queries/suite.py
@@ -1,4 +1,11 @@
-#!/usr/bin/python
+""" Suite related queries
+
+@contact: Debian FTPMaster <ftpmaster@debian.org>
+@copyright: 2014 Mark Hymers <mhy@debian.org>
+@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/<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}<dakweb.queries.suite.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 d7e7990..e4606f6 100644
--- a/dakweb/webregister.py
+++ b/dakweb/webregister.py
@@ -1,3 +1,9 @@
+"""
+@contact: Debian FTPMaster <ftpmaster@debian.org>
+@copyright: 2014 Mark Hymers <mhy@debian.org>
+@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']
--
1.7.10.4
Reply to: