Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 6160:9619d64c0351

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Doc updates for customizing.txt, start of index generation customizing.txt: fix doc on schema.py. Documented obsolete db schema declaration/initial data method. doc on config.ini is incomplete. doc as such. Add doc for [rdbms]: backend, cache_size, sqlite_timeout document Interval schema type. Also change formatting for list of schema types to description list from regular list so types are more visible. add link to roundup wiki for schema chnge examples. fix formatting for postfix config. document Rest Access and Xmlrpc Access permissions; change classic schema.py example to include them. doc db/backend_name as obsolete, conf.py [rdbms] backend used instead. start adding index references conf.py: update copyright year index.txt: add link to genindex.html. _templates/layout.html: change code to make index output work. Not sure what the change does, just monkey pasting from sphinx basic/layout.html
author John Rouillard <rouilj@ieee.org>
date Mon, 11 May 2020 00:02:31 -0400
parents e2b70d43d0fc
children 81ae33038ec5
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
1 =========================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
2 XML-RPC access to Roundup
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
3 =========================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
4
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
5 .. contents::
4890
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4732
diff changeset
6 :local:
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
7
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
8 Introduction
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
9 ------------
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
10 Version 1.4 of Roundup includes an XML-RPC frontend for remote access. The
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
11 XML-RPC interface allows a limited subset of commands similar to those found in
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
12 local `roundup-admin` tool.
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
13
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
14 By default XML-RPC is accessible from ``/xmlrpc`` endpoint:
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
15
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
16 http://username:password@localhost:8000/xmlrpc
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
17
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
18 For demo tracker the URL would be:
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
19
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
20 http://localhost:8917/demo/xmlrpc
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
21
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
22 Enabling XML-RPC server
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
23 -----------------------
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
24 There are two ways to run the XML-RPC interface:
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
25
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
26 through roundup itself
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
27
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
28 stand alone roundup-xmlrpc-server
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
29
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
30
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
31 through roundup
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
32 ---------------
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
33 The XML-RPC service is available from the roundup HTTP server under
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
34 /xmlrpc.
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
35
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
36 To enable this set ``enable_xmlrpc`` to ``yes`` in the ``[web]``
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
37 section of the ``config.ini`` file in your tracker.
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
38
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
39 Each user that needs access must include the "Xmlrpc Access" role. To
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
40 add this new permission to the "User" role you should change your
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
41 schema.py to add::
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
42
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
43 db.security.addPermissionToRole('User', 'Xmlrpc Access')
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
44
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
45 This is usually included near where other permissions like "Web Access"
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
46 or "Email Access" are assigned.
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
47
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
48 stand alone roundup-xmlrpc-server
4732
8ee41c7372e7 doc: Fix some Sphinx warnings.
anatoly techtonik <techtonik@gmail.com>
parents: 4678
diff changeset
49 ---------------------------------
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
50 Using roundup to access the xmlrpc interface is preferred. Roundup
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
51 provides better control over who can use the interface.
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
52
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
53 The Roundup XML-RPC standalone server must be started before remote
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
54 clients can access the tracker via XML-RPC. ``roundup-xmlrpc-server``
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
55 is installed in the scripts directory alongside ``roundup-server`` and
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
56 ``roundup-admin``. When invoked, the location of the tracker instance
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
57 must be specified.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
58
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
59 roundup-xmlrpc-server -i ``/path/to/tracker``
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
60
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
61 The default port is ``8000``. An alternative port can be specified with the
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
62 ``--port`` switch.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
63
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
64 security consideration
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
65 ----------------------
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
66 Both the standalone and embedded roundup XML endpoints used the
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
67 default python XML parser. This parser is know to have security
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
68 issues. For details see: https://pypi.python.org/pypi/defusedxml/.
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
69 You may wish to use the rest interface which doesn't have the same
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
70 issues. Patches with tests to roundup to use defusedxml are welcome.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
71
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
72 Note that the current ``roundup-xmlrpc-server`` implementation does
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
73 not support SSL. This means that usernames and passwords will be
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
74 passed in cleartext unless the server is being proxied behind another
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
75 server (such as Apache or lighttpd) that provide SSL.
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
76
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
77 Client API
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
78 ----------
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
79 The server currently implements four methods. Each method requires
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
80 that the user provide a username and password in the HTTP
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
81 authorization header in order to authenticate the request against the
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
82 tracker.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
83
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
84 ======= ====================================================================
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
85 Command Description
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
86 ======= ====================================================================
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
87 schema
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
88
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
89 Fetch tracker schema.
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
90
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
91 list arguments: *classname, [property_name]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
92
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
93 List all elements of a given ``classname``. If ``property_name`` is
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
94 specified, that is the property that will be displayed for each
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
95 element. If ``property_name`` is not specified the default label
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
96 property will be used.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
97
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
98 display arguments: *designator, [property_1, ..., property_N]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
99
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
100 Display a single item in the tracker as specified by ``designator``
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
101 (e.g. issue20 or user5). The default is to display all properties
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
102 for the item. Alternatively, a list of properties to display can be
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
103 specified.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
104
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
105 create arguments: *classname, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
106
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
107 Create a new instance of ``classname`` with ``arg_1`` through
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
108 ``arg_N`` as the values of the new instance. The arguments are
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
109 name=value pairs (e.g. ``status='3'``).
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
110
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
111 set arguments: *designator, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
112
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
113 Set the values of an existing item in the tracker as specified by
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
114 ``designator``. The new values are specified in ``arg_1`` through
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
115 ``arg_N``. The arguments are name=value pairs (e.g. ``status='3'``).
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
116
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
117 lookup arguments: *classname, key_value*
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
118
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
119 looks up the key_value for the given class. The class needs to
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
120 have a key and the user needs search permission on the key
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
121 attribute and id for the given classname.
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
122
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
123 filter arguments: *classname, list or None, attributes*
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
124
4929
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
125 ``list`` is a list of ids to filter. It can be set to None to run
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
126 filter over all values (requires ``allow_none=True`` when
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
127 instantiating the ServerProxy). The ``attributes`` are given as a
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
128 dictionary of name value pairs to search for. See also :ref:`query-tracker`.
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
129 ======= ====================================================================
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
130
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
131 sample python client
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
132 ====================
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
133
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
134 This client will work if you turn off the x-requested-with header and
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
135 the only CSRF header check you require is the HTTP host header::
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
136
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
137 >>> import xmlrpclib
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
138 >>> roundup_server = xmlrpclib.ServerProxy('http://admin:admin@localhost:8917/demo/xmlrpc', allow_none=True)
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
139 >>> roundup_server.schema()
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
140 {'user': [['username', '<roundup.hyperdb.String>'], ...], 'issue': [...]}
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
141 >>> roundup_server.list('user')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
142 ['admin', 'anonymous', 'demo']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
143 >>> roundup_server.list('issue', 'id')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
144 ['1']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
145 >>> roundup_server.display('issue1')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
146 {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
147 >>> roundup_server.display('issue1', 'priority', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
148 {'priority' : '1', 'status' : '2'}
3951
53b922e0d2b7 typo in docs for xmlrpc
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3950
diff changeset
149 >>> roundup_server.set('issue1', 'status=3')
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
150 >>> roundup_server.display('issue1', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
151 {'status' : '3' }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
152 >>> roundup_server.create('issue', "title='another bug'", "status=2")
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
153 '2'
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
154 >>> roundup_server.filter('user',None,{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
155 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
156 >>> roundup_server.filter('user',['1','2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
157 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
158 >>> roundup_server.filter('user',['2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
159 []
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
160 >>> roundup_server.filter('user',[],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
161 []
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
162 >>> roundup_server.lookup('user','admin')
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
163 '1'
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
164
5298
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
165 advanced python client adding anti-csrf headers
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
166 ===============================================
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
167
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
168 The one below adds Referer and X-Requested-With headers so it can pass
5220
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
169 stronger CSRF detection methods. It also generates a fault message
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
170 from the server and reports it. Note if you are using http rather than
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
171 https, replace xmlrpclib.SafeTransport with xmlrpclib.Transport::
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
172
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
173 import xmlrpclib
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
174
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
175 class SpecialTransport(xmlrpclib.SafeTransport):
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
176
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
177 def send_content(self, connection, request_body):
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
178
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
179 connection.putheader("Referer", "https://localhost/demo/")
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
180 connection.putheader("Origin", "https://localhost")
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
181 connection.putheader("X-Requested-With", "XMLHttpRequest")
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
182
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
183 connection.putheader("Content-Type", "text/xml")
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
184 connection.putheader("Content-Length", str(len(request_body)))
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
185 connection.endheaders()
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
186 if request_body:
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
187 connection.send(request_body)
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
188
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
189 roundup_server = xmlrpclib.ServerProxy(
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
190 'https://admin:admin@localhost/demo/xmlrpc',
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
191 transport=SpecialTransport(),
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
192 verbose=False,
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
193 allow_none=True)
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
194
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
195 print(roundup_server.schema())
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
196 print(roundup_server.display('user2', 'username'))
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
197 print(roundup_server.display('issue1', 'status'))
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
198 print(roundup_server.filter('user',['1','2','3'],{'username':'demo'}))
5220
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
199
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
200 # this will fail with a fault
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
201 try:
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
202 print(roundup_server.filter('usr',['0','2','3'],{'username':'demo'}))
5248
198b6e810c67 Use Python-3-compatible 'as' syntax for except statements
Eric S. Raymond <esr@thyrsus.com>
parents: 5220
diff changeset
203 except Exception as msg:
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
204 print(msg)
Roundup Issue Tracker: http://roundup-tracker.org/