www/cgi-bin/soap-alpha.cgi

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright © 2008 Stefano Zacchiroli <zack@debian.org>
#
# This file is distributed under the terms of the General Public License
# version 3 or (at your option) any later version.

"""
Debian's PTS SOAP API reference
===============================

This is the API reference for U{Debian<http://www.debian.org>}'s
U{Package Tracking System<http://packages.qa.debian.org>} (PTS) U{SOAP
interface<http://wiki.debian.org/qa.debian.org/pts/SoapInterface>}.
For more information, see the U{wiki
page<http://wiki.debian.org/qa.debian.org/pts/SoapInterface>}.

Naming conventions
------------------

- all methods ending with C{_url} return atomic C{str} values denoting
  URLs

"""

import sys

import config
sys.path.insert(0, config.libdir)
from soap_lib import *


__svn_rev = '$Revision$'
__base_version = '0.1'  # SVN revision will be appended when asked for
__version = __base_version + '.' + __svn_rev.split()[1]


def version():
    """
    Return the SOAP API version

    @rtype: C{str}
    @return: current API version as a string
    """
    global __svn_rev, __base_version, __version
    return __version

def latest_version(source):
    """
    Return the latest (known) version of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{str}
    @return: latest source package version
    """
    return to_string(as_id('latest_version', source))

def versions(source):
    """
    Return all the (known) versions of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{dict} with C{str} keys and values
    @return: dictionary mapping suite names to the latest known
      version of the package in those suites.

      E.g.: C{{'stable': '1.2-4', 'testing': '1.5-6', 'unstable': '1.5-7'}}
    """
    nodes = as_xpath("//xhtml:span[starts-with(@class,'srcversion')]/@title "
                     "| //xhtml:span[starts-with(@class,'srcversion')]/child::text()",
                     source)
    nodes.reverse()
    return dict_of_list(map(to_string, nodes))

def maintainer_name(source):
    """
    Return the name of the maintainer of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{str}
    @return: maintainer name
    """
    nodes = as_xpath("//*[starts-with(@class,'maintainer')]"
                     "//*[starts-with(@title,'maintainer')]/child::text()", source)
    return to_string(singleton(nodes))

def maintainer_email(source):
    """
    Return the email of the maintainer of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{str}
    @return: maintainer email
    """
    nodes = as_xpath("//*[starts-with(@class,'maintainer')]/xhtml:a/@href",
                     source)
    s = to_string(singleton(nodes))
    return s.split('login=')[1]

def maintainer(source):
    """
    Return information about the maintainer of a given source package.

    Maintainer information are currently name and email, as returned
    respectively by L{maintainer_name} and L{maintainer_email}.

    @type source: C{str}
    @param source: source package name
    @rtype: C{dict} with C{str} keys and values
    @return: a dictionary mapping C{'name'} to the maintainer name and
      C{'email'} to the maintainer email
    """
    return {'name': maintainer_name(source), 'email': maintainer_email(source)}

def uploader_names(source):
    """
    Return the names of all the uploaders of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{list} of C{str}
    @return: uploader name list
    """
    nodes = as_xpath("//*[starts-with(@class,'maintainer')]"
                     "//*[starts-with(@class,'uploader')]"
                     "//*[starts-with(@class,'name')]/child::text()", source)
    return to_strings(nodes)

def uploader_emails(source):
    """
    Return the emails of all the uploaders of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{list} of C{str}
    @return: uploader email list
    """
    nodes = as_xpath("//*[starts-with(@class,'maintainer')]"
                     "//*[starts-with(@class,'uploader')]"
                     "//xhtml:a/@href", source)
    return map(lambda s: s.split('login=')[1], to_strings(nodes))

def uploaders(source):
    """
    Return information about all the uploaders of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{list} of C{dict} with C{str} keys and values
    @return: a list of uploader information; information are returned
      in the same format of L{maintainer}
    """
    def combine(names, emails):
        assert len(names) == len(emails)
        return [ { 'name': names[i], 'email': emails[i] }
                 for i in range(len(names)) ]
    return combine(uploader_names(source), uploader_emails(source))

def standards_version(source):
    """
    Return latest C{Standards-Version} value of a given source
    package, i.e., latest version of the U{policy
    manual<http://www.debian.org/doc/debian-policy/>} that the package
    declares to be conforming to.

    @type source: C{str}
    @param source: source package name
    @rtype: C{str}
    @return: latest package standards version
    """
    return to_string(as_id('standards_version', source))

def priority(source):
    """
    Return the C{Priority} value of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{str}
    @return: package priority
    """
    nodes = as_xpath("//*[@id='priority']/xhtml:small/child::text()", source)
    return to_string(singleton(nodes))

def section(source):
    """
    Return the C{Section} value of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{str}
    @return: package section
    """
    nodes = as_xpath("//*[@id='section']/xhtml:small/child::text()", source)
    return to_string(singleton(nodes))

def binary_names(source):
    """
    Return the names of all the binary packages of a given source package.

    @type source: C{str}
    @param source: source package name
    @rtype: C{list} of C{str}
    @return: binary package names
    """
    nodes = as_xpath("//xhtml:span[starts-with(@class,'binpkg')]//child::text()",
                     source)
    return to_strings(nodes)

def lintian(source):
    """
    Return the lintian summary for a given source package.

    Currently only warnings and errors are reported.

    @type source: C{str}
    @param source: source package name
    @rtype: C{dict} with C{str} keys and C{int} values
    @return: a dictionary mapping C{'warnings'} to the number of
      lintian warnings and C{'errors'} to that of lintian errors
    """
    warn = as_id('lintian_warnings', source)
    err = as_id('lintian_errors', source)
    return {'warnings': to_int(warn), 'errors': to_int(err)}

def bug_counts(source):
    """
    Return the bug summary for a given source package.

    Merged bugs are I{not} counted more than once in the returned bug
    counts.

    It is not granted that all counts are there in all summaries, some
    are optionals and are marked as such below.

    @type source: C{str}
    @param source: source package name
    @rtype: C{dict} with C{str} keys and C{int} values
    @return: a dictionary with the following mappings:
      - C{'all'}: total number of bugs
      - C{'rc'}: release critical bugs
      - C{'in'}: severity important and normal bugs
      - C{'mw'}: severity medium and wishlist bugs
      - C{'fp'}: fixed and pending bugs
      - C{'help'}: bugs tagged C{help} I{(optional)}
      - C{'gift'}: bugs tagged C{gift} I{(optional)}
    """
    nodes = as_xpath("//xhtml:span[starts-with(@class,'bugcount')]/@title "
                     "| //xhtml:span[starts-with(@class,'bugcount')]/child::text()",
                     source)
    nodes.reverse()
    return dict_of_list(map(to_string, nodes))

def hyperlinks(source):
    """
    B{NOT IMPLEMENTED}.

    Return a list of hyperlinks related to a given source package.
    """
    raise NotImplementedError('hyperlinks')

def files(source):
    """
    B{NOT IMPLEMENTED}.

    Return (URLs of) files composing a given source package.
    """
    raise NotImplementedError('files')

def ubuntu_info(source):
    """
    B{NOT IMPLEMENTED}.

    Return the summary of Ubuntu-originated information about a given
    source package.
    """
    raise NotImplementedError('ubuntu_info')

def subscriber_count(source):
    """
    B{NOT IMPLEMENTED}.

    Return the number of subscribers to PTS notification for a given
    source package.
    """
    raise NotImplementedError('subscriber_count')

def todos(source):
    """
    B{NOT IMPLEMENTED}.

    Return a list of TODO items related to a given source package.
    """
    raise NotImplementedError('todos')

def problems(source):
    """
    B{NOT IMPLEMENTED}.

    Return a list of problems affecting a given source package.
    """
    raise NotImplementedError('problems')

def news(source):
    """
    B{NOT IMPLEMENTED}.

    Return a list of recent news about a given source package.
    """
    raise NotImplementedError('news')

def news_feed_url(source):
    """
    B{NOT IMPLEMENTED}.

    Return the URL of a RSS feed containing news about a given source
    package.
    """
    raise NotImplementedError('news_feed_url')


from ZSI import dispatch
dispatch.AsCGI(rpc=True)
# dispatch.AsServer(port=9999, rpc=True)

1	#!/usr/bin/python
2	# -- coding: utf-8 --
3
4	# Copyright © 2008 Stefano Zacchiroli <zack@debian.org>
5	#
6	# This file is distributed under the terms of the General Public License
7	# version 3 or (at your option) any later version.
8
9	"""
10	Debian's PTS SOAP API reference
11	===============================
12
13	This is the API reference for U{Debian<http://www.debian.org>}'s
14	U{Package Tracking System<http://packages.qa.debian.org>} (PTS) U{SOAP
15	interface<http://wiki.debian.org/qa.debian.org/pts/SoapInterface>}.
16	For more information, see the U{wiki
17	page<http://wiki.debian.org/qa.debian.org/pts/SoapInterface>}.
18
19	Naming conventions
20	------------------
21
22	- all methods ending with C{_url} return atomic C{str} values denoting
23	URLs
24
25	"""
26
27	import sys
28
29	import config
30	sys.path.insert(0, config.libdir)
31	from soap_lib import *
32
33
34	__svn_rev = '$Revision$'
35	__base_version = '0.1' # SVN revision will be appended when asked for
36	__version = __base_version + '.' + __svn_rev.split()[1]
37
38
39	def version():
40	"""
41	Return the SOAP API version
42
43	@rtype: C{str}
44	@return: current API version as a string
45	"""
46	global __svn_rev, __base_version, __version
47	return __version
48
49	def latest_version(source):
50	"""
51	Return the latest (known) version of a given source package.
52
53	@type source: C{str}
54	@param source: source package name
55	@rtype: C{str}
56	@return: latest source package version
57	"""
58	return to_string(as_id('latest_version', source))
59
60	def versions(source):
61	"""
62	Return all the (known) versions of a given source package.
63
64	@type source: C{str}
65	@param source: source package name
66	@rtype: C{dict} with C{str} keys and values
67	@return: dictionary mapping suite names to the latest known
68	version of the package in those suites.
69
70	E.g.: C{{'stable': '1.2-4', 'testing': '1.5-6', 'unstable': '1.5-7'}}
71	"""
72	nodes = as_xpath("//xhtml:span[starts-with(@class,'srcversion')]/@title "
73	"\| //xhtml:span[starts-with(@class,'srcversion')]/child::text()",
74	source)
75	nodes.reverse()
76	return dict_of_list(map(to_string, nodes))
77
78	def maintainer_name(source):
79	"""
80	Return the name of the maintainer of a given source package.
81
82	@type source: C{str}
83	@param source: source package name
84	@rtype: C{str}
85	@return: maintainer name
86	"""
87	nodes = as_xpath("//*[starts-with(@class,'maintainer')]"
88	"//*[starts-with(@title,'maintainer')]/child::text()", source)
89	return to_string(singleton(nodes))
90
91	def maintainer_email(source):
92	"""
93	Return the email of the maintainer of a given source package.
94
95	@type source: C{str}
96	@param source: source package name
97	@rtype: C{str}
98	@return: maintainer email
99	"""
100	nodes = as_xpath("//*[starts-with(@class,'maintainer')]/xhtml:a/@href",
101	source)
102	s = to_string(singleton(nodes))
103	return s.split('login=')[1]
104
105	def maintainer(source):
106	"""
107	Return information about the maintainer of a given source package.
108
109	Maintainer information are currently name and email, as returned
110	respectively by L{maintainer_name} and L{maintainer_email}.
111
112	@type source: C{str}
113	@param source: source package name
114	@rtype: C{dict} with C{str} keys and values
115	@return: a dictionary mapping C{'name'} to the maintainer name and
116	C{'email'} to the maintainer email
117	"""
118	return {'name': maintainer_name(source), 'email': maintainer_email(source)}
119
120	def uploader_names(source):
121	"""
122	Return the names of all the uploaders of a given source package.
123
124	@type source: C{str}
125	@param source: source package name
126	@rtype: C{list} of C{str}
127	@return: uploader name list
128	"""
129	nodes = as_xpath("//*[starts-with(@class,'maintainer')]"
130	"//*[starts-with(@class,'uploader')]"
131	"//*[starts-with(@class,'name')]/child::text()", source)
132	return to_strings(nodes)
133
134	def uploader_emails(source):
135	"""
136	Return the emails of all the uploaders of a given source package.
137
138	@type source: C{str}
139	@param source: source package name
140	@rtype: C{list} of C{str}
141	@return: uploader email list
142	"""
143	nodes = as_xpath("//*[starts-with(@class,'maintainer')]"
144	"//*[starts-with(@class,'uploader')]"
145	"//xhtml:a/@href", source)
146	return map(lambda s: s.split('login=')[1], to_strings(nodes))
147
148	def uploaders(source):
149	"""
150	Return information about all the uploaders of a given source package.
151
152	@type source: C{str}
153	@param source: source package name
154	@rtype: C{list} of C{dict} with C{str} keys and values
155	@return: a list of uploader information; information are returned
156	in the same format of L{maintainer}
157	"""
158	def combine(names, emails):
159	assert len(names) == len(emails)
160	return [ { 'name': names[i], 'email': emails[i] }
161	for i in range(len(names)) ]
162	return combine(uploader_names(source), uploader_emails(source))
163
164	def standards_version(source):
165	"""
166	Return latest C{Standards-Version} value of a given source
167	package, i.e., latest version of the U{policy
168	manual<http://www.debian.org/doc/debian-policy/>} that the package
169	declares to be conforming to.
170
171	@type source: C{str}
172	@param source: source package name
173	@rtype: C{str}
174	@return: latest package standards version
175	"""
176	return to_string(as_id('standards_version', source))
177
178	def priority(source):
179	"""
180	Return the C{Priority} value of a given source package.
181
182	@type source: C{str}
183	@param source: source package name
184	@rtype: C{str}
185	@return: package priority
186	"""
187	nodes = as_xpath("//*[@id='priority']/xhtml:small/child::text()", source)
188	return to_string(singleton(nodes))
189
190	def section(source):
191	"""
192	Return the C{Section} value of a given source package.
193
194	@type source: C{str}
195	@param source: source package name
196	@rtype: C{str}
197	@return: package section
198	"""
199	nodes = as_xpath("//*[@id='section']/xhtml:small/child::text()", source)
200	return to_string(singleton(nodes))
201
202	def binary_names(source):
203	"""
204	Return the names of all the binary packages of a given source package.
205
206	@type source: C{str}
207	@param source: source package name
208	@rtype: C{list} of C{str}
209	@return: binary package names
210	"""
211	nodes = as_xpath("//xhtml:span[starts-with(@class,'binpkg')]//child::text()",
212	source)
213	return to_strings(nodes)
214
215	def lintian(source):
216	"""
217	Return the lintian summary for a given source package.
218
219	Currently only warnings and errors are reported.
220
221	@type source: C{str}
222	@param source: source package name
223	@rtype: C{dict} with C{str} keys and C{int} values
224	@return: a dictionary mapping C{'warnings'} to the number of
225	lintian warnings and C{'errors'} to that of lintian errors
226	"""
227	warn = as_id('lintian_warnings', source)
228	err = as_id('lintian_errors', source)
229	return {'warnings': to_int(warn), 'errors': to_int(err)}
230
231	def bug_counts(source):
232	"""
233	Return the bug summary for a given source package.
234
235	Merged bugs are I{not} counted more than once in the returned bug
236	counts.
237
238	It is not granted that all counts are there in all summaries, some
239	are optionals and are marked as such below.
240
241	@type source: C{str}
242	@param source: source package name
243	@rtype: C{dict} with C{str} keys and C{int} values
244	@return: a dictionary with the following mappings:
245	- C{'all'}: total number of bugs
246	- C{'rc'}: release critical bugs
247	- C{'in'}: severity important and normal bugs
248	- C{'mw'}: severity medium and wishlist bugs
249	- C{'fp'}: fixed and pending bugs
250	- C{'help'}: bugs tagged C{help} I{(optional)}
251	- C{'gift'}: bugs tagged C{gift} I{(optional)}
252	"""
253	nodes = as_xpath("//xhtml:span[starts-with(@class,'bugcount')]/@title "
254	"\| //xhtml:span[starts-with(@class,'bugcount')]/child::text()",
255	source)
256	nodes.reverse()
257	return dict_of_list(map(to_string, nodes))
258
259	def hyperlinks(source):
260	"""
261	B{NOT IMPLEMENTED}.
262
263	Return a list of hyperlinks related to a given source package.
264	"""
265	raise NotImplementedError('hyperlinks')
266
267	def files(source):
268	"""
269	B{NOT IMPLEMENTED}.
270
271	Return (URLs of) files composing a given source package.
272	"""
273	raise NotImplementedError('files')
274
275	def ubuntu_info(source):
276	"""
277	B{NOT IMPLEMENTED}.
278
279	Return the summary of Ubuntu-originated information about a given
280	source package.
281	"""
282	raise NotImplementedError('ubuntu_info')
283
284	def subscriber_count(source):
285	"""
286	B{NOT IMPLEMENTED}.
287
288	Return the number of subscribers to PTS notification for a given
289	source package.
290	"""
291	raise NotImplementedError('subscriber_count')
292
293	def todos(source):
294	"""
295	B{NOT IMPLEMENTED}.
296
297	Return a list of TODO items related to a given source package.
298	"""
299	raise NotImplementedError('todos')
300
301	def problems(source):
302	"""
303	B{NOT IMPLEMENTED}.
304
305	Return a list of problems affecting a given source package.
306	"""
307	raise NotImplementedError('problems')
308
309	def news(source):
310	"""
311	B{NOT IMPLEMENTED}.
312
313	Return a list of recent news about a given source package.
314	"""
315	raise NotImplementedError('news')
316
317	def news_feed_url(source):
318	"""
319	B{NOT IMPLEMENTED}.
320
321	Return the URL of a RSS feed containing news about a given source
322	package.
323	"""
324	raise NotImplementedError('news_feed_url')
325
326
327	from ZSI import dispatch
328	dispatch.AsCGI(rpc=True)
329	# dispatch.AsServer(port=9999, rpc=True)
330