Suds

- Update exceptions to be more /standard/ python by using
`Exception.__init__()` to set `Exception.message` as suggested by
ticket 14; update bindings to raise `WebFault` passing (p).
- Add capability in bindings to handle multiple root nodes in the
returned values; returned as a composite object unlike when lists
are returned.
- Fix `soapAction` to be enclosed by quotes.
- Add support for `<xs:all/>`.
- Fix `unbounded()` method in `SchemaObject`.
- Refactored schema into new `xsd` package. Files just getting too
big. Added `execute()` to `Query` and retrofitted `suds` to
`execute()` query instead of using `Schema.find()` directly. Also,
moved hokey `start()` methods from schema, as well as, query
incrementation.
- Add `inject` keyword used to `inject` outbound SOAP messages and/or
inbound reply messages.
- Refactored SoapClient and
1) rename `send()` to `invoke(`)
2) split message sending from `invoke()` and place in `send()`
- Add `TestClient` which allows for invocation kwargs to have
`inject={'msg=, and reply='}` for message and reply injection.
- Add `Namespace` class to `sax` for better management of namespace
behavior; retrofix `suds` to import and use `Namespace`.
- Change the default namespace used to resolve referenced types
(having attributes `base=""`, `type=""`) so that when no prefix is
specified: uses XML (node) namespace instead of the
`targetNamespace`.
- Apply fix as defined by <davidglickonenw.org> in ticket 13.
- Update service definition to print to display service methods as
`my_method(xs:int arg0, Person arg1)` instead of
`my_method(arg0{xs:int}, arg1{Person})` which is more like
traditional method signatures.
- Add XSD/python type conversion to unmarshaller (`XBoolean` only);
refactor unmarshaller to use `Content` class which makes APIs
cleaner, adds symmetry between marshaller(s) and unmarshaller(s),
provides good mechanism for schema-property based type conversions.
- Refactored marshaller with Appenders; add `nobuiltin` flag to
`resolve()` to support fix for `returned_type()` and
`returned_collection()` in bindings.
- Add support for (202, 204) HTTP codes.
- Add `XBoolean` and mappings; add `findattr()` to `TreeResolver` in
preparation for type conversions.
- Updated schema and schema property loading (deep recursion stopped);
Changed `Imported` schemas so then no longer copy imported schemas,
rather the import proxies find requests; Add `ServiceDefinition`
class which provides better service inspection; also provides
namespace mapping and show types; schema property API simplified;
support for `xs:any` and `xs:anyType` added; Some schema lookup
problems fixed; Binding classes refactored slightly; A lot of debug
logging added (might have to comment some out for performance -some
of the args are expensive).
- Add `sudsobject.Property`; a property is a special `Object` that
contains a `value` attribute and is returned by the `Builder`
(factory) for schema-types without children such as: `<element/>`
and `<simpleType/>`; `Builder`, `Marshaller` and `Resolver` updated
to handle `Properties`; `Resolver` and `Schema` also updated to
handle attribute lookups (this was missing).
- Add groundwork for user defined SOAP headers.
- Fix `elementFormDefault` per ticket 7
- Remove unused kwargs from bindings; cache bindings in WSDL; retrofit
legacy `ServiceProxy` to delegate to {new} `Client` API; remove
keyword `nil_supported` in favor of natural handling by `nillable`
attribute on `<element/>` within schemas.
- Add support for `<element/>` attribute flags (`nillable` and
`form`).
- Add the `Proxy` (2nd generation API) class.
- Add accessor/conversion functions so that users do not need to
access `__x__` attributes. Also add `todict()` and `get_items()` for
easy conversion to dictionary and iteration.
- Search top-level elements for `ref` before looking deeper.
- Add `derived()` to `SchemaObject`. This is needed to ensure that all
derived types (WSDL classes) are qualified by `xsi:type` without
specifying the `xsi:type` for all custom types as did in earlier
`suds` releases. Update the literal marshaller to only add the
`xsi:type` when the type needs to be specified.
- Change ns promotion in `sax` to prevent ns promoted to parent when
parent has the prefix.
- Changed binding `returned_type()` to return the (unresolved)
`Element`.
- In order to support the new features and fix reported bugs, I\'m in
the process of refactoring and hopefully evolving the components in
`suds` that provide the input/output translations:

- `Builder` (translates: XSD objects =\> python objects)
- `Marshaller` (translates: python objects =\> XML/SOAP)
- `Unmarshaller` (translates: XML/SOAP =\> python objects)

This evolution will provide better symmetry between these components
as follows:

The `Builder` and `Unmarshaller` will produce python (subclass of
`sudsobject.Object`) objects with:

- `__metadata__.__type__` = XSD type (`SchemaObject`)
- subclass name (`__class__.__name__`) = schema-type name

and

The `Marshaller`, while consuming python objects produced by the
`Builder` or `Unmarshaller`, will leverage this standard information
to produce the appropriate output (XML/SOAP).

The 0.2.1 code behaves *mostly* like this but \... not quite. Also,
the implementations have some redundancy.

While doing this, it made sense to factor out the common schema-type
\"lookup\" functionality used by the `Builder`, `Marshaller` and
`Unmarshaller` classes into a hierarchy of `Resolver` classes. This
reduces the complexity and redundancy of the `Builder`, `Marshaller`
and `Unmarshaller` classes and allows for better modularity. Once
this refactoring was complete, the difference between the
literal/encoded `Marshallers` became very small. Given that the
amount of code in the `bindings.literal` and `bindings.encoded`
packages was small (and getting smaller) and in the interest of
keeping the `suds` code base compact, I moved all of the marshalling
classes to the `bindings.marshaller` module. All of the
`bindings.XX` sub-packages will be removed.

The net effect:

All of the `suds` major components:

- client (old: service proxy)
- WSDL
- schema (xsd package)
- resolvers
- output (marshalling)
- builder
- input (unmarshalling)

Now have better:

- modularity
- symmetry with regard to `Object` metadata.
- code re-use (\< 1% code duplication \-\-- I hope)
- looser coupling

and better provide for the following features/bug-fix:

- Proper level of XML element qualification based on
`<schema elementFormDefault=""/>` attribute. This will ensure
that when `elementFormDefault="qualified"`, `suds` will include
the proper namespace on root elements for both literal and
encoded bindings. In order for this to work properly, the
literal marshaller (like the encoded marshaller) needed to be
schema-type aware. Had I added the same schema-type lookup as
the encoded marshaller instead of the refactoring described
above, the two classes would have been almost a complete
duplicate of each other :-(

- The builder and unmarshaller used the `schema.Schema.find()` to
resolve schema-types. They constructed a path as `person.name.first`
to resolve types in proper context. Since `Schema.find()` was
stateless, it resolved the intermediate path elements on every call.
The new resolver classes are stateful and resolve child types *much*
more efficiently.
- Prevent name collisions in `sudsobject.Object` like the `items()`
method. I\'ve moved all methods (including class methods) to a
`Factory` class that is included in the `Object` class as a class
attr (`__factory__`). Now that *all* attributes have python built-in
naming, we should not have any more name collisions. This of course
assumes that no WSDL/schema entity names will have a name with the
python built-in naming convention but I have to draw the line
somewhere. :-)

- Update the `schema.py` `SchemaProperty` loading sequence so that the
schema is loaded in 3 steps:

1) Build the raw tree.
2) Resolve dependencies such as `ref` and `base`.
3) Promote grandchildren as needed to flatten (denormalize) the
tree.

The WSDL was also changed to only load the schema once and store it.
The schema collection was changed to load schemas in 2 steps:

1) Create all raw schema objects.
2) Load schemas.

This ensures that local imported schemas can be found when
referenced out of order. The `sax.py` `Element` interface changed:
`attribute()` replaced by `get()` and `set()`. Also, `__getitem__()`
and `__setitem__()` can be used to access attribute values. Epydocs
updated for `sax.py`. And \... last `<element ref=/>` now supported
properly.

- Fix logging by: NOT setting to info in `suds.__init__.logger()`; set
handler on root logger only; moved logger (log) from classes to
modules and use \_\_name\_\_ for logger name. NOTE: This means that
to enable SOAP message logging one should use:

>
> logger('suds.serviceproxy').setLevel(logging.DEBUG)
>

instead of:

>
> logger('serviceproxy').setLevel(logging.DEBUG)
>

- Add support for XSD schema `<attribute/>` nodes which primarily
affects objects returned by the `Builder`.
- Update `serviceproxy.py:set_proxies()` to log `DEBUG` instead of
`INFO`.
- Enhance schema `__str__()` to show both the raw XML and the model
(mostly for debugging).

- Contains the first cut at the rpc/encoded SOAP style.
- Replaced `Property` class with `suds.sudsobject.Object`. The
`Property` class was developed a long time ago with a slightly
different purpose. The `suds` `Object` is a simpler (more straight
forward) approach that requires less code and works better in the
debugger.
- The `Binding` (and the encoding) is selected on a per-method basis
which is more consistent with the WSDL. In \<= 0.1.7, the binding
was selected when the `ServiceProxy` was constructed and used for
all service methods. The binding was stored as `self.binding`. Since
the WSDL provides for a separate binding style and encoding for each
operation, `suds` needed to be change to work the same way.
- The `nil_supported` and `faults` flag(s) passed into the service
proxy using \*\*kwargs. In addition to these flags, a `http_proxy`
flag has been added and is passed to the `urllib2.Request` object.
The following args are supported:
- `faults` = Raise faults raised by server (default:`True`), else
return tuple from service method invocation as (HTTP code,
object).
- `nil_supported` = The bindings will set the `xsi:nil="true"` on
nodes that have a `value=None` when this flag is `True`
(default:`True`). Otherwise, an empty node `<x/>` is sent.
- `proxy` = An HTTP proxy to be specified on requests
(default:`{}`). The proxy is defined as `{protocol:proxy,}`.
- HTTP proxy supported (see above).
- `ServiceProxy` refactored to delegate to a `SoapClient`. Since the
service proxy exposes web services via `getattr()`, any attribute
(including methods) provided by the `ServiceProxy` class hides WS
operations defined by the WSDL. So, by moving everything to the
`SoapClient`, WSDL operations are no longer hidden without having to
use *hokey* names for attributes and methods in the service proxy.
Instead, the service proxy has `__client__` and `__factory__`
attributes (which really should be at low risk for name collision).
For now the `get_instance()` and `get_enum()` methods have not been
moved to preserve backward compatibility. Although, the preferred
API change would to replace:

> service = ServiceProxy('myurl')
> person = service.get_instance('person')

with something like:

> service = ServiceProxy('myurl')
> person = service.__factory__.get_instance('person')

After a few releases giving time for users to switch the new API,
the `get_instance()` and `get_enum()` methods may be removed with a
notice in big letters.

- Fixed problem where a WSDL does not define a `<schema/>` section and
`suds` can not resolve the prefixes for the
`http://www.w3.org/2001/XMLSchema` namespace to detect builtin types
such as `xs:string`.

- Added `Binding.nil_supported` to control how property values (out) =
`None` and empty tag (in) are processed.
- `service.binding.nil_supported = True` \-- means that property
values = `None` are marshalled (out) as `<x xsi:nil=true/>` and
\<x/\> is unmarshalled as `''` and `<x xsi:nil/>` is
unmarshalled as `None`.
- `service.binding.nil_supported = False` \-- means that property
values = `None` are marshalled (out) as `<x/>` *and*
`<x xsi:nil=true/>` is unmarshalled as `None`. The `xsi:nil` is
really ignored.
- THE DEFAULT IS `True`.
- Sax handler updated to handle `multiple character()` callbacks when
the sax parser \"chunks\" the text. When the `node.text` is `None`,
the `node.text` is set to the characters. Else, the characters are
appended. Thanks - \'<andrea.spinelliimteam.it>\'.
- Replaced special `text` attribute with `__text__` to allow for
natural elements named \"text\".
- Add unicode support by:
- Add `__unicode__()` to all classes with `__str__()`.
- Replace all `str()` calls with `unicode()`.
- `__str__()` returns UTF-8 encoded result of `__unicode__()`.
- XML output encoded as UTF-8 which matches the HTTP header and
supports unicode.
- `SchemaCollection` changed to provide the `builtin()` and `custom()`
methods. To support this, `findPrefixes()` was added to the
`Element` in `sax.py`. This is a better approach anyway since the
WSDL and schemas may have many prefixes to
\'<http://www.w3.org/2001/XMLSchema>\'. Tested using both doc/lit
and rpc/lit bindings.
- Refactored bindings packages from document & rpc to literal &
encoded.
- Contains the completion of *full* namespace support as follows:
- Namespace prefixes are no longer stripped from attribute values
that reference types defined in the WSDL.
- Schema\'s imported using `<import/>` should properly handle
namespace and prefix mapping and re-mapping as needed.
- All types are resolved, using fully qualified (w/ namespaces)
lookups.
- `Schema.get_type()` supports paths with and without ns prefixes.
When no prefix is specified the type is matched using the
schema\'s target namespace.
- Property maintains attribute names (keys) in the order added. This
also means that `get_item()` and `get_names()` return ordered
values. Although, I suspect ordering really needs to be done in the
marshaller using the order specified in the WSDL/schema.
- Major refactoring of the `schema.py`. The primary goals is
preparation for type lookups that are fully qualified by namespace.
Once completed, the prefixes on attribute values will no longer be
stripped (purged). Change summary:
1) `SchemaProperty` overlay classes created at `__init__()` instead
of on-demand.
2) schema imports performed by new `Import` class instead of by
`Schema`.
3) Schema loads top level properties using a factory.
4) All `SchemaProperty` /children/ lists are sorted by `__cmp__()`
in `SchemaProperty` derived classes. This ensures that types
with the same name are resolved in the following order
(`Import`, `Complex`, `Simple`, `Element`).
5) All /children/ `SchemaProperty` lists are constructed at
`__init__()` instead of on-demand.
6) The SchemaGroup created and WSDL class updated. This works
better then having the WSDL aggregate the `<schema/>` nodes
which severs linkage to the WSDL parent element that have
namespace prefix mapping.
7) `<import/>` element handles properly in that both namespace
remapping and prefix re-mapping of the imported schema\'s
`targetNamespace` and associated prefix mapping - is performed.
E.g. SCHEMA-A has prefix `tns` mapped as `xmlns:tns=http://nsA`
and has `targetNamespace='http://nsA'`. SCHEMA-B is importing
schema A and has prefix `abc` mapped as
`xmlns:abc='http://nsABC'`. SCHEMA-B imports A as
`<import namespace=http://nsB xxx schemaLocation=http://nsA/schema-a.xsd>`.
So, since SCHEMA-B will be referencing elements of SCHEMA-A with
prefix `abc` such as `abc:something`, SCHEMA-A\'s
`targetNamespace` must be updated as `http://nsABC` and all
elements with `type=tns:something` must be updated to be
`type=abc:something` so they can be resolved.
- Fixes unmarshalling problem where nodes are added to property as
(text, value). This was introduced when the bindings were
refactored.
- Fixed various `Property` print problems.

Notes:

> Thanks to Jesper Noehr of Coniuro for the majority of the rpc/literal
> binding and for lots of collaboration on `suds`.

- Provides proper handling of WSDLs that contain schema sections
containing XSD schema imports:
`<import namespace="" schemaLocation=""?>`. The referenced schemas
are imported when a `schemaLocation` is specified.
- Raises exceptions for HTTP status codes not already handled.

- Provides better logging in the modules get logger by hierarchal
names.
- Refactored as needed to truly support other bindings.
- Add `sax` module which replaces `ElementTree`. This is faster,
simpler and handles namespaces (prefixes) properly.