PyYaml TUTORIAL
2002-08-09 Mike Orr

1.  INTRODUCTION

PyYaml is a Python implementation of YAML ("YAML Ain't Markup Language"),
a portable, text-readable object serialization format.  Its uses include:
    * Exchanging data with an unknown platform (like XML).
    * Exchanging data with a program written in another programming
language (like XML).  Currently, Perl and C modules exist.
    * Having the foreign system unpack the data into native types
(more than XML does).  Most modern languages have types corresponding to
Python's ints, floats, strings, lists, dictionaries, None and True/False.
    * Maintaining a text configuration file that can be edited by hand.
(Like the ConfigParser, rfc822 modules and Python's execfile() function
can do, but portable and in some cases more elegant.)
    * Saving a data structure in a file and reconstructing it later
(like pickle and marshal).

More information about YAML is on the YAML web site, http://yaml.org/ .

PyYaml and YAML are alpha-level software and subject to change.
In particular, PyYaml does not yet completely implement the YAML spec,
and the correct serializing/unserializing of all Python values is not
guaranteed.

2.  yaml functions

PyYaml installs via distutils into one module 'yaml'.  Actually it's
is a package but all its submodules are private.  Pretend it's a module.
This "module" contains five public functions:

load(s)  ->  iterator
	Parse string 's' and return an iterator of the YAML documents
	found.

loadFile(f)  ->  iterator
	Same but parse the file named 'f'.

dump(data, indent="    ", sort=alpha_sort)  ->  string
	Serialize the Python data structure 'data'.  Prefix 'indent'
	to every output line.  (Except the first and last lines?)

timestamp
	A class that stores a date/time.  It uses mx.DateTime if available
	but also does other stuff.

ypath(expr, target=noTarget, cntx=0)  ->  a Python type
	Does something like searching keys and subkeys from a string
	with "/" separators, like a URI?


Use the 'indent' argument to 'dump' to add extra indentation when
putting a YAML document inside another YAML document.

3.  LIMITATIONS

PyYaml converts Python builtin types bidirectionally, and converts
instances unidirectionally.  When YAMLizing an instance, PyYaml
serializes only its instance data (its '.__dict__'), with no 
meta-information about which class it came from.  So unYAMLizing the
result will not yield an instance but instead a dictionary.  You can
create an empty instance and then use 
"instance.__dict__.update(resultOfLoad)" if you like.

'dump' and 'dumpFile' choose the quoting mechanism for each item.
Perhaps there should be options to force a certain item to be quoted
a certain way -- e.g., a string that's normally multi-line but is
single line now -- but such options don't exist.

PyYaml does not handle file locking or concurrent access.  Use locks
and/or keep each document in a separate file as appropriate.

Ideas for future: pickle interface, shelve interface, locking
interface.
