This repository has been archived by the owner on Oct 19, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 2
/
generateDS.html
3388 lines (3334 loc) · 183 KB
/
generateDS.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>generateDS -- Generate Data Structures from XML Schema</title>
<meta name="author" content="Dave Kuhlman" />
<style type="text/css">
/* css */
body {
font: 90% 'Lucida Grande', Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
background: #ffffff;
color: black;
margin: 2em;
padding: 2em;
}
a[href] {
color: #436976;
background-color: transparent;
}
a.toc-backref {
text-decoration: none;
}
h1 a[href] {
text-decoration: none;
color: #fcb100;
background-color: transparent;
}
a.strong {
font-weight: bold;
}
img {
margin: 0;
border: 0;
}
p {
margin: 0.5em 0 1em 0;
line-height: 1.5em;
}
p a {
text-decoration: underline;
}
p a:visited {
color: purple;
background-color: transparent;
}
p a:active {
color: red;
background-color: transparent;
}
a:hover {
text-decoration: none;
}
p img {
border: 0;
margin: 0;
}
h1, h2, h3, h4, h5, h6 {
color: #003a6b;
background-color: transparent;
font: 100% 'Lucida Grande', Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
margin: 0;
padding-top: 0.5em;
}
h1 {
font-size: 160%;
margin-bottom: 0.5em;
border-bottom: 1px solid #fcb100;
}
h2 {
font-size: 140%;
margin-bottom: 0.5em;
border-bottom: 1px solid #aaa;
}
h3 {
font-size: 130%;
margin-bottom: 0.5em;
text-decoration: underline;
}
h4 {
font-size: 110%;
font-weight: bold;
}
h5 {
font-size: 100%;
font-weight: bold;
}
h6 {
font-size: 80%;
font-weight: bold;
}
ul a, ol a {
text-decoration: underline;
}
dt {
font-weight: bold;
}
dt a {
text-decoration: none;
}
dd {
line-height: 1.5em;
margin-bottom: 1em;
}
legend {
background: #ffffff;
padding: 0.5em;
}
form {
margin: 0;
}
dl.form {
margin: 0;
padding: 1em;
}
dl.form dt {
width: 30%;
float: left;
margin: 0;
padding: 0 0.5em 0.5em 0;
text-align: right;
}
input {
font: 100% 'Lucida Grande', Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
color: black;
background-color: white;
vertical-align: middle;
}
abbr, acronym, .explain {
color: black;
background-color: transparent;
}
q, blockquote {
}
code, pre {
font-family: monospace;
font-size: 1.2em;
display: block;
padding: 10px;
border: 1px solid #838183;
background-color: #eee;
color: #000;
overflow: auto;
margin: 0.5em 1em;
}
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
tt.docutils {
background-color: #dddddd;
}
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="generateds-generate-data-structures-from-xml-schema">
<h1 class="title">generateDS -- Generate Data Structures from XML Schema</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Dave Kuhlman</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td>dkuhlman (at) davekuhlman (dot) org</td></tr>
<tr><th class="docinfo-name">Address:</th>
<td><pre class="address">
<a class="first last reference external" href="http://www.davekuhlman.org">http://www.davekuhlman.org</a>
</pre>
</td></tr>
</tbody>
</table>
<!-- Do not modify the following version comments.
They are used by updateversion.py. -->
<!-- version -->
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">revision:</th><td class="field-body">2.29.3</td>
</tr>
</tbody>
</table>
<!-- version -->
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">date:</th><td class="field-body">December 11, 2017</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Copyright (c) 2004 Dave Kuhlman. This documentation
and the software it describes is covered by The MIT License:
<a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">http://www.opensource.org/licenses/mit-license.php</a>.</td>
</tr>
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><tt class="docutils literal">generateDS.py</tt> generates Python data structures (for
example, class definitions) from an XML Schema document. These
data structures represent the elements in an XML document
described by the XML Schema. It also generates parsers that
load an XML document into those data structures. In addition,
a separate file containing subclasses (stubs) is optionally
generated. The user can add methods to the subclasses in order
to process the contents of an XML document.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#introduction" id="id7">1 Introduction</a></li>
<li><a class="reference internal" href="#where-to-find-it" id="id8">2 Where To find it</a><ul class="auto-toc">
<li><a class="reference internal" href="#download" id="id9">2.1 Download</a></li>
<li><a class="reference internal" href="#support-and-more-information" id="id10">2.2 Support and more information</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-build-and-install-it" id="id11">3 How to build and install it</a><ul class="auto-toc">
<li><a class="reference internal" href="#requirements" id="id12">3.1 Requirements</a></li>
<li><a class="reference internal" href="#installation" id="id13">3.2 Installation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#packaging-your-code" id="id14">4 Packaging your code</a></li>
<li><a class="reference internal" href="#the-command-line-interface-how-to-use-it" id="id15">5 The command line interface -- How to use it</a><ul class="auto-toc">
<li><a class="reference internal" href="#running-generateds-py" id="id16">5.1 Running <tt class="docutils literal">generateDS.py</tt></a></li>
<li><a class="reference internal" href="#command-line-options" id="id17">5.2 Command line options</a></li>
<li><a class="reference internal" href="#name-conflicts-etc" id="id18">5.3 Name conflicts etc.</a><ul class="auto-toc">
<li><a class="reference internal" href="#conflicts-with-python-keywords" id="id19">5.3.1 Conflicts with Python keywords</a></li>
<li><a class="reference internal" href="#conflicts-between-child-elements-and-attributes" id="id20">5.3.2 Conflicts between child elements and attributes</a></li>
<li><a class="reference internal" href="#cleaning-up-names-with-special-characters-etc" id="id21">5.3.3 Cleaning up names with special characters etc.</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#the-graphical-user-interface-how-to-use-it" id="id22">6 The graphical user interface -- How to use it</a></li>
<li><a class="reference internal" href="#common-problems" id="id23">7 Common problems</a><ul class="auto-toc">
<li><a class="reference internal" href="#namespace-prefix-mis-match" id="id24">7.1 Namespace prefix mis-match</a></li>
<li><a class="reference internal" href="#using-multiple-subclass-modules-with-the-same-superclass-module" id="id25">7.2 Using multiple subclass modules with the same superclass module</a></li>
</ul>
</li>
<li><a class="reference internal" href="#supported-features-of-xml-schema" id="id26">8 Supported features of XML Schema</a><ul class="auto-toc">
<li><a class="reference internal" href="#attributes-no-nested-children" id="id27">8.1 Attributes + no nested children</a></li>
<li><a class="reference internal" href="#mixed-content" id="id28">8.2 Mixed content</a></li>
<li><a class="reference internal" href="#anyattribute" id="id29">8.3 anyAttribute</a></li>
<li><a class="reference internal" href="#element-extensions" id="id30">8.4 Element extensions</a></li>
<li><a class="reference internal" href="#attribute-groups" id="id31">8.5 Attribute groups</a></li>
<li><a class="reference internal" href="#substitution-groups" id="id32">8.6 Substitution groups</a></li>
<li><a class="reference internal" href="#primitive-types" id="id33">8.7 Primitive types</a></li>
<li><a class="reference internal" href="#simpletype" id="id34">8.8 simpleType</a></li>
<li><a class="reference internal" href="#list-values-optional-values-maxoccurs-etc" id="id35">8.9 List values, optional values, maxOccurs, etc.</a></li>
<li><a class="reference internal" href="#simpletype-and-validators" id="id36">8.10 simpleType and validators</a><ul class="auto-toc">
<li><a class="reference internal" href="#generating-validator-bodies-from-xml-schema" id="id37">8.10.1 Generating validator bodies from XML schema</a></li>
<li><a class="reference internal" href="#user-written-validator-bodies" id="id38">8.10.2 User written validator bodies</a></li>
<li><a class="reference internal" href="#turning-off-validation-of-simpletype-data" id="id39">8.10.3 Turning off validation of <tt class="docutils literal">simpleType</tt> data</a></li>
<li><a class="reference internal" href="#additional-notes-on-simpletype-validation" id="id40">8.10.4 Additional notes on <tt class="docutils literal">simpleType</tt> validation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#include-file-processing" id="id41">8.11 Include file processing</a></li>
<li><a class="reference internal" href="#abstract-types" id="id42">8.12 Abstract types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-xml-schema-input-to-generateds" id="id43">9 The XML schema input to generateDS</a><ul class="auto-toc">
<li><a class="reference internal" href="#additional-constructions" id="id44">9.1 Additional constructions</a><ul class="auto-toc">
<li><a class="reference internal" href="#complextype-at-top-level" id="id45">9.1.1 <complexType> at top-level</a></li>
<li><a class="reference internal" href="#use-of-ref-instead-of-name-and-type-attributes" id="id46">9.1.2 Use of "ref" instead of "name" and "type" attributes</a></li>
<li><a class="reference internal" href="#extension-types" id="id47">9.1.3 Extension types</a></li>
<li><a class="reference internal" href="#elements-containing-mixed-content" id="id48">9.1.4 Elements containing mixed content</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#id2" id="id49">10 XMLBehaviors</a><ul class="auto-toc">
<li><a class="reference internal" href="#the-xmlbehaviors-input-file" id="id50">10.1 The XMLBehaviors input file</a></li>
<li><a class="reference internal" href="#implementing-other-sources-for-implementation-bodies" id="id51">10.2 Implementing other sources for implementation bodies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#additional-features" id="id52">11 Additional features</a><ul class="auto-toc">
<li><a class="reference internal" href="#xsd-list-element-support" id="id53">11.1 xsd:list element support</a></li>
<li><a class="reference internal" href="#xsd-enumeration-support" id="id54">11.2 xsd:enumeration support</a></li>
<li><a class="reference internal" href="#xsd-union-support" id="id55">11.3 xsd:union support</a></li>
<li><a class="reference internal" href="#extended-xsd-choice-support" id="id56">11.4 Extended xsd:choice support</a></li>
<li><a class="reference internal" href="#arity-minoccurs-maxoccurs-etc" id="id57">11.5 Arity, minOccurs, maxOccurs, etc</a></li>
<li><a class="reference internal" href="#more-thorough-content-type-and-base-type-resolution" id="id58">11.6 More thorough content type and base type resolution</a></li>
<li><a class="reference internal" href="#making-top-level-simpletypes-available-from-xschemahandler" id="id59">11.7 Making top level simpleTypes available from XschemaHandler</a></li>
<li><a class="reference internal" href="#namespaces-inserting-namespace-definition-in-exported-documents" id="id60">11.8 Namespaces -- inserting namespace definition in exported documents</a></li>
<li><a class="reference internal" href="#support-for-xs-any" id="id61">11.9 Support for xs:any</a></li>
<li><a class="reference internal" href="#generating-lxml-element-tree" id="id62">11.10 Generating Lxml Element tree</a><ul class="auto-toc">
<li><a class="reference internal" href="#mapping-generateds-objects-to-lxml-elements-and-back" id="id63">11.10.1 Mapping generateDS objects to Lxml Elements and back</a></li>
</ul>
</li>
<li><a class="reference internal" href="#specifying-names-for-anonymous-nested-type-definitions" id="id64">11.11 Specifying names for anonymous nested type definitions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-use-the-generated-source-code" id="id65">12 How to use the generated source code</a><ul class="auto-toc">
<li><a class="reference internal" href="#the-parsing-functions" id="id66">12.1 The parsing functions</a></li>
<li><a class="reference internal" href="#recognizing-the-top-level-element" id="id67">12.2 Recognizing the top level element</a></li>
<li><a class="reference internal" href="#the-export-methods" id="id68">12.3 The export methods</a><ul class="auto-toc">
<li><a class="reference internal" href="#method-export" id="id69">12.3.1 Method export</a></li>
<li><a class="reference internal" href="#method-exportliteral" id="id70">12.3.2 Method <tt class="docutils literal">exportLiteral</tt></a><ul class="auto-toc">
<li><a class="reference internal" href="#what-it-does" id="id71">12.3.2.1 What It Does</a></li>
<li><a class="reference internal" href="#why-you-might-care" id="id72">12.3.2.2 Why You Might Care</a></li>
<li><a class="reference internal" href="#how-to-use-it" id="id73">12.3.2.3 How to use it</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exporting-compact-xml-documents" id="id74">12.3.3 Exporting compact XML documents</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-instances" id="id75">12.4 Building instances</a></li>
<li><a class="reference internal" href="#using-the-subclass-module" id="id76">12.5 Using the subclass module</a></li>
<li><a class="reference internal" href="#elements-with-attributes-but-no-nested-children" id="id77">12.6 Elements with attributes but no nested children</a></li>
<li><a class="reference internal" href="#id4" id="id78">12.7 Mixed content</a></li>
<li><a class="reference internal" href="#id6" id="id79">12.8 anyAttribute</a></li>
<li><a class="reference internal" href="#user-methods" id="id80">12.9 User Methods</a></li>
<li><a class="reference internal" href="#overridable-methods-generatedssuper-py" id="id81">12.10 Overridable methods -- generatedssuper.py</a></li>
<li><a class="reference internal" href="#the-element-name-to-class-name-dictionary" id="id82">12.11 The element name to class name dictionary</a></li>
<li><a class="reference internal" href="#adding-custom-exported-attributes-and-namespace-prefix-definitions" id="id83">12.12 Adding custom exported attributes and namespace prefix definitions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#one-per-generating-separate-files-from-imported-included-schemas" id="id84">13 "One Per" -- generating separate files from imported/included schemas</a><ul class="auto-toc">
<li><a class="reference internal" href="#approach-1-command-line-option-one-file-per-xsd" id="id85">13.1 Approach 1 -- Command line option --one-file-per-xsd</a></li>
<li><a class="reference internal" href="#approach-2-extraction-and-generation-utilities" id="id86">13.2 Approach 2 -- Extraction and generation utilities</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-modify-the-generated-code" id="id87">14 How to modify the generated code</a><ul class="auto-toc">
<li><a class="reference internal" href="#adding-features-to-class-definitions" id="id88">14.1 Adding features to class definitions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examples-and-demonstrations" id="id89">15 Examples and demonstrations</a><ul class="auto-toc">
<li><a class="reference internal" href="#django-generating-models-and-forms" id="id90">15.1 Django -- Generating Models and Forms</a><ul class="auto-toc">
<li><a class="reference internal" href="#how-to-generate-django-models-and-forms" id="id91">15.1.1 How to generate Django models and forms</a></li>
<li><a class="reference internal" href="#how-it-works" id="id92">15.1.2 How it works</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#sample-code-and-extensions" id="id93">16 Sample code and extensions</a><ul class="auto-toc">
<li><a class="reference internal" href="#capturing-xs-date-elements-as-dates" id="id94">16.1 Capturing xs:date elements as dates</a></li>
</ul>
</li>
<li><a class="reference internal" href="#limitations-of-generateds" id="id95">17 Limitations of generateDS</a><ul class="auto-toc">
<li><a class="reference internal" href="#xml-schema-limitations" id="id96">17.1 XML Schema limitations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#includes-the-xml-schema-xs-include-and-xs-import-elements" id="id97">18 Includes -- The XML schema xs:include and xs:import elements</a></li>
<li><a class="reference internal" href="#processing-relaxng-schemas" id="id98">19 Processing RelaxNG schemas</a></li>
<li><a class="reference internal" href="#acknowledgments" id="id99">20 Acknowledgments</a></li>
<li><a class="reference internal" href="#see-also" id="id100">21 See also</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id7">1 Introduction</a></h1>
<p><tt class="docutils literal">generateDS.py</tt> generates Python data structures (for example,
class definitions) from an XML Schema document. These data
structures represent the elements in an XML document described by
the XML Schema. It also generates parsers that load an XML
document into those data structures. In addition, a separate file
containing subclasses (stubs) is optionally generated. The user
can add methods to the subclasses in order to process the contents
of an XML document.</p>
<p>The generated Python code contains:</p>
<ul class="simple">
<li>A class definition for each element defined in the XML Schema
document.</li>
<li>A main and driver function that can be used to test the
generated code.</li>
<li>A parser that will read an XML document which satisfies the XML
Schema from which the parser was generated. The parser creates
and populates a tree structure of instances of the generated
Python classes.</li>
<li>Methods in each class to export the instance back out to XML
(method <tt class="docutils literal">export</tt>) and to export the instance to a literal
representing the Python data structure (method
<tt class="docutils literal">exportLiteral</tt>).</li>
</ul>
<p>The generated classes contain the following:</p>
<ul class="simple">
<li>A constructor method (__init__), with member variable
initializers.</li>
<li>Methods with names 'getX' and 'setX' for each member variable
'X' or, if the member variable is defined with
maxOccurs="unbounded", methods with names 'getX', 'setX',
'addX', and 'insertX'.</li>
<li>A "build" method that can be used to populate an instance of the
class from a node in a minidom tree.</li>
<li>An "export" method that will write the instance (and any nested
sub-instances) to a file object as XML text.</li>
<li>An "exportLiteral" method that will write the instance (and any
nested sub-instances) to a file object as Python literals (text).</li>
</ul>
<p>The generated subclass file contains one (sub-)class definition
for each data representation class. If the subclass file is used,
then the parser creates instances of the subclasses (instead of
creating instances of the superclasses). This enables the user to
extend the subclasses with "tree walk" methods, for example, that
process the contents of the XML file. The user can also generate
and extend multiple subclass files which use a single, common
superclass file, thus implementing a number of different processes
on the same XML document type.</p>
<p><tt class="docutils literal">generateDS.py</tt> can be run under either Python 2 or Python 3. The
generated Python code (both superclass and subclass modules) can be
run under either Python 2 or Python 3.</p>
<p>This document explains (1) how to use <tt class="docutils literal">generateDS.py</tt>; (2) how
to use the Python code and data structures that it generates; and
(3) how to modify the generated code for special purposes.</p>
<p>There is also support for packaging the code you generate with
<tt class="docutils literal">generateDS.py</tt>. See <a class="reference internal" href="#packaging-your-code">Packaging your code</a>.</p>
</div>
<div class="section" id="where-to-find-it">
<h1><a class="toc-backref" href="#id8">2 Where To find it</a></h1>
<div class="section" id="download">
<h2><a class="toc-backref" href="#id9">2.1 Download</a></h2>
<p>You can find the source distribution here:</p>
<ul class="simple">
<li><a class="reference external" href="http://pypi.python.org/pypi/generateDS/">Python Package Index --
http://pypi.python.org/pypi/generateDS/</a></li>
<li><a class="reference external" href="http://sourceforge.net/projects/generateds/">Source Forge --
http://sourceforge.net/projects/generateds/</a></li>
<li><a class="reference external" href="https://bitbucket.org/dkuhlman/generateds">Bitbucket --
https://bitbucket.org/dkuhlman/generateds</a></li>
</ul>
</div>
<div class="section" id="support-and-more-information">
<h2><a class="toc-backref" href="#id10">2.2 Support and more information</a></h2>
<p>There is a mailing list at SourceForge:
<a class="reference external" href="https://lists.sourceforge.net/lists/listinfo/generateds-users">generateds-users --
https://lists.sourceforge.net/lists/listinfo/generateds-users</a>.</p>
<p>There is a tutorial in the distribution:
<tt class="docutils literal">tutorial/tutorial.html</tt> and at
<a class="reference external" href="http://www.davekuhlman.org/generateds_tutorial.html">generateDS -- Introduction and Tutorial --
http://www.davekuhlman.org/generateds_tutorial.html</a>.</p>
</div>
</div>
<div class="section" id="how-to-build-and-install-it">
<h1><a class="toc-backref" href="#id11">3 How to build and install it</a></h1>
<div class="section" id="requirements">
<h2><a class="toc-backref" href="#id12">3.1 Requirements</a></h2>
<p><tt class="docutils literal">Lxml</tt> is used both by <tt class="docutils literal">generateDS.py</tt> and by the code it
generates. <tt class="docutils literal">Lxml</tt> is available at the Python Package Index
<a class="reference external" href="https://pypi.python.org/pypi/lxml/">https://pypi.python.org/pypi/lxml/</a> and at the <tt class="docutils literal">Lxml</tt> project home
site <a class="reference external" href="http://lxml.de/">http://lxml.de/</a>.</p>
<p>Older versions of Python XML support can sometimes cause problems.
If you receive a traceback that includes "_xmlplus", then you will
need to remove that <tt class="docutils literal">_xmlplus</tt> package.</p>
</div>
<div class="section" id="installation">
<h2><a class="toc-backref" href="#id13">3.2 Installation</a></h2>
<p>De-compress the <tt class="docutils literal">generateDS</tt> distribution file. Use something
like the following:</p>
<pre class="literal-block">
tar xzvf generateDS-x.xx.tar.gz
</pre>
<p>Then, the regular Distutils commands should work:</p>
<pre class="literal-block">
$ cd generateDS-x.xx
$ python setup.py build
$ python setup.py install # probably as root
</pre>
</div>
</div>
<div class="section" id="packaging-your-code">
<h1><a class="toc-backref" href="#id14">4 Packaging your code</a></h1>
<p>There is some support for packaging the code you generate with
<tt class="docutils literal">generateDS.py</tt>. This support helps you to produce a directory
structure with places to put sample code, sample XML instance
documents, and utility code for use with your generated module. It
also assists you in using <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> to
generate documentation for your module. The Sphinx support is
especially useful when the schema used to generate code contains
"annotation" elements that document complexType definitions.</p>
<p>Instructions on how to use it are here:
<a class="reference external" href="librarytemplate_howto.html">How to package a generateDS.py generated library --
librarytemplate_howto.html</a></p>
<p>And the package building support itself is here:
<a class="reference external" href="http://www.davekuhlman.org/librarytemplate-1.0a.zip">LibraryTemplate --
http://www.davekuhlman.org/librarytemplate-1.0a.zip</a>.
It is also included in the generateDS distribution package.</p>
</div>
<div class="section" id="the-command-line-interface-how-to-use-it">
<h1><a class="toc-backref" href="#id15">5 The command line interface -- How to use it</a></h1>
<div class="section" id="running-generateds-py">
<h2><a class="toc-backref" href="#id16">5.1 Running <tt class="docutils literal">generateDS.py</tt></a></h2>
<p>Run <tt class="docutils literal">generateDS.py</tt> with a single argument, the XML Schema file
that defines the data structures. For example, the following will
generate Python source code for data structures described in
people.xsd and will write it to the file people.py. In addition,
it will write subclass stubs to the file peoplesubs.py:</p>
<pre class="literal-block">
python generateDS.py -o people.py -s peoplesubs.py people.xsd
</pre>
<p>Here is the usage message displayed by <tt class="docutils literal">generateDS.py</tt>:</p>
<pre class="literal-block">
Synopsis:
Generate Python classes from XML schema definition.
Input is read from in_xsd_file or, if "-" (dash) arg, from stdin.
Output is written to files named in "-o" and "-s" options.
Usage:
python generateDS.py [ options ] <xsd_file>
python generateDS.py [ options ] -
Options:
-h, --help Display this help information.
-o <outfilename> Output file name for data representation classes
-s <subclassfilename> Output file name for subclasses
-p <prefix> Prefix string to be pre-pended to the class names
-f Force creation of output files. Do not ask.
-a <namespaceabbrev> Namespace abbreviation, e.g. "xsd:".
Default = 'xs:'.
-b <behaviorfilename> Input file name for behaviors added to subclasses
-m Generate properties for member variables
-c <xmlcatalogfilename> Input file name to load an XML catalog
--one-file-per-xsd Create a python module for each XSD processed.
--output-directory="XXX" Used in conjunction with --one-file-per-xsd.
The directory where the modules will be created.
--module-suffix="XXX" To be used in conjunction with --one-file-per-xsd.
Append XXX to the end of each file created.
--subclass-suffix="XXX" Append XXX to the generated subclass names.
Default="Sub".
--root-element="XX" When parsing, assume XX is root element of
--root-element="XX|YY" instance docs. Default is first element defined
in schema. If YY is added, then YY is used as the
top level class; if YY omitted XX is the default.
class. Also see section "Recognizing the top level
element" in the documentation.
--super="XXX" Super module name in generated subclass
module. Default="???"
--validator-bodies=path Path to a directory containing files that provide
bodies (implementations) of validator methods.
--use-old-simpletype-validators
Use the old style simpleType validator functions
stored in a specified directory, instead of the
new style validators generated directly from the
XML schema. See option --validator-bodies.
--use-getter-setter Generate getter and setter methods. Values:
"old" - Name getters/setters getVar()/setVar().
"new" - Name getters/setters get_var()/set_var().
"none" - Do not generate getter/setter methods.
Default is "new".
--use-source-file-as-module-name
Used in conjunction with --one-file-per-xsd to
use the source XSD file names to determine the
module name of the generated classes.
--user-methods= <module>,
-u <module> Optional module containing user methods. See
section "User Methods" in the documentation.
--no-dates Do not include the current date in the generated
files. This is useful if you want to minimize
the amount of (no-operation) changes to the
generated python code.
--no-versions Do not include the current version in the
generated files. This is useful if you want
to minimize the amount of (no-operation)
changes to the generated python code.
--no-process-includes Do not use process_includes.py to pre-process
included XML schema files. By default,
generateDS.py will insert content from files
referenced by xs:include and xs:import elements
into the XML schema to be processed and perform
several other pre-procesing tasks. You likely do
not want to use this option; its use has been
reported to result in errors in generated modules.
Consider using --no-collect-includes and/or
--no-redefine-groups instead.
--no-collect-includes Do not (recursively) collect and insert schemas
referenced by xs:include and xs:import elements.
--no-redefine-groups Do not pre-process and redefine group definitions.
--silence Normally, the code generated with generateDS
echoes the information being parsed. To prevent
the echo from occurring, use the --silence switch.
Also note optional "silence" parameter on
generated functions, e.g. parse, parseString, etc.
--namespacedef='xmlns:abc="http://www.abc.com"'
Namespace definition to be passed in as the
value for the namespacedef_ parameter of
the export() method by the generated
parse() and parseString() functions.
Default=''.
--no-namespace-defs Do not pass namespace definitions as the value
for the namespacedef_ parameter of the export
method, even if it can be extraced from the
schema.
--external-encoding=<encoding>
Encode output written by the generated export
methods using this encoding. Default, if omitted,
is the value returned by sys.getdefaultencoding().
Example: --external-encoding='utf-8'.
--member-specs=list|dict
Generate member (type) specifications in each
class: a dictionary of instances of class
MemberSpec_ containing member name, type,
and array or not. Allowed values are
"list" or "dict". Default: do not generate.
--export=<export-list> Specifies export functions to be generated.
Value is a whitespace separated list of
any of the following:
write -- write XML to file
literal -- write out python code
etree -- build element tree (can serialize
to XML)
Example: "write etree"
Default: "write"
--disable-generatedssuper-lookup
Disables the generatetion of the lookup logic for
presence of an external module from which to load
a custom `GeneratedsSuper` base-class definition.
--disable-xml Disables generation of all XML build/export
methods and command line interface
--preserve-cdata-tags Preserve CDATA tags. Default: False
--cleanup-name-list=<replacement-map>
Specifies list of 2-tuples used for cleaning
names. First element is a regular expression
search pattern and second is a replacement.
Example: "[('[-:.]', '_'), ('^__', 'Special')]"
Default: "[('[-:.]', '_')]"
-q, --no-questions Do not ask questions, for example,
force overwrite.
--no-warnings Do not print warning messages.
--session=mysession.session
Load and use options from session file. You can
create session file in generateds_gui.py. Or,
copy and edit sample.session from the
distribution.
--fix-type-names="oldname1:newname1;oldname2:newname2;..."
Fix up (replace) complex type names.
--version Print version and exit.
Usage example:
$ python generateDS.py -f -o sample_lib.py sample_api.xsd
creates (with force over-write) sample_lib.py from sample_api.xsd.
$ python generateDS.py -o sample_lib.py -s sample_app1.py \
--member-specs=dict sample_api.xsd
creates sample_lib.py superclass and sample_app1.py subclass modules;
also generates member specifications in each class (in a dictionary).
</pre>
</div>
<div class="section" id="command-line-options">
<h2><a class="toc-backref" href="#id17">5.2 Command line options</a></h2>
<p>The following command line options are recognized by <tt class="docutils literal">generateDS.py</tt>:</p>
<dl class="docutils">
<dt>o <filename></dt>
<dd>Write the data representation classes to file filename.</dd>
<dt>s <filename></dt>
<dd>Write the subclass stubs to file filename.</dd>
<dt>p <prefix></dt>
<dd>Prepend prefix to the name of each generated data structure
(class).</dd>
<dt>f</dt>
<dd>Force generation of output files even if they already exist.
Do not ask before over-writing existing files.</dd>
<dt>a <namespaceabbrev></dt>
<dd><p class="first">Namespace abbreviation, for example "xsd:". The default is
'xs:'. If the <tt class="docutils literal"><schema> element</tt> in your XML Schema,
specifies something other than "xmlns:xs=", then you need to
use this option. So, suppose you have the following at the
beginning of your XSchema file:</p>
<pre class="literal-block">
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
</pre>
<p>Then you can the following command line option:</p>
<pre class="literal-block">
-a "xsd:"
</pre>
<p class="last">But, note that <tt class="docutils literal">generateDS.py</tt> also tries to pick-up the
namespace prefix used in the XMLSchema file automatically. If
the <schema> element has an attribute "xmlns:xxx" whose value
is "http://www.w3.org/2001/XMLSchema", then <tt class="docutils literal">generateDS.py</tt>
will use "xxx:" as the alias for the XMLSchema namespace in
the XMLSchema document.</p>
</dd>
<dt>b <behaviorfilename></dt>
<dd>Input file name for behaviors to be added to subclasses.
Specifies is the name of an XML document containing
descriptions of methods to be added to subclasses generated
with the -s flag. The -b flag requires the -s flag. See the
section on <a class="reference internal" href="#xmlbehaviors">XMLBehaviors</a> below.</dd>
<dt>m</dt>
<dd>Generate property members and new style classes. Causes
generated classes to inherit from class object. Generates
a call to the built-in property function for each pair of
getters and setters. This is experimental.</dd>
<dt>c <xmlcatalogfilename></dt>
<dd>Specify the file to be used as an XML catalog. This file will
be used by process_includes.py if needed to resolve references
in <xs:import> and <xs:include> elements in the XML Schema. For
more information on XML catalogs, see:
http://en.wikipedia.org/wiki/XML_Catalog</dd>
<dt>one-file-per-xsd</dt>
<dd>Create a separate Python module for each XML Schema document
processed (for example, using <xs:include> or <xs:import>). For
help with using this option, see <a class="reference internal" href="#one-per-generating-separate-files-from-imported-included-schemas">"One Per" -- generating
separate files from imported/included schemas</a>.</dd>
<dt>output-directory <directory></dt>
<dd>When used with <tt class="docutils literal"><span class="pre">one-file-per-xsd</span></tt>, create generated output
files in path <tt class="docutils literal"><directory></tt>.</dd>
<dt>module-suffix <suffix></dt>
<dd>When used with <tt class="docutils literal"><span class="pre">one-file-per-xsd</span></tt>, append <tt class="docutils literal"><suffix></tt> to the
end of each module name.</dd>
<dt>subclass-suffix=<suffix></dt>
<dd><p class="first">Append suffix to the name of classes generated in the subclass
file. The default, if omitted, is "Sub". For example, the
following will append "_Action" to each generated subclass
name:</p>
<pre class="literal-block">
generateDS.py --subclass-suffix="_Action" -s actions.py mydef.xsd
</pre>
<p>And the following will append nothing, making the superclass
and subclass names the same:</p>
<pre class="last literal-block">
generateDS.py --subclass-suffix="" -s actions.py mydef.xsd
</pre>
</dd>
<dt>root-element=<element_name> -OR- <element_name>|<class_name></dt>
<dd>Make <tt class="docutils literal">element_name</tt> the assumed root of instance documents.
The default is the name of the element whose definition is first
in the XML Schema document. If <tt class="docutils literal">class_name</tt> is also present
(after a vertical bar), then <tt class="docutils literal">class_name</tt> is assumed to be the
name of the class to be created from the root (top level)
element when parsing an XML instance document. If
<tt class="docutils literal">class_name</tt> is omitted, the default class name is the same as
<tt class="docutils literal">element_name</tt>. This flag effects the parsing functions (for
example, parse(), parseString(), etc).</dd>
<dt>super=<module_name></dt>
<dd><p class="first">Make module_name the name of the superclass module imported
by the subclass module. If this flag is omitted, the
following is generated near the top of the subclass file:</p>
<pre class="literal-block">
import ??? as supermod
</pre>
<p class="last">and you will need to hand edit this so the correct superclass
module is imported.</p>
</dd>
<dt>validator-bodies=<path></dt>
<dd>Obtain the bodies (implementations) for validator methods for
members defined as <tt class="docutils literal">simpleType</tt> from files in directory
specified by <tt class="docutils literal"><path></tt>. The name of the file in that
directory should be the same as the <tt class="docutils literal">simpleType</tt> name with
an optional ".py" extension. If a file is not provided for a
given type, an empty body (<tt class="docutils literal">pass</tt>) is generated. In these
files, lines with "##" in the first two columns are ignored
and are not inserted.</dd>
<dt>use-old-simpletype-validators</dt>
<dd><p class="first"><tt class="docutils literal">generateDS.py</tt> is capable of generating validator bodies --
the code that validates data content in an XML instance
docuement and writes out warning messages if that data does not
satisfy the facets in the <tt class="docutils literal">xs:restriction</tt> in the
<tt class="docutils literal">xs:simpleType</tt> defintion in the XML schema. Use this option
if you want to use your own validation bodies/code defined in a
specified directory . See option <tt class="docutils literal"><span class="pre">--validator-bodies</span></tt> for
information on that. <em>Without</em> this option
(<tt class="docutils literal"><span class="pre">--use-old-simpletype-validators</span></tt>), the validator code will
be generated directly from the XML schema, which is the default.</p>
<p class="last">This option can also be used to generate code that does <em>no</em>
validation. See <a class="reference internal" href="#simpletype-and-validators">simpleType and validators</a> and <a class="reference internal" href="#turning-off-validation-of-simpletype-data">Turning off
validation of simpleType data</a> for more information.</p>
</dd>
<dt>use-getter-setter</dt>
<dd><p class="first"><tt class="docutils literal">generateDS.py</tt> now generates getter and setter methods (for
variable "abc", for example) with the names get_abc() and
set_abc(), which I believe is a more Pythonic style, instead of
getAbc() and setAbc(), which was the old behavior. Use this
flag to generate getters and setters in the old style (getAbc()
and setAbc()) or the newer style(get_abc() and set_abc()) which
is the default or to omit generation of getter and setter
methods. Possible values are:</p>
<ul class="simple">
<li>"old" - Name getters/setters getVar()/setVar().</li>
<li>"new" - Name getters/setters get_var()/set_var().</li>
<li>"none" - Do not generate getter/setter methods.</li>
</ul>
<p class="last">The default is "new".</p>
</dd>
<dt>use-source-file-as-module-name</dt>
<dd>Used in conjunction with and only has an effect when used with
<tt class="docutils literal"><span class="pre">--one-file-per-xsd</span></tt>. The effect of this option is to use the
source XML schema file names to determine the module name of the
generated classes. Without this option, the first root element
is used to construct module names. The default is False.</dd>
<dt>u, user-methods=<module></dt>
<dd>If specified, <tt class="docutils literal">generateDS.py</tt> will add methods to generated
classes as specified in the indicated module. For more
information, see section <a class="reference internal" href="#user-methods">User Methods</a>.</dd>
<dt>no-dates</dt>
<dd>Do not include the current date in the generated files. This is
useful if you want to minimize the amount of (no-operation)
changes to the generated python code.</dd>
<dt>no-versions</dt>
<dd>Do not include the current version in the generated files. This is
useful if you want to minimize the amount of (no-operation)
changes to the generated python code.</dd>
<dt>no-process-includes</dt>
<dd>Do not use <tt class="docutils literal">process_includes.py</tt> to pre-process included XML
Schema files. By default, generateDS.py will insert content
from files referenced by <tt class="docutils literal">xs:include</tt> and <tt class="docutils literal">xs:import</tt>
elements into the XML Schema to be processed. See section
<a class="reference internal" href="#include-file-processing">Include file processing</a>. Note that include processing, which
is performed in <tt class="docutils literal">process_includes.py</tt> is required for
generating validator bodies from the XML schema, because the
Lxml ElementTree produced in <tt class="docutils literal">process_includes.py</tt> is needed
to generate the validator code. So, using this option also
turns off automatic generation of validator code. Also note
that process_includes(.py) performs additional tasks; it also
(1) assigns names to each anonymous complexType, (2) processes
(replaces) group definitions, and (3) possibly fixes complexType
names (see command line option --fix-type-names). You likely do
not want to use this option; its use has been reported to result
in errors in generated modules. Consider using
--no-collect-includes and/or --no-redefine-groups instead.</dd>
<dt>no-collect-includes</dt>
<dd>Do not (recursively) collect and insert schemas referenced by
<tt class="docutils literal">xs:include</tt> and <tt class="docutils literal">xs:import</tt> elements. This task is
performed in <tt class="docutils literal">process_includes.py</tt>.</dd>
<dt>no-redefine-groups</dt>
<dd>Do not pre-process and redefine group definitions. This task is
performed in <tt class="docutils literal">process_includes.py</tt>.</dd>
<dt>silence</dt>
<dd>Normally, the code generated with generateDS echoes the
information being parsed. To prevent the echo from occurring,
use the --silence switch. This switch causes generateDS.py,
when it generates boiler-plate parsing functions, (parse(),
parseString(), parseLiteral()), to generate code that does
<em>not</em> print out output (export output to stdout).</dd>
<dt>namespacedef="<<a class="reference external" href="http://...">http://...</a>>"</dt>
<dd>Namespace definition to be passed in as the value for the
<tt class="docutils literal">namespacedef_</tt> parameter of the export() method by the generated
parse() and parseString() functions. If this parameter is
specified, then the export function will insert a namespace
prefix definition attribute in the top-most (outer-most)
element. (Actually, you can insert any attribute.) The default
is an empty string.</dd>
<dt>no-namespace-defs</dt>
<dd>Do not pass namespace definitions as the value for the
<tt class="docutils literal">namespacedef_</tt> parameter of the export method, even if it can
be extraced from the schema. The default is off. You might
want to consider using this in combination with the ability to
attach namespace prefix definitions to specific element types
during export, as described here: <a class="reference internal" href="#adding-custom-exported-attributes-and-namespace-prefix-definitions">Adding custom exported
attributes and namespace prefix definitions</a>.</dd>
<dt>external-encoding=<encoding></dt>
<dd>If an XML instance document contains character data or
attribute values that are not in the ASCII character set, then
that data will not be written out correctly or will throw an
exception. This flag enables the user to specify a character
encoding into which character data will be encoded before it is
written out by the export functions. The generated export
methods encode data using this encoding. The default value, if
this flag is omitted, is the value returned by
sys.getdefaultencoding(). You can find a list of standard
encodings here: <a class="reference external" href="http://docs.python.org/library/codecs.html#id3">http://docs.python.org/library/codecs.html#id3</a>.
Example use: --external-encoding='utf-8'.</dd>
<dt>member-specs Generate member (type) specifications in each class</dt>
<dd>A dictionary of instances of class <tt class="docutils literal">MemberSpec_</tt> containing
member name, type, array or not, and whether the item is
optional (i.e. defined with minOccurs="0"). See <a class="reference internal" href="#user-methods">User Methods</a>
section for more information about <tt class="docutils literal">MemberSpec_</tt>. Allowed
values are "list" or "dict". Default: do <em>not</em> generate member
specifications (unless --user-methods specified).</dd>
<dt>export</dt>
<dd><p class="first">Specify which of the export related member methods are to be
generated. The value is a whitespace separated list of any of
the following:</p>
<ul class="simple">
<li>write -- Generate methods <tt class="docutils literal">export</tt>, <tt class="docutils literal">exportAttributes</tt>,
and <tt class="docutils literal">exportChildren</tt>. These methods write XML to a file.</li>
<li>literal -- Generate methods <tt class="docutils literal">exportLiteral</tt>,
<tt class="docutils literal">exportLiteralAttributes</tt> and <tt class="docutils literal">exportLiteralChildren</tt>.
These methods write out python code.</li>
<li>etree -- Generate method <tt class="docutils literal">to_etree</tt>. This method builds an
lxml element tree, which can, for example, be serialized to
XML using lxml's <tt class="docutils literal">tostring</tt> function and searched with the
lxml xpath capability. You can also iterate over nodes in the
tree with the node's <tt class="docutils literal">getiterator</tt>, <tt class="docutils literal">iterchildren</tt>, etc,
and use any of lxml's other capabilities.</li>
</ul>
<p class="last">For example: <tt class="docutils literal"><span class="pre">--export="write</span> etree"</tt> and <tt class="docutils literal"><span class="pre">--export="write"</span></tt>. The
default is: <tt class="docutils literal"><span class="pre">--export="write"</span></tt>.</p>
</dd>
<dt>disable-generatedssuper-lookup</dt>
<dd>Disables the generation of code implementing the lookup for
presence of an external module from which to load a custom
replacement for the default <tt class="docutils literal">GeneratedsSuper</tt> base-class.
With this flag, unconditionally uses the built-in implementation
of <tt class="docutils literal">GeneratedsSuper</tt>. (Suggestion: In order to get a picture
of what difference this option makes, you might consider
generating modules both with and without it, and then comparing
the results with <tt class="docutils literal">diff</tt>.) The default is False.</dd>
<dt>disable-xml</dt>
<dd>Disables generation of code that enables XML build/export
methods and command line interface. Actually, the code is
there, but is commented out. If you enable this option, the
generated modules will <em>not</em> contain code for the following: (1)
run as a script without explicitly running <tt class="docutils literal">python</tt> (the
<tt class="docutils literal"><span class="pre">#!/usr/bin/env</span> python</tt> line is omitted); (2) import
<tt class="docutils literal">lxml.etree</tt>; (3) parse an XML file; (4) export an XML file.
(Suggestion: In order to get a picture of what difference this
option makes, you might consider generating modules both with
and without it, and then comparing the results with <tt class="docutils literal">diff</tt>.)
The default is False.</dd>
<dt>preserve-cdata-tags</dt>
<dd>Preserve CDATA tags. Normally, CDATA tags ("<![CDATA[ ... ]]>")
are dropped while parsing an XML instance document. If this
option is included, the generated code will preserve those tags
and will write them out during export. The default is False.</dd>
<dt>cleanup-name-list=<replacement-map></dt>
<dd><p class="first">Specifies replacement pairs to be used when cleaning up names.
Must be a string representation of a Python list of 2-tuples.
The values of each pair (2-tuple) must be strings. The first
item of each pair is a pattern and must be a valid Python
regular expression (see
<a class="reference external" href="https://docs.python.org/2/library/re.html#module-re">https://docs.python.org/2/library/re.html#module-re</a>) The second
item of each pair is a string that will replace anything matched
by the pattern. Also see <a class="reference internal" href="#cleaning-up-names-with-special-characters-etc">Cleaning up names with special characters etc.</a></p>
<p>The intension is to enable us to replace
special characters in names that would cause the generation of
invalid Python names, for example the names of generated
classes. However, since a string replacement is
performed, you can replace any single character or sequence of
characters by any other single character or sequence of
characters. Example:
<tt class="docutils literal"><span class="pre">[(':',</span> <span class="pre">'colon'),</span> <span class="pre">('-',</span> <span class="pre">'dash'),</span> <span class="pre">('.',</span> <span class="pre">'dot')]</span></tt>.</p>
<p class="last">The default when omitted is <tt class="docutils literal"><span class="pre">[('[-:.]',</span> <span class="pre">'_')]</span></tt>.</p>
</dd>
<dt>q, no-questions</dt>
<dd>Do not ask questions. For example, if the "-f" command line
option is omitted and the ouput file exists, then generateDS.py
will not ask whether the file should be overwritten. (In this
case, when "-q" is used, the "-f" must be used to force the
output file to be written.</dd>
<dt>no-warnings</dt>
<dd>While running generateDS.py, do not print warning messages that
would be written to stderr.</dd>
<dt>session=mysession.session</dt>
<dd>Load and use options from session file. You can create a
session file in generateds_gui.py, the graphical front-end for
generateDS.py. Additional options on the command line can be
used to override options in the session file. A session file
is an XML document, so you can modify it with a text editor.</dd>
<dt>fix-type-names="oldname1:newname1;oldname2:newname2;..."</dt>
<dd><p class="first">Fix up (replace) complex type names. Using this option will
replace the following: (1) the 'name' attribute of a
complexType; (2) the 'type' attribute of each element that
refers to the type; and (3) the 'base' attribute of each
extension that refers to the type. These fixups happen before
information is collected from the schema for code generation.
Therefore, using this option is effectively equivalent to
copying your schema, then editing it with your text editor, then
generating code from the modified schema. If a new name is not
specified, the default is to replace the old name with the old
name plus an added "xx" suffix. Examples:</p>
<pre class="last literal-block">
$ generateDS.py --fix-type-names="type1:type1Aux"
$ generateDS.py --fix-type-names="type1;type2:type2Repl"
</pre>