source: trunk/lib/syck/__init__.py @ 25

Revision 25, 2.7 KB checked in by xi, 9 years ago (diff)

Adding some docstrings.

Line 
1"""
2YAML is a data serialization format designed for human readability and
3interaction with scripting languages.
4
5Syck is an extension for reading and writing YAML in scripting languages.
6
7PySyck provides Python bindings for Syck YAML parser and emitter.
8
9To start working with PySyck, import the package 'syck':
10>>> from syck import *
11
12To parse a YAML document into a Python object, use the function 'load()':
13>>> load('''
14... - Mark McGwire
15... - Sammy Sosa
16... - Ken Griffey
17... ''')
18['Mark McGwire', 'Sammy Sosa', 'Ken Griffey']
19
20To emit a Python object into a YAML document, use the function 'dump()':
21>>> print dump(['Mark McGwire', 'Sammy Sosa', 'Ken Griffey'])
22---
23- Mark McGwire
24- Sammy Sosa
25- Ken Griffey
26
27You may get access to the YAML parser tree using the function 'parse()':
28>>> root_node = parse('''
29... - Mark McGwire
30... - Sammy Sosa
31... - Ken Griffey
32... ''')
33>>> root_node
34<_syck.Seq object at 0xb7a1f874>
35>>> root_node.kind
36'seq'
37>>> root_node.value
38[<_syck.Scalar object at 0xb7a1e5fc>, <_syck.Scalar object at 0xb7a1e65c>, <_syck.Scalar object at 0xb7a1e6bc>]
39
40You may now use the function 'emit()' to obtain the YAML document again:
41>>> print emit(root_node)
42---
43- Mark McGwire
44- Sammy Sosa
45- Ken Griffey
46
47What do you get if you apply the function 'dump()' to root_node? Let's try it:
48>>> print dump(root_node)
49--- !python/object:_syck.Seq
50value:
51- !python/object:_syck.Scalar
52  value: Mark McGwire
53  tag: tag:yaml.org,2002:str
54- !python/object:_syck.Scalar
55  value: Sammy Sosa
56  tag: tag:yaml.org,2002:str
57- !python/object:_syck.Scalar
58  value: Ken Griffey
59  tag: tag:yaml.org,2002:str
60
61As you can see, PySyck allow you to represent complex Python objects.
62
63You can also dump the generated YAML output into any file-like object:
64>>> import os
65>>> stream = os.tmpfile()
66>>> object = ['foo', 'bar', ['baz']]
67>>> dump(object, stream)
68>>> stream.seek(0)
69>>> print stream.read()
70---
71- foo
72- bar
73- - baz
74
75To load several documents from a single YAML stream, use the function
76'load_documents()':
77>>> source = '''
78... ---
79... american:
80...   - Boston Red Sox
81...   - Detroit Tigers
82...   - New York Yankees
83... national:
84...   - New York Mets
85...   - Chicago Cubs
86...   - Atlanta Braves
87... ---
88... - [name        , hr, avg  ]
89... - [Mark McGwire, 65, 0.278]
90... - [Sammy Sosa  , 63, 0.288]
91... '''
92>>> for document in load_documents(source):
93...     print document
94...
95{'national': ['New York Mets', 'Chicago Cubs', 'Atlanta Braves'], 'american': ['Boston Red Sox', 'Detroit Tigers', 'New York Yankees']}
96[['name', 'hr', 'avg'], ['Mark McGwire', 65, 0.27800000000000002], ['Sammy Sosa', 63, 0.28799999999999998]]
97
98See the source code for more details.
99"""
100
101
102from _syck import *
103from loaders import *
104from dumpers import *
105
Note: See TracBrowser for help on using the repository browser.