From: Georg Brandl <georg@python.org>
Date: Mon, 21 Jan 2008 16:34:07 +0000 (+0000)
Subject: #1555501: document plistlib and move it to the general library.
X-Git-Tag: v2.6a1~488
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=864de8274c5d2904e1df6837450408cfdb6f9e11;p=python

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

diff --git a/Doc/library/fileformats.rst b/Doc/library/fileformats.rst
index c0c2eedb6c..d2f0639a4a 100644
--- a/Doc/library/fileformats.rst
+++ b/Doc/library/fileformats.rst
@@ -16,3 +16,4 @@ that aren't markup languages or are related to e-mail.
    robotparser.rst
    netrc.rst
    xdrlib.rst
+   plistlib.rst
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"]
diff --git a/Lib/plat-mac/plistlib.py b/Lib/plistlib.py
similarity index 99%
rename from Lib/plat-mac/plistlib.py
rename to Lib/plistlib.py
index e61c4a4471..5e107b6633 100644
--- a/Lib/plat-mac/plistlib.py
+++ b/Lib/plistlib.py
@@ -1,6 +1,6 @@
 """plistlib.py -- a tool to generate and parse MacOSX .plist files.
 
-The PropertList (.plist) file format is a simple XML pickle supporting
+The PropertyList (.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.
 
diff --git a/Misc/NEWS b/Misc/NEWS
index 02bb1492ad..576895149b 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -369,6 +369,8 @@ Core and builtins
 Library
 -------
 
+- #1555501: move plistlib from plat-mac directory to general library.
+
 - #1269: fix a bug in pstats.add_callers() and add a unit test file for
   pstats.