[Zope-CVS] CVS: Packages/WebService/doc - Serializer.tex:1.1 make_table.py:1.1

[Brian Lloyd]

Update of /cvs-repository/Packages/WebService/doc
In directory cvs.zope.org:/tmp/cvs-serv24018/doc

Added Files:
	Serializer.tex make_table.py 
Log Message:
Added beginnings of Serializer module docs


=== Added File Packages/WebService/doc/Serializer.tex ===
\section{\module{WebService.Serializer}}
\declaremodule{}{WebService.Serializer}

(Give an overview of the architecture here...)

The \module{Serializer} module provides classes for managing serialization 
of data to and from SOAP messages. It supports the SOAP RPC encoding as 
described in the SOAP 1.1 specification, as well as ``document style'' 
schema-driven serialization.


\begin{classdesc}{Serializer}{}
A \class{Serializer} handles serialization and deserialization of values 
to and from SOAP messages. It contains built-in type handlers for the 
standard SOAP and XML Schema primitive types. One or more \class{XMLSchema} 
instances may be loaded into a serializer to provide support for the types 
defined in the corresponding schema.
\end{classdesc}

\begin{classdesc}{SerializationContext}{serializer}
A \class{SerializationContext} maintains per-message serialization state 
when serializing or deserializing data. The context maintains a handle to 
the \var{serializer} in use, as well as configuration data that can be 
affect the behavior of the serializer and its type handlers.
\end{classdesc}

\begin{excdesc}{SerializationError}
This exception is raised when errors occur in data serialization or 
deserialization.
\end{excdesc}


\subsection{Serializer Objects}

A \class{Serializer} instance contains a number of \emph{type handlers}, 
which know how to convert values of a given type to and from XML. The 
\class{Serializer} provides built-in type handlers for the standard SOAP 
and XML Schema simple types. The built-in type handlers are shared by 
all \class{Serializer} instances.

You can register new type handlers with a \class{Serializer} instance 
either explicitly or by loading one or more \class{XMLSchema} objects into 
the instance. 

[Note: some of the following API docs are ``pro-active truth'' :)]


\begin{methoddesc}[Serializer]{serialize}{
name, value, typeName, context\optional{ ,namespace}
}
xxx
\end{methoddesc}

\begin{methoddesc}[Serializer]{deserialize}{element, context}
xxx
\end{methoddesc}

\begin{methoddesc}[Serializer]{registerHandler}{typeName, handler}
xxx
\end{methoddesc}

\begin{methoddesc}[Serializer]{findHandler}{typeName\optional{ ,default}}
xxx
\end{methoddesc}

\begin{methoddesc}[Serializer]{loadSchema}{schema}
xxx
\end{methoddesc}


\subsection{SerializationContext Objects}

A \class{SerializationContext} instance contains per-message serialization 
state, and provides a common container used to pass various bits of data 
around during the serialization process. This data includes the 
\class{SOAPReader} or \class{SOAPWriter} to be used for input / output, 
information about the encoding style to be used, multi-reference data and 
a reference to the \class{Serializer} being used.

\begin{memberdesc}{serializer}
The \class{Serializer} instance associated with the serialization context.
\end{memberdesc}

\begin{memberdesc}{reader}
The \class{SOAPReader} that contains the message being deserialized, or 
\code{None} (if the context is for serialization rather than deserialization).
\end{memberdesc}

\begin{memberdesc}{writer}
The \class{SOAPWriter} that is managing the SOAP message being serialized, or 
\code{None} (if the context is for deserialization rather than serialization).
\end{memberdesc}


\begin{methoddesc}[SerializationContext]{mapReferences}{values}
Call this method to have the context map the reference relationships between 
the objects in the passed-in sequence of \var{values}. After calling this 
method, the members of \var{values} may be used as arguments to the 
\method{isMultiRef()} method.
\end{methoddesc}

\begin{methoddesc}[SerializationContext]{isMultiRef}{value}
Return true if a value is multi-reference (with regard to a sequence of 
values previously passed to \method{mapReferences()}.
\end{methoddesc}


\subsection{Python Type Mapping}

The mapping of SOAP / XML Schema simple datatypes to Python data types 
outlined in the table below. Note that unless otherwise specified, 'string' 
means either a Python (8-bit) string or Unicode type.

\begin{tableii}{l|l}{}{Schema Type}{Python Type}
\lineii{\code{xsd:boolean}}{\code{int}}
\lineii{\code{xsd:integer}}{\code{long}}
\lineii{\code{xsd:unsignedInt}}{\code{long}}
\lineii{\code{xsd:unsignedLong}}{\code{long}}
\lineii{\code{xsd:nonPositiveInteger}}{\code{long}}
\lineii{\code{xsd:nonNegativeInteger}}{\code{long}}
\lineii{\code{xsd:negativeInteger}}{\code{long}}
\lineii{\code{xsd:positiveInteger}}{\code{long}}
\lineii{\code{xsd:long}}{\code{long}}
\lineii{\code{xsd:int}}{\code{int}}
\lineii{\code{xsd:short}}{\code{int}}
\lineii{\code{xsd:unsignedShort}}{\code{int}}
\lineii{\code{xsd:byte}}{\code{int}}
\lineii{\code{xsd:unsignedByte}}{\code{int}}
\lineii{\code{xsd:decimal}}{\code{float}}
\lineii{\code{xsd:double}}{\code{float}}
\lineii{\code{xsd:float}}{\code{float}}
\lineii{\code{xsd:string}}{\code{string}}
\lineii{\code{xsd:normalizedString}}{\code{string}}
\lineii{\code{xsd:anyURI}}{\code{string}}
\lineii{\code{xsd:QName}}{\code{string}}
\lineii{\code{xsd:Name}}{\code{string}}
\lineii{\code{xsd:NCName}}{\code{string}}
\lineii{\code{xsd:token}}{\code{string}}
\lineii{\code{xsd:language}}{\code{string}}
\lineii{\code{xsd:NOTATION}}{\code{string}}
\lineii{\code{xsd:NMTOKENS}}{\code{sequence}}
\lineii{\code{xsd:NMTOKEN}}{\code{string}}
\lineii{\code{xsd:IDREFS}}{\code{sequence}}
\lineii{\code{xsd:IDREF}}{\code{string}}
\lineii{\code{xsd:ENTITIES}}{\code{sequence}}
\lineii{\code{xsd:ENTITY}}{\code{string}}
\lineii{\code{xsd:ID}}{\code{string}}
\lineii{\code{xsd:dateTime}}{\code{date-time tuple}}
\lineii{\code{xsd:timePeriod}}{\code{date-time tuple}}
\lineii{\code{xsd:duration}}{\code{date-time tuple}}
\lineii{\code{xsd:time}}{\code{date-time tuple}}
\lineii{\code{xsd:date}}{\code{date-time tuple}}
\lineii{\code{xsd:gYearMonth}}{\code{date-time tuple}}
\lineii{\code{xsd:gYear}}{\code{date-time tuple}}
\lineii{\code{xsd:gMonthDay}}{\code{date-time tuple}}
\lineii{\code{xsd:gDay}}{\code{date-time tuple}}
\lineii{\code{xsd:gMonth}}{\code{date-time tuple}}
\lineii{\code{xsd:base64Binary}}{\code{string}}
\lineii{\code{xsd:base64}}{\code{string}}
\lineii{\code{xsd:hexBinary}}{\code{string}}
\lineii{\code{enc:base64}}{\code{string}}
\lineii{\code{enc:arrayType}}{\code{sequence}}
\end{tableii}


There are also a set of default type mappings that are used by the 
serializer to guess an appropriate schema type when all it has to go on 
is the Python type of an object.

\begin{tableii}{l|l}{}{Schema Type}{Python Type}
\lineii{\code{string}}{\code{xsd:string}}
\lineii{\code{int}}{\code{xsd:integer}}
\lineii{\code{long}}{\code{xsd:long}}
\lineii{\code{float}}{\code{xsd:float}}
\lineii{\code{sequence}}{\code{soap-enc:Array}}
\end{tableii}



=== Added File Packages/WebService/doc/make_table.py ===
#! /usr/bin/env python

import sys, os, string


xsd_to_py_mapping = (
    ('xsd:boolean', 'int'),
    ('xsd:integer', 'long'),
    ('xsd:unsignedInt', 'long'),
    ('xsd:unsignedLong', 'long'),
    ('xsd:nonPositiveInteger', 'long'),
    ('xsd:nonNegativeInteger', 'long'),
    ('xsd:negativeInteger', 'long'),
    ('xsd:positiveInteger', 'long'),
    ('xsd:long', 'long'),
    
    ('xsd:int', 'int'),
    ('xsd:short', 'int'),
    ('xsd:unsignedShort', 'int'),
    ('xsd:byte', 'int'),
    ('xsd:unsignedByte', 'int'),
    
    ('xsd:decimal', 'float'),
    ('xsd:double', 'float'),
    ('xsd:float', 'float'),
    
    ('xsd:string', 'string'),
    ('xsd:normalizedString', 'string'),
    ('xsd:anyURI', 'string'),
    ('xsd:QName', 'string'),
    ('xsd:Name', 'string'),
    ('xsd:NCName', 'string'),
    ('xsd:token', 'string'),
    ('xsd:language', 'string'),
    
    ('xsd:NOTATION', 'string'),
    ('xsd:NMTOKENS', 'sequence'),
    ('xsd:NMTOKEN', 'string'),
    ('xsd:IDREFS', 'sequence'),
    ('xsd:IDREF', 'string'),
    ('xsd:ENTITIES', 'sequence'),
    ('xsd:ENTITY', 'string'),
    ('xsd:ID', 'string'),
    
    ('xsd:dateTime', 'date-time tuple'),
    ('xsd:timePeriod', 'date-time tuple'),
    ('xsd:duration','date-time tuple'),
    ('xsd:time', 'date-time tuple'),
    ('xsd:date', 'date-time tuple'),
    ('xsd:gYearMonth', 'date-time tuple'),
    ('xsd:gYear', 'date-time tuple'),
    ('xsd:gMonthDay', 'date-time tuple'),
    ('xsd:gDay', 'date-time tuple'),
    ('xsd:gMonth', 'date-time tuple'),
    
    ('xsd:base64Binary', 'string'),
    ('xsd:base64', 'string'),
    ('xsd:hexBinary', 'string'),
    
    ('enc:base64', 'string'),
    ('enc:arrayType', 'sequence'),
)

default_py_mapping = (
    ('string', 'xsd:string'),
    ('int', 'xsd:integer'),
    ('long', 'xsd:long'),
    ('float', 'xsd:float'),
    ('sequence', 'soap-enc:Array')
    )


def main():
    output = open('typemapping.txt', 'wb')
    line='\\begin{tableii}{l|l}{}{Schema Type}{Python Type}\n'
    output.write(line)
    for item in xsd_to_py_mapping:
        xsd_type, py_type = item
        line='\\lineii{\\code{%s}}{\\code{%s}}\n' % (xsd_type, py_type)
        output.write(line)
    line = '\\end{tableii}\n\n'
    output.write(line)

    line='\\begin{tableii}{l|l}{}{Schema Type}{Python Type}\n'
    output.write(line)
    for item in default_py_mapping:
        py_type, xsd_type = item
        line='\\lineii{\\code{%s}}{\\code{%s}}\n' % (py_type, xsd_type)
        output.write(line)
    line = '\\end{tableii}\n\n'
    output.write(line)

    output.close()
    sys.exit(0)


if __name__ == '__main__':
    main()