<!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&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"> </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"> </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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></span> documents <span class="o">=</span> <span class="s">"""
... ---
... name: The Set of Gauntlets 'Pauraegen'
... description: >
... A set of handgear with sparks that crackle
... across its knuckleguards.
... ---
... name: The Set of Gauntlets 'Paurnen'
... description: >
... A set of gauntlets that gives off a foul,
... acrid odour yet remains untarnished.
... ---
... name: The Set of Gauntlets 'Paurnimmen'
... description: >
... A set of handgear, freezing with unnatural cold.
... """</span>
<span class="o">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>> 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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></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">>>></span> <span class="kn">import</span> <span class="nn">re</span>
<span class="o">>>></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">>>></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">>>></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">>>></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"> </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"> </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: >
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>&</tt></strong> indicator while aliases are denoted by <strong><tt>*</tt></strong>. For instance,
the document
</p>
<pre class="wiki">left hand: &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">&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"> </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">>>></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"># '&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">>>></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:
... - &A !!int '5'
... - *A
... ...
... """</span>
<span class="o">>>></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>'>'</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">>>></span> document <span class="o">=</span> <span class="s">"""
... scalar: &A !!int '5'
... alias: *A
... sequence: [1, 2, 3]
... mapping: [1: one, 2: two, 3: three]
... """</span>
<span class="o">>>></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">>>></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">>>></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">>>></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>[ !<!tag,> value ]</strong> and <strong>[ !<!tag> "", "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>
