diff options
Diffstat (limited to 'pyyaml/PyYAMLDocumentation.html')
| -rw-r--r-- | pyyaml/PyYAMLDocumentation.html | 1659 |
1 files changed, 0 insertions, 1659 deletions
diff --git a/pyyaml/PyYAMLDocumentation.html b/pyyaml/PyYAMLDocumentation.html deleted file mode 100644 index eaf72e3..0000000 --- a/pyyaml/PyYAMLDocumentation.html +++ /dev/null @@ -1,1659 +0,0 @@ -<!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 |