aboutsummaryrefslogtreecommitdiffstats
path: root/pyyaml/PyYAMLDocumentation.html
blob: eaf72e34b90ca5aa01a295c57094e24695b24549 (plain) (blame) 
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>
      PyYAMLDocumentation – PyYAML
    </title>
        <link rel="search" href="http://pyyaml.org/search">
        <link rel="help" href="http://pyyaml.org/wiki/TracGuide">
        <link rel="alternate" href="http://pyyaml.org/wiki/PyYAMLDocumentation?format=txt" type="text/x-trac-wiki" title="Plain Text">
        <link rel="start" href="http://pyyaml.org/wiki">
        <link rel="stylesheet" href="PyYAMLDocumentation_files/trac.css" type="text/css"><link rel="stylesheet" href="PyYAMLDocumentation_files/wiki.css" type="text/css">
        <link rel="shortcut icon" href="http://pyyaml.org/favicon.ico" type="image/x-icon">
        <link rel="icon" href="http://pyyaml.org/favicon.ico" type="image/x-icon">
      <link type="application/opensearchdescription+xml" rel="search" href="http://pyyaml.org/search/opensearch" title="Search PyYAML">
    <script type="text/javascript" src="PyYAMLDocumentation_files/jquery.js"></script><script type="text/javascript" src="PyYAMLDocumentation_files/trac.js"></script><script type="text/javascript" src="PyYAMLDocumentation_files/search.js"></script>
    <!--[if lt IE 7]>
    <script type="text/javascript" src="/chrome/common/js/ie_pre7_hacks.js"></script>
    <![endif]-->
    <script type="text/javascript">
      jQuery(document).ready(function($) {
        $("#content").find("h1,h2,h3,h4,h5,h6").addAnchor("Link to this section");
      });
    </script>
  </head>
  <body>
    <div id="banner">
      <div id="header">
        <a id="logo" href="http://pyyaml.org/"><img src="PyYAMLDocumentation_files/pyyaml.png" alt="PyYAML" height="73" width="236"></a>
      </div>
      <form id="search" action="/search" method="get">
        <div>
          <label for="proj-search">Search:</label>
          <input id="proj-search" name="q" size="18" type="text">
          <input value="Search" type="submit">
        </div>
      </form>
      <div id="metanav" class="nav">
    <ul>
      <li class="first"><a href="http://pyyaml.org/login">Login</a></li><li><a href="http://pyyaml.org/wiki/TracGuide">Help/Guide</a></li><li><a href="http://pyyaml.org/about">About Trac</a></li><li class="last"><a href="http://pyyaml.org/prefs">Preferences</a></li>
    </ul>
  </div>
    </div>
    <div id="mainnav" class="nav">
    <ul>
      <li class="first active"><a href="http://pyyaml.org/wiki">Wiki</a></li><li><a href="http://pyyaml.org/timeline">Timeline</a></li><li><a href="http://pyyaml.org/roadmap">Roadmap</a></li><li><a href="http://pyyaml.org/browser">Browse Source</a></li><li><a href="http://pyyaml.org/report">View Tickets</a></li><li><a href="http://pyyaml.org/newticket">New Ticket</a></li><li class="last"><a href="http://pyyaml.org/search">Search</a></li>
    </ul>
  </div>
    <div id="main">
      <div id="ctxtnav" class="nav">
        <h2>Context Navigation</h2>
          <ul>
              <li class="first"><a href="http://pyyaml.org/wiki/WikiStart">Start Page</a></li><li><a href="http://pyyaml.org/wiki/TitleIndex">Index</a></li><li><a href="http://pyyaml.org/wiki/PyYAMLDocumentation?action=history">History</a></li><li class="last"><a href="http://pyyaml.org/wiki/PyYAMLDocumentation?action=diff&amp;version=48">Last Change</a></li>
          </ul>
        <hr>
      </div>
    <div id="content" class="wiki">
      <div class="wikipage searchable">
        
          <h1 id="PyYAMLDocumentation">PyYAML Documentation</h1>
<p>
<i>RPG-ish descriptions are stolen from <a class="ext-link" href="http://www.thangorodrim.net/"><span class="icon">&nbsp;</span>the Angband rogue-like game</a>.
Names of the heroes are generated with <a class="ext-link" href="http://www.ibiblio.org/pub/Linux/games/muds/mudnames-1.5.lsm"><span class="icon">&nbsp;</span>MudNames</a>.</i>
</p>
<p>
<i>This documentation is very brief and incomplete. Feel free to fix or improve it.</i>
</p>
<p>
</p><div class="wiki-toc"><ol><li><a href="#PyYAMLDocumentation">PyYAML Documentation</a><ol><li><a href="#Installation">Installation</a></li><li>
<a href="#FrequentlyAskedQuestions">Frequently Asked Questions</a><ol><li><a href="#Dictionarieswithoutnestedcollectionsarenotdumpedcorrectly">Dictionaries without nested collections are not dumped correctly</a></li></ol></li><li>
<a href="#Python3support">Python 3 support</a></li><li>
<a href="#Tutorial">Tutorial</a><ol><li><a href="#LoadingYAML">Loading YAML</a></li><li>
<a href="#DumpingYAML">Dumping YAML</a></li><li>
<a href="#Constructorsrepresentersresolvers">Constructors, representers, resolvers</a></li></ol></li><li>
<a href="#YAMLsyntax">YAML syntax</a><ol><li><a href="#Documents">Documents</a></li><li>
<a href="#Blocksequences">Block sequences</a></li><li>
<a href="#Blockmappings">Block mappings</a></li><li>
<a href="#Flowcollections">Flow collections</a></li><li>
<a href="#Scalars">Scalars</a></li><li>
<a href="#Aliases">Aliases</a></li><li>
<a href="#Tags">Tags</a></li></ol></li><li>
<a href="#YAMLtagsandPythontypes">YAML tags and Python types</a><ol><li><a href="#StringconversionPython2only">String conversion (Python 2 only)</a></li><li>
<a href="#StringconversionPython3only">String conversion (Python 3 only)</a></li><li>
<a href="#Namesandmodules">Names and modules</a></li><li>
<a href="#Objects">Objects</a></li></ol></li><li>
<a href="#Reference">Reference</a><ol><li><a href="#Theyamlpackage">The yaml package</a></li><li>
<a href="#Mark">Mark</a></li><li>
<a href="#YAMLError">YAMLError</a></li><li>
<a href="#Tokens">Tokens</a></li><li>
<a href="#Events">Events</a></li><li>
<a href="#Nodes">Nodes</a></li><li>
<a href="#Loader">Loader</a></li><li>
<a href="#Dumper">Dumper</a></li><li>
<a href="#YAMLObject">YAMLObject</a></li></ol></li><li>
<a href="#Deviationsfromthespecification">Deviations from the specification</a></li></ol></li></ol></div><p>
</p>
<h2 id="Installation">Installation</h2>
<p>
Download the source package <strong>PyYAML-3.08.tar.gz</strong> and unpack it. Go to the directory <strong>PyYAML-3.08</strong>
and run
</p>
<pre class="wiki">$ python setup.py install
</pre><p>
If you want to use LibYAML bindings, which are much faster than the pure Python version, you need to
download and install <a class="wiki" href="http://pyyaml.org/wiki/LibYAML">LibYAML</a>.  Then you may build and install the bindings by executing
</p>
<pre class="wiki">$ python setup.py --with-libyaml install
</pre><p>
In order to use <a class="wiki" href="http://pyyaml.org/wiki/LibYAML">LibYAML</a> based parser and emitter, use the classes <strong><tt>CParser</tt></strong> and <strong><tt>CEmitter</tt></strong>.
For instance,
</p>
<div class="code"><pre><span class="kn">from</span> <span class="nn">yaml</span> <span class="kn">import</span> load<span class="p">,</span> dump
<span class="k">try</span><span class="p">:</span>
    <span class="kn">from</span> <span class="nn">yaml</span> <span class="kn">import</span> CLoader <span class="k">as</span> Loader<span class="p">,</span> CDumper <span class="k">as</span> Dumper
<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>
    <span class="kn">from</span> <span class="nn">yaml</span> <span class="kn">import</span> Loader<span class="p">,</span> Dumper

<span class="c"># ...</span>

data <span class="o">=</span> load<span class="p">(</span>stream<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>

<span class="c"># ...</span>

output <span class="o">=</span> dump<span class="p">(</span>data<span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">)</span>
</pre></div><p>
Note that there are some subtle (but not really significant) differences between pure Python and <a class="wiki" href="http://pyyaml.org/wiki/LibYAML">LibYAML</a> based parsers
and emitters.
</p>
<h2 id="FrequentlyAskedQuestions">Frequently Asked Questions</h2>
<h3 id="Dictionarieswithoutnestedcollectionsarenotdumpedcorrectly">Dictionaries without nested collections are not dumped correctly</h3>
<p>
<i>Why does</i>
</p>
<div class="code"><pre><span class="kn">import</span> <span class="nn">yaml</span>
document <span class="o">=</span> <span class="s">"""
  a: 1
  b:
    c: 3
    d: 4
"""</span>
<span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span>yaml<span class="o">.</span>load<span class="p">(</span>document<span class="p">))</span>
</pre></div><p>
<i>give</i>
</p>
<pre class="wiki">a: 1
b: {c: 3, d: 4}
</pre><p>
<i>(see <a class="closed ticket" href="http://pyyaml.org/ticket/18" title="defect: [bug] nested dictionnary load works dump doesn't (closed: worksforme)">#18</a>, <a class="closed ticket" href="http://pyyaml.org/ticket/24" title="defect: dictionaries without at least one list element as values seem not to work (closed: worksforme)">#24</a>)?</i>
</p>
<p>
It's a correct output despite the fact that the style of the nested mapping is different.
</p>
<p>
By default, PyYAML chooses the style of a collection depending on whether it has nested
collections. If a collection has nested collections, it will be assigned the block style.
Otherwise it will have the flow style.
</p>
<p>
If you want collections to be always serialized in the block style, set the parameter
<strong><tt>default_flow_style</tt></strong> of <strong><tt>dump()</tt></strong> to <strong><tt>False</tt></strong>. For instance,
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span>yaml<span class="o">.</span>load<span class="p">(</span>document<span class="p">),</span> default_flow_style<span class="o">=</span><span class="bp">False</span><span class="p">)</span>
a<span class="p">:</span> <span class="mi">1</span>
b<span class="p">:</span>
  c<span class="p">:</span> <span class="mi">3</span>
  d<span class="p">:</span> <span class="mi">4</span>
</pre></div><h2 id="Python3support">Python 3 support</h2>
<p>
Starting from the <strong>3.08</strong> release, PyYAML and LibYAML bindings provide a complete support
for Python 3.  This is a short outline of differences in PyYAML API between Python 2
and Python 3 versions.
</p>
<p>
<i>In Python 2:</i>
</p>
<ul><li><strong><tt>str</tt></strong> objects are converted into <strong><tt>!!str</tt></strong>, <strong><tt>!!python/str</tt></strong>
or <strong><tt>!binary</tt></strong> nodes depending on whether the object is an ASCII, UTF-8
or binary string.
</li><li><strong><tt>unicode</tt></strong> objects are converted into <strong><tt>!!python/unicode</tt></strong> or
<strong><tt>!!str</tt></strong> nodes depending on whether the object is an ASCII string or not.
</li><li><tt>yaml.dump(data)</tt> produces the document as a UTF-8 encoded <strong><tt>str</tt></strong> object.
</li><li><tt>yaml.dump(data, encoding=('utf-8'|'utf-16-be'|'utf-16-le'))</tt> produces
a <strong><tt>str</tt></strong> object in the specified encoding.
</li><li><tt>yaml.dump(data, encoding=None)</tt> produces a <strong><tt>unicode</tt></strong> object.
</li></ul><p>
<i>In Python 3:</i>
</p>
<ul><li><strong><tt>str</tt></strong> objects are converted to <strong><tt>!!str</tt></strong> nodes.
</li><li><strong><tt>bytes</tt></strong> objects are converted to <strong><tt>!!binary</tt></strong> nodes.
</li><li>For compatibility reasons, <strong><tt>!!python/str</tt></strong> and <strong><tt>!python/unicode</tt></strong> tags are
still supported and the corresponding nodes are converted to <strong><tt>str</tt></strong> objects.
</li><li><tt>yaml.dump(data)</tt> produces the document as a <strong><tt>str</tt></strong> object.
</li><li><tt>yaml.dump(data, encoding=('utf-8'|'utf-16-be'|'utf-16-le'))</tt> produces
a <strong><tt>bytes</tt></strong> object in the specified encoding.
</li></ul><h2 id="Tutorial">Tutorial</h2>
<p>
Start with importing the <strong><tt>yaml</tt></strong> package.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">yaml</span>
</pre></div><h3 id="LoadingYAML">Loading YAML</h3>
<p>
<strong>Warning: It is not safe to call <tt>yaml.load</tt> with any data received from an untrusted source!
<tt>yaml.load</tt> is as powerful as <tt>pickle.load</tt> and so may call any Python function.</strong>
Check the <strong><tt>yaml.safe_load</tt></strong> function though.
</p>
<p>
The function <strong><tt>yaml.load</tt></strong> converts a YAML document to a Python object.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="s">"""
... - Hesperiidae
... - Papilionidae
... - Apatelodidae
... - Epiplemidae
... """</span><span class="p">)</span>

<span class="p">[</span><span class="s">'Hesperiidae'</span><span class="p">,</span> <span class="s">'Papilionidae'</span><span class="p">,</span> <span class="s">'Apatelodidae'</span><span class="p">,</span> <span class="s">'Epiplemidae'</span><span class="p">]</span>
</pre></div><p>
<strong><tt>yaml.load</tt></strong> accepts a byte string, a Unicode string, an open binary file object,
or an open text file object. A byte string or a file must be encoded with <strong>utf-8</strong>,
<strong>utf-16-be</strong> or <strong>utf-16-le</strong> encoding. <strong><tt>yaml.load</tt></strong> detects the encoding
by checking the <strong>BOM</strong> (byte order mark) sequence at the beginning of the
string/file. If no <strong>BOM</strong> is present, the <strong>utf-8</strong> encoding is assumed.
</p>
<p>
<strong><tt>yaml.load</tt></strong> returns a Python object.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="s">u"""
... hello: Привет!
... """</span><span class="p">)</span>    <span class="c"># In Python 3, do not use the 'u' prefix</span>

<span class="p">{</span><span class="s">'hello'</span><span class="p">:</span> <span class="s">u'</span><span class="se">\u041f\u0440\u0438\u0432\u0435\u0442</span><span class="s">!'</span><span class="p">}</span>

<span class="o">&gt;&gt;&gt;</span> stream <span class="o">=</span> <span class="nb">file</span><span class="p">(</span><span class="s">'document.yaml'</span><span class="p">,</span> <span class="s">'r'</span><span class="p">)</span>    <span class="c"># 'document.yaml' contains a single YAML document.</span>
<span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>load<span class="p">(</span>stream<span class="p">)</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>    <span class="c"># A Python object corresponding to the document.</span>
</pre></div><p>
If a string or a file contains several documents, you may load them all with the
<strong><tt>yaml.load_all</tt></strong> function.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> documents <span class="o">=</span> <span class="s">"""
... ---
... name: The Set of Gauntlets 'Pauraegen'
... description: &gt;
...     A set of handgear with sparks that crackle
...     across its knuckleguards.
... ---
... name: The Set of Gauntlets 'Paurnen'
... description: &gt;
...   A set of gauntlets that gives off a foul,
...   acrid odour yet remains untarnished.
... ---
... name: The Set of Gauntlets 'Paurnimmen'
... description: &gt;
...   A set of handgear, freezing with unnatural cold.
... """</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> data <span class="ow">in</span> yaml<span class="o">.</span>load_all<span class="p">(</span>documents<span class="p">):</span>
<span class="o">...</span>     <span class="k">print</span> data

<span class="p">{</span><span class="s">'description'</span><span class="p">:</span> <span class="s">'A set of handgear with sparks that crackle across its knuckleguards.</span><span class="se">\n</span><span class="s">'</span><span class="p">,</span>
<span class="s">'name'</span><span class="p">:</span> <span class="s">"The Set of Gauntlets 'Pauraegen'"</span><span class="p">}</span>
<span class="p">{</span><span class="s">'description'</span><span class="p">:</span> <span class="s">'A set of gauntlets that gives off a foul, acrid odour yet remains untarnished.</span><span class="se">\n</span><span class="s">'</span><span class="p">,</span>
<span class="s">'name'</span><span class="p">:</span> <span class="s">"The Set of Gauntlets 'Paurnen'"</span><span class="p">}</span>
<span class="p">{</span><span class="s">'description'</span><span class="p">:</span> <span class="s">'A set of handgear, freezing with unnatural cold.</span><span class="se">\n</span><span class="s">'</span><span class="p">,</span>
<span class="s">'name'</span><span class="p">:</span> <span class="s">"The Set of Gauntlets 'Paurnimmen'"</span><span class="p">}</span>
</pre></div><p>
PyYAML allows you to construct a Python object of any type.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="s">"""
... none: [~, null]
... bool: [true, false, on, off]
... int: 42
... float: 3.14159
... list: [LITE, RES_ACID, SUS_DEXT]
... dict: {hp: 13, sp: 5}
... """</span><span class="p">)</span>

<span class="p">{</span><span class="s">'none'</span><span class="p">:</span> <span class="p">[</span><span class="bp">None</span><span class="p">,</span> <span class="bp">None</span><span class="p">],</span> <span class="s">'int'</span><span class="p">:</span> <span class="mi">42</span><span class="p">,</span> <span class="s">'float'</span><span class="p">:</span> <span class="mf">3.1415899999999999</span><span class="p">,</span>
<span class="s">'list'</span><span class="p">:</span> <span class="p">[</span><span class="s">'LITE'</span><span class="p">,</span> <span class="s">'RES_ACID'</span><span class="p">,</span> <span class="s">'SUS_DEXT'</span><span class="p">],</span> <span class="s">'dict'</span><span class="p">:</span> <span class="p">{</span><span class="s">'hp'</span><span class="p">:</span> <span class="mi">13</span><span class="p">,</span> <span class="s">'sp'</span><span class="p">:</span> <span class="mi">5</span><span class="p">},</span>
<span class="s">'bool'</span><span class="p">:</span> <span class="p">[</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">,</span> <span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">]}</span>
</pre></div><p>
Even instances of Python classes can be constructed using the <strong><tt>!!python/object</tt></strong> tag.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">class</span> <span class="nc">Hero</span><span class="p">:</span>
<span class="o">...</span>     <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> name<span class="p">,</span> hp<span class="p">,</span> sp<span class="p">):</span>
<span class="o">...</span>         <span class="bp">self</span><span class="o">.</span>name <span class="o">=</span> name
<span class="o">...</span>         <span class="bp">self</span><span class="o">.</span>hp <span class="o">=</span> hp
<span class="o">...</span>         <span class="bp">self</span><span class="o">.</span>sp <span class="o">=</span> sp
<span class="o">...</span>     <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="o">...</span>         <span class="k">return</span> <span class="s">"</span><span class="si">%s</span><span class="s">(name=</span><span class="si">%r</span><span class="s">, hp=</span><span class="si">%r</span><span class="s">, sp=</span><span class="si">%r</span><span class="s">)"</span> <span class="o">%</span> <span class="p">(</span>
<span class="o">...</span>             <span class="bp">self</span><span class="o">.</span>__class__<span class="o">.</span>__name__<span class="p">,</span> <span class="bp">self</span><span class="o">.</span>name<span class="p">,</span> <span class="bp">self</span><span class="o">.</span>hp<span class="p">,</span> <span class="bp">self</span><span class="o">.</span>sp<span class="p">)</span>

<span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="s">"""
... !!python/object:__main__.Hero
... name: Welthyr Syxgon
... hp: 1200
... sp: 0
... """</span><span class="p">)</span>

Hero<span class="p">(</span>name<span class="o">=</span><span class="s">'Welthyr Syxgon'</span><span class="p">,</span> hp<span class="o">=</span><span class="mi">1200</span><span class="p">,</span> sp<span class="o">=</span><span class="mi">0</span><span class="p">)</span>
</pre></div><p>
Note that the ability to construct an arbitrary Python object may be dangerous
if you receive a YAML document from an untrusted source such as Internet.
The function <strong><tt>yaml.safe_load</tt></strong> limits this ability to simple Python objects
like integers or lists.
</p>
<p>
A python object can be marked as safe and thus be recognized by <strong><tt>yaml.safe_load</tt></strong>.
To do this, derive it from <tt>yaml.YAMLObject</tt> (as explained in section
<strong>Constructors, representers, resolvers</strong>) and explicitly set its class property
<tt>yaml_loader</tt> to <tt>yaml.SafeLoader</tt>.
</p>
<h3 id="DumpingYAML">Dumping YAML</h3>
<p>
The <strong><tt>yaml.dump</tt></strong> function accepts a Python object and produces a YAML document.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">({</span><span class="s">'name'</span><span class="p">:</span> <span class="s">'Silenthand Olleander'</span><span class="p">,</span> <span class="s">'race'</span><span class="p">:</span> <span class="s">'Human'</span><span class="p">,</span>
<span class="o">...</span> <span class="s">'traits'</span><span class="p">:</span> <span class="p">[</span><span class="s">'ONE_HAND'</span><span class="p">,</span> <span class="s">'ONE_EYE'</span><span class="p">]})</span>

name<span class="p">:</span> Silenthand Olleander
race<span class="p">:</span> Human
traits<span class="p">:</span> <span class="p">[</span>ONE_HAND<span class="p">,</span> ONE_EYE<span class="p">]</span>
</pre></div><p>
<strong><tt>yaml.dump</tt></strong> accepts the second optional argument, which must be an open text
or binary file.  In this case, <strong><tt>yaml.dump</tt></strong> will write the produced YAML document
into the file.  Otherwise, <strong><tt>yaml.dump</tt></strong> returns the produced document.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> stream <span class="o">=</span> <span class="nb">file</span><span class="p">(</span><span class="s">'document.yaml'</span><span class="p">,</span> <span class="s">'w'</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>dump<span class="p">(</span>data<span class="p">,</span> stream<span class="p">)</span>    <span class="c"># Write a YAML representation of data to 'document.yaml'.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span>data<span class="p">)</span>      <span class="c"># Output the document to the screen.</span>
</pre></div><p>
If you need to dump several YAML documents to a single stream, use the function
<strong><tt>yaml.dump_all</tt></strong>. <strong><tt>yaml.dump_all</tt></strong> accepts a list or a generator producing
</p>
<p>
Python objects to be serialized into a YAML document. The second optional argument is
an open file.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> explicit_start<span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="o">---</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump_all<span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> explicit_start<span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="o">---</span> <span class="mi">1</span>
<span class="o">---</span> <span class="mi">2</span>
<span class="o">---</span> <span class="mi">3</span>
</pre></div><p>
You may even dump instances of Python classes.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">class</span> <span class="nc">Hero</span><span class="p">:</span>
<span class="o">...</span>     <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> name<span class="p">,</span> hp<span class="p">,</span> sp<span class="p">):</span>
<span class="o">...</span>         <span class="bp">self</span><span class="o">.</span>name <span class="o">=</span> name
<span class="o">...</span>         <span class="bp">self</span><span class="o">.</span>hp <span class="o">=</span> hp
<span class="o">...</span>         <span class="bp">self</span><span class="o">.</span>sp <span class="o">=</span> sp
<span class="o">...</span>     <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="o">...</span>         <span class="k">return</span> <span class="s">"</span><span class="si">%s</span><span class="s">(name=</span><span class="si">%r</span><span class="s">, hp=</span><span class="si">%r</span><span class="s">, sp=</span><span class="si">%r</span><span class="s">)"</span> <span class="o">%</span> <span class="p">(</span>
<span class="o">...</span>             <span class="bp">self</span><span class="o">.</span>__class__<span class="o">.</span>__name__<span class="p">,</span> <span class="bp">self</span><span class="o">.</span>name<span class="p">,</span> <span class="bp">self</span><span class="o">.</span>hp<span class="p">,</span> <span class="bp">self</span><span class="o">.</span>sp<span class="p">)</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span>Hero<span class="p">(</span><span class="s">"Galain Ysseleg"</span><span class="p">,</span> hp<span class="o">=-</span><span class="mi">3</span><span class="p">,</span> sp<span class="o">=</span><span class="mi">2</span><span class="p">))</span>

<span class="err">!!</span>python<span class="o">/</span><span class="nb">object</span><span class="p">:</span>__main__<span class="o">.</span>Hero <span class="p">{</span>hp<span class="p">:</span> <span class="o">-</span><span class="mi">3</span><span class="p">,</span> name<span class="p">:</span> Galain Ysseleg<span class="p">,</span> sp<span class="p">:</span> <span class="mi">2</span><span class="p">}</span>
</pre></div><p>
<strong><tt>yaml.dump</tt></strong> supports a number of keyword arguments that specify
formatting details for the emitter. For instance, you may set the
preferred intendation and width, use the canonical YAML format or
force preferred style for scalars and collections.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">50</span><span class="p">))</span>
<span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">13</span><span class="p">,</span> <span class="mi">14</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">16</span><span class="p">,</span> <span class="mi">17</span><span class="p">,</span> <span class="mi">18</span><span class="p">,</span> <span class="mi">19</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">21</span><span class="p">,</span> <span class="mi">22</span><span class="p">,</span>
  <span class="mi">23</span><span class="p">,</span> <span class="mi">24</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="mi">26</span><span class="p">,</span> <span class="mi">27</span><span class="p">,</span> <span class="mi">28</span><span class="p">,</span> <span class="mi">29</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">31</span><span class="p">,</span> <span class="mi">32</span><span class="p">,</span> <span class="mi">33</span><span class="p">,</span> <span class="mi">34</span><span class="p">,</span> <span class="mi">35</span><span class="p">,</span> <span class="mi">36</span><span class="p">,</span> <span class="mi">37</span><span class="p">,</span> <span class="mi">38</span><span class="p">,</span> <span class="mi">39</span><span class="p">,</span> <span class="mi">40</span><span class="p">,</span> <span class="mi">41</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span>
  <span class="mi">43</span><span class="p">,</span> <span class="mi">44</span><span class="p">,</span> <span class="mi">45</span><span class="p">,</span> <span class="mi">46</span><span class="p">,</span> <span class="mi">47</span><span class="p">,</span> <span class="mi">48</span><span class="p">,</span> <span class="mi">49</span><span class="p">]</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">50</span><span class="p">),</span> width<span class="o">=</span><span class="mi">50</span><span class="p">,</span> indent<span class="o">=</span><span class="mi">4</span><span class="p">)</span>
<span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">13</span><span class="p">,</span> <span class="mi">14</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span>
    <span class="mi">16</span><span class="p">,</span> <span class="mi">17</span><span class="p">,</span> <span class="mi">18</span><span class="p">,</span> <span class="mi">19</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">21</span><span class="p">,</span> <span class="mi">22</span><span class="p">,</span> <span class="mi">23</span><span class="p">,</span> <span class="mi">24</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="mi">26</span><span class="p">,</span> <span class="mi">27</span><span class="p">,</span>
    <span class="mi">28</span><span class="p">,</span> <span class="mi">29</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">31</span><span class="p">,</span> <span class="mi">32</span><span class="p">,</span> <span class="mi">33</span><span class="p">,</span> <span class="mi">34</span><span class="p">,</span> <span class="mi">35</span><span class="p">,</span> <span class="mi">36</span><span class="p">,</span> <span class="mi">37</span><span class="p">,</span> <span class="mi">38</span><span class="p">,</span> <span class="mi">39</span><span class="p">,</span>
    <span class="mi">40</span><span class="p">,</span> <span class="mi">41</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="mi">43</span><span class="p">,</span> <span class="mi">44</span><span class="p">,</span> <span class="mi">45</span><span class="p">,</span> <span class="mi">46</span><span class="p">,</span> <span class="mi">47</span><span class="p">,</span> <span class="mi">48</span><span class="p">,</span> <span class="mi">49</span><span class="p">]</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">),</span> canonical<span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="o">---</span>
<span class="err">!!</span>seq <span class="p">[</span>
  <span class="err">!!</span><span class="nb">int</span> <span class="s">"0"</span><span class="p">,</span>
  <span class="err">!!</span><span class="nb">int</span> <span class="s">"1"</span><span class="p">,</span>
  <span class="err">!!</span><span class="nb">int</span> <span class="s">"2"</span><span class="p">,</span>
  <span class="err">!!</span><span class="nb">int</span> <span class="s">"3"</span><span class="p">,</span>
  <span class="err">!!</span><span class="nb">int</span> <span class="s">"4"</span><span class="p">,</span>
<span class="p">]</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">),</span> default_flow_style<span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="o">-</span> <span class="mi">0</span>
<span class="o">-</span> <span class="mi">1</span>
<span class="o">-</span> <span class="mi">2</span>
<span class="o">-</span> <span class="mi">3</span>
<span class="o">-</span> <span class="mi">4</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">),</span> default_flow_style<span class="o">=</span><span class="bp">True</span><span class="p">,</span> default_style<span class="o">=</span><span class="s">'"'</span><span class="p">)</span>
<span class="p">[</span><span class="err">!!</span><span class="nb">int</span> <span class="s">"0"</span><span class="p">,</span> <span class="err">!!</span><span class="nb">int</span> <span class="s">"1"</span><span class="p">,</span> <span class="err">!!</span><span class="nb">int</span> <span class="s">"2"</span><span class="p">,</span> <span class="err">!!</span><span class="nb">int</span> <span class="s">"3"</span><span class="p">,</span> <span class="err">!!</span><span class="nb">int</span> <span class="s">"4"</span><span class="p">]</span>
</pre></div><h3 id="Constructorsrepresentersresolvers">Constructors, representers, resolvers</h3>
<p>
You may define your own application-specific tags. The easiest way to do it is
to define a subclass of <strong><tt>yaml.YAMLObject</tt></strong>:
</p>
<pre class="wiki">&gt;&gt;&gt; class Monster(yaml.YAMLObject):
...     yaml_tag = u'!Monster'
...     def __init__(self, name, hp, ac, attacks):
...         self.name = name
...         self.hp = hp
...         self.ac = ac
...         self.attacks = attacks
...     def __repr__(self):
...         return "%s(name=%r, hp=%r, ac=%r, attacks=%r)" % (
...             self.__class__.__name__, self.name, self.hp, self.ac, self.attacks)
</pre><p>
The above definition is enough to automatically load and dump <tt>Monster</tt> objects:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="s">"""
... --- !Monster
... name: Cave spider
... hp: [2,6]    # 2d6
... ac: 16
... attacks: [BITE, HURT]
... """</span><span class="p">)</span>

Monster<span class="p">(</span>name<span class="o">=</span><span class="s">'Cave spider'</span><span class="p">,</span> hp<span class="o">=</span><span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> ac<span class="o">=</span><span class="mi">16</span><span class="p">,</span> attacks<span class="o">=</span><span class="p">[</span><span class="s">'BITE'</span><span class="p">,</span> <span class="s">'HURT'</span><span class="p">])</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span>Monster<span class="p">(</span>
<span class="o">...</span>     name<span class="o">=</span><span class="s">'Cave lizard'</span><span class="p">,</span> hp<span class="o">=</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">],</span> ac<span class="o">=</span><span class="mi">16</span><span class="p">,</span> attacks<span class="o">=</span><span class="p">[</span><span class="s">'BITE'</span><span class="p">,</span><span class="s">'HURT'</span><span class="p">]))</span>

<span class="err">!</span>Monster
ac<span class="p">:</span> <span class="mi">16</span>
attacks<span class="p">:</span> <span class="p">[</span>BITE<span class="p">,</span> HURT<span class="p">]</span>
hp<span class="p">:</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">]</span>
name<span class="p">:</span> Cave lizard
</pre></div><p>
<strong><tt>yaml.YAMLObject</tt></strong> uses metaclass magic to register a constructor, which
transforms a YAML node to a class instance, and a representer, which serializes
a class instance to a YAML node.
</p>
<p>
If you don't want to use metaclasses, you may register your constructors
and representers using the functions <strong><tt>yaml.add_constructor</tt></strong> and
<strong><tt>yaml.add_representer</tt></strong>. For instance, you may want to add a constructor
and a representer for the following <strong><tt>Dice</tt></strong> class:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">class</span> <span class="nc">Dice</span><span class="p">(</span><span class="nb">tuple</span><span class="p">):</span>
<span class="o">...</span>     <span class="k">def</span> <span class="nf">__new__</span><span class="p">(</span>cls<span class="p">,</span> a<span class="p">,</span> b<span class="p">):</span>
<span class="o">...</span>         <span class="k">return</span> <span class="nb">tuple</span><span class="o">.</span>__new__<span class="p">(</span>cls<span class="p">,</span> <span class="p">[</span>a<span class="p">,</span> b<span class="p">])</span>
<span class="o">...</span>     <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="o">...</span>         <span class="k">return</span> <span class="s">"Dice(</span><span class="si">%s</span><span class="s">,</span><span class="si">%s</span><span class="s">)"</span> <span class="o">%</span> <span class="bp">self</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> Dice<span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">)</span>
Dice<span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">)</span>
</pre></div><p>
The default representation for <strong><tt>Dice</tt></strong> objects is not nice:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span>Dice<span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">))</span>

<span class="err">!!</span>python<span class="o">/</span><span class="nb">object</span><span class="o">/</span>new<span class="p">:</span>__main__<span class="o">.</span>Dice
<span class="o">-</span> <span class="err">!!</span>python<span class="o">/</span><span class="nb">tuple</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">]</span>
</pre></div><p>
Suppose you want a <strong><tt>Dice</tt></strong> object to represented as <strong><tt>AdB</tt></strong> in YAML:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">(</span>Dice<span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">))</span>

<span class="mi">3</span>d6
</pre></div><p>
First we define a representer that convert a dice object to scalar node
with the tag <tt>!dice</tt> and register it.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">def</span> <span class="nf">dice_representer</span><span class="p">(</span>dumper<span class="p">,</span> data<span class="p">):</span>
<span class="o">...</span>     <span class="k">return</span> dumper<span class="o">.</span>represent_scalar<span class="p">(</span><span class="s">u'!dice'</span><span class="p">,</span> <span class="s">u'</span><span class="si">%s</span><span class="s">d</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> data<span class="p">)</span>

<span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>add_representer<span class="p">(</span>Dice<span class="p">,</span> dice_representer<span class="p">)</span>
</pre></div><p>
Now you may dump an instance of the <tt>Dice</tt> object:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">({</span><span class="s">'gold'</span><span class="p">:</span> Dice<span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="mi">6</span><span class="p">)})</span>
<span class="p">{</span>gold<span class="p">:</span> <span class="err">!</span>dice <span class="s">'10d6'</span><span class="p">}</span>
</pre></div><p>
Let us add the code to construct a Dice object:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">def</span> <span class="nf">dice_constructor</span><span class="p">(</span>loader<span class="p">,</span> node<span class="p">):</span>
<span class="o">...</span>     value <span class="o">=</span> loader<span class="o">.</span>construct_scalar<span class="p">(</span>node<span class="p">)</span>
<span class="o">...</span>     a<span class="p">,</span> b <span class="o">=</span> <span class="nb">map</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> value<span class="o">.</span>split<span class="p">(</span><span class="s">'d'</span><span class="p">))</span>
<span class="o">...</span>     <span class="k">return</span> Dice<span class="p">(</span>a<span class="p">,</span> b<span class="p">)</span>

<span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>add_constructor<span class="p">(</span><span class="s">u'!dice'</span><span class="p">,</span> dice_constructor<span class="p">)</span>
</pre></div><p>
Then you may load a <tt>Dice</tt> object as well:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="s">"""
... initial hit points: !dice 8d4
... """</span><span class="p">)</span>

<span class="p">{</span><span class="s">'initial hit points'</span><span class="p">:</span> Dice<span class="p">(</span><span class="mi">8</span><span class="p">,</span><span class="mi">4</span><span class="p">)}</span>
</pre></div><p>
You might want to not specify the tag <tt>!dice</tt> everywhere. There is a way
to teach PyYAML that any untagged plain scalar that looks like XdY has
the implicit tag <tt>!dice</tt>. Use <strong><tt>add_implicit_resolver</tt></strong>:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">re</span>
<span class="o">&gt;&gt;&gt;</span> pattern <span class="o">=</span> re<span class="o">.</span>compile<span class="p">(</span><span class="s">r'^\d+d\d+$'</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> yaml<span class="o">.</span>add_implicit_resolver<span class="p">(</span><span class="s">u'!dice'</span><span class="p">,</span> pattern<span class="p">)</span>
</pre></div><p>
Now you don't have to specify the tag to define a <tt>Dice</tt> object:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>dump<span class="p">({</span><span class="s">'treasure'</span><span class="p">:</span> Dice<span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="mi">20</span><span class="p">)})</span>

<span class="p">{</span>treasure<span class="p">:</span> <span class="mi">10</span>d20<span class="p">}</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="s">"""
... damage: 5d10
... """</span><span class="p">)</span>

<span class="p">{</span><span class="s">'damage'</span><span class="p">:</span> Dice<span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="mi">10</span><span class="p">)}</span>
</pre></div><h2 id="YAMLsyntax">YAML syntax</h2>
<p>
A good introduction to the YAML syntax is
<a class="ext-link" href="http://yaml.org/spec/1.1/#id857168"><span class="icon">&nbsp;</span>Chapter 2 of the YAML specification</a>.
</p>
<p>
You may also check <a class="ext-link" href="http://yaml4r.sourceforge.net/cookbook/"><span class="icon">&nbsp;</span>the YAML cookbook</a>. Note
that it is focused on a Ruby implementation and uses the old YAML 1.0 syntax.
</p>
<p>
Here we present most common YAML constructs together with the corresponding Python objects.
</p>
<h3 id="Documents">Documents</h3>
<p>
YAML stream is a collection of zero or more documents. An empty stream contains no documents.
Documents are separated with <strong><tt>---</tt></strong>. Documents may optionally end with <strong><tt>...</tt></strong>.
A single document may or may not be marked with <strong><tt>---</tt></strong>.
</p>
<p>
Example of an implicit document:
</p>
<pre class="wiki">- Multimedia
- Internet
- Education
</pre><p>
Example of an explicit document:
</p>
<pre class="wiki">---
- Afterstep
- CTWM
- Oroborus
...
</pre><p>
Example of several documents in the same stream:
</p>
<pre class="wiki">---
- Ada
- APL
- ASP

- Assembly
- Awk
---
- Basic
---
- C
- C#    # Note that comments are denoted with ' #' (space and #).
- C++
- Cold Fusion
</pre><h3 id="Blocksequences">Block sequences</h3>
<p>
In the block context, sequence entries are denoted by <strong><tt>- </tt></strong> (dash and space):
</p>
<pre class="wiki"># YAML
- The Dagger 'Narthanc'
- The Dagger 'Nimthanc'
- The Dagger 'Dethanc'
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">[</span><span class="s">"The Dagger 'Narthanc'"</span><span class="p">,</span> <span class="s">"The Dagger 'Nimthanc'"</span><span class="p">,</span> <span class="s">"The Dagger 'Dethanc'"</span><span class="p">]</span>
</pre></div><p>
Block sequences can be nested:
</p>
<pre class="wiki"># YAML
-
  - HTML
  - LaTeX
  - SGML
  - VRML
  - XML
  - YAML
-
  - BSD
  - GNU Hurd
  - Linux
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">[[</span><span class="s">'HTML'</span><span class="p">,</span> <span class="s">'LaTeX'</span><span class="p">,</span> <span class="s">'SGML'</span><span class="p">,</span> <span class="s">'VRML'</span><span class="p">,</span> <span class="s">'XML'</span><span class="p">,</span> <span class="s">'YAML'</span><span class="p">],</span> <span class="p">[</span><span class="s">'BSD'</span><span class="p">,</span> <span class="s">'GNU Hurd'</span><span class="p">,</span> <span class="s">'Linux'</span><span class="p">]]</span>
</pre></div><p>
It's not necessary to start a nested sequence with a new line:
</p>
<pre class="wiki"># YAML
- 1.1
- - 2.1
  - 2.2
- - - 3.1
    - 3.2
    - 3.3
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">[</span><span class="mf">1.1</span><span class="p">,</span> <span class="p">[</span><span class="mf">2.1</span><span class="p">,</span> <span class="mf">2.2</span><span class="p">],</span> <span class="p">[[</span><span class="mf">3.1</span><span class="p">,</span> <span class="mf">3.2</span><span class="p">,</span> <span class="mf">3.3</span><span class="p">]]]</span>
</pre></div><p>
A block sequence may be nested to a block mapping. Note that in this
case it is not necessary to indent the sequence.
</p>
<pre class="wiki"># YAML
left hand:
- Ring of Teleportation
- Ring of Speed

right hand:
- Ring of Resist Fire
- Ring of Resist Cold
- Ring of Resist Poison
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">{</span><span class="s">'right hand'</span><span class="p">:</span> <span class="p">[</span><span class="s">'Ring of Resist Fire'</span><span class="p">,</span> <span class="s">'Ring of Resist Cold'</span><span class="p">,</span> <span class="s">'Ring of Resist Poison'</span><span class="p">],</span>
<span class="s">'left hand'</span><span class="p">:</span> <span class="p">[</span><span class="s">'Ring of Teleportation'</span><span class="p">,</span> <span class="s">'Ring of Speed'</span><span class="p">]}</span>
</pre></div><h3 id="Blockmappings">Block mappings</h3>
<p>
In the block context, keys and values of mappings are separated by <strong><tt>: </tt></strong> (colon and space):
</p>
<pre class="wiki"># YAML
base armor class: 0
base damage: [4,4]
plus to-hit: 12
plus to-dam: 16
plus to-ac: 0
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">{</span><span class="s">'plus to-hit'</span><span class="p">:</span> <span class="mi">12</span><span class="p">,</span> <span class="s">'base damage'</span><span class="p">:</span> <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">],</span> <span class="s">'base armor class'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s">'plus to-ac'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s">'plus to-dam'</span><span class="p">:</span> <span class="mi">16</span><span class="p">}</span>
</pre></div><p>
Complex keys are denoted with <strong><tt>? </tt></strong> (question mark and space):
</p>
<pre class="wiki"># YAML
? !!python/tuple [0,0]
: The Hero
? !!python/tuple [0,1]
: Treasure
? !!python/tuple [1,0]
: Treasure
? !!python/tuple [1,1]
: The Dragon
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">{(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">):</span> <span class="s">'Treasure'</span><span class="p">,</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">):</span> <span class="s">'Treasure'</span><span class="p">,</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">):</span> <span class="s">'The Hero'</span><span class="p">,</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">):</span> <span class="s">'The Dragon'</span><span class="p">}</span>
</pre></div><p>
Block mapping can be nested:
</p>
<pre class="wiki"># YAML
hero:
  hp: 34
  sp: 8
  level: 4
orc:
  hp: 12
  sp: 0
  level: 2
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">{</span><span class="s">'hero'</span><span class="p">:</span> <span class="p">{</span><span class="s">'hp'</span><span class="p">:</span> <span class="mi">34</span><span class="p">,</span> <span class="s">'sp'</span><span class="p">:</span> <span class="mi">8</span><span class="p">,</span> <span class="s">'level'</span><span class="p">:</span> <span class="mi">4</span><span class="p">},</span> <span class="s">'orc'</span><span class="p">:</span> <span class="p">{</span><span class="s">'hp'</span><span class="p">:</span> <span class="mi">12</span><span class="p">,</span> <span class="s">'sp'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s">'level'</span><span class="p">:</span> <span class="mi">2</span><span class="p">}}</span>
</pre></div><p>
A block mapping may be nested in a block sequence:
</p>
<pre class="wiki"># YAML
- name: PyYAML
  status: 4
  license: MIT
  language: Python
- name: PySyck
  status: 5
  license: BSD
  language: Python
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">[{</span><span class="s">'status'</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span> <span class="s">'language'</span><span class="p">:</span> <span class="s">'Python'</span><span class="p">,</span> <span class="s">'name'</span><span class="p">:</span> <span class="s">'PyYAML'</span><span class="p">,</span> <span class="s">'license'</span><span class="p">:</span> <span class="s">'MIT'</span><span class="p">},</span>
<span class="p">{</span><span class="s">'status'</span><span class="p">:</span> <span class="mi">5</span><span class="p">,</span> <span class="s">'license'</span><span class="p">:</span> <span class="s">'BSD'</span><span class="p">,</span> <span class="s">'name'</span><span class="p">:</span> <span class="s">'PySyck'</span><span class="p">,</span> <span class="s">'language'</span><span class="p">:</span> <span class="s">'Python'</span><span class="p">}]</span>
</pre></div><h3 id="Flowcollections">Flow collections</h3>
<p>
The syntax of flow collections in YAML is very close to the syntax of list and
dictionary constructors in Python:
</p>
<pre class="wiki"># YAML
{ str: [15, 17], con: [16, 16], dex: [17, 18], wis: [16, 16], int: [10, 13], chr: [5, 8] }
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">{</span><span class="s">'dex'</span><span class="p">:</span> <span class="p">[</span><span class="mi">17</span><span class="p">,</span> <span class="mi">18</span><span class="p">],</span> <span class="s">'int'</span><span class="p">:</span> <span class="p">[</span><span class="mi">10</span><span class="p">,</span> <span class="mi">13</span><span class="p">],</span> <span class="s">'chr'</span><span class="p">:</span> <span class="p">[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">8</span><span class="p">],</span> <span class="s">'wis'</span><span class="p">:</span> <span class="p">[</span><span class="mi">16</span><span class="p">,</span> <span class="mi">16</span><span class="p">],</span> <span class="s">'str'</span><span class="p">:</span> <span class="p">[</span><span class="mi">15</span><span class="p">,</span> <span class="mi">17</span><span class="p">],</span> <span class="s">'con'</span><span class="p">:</span> <span class="p">[</span><span class="mi">16</span><span class="p">,</span> <span class="mi">16</span><span class="p">]}</span>
</pre></div><h3 id="Scalars">Scalars</h3>
<p>
There are 5 styles of scalars in YAML: plain, single-quoted, double-quoted, literal, and folded:
</p>
<pre class="wiki"># YAML
plain: Scroll of Remove Curse
single-quoted: 'EASY_KNOW'
double-quoted: "?"
literal: |    # Borrowed from http://www.kersbergen.com/flump/religion.html
  by hjw              ___
     __              /.-.\
    /  )_____________\\  Y
   /_ /=== == === === =\ _\_
  ( /)=== == === === == Y   \
   `-------------------(  o  )
                        \___/
folded: &gt;
  It removes all ordinary curses from all equipped items.
  Heavy or permanent curses are unaffected.
</pre><div class="code"><pre><span class="c"># Python</span>
<span class="p">{</span><span class="s">'plain'</span><span class="p">:</span> <span class="s">'Scroll of Remove Curse'</span><span class="p">,</span>
<span class="s">'literal'</span><span class="p">:</span>
    <span class="s">'by hjw              ___</span><span class="se">\n</span><span class="s">'</span>
    <span class="s">'   __              /.-.</span><span class="se">\\\n</span><span class="s">'</span>
    <span class="s">'  /  )_____________</span><span class="se">\\\\</span><span class="s">  Y</span><span class="se">\n</span><span class="s">'</span>
    <span class="s">' /_ /=== == === === =</span><span class="se">\\</span><span class="s"> _</span><span class="se">\\</span><span class="s">_</span><span class="se">\n</span><span class="s">'</span>
    <span class="s">'( /)=== == === === == Y   </span><span class="se">\\\n</span><span class="s">'</span>
    <span class="s">' `-------------------(  o  )</span><span class="se">\n</span><span class="s">'</span>
    <span class="s">'                      </span><span class="se">\\</span><span class="s">___/</span><span class="se">\n</span><span class="s">'</span><span class="p">,</span>
<span class="s">'single-quoted'</span><span class="p">:</span> <span class="s">'EASY_KNOW'</span><span class="p">,</span>
<span class="s">'double-quoted'</span><span class="p">:</span> <span class="s">'?'</span><span class="p">,</span>
<span class="s">'folded'</span><span class="p">:</span> <span class="s">'It removes all ordinary curses from all equipped items. Heavy or permanent curses are unaffected.</span><span class="se">\n</span><span class="s">'</span><span class="p">}</span>
</pre></div><p>
Each style has its own quirks. A plain scalar does not use indicators to denote its
start and end, therefore it's the most restricted style. Its natural applications are
names of attributes and parameters.
</p>
<p>
Using single-quoted scalars, you may express any value that does not contain special characters.
No escaping occurs for single quoted scalars except that duplicate quotes <strong><tt>''</tt></strong> are replaced
with a single quote <strong><tt>'</tt></strong>.
</p>
<p>
Double-quoted is the most powerful style and the only style that can express any scalar value.
Double-quoted scalars allow <i>escaping</i>. Using escaping sequences <strong><tt>\x**</tt></strong> and <strong><tt>\u****</tt></strong>,
you may express any ASCII or Unicode character.
</p>
<p>
There are two kind of block scalar styles: <strong>literal</strong> and <strong>folded</strong>. The literal style is
the most suitable style for large block of text such as source code. The folded style is similar
to the literal style, but two consequent non-empty lines are joined to a single line separated
by a space character.
</p>
<h3 id="Aliases">Aliases</h3>
<p>
<del><strong>Note that PyYAML does not yet support recursive objects.</strong></del>
</p>
<p>
Using YAML you may represent objects of arbitrary graph-like structures. If you want to refer
to the same object from different parts of a document, you need to use anchors and aliases.
</p>
<p>
Anchors are denoted by the <strong><tt>&amp;</tt></strong> indicator while aliases are denoted by <strong><tt>*</tt></strong>. For instance,
the document
</p>
<pre class="wiki">left hand: &amp;A
  name: The Bastard Sword of Eowyn
  weight: 30
right hand: *A
</pre><p>
expresses the idea of a hero holding a heavy sword in both hands.
</p>
<p>
PyYAML now fully supports recursive objects. For instance, the document 
</p>
<pre class="wiki">&amp;A [ *A ]
</pre><p>
will produce a list object containing a reference to itself.
</p>
<h3 id="Tags">Tags</h3>
<p>
Tags are used to denote the type of a YAML node. Standard YAML tags are defined at
<a class="ext-link" href="http://yaml.org/type/index.html"><span class="icon">&nbsp;</span>http://yaml.org/type/index.html</a>.
</p>
<p>
Tags may be implicit:
</p>
<pre class="wiki">boolean: true
integer: 3
float: 3.14
</pre><div class="code"><pre><span class="p">{</span><span class="s">'boolean'</span><span class="p">:</span> <span class="bp">True</span><span class="p">,</span> <span class="s">'integer'</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s">'float'</span><span class="p">:</span> <span class="mf">3.14</span><span class="p">}</span>
</pre></div><p>
or explicit:
</p>
<pre class="wiki">boolean: !!bool "true"
integer: !!int "3"
float: !!float "3.14"
</pre><div class="code"><pre><span class="p">{</span><span class="s">'boolean'</span><span class="p">:</span> <span class="bp">True</span><span class="p">,</span> <span class="s">'integer'</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s">'float'</span><span class="p">:</span> <span class="mf">3.14</span><span class="p">}</span>
</pre></div><p>
Plain scalars without explicitly defined tag are subject to implicit tag
resolution. The scalar value is checked against a set of regular expressions
</p>
<p>
and if one of them matches, the corresponding tag is assigned to the scalar.
PyYAML allows an application to add custom implicit tag resolvers.
</p>
<h2 id="YAMLtagsandPythontypes">YAML tags and Python types</h2>
<p>
The following table describes how nodes with different tags are converted
to Python objects.
</p>
<table class="wiki">
<tbody><tr><td> <strong>YAML tag</strong>                   </td><td> <strong>Python type</strong>                      
</td></tr><tr><td> <i>Standard YAML tags</i>           </td><td>                                        
</td></tr><tr><td> <tt>!!null</tt>                         </td><td> <tt>None</tt>                                 
</td></tr><tr><td> <tt>!!bool</tt>                         </td><td> <tt>bool</tt>                                 
</td></tr><tr><td> <tt>!!int</tt>                          </td><td> <tt>int</tt> or <tt>long</tt> (<tt>int</tt> in Python 3)    
</td></tr><tr><td> <tt>!!float</tt>                        </td><td> <tt>float</tt>                                
</td></tr><tr><td> <tt>!!binary</tt>                       </td><td> <tt>str</tt> (<tt>bytes</tt> in Python 3)            
</td></tr><tr><td> <tt>!!timestamp</tt>                    </td><td> <tt>datetime.datetime</tt>                    
</td></tr><tr><td> <tt>!!omap</tt>, <tt></tt>!!pairs<tt></tt>            </td><td> <tt>list</tt> of pairs                        
</td></tr><tr><td> <tt>!!set</tt>                          </td><td> <tt>set</tt>                                  
</td></tr><tr><td> <tt>!!str</tt>                          </td><td> <tt>str</tt> or <tt>unicode</tt> (<tt>str</tt> in Python 3) 
</td></tr><tr><td> <tt>!!seq</tt>                          </td><td> <tt>list</tt>                                 
</td></tr><tr><td> <tt>!!map</tt>                          </td><td> <tt>dict</tt>                                 
</td></tr><tr><td> <i>Python-specific tags</i>         </td><td>                                        
</td></tr><tr><td> <tt>!!python/none</tt>                  </td><td> <tt>None</tt>                                 
</td></tr><tr><td> <tt>!!python/bool</tt>                  </td><td> <tt>bool</tt>                                 
</td></tr><tr><td> <tt>!!python/bytes</tt>                 </td><td> (<tt>bytes</tt> in Python 3)                  
</td></tr><tr><td> <tt>!!python/str</tt>                   </td><td> <tt>str</tt> (<tt>str</tt> in Python 3)              
</td></tr><tr><td> <tt>!!python/unicode</tt>               </td><td> <tt>unicode</tt> (<tt>str</tt> in Python 3)          
</td></tr><tr><td> <tt>!!python/int</tt>                   </td><td> <tt>int</tt>                                  
</td></tr><tr><td> <tt>!!python/long</tt>                  </td><td> <tt>long</tt> (<tt>int</tt> in Python 3)             
</td></tr><tr><td> <tt>!!python/float</tt>                 </td><td> <tt>float</tt>                                
</td></tr><tr><td> <tt>!!python/complex</tt>               </td><td> <tt>complex</tt>                              
</td></tr><tr><td> <tt>!!python/list</tt>                  </td><td> <tt>list</tt>                                 
</td></tr><tr><td> <tt>!!python/tuple</tt>                 </td><td> <tt>tuple</tt>                                
</td></tr><tr><td> <tt>!!python/dict</tt>                  </td><td> <tt>dict</tt>                                 
</td></tr><tr><td> <i>Complex Python tags</i>          </td><td>                                        
</td></tr><tr><td> <tt>!!python/name:module.name</tt>      </td><td> <tt>module.name</tt>                          
</td></tr><tr><td> <tt>!!python/module:package.module</tt> </td><td> <tt>package.module</tt>                       
</td></tr><tr><td> <tt>!!python/object:module.cls</tt>     </td><td> <tt>module.cls</tt> instance                  
</td></tr><tr><td> <tt>!!python/object/new:module.cls</tt> </td><td> <tt>module.cls</tt> instance                  
</td></tr><tr><td> <tt>!!python/object/apply:module.f</tt> </td><td> value of <tt>f(...)</tt>                      
</td></tr></tbody></table>
<h3 id="StringconversionPython2only">String conversion (Python 2 only)</h3>
<p>
There are four tags that are converted to <tt>str</tt> and <tt>unicode</tt> values:
<tt>!!str</tt>, <tt>!!binary</tt>, <tt>!!python/str</tt>, and <tt>!!python/unicode</tt>.
</p>
<p>
<tt>!!str</tt>-tagged scalars are converted to <tt>str</tt> objects if its value is <i>ASCII</i>. Otherwise it is converted to <tt>unicode</tt>.
<tt>!!binary</tt>-tagged scalars are converted to <tt>str</tt> objects with its value decoded using the <i>base64</i> encoding.
<tt>!!python/str</tt> scalars are converted to <tt>str</tt> objects encoded with <i>utf-8</i> encoding.
<tt>!!python/unicode</tt> scalars are converted to <tt>unicode</tt> objects.
</p>
<p>
Conversely, a <tt>str</tt> object is converted to
</p>
<ol><li>a <tt>!!str</tt> scalar if its value is <i>ASCII</i>.
</li><li>a <tt>!!python/str</tt> scalar if its value is a correct <i>utf-8</i> sequence.
</li><li>a <tt>!!binary</tt> scalar otherwise.
</li></ol><p>
A <tt>unicode</tt> object is converted to
</p>
<ol><li>a <tt>!!python/unicode</tt> scalar if its value is <i>ASCII</i>.
</li><li>a <tt>!!str</tt> scalar otherwise.
</li></ol><h3 id="StringconversionPython3only">String conversion (Python 3 only)</h3>
<p>
In Python 3, <tt>str</tt> objects are converted to <tt>!!str</tt> scalars and <tt>bytes</tt> objects to <tt>!!binary</tt> scalars.
For compatibility reasons, tags <tt>!!python/str</tt> and <tt>!!python/unicode</tt> are still supported and converted
to <tt>str</tt> objects.
</p>
<h3 id="Namesandmodules">Names and modules</h3>
<p>
In order to represent static Python objects like functions or classes, you need to use
a complex <strong><tt>!!python/name</tt></strong> tag. For instance, the function <strong><tt>yaml.dump</tt></strong> can be represented as
</p>
<pre class="wiki">!!python/name:yaml.dump
</pre><p>
Similarly, modules are represented using the tag <strong><tt>!python/module</tt></strong>:
</p>
<pre class="wiki">!!python/module:yaml
</pre><h3 id="Objects">Objects</h3>
<p>
Any pickleable object can be serialized using the <strong><tt>!!python/object</tt></strong> tag:
</p>
<pre class="wiki">!!python/object:module.Class { attribute: value, ... }
</pre><p>
In order to support the pickle protocol, two additional forms of the <strong><tt>!!python/object</tt></strong> tag
are provided:
</p>
<pre class="wiki">!!python/object/new:module.Class
args: [argument, ...]
kwds: {key: value, ...}
state: ...
listitems: [item, ...]
dictitems: [key: value, ...]
</pre><pre class="wiki">!!python/object/apply:module.function
args: [argument, ...]
kwds: {key: value, ...}
state: ...
listitems: [item, ...]
dictitems: [key: value, ...]
</pre><p>
If only the <strong><tt>args</tt></strong> field is non-empty, the above records can be shortened:
</p>
<pre class="wiki">!!python/object/new:module.Class [argument, ...]
</pre><pre class="wiki">!!python/object/apply:module.function [argument, ...]
</pre><h2 id="Reference">Reference</h2>
<p>
<strong>Warning: API stability is not guaranteed'''
</strong></p>
<h3 id="Theyamlpackage">The yaml package</h3>
<div class="code"><pre>scan<span class="p">(</span>stream<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>
</pre></div><p>
<strong><tt>scan(stream)</tt></strong> scans the given <tt>stream</tt> and produces a sequence of tokens.
</p>
<div class="code"><pre>parse<span class="p">(</span>stream<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>

emit<span class="p">(</span>events<span class="p">,</span> stream<span class="o">=</span><span class="bp">None</span><span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">,</span>
    canonical<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    indent<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    width<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    allow_unicode<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    line_break<span class="o">=</span><span class="bp">None</span><span class="p">)</span>
</pre></div><p>
<strong><tt>parse(stream)</tt></strong> parses the given <tt>stream</tt> and produces a sequence of parsing events.
</p>
<p>
<strong><tt>emit(events, stream=None)</tt></strong> serializes the given sequence of parsing <tt>events</tt> and
write them to the <tt>stream</tt>. if <tt>stream</tt> is <tt>None</tt>, it returns the produced stream.
</p>
<div class="code"><pre>compose<span class="p">(</span>stream<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>
compose_all<span class="p">(</span>stream<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>

serialize<span class="p">(</span>node<span class="p">,</span> stream<span class="o">=</span><span class="bp">None</span><span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">,</span>
    encoding<span class="o">=</span><span class="s">'utf-8'</span><span class="p">,</span> <span class="c"># encoding=None (Python 3)</span>
    explicit_start<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    explicit_end<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    version<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    tags<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    canonical<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    indent<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    width<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    allow_unicode<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    line_break<span class="o">=</span><span class="bp">None</span><span class="p">)</span>
serialize_all<span class="p">(</span>nodes<span class="p">,</span> stream<span class="o">=</span><span class="bp">None</span><span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</pre></div><p>
<strong><tt>compose(stream)</tt></strong> parses the given <tt>stream</tt> and returns the root of the representation graph
for the first document in the stream. If there are no documents in the stream, it returns <tt>None</tt>.
</p>
<p>
<strong><tt>compose_all(stream)</tt></strong> parses the given <tt>stream</tt> and returns a sequence of representation graphs
corresponding to the documents in the stream.
</p>
<p>
<strong><tt>serialize(node, stream=None)</tt></strong> serializes the given representation graph into the <tt>stream</tt>.
If <tt>stream</tt> is <tt>None</tt>, it returns the produced stream.
</p>
<p>
<strong><tt>serialize_all(node, stream=None)</tt></strong> serializes the given sequence of representation graphs
into the given <tt>stream</tt>. If <tt>stream</tt> is <tt>None</tt>, it returns the produced stream.
</p>
<div class="code"><pre>load<span class="p">(</span>stream<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>
load_all<span class="p">(</span>stream<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>

safe_load<span class="p">(</span>stream<span class="p">)</span>
safe_load_all<span class="p">(</span>stream<span class="p">)</span>

dump<span class="p">(</span>data<span class="p">,</span> stream<span class="o">=</span><span class="bp">None</span><span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">,</span>
    default_style<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    default_flow_style<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    encoding<span class="o">=</span><span class="s">'utf-8'</span><span class="p">,</span> <span class="c"># encoding=None (Python 3)</span>
    explicit_start<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    explicit_end<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    version<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    tags<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    canonical<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    indent<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    width<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    allow_unicode<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    line_break<span class="o">=</span><span class="bp">None</span><span class="p">)</span>
dump_all<span class="p">(</span>data<span class="p">,</span> stream<span class="o">=</span><span class="bp">None</span><span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">,</span> <span class="o">...</span><span class="p">)</span>

safe_dump<span class="p">(</span>data<span class="p">,</span> stream<span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
safe_dump_all<span class="p">(</span>data<span class="p">,</span> stream<span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</pre></div><p>
<strong><tt>load(stream)</tt></strong> parses the given <tt>stream</tt> and returns a Python object constructed from
for the first document in the stream. If there are no documents in the stream, it returns <tt>None</tt>.
</p>
<p>
<strong><tt>load_all(stream)</tt></strong> parses the given <tt>stream</tt> and returns a sequence of Python objects
corresponding to the documents in the stream.
</p>
<p>
<strong><tt>safe_load(stream)</tt></strong> parses the given <tt>stream</tt> and returns a Python object constructed from
for the first document in the stream. If there are no documents in the stream, it returns <tt>None</tt>.
<tt>safe_load</tt> recognizes only standard YAML tags and cannot construct an arbitrary Python object.
</p>
<p>
A python object can be marked as safe and thus be recognized by <strong><tt>yaml.safe_load</tt></strong>.
To do this, derive it from <tt>yaml.YAMLObject</tt> (as explained in section
<strong>Constructors, representers, resolvers</strong>) and explicitly set its class property
<tt>yaml_loader</tt> to <tt>yaml.SafeLoader</tt>.
</p>
<p>
<strong><tt>safe_load_all(stream)</tt></strong> parses the given <tt>stream</tt> and returns a sequence of Python objects
corresponding to the documents in the stream. <tt>safe_load_all</tt> recognizes only standard YAML tags
and cannot construct an arbitrary Python object.
</p>
<p>
<strong><tt>dump(data, stream=None)</tt></strong> serializes the given Python object into the <tt>stream</tt>.
If <tt>stream</tt> is <tt>None</tt>, it returns the produced stream.
</p>
<p>
<strong><tt>dump_all(data, stream=None)</tt></strong> serializes the given sequence of Python objects
into the given <tt>stream</tt>. If <tt>stream</tt> is <tt>None</tt>, it returns the produced stream.
Each object is represented as a YAML document.
</p>
<p>
<strong><tt>safe_dump(data, stream=None)</tt></strong> serializes the given Python object into the <tt>stream</tt>.
If <tt>stream</tt> is <tt>None</tt>, it returns the produced stream. <tt>safe_dump</tt> produces only standard YAML
tags and cannot represent an arbitrary Python object.
</p>
<p>
<strong><tt>safe_dump_all(data, stream=None)</tt></strong> serializes the given sequence of Python objects
into the given <tt>stream</tt>. If <tt>stream</tt> is <tt>None</tt>, it returns the produced stream.
Each object is represented as a YAML document.  <tt>safe_dump_all</tt> produces only standard YAML
tags and cannot represent an arbitrary Python object.
</p>
<div class="code"><pre><span class="k">def</span> <span class="nf">constructor</span><span class="p">(</span>loader<span class="p">,</span> node<span class="p">):</span>
    <span class="c"># ...</span>
    <span class="k">return</span> data

<span class="k">def</span> <span class="nf">multi_constructor</span><span class="p">(</span>loader<span class="p">,</span> tag_suffix<span class="p">,</span> node<span class="p">):</span>
    <span class="c"># ...</span>
    <span class="k">return</span> data

add_constructor<span class="p">(</span>tag<span class="p">,</span> constructor<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>
add_multi_constructor<span class="p">(</span>tag_prefix<span class="p">,</span> multi_constructor<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">)</span>
</pre></div><p>
<strong><tt>add_constructor(tag, constructor)</tt></strong> allows to specify a <tt>constructor</tt> for the given <tt>tag</tt>.
A constructor is a function that converts a node of a YAML representation graph to a native Python object.
A constructor accepts an instance of <tt>Loader</tt> and a node and returns a Python object.
</p>
<p>
<strong><tt>add_multi_constructor(tag_prefix, multi_constructor)</tt></strong> allows to specify a <tt>multi_constructor</tt>
for the given <tt>tag_prefix</tt>. A multi-constructor is a function that converts a node of a YAML
representation graph to a native Python object. A multi-constructor accepts an instance of <tt>Loader</tt>,
the suffix of the node tag, and a node and returns a Python object.
</p>
<div class="code"><pre><span class="k">def</span> <span class="nf">representer</span><span class="p">(</span>dumper<span class="p">,</span> data<span class="p">):</span>
    <span class="c"># ...</span>
    <span class="k">return</span> node

<span class="k">def</span> <span class="nf">multi_representer</span><span class="p">(</span>dumper<span class="p">,</span> data<span class="p">):</span>
    <span class="c"># ...</span>
    <span class="k">return</span> node

add_representer<span class="p">(</span>data_type<span class="p">,</span> representer<span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">)</span>
add_multi_representer<span class="p">(</span>base_data_type<span class="p">,</span> multi_representer<span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">)</span>
</pre></div><p>
<strong><tt>add_representer(data_type, representer)</tt></strong> allows to specify a <tt>representer</tt> for Python objects
of the given <tt>data_type</tt>. A representer is a function that converts a native Python object to a node
of a YAML representation graph. A representer accepts an instance of <tt>Dumper</tt> and an object and returns a node.
</p>
<p>
<strong><tt>add_multi_representer(base_data_type, multi_representer)</tt></strong> allows to specify a <tt>multi_representer</tt>
for Python objects of the given <tt>base_data_type</tt> or any of its subclasses. A multi-representer is
a function that converts a native Python object to a node of a YAML representation graph.
A multi-representer accepts an instance of <tt>Dumper</tt> and an object and returns a node.
</p>
<div class="code"><pre>add_implicit_resolver<span class="p">(</span>tag<span class="p">,</span> regexp<span class="p">,</span> first<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">)</span>
add_path_resolver<span class="p">(</span>tag<span class="p">,</span> path<span class="p">,</span> kind<span class="p">,</span> Loader<span class="o">=</span>Loader<span class="p">,</span> Dumper<span class="o">=</span>Dumper<span class="p">)</span>
</pre></div><p>
<strong><tt>add_implicit_resolver(tag, regexp, first)</tt></strong> adds an implicit tag resolver for plain scalars.
If the scalar value is matched the given <tt>regexp</tt>, it is assigned the <tt>tag</tt>. <tt>first</tt> is a
list of possible initial characters or <tt>None</tt>.
</p>
<p>
<strong><tt>add_path_resolver(tag, path, kind)</tt></strong> adds a path-based implicit tag resolver.
A <tt>path</tt> is a list of keys that form a path to a node in the representation graph.
Paths elements can be string values, integers, or <tt>None</tt>. The <tt>kind</tt> of a node can
be <tt>str</tt>, <tt>list</tt>, <tt>dict</tt>, or <tt>None</tt>.
</p>
<h3 id="Mark">Mark</h3>
<div class="code"><pre>Mark<span class="p">(</span>name<span class="p">,</span> index<span class="p">,</span> line<span class="p">,</span> column<span class="p">,</span> <span class="nb">buffer</span><span class="p">,</span> pointer<span class="p">)</span>
</pre></div><p>
An instance of <strong><tt>Mark</tt></strong> points to a certain position in the input stream. <strong><tt>name</tt></strong> is
the name of the stream, for instance it may be the filename if the input stream is a file.
<strong><tt>line</tt></strong> and <strong><tt>column</tt></strong> is the line and column of the position (starting from 0).
<strong><tt>buffer</tt></strong>, when it is not <tt>None</tt>, is a part of the input stream that contain the position
and <strong><tt>pointer</tt></strong> refers to the position in the <tt>buffer</tt>.
</p>
<h3 id="YAMLError">YAMLError</h3>
<div class="code"><pre>YAMLError<span class="p">()</span>
</pre></div><p>
If the YAML parser encounters an error condition, it raises an exception which is an instance of
<strong><tt>YAMLError</tt></strong> or of its subclass. An application may catch this exception and warn a user.
</p>
<div class="code"><pre><span class="k">try</span><span class="p">:</span>
    config <span class="o">=</span> yaml<span class="o">.</span>load<span class="p">(</span><span class="nb">file</span><span class="p">(</span><span class="s">'config.yaml'</span><span class="p">,</span> <span class="s">'r'</span><span class="p">))</span>
<span class="k">except</span> yaml<span class="o">.</span>YAMLError<span class="p">,</span> exc<span class="p">:</span>
    <span class="k">print</span> <span class="s">"Error in configuration file:"</span><span class="p">,</span> exc
</pre></div><p>
An exception produced by the YAML processor may point to the problematic position.
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">try</span><span class="p">:</span>
<span class="o">...</span>     yaml<span class="o">.</span>load<span class="p">(</span><span class="s">"unbalanced blackets: ]["</span><span class="p">)</span>
<span class="o">...</span> <span class="k">except</span> yaml<span class="o">.</span>YAMLError<span class="p">,</span> exc<span class="p">:</span>
<span class="o">...</span>     <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span>exc<span class="p">,</span> <span class="s">'problem_mark'</span><span class="p">):</span>
<span class="o">...</span>         mark <span class="o">=</span> exc<span class="o">.</span>problem_mark
<span class="o">...</span>         <span class="k">print</span> <span class="s">"Error position: (</span><span class="si">%s</span><span class="s">:</span><span class="si">%s</span><span class="s">)"</span> <span class="o">%</span> <span class="p">(</span>mark<span class="o">.</span>line<span class="o">+</span><span class="mi">1</span><span class="p">,</span> mark<span class="o">.</span>column<span class="o">+</span><span class="mi">1</span><span class="p">)</span>

Error position<span class="p">:</span> <span class="p">(</span><span class="mi">1</span><span class="p">:</span><span class="mi">22</span><span class="p">)</span>
</pre></div><h3 id="Tokens">Tokens</h3>
<p>
Tokens are produced by a YAML scanner. They are not really useful except for low-level YAML
applications such as syntax highlighting.
</p>
<p>
The PyYAML scanner produces the following types of tokens:
</p>
<div class="code"><pre>StreamStartToken<span class="p">(</span>encoding<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># Start of the stream.</span>
StreamEndToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># End of the stream.</span>
DirectiveToken<span class="p">(</span>name<span class="p">,</span> value<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># YAML directive, either %YAML or %TAG.</span>
DocumentStartToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '---'.</span>
DocumentEndToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '...'.</span>
BlockSequenceStartToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># Start of a new block sequence.</span>
BlockMappingStartToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># Start of a new block mapping.</span>
BlockEndToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># End of a block collection.</span>
FlowSequenceStartToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '['.</span>
FlowMappingStartToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '{'.</span>
FlowSequenceEndToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># ']'.</span>
FlowMappingEndToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '}'.</span>
KeyToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># Either '?' or start of a simple key.</span>
ValueToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># ':'.</span>
BlockEntryToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '-'.</span>
FlowEntryToken<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># ','.</span>
AliasToken<span class="p">(</span>value<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '*value'.</span>
AnchorToken<span class="p">(</span>value<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '&amp;value'.</span>
TagToken<span class="p">(</span>value<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># '!value'.</span>
ScalarToken<span class="p">(</span>value<span class="p">,</span> plain<span class="p">,</span> style<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span> <span class="c"># 'value'.</span>
</pre></div><p>
<strong><tt>start_mark</tt></strong> and <strong><tt>end_mark</tt></strong> denote the beginning and the end of a token.
</p>
<p>
Example:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> document <span class="o">=</span> <span class="s">"""
... ---
... block sequence:
... - BlockEntryToken
... block mapping:
...   ? KeyToken
...   : ValueToken
... flow sequence: [FlowEntryToken, FlowEntryToken]
... flow mapping: {KeyToken: ValueToken}
... anchors and tags:
... - &amp;A !!int '5'
... - *A
... ...
... """</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> token <span class="ow">in</span> yaml<span class="o">.</span>scan<span class="p">(</span>document<span class="p">):</span>
<span class="o">...</span>     <span class="k">print</span> token

StreamStartToken<span class="p">(</span>encoding<span class="o">=</span><span class="s">'utf-8'</span><span class="p">)</span>

DocumentStartToken<span class="p">()</span>

BlockMappingStartToken<span class="p">()</span>

KeyToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'block sequence'</span><span class="p">)</span>

ValueToken<span class="p">()</span>
BlockEntryToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'BlockEntryToken'</span><span class="p">)</span>

KeyToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'block mapping'</span><span class="p">)</span>

ValueToken<span class="p">()</span>
BlockMappingStartToken<span class="p">()</span>

KeyToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'KeyToken'</span><span class="p">)</span>
ValueToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'ValueToken'</span><span class="p">)</span>
BlockEndToken<span class="p">()</span>

KeyToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'flow sequence'</span><span class="p">)</span>

ValueToken<span class="p">()</span>
FlowSequenceStartToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'FlowEntryToken'</span><span class="p">)</span>
FlowEntryToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'FlowEntryToken'</span><span class="p">)</span>
FlowSequenceEndToken<span class="p">()</span>

KeyToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'flow mapping'</span><span class="p">)</span>

ValueToken<span class="p">()</span>
FlowMappingStartToken<span class="p">()</span>
KeyToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'KeyToken'</span><span class="p">)</span>
ValueToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'ValueToken'</span><span class="p">)</span>
FlowMappingEndToken<span class="p">()</span>

KeyToken<span class="p">()</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">True</span><span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'anchors and tags'</span><span class="p">)</span>

ValueToken<span class="p">()</span>
BlockEntryToken<span class="p">()</span>
AnchorToken<span class="p">(</span>value<span class="o">=</span><span class="s">u'A'</span><span class="p">)</span>
TagToken<span class="p">(</span>value<span class="o">=</span><span class="p">(</span><span class="s">u'!!'</span><span class="p">,</span> <span class="s">u'int'</span><span class="p">))</span>
ScalarToken<span class="p">(</span>plain<span class="o">=</span><span class="bp">False</span><span class="p">,</span> style<span class="o">=</span><span class="s">"'"</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'5'</span><span class="p">)</span>

BlockEntryToken<span class="p">()</span>
AliasToken<span class="p">(</span>value<span class="o">=</span><span class="s">u'A'</span><span class="p">)</span>

BlockEndToken<span class="p">()</span>

DocumentEndToken<span class="p">()</span>

StreamEndToken<span class="p">()</span>
</pre></div><h3 id="Events">Events</h3>
<p>
Events are used by the low-level Parser and Emitter interfaces, which are similar to the SAX API.
While the Parser parses a YAML stream and produces a sequence of events, the Emitter accepts
a sequence of events and emits a YAML stream.
</p>
<p>
The following events are defined:
</p>
<div class="code"><pre>StreamStartEvent<span class="p">(</span>encoding<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
StreamEndEvent<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span>
DocumentStartEvent<span class="p">(</span>explicit<span class="p">,</span> version<span class="p">,</span> tags<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
DocumentEndEvent<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span>
SequenceStartEvent<span class="p">(</span>anchor<span class="p">,</span> tag<span class="p">,</span> implicit<span class="p">,</span> flow_style<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
SequenceEndEvent<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span>
MappingStartEvent<span class="p">(</span>anchor<span class="p">,</span> tag<span class="p">,</span> implicit<span class="p">,</span> flow_style<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
MappingEndEvent<span class="p">(</span>start_mark<span class="p">,</span> end_mark<span class="p">)</span>
AliasEvent<span class="p">(</span>anchor<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="p">,</span> tag<span class="p">,</span> implicit<span class="p">,</span> value<span class="p">,</span> style<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
</pre></div><p>
The <strong><tt>flow_style</tt></strong> flag indicates if a collection is block or flow. The possible values are
<tt>None</tt>, <tt>True</tt>, <tt>False</tt>. The <strong><tt>style</tt></strong> flag of a scalar event indicates the style of the scalar.
Possible values are <tt>None</tt>, <tt>''</tt>, <tt>'\''</tt>, <tt>'"'</tt>, <tt>'|'</tt>, <tt>'&gt;'</tt>. The <strong><tt>implicit</tt></strong> flag of a collection
start event indicates if the tag may be omitted when the collection is emitted. The <strong><tt>implicit</tt></strong> flag
of a scalar event is a pair of boolean values that indicate if the tag may be omitted when the scalar
is emitted in a plain and non-plain style correspondingly.
</p>
<p>
Example:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> document <span class="o">=</span> <span class="s">"""
... scalar: &amp;A !!int '5'
... alias: *A
... sequence: [1, 2, 3]
... mapping: [1: one, 2: two, 3: three]
... """</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> event <span class="ow">in</span> yaml<span class="o">.</span>parse<span class="p">(</span>document<span class="p">):</span>
<span class="o">...</span>     <span class="k">print</span> event

StreamStartEvent<span class="p">()</span>

DocumentStartEvent<span class="p">()</span>

MappingStartEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="bp">True</span><span class="p">)</span>

ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'scalar'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="s">u'A'</span><span class="p">,</span> tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:int'</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">False</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'5'</span><span class="p">)</span>

ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'alias'</span><span class="p">)</span>
AliasEvent<span class="p">(</span>anchor<span class="o">=</span><span class="s">u'A'</span><span class="p">)</span>

ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'sequence'</span><span class="p">)</span>
SequenceStartEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="bp">True</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'1'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'2'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'3'</span><span class="p">)</span>
SequenceEndEvent<span class="p">()</span>

ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'mapping'</span><span class="p">)</span>
MappingStartEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="bp">True</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'1'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'one'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'2'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'two'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'3'</span><span class="p">)</span>
ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="bp">None</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'three'</span><span class="p">)</span>
MappingEndEvent<span class="p">()</span>

MappingEndEvent<span class="p">()</span>

DocumentEndEvent<span class="p">()</span>

StreamEndEvent<span class="p">()</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>emit<span class="p">([</span>
<span class="o">...</span>     yaml<span class="o">.</span>StreamStartEvent<span class="p">(</span>encoding<span class="o">=</span><span class="s">'utf-8'</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>DocumentStartEvent<span class="p">(</span>explicit<span class="o">=</span><span class="bp">True</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>MappingStartEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:map'</span><span class="p">,</span> implicit<span class="o">=</span><span class="bp">True</span><span class="p">,</span> flow_style<span class="o">=</span><span class="bp">False</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">True</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'agile languages'</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>SequenceStartEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:seq'</span><span class="p">,</span> implicit<span class="o">=</span><span class="bp">True</span><span class="p">,</span> flow_style<span class="o">=</span><span class="bp">True</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">True</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'Python'</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">True</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'Perl'</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>ScalarEvent<span class="p">(</span>anchor<span class="o">=</span><span class="bp">None</span><span class="p">,</span> tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> implicit<span class="o">=</span><span class="p">(</span><span class="bp">True</span><span class="p">,</span> <span class="bp">True</span><span class="p">),</span> value<span class="o">=</span><span class="s">u'Ruby'</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>SequenceEndEvent<span class="p">(),</span>
<span class="o">...</span>     yaml<span class="o">.</span>MappingEndEvent<span class="p">(),</span>
<span class="o">...</span>     yaml<span class="o">.</span>DocumentEndEvent<span class="p">(</span>explicit<span class="o">=</span><span class="bp">True</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>StreamEndEvent<span class="p">(),</span>
<span class="o">...</span> <span class="p">])</span>

<span class="o">---</span>
agile languages<span class="p">:</span> <span class="p">[</span>Python<span class="p">,</span> Perl<span class="p">,</span> Ruby<span class="p">]</span>
<span class="o">...</span>
</pre></div><h3 id="Nodes">Nodes</h3>
<p>
Nodes are entities in the YAML informational model. There are three kinds of nodes:
<i>scalar</i>, <i>sequence</i>, and <i>mapping</i>. In PyYAML, nodes are produced by Composer
and can be serialized to a YAML stream by Serializer.
</p>
<div class="code"><pre>ScalarNode<span class="p">(</span>tag<span class="p">,</span> value<span class="p">,</span> style<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
SequenceNode<span class="p">(</span>tag<span class="p">,</span> value<span class="p">,</span> flow_style<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
MappingNode<span class="p">(</span>tag<span class="p">,</span> value<span class="p">,</span> flow_style<span class="p">,</span> start_mark<span class="p">,</span> end_mark<span class="p">)</span>
</pre></div><p>
The <strong><tt>style</tt></strong> and <strong><tt>flow_style</tt></strong> flags have the same meaning as for events.
The value of a scalar node must be a unicode string. The value of a sequence node is
a list of nodes. The value of a mapping node is a list of pairs consisting of key and
value nodes.
</p>
<p>
Example:
</p>
<div class="code"><pre><span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>compose<span class="p">(</span><span class="s">"""
... kinds:
... - scalar
... - sequence
... - mapping
... """</span><span class="p">)</span>

MappingNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:map'</span><span class="p">,</span> value<span class="o">=</span><span class="p">[</span>
    <span class="p">(</span>ScalarNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'kinds'</span><span class="p">),</span> SequenceNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:seq'</span><span class="p">,</span> value<span class="o">=</span><span class="p">[</span>
        ScalarNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'scalar'</span><span class="p">),</span>
        ScalarNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'sequence'</span><span class="p">),</span>
        ScalarNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'mapping'</span><span class="p">)]))])</span>

<span class="o">&gt;&gt;&gt;</span> <span class="k">print</span> yaml<span class="o">.</span>serialize<span class="p">(</span>yaml<span class="o">.</span>SequenceNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:seq'</span><span class="p">,</span> value<span class="o">=</span><span class="p">[</span>
<span class="o">...</span>     yaml<span class="o">.</span>ScalarNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'scalar'</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>ScalarNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'sequence'</span><span class="p">),</span>
<span class="o">...</span>     yaml<span class="o">.</span>ScalarNode<span class="p">(</span>tag<span class="o">=</span><span class="s">u'tag:yaml.org,2002:str'</span><span class="p">,</span> value<span class="o">=</span><span class="s">u'mapping'</span><span class="p">)]))</span>

<span class="o">-</span> scalar
<span class="o">-</span> sequence
<span class="o">-</span> mapping
</pre></div><h3 id="Loader">Loader</h3>
<div class="code"><pre>Loader<span class="p">(</span>stream<span class="p">)</span>
SafeLoader<span class="p">(</span>stream<span class="p">)</span>
BaseLoader<span class="p">(</span>stream<span class="p">)</span>

<span class="c"># The following classes are available only if you build LibYAML bindings.</span>
CLoader<span class="p">(</span>stream<span class="p">)</span>
CSafeLoader<span class="p">(</span>stream<span class="p">)</span>
CBaseLoader<span class="p">(</span>stream<span class="p">)</span>
</pre></div><p>
<strong><tt>Loader(stream)</tt></strong> is the most common of the above classes and should be used in most cases.
<tt>stream</tt> is an input YAML stream. It can be a string, a Unicode string, an open file, an open Unicode file.
</p>
<p>
<strong><tt>Loader</tt></strong> supports all predefined tags and may construct an arbitrary Python object. Therefore it is not safe to use
<tt>Loader</tt> to load a document received from an untrusted source. By default, the functions <tt>scan</tt>, <tt>parse</tt>,
<tt>compose</tt>, <tt>construct</tt>, and others use <tt>Loader</tt>.
</p>
<p>
<strong><tt>SafeLoader(stream)</tt></strong> supports only standard YAML tags and thus it does not construct class instances and
probably safe to use with documents received from an untrusted source. The functions <tt>safe_load</tt> and
<tt>safe_load_all</tt> use <tt>SafeLoader</tt> to parse a stream.
</p>
<p>
<strong><tt>BaseLoader(stream)</tt></strong> does not resolve or support any tags and construct only basic Python objects:
lists, dictionaries and Unicode strings.
</p>
<p>
<strong><tt>CLoader</tt></strong>, <strong><tt>CSafeLoader</tt></strong>, <strong><tt>CBaseLoader</tt></strong> are versions of the above classes written in C
using the <a class="wiki" href="http://pyyaml.org/wiki/LibYAML">LibYAML</a> library.
</p>
<div class="code"><pre>Loader<span class="o">.</span>check_token<span class="p">(</span><span class="o">*</span>TokenClasses<span class="p">)</span>
Loader<span class="o">.</span>peek_token<span class="p">()</span>
Loader<span class="o">.</span>get_token<span class="p">()</span>
</pre></div><p>
<strong><tt>Loader.check_token(*TokenClasses)</tt></strong> returns <tt>True</tt> if the next token in the stream
is an instance of one of the given <tt>TokenClasses</tt>. Otherwise it returns <tt>False</tt>.
</p>
<p>
<strong><tt>Loader.peek_token()</tt></strong> returns the next token in the stream, but does not remove
it from the internal token queue. The function returns <tt>None</tt> at the end of the stream.
</p>
<p>
<strong><tt>Loader.get_token()</tt></strong> returns the next token in the stream and removes
it from the internal token queue. The function returns <tt>None</tt> at the end of the stream.
</p>
<div class="code"><pre>Loader<span class="o">.</span>check_event<span class="p">(</span><span class="o">*</span>EventClasses<span class="p">)</span>
Loader<span class="o">.</span>peek_event<span class="p">()</span>
Loader<span class="o">.</span>get_event<span class="p">()</span>
</pre></div><p>
<strong><tt>Loader.check_event(*EventClasses)</tt></strong> returns <tt>True</tt> if the next event in the stream
is an instance of one of the given <tt>EventClasses</tt>. Otherwise it returns <tt>False</tt>.
</p>
<p>
<strong><tt>Loader.peek_event()</tt></strong> returns the next event in the stream, but does not remove
it from the internal event queue. The function returns <tt>None</tt> at the end of the stream.
</p>
<p>
<strong><tt>Loader.get_event()</tt></strong> returns the next event in the stream and removes
it from the internal event queue. The function returns <tt>None</tt> at the end of the stream.
</p>
<div class="code"><pre>Loader<span class="o">.</span>check_node<span class="p">()</span>
Loader<span class="o">.</span>get_node<span class="p">()</span>
</pre></div><p>
<strong><tt>Loader.check_node()</tt></strong> returns <tt>True</tt> is there are more documents available in the stream. Otherwise
it returns <tt>False</tt>.
</p>
<p>
<strong><tt>Loader.get_node()</tt></strong> construct the representation graph of the next document in the stream and
returns its root node.
</p>
<div class="code"><pre>Loader<span class="o">.</span>check_data<span class="p">()</span>
Loader<span class="o">.</span>get_data<span class="p">()</span>

Loader<span class="o">.</span>add_constructor<span class="p">(</span>tag<span class="p">,</span> constructor<span class="p">)</span> <span class="c"># Loader.add_constructor is a class method.</span>
Loader<span class="o">.</span>add_multi_constructor<span class="p">(</span>tag_prefix<span class="p">,</span> multi_constructor<span class="p">)</span> <span class="c"># Loader.add_multi_constructor is a class method.</span>

Loader<span class="o">.</span>construct_scalar<span class="p">(</span>node<span class="p">)</span>
Loader<span class="o">.</span>construct_sequence<span class="p">(</span>node<span class="p">)</span>
Loader<span class="o">.</span>construct_mapping<span class="p">(</span>node<span class="p">)</span>
</pre></div><p>
<strong><tt>Loader.check_data()</tt></strong> returns <tt>True</tt> is there are more documents available in the stream. Otherwise
it returns <tt>False</tt>.
</p>
<p>
<strong><tt>Loader.get_data()</tt></strong> constructs and returns a Python object corresponding to the next document
in the stream.
</p>
<p>
<strong><tt>Loader.add_constructor(tag, constructor)</tt></strong>: see <tt>add_constructor</tt>.
</p>
<p>
<strong><tt>Loader.add_multi_constructor(tag_prefix, multi_constructor)</tt></strong>: see <tt>add_multi_constructor</tt>.
</p>
<p>
<strong><tt>Loader.construct_scalar(node)</tt></strong> checks that the given <tt>node</tt> is a scalar and returns its value.
This function is intended to be used in constructors.
</p>
<p>
<strong><tt>Loader.construct_sequence(node)</tt></strong> checks that the given <tt>node</tt> is a sequence and returns a list
of Python objects corresponding to the node items. This function is intended to be used in constructors.
</p>
<p>
<strong><tt>Loader.construct_mapping(node)</tt></strong> checks that the given <tt>node</tt> is a mapping and returns a dictionary
of Python objects corresponding to the node keys and values. This function is intended to be used in constructors.
</p>
<div class="code"><pre>Loader<span class="o">.</span>add_implicit_resolver<span class="p">(</span>tag<span class="p">,</span> regexp<span class="p">,</span> first<span class="p">)</span> <span class="c"># Loader.add_implicit_resolver is a class method.</span>
Loader<span class="o">.</span>add_path_resolver<span class="p">(</span>tag<span class="p">,</span> path<span class="p">,</span> kind<span class="p">)</span> <span class="c"># Loader.add_path_resolver is a class method.</span>
</pre></div><p>
<strong><tt>Loader.add_implicit_resolver(tag, regexp, first)</tt></strong>: see <tt>add_implicit_resolver</tt>.
</p>
<p>
<strong><tt>Loader.add_path_resolver(tag, path, kind)</tt></strong>: see <tt>add_path_resolver</tt>.
</p>
<h3 id="Dumper">Dumper</h3>
<div class="code"><pre>Dumper<span class="p">(</span>stream<span class="p">,</span>
    default_style<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    default_flow_style<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    canonical<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    indent<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    width<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    allow_unicode<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    line_break<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    encoding<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    explicit_start<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    explicit_end<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    version<span class="o">=</span><span class="bp">None</span><span class="p">,</span>
    tags<span class="o">=</span><span class="bp">None</span><span class="p">)</span>
SafeDumper<span class="p">(</span>stream<span class="p">,</span> <span class="o">...</span><span class="p">)</span>
BaseDumper<span class="p">(</span>stream<span class="p">,</span> <span class="o">...</span><span class="p">)</span>

<span class="c"># The following classes are available only if you build LibYAML bindings.</span>
CDumper<span class="p">(</span>stream<span class="p">,</span> <span class="o">...</span><span class="p">)</span>
CSafeDumper<span class="p">(</span>stream<span class="p">,</span> <span class="o">...</span><span class="p">)</span>
CBaseDumper<span class="p">(</span>stream<span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</pre></div><p>
<strong><tt>Dumper(stream)</tt></strong> is the most common of the above classes and should be used in most cases.
<tt>stream</tt> is an output YAML stream. It can be an open file or an open Unicode file.
</p>
<p>
<strong><tt>Dumper</tt></strong> supports all predefined tags and may represent an arbitrary Python object. Therefore
it may produce a document that cannot be loaded by other YAML processors. By default, the functions
<tt>emit</tt>, <tt>serialize</tt>, <tt>dump</tt>, and others use <tt>Dumper</tt>.
</p>
<p>
<strong><tt>SafeDumper(stream)</tt></strong> produces only standard YAML tags and thus cannot represent class instances and
probably more compatible with other YAML processors. The functions <tt>safe_dump</tt> and <tt>safe_dump_all</tt>
use <tt>SafeDumper</tt> to produce a YAML document.
</p>
<p>
<strong><tt>BaseDumper(stream)</tt></strong> does not support any tags and is useful only for subclassing.
</p>
<p>
<strong><tt>CDumper</tt></strong>, <strong><tt>CSafeDumper</tt></strong>, <strong><tt>CBaseDumper</tt></strong> are versions of the above classes written in C
using the <a class="wiki" href="http://pyyaml.org/wiki/LibYAML">LibYAML</a> library.
</p>
<div class="code"><pre>Dumper<span class="o">.</span>emit<span class="p">(</span>event<span class="p">)</span>
</pre></div><p>
<strong><tt>Dumper.emit(event)</tt></strong> serializes the given <tt>event</tt> and write it to the output stream.
</p>
<div class="code"><pre>Dumper<span class="o">.</span>open<span class="p">()</span>
Dumper<span class="o">.</span>serialize<span class="p">(</span>node<span class="p">)</span>
Dumper<span class="o">.</span>close<span class="p">()</span>
</pre></div><p>
<strong><tt>Dumper.open()</tt></strong> emits <tt>StreamStartEvent</tt>.
</p>
<p>
<strong><tt>Dumper.serialize(node)</tt></strong> serializes the given representation graph into the output stream.
</p>
<p>
<strong><tt>Dumper.close()</tt></strong> emits <tt>StreamEndEvent</tt>.
</p>
<div class="code"><pre>Dumper<span class="o">.</span>represent<span class="p">(</span>data<span class="p">)</span>

Dumper<span class="o">.</span>add_representer<span class="p">(</span>data_type<span class="p">,</span> representer<span class="p">)</span> <span class="c"># Dumper.add_representer is a class method.</span>
Dumper<span class="o">.</span>add_multi_representer<span class="p">(</span>base_data_type<span class="p">,</span> multi_representer<span class="p">)</span> <span class="c"># Dumper.add_multi_representer is a class method.</span>

Dumper<span class="o">.</span>represent_scalar<span class="p">(</span>tag<span class="p">,</span> value<span class="p">,</span> style<span class="o">=</span><span class="bp">None</span><span class="p">)</span>
Dumper<span class="o">.</span>represent_sequence<span class="p">(</span>tag<span class="p">,</span> value<span class="p">,</span> flow_style<span class="o">=</span><span class="bp">None</span><span class="p">)</span>
Dumper<span class="o">.</span>represent_mapping<span class="p">(</span>tag<span class="p">,</span> value<span class="p">,</span> flow_style<span class="o">=</span><span class="bp">None</span><span class="p">)</span>
</pre></div><p>
<strong><tt>Dumper.represent(data)</tt></strong> serializes the given Python object to the output YAML stream.
</p>
<p>
<strong><tt>Dumper.add_representer(data_type, representer)</tt></strong>: see <tt>add_representer</tt>.
</p>
<p>
<strong><tt>Dumper.add_multi_representer(base_data_type, multi_representer)</tt></strong>: see <tt>add_multi_representer</tt>.
</p>
<p>
<strong><tt>Dumper.represent_scalar(tag, value, style=None)</tt></strong> returns a scalar node with the given <tt>tag</tt>, <tt>value</tt>, and <tt>style</tt>.
This function is intended to be used in representers.
</p>
<p>
<strong><tt>Dumper.represent_sequence(tag, sequence, flow_style=None)</tt></strong> return a sequence node with the given <tt>tag</tt>
and subnodes generated from the items of the given <tt>sequence</tt>.
</p>
<p>
<strong><tt>Dumper.represent_mapping(tag, mapping, flow_style=None)</tt></strong> return a mapping node with the given <tt>tag</tt>
and subnodes generated from the keys and values of the given <tt>mapping</tt>.
</p>
<div class="code"><pre>Dumper<span class="o">.</span>add_implicit_resolver<span class="p">(</span>tag<span class="p">,</span> regexp<span class="p">,</span> first<span class="p">)</span> <span class="c"># Dumper.add_implicit_resolver is a class method.</span>
Dumper<span class="o">.</span>add_path_resolver<span class="p">(</span>tag<span class="p">,</span> path<span class="p">,</span> kind<span class="p">)</span> <span class="c"># Dumper.add_path_resolver is a class method.</span>
</pre></div><p>
<strong><tt>Dumper.add_implicit_resolver(tag, regexp, first)</tt></strong>: see <tt>add_implicit_resolver</tt>.
</p>
<p>
<strong><tt>Dumper.add_path_resolver(tag, path, kind)</tt></strong>: see <tt>add_path_resolver</tt>.
</p>
<h3 id="YAMLObject">YAMLObject</h3>
<div class="code"><pre><span class="k">class</span> <span class="nc">MyYAMLObject</span><span class="p">(</span>YAMLObject<span class="p">):</span>
    yaml_loader <span class="o">=</span> Loader
    yaml_dumper <span class="o">=</span> Dumper

    yaml_tag <span class="o">=</span> <span class="s">u'...'</span>
    yaml_flow_style <span class="o">=</span> <span class="o">...</span>

    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_yaml</span><span class="p">(</span>cls<span class="p">,</span> loader<span class="p">,</span> node<span class="p">):</span>
        <span class="c"># ...</span>
        <span class="k">return</span> data

    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">to_yaml</span><span class="p">(</span>cls<span class="p">,</span> dumper<span class="p">,</span> data<span class="p">):</span>
        <span class="c"># ...</span>
        <span class="k">return</span> node
</pre></div><p>
Subclassing <strong><tt>YAMLObject</tt></strong> is an easy way to define tags, constructors, and representers
for your classes. You only need to override the <tt>yaml_tag</tt> attribute. If you want
to define your custom constructor and representer, redefine the <tt>from_yaml</tt> and <tt>to_yaml</tt> method
correspondingly.
</p>
<h2 id="Deviationsfromthespecification">Deviations from the specification</h2>
<p>
<i>need to update this section</i>
</p>
<ul><li>rules for tabs in YAML are confusing. We are close, but not there yet.
Perhaps both the spec and the parser should be fixed. Anyway, the best
rule for tabs in YAML is to not use them at all.
</li><li>Byte order mark. The initial BOM is stripped, but BOMs inside the stream
are considered as parts of the content. It can be fixed, but it's not
really important now.
</li><li><del>Empty plain scalars are not allowed if alias or tag is specified.</del> This
is done to prevent anomalities like <strong>[ !tag, value]</strong>, which can be
interpreted both as <strong>[ !&lt;!tag,&gt; value ]</strong> and <strong>[ !&lt;!tag&gt; "", "value" ]</strong>.
The spec should be fixed.
</li><li>Indentation of flow collections. The spec requires them to be indented
more than their block parent node. Unfortunately this rule renders many intuitively
correct constructs invalid, for instance,
<pre class="wiki">block: {
} # this is indentation violation according to the spec.
</pre></li><li>':' is not allowed for plain scalars in the flow mode. <del><strong>{1:2}</strong> is
interpreted as <strong>{ 1 : 2 }</strong>.</del>
</li></ul>
        
        
      </div>
          <div class="buttons">
              <form method="get" action="/wiki/PyYAMLDocumentation" id="modifypage">
                <div>
                  <input name="action" value="edit" type="hidden">
                      <input value="Edit this page" type="submit">
                </div>
              </form>
    <form method="get" action="/attachment/wiki/PyYAMLDocumentation/" id="attachfile">
      <div>
        <input name="action" value="new" type="hidden">
        <input name="attachfilebutton" value="Attach file" type="submit">
      </div>
    </form>
          </div>
    </div>
    <script type="text/javascript">
        jQuery.loadStyleSheet("/pygments/trac.css", "text/css");
    </script>
    <div id="altlinks">
      <h3>Download in other formats:</h3>
      <ul>
        <li class="last first">
          <a rel="nofollow" href="http://pyyaml.org/wiki/PyYAMLDocumentation?format=txt">Plain Text</a>
        </li>
      </ul>
    </div>
    </div>
    <div id="footer" xml:lang="en" lang="en"><hr>
      <a id="tracpowered" href="http://trac.edgewall.org/"><img src="PyYAMLDocumentation_files/trac_logo_mini.png" alt="Trac Powered" height="30" width="107"></a>
      <p class="left">
        Powered by <a href="http://pyyaml.org/about"><strong>Trac 0.11.7</strong></a><br>
        By <a href="http://www.edgewall.org/">Edgewall Software</a>.
      </p>
      <p class="right">Visit the Trac open source project at<br><a href="http://trac.edgewall.org/">http://trac.edgewall.org/</a></p>
    </div>
    <script type="text/javascript">
    var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
    document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
    </script>
    <script type="text/javascript">
    try {
    var pageTracker = _gat._getTracker("UA-6910635-1");
    pageTracker._trackPageview();
    } catch(err) {}</script>
    <script type="text/javascript">
    //<![CDATA[
      var re = RegExp("^http://pyyaml.org(/download/.*)$");
      var as = document.getElementsByTagName('a');
      for (var i = 0; i < as.length; i++) {
        var a = as[i];
        if (a.href && re.test(a.href)) {
          a.onclick = function() { try { pageTracker._trackPageview(re.exec(this.href)[1]); } catch(err) {} };
        }
      }
    //]]>
    </script>
  
</body></html>
generated by cgit (git 2.34.1) at 2024-11-08 20:05:10 +0000