1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
===================================================================
Notes on input argument usage when invoking a web service operation
===================================================================
:Authors: Jurko Gospodneti
:Date: 2014-01-23
===========
Definitions
===========
message parts
WSDL schema defines message parts representing a web service operation's input
data. Each such part's data structure is defined by mapping the message part
to XSD element or type.
input parameters
Suds library's view of a web service operation's input data. Each message part
may correspond to 1 or more input parameters. See the `Bare/wrapped web
service operation input parameters`_ section for more detailed information.
input arguments
Values passed to suds library's Python function or function object invoking a
web service operation. Suds attempts to map each input argument to a single
web service operation input parameter.
===================================================
Bare/wrapped web service operation input parameters
===================================================
When suds library models a web service operation, it can be configured to map
each of its message parts to a single input parameter expecting values directly
matching the data type defined for that message part in the web service's WSDL
schema. Such input parameters are called ``bare``.
If a particular message part has a type which is actually a structure containing
a collection of simpler elements, then suds may be configured to map each of
those simpler elements to a single input parameter. Such input parameters are
called 'wrapped'.
If an input parameter is represented by structured XSD element containing other
elements, suds may treat it as either ``bare`` or ``wrapped``. If it is
considered ``wrapped``, then suds library's web service operation invocation
function will take values for the input parameter's internal elements as input
arguments, instead of taking only a single wrapper object as a value for the
external wrapper element.
``wrapped`` input parameter support has been implemented to make the interface
simpler for the user/programmer using suds to invoke web service operations. It
does not affect how the the resulting web service operation invocation request
is constructed, i.e. passing a suds object as a single ``bare`` input parameter
value, or passing matching contained element values as separate wrapped input
parameter values results in the same web service operation invocation request
being constructed.
Example:
--------
Consider an operation taking the following element as its only message part::
<xsd:element name="unga">
<sequence>
<xsd:element name="a" type="xsd:string"/>
<xsd:element name="b" type="xsd:integer"/>
<xsd:element name="c" type="MyType"/>
</xsd:sequence>
</xsd:element>
Suds may be configured to map that message part into with a single ``bare`` or
three ``wrapped`` input parameters.
If a ``bare`` input parameter is used, the operation invocation function would
take only a single argument:
* a suds object argument for element ``unga``
If ``wrapped`` input parameters are used, the operation invocation function
would take the following input arguments:
* a string argument for element ``a``
* an integer argument for element ``b``
* a suds object argument for element ``c``
==================================================================
Input parameter values in original and current suds implementation
==================================================================
* A user may or may not specify a value for a specific input parameter.
* We refer to unspecified or ``None`` input parameter values as `undefined`.
* We refer to all other input parameter values `defined`.
Original suds library implementation:
-------------------------------------
* An element may be explicitly marked as optional.
* ``choice`` input parameter structures not supported.
* A defined input parameter value is used directly.
* An undefined optional input parameter value is ignored.
* An undefined non-optional input parameter value is interpreted as an empty
string.
* Multiple values specified for a single input parameter are ignored.
* Extra input arguments are ignored.
Defects:
* ``choice`` input parameter structures not supported correctly. When used,
result in incorrectly constructed web service operation invocation requests.
* An ``all``/``choice``/``sequence`` input parameter structure may be explicitly
marked as optional, but this is ignored when deciding whether a specific input
parameter inside that structure is optional or not.
* No error when multiple values are specified for a single input parameter.
* No error on extra input arguments.
Current suds library implementation:
------------------------------------
* An element may be explicitly marked as optional.
* ``choice`` input parameter structures supported.
* Input parameters contained inside a ``choice`` input parameter structure
(either directly or indirectly) are always considered optional.
* An input parameter structure containing at least one input parameter with a
defined value (either directly or indirectly) is considered to have a defined
value.
* A defined input parameter value is used directly.
* An undefined optional input parameter value is ignored.
* An undefined non-optional input parameters value is treated as an empty
string.
Configurable features:
* Multiple values specified for a single input parameter may be reported as an
error.
* ``choice`` input parameter structure directly containing multiple input
parameters and/or input parameter structures with defined values may be
reported as an error.
* Extra input argument may be reported as an error.
Defects (demonstrated by existing unit tests):
* An ``all``/``choice``/``sequence`` input parameter structure may be explicitly
marked as optional, but this is ignored when deciding whether a specific input
parameter inside that structure is optional or not.
* Undefined value for a non-optional input parameter contained directly inside
an ``all``/``sequence`` input parameter structure contained inside a
``choice`` input parameter structure should be treated as an empty string if
the ``all``/``sequence`` input parameter structure has a defined value.
* A ``choice`` input parameter structure directly containing an input parameter
structure with no elements should be considered optional.
Still missing features:
-----------------------
* Non-optional ``choice`` input parameter structure with no defined value should
be treated as if its first input parameter's value had been specified as an
empty string.
|
