Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r60151 | christian.heimes | 2008-01-21 14:11:15 +0100 (Mon, 21 Jan 2008) | 1 line

  A bunch of header files were not listed as dependencies for object files. Changes to files like Parser/parser.h weren't picked up by make.
........
  r60152 | georg.brandl | 2008-01-21 15:16:46 +0100 (Mon, 21 Jan 2008) | 3 lines

  #1087741: make mmap.mmap the type of mmap objects, not a
  factory function. Allow it to be subclassed.
........
  r60153 | georg.brandl | 2008-01-21 15:18:14 +0100 (Mon, 21 Jan 2008) | 2 lines

  mmap is an extension module.
........
  r60154 | georg.brandl | 2008-01-21 17:28:13 +0100 (Mon, 21 Jan 2008) | 2 lines

  Fix example.
........
  r60155 | georg.brandl | 2008-01-21 17:34:07 +0100 (Mon, 21 Jan 2008) | 2 lines

  #1555501: document plistlib and move it to the general library.
........
  r60156 | georg.brandl | 2008-01-21 17:36:00 +0100 (Mon, 21 Jan 2008) | 2 lines

  Add a stub for bundlebuilder documentation.
........
  r60157 | georg.brandl | 2008-01-21 17:46:58 +0100 (Mon, 21 Jan 2008) | 2 lines

  Removing bundlebuilder docs again -- it's not to be used anymore (see #779825).
........
  r60158 | georg.brandl | 2008-01-21 17:51:51 +0100 (Mon, 21 Jan 2008) | 2 lines

  #997912: acknowledge nested scopes in tutorial.
........
  r60159 | vinay.sajip | 2008-01-21 18:02:26 +0100 (Mon, 21 Jan 2008) | 1 line

  Fix: #1836: Off-by-one bug in TimedRotatingFileHandler rollover calculation. Patch thanks to Kathryn M. Kowalski.
........
  r60161 | georg.brandl | 2008-01-21 18:13:03 +0100 (Mon, 21 Jan 2008) | 2 lines

  Adapt pydoc to new doc URLs.
........
  r60162 | georg.brandl | 2008-01-21 18:17:00 +0100 (Mon, 21 Jan 2008) | 2 lines

  Fix old link.
........
  r60163 | georg.brandl | 2008-01-21 18:22:06 +0100 (Mon, 21 Jan 2008) | 2 lines

  #1726198: replace while 1: fp.readline() with file iteration.
........
  r60164 | georg.brandl | 2008-01-21 18:29:23 +0100 (Mon, 21 Jan 2008) | 2 lines

  Clarify $ behavior in re docstring. #1631394.
........
  r60165 | vinay.sajip | 2008-01-21 18:39:22 +0100 (Mon, 21 Jan 2008) | 1 line

  Minor documentation change - hyperlink tidied up.
........
  r60166 | georg.brandl | 2008-01-21 18:42:40 +0100 (Mon, 21 Jan 2008) | 2 lines

  #1530959: change distutils build dir for --with-pydebug python builds.
........
  r60167 | vinay.sajip | 2008-01-21 19:16:05 +0100 (Mon, 21 Jan 2008) | 1 line

  Updated to include news on recent logging fixes and documentation changes.
........
  r60168 | georg.brandl | 2008-01-21 19:35:49 +0100 (Mon, 21 Jan 2008) | 3 lines

  Issue #1882: when compiling code from a string, encoding cookies in the
  second line of code were not always recognized correctly.
........
  r60170 | georg.brandl | 2008-01-21 19:36:51 +0100 (Mon, 21 Jan 2008) | 2 lines

  Add NEWS entry for #1882.
........
  r60172 | georg.brandl | 2008-01-21 19:41:24 +0100 (Mon, 21 Jan 2008) | 2 lines

  Use original location of document, which has translations.
........
  r60173 | walter.doerwald | 2008-01-21 21:18:04 +0100 (Mon, 21 Jan 2008) | 2 lines

  Follow PEP 8 in module docstring.
........
  r60175 | georg.brandl | 2008-01-21 21:20:53 +0100 (Mon, 21 Jan 2008) | 2 lines

  Adapt to latest doctools refactoring.
........

1 files changed, 124 insertions, 0 deletions

diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst
new file mode 100644
index 0000000..508f8e8
--- /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"]