add a note document on suds library's argument parsing

These are notes collected while working on updating suds to report extra input
argument errors.

notes/argument_parsing.rst

@@ -0,0 +1,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.