================================================
         generateDS.py -- Generate Python Data Structures
         ================================================

----------
What is it
----------

generateDS.py generates Python data structures from an Xschema
document.  It generates a file containing: (1) a Python class for
each element definition and (2) parsers (which use the Python
minidom module) for XML documents that satisfy the Xschema
document.  The class definitions contain:

- A constructor with initializers for member variables.

- Get and set methods for member variables.

- A 'build' method used during parsing to populate and instance.

- An 'export' method that will re-create the XML element in an XML
  document.

- An 'exportLiteral' method that will write out a text (literal)
  Python data structure that represents the content of the XML
  document.


---------------------------
How to build and install it
---------------------------

De-compress the generateDS distribution file.  Use something like
the following:
 
    tar xzvf generateDS-1.5a.tar.gz

Then, the regular Distutils commands should work:

    python setup.py build
    python setup.py install


-------------
How to use it
-------------

See generateDS.html for documentation.

Produce class definitions and sub-class definitions with something
like the following:

    $ python generateDS.py -o people.py -s people_subs.py people.xsd

Here is a test using the enclosed sample Xschema file:

    $ python generateDS.py -o people.py people.xsd
    $ python people.py people.xml


----------------
More information
----------------

More information on generateDS.py is in generateDS.html
in the distribution or
`generateDS -- Generate Data Structures from XML Schema --
http://www.rexx.com/~dkuhlman/generateDS.html
<http://www.rexx.com/~dkuhlman/generateDS.html>`_.

There is also a tutorial.  See tutorial/tutorial.html
in the distribution or
`generateDS -- Introduction and Tutorial --
http://www.rexx.com/~dkuhlman/generateds_tutorial.html
<http://www.rexx.com/~dkuhlman/generateds_tutorial.html>`_.


-----------
Limitations
-----------

XML Schema limitations -- There are lots of things in Xschema that
are not supported.  You will have to use a restricted sub-set of
Xschema to define your data structures.  See the documentation
(generateDS.html) for supported features.  See people.xsd and
people.xml for examples.

Mixed content -- generateDS.py generates a parser and data
structures that do not handle or represent mixed content.  Here is
an example of mixed content:

    <note>This is a <bold>nice</bold> comment.</note>

My only, and some what feeble, excuse for this is that
generateDS.py is intended for structured data rather than marked
up text.  However, whether my excuse is a good one or a feeble
one, you should be warned that if you anticipate needing mixed
text, do *not* use generateDS.py.

Large documents -- The parser generated by generateDS.py uses
minidom.  This means that the entire XML document must be read and
a DOM tree constructed in memory.  In addition, the data
structures generated by generateDS.py must occupy memory.  This
means that generateDS.py is not well-suited for applications that
read large XML documents, although what "large" means depends on
your hardware.  Notice that the parsing functions (parse() and
parseString()) over-write the variable doc so as to enable Python
to reclaim the space occupied by the DOM tree, which may help
alleviate the memory problem to some extent.


-------
License
-------

Copyright (c) 2002 Dave Kuhlman

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

[MIT License -- http://www.opensource.org/licenses/mit-license.php]


--------------
Change history
--------------

Version 2.5a (06/06/2011)
  * Fix for generation of default value in parameters for the
    constructors.
  * Fix for lookup of attribute value in generated buildAttributes
    methods -- Formerly, attribute names having a namespace prefix
    were not being found.
  * Added some support for xs:group -- Named model groups (model
    group definitions) are now treated as definitions of blocks of
    elements to be copied/inserted where referred to.  This
    replacement has been added to the preprocessing done in
    process_includes.py.  So, this <xs:group ref="some_def"/> is
    replaced by the contents of <xs:group name="some_def"> ...
  * Fix to generation of calls to validator methods for child
    elements.  Before the fix, the validators were called in
    buildAttributes methods but not in buildChildren.  Also,
    generation of the validator method (stubs) was also missing in
    some cases.  Thanks to Béres Botond for alerting me to this.
  * Fixes to generateds_gui.py -- Now it can load a session again.
    Also a fix to the check for and warnings about the changes to
    current session on exit.
  * process_includes.py -- Fix for yet another problem with
    including the same file multiple times when included from
    differnet directories.

Version 2.4c (03/21/2011)
  * Added minimal support for unsignedLong, unsignedInt, and
    unsignedByte.
  * Made the retrieval of the parent (superclass) name and parent
    object for an element more consistent.  Fixed some cases where
    this was not handled correctly, in particular, the generation of
    arguments and paramenters for ctors (__init__) was inconsistent
    and caused errors.
  * Regularized the handling of fromsubclass_ and added this
    handling to the exportChildren methods.  This is used to tell a
    superclass, during build and export, that the subclass has
    already performed certain operations.
  * Fix to process_includes.py so as to prevent it from loading
    schemas multiple times.  The check for already_processed was
    formerly incorrect.
  * Fix related to restrictions on complexType -- Do not generate
    call buildChildren in the superclass for restrictions (as
    opposed to extensions) of a complexType.  Ditto for
    exportChildren.  Note that restrictions must repeat (and
    restrict the value of) each sub-element that is to be included
    in the content of the restriction.  See:
    http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/#DerivByRestrict

Version 2.4b (02/21/2011)
  * Fix to generation the superclass in the class statement header
    line.  Formerly we did not correctly pick-up the superclass
    name (from extension base="").  Thanks to Timo Sugliani for
    finding this bug.

Version 2.4a (02/16/2011)
  * A few fixes to format of some error messages.
  * Clean-up names in the exportableClassList (__all__).
  * Modify reading session object/doc to use lxml instead of
    minidom.
  * Fix to process_includes.py to protect against crash when an
    import element is missing a schemaLocation attribute.
  * Fix to parsing and exporting simpleTypes declared as lists
    (<xs:list>).
  * Added new methods to class GeneratedsSuper to validate (during
    build) and format (during export) for simpleTypes declared as lists
    (<xs:list>).
  * Fix for incorrect detection of type during generation of build
    method.
  * Added first cut at generating Django models and forms.
    Thanks to Derek Corbett for this suggestion.
  * Added "meta-app" that generates Django database models and
    Django forms.  See doc and files in subdirectory django/.
  * Fix to generation of __all__ list: converted non-word
    characters to "_" etc
  * Fix to process_includes.py so that it uses the entire path to a
    file when trying to determine whether it duplicates a previous
    import.  Perhaps this will avoid skipping an import when
    attempting to import two files with the same name from
    different directories.  Thanks to Mihai Ibanescu for pointing
    out this fix.

Version 2.3b (12/28/2010)
  * Fix for simpleTypes defined as a restriction whose (ultimate)
    base type is a pre-defined simple type which were not generating
    correct (type-specific) code in build method.  Thanks to
    Noel Merket for finding this problem.
  * Fix for simpleTypes defined as a xs:list with "itemType"
    attribute where the type was not being recognized.
  * Fix so that we recognize some other simple types as xs:string
    type (e.g. xs:NMTOKEN, xs:ID, xs:Name).
  * To do:
    - If a simpleType is a restriction on another simpleType and
      the base simpleType definition is declared as a list, we are
      not recognizing that it is a list.

Version 2.3a (12/02/2010)
  * Added generatation of code to handle attributes inherited by a
    restriction from its base type and the types that the base
    extends (i.e.  from a restriction base class and its
    superclasses).  Thanks for help from Jaime Cepas.
  * Fix to code that generate the references to the superclass from
    a type that is an extension: special characters (e.g. dash)
    were not being cleaned/mapped.  Reported by Koen Smets; thanks.
  * To do:
    - In a restriction, inherited attributes can be "prohibited". 
      It would be nice if gDS would do something to block their
      use.
    - When:
          AbstractElement mixed=false and
          Element1 mixed=true base=AbstractElement and
          Element2 mixed=FALSE base=AbstractElement 
      Incorrect parse code is generated for Element2.
      Reported by Jaime Cepas.
    - It might be desirable if the getter functions could be asked
      to return values encoded to utf-8 for xs:string types.
    - Code that is generated to export to python code needs
      updating, in particular we need to update encoding of
      exported strings.  Thanks to Kristoffer Kobosko for
      reporting this.
    - Update to the code that generates code that exports Python
      literals (exportLiteral ...).  In particular: (1) fix
      excoding of Python code and of string literals (unicode, utf-8).

Version 2.2b (11/10/2010)
  * Added generation of __all__ global variable containing a list
    of generated class names.  This enables you to do a reasonably
    safe "from mymodule import *.  It's sorted, so it also gives
    you something in the way of an alphabetical table of contents
    of the generated classes.  Thanks to Jaime Cepas for this.
  * Added another fix so that the generated code for mixed content
    elements will not generate empty blank lines on export.  Thanks
    again to Jaime for this fix.
  * Added patch to sort mixed content in their class containers.
    Jaime contributed this one too.  Thanks again.
  * Added check for endless recursion while collection list of
    parent type element names.  When detected, raises exception
    that identifies the elements.  Thanks to Maximilian Holtzberg
    for finding this one.  One case that can cause this problem is
    when an element type definition extends a type definition of
    the same name in a different namespace.  Since generateDS.py
    ignores the namespace, this looks like a type that is extending
    itself.
  * Modified code generated to process token lists in order to
    prevent breakage processing some strings.
  * Updated the tutorial so that the examples use the new parsers
    (ElementTree or lxml).
  * The "Clear" buttons in generateds_gui.py is broken when run with
    GTK2.  generateds_gui.py is still usable, but, if you need to
    erase the contents of a text field, you will have to do so
    manually until I can figure out a fix.

Version 2.2a (9/14/2010)
  * Changes for coding consistency -- Used wrt() pervasively
    instead of outfile.write().
  * Re-write of process_includes.py -- It now handles
    xs:include/xs:import elements that include a file from another
    directory that incude a file relative to that directory that
    include a file across HTTP, and so on.
  * The command line option --search-path is no longer supported.  I
    don't think that behavior was standard for XML schema anyway.
    Removed support for search_path from generateDS.py,
    process_includes.py, and generateds_gui.py.
  * Added support for specifying additional name mappings in a config
    file: generateds_config.py.  That file, if it exists, must be
    located where it can be imported by generateDS.py and should
    contain a dictionary named NameTable.  For example, the following
    maps the name "range" to "rangeType" so that if the schema defines
    a complexType "range", generateDS.py will generate a class named
    "rangeType":
        NameTable = {
            'range': 'rangeType',
            }
    See the doc for more on this.
  * Instead of using the lower() function from the string module,
    added a function to the GeneratedsSuper class and used the string
    method.  Prepares for Python 3.0
  * Added "gds_" prefix to all methods in class GeneratedsSuper to
    make possible name clashes less likely.
  * Fixes to exporting elements with mixed="true" -- Reduced extra
    whitespace.
  * Fixes to building (capturing) attribute values for elements with
    anyAttribute="..." -- Eliminated capture of duplicate attribute
    values.
        
Version 2.1d (8/23/2010)
  * Fix to indentation of generated code in the build method for
    type checking of NonNegativeIntegerType.
  * Fix to generation parameters in call to superclass constructor. 
    Count of children was incorrect, triggering generation of
    valueOf_.
  * Known issue -- If type B extends type A, and type A declares
    anyAttribute, then duplicate attributes with the same name may
    be produced during export.
  * Known issue -- Some namespaces ("{URI}") are not converted to
    namespace prefix during export.  The needed information is not
    available during export.

Version 2.1c (8/8/2010)
  * Fix to functions parse, parseString, and parseLiteral so that
    they start the build with the correct root class.  I believe
    that there yet is another case that this does not handle,
    specifically when element name is different from class/type
    name and the element definition is not the first definition in
    the schema.
  * Fix to generation of build method for derived elements (i.e.
    elements with "extension base=".  These were being treated as
    if they were abstract, i.e. 'abstract="true"'.
  * Fix to generation of the call to the superclass constructor in
    the generated subclass module.  Prevented the generation of
    duplicate arguments.
  * Added a comment to the generated superclass module at the top
    that specifies the utf-8 source code encoding:
        # -*- coding: utf-8 -*- 

Version 2.1b (8/2/2010)
  * Fix to generation of export functions.  If no children, must
    generate "pass" statement.
  * Changed generated get_all_text function so that it uses an "if"
    statement instead of a conditional (if) expression.  The
    conditional expression does not work with older versions of
    Python.

Version 2.1a (7/8/2010)
  * Added ability to capture annotation/documentation element text
    as doc-strings in the generated classes.  Thanks to
    Roy Williams for suggesting this and for guidance.

Version 2.0b (6/24/2010)
  * Fix to generation of export method so that valueOf_ is exported
    when childCount == 0 and not isMixed.

Version 2.0a (6/21/2010)
  * Switched to use of lxml/ElementTree in generated files. 
    Thanks to Biswanath Patel and Jaime Huerta Cepas for
    encouraging me to implement the switch to lxml/ElementTree.
  * Modified the generation of functions parse(), parseString(),
    and parseLiteral() so that they automatically recognize the
    root element of an instance XML document and call the build
    method of the appropriate class.
  * Fix to hasContent_ method so that so that in elements defined
    with extension-base, the superclass is checked also.
  * For classes that must call an overridden method m in the
    superclass, switched to use "super(superclassname, self).m(...)"
    instead of "m.(self, ...)".
  * Known issues -- (1) generateDS.py loops and crashes with
    "RuntimeError: maximum recursion depth exceeded" on some
    schemas (for example collada_schema_1_4.xsd).  (2) Failure in
    process_includes.py with import of remote file and nested
    imports (for example collada_schema_1_5.xsd).

Version 1.20g (5/21/2010)
  * Update to documentation -- Added a section on suggested ways to
    handle/recognize different top level (root) elements.

Version 1.20f (5/3/2010)
  * Fix to generation of export so that anyAttribute does not cause
    duplicate attributes to be exported.
  * Fix so that we do a better job of determining whether a
    reference to a type is a simple, builtin type in generation of
    constructor.
  * Fix to generation of constructors so that (1) valueOf_ is
    intialized in subclass modules and (2) valueOf_ is initialized
    to None (rather than '').
  To do: Extend the --root-element flag so that we can specify both
    the tag name and the element/type name.  Sometimes they are
    different.

Version 1.20e (2/8/2010)
  * Fixed error that caused incorrect tag name to be exported
    when the tag name contains special characters and the tag name is
    different from the type name.
  * Fixed links so that latest versions are included in the install
    distribution file.

Version 1.20d (2/3/2010)
  * Updated version number/info in genereateds_gui.py.
  * Fix to process_includes.py -- Handle include elements and
    import elements in the same way.  In particular, allow both to
    reference schema files on either the local file system or
    remotely across the Net (via ftp or http).
  * Fix to generation of properties -- When the name of a member is
    mapped (e.g. a Python language keyword), wrong name for getter
    and setter was used.
  * Fix to generation of export methods: missing encoding.
  * Fix to selection of type for exportLiteral.
  * Added missing files in the tests/ directory to the distribution.

Version 1.20c (1/1/2010)
  * Replaced symbolic links in the distribution with hard links. 
    Symbolic links do not work on MS Windows.
  * Fix to the use of the subprocess module in generateds_gui.py,
    which had caused a problem on MS Windows.
  * Cosmetic fix in generateds_gui.py: labeled "Save" (session) button.
  * Fix so that File/Open action in generateds_gui.py will check
    for and warn user if the session data has been modified.
  * Fix to generation of code for simpleContent with restriction:
    now treats the restriction element as a superclass.  Thanks
    to Franis Sirkovic for catching this and for providing the
    patch.  Also added a unit test for this case.

Version 1.20b (12/14/2009)
  * Fix to process_includes.py so that it handles relative paths
    in include/import elements in the schema.
  * Various fixes and additions to the GUI front-end, e.g. added
    "Clear" buttons to erase some fields.
  * Fixed bug -- self.inRestrictionType was not initialized.
  * Added --session command line option to generateDS.py -- It
    can now use session files generated by the GUI front-end.
  * Fixes to the generation of the exportLiteral methods.  We can
    now export Python literal representation of an instance doc
    that can be read/imported by Python.
  * Added unit test for generation of Python literal representation.
  * With the help of Erica Tolbert, generateDS.py can now generate
    bindings for gcdml (Genomic Contextual Data Markup Language. 
    See http://gensc.org).  Thank you, Erica.
  * generateDS.py can now generate bindings for the following
    (rather large) schemas:
    - gcdml -- Genomic Contextual Data Markup Language --
      See http://gensc.org
    - Collada -- 3D Asset Exchange Schema 1.5 -- See
      http://www.khronos.org/collada/
    - Vcloud --Cloud computing -- See
      http://www.vmware.com/solutions/cloud-computing/vcloud.html
    - FpML -- Financial products Markup Language -- See
      http://www.fpml.org/

Version 1.20a (12/01/2009)
  * Added first version of the GUI front-end.  See the generateDS
    doc (generateDS.html).

Version 1.19a (10/21/2009)
  * Enhancement to the table of information generated in each class
    when the --member-specs=list|dict command line option is used. 
    For a complexType defined as a simpleType, we now generate a
    list of the simpleType and the simpleTypes it is based on using
    name "valueOf_".  Thanks to Ryan Leslie for much help and
    guidance with these changes.
    Example:
        'valueOf_': MemberSpec_('valueOf_', [u'RelationType', 
            u'RelationType2', u'xs:string'], 0),
    Note the following incompatible changes:
      - _MemberSpec changed to MemberSpec_ -- We want avoid posible
        name conflicts, not make it "weakly hidden".  See the Python
        style guide for more on this
      - _member_data_items changed to member_data_items_ -- Same
        reason.
      - Method MemberSpec_.get_data_type() now returns the last item
        if the types is a list and the single type if not a list.
      - Method MemberSpec_.get_data_type_chain() is a new method that
        returns the entire list of data types.
    The new tutorial (see tutorial/tutorial.html in the
    distribution) has an example of the use of the MemberSpec
    feature.
  * Fix to DecimalType -- In some cases treated as an integer. 
    Should be a float.  Thanks Ryan Leslie for catching this.
  * Removed last bits of the generation of a SAX parser.  It no
    longer worked and is not needed.
  * Several fixes to determination and handling of types.
  * Added unit test for extensions to simple types and for MemberSpec.
  * There is now a preliminary version of a tutorial.

Version 1.18f (9/14/2009)
  * Fixes to process_includes.py from Mihai Ibanescu.  These fixes
    address namespace and namespace prefix problems for XML tree
    that is copied into a document.  Thanks Mihai.
  * Added xs:anySimpleType to the list of OtherSimpleTypes.  This
    prevents anySimpleType from being used as a base type.
  * Change so that sub-classes are generated for types that do not
    have children or attributes.
  * Fixed crash that occurred when a simple type is nested in a simple
    type and use of memberTypes attribute.
  * Fix to GeneratedsSuper -- Inherit from "object".
  * Added command line option --no-versions,
    which, when used, tells generateDS.py not to insert the
    version in generated files.  This is useful when you want to
    be able to compare generated files and not detect version
    differences.
  * Patch to eliminate extra space after element tag.  Thank you
    Ryan Leslie.

Version 1.18e (9/1/2009)
  * Added patch from Mihai Ibanescu which handles and expands
    groups.  Also added Mihai's unit test for groups.  Thank you,
    Mihai.
  * Added patch, also from Mihai, that passes the node's text to
    the super-class constructor.  
  * Added patch that implements a --no-dates command line flag
    which, when used, tells generateDS.py not to insert the
    time-stamp in generated files.  This is useful when you want to
    be able to compare generated files and not detect date/time
    differences.  Thanks again to Mihai.

Version 1.18d (8/26/2009)
  * Automatic detection of the namespace prefix used in the schema
    document.  Thanks to Mihai Ibanescu for this enhancement.
  * Fix to deal conflicts with generateDS's internal function
    names, for example "build".  Thanks again to Mihai.
  * Upgrade to the unit test harness.  Replace popen (which is
    deprecated) with use of the subprocess module.  Thank you Mahai.
  * Fix in the class constructors (__init__) to cast XML primitive
    types (xs:integer, xs:float, etc) to Python built-in types
    (int, float, etc).  Thanks once more to Mahai.
  * Fix to add enumeration value resolution when the possible
    values are not declared in an explicit definition but in a "top
    level" type.  Also fix a bug with enumeration value population
    for elements where the unwound element stack contains more than
    one element.  Thanks to Chris Allan for this fix.

Version 1.18c (8/11/2009)
  * Small changes related to check for mixed content.
  * Enhancement to generation of hasContent_() method to check for items
    with maxOccurs > 1.
  * Fix for generation of test for valueOf_ in hasContent() method.
  * Fix for generation of initializers in ctor -- children were being
    skipped when the element is mixed.

Version 1.18b (7/29/2009)
  * Fix for exception with simpleType that is an extension of 
    another simpleType.
  * Change to mixed extension chain -- Will now generate class.
  * Fix to generation of constructors -- Will now initialize to
    default value for simpleTypes.
  * Fixed generations of validator methods, validator bodies, 
    and call to validator bodies for attributes.
  * Command line option "--validator-bodies" now triggers check for
    option value is an existing directory.
  * Various cleanup, deleting commented-out debug code, etc.
  * Now writing help messages, error messages to stderr instead of
    to stdout.

Version 1.18a (7/14/2009)
  * Added command line flag --member-specs to generate the member
    specifications as described in "User Methods" section of the doc.
    The member specs can be a list or a dictionary.
  * Fix to export indentation.  Thanks Tim Marchelli.
  * Added a utility script: generate_coverage.py which generates a
    dictionary of class names and classes from a (superclass) module
    generated by generateDS.py.

Version 1.17d (7/2/2009)
  * Fix for generation of recursively defined simpleTypes, e.g.
    a simpleType defined as a restriction of another simpleType.
    (see fix_simpletype comment in generateDS.py)
  * Added version number to generated class files.
  * Fixes to/for process_includes.py -- DirPath/DIRPATH now initialized
    correctly and fixed failure to initialize a local variable.

Version 1.17c (6/24/2009)
  * Fix for error generating code for exporting related to
    simpleType.
  * Fix for syntax error in export of boolean types.
  * Fix for export of elements with type of attribute defined
    in-line.
  * Fix to generation of export function when the --silence
    command line option is used.

Version 1.17b (6/10/2009)
  * Fix so that generateDS.py will still work with Python 2.4. 
    Thanks to Dave Sugar for that.

Version 1.17a (5/20/2009)
  * Modified export of children of type xs:string so that
    (1) if None, not exported and (2) if not None but an
    empty string, exported (example "<aa></aa>").
  * Generated calls to format_string(), format_integer(), etc
    in the generated export methods.  Enables the user to
    override these methods to customize format of exported
    values.  See the "Overridable methods" section in the
    doc (generateDS.html) for more info and for an
    explanation of how to override these methods.
    Currently used to give the user control over formatting
    of values during export.
  * Fixes to generated build and export methods so that
    elements defined as xs:simpleType as handled as
    the specificsimpleType xs:restriction base, for example
    xs:string, xs:integer, etc.

Version 1.16e (4/28/2009)
  * Eliminated generation of SAX parser.  I'm sure it no longer
    worked, anyway.
  * Fix to export of CDATA characters, provided by Kerim Mansour.
    Thanks.
  * Added support for command line option --external-encoding.
    Exported character data is now encoded to sys.getdefaultencoding()
    or to the encoding specified by command line option
    --external-encoding.
  * Added attributes (in addition to children) to the list of
    data type specifications in _MemberSpec/_member_data_items.
    This fix was provided by Ryan.
  * Several fixes suggested by Kerim Mansour including one related
    to export of CDATA.  Thank you Kerim.
  * Removed generation of SAX parser.  It did not work
    any more anyway.

Version 1.16d (3/25/2009)
  * Fixes to generation of the exportLiteral functions.  We
    can now do exportLiteral, then import the resulting file 
    in Python.  See generated parseLiteral() for an example.
  * Added an additional parameter to the export() methods.
    Now, you can call export() as follows:
        rootObj.export(outfile, 0,
            namespacedef_='xmlns:abc="http://www.abc.com/namespacelo"')
    which will insert the namespace prefix definition in the
    exported root element.
  * Added new command line option --namespacedef= to specify
    the namespacedef_ to be passed in by the generated
    parse() and parseString() functions.  Example use:
        generateDS.py --namespacedef='xmlns:abc="http://www.abc.com/"'
            -o out.py myschema.xsd

Version 1.16c (3/13/2009)
  * One more fix for abstract types -- When the implementation
    element/class for an abstract class exports itself, it adds
    the xsi:type="class_name" attribute.
  * A minor fix to handling namespace prefix and the -a command
    line option.
  * Additional fixes so that in constructors (__init__), all
    instance variables are initialized to None.
  * Some fixes to quoting and escaping quotes when exporting
    attribute values.  Thanks to Kerim Mansour for help with this.

Version 1.16b (3/9/2009)
  * Added support for restriction/list, i.e. a list of words
    separated by whitespace.

Version 1.16a (2/16/2009)
  * Generated export methods now check for empty content and 
    write out <xx ... /> rather than <xx ...></xx> if empty.
  * All generated constructors (__init__()) now initialize
    instance variables to None.
  * Generated export methods now check for None before attempting
    to write out attributes and children.
  * More consistent use of direct access to instance variables
    rather than calling getter methods with a class, that is
    use of self.xxx rather than self.get_xxx().

Version 1.15d (1/22/2009)
  * Fix to setup.py so that it also installs process_includes.py.
  * Enhancements to process_includes.py so that it can also
    retrieve included files via ftp and http.
  * Fixes for default values for attributes.
  * The above changes are all from Arne Grimstrup.  Thank you Arne.

Version 1.15c (11/26/2008)
  * Added switch (--silence) to cause generateDS.py to generate
    parsing functions that do not write output to stdout.  This fix
    contributed by Al Niessner.

Version 1.15b (11/24/2008)
  * Added Amnon Janiv's fixes for attribute groups and for logging.

Version 1.15a (11/20/2008)
  * Added support for abstract elements/types.  See:
    http://www.w3.org/TR/xmlschema-0/#abstract
    Thanks to Luigi Paioro for help with this.

Version 1.14g (10/17/2008)
  * Fix in generation of exportChildren (omitted "_" in "namespace".

Version 1.14f (10/06/2008)
  * Minor fix related to simple types in generateBuildStandard_1().

Version 1.14e (09/25/2008)
  * Minor fix for generation of syntax error (missing parenthesis).
  * Eliminated generation of specification of superclass
    (superclass =) for undefined types.
  * Fixed error setting value in SimpleElementDict.
  * Fixed error when getting type for building attributes.
  * Fixed and regularized exception reporting when building float
    and integer values.
  * Fixed error referring to simple types in build function.

Version 1.14d (08/28/2008)
  * Several fixes related to simple types.

Version 1.14c (08/16/2008)
  * One more namespace patch from Andre Adrian.
  * A fix to generated export methods for valueOf from Oscar (Oeg
    Bizz).
  * First attempt to fix the name_type problem, specifically an
    incorrect generation of the element name where it should
    generate the type name and vice versa.

Version 1.14b (06/17/2008):
  * More namespace patches from Andre Adrian.
  * Changed "lower()" to "str_lower()" in generated code so that
    we have a less common name in generated code.

Version 1.14a (06/03/2008):
  * In generateBuildFn, the generated code formerly would skip the
    children of a base class in an extension class if the
    extension class has children of its own.  This patch fixes
    that problem.  (The buildChildren call for the base class is
    inside a "if hasChildren == 0" block.)
  * The export functions formerly would output the attributes and
    children of the derived classes before those of the base
    class, where the XSL spec specifies that the base class
    elements are earlier than derived elements in a sequence.  This
    patch corrects the generation order.
  * This patch adds proper xs:boolean reading and writing to
    generateDS. "true" and "false" values in the XML will become
    True and False in Python, and will be written back out as
    "true" and "false", respectively.

Version 1.13a (05/26/2008):
  * Added support for generating namespace prefix during export
    if the XML Schema specifies the targetNamespace.  Thanks to
    Andre Adrian for implementing this feature. 

Version 1.12b (05/20/2008):
  * Patches to escape special XML characters (entities) in valueOf
    and attributes.  Thanks to Darius Powell for this fix.

Version 1.12a (05/06/2008):
  * Fix to name used to generate validation method.
  * Embedded process_includes.py functionality into generateDS.py.

Version 1.11d (04/28/2008)
  * Added support for specifying default values in attributes
    and elements that are primitive types.

Version 1.11c (03/31/2008)
  * A fix in enumeration building code.

Version 1.11b (11/19/2007)
  * Fixed bug that caused an infinite loop when a class has a
    simple type as a base/super class.
  * Added additional simple types to the list of recognized simple
    types.  For a list of simple types, see:
    http://www.w3.org/TR/xmlschema-0/#SimpleTypeFacets
  * Added additional Python keywords to list of transformed names.
    See global variable NameTable.

Version 1.11a (10/11/2007)
  * Various added features contributed by Chris Allan.  For more
    information see:
    http://www.rexx.com/~dkuhlman/generateDS.html#additional-features

Version 1.10a (08/21/2007, again)
  * Added xs:int basic type.  Handle same as xs:integer.
  * Generate tests so that for elements declared with
    minOccurs="0" and maxOccurs="1" and empty value, then
    export does not generate output.

Version 1.10a (05/11/2007)
  * Added support for user methods.  See section "User Methods" in
    the documentation.

Version 1.9a (03/21/2007, again)
  * Added process_includes.py which can be used as a pre-processor
    to process include elements and create an XML Schema document
    containing all included content.
  * Modified generateDS.py so that it will read its input from a
    pipe when given the command line argument "-" (dash).

Version 1.9a (02/13/2007, again)
  * Changed naming of getter and setter methods.  Default is to
    use get_var() and set_var() instead of getVar() and setVar().
    The old behavior is available using the flag
    --use-old-getter-setter.

Version 1.9a (01/30/2007, again)
  * Fix so that validator methods for simpleType are also
    generated when the <xs:simpleType> occurs within an
    <xs:element>.

Version 1.9a (12/04/2006, again)
  * Fixed errors (occuring on import of superclass module) when 
    an element is defined as an extension of an element that is
    defined as a simpleType restriction on an xs:string.

Version 1.9a (11/27/2006, again)
  * Fix for elements that have attributes and no nested children.
    Eliminated writing out new line chars in export methods.

Version 1.9a (10/22/2006, again)
  * Fix to capture text content of nodes defined with attributes
    but with no nested elements into member varialbe valueOf_.

Version 1.9a (10/10/2006)
  * Added minimal support for simpleType.
  * Generate stubs for and calls to validator methods for
    simpleType.
  * Retrieve bodies for validator methods for simpleTypes from
    files in a directory specified with the --validator-bodies
    command line flag.

Version 1.8d (10/4/2006, again)
  * Fixed several errors related to anyAttribute.  It was
    generating bad code if an element was defined with
    anyAttribute but had no other attributes.  And, in the same
    situation, it was not generating export code properly.

Version 1.8d (7/26/2006, again)
  * Allowed dot/period as special character in element tags/names.
  * Fixed several errors in generation of export and exportLiteral
    functions.  Special names (e.g. 'type', 'class') were not
    being mapped to special spellings (e.g. 'ttype', 'klass', ).
  * Fixed error in determining ExplicitDefine, which was
    preventing export of some objects.

Version 1.8d (7/19/2006, again)
  * Added support for empty elements, i.e. elements that have no
    children and no attributes.  Formerly, they were ignored due
    to a quirk in logic.

Version 1.8d (4/13/2006) 
  * Added support for the following simple types: duration, anyURI
    and unsignedShort.  They are coerced to (and treated the same
    as) xs:string, xs:string, and xs:integer, respectively

Version 1.8c (12/22/2005, again)
  * Fixed use of mapped names in generateExportLiteralFn().

Version 1.8c (12/20/2005, again)
  * Fix to generation of getters and setters for attributes.
    Formerly generating accessors that handled *lists* of attribute
    values.

Version 1.8c (12/15/2005, again)
  * Fix generated code so that it uses documentElement instead of
    childNodes[0] to get the root element.

Version 1.8c (5/10/2005, again)
  * Patch for <xs:attribute ref="xxxx"/> -- Use the value of ref
    as the name of the attribute.  I'm not sure whether this is
    correct in all situations.
  * Fix for generation of ctor for mixed type elements.  Before
    this fix, generateDS.py was failing to generate the
    initializers in the __init__ method signature.
  * Fix for generation of "class" declaration for extension
    classes whose base class name is qualified with a namespace
    (e.g., <xs:extension base="iodef:TextAbstractType">).  Removed
    the namespace.  This fix also corrected the order of
    generation of classes so that the base class is now correctly
    generated *before* the subclass.

Version 1.8c (4/26/2005)
  * Added support for several simple types: xs:token, xs:short,
    xs:long, xs:positiveInteger, xs:negativeInteger,
    xs:long, xs:nonPositiveInteger, xs:nonNegativeInteger,
    xs:date.
  * Fixed error produced when an element definition inherits from
    a simple type.

Version 1.8b (2/25/2005)
  * Added support for anyAttribute.

Version 1.8a (2/23/05, again)
  * Fixed incorrect generation of name and type for export
    functions for root element.
  * Fixed reference to root element type when root element name
    and type are different.

Version 1.8a (1/13/05, again)
  * Fixed incorrect handling of extension of in-line element
    definition.
  * Code cleanup in support of the above.

Version 1.8a (12/22/04)
  * Added support for attributeGroup.  Enables an XML Schema to
    define attribute groups and then include them in
    element/complexType definition.
  * Added support for substitutionGroup.  Enables use any of a set
    of element types as alternatives to another element type.
    Limitation: Does not work with simple element types.

Version 1.7b (11/15/04)
  * From an XML Schema, it is not possible to determine the
    outer-most element in instance documents.  generateDS.py now
    generates a parser (parseSelect) that first uses a small SAX
    parser to determine the outer-most element in the input
    document, then invokes the normal parser with that element as
    the root.

Version 1.7a (10/28/04)
  Thanks very much to Lloyd Kvam for help with these fixes and
  improvements.  His ideas, suggestions, and work have been
  extremely valuable.
  * Implementd partial support for <xsd:extension base="">.
    Limitation: extension elements cannot override members
    defined in a base.
  * Refactored generated methods export and build, so that they
    can be called by subclasses.
  * The generated method exportLiteral has been left behind during
    recent work.  Brought it up-to-date.
  * For Python, a super-class must be defined before the
    sub-classes that reference it.  Implemented a delaying
    mechanism that enforces this ordering of generation of classes.
  * Fixed a bug that occurred when an element is defined with
    maxOccurs given a value other than "1" or "unbounded".

Version 1.6d (10/1/04)
  * Several bug fixes.
  * Added command-line flag --subclass-suffix="X".  Changes the
    suffix appended to the class name in subclass files.  Default
    if omitted is "Sub".
  * Added an underscore to certain local variables to avoid name
    conflicts.
  * Thanks to Lloyd Kvam for help with this release.  Lloyd found
    and fixed a number of these problems.
  * Added command-line flag "--subclass-suffix", which specifies
    the suffix to be added to class names in subclass files.
    Default is "Sub".
  * Added command-line flag "--root-element", which makes a
    specified element name the assumed root of instance documents
  * In some schemas, attributes on a nested <complexType> pertain
    to the containing <element>.  Added code to copy the
    attributes from the <complexType> to the <element>, if it is
    nested.

Version 1.6c (9/15/04)
  * generateDS.py was not walking lower levels of the tree data
    structure collected by the SAX parser that describes the
    classes to be generated.  Now, function generate() calls
    function generateFromTree() to recursively walk lower levels
    of this tree structure.
  * Fixed various errors that were introduced or uncovered by the
    above change.
  * Strengthen handling of mixed content.  When an element
    definition (<element> or <complexType>) contains the attribute
    "mixed=" with a true value, then we generate the code for text
    content, e.g. getValue(), setValue(), capture value in
    build(), etc.

Version 1.6b (9/10/04, yet again)
  * Still fixing bug related to generating all the sub-class
    stubs.  All sub-classes were not being generated when no
    superclasses were generated (-o flag omitted), because there
    are data structures that are created when superclasses are
    generated and which are needed during sub-class generation.
    Now we *always* write out super-classes, but write them to a
    temp file if they are not requested.

Version 1.6b (8/26/04, again)
  * Fixed bug -- complexTypes defined in-line were omitted from the
    sub-class file.  Now these sub-classes are being generated.

Version 1.6b (8/18/04)
  * Added ability to access the text content of elements that are
    defined but have *no* nested elements.  The member variable is
    "valueOf_" (note underscore which will hopefully avoid name
    conflicts) and the getter and setter methods are "getValueOf_"
    and "setValueOf_".
  * Fixes to generation of exportLiteral methods.  Formerly,
    export of attributes was omitted.
  * Removed un-used function that contained "yield" statement,
    which caused problems with older versions of Python.

Version 1.6a (7/23/04, again)
  * Added optional generation of new style classes with
    properties.  This is experimental and, admittedly, not very
    useful, as the property functions are simple getters and
    setters.  Maybe someday ...  Use the "-m" flag to see the
    resulting code.

Version 1.6a (7/9/04, again)
  * Minor fixes.  Replaced dashes in names used as attributes (see
    cleanupName().

Version 1.6a (7/6/04, again)
  * For XMLBehaviors, implemented ability to retrieve
    implementation bodies for behaviors and for ancillaries
    (pre-conditions and post-conditions) from a Web address (URL).

Version 1.6a (6/30/04)
  * Added generation of behaviors.  An XML document can be used to
    specify behaviors (methods) to be added to generated sub-class
    files, including DBC (design by contract) pre- and
    post-condition tests.  See generateDS.html for more
    information on XMLBehaviors.

Version 1.5b (6/20/04, again)
  * Fixed handling namespace prefix in the XMLSchema file itself.
    generateDS.py now attempts to pick-up the namespace prefix
    (alias) from the "xmlns:" attribute on the "schema" element.

Version 1.5b (5/7/04)
  * Fixed several minor problems related to XML namespaces.
    Namespace prefix ignored when creating Python names (e.g. of
    classes and namespace prefix ignored during parsing.  That's
    about the best I know to do right now.
  * Fixed problems in generating code for names containing dashes.
    Now using underscore in place of dashes for Python names.

Version 1.5a (3/24/04)
  * Added keyword arguments to the generated factory functions.
  * Added generation of method "exportLiteral" and related support
    to export elements/instances to Python data structure
    literals.

Version 1.4c (3/10/04)
  * Element <complexType> in XSchema file not handled correctly.
    Fixed this so that when <complexType> is at top level, it will
    be handled the same way that an <element> is handled.  Note:
    We still have problems with <complexType> elements that are
    more deeply nested.

Version 1.4c (3/8/04)
  * Added ability to pass namespace abbreviation from the command
    line.  For example, the "-a" option enables you to replace
    "xs:" with "xsd:".

Version 1.4b (9/30/03, again)
  * Removed dependence on PyXML.  Will now import XML support from
    PyXML, if it is available, but if not, imports from the
    Python standard library.

Version 1.4b (9/30/03)
  * Fixed name conflict in factory function (added underscore).
  * Added generation of saxParseString function (parse string, not
    file/URL).
  * Fixed error -- ome constructors not using factory.

Version 1.4a (9/17/03)
  * Added generation of a SAX parser.

Version 1.3c (9/11/03)
  * Fixed problem caused by shared content model, i.e. when a
    field (content) is declared with a complex type and the name
    and the type are different.  The fix enabled the field name
    and the type of the object in that field to be different.

Version 1.3b (9/9/03)
  * Fixed error when a separate xs:element declaration is used for
    elements declared with a simple type.

Version 1.3a (8/18/03)
  * Removed YAML support.
  * Fixed error in name generation in generateBuildFn().
  * Various fixes and cleanup in tests/ and Demo/.

Version 1.2a (again, 5/16/03)
  * Fixed error in code generation for boolean attributes.
  * Fixed error in code generation for float values.
  * Added very simple unit tests in tests directory.  Can be run
    with:
        cd tests
        python test.py

Version 1.2a (3/14/03)
  * Added support for XML Schema xs:double and xs:boolean types.

Version 1.1a (8/13/02)
  * Added ability to generate subclass stubs for user method
    implementation.
  * A bit of clean-up to the command line options.

Version 1.0a (3/15/02)
  * Initial release


-----
To do
-----

The following enhancements and fixes remain to be done:

- The <sequence> element can have "minOccurs" and "maxOccurs"
  attributes.  I'm guessing, but am not sure that this specifies
  repeated groups.  For example, the following:

      <xs:sequence minOccurs="0" maxOccurs="unbounded">
          <xs:element name="description" type="xs:string"/>
          <xs:element name="size" type="xs:integer"/>
      </xs:sequence>

  specifies that we can have any number of pairs of elements
  "description" and "size".  A future enhancement to generateDS.py
  would enable us to specify and enforce this restriction.

- And so many more complexities in the XSchema specifications.


Dave Kuhlman
dkuhlman@rexx.com
http://www.rexx.com/~dkuhlman


This file was modified by PyCharm 1.2.1 for binding GitHub repository