From: R David Murray <rdmurray@bitdance.com>
Date: Sun, 9 Mar 2014 19:09:04 +0000 (-0400)
Subject: whatsnew: plistlib new api and deprecations (#14455)
X-Git-Tag: v3.4.1rc1~233^2~105
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1d342b2e8b4a74e823bec4cd5653da63f545955f;p=thirdparty%2FPython%2Fcpython.git

whatsnew: plistlib new api and deprecations (#14455)

Also fixed the versionchanged/deprecation tags in the docs.
---

diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst
index 7301d49510bc..6a2d6b4971c0 100644
--- a/Doc/library/plistlib.rst
+++ b/Doc/library/plistlib.rst
@@ -32,6 +32,9 @@ Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
 (but only with string keys), :class:`Data`, :class:`bytes`, :class:`bytesarray`
 or :class:`datetime.datetime` objects.
 
+.. versionchanged:: 3.4
+   New API, old API deprecated.  Support for binary format plists added.
+
 .. seealso::
 
    `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
@@ -107,7 +110,7 @@ This module defines the following functions:
    An :exc:`OverflowError` will be raised for integer values that cannot
    be represented in (binary) plist files.
 
-   .. versionadded: 3.4
+   .. versionadded:: 3.4
 
 
 .. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
@@ -116,7 +119,7 @@ This module defines the following functions:
    the documentation for :func:`dump` for an explanation of the keyword
    arguments of this function.
 
-   .. versionadded: 3.4
+   .. versionadded:: 3.4
 
 The following functions are deprecated:
 
@@ -135,7 +138,7 @@ The following functions are deprecated:
       to ``__getitem_``. This means that you can use attribute access to
       access items of these dictionaries.
 
-   .. deprecated: 3.4 Use :func:`load` instead.
+   .. deprecated:: 3.4 Use :func:`load` instead.
 
 
 .. function:: writePlist(rootObject, pathOrFile)
@@ -143,7 +146,7 @@ The following functions are deprecated:
    Write *rootObject* to an XML plist file. *pathOrFile* may be either a file name
    or a (writable and binary) file object
 
-   .. deprecated: 3.4 Use :func:`dump` instead.
+   .. deprecated:: 3.4 Use :func:`dump` instead.
 
 
 .. function:: readPlistFromBytes(data)
@@ -194,7 +197,7 @@ The following classes are available:
    .. deprecated:: 3.4 Use a :class:`bytes` object instead
 
 
-The following constants are avaiable:
+The following constants are available:
 
 .. data:: FMT_XML
 
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 47e8c1635e0c..d63d7690e36f 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -1097,9 +1097,13 @@ keyword-only arguments.  It also provides some efficiency improvements.
 plistlib
 --------
 
-:mod:`plistlib` now supports binary plist files, and offers the common
-``load``/``loads``/``dump``/``dumps`` API pattern for serialization formats
-(Contributed by Ronald Oussoren and others in :issue:`14455`).
+:mod:`plistlib` now has an API that is similar to the standard pattern for
+stdlib serialization protocols, with new :func:`~plistlib.load`,
+:func:`~plistlib.dump`, :func:`~plistlib.loads`, and :func:`~plistlib.dumps`
+functions.  (The older API is now deprecated.)  In addition to the already
+supported XML plist format (:data:`~plistlib.FMT_XML`), it also now supports
+the binary plist format (:data:`~plistlib.FMT_BINARY`).  (Contributed by Ronald
+Oussoren and others in :issue:`14455`).
 
 
 poplib
@@ -1887,6 +1891,13 @@ Deprecated Python Modules, Functions and Methods
 * The :func:`hmac.new` *digestmod* keyword having a default value (currently
   ``MD5``) is deprecated.
 
+* The :mod:`plistlib` :func:`~plistlib.readPlist`,
+  :func:`~plistlib.writePlist`, :func:`~plistlib.readPlistFromBytes`, and
+  :func:`~plistlib.writePlistToBytes` functions are deprecated in favor of the
+  corresponding new functions :func:`~plistlib.load`, :func:`~plistlib.dump`,
+  :func:`~plistlib.loads`, and :func:`~plistlib.dumps`.  :func:`~plistlib.Data`
+  is deprecated in favor of just using the :class:`bytes` constructor.
+
 
 Deprecated Functions and Types in the C API
 -------------------------------------------