= User Documentation for the old PyYAML code =

For the moment, this is a copy of the USAGE written by Mike Orr from his extention work on 0.32

'''!PyYaml TUTORIAL''' 2002-08-09 Mike Orr

== INTRODUCTIONS ==

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

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

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