INTRODUCTIONS

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).

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.

yaml functions

PyYaml? installs via distutils into one module 'yaml'. The yaml module contains the tests 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.

LIMITATIONS

PyYaml converts Python builtin types bidirectionally, and converts instances unidirectionally (although with directives eg from_yaml and to_yaml it can do this bidirectionally). 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. (see future notes on to_yaml from_yaml)

'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.