bpo-38053 Update documentation for plistlib

Doc/library/plistlib.rst

@@ -1,8 +1,8 @@
-:mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files
-================================================================
+:mod:`plistlib` --- Generate and parse Apple ``.plist`` files
+=============================================================
 
 .. module:: plistlib
-   :synopsis: Generate and parse Mac OS X plist files.
+   :synopsis: Generate and parse Apple plist files.
 
 .. moduleauthor:: Jack Jansen
 .. sectionauthor:: Georg Brandl <[email protected]>
@@ -17,7 +17,8 @@
 --------------
 
 This module provides an interface for reading and writing the "property list"
-files used mainly by Mac OS X and supports both binary and XML plist files.
+files used by Apple, primarily on macOS and iOS. This module supports both binary
+and XML plist files.
 
 The property list (``.plist``) file format is a simple serialization supporting
 basic object types, like dictionaries, lists, numbers and strings.  Usually the
@@ -33,9 +34,6 @@ Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
 (but only with string keys), :class:`bytes`, :class:`bytearray`
 or :class:`datetime.datetime` objects.
 
-.. versionchanged:: 3.4
-   New API, old API deprecated.  Support for binary format plists added.
-
 .. versionchanged:: 3.8
    Support added for reading and writing :class:`UID` tokens in binary plists as used
    by NSKeyedArchiver and NSKeyedUnarchiver.
@@ -76,16 +74,12 @@ This module defines the following functions:
    The parser for the binary format raises :exc:`InvalidFileException`
    when the file cannot be parsed.
 
-   .. versionadded:: 3.4
-
 
 .. function:: loads(data, \*, fmt=None, dict_type=dict)
 
    Load a plist from a bytes object. See :func:`load` for an explanation of
    the keyword arguments.
 
-   .. versionadded:: 3.4
-
 
 .. function:: dump(value, fp, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
 
@@ -112,16 +106,25 @@ 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
-
 
 .. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
 
    Return *value* as a plist-formatted bytes object. See
    the documentation for :func:`dump` for an explanation of the keyword
    arguments of this function.
 
-   .. versionadded:: 3.4
+
+The following classes are available:
+
+.. class:: UID(data)
+
+   Wraps an :class:`int`.  This is used when reading or writing NSKeyedArchiver
+   encoded data, which contains UID (see PList manual).
+
+   It has one attribute, :attr:`data` which can be used to retrieve the int value
+   of the UID.  :attr:`data` must be in the range `0 <= data <= 2**64`.
+
+   .. versionadded:: 3.8
 
 
 The following constants are available:
@@ -130,15 +133,11 @@ The following constants are available:
 
    The XML format for plist files.
 
-   .. versionadded:: 3.4
-
 
 .. data:: FMT_BINARY
 
    The binary format for plist files
 
-   .. versionadded:: 3.4
-
 
 Examples
 --------

Misc/NEWS.d/next/Documentation/2019-09-07-19-09-01.bpo-38053.lttibE.rst

@@ -0,0 +1 @@
+Modernized the plistlib documentation