SOAPpy/docs/MethodParameterNaming.txt

Experimental method for handing ordered vs named method parameters
------------------------------------------------------------------

There is an incompatibility with the way that Python and SOAP handle
method arguments: SOAP requires that all arguments have names and that
they are presented in the same order as the method signature. Python
(like other scripting languages, notably the S language) has the
concept of unnamed arguments.  Further Python does not preserve the
order of named arguments, since they are handled using the dictionary
data type.  It seems to me that this makes it impossible to fully meet
the SOAP specification without significant modifications to the Python
method of handling named arguments or to the Python dictionary class.

Historically SOAPpy has attempted to work around this issue by
handling all arguments as unnamed unless the method or function was
explicitly flagged, in which case all arguments were considered named.
This has resulted in a several problems, particularly for a SOAPpy
client communicating with a SOAPpy server.  First, when named
arguments were used in call to a non-flagged function, the argument
would silently be reordered by the sender (since they were stored
using a Python dictionary), *and* the names would be ignored by the
receiver, which assumed that the parameters were unnamed and only the
order was significant.  This results in incorrect argument matching.
This problem also occurred with mixed named and unnamed arguments.

For my primary SOAP application, it is not reasonable to flag all of
the SOAPpy methods as requiring named arguments, for a variety of
reasons.  One reason is that the available methods are not known
apriori by the client software, hence the names of the arguments are
not known.  Second, many of the methods provide a large number of
optional arguments, making it impractical to specify them all.

In an attempt to overcome this problem, I implemented an experimental
and non-standard method of handling named and unnamed arguments.  This
mechanism is enabled in SOAPpy by setting
SOAPpy.SOAP.Config.specialArgs=1, and disabled by setting
SOAPpy.SOAP.Config.specialArgs=0.

When enabled, parameters with names of the form v#### (i.e., matching
the regexp "^v[0-9]+$") are assumed to be unnamed parameters and are
passed to the method in numeric order.  All other parameters are
assumed to be named and are passed using the name.  Outgoing SOAP
method calls now always generate names in this way--whether or not
specialArgs is enabled. 


I selected the form v#### because it is a valid XML name, but is
unlikely to be used as a parameter name.

[As it turns out, this choice was fortitous because Apache's SOAP tool
uses the same system.]

In my testing, this mechanism for handling method parameter names
works fine between a SOAPpy client and a SOAPpy server, and resolves
the parameter reordering problems I was experiencing.  This system
seems unlikely to have any negative side effects on other SOAP
applications, except in the (hopefully) rare case when v#### might be
used as an actual parameter name.

**In version 0.9.9-pre1, this feature is enabled by default.** Please
let me know if there are situations where this causes problems.

Note that this mechanism is only a partial solution, since it is still
impossible to return named parameters in a specified order using
SOAPpy. SOAP applications or implementations which require this
feature are simply not compatible with SOAPpy.

-Greg Warnes <Gregory.R.Warnes@Pfizer.com>
2003-03-07 (updated 2003-11-14)