Changes between Version 2 and Version 3 of PyYAMLDocumentation

Timestamp:

04/23/06 07:49:43 (7 years ago)

Author:

xi

Comment:

--

PyYAMLDocumentation

@@ -3 +3 @@
 ''work in progress''
 
+''Some RPG-ish descriptions are stolen from [http://www.thangorodrim.net/ the Angband rogue-like game].
+
 [[PageOutline]]
 
 == Basic usage ==
 
+Start with importing the '''`yaml`''' package.
+
+{{{
+#!python
+>>> import yaml
+}}}
+
 === load() ===
 
+'''Warning: It is not safe to call `yaml.load` with any data received from an untrusted source!
+`yaml.load` is as powerful as `pickle.load` and so may call any Python function.'''
+Check the '''`yaml.safe_load`''' function though.
+
+The function '''`yaml.load`''' converts a YAML document to a Python object.
+
+{{{
+#!python
+>>> yaml.load("""
+... - Hesperiidae
+... - Papilionidae
+... - Apatelodidae
+... - Epiplemidae
+... """)
+
+['Hesperiidae', 'Papilionidae', 'Apatelodidae', 'Epiplemidae']
+}}}
+
+'''`yaml.load`''' accepts a string, a Unicode string, an open file object, or
+an open Unicode file object. A string or a file must be encoded with '''utf-8''',
+'''utf-16-be''' or '''utf-16-le''' encoding. '''`yaml.load`''' detects the encoding
+by checking the '''BOM''' (byte order mark) sequence at the beginning of the
+string/file. If no '''BOM''' is present, the '''utf-8''' encoding is assumed.
+{{{
+#!python
+>>> yaml.load(u"""
+... hello: Привет!
+... """)
+
+{'hello': u'\u041f\u0440\u0438\u0432\u0435\u0442!'}
+
+>>> stream = file('document.yaml', 'r')    # 'document.yaml' contains a single YAML document.
+>>> yaml.load(stream)
+[...]    # A Python object corresponding to the document.
+}}}
+
+if a string or a file contains several documents, you may load them all with the
+'''`yaml.load_all`''' function.
+
+{{{
+#!python
+>>> documents = """
+... ---
+... 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.
+... """
+
+>>> for data in yaml.load_all(documents):
+...     print data
+
+{'description': 'A set of handgear with sparks that crackle across its knuckleguards.\n',
+'name': "The Set of Gauntlets 'Pauraegen'"}
+{'description': 'A set of gauntlets that gives off a foul, acrid odour yet remains untarnished.\n',
+'name': "The Set of Gauntlets 'Paurnen'"}
+{'description': 'A set of handgear, freezing with unnatural cold.\n',
+'name': "The Set of Gauntlets 'Paurnimmen'"}
+}}}
+
 === dump() ===
 
@@ -47 +125 @@
 ==== Resolver interface ====
 
-==== The yaml package ====
+=== YAMLObject ===
+
+=== The yaml package ===
 
 == Deviations from the specification ==