This module defines the following functions:
-.. function:: readPlist(pathOrFile)
+.. function:: load(fp, \*, fmt=None, use_builtin_types=True, dict_type=dict)
- Read a plist file. *pathOrFile* may either be a file name or a (readable and
- binary) file object. Return the unpacked root object (which usually is a
+ Read a plist file. *fp* should be a readable and binary 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.
+ The *fmt* is the format of the file and the following values are valid:
+
+ * :data:`None`: Autodetect the file format
+
+ * :data:`FMT_XML`: XML file format
+
+ * :data:`FMT_BINARY`: Binary plist format
+
- If *use_builtin_types* is True (the default) binary data will be returned
++ If *use_builtin_types* is true (the default) binary data will be returned
+ as instances of :class:`bytes`, otherwise it is returned as instances of
+ :class:`Data`.
+
+ The *dict_type* is the type used for dictionaries that are read from the
+ plist file. The exact structure of the plist can be recovered by using
+ :class:`collections.OrderedDict` (although the order of keys shouldn't be
+ important in plist files).
+
+ XML data for the :data:`FMT_XML` format 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.
+
+ The parser for the binary format raises :exc:`InvalidFileException`
+ when the file cannot be parsed.
+
+ .. versionadded:: 3.4
+
+
+.. function:: loads(data, \*, fmt=None, use_builtin_types=True, dict_type=dict)
+
+ Load a plist from a bytes object. See :func:`load` for an explanation of
+ the keyword arguments.
+
+
+.. function:: dump(value, fp, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
+
+ Write *value* to a plist file. *Fp* should be a writable, binary
+ file object.
+
+ The *fmt* argument specifies the format of the plist file and can be
+ one of the following values:
+
+ * :data:`FMT_XML`: XML formatted plist file
+
+ * :data:`FMT_BINARY`: Binary formatted plist file
+
+ When *sort_keys* is true (the default) the keys for dictionaries will be
+ written to the plist in sorted order, otherwise they will be written in
+ the iteration order of the dictionary.
+
+ When *skipkeys* is false (the default) the function raises :exc:`TypeError`
+ when a key of a dictionary is not a string, otherwise such keys are skipped.
+
+ A :exc:`TypeError` will be raised if the object is of an unsupported type or
+ a container that contains objects of unsupported types.
+
+ .. versionchanged:: 3.4
+ Added the *fmt*, *sort_keys* and *skipkeys* arguments.
+
+
+.. 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.
+
+
+The following functions are deprecated:
+
+.. function:: readPlist(pathOrFile)
+
+ Read a plist file. *pathOrFile* may be either a file name or a (readable
+ and binary) file object. Returns the unpacked root object (which usually
+ is a dictionary).
+
+ This function calls :func:`load` to do the actual work, the the documentation
+ of :func:`that function <load>` for an explanation of the keyword arguments.
+
+ .. note::
+
+ Dict values in the result have a ``__getattr__`` method that defers
+ to ``__getitem_``. This means that you can use attribute access to
+ access items of these dictionaries.
+
+ .. deprecated: 3.4 Use :func:`load` instead.
.. function:: writePlist(rootObject, pathOrFile)
- Issue #19545: Avoid chained exceptions while passing stray % to
time.strptime(). Initial patch by Claudiu Popa.
-- Issue #19633: Fixed writing not compressed 16- and 32-bit wave files on
- big-endian platforms.
+Tests
+-----
-- Issue #19449: in csv's writerow, handle non-string keys when generating the
- error message that certain keys are not in the 'fieldnames' list.
+- Issue #19595: Re-enabled a long-disabled test in test_winsound.
-- Fix test.support.bind_port() to not cause an error when Python was compiled
- on a system with SO_REUSEPORT defined in the headers but run on a system
- with an OS kernel that does not support that reasonably new socket option.
+- Issue #19588: Fixed tests in test_random that were silently skipped most
+ of the time. Patch by Julian Gindi.
-- Fix compilation error under gcc of the ctypes module bundled libffi for arm.
+Build
+-----
-- Issue #19523: Closed FileHandler leak which occurred when delay was set.
+- Issue #19788: kill_python(_d).exe is now run as a PreBuildEvent on the
+ pythoncore sub-project. This should prevent build errors due a previous
+ build's python(_d).exe still running.
-- Issue #13674: Prevented time.strftime from crashing on Windows when given
- a year before 1900 and a format of %y.
++Documentation
++-------------
+
-- Issue #19544 and Issue #6286: Restore use of urllib over http allowing use
- of http_proxy for Distutils upload command, a feature accidentally lost
- in the rollback of distutils2.
++- Issue #19795: Improved markup of True/False constants.
+
-- Issue #19544 and Issue #7457: Restore the read_pkg_file method to
- distutils.dist.DistributionMetadata accidentally removed in the undo of
- distutils2.
+
-- Issue #1575020: Fixed support of 24-bit wave files on big-endian platforms.
+What's New in Python 3.4.0 Beta 1?
+==================================
-- Issue #19480: HTMLParser now accepts all valid start-tag names as defined
- by the HTML5 standard.
+Release date: 2013-11-24
-- Issue #6157: Fixed tkinter.Text.debug(). Original patch by Guilherme Polo.
+Core and Builtins
+-----------------
-- Issue #6160: The bbox() method of tkinter.Spinbox now returns a tuple of
- integers instead of a string. Based on patch by Guilherme Polo.
+- Use the repr of a module name in more places in import, especially
+ exceptions.
-- Issue #10197: Rework subprocess.get[status]output to use subprocess
- functionality and thus to work on Windows. Patch by Nick Coghlan.
+- Issue #19619: str.encode, bytes.decode and bytearray.decode now use an
+ internal API to throw LookupError for known non-text encodings, rather
+ than attempting the encoding or decoding operation and then throwing a
+ TypeError for an unexpected output type. (The latter mechanism remains
+ in place for third party non-text encodings)
-- Issue #19286: Directories in ``package_data`` are no longer added to
- the filelist, preventing failure outlined in the ticket.
+- Issue #19183: Implement PEP 456 'secure and interchangeable hash algorithm'.
+ Python now uses SipHash24 on all major platforms.
-Tests
------
+- Issue #12892: The utf-16* and utf-32* encoders no longer allow surrogate code
+ points (U+D800-U+DFFF) to be encoded. The utf-32* decoders no longer decode
+ byte sequences that correspond to surrogate code points. The surrogatepass
+ error handler now works with the utf-16* and utf-32* codecs. Based on
+ patches by Victor Stinner and Kang-Hao (Kenny) Lu.
-- Issue #19588: Fixed tests in test_random that were silently skipped most
- of the time. Patch by Julian Gindi.
+- Issue #17806: Added keyword-argument support for "tabsize" to
+ str/bytes.expandtabs().
-- Issue #19596: Set untestable tests in test_importlib to None to avoid
- reporting success on empty tests.
+- Issue #17828: Output type errors in str.encode(), bytes.decode() and
+ bytearray.decode() now direct users to codecs.encode() or codecs.decode()
+ as appropriate.
-- Issue #19440: Clean up test_capi by removing an unnecessary __future__
- import, converting from test_main to unittest.main, and running the
- _testcapi module tests within a unittest TestCase.
+- Issue #17828: The interpreter now attempts to chain errors that occur in
+ codec processing with a replacement exception of the same type that
+ includes the codec name in the error message. It ensures it only does this
+ when the creation of the replacement exception won't lose any information.
-- Issue #18702: All skipped tests now reported as skipped.
+- Issue #19466: Clear the frames of daemon threads earlier during the
+ Python shutdown to call objects destructors. So "unclosed file" resource
+ warnings are now corretly emitted for daemon threads.
-- Issue #19085: Added basic tests for all tkinter widget options.
+- Issue #19514: Deduplicate some _Py_IDENTIFIER declarations.
+ Patch by Andrei Dorian Duma.
-Documentation
--------------
+- Issue #17936: Fix O(n**2) behaviour when adding or removing many subclasses
+ of a given type.
-- Issue #19795: Improved markup of True/False constants.
+- Issue #19428: zipimport now handles errors when reading truncated or invalid
+ ZIP archive.
-- Issue #18326: Clarify that list.sort's arguments are keyword-only. Also,
- attempt to reduce confusion in the glossary by not saying there are
- different "types" of arguments and parameters.
+- Issue #18408: Add a new PyFrame_FastToLocalsWithError() function to handle
+ exceptions when merging fast locals into f_locals of a frame.
+ PyEval_GetLocals() now raises an exception and return NULL on failure.
-Build
------
+- Issue #19369: Optimized the usage of __length_hint__().
-- Issue #19788: kill_python(_d).exe is now run as a PreBuildEvent on the
- pythoncore sub-project. This should prevent build errors due a previous
- build's python(_d).exe still running.
+- Issue #18603: Ensure that PyOS_mystricmp and PyOS_mystrnicmp are in the
+ Python executable and not removed by the linker's optimizer.
-- Add workaround for VS 2010 nmake clean issue. VS 2010 doesn't set up PATH
- for nmake.exe correctly.
+- Issue #19306: Add extra hints to the faulthandler module's stack
+ dumps that these are "upside down".
+Library
+-------
-What's New in Python 3.3.3?
-===========================
+- Issue #3158: doctest can now find doctests in functions and methods
+ written in C.
-*Release date: 17-Nov-2013*
+- Issue #13477: Added command line interface to the tarfile module.
+ Original patch by Berker Peksag.
-No changes from release candidate 2.
+- Issue #19674: inspect.signature() now produces a correct signature
+ for some builtins.
+- Issue #19722: Added opcode.stack_effect(), which
+ computes the stack effect of bytecode instructions.
-What's New in Python 3.3.3 release candidate 2?
-===============================================
+- Issue #19735: Implement private function ssl._create_stdlib_context() to
+ create SSLContext objects in Python's stdlib module. It provides a single
+ configuration point and makes use of SSLContext.load_default_certs().
-*Release date: 11-Nov-2013*
+- Issue #16203: Add re.fullmatch() function and regex.fullmatch() method,
+ which anchor the pattern at both ends of the string to match.
+ Original patch by Matthew Barnett.
-Library
--------
+- Issue #13592: Improved the repr for regular expression pattern objects.
+ Based on patch by Hugo Lopes Tavares.
-- Issue #19227: Any re-seeding of the OpenSSL RNG on fork has been removed;
- this should be handled by OpenSSL itself or by the application.
+- Issue #19641: Added the audioop.byteswap() function to convert big-endian
+ samples to little-endian and vice versa.
-- Issue #19435: Fix directory traversal attack on CGIHttpRequestHandler.
+- Issue #15204: Deprecated the 'U' mode in file-like objects.
-Tests
------
+- Issue #17810: Implement PEP 3154, pickle protocol 4.
-- Issue #18964: Fix test_tcl when run with Tcl/Tk versions < 8.5.
+- Issue #19668: Added support for the cp1125 encoding.
-Build
------
+- Issue #19689: Add ssl.create_default_context() factory function. It creates
+ a new SSLContext object with secure default settings.
-- Issue #15663: Revert OS X installer built-in Tcl/Tk support for 3.3.3.
- Some third-party projects, such as Matplotlib and PIL/Pillow,
- depended on being able to build with Tcl and Tk frameworks in
- /Library/Frameworks.
+- Issue #19727: os.utime(..., None) is now potentially more precise
+ under Windows.
+- Issue #17201: ZIP64 extensions now are enabled by default. Patch by
+ William Mallard.
-What's New in Python 3.3.3 release candidate 1?
-===============================================
+- Issue #19292: Add SSLContext.load_default_certs() to load default root CA
+ certificates from default stores or system stores. By default the method
+ loads CA certs for authentication of server certs.
-*Release date: 27-Oct-2013*
+- Issue #19673: Add pathlib to the stdlib as a provisional module (PEP 428).
-Core and Builtins
------------------
+- Issue #16596: pdb in a generator now properly skips over yield and
+ yield from rather than stepping out of the generator into its
+ caller. (This is essential for stepping through asyncio coroutines.)
-- Issue #18603: Ensure that PyOS_mystricmp and PyOS_mystrnicmp are in the
- Python executable and not removed by the linker's optimizer.
+- Issue #17916: Added dis.Bytecode.from_traceback() and
+ dis.Bytecode.current_offset to easily display "current instruction"
+ markers in the new disassembly API (Patch by Claudiu Popa).
-- Issue #19279: UTF-7 decoder no more produces illegal strings.
+- Issue #19552: venv now supports bootstrapping pip into virtual environments
-- Fix macro expansion of _PyErr_OCCURRED(), and make sure to use it in at
- least one place so as to avoid regressions.
+- Issue #17134: Finalize interface to Windows' certificate store. Cert and
+ CRL enumeration are now two functions. enum_certificates() also returns
+ purpose flags as set of OIDs.
-- Issue #19014: memoryview.cast() is now allowed on zero-length views.
+- Issue #19555: Restore sysconfig.get_config_var('SO'), (and the distutils
+ equivalent) with a DeprecationWarning pointing people at $EXT_SUFFIX.
-- Issue #19098: Prevent overflow in the compiler when the recursion limit is set
- absurdly high.
+- Issue #8813: Add SSLContext.verify_flags to change the verification flags
+ of the context in order to enable certification revocation list (CRL)
+ checks or strict X509 rules.
-- Issue #18942: sys._debugmallocstats() output was damaged on Windows.
+- Issue #18294: Fix the zlib module to make it 64-bit safe.
-- Issue #18667: Add missing "HAVE_FCHOWNAT" symbol to posix._have_functions.
+- Issue #19682: Fix compatibility issue with old version of OpenSSL that
+ was introduced by Issue #18379.
-- Issue #18368: PyOS_StdioReadline() no longer leaks memory when realloc()
- fails.
+- Issue #14455: plistlib now supports binary plists and has an updated API.
-- Issue #16741: Fix an error reporting in int().
+- Issue #19633: Fixed writing not compressed 16- and 32-bit wave files on
+ big-endian platforms.
-- Issue #17899: Fix rare file descriptor leak in os.listdir().
+- Issue #18379: SSLSocket.getpeercert() returns CA issuer AIA fields, OCSP
+ and CRL distribution points.
-- Issue #18552: Check return value of PyArena_AddPyObject() in
- obj2ast_object().
+- Issue #18138: Implement cadata argument of SSLContext.load_verify_location()
+ to load CA certificates and CRL from memory. It supports PEM and DER
+ encoded strings.
-- Issue #18560: Fix potential NULL pointer dereference in sum().
+- Issue #18775: Add name and block_size attribute to HMAC object. They now
+ provide the same API elements as non-keyed cryptographic hash functions.
-- Issue #15905: Fix theoretical buffer overflow in handling of sys.argv[0],
- prefix and exec_prefix if the operation system does not obey MAXPATHLEN.
+- Issue #17276: MD5 as default digestmod for HMAC is deprecated. The HMAC
+ module supports digestmod names, e.g. hmac.HMAC('sha1').
-- Issue #18344: Fix potential ref-leaks in _bufferedreader_read_all().
+- Issue #19449: in csv's writerow, handle non-string keys when generating the
+ error message that certain keys are not in the 'fieldnames' list.
-- Issue #17872: Fix a segfault in marshal.load() when input stream returns
- more bytes than requested.
+- Issue #13633: Added a new convert_charrefs keyword arg to HTMLParser that,
+ when True, automatically converts all character references.
-- Issue #18426: Fix NULL pointer dereference in C extension import when
- PyModule_GetDef() returns an error.
+- Issue #2927: Added the unescape() function to the html module.
-- Issue #18328: Reorder ops in PyThreadState_Delete*() functions. Now the
- tstate is first removed from TLS and then deallocated.
+- Issue #8402: Added the escape() function to the glob module.
-- Issue #18184: PyUnicode_FromFormat() and PyUnicode_FromFormatV() now raise
- OverflowError when an argument of %c format is out of range.
+- Issue #17618: Add Base85 and Ascii85 encoding/decoding to the base64 module.
-- Issue #18137: Detect integer overflow on precision in float.__format__()
- and complex.__format__().
+- Issue #19634: time.strftime("%y") now raises a ValueError on AIX when given a
+ year before 1900.
-- Issue #18183: Fix various unicode operations on strings with large unicode
- codepoints.
+- Fix test.support.bind_port() to not cause an error when Python was compiled
+ on a system with SO_REUSEPORT defined in the headers but run on a system
+ with an OS kernel that does not support that reasonably new socket option.
-- Issue #18180: Fix ref leak in _PyImport_GetDynLoadWindows().
+- Fix compilation error under gcc of the ctypes module bundled libffi for arm.
-- Issue #18038: SyntaxError raised during compilation sources with illegal
- encoding now always contains an encoding name.
+- Issue #19448: Add private API to SSL module to lookup ASN.1 objects by OID,
+ NID, short name and long name.
-- Issue #17644: Fix a crash in str.format when curly braces are used in square
- brackets.
+- Issue #19282: dbm.open now supports the context manager protocol. (Inital
+ patch by Claudiu Popa)
-- Issue #17983: Raise a SyntaxError for a ``global __class__`` statement in a
- class body.
+- Issue #8311: Added support for writing any bytes-like objects in the aifc,
+ sunau, and wave modules.
-- Issue #17927: Frame objects kept arguments alive if they had been copied into
- a cell, even if the cell was cleared.
+- Issue #5202: Added support for unseekable files in the wave module.
-Library
--------
+- Issue #19544 and Issue #1180: Restore global option to ignore
+ ~/.pydistutils.cfg in Distutils, accidentally removed in backout of
+ distutils2 changes.
+
+- Issue #19523: Closed FileHandler leak which occurred when delay was set.
+
+- Issue #19544 and #6516: Restore support for --user and --group parameters to
+ sdist command accidentally rolled back as part of the distutils2 rollback.
+
+- Issue #13674: Prevented time.strftime from crashing on Windows when given
+ a year before 1900 and a format of %y.
+
+- Issue #19406: implementation of the ensurepip module (part of PEP 453).
+ Patch by Donald Stufft and Nick Coghlan.
+
+- Issue #19544 and Issue #6286: Restore use of urllib over http allowing use
+ of http_proxy for Distutils upload command, a feature accidentally lost
+ in the rollback of distutils2.
+
+- Issue #19544 and Issue #7457: Restore the read_pkg_file method to
+ distutils.dist.DistributionMetadata accidentally removed in the undo of
+ distutils2.
+
+- Issue #16685: Added support for any bytes-like objects in the audioop module.
+ Removed support for strings.
+
+- Issue #7171: Add Windows implementation of ``inet_ntop`` and ``inet_pton``
+ to socket module. Patch by Atsuo Ishimoto.
+
+- Issue #19261: Added support for writing 24-bit samples in the sunau module.
+
+- Issue #1097797: Added CP273 encoding, used on IBM mainframes in
+ Germany and Austria. Mapping provided by Michael Bierenfeld.
+
+- Issue #1575020: Fixed support of 24-bit wave files on big-endian platforms.
+
+- Issue #19378: Fixed a number of cases in the dis module where the new
+ "file" parameter was not being honoured correctly
+
+- Issue #19378: Removed the "dis.Bytecode.show_info" method
+
+- Issue #19378: Renamed the "dis.Bytecode.display_code" method to
+ "dis.Bytecode.dis" and converted it to returning a string rather than
+ printing output.
+
+- Issue #19378: the "line_offset" parameter in the new "dis.get_instructions"
+ API has been renamed to "first_line" (and the default value and usage
+ changed accordingly). This should reduce confusion with the more common use
+ of "offset" in the dis docs to refer to bytecode offsets.
+
+- Issue #18678: Corrected spwd struct member names in spwd module:
+ sp_nam->sp_namp, and sp_pwd->sp_pwdp. The old names are kept as extra
+ structseq members, for backward compatibility.
+
+- Issue #6157: Fixed tkinter.Text.debug(). tkinter.Text.bbox() now raises
+ TypeError instead of TclError on wrong number of arguments. Original patch
+ by Guilherme Polo.
+
+- Issue #10197: Rework subprocess.get[status]output to use subprocess
+ functionality and thus to work on Windows. Patch by Nick Coghlan
-- Issue #19395: Raise an exception when attempting to pickle a bz2 or lzma
- compressor/decompressor object, rather than creating a pickle that would
- cause a segfault when loaded and used.
+- Issue #6160: The bbox() method of tkinter.Spinbox now returns a tuple of
+ integers instead of a string. Based on patch by Guilherme Polo.
+
+- Issue #19403: contextlib.redirect_stdout is now reentrant
+
+- Issue #19286: Directories in ``package_data`` are no longer added to
+ the filelist, preventing failure outlined in the ticket.
+
+- Issue #19480: HTMLParser now accepts all valid start-tag names as defined
+ by the HTML5 standard.
+
+- Issue #15114: The html.parser module now raises a DeprecationWarning when the
+ strict argument of HTMLParser or the HTMLParser.error method are used.
+
+- Issue #19410: Undo the special-casing removal of '' for
+ importlib.machinery.FileFinder.
+
+- Issue #19424: Fix the warnings module to accept filename containing surrogate
+ characters.
+
+- Issue #19435: Fix directory traversal attack on CGIHttpRequestHandler.
+
+- Issue #19227: Remove pthread_atfork() handler. The handler was added to
+ solve #18747 but has caused issues.
+
+- Issue #19420: Fix reference leak in module initalization code of
+ _hashopenssl.c
+
+- Issue #19329: Optimized compiling charsets in regular expressions.
- Issue #19227: Try to fix deadlocks caused by re-seeding then OpenSSL
pseudo-random number generator on fork().