wiki:LegacyUserDocumentation

Version 1 (modified by xi, 8 years ago) (diff)

--

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.