Soapfish

This project is not actively maintained. If you only need a dynamic client using a predefined WSDL rather than generated code, it is recommended that you check out Zeep.

Introduction

Soapfish is a library to use SOAP services in Python. The server-side component can be used with Django, Flask, Pyramid and other frameworks (including plain WSGI). The library can also be used to implement SOAP clients.

The library can help parsing/serializing a Python class model from/to XML and a bare-bones SOAP client.

Currently the project supports the following:

• SOAP 1.1 and 1.2
• WSDL 1.1
• WS-Addressing

Other notable features include:

• Support for Python 3.6+
• Licensed under the 3-clause BSD license
• Code generation utilities to get started quickly
• Parsing/serializing a Python class model from/to XML so you can easily work with XML even if you don't use SOAP at all.

Authors

Soapfish was originally written by Damian Powązka while working at Flight Data Services. At that time it was called Soapbox and from February 2012 was maintained by Flight Data Services. The project was forked in November 2013 by Felix Schwarz (based on the last BSD-licensed commit), after which a large number of new features were added by Thomas Recouvreux and Xavier Fernandez from Polyconseil between February and June 2014. Iuri de Silvio from Pricez added some features and fixed numerous bugs during 2015. In early 2016, Flight Data Services retired the unmaintained Soapbox project in favour of Soapfish.

Original Author:

• Damian Powązka (Flight Data Services)

Maintainers:

• Felix Schwarz (sponsored by Rechenzentrum für Berliner Apotheken Stein & Reichwald GmbH)
• Nick Pope (Flight Data Services)
• Iuri de Silvio (Pricez)

Major Contributors:

• Thomas Recouvreux (Polyconseil)
• Xavier Fernandez (Polyconseil)

Changes

0.6.0 (2020-??-??)

Project has been renamed to soapfish to distinguish it from the legacy soapbox project and allow for publishing the project on PyPI. Note that the rename effectively makes it backwards incompatible with previous releases due to API breakage.

Due to lack of time to maintain the original soapbox project, soapbox been retired by Flight Data Services who now contribute to and recommend the use of the soapfish fork.

• Security:
  • Fixed potential security issue - pattern restrictions were not applied correctly
• Features:
  • Add support for xsd.date (date range currently limited by datetime.date)
  • Add support relative schema paths (#49)
  • Add support to string restrictions length, minLength, maxLength, whiteSpace (#67)
  • Add support for choice indicator in ComplexTypes (#39)
    • Fixes validation of matching XML documents - previously sequences were always assumed - and code generation from WSDL/XSD.
    • Patch contributed by Martin Mrose, tests written by Felix Schwarz
  • Implemented a dispatcher for Flask (#53)
  • Implement service.route function to avoid changes to generated code (#68)
  • Changed to use requests instead of httplib2.
  • Added support for multiple inline schema imports and includes.
  • Added support for import of other WSDL documents.
  • Support for reordering of schema imports and includes and handle circular imports.
• Bug Fixes:
  • Make xsd.Decimal field accept Python Decimal (#52)
  • Fix relative imports with remote files. (#96)
  • Schema validation now also uses imported schemas correctly
  • Various fixes for wsdl2py and xsd2py when using Python 3
  • Fix exception in SOAPDispatcher when a handler does not return a SOAPResponse
  • Fix bad WSDL generation due to unresolved type references
  • Correctly apply pattern restrictions for simple types
  • Pattern restriction was not correctly serialized when generating schemas
  • Omit minOccurs=1 and maxOccurs=1 in xsd2py as these are the default. (The latter produces invalid code because xsd.Element doesn't support it.)
  • Restored ability to validate parsed XML using a soapfish schema in ComplexType
  • Fixed WSDL classes to more closely match the WSDL specifications.
  • Fixed WSDL classes to correctly define SOAP extensibility elements.
  • Removed reverse references from WSDL classes.
  • Fixed query string handling in dispatch to be more robust.
  • Support importing documents over HTTPS.
  • Fixed detection of XML schema namespaces.
  • Attempts to fix handling of remote vs local imports.
• Miscellaneous:
  • Renamed SoapboxRequest and SoapboxResponse to SOAPRequest and SOAPResponse respectively.
  • Support Python 3.6+, Django 1.11, 2.2 & 3.0, and Flask 1.0.0+
  • Improved testing against different versions of Python, Django & Flask.
  • Improved entry points for generation scripts - additional flags, etc.
  • Moved to using an external dependency for iso8601

0.5.1 (2014-06-12)

• Miscellaneous:
  • Downgrade log level on soap action discovery.

0.5.0 (2014-06-12)

• Miscellaneous:
  • Make elements inherit from schema namespace
  • Better logging in soap/stub
  • soap12: Quotes around action in HTTP header

0.4.0 (2014-05-06)

Project forked by Felix Schwarz as soapbox-bsd due to licensing incompatibilities.

Flight Data Services started using the GPL-incompatible OSL for the soapbox project. This fork is based on the last soapbox commit still using the original 3-clause BSD license (7d3516fe). Later on the fork received significant contributions from Thomas Recouvreux and Xavier Fernandez (Polyconseil).

• Features:
  • Added support for SOAP 1.2 and WSDL 1.2
  • Added support for WS-Addressing
  • Added support for fault actors (Damian Powązka)
  • Added support for Django >= 1.4
  • Added compatibility with Python 3
  • Added framework-agnostic SOAP dispatcher to support virtually any web framework.
• Bug Fixes:
  • Preserve elementFormDefault attribute in Schema
  • Many bug fixes for code generation and XML rendering
• Miscellaneous:
  • Ability to use custom SOAP headers
  • Middleware stack to hook into SOAP request processing
  • Better handling of invalid SOAP requests, e.g. missing bodies, invalid actions.

0.3.2 (2012-03-09)

• Miscellaneous:
  • Initial support for variable URL scheme and host
  • Test suite executes

0.3.1 (2012-03-08)

• Miscellaneous:
  • SSL certificate verification

0.3.0 (2012-03-02)

• Features:
  • Add option to disable schema validation on parsing:
    • Set xsd.VALIDATE_ON_PARSE to False.
  • Added some initial logging support:
    • Request logging available at when level set to DEBUG.
• Bug Fixes:
  • Allow unicode as a valid type for strings.
  • Check for Python keywords and prefix with underscore.
• Miscellaneous:
  • Python code templates now loaded from external files.
  • Generated code is now much cleaner.
  • Generated code is now timestamped.
  • Code tidying as reported by pyflakes and pep8.
  • Fixed a number of typographical errors.
  • Various name improvements to functions.
  • Updated .hgignore
• Known Issues:
  • Generated schema classes can be circular referencing.

To Do

This project is very, very promising:

• It is focused on XML and SOAP/WSDL without any compromise. In an ideal world soapfish works with each and every syntax allowed by these technologies.
• It allows you to have a representation of arbitrary XML including support for XSD. Parse any XML described by a schema into a nice class-based tree (and the other way round: serialization is possible as well).
• Because soapfish supports only SOAP and no other remoting protocol (e.g. ReST-style APIs with JSON) the API is not tied to the lowest common denominator. You should be able implement any given WSDL.

Unfortunately we're not there yet.

This is a typical open source software and XML/SOAP is usually not perceived as a fun project. So various users added some smaller features which they needed but typically there are many incomplete implementations above the very basic layer (the object model to represent XML/XSD programmatically). On the upside that means there are a lot of ways to improve the code and your contribution and make a big difference.

Here some bigger areas which need work:

• A much more comprehensive set of unit tests
• Implement support for additional web frameworks
• XSD schema generation (object graph to XSD file) has most of its logic in a very complex Jinja2 template which shows it limits. For example features like named xs:Elements with embedded anonymous ComplexTypes can not be serialized to XSD currently. However the code internally assumes that the class tree and the XSD representation contain the same information so this can lead to bugs.
• The XSD mapping is currently incomplete: Some types in schemas are not implemented at all (e.g. xs:date, xs:gYearMonth). Other types might not be parsed/serialized correctly. Also references to xs:elements are pretty incomplete right now.
• Generated code (e.g. WSDL handling or XSD mapping) usually has some syntax errors. Some of them are fixable on their own but often this is because of other missing features (see above). The output should be usable as scaffolding though.

Don't worry if the items on the list above seem to big for you. Just start out with something small, write tests and contribute them. Even a small (failing) unit test which demonstrates a current shortcoming is great.

You might also check out current skipped unit tests which usually represent missing functionality (though these might not be ideal beginner projects - if they were trivial to implement I would have done that already).

All these shortcomings and limitations exist only because of the lack of time and/or awareness about certain XSD features. The goal of this library is to fully implement XSD schemas and potentially SOAP/WSDL so patches (with tests) are always welcome.

Specific Items

• Fix circular dependency of generated schema classes.

See the TODO markers in soapfish/*.py for a complete list.