Changes between Version 41 and Version 42 of PyYAMLDocumentation


Ignore:
Timestamp:
12/30/08 13:02:08 (6 years ago)
Author:
xi
Comment:

Reflected Python 3 support

Legend:

Unmodified
Added
Removed
Modified
  • PyYAMLDocumentation

    v41 v42  
    8888 
    8989 
     90== Python 3 support == 
     91 
     92Starting from the '''3.08''' release, PyYAML and LibYAML bindings provide a complete support 
     93for Python 3.  This is a short outline of differences in PyYAML API between Python 2 
     94and Python 3 versions. 
     95 
     96''In Python 2:'' 
     97 
     98 * '''`str`''' objects are converted into '''`!!str`''', '''`!!python/str`''' 
     99   or '''`!binary`''' nodes depending on whether the object is an ASCII, UTF-8 
     100   or binary string. 
     101 * '''`unicode`''' objects are converted into '''`!!python/unicode`''' or 
     102   '''`!!str`''' nodes depending on whether the object is an ASCII string or not. 
     103 * `yaml.dump(data)` produces the document as a UTF-8 encoded '''`str`''' object. 
     104 * `yaml.dump(data, encoding=('utf-8'|'utf-16-be'|'utf-16-le'))` produces 
     105   a '''`str`''' object in the specified encoding. 
     106 * `yaml.dump(data, encoding=None)` produces a '''`unicode`''' object. 
     107 
     108''In Python 3:'' 
     109 
     110 * '''`str`''' objects are converted to '''`!!str`''' nodes. 
     111 * '''`bytes`''' objects are converted to '''`!!binary`''' nodes. 
     112 * For compatibility reasons, '''`!!python/str`''' and '''`!python/unicode`''' tags are 
     113   still supported and the corresponding nodes are converted to '''`str`''' objects. 
     114 * `yaml.dump(data)` produces the document as a '''`str`''' object. 
     115 * `yaml.dump(data, encoding=('utf-8'|'utf-16-be'|'utf-16-le'))` produces 
     116   a '''`bytes`''' object in the specified encoding. 
     117 
    90118== Tutorial == 
    91119 
     
    118146}}} 
    119147 
    120 '''`yaml.load`''' accepts a string, a Unicode string, an open file object, or 
    121 an open Unicode file object. A string or a file must be encoded with '''utf-8''', 
     148'''`yaml.load`''' accepts a byte string, a Unicode string, an open binary file object, 
     149or an open text file object. A byte string or a file must be encoded with '''utf-8''', 
    122150'''utf-16-be''' or '''utf-16-le''' encoding. '''`yaml.load`''' detects the encoding 
    123151by checking the '''BOM''' (byte order mark) sequence at the beginning of the 
     
    130158>>> yaml.load(u""" 
    131159... hello: Привет! 
    132 ... """) 
     160... """)    # In Python 3, do not use the 'u' prefix 
    133161 
    134162{'hello': u'\u041f\u0440\u0438\u0432\u0435\u0442!'} 
     
    231259}}} 
    232260 
    233 '''`yaml.dump`''' accepts the second optional argument, which must be an open file. 
    234 In this case, '''`yaml.dump`''' will write the produced YAML document into the file. 
    235 Otherwise, '''`yaml.dump`''' returns the produced document. 
     261'''`yaml.dump`''' accepts the second optional argument, which must be an open text 
     262or binary file.  In this case, '''`yaml.dump`''' will write the produced YAML document 
     263into the file.  Otherwise, '''`yaml.dump`''' returns the produced document. 
    236264 
    237265{{{ 
     
    244272If you need to dump several YAML documents to a single stream, use the function 
    245273'''`yaml.dump_all`'''. '''`yaml.dump_all`''' accepts a list or a generator producing 
     274 
    246275Python objects to be serialized into a YAML document. The second optional argument is 
    247276an open file. 
     
    459488 
    460489A good introduction to the YAML syntax is 
    461 [http://yaml.org/spec/cvs/current.html#id857168 Chapter 2 of the YAML specification]. 
     490[http://yaml.org/spec/1.1/#id857168 Chapter 2 of the YAML specification]. 
    462491 
    463492You may also check [http://yaml4r.sourceforge.net/cookbook/ the YAML cookbook]. Note 
     
    777806Plain scalars without explicitly defined tag are subject to implicit tag 
    778807resolution. The scalar value is checked against a set of regular expressions 
     808 
    779809and if one of them matches, the corresponding tag is assigned to the scalar. 
    780810PyYAML allows an application to add custom implicit tag resolvers. 
     
    786816to Python objects. 
    787817 
    788 || '''YAML tag'''                  || '''Python type'''  || 
    789 || ''Standard YAML tags''          ||                    || 
    790 || `!!null`                        || `None`             || 
    791 || `!!bool`                        || `bool`             || 
    792 || `!!int`                         || `int` or `long`    || 
    793 || `!!float`                       || `float`            || 
    794 || `!!binary`                      || `str`              || 
    795 || `!!timestamp`                   || `datetime.datetime` || 
    796 || `!!omap`, ``!!pairs``           || `list` of pairs    || 
    797 || `!!set`                         || `set`              || 
    798 || `!!str`                         || `str` or `unicode` || 
    799 || `!!seq`                         || `list`             || 
    800 || `!!map`                         || `dict`             || 
    801 || ''Python-specific tags''        ||                    || 
    802 || `!!python/none`                 || `None`             || 
    803 || `!!python/bool`                 || `bool`             || 
    804 || `!!python/str`                  || `str`              || 
    805 || `!!python/unicode`              || `unicode`          || 
    806 || `!!python/int`                  || `int`              || 
    807 || `!!python/long`                 || `long`             || 
    808 || `!!python/float`                || `float`            || 
    809 || `!!python/complex`              || `complex`          || 
    810 || `!!python/list`                 || `list`             || 
    811 || `!!python/tuple`                || `tuple`            || 
    812 || `!!python/dict`                 || `dict`             || 
    813 || ''Complex Python tags''         ||                    || 
    814 || `!!python/name:module.name`      || `module.name`       || 
    815 || `!!python/module:package.module` || `package.module`   || 
    816 || `!!python/object:module.cls`     || `module.cls` instance || 
    817 || `!!python/object/new:module.cls` || `module.cls` instance || 
    818 || `!!python/object/apply:module.f` || value of `f(...)`    || 
    819  
    820  
    821 === String conversion === 
     818|| '''YAML tag'''                   || '''Python type'''                      || 
     819|| ''Standard YAML tags''           ||                                        || 
     820|| `!!null`                         || `None`                                 || 
     821|| `!!bool`                         || `bool`                                 || 
     822|| `!!int`                          || `int` or `long` (`int` in Python 3)    || 
     823|| `!!float`                        || `float`                                || 
     824|| `!!binary`                       || `str` (`bytes` in Python 3)            || 
     825|| `!!timestamp`                    || `datetime.datetime`                    || 
     826|| `!!omap`, ``!!pairs``            || `list` of pairs                        || 
     827|| `!!set`                          || `set`                                  || 
     828|| `!!str`                          || `str` or `unicode` (`str` in Python 3) || 
     829|| `!!seq`                          || `list`                                 || 
     830|| `!!map`                          || `dict`                                 || 
     831|| ''Python-specific tags''         ||                                        || 
     832|| `!!python/none`                  || `None`                                 || 
     833|| `!!python/bool`                  || `bool`                                 || 
     834|| `!!python/bytes`                 || (`bytes` in Python 3)                  || 
     835|| `!!python/str`                   || `str` (`str` in Python 3)              || 
     836|| `!!python/unicode`               || `unicode` (`str` in Python 3)          || 
     837|| `!!python/int`                   || `int`                                  || 
     838|| `!!python/long`                  || `long` (`int` in Python 3)             || 
     839|| `!!python/float`                 || `float`                                || 
     840|| `!!python/complex`               || `complex`                              || 
     841|| `!!python/list`                  || `list`                                 || 
     842|| `!!python/tuple`                 || `tuple`                                || 
     843|| `!!python/dict`                  || `dict`                                 || 
     844|| ''Complex Python tags''          ||                                        || 
     845|| `!!python/name:module.name`      || `module.name`                          || 
     846|| `!!python/module:package.module` || `package.module`                       || 
     847|| `!!python/object:module.cls`     || `module.cls` instance                  || 
     848|| `!!python/object/new:module.cls` || `module.cls` instance                  || 
     849|| `!!python/object/apply:module.f` || value of `f(...)`                      || 
     850 
     851 
     852=== String conversion (Python 2 only) === 
    822853 
    823854There are four tags that are converted to `str` and `unicode` values: 
     
    839870 
    840871 
     872=== String conversion (Python 3 only) === 
     873 
     874In Python 3, `str` objects are converted to `!!str` scalars and `bytes` objects to `!!binary` scalars. 
     875For compatibility reasons, tags `!!python/str` and `!!python/unicode` are still supported and converted 
     876to `str` objects. 
     877 
     878 
    841879=== Names and modules === 
    842880 
     
    846884!!python/name:yaml.dump 
    847885}}} 
    848  
    849886 
    850887Similarly, modules are represented using the tag '''`!python/module`''': 
     
    894931 
    895932 
     933 
    896934=== The yaml package === 
    897935 
     
    926964 
    927965serialize(node, stream=None, Dumper=Dumper, 
    928     encoding='utf-8', 
     966    encoding='utf-8', # encoding=None (Python 3) 
    929967    explicit_start=None, 
    930968    explicit_end=None, 
     
    9621000    default_style=None, 
    9631001    default_flow_style=None, 
    964     encoding='utf-8', 
     1002    encoding='utf-8', # encoding=None (Python 3) 
    9651003    explicit_start=None, 
    9661004    explicit_end=None, 
     
    11861224BlockMappingStartToken() 
    11871225 
    1188  
    11891226KeyToken() 
    11901227ScalarToken(plain=True, style=None, value=u'KeyToken') 
     
    13461383The '''`style`''' and '''`flow_style`''' flags have the same meaning as for events. 
    13471384The value of a scalar node must be a unicode string. The value of a sequence node is 
    1348 a list of nodes. The value of a mapping node is a dictionary which keys and values 
    1349 are nodes. 
     1385a list of nodes. The value of a mapping node is a list of pairs consisting of key and 
     1386value nodes. 
    13501387 
    13511388Example: 
     
    13591396... """) 
    13601397 
    1361 MappingNode(tag=u'tag:yaml.org,2002:map', value={ 
    1362     ScalarNode(tag=u'tag:yaml.org,2002:str', value=u'kinds'): SequenceNode(tag=u'tag:yaml.org,2002:seq', value=[ 
     1398MappingNode(tag=u'tag:yaml.org,2002:map', value=[ 
     1399    (ScalarNode(tag=u'tag:yaml.org,2002:str', value=u'kinds'), SequenceNode(tag=u'tag:yaml.org,2002:seq', value=[ 
    13631400        ScalarNode(tag=u'tag:yaml.org,2002:str', value=u'scalar'), 
    13641401        ScalarNode(tag=u'tag:yaml.org,2002:str', value=u'sequence'), 
    1365         ScalarNode(tag=u'tag:yaml.org,2002:str', value=u'mapping')])}) 
     1402        ScalarNode(tag=u'tag:yaml.org,2002:str', value=u'mapping')]))]) 
    13661403 
    13671404>>> print yaml.serialize(yaml.SequenceNode(tag=u'tag:yaml.org,2002:seq', value=[ 
     
    16461683   interpreted as '''{ 1 : 2 }'''.~~~ 
    16471684 
    1648  
    1649 == Notes == 
    1650  
    1651 To do and long-term goals: 
    1652  * ~~fix recursive objects,~~ refactor Emitter, tabs, 
    1653    ~~indentation for flow collections, indentation for scalars (min=1?), 'y' is '''!!bool'''~~, 
    1654  * ~~libyaml3000 (my SoC proposal).~~