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