Changes between Version 5 and Version 6 of PyYAML


Ignore:
Timestamp:
04/20/06 11:20:19 (7 years ago)
Author:
xi
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • PyYAML

    v5 v6  
    1 = PyYAML 3000 = 
     1= PyYAML = 
    22 
    3 PyYAML 3000 is the next generation YAML parser for Python. 
     3'''PyYAML is a YAML parser and emitter for Python.''' 
    44 
    5 If you have any questions, please post them to the 
    6 [http://lists.sourceforge.net/lists/listinfo/yaml-core YAML-core mailing list]. 
    75 
    8 If you find any bugs, you may post them to the list or open a ticket in  
    9 the [http://pyyaml.org/newticket BTS]. 
     6== Overview == 
    107 
    11 == Download and installing == 
     8[http://yaml.org/ YAML] is a data serialization format designed for human 
     9readability and interaction with scripting languages. 
    1210 
    13 Check it out from the SVN repository http://svn.pyyaml.org/pyyaml/trunk. 
     11[http://pyyaml.org/wiki/PyYAML PyYAML] is a YAML parser and emitter for 
     12the Python programming language. 
     13 
     14PyYAML features 
     15 
     16 * a '''complete''' [http://yaml.org/spec/cvs/current.html YAML 1.1] parser. 
     17   In particular, PyYAML can parse all examples from the specification. 
     18   The parsing algorithm is simple enough to be ported to C or other language. 
     19 * Unicode support including UTF-8/UTF-16 input and '''\u''' escape sequences. 
     20 * event-based parser and emitter API (like SAX). 
     21 * high-level API for serializing and deserializing native Python objects (like DOM or pickle). 
     22 * support for all types from the [http://yaml.org/type/index.html YAML types repository]. 
     23   A simple extension API is provided. 
     24 * relatively meaningful error messages. 
     25 
     26Note that PyYAML is still young and may have some bugs. Furthermore, 
     27PyYAML is written in Python and is slow comparing to C based parsers. 
     28 
     29 
     30== Requirements == 
     31 
     32PyYAML requires Python 2.3 or higher. 
     33 
     34 
     35== Download and Installation == 
     36 
     37You may check out PyYAML code from the Subversion repository 
     38http://svn.pyyaml.org/pyyaml/trunk 
     39 
     40{{{ 
     41$ svn checkout http://svn.pyyaml.org/pyyaml/trunk pyyaml-trunk 
     42}}} 
    1443 
    1544Install it by running 
    … …  
    1847}}} 
    1948 
    20 == Features == 
    2149 
    22  * PyYAML3000 is a '''complete''' [http://yaml.org/spec/cvs/current.html YAML 1.1] parser. 
    23    In particular, PyYAML3000 can parse all examples from the specification. 
    24    The parsing algorithm is simple enough to be a reference for implementing YAML parsers 
    25    in C or other languages. 
    26  * PyYAML3000 supports Unicode including UTF-8/UTF-16 input and '''\u''' escape sequences. 
    27  * PyYAML3000 provides both a low-level event-based interface to the parser (think SAX) 
    28    and high-level API for generating native Python objects (think DOM). 
    29  * PyYAML3000 supports almost all types from the [http://yaml.org/type/index.html YAML types repository] 
    30    and has a simple API to extend it with application-specific tags. 
    31  * PyYAML3000 produces relatively meaningful error messages. 
     50== Documentation == 
    3251 
    33 Note that PyYAML3000 is still young and may have some bugs. In particular, 
    34 there are two major drawbacks: 
    35  * ~~There in no '''YAML emitter''' yet.~~ 
    36  * PyYAML3000 is written in Python and is slow comparing to C based parsers. 
    37  
    38 == High-level API == 
    39  
    40 '''Warning: API is not stable and may change in the future''' 
    41  
    42 === Basic examples === 
    43  
    44 Start with importing the package: 
     52''Quick example:'' 
    4553{{{ 
    4654#!python 
    47 >>> import yaml 
     55>>> from yaml import * 
     56>>> print load(""" 
     57... - foo 
     58... - bar 
     59... - baz 
     60... """) 
     61['foo', 'bar', 'baz'] 
     62>>> print dump(['foo', 'bar', 'baz']) 
     63- foo 
     64- bar 
     65- baz 
    4866}}} 
    4967 
    50 Define the input data: 
    51 {{{ 
    52 #!python 
    53 >>> data = """ 
    54 ... - YAML 
    55 ... - is 
    56 ... - fun! 
    57 ... """ 
    58 }}} 
    59 The parser accepts string objects, unicode objects, open file objects, and unicode file objects. 
     68For more details, please check [wiki:PyYAMLDocumentation PyYAML Documentation]. 
    6069 
    61 Now convert it to a native Python object: 
    62 {{{ 
    63 >>> yaml.load(data) 
    64 ['YAML', 'is', 'fun!'] 
    65 }}} 
    6670 
    67 Conversely, you may convert a Python object into a YAML document: 
    68 {{{ 
    69 >>> print yaml.dump(['YAML', 'is', 'fun!']) 
    70 - YAML 
    71 - is 
    72 - fun! 
    73 }}} 
     71== Development and bug reports == 
    7472 
    75 PyYAML 3000 supports many of the types defined in the YAML tags repository: 
    76 {{{ 
    77 >>> data = """ 
    78 ... - ~ 
    79 ... - true 
    80 ... - 3_141_592.653e-6 
    81 ... - 3000 
    82 ... - PyYAML3000 birthday: 2006-02-11 
    83 ... - primes (sort of): !!set { 2, 3, 5, 7, 11, 13 } 
    84 ... - pairs: !!pairs [1: 2, 3: 4, 5: 6] 
    85 ... """ 
    86 >>> for x in yaml.load(data): print x 
    87 None 
    88 True 
    89 3.141592653 
    90 3000 
    91 {'PyYAML3000 birthday': datetime.datetime(2006, 2, 11, 0, 0)} 
    92 {'primes (sort of)': set([2, 3, 5, 7, 11, 13])} 
    93 {'pairs': [(1, 2), (3, 4), (5, 6)]} 
    94 >>> print yaml.dump([None, True, False, 123, 123.456, 'a string', 
    95 ... {'a': 'dictionary'}, ['a', 'list']]) 
    96 - null 
    97 - true 
    98 - false 
    99 - 123 
    100 - 123.456 
    101 - a string 
    102 - a: dictionary 
    103 - - a 
    104   - list 
    105 }}} 
     73You may check out the PyYAML source code from 
     74[http://svn.pyyaml.org/pyyaml PyYAML SVN repository]. 
    10675 
    107 The following tags are supported: '''!!map''', '''!!omap''', '''!!pairs''', 
    108 '''!!set''', '''!!seq''', '''!!binary''', '''!!bool''', '''!!float''', 
    109 '''!!int''', '''!!merge''', '''!!null''', '''!!str''', '''!!timestamp''', 
    110 '''!!value'''. 
     76If you find a bug in PyYAML, please 
     77[http://pyyaml.org/newticket?component=pyyaml file a bug report]. 
     78You may review open bugs through 
     79[http://pyyaml.org/query?action=view&component=pyyaml&order=priority the list of open tickets]. 
    11180 
    112 === Defining custom tags === 
     81You may discuss PyYAML at 
     82[http://lists.sourceforge.net/lists/listinfo/yaml-core the YAML-core mailing list]. 
    11383 
    114 You may define constructors for your own application-specific tags. You may use 
    115 either the function '''yaml.add_constructor''' or subclass from '''yaml.YAMLObject'''. 
    11684 
    117 Instances of '''yaml.YAMLObject''' are automatically serialized to YAML and vice versa. 
    118 You only need to define the YAML tag with the '''yaml_tag''' variable. 
    119 {{{ 
    120 #!python 
    121 class Person(yaml.YAMLObject): 
    122     yaml_tag = '!Person' 
    123     def __init__(self, first_name=None, last_name=None, email=None, birthday=None): 
    124         self.first_name = first_name 
    125         self.last_name = last_name 
    126         self.email = email 
    127         self.birthday = birthday 
    128     def __repr__(self): 
    129         return "%s(first_name=%r, last_name=%r, email=%r, birthday=%r)"  \ 
    130                 % (self.__class__.__name__, self.first_name, self.last_name, 
    131                         self.email, self.birthday) 
    132 }}} 
     85== Author and copyright == 
    13386 
    134 {{{ 
    135 #!python 
    136 >>> p = yaml.load(""" 
    137 ... !Person 
    138 ... first_name: Kirill 
    139 ... last_name: Simonov 
    140 ... email: xi(at)resolvent.net 
    141 ... birthday: none 
    142 ... """) 
    143 >>> print p 
    144 Person(first_name='Kirill', last_name='Simonov', email='xi(at)resolvent.net', birthday='none') 
    145 >>> print yaml.dump(p) 
    146 !Person 
    147 last_name: Simonov 
    148 first_name: Kirill 
    149 email: xi(at)resolvent.net 
    150 birthday: none 
    151 }}} 
     87The PyYAML module is written by [mailto:xi@resolvent.net Kirill Simonov]. 
    15288 
    153 If you don't want to use metaclass magic, you may define the constructor 
    154 and representer as functions and register them: 
    155 {{{ 
    156 #!python 
    157 def construct_person(constructor, node): 
    158     # ... 
    159 def represent_person(representer, person): 
    160     # ... 
    161 yaml.add_constructor('!Person', construct_person) 
    162 yaml.add_representer(Person, represent_person) 
    163 }}} 
    164  
    165 === Parsing and emitting multiple documents in a stream === 
    166  
    167 If an input stream contains several documents, you may load all of them using the '''yaml.load_all''' function. 
    168 {{{ 
    169 #!python 
    170 >>> data = """ 
    171 ... This is the first document 
    172 ... --- # This is an empty document 
    173 ... --- 
    174 ... - this 
    175 ... - is: the 
    176 ...   last: document 
    177 ... """ 
    178 >>> for document in yaml.load_all(data): print document 
    179 This is the first document 
    180 None 
    181 ['this', {'is': 'the', 'last': 'document'}] 
    182 }}} 
    183  
    184 You may also dump several documents into the same stream using the '''yaml.dump_all''' function. 
    185 {{{ 
    186 #!python 
    187 >>> print yaml.dump_all(["The first document", None, ["The", "last", "document"]]) 
    188 The first document 
    189 --- null 
    190 --- 
    191 - The 
    192 - last 
    193 - document 
    194 }}} 
    195  
    196 There are more features, check the source to find out. 
    197  
    198 == Low-level API == 
    199  
    200 PyYAML 3000 provides low-level event-based and easy-to-use parser and emitter API. 
    201  
    202 Example: 
    203 {{{ 
    204 #!python 
    205 >>> data = """ 
    206 ... --- !tag 
    207 ... scalar 
    208 ... --- 
    209 ... - &anchor item 
    210 ... - another item 
    211 ... - *anchor 
    212 ... --- 
    213 ... key: value 
    214 ... ? - complex 
    215 ...   - key 
    216 ... : - complex 
    217 ...   - value 
    218 ... """ 
    219 >>> for event in yaml.parse(data): print event 
    220 StreamStartEvent() 
    221 DocumentStartEvent() 
    222 ScalarEvent(anchor=None, tag=u'!tag', implicit=(False, False), value=u'scalar') 
    223 DocumentEndEvent() 
    224 DocumentStartEvent() 
    225 SequenceStartEvent(anchor=None, tag=None, implicit=True) 
    226 ScalarEvent(anchor=u'anchor', tag=None, implicit=(True, False), value=u'item') 
    227 ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'another item') 
    228 AliasEvent(anchor=u'anchor') 
    229 SequenceEndEvent() 
    230 DocumentEndEvent() 
    231 DocumentStartEvent() 
    232 MappingStartEvent(anchor=None, tag=None, implicit=True) 
    233 ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'key') 
    234 ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'value') 
    235 SequenceStartEvent(anchor=None, tag=None, implicit=True) 
    236 ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'complex') 
    237 ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'key') 
    238 SequenceEndEvent() 
    239 SequenceStartEvent(anchor=None, tag=None, implicit=True) 
    240 ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'complex') 
    241 ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'value') 
    242 SequenceEndEvent() 
    243 MappingEndEvent() 
    244 DocumentEndEvent() 
    245 StreamEndEvent() 
    246 >>> events = [ 
    247 ... yaml.StreamStartEvent(encoding='utf-8'), 
    248 ... yaml.DocumentStartEvent(explicit=True), 
    249 ... yaml.MappingStartEvent(anchor=None, tag=None, implicit=True), 
    250 ... yaml.ScalarEvent(anchor=None, tag=None, value=u'flow sequence', implicit=(True, True)), 
    251 ... yaml.SequenceStartEvent(anchor=None, tag=None, flow_style=True, implicit=True), 
    252 ... yaml.ScalarEvent(anchor=None, tag=None, value=u'123', implicit=(True, False)), 
    253 ... yaml.ScalarEvent(anchor=None, tag=None, value=u'456', implicit=(True, False)), 
    254 ... yaml.SequenceEndEvent(), 
    255 ... yaml.ScalarEvent(anchor=None, tag=None, value=u'block scalar', implicit=(True, True)), 
    256 ... yaml.ScalarEvent(anchor=None, tag=None, value=u'YAML\nis\nfun!\n', style='|', implicit=(True, True)), 
    257 ... yaml.MappingEndEvent(), 
    258 ... yaml.DocumentEndEvent(explicit=True), 
    259 ... yaml.StreamEndEvent(), 
    260 ... ] 
    261  
    262 >>> print yaml.emit(events) 
    263 --- 
    264 flow sequence: [123, 456] 
    265 block scalar: | 
    266   YAML 
    267   is 
    268   fun! 
    269 ... 
    270 }}} 
    271  
    272 == To Do == 
    273  
    274 For the initial release we need ~~website~~ and documentation. 
    275  
    276 Long-term goals: 
    277  * fix tabs, i~~ndentation for flow collections, indentation for scalars (min=1?), 'y' is '''!!bool'''~~, 
    278  * ~~emitter~~ 
    279  * libyaml3000 
    280  
    281 == Deviations from the specification == 
    282  
    283  * rules for tabs in YAML are confusing. We are close, but not there yet. 
    284    Perhaps both the spec and the parser should be fixed. Anyway, the best 
    285    rule for tabs in YAML is to not use them at all. 
    286  * Byte order mark. The initial BOM is stripped, but BOMs inside the stream 
    287    are considered as parts of the content. It can be fixed, but it's not 
    288    really important now. 
    289  * ~~Empty plain scalars are not allowed if alias or tag is specified.~~ This 
    290    is done to prevent anomalities like '''[ !tag, value]''', which can be 
    291    interpreted both as '''[ !<!tag,> value ]''' and '''[ !<!tag> "", "value" ]'''. 
    292    The spec should be fixed. 
    293  * Indentation of flow collections. The spec requires them to be indented 
    294    more then their block parent node. Unfortunately this rule many intuitively 
    295    correct constructs invalid, for instance, 
    296 {{{ 
    297 block: { 
    298 } # this is indentation violation according to the spec. 
    299 }}} 
    300  * ':' is not allowed for plain scalars in the flow mode. '''{1:2}''' is 
    301    interpreted as '''{ 1 : 2 }'''. 
    302  
    303 == Notes == 
    304  
    305  * SpecBugs 
     89PyYAML is released under the MIT license.