summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2008-01-21 16:34:07 (GMT)
committerGeorg Brandl <georg@python.org>2008-01-21 16:34:07 (GMT)
commit864de8274c5d2904e1df6837450408cfdb6f9e11 (patch)
tree27e98a38dbcf825323315947b196542d2ba0a464
parent960b186eafd75954507369eed443896465b0b010 (diff)
downloadcpython-864de8274c5d2904e1df6837450408cfdb6f9e11.zip
cpython-864de8274c5d2904e1df6837450408cfdb6f9e11.tar.gz
cpython-864de8274c5d2904e1df6837450408cfdb6f9e11.tar.bz2
#1555501: document plistlib and move it to the general library.
-rw-r--r--Doc/library/fileformats.rst1
-rw-r--r--Doc/library/plistlib.rst124
-rw-r--r--Lib/plistlib.py (renamed from Lib/plat-mac/plistlib.py)2
-rw-r--r--Misc/NEWS2
4 files changed, 128 insertions, 1 deletions
diff --git a/Doc/library/fileformats.rst b/Doc/library/fileformats.rst
index c0c2eed..d2f0639 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 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"]
diff --git a/Lib/plat-mac/plistlib.py b/Lib/plistlib.py
index e61c4a4..5e107b6 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 02bb149..5768951 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.