Changes between Version 41 and Version 42 of PyYAMLDocumentation
- Timestamp:
- 12/30/08 13:02:08 (4 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
PyYAMLDocumentation
v41 v42 88 88 89 89 90 == Python 3 support == 91 92 Starting from the '''3.08''' release, PyYAML and LibYAML bindings provide a complete support 93 for Python 3. This is a short outline of differences in PyYAML API between Python 2 94 and 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 90 118 == Tutorial == 91 119 … … 118 146 }}} 119 147 120 '''`yaml.load`''' accepts a string, a Unicode string, an open file object, or121 an open Unicode file object. Astring or a file must be encoded with '''utf-8''',148 '''`yaml.load`''' accepts a byte string, a Unicode string, an open binary file object, 149 or an open text file object. A byte string or a file must be encoded with '''utf-8''', 122 150 '''utf-16-be''' or '''utf-16-le''' encoding. '''`yaml.load`''' detects the encoding 123 151 by checking the '''BOM''' (byte order mark) sequence at the beginning of the … … 130 158 >>> yaml.load(u""" 131 159 ... hello: Привет! 132 ... """) 160 ... """) # In Python 3, do not use the 'u' prefix 133 161 134 162 {'hello': u'\u041f\u0440\u0438\u0432\u0435\u0442!'} … … 231 259 }}} 232 260 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 262 or binary file. In this case, '''`yaml.dump`''' will write the produced YAML document 263 into the file. Otherwise, '''`yaml.dump`''' returns the produced document. 236 264 237 265 {{{ … … 244 272 If you need to dump several YAML documents to a single stream, use the function 245 273 '''`yaml.dump_all`'''. '''`yaml.dump_all`''' accepts a list or a generator producing 274 246 275 Python objects to be serialized into a YAML document. The second optional argument is 247 276 an open file. … … 459 488 460 489 A 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]. 462 491 463 492 You may also check [http://yaml4r.sourceforge.net/cookbook/ the YAML cookbook]. Note … … 777 806 Plain scalars without explicitly defined tag are subject to implicit tag 778 807 resolution. The scalar value is checked against a set of regular expressions 808 779 809 and if one of them matches, the corresponding tag is assigned to the scalar. 780 810 PyYAML allows an application to add custom implicit tag resolvers. … … 786 816 to Python objects. 787 817 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) === 822 853 823 854 There are four tags that are converted to `str` and `unicode` values: … … 839 870 840 871 872 === String conversion (Python 3 only) === 873 874 In Python 3, `str` objects are converted to `!!str` scalars and `bytes` objects to `!!binary` scalars. 875 For compatibility reasons, tags `!!python/str` and `!!python/unicode` are still supported and converted 876 to `str` objects. 877 878 841 879 === Names and modules === 842 880 … … 846 884 !!python/name:yaml.dump 847 885 }}} 848 849 886 850 887 Similarly, modules are represented using the tag '''`!python/module`''': … … 894 931 895 932 933 896 934 === The yaml package === 897 935 … … 926 964 927 965 serialize(node, stream=None, Dumper=Dumper, 928 encoding='utf-8', 966 encoding='utf-8', # encoding=None (Python 3) 929 967 explicit_start=None, 930 968 explicit_end=None, … … 962 1000 default_style=None, 963 1001 default_flow_style=None, 964 encoding='utf-8', 1002 encoding='utf-8', # encoding=None (Python 3) 965 1003 explicit_start=None, 966 1004 explicit_end=None, … … 1186 1224 BlockMappingStartToken() 1187 1225 1188 1189 1226 KeyToken() 1190 1227 ScalarToken(plain=True, style=None, value=u'KeyToken') … … 1346 1383 The '''`style`''' and '''`flow_style`''' flags have the same meaning as for events. 1347 1384 The 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 values1349 are nodes.1385 a list of nodes. The value of a mapping node is a list of pairs consisting of key and 1386 value nodes. 1350 1387 1351 1388 Example: … … 1359 1396 ... """) 1360 1397 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=[1398 MappingNode(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=[ 1363 1400 ScalarNode(tag=u'tag:yaml.org,2002:str', value=u'scalar'), 1364 1401 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')]))]) 1366 1403 1367 1404 >>> print yaml.serialize(yaml.SequenceNode(tag=u'tag:yaml.org,2002:seq', value=[ … … 1646 1683 interpreted as '''{ 1 : 2 }'''.~~~ 1647 1684 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).~~
