#1555501: document plistlib and move it to the general library.

1 files changed, 124 insertions, 0 deletions

diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst
new file mode 100644
index 0000000000..508f8e8d2a
--- /dev/null
+++ b/Doc/library/plistlib.rst
@@ -0,0 +1,124 @@
+:mod:`plistlib` --- Generate and parse MacOS X ``.plist`` files
+===============================================================
+
+.. module:: plistlib
+   :synopsis: Generate and parse MacOS X plist files.
+.. moduleauthor:: Jack Jansen
+.. sectionauthor:: Georg Brandl <georg@python.org>
+.. (harvested from docstrings in the original file)
+
+.. versionchanged:: 2.6
+   This module was previously only available in the Mac-specific library, it is
+   now available for all platforms.
+
+.. index::
+   pair: plist; file
+   single: property list
+
+This module provides an interface for reading and writing the "property list"
+XML files used mainly by MacOS X.
+
+The property list (``.plist``) file format is a simple XML pickle supporting
+basic object types, like dictionaries, lists, numbers and strings.  Usually the
+top level object is a dictionary.
+
+Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
+(but only with string keys), :class:`Data` or :class:`datetime.datetime`
+objects.  String values (including dictionary keys) may be unicode strings --
+they will be written out as UTF-8.
+
+The ``<data>`` plist type is supported through the :class:`Data` class.  This is
+a thin wrapper around a Python string.  Use :class:`Data` if your strings
+contain control characters.
+
+.. seealso::
+
+   `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`
+      Apple's documentation of the file format.
+
+
+This module defines the following functions:
+
+.. function:: readPlist(pathOrFile)
+
+   Read a plist file. *pathOrFile* may either be a file name or a (readable)
+   file object.  Return the unpacked root object (which usually is a
+   dictionary).
+
+   The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat`
+   -- see its documentation for possible exceptions on ill-formed XML.
+   Unknown elements will simply be ignored by the plist parser.
+
+
+.. function:: writePlist(rootObject, pathOrFile)
+
+    Write *rootObject* to a plist file. *pathOrFile* may either be a file name
+    or a (writable) file object.
+
+    A :exc:`TypeError` will be raised if the object is of an unsupported type or
+    a container that contains objects of unsupported types.
+
+
+.. function:: readPlistFromString(data)
+
+   Read a plist from a string.  Return the root object.
+
+
+.. function:: writePlistToString(rootObject)
+
+   Return *rootObject* as a plist-formatted string.
+
+
+
+.. function:: readPlistFromResource(path[, restype='plst'[, resid=0]])
+
+    Read a plist from the resource with type *restype* from the resource fork of
+    *path*.  Availability: MacOS X.
+
+
+.. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]])
+
+    Write *rootObject* as a resource with type *restype* to the resource fork of
+    *path*.  Availability: MacOS X.
+
+
+The following class is available:
+
+.. class:: Data(data)
+
+   Return a "data" wrapper object around the string *data*.  This is used in
+   functions converting from/to plists to represent the ``<data>`` type
+   available in plists.
+
+   It has one attribute, :attr:`data`, that can be used to retrieve the Python
+   string stored in it.
+
+
+Examples
+--------
+
+Generating a plist::
+
+    pl = dict(
+        aString="Doodah",
+        aList=["A", "B", 12, 32.1, [1, 2, 3]],
+        aFloat = 0.1,
+        anInt = 728,
+        aDict=dict(
+            anotherString="<hello & hi there!>",
+            aUnicodeValue=u'M\xe4ssig, Ma\xdf',
+            aTrueValue=True,
+            aFalseValue=False,
+        ),
+        someData = Data("<binary gunk>"),
+        someMoreData = Data("<lots of binary gunk>" * 10),
+        aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
+    )
+    # unicode keys are possible, but a little awkward to use:
+    pl[u'\xc5benraa'] = "That was a unicode key."
+    writePlist(pl, fileName)
+
+Parsing a plist::
+
+    pl = readPlist(pathOrFile)
+    print pl["aKey"]