Changes between Version 20 and Version 21 of PyYAMLDocumentation

Timestamp:

05/07/06 05:21:37 (7 years ago)

Author:

xi

Comment:

--

PyYAMLDocumentation

@@ -1335 +1335 @@
 == Deviations from the specification ==
 
-
-== Download and installing ==
-
-Check it out from the SVN repository http://svn.pyyaml.org/pyyaml/trunk.
-
-Install it by running
-{{{
-$ python setup.py install
-}}}
-
-
-== High-level API ==
-
-'''Warning: API is not stable and may change in the future'''
-
-=== Basic examples ===
-
-Start with importing the package:
-{{{
-#!python
->>> import yaml
-}}}
-
-Define the input data:
-{{{
-#!python
->>> data = """
-... - YAML
-... - is
-... - fun!
-... """
-}}}
-The parser accepts string objects, unicode objects, open file objects, and unicode file objects.
-
-Now convert it to a native Python object:
-{{{
->>> yaml.load(data)
-['YAML', 'is', 'fun!']
-}}}
-
-Conversely, you may convert a Python object into a YAML document:
-{{{
->>> print yaml.dump(['YAML', 'is', 'fun!'])
-- YAML
-- is
-- fun!
-}}}
-
-PyYAML 3000 supports many of the types defined in the YAML tags repository:
-{{{
->>> data = """
-... - ~
-... - true
-... - 3_141_592.653e-6
-... - 3000
-... - PyYAML3000 birthday: 2006-02-11
-... - primes (sort of): !!set { 2, 3, 5, 7, 11, 13 }
-... - pairs: !!pairs [1: 2, 3: 4, 5: 6]
-... """
->>> for x in yaml.load(data): print x
-None
-True
-3.141592653
-3000
-{'PyYAML3000 birthday': datetime.datetime(2006, 2, 11, 0, 0)}
-{'primes (sort of)': set([2, 3, 5, 7, 11, 13])}
-{'pairs': [(1, 2), (3, 4), (5, 6)]}
->>> print yaml.dump([None, True, False, 123, 123.456, 'a string',
-... {'a': 'dictionary'}, ['a', 'list']])
-- null
-- true
-- false
-- 123
-- 123.456
-- a string
-- a: dictionary
-- - a
-  - list
-}}}
-
-The following tags are supported: '''!!map''', '''!!omap''', '''!!pairs''',
-'''!!set''', '''!!seq''', '''!!binary''', '''!!bool''', '''!!float''',
-'''!!int''', '''!!merge''', '''!!null''', '''!!str''', '''!!timestamp''',
-'''!!value'''.
-
-=== Defining custom tags ===
-
-You may define constructors for your own application-specific tags. You may use
-either the function '''yaml.add_constructor''' or subclass from '''yaml.YAMLObject'''.
-
-Instances of '''yaml.YAMLObject''' are automatically serialized to YAML and vice versa.
-You only need to define the YAML tag with the '''yaml_tag''' variable.
-{{{
-#!python
-class Person(yaml.YAMLObject):
-    yaml_tag = '!Person'
-    def __init__(self, first_name=None, last_name=None, email=None, birthday=None):
-        self.first_name = first_name
-        self.last_name = last_name
-        self.email = email
-        self.birthday = birthday
-    def __repr__(self):
-        return "%s(first_name=%r, last_name=%r, email=%r, birthday=%r)"  \
-                % (self.__class__.__name__, self.first_name, self.last_name,
-                        self.email, self.birthday)
-}}}
-
-{{{
-#!python
->>> p = yaml.load("""
-... !Person
-... first_name: Kirill
-... last_name: Simonov
-... email: xi(at)resolvent.net
-... birthday: null
-... """)
->>> print p
-Person(first_name='Kirill', last_name='Simonov', email='xi(at)resolvent.net', birthday=None)
->>> print yaml.dump(p)
-!Person
-last_name: Simonov
-first_name: Kirill
-email: xi(at)resolvent.net
-birthday: null
-}}}
-
-If you don't want to use metaclass magic, you may define the constructor
-and representer as functions and register them:
-{{{
-#!python
-def construct_person(constructor, node):
-    # ...
-def represent_person(representer, person):
-    # ...
-yaml.add_constructor('!Person', construct_person)
-yaml.add_representer(Person, represent_person)
-}}}
-
-=== Parsing and emitting multiple documents in a stream ===
-
-If an input stream contains several documents, you may load all of them using the '''yaml.load_all''' function.
-{{{
-#!python
->>> data = """
-... This is the first document
-... --- # This is an empty document
-... ---
-... - this
-... - is: the
-...   last: document
-... """
->>> for document in yaml.load_all(data): print document
-This is the first document
-None
-['this', {'is': 'the', 'last': 'document'}]
-}}}
-
-You may also dump several documents into the same stream using the '''yaml.dump_all''' function.
-{{{
-#!python
->>> print yaml.dump_all(["The first document", None, ["The", "last", "document"]])
-The first document
---- null
----
-- The
-- last
-- document
-}}}
-
-There are more features, check the source to find out.
-
-
-== Low-level API ==
-
-PyYAML 3000 provides low-level event-based and easy-to-use parser and emitter API.
-
-Example:
-{{{
-#!python
->>> data = """
-... --- !tag
-... scalar
-... ---
-... - &anchor item
-... - another item
-... - *anchor
-... ---
-... key: value
-... ? - complex
-...   - key
-... : - complex
-...   - value
-... """
->>> for event in yaml.parse(data): print event
-StreamStartEvent()
-DocumentStartEvent()
-ScalarEvent(anchor=None, tag=u'!tag', implicit=(False, False), value=u'scalar')
-DocumentEndEvent()
-DocumentStartEvent()
-SequenceStartEvent(anchor=None, tag=None, implicit=True)
-ScalarEvent(anchor=u'anchor', tag=None, implicit=(True, False), value=u'item')
-ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'another item')
-AliasEvent(anchor=u'anchor')
-SequenceEndEvent()
-DocumentEndEvent()
-DocumentStartEvent()
-MappingStartEvent(anchor=None, tag=None, implicit=True)
-ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'key')
-ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'value')
-SequenceStartEvent(anchor=None, tag=None, implicit=True)
-ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'complex')
-ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'key')
-SequenceEndEvent()
-SequenceStartEvent(anchor=None, tag=None, implicit=True)
-ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'complex')
-ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'value')
-SequenceEndEvent()
-MappingEndEvent()
-DocumentEndEvent()
-StreamEndEvent()
->>> events = [
-... yaml.StreamStartEvent(encoding='utf-8'),
-... yaml.DocumentStartEvent(explicit=True),
-... yaml.MappingStartEvent(anchor=None, tag=None, implicit=True),
-... yaml.ScalarEvent(anchor=None, tag=None, value=u'flow sequence', implicit=(True, True)),
-... yaml.SequenceStartEvent(anchor=None, tag=None, flow_style=True, implicit=True),
-... yaml.ScalarEvent(anchor=None, tag=None, value=u'123', implicit=(True, False)),
-... yaml.ScalarEvent(anchor=None, tag=None, value=u'456', implicit=(True, False)),
-... yaml.SequenceEndEvent(),
-... yaml.ScalarEvent(anchor=None, tag=None, value=u'block scalar', implicit=(True, True)),
-... yaml.ScalarEvent(anchor=None, tag=None, value=u'YAML\nis\nfun!\n', style='|', implicit=(True, True)),
-... yaml.MappingEndEvent(),
-... yaml.DocumentEndEvent(explicit=True),
-... yaml.StreamEndEvent(),
-... ]
-
->>> print yaml.emit(events)
----
-flow sequence: [123, 456]
-block scalar: |
-  YAML
-  is
-  fun!
-...
-}}}
-
-
-== To Do ==
-
-Long-term goals:
- * fix tabs, i~~ndentation for flow collections, indentation for scalars (min=1?), 'y' is '''!!bool'''~~,
- * libyaml3000
-
-== Deviations from the specification ==
+''need to update this section''
 
  * rules for tabs in YAML are confusing. We are close, but not there yet.
@@ -1610 +1357 @@
    interpreted as '''{ 1 : 2 }'''.
 
+
 == Notes ==
 
- * SpecBugs
+Long-term goals:
+ * fix tabs, ~~indentation for flow collections, indentation for scalars (min=1?), 'y' is '''!!bool'''~~,
+ * libyaml3000 (my SoC proposal).
+
+SpecBugs