diff options
| author | Matěj Cepl <mcepl@redhat.com> | 2012-02-16 16:24:51 +0100 |
|---|---|---|
| committer | Matěj Cepl <mcepl@redhat.com> | 2012-02-16 16:24:51 +0100 |
| commit | 7d08baca38827b59af9592e415bc4778fb8c4958 (patch) | |
| tree | f6ad4a356235367d6a741d197e04f619f65c70a2 /pyyaml/PyYAMLDocumentation.html | |
| parent | d7e73ec4c238d0eb1c5493bb90c022d683123296 (diff) | |
| download | yamlish-7d08baca38827b59af9592e415bc4778fb8c4958.tar.gz | |
Start building tests.
Diffstat (limited to 'pyyaml/PyYAMLDocumentation.html')
| -rw-r--r-- | pyyaml/PyYAMLDocumentation.html | 1659 |
1 files changed, 1659 insertions, 0 deletions
diff --git a/pyyaml/PyYAMLDocumentation.html b/pyyaml/PyYAMLDocumentation.html new file mode 100644 index 0000000..eaf72e3 --- /dev/null +++ b/pyyaml/PyYAMLDocumentation.html @@ -0,0 +1,1659 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> + <title> + PyYAMLDocumentation – PyYAML + </title> + <link rel="search" href="http://pyyaml.org/search"> + <link rel="help" href="http://pyyaml.org/wiki/TracGuide"> + <link rel="alternate" href="http://pyyaml.org/wiki/PyYAMLDocumentation?format=txt" type="text/x-trac-wiki" title="Plain Text"> + <link rel="start" href="http://pyyaml.org/wiki"> + <link rel="stylesheet" href="PyYAMLDocumentation_files/trac.css" type="text/css"><link rel="stylesheet" href="PyYAMLDocumentation_files/wiki.css" type="text/css"> + <link rel="shortcut icon" href="http://pyyaml.org/favicon.ico" type="image/x-icon"> + <link rel="icon" href="http://pyyaml.org/favicon.ico" type="image/x-icon"> + <link type="application/opensearchdescription+xml" rel="search" href="http://pyyaml.org/search/opensearch" title="Search PyYAML"> + <script type="text/javascript" src="PyYAMLDocumentation_files/jquery.js"></script><script type="text/javascript" src="PyYAMLDocumentation_files/trac.js"></script><script type="text/javascript" src="PyYAMLDocumentation_files/search.js"></script> + <!--[if lt IE 7]> + <script type="text/javascript" src="/chrome/common/js/ie_pre7_hacks.js"></script> + <![endif]--> + <script type="text/javascript"> + jQuery(document).ready(function($) { + $("#content").find("h1,h2,h3,h4,h5,h6").addAnchor("Link to this section"); + }); + </script> + </head> + <body> + <div id="banner"> + <div id="header"> + <a id="logo" href="http://pyyaml.org/"><img src="PyYAMLDocumentation_files/pyyaml.png" alt="PyYAML" height="73" width="236"></a> + </div> + <form id="search" action="/search" method="get"> + <div> + <label for="proj-search">Search:</label> + <input id="proj-search" name="q" size="18" type="text"> + <input value="Search" type="submit"> + </div> + </form> + <div id="metanav" class="nav"> + <ul> + <li class="first"><a href="http://pyyaml.org/login">Login</a></li><li><a href="http://pyyaml.org/wiki/TracGuide">Help/Guide</a></li><li><a href="http://pyyaml.org/about">About Trac</a></li><li class="last"><a href="http://pyyaml.org/prefs">Preferences</a></li> + </ul> + </div> + </div> + <div id="mainnav" class="nav"> + <ul> + <li class="first active"><a href="http://pyyaml.org/wiki">Wiki</a></li><li><a href="http://pyyaml.org/timeline">Timeline</a></li><li><a href="http://pyyaml.org/roadmap">Roadmap</a></li><li><a href="http://pyyaml.org/browser">Browse Source</a></li><li><a href="http://pyyaml.org/report">View Tickets</a></li><li><a href="http://pyyaml.org/newticket">New Ticket</a></li><li class="last"><a href="http://pyyaml.org/search">Search</a></li> + </ul> + </div> + <div id="main"> + <div id="ctxtnav" class="nav"> + <h2>Context Navigation</h2> + <ul> + <li class="first"><a href="http://pyyaml.org/wiki/WikiStart">Start Page</a></li><li><a href="http://pyyaml.org/wiki/TitleIndex">Index</a></li><li><a href="http://pyyaml.org/wiki/PyYAMLDocumentation?action=history">History</a></li><li class="last"><a href="http://pyyaml.org/wiki/PyYAMLDocumentation?action=diff&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>
\ No newline at end of file |