[Python-checkins] cpython: whatsnew: plistlib new api and deprecations (#14455)

[r.david.murray]

http://hg.python.org/cpython/rev/728f626ee337
changeset:   89532:728f626ee337
user:        R David Murray <rdmurray at bitdance.com>
date:        Sun Mar 09 15:09:04 2014 -0400
summary:
  whatsnew: plistlib new api and deprecations (#14455)

Also fixed the versionchanged/deprecation tags in the docs.

files:
  Doc/library/plistlib.rst |  13 ++++++++-----
  Doc/whatsnew/3.4.rst     |  17 ++++++++++++++---
  2 files changed, 22 insertions(+), 8 deletions(-)


diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst
--- a/Doc/library/plistlib.rst
+++ b/Doc/library/plistlib.rst
@@ -32,6 +32,9 @@
 (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 @@
    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 @@
    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 @@
       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 @@
    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 @@
    .. 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
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -1097,9 +1097,13 @@
 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 @@
 * 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
 -------------------------------------------

-- 
Repository URL: http://hg.python.org/cpython