From f37b0cb230069481609b0bb06891b5dd26320504 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Fri, 24 Feb 2017 15:31:48 -0500 Subject: [PATCH 01/24] bpo-25008: Deprecate smtpd and point to aiosmtpd (#274) (#280) --- Doc/library/smtpd.rst | 6 ++++++ Misc/NEWS | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/Doc/library/smtpd.rst b/Doc/library/smtpd.rst index 3ebed06260945c..78f9d7feec4953 100644 --- a/Doc/library/smtpd.rst +++ b/Doc/library/smtpd.rst @@ -13,6 +13,12 @@ This module offers several classes to implement SMTP (email) servers. +.. seealso:: + + The `aiosmtpd `_ package is a recommended + replacement for this module. It is based on :mod:`asyncio` and provides a + more straightforward API. :mod:`smtpd` should be considered deprecated. + Several server implementations are present; one is a generic do-nothing implementation, which can be overridden, while the other two offer specific mail-sending strategies. diff --git a/Misc/NEWS b/Misc/NEWS index 7acaf2fd50e20e..d9e691b2496bd1 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -10,6 +10,12 @@ Release date: XXXX-XX-XX Core and Builtins ----------------- +Documentation +------------- + +- bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to + aiosmtpd, a third-party asyncio-based replacement. + Library ------- From fa53dbdec818b0f2a0e22ca12a49d83ec948fc91 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 10 Mar 2017 01:49:11 +0100 Subject: [PATCH 02/24] Issues #27850 and #27766: Remove 3DES from ssl default cipher list and add ChaCha20 Poly1305. (#224) Backport: replace 3.5.3 with 3.4.7 in the doc versionchanged. (cherry picked from commit 03d13c0cbfe912eb0f9b9a02987b9e569f25fe19) --- Doc/library/ssl.rst | 6 ++++++ Lib/ssl.py | 36 +++++++++++++++++++++--------------- Misc/NEWS | 2 ++ 3 files changed, 29 insertions(+), 15 deletions(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index b0cf4ebd83921f..1ad4d618064294 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -280,6 +280,12 @@ purposes. RC4 was dropped from the default cipher string. + .. versionchanged:: 3.4.7 + + ChaCha20/Poly1305 was added to the default cipher string. + + 3DES was dropped from the default cipher string. + Random generation ^^^^^^^^^^^^^^^^^ diff --git a/Lib/ssl.py b/Lib/ssl.py index ec42e38d08638c..873aa4798bbc5d 100644 --- a/Lib/ssl.py +++ b/Lib/ssl.py @@ -160,36 +160,42 @@ def _import_symbols(prefix): else: CHANNEL_BINDING_TYPES = [] + # Disable weak or insecure ciphers by default # (OpenSSL's default setting is 'DEFAULT:!aNULL:!eNULL') # Enable a better set of ciphers by default # This list has been explicitly chosen to: # * Prefer cipher suites that offer perfect forward secrecy (DHE/ECDHE) # * Prefer ECDHE over DHE for better performance -# * Prefer any AES-GCM over any AES-CBC for better performance and security +# * Prefer AEAD over CBC for better performance and security +# * Prefer AES-GCM over ChaCha20 because most platforms have AES-NI +# (ChaCha20 needs OpenSSL 1.1.0 or patched 1.0.2) +# * Prefer any AES-GCM and ChaCha20 over any AES-CBC for better +# performance and security # * Then Use HIGH cipher suites as a fallback -# * Then Use 3DES as fallback which is secure but slow -# * Disable NULL authentication, NULL encryption, and MD5 MACs for security -# reasons +# * Disable NULL authentication, NULL encryption, 3DES and MD5 MACs +# for security reasons _DEFAULT_CIPHERS = ( - 'ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+HIGH:' - 'DH+HIGH:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+HIGH:RSA+3DES:!aNULL:' - '!eNULL:!MD5' -) + 'ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:DH+CHACHA20:ECDH+AES256:DH+AES256:' + 'ECDH+AES128:DH+AES:ECDH+HIGH:DH+HIGH:RSA+AESGCM:RSA+AES:RSA+HIGH:' + '!aNULL:!eNULL:!MD5:!3DES' + ) # Restricted and more secure ciphers for the server side # This list has been explicitly chosen to: # * Prefer cipher suites that offer perfect forward secrecy (DHE/ECDHE) # * Prefer ECDHE over DHE for better performance -# * Prefer any AES-GCM over any AES-CBC for better performance and security +# * Prefer AEAD over CBC for better performance and security +# * Prefer AES-GCM over ChaCha20 because most platforms have AES-NI +# * Prefer any AES-GCM and ChaCha20 over any AES-CBC for better +# performance and security # * Then Use HIGH cipher suites as a fallback -# * Then Use 3DES as fallback which is secure but slow -# * Disable NULL authentication, NULL encryption, MD5 MACs, DSS, and RC4 for -# security reasons +# * Disable NULL authentication, NULL encryption, MD5 MACs, DSS, RC4, and +# 3DES for security reasons _RESTRICTED_SERVER_CIPHERS = ( - 'ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+HIGH:' - 'DH+HIGH:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+HIGH:RSA+3DES:!aNULL:' - '!eNULL:!MD5:!DSS:!RC4' + 'ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:DH+CHACHA20:ECDH+AES256:DH+AES256:' + 'ECDH+AES128:DH+AES:ECDH+HIGH:DH+HIGH:RSA+AESGCM:RSA+AES:RSA+HIGH:' + '!aNULL:!eNULL:!MD5:!DSS:!RC4:!3DES' ) diff --git a/Misc/NEWS b/Misc/NEWS index d9e691b2496bd1..ac54bbc8b35a5f 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -19,6 +19,8 @@ Documentation Library ------- +- Issue #27850: Remove 3DES from ssl module's default cipher list to counter + measure sweet32 attack (CVE-2016-2183). What's New in Python 3.4.6? =========================== From ad1fb813a62733c096a877971d678a2585797b24 Mon Sep 17 00:00:00 2001 From: larryhastings Date: Thu, 22 Jun 2017 16:00:46 -0700 Subject: [PATCH 03/24] Add "Misc/NEWS.d" directory tree for "blurb". GH-2331 CPython workflow is changing! We're going to start using "blurb" to manage Misc/NEWS entries: https://github.com/python/core-workflow (This will be a big win for release managers, honest.) This checkin simply populates the "Misc/NEWS.d" subdirectory tree so that people can start putting their news entries in there. No other changes (yet). --- Misc/NEWS.d/next/Build/README.rst | 1 + Misc/NEWS.d/next/C API/README.rst | 1 + Misc/NEWS.d/next/Core and Builtins/README.rst | 1 + Misc/NEWS.d/next/Documentation/README.rst | 1 + Misc/NEWS.d/next/IDLE/README.rst | 1 + Misc/NEWS.d/next/Library/README.rst | 1 + Misc/NEWS.d/next/Security/README.rst | 1 + Misc/NEWS.d/next/Tests/README.rst | 1 + Misc/NEWS.d/next/Tools-Demos/README.rst | 1 + Misc/NEWS.d/next/Windows/README.rst | 1 + Misc/NEWS.d/next/macOS/README.rst | 1 + 11 files changed, 11 insertions(+) create mode 100644 Misc/NEWS.d/next/Build/README.rst create mode 100644 Misc/NEWS.d/next/C API/README.rst create mode 100644 Misc/NEWS.d/next/Core and Builtins/README.rst create mode 100644 Misc/NEWS.d/next/Documentation/README.rst create mode 100644 Misc/NEWS.d/next/IDLE/README.rst create mode 100644 Misc/NEWS.d/next/Library/README.rst create mode 100644 Misc/NEWS.d/next/Security/README.rst create mode 100644 Misc/NEWS.d/next/Tests/README.rst create mode 100644 Misc/NEWS.d/next/Tools-Demos/README.rst create mode 100644 Misc/NEWS.d/next/Windows/README.rst create mode 100644 Misc/NEWS.d/next/macOS/README.rst diff --git a/Misc/NEWS.d/next/Build/README.rst b/Misc/NEWS.d/next/Build/README.rst new file mode 100644 index 00000000000000..0d2d2c1fc38be9 --- /dev/null +++ b/Misc/NEWS.d/next/Build/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Build* section in this directory. diff --git a/Misc/NEWS.d/next/C API/README.rst b/Misc/NEWS.d/next/C API/README.rst new file mode 100644 index 00000000000000..5a04f76f47b67e --- /dev/null +++ b/Misc/NEWS.d/next/C API/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *C API* section in this directory. diff --git a/Misc/NEWS.d/next/Core and Builtins/README.rst b/Misc/NEWS.d/next/Core and Builtins/README.rst new file mode 100644 index 00000000000000..52b8c3e6263163 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Core and Builtins* section in this directory. diff --git a/Misc/NEWS.d/next/Documentation/README.rst b/Misc/NEWS.d/next/Documentation/README.rst new file mode 100644 index 00000000000000..405f0ac01a7202 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Documentation* section in this directory. diff --git a/Misc/NEWS.d/next/IDLE/README.rst b/Misc/NEWS.d/next/IDLE/README.rst new file mode 100644 index 00000000000000..5475f7b42050cd --- /dev/null +++ b/Misc/NEWS.d/next/IDLE/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *IDLE* section in this directory. diff --git a/Misc/NEWS.d/next/Library/README.rst b/Misc/NEWS.d/next/Library/README.rst new file mode 100644 index 00000000000000..6d2d30eca0fd05 --- /dev/null +++ b/Misc/NEWS.d/next/Library/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Library* section in this directory. diff --git a/Misc/NEWS.d/next/Security/README.rst b/Misc/NEWS.d/next/Security/README.rst new file mode 100644 index 00000000000000..84c1a3a6ed7a07 --- /dev/null +++ b/Misc/NEWS.d/next/Security/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Security* section in this directory. diff --git a/Misc/NEWS.d/next/Tests/README.rst b/Misc/NEWS.d/next/Tests/README.rst new file mode 100644 index 00000000000000..d2e50e43d84790 --- /dev/null +++ b/Misc/NEWS.d/next/Tests/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Tests* section in this directory. diff --git a/Misc/NEWS.d/next/Tools-Demos/README.rst b/Misc/NEWS.d/next/Tools-Demos/README.rst new file mode 100644 index 00000000000000..357f82862cb51a --- /dev/null +++ b/Misc/NEWS.d/next/Tools-Demos/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Tools/Demos* section in this directory. diff --git a/Misc/NEWS.d/next/Windows/README.rst b/Misc/NEWS.d/next/Windows/README.rst new file mode 100644 index 00000000000000..1e65de35f0ad97 --- /dev/null +++ b/Misc/NEWS.d/next/Windows/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *Windows* section in this directory. diff --git a/Misc/NEWS.d/next/macOS/README.rst b/Misc/NEWS.d/next/macOS/README.rst new file mode 100644 index 00000000000000..a3adb59b62631e --- /dev/null +++ b/Misc/NEWS.d/next/macOS/README.rst @@ -0,0 +1 @@ +Put news entry ``blurb`` files for the *macOS* section in this directory. From fe82c46327effc124ff166e1fa1e611579e1176b Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 11 Jul 2017 13:24:10 +0300 Subject: [PATCH 04/24] [security][3.4] bpo-30730: Prevent environment variables injection in subprocess on Windows. (GH-2325) (#2362) * [3.4] bpo-30730: Prevent environment variables injection in subprocess on Windows. (GH-2325) Prevent passing other invalid environment variables and command arguments.. (cherry picked from commit d174d24a5d37d1516b885dc7c82f71ecd5930700) * Update NEWS --- Lib/subprocess.py | 8 ++++++-- Lib/test/test_subprocess.py | 40 +++++++++++++++++++++++++++++++++++++ Misc/NEWS | 4 ++++ Modules/_winapi.c | 23 +++++++++++++++++---- Objects/abstract.c | 4 ++-- 5 files changed, 71 insertions(+), 8 deletions(-) diff --git a/Lib/subprocess.py b/Lib/subprocess.py index 04cfb44de30b80..bf660ef08ff6f4 100644 --- a/Lib/subprocess.py +++ b/Lib/subprocess.py @@ -1375,8 +1375,12 @@ def _execute_child(self, args, executable, preexec_fn, close_fds, # and pass it to fork_exec() if env is not None: - env_list = [os.fsencode(k) + b'=' + os.fsencode(v) - for k, v in env.items()] + env_list = [] + for k, v in env.items(): + k = os.fsencode(k) + if b'=' in k: + raise ValueError("illegal environment variable name") + env_list.append(k + b'=' + os.fsencode(v)) else: env_list = None # Use execv instead of execve. executable = os.fsencode(executable) diff --git a/Lib/test/test_subprocess.py b/Lib/test/test_subprocess.py index 4719cc01658b54..19b140239439cf 100644 --- a/Lib/test/test_subprocess.py +++ b/Lib/test/test_subprocess.py @@ -606,6 +606,46 @@ def test_empty_env(self): # environment b"['__CF_USER_TEXT_ENCODING']")) + def test_invalid_cmd(self): + # null character in the command name + cmd = sys.executable + '\0' + with self.assertRaises(ValueError): + subprocess.Popen([cmd, "-c", "pass"]) + + # null character in the command argument + with self.assertRaises(ValueError): + subprocess.Popen([sys.executable, "-c", "pass#\0"]) + + def test_invalid_env(self): + # null character in the enviroment variable name + newenv = os.environ.copy() + newenv["FRUIT\0VEGETABLE"] = "cabbage" + with self.assertRaises(ValueError): + subprocess.Popen([sys.executable, "-c", "pass"], env=newenv) + + # null character in the enviroment variable value + newenv = os.environ.copy() + newenv["FRUIT"] = "orange\0VEGETABLE=cabbage" + with self.assertRaises(ValueError): + subprocess.Popen([sys.executable, "-c", "pass"], env=newenv) + + # equal character in the enviroment variable name + newenv = os.environ.copy() + newenv["FRUIT=ORANGE"] = "lemon" + with self.assertRaises(ValueError): + subprocess.Popen([sys.executable, "-c", "pass"], env=newenv) + + # equal character in the enviroment variable value + newenv = os.environ.copy() + newenv["FRUIT"] = "orange=lemon" + with subprocess.Popen([sys.executable, "-c", + 'import sys, os;' + 'sys.stdout.write(os.getenv("FRUIT"))'], + stdout=subprocess.PIPE, + env=newenv) as p: + stdout, stderr = p.communicate() + self.assertEqual(stdout, b"orange=lemon") + def test_communicate_stdin(self): p = subprocess.Popen([sys.executable, "-c", 'import sys;' diff --git a/Misc/NEWS b/Misc/NEWS index ac54bbc8b35a5f..86985a15879cd2 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -19,9 +19,13 @@ Documentation Library ------- +- [Security] bpo-30730: Prevent environment variables injection in subprocess on + Windows. Prevent passing other invalid environment variables and command arguments. + - Issue #27850: Remove 3DES from ssl module's default cipher list to counter measure sweet32 attack (CVE-2016-2183). + What's New in Python 3.4.6? =========================== diff --git a/Modules/_winapi.c b/Modules/_winapi.c index d472c9ee53efef..5ff820fc9452d0 100644 --- a/Modules/_winapi.c +++ b/Modules/_winapi.c @@ -535,6 +535,20 @@ getenvironment(PyObject* environment) "environment can only contain strings"); goto error; } + if (PyUnicode_FindChar(key, '\0', 0, PyUnicode_GET_LENGTH(key), 1) != -1 || + PyUnicode_FindChar(value, '\0', 0, PyUnicode_GET_LENGTH(value), 1) != -1) + { + PyErr_SetString(PyExc_ValueError, "embedded null character"); + goto error; + } + /* Search from index 1 because on Windows starting '=' is allowed for + defining hidden environment variables. */ + if (PyUnicode_GET_LENGTH(key) == 0 || + PyUnicode_FindChar(key, '=', 1, PyUnicode_GET_LENGTH(key), 1) != -1) + { + PyErr_SetString(PyExc_ValueError, "illegal environment variable name"); + goto error; + } if (totalsize > PY_SSIZE_T_MAX - PyUnicode_GET_LENGTH(key) - 1) { PyErr_SetString(PyExc_OverflowError, "environment too long"); goto error; @@ -643,12 +657,13 @@ winapi_CreateProcess(PyObject* self, PyObject* args) if (env_mapping != Py_None) { environment = getenvironment(env_mapping); - if (! environment) + if (environment == NULL) { return NULL; + } + /* contains embedded null characters */ wenvironment = PyUnicode_AsUnicode(environment); - if (wenvironment == NULL) - { - Py_XDECREF(environment); + if (wenvironment == NULL) { + Py_DECREF(environment); return NULL; } } diff --git a/Objects/abstract.c b/Objects/abstract.c index 5e9613816a834f..e1a10803606394 100644 --- a/Objects/abstract.c +++ b/Objects/abstract.c @@ -2714,8 +2714,8 @@ _PySequence_BytesToCharpArray(PyObject* self) array[i] = NULL; goto fail; } - data = PyBytes_AsString(item); - if (data == NULL) { + /* check for embedded null bytes */ + if (PyBytes_AsStringAndSize(item, &data, NULL) < 0) { /* NULL terminate before freeing. */ array[i] = NULL; goto fail; From f7344798e57da6b9c4ed9372e8eaecde80989c86 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 11 Jul 2017 16:30:21 +0300 Subject: [PATCH 05/24] [3.4] [3.5] bpo-27945: Fixed various segfaults with dict. (GH-1657) (GH-1678) (#2248) Based on patches by Duane Griffin and Tim Mitchell. (cherry picked from commit 753bca3934a7618a4fa96e107ad1c5c18633a683). (cherry picked from commit 2f7f533cf6fb57fcedcbc7bd454ac59fbaf2c655) --- Lib/test/test_dict.py | 86 +++++++++++++++++++++++++++++++++++++++++++ Misc/ACKS | 1 + Misc/NEWS | 6 ++- Objects/dictobject.c | 80 +++++++++++++++++++++++++--------------- 4 files changed, 143 insertions(+), 30 deletions(-) diff --git a/Lib/test/test_dict.py b/Lib/test/test_dict.py index 80feb903a94bca..75509a7aa4bfbd 100644 --- a/Lib/test/test_dict.py +++ b/Lib/test/test_dict.py @@ -952,6 +952,92 @@ def __eq__(self, o): d = {X(): 0, 1: 1} self.assertRaises(RuntimeError, d.update, other) + def test_equal_operator_modifying_operand(self): + # test fix for seg fault reported in issue 27945 part 3. + class X(): + def __del__(self): + dict_b.clear() + + def __eq__(self, other): + dict_a.clear() + return True + + def __hash__(self): + return 13 + + dict_a = {X(): 0} + dict_b = {X(): X()} + self.assertTrue(dict_a == dict_b) + + def test_fromkeys_operator_modifying_dict_operand(self): + # test fix for seg fault reported in issue 27945 part 4a. + class X(int): + def __hash__(self): + return 13 + + def __eq__(self, other): + if len(d) > 1: + d.clear() + return False + + d = {} # this is required to exist so that d can be constructed! + d = {X(1): 1, X(2): 2} + try: + dict.fromkeys(d) # shouldn't crash + except RuntimeError: # implementation defined + pass + + def test_fromkeys_operator_modifying_set_operand(self): + # test fix for seg fault reported in issue 27945 part 4b. + class X(int): + def __hash__(self): + return 13 + + def __eq__(self, other): + if len(d) > 1: + d.clear() + return False + + d = {} # this is required to exist so that d can be constructed! + d = {X(1), X(2)} + try: + dict.fromkeys(d) # shouldn't crash + except RuntimeError: # implementation defined + pass + + def test_dictitems_contains_use_after_free(self): + class X: + def __eq__(self, other): + d.clear() + return NotImplemented + + d = {0: set()} + (0, X()) in d.items() + + def test_init_use_after_free(self): + class X: + def __hash__(self): + pair[:] = [] + return 13 + + pair = [X(), 123] + dict([pair]) + + def test_oob_indexing_dictiter_iternextitem(self): + class X(int): + def __del__(self): + d.clear() + + d = {i: X(i) for i in range(8)} + + def iter_and_mutate(): + for result in d.items(): + if result[0] == 2: + d[2] = None # free d[2] --> X(2).__del__ was called + + self.assertRaises(RuntimeError, iter_and_mutate) + + from test import mapping_tests class GeneralMappingTests(mapping_tests.BasicTestMappingProtocol): diff --git a/Misc/ACKS b/Misc/ACKS index 6824554d16e104..bc188119b205be 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -506,6 +506,7 @@ Hans de Graaff Tim Graham Nathaniel Gray Eddy De Greef +Duane Griffin Grant Griffin Andrea Griffini Duncan Grisby diff --git a/Misc/NEWS b/Misc/NEWS index 86985a15879cd2..88d6c70fd4a742 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -1,4 +1,4 @@ -+++++++++++ ++++++++++++ Python News +++++++++++ @@ -10,6 +10,10 @@ Release date: XXXX-XX-XX Core and Builtins ----------------- +- bpo-27945: Fixed various segfaults with dict when input collections are + mutated during searching, inserting or comparing. Based on patches by + Duane Griffin and Tim Mitchell. + Documentation ------------- diff --git a/Objects/dictobject.c b/Objects/dictobject.c index 25619c116bf57b..5fc698c8854362 100644 --- a/Objects/dictobject.c +++ b/Objects/dictobject.c @@ -805,56 +805,61 @@ insertdict(PyDictObject *mp, PyObject *key, Py_hash_t hash, PyObject *value) PyDictKeyEntry *ep; assert(key != dummy); + Py_INCREF(key); + Py_INCREF(value); if (mp->ma_values != NULL && !PyUnicode_CheckExact(key)) { if (insertion_resize(mp) < 0) - return -1; + goto Fail; } ep = mp->ma_keys->dk_lookup(mp, key, hash, &value_addr); - if (ep == NULL) { - return -1; - } + if (ep == NULL) + goto Fail; + assert(PyUnicode_CheckExact(key) || mp->ma_keys->dk_lookup == lookdict); - Py_INCREF(value); MAINTAIN_TRACKING(mp, key, value); old_value = *value_addr; if (old_value != NULL) { assert(ep->me_key != NULL && ep->me_key != dummy); *value_addr = value; Py_DECREF(old_value); /* which **CAN** re-enter (see issue #22653) */ + Py_DECREF(key); } else { if (ep->me_key == NULL) { - Py_INCREF(key); if (mp->ma_keys->dk_usable <= 0) { /* Need to resize. */ - if (insertion_resize(mp) < 0) { - Py_DECREF(key); - Py_DECREF(value); - return -1; - } + if (insertion_resize(mp) < 0) + goto Fail; ep = find_empty_slot(mp, key, hash, &value_addr); } + mp->ma_used++; + *value_addr = value; mp->ma_keys->dk_usable--; assert(mp->ma_keys->dk_usable >= 0); ep->me_key = key; ep->me_hash = hash; + assert(ep->me_key != NULL && ep->me_key != dummy); } else { + mp->ma_used++; + *value_addr = value; if (ep->me_key == dummy) { - Py_INCREF(key); ep->me_key = key; ep->me_hash = hash; Py_DECREF(dummy); } else { assert(_PyDict_HasSplitTable(mp)); + Py_DECREF(key); } } - mp->ma_used++; - *value_addr = value; - assert(ep->me_key != NULL && ep->me_key != dummy); } return 0; + +Fail: + Py_DECREF(value); + Py_DECREF(key); + return -1; } /* @@ -1911,11 +1916,18 @@ PyDict_MergeFromSeq2(PyObject *d, PyObject *seq2, int override) /* Update/merge with this (key, value) pair. */ key = PySequence_Fast_GET_ITEM(fast, 0); value = PySequence_Fast_GET_ITEM(fast, 1); + Py_INCREF(key); + Py_INCREF(value); if (override || PyDict_GetItem(d, key) == NULL) { int status = PyDict_SetItem(d, key, value); - if (status < 0) + if (status < 0) { + Py_DECREF(key); + Py_DECREF(value); goto Fail; + } } + Py_DECREF(key); + Py_DECREF(value); Py_DECREF(fast); Py_DECREF(item); } @@ -2174,14 +2186,15 @@ dict_equal(PyDictObject *a, PyDictObject *b) bval = NULL; else bval = *vaddr; - Py_DECREF(key); if (bval == NULL) { + Py_DECREF(key); Py_DECREF(aval); if (PyErr_Occurred()) return -1; return 0; } cmp = PyObject_RichCompareBool(aval, bval, Py_EQ); + Py_DECREF(key); Py_DECREF(aval); if (cmp <= 0) /* error or not equal */ return cmp; @@ -3046,7 +3059,7 @@ PyTypeObject PyDictIterValue_Type = { static PyObject *dictiter_iternextitem(dictiterobject *di) { - PyObject *key, *value, *result = di->di_result; + PyObject *key, *value, *result; Py_ssize_t i, mask, offset; PyDictObject *d = di->di_dict; PyObject **value_ptr; @@ -3082,22 +3095,27 @@ static PyObject *dictiter_iternextitem(dictiterobject *di) if (i > mask) goto fail; - if (result->ob_refcnt == 1) { + di->len--; + key = d->ma_keys->dk_entries[i].me_key; + value = *value_ptr; + Py_INCREF(key); + Py_INCREF(value); + result = di->di_result; + if (Py_REFCNT(result) == 1) { + PyObject *oldkey = PyTuple_GET_ITEM(result, 0); + PyObject *oldvalue = PyTuple_GET_ITEM(result, 1); + PyTuple_SET_ITEM(result, 0, key); /* steals reference */ + PyTuple_SET_ITEM(result, 1, value); /* steals reference */ Py_INCREF(result); - Py_DECREF(PyTuple_GET_ITEM(result, 0)); - Py_DECREF(PyTuple_GET_ITEM(result, 1)); + Py_DECREF(oldkey); + Py_DECREF(oldvalue); } else { result = PyTuple_New(2); if (result == NULL) return NULL; + PyTuple_SET_ITEM(result, 0, key); /* steals reference */ + PyTuple_SET_ITEM(result, 1, value); /* steals reference */ } - di->len--; - key = d->ma_keys->dk_entries[i].me_key; - value = *value_ptr; - Py_INCREF(key); - Py_INCREF(value); - PyTuple_SET_ITEM(result, 0, key); - PyTuple_SET_ITEM(result, 1, value); return result; fail: @@ -3596,6 +3614,7 @@ dictitems_iter(dictviewobject *dv) static int dictitems_contains(dictviewobject *dv, PyObject *obj) { + int result; PyObject *key, *value, *found; if (dv->dv_dict == NULL) return 0; @@ -3609,7 +3628,10 @@ dictitems_contains(dictviewobject *dv, PyObject *obj) return -1; return 0; } - return PyObject_RichCompareBool(value, found, Py_EQ); + Py_INCREF(found); + result = PyObject_RichCompareBool(value, found, Py_EQ); + Py_DECREF(found); + return result; } static PySequenceMethods dictitems_as_sequence = { From 71572bbe82aa0836c036d44d41c8269ba6a321be Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 12 Jul 2017 14:41:34 +0200 Subject: [PATCH 06/24] [3.4] bpo-29591, bpo-30694: Upgrade Modules/expat to libexpat 2.2.1 (#2164) (#2203) * bpo-29591: Upgrade Modules/expat to libexpat 2.2 (#2164) * bpo-29591: Upgrade Modules/expat to libexpat 2.2 * bpo-29591: Restore Python changes on expat * bpo-29591: Remove expat config of unsupported platforms Remove the configuration (Modules/expat/*config.h) of unsupported platforms: * Amiga * MacOS Classic on PPC32 * Open Watcom * bpo-29591: Remove useless XML_HAS_SET_HASH_SALT The XML_HAS_SET_HASH_SALT define of Modules/expat/expat.h became useless since our local expat copy was upgrade to expat 2.1 (it's now expat 2.2.0). (cherry picked from commit 23ec4b57e1359f9c539b8defc317542173ae087e) * bpo-30694: Upgrade Modules/expat/ to libexpat 2.2.1 (#2300) New file: Modules/expat/siphash.h. (cherry picked from commit 5ff7132313eb651107b179d20218dfe5d4e47f13) * bpo-30726: PCbuild _elementtree: remove duplicate defines (#2348) bpo-30726, bpo-29591: libexpat 2.2.1 of Modules/expat/ now uses a winconfig.h configuration file which already defines: * XML_NS * XML_DTD * BYTEORDER=1234 * XML_CONTEXT_BYTES=1024 * HAVE_MEMMOVE Remove these defines from PCbuild/_elementtree.vcxproj to prevent compiler warnings. Co-Authored-By: Jeremy Kloth (cherry picked from commit c8fb58bd7917151e63398587a7fc2126db7c26de) * bpo-30726: Fix elementtree warnings on Windows due to expat upgrade (#2319) * bpo-30726: Fix elementtree warnings on Windows Caused by usage of `getenv` which should be safe. And a few integer truncations which should also be ok. * bpo-30726: Don't ignore libexpat warnings which haypo intends to fix upstream (cherry picked from commit 87c65550730a8f85ce339ba197bce4fb7e836619) --- .../2017-07-11-22-25-24.bpo-30694.oOf3Er.rst | 8 + .../2017-07-11-22-26-48.bpo-29591.cOeMX-.rst | 3 + Modules/expat/COPYING | 5 +- Modules/expat/amigaconfig.h | 32 - Modules/expat/expat.h | 35 +- Modules/expat/expat_external.h | 19 +- Modules/expat/internal.h | 22 + Modules/expat/macconfig.h | 53 -- Modules/expat/siphash.h | 344 +++++++++ Modules/expat/watcomconfig.h | 47 -- Modules/expat/winconfig.h | 10 + Modules/expat/xmlparse.c | 700 ++++++++++++++---- Modules/expat/xmlrole.c | 230 +++--- Modules/expat/xmltok.c | 244 ++++-- Modules/expat/xmltok.h | 10 +- Modules/expat/xmltok_impl.c | 226 +++--- Modules/pyexpat.c | 6 +- PCbuild/_elementtree.vcxproj | 4 +- 18 files changed, 1388 insertions(+), 610 deletions(-) create mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst create mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst delete mode 100644 Modules/expat/amigaconfig.h delete mode 100644 Modules/expat/macconfig.h create mode 100644 Modules/expat/siphash.h delete mode 100644 Modules/expat/watcomconfig.h diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst new file mode 100644 index 00000000000000..ee2c0a5c35b160 --- /dev/null +++ b/Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst @@ -0,0 +1,8 @@ +Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security +vulnerabilities including: CVE-2017-9233 (External entity infinite loop +DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix +regression bugs from 2.2.0's fix to CVE-2016-0718) and CVE-2012-0876 +(Counter hash flooding with SipHash). Note: the CVE-2016-5300 (Use os- +specific entropy sources like getrandom) doesn't impact Python, since Python +already gets entropy from the OS to set the expat secret using +``XML_SetHashSalt()``. diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst new file mode 100644 index 00000000000000..ca740bb1b11a6a --- /dev/null +++ b/Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst @@ -0,0 +1,3 @@ +Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and +CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more +information. diff --git a/Modules/expat/COPYING b/Modules/expat/COPYING index dcb4506429684b..8d288f0f28fddd 100644 --- a/Modules/expat/COPYING +++ b/Modules/expat/COPYING @@ -1,6 +1,5 @@ -Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd - and Clark Cooper -Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006 Expat maintainers. +Copyright (c) 1998-2000 Thai Open Source Software Center Ltd and Clark Cooper +Copyright (c) 2001-2017 Expat maintainers Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/Modules/expat/amigaconfig.h b/Modules/expat/amigaconfig.h deleted file mode 100644 index 86c611504025fb..00000000000000 --- a/Modules/expat/amigaconfig.h +++ /dev/null @@ -1,32 +0,0 @@ -#ifndef AMIGACONFIG_H -#define AMIGACONFIG_H - -/* 1234 = LIL_ENDIAN, 4321 = BIGENDIAN */ -#define BYTEORDER 4321 - -/* Define to 1 if you have the `bcopy' function. */ -#define HAVE_BCOPY 1 - -/* Define to 1 if you have the header file. */ -#undef HAVE_CHECK_H - -/* Define to 1 if you have the `memmove' function. */ -#define HAVE_MEMMOVE 1 - -/* Define to 1 if you have the header file. */ -#define HAVE_UNISTD_H 1 - -/* whether byteorder is bigendian */ -#define WORDS_BIGENDIAN - -/* Define to specify how much context to retain around the current parse - point. */ -#define XML_CONTEXT_BYTES 1024 - -/* Define to make parameter entity parsing functionality available. */ -#define XML_DTD - -/* Define to make XML Namespaces functionality available. */ -#define XML_NS - -#endif /* AMIGACONFIG_H */ diff --git a/Modules/expat/expat.h b/Modules/expat/expat.h index e8eefddc6d8474..28b0f954d41963 100644 --- a/Modules/expat/expat.h +++ b/Modules/expat/expat.h @@ -95,7 +95,9 @@ enum XML_Error { /* Added in 2.0. */ XML_ERROR_RESERVED_PREFIX_XML, XML_ERROR_RESERVED_PREFIX_XMLNS, - XML_ERROR_RESERVED_NAMESPACE_URI + XML_ERROR_RESERVED_NAMESPACE_URI, + /* Added in 2.2.1. */ + XML_ERROR_INVALID_ARGUMENT }; enum XML_Content_Type { @@ -342,7 +344,7 @@ XML_SetEntityDeclHandler(XML_Parser parser, XML_EntityDeclHandler handler); /* OBSOLETE -- OBSOLETE -- OBSOLETE - This handler has been superceded by the EntityDeclHandler above. + This handler has been superseded by the EntityDeclHandler above. It is provided here for backward compatibility. This is called for a declaration of an unparsed (NDATA) entity. @@ -706,6 +708,7 @@ XML_UseParserAsHandlerArg(XML_Parser parser); be called, despite an external subset being parsed. Note: If XML_DTD is not defined when Expat is compiled, returns XML_ERROR_FEATURE_REQUIRES_XML_DTD. + Note: If parser == NULL, returns XML_ERROR_INVALID_ARGUMENT. */ XMLPARSEAPI(enum XML_Error) XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD); @@ -729,15 +732,16 @@ XML_GetBase(XML_Parser parser); to the XML_StartElementHandler that were specified in the start-tag rather than defaulted. Each attribute/value pair counts as 2; thus this correspondds to an index into the atts array passed to the - XML_StartElementHandler. + XML_StartElementHandler. Returns -1 if parser == NULL. */ XMLPARSEAPI(int) XML_GetSpecifiedAttributeCount(XML_Parser parser); /* Returns the index of the ID attribute passed in the last call to - XML_StartElementHandler, or -1 if there is no ID attribute. Each - attribute/value pair counts as 2; thus this correspondds to an - index into the atts array passed to the XML_StartElementHandler. + XML_StartElementHandler, or -1 if there is no ID attribute or + parser == NULL. Each attribute/value pair counts as 2; thus this + correspondds to an index into the atts array passed to the + XML_StartElementHandler. */ XMLPARSEAPI(int) XML_GetIdAttributeIndex(XML_Parser parser); @@ -901,6 +905,7 @@ enum XML_ParamEntityParsing { entities is requested; otherwise it will return non-zero. Note: If XML_SetParamEntityParsing is called after XML_Parse or XML_ParseBuffer, then it has no effect and will always return 0. + Note: If parser == NULL, the function will do nothing and return 0. */ XMLPARSEAPI(int) XML_SetParamEntityParsing(XML_Parser parser, @@ -910,13 +915,12 @@ XML_SetParamEntityParsing(XML_Parser parser, Helps in preventing DoS attacks based on predicting hash function behavior. This must be called before parsing is started. Returns 1 if successful, 0 when called after parsing has started. + Note: If parser == NULL, the function will do nothing and return 0. */ XMLPARSEAPI(int) XML_SetHashSalt(XML_Parser parser, unsigned long hash_salt); -#define XML_HAS_SET_HASH_SALT /* Python Only: Defined for pyexpat.c. */ - /* If XML_Parse or XML_ParseBuffer have returned XML_STATUS_ERROR, then XML_GetErrorCode returns information about the error. */ @@ -938,6 +942,10 @@ XML_GetErrorCode(XML_Parser parser); the location is the location of the character at which the error was detected; otherwise the location is the location of the last parse event, as described above. + + Note: XML_GetCurrentLineNumber and XML_GetCurrentColumnNumber + return 0 to indicate an error. + Note: XML_GetCurrentByteIndex returns -1 to indicate an error. */ XMLPARSEAPI(XML_Size) XML_GetCurrentLineNumber(XML_Parser parser); XMLPARSEAPI(XML_Size) XML_GetCurrentColumnNumber(XML_Parser parser); @@ -975,9 +983,12 @@ XML_FreeContentModel(XML_Parser parser, XML_Content *model); /* Exposing the memory handling functions used in Expat */ XMLPARSEAPI(void *) +XML_ATTR_MALLOC +XML_ATTR_ALLOC_SIZE(2) XML_MemMalloc(XML_Parser parser, size_t size); XMLPARSEAPI(void *) +XML_ATTR_ALLOC_SIZE(3) XML_MemRealloc(XML_Parser parser, void *ptr, size_t size); XMLPARSEAPI(void) @@ -1033,13 +1044,11 @@ XMLPARSEAPI(const XML_Feature *) XML_GetFeatureList(void); -/* Expat follows the GNU/Linux convention of odd number minor version for - beta/development releases and even number minor version for stable - releases. Micro is bumped with each release, and set to 0 with each - change to major or minor version. +/* Expat follows the semantic versioning convention. + See http://semver.org. */ #define XML_MAJOR_VERSION 2 -#define XML_MINOR_VERSION 1 +#define XML_MINOR_VERSION 2 #define XML_MICRO_VERSION 1 #ifdef __cplusplus diff --git a/Modules/expat/expat_external.h b/Modules/expat/expat_external.h index f337e1c5622a95..4c9e5eabdee2ce 100644 --- a/Modules/expat/expat_external.h +++ b/Modules/expat/expat_external.h @@ -69,12 +69,26 @@ #endif #endif /* not defined XML_STATIC */ +#if !defined(XMLIMPORT) && defined(__GNUC__) && (__GNUC__ >= 4) +#define XMLIMPORT __attribute__ ((visibility ("default"))) +#endif /* If we didn't define it above, define it away: */ #ifndef XMLIMPORT #define XMLIMPORT #endif +#if defined(__GNUC__) && (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)) +#define XML_ATTR_MALLOC __attribute__((__malloc__)) +#else +#define XML_ATTR_MALLOC +#endif + +#if defined(__GNUC__) && ((__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)) +#define XML_ATTR_ALLOC_SIZE(x) __attribute__((__alloc_size__(x))) +#else +#define XML_ATTR_ALLOC_SIZE(x) +#endif #define XMLPARSEAPI(type) XMLIMPORT type XMLCALL @@ -83,7 +97,10 @@ extern "C" { #endif #ifdef XML_UNICODE_WCHAR_T -#define XML_UNICODE +# define XML_UNICODE +# if defined(__SIZEOF_WCHAR_T__) && (__SIZEOF_WCHAR_T__ != 2) +# error "sizeof(wchar_t) != 2; Need -fshort-wchar for both Expat and libc" +# endif #endif #ifdef XML_UNICODE /* Information is UTF-16 encoded. */ diff --git a/Modules/expat/internal.h b/Modules/expat/internal.h index dd5454831da2b4..94cb98e15cae40 100644 --- a/Modules/expat/internal.h +++ b/Modules/expat/internal.h @@ -71,3 +71,25 @@ #define inline #endif #endif + +#ifndef UNUSED_P +# ifdef __GNUC__ +# define UNUSED_P(p) UNUSED_ ## p __attribute__((__unused__)) +# else +# define UNUSED_P(p) UNUSED_ ## p +# endif +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + + +void +align_limit_to_full_utf8_characters(const char * from, const char ** fromLimRef); + + +#ifdef __cplusplus +} +#endif diff --git a/Modules/expat/macconfig.h b/Modules/expat/macconfig.h deleted file mode 100644 index 2725caaf54a2e2..00000000000000 --- a/Modules/expat/macconfig.h +++ /dev/null @@ -1,53 +0,0 @@ -/*================================================================ -** Copyright 2000, Clark Cooper -** All rights reserved. -** -** This is free software. You are permitted to copy, distribute, or modify -** it under the terms of the MIT/X license (contained in the COPYING file -** with this distribution.) -** -*/ - -#ifndef MACCONFIG_H -#define MACCONFIG_H - - -/* 1234 = LIL_ENDIAN, 4321 = BIGENDIAN */ -#define BYTEORDER 4321 - -/* Define to 1 if you have the `bcopy' function. */ -#undef HAVE_BCOPY - -/* Define to 1 if you have the `memmove' function. */ -#define HAVE_MEMMOVE - -/* Define to 1 if you have a working `mmap' system call. */ -#undef HAVE_MMAP - -/* Define to 1 if you have the header file. */ -#undef HAVE_UNISTD_H - -/* whether byteorder is bigendian */ -#define WORDS_BIGENDIAN - -/* Define to specify how much context to retain around the current parse - point. */ -#undef XML_CONTEXT_BYTES - -/* Define to make parameter entity parsing functionality available. */ -#define XML_DTD - -/* Define to make XML Namespaces functionality available. */ -#define XML_NS - -/* Define to empty if `const' does not conform to ANSI C. */ -#undef const - -/* Define to `long' if does not define. */ -#define off_t long - -/* Define to `unsigned' if does not define. */ -#undef size_t - - -#endif /* ifndef MACCONFIG_H */ diff --git a/Modules/expat/siphash.h b/Modules/expat/siphash.h new file mode 100644 index 00000000000000..23b56d2ae48754 --- /dev/null +++ b/Modules/expat/siphash.h @@ -0,0 +1,344 @@ +/* ========================================================================== + * siphash.h - SipHash-2-4 in a single header file + * -------------------------------------------------------------------------- + * Derived by William Ahern from the reference implementation[1] published[2] + * by Jean-Philippe Aumasson and Daniel J. Berstein. Licensed in kind. + * by Jean-Philippe Aumasson and Daniel J. Berstein. + * Minimal changes by Sebastian Pipping on top, details below. + * Licensed under the CC0 Public Domain Dedication license. + * + * 1. https://www.131002.net/siphash/siphash24.c + * 2. https://www.131002.net/siphash/ + * -------------------------------------------------------------------------- + * HISTORY: + * + * 2017-06-10 (Sebastian Pipping) + * - Clarify license note in the header + * - Address C89 issues: + * - Stop using inline keyword (and let compiler decide) + * - Turn integer suffix ULL to UL + * - Replace _Bool by int + * - Turn macro siphash24 into a function + * - Address invalid conversion (void pointer) by explicit cast + * - Always expose sip24_valid (for self-tests) + * + * 2012-11-04 - Born. (William Ahern) + * -------------------------------------------------------------------------- + * USAGE: + * + * SipHash-2-4 takes as input two 64-bit words as the key, some number of + * message bytes, and outputs a 64-bit word as the message digest. This + * implementation employs two data structures: a struct sipkey for + * representing the key, and a struct siphash for representing the hash + * state. + * + * For converting a 16-byte unsigned char array to a key, use either the + * macro sip_keyof or the routine sip_tokey. The former instantiates a + * compound literal key, while the latter requires a key object as a + * parameter. + * + * unsigned char secret[16]; + * arc4random_buf(secret, sizeof secret); + * struct sipkey *key = sip_keyof(secret); + * + * For hashing a message, use either the convenience macro siphash24 or the + * routines sip24_init, sip24_update, and sip24_final. + * + * struct siphash state; + * void *msg; + * size_t len; + * uint64_t hash; + * + * sip24_init(&state, key); + * sip24_update(&state, msg, len); + * hash = sip24_final(&state); + * + * or + * + * hash = siphash24(msg, len, key); + * + * To convert the 64-bit hash value to a canonical 8-byte little-endian + * binary representation, use either the macro sip_binof or the routine + * sip_tobin. The former instantiates and returns a compound literal array, + * while the latter requires an array object as a parameter. + * -------------------------------------------------------------------------- + * NOTES: + * + * o Neither sip_keyof, sip_binof, nor siphash24 will work with compilers + * lacking compound literal support. Instead, you must use the lower-level + * interfaces which take as parameters the temporary state objects. + * + * o Uppercase macros may evaluate parameters more than once. Lowercase + * macros should not exhibit any such side effects. + * ========================================================================== + */ +#ifndef SIPHASH_H +#define SIPHASH_H + +#include /* size_t */ +#include /* uint64_t uint32_t uint8_t */ + + +#define SIP_ROTL(x, b) (uint64_t)(((x) << (b)) | ( (x) >> (64 - (b)))) + +#define SIP_U32TO8_LE(p, v) \ + (p)[0] = (uint8_t)((v) >> 0); (p)[1] = (uint8_t)((v) >> 8); \ + (p)[2] = (uint8_t)((v) >> 16); (p)[3] = (uint8_t)((v) >> 24); + +#define SIP_U64TO8_LE(p, v) \ + SIP_U32TO8_LE((p) + 0, (uint32_t)((v) >> 0)); \ + SIP_U32TO8_LE((p) + 4, (uint32_t)((v) >> 32)); + +#define SIP_U8TO64_LE(p) \ + (((uint64_t)((p)[0]) << 0) | \ + ((uint64_t)((p)[1]) << 8) | \ + ((uint64_t)((p)[2]) << 16) | \ + ((uint64_t)((p)[3]) << 24) | \ + ((uint64_t)((p)[4]) << 32) | \ + ((uint64_t)((p)[5]) << 40) | \ + ((uint64_t)((p)[6]) << 48) | \ + ((uint64_t)((p)[7]) << 56)) + + +#define SIPHASH_INITIALIZER { 0, 0, 0, 0, { 0 }, 0, 0 } + +struct siphash { + uint64_t v0, v1, v2, v3; + + unsigned char buf[8], *p; + uint64_t c; +}; /* struct siphash */ + + +#define SIP_KEYLEN 16 + +struct sipkey { + uint64_t k[2]; +}; /* struct sipkey */ + +#define sip_keyof(k) sip_tokey(&(struct sipkey){ { 0 } }, (k)) + +static struct sipkey *sip_tokey(struct sipkey *key, const void *src) { + key->k[0] = SIP_U8TO64_LE((const unsigned char *)src); + key->k[1] = SIP_U8TO64_LE((const unsigned char *)src + 8); + return key; +} /* sip_tokey() */ + + +#define sip_binof(v) sip_tobin((unsigned char[8]){ 0 }, (v)) + +static void *sip_tobin(void *dst, uint64_t u64) { + SIP_U64TO8_LE((unsigned char *)dst, u64); + return dst; +} /* sip_tobin() */ + + +static void sip_round(struct siphash *H, const int rounds) { + int i; + + for (i = 0; i < rounds; i++) { + H->v0 += H->v1; + H->v1 = SIP_ROTL(H->v1, 13); + H->v1 ^= H->v0; + H->v0 = SIP_ROTL(H->v0, 32); + + H->v2 += H->v3; + H->v3 = SIP_ROTL(H->v3, 16); + H->v3 ^= H->v2; + + H->v0 += H->v3; + H->v3 = SIP_ROTL(H->v3, 21); + H->v3 ^= H->v0; + + H->v2 += H->v1; + H->v1 = SIP_ROTL(H->v1, 17); + H->v1 ^= H->v2; + H->v2 = SIP_ROTL(H->v2, 32); + } +} /* sip_round() */ + + +static struct siphash *sip24_init(struct siphash *H, const struct sipkey *key) { + H->v0 = 0x736f6d6570736575UL ^ key->k[0]; + H->v1 = 0x646f72616e646f6dUL ^ key->k[1]; + H->v2 = 0x6c7967656e657261UL ^ key->k[0]; + H->v3 = 0x7465646279746573UL ^ key->k[1]; + + H->p = H->buf; + H->c = 0; + + return H; +} /* sip24_init() */ + + +#define sip_endof(a) (&(a)[sizeof (a) / sizeof *(a)]) + +static struct siphash *sip24_update(struct siphash *H, const void *src, size_t len) { + const unsigned char *p = (const unsigned char *)src, *pe = p + len; + uint64_t m; + + do { + while (p < pe && H->p < sip_endof(H->buf)) + *H->p++ = *p++; + + if (H->p < sip_endof(H->buf)) + break; + + m = SIP_U8TO64_LE(H->buf); + H->v3 ^= m; + sip_round(H, 2); + H->v0 ^= m; + + H->p = H->buf; + H->c += 8; + } while (p < pe); + + return H; +} /* sip24_update() */ + + +static uint64_t sip24_final(struct siphash *H) { + char left = H->p - H->buf; + uint64_t b = (H->c + left) << 56; + + switch (left) { + case 7: b |= (uint64_t)H->buf[6] << 48; + case 6: b |= (uint64_t)H->buf[5] << 40; + case 5: b |= (uint64_t)H->buf[4] << 32; + case 4: b |= (uint64_t)H->buf[3] << 24; + case 3: b |= (uint64_t)H->buf[2] << 16; + case 2: b |= (uint64_t)H->buf[1] << 8; + case 1: b |= (uint64_t)H->buf[0] << 0; + case 0: break; + } + + H->v3 ^= b; + sip_round(H, 2); + H->v0 ^= b; + H->v2 ^= 0xff; + sip_round(H, 4); + + return H->v0 ^ H->v1 ^ H->v2 ^ H->v3; +} /* sip24_final() */ + + +static uint64_t siphash24(const void *src, size_t len, const struct sipkey *key) { + struct siphash state = SIPHASH_INITIALIZER; + return sip24_final(sip24_update(sip24_init(&state, key), src, len)); +} /* siphash24() */ + + +/* + * SipHash-2-4 output with + * k = 00 01 02 ... + * and + * in = (empty string) + * in = 00 (1 byte) + * in = 00 01 (2 bytes) + * in = 00 01 02 (3 bytes) + * ... + * in = 00 01 02 ... 3e (63 bytes) + */ +static int sip24_valid(void) { + static const unsigned char vectors[64][8] = { + { 0x31, 0x0e, 0x0e, 0xdd, 0x47, 0xdb, 0x6f, 0x72, }, + { 0xfd, 0x67, 0xdc, 0x93, 0xc5, 0x39, 0xf8, 0x74, }, + { 0x5a, 0x4f, 0xa9, 0xd9, 0x09, 0x80, 0x6c, 0x0d, }, + { 0x2d, 0x7e, 0xfb, 0xd7, 0x96, 0x66, 0x67, 0x85, }, + { 0xb7, 0x87, 0x71, 0x27, 0xe0, 0x94, 0x27, 0xcf, }, + { 0x8d, 0xa6, 0x99, 0xcd, 0x64, 0x55, 0x76, 0x18, }, + { 0xce, 0xe3, 0xfe, 0x58, 0x6e, 0x46, 0xc9, 0xcb, }, + { 0x37, 0xd1, 0x01, 0x8b, 0xf5, 0x00, 0x02, 0xab, }, + { 0x62, 0x24, 0x93, 0x9a, 0x79, 0xf5, 0xf5, 0x93, }, + { 0xb0, 0xe4, 0xa9, 0x0b, 0xdf, 0x82, 0x00, 0x9e, }, + { 0xf3, 0xb9, 0xdd, 0x94, 0xc5, 0xbb, 0x5d, 0x7a, }, + { 0xa7, 0xad, 0x6b, 0x22, 0x46, 0x2f, 0xb3, 0xf4, }, + { 0xfb, 0xe5, 0x0e, 0x86, 0xbc, 0x8f, 0x1e, 0x75, }, + { 0x90, 0x3d, 0x84, 0xc0, 0x27, 0x56, 0xea, 0x14, }, + { 0xee, 0xf2, 0x7a, 0x8e, 0x90, 0xca, 0x23, 0xf7, }, + { 0xe5, 0x45, 0xbe, 0x49, 0x61, 0xca, 0x29, 0xa1, }, + { 0xdb, 0x9b, 0xc2, 0x57, 0x7f, 0xcc, 0x2a, 0x3f, }, + { 0x94, 0x47, 0xbe, 0x2c, 0xf5, 0xe9, 0x9a, 0x69, }, + { 0x9c, 0xd3, 0x8d, 0x96, 0xf0, 0xb3, 0xc1, 0x4b, }, + { 0xbd, 0x61, 0x79, 0xa7, 0x1d, 0xc9, 0x6d, 0xbb, }, + { 0x98, 0xee, 0xa2, 0x1a, 0xf2, 0x5c, 0xd6, 0xbe, }, + { 0xc7, 0x67, 0x3b, 0x2e, 0xb0, 0xcb, 0xf2, 0xd0, }, + { 0x88, 0x3e, 0xa3, 0xe3, 0x95, 0x67, 0x53, 0x93, }, + { 0xc8, 0xce, 0x5c, 0xcd, 0x8c, 0x03, 0x0c, 0xa8, }, + { 0x94, 0xaf, 0x49, 0xf6, 0xc6, 0x50, 0xad, 0xb8, }, + { 0xea, 0xb8, 0x85, 0x8a, 0xde, 0x92, 0xe1, 0xbc, }, + { 0xf3, 0x15, 0xbb, 0x5b, 0xb8, 0x35, 0xd8, 0x17, }, + { 0xad, 0xcf, 0x6b, 0x07, 0x63, 0x61, 0x2e, 0x2f, }, + { 0xa5, 0xc9, 0x1d, 0xa7, 0xac, 0xaa, 0x4d, 0xde, }, + { 0x71, 0x65, 0x95, 0x87, 0x66, 0x50, 0xa2, 0xa6, }, + { 0x28, 0xef, 0x49, 0x5c, 0x53, 0xa3, 0x87, 0xad, }, + { 0x42, 0xc3, 0x41, 0xd8, 0xfa, 0x92, 0xd8, 0x32, }, + { 0xce, 0x7c, 0xf2, 0x72, 0x2f, 0x51, 0x27, 0x71, }, + { 0xe3, 0x78, 0x59, 0xf9, 0x46, 0x23, 0xf3, 0xa7, }, + { 0x38, 0x12, 0x05, 0xbb, 0x1a, 0xb0, 0xe0, 0x12, }, + { 0xae, 0x97, 0xa1, 0x0f, 0xd4, 0x34, 0xe0, 0x15, }, + { 0xb4, 0xa3, 0x15, 0x08, 0xbe, 0xff, 0x4d, 0x31, }, + { 0x81, 0x39, 0x62, 0x29, 0xf0, 0x90, 0x79, 0x02, }, + { 0x4d, 0x0c, 0xf4, 0x9e, 0xe5, 0xd4, 0xdc, 0xca, }, + { 0x5c, 0x73, 0x33, 0x6a, 0x76, 0xd8, 0xbf, 0x9a, }, + { 0xd0, 0xa7, 0x04, 0x53, 0x6b, 0xa9, 0x3e, 0x0e, }, + { 0x92, 0x59, 0x58, 0xfc, 0xd6, 0x42, 0x0c, 0xad, }, + { 0xa9, 0x15, 0xc2, 0x9b, 0xc8, 0x06, 0x73, 0x18, }, + { 0x95, 0x2b, 0x79, 0xf3, 0xbc, 0x0a, 0xa6, 0xd4, }, + { 0xf2, 0x1d, 0xf2, 0xe4, 0x1d, 0x45, 0x35, 0xf9, }, + { 0x87, 0x57, 0x75, 0x19, 0x04, 0x8f, 0x53, 0xa9, }, + { 0x10, 0xa5, 0x6c, 0xf5, 0xdf, 0xcd, 0x9a, 0xdb, }, + { 0xeb, 0x75, 0x09, 0x5c, 0xcd, 0x98, 0x6c, 0xd0, }, + { 0x51, 0xa9, 0xcb, 0x9e, 0xcb, 0xa3, 0x12, 0xe6, }, + { 0x96, 0xaf, 0xad, 0xfc, 0x2c, 0xe6, 0x66, 0xc7, }, + { 0x72, 0xfe, 0x52, 0x97, 0x5a, 0x43, 0x64, 0xee, }, + { 0x5a, 0x16, 0x45, 0xb2, 0x76, 0xd5, 0x92, 0xa1, }, + { 0xb2, 0x74, 0xcb, 0x8e, 0xbf, 0x87, 0x87, 0x0a, }, + { 0x6f, 0x9b, 0xb4, 0x20, 0x3d, 0xe7, 0xb3, 0x81, }, + { 0xea, 0xec, 0xb2, 0xa3, 0x0b, 0x22, 0xa8, 0x7f, }, + { 0x99, 0x24, 0xa4, 0x3c, 0xc1, 0x31, 0x57, 0x24, }, + { 0xbd, 0x83, 0x8d, 0x3a, 0xaf, 0xbf, 0x8d, 0xb7, }, + { 0x0b, 0x1a, 0x2a, 0x32, 0x65, 0xd5, 0x1a, 0xea, }, + { 0x13, 0x50, 0x79, 0xa3, 0x23, 0x1c, 0xe6, 0x60, }, + { 0x93, 0x2b, 0x28, 0x46, 0xe4, 0xd7, 0x06, 0x66, }, + { 0xe1, 0x91, 0x5f, 0x5c, 0xb1, 0xec, 0xa4, 0x6c, }, + { 0xf3, 0x25, 0x96, 0x5c, 0xa1, 0x6d, 0x62, 0x9f, }, + { 0x57, 0x5f, 0xf2, 0x8e, 0x60, 0x38, 0x1b, 0xe5, }, + { 0x72, 0x45, 0x06, 0xeb, 0x4c, 0x32, 0x8a, 0x95, } + }; + unsigned char in[64]; + struct sipkey k; + size_t i; + + sip_tokey(&k, "\000\001\002\003\004\005\006\007\010\011\012\013\014\015\016\017"); + + for (i = 0; i < sizeof in; ++i) { + in[i] = i; + + if (siphash24(in, i, &k) != SIP_U8TO64_LE(vectors[i])) + return 0; + } + + return 1; +} /* sip24_valid() */ + + +#if SIPHASH_MAIN + +#include + +int main(void) { + int ok = sip24_valid(); + + if (ok) + puts("OK"); + else + puts("FAIL"); + + return !ok; +} /* main() */ + +#endif /* SIPHASH_MAIN */ + + +#endif /* SIPHASH_H */ diff --git a/Modules/expat/watcomconfig.h b/Modules/expat/watcomconfig.h deleted file mode 100644 index 2f05e3f227c162..00000000000000 --- a/Modules/expat/watcomconfig.h +++ /dev/null @@ -1,47 +0,0 @@ -/* expat_config.h for use with Open Watcom 1.5 and above. */ - -#ifndef WATCOMCONFIG_H -#define WATCOMCONFIG_H - -#ifdef __NT__ -#define WIN32_LEAN_AND_MEAN -#include -#undef WIN32_LEAN_AND_MEAN -#endif - -/* 1234 = LIL_ENDIAN, 4321 = BIGENDIAN */ -#define BYTEORDER 1234 - -/* Define to 1 if you have the `memmove' function. */ -#define HAVE_MEMMOVE 1 - -/* Define to 1 if you have the header file. */ -#define HAVE_UNISTD_H 1 - -/* Define to the address where bug reports for this package should be sent. */ -#define PACKAGE_BUGREPORT "expat-bugs@mail.libexpat.org" - -/* Define to the full name of this package. */ -#define PACKAGE_NAME "expat" - -/* Define to the full name and version of this package. */ -#define PACKAGE_STRING "expat 2.0.0" - -/* Define to the one symbol short name of this package. */ -#undef PACKAGE_TARNAME - -/* Define to the version of this package. */ -#define PACKAGE_VERSION "2.0.0" - -/* Define to specify how much context to retain around the current parse - point. */ -#define XML_CONTEXT_BYTES 1024 - -/* Define to make parameter entity parsing functionality available. */ -#define XML_DTD 1 - -/* Define to make XML Namespaces functionality available. */ -#define XML_NS 1 - -#endif - diff --git a/Modules/expat/winconfig.h b/Modules/expat/winconfig.h index c1b791d62d0d0c..9bf014d7fbabd6 100644 --- a/Modules/expat/winconfig.h +++ b/Modules/expat/winconfig.h @@ -17,6 +17,12 @@ #include #include + +#if defined(HAVE_EXPAT_CONFIG_H) /* e.g. MinGW */ +# include +#else /* !defined(HAVE_EXPAT_CONFIG_H) */ + + #define XML_NS 1 #define XML_DTD 1 #define XML_CONTEXT_BYTES 1024 @@ -27,4 +33,8 @@ /* Windows has memmove() available. */ #define HAVE_MEMMOVE + +#endif /* !defined(HAVE_EXPAT_CONFIG_H) */ + + #endif /* ndef WINCONFIG_H */ diff --git a/Modules/expat/xmlparse.c b/Modules/expat/xmlparse.c index 412838794d703b..76f078e2505f90 100644 --- a/Modules/expat/xmlparse.c +++ b/Modules/expat/xmlparse.c @@ -1,29 +1,37 @@ /* Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd See the file COPYING for copying permission. -*/ -#define XML_BUILDING_EXPAT 1 + 77fea421d361dca90041d0040ecf1dca651167fadf2af79e990e35168d70d933 (2.2.1+) +*/ -#ifdef COMPILED_FROM_DSP -#include "winconfig.h" -#elif defined(MACOS_CLASSIC) -#include "macconfig.h" -#elif defined(__amigaos__) -#include "amigaconfig.h" -#elif defined(__WATCOMC__) -#include "watcomconfig.h" -#elif defined(HAVE_EXPAT_CONFIG_H) -#include -#endif /* ndef COMPILED_FROM_DSP */ +#define _GNU_SOURCE /* syscall prototype */ #include #include /* memset(), memcpy() */ #include #include /* UINT_MAX */ -#include /* time() */ +#include /* fprintf */ +#include /* getenv */ + +#ifdef _WIN32 +#define getpid GetCurrentProcessId +#else +#include /* gettimeofday() */ +#include /* getpid() */ +#include /* getpid() */ +#endif + +#define XML_BUILDING_EXPAT 1 + +#ifdef _WIN32 +#include "winconfig.h" +#elif defined(HAVE_EXPAT_CONFIG_H) +#include +#endif /* ndef _WIN32 */ #include "ascii.h" #include "expat.h" +#include "siphash.h" #ifdef XML_UNICODE #define XML_ENCODE_MAX XML_UTF16_ENCODE_MAX @@ -102,17 +110,11 @@ typedef struct { const XML_Memory_Handling_Suite *mem; } HASH_TABLE; -/* Basic character hash algorithm, taken from Python's string hash: - h = h * 1000003 ^ character, the constant being a prime number. +static size_t +keylen(KEY s); -*/ -#ifdef XML_UNICODE -#define CHAR_HASH(h, c) \ - (((h) * 0xF4243) ^ (unsigned short)(c)) -#else -#define CHAR_HASH(h, c) \ - (((h) * 0xF4243) ^ (unsigned char)(c)) -#endif +static void +copy_salt_to_sipkey(XML_Parser parser, struct sipkey * key); /* For probing (after a collision) we need a step size relative prime to the hash table size, which is a power of 2. We use double-hashing, @@ -348,6 +350,8 @@ doIgnoreSection(XML_Parser parser, const ENCODING *, const char **startPtr, const char *end, const char **nextPtr, XML_Bool haveMore); #endif /* XML_DTD */ +static void +freeBindings(XML_Parser parser, BINDING *bindings); static enum XML_Error storeAtts(XML_Parser parser, const ENCODING *, const char *s, TAG_NAME *tagNamePtr, BINDING **bindingsPtr); @@ -432,7 +436,7 @@ static ELEMENT_TYPE * getElementType(XML_Parser parser, const ENCODING *enc, const char *ptr, const char *end); -static unsigned long generate_hash_secret_salt(void); +static unsigned long generate_hash_secret_salt(XML_Parser parser); static XML_Bool startParsing(XML_Parser parser); static XML_Parser @@ -690,12 +694,155 @@ static const XML_Char implicitContext[] = { ASCII_s, ASCII_p, ASCII_a, ASCII_c, ASCII_e, '\0' }; + +#if defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) +# include + +# if defined(HAVE_GETRANDOM) +# include /* getrandom */ +# else +# include /* syscall */ +# include /* SYS_getrandom */ +# endif + +/* Obtain entropy on Linux 3.17+ */ +static int +writeRandomBytes_getrandom(void * target, size_t count) { + int success = 0; /* full count bytes written? */ + size_t bytesWrittenTotal = 0; + const unsigned int getrandomFlags = 0; + + do { + void * const currentTarget = (void*)((char*)target + bytesWrittenTotal); + const size_t bytesToWrite = count - bytesWrittenTotal; + + const int bytesWrittenMore = +#if defined(HAVE_GETRANDOM) + getrandom(currentTarget, bytesToWrite, getrandomFlags); +#else + syscall(SYS_getrandom, currentTarget, bytesToWrite, getrandomFlags); +#endif + + if (bytesWrittenMore > 0) { + bytesWrittenTotal += bytesWrittenMore; + if (bytesWrittenTotal >= count) + success = 1; + } + } while (! success && (errno == EINTR || errno == EAGAIN)); + + return success; +} + +#endif /* defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) */ + + +#ifdef _WIN32 + +typedef BOOLEAN (APIENTRY *RTLGENRANDOM_FUNC)(PVOID, ULONG); + +/* Obtain entropy on Windows XP / Windows Server 2003 and later. + * Hint on RtlGenRandom and the following article from libsodioum. + * + * Michael Howard: Cryptographically Secure Random number on Windows without using CryptoAPI + * https://blogs.msdn.microsoft.com/michael_howard/2005/01/14/cryptographically-secure-random-number-on-windows-without-using-cryptoapi/ + */ +static int +writeRandomBytes_RtlGenRandom(void * target, size_t count) { + int success = 0; /* full count bytes written? */ + const HMODULE advapi32 = LoadLibrary("ADVAPI32.DLL"); + + if (advapi32) { + const RTLGENRANDOM_FUNC RtlGenRandom + = (RTLGENRANDOM_FUNC)GetProcAddress(advapi32, "SystemFunction036"); + if (RtlGenRandom) { + if (RtlGenRandom((PVOID)target, (ULONG)count) == TRUE) { + success = 1; + } + } + FreeLibrary(advapi32); + } + + return success; +} + +#endif /* _WIN32 */ + + static unsigned long -generate_hash_secret_salt(void) +gather_time_entropy(void) { - unsigned int seed = time(NULL) % UINT_MAX; - srand(seed); - return rand(); +#ifdef _WIN32 + FILETIME ft; + GetSystemTimeAsFileTime(&ft); /* never fails */ + return ft.dwHighDateTime ^ ft.dwLowDateTime; +#else + struct timeval tv; + int gettimeofday_res; + + gettimeofday_res = gettimeofday(&tv, NULL); + assert (gettimeofday_res == 0); + + /* Microseconds time is <20 bits entropy */ + return tv.tv_usec; +#endif +} + +#if defined(HAVE_ARC4RANDOM_BUF) && defined(HAVE_LIBBSD) +# include +#endif + +static unsigned long +ENTROPY_DEBUG(const char * label, unsigned long entropy) { + const char * const EXPAT_ENTROPY_DEBUG = getenv("EXPAT_ENTROPY_DEBUG"); + if (EXPAT_ENTROPY_DEBUG && ! strcmp(EXPAT_ENTROPY_DEBUG, "1")) { + fprintf(stderr, "Entropy: %s --> 0x%0*lx (%lu bytes)\n", + label, + (int)sizeof(entropy) * 2, entropy, + (unsigned long)sizeof(entropy)); + } + return entropy; +} + +static unsigned long +generate_hash_secret_salt(XML_Parser parser) +{ + unsigned long entropy; + (void)parser; +#if defined(HAVE_ARC4RANDOM_BUF) || defined(__CloudABI__) + (void)gather_time_entropy; + arc4random_buf(&entropy, sizeof(entropy)); + return ENTROPY_DEBUG("arc4random_buf", entropy); +#else + /* Try high quality providers first .. */ +#ifdef _WIN32 + if (writeRandomBytes_RtlGenRandom((void *)&entropy, sizeof(entropy))) { + return ENTROPY_DEBUG("RtlGenRandom", entropy); + } +#elif defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) + if (writeRandomBytes_getrandom((void *)&entropy, sizeof(entropy))) { + return ENTROPY_DEBUG("getrandom", entropy); + } +#endif + /* .. and self-made low quality for backup: */ + + /* Process ID is 0 bits entropy if attacker has local access */ + entropy = gather_time_entropy() ^ getpid(); + + /* Factors are 2^31-1 and 2^61-1 (Mersenne primes M31 and M61) */ + if (sizeof(unsigned long) == 4) { + return ENTROPY_DEBUG("fallback(4)", entropy * 2147483647); + } else { + return ENTROPY_DEBUG("fallback(8)", + entropy * (unsigned long)2305843009213693951); + } +#endif +} + +static unsigned long +get_hash_secret_salt(XML_Parser parser) { + if (parser->m_parentParser != NULL) + return get_hash_secret_salt(parser->m_parentParser); + return parser->m_hash_secret_salt; } static XML_Bool /* only valid for root parser */ @@ -703,7 +850,7 @@ startParsing(XML_Parser parser) { /* hash functions must be initialized before setContext() is called */ if (hash_secret_salt == 0) - hash_secret_salt = generate_hash_secret_salt(); + hash_secret_salt = generate_hash_secret_salt(parser); if (ns) { /* implicit context only set for root parser, since child parsers (i.e. external entity parsers) will inherit it @@ -926,6 +1073,10 @@ XML_ParserReset(XML_Parser parser, const XML_Char *encodingName) { TAG *tStk; OPEN_INTERNAL_ENTITY *openEntityList; + + if (parser == NULL) + return XML_FALSE; + if (parentParser) return XML_FALSE; /* move tagStack to freeTagList */ @@ -960,6 +1111,8 @@ XML_ParserReset(XML_Parser parser, const XML_Char *encodingName) enum XML_Status XMLCALL XML_SetEncoding(XML_Parser parser, const XML_Char *encodingName) { + if (parser == NULL) + return XML_STATUS_ERROR; /* Block after XML_Parse()/XML_ParseBuffer() has been called. XXX There's no way for the caller to determine which of the XXX possible error cases caused the XML_STATUS_ERROR return. @@ -983,52 +1136,88 @@ XML_ExternalEntityParserCreate(XML_Parser oldParser, { XML_Parser parser = oldParser; DTD *newDtd = NULL; - DTD *oldDtd = _dtd; - XML_StartElementHandler oldStartElementHandler = startElementHandler; - XML_EndElementHandler oldEndElementHandler = endElementHandler; - XML_CharacterDataHandler oldCharacterDataHandler = characterDataHandler; - XML_ProcessingInstructionHandler oldProcessingInstructionHandler - = processingInstructionHandler; - XML_CommentHandler oldCommentHandler = commentHandler; - XML_StartCdataSectionHandler oldStartCdataSectionHandler - = startCdataSectionHandler; - XML_EndCdataSectionHandler oldEndCdataSectionHandler - = endCdataSectionHandler; - XML_DefaultHandler oldDefaultHandler = defaultHandler; - XML_UnparsedEntityDeclHandler oldUnparsedEntityDeclHandler - = unparsedEntityDeclHandler; - XML_NotationDeclHandler oldNotationDeclHandler = notationDeclHandler; - XML_StartNamespaceDeclHandler oldStartNamespaceDeclHandler - = startNamespaceDeclHandler; - XML_EndNamespaceDeclHandler oldEndNamespaceDeclHandler - = endNamespaceDeclHandler; - XML_NotStandaloneHandler oldNotStandaloneHandler = notStandaloneHandler; - XML_ExternalEntityRefHandler oldExternalEntityRefHandler - = externalEntityRefHandler; - XML_SkippedEntityHandler oldSkippedEntityHandler = skippedEntityHandler; - XML_UnknownEncodingHandler oldUnknownEncodingHandler - = unknownEncodingHandler; - XML_ElementDeclHandler oldElementDeclHandler = elementDeclHandler; - XML_AttlistDeclHandler oldAttlistDeclHandler = attlistDeclHandler; - XML_EntityDeclHandler oldEntityDeclHandler = entityDeclHandler; - XML_XmlDeclHandler oldXmlDeclHandler = xmlDeclHandler; - ELEMENT_TYPE * oldDeclElementType = declElementType; - - void *oldUserData = userData; - void *oldHandlerArg = handlerArg; - XML_Bool oldDefaultExpandInternalEntities = defaultExpandInternalEntities; - XML_Parser oldExternalEntityRefHandlerArg = externalEntityRefHandlerArg; + DTD *oldDtd; + XML_StartElementHandler oldStartElementHandler; + XML_EndElementHandler oldEndElementHandler; + XML_CharacterDataHandler oldCharacterDataHandler; + XML_ProcessingInstructionHandler oldProcessingInstructionHandler; + XML_CommentHandler oldCommentHandler; + XML_StartCdataSectionHandler oldStartCdataSectionHandler; + XML_EndCdataSectionHandler oldEndCdataSectionHandler; + XML_DefaultHandler oldDefaultHandler; + XML_UnparsedEntityDeclHandler oldUnparsedEntityDeclHandler; + XML_NotationDeclHandler oldNotationDeclHandler; + XML_StartNamespaceDeclHandler oldStartNamespaceDeclHandler; + XML_EndNamespaceDeclHandler oldEndNamespaceDeclHandler; + XML_NotStandaloneHandler oldNotStandaloneHandler; + XML_ExternalEntityRefHandler oldExternalEntityRefHandler; + XML_SkippedEntityHandler oldSkippedEntityHandler; + XML_UnknownEncodingHandler oldUnknownEncodingHandler; + XML_ElementDeclHandler oldElementDeclHandler; + XML_AttlistDeclHandler oldAttlistDeclHandler; + XML_EntityDeclHandler oldEntityDeclHandler; + XML_XmlDeclHandler oldXmlDeclHandler; + ELEMENT_TYPE * oldDeclElementType; + + void *oldUserData; + void *oldHandlerArg; + XML_Bool oldDefaultExpandInternalEntities; + XML_Parser oldExternalEntityRefHandlerArg; #ifdef XML_DTD - enum XML_ParamEntityParsing oldParamEntityParsing = paramEntityParsing; - int oldInEntityValue = prologState.inEntityValue; + enum XML_ParamEntityParsing oldParamEntityParsing; + int oldInEntityValue; +#endif + XML_Bool oldns_triplets; + /* Note that the new parser shares the same hash secret as the old + parser, so that dtdCopy and copyEntityTable can lookup values + from hash tables associated with either parser without us having + to worry which hash secrets each table has. + */ + unsigned long oldhash_secret_salt; + + /* Validate the oldParser parameter before we pull everything out of it */ + if (oldParser == NULL) + return NULL; + + /* Stash the original parser contents on the stack */ + oldDtd = _dtd; + oldStartElementHandler = startElementHandler; + oldEndElementHandler = endElementHandler; + oldCharacterDataHandler = characterDataHandler; + oldProcessingInstructionHandler = processingInstructionHandler; + oldCommentHandler = commentHandler; + oldStartCdataSectionHandler = startCdataSectionHandler; + oldEndCdataSectionHandler = endCdataSectionHandler; + oldDefaultHandler = defaultHandler; + oldUnparsedEntityDeclHandler = unparsedEntityDeclHandler; + oldNotationDeclHandler = notationDeclHandler; + oldStartNamespaceDeclHandler = startNamespaceDeclHandler; + oldEndNamespaceDeclHandler = endNamespaceDeclHandler; + oldNotStandaloneHandler = notStandaloneHandler; + oldExternalEntityRefHandler = externalEntityRefHandler; + oldSkippedEntityHandler = skippedEntityHandler; + oldUnknownEncodingHandler = unknownEncodingHandler; + oldElementDeclHandler = elementDeclHandler; + oldAttlistDeclHandler = attlistDeclHandler; + oldEntityDeclHandler = entityDeclHandler; + oldXmlDeclHandler = xmlDeclHandler; + oldDeclElementType = declElementType; + + oldUserData = userData; + oldHandlerArg = handlerArg; + oldDefaultExpandInternalEntities = defaultExpandInternalEntities; + oldExternalEntityRefHandlerArg = externalEntityRefHandlerArg; +#ifdef XML_DTD + oldParamEntityParsing = paramEntityParsing; + oldInEntityValue = prologState.inEntityValue; #endif - XML_Bool oldns_triplets = ns_triplets; + oldns_triplets = ns_triplets; /* Note that the new parser shares the same hash secret as the old parser, so that dtdCopy and copyEntityTable can lookup values from hash tables associated with either parser without us having to worry which hash secrets each table has. */ - unsigned long oldhash_secret_salt = hash_secret_salt; + oldhash_secret_salt = hash_secret_salt; #ifdef XML_DTD if (!context) @@ -1194,12 +1383,15 @@ XML_ParserFree(XML_Parser parser) void XMLCALL XML_UseParserAsHandlerArg(XML_Parser parser) { - handlerArg = parser; + if (parser != NULL) + handlerArg = parser; } enum XML_Error XMLCALL XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD) { + if (parser == NULL) + return XML_ERROR_INVALID_ARGUMENT; #ifdef XML_DTD /* block after XML_Parse()/XML_ParseBuffer() has been called */ if (ps_parsing == XML_PARSING || ps_parsing == XML_SUSPENDED) @@ -1214,6 +1406,8 @@ XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD) void XMLCALL XML_SetReturnNSTriplet(XML_Parser parser, int do_nst) { + if (parser == NULL) + return; /* block after XML_Parse()/XML_ParseBuffer() has been called */ if (ps_parsing == XML_PARSING || ps_parsing == XML_SUSPENDED) return; @@ -1223,6 +1417,8 @@ XML_SetReturnNSTriplet(XML_Parser parser, int do_nst) void XMLCALL XML_SetUserData(XML_Parser parser, void *p) { + if (parser == NULL) + return; if (handlerArg == userData) handlerArg = userData = p; else @@ -1232,6 +1428,8 @@ XML_SetUserData(XML_Parser parser, void *p) enum XML_Status XMLCALL XML_SetBase(XML_Parser parser, const XML_Char *p) { + if (parser == NULL) + return XML_STATUS_ERROR; if (p) { p = poolCopyString(&_dtd->pool, p); if (!p) @@ -1246,18 +1444,24 @@ XML_SetBase(XML_Parser parser, const XML_Char *p) const XML_Char * XMLCALL XML_GetBase(XML_Parser parser) { + if (parser == NULL) + return NULL; return curBase; } int XMLCALL XML_GetSpecifiedAttributeCount(XML_Parser parser) { + if (parser == NULL) + return -1; return nSpecifiedAtts; } int XMLCALL XML_GetIdAttributeIndex(XML_Parser parser) { + if (parser == NULL) + return -1; return idAttIndex; } @@ -1265,6 +1469,8 @@ XML_GetIdAttributeIndex(XML_Parser parser) const XML_AttrInfo * XMLCALL XML_GetAttributeInfo(XML_Parser parser) { + if (parser == NULL) + return NULL; return attInfo; } #endif @@ -1274,6 +1480,8 @@ XML_SetElementHandler(XML_Parser parser, XML_StartElementHandler start, XML_EndElementHandler end) { + if (parser == NULL) + return; startElementHandler = start; endElementHandler = end; } @@ -1281,34 +1489,39 @@ XML_SetElementHandler(XML_Parser parser, void XMLCALL XML_SetStartElementHandler(XML_Parser parser, XML_StartElementHandler start) { - startElementHandler = start; + if (parser != NULL) + startElementHandler = start; } void XMLCALL XML_SetEndElementHandler(XML_Parser parser, XML_EndElementHandler end) { - endElementHandler = end; + if (parser != NULL) + endElementHandler = end; } void XMLCALL XML_SetCharacterDataHandler(XML_Parser parser, XML_CharacterDataHandler handler) { - characterDataHandler = handler; + if (parser != NULL) + characterDataHandler = handler; } void XMLCALL XML_SetProcessingInstructionHandler(XML_Parser parser, XML_ProcessingInstructionHandler handler) { - processingInstructionHandler = handler; + if (parser != NULL) + processingInstructionHandler = handler; } void XMLCALL XML_SetCommentHandler(XML_Parser parser, XML_CommentHandler handler) { - commentHandler = handler; + if (parser != NULL) + commentHandler = handler; } void XMLCALL @@ -1316,6 +1529,8 @@ XML_SetCdataSectionHandler(XML_Parser parser, XML_StartCdataSectionHandler start, XML_EndCdataSectionHandler end) { + if (parser == NULL) + return; startCdataSectionHandler = start; endCdataSectionHandler = end; } @@ -1323,19 +1538,23 @@ XML_SetCdataSectionHandler(XML_Parser parser, void XMLCALL XML_SetStartCdataSectionHandler(XML_Parser parser, XML_StartCdataSectionHandler start) { - startCdataSectionHandler = start; + if (parser != NULL) + startCdataSectionHandler = start; } void XMLCALL XML_SetEndCdataSectionHandler(XML_Parser parser, XML_EndCdataSectionHandler end) { - endCdataSectionHandler = end; + if (parser != NULL) + endCdataSectionHandler = end; } void XMLCALL XML_SetDefaultHandler(XML_Parser parser, XML_DefaultHandler handler) { + if (parser == NULL) + return; defaultHandler = handler; defaultExpandInternalEntities = XML_FALSE; } @@ -1344,6 +1563,8 @@ void XMLCALL XML_SetDefaultHandlerExpand(XML_Parser parser, XML_DefaultHandler handler) { + if (parser == NULL) + return; defaultHandler = handler; defaultExpandInternalEntities = XML_TRUE; } @@ -1353,6 +1574,8 @@ XML_SetDoctypeDeclHandler(XML_Parser parser, XML_StartDoctypeDeclHandler start, XML_EndDoctypeDeclHandler end) { + if (parser == NULL) + return; startDoctypeDeclHandler = start; endDoctypeDeclHandler = end; } @@ -1360,27 +1583,31 @@ XML_SetDoctypeDeclHandler(XML_Parser parser, void XMLCALL XML_SetStartDoctypeDeclHandler(XML_Parser parser, XML_StartDoctypeDeclHandler start) { - startDoctypeDeclHandler = start; + if (parser != NULL) + startDoctypeDeclHandler = start; } void XMLCALL XML_SetEndDoctypeDeclHandler(XML_Parser parser, XML_EndDoctypeDeclHandler end) { - endDoctypeDeclHandler = end; + if (parser != NULL) + endDoctypeDeclHandler = end; } void XMLCALL XML_SetUnparsedEntityDeclHandler(XML_Parser parser, XML_UnparsedEntityDeclHandler handler) { - unparsedEntityDeclHandler = handler; + if (parser != NULL) + unparsedEntityDeclHandler = handler; } void XMLCALL XML_SetNotationDeclHandler(XML_Parser parser, XML_NotationDeclHandler handler) { - notationDeclHandler = handler; + if (parser != NULL) + notationDeclHandler = handler; } void XMLCALL @@ -1388,6 +1615,8 @@ XML_SetNamespaceDeclHandler(XML_Parser parser, XML_StartNamespaceDeclHandler start, XML_EndNamespaceDeclHandler end) { + if (parser == NULL) + return; startNamespaceDeclHandler = start; endNamespaceDeclHandler = end; } @@ -1395,32 +1624,38 @@ XML_SetNamespaceDeclHandler(XML_Parser parser, void XMLCALL XML_SetStartNamespaceDeclHandler(XML_Parser parser, XML_StartNamespaceDeclHandler start) { - startNamespaceDeclHandler = start; + if (parser != NULL) + startNamespaceDeclHandler = start; } void XMLCALL XML_SetEndNamespaceDeclHandler(XML_Parser parser, XML_EndNamespaceDeclHandler end) { - endNamespaceDeclHandler = end; + if (parser != NULL) + endNamespaceDeclHandler = end; } void XMLCALL XML_SetNotStandaloneHandler(XML_Parser parser, XML_NotStandaloneHandler handler) { - notStandaloneHandler = handler; + if (parser != NULL) + notStandaloneHandler = handler; } void XMLCALL XML_SetExternalEntityRefHandler(XML_Parser parser, XML_ExternalEntityRefHandler handler) { - externalEntityRefHandler = handler; + if (parser != NULL) + externalEntityRefHandler = handler; } void XMLCALL XML_SetExternalEntityRefHandlerArg(XML_Parser parser, void *arg) { + if (parser == NULL) + return; if (arg) externalEntityRefHandlerArg = (XML_Parser)arg; else @@ -1431,7 +1666,8 @@ void XMLCALL XML_SetSkippedEntityHandler(XML_Parser parser, XML_SkippedEntityHandler handler) { - skippedEntityHandler = handler; + if (parser != NULL) + skippedEntityHandler = handler; } void XMLCALL @@ -1439,6 +1675,8 @@ XML_SetUnknownEncodingHandler(XML_Parser parser, XML_UnknownEncodingHandler handler, void *data) { + if (parser == NULL) + return; unknownEncodingHandler = handler; unknownEncodingHandlerData = data; } @@ -1447,33 +1685,39 @@ void XMLCALL XML_SetElementDeclHandler(XML_Parser parser, XML_ElementDeclHandler eldecl) { - elementDeclHandler = eldecl; + if (parser != NULL) + elementDeclHandler = eldecl; } void XMLCALL XML_SetAttlistDeclHandler(XML_Parser parser, XML_AttlistDeclHandler attdecl) { - attlistDeclHandler = attdecl; + if (parser != NULL) + attlistDeclHandler = attdecl; } void XMLCALL XML_SetEntityDeclHandler(XML_Parser parser, XML_EntityDeclHandler handler) { - entityDeclHandler = handler; + if (parser != NULL) + entityDeclHandler = handler; } void XMLCALL XML_SetXmlDeclHandler(XML_Parser parser, XML_XmlDeclHandler handler) { - xmlDeclHandler = handler; + if (parser != NULL) + xmlDeclHandler = handler; } int XMLCALL XML_SetParamEntityParsing(XML_Parser parser, enum XML_ParamEntityParsing peParsing) { + if (parser == NULL) + return 0; /* block after XML_Parse()/XML_ParseBuffer() has been called */ if (ps_parsing == XML_PARSING || ps_parsing == XML_SUSPENDED) return 0; @@ -1489,6 +1733,10 @@ int XMLCALL XML_SetHashSalt(XML_Parser parser, unsigned long hash_salt) { + if (parser == NULL) + return 0; + if (parser->m_parentParser) + return XML_SetHashSalt(parser->m_parentParser, hash_salt); /* block after XML_Parse()/XML_ParseBuffer() has been called */ if (ps_parsing == XML_PARSING || ps_parsing == XML_SUSPENDED) return 0; @@ -1499,6 +1747,10 @@ XML_SetHashSalt(XML_Parser parser, enum XML_Status XMLCALL XML_Parse(XML_Parser parser, const char *s, int len, int isFinal) { + if ((parser == NULL) || (len < 0) || ((s == NULL) && (len != 0))) { + errorCode = XML_ERROR_INVALID_ARGUMENT; + return XML_STATUS_ERROR; + } switch (ps_parsing) { case XML_SUSPENDED: errorCode = XML_ERROR_SUSPENDED; @@ -1551,6 +1803,13 @@ XML_Parse(XML_Parser parser, const char *s, int len, int isFinal) const char *end; int nLeftOver; enum XML_Status result; + /* Detect overflow (a+b > MAX <==> b > MAX-a) */ + if (len > ((XML_Size)-1) / 2 - parseEndByteIndex) { + errorCode = XML_ERROR_NO_MEMORY; + eventPtr = eventEndPtr = NULL; + processor = errorProcessor; + return XML_STATUS_ERROR; + } parseEndByteIndex += len; positionPtr = s; ps_finalBuffer = (XML_Bool)isFinal; @@ -1583,11 +1842,14 @@ XML_Parse(XML_Parser parser, const char *s, int len, int isFinal) nLeftOver = s + len - end; if (nLeftOver) { if (buffer == NULL || nLeftOver > bufferLim - buffer) { - /* FIXME avoid integer overflow */ - char *temp; - temp = (buffer == NULL - ? (char *)MALLOC(len * 2) - : (char *)REALLOC(buffer, len * 2)); + /* avoid _signed_ integer overflow */ + char *temp = NULL; + const int bytesToAllocate = (int)((unsigned)len * 2U); + if (bytesToAllocate > 0) { + temp = (buffer == NULL + ? (char *)MALLOC(bytesToAllocate) + : (char *)REALLOC(buffer, bytesToAllocate)); + } if (temp == NULL) { errorCode = XML_ERROR_NO_MEMORY; eventPtr = eventEndPtr = NULL; @@ -1595,7 +1857,7 @@ XML_Parse(XML_Parser parser, const char *s, int len, int isFinal) return XML_STATUS_ERROR; } buffer = temp; - bufferLim = buffer + len * 2; + bufferLim = buffer + bytesToAllocate; } memcpy(buffer, end, nLeftOver); } @@ -1625,6 +1887,8 @@ XML_ParseBuffer(XML_Parser parser, int len, int isFinal) const char *start; enum XML_Status result = XML_STATUS_OK; + if (parser == NULL) + return XML_STATUS_ERROR; switch (ps_parsing) { case XML_SUSPENDED: errorCode = XML_ERROR_SUSPENDED; @@ -1678,6 +1942,8 @@ XML_ParseBuffer(XML_Parser parser, int len, int isFinal) void * XMLCALL XML_GetBuffer(XML_Parser parser, int len) { + if (parser == NULL) + return NULL; if (len < 0) { errorCode = XML_ERROR_NO_MEMORY; return NULL; @@ -1695,15 +1961,15 @@ XML_GetBuffer(XML_Parser parser, int len) if (len > bufferLim - bufferEnd) { #ifdef XML_CONTEXT_BYTES int keep; -#endif - int neededSize = len + (int)(bufferEnd - bufferPtr); +#endif /* defined XML_CONTEXT_BYTES */ + /* Do not invoke signed arithmetic overflow: */ + int neededSize = (int) ((unsigned)len + (unsigned)(bufferEnd - bufferPtr)); if (neededSize < 0) { errorCode = XML_ERROR_NO_MEMORY; return NULL; } #ifdef XML_CONTEXT_BYTES keep = (int)(bufferPtr - buffer); - if (keep > XML_CONTEXT_BYTES) keep = XML_CONTEXT_BYTES; neededSize += keep; @@ -1728,7 +1994,8 @@ XML_GetBuffer(XML_Parser parser, int len) if (bufferSize == 0) bufferSize = INIT_BUFFER_SIZE; do { - bufferSize *= 2; + /* Do not invoke signed arithmetic overflow: */ + bufferSize = (int) (2U * (unsigned) bufferSize); } while (bufferSize < neededSize && bufferSize > 0); if (bufferSize <= 0) { errorCode = XML_ERROR_NO_MEMORY; @@ -1773,6 +2040,8 @@ XML_GetBuffer(XML_Parser parser, int len) enum XML_Status XMLCALL XML_StopParser(XML_Parser parser, XML_Bool resumable) { + if (parser == NULL) + return XML_STATUS_ERROR; switch (ps_parsing) { case XML_SUSPENDED: if (resumable) { @@ -1805,6 +2074,8 @@ XML_ResumeParser(XML_Parser parser) { enum XML_Status result = XML_STATUS_OK; + if (parser == NULL) + return XML_STATUS_ERROR; if (ps_parsing != XML_SUSPENDED) { errorCode = XML_ERROR_NOT_SUSPENDED; return XML_STATUS_ERROR; @@ -1841,6 +2112,8 @@ XML_ResumeParser(XML_Parser parser) void XMLCALL XML_GetParsingStatus(XML_Parser parser, XML_ParsingStatus *status) { + if (parser == NULL) + return; assert(status != NULL); *status = parser->m_parsingStatus; } @@ -1848,20 +2121,26 @@ XML_GetParsingStatus(XML_Parser parser, XML_ParsingStatus *status) enum XML_Error XMLCALL XML_GetErrorCode(XML_Parser parser) { + if (parser == NULL) + return XML_ERROR_INVALID_ARGUMENT; return errorCode; } XML_Index XMLCALL XML_GetCurrentByteIndex(XML_Parser parser) { + if (parser == NULL) + return -1; if (eventPtr) - return parseEndByteIndex - (parseEndPtr - eventPtr); + return (XML_Index)(parseEndByteIndex - (parseEndPtr - eventPtr)); return -1; } int XMLCALL XML_GetCurrentByteCount(XML_Parser parser) { + if (parser == NULL) + return 0; if (eventEndPtr && eventPtr) return (int)(eventEndPtr - eventPtr); return 0; @@ -1871,11 +2150,19 @@ const char * XMLCALL XML_GetInputContext(XML_Parser parser, int *offset, int *size) { #ifdef XML_CONTEXT_BYTES + if (parser == NULL) + return NULL; if (eventPtr && buffer) { - *offset = (int)(eventPtr - buffer); - *size = (int)(bufferEnd - buffer); + if (offset != NULL) + *offset = (int)(eventPtr - buffer); + if (size != NULL) + *size = (int)(bufferEnd - buffer); return buffer; } +#else + (void)parser; + (void)offset; + (void)size; #endif /* defined XML_CONTEXT_BYTES */ return (char *) 0; } @@ -1883,6 +2170,8 @@ XML_GetInputContext(XML_Parser parser, int *offset, int *size) XML_Size XMLCALL XML_GetCurrentLineNumber(XML_Parser parser) { + if (parser == NULL) + return 0; if (eventPtr && eventPtr >= positionPtr) { XmlUpdatePosition(encoding, positionPtr, eventPtr, &position); positionPtr = eventPtr; @@ -1893,6 +2182,8 @@ XML_GetCurrentLineNumber(XML_Parser parser) XML_Size XMLCALL XML_GetCurrentColumnNumber(XML_Parser parser) { + if (parser == NULL) + return 0; if (eventPtr && eventPtr >= positionPtr) { XmlUpdatePosition(encoding, positionPtr, eventPtr, &position); positionPtr = eventPtr; @@ -1903,30 +2194,38 @@ XML_GetCurrentColumnNumber(XML_Parser parser) void XMLCALL XML_FreeContentModel(XML_Parser parser, XML_Content *model) { - FREE(model); + if (parser != NULL) + FREE(model); } void * XMLCALL XML_MemMalloc(XML_Parser parser, size_t size) { + if (parser == NULL) + return NULL; return MALLOC(size); } void * XMLCALL XML_MemRealloc(XML_Parser parser, void *ptr, size_t size) { + if (parser == NULL) + return NULL; return REALLOC(ptr, size); } void XMLCALL XML_MemFree(XML_Parser parser, void *ptr) { - FREE(ptr); + if (parser != NULL) + FREE(ptr); } void XMLCALL XML_DefaultCurrent(XML_Parser parser) { + if (parser == NULL) + return; if (defaultHandler) { if (openInternalEntities) reportDefault(parser, @@ -2429,11 +2728,11 @@ doContent(XML_Parser parser, for (;;) { int bufSize; int convLen; - XmlConvert(enc, + const enum XML_Convert_Result convert_res = XmlConvert(enc, &fromPtr, rawNameEnd, (ICHAR **)&toPtr, (ICHAR *)tag->bufEnd - 1); convLen = (int)(toPtr - (XML_Char *)tag->buf); - if (fromPtr == rawNameEnd) { + if ((fromPtr >= rawNameEnd) || (convert_res == XML_CONVERT_INPUT_INCOMPLETE)) { tag->name.strLen = convLen; break; } @@ -2476,8 +2775,10 @@ doContent(XML_Parser parser, return XML_ERROR_NO_MEMORY; poolFinish(&tempPool); result = storeAtts(parser, enc, s, &name, &bindings); - if (result) + if (result != XML_ERROR_NONE) { + freeBindings(parser, bindings); return result; + } poolFinish(&tempPool); if (startElementHandler) { startElementHandler(handlerArg, name.str, (const XML_Char **)atts); @@ -2492,15 +2793,7 @@ doContent(XML_Parser parser, if (noElmHandlers && defaultHandler) reportDefault(parser, enc, s, next); poolClear(&tempPool); - while (bindings) { - BINDING *b = bindings; - if (endNamespaceDeclHandler) - endNamespaceDeclHandler(handlerArg, b->prefix->name); - bindings = bindings->nextTagBinding; - b->nextTagBinding = freeBindingList; - freeBindingList = b; - b->prefix->binding = b->prevPrefixBinding; - } + freeBindings(parser, bindings); } if (tagLevel == 0) return epilogProcessor(parser, next, end, nextPtr); @@ -2654,11 +2947,11 @@ doContent(XML_Parser parser, if (MUST_CONVERT(enc, s)) { for (;;) { ICHAR *dataPtr = (ICHAR *)dataBuf; - XmlConvert(enc, &s, next, &dataPtr, (ICHAR *)dataBufEnd); + const enum XML_Convert_Result convert_res = XmlConvert(enc, &s, next, &dataPtr, (ICHAR *)dataBufEnd); *eventEndPP = s; charDataHandler(handlerArg, dataBuf, (int)(dataPtr - (ICHAR *)dataBuf)); - if (s == next) + if ((convert_res == XML_CONVERT_COMPLETED) || (convert_res == XML_CONVERT_INPUT_INCOMPLETE)) break; *eventPP = s; } @@ -2698,6 +2991,29 @@ doContent(XML_Parser parser, /* not reached */ } +/* This function does not call free() on the allocated memory, merely + * moving it to the parser's freeBindingList where it can be freed or + * reused as appropriate. + */ +static void +freeBindings(XML_Parser parser, BINDING *bindings) +{ + while (bindings) { + BINDING *b = bindings; + + /* startNamespaceDeclHandler will have been called for this + * binding in addBindings(), so call the end handler now. + */ + if (endNamespaceDeclHandler) + endNamespaceDeclHandler(handlerArg, b->prefix->name); + + bindings = bindings->nextTagBinding; + b->nextTagBinding = freeBindingList; + freeBindingList = b; + b->prefix->binding = b->prevPrefixBinding; + } +} + /* Precondition: all arguments must be non-NULL; Purpose: - normalize attributes @@ -2922,7 +3238,13 @@ storeAtts(XML_Parser parser, const ENCODING *enc, if (s[-1] == 2) { /* prefixed */ ATTRIBUTE_ID *id; const BINDING *b; - unsigned long uriHash = hash_secret_salt; + unsigned long uriHash; + struct siphash sip_state; + struct sipkey sip_key; + + copy_salt_to_sipkey(parser, &sip_key); + sip24_init(&sip_state, &sip_key); + ((XML_Char *)s)[-1] = 0; /* clear flag */ id = (ATTRIBUTE_ID *)lookup(parser, &dtd->attributeIds, s, 0); if (!id || !id->prefix) @@ -2931,22 +3253,26 @@ storeAtts(XML_Parser parser, const ENCODING *enc, if (!b) return XML_ERROR_UNBOUND_PREFIX; - /* as we expand the name we also calculate its hash value */ for (j = 0; j < b->uriLen; j++) { const XML_Char c = b->uri[j]; if (!poolAppendChar(&tempPool, c)) return XML_ERROR_NO_MEMORY; - uriHash = CHAR_HASH(uriHash, c); } + + sip24_update(&sip_state, b->uri, b->uriLen * sizeof(XML_Char)); + while (*s++ != XML_T(ASCII_COLON)) ; + + sip24_update(&sip_state, s, keylen(s) * sizeof(XML_Char)); + do { /* copies null terminator */ - const XML_Char c = *s; if (!poolAppendChar(&tempPool, *s)) return XML_ERROR_NO_MEMORY; - uriHash = CHAR_HASH(uriHash, c); } while (*s++); + uriHash = (unsigned long)sip24_final(&sip_state); + { /* Check hash table for duplicate of expanded name (uriName). Derived from code in lookup(parser, HASH_TABLE *table, ...). */ @@ -3264,11 +3590,11 @@ doCdataSection(XML_Parser parser, if (MUST_CONVERT(enc, s)) { for (;;) { ICHAR *dataPtr = (ICHAR *)dataBuf; - XmlConvert(enc, &s, next, &dataPtr, (ICHAR *)dataBufEnd); + const enum XML_Convert_Result convert_res = XmlConvert(enc, &s, next, &dataPtr, (ICHAR *)dataBufEnd); *eventEndPP = next; charDataHandler(handlerArg, dataBuf, (int)(dataPtr - (ICHAR *)dataBuf)); - if (s == next) + if ((convert_res == XML_CONVERT_COMPLETED) || (convert_res == XML_CONVERT_INPUT_INCOMPLETE)) break; *eventPP = s; } @@ -3660,6 +3986,14 @@ entityValueInitProcessor(XML_Parser parser, *nextPtr = next; return XML_ERROR_NONE; } + /* If we get this token, we have the start of what might be a + normal tag, but not a declaration (i.e. it doesn't begin with + "internalEventEndPtr = NULL; textStart = (char *)entity->textPtr; textEnd = (char *)(entity->textPtr + entity->textLen); + /* Set a safe default value in case 'next' does not get set */ + next = textStart; #ifdef XML_DTD if (entity->is_param) { @@ -4881,6 +5217,8 @@ internalEntityProcessor(XML_Parser parser, entity = openEntity->entity; textStart = ((char *)entity->textPtr) + entity->processed; textEnd = (char *)(entity->textPtr + entity->textLen); + /* Set a safe default value in case 'next' does not get set */ + next = textStart; #ifdef XML_DTD if (entity->is_param) { @@ -4927,9 +5265,9 @@ internalEntityProcessor(XML_Parser parser, static enum XML_Error PTRCALL errorProcessor(XML_Parser parser, - const char *s, - const char *end, - const char **nextPtr) + const char *UNUSED_P(s), + const char *UNUSED_P(end), + const char **UNUSED_P(nextPtr)) { return errorCode; } @@ -5345,6 +5683,7 @@ reportDefault(XML_Parser parser, const ENCODING *enc, const char *s, const char *end) { if (MUST_CONVERT(enc, s)) { + enum XML_Convert_Result convert_res; const char **eventPP; const char **eventEndPP; if (enc == encoding) { @@ -5357,11 +5696,11 @@ reportDefault(XML_Parser parser, const ENCODING *enc, } do { ICHAR *dataPtr = (ICHAR *)dataBuf; - XmlConvert(enc, &s, end, &dataPtr, (ICHAR *)dataBufEnd); + convert_res = XmlConvert(enc, &s, end, &dataPtr, (ICHAR *)dataBufEnd); *eventEndPP = s; defaultHandler(handlerArg, dataBuf, (int)(dataPtr - (ICHAR *)dataBuf)); *eventPP = s; - } while (s != end); + } while ((convert_res != XML_CONVERT_COMPLETED) && (convert_res != XML_CONVERT_INPUT_INCOMPLETE)); } else defaultHandler(handlerArg, (XML_Char *)s, (int)((XML_Char *)end - (XML_Char *)s)); @@ -5840,7 +6179,6 @@ dtdCopy(XML_Parser oldParser, DTD *newDtd, const DTD *oldDtd, const XML_Memory_H newE->defaultAtts = (DEFAULT_ATTRIBUTE *) ms->malloc_fcn(oldE->nDefaultAtts * sizeof(DEFAULT_ATTRIBUTE)); if (!newE->defaultAtts) { - ms->free_fcn(newE); return 0; } } @@ -5975,13 +6313,32 @@ keyeq(KEY s1, KEY s2) return XML_FALSE; } +static size_t +keylen(KEY s) +{ + size_t len = 0; + for (; *s; s++, len++); + return len; +} + +static void +copy_salt_to_sipkey(XML_Parser parser, struct sipkey * key) +{ + key->k[0] = 0; + key->k[1] = get_hash_secret_salt(parser); +} + static unsigned long FASTCALL hash(XML_Parser parser, KEY s) { - unsigned long h = hash_secret_salt; - while (*s) - h = CHAR_HASH(h, *s++); - return h; + struct siphash state; + struct sipkey key; + (void)sip_tobin; + (void)sip24_valid; + copy_salt_to_sipkey(parser, &key); + sip24_init(&state, &key); + sip24_update(&state, s, keylen(s) * sizeof(XML_Char)); + return (unsigned long)sip24_final(&state); } static NAMED * @@ -6166,8 +6523,8 @@ poolAppend(STRING_POOL *pool, const ENCODING *enc, if (!pool->ptr && !poolGrow(pool)) return NULL; for (;;) { - XmlConvert(enc, &ptr, end, (ICHAR **)&(pool->ptr), (ICHAR *)pool->end); - if (ptr == end) + const enum XML_Convert_Result convert_res = XmlConvert(enc, &ptr, end, (ICHAR **)&(pool->ptr), (ICHAR *)pool->end); + if ((convert_res == XML_CONVERT_COMPLETED) || (convert_res == XML_CONVERT_INPUT_INCOMPLETE)) break; if (!poolGrow(pool)) return NULL; @@ -6224,6 +6581,35 @@ poolStoreString(STRING_POOL *pool, const ENCODING *enc, return pool->start; } +static size_t +poolBytesToAllocateFor(int blockSize) +{ + /* Unprotected math would be: + ** return offsetof(BLOCK, s) + blockSize * sizeof(XML_Char); + ** + ** Detect overflow, avoiding _signed_ overflow undefined behavior + ** For a + b * c we check b * c in isolation first, so that addition of a + ** on top has no chance of making us accept a small non-negative number + */ + const size_t stretch = sizeof(XML_Char); /* can be 4 bytes */ + + if (blockSize <= 0) + return 0; + + if (blockSize > (int)(INT_MAX / stretch)) + return 0; + + { + const int stretchedBlockSize = blockSize * (int)stretch; + const int bytesToAllocate = (int)( + offsetof(BLOCK, s) + (unsigned)stretchedBlockSize); + if (bytesToAllocate < 0) + return 0; + + return (size_t)bytesToAllocate; + } +} + static XML_Bool FASTCALL poolGrow(STRING_POOL *pool) { @@ -6251,11 +6637,19 @@ poolGrow(STRING_POOL *pool) } } if (pool->blocks && pool->start == pool->blocks->s) { - int blockSize = (int)(pool->end - pool->start)*2; - BLOCK *temp = (BLOCK *) - pool->mem->realloc_fcn(pool->blocks, - (offsetof(BLOCK, s) - + blockSize * sizeof(XML_Char))); + BLOCK *temp; + int blockSize = (int)((unsigned)(pool->end - pool->start)*2U); + size_t bytesToAllocate; + + if (blockSize < 0) + return XML_FALSE; + + bytesToAllocate = poolBytesToAllocateFor(blockSize); + if (bytesToAllocate == 0) + return XML_FALSE; + + temp = (BLOCK *) + pool->mem->realloc_fcn(pool->blocks, (unsigned)bytesToAllocate); if (temp == NULL) return XML_FALSE; pool->blocks = temp; @@ -6267,12 +6661,26 @@ poolGrow(STRING_POOL *pool) else { BLOCK *tem; int blockSize = (int)(pool->end - pool->start); + size_t bytesToAllocate; + + if (blockSize < 0) + return XML_FALSE; + if (blockSize < INIT_BLOCK_SIZE) blockSize = INIT_BLOCK_SIZE; - else + else { + /* Detect overflow, avoiding _signed_ overflow undefined behavior */ + if ((int)((unsigned)blockSize * 2U) < 0) { + return XML_FALSE; + } blockSize *= 2; - tem = (BLOCK *)pool->mem->malloc_fcn(offsetof(BLOCK, s) - + blockSize * sizeof(XML_Char)); + } + + bytesToAllocate = poolBytesToAllocateFor(blockSize); + if (bytesToAllocate == 0) + return XML_FALSE; + + tem = (BLOCK *)pool->mem->malloc_fcn(bytesToAllocate); if (!tem) return XML_FALSE; tem->size = blockSize; diff --git a/Modules/expat/xmlrole.c b/Modules/expat/xmlrole.c index 44772e21dd337b..a7c56302796957 100644 --- a/Modules/expat/xmlrole.c +++ b/Modules/expat/xmlrole.c @@ -4,19 +4,13 @@ #include -#ifdef COMPILED_FROM_DSP +#ifdef _WIN32 #include "winconfig.h" -#elif defined(MACOS_CLASSIC) -#include "macconfig.h" -#elif defined(__amigaos__) -#include "amigaconfig.h" -#elif defined(__WATCOMC__) -#include "watcomconfig.h" #else #ifdef HAVE_EXPAT_CONFIG_H #include #endif -#endif /* ndef COMPILED_FROM_DSP */ +#endif /* ndef _WIN32 */ #include "expat_external.h" #include "internal.h" @@ -195,9 +189,9 @@ prolog1(PROLOG_STATE *state, static int PTRCALL prolog2(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -216,9 +210,9 @@ prolog2(PROLOG_STATE *state, static int PTRCALL doctype0(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -264,9 +258,9 @@ doctype1(PROLOG_STATE *state, static int PTRCALL doctype2(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -281,9 +275,9 @@ doctype2(PROLOG_STATE *state, static int PTRCALL doctype3(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -298,9 +292,9 @@ doctype3(PROLOG_STATE *state, static int PTRCALL doctype4(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -318,9 +312,9 @@ doctype4(PROLOG_STATE *state, static int PTRCALL doctype5(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -437,9 +431,9 @@ externalSubset1(PROLOG_STATE *state, static int PTRCALL entity0(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -457,9 +451,9 @@ entity0(PROLOG_STATE *state, static int PTRCALL entity1(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -502,9 +496,9 @@ entity2(PROLOG_STATE *state, static int PTRCALL entity3(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -519,9 +513,9 @@ entity3(PROLOG_STATE *state, static int PTRCALL entity4(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -559,9 +553,9 @@ entity5(PROLOG_STATE *state, static int PTRCALL entity6(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -605,9 +599,9 @@ entity7(PROLOG_STATE *state, static int PTRCALL entity8(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -622,9 +616,9 @@ entity8(PROLOG_STATE *state, static int PTRCALL entity9(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -639,9 +633,9 @@ entity9(PROLOG_STATE *state, static int PTRCALL entity10(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -656,9 +650,9 @@ entity10(PROLOG_STATE *state, static int PTRCALL notation0(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -697,9 +691,9 @@ notation1(PROLOG_STATE *state, static int PTRCALL notation2(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -714,9 +708,9 @@ notation2(PROLOG_STATE *state, static int PTRCALL notation3(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -732,9 +726,9 @@ notation3(PROLOG_STATE *state, static int PTRCALL notation4(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -753,9 +747,9 @@ notation4(PROLOG_STATE *state, static int PTRCALL attlist0(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -771,9 +765,9 @@ attlist0(PROLOG_STATE *state, static int PTRCALL attlist1(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -833,9 +827,9 @@ attlist2(PROLOG_STATE *state, static int PTRCALL attlist3(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -852,9 +846,9 @@ attlist3(PROLOG_STATE *state, static int PTRCALL attlist4(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -872,9 +866,9 @@ attlist4(PROLOG_STATE *state, static int PTRCALL attlist5(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -889,9 +883,9 @@ attlist5(PROLOG_STATE *state, static int PTRCALL attlist6(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -906,9 +900,9 @@ attlist6(PROLOG_STATE *state, static int PTRCALL attlist7(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -967,9 +961,9 @@ attlist8(PROLOG_STATE *state, static int PTRCALL attlist9(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -984,9 +978,9 @@ attlist9(PROLOG_STATE *state, static int PTRCALL element0(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1072,9 +1066,9 @@ element2(PROLOG_STATE *state, static int PTRCALL element3(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1097,9 +1091,9 @@ element3(PROLOG_STATE *state, static int PTRCALL element4(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1115,9 +1109,9 @@ element4(PROLOG_STATE *state, static int PTRCALL element5(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1136,9 +1130,9 @@ element5(PROLOG_STATE *state, static int PTRCALL element6(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1166,9 +1160,9 @@ element6(PROLOG_STATE *state, static int PTRCALL element7(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1240,9 +1234,9 @@ condSect0(PROLOG_STATE *state, static int PTRCALL condSect1(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1258,9 +1252,9 @@ condSect1(PROLOG_STATE *state, static int PTRCALL condSect2(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1277,9 +1271,9 @@ condSect2(PROLOG_STATE *state, static int PTRCALL declClose(PROLOG_STATE *state, int tok, - const char *ptr, - const char *end, - const ENCODING *enc) + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { switch (tok) { case XML_TOK_PROLOG_S: @@ -1292,11 +1286,11 @@ declClose(PROLOG_STATE *state, } static int PTRCALL -error(PROLOG_STATE *state, - int tok, - const char *ptr, - const char *end, - const ENCODING *enc) +error(PROLOG_STATE *UNUSED_P(state), + int UNUSED_P(tok), + const char *UNUSED_P(ptr), + const char *UNUSED_P(end), + const ENCODING *UNUSED_P(enc)) { return XML_ROLE_NONE; } diff --git a/Modules/expat/xmltok.c b/Modules/expat/xmltok.c index bf09dfc72b9fc8..cdf0720dd89689 100644 --- a/Modules/expat/xmltok.c +++ b/Modules/expat/xmltok.c @@ -4,19 +4,13 @@ #include -#ifdef COMPILED_FROM_DSP +#ifdef _WIN32 #include "winconfig.h" -#elif defined(MACOS_CLASSIC) -#include "macconfig.h" -#elif defined(__amigaos__) -#include "amigaconfig.h" -#elif defined(__WATCOMC__) -#include "watcomconfig.h" #else #ifdef HAVE_EXPAT_CONFIG_H #include #endif -#endif /* ndef COMPILED_FROM_DSP */ +#endif /* ndef _WIN32 */ #include "expat_external.h" #include "internal.h" @@ -46,7 +40,7 @@ #define VTABLE VTABLE1, PREFIX(toUtf8), PREFIX(toUtf16) #define UCS2_GET_NAMING(pages, hi, lo) \ - (namingBitmap[(pages[hi] << 3) + ((lo) >> 5)] & (1 << ((lo) & 0x1F))) + (namingBitmap[(pages[hi] << 3) + ((lo) >> 5)] & (1u << ((lo) & 0x1F))) /* A 2 byte UTF-8 representation splits the characters 11 bits between the bottom 5 and 6 bits of the bytes. We need 8 bits to index into @@ -56,7 +50,7 @@ (namingBitmap[((pages)[(((byte)[0]) >> 2) & 7] << 3) \ + ((((byte)[0]) & 3) << 1) \ + ((((byte)[1]) >> 5) & 1)] \ - & (1 << (((byte)[1]) & 0x1F))) + & (1u << (((byte)[1]) & 0x1F))) /* A 3 byte UTF-8 representation splits the characters 16 bits between the bottom 4, 6 and 6 bits of the bytes. We need 8 bits to index @@ -69,7 +63,7 @@ << 3) \ + ((((byte)[1]) & 3) << 1) \ + ((((byte)[2]) >> 5) & 1)] \ - & (1 << (((byte)[2]) & 0x1F))) + & (1u << (((byte)[2]) & 0x1F))) #define UTF8_GET_NAMING(pages, p, n) \ ((n) == 2 \ @@ -122,19 +116,19 @@ ((*p) == 0xF4 ? (p)[1] > 0x8F : ((p)[1] & 0xC0) == 0xC0))) static int PTRFASTCALL -isNever(const ENCODING *enc, const char *p) +isNever(const ENCODING *UNUSED_P(enc), const char *UNUSED_P(p)) { return 0; } static int PTRFASTCALL -utf8_isName2(const ENCODING *enc, const char *p) +utf8_isName2(const ENCODING *UNUSED_P(enc), const char *p) { return UTF8_GET_NAMING2(namePages, (const unsigned char *)p); } static int PTRFASTCALL -utf8_isName3(const ENCODING *enc, const char *p) +utf8_isName3(const ENCODING *UNUSED_P(enc), const char *p) { return UTF8_GET_NAMING3(namePages, (const unsigned char *)p); } @@ -142,13 +136,13 @@ utf8_isName3(const ENCODING *enc, const char *p) #define utf8_isName4 isNever static int PTRFASTCALL -utf8_isNmstrt2(const ENCODING *enc, const char *p) +utf8_isNmstrt2(const ENCODING *UNUSED_P(enc), const char *p) { return UTF8_GET_NAMING2(nmstrtPages, (const unsigned char *)p); } static int PTRFASTCALL -utf8_isNmstrt3(const ENCODING *enc, const char *p) +utf8_isNmstrt3(const ENCODING *UNUSED_P(enc), const char *p) { return UTF8_GET_NAMING3(nmstrtPages, (const unsigned char *)p); } @@ -156,19 +150,19 @@ utf8_isNmstrt3(const ENCODING *enc, const char *p) #define utf8_isNmstrt4 isNever static int PTRFASTCALL -utf8_isInvalid2(const ENCODING *enc, const char *p) +utf8_isInvalid2(const ENCODING *UNUSED_P(enc), const char *p) { return UTF8_INVALID2((const unsigned char *)p); } static int PTRFASTCALL -utf8_isInvalid3(const ENCODING *enc, const char *p) +utf8_isInvalid3(const ENCODING *UNUSED_P(enc), const char *p) { return UTF8_INVALID3((const unsigned char *)p); } static int PTRFASTCALL -utf8_isInvalid4(const ENCODING *enc, const char *p) +utf8_isInvalid4(const ENCODING *UNUSED_P(enc), const char *p) { return UTF8_INVALID4((const unsigned char *)p); } @@ -222,6 +216,17 @@ struct normal_encoding { E ## isInvalid3, \ E ## isInvalid4 +#define NULL_VTABLE \ + /* isName2 */ NULL, \ + /* isName3 */ NULL, \ + /* isName4 */ NULL, \ + /* isNmstrt2 */ NULL, \ + /* isNmstrt3 */ NULL, \ + /* isNmstrt4 */ NULL, \ + /* isInvalid2 */ NULL, \ + /* isInvalid3 */ NULL, \ + /* isInvalid4 */ NULL + static int FASTCALL checkCharRefNumber(int); #include "xmltok_impl.h" @@ -318,39 +323,89 @@ enum { /* UTF8_cvalN is value of masked first byte of N byte sequence */ UTF8_cval4 = 0xf0 }; -static void PTRCALL -utf8_toUtf8(const ENCODING *enc, +void +align_limit_to_full_utf8_characters(const char * from, const char ** fromLimRef) +{ + const char * fromLim = *fromLimRef; + size_t walked = 0; + for (; fromLim > from; fromLim--, walked++) { + const unsigned char prev = (unsigned char)fromLim[-1]; + if ((prev & 0xf8u) == 0xf0u) { /* 4-byte character, lead by 0b11110xxx byte */ + if (walked + 1 >= 4) { + fromLim += 4 - 1; + break; + } else { + walked = 0; + } + } else if ((prev & 0xf0u) == 0xe0u) { /* 3-byte character, lead by 0b1110xxxx byte */ + if (walked + 1 >= 3) { + fromLim += 3 - 1; + break; + } else { + walked = 0; + } + } else if ((prev & 0xe0u) == 0xc0u) { /* 2-byte character, lead by 0b110xxxxx byte */ + if (walked + 1 >= 2) { + fromLim += 2 - 1; + break; + } else { + walked = 0; + } + } else if ((prev & 0x80u) == 0x00u) { /* 1-byte character, matching 0b0xxxxxxx */ + break; + } + } + *fromLimRef = fromLim; +} + +static enum XML_Convert_Result PTRCALL +utf8_toUtf8(const ENCODING *UNUSED_P(enc), const char **fromP, const char *fromLim, char **toP, const char *toLim) { char *to; const char *from; - if (fromLim - *fromP > toLim - *toP) { - /* Avoid copying partial characters. */ - for (fromLim = *fromP + (toLim - *toP); fromLim > *fromP; fromLim--) - if (((unsigned char)fromLim[-1] & 0xc0) != 0x80) - break; - } - for (to = *toP, from = *fromP; from != fromLim; from++, to++) + const char *fromLimInitial = fromLim; + + /* Avoid copying partial characters. */ + align_limit_to_full_utf8_characters(*fromP, &fromLim); + + for (to = *toP, from = *fromP; (from < fromLim) && (to < toLim); from++, to++) *to = *from; *fromP = from; *toP = to; + + if (fromLim < fromLimInitial) + return XML_CONVERT_INPUT_INCOMPLETE; + else if ((to == toLim) && (from < fromLim)) + return XML_CONVERT_OUTPUT_EXHAUSTED; + else + return XML_CONVERT_COMPLETED; } -static void PTRCALL +static enum XML_Convert_Result PTRCALL utf8_toUtf16(const ENCODING *enc, const char **fromP, const char *fromLim, unsigned short **toP, const unsigned short *toLim) { + enum XML_Convert_Result res = XML_CONVERT_COMPLETED; unsigned short *to = *toP; const char *from = *fromP; - while (from != fromLim && to != toLim) { + while (from < fromLim && to < toLim) { switch (((struct normal_encoding *)enc)->type[(unsigned char)*from]) { case BT_LEAD2: + if (fromLim - from < 2) { + res = XML_CONVERT_INPUT_INCOMPLETE; + goto after; + } *to++ = (unsigned short)(((from[0] & 0x1f) << 6) | (from[1] & 0x3f)); from += 2; break; case BT_LEAD3: + if (fromLim - from < 3) { + res = XML_CONVERT_INPUT_INCOMPLETE; + goto after; + } *to++ = (unsigned short)(((from[0] & 0xf) << 12) | ((from[1] & 0x3f) << 6) | (from[2] & 0x3f)); from += 3; @@ -358,8 +413,14 @@ utf8_toUtf16(const ENCODING *enc, case BT_LEAD4: { unsigned long n; - if (to + 1 == toLim) + if (toLim - to < 2) { + res = XML_CONVERT_OUTPUT_EXHAUSTED; + goto after; + } + if (fromLim - from < 4) { + res = XML_CONVERT_INPUT_INCOMPLETE; goto after; + } n = ((from[0] & 0x7) << 18) | ((from[1] & 0x3f) << 12) | ((from[2] & 0x3f) << 6) | (from[3] & 0x3f); n -= 0x10000; @@ -374,9 +435,12 @@ utf8_toUtf16(const ENCODING *enc, break; } } + if (from < fromLim) + res = XML_CONVERT_OUTPUT_EXHAUSTED; after: *fromP = from; *toP = to; + return res; } #ifdef XML_NS @@ -425,38 +489,43 @@ static const struct normal_encoding internal_utf8_encoding = { STANDARD_VTABLE(sb_) NORMAL_VTABLE(utf8_) }; -static void PTRCALL -latin1_toUtf8(const ENCODING *enc, +static enum XML_Convert_Result PTRCALL +latin1_toUtf8(const ENCODING *UNUSED_P(enc), const char **fromP, const char *fromLim, char **toP, const char *toLim) { for (;;) { unsigned char c; if (*fromP == fromLim) - break; + return XML_CONVERT_COMPLETED; c = (unsigned char)**fromP; if (c & 0x80) { if (toLim - *toP < 2) - break; + return XML_CONVERT_OUTPUT_EXHAUSTED; *(*toP)++ = (char)((c >> 6) | UTF8_cval2); *(*toP)++ = (char)((c & 0x3f) | 0x80); (*fromP)++; } else { if (*toP == toLim) - break; + return XML_CONVERT_OUTPUT_EXHAUSTED; *(*toP)++ = *(*fromP)++; } } } -static void PTRCALL -latin1_toUtf16(const ENCODING *enc, +static enum XML_Convert_Result PTRCALL +latin1_toUtf16(const ENCODING *UNUSED_P(enc), const char **fromP, const char *fromLim, unsigned short **toP, const unsigned short *toLim) { - while (*fromP != fromLim && *toP != toLim) + while (*fromP < fromLim && *toP < toLim) *(*toP)++ = (unsigned char)*(*fromP)++; + + if ((*toP == toLim) && (*fromP < fromLim)) + return XML_CONVERT_OUTPUT_EXHAUSTED; + else + return XML_CONVERT_COMPLETED; } #ifdef XML_NS @@ -467,7 +536,7 @@ static const struct normal_encoding latin1_encoding_ns = { #include "asciitab.h" #include "latin1tab.h" }, - STANDARD_VTABLE(sb_) + STANDARD_VTABLE(sb_) NULL_VTABLE }; #endif @@ -480,16 +549,21 @@ static const struct normal_encoding latin1_encoding = { #undef BT_COLON #include "latin1tab.h" }, - STANDARD_VTABLE(sb_) + STANDARD_VTABLE(sb_) NULL_VTABLE }; -static void PTRCALL -ascii_toUtf8(const ENCODING *enc, +static enum XML_Convert_Result PTRCALL +ascii_toUtf8(const ENCODING *UNUSED_P(enc), const char **fromP, const char *fromLim, char **toP, const char *toLim) { - while (*fromP != fromLim && *toP != toLim) + while (*fromP < fromLim && *toP < toLim) *(*toP)++ = *(*fromP)++; + + if ((*toP == toLim) && (*fromP < fromLim)) + return XML_CONVERT_OUTPUT_EXHAUSTED; + else + return XML_CONVERT_COMPLETED; } #ifdef XML_NS @@ -500,7 +574,7 @@ static const struct normal_encoding ascii_encoding_ns = { #include "asciitab.h" /* BT_NONXML == 0 */ }, - STANDARD_VTABLE(sb_) + STANDARD_VTABLE(sb_) NULL_VTABLE }; #endif @@ -513,7 +587,7 @@ static const struct normal_encoding ascii_encoding = { #undef BT_COLON /* BT_NONXML == 0 */ }, - STANDARD_VTABLE(sb_) + STANDARD_VTABLE(sb_) NULL_VTABLE }; static int PTRFASTCALL @@ -536,13 +610,14 @@ unicode_byte_type(char hi, char lo) } #define DEFINE_UTF16_TO_UTF8(E) \ -static void PTRCALL \ -E ## toUtf8(const ENCODING *enc, \ +static enum XML_Convert_Result PTRCALL \ +E ## toUtf8(const ENCODING *UNUSED_P(enc), \ const char **fromP, const char *fromLim, \ char **toP, const char *toLim) \ { \ - const char *from; \ - for (from = *fromP; from != fromLim; from += 2) { \ + const char *from = *fromP; \ + fromLim = from + (((fromLim - from) >> 1) << 1); /* shrink to even */ \ + for (; from < fromLim; from += 2) { \ int plane; \ unsigned char lo2; \ unsigned char lo = GET_LO(from); \ @@ -552,7 +627,7 @@ E ## toUtf8(const ENCODING *enc, \ if (lo < 0x80) { \ if (*toP == toLim) { \ *fromP = from; \ - return; \ + return XML_CONVERT_OUTPUT_EXHAUSTED; \ } \ *(*toP)++ = lo; \ break; \ @@ -562,7 +637,7 @@ E ## toUtf8(const ENCODING *enc, \ case 0x4: case 0x5: case 0x6: case 0x7: \ if (toLim - *toP < 2) { \ *fromP = from; \ - return; \ + return XML_CONVERT_OUTPUT_EXHAUSTED; \ } \ *(*toP)++ = ((lo >> 6) | (hi << 2) | UTF8_cval2); \ *(*toP)++ = ((lo & 0x3f) | 0x80); \ @@ -570,7 +645,7 @@ E ## toUtf8(const ENCODING *enc, \ default: \ if (toLim - *toP < 3) { \ *fromP = from; \ - return; \ + return XML_CONVERT_OUTPUT_EXHAUSTED; \ } \ /* 16 bits divided 4, 6, 6 amongst 3 bytes */ \ *(*toP)++ = ((hi >> 4) | UTF8_cval3); \ @@ -580,7 +655,11 @@ E ## toUtf8(const ENCODING *enc, \ case 0xD8: case 0xD9: case 0xDA: case 0xDB: \ if (toLim - *toP < 4) { \ *fromP = from; \ - return; \ + return XML_CONVERT_OUTPUT_EXHAUSTED; \ + } \ + if (fromLim - from < 4) { \ + *fromP = from; \ + return XML_CONVERT_INPUT_INCOMPLETE; \ } \ plane = (((hi & 0x3) << 2) | ((lo >> 6) & 0x3)) + 1; \ *(*toP)++ = ((plane >> 2) | UTF8_cval4); \ @@ -596,20 +675,32 @@ E ## toUtf8(const ENCODING *enc, \ } \ } \ *fromP = from; \ + if (from < fromLim) \ + return XML_CONVERT_INPUT_INCOMPLETE; \ + else \ + return XML_CONVERT_COMPLETED; \ } #define DEFINE_UTF16_TO_UTF16(E) \ -static void PTRCALL \ -E ## toUtf16(const ENCODING *enc, \ +static enum XML_Convert_Result PTRCALL \ +E ## toUtf16(const ENCODING *UNUSED_P(enc), \ const char **fromP, const char *fromLim, \ unsigned short **toP, const unsigned short *toLim) \ { \ + enum XML_Convert_Result res = XML_CONVERT_COMPLETED; \ + fromLim = *fromP + (((fromLim - *fromP) >> 1) << 1); /* shrink to even */ \ /* Avoid copying first half only of surrogate */ \ if (fromLim - *fromP > ((toLim - *toP) << 1) \ - && (GET_HI(fromLim - 2) & 0xF8) == 0xD8) \ + && (GET_HI(fromLim - 2) & 0xF8) == 0xD8) { \ fromLim -= 2; \ - for (; *fromP != fromLim && *toP != toLim; *fromP += 2) \ + res = XML_CONVERT_INPUT_INCOMPLETE; \ + } \ + for (; *fromP < fromLim && *toP < toLim; *fromP += 2) \ *(*toP)++ = (GET_HI(*fromP) << 8) | GET_LO(*fromP); \ + if ((*toP == toLim) && (*fromP < fromLim)) \ + return XML_CONVERT_OUTPUT_EXHAUSTED; \ + else \ + return res; \ } #define SET2(ptr, ch) \ @@ -726,7 +817,7 @@ static const struct normal_encoding little2_encoding_ns = { #include "asciitab.h" #include "latin1tab.h" }, - STANDARD_VTABLE(little2_) + STANDARD_VTABLE(little2_) NULL_VTABLE }; #endif @@ -745,7 +836,7 @@ static const struct normal_encoding little2_encoding = { #undef BT_COLON #include "latin1tab.h" }, - STANDARD_VTABLE(little2_) + STANDARD_VTABLE(little2_) NULL_VTABLE }; #if BYTEORDER != 4321 @@ -758,7 +849,7 @@ static const struct normal_encoding internal_little2_encoding_ns = { #include "iasciitab.h" #include "latin1tab.h" }, - STANDARD_VTABLE(little2_) + STANDARD_VTABLE(little2_) NULL_VTABLE }; #endif @@ -771,7 +862,7 @@ static const struct normal_encoding internal_little2_encoding = { #undef BT_COLON #include "latin1tab.h" }, - STANDARD_VTABLE(little2_) + STANDARD_VTABLE(little2_) NULL_VTABLE }; #endif @@ -867,7 +958,7 @@ static const struct normal_encoding big2_encoding_ns = { #include "asciitab.h" #include "latin1tab.h" }, - STANDARD_VTABLE(big2_) + STANDARD_VTABLE(big2_) NULL_VTABLE }; #endif @@ -886,7 +977,7 @@ static const struct normal_encoding big2_encoding = { #undef BT_COLON #include "latin1tab.h" }, - STANDARD_VTABLE(big2_) + STANDARD_VTABLE(big2_) NULL_VTABLE }; #if BYTEORDER != 1234 @@ -899,7 +990,7 @@ static const struct normal_encoding internal_big2_encoding_ns = { #include "iasciitab.h" #include "latin1tab.h" }, - STANDARD_VTABLE(big2_) + STANDARD_VTABLE(big2_) NULL_VTABLE }; #endif @@ -912,7 +1003,7 @@ static const struct normal_encoding internal_big2_encoding = { #undef BT_COLON #include "latin1tab.h" }, - STANDARD_VTABLE(big2_) + STANDARD_VTABLE(big2_) NULL_VTABLE }; #endif @@ -938,7 +1029,7 @@ streqci(const char *s1, const char *s2) } static void PTRCALL -initUpdatePosition(const ENCODING *enc, const char *ptr, +initUpdatePosition(const ENCODING *UNUSED_P(enc), const char *ptr, const char *end, POSITION *pos) { normal_updatePosition(&utf8_encoding.enc, ptr, end, pos); @@ -1288,7 +1379,7 @@ unknown_isInvalid(const ENCODING *enc, const char *p) return (c & ~0xFFFF) || checkCharRefNumber(c) < 0; } -static void PTRCALL +static enum XML_Convert_Result PTRCALL unknown_toUtf8(const ENCODING *enc, const char **fromP, const char *fromLim, char **toP, const char *toLim) @@ -1299,21 +1390,21 @@ unknown_toUtf8(const ENCODING *enc, const char *utf8; int n; if (*fromP == fromLim) - break; + return XML_CONVERT_COMPLETED; utf8 = uenc->utf8[(unsigned char)**fromP]; n = *utf8++; if (n == 0) { int c = uenc->convert(uenc->userData, *fromP); n = XmlUtf8Encode(c, buf); if (n > toLim - *toP) - break; + return XML_CONVERT_OUTPUT_EXHAUSTED; utf8 = buf; *fromP += (AS_NORMAL_ENCODING(enc)->type[(unsigned char)**fromP] - (BT_LEAD2 - 2)); } else { if (n > toLim - *toP) - break; + return XML_CONVERT_OUTPUT_EXHAUSTED; (*fromP)++; } do { @@ -1322,13 +1413,13 @@ unknown_toUtf8(const ENCODING *enc, } } -static void PTRCALL +static enum XML_Convert_Result PTRCALL unknown_toUtf16(const ENCODING *enc, const char **fromP, const char *fromLim, unsigned short **toP, const unsigned short *toLim) { const struct unknown_encoding *uenc = AS_UNKNOWN_ENCODING(enc); - while (*fromP != fromLim && *toP != toLim) { + while (*fromP < fromLim && *toP < toLim) { unsigned short c = uenc->utf16[(unsigned char)**fromP]; if (c == 0) { c = (unsigned short) @@ -1340,6 +1431,11 @@ unknown_toUtf16(const ENCODING *enc, (*fromP)++; *(*toP)++ = c; } + + if ((*toP == toLim) && (*fromP < fromLim)) + return XML_CONVERT_OUTPUT_EXHAUSTED; + else + return XML_CONVERT_COMPLETED; } ENCODING * @@ -1503,7 +1599,7 @@ initScan(const ENCODING * const *encodingTable, { const ENCODING **encPtr; - if (ptr == end) + if (ptr >= end) return XML_TOK_NONE; encPtr = enc->encPtr; if (ptr + 1 == end) { diff --git a/Modules/expat/xmltok.h b/Modules/expat/xmltok.h index ca867aa6b429cf..752007e8b9e219 100644 --- a/Modules/expat/xmltok.h +++ b/Modules/expat/xmltok.h @@ -130,6 +130,12 @@ typedef int (PTRCALL *SCANNER)(const ENCODING *, const char *, const char **); +enum XML_Convert_Result { + XML_CONVERT_COMPLETED = 0, + XML_CONVERT_INPUT_INCOMPLETE = 1, + XML_CONVERT_OUTPUT_EXHAUSTED = 2 /* and therefore potentially input remaining as well */ +}; + struct encoding { SCANNER scanners[XML_N_STATES]; SCANNER literalScanners[XML_N_LITERAL_TYPES]; @@ -158,12 +164,12 @@ struct encoding { const char *ptr, const char *end, const char **badPtr); - void (PTRCALL *utf8Convert)(const ENCODING *enc, + enum XML_Convert_Result (PTRCALL *utf8Convert)(const ENCODING *enc, const char **fromP, const char *fromLim, char **toP, const char *toLim); - void (PTRCALL *utf16Convert)(const ENCODING *enc, + enum XML_Convert_Result (PTRCALL *utf16Convert)(const ENCODING *enc, const char **fromP, const char *fromLim, unsigned short **toP, diff --git a/Modules/expat/xmltok_impl.c b/Modules/expat/xmltok_impl.c index 9c2895b87739ef..5f779c0571b5b1 100644 --- a/Modules/expat/xmltok_impl.c +++ b/Modules/expat/xmltok_impl.c @@ -87,27 +87,45 @@ #define PREFIX(ident) ident #endif + +#define HAS_CHARS(enc, ptr, end, count) \ + (end - ptr >= count * MINBPC(enc)) + +#define HAS_CHAR(enc, ptr, end) \ + HAS_CHARS(enc, ptr, end, 1) + +#define REQUIRE_CHARS(enc, ptr, end, count) \ + { \ + if (! HAS_CHARS(enc, ptr, end, count)) { \ + return XML_TOK_PARTIAL; \ + } \ + } + +#define REQUIRE_CHAR(enc, ptr, end) \ + REQUIRE_CHARS(enc, ptr, end, 1) + + /* ptr points to character following " */ switch (BYTE_TYPE(enc, ptr + MINBPC(enc))) { case BT_S: case BT_CR: case BT_LF: case BT_PERCNT: @@ -175,7 +191,7 @@ PREFIX(scanDecl)(const ENCODING *enc, const char *ptr, } static int PTRCALL -PREFIX(checkPiTarget)(const ENCODING *enc, const char *ptr, +PREFIX(checkPiTarget)(const ENCODING *UNUSED_P(enc), const char *ptr, const char *end, int *tokPtr) { int upper = 0; @@ -225,15 +241,14 @@ PREFIX(scanPi)(const ENCODING *enc, const char *ptr, { int tok; const char *target = ptr; - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) default: *nextTokPtr = ptr; return XML_TOK_INVALID; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) case BT_S: case BT_CR: case BT_LF: @@ -242,13 +257,12 @@ PREFIX(scanPi)(const ENCODING *enc, const char *ptr, return XML_TOK_INVALID; } ptr += MINBPC(enc); - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { INVALID_CASES(ptr, nextTokPtr) case BT_QUEST: ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); if (CHAR_MATCHES(enc, ptr, ASCII_GT)) { *nextTokPtr = ptr + MINBPC(enc); return tok; @@ -266,8 +280,7 @@ PREFIX(scanPi)(const ENCODING *enc, const char *ptr, return XML_TOK_INVALID; } ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); if (CHAR_MATCHES(enc, ptr, ASCII_GT)) { *nextTokPtr = ptr + MINBPC(enc); return tok; @@ -282,15 +295,14 @@ PREFIX(scanPi)(const ENCODING *enc, const char *ptr, } static int PTRCALL -PREFIX(scanCdataSection)(const ENCODING *enc, const char *ptr, +PREFIX(scanCdataSection)(const ENCODING *UNUSED_P(enc), const char *ptr, const char *end, const char **nextTokPtr) { static const char CDATA_LSQB[] = { ASCII_C, ASCII_D, ASCII_A, ASCII_T, ASCII_A, ASCII_LSQB }; int i; /* CDATA[ */ - if (end - ptr < 6 * MINBPC(enc)) - return XML_TOK_PARTIAL; + REQUIRE_CHARS(enc, ptr, end, 6); for (i = 0; i < 6; i++, ptr += MINBPC(enc)) { if (!CHAR_MATCHES(enc, ptr, CDATA_LSQB[i])) { *nextTokPtr = ptr; @@ -305,7 +317,7 @@ static int PTRCALL PREFIX(cdataSectionTok)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr == end) + if (ptr >= end) return XML_TOK_NONE; if (MINBPC(enc) > 1) { size_t n = end - ptr; @@ -319,13 +331,11 @@ PREFIX(cdataSectionTok)(const ENCODING *enc, const char *ptr, switch (BYTE_TYPE(enc, ptr)) { case BT_RSQB: ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); if (!CHAR_MATCHES(enc, ptr, ASCII_RSQB)) break; ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); if (!CHAR_MATCHES(enc, ptr, ASCII_GT)) { ptr -= MINBPC(enc); break; @@ -334,8 +344,7 @@ PREFIX(cdataSectionTok)(const ENCODING *enc, const char *ptr, return XML_TOK_CDATA_SECT_CLOSE; case BT_CR: ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); if (BYTE_TYPE(enc, ptr) == BT_LF) ptr += MINBPC(enc); *nextTokPtr = ptr; @@ -348,7 +357,7 @@ PREFIX(cdataSectionTok)(const ENCODING *enc, const char *ptr, ptr += MINBPC(enc); break; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { #define LEAD_CASE(n) \ case BT_LEAD ## n: \ @@ -383,19 +392,18 @@ static int PTRCALL PREFIX(scanEndTag)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) default: *nextTokPtr = ptr; return XML_TOK_INVALID; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) case BT_S: case BT_CR: case BT_LF: - for (ptr += MINBPC(enc); ptr != end; ptr += MINBPC(enc)) { + for (ptr += MINBPC(enc); HAS_CHAR(enc, ptr, end); ptr += MINBPC(enc)) { switch (BYTE_TYPE(enc, ptr)) { case BT_S: case BT_CR: case BT_LF: break; @@ -432,7 +440,7 @@ static int PTRCALL PREFIX(scanHexCharRef)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr != end) { + if (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { case BT_DIGIT: case BT_HEX: @@ -441,7 +449,7 @@ PREFIX(scanHexCharRef)(const ENCODING *enc, const char *ptr, *nextTokPtr = ptr; return XML_TOK_INVALID; } - for (ptr += MINBPC(enc); ptr != end; ptr += MINBPC(enc)) { + for (ptr += MINBPC(enc); HAS_CHAR(enc, ptr, end); ptr += MINBPC(enc)) { switch (BYTE_TYPE(enc, ptr)) { case BT_DIGIT: case BT_HEX: @@ -464,7 +472,7 @@ static int PTRCALL PREFIX(scanCharRef)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr != end) { + if (HAS_CHAR(enc, ptr, end)) { if (CHAR_MATCHES(enc, ptr, ASCII_x)) return PREFIX(scanHexCharRef)(enc, ptr + MINBPC(enc), end, nextTokPtr); switch (BYTE_TYPE(enc, ptr)) { @@ -474,7 +482,7 @@ PREFIX(scanCharRef)(const ENCODING *enc, const char *ptr, *nextTokPtr = ptr; return XML_TOK_INVALID; } - for (ptr += MINBPC(enc); ptr != end; ptr += MINBPC(enc)) { + for (ptr += MINBPC(enc); HAS_CHAR(enc, ptr, end); ptr += MINBPC(enc)) { switch (BYTE_TYPE(enc, ptr)) { case BT_DIGIT: break; @@ -496,8 +504,7 @@ static int PTRCALL PREFIX(scanRef)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) case BT_NUM: @@ -506,7 +513,7 @@ PREFIX(scanRef)(const ENCODING *enc, const char *ptr, const char *end, *nextTokPtr = ptr; return XML_TOK_INVALID; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) case BT_SEMI: @@ -529,7 +536,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, #ifdef XML_NS int hadColon = 0; #endif - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) #ifdef XML_NS @@ -540,8 +547,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, } hadColon = 1; ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) default: @@ -555,8 +561,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, int t; ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); t = BYTE_TYPE(enc, ptr); if (t == BT_EQUALS) break; @@ -579,8 +584,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, #endif for (;;) { ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); open = BYTE_TYPE(enc, ptr); if (open == BT_QUOT || open == BT_APOS) break; @@ -598,8 +602,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, /* in attribute value */ for (;;) { int t; - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); t = BYTE_TYPE(enc, ptr); if (t == open) break; @@ -624,8 +627,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, } } ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { case BT_S: case BT_CR: @@ -642,8 +644,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, /* ptr points to closing quote */ for (;;) { ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) case BT_S: case BT_CR: case BT_LF: @@ -655,8 +656,7 @@ PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, case BT_SOL: sol: ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); if (!CHAR_MATCHES(enc, ptr, ASCII_GT)) { *nextTokPtr = ptr; return XML_TOK_INVALID; @@ -688,13 +688,12 @@ PREFIX(scanLt)(const ENCODING *enc, const char *ptr, const char *end, #ifdef XML_NS int hadColon; #endif - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) case BT_EXCL: - if ((ptr += MINBPC(enc)) == end) - return XML_TOK_PARTIAL; + ptr += MINBPC(enc); + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { case BT_MINUS: return PREFIX(scanComment)(enc, ptr + MINBPC(enc), end, nextTokPtr); @@ -716,7 +715,7 @@ PREFIX(scanLt)(const ENCODING *enc, const char *ptr, const char *end, hadColon = 0; #endif /* we have a start-tag */ - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) #ifdef XML_NS @@ -727,8 +726,7 @@ PREFIX(scanLt)(const ENCODING *enc, const char *ptr, const char *end, } hadColon = 1; ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) default: @@ -740,7 +738,7 @@ PREFIX(scanLt)(const ENCODING *enc, const char *ptr, const char *end, case BT_S: case BT_CR: case BT_LF: { ptr += MINBPC(enc); - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) case BT_GT: @@ -765,8 +763,7 @@ PREFIX(scanLt)(const ENCODING *enc, const char *ptr, const char *end, case BT_SOL: sol: ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); if (!CHAR_MATCHES(enc, ptr, ASCII_GT)) { *nextTokPtr = ptr; return XML_TOK_INVALID; @@ -785,7 +782,7 @@ static int PTRCALL PREFIX(contentTok)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr == end) + if (ptr >= end) return XML_TOK_NONE; if (MINBPC(enc) > 1) { size_t n = end - ptr; @@ -803,7 +800,7 @@ PREFIX(contentTok)(const ENCODING *enc, const char *ptr, const char *end, return PREFIX(scanRef)(enc, ptr + MINBPC(enc), end, nextTokPtr); case BT_CR: ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return XML_TOK_TRAILING_CR; if (BYTE_TYPE(enc, ptr) == BT_LF) ptr += MINBPC(enc); @@ -814,12 +811,12 @@ PREFIX(contentTok)(const ENCODING *enc, const char *ptr, const char *end, return XML_TOK_DATA_NEWLINE; case BT_RSQB: ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return XML_TOK_TRAILING_RSQB; if (!CHAR_MATCHES(enc, ptr, ASCII_RSQB)) break; ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return XML_TOK_TRAILING_RSQB; if (!CHAR_MATCHES(enc, ptr, ASCII_GT)) { ptr -= MINBPC(enc); @@ -832,7 +829,7 @@ PREFIX(contentTok)(const ENCODING *enc, const char *ptr, const char *end, ptr += MINBPC(enc); break; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { #define LEAD_CASE(n) \ case BT_LEAD ## n: \ @@ -845,12 +842,12 @@ PREFIX(contentTok)(const ENCODING *enc, const char *ptr, const char *end, LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) #undef LEAD_CASE case BT_RSQB: - if (ptr + MINBPC(enc) != end) { + if (HAS_CHARS(enc, ptr, end, 2)) { if (!CHAR_MATCHES(enc, ptr + MINBPC(enc), ASCII_RSQB)) { ptr += MINBPC(enc); break; } - if (ptr + 2*MINBPC(enc) != end) { + if (HAS_CHARS(enc, ptr, end, 3)) { if (!CHAR_MATCHES(enc, ptr + 2*MINBPC(enc), ASCII_GT)) { ptr += MINBPC(enc); break; @@ -884,8 +881,7 @@ static int PTRCALL PREFIX(scanPercent)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) case BT_S: case BT_LF: case BT_CR: case BT_PERCNT: @@ -895,7 +891,7 @@ PREFIX(scanPercent)(const ENCODING *enc, const char *ptr, const char *end, *nextTokPtr = ptr; return XML_TOK_INVALID; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) case BT_SEMI: @@ -913,15 +909,14 @@ static int PTRCALL PREFIX(scanPoundName)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) default: *nextTokPtr = ptr; return XML_TOK_INVALID; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) case BT_CR: case BT_LF: case BT_S: @@ -941,7 +936,7 @@ PREFIX(scanLit)(int open, const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { int t = BYTE_TYPE(enc, ptr); switch (t) { INVALID_CASES(ptr, nextTokPtr) @@ -950,7 +945,7 @@ PREFIX(scanLit)(int open, const ENCODING *enc, ptr += MINBPC(enc); if (t != open) break; - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return -XML_TOK_LITERAL; *nextTokPtr = ptr; switch (BYTE_TYPE(enc, ptr)) { @@ -973,7 +968,7 @@ PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { int tok; - if (ptr == end) + if (ptr >= end) return XML_TOK_NONE; if (MINBPC(enc) > 1) { size_t n = end - ptr; @@ -992,8 +987,7 @@ PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, case BT_LT: { ptr += MINBPC(enc); - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); switch (BYTE_TYPE(enc, ptr)) { case BT_EXCL: return PREFIX(scanDecl)(enc, ptr + MINBPC(enc), end, nextTokPtr); @@ -1021,7 +1015,7 @@ PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, case BT_S: case BT_LF: for (;;) { ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) break; switch (BYTE_TYPE(enc, ptr)) { case BT_S: case BT_LF: @@ -1048,11 +1042,10 @@ PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, return XML_TOK_OPEN_BRACKET; case BT_RSQB: ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return -XML_TOK_CLOSE_BRACKET; if (CHAR_MATCHES(enc, ptr, ASCII_RSQB)) { - if (ptr + MINBPC(enc) == end) - return XML_TOK_PARTIAL; + REQUIRE_CHARS(enc, ptr, end, 2); if (CHAR_MATCHES(enc, ptr + MINBPC(enc), ASCII_GT)) { *nextTokPtr = ptr + 2*MINBPC(enc); return XML_TOK_COND_SECT_CLOSE; @@ -1065,7 +1058,7 @@ PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, return XML_TOK_OPEN_PAREN; case BT_RPAR: ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return -XML_TOK_CLOSE_PAREN; switch (BYTE_TYPE(enc, ptr)) { case BT_AST: @@ -1141,7 +1134,7 @@ PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, *nextTokPtr = ptr; return XML_TOK_INVALID; } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) case BT_GT: case BT_RPAR: case BT_COMMA: @@ -1154,8 +1147,7 @@ PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, ptr += MINBPC(enc); switch (tok) { case XML_TOK_NAME: - if (ptr == end) - return XML_TOK_PARTIAL; + REQUIRE_CHAR(enc, ptr, end); tok = XML_TOK_PREFIXED_NAME; switch (BYTE_TYPE(enc, ptr)) { CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) @@ -1204,10 +1196,12 @@ PREFIX(attributeValueTok)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { const char *start; - if (ptr == end) + if (ptr >= end) return XML_TOK_NONE; + else if (! HAS_CHAR(enc, ptr, end)) + return XML_TOK_PARTIAL; start = ptr; - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { #define LEAD_CASE(n) \ case BT_LEAD ## n: ptr += n; break; @@ -1232,7 +1226,7 @@ PREFIX(attributeValueTok)(const ENCODING *enc, const char *ptr, case BT_CR: if (ptr == start) { ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return XML_TOK_TRAILING_CR; if (BYTE_TYPE(enc, ptr) == BT_LF) ptr += MINBPC(enc); @@ -1262,10 +1256,12 @@ PREFIX(entityValueTok)(const ENCODING *enc, const char *ptr, const char *end, const char **nextTokPtr) { const char *start; - if (ptr == end) + if (ptr >= end) return XML_TOK_NONE; + else if (! HAS_CHAR(enc, ptr, end)) + return XML_TOK_PARTIAL; start = ptr; - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { #define LEAD_CASE(n) \ case BT_LEAD ## n: ptr += n; break; @@ -1294,7 +1290,7 @@ PREFIX(entityValueTok)(const ENCODING *enc, const char *ptr, case BT_CR: if (ptr == start) { ptr += MINBPC(enc); - if (ptr == end) + if (! HAS_CHAR(enc, ptr, end)) return XML_TOK_TRAILING_CR; if (BYTE_TYPE(enc, ptr) == BT_LF) ptr += MINBPC(enc); @@ -1326,15 +1322,15 @@ PREFIX(ignoreSectionTok)(const ENCODING *enc, const char *ptr, end = ptr + n; } } - while (ptr != end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { INVALID_CASES(ptr, nextTokPtr) case BT_LT: - if ((ptr += MINBPC(enc)) == end) - return XML_TOK_PARTIAL; + ptr += MINBPC(enc); + REQUIRE_CHAR(enc, ptr, end); if (CHAR_MATCHES(enc, ptr, ASCII_EXCL)) { - if ((ptr += MINBPC(enc)) == end) - return XML_TOK_PARTIAL; + ptr += MINBPC(enc); + REQUIRE_CHAR(enc, ptr, end); if (CHAR_MATCHES(enc, ptr, ASCII_LSQB)) { ++level; ptr += MINBPC(enc); @@ -1342,11 +1338,11 @@ PREFIX(ignoreSectionTok)(const ENCODING *enc, const char *ptr, } break; case BT_RSQB: - if ((ptr += MINBPC(enc)) == end) - return XML_TOK_PARTIAL; + ptr += MINBPC(enc); + REQUIRE_CHAR(enc, ptr, end); if (CHAR_MATCHES(enc, ptr, ASCII_RSQB)) { - if ((ptr += MINBPC(enc)) == end) - return XML_TOK_PARTIAL; + ptr += MINBPC(enc); + REQUIRE_CHAR(enc, ptr, end); if (CHAR_MATCHES(enc, ptr, ASCII_GT)) { ptr += MINBPC(enc); if (level == 0) { @@ -1373,7 +1369,7 @@ PREFIX(isPublicId)(const ENCODING *enc, const char *ptr, const char *end, { ptr += MINBPC(enc); end -= MINBPC(enc); - for (; ptr != end; ptr += MINBPC(enc)) { + for (; HAS_CHAR(enc, ptr, end); ptr += MINBPC(enc)) { switch (BYTE_TYPE(enc, ptr)) { case BT_DIGIT: case BT_HEX: @@ -1521,7 +1517,7 @@ PREFIX(getAtts)(const ENCODING *enc, const char *ptr, } static int PTRFASTCALL -PREFIX(charRefNumber)(const ENCODING *enc, const char *ptr) +PREFIX(charRefNumber)(const ENCODING *UNUSED_P(enc), const char *ptr) { int result = 0; /* skip &# */ @@ -1565,7 +1561,7 @@ PREFIX(charRefNumber)(const ENCODING *enc, const char *ptr) } static int PTRCALL -PREFIX(predefinedEntityName)(const ENCODING *enc, const char *ptr, +PREFIX(predefinedEntityName)(const ENCODING *UNUSED_P(enc), const char *ptr, const char *end) { switch ((end - ptr)/MINBPC(enc)) { @@ -1683,11 +1679,11 @@ PREFIX(sameName)(const ENCODING *enc, const char *ptr1, const char *ptr2) } static int PTRCALL -PREFIX(nameMatchesAscii)(const ENCODING *enc, const char *ptr1, +PREFIX(nameMatchesAscii)(const ENCODING *UNUSED_P(enc), const char *ptr1, const char *end1, const char *ptr2) { for (; *ptr2; ptr1 += MINBPC(enc), ptr2++) { - if (ptr1 == end1) + if (end1 - ptr1 < MINBPC(enc)) return 0; if (!CHAR_MATCHES(enc, ptr1, *ptr2)) return 0; @@ -1744,7 +1740,7 @@ PREFIX(updatePosition)(const ENCODING *enc, const char *end, POSITION *pos) { - while (ptr < end) { + while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { #define LEAD_CASE(n) \ case BT_LEAD ## n: \ @@ -1760,7 +1756,7 @@ PREFIX(updatePosition)(const ENCODING *enc, case BT_CR: pos->lineNumber++; ptr += MINBPC(enc); - if (ptr != end && BYTE_TYPE(enc, ptr) == BT_LF) + if (HAS_CHAR(enc, ptr, end) && BYTE_TYPE(enc, ptr) == BT_LF) ptr += MINBPC(enc); pos->columnNumber = (XML_Size)-1; break; diff --git a/Modules/pyexpat.c b/Modules/pyexpat.c index 6a901f756cabfc..53d34459d152d1 100644 --- a/Modules/pyexpat.c +++ b/Modules/pyexpat.c @@ -1107,10 +1107,8 @@ newxmlparseobject(char *encoding, char *namespace_separator, PyObject *intern) Py_DECREF(self); return NULL; } -#if ((XML_MAJOR_VERSION >= 2) && (XML_MINOR_VERSION >= 1)) || defined(XML_HAS_SET_HASH_SALT) - /* This feature was added upstream in libexpat 2.1.0. Our expat copy - * has a backport of this feature where we also define XML_HAS_SET_HASH_SALT - * to indicate that we can still use it. */ +#if XML_COMBINED_VERSION >= 20100 + /* This feature was added upstream in libexpat 2.1.0. */ XML_SetHashSalt(self->itself, (unsigned long)_Py_HashSecret.expat.hashsalt); #endif diff --git a/PCbuild/_elementtree.vcxproj b/PCbuild/_elementtree.vcxproj index 7802ab30ae227d..3bd513ffddbf15 100644 --- a/PCbuild/_elementtree.vcxproj +++ b/PCbuild/_elementtree.vcxproj @@ -164,7 +164,7 @@ ..\Modules\expat;%(AdditionalIncludeDirectories) - XML_NS;XML_DTD;BYTEORDER=1234;XML_CONTEXT_BYTES=1024;USE_PYEXPAT_CAPI;XML_STATIC;HAVE_MEMMOVE;%(PreprocessorDefinitions) + _CRT_SECURE_NO_WARNINGS;USE_PYEXPAT_CAPI;XML_STATIC;%(PreprocessorDefinitions) 0x1D100000 @@ -267,4 +267,4 @@ - \ No newline at end of file + From cc54c1c0d2d05fe7404ba64c53df4b1352ed2262 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 12 Jul 2017 14:51:46 +0200 Subject: [PATCH 07/24] bpo-30500: urllib: Simplify splithost by calling into urlparse. (#1849) (#2291) The current regex based splitting produces a wrong result. For example:: http://abc#@def Web browsers parse that URL as ``http://abc/#@def``, that is, the host is ``abc``, the path is ``/``, and the fragment is ``#@def``. (cherry picked from commit 90e01e50ef8a9e6c91f30d965563c378a4ad26de) --- Lib/test/test_urlparse.py | 51 ++++++++++++++----- Lib/urllib/parse.py | 2 +- Misc/ACKS | 1 + .../2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst | 4 ++ 4 files changed, 45 insertions(+), 13 deletions(-) create mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst diff --git a/Lib/test/test_urlparse.py b/Lib/test/test_urlparse.py index 1775ef33536655..f087cedbe00c59 100644 --- a/Lib/test/test_urlparse.py +++ b/Lib/test/test_urlparse.py @@ -681,28 +681,35 @@ def test_default_scheme(self): def test_parse_fragments(self): # Exercise the allow_fragments parameter of urlparse() and urlsplit() tests = ( - ("http:#frag", "path"), - ("//example.net#frag", "path"), - ("index.html#frag", "path"), - (";a=b#frag", "params"), - ("?a=b#frag", "query"), - ("#frag", "path"), + ("http:#frag", "path", "frag"), + ("//example.net#frag", "path", "frag"), + ("index.html#frag", "path", "frag"), + (";a=b#frag", "params", "frag"), + ("?a=b#frag", "query", "frag"), + ("#frag", "path", "frag"), + ("abc#@frag", "path", "@frag"), + ("//abc#@frag", "path", "@frag"), + ("//abc:80#@frag", "path", "@frag"), + ("//abc#@frag:80", "path", "@frag:80"), ) - for url, attr in tests: + for url, attr, expected_frag in tests: for func in (urllib.parse.urlparse, urllib.parse.urlsplit): if attr == "params" and func is urllib.parse.urlsplit: attr = "path" with self.subTest(url=url, function=func): result = func(url, allow_fragments=False) self.assertEqual(result.fragment, "") - self.assertTrue(getattr(result, attr).endswith("#frag")) + self.assertTrue( + getattr(result, attr).endswith("#" + expected_frag)) self.assertEqual(func(url, "", False).fragment, "") result = func(url, allow_fragments=True) - self.assertEqual(result.fragment, "frag") - self.assertFalse(getattr(result, attr).endswith("frag")) - self.assertEqual(func(url, "", True).fragment, "frag") - self.assertEqual(func(url).fragment, "frag") + self.assertEqual(result.fragment, expected_frag) + self.assertFalse( + getattr(result, attr).endswith(expected_frag)) + self.assertEqual(func(url, "", True).fragment, + expected_frag) + self.assertEqual(func(url).fragment, expected_frag) def test_mixed_types_rejected(self): # Several functions that process either strings or ASCII encoded bytes @@ -883,6 +890,26 @@ def test_splithost(self): self.assertEqual(splithost('/foo/bar/baz.html'), (None, '/foo/bar/baz.html')) + # bpo-30500: # starts a fragment. + self.assertEqual(splithost('//127.0.0.1#@host.com'), + ('127.0.0.1', '/#@host.com')) + self.assertEqual(splithost('//127.0.0.1#@host.com:80'), + ('127.0.0.1', '/#@host.com:80')) + self.assertEqual(splithost('//127.0.0.1:80#@host.com'), + ('127.0.0.1:80', '/#@host.com')) + + # Empty host is returned as empty string. + self.assertEqual(splithost("///file"), + ('', '/file')) + + # Trailing semicolon, question mark and hash symbol are kept. + self.assertEqual(splithost("//example.net/file;"), + ('example.net', '/file;')) + self.assertEqual(splithost("//example.net/file?"), + ('example.net', '/file?')) + self.assertEqual(splithost("//example.net/file#"), + ('example.net', '/file#')) + def test_splituser(self): splituser = urllib.parse.splituser self.assertEqual(splituser('User:Pass@www.python.org:080'), diff --git a/Lib/urllib/parse.py b/Lib/urllib/parse.py index d36833111fb9c1..d7b4e8846328ce 100644 --- a/Lib/urllib/parse.py +++ b/Lib/urllib/parse.py @@ -865,7 +865,7 @@ def splithost(url): """splithost('//host[:port]/path') --> 'host[:port]', '/path'.""" global _hostprog if _hostprog is None: - _hostprog = re.compile('^//([^/?]*)(.*)$') + _hostprog = re.compile('//([^/#?]*)(.*)', re.DOTALL) match = _hostprog.match(url) if match: diff --git a/Misc/ACKS b/Misc/ACKS index bc188119b205be..2e45f3d014bf04 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -994,6 +994,7 @@ Max Neunhöffer Anthon van der Neut George Neville-Neil Hieu Nguyen +Nam Nguyen Johannes Nicolai Samuel Nicolary Jonathan Niehof diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst new file mode 100644 index 00000000000000..6570e709d6bfac --- /dev/null +++ b/Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst @@ -0,0 +1,4 @@ +Fix urllib.parse.splithost() to correctly parse fragments. For example, +``splithost('//127.0.0.1#@evil.com/')`` now correctly returns the +``127.0.0.1`` host, instead of treating ``@evil.com`` as the host in an +authentification (``login@host``). From 6f6bc1da8aaae52664e7747e328d26eb59c0e74f Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 12 Jul 2017 14:52:04 +0200 Subject: [PATCH 08/24] bpo-26657: Fix Windows directory traversal vulnerability with http.server (#782) Based on patch by Philipp Hagemeister. This fixes a regression caused by revision f4377699fd47. (cherry picked from commit d274b3f1f1e2d8811733fb952c9f18d7da3a376a) --- Lib/http/server.py | 6 +++--- Lib/test/test_httpservers.py | 19 +++++++++++++++++++ .../2017-07-11-22-07-03.bpo-26657.wvpzFD.rst | 3 +++ 3 files changed, 25 insertions(+), 3 deletions(-) create mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst diff --git a/Lib/http/server.py b/Lib/http/server.py index 4688096b31c47b..2cfd3172a137e4 100644 --- a/Lib/http/server.py +++ b/Lib/http/server.py @@ -817,9 +817,9 @@ def translate_path(self, path): words = filter(None, words) path = os.getcwd() for word in words: - drive, word = os.path.splitdrive(word) - head, word = os.path.split(word) - if word in (os.curdir, os.pardir): continue + if os.path.dirname(word) or word in (os.curdir, os.pardir): + # Ignore components that are not a simple file/directory name + continue path = os.path.join(path, word) if trailing_slash: path += '/' diff --git a/Lib/test/test_httpservers.py b/Lib/test/test_httpservers.py index 6e5f2db7fdd36b..64a576570312f8 100644 --- a/Lib/test/test_httpservers.py +++ b/Lib/test/test_httpservers.py @@ -12,6 +12,7 @@ import sys import re import base64 +import ntpath import shutil import urllib.parse import html @@ -829,6 +830,24 @@ def test_start_with_double_slash(self): path = self.handler.translate_path('//filename?foo=bar') self.assertEqual(path, self.translated) + def test_windows_colon(self): + with support.swap_attr(server.os, 'path', ntpath): + path = self.handler.translate_path('c:c:c:foo/filename') + path = path.replace(ntpath.sep, os.sep) + self.assertEqual(path, self.translated) + + path = self.handler.translate_path('\\c:../filename') + path = path.replace(ntpath.sep, os.sep) + self.assertEqual(path, self.translated) + + path = self.handler.translate_path('c:\\c:..\\foo/filename') + path = path.replace(ntpath.sep, os.sep) + self.assertEqual(path, self.translated) + + path = self.handler.translate_path('c:c:foo\\c:c:bar/filename') + path = path.replace(ntpath.sep, os.sep) + self.assertEqual(path, self.translated) + class MiscTestCase(unittest.TestCase): def test_all(self): diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst new file mode 100644 index 00000000000000..ac1dc14d061a7b --- /dev/null +++ b/Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst @@ -0,0 +1,3 @@ +Fix directory traversal vulnerability with http.server on Windows. This +fixes a regression that was introduced in 3.3.4rc1 and 3.4.0rc1. Based on +patch by Philipp Hagemeister. From 34fae03cd6c9e304e02c571b3bf9e8df0cfe76be Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 22 Jul 2017 22:07:10 +0300 Subject: [PATCH 09/24] [3.4] bpo-26617: Ensure gc tracking is off when invoking weakref callbacks. (#2695) * [3.4] bpo-26617: Ensure gc tracking is off when invoking weakref callbacks. (cherry picked from commit 8f657c35b978b681e6e919f08358992e1aed7dc1) * Rewrite a NEWS entry as a NEWS.d entry. --- Lib/test/test_weakref.py | 8 ++++++ .../2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst | 1 + Objects/typeobject.c | 25 ++++++++++--------- 3 files changed, 22 insertions(+), 12 deletions(-) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst diff --git a/Lib/test/test_weakref.py b/Lib/test/test_weakref.py index 4313c1d5c85620..28f012f084f8a4 100644 --- a/Lib/test/test_weakref.py +++ b/Lib/test/test_weakref.py @@ -827,6 +827,14 @@ def test_set_callback_attribute(self): with self.assertRaises(AttributeError): ref1.__callback__ = lambda ref: None + def test_callback_gcs(self): + class ObjectWithDel(Object): + def __del__(self): pass + x = ObjectWithDel(1) + ref1 = weakref.ref(x, lambda ref: support.gc_collect()) + del x + support.gc_collect() + class SubclassableWeakrefTestCase(TestBase): diff --git a/Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst b/Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst new file mode 100644 index 00000000000000..c3a41396df8f53 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst @@ -0,0 +1 @@ +Fix crash when GC runs during weakref callbacks. diff --git a/Objects/typeobject.c b/Objects/typeobject.c index ca5355a7dafc15..2fae4d7359022f 100644 --- a/Objects/typeobject.c +++ b/Objects/typeobject.c @@ -1116,11 +1116,6 @@ subtype_dealloc(PyObject *self) Py_TRASHCAN_SAFE_BEGIN(self); --_PyTrash_delete_nesting; -- tstate->trash_delete_nesting; - /* DO NOT restore GC tracking at this point. weakref callbacks - * (if any, and whether directly here or indirectly in something we - * call) may trigger GC, and if self is tracked at that point, it - * will look like trash to GC and GC will try to delete self again. - */ /* Find the nearest base with a different tp_dealloc */ base = type; @@ -1131,30 +1126,36 @@ subtype_dealloc(PyObject *self) has_finalizer = type->tp_finalize || type->tp_del; - /* Maybe call finalizer; exit early if resurrected */ - if (has_finalizer) - _PyObject_GC_TRACK(self); - if (type->tp_finalize) { + _PyObject_GC_TRACK(self); if (PyObject_CallFinalizerFromDealloc(self) < 0) { /* Resurrected */ goto endlabel; } + _PyObject_GC_UNTRACK(self); } - /* If we added a weaklist, we clear it. Do this *before* calling - tp_del, clearing slots, or clearing the instance dict. */ + /* + If we added a weaklist, we clear it. Do this *before* calling tp_del, + clearing slots, or clearing the instance dict. + + GC tracking must be off at this point. weakref callbacks (if any, and + whether directly here or indirectly in something we call) may trigger GC, + and if self is tracked at that point, it will look like trash to GC and GC + will try to delete self again. + */ if (type->tp_weaklistoffset && !base->tp_weaklistoffset) PyObject_ClearWeakRefs(self); if (type->tp_del) { + _PyObject_GC_TRACK(self); type->tp_del(self); if (self->ob_refcnt > 0) { /* Resurrected */ goto endlabel; } + _PyObject_GC_UNTRACK(self); } if (has_finalizer) { - _PyObject_GC_UNTRACK(self); /* New weakrefs could be created during the finalizer call. If this occurs, clear them out without calling their finalizers since they might rely on part of the object From 3b3a5a5b70dc468dcfacb17a3d6b342820b480ff Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Sat, 22 Jul 2017 15:18:44 -0400 Subject: [PATCH 10/24] bpo-30939: Avoid Sphinx deprecation warning in docs build. (#2721) (#2724) (cherry picked from commit 50f58163a69abe2f35e91044d1df165ee7bdbb42) --- Doc/tools/extensions/pyspecific.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 64a56655f7fc94..169060c1cdcd93 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -15,6 +15,7 @@ from time import asctime from pprint import pformat from docutils.io import StringOutput +from docutils.parsers.rst import Directive from docutils.utils import new_document from docutils import nodes, utils @@ -22,7 +23,6 @@ from sphinx import addnodes from sphinx.builders import Builder from sphinx.util.nodes import split_explicit_title -from sphinx.util.compat import Directive from sphinx.writers.html import HTMLTranslator from sphinx.writers.text import TextWriter from sphinx.writers.latex import LaTeXTranslator From b1549175ed30f2931e2bb980a7e3c360ed19e1c9 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Sat, 22 Jul 2017 21:22:31 +0200 Subject: [PATCH 11/24] [3.4] Backport CI config from master (#2475) * Issues #23808, #25911: Trying to fix walk tests on Windows. On Windows a symlink can has the FILE_ATTRIBUTE_DIRECTORY flag. (cherry picked from commit 388b90f28e029daaf06aae8026b596e2f20a1cd3) * bpo-30231: Remove skipped test_imaplib tests (#1419) (#2193) The public cyrus.andrew.cmu.edu IMAP server (port 993) doesn't accept TLS connection using our self-signed x509 certificate. Remove the two tests which are already skipped. (cherry picked from commit 7895a0585b4b6a1c8082d17227307c6ce2c8bb8b) * Backport CI config from master * Add .travis.yml for Travis CI * Add .github/ for AppVeyor and CodeCov. * Travis CI: remove "make regen-all" check The regen-all Makefile rule doesn't exist in Python 3.4, only since Python 3.5 and newer (and 2.7). * appveyor: replace --slowest with --slow * Travis CI: remove the GCC coverage job * Travis CI: remove tzdata resource from regrtest tzdata resource doesn't exist in Python 3.4. * Travis CI: remove the doc job Fixing Sphinx warnings requires to backport huge intrusive changes like: - commit d97b7dc94b19063f0589d401bdc4aaadc7030762 - commit 5c6793394066b012b9674681b0815667938ce4d9 * appveyor: set version to 3.4.6+ * bpo-30730: Fix test_os tests. Fix test_invalid_cmd() and test_invalid_env(), TypeError is raised on Python 3.4. (cherry picked from commit 5e22721e586344b547194f0f7ea67fd425f94e72) --- .github/CONTRIBUTING.rst | 47 +++++++++++++++++++++++++ .github/appveyor.yml | 28 +++++++++++++++ .travis.yml | 68 +++++++++++++++++++++++++++++++++++++ Lib/test/test_imaplib.py | 10 ------ Lib/test/test_os.py | 6 +++- Lib/test/test_subprocess.py | 8 ++--- 6 files changed, 152 insertions(+), 15 deletions(-) create mode 100644 .github/CONTRIBUTING.rst create mode 100644 .github/appveyor.yml create mode 100644 .travis.yml diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst new file mode 100644 index 00000000000000..83cfee34b45cfb --- /dev/null +++ b/.github/CONTRIBUTING.rst @@ -0,0 +1,47 @@ +Contributing to Python +====================== + +Build Status +------------ + +- master + + + `Stable buildbots `_ + +- 3.6 + + + `Stable buildbots `_ + +- 3.5 + + + `Stable buildbots `_ + +- 2.7 + + + `Stable buildbots `_ + + +Contribution Guidelines +----------------------- +Please read the `devguide `_ for +guidance on how to contribute to this project. The documentation covers +everything from how to build the code to submitting a pull request. There are +also suggestions on how you can most effectively help the project. + +Please be aware that our workflow does deviate slightly from the typical GitHub +project. Details on how to properly submit a pull request are covered in +`Lifecycle of a Pull Request `_. +One key point is to keep comments on GitHub to only those related to the reviewing +the code in the pull request. All other discussions -- e.g. about the issue being +fixed -- should happen on bugs.python.org. + +If you are making a code contribution or large documentation contribution, +please feel free to add yourself to the ``Misc/ACKS`` file alphabetically. + + +Code of Conduct +--------------- +All interactions for this project are covered by the +`PSF Code of Conduct `_. Everyone is +expected to be open, considerate, and respectful of others no matter their +position within the project. diff --git a/.github/appveyor.yml b/.github/appveyor.yml new file mode 100644 index 00000000000000..e71346fa2b2e73 --- /dev/null +++ b/.github/appveyor.yml @@ -0,0 +1,28 @@ +version: 3.4.6+.{build} +clone_depth: 5 +branches: + only: + - master + - /\d\.\d/ + - buildbot-custom +build_script: +- cmd: PCbuild\build.bat -e +test_script: +- cmd: PCbuild\rt.bat -q -uall -u-cpu -rwW --slow --timeout=1200 -j0 + +# Only trigger AppVeyor if actual code or its configuration changes +only_commits: + files: + - .github/appveyor.yml + - .gitattributes + - Grammar/ + - Include/ + - Lib/ + - Modules/ + - Objects/ + - PC/ + - PCBuild/ + - Parser/ + - Programs/ + - Python/ + - Tools/ diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000000000..169ec5c51e0872 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,68 @@ +language: c +dist: trusty +sudo: false +group: beta + +# To cache doc-building dependencies. +cache: pip + +branches: + only: + - master + - /^\d\.\d$/ + +matrix: + fast_finish: true + allow_failures: + - env: OPTIONAL=true + include: + - os: linux + language: c + compiler: clang + # gcc also works, but to keep the # of concurrent builds down, we use one C + # compiler here and the other to run the coverage build. Clang is preferred + # in this instance for its better error messages. + env: TESTING=cpython + - os: osx + language: c + compiler: clang + # Testing under macOS is optional until testing stability has been demonstrated. + env: OPTIONAL=true + before_install: + - brew install openssl xz + - export CPPFLAGS="-I$(brew --prefix openssl)/include" + - export LDFLAGS="-L$(brew --prefix openssl)/lib" + +# Travis provides only 2 cores, so don't overdo the parallelism and waste memory. +before_script: + - | + set -e + if ! git diff --name-only $TRAVIS_COMMIT_RANGE | grep -qvE '(\.rst$)|(^Doc)|(^Misc)' + then + echo "Only docs were updated, stopping build process." + exit + fi + ./configure --with-pydebug + make -j4 + +script: + # Using the built Python as patchcheck.py is built around the idea of using + # a checkout-build of CPython to know things like what base branch the changes + # should be compared against. + # Only run on Linux as the check only needs to be run once. + - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi + # `-r -w` implicitly provided through `make buildbottest`. + - make buildbottest TESTOPTS="-j4 -uall,-cpu" + +notifications: + email: false + irc: + channels: + # This is set to a secure variable to prevent forks from notifying the + # IRC channel whenever they fail a build. This can be removed when travis + # implements https://github.com/travis-ci/travis-ci/issues/1094. + # The actual value here is: irc.freenode.net#python-dev + - secure: "s7kAkpcom2yUJ8XqyjFI0obJmhAGrn1xmoivdaPdgBIA++X47TBp1x4pgDsbEsoalef7bEwa4l07KdT4qa+DOd/c4QxaWom7fbN3BuLVsZuVfODnl79+gYq/TAbGfyH+yDs18DXrUfPgwD7C5aW32ugsqAOd4iWzfGJQ5OrOZzqzGjYdYQUEkJFXgxDEIb4aHvxNDWGO3Po9uKISrhb5saQ0l776yLo1Ur7M4oxl8RTbCdgX0vf5TzPg52BgvZpOgt3DHOUYPeiJLKNjAE6ibg0U95sEvMfHX77nz4aFY4/3UI6FFaRla34rZ+mYKrn0TdxOhera1QOgPmM6HzdO4K44FpfK1DS0Xxk9U9/uApq+cG0bU3W+cVUHDBe5+90lpRBAXHeHCgT7TI8gec614aiT8lEr3+yH8OBRYGzkjNK8E2LJZ/SxnVxDe7aLF6AWcoWLfS6/ziAIBFQ5Nc4U72CT8fGVSkl8ywPiRlvixKdvTODMSZo0jMqlfZSNaAPTsNRx4wu5Uis4qekwe32Fz4aB6KGpsuuVjBi+H6v0RKxNJNGY3JKDiEH2TK0UE2auJ5GvLW48aUVFcQMB7euCWYXlSWVRHh3WLU8QXF29Dw4JduRZqUpOdRgMHU79UHRq+mkE0jAS/nBcS6CvsmxCpTSrfVYuMOu32yt18QQoTyU=" + on_success: change + on_failure: always + skip_join: true diff --git a/Lib/test/test_imaplib.py b/Lib/test/test_imaplib.py index 838411e76fe691..68a710561327f6 100644 --- a/Lib/test/test_imaplib.py +++ b/Lib/test/test_imaplib.py @@ -468,16 +468,6 @@ def test_logincapa(self): _server = self.imap_class(self.host, self.port) self.check_logincapa(_server) - def test_logincapa_with_client_certfile(self): - with transient_internet(self.host): - _server = self.imap_class(self.host, self.port, certfile=CERTFILE) - self.check_logincapa(_server) - - def test_logincapa_with_client_ssl_context(self): - with transient_internet(self.host): - _server = self.imap_class(self.host, self.port, ssl_context=self.create_ssl_context()) - self.check_logincapa(_server) - def test_logout(self): with transient_internet(self.host): _server = self.imap_class(self.host, self.port) diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py index e29b0d585c7230..c5f5937889f76b 100644 --- a/Lib/test/test_os.py +++ b/Lib/test/test_os.py @@ -770,7 +770,11 @@ def setUp(self): if support.can_symlink(): os.symlink(os.path.abspath(t2_path), self.link_path) os.symlink('broken', broken_link_path, True) - self.sub2_tree = (sub2_path, ["link"], ["broken_link", "tmp3"]) + if os.path.isdir(broken_link_path): + # On Windows a symlink can has the FILE_ATTRIBUTE_DIRECTORY flag. + self.sub2_tree = (sub2_path, ["broken_link", "link"], ["tmp3"]) + else: + self.sub2_tree = (sub2_path, ["link"], ["broken_link", "tmp3"]) else: self.sub2_tree = (sub2_path, [], ["tmp3"]) diff --git a/Lib/test/test_subprocess.py b/Lib/test/test_subprocess.py index 19b140239439cf..6d55f9bbf34ba4 100644 --- a/Lib/test/test_subprocess.py +++ b/Lib/test/test_subprocess.py @@ -609,24 +609,24 @@ def test_empty_env(self): def test_invalid_cmd(self): # null character in the command name cmd = sys.executable + '\0' - with self.assertRaises(ValueError): + with self.assertRaises((ValueError, TypeError)): subprocess.Popen([cmd, "-c", "pass"]) # null character in the command argument - with self.assertRaises(ValueError): + with self.assertRaises((ValueError, TypeError)): subprocess.Popen([sys.executable, "-c", "pass#\0"]) def test_invalid_env(self): # null character in the enviroment variable name newenv = os.environ.copy() newenv["FRUIT\0VEGETABLE"] = "cabbage" - with self.assertRaises(ValueError): + with self.assertRaises((ValueError, TypeError)): subprocess.Popen([sys.executable, "-c", "pass"], env=newenv) # null character in the enviroment variable value newenv = os.environ.copy() newenv["FRUIT"] = "orange\0VEGETABLE=cabbage" - with self.assertRaises(ValueError): + with self.assertRaises((ValueError, TypeError)): subprocess.Popen([sys.executable, "-c", "pass"], env=newenv) # equal character in the enviroment variable name From f067f7e2c1f1702e7302cbc6a5683a1c2d6a1d8e Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Sun, 23 Jul 2017 17:55:09 -0700 Subject: [PATCH 12/24] Switch to using blurb to manage Misc/NEWS! --- Doc/Makefile | 27 +- Doc/whatsnew/changelog.rst | 4 +- Misc/NEWS | 10637 ---------------- Misc/NEWS.d/3.3.0.rst | 27 + Misc/NEWS.d/3.3.0a1.rst | 7646 +++++++++++ Misc/NEWS.d/3.3.0a2.rst | 684 + Misc/NEWS.d/3.3.0a3.rst | 730 ++ Misc/NEWS.d/3.3.0a4.rst | 814 ++ Misc/NEWS.d/3.3.0b1.rst | 944 ++ Misc/NEWS.d/3.3.0b2.rst | 1117 ++ Misc/NEWS.d/3.3.0rc1.rst | 411 + Misc/NEWS.d/3.3.0rc2.rst | 122 + Misc/NEWS.d/3.3.0rc3.rst | 98 + Misc/NEWS.d/3.4.0.rst | 17 + Misc/NEWS.d/3.4.0a1.rst | 7206 +++++++++++ Misc/NEWS.d/3.4.0a2.rst | 788 ++ Misc/NEWS.d/3.4.0a3.rst | 283 + Misc/NEWS.d/3.4.0a4.rst | 659 + Misc/NEWS.d/3.4.0b1.rst | 1451 +++ Misc/NEWS.d/3.4.0b2.rst | 1197 ++ Misc/NEWS.d/3.4.0b3.rst | 665 + Misc/NEWS.d/3.4.0rc1.rst | 715 ++ Misc/NEWS.d/3.4.0rc2.rst | 177 + Misc/NEWS.d/3.4.0rc3.rst | 66 + Misc/NEWS.d/3.4.1.rst | 117 + Misc/NEWS.d/3.4.1rc1.rst | 913 ++ Misc/NEWS.d/3.4.2.rst | 77 + Misc/NEWS.d/3.4.2rc1.rst | 1332 ++ Misc/NEWS.d/3.4.3.rst | 1238 ++ Misc/NEWS.d/3.4.4.rst | 7 + Misc/NEWS.d/3.4.4rc1.rst | 2504 ++++ Misc/NEWS.d/3.4.5.rst | 7 + Misc/NEWS.d/3.4.5rc1.rst | 101 + Misc/NEWS.d/3.4.6.rst | 7 + Misc/NEWS.d/3.4.6rc1.rst | 114 + .../Core and Builtins/04.bpo-27945.p29r3O.rst | 3 + .../Documentation/03.bpo-25008.CeIzyU.rst | 2 + .../next/Library/01.bpo-27850.kIVQ0m.rst | 2 + .../next/Security/02.bpo-30730.ZF8XGV.rst | 4 + 39 files changed, 32268 insertions(+), 10645 deletions(-) delete mode 100644 Misc/NEWS create mode 100644 Misc/NEWS.d/3.3.0.rst create mode 100644 Misc/NEWS.d/3.3.0a1.rst create mode 100644 Misc/NEWS.d/3.3.0a2.rst create mode 100644 Misc/NEWS.d/3.3.0a3.rst create mode 100644 Misc/NEWS.d/3.3.0a4.rst create mode 100644 Misc/NEWS.d/3.3.0b1.rst create mode 100644 Misc/NEWS.d/3.3.0b2.rst create mode 100644 Misc/NEWS.d/3.3.0rc1.rst create mode 100644 Misc/NEWS.d/3.3.0rc2.rst create mode 100644 Misc/NEWS.d/3.3.0rc3.rst create mode 100644 Misc/NEWS.d/3.4.0.rst create mode 100644 Misc/NEWS.d/3.4.0a1.rst create mode 100644 Misc/NEWS.d/3.4.0a2.rst create mode 100644 Misc/NEWS.d/3.4.0a3.rst create mode 100644 Misc/NEWS.d/3.4.0a4.rst create mode 100644 Misc/NEWS.d/3.4.0b1.rst create mode 100644 Misc/NEWS.d/3.4.0b2.rst create mode 100644 Misc/NEWS.d/3.4.0b3.rst create mode 100644 Misc/NEWS.d/3.4.0rc1.rst create mode 100644 Misc/NEWS.d/3.4.0rc2.rst create mode 100644 Misc/NEWS.d/3.4.0rc3.rst create mode 100644 Misc/NEWS.d/3.4.1.rst create mode 100644 Misc/NEWS.d/3.4.1rc1.rst create mode 100644 Misc/NEWS.d/3.4.2.rst create mode 100644 Misc/NEWS.d/3.4.2rc1.rst create mode 100644 Misc/NEWS.d/3.4.3.rst create mode 100644 Misc/NEWS.d/3.4.4.rst create mode 100644 Misc/NEWS.d/3.4.4rc1.rst create mode 100644 Misc/NEWS.d/3.4.5.rst create mode 100644 Misc/NEWS.d/3.4.5rc1.rst create mode 100644 Misc/NEWS.d/3.4.6.rst create mode 100644 Misc/NEWS.d/3.4.6rc1.rst create mode 100644 Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst create mode 100644 Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst create mode 100644 Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst create mode 100644 Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst diff --git a/Doc/Makefile b/Doc/Makefile index e3d204d84907bc..49a6f0f808d867 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -4,22 +4,24 @@ # # You can set these variables from the command line. -PYTHON = python +PYTHON = python3 SPHINXBUILD = sphinx-build +BLURB = $(PYTHON) -m blurb PAPER = SOURCES = DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) -ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \ +ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_elements.papersize=$(PAPER) \ $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES) .PHONY: help build html htmlhelp latex text changes linkcheck \ suspicious coverage doctest pydoc-topics htmlview clean dist check serve \ - autobuild-dev autobuild-stable + autobuild-dev autobuild-stable venv help: @echo "Please use \`make ' where is one of" @echo " clean to remove build files" + @echo " venv to create a venv with necessary tools" @echo " html to make standalone HTML files" @echo " htmlview to open the index page built by the html target in your browser" @echo " htmlhelp to make HTML files and a HTML help project" @@ -37,6 +39,8 @@ help: @echo " serve to serve the documentation on the localhost (8000)" build: + -mkdir -p build + $(BLURB) merge -f build/NEWS $(SPHINXBUILD) $(ALLSPHINXOPTS) @echo @@ -102,7 +106,11 @@ htmlview: html $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" clean: - -rm -rf build/* + -rm -rf build/* venv/* + +venv: + $(PYTHON) -m venv venv + ./venv/bin/python3 -m pip install -U Sphinx dist: rm -rf dist @@ -148,21 +156,26 @@ dist: cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub check: - $(PYTHON) tools/rstlint.py -i tools + $(PYTHON) tools/rstlint.py -i tools -i venv -i README.rst serve: ../Tools/scripts/serve.py build/html # Targets for daily automated doc build +# By default, Sphinx only rebuilds pages where the page content has changed. +# This means it doesn't always pick up changes to preferred link targets, etc +# To ensure such changes are picked up, we build the published docs with +# `-E` (to ignore the cached environment) and `-a` (to ignore already existing +# output files) # for development releases: always build autobuild-dev: - make dist SPHINXOPTS='-A daily=1 -A versionswitcher=1' + make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1' -make suspicious # for quick rebuilds (HTML only) autobuild-dev-html: - make html SPHINXOPTS='-A daily=1 -A versionswitcher=1' + make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1' # for stable releases: only build if not in pre-release stage (alpha, beta) # release candidate downloads are okay, since the stable tree can be in that stage diff --git a/Doc/whatsnew/changelog.rst b/Doc/whatsnew/changelog.rst index 07f90948bd0ad1..b4356143659031 100644 --- a/Doc/whatsnew/changelog.rst +++ b/Doc/whatsnew/changelog.rst @@ -1,5 +1,7 @@ +.. _changelog: + +++++++++ Changelog +++++++++ -.. miscnews:: ../../Misc/NEWS +.. miscnews:: ../build/NEWS diff --git a/Misc/NEWS b/Misc/NEWS deleted file mode 100644 index 88d6c70fd4a742..00000000000000 --- a/Misc/NEWS +++ /dev/null @@ -1,10637 +0,0 @@ -+++++++++++ -Python News -+++++++++++ - -What's New in Python 3.4.7 release candidate 1? -=============================================== - -Release date: XXXX-XX-XX - -Core and Builtins ------------------ - -- bpo-27945: Fixed various segfaults with dict when input collections are - mutated during searching, inserting or comparing. Based on patches by - Duane Griffin and Tim Mitchell. - -Documentation -------------- - -- bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to - aiosmtpd, a third-party asyncio-based replacement. - -Library -------- - -- [Security] bpo-30730: Prevent environment variables injection in subprocess on - Windows. Prevent passing other invalid environment variables and command arguments. - -- Issue #27850: Remove 3DES from ssl module's default cipher list to counter - measure sweet32 attack (CVE-2016-2183). - - -What's New in Python 3.4.6? -=========================== - -Release date: 2017-01-17 - -There were no changes between 3.4.6rc1 and 3.4.6 final. - - -What's New in Python 3.4.6rc1? -============================== - -Release date: 2017-01-02 - -Core and Builtins ------------------ - -- Issue #28648: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X - when decode astral characters. Patch by Xiang Zhang. - -- Issue #28426: Fixed potential crash in PyUnicode_AsDecodedObject() in debug - build. - -Library -------- - -- Issue #28563: Fixed possible DoS and arbitrary code execution when handle - plural form selections in the gettext module. The expression parser now - supports exact syntax supported by GNU gettext. - -- In the curses module, raise an error if window.getstr() or window.instr() is - passed a negative value. - -- Issue #27783: Fix possible usage of uninitialized memory in operator.methodcaller. - -- Issue #27774: Fix possible Py_DECREF on unowned object in _sre. - -- Issue #27760: Fix possible integer overflow in binascii.b2a_qp. - -- Issue #27758: Fix possible integer overflow in the _csv module for large record - lengths. - -- Issue #27568: Prevent HTTPoxy attack (CVE-2016-1000110). Ignore the - HTTP_PROXY variable when REQUEST_METHOD environment is set, which indicates - that the script is in CGI mode. - -- Issue #27759: Fix selectors incorrectly retain invalid file descriptors. - Patch by Mark Williams. - -Build ------ - -- Issue #28248: Update Windows build to use OpenSSL 1.0.2j. - -Tests ------ - -- Issue #27369: In test_pyexpat, avoid testing an error message detail that - changed in Expat 2.2.0. - - -What's New in Python 3.4.5? -=========================== - -Release date: 2016-06-26 - -Tests ------ - -- Issue #26867: Ubuntu's openssl OP_NO_SSLv3 is forced on by default; fix test. - - -What's New in Python 3.4.5rc1? -============================== - -Release date: 2016-06-11 - -Core and Builtins ------------------ - -- Issue #26478: Fix semantic bugs when using binary operators with dictionary - views and tuples. - -- Issue #26171: Fix possible integer overflow and heap corruption in - zipimporter.get_data(). - -Library -------- - -- Issue #26556: Update expat to 2.1.1, fixes CVE-2015-1283. - -- Fix TLS stripping vulnerability in smptlib, CVE-2016-0772. Reported by Team - Oststrom - -- Issue #25939: On Windows open the cert store readonly in ssl.enum_certificates. - -- Issue #26012: Don't traverse into symlinks for ** pattern in - pathlib.Path.[r]glob(). - -- Issue #24120: Ignore PermissionError when traversing a tree with - pathlib.Path.[r]glob(). Patch by Ulrich Petri. - -- Skip getaddrinfo if host is already resolved. - Patch by A. Jesse Jiryu Davis. - -- Add asyncio.timeout() context manager. - -- Issue #26050: Add asyncio.StreamReader.readuntil() method. - Patch by Марк Коренберг. - -Tests ------ - -- Issue #25940: Changed test_ssl to use self-signed.pythontest.net. This - avoids relying on svn.python.org, which recently changed root certificate. - - -What's New in Python 3.4.4? -=========================== - -Release date: 2015/12/20 - -Windows -------- - -- Issue #25844: Corrected =/== typo potentially leading to crash in launcher. - - -What's New in Python 3.4.4rc1? -============================== - -Release date: 2015/12/06 - -Core and Builtins ------------------ - -- Issue #25709: Fixed problem with in-place string concatenation and utf-8 - cache. - -- Issue #24097: Fixed crash in object.__reduce__() if slot name is freed inside - __getattr__. - -- Issue #24731: Fixed crash on converting objects with special methods - __bytes__, __trunc__, and __float__ returning instances of subclasses of - bytes, int, and float to subclasses of bytes, int, and float correspondingly. - -- Issue #25388: Fixed tokenizer crash when processing undecodable source code - with a null byte. - -- Issue #22995: Default implementation of __reduce__ and __reduce_ex__ now - rejects builtin types with not defined __new__. - -- Issue #24802: Avoid buffer overreads when int(), float(), compile(), exec() - and eval() are passed bytes-like objects. These objects are not - necessarily terminated by a null byte, but the functions assumed they were. - -- Issue #24402: Fix input() to prompt to the redirected stdout when - sys.stdout.fileno() fails. - -- Issue #24806: Prevent builtin types that are not allowed to be subclassed from - being subclassed through multiple inheritance. - -- Issue #24848: Fixed a number of bugs in UTF-7 decoding of misformed data. - -- Issue #25280: Import trace messages emitted in verbose (-v) mode are no - longer formatted twice. - -- Issue #25003: os.urandom() doesn't use getentropy() on Solaris because - getentropy() is blocking, whereas os.urandom() should not block. getentropy() - is supported since Solaris 11.3. - -- Issue #25182: The stdprinter (used as sys.stderr before the io module is - imported at startup) now uses the backslashreplace error handler. - -- Issue #24891: Fix a race condition at Python startup if the file descriptor - of stdin (0), stdout (1) or stderr (2) is closed while Python is creating - sys.stdin, sys.stdout and sys.stderr objects. These attributes are now set - to None if the creation of the object failed, instead of raising an OSError - exception. Initial patch written by Marco Paolini. - -- Issue #21167: NAN operations are now handled correctly when python is - compiled with ICC even if -fp-model strict is not specified. - -- Issue #4395: Better testing and documentation of binary operators. - Patch by Martin Panter. - -- Issue #24467: Fixed possible buffer over-read in bytearray. The bytearray - object now always allocates place for trailing null byte and it's buffer now - is always null-terminated. - -- Issue #24115: Update uses of PyObject_IsTrue(), PyObject_Not(), - PyObject_IsInstance(), PyObject_RichCompareBool() and _PyDict_Contains() - to check for and handle errors correctly. - -- Issue #24257: Fixed system error in the comparison of faked - types.SimpleNamespace. - -- Issue #22939: Fixed integer overflow in iterator object. Patch by - Clement Rouault. - -- Issue #23985: Fix a possible buffer overrun when deleting a slice from - the front of a bytearray and then appending some other bytes data. - -- Issue #24102: Fixed exception type checking in standard error handlers. - -- Issue #23757: PySequence_Tuple() incorrectly called the concrete list API - when the data was a list subclass. - -- Issue #24407: Fix crash when dict is mutated while being updated. - -- Issue #24096: Make warnings.warn_explicit more robust against mutation of the - warnings.filters list. - -- Issue #23996: Avoid a crash when a delegated generator raises an - unnormalized StopIteration exception. Patch by Stefan Behnel. - -- Issue #24022: Fix tokenizer crash when processing undecodable source code. - -- Issue #23309: Avoid a deadlock at shutdown if a daemon thread is aborted - while it is holding a lock to a buffered I/O object, and the main thread - tries to use the same I/O object (typically stdout or stderr). A fatal - error is emitted instead. - -- Issue #22977: Fixed formatting Windows error messages on Wine. - Patch by Martin Panter. - -- Issue #23803: Fixed str.partition() and str.rpartition() when a separator - is wider then partitioned string. - -- Issue #23192: Fixed generator lambdas. Patch by Bruno Cauet. - -- Issue #23629: Fix the default __sizeof__ implementation for variable-sized - objects. - -- Issue #24044: Fix possible null pointer dereference in list.sort in out of - memory conditions. - -- Issue #21354: PyCFunction_New function is exposed by python DLL again. - -Library -------- - -- Issue #24903: Fix regression in number of arguments compileall accepts when - '-d' is specified. The check on the number of arguments has been dropped - completely as it never worked correctly anyway. - -- Issue #25764: In the subprocess module, preserve any exception caused by - fork() failure when preexec_fn is used. - -- Issue #6478: _strptime's regexp cache now is reset after changing timezone - with time.tzset(). - -- Issue #25177: Fixed problem with the mean of very small and very large - numbers. As a side effect, statistics.mean and statistics.variance should - be significantly faster. - -- Issue #25718: Fixed copying object with state with boolean value is false. - -- Issue #10131: Fixed deep copying of minidom documents. Based on patch - by Marian Ganisin. - -- Issue #25725: Fixed a reference leak in pickle.loads() when unpickling - invalid data including tuple instructions. - -- Issue #25663: In the Readline completer, avoid listing duplicate global - names, and search the global namespace before searching builtins. - -- Issue #25688: Fixed file leak in ElementTree.iterparse() raising an error. - -- Issue #23914: Fixed SystemError raised by unpickler on broken pickle data. - -- Issue #25691: Fixed crash on deleting ElementTree.Element attributes. - -- Issue #25624: ZipFile now always writes a ZIP_STORED header for directory - entries. Patch by Dingyuan Wang. - -- Issue #25583: Avoid incorrect errors raised by os.makedirs(exist_ok=True) - when the OS gives priority to errors such as EACCES over EEXIST. - -- Issue #25593: Change semantics of EventLoop.stop() in asyncio. - -- Issue #6973: When we know a subprocess.Popen process has died, do - not allow the send_signal(), terminate(), or kill() methods to do - anything as they could potentially signal a different process. - -- Issue #25578: Fix (another) memory leak in SSLSocket.getpeercer(). - -- Issue #25590: In the Readline completer, only call getattr() once per - attribute. - -- Issue #25498: Fix a crash when garbage-collecting ctypes objects created - by wrapping a memoryview. This was a regression made in 3.4.3. Based - on patch by Eryksun. - -- Issue #18010: Fix the pydoc web server's module search function to handle - exceptions from importing packages. - -- Issue #25510: fileinput.FileInput.readline() now returns b'' instead of '' - at the end if the FileInput was opened with binary mode. - Patch by Ryosuke Ito. - -- Issue #25530: Disable the vulnerable SSLv3 protocol by default when creating - ssl.SSLContext. - -- Issue #25569: Fix memory leak in SSLSocket.getpeercert(). - -- Issue #21827: Fixed textwrap.dedent() for the case when largest common - whitespace is a substring of smallest leading whitespace. - Based on patch by Robert Li. - -- Issue #25471: Sockets returned from accept() shouldn't appear to be - nonblocking. - -- Issue #25441: asyncio: Raise error from drain() when socket is closed. - -- Issue #25411: Improved Unicode support in SMTPHandler through better use of - the email package. Thanks to user simon04 for the patch. - -- Issue #25380: Fixed protocol for the STACK_GLOBAL opcode in - pickletools.opcodes. - -- Issue #23972: Updates asyncio datagram create method allowing reuseport - and reuseaddr socket options to be set prior to binding the socket. - Mirroring the existing asyncio create_server method the reuseaddr option - for datagram sockets defaults to True if the O/S is 'posix' (except if the - platform is Cygwin). Patch by Chris Laws. - -- Issue #25304: Add asyncio.run_coroutine_threadsafe(). This lets you - submit a coroutine to a loop from another thread, returning a - concurrent.futures.Future. By Vincent Michel. - -- Issue #25319: When threading.Event is reinitialized, the underlying condition - should use a regular lock rather than a recursive lock. - -- Issue #25232: Fix CGIRequestHandler to split the query from the URL at the - first question mark (?) rather than the last. Patch from Xiang Zhang. - -- Issue #24657: Prevent CGIRequestHandler from collapsing slashes in the - query part of the URL as if it were a path. Patch from Xiang Zhang. - -- Issue #22958: Constructor and update method of weakref.WeakValueDictionary - now accept the self and the dict keyword arguments. - -- Issue #22609: Constructor of collections.UserDict now accepts the self keyword - argument. - -- Issue #25262. Added support for BINBYTES8 opcode in Python implementation of - unpickler. Highest 32 bits of 64-bit size for BINUNICODE8 and BINBYTES8 - opcodes no longer silently ignored on 32-bit platforms in C implementation. - -- Issue #25034: Fix string.Formatter problem with auto-numbering and - nested format_specs. Patch by Anthon van der Neut. - -- Issue #25233: Rewrite the guts of asyncio.Queue and - asyncio.Semaphore to be more understandable and correct. - -- Issue #23600: Default implementation of tzinfo.fromutc() was returning - wrong results in some cases. - -- Issue #25203: Failed readline.set_completer_delims() no longer left the - module in inconsistent state. - -- Prevent overflow in _Unpickler_Read. - -- Issue #25047: The XML encoding declaration written by Element Tree now - respects the letter case given by the user. This restores the ability to - write encoding names in uppercase like "UTF-8", which worked in Python 2. - -- Issue #19143: platform module now reads Windows version from kernel32.dll to - avoid compatibility shims. - -- Issue #23517: Fix rounding in fromtimestamp() and utcfromtimestamp() methods - of datetime.datetime: microseconds are now rounded to nearest with ties - going to nearest even integer (ROUND_HALF_EVEN), instead of being rounding - towards zero (ROUND_DOWN). It's important that these methods use the same - rounding mode than datetime.timedelta to keep the property: - (datetime(1970,1,1) + timedelta(seconds=t)) == datetime.utcfromtimestamp(t). - It also the rounding mode used by round(float) for example. - -- Issue #24684: socket.socket.getaddrinfo() now calls - PyUnicode_AsEncodedString() instead of calling the encode() method of the - host, to handle correctly custom string with an encode() method which doesn't - return a byte string. The encoder of the IDNA codec is now called directly - instead of calling the encode() method of the string. - -- Issue #24982: shutil.make_archive() with the "zip" format now adds entries - for directories (including empty directories) in ZIP file. - -- Issue #24857: Comparing call_args to a long sequence now correctly returns a - boolean result instead of raising an exception. Patch by A Kaptur. - -- Issue #25019: Fixed a crash caused by setting non-string key of expat parser. - Based on patch by John Leitch. - -- Issue #24917: time_strftime() buffer over-read. - -- Issue #23144: Make sure that HTMLParser.feed() returns all the data, even - when convert_charrefs is True. - -- Issue #16180: Exit pdb if file has syntax error, instead of trapping user - in an infinite loop. Patch by Xavier de Gaye. - -- Issue #21112: Fix regression in unittest.expectedFailure on subclasses. - Patch from Berker Peksag. - -- Issue #24931: Instances of subclasses of namedtuples have their own __dict__ - which breaks the inherited __dict__ property and breaks the _asdict() method. - Removed the __dict__ property to prevent the conflict and fixed _asdict(). - -- Issue #24764: cgi.FieldStorage.read_multi() now ignores the Content-Length - header in part headers. Patch written by Peter Landry and reviewed by Pierre - Quentel. - -- Issue #24774: Fix docstring in http.server.test. Patch from Chiu-Hsiang Hsu. - -- Issue #21159: Improve message in configparser.InterpolationMissingOptionError. - Patch from Łukasz Langa. - -- Issue #23888: Handle fractional time in cookie expiry. Patch by ssh. - -- Issue #23004: mock_open() now reads binary data correctly when the type of - read_data is bytes. Initial patch by Aaron Hill. - -- Issue #23652: Make it possible to compile the select module against the - libc headers from the Linux Standard Base, which do not include some - EPOLL macros. Patch by Matt Frank. - -- Issue #22932: Fix timezones in email.utils.formatdate. - Patch from Dmitry Shachnev. - -- Issue #23779: imaplib raises TypeError if authenticator tries to abort. - Patch from Craig Holmquist. - -- Issue #23319: Fix ctypes.BigEndianStructure, swap correctly bytes. Patch - written by Matthieu Gautier. - -- Issue #23254: Document how to close the TCPServer listening socket. - Patch from Martin Panter. - -- Issue #19450: Update Windows and OS X installer builds to use SQLite 3.8.11. - -- Issue #23441: rcompleter now prints a tab character instead of displaying - possible completions for an empty word. Initial patch by Martin Sekera. - -- Issue #24735: Fix invalid memory access in - itertools.combinations_with_replacement(). - -- Issue #17527: Add PATCH to wsgiref.validator. Patch from Luca Sbardella. - -- Issue #24683: Fixed crashes in _json functions called with arguments of - inappropriate type. - -- Issue #21697: shutil.copytree() now correctly handles symbolic links that - point to directories. Patch by Eduardo Seabra and Thomas Kluyver. - -- Issue #24620: Random.setstate() now validates the value of state last element. - -- Issue #22153: Improve unittest docs. Patch from Martin Panter and evilzero. - -- Issue #24206: Fixed __eq__ and __ne__ methods of inspect classes. - -- Issue #21750: mock_open.read_data can now be read from each instance, as it - could in Python 3.3. - -- Issue #23247: Fix a crash in the StreamWriter.reset() of CJK codecs. - -- Issue #18622: unittest.mock.mock_open().reset_mock would recurse infinitely. - Patch from Nicola Palumbo and Laurent De Buyst. - -- Issue #24608: chunk.Chunk.read() now always returns bytes, not str. - -- Issue #18684: Fixed reading out of the buffer in the re module. - -- Issue #24259: tarfile now raises a ReadError if an archive is truncated - inside a data segment. - -- Issue #24552: Fix use after free in an error case of the _pickle module. - -- Issue #24514: tarfile now tolerates number fields consisting of only - whitespace. - -- Issue #19176: Fixed doctype() related bugs in C implementation of ElementTree. - A deprecation warning no longer issued by XMLParser subclass with default - doctype() method. Direct call of doctype() now issues a warning. Parser's - doctype() now is not called if target's doctype() is called. Based on patch - by Martin Panter. - -- Issue #20387: Restore semantic round-trip correctness in tokenize/untokenize - for tab-indented blocks. - -- Issue #24456: Fixed possible buffer over-read in adpcm2lin() and lin2adpcm() - functions of the audioop module. - -- Issue #24336: The contextmanager decorator now works with functions with - keyword arguments called "func" and "self". Patch by Martin Panter. - -- Issue #24489: ensure a previously set C errno doesn't disturb cmath.polar(). - -- Issue #5633: Fixed timeit when the statement is a string and the setup is not. - -- Issue #24326: Fixed audioop.ratecv() with non-default weightB argument. - Original patch by David Moore. - -- Issue #23840: tokenize.open() now closes the temporary binary file on error - to fix a resource warning. - -- Issue #24257: Fixed segmentation fault in sqlite3.Row constructor with faked - cursor type. - -- Issue #22107: tempfile.gettempdir() and tempfile.mkdtemp() now try again - when a directory with the chosen name already exists on Windows as well as - on Unix. tempfile.mkstemp() now fails early if parent directory is not - valid (not exists or is a file) on Windows. - -- Issue #6598: Increased time precision and random number range in - email.utils.make_msgid() to strengthen the uniqueness of the message ID. - -- Issue #24091: Fixed various crashes in corner cases in C implementation of - ElementTree. - -- Issue #21931: msilib.FCICreate() now raises TypeError in the case of a bad - argument instead of a ValueError with a bogus FCI error number. - Patch by Jeffrey Armstrong. - -- Issue #23796: peek and read1 methods of BufferedReader now raise ValueError - if they called on a closed object. Patch by John Hergenroeder. - -- Issue #24521: Fix possible integer overflows in the pickle module. - -- Issue #22931: Allow '[' and ']' in cookie values. - -- Issue #20274: Remove ignored and erroneous "kwargs" parameters from three - METH_VARARGS methods on _sqlite.Connection. - -- Issue #24094: Fix possible crash in json.encode with poorly behaved dict - subclasses. - -- Asyncio issue 222 / PR 231 (Victor Stinner) -- fix @coroutine - functions without __name__. - -- Issue #9246: On POSIX, os.getcwd() now supports paths longer than 1025 bytes. - Patch written by William Orr. - -- The keywords attribute of functools.partial is now always a dictionary. - -- Issues #24099, #24100, and #24101: Fix free-after-use bug in heapq's siftup - and siftdown functions. - -- Backport collections.deque fixes from Python 3.5. Prevents reentrant badness - during deletion by deferring the decref until the container has been restored - to a consistent state. - -- Issue #23008: Fixed resolving attributes with boolean value is False in pydoc. - -- Fix asyncio issue 235: LifoQueue and PriorityQueue's put didn't - increment unfinished tasks (this bug was introduced in 3.4.3 when - JoinableQueue was merged with Queue). - -- Issue #23908: os functions now reject paths with embedded null character - on Windows instead of silently truncate them. - -- Issue #23728: binascii.crc_hqx() could return an integer outside of the range - 0-0xffff for empty data. - -- Issue #23811: Add missing newline to the PyCompileError error message. - Patch by Alex Shkop. - -- Issue #17898: Fix exception in gettext.py when parsing certain plural forms. - -- Issue #22982: Improve BOM handling when seeking to multiple positions of - a writable text file. - -- Issue #23865: close() methods in multiple modules now are idempotent and more - robust at shutdown. If they need to release multiple resources, all are - released even if errors occur. - -- Issue #23881: urllib.request.ftpwrapper constructor now closes the socket if - the FTP connection failed to fix a ResourceWarning. - -- Issue #23400: Raise same exception on both Python 2 and 3 if sem_open is not - available. Patch by Davin Potts. - -- Issue #15133: _tkinter.tkapp.getboolean() now supports Tcl_Obj and always - returns bool. tkinter.BooleanVar now validates input values (accepted bool, - int, str, and Tcl_Obj). tkinter.BooleanVar.get() now always returns bool. - -- Issue #23338: Fixed formatting ctypes error messages on Cygwin. - Patch by Makoto Kato. - -- Issue #16840: Tkinter now supports 64-bit integers added in Tcl 8.4 and - arbitrary precision integers added in Tcl 8.5. - -- Issue #23834: Fix socket.sendto(), use the C Py_ssize_t type to store the - result of sendto() instead of the C int type. - -- Issue #21526: Tkinter now supports new boolean type in Tcl 8.5. - -- Issue #23838: linecache now clears the cache and returns an empty result on - MemoryError. - -- Issue #18473: Fixed 2to3 and 3to2 compatible pickle mappings. Fixed - ambigious reverse mappings. Added many new mappings. Import mapping is no - longer applied to modules already mapped with full name mapping. - -- Issue #23745: The new email header parser now handles duplicate MIME - parameter names without error, similar to how get_param behaves. - -- Issue #23792: Ignore KeyboardInterrupt when the pydoc pager is active. - This mimics the behavior of the standard unix pagers, and prevents - pipepager from shutting down while the pager itself is still running. - -- Issue #23742: ntpath.expandvars() no longer loses unbalanced single quotes. - -- Issue #21802: The reader in BufferedRWPair now is closed even when closing - writer failed in BufferedRWPair.close(). - -- Issue #23671: string.Template now allows to specify the "self" parameter as - keyword argument. string.Formatter now allows to specify the "self" and - the "format_string" parameters as keyword arguments. - -- Issue #21560: An attempt to write a data of wrong type no longer cause - GzipFile corruption. Original patch by Wolfgang Maier. - -- Issue #23647: Increase impalib's MAXLINE to accommodate modern mailbox sizes. - -- Issue #23539: If body is None, http.client.HTTPConnection.request now sets - Content-Length to 0 for PUT, POST, and PATCH headers to avoid 411 errors from - some web servers. - -- Issue #22351: The nntplib.NNTP constructor no longer leaves the connection - and socket open until the garbage collector cleans them up. Patch by - Martin Panter. - -- Issue #23136: _strptime now uniformly handles all days in week 0, including - Dec 30 of previous year. Based on patch by Jim Carroll. - -- Issue #23700: Iterator of NamedTemporaryFile now keeps a reference to - NamedTemporaryFile instance. Patch by Bohuslav Kabrda. - -- Issue #22903: The fake test case created by unittest.loader when it fails - importing a test module is now picklable. - -- Issue #23568: Add rdivmod support to MagicMock() objects. - Patch by Håkan Lövdahl. - -- Issue #23138: Fixed parsing cookies with absent keys or values in cookiejar. - Patch by Demian Brecht. - -- Issue #23051: multiprocessing.Pool methods imap() and imap_unordered() now - handle exceptions raised by an iterator. Patch by Alon Diamant and Davin - Potts. - -- Issue #22928: Disabled HTTP header injections in http.client. - Original patch by Demian Brecht. - -- Issue #23615: Modules bz2, tarfile and tokenize now can be reloaded with - imp.reload(). Patch by Thomas Kluyver. - -- Issue #23476: In the ssl module, enable OpenSSL's X509_V_FLAG_TRUSTED_FIRST - flag on certificate stores when it is available. - -- Issue #23576: Avoid stalling in SSL reads when EOF has been reached in the - SSL layer but the underlying connection hasn't been closed. - -- Issue #23504: Added an __all__ to the types module. - -- Issue #20204: Added the __module__ attribute to _tkinter classes. - -- Issue #23521: Corrected pure python implementation of timedelta division. - - * Eliminated OverflowError from timedelta * float for some floats; - * Corrected rounding in timedlta true division. - -- Issue #21619: Popen objects no longer leave a zombie after exit in the with - statement if the pipe was broken. Patch by Martin Panter. - -- Issue #6639: Module-level turtle functions no longer raise TclError after - closing the window. - -- Issues #814253, #9179: Warnings now are raised when group references and - conditional group references are used in lookbehind assertions in regular - expressions. - -- Issue #23215: Multibyte codecs with custom error handlers that ignores errors - consumed too much memory and raised SystemError or MemoryError. - Original patch by Aleksi Torhamo. - -- Issue #5700: io.FileIO() called flush() after closing the file. - flush() was not called in close() if closefd=False. - -- Issue #23374: Fixed pydoc failure with non-ASCII files when stdout encoding - differs from file system encoding (e.g. on Mac OS). - -- Issue #23481: Remove RC4 from the SSL module's default cipher list. - -- Issue #21548: Fix pydoc.synopsis() and pydoc.apropos() on modules with empty - docstrings. - -- Issue #22885: Fixed arbitrary code execution vulnerability in the dbm.dumb - module. Original patch by Claudiu Popa. - -- Issue #23146: Fix mishandling of absolute Windows paths with forward - slashes in pathlib. - -- Issue #23421: Fixed compression in tarfile CLI. Patch by wdv4758h. - -- Issue #23367: Fix possible overflows in the unicodedata module. - -- Issue #23361: Fix possible overflow in Windows subprocess creation code. - -- Issue #23801: Fix issue where cgi.FieldStorage did not always ignore the - entire preamble to a multipart body. - -- Issue #23310: Fix MagicMock's initializer to work with __methods__, just - like configure_mock(). Patch by Kasia Jachim. - -- asyncio: New event loop APIs: set_task_factory() and get_task_factory(). - -- asyncio: async() function is deprecated in favour of ensure_future(). - -- Issue #23898: Fix inspect.classify_class_attrs() to support attributes - with overloaded __eq__ and __bool__. Patch by Mike Bayer. - -- Issue #24298: Fix inspect.signature() to correctly unwrap wrappers - around bound methods. - -- Issue #23572: Fixed functools.singledispatch on classes with falsy - metaclasses. Patch by Ethan Furman. - -IDLE ----- - -- Issue 15348: Stop the debugger engine (normally in a user process) - before closing the debugger window (running in the IDLE process). - This prevents the RuntimeErrors that were being caught and ignored. - -- Issue #24455: Prevent IDLE from hanging when a) closing the shell while the - debugger is active (15347); b) closing the debugger with the [X] button - (15348); and c) activating the debugger when already active (24455). - The patch by Mark Roseman does this by making two changes. - 1. Suspend and resume the gui.interaction method with the tcl vwait - mechanism intended for this purpose (instead of root.mainloop & .quit). - 2. In gui.run, allow any existing interaction to terminate first. - -- Change 'The program' to 'Your program' in an IDLE 'kill program?' message - to make it clearer that the program referred to is the currently running - user program, not IDLE itself. - -- Issue #24750: Improve the appearance of the IDLE editor window status bar. - Patch by Mark Roseman. - -- Issue #25313: Change the handling of new built-in text color themes to better - address the compatibility problem introduced by the addition of IDLE Dark. - Consistently use the revised idleConf.CurrentTheme everywhere in idlelib. - -- Issue #24782: Extension configuration is now a tab in the IDLE Preferences - dialog rather than a separate dialog. The former tabs are now a sorted - list. Patch by Mark Roseman. - -- Issue #22726: Re-activate the config dialog help button with some content - about the other buttons and the new IDLE Dark theme. - -- Issue #24820: IDLE now has an 'IDLE Dark' built-in text color theme. - It is more or less IDLE Classic inverted, with a cobalt blue background. - Strings, comments, keywords, ... are still green, red, orange, ... . - To use it with IDLEs released before November 2015, hit the - 'Save as New Custom Theme' button and enter a new name, - such as 'Custom Dark'. The custom theme will work with any IDLE - release, and can be modified. - -- Issue #25224: README.txt is now an idlelib index for IDLE developers and - curious users. The previous user content is now in the IDLE doc chapter. - 'IDLE' now means 'Integrated Development and Learning Environment'. - -- Issue #24820: Users can now set breakpoint colors in - Settings -> Custom Highlighting. Original patch by Mark Roseman. - -- Issue #24972: Inactive selection background now matches active selection - background, as configured by users, on all systems. Found items are now - always highlighted on Windows. Initial patch by Mark Roseman. - -- Issue #24570: Idle: make calltip and completion boxes appear on Macs - affected by a tk regression. Initial patch by Mark Roseman. - -- Issue #24988: Idle ScrolledList context menus (used in debugger) - now work on Mac Aqua. Patch by Mark Roseman. - -- Issue #24801: Make right-click for context menu work on Mac Aqua. - Patch by Mark Roseman. - -- Issue #25173: Associate tkinter messageboxes with a specific widget. - For Mac OSX, make them a 'sheet'. Patch by Mark Roseman. - -- Issue #25198: Enhance the initial html viewer now used for Idle Help. - * Properly indent fixed-pitch text (patch by Mark Roseman). - * Give code snippet a very Sphinx-like light blueish-gray background. - * Re-use initial width and height set by users for shell and editor. - * When the Table of Contents (TOC) menu is used, put the section header - at the top of the screen. - -- Issue #25225: Condense and rewrite Idle doc section on text colors. - -- Issue #21995: Explain some differences between IDLE and console Python. - -- Issue #22820: Explain need for *print* when running file from Idle editor. - -- Issue #25224: Doc: augment Idle feature list and no-subprocess section. - -- Issue #25219: Update doc for Idle command line options. - Some were missing and notes were not correct. - -- Issue #24861: Most of idlelib is private and subject to change. - Use idleib.idle.* to start Idle. See idlelib.__init__.__doc__. - -- Issue #25199: Idle: add synchronization comments for future maintainers. - -- Issue #16893: Replace help.txt with help.html for Idle doc display. - The new idlelib/help.html is rstripped Doc/build/html/library/idle.html. - It looks better than help.txt and will better document Idle as released. - The tkinter html viewer that works for this file was written by Mark Roseman. - The now unused EditorWindow.HelpDialog class and helt.txt file are deprecated. - -- Issue #24199: Deprecate unused idlelib.idlever with possible removal in 3.6. - -- Issue #24790: Remove extraneous code (which also create 2 & 3 conflicts). - -- Issue #23672: Allow Idle to edit and run files with astral chars in name. - Patch by Mohd Sanad Zaki Rizvi. - -- Issue 24745: Idle editor default font. Switch from Courier to - platform-sensitive TkFixedFont. This should not affect current customized - font selections. If there is a problem, edit $HOME/.idlerc/config-main.cfg - and remove 'fontxxx' entries from [Editor Window]. Patch by Mark Roseman. - -- Issue #21192: Idle editor. When a file is run, put its name in the restart bar. - Do not print false prompts. Original patch by Adnan Umer. - -- Issue #13884: Idle menus. Remove tearoff lines. Patch by Roger Serwy. - -- Issue #23184: remove unused names and imports in idlelib. - Initial patch by Al Sweigart. - -Tests ------ - -- Issue #25616: Tests for OrderedDict are extracted from test_collections - into separate file test_ordered_dict. - -- Issue #25099: Make test_compileall not fail when an entry on sys.path cannot - be written to (commonly seen in administrative installs on Windows). - -- Issue #24751: When running regrtest with the ``-w`` command line option, - a test run is no longer marked as a failure if all tests succeed when - re-run. - -- Issue #21520: test_zipfile no longer fails if the word 'bad' appears - anywhere in the name of the current directory. - -- Issue #23799: Added test.support.start_threads() for running and - cleaning up multiple threads. - -- Issue #22390: test.regrtest now emits a warning if temporary files or - directories are left after running a test. - -- Issue #23583: Added tests for standard IO streams in IDLE. - -Build ------ - -- Issue #23445: pydebug builds now use "gcc -Og" where possible, to make - the resulting executable faster. - -- Issue #24603: Update Windows builds to use OpenSSL1.0.2d - and OS X 10.5 installer to use OpenSSL 1.0.2e. - -C API ------ - -- Issue #23998: PyImport_ReInitLock() now checks for lock allocation error - -Documentation -------------- - -- Issue #12067: Rewrite Comparisons section in the Expressions chapter of the - language reference. Some of the details of comparing mixed types were - incorrect or ambiguous. NotImplemented is only relevant at a lower level - than the Expressions chapter. Added details of comparing range() objects, - and default behaviour and consistency suggestions for user-defined classes. - Patch from Andy Maier. - -- Issue #24952: Clarify the default size argument of stack_size() in - the "threading" and "_thread" modules. Patch from Mattip. - -- Issue #24808: Update the types of some PyTypeObject fields. Patch by - Joseph Weston. - -- Issue #22812: Fix unittest discovery examples. - Patch from Pam McA'Nulty. - -- Issue #24129: Clarify the reference documentation for name resolution. - This includes removing the assumption that readers will be familiar with the - name resolution scheme Python used prior to the introduction of lexical - scoping for function namespaces. Patch by Ivan Levkivskyi. - -- Issue #20769: Improve reload() docs. Patch by Dorian Pula. - -- Issue #23589: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan. - -- Issue #24729: Correct IO tutorial to match implementation regarding - encoding parameter to open function. - -- Issue #24351: Clarify what is meant by "identifier" in the context of - string.Template instances. - -- Issue #22155: Add File Handlers subsection with createfilehandler to tkinter - doc. Remove obsolete example from FAQ. Patch by Martin Panter. - -- Issue #24029: Document the name binding behavior for submodule imports. - -- Issue #24077: Fix typo in man page for -I command option: -s, not -S. - -Tools/Demos ------------ - -- Issue #25440: Fix output of python-config --extension-suffix. - -- Issue #23330: h2py now supports arbitrary filenames in #include. - -- Issue #24031: make patchcheck now supports git checkouts, too. - -Windows -------- - -- Issue #24306: Sets component ID for launcher to match 3.5 and later - to avoid downgrading. - -- Issue #25022: Removed very outdated PC/example_nt/ directory. - - -What's New in Python 3.4.3? -=========================== - -Release date: 2015-02-23 - -Core and Builtins ------------------ - -- Issue #22735: Fix many edge cases (including crashes) involving custom mro() - implementations. - -- Issue #22896: Avoid using PyObject_AsCharBuffer(), PyObject_AsReadBuffer() - and PyObject_AsWriteBuffer(). - -- Issue #21295: Revert some changes (issue #16795) to AST line numbers and - column offsets that constituted a regression. - -- Issue #21408: The default __ne__() now returns NotImplemented if __eq__() - returned NotImplemented. Original patch by Martin Panter. - -- Issue #23321: Fixed a crash in str.decode() when error handler returned - replacment string longer than mailformed input data. - -- Issue #23048: Fix jumping out of an infinite while loop in the pdb. - -- Issue #20335: bytes constructor now raises TypeError when encoding or errors - is specified with non-string argument. Based on patch by Renaud Blanch. - -- Issue #22335: Fix crash when trying to enlarge a bytearray to 0x7fffffff - bytes on a 32-bit platform. - -- Issue #22653: Fix an assertion failure in debug mode when doing a reentrant - dict insertion in debug mode. - -- Issue #22643: Fix integer overflow in Unicode case operations (upper, lower, - title, swapcase, casefold). - -- Issue #22604: Fix assertion error in debug mode when dividing a complex - number by (nan+0j). - -- Issue #22470: Fixed integer overflow issues in "backslashreplace", - "xmlcharrefreplace", and "surrogatepass" error handlers. - -- Issue #22520: Fix overflow checking when generating the repr of a unicode - object. - -- Issue #22519: Fix overflow checking in PyBytes_Repr. - -- Issue #22518: Fix integer overflow issues in latin-1 encoding. - -- Issue #23165: Perform overflow checks before allocating memory in the - _Py_char2wchar function. - -Library -------- - -- Issue #23399: pyvenv creates relative symlinks where possible. - -- Issue #23099: Closing io.BytesIO with exported buffer is rejected now to - prevent corrupting exported buffer. - -- Issue #23363: Fix possible overflow in itertools.permutations. - -- Issue #23364: Fix possible overflow in itertools.product. - -- Issue #23366: Fixed possible integer overflow in itertools.combinations. - -- Issue #23369: Fixed possible integer overflow in - _json.encode_basestring_ascii. - -- Issue #23353: Fix the exception handling of generators in - PyEval_EvalFrameEx(). At entry, save or swap the exception state even if - PyEval_EvalFrameEx() is called with throwflag=0. At exit, the exception state - is now always restored or swapped, not only if why is WHY_YIELD or - WHY_RETURN. Patch co-written with Antoine Pitrou. - -- Issue #18518: timeit now rejects statements which can't be compiled outside - a function or a loop (e.g. "return" or "break"). - -- Issue #23094: Fixed readline with frames in Python implementation of pickle. - -- Issue #23268: Fixed bugs in the comparison of ipaddress classes. - -- Issue #21408: Removed incorrect implementations of __ne__() which didn't - returned NotImplemented if __eq__() returned NotImplemented. The default - __ne__() now works correctly. - -- Issue #19996: :class:`email.feedparser.FeedParser` now handles (malformed) - headers with no key rather than assuming the body has started. - -- Issue #23248: Update ssl error codes from latest OpenSSL git master. - -- Issue #23098: 64-bit dev_t is now supported in the os module. - -- Issue #23250: In the http.cookies module, capitalize "HttpOnly" and "Secure" - as they are written in the standard. - -- Issue #23063: In the disutils' check command, fix parsing of reST with code or - code-block directives. - -- Issue #23209, #23225: selectors.BaseSelector.close() now clears its internal - reference to the selector mapping to break a reference cycle. Initial patch - written by Martin Richard. - -- Issue #21356: Make ssl.RAND_egd() optional to support LibreSSL. The - availability of the function is checked during the compilation. Patch written - by Bernard Spil. - -- Issue #20896, #22935: The :func:`ssl.get_server_certificate` function now - uses the :data:`~ssl.PROTOCOL_SSLv23` protocol by default, not - :data:`~ssl.PROTOCOL_SSLv3`, for maximum compatibility and support platforms - where :data:`~ssl.PROTOCOL_SSLv3` support is disabled. - -- Issue #23111: In the ftplib, make ssl.PROTOCOL_SSLv23 the default protocol - version. - -- Issue #23132: Mitigate regression in speed and clarity in functools.total_ordering. - -- Issue #22585: On OpenBSD 5.6 and newer, os.urandom() now calls getentropy(), - instead of reading /dev/urandom, to get pseudo-random bytes. - -- Issue #23112: Fix SimpleHTTPServer to correctly carry the query string and - fragment when it redirects to add a trailing slash. - -- Issue #23093: In the io, module allow more operations to work on detached - streams. - -- Issue #19104: pprint now produces evaluable output for wrapped strings. - -- Issue #23071: Added missing names to codecs.__all__. Patch by Martin Panter. - -- Issue #15513: Added a __sizeof__ implementation for pickle classes. - -- Issue #19858: pickletools.optimize() now aware of the MEMOIZE opcode, can - produce more compact result and no longer produces invalid output if input - data contains MEMOIZE opcodes together with PUT or BINPUT opcodes. - -- Issue #22095: Fixed HTTPConnection.set_tunnel with default port. The port - value in the host header was set to "None". Patch by Demian Brecht. - -- Issue #23016: A warning no longer produces an AttributeError when the program - is run with pythonw.exe. - -- Issue #21775: shutil.copytree(): fix crash when copying to VFAT. An exception - handler assumed that that OSError objects always have a 'winerror' attribute. - That is not the case, so the exception handler itself raised AttributeError - when run on Linux (and, presumably, any other non-Windows OS). - Patch by Greg Ward. - -- Issue #1218234: Fix inspect.getsource() to load updated source of - reloaded module. Initial patch by Berker Peksag. - -- Issue #22959: In the constructor of http.client.HTTPSConnection, prefer the - context's check_hostname attribute over the *check_hostname* parameter. - -- Issue #16043: Add a default limit for the amount of data xmlrpclib.gzip_decode - will return. This resolves CVE-2013-1753. - -- Issue #22966: Fix __pycache__ pyc file name clobber when pyc_compile is - asked to compile a source file containing multiple dots in the source file - name. - -- Issue #21971: Update turtledemo doc and add module to the index. - -- Issue #21032. Fixed socket leak if HTTPConnection.getresponse() fails. - Original patch by Martin Panter. - -- Issue #22960: Add a context argument to xmlrpclib.ServerProxy constructor. - -- Issue #22915: SAX parser now supports files opened with file descriptor or - bytes path. - -- Issue #22609: Constructors and update methods of mapping classes in the - collections module now accept the self keyword argument. - -- Issue #22788: Add *context* parameter to logging.handlers.HTTPHandler. - -- Issue #22921: Allow SSLContext to take the *hostname* parameter even if - OpenSSL doesn't support SNI. - -- Issue #22894: TestCase.subTest() would cause the test suite to be stopped - when in failfast mode, even in the absence of failures. - -- Issue #22638: SSLv3 is now disabled throughout the standard library. - It can still be enabled by instantiating a SSLContext manually. - -- Issue #22370: Windows detection in pathlib is now more robust. - -- Issue #22841: Reject coroutines in asyncio add_signal_handler(). - Patch by Ludovic.Gasc. - -- Issue #22849: Fix possible double free in the io.TextIOWrapper constructor. - -- Issue #12728: Different Unicode characters having the same uppercase but - different lowercase are now matched in case-insensitive regular expressions. - -- Issue #22821: Fixed fcntl() with integer argument on 64-bit big-endian - platforms. - -- Issue #22406: Fixed the uu_codec codec incorrectly ported to 3.x. - Based on patch by Martin Panter. - -- Issue #17293: uuid.getnode() now determines MAC address on AIX using netstat. - Based on patch by Aivars Kalvāns. - -- Issue #22769: Fixed ttk.Treeview.tag_has() when called without arguments. - -- Issue #22417: Verify certificates by default in httplib (PEP 476). - -- Issue #22775: Fixed unpickling of http.cookies.SimpleCookie with protocol 2 - and above. Patch by Tim Graham. - -- Issue #22366: urllib.request.urlopen will accept a context object - (SSLContext) as an argument which will then used be for HTTPS connection. - Patch by Alex Gaynor. - -- Issue #22776: Brought excluded code into the scope of a try block in - SysLogHandler.emit(). - -- Issue #22665: Add missing get_terminal_size and SameFileError to - shutil.__all__. - -- Issue #17381: Fixed handling of case-insensitive ranges in regular - expressions. - -- Issue #22410: Module level functions in the re module now cache compiled - locale-dependent regular expressions taking into account the locale. - -- Issue #22759: Query methods on pathlib.Path() (exists(), is_dir(), etc.) - now return False when the underlying stat call raises NotADirectoryError. - -- Issue #8876: distutils now falls back to copying files when hard linking - doesn't work. This allows use with special filesystems such as VirtualBox - shared folders. - -- Issue #18853: Fixed ResourceWarning in shlex.__nain__. - -- Issue #9351: Defaults set with set_defaults on an argparse subparser - are no longer ignored when also set on the parent parser. - -- Issue #21991: Make email.headerregistry's header 'params' attributes - be read-only (MappingProxyType). Previously the dictionary was modifiable - but a new one was created on each access of the attribute. - -- Issue #22641: In asyncio, the default SSL context for client connections - is now created using ssl.create_default_context(), for stronger security. - -- Issue #22435: Fix a file descriptor leak when SocketServer bind fails. - -- Issue #13096: Fixed segfault in CTypes POINTER handling of large - values. - -- Issue #11694: Raise ConversionError in xdrlib as documented. Patch - by Filip Gruszczyński and Claudiu Popa. - -- Issue #22462: Fix pyexpat's creation of a dummy frame to make it - appear in exception tracebacks. - -- Issue #21173: Fix len() on a WeakKeyDictionary when .clear() was called - with an iterator alive. - -- Issue #11866: Eliminated race condition in the computation of names - for new threads. - -- Issue #21905: Avoid RuntimeError in pickle.whichmodule() when sys.modules - is mutated while iterating. Patch by Olivier Grisel. - -- Issue #22219: The zipfile module CLI now adds entries for directories - (including empty directories) in ZIP file. - -- Issue #22449: In the ssl.SSLContext.load_default_certs, consult the - environmental variables SSL_CERT_DIR and SSL_CERT_FILE on Windows. - -- Issue #20076: Added non derived UTF-8 aliases to locale aliases table. - -- Issue #20079: Added locales supported in glibc 2.18 to locale alias table. - -- Issue #22396: On 32-bit AIX platform, don't expose os.posix_fadvise() nor - os.posix_fallocate() because their prototypes in system headers are wrong. - -- Issue #22517: When a io.BufferedRWPair object is deallocated, clear its - weakrefs. - -- Issue #22448: Improve canceled timer handles cleanup to prevent - unbound memory usage. Patch by Joshua Moore-Oliva. - -- Issue #23009: Make sure selectors.EpollSelecrtor.select() works when no - FD is registered. - -IDLE ----- - -- Issue #20577: Configuration of the max line length for the FormatParagraph - extension has been moved from the General tab of the Idle preferences dialog - to the FormatParagraph tab of the Config Extensions dialog. - Patch by Tal Einat. - -- Issue #16893: Update Idle doc chapter to match current Idle and add new - information. - -- Issue #3068: Add Idle extension configuration dialog to Options menu. - Changes are written to HOME/.idlerc/config-extensions.cfg. - Original patch by Tal Einat. - -- Issue #16233: A module browser (File : Class Browser, Alt+C) requires an - editor window with a filename. When Class Browser is requested otherwise, - from a shell, output window, or 'Untitled' editor, Idle no longer displays - an error box. It now pops up an Open Module box (Alt+M). If a valid name - is entered and a module is opened, a corresponding browser is also opened. - -- Issue #4832: Save As to type Python files automatically adds .py to the - name you enter (even if your system does not display it). Some systems - automatically add .txt when type is Text files. - -- Issue #21986: Code objects are not normally pickled by the pickle module. - To match this, they are no longer pickled when running under Idle. - -- Issue #23180: Rename IDLE "Windows" menu item to "Window". - Patch by Al Sweigart. - -Tests ------ - -- Issue #23392: Added tests for marshal C API that works with FILE*. - -- Issue #18982: Add tests for CLI of the calendar module. - -- Issue #19548: Added some additional checks to test_codecs to ensure that - statements in the updated documentation remain accurate. Patch by Martin - Panter. - -- Issue #22838: All test_re tests now work with unittest test discovery. - -- Issue #22173: Update lib2to3 tests to use unittest test discovery. - -- Issue #16000: Convert test_curses to use unittest. - -- Issue #21456: Skip two tests in test_urllib2net.py if _ssl module not - present. Patch by Remi Pointel. - -- Issue #22770: Prevent some Tk segfaults on OS X when running gui tests. - -- Issue #23211: Workaround test_logging failure on some OS X 10.6 systems. - -- Issue #23345: Prevent test_ssl failures with large OpenSSL patch level - values (like 0.9.8zc). - -- Issue #22289: Prevent test_urllib2net failures due to ftp connection timeout. - -Build ------ - -- Issue #15506: Use standard PKG_PROG_PKG_CONFIG autoconf macro in the configure - script. - -- Issue #22935: Allow the ssl module to be compiled if openssl doesn't support - SSL 3. - -- Issue #16537: Check whether self.extensions is empty in setup.py. Patch by - Jonathan Hosmer. - -- Issue #18096: Fix library order returned by python-config. - -- Issue #17219: Add library build dir for Python extension cross-builds. - -- Issue #17128: Use private version of OpenSSL for 3.4.3 OS X 10.5+ installer. - -C API ------ - -- Issue #22079: PyType_Ready() now checks that statically allocated type has - no dynamically allocated bases. - -Documentation -------------- - -- Issue #19548: Update the codecs module documentation to better cover the - distinction between text encodings and other codecs, together with other - clarifications. Patch by Martin Panter. - -- Issue #22914: Update the Python 2/3 porting HOWTO to describe a more automated - approach. - -- Issue #21514: The documentation of the json module now refers to new JSON RFC - 7159 instead of obsoleted RFC 4627. - -Tools/Demos ------------ - -- Issue #22314: pydoc now works when the LINES environment variable is set. - -Windows -------- - -- Issue #17896: The Windows build scripts now expect external library sources - to be in ``PCbuild\..\externals`` rather than ``PCbuild\..\..``. - -- Issue #17717: The Windows build scripts now use a copy of NASM pulled from - svn.python.org to build OpenSSL. - -- Issue #22644: The bundled version of OpenSSL has been updated to 1.0.1j. - - -What's New in Python 3.4.2? -=========================== - -Release date: 2014-10-06 - -Library -------- - -- Issue #10510: distutils register and upload methods now use HTML standards - compliant CRLF line endings. - -- Issue #9850: Fixed macpath.join() for empty first component. Patch by - Oleg Oshmyan. - -- Issue #22427: TemporaryDirectory no longer attempts to clean up twice when - used in the with statement in generator. - -- Issue #20912: Now directories added to ZIP file have correct Unix and MS-DOS - directory attributes. - -- Issue #21866: ZipFile.close() no longer writes ZIP64 central directory - records if allowZip64 is false. - -- Issue #22415: Fixed debugging output of the GROUPREF_EXISTS opcode in the re - module. Removed trailing spaces in debugging output. - -- Issue #22423: Unhandled exception in thread no longer causes unhandled - AttributeError when sys.stderr is None. - -- Issue #21332: Ensure that ``bufsize=1`` in subprocess.Popen() selects - line buffering, rather than block buffering. Patch by Akira Li. - - -What's New in Python 3.4.2rc1? -============================== - -Release date: 2014-09-22 - -Core and Builtins ------------------ - -- Issue #22258: Fix the the internal function set_inheritable() on Illumos. - This platform exposes the function ``ioctl(FIOCLEX)``, but calling it fails - with errno is ENOTTY: "Inappropriate ioctl for device". set_inheritable() - now falls back to the slower ``fcntl()`` (``F_GETFD`` and then ``F_SETFD``). - -- Issue #21669: With the aid of heuristics in SyntaxError.__init__, the - parser now attempts to generate more meaningful (or at least more search - engine friendly) error messages when "exec" and "print" are used as - statements. - -- Issue #21642: In the conditional if-else expression, allow an integer written - with no space between itself and the ``else`` keyword (e.g. ``True if 42else - False``) to be valid syntax. - -- Issue #21523: Fix over-pessimistic computation of the stack effect of - some opcodes in the compiler. This also fixes a quadratic compilation - time issue noticeable when compiling code with a large number of "and" - and "or" operators. - -Library -------- - -- Issue #21091: Fix API bug: email.message.EmailMessage.is_attachment is now - a method. Since EmailMessage is provisional, we can change the API in a - maintenance release, but we use a trick to remain backward compatible with - 3.4.0/1. - -- Issue #21079: Fix email.message.EmailMessage.is_attachment to return the - correct result when the header has parameters as well as a value. - -- Issue #22247: Add NNTPError to nntplib.__all__. - -- Issue #4180: The warnings registries are now reset when the filters - are modified. - -- Issue #22419: Limit the length of incoming HTTP request in wsgiref server to - 65536 bytes and send a 414 error code for higher lengths. Patch contributed - by Devin Cook. - -- Lax cookie parsing in http.cookies could be a security issue when combined - with non-standard cookie handling in some Web browsers. Reported by - Sergey Bobrov. - -- Issue #22384: An exception in Tkinter callback no longer crashes the program - when it is run with pythonw.exe. - -- Issue #22168: Prevent turtle AttributeError with non-default Canvas on OS X. - -- Issue #21147: sqlite3 now raises an exception if the request contains a null - character instead of truncate it. Based on patch by Victor Stinner. - -- Issue #21951: Fixed a crash in Tkinter on AIX when called Tcl command with - empty string or tuple argument. - -- Issue #21951: Tkinter now most likely raises MemoryError instead of crash - if the memory allocation fails. - -- Issue #22338: Fix a crash in the json module on memory allocation failure. - -- Issue #22226: First letter no longer is stripped from the "status" key in - the result of Treeview.heading(). - -- Issue #19524: Fixed resource leak in the HTTP connection when an invalid - response is received. Patch by Martin Panter. - -- Issue #22051: turtledemo no longer reloads examples to re-run them. - Initialization of variables and gui setup should be done in main(), - which is called each time a demo is run, but not on import. - -- Issue #21933: Turtledemo users can change the code font size with a menu - selection or control(command) '-' or '+' or control-mousewheel. - Original patch by Lita Cho. - -- Issue #21597: The separator between the turtledemo text pane and the drawing - canvas can now be grabbed and dragged with a mouse. The code text pane can - be widened to easily view or copy the full width of the text. The canvas - can be widened on small screens. Original patches by Jan Kanis and Lita Cho. - -- Issue #18132: Turtledemo buttons no longer disappear when the window is - shrunk. Original patches by Jan Kanis and Lita Cho. - -- Issue #22216: smtplib now resets its state more completely after a quit. The - most obvious consequence of the previous behavior was a STARTTLS failure - during a connect/starttls/quit/connect/starttls sequence. - -- Issue #22185: Fix an occasional RuntimeError in threading.Condition.wait() - caused by mutation of the waiters queue without holding the lock. Patch - by Doug Zongker. - -- Issue #22182: Use e.args to unpack exceptions correctly in - distutils.file_util.move_file. Patch by Claudiu Popa. - -- The webbrowser module now uses subprocess's start_new_session=True rather - than a potentially risky preexec_fn=os.setsid call. - -- Issue #22236: Fixed Tkinter images copying operations in NoDefaultRoot mode. - -- Issue #22191: Fix warnings.__all__. - -- Issue #15696: Add a __sizeof__ implementation for mmap objects on Windows. - -- Issue #22068: Avoided reference loops with Variables and Fonts in Tkinter. - -- Issue #22165: SimpleHTTPRequestHandler now supports undecodable file names. - -- Issue #8797: Raise HTTPError on failed Basic Authentication immediately. - Initial patch by Sam Bull. - -- Issue #20729: Restored the use of lazy iterkeys()/itervalues()/iteritems() - in the mailbox module. - -- Issue #21448: Changed FeedParser feed() to avoid O(N**2) behavior when - parsing long line. Original patch by Raymond Hettinger. - -- Issue #22184: The functools LRU Cache decorator factory now gives an earlier - and clearer error message when the user forgets the required parameters. - -- Issue #17923: glob() patterns ending with a slash no longer match non-dirs on - AIX. Based on patch by Delhallt. - -- Issue #21121: Don't force 3rd party C extensions to be built with - -Werror=declaration-after-statement. - -- Issue #21975: Fixed crash when using uninitialized sqlite3.Row (in particular - when unpickling pickled sqlite3.Row). sqlite3.Row is now initialized in the - __new__() method. - -- Issue #21580: Now Tkinter correctly handles bytes arguments passed to Tk. - In particular this allows to initialize images from binary data. - -- Issue #17172: Make turtledemo start as active on OS X even when run with - subprocess. Patch by Lita Cho. - -- Issue #21704: Fix build error for _multiprocessing when semaphores - are not available. Patch by Arfrever Frehtes Taifersar Arahesis. - -- Fix repr(_socket.socket) on Windows 64-bit: don't fail with OverflowError - on closed socket. repr(socket.socket) already works fine. - -- Issue #16133: The asynchat.async_chat.handle_read() method now ignores - BlockingIOError exceptions. - -- Issue #22044: Fixed premature DECREF in call_tzinfo_method. - Patch by Tom Flanagan. - -- Issue #19884: readline: Disable the meta modifier key if stdout is not - a terminal to not write the ANSI sequence "\033[1034h" into stdout. This - sequence is used on some terminal (ex: TERM=xterm-256color") to enable - support of 8 bit characters. - -- Issue #21888: plistlib's load() and loads() now work if the fmt parameter is - specified. - -- Issue #21044: tarfile.open() now handles fileobj with an integer 'name' - attribute. Based on patch by Antoine Pietri. - -- Issue #21867: Prevent turtle crash due to invalid undo buffer size. - -- Issue #19076: Don't pass the redundant 'file' argument to self.error(). - -- Issue #21942: Fixed source file viewing in pydoc's server mode on Windows. - -- Issue #11259: asynchat.async_chat().set_terminator() now raises a ValueError - if the number of received bytes is negative. - -- Issue #12523: asynchat.async_chat.push() now raises a TypeError if it doesn't - get a bytes string - -- Issue #21707: Add missing kwonlyargcount argument to - ModuleFinder.replace_paths_in_code(). - -- Issue #20639: calling Path.with_suffix('') allows removing the suffix - again. Patch by July Tikhonov. - -- Issue #21714: Disallow the construction of invalid paths using - Path.with_name(). Original patch by Antony Lee. - -- Issue #21897: Fix a crash with the f_locals attribute with closure - variables when frame.clear() has been called. - -- Issue #21151: Fixed a segfault in the winreg module when ``None`` is passed - as a ``REG_BINARY`` value to SetValueEx. Patch by John Ehresman. - -- Issue #21090: io.FileIO.readall() does not ignore I/O errors anymore. Before, - it ignored I/O errors if at least the first C call read() succeed. - -- Issue #21781: ssl.RAND_add() now supports strings longer than 2 GB. - -- Issue #11453: asyncore: emit a ResourceWarning when an unclosed file_wrapper - object is destroyed. The destructor now closes the file if needed. The - close() method can now be called twice: the second call does nothing. - -- Issue #21858: Better handling of Python exceptions in the sqlite3 module. - -- Issue #21476: Make sure the email.parser.BytesParser TextIOWrapper is - discarded after parsing, so the input file isn't unexpectedly closed. - -- Issue #21729: Used the "with" statement in the dbm.dumb module to ensure - files closing. Patch by Claudiu Popa. - -- Issue #21491: socketserver: Fix a race condition in child processes reaping. - -- Issue #21832: Require named tuple inputs to be exact strings. - -- Issue #19145: The times argument for itertools.repeat now handles - negative values the same way for keyword arguments as it does for - positional arguments. - -- Issue #21812: turtle.shapetransform did not tranform the turtle on the - first call. (Issue identified and fixed by Lita Cho.) - -- Issue #21635: The difflib SequenceMatcher.get_matching_blocks() method - cache didn't match the actual result. The former was a list of tuples - and the latter was a list of named tuples. - -- Issue #21722: The distutils "upload" command now exits with a non-zero - return code when uploading fails. Patch by Martin Dengler. - -- Issue #21723: asyncio.Queue: support any type of number (ex: float) for the - maximum size. Patch written by Vajrasky Kok. - -- Issue #21326: Add a new is_closed() method to asyncio.BaseEventLoop. - run_forever() and run_until_complete() methods of asyncio.BaseEventLoop now - raise an exception if the event loop was closed. - -- Issue #21774: Fixed NameError for an incorrect variable reference in the - XML Minidom code for creating processing instructions. - (Found and fixed by Claudiu Popa.) - -- Issue #21766: Prevent a security hole in CGIHTTPServer by URL unquoting paths - before checking for a CGI script at that path. - -- Issue #21310: Fixed possible resource leak in failed open(). - -- Issue #21677: Fixed chaining nonnormalized exceptions in io close() methods. - -- Issue #11709: Fix the pydoc.help function to not fail when sys.stdin is not a - valid file. - -- Issue #13223: Fix pydoc.writedoc so that the HTML documentation for methods - that use 'self' in the example code is generated correctly. - -- Issue #21463: In urllib.request, fix pruning of the FTP cache. - -- Issue #21618: The subprocess module could fail to close open fds that were - inherited by the calling process and already higher than POSIX resource - limits would otherwise allow. On systems with a functioning /proc/self/fd - or /dev/fd interface the max is now ignored and all fds are closed. - -- Issue #21552: Fixed possible integer overflow of too long string lengths in - the tkinter module on 64-bit platforms. - -- Issue #14315: The zipfile module now ignores extra fields in the central - directory that are too short to be parsed instead of letting a struct.unpack - error bubble up as this "bad data" appears in many real world zip files in - the wild and is ignored by other zip tools. - -- Issue #21402: tkinter.ttk now works when default root window is not set. - -- Issue #10203: sqlite3.Row now truly supports sequence protocol. In particular - it supports reverse() and negative indices. Original patch by Claudiu Popa. - -- Issue #18807: If copying (no symlinks) specified for a venv, then the python - interpreter aliases (python, python3) are now created by copying rather than - symlinking. - -- Issue #14710: pkgutil.get_loader() no longer raises an exception when None is - found in sys.modules. - -- Issue #14710: pkgutil.find_loader() no longer raises an exception when a - module doesn't exist. - -- Issue #21481: Argparse equality and inequality tests now return - NotImplemented when comparing to an unknown type. - -- Issue #8743: Fix interoperability between set objects and the - collections.Set() abstract base class. - -- Issue #13355: random.triangular() no longer fails with a ZeroDivisionError - when low equals high. - -- Issue #21538: The plistlib module now supports loading of binary plist files - when reference or offset size is not a power of two. - -- Issue #21801: Validate that __signature__ is None or an instance of Signature. - -- Issue #21923: Prevent AttributeError in distutils.sysconfig.customize_compiler - due to possible uninitialized _config_vars. - -- Issue #21323: Fix http.server to again handle scripts in CGI subdirectories, - broken by the fix for security issue #19435. Patch by Zach Byrne. - -Extension Modules ------------------ - -- Issue #22176: Update the ctypes module's libffi to v3.1. This release - adds support for the Linux AArch64 and POWERPC ELF ABIv2 little endian - architectures. - -Build ------ - -- Issue #15661: python.org OS X installers are now distributed as signed - installer packages compatible with the Gatekeeper security feature. - -- Issue #21958: Define HAVE_ROUND when building with Visual Studio 2013 and - above. Patch by Zachary Turner. - -- Issue #15759: "make suspicious", "make linkcheck" and "make doctest" in Doc/ - now display special message when and only when there are failures. - -- Issue #17095: Fix Modules/Setup *shared* support. - -- Issue #21811: Anticipated fixes to support OS X versions > 10.9. - -- Issue #21166: Prevent possible segfaults and other random failures of - python --generate-posix-vars in pybuilddir.txt build target. - -IDLE ----- - -- Issue #17390: Adjust Editor window title; remove 'Python', - move version to end. - -- Issue #14105: Idle debugger breakpoints no longer disappear - when inseting or deleting lines. - -- Issue #17172: Turtledemo can now be run from Idle. - Currently, the entry is on the Help menu, but it may move to Run. - Patch by Ramchandra Apt and Lita Cho. - -- Issue #21765: Add support for non-ascii identifiers to HyperParser. - -- Issue #21940: Add unittest for WidgetRedirector. Initial patch by Saimadhav - Heblikar. - -- Issue #18592: Add unittest for SearchDialogBase. Patch by Phil Webster. - -- Issue #21694: Add unittest for ParenMatch. Patch by Saimadhav Heblikar. - -- Issue #21686: add unittest for HyperParser. Original patch by Saimadhav - Heblikar. - -- Issue #12387: Add missing upper(lower)case versions of default Windows key - bindings for Idle so Caps Lock does not disable them. Patch by Roger Serwy. - -- Issue #21695: Closing a Find-in-files output window while the search is - still in progress no longer closes Idle. - -- Issue #18910: Add unittest for textView. Patch by Phil Webster. - -- Issue #18292: Add unittest for AutoExpand. Patch by Saihadhav Heblikar. - -- Issue #18409: Add unittest for AutoComplete. Patch by Phil Webster. - -Tests ------ - -- Issue #22166: With the assistance of a new internal _codecs._forget_codec - helping function, test_codecs now clears the encoding caches to avoid the - appearance of a reference leak - -- Issue #22236: Tkinter tests now don't reuse default root window. New root - window is created for every test class. - -- Issue #20746: Fix test_pdb to run in refleak mode (-R). Patch by Xavier - de Gaye. - -- Issue #22060: test_ctypes has been somewhat cleaned up and simplified; it - now uses unittest test discovery to find its tests. - -- Issue #22104: regrtest.py no longer holds a reference to the suite of tests - loaded from test modules that don't define test_main(). - -- Issue #22002: Added ``load_package_tests`` function to test.support and used - it to implement/augment test discovery in test_asyncio, test_email, - test_importlib, test_json, and test_tools. - -- Issue #21976: Fix test_ssl to accept LibreSSL version strings. Thanks - to William Orr. - -- Issue #21918: Converted test_tools from a module to a package containing - separate test files for each tested script. - -- Issue #20155: Changed HTTP method names in failing tests in test_httpservers - so that packet filtering software (specifically Windows Base Filtering Engine) - does not interfere with the transaction semantics expected by the tests. - -- Issue #19493: Refactored the ctypes test package to skip tests explicitly - rather than silently. - -- Issue #18492: All resources are now allowed when tests are not run by - regrtest.py. - -- Issue #21634: Fix pystone micro-benchmark: use floor division instead of true - division to benchmark integers instead of floating point numbers. Set pystone - version to 1.2. Patch written by Lennart Regebro. - -- Issue #21605: Added tests for Tkinter images. - -- Issue #21493: Added test for ntpath.expanduser(). Original patch by - Claudiu Popa. - -- Issue #19925: Added tests for the spwd module. Original patch by Vajrasky Kok. - -- Issue #21522: Added Tkinter tests for Listbox.itemconfigure(), - PanedWindow.paneconfigure(), and Menu.entryconfigure(). - -Documentation -------------- - -- Issue #21777: The binary sequence methods on bytes and bytearray are now - documented explicitly, rather than assuming users will be able to derive - the expected behaviour from the behaviour of the corresponding str methods. - -Windows -------- - -- Issue #21671, #22160, CVE-2014-0224: The bundled version of OpenSSL has been - updated to 1.0.1i. - -- Issue #10747: Use versioned labels in the Windows start menu. - Patch by Olive Kilburn. - -Tools/Demos ------------ - -- Issue #22201: Command-line interface of the zipfile module now correctly - extracts ZIP files with directory entries. Patch by Ryan Wilson. - -- Issue #21906: Make Tools/scripts/md5sum.py work in Python 3. - Patch by Zachary Ware. - -- Issue #21629: Fix Argument Clinic's "--converters" feature. - - -What's New in Python 3.4.1? -=========================== - -Release date: 2014-05-18 - -Core and Builtins ------------------ - -- Issue #21418: Fix a crash in the builtin function super() when called without - argument and without current frame (ex: embedded Python). - -- Issue #21425: Fix flushing of standard streams in the interactive - interpreter. - -- Issue #21435: In rare cases, when running finalizers on objects in cyclic - trash a bad pointer dereference could occur due to a subtle flaw in - internal iteration logic. - -Library -------- - -- Issue #10744: Fix PEP 3118 format strings on ctypes objects with a nontrivial - shape. - -- Issue #20998: Fixed re.fullmatch() of repeated single character pattern - with ignore case. Original patch by Matthew Barnett. - -- Issue #21075: fileinput.FileInput now reads bytes from standard stream if - binary mode is specified. Patch by Sam Kimbrel. - -- Issue #21396: Fix TextIOWrapper(..., write_through=True) to not force a - flush() on the underlying binary stream. Patch by akira. - -- Issue #21470: Do a better job seeding the random number generator by - using enough bytes to span the full state space of the Mersenne Twister. - -- Issue #21398: Fix an unicode error in the pydoc pager when the documentation - contains characters not encodable to the stdout encoding. - -Tests ------ - -- Issue #17756: Fix test_code test when run from the installed location. - -- Issue #17752: Fix distutils tests when run from the installed location. - -IDLE ----- - -- Issue #18104: Add idlelib/idle_test/htest.py with a few sample tests to begin - consolidating and improving human-validated tests of Idle. Change other files - as needed to work with htest. Running the module as __main__ runs all tests. - - -What's New in Python 3.4.1rc1? -============================== - -Release date: 2014-05-05 - -Core and Builtins ------------------ - -- Issue #21274: Define PATH_MAX for GNU/Hurd in Python/pythonrun.c. - -- Issue #21209: Fix sending tuples to custom generator objects with the yield - from syntax. - -- Issue #21134: Fix segfault when str is called on an uninitialized - UnicodeEncodeError, UnicodeDecodeError, or UnicodeTranslateError object. - -- Issue #19537: Fix PyUnicode_DATA() alignment under m68k. Patch by - Andreas Schwab. - -- Issue #20929: Add a type cast to avoid shifting a negative number. - -- Issue #20731: Properly position in source code files even if they - are opened in text mode. Patch by Serhiy Storchaka. - -- Issue #20637: Key-sharing now also works for instance dictionaries of - subclasses. Patch by Peter Ingebretson. - -- Issue #12546: Allow ``\x00`` to be used as a fill character when using str, int, - float, and complex __format__ methods. - -- Issue #13598: Modify string.Formatter to support auto-numbering of - replacement fields. It now matches the behavior of str.format() in - this regard. Patches by Phil Elson and Ramchandra Apte. - -Library -------- - -- Issue #21088: Bugfix for curses.window.addch() regression in 3.4.0. - In porting to Argument Clinic, the first two arguments were reversed. - -- Issue #21469: Reduced the risk of false positives in robotparser by - checking to make sure that robots.txt has been read or does not exist - prior to returning True in can_fetch(). - -- Issue #21321: itertools.islice() now releases the reference to the source - iterator when the slice is exhausted. Patch by Anton Afanasyev. - -- Issue #9815: assertRaises now tries to clear references to local variables - in the exception's traceback. - -- Issue #13204: Calling sys.flags.__new__ would crash the interpreter, - now it raises a TypeError. - -- Issue #19385: Make operations on a closed dbm.dumb database always raise the - same exception. - -- Issue #21207: Detect when the os.urandom cached fd has been closed or - replaced, and open it anew. - -- Issue #21291: subprocess's Popen.wait() is now thread safe so that - multiple threads may be calling wait() or poll() on a Popen instance - at the same time without losing the Popen.returncode value. - -- Issue #21127: Path objects can now be instantiated from str subclass - instances (such as ``numpy.str_``). - -- Issue #15002: urllib.response object to use _TemporaryFileWrapper (and - _TemporaryFileCloser) facility. Provides a better way to handle file - descriptor close. Patch contributed by Christian Theune. - -- Issue #12220: mindom now raises a custom ValueError indicating it doesn't - support spaces in URIs instead of letting a 'split' ValueError bubble up. - -- Issue #21239: patch.stopall() didn't work deterministically when the same - name was patched more than once. - -- Issue #21222: Passing name keyword argument to mock.create_autospec now - works. - -- Issue #21197: Add lib64 -> lib symlink in venvs on 64-bit non-OS X POSIX. - -- Issue #17498: Some SMTP servers disconnect after certain errors, violating - strict RFC conformance. Instead of losing the error code when we issue the - subsequent RSET, smtplib now returns the error code and defers raising the - SMTPServerDisconnected error until the next command is issued. - -- Issue #17826: setting an iterable side_effect on a mock function created by - create_autospec now works. Patch by Kushal Das. - -- Issue #7776: Fix ``Host:`` header and reconnection when using - http.client.HTTPConnection.set_tunnel(). Patch by Nikolaus Rath. - -- Issue #20968: unittest.mock.MagicMock now supports division. - Patch by Johannes Baiter. - -- Issue #21529 (CVE-2014-4616): Fix arbitrary memory access in - JSONDecoder.raw_decode with a negative second parameter. Bug reported by Guido - Vranken. - -- Issue #21169: getpass now handles non-ascii characters that the - input stream encoding cannot encode by re-encoding using the - replace error handler. - -- Issue #21171: Fixed undocumented filter API of the rot13 codec. - Patch by Berker Peksag. - -- Issue #21172: isinstance check relaxed from dict to collections.Mapping. - -- Issue #21155: asyncio.EventLoop.create_unix_server() now raises a ValueError - if path and sock are specified at the same time. - -- Issue #21149: Improved thread-safety in logging cleanup during interpreter - shutdown. Thanks to Devin Jeanpierre for the patch. - -- Issue #20145: `assertRaisesRegex` and `assertWarnsRegex` now raise a - TypeError if the second argument is not a string or compiled regex. - -- Issue #21058: Fix a leak of file descriptor in - :func:`tempfile.NamedTemporaryFile`, close the file descriptor if - :func:`io.open` fails - -- Issue #21200: Return None from pkgutil.get_loader() when __spec__ is missing. - -- Issue #21013: Enhance ssl.create_default_context() when used for server side - sockets to provide better security by default. - -- Issue #20633: Replace relative import by absolute import. - -- Issue #20980: Stop wrapping exception when using ThreadPool. - -- Issue #21082: In os.makedirs, do not set the process-wide umask. Note this - changes behavior of makedirs when exist_ok=True. - -- Issue #20990: Fix issues found by pyflakes for multiprocessing. - -- Issue #21015: SSL contexts will now automatically select an elliptic - curve for ECDH key exchange on OpenSSL 1.0.2 and later, and otherwise - default to "prime256v1". - -- Issue #20995: Enhance default ciphers used by the ssl module to enable - better security an prioritize perfect forward secrecy. - -- Issue #20884: Don't assume that __file__ is defined on importlib.__init__. - -- Issue #21499: Ignore __builtins__ in several test_importlib.test_api tests. - -- Issue #20879: Delay the initialization of encoding and decoding tables for - base32, ascii85 and base85 codecs in the base64 module, and delay the - initialization of the unquote_to_bytes() table of the urllib.parse module, to - not waste memory if these modules are not used. - -- Issue #19157: Include the broadcast address in the usuable hosts for IPv6 - in ipaddress. - -- Issue #11599: When an external command (e.g. compiler) fails, distutils now - prints out the whole command line (instead of just the command name) if the - environment variable DISTUTILS_DEBUG is set. - -- Issue #4931: distutils should not produce unhelpful "error: None" messages - anymore. distutils.util.grok_environment_error is kept but doc-deprecated. - -- Issue #20875: Prevent possible gzip "'read' is not defined" NameError. - Patch by Claudiu Popa. - -- Issue #11558: ``email.message.Message.attach`` now returns a more - useful error message if ``attach`` is called on a message for which - ``is_multipart`` is False. - -- Issue #20283: RE pattern methods now accept the string keyword parameters - as documented. The pattern and source keyword parameters are left as - deprecated aliases. - -- Issue #20778: Fix modulefinder to work with bytecode-only modules. - -- Issue #20791: copy.copy() now doesn't make a copy when the input is - a bytes object. Initial patch by Peter Otten. - -- Issue #19748: On AIX, time.mktime() now raises an OverflowError for year - outsize range [1902; 2037]. - -- Issue #20816: Fix inspect.getcallargs() to raise correct TypeError for - missing keyword-only arguments. Patch by Jeremiah Lowin. - -- Issue #20817: Fix inspect.getcallargs() to fail correctly if more - than 3 arguments are missing. Patch by Jeremiah Lowin. - -- Issue #6676: Ensure a meaningful exception is raised when attempting - to parse more than one XML document per pyexpat xmlparser instance. - (Original patches by Hirokazu Yamamoto and Amaury Forgeot d'Arc, with - suggested wording by David Gutteridge) - -- Issue #21117: Fix inspect.signature to better support functools.partial. - Due to the specifics of functools.partial implementation, - positional-or-keyword arguments passed as keyword arguments become - keyword-only. - -- Issue #21209: Fix asyncio.tasks.CoroWrapper to workaround a bug - in yield-from implementation in CPythons prior to 3.4.1. - -- asyncio: Add gi_{frame,running,code} properties to CoroWrapper - (upstream issue #163). - -- Issue #21311: Avoid exception in _osx_support with non-standard compiler - configurations. Patch by John Szakmeister. - -- Issue #11571: Ensure that the turtle window becomes the topmost window - when launched on OS X. - -Extension Modules ------------------ - -- Issue #21276: posixmodule: Don't define USE_XATTRS on KFreeBSD and the Hurd. - -- Issue #21226: Set up modules properly in PyImport_ExecCodeModuleObject - (and friends). - -IDLE ----- - -- Issue #21139: Change default paragraph width to 72, the PEP 8 recommendation. - -- Issue #21284: Paragraph reformat test passes after user changes reformat width. - -- Issue #17654: Ensure IDLE menus are customized properly on OS X for - non-framework builds and for all variants of Tk. - -Build ------ - -- The Windows build now includes OpenSSL 1.0.1g - -- Issue #21285: Refactor and fix curses configure check to always search - in a ncursesw directory. - -- Issue #15234: For BerkelyDB and Sqlite, only add the found library and - include directories if they aren't already being searched. This avoids - an explicit runtime library dependency. - -- Issue #20644: OS X installer build support for documentation build changes - in 3.4.1: assume externally supplied sphinx-build is available in /usr/bin. - -C API ------ - -- Issue #20942: PyImport_ImportFrozenModuleObject() no longer sets __file__ to - match what importlib does; this affects _frozen_importlib as well as any - module loaded using imp.init_frozen(). - -Documentation -------------- - -- Issue #17386: Expanded functionality of the ``Doc/make.bat`` script to make - it much more comparable to ``Doc/Makefile``. - -- Issue #21043: Remove the recommendation for specific CA organizations and to - mention the ability to load the OS certificates. - -- Issue #20765: Add missing documentation for PurePath.with_name() and - PurePath.with_suffix(). - -- Issue #19407: New package installation and distribution guides based on - the Python Packaging Authority tools. Existing guides have been retained - as legacy links from the distutils docs, as they still contain some - required reference material for tool developers that isn't recorded - anywhere else. - -- Issue #19697: Document cases where __main__.__spec__ is None. - -Tests ------ - -- Issue #18604: Consolidated checks for GUI availability. All platforms now - at least check whether Tk can be instantiated when the GUI resource is - requested. - -- Issue #21275: Fix a socket test on KFreeBSD. - -- Issue #21223: Pass test_site/test_startup_imports when some of the extensions - are built as builtins. - -- Issue #20635: Added tests for Tk geometry managers. - -- Add test case for freeze. - -- Issue #20743: Fix a reference leak in test_tcl. - -- Issue #21097: Move test_namespace_pkgs into test_importlib. - -- Issue #20939: Avoid various network test failures due to new - redirect of http://www.python.org/ to https://www.python.org: - use http://www.example.com instead. - -- Issue #20668: asyncio tests no longer rely on tests.txt file. - (Patch by Vajrasky Kok) - -- Issue #21093: Prevent failures of ctypes test_macholib on OS X if a - copy of libz exists in $HOME/lib or /usr/local/lib. - -Tools/Demos ------------ - -- Add support for ``yield from`` to 2to3. - -- Add support for the PEP 465 matrix multiplication operator to 2to3. - -- Issue #16047: Fix module exception list and __file__ handling in freeze. - Patch by Meador Inge. - -- Issue #11824: Consider ABI tags in freeze. Patch by Meador Inge. - -- Issue #20535: PYTHONWARNING no longer affects the run_tests.py script. - Patch by Arfrever Frehtes Taifersar Arahesis. - - -What's New in Python 3.4.0? -=========================== - -Release date: 2014-03-16 - -Library -------- - -- Issue #20939: Fix test_geturl failure in test_urllibnet due to - new redirect of http://www.python.org/ to https://www.python.org. - -Documentation -------------- - -- Merge in all documentation changes since branching 3.4.0rc1. - - -What's New in Python 3.4.0 release candidate 3? -=============================================== - -Release date: 2014-03-09 - -Core and Builtins ------------------ - -- Issue #20786: Fix signatures for dict.__delitem__ and - property.__delete__ builtins. - -Library -------- - -- Issue #20839: Don't trigger a DeprecationWarning in the still supported - pkgutil.get_loader() API when __loader__ isn't set on a module (nor - when pkgutil.find_loader() is called directly). - -Build ------ - -- Issue #14512: Launch pydoc -b instead of pydocgui.pyw on Windows. - -- Issue #20748: Uninstalling pip does not leave behind the pyc of - the uninstaller anymore. - -- Issue #20568: The Windows installer now installs the unversioned ``pip`` - command in addition to the versioned ``pip3`` and ``pip3.4`` commands. - -- Issue #20757: The ensurepip helper for the Windows uninstaller now skips - uninstalling pip (rather than failing) if the user has updated pip to a - different version from the one bundled with ensurepip. - -- Issue #20465: Update OS X and Windows installer builds to use - SQLite 3.8.3.1. - - -What's New in Python 3.4.0 release candidate 2? -=============================================== - -Release date: 2014-02-23 - -Core and Builtins ------------------ - -- Issue #20625: Parameter names in __annotations__ were not mangled properly. - Discovered by Jonas Wielicki, patch by Yury Selivanov. - -- Issue #20261: In pickle, lookup __getnewargs__ and __getnewargs_ex__ on the - type of the object. - -- Issue #20619: Give the AST nodes of keyword-only arguments a column and line - number. - -- Issue #20526: Revert changes of issue #19466 which introduces a regression: - don't clear anymore the state of Python threads early during the Python - shutdown. - -Library -------- - -- Issue #20710: The pydoc summary line no longer displays the "self" parameter - for bound methods. - -- Issue #20566: Change asyncio.as_completed() to use a Queue, to - avoid O(N**2) behavior. - -- Issue #20704: Implement new debug API in asyncio. Add new methods - BaseEventLoop.set_debug() and BaseEventLoop.get_debug(). - Add support for setting 'asyncio.tasks._DEBUG' variable with - 'PYTHONASYNCIODEBUG' environment variable. - -- asyncio: Refactoring and fixes: BaseEventLoop.sock_connect() raises an - error if the address is not resolved; use __slots__ in Handle and - TimerHandle; as_completed() and wait() raise TypeError if the passed - list of Futures is a single Future; call_soon() and other 'call_*()' - functions raise TypeError if the passed callback is a coroutine - function; _ProactorBasePipeTransport uses _FlowControlMixin; - WriteTransport.set_write_buffer_size() calls _maybe_pause_protocol() - to consider pausing receiving if the watermark limits have changed; - fix _check_resolved_address() for IPv6 address; and other minor - improvements, along with multiple documentation updates. - -- Issue #20684: Fix inspect.getfullargspec() to not to follow __wrapped__ - chains. Make its behaviour consistent with bound methods first argument. - Patch by Nick Coghlan and Yury Selivanov. - -- Issue #20681: Add new error handling API in asyncio. New APIs: - loop.set_exception_handler(), loop.default_exception_handler(), and - loop.call_exception_handler(). - -- Issue #20673: Implement support for UNIX Domain Sockets in asyncio. - New APIs: loop.create_unix_connection(), loop.create_unix_server(), - streams.open_unix_connection(), and streams.start_unix_server(). - -- Issue #20616: Add a format() method to tracemalloc.Traceback. - -- Issue #19744: the ensurepip installation step now just prints a warning to - stderr rather than failing outright if SSL/TLS is unavailable. This allows - local installation of POSIX builds without SSL/TLS support. - -- Issue #20594: Avoid name clash with the libc function posix_close. - -Build ------ - -- Issue #20641: Run MSI custom actions (pip installation, pyc compilation) - with the NoImpersonate flag, to support elevated execution (UAC). - -- Issue #20221: Removed conflicting (or circular) hypot definition when - compiled with VS 2010 or above. Initial patch by Tabrez Mohammed. - -- Issue #20609: Restored the ability to build 64-bit Windows binaries on - 32-bit Windows, which was broken by the change in issue #19788. - - -What's New in Python 3.4.0 release candidate 1? -=============================================== - -Release date: 2014-02-10 - -Core and Builtins ------------------ - -- Issue #19255: The builtins module is restored to initial value before - cleaning other modules. The sys and builtins modules are cleaned last. - -- Issue #20588: Make Python-ast.c C89 compliant. - -- Issue #20437: Fixed 22 potential bugs when deleting objects references. - -- Issue #20500: Displaying an exception at interpreter shutdown no longer - risks triggering an assertion failure in PyObject_Str. - -- Issue #20538: UTF-7 incremental decoder produced inconsistent string when - input was truncated in BASE64 section. - -- Issue #20404: io.TextIOWrapper (and hence the open() builtin) now uses the - internal codec marking system added for issue #19619 to throw LookupError - for known non-text encodings at stream construction time. The existing - output type checks remain in place to deal with unmarked third party - codecs. - -- Issue #17162: Add PyType_GetSlot. - -- Issue #20162: Fix an alignment issue in the siphash24() hash function which - caused a crash on PowerPC 64-bit (ppc64). - -Library -------- - -- Issue #20530: The signatures for slot builtins have been updated - to reflect the fact that they only accept positional-only arguments. - -- Issue #20517: Functions in the os module that accept two filenames - now register both filenames in the exception on failure. - -- Issue #20563: The ipaddress module API is now considered stable. - -- Issue #14983: email.generator now always adds a line end after each MIME - boundary marker, instead of doing so only when there is an epilogue. This - fixes an RFC compliance bug and solves an issue with signed MIME parts. - -- Issue #20540: Fix a performance regression (vs. Python 3.2) when layering - a multiprocessing Connection over a TCP socket. For small payloads, Nagle's - algorithm would introduce idle delays before the entire transmission of a - message. - -- Issue #16983: the new email header parsing code will now decode encoded words - that are (incorrectly) surrounded by quotes, and register a defect. - -- Issue #19772: email.generator no longer mutates the message object when - doing a down-transform from 8bit to 7bit CTEs. - -- Issue #20536: the statistics module now correctly handle Decimal instances - with positive exponents - -- Issue #18805: the netmask/hostmask parsing in ipaddress now more reliably - filters out illegal values and correctly allows any valid prefix length. - -- Issue #20481: For at least Python 3.4, the statistics module will require - that all inputs for a single operation be of a single consistent type, or - else a mixed of ints and a single other consistent type. This avoids - some interoperability issues that arose with the previous approach of - coercing to a suitable common type. - -- Issue #20478: the statistics module now treats collections.Counter inputs - like any other iterable. - -- Issue #17369: get_filename was raising an exception if the filename - parameter's RFC2231 encoding was broken in certain ways. This was - a regression relative to python2. - -- Issue #20013: Some imap servers disconnect if the current mailbox is - deleted, and imaplib did not handle that case gracefully. Now it - handles the 'bye' correctly. - -- Issue #20531: Revert 3.4 version of fix for #19063, and apply the 3.3 - version. That is, do *not* raise an error if unicode is passed to - email.message.Message.set_payload. - -- Issue #20476: If a non-compat32 policy is used with any of the email parsers, - EmailMessage is now used as the factory class. The factory class should - really come from the policy; that will get fixed in 3.5. - -- Issue #19920: TarFile.list() no longer fails when outputs a listing - containing non-encodable characters. Based on patch by Vajrasky Kok. - -- Issue #20515: Fix NULL pointer dereference introduced by issue #20368. - -- Issue #19186: Restore namespacing of expat symbols inside the pyexpat module. - -- Issue #20053: ensurepip (and hence venv) are no longer affected by the - settings in the default pip configuration file. - -- Issue #20426: When passing the re.DEBUG flag, re.compile() displays the - debug output every time it is called, regardless of the compilation cache. - -- Issue #20368: The null character now correctly passed from Tcl to Python. - Improved error handling in variables-related commands. - -- Issue #20435: Fix _pyio.StringIO.getvalue() to take into account newline - translation settings. - -- tracemalloc: Fix slicing traces and fix slicing a traceback. - -- Issue #20354: Fix an alignment issue in the tracemalloc module on 64-bit - platforms. Bug seen on 64-bit Linux when using "make profile-opt". - -- Issue #17159: inspect.signature now accepts duck types of functions, - which adds support for Cython functions. Initial patch by Stefan Behnel. - -- Issue #18801: Fix inspect.classify_class_attrs to correctly classify - object.__new__ and object.__init__. - -- Fixed cmath.isinf's name in its argument parsing code. - -- Issue #20311, #20452: poll and epoll now round the timeout away from zero, - instead of rounding towards zero, in select and selectors modules: - select.epoll.poll(), selectors.PollSelector.poll() and - selectors.EpollSelector.poll(). For example, a timeout of one microsecond - (1e-6) is now rounded to one millisecondi (1e-3), instead of being rounded to - zero. However, the granularity property and asyncio's resolution feature - were removed again. - -- asyncio: Some refactoring; various fixes; add write flow control to - unix pipes; Future.set_exception() instantiates the exception - argument if it is a class; improved proactor pipe transport; support - wait_for(f, None); don't log broken/disconnected pipes; use - ValueError instead of assert for forbidden subprocess_{shell,exec} - arguments; added a convenience API for subprocess management; added - StreamReader.at_eof(); properly handle duplicate coroutines/futures - in gather(), wait(), as_completed(); use a bytearray for buffering - in StreamReader; and more. - -- Issue #20288: fix handling of invalid numeric charrefs in HTMLParser. - -- Issue #20424: Python implementation of io.StringIO now supports lone surrogates. - -- Issue #20308: inspect.signature now works on classes without user-defined - __init__ or __new__ methods. - -- Issue #20372: inspect.getfile (and a bunch of other inspect functions that - use it) doesn't crash with unexpected AttributeError on classes defined in C - without __module__. - -- Issue #20356: inspect.signature formatting uses '/' to separate - positional-only parameters from others. - -- Issue #20223: inspect.signature now supports methods defined with - functools.partialmethods. - -- Issue #19456: ntpath.join() now joins relative paths correctly when a drive - is present. - -- Issue #19077: tempfile.TemporaryDirectory cleanup no longer fails when - called during shutdown. Emitting resource warning in __del__ no longer fails. - Original patch by Antoine Pitrou. - -- Issue #20394: Silence Coverity warning in audioop module. - -- Issue #20367: Fix behavior of concurrent.futures.as_completed() for - duplicate arguments. Patch by Glenn Langford. - -- Issue #8260: The read(), readline() and readlines() methods of - codecs.StreamReader returned incomplete data when were called after - readline() or read(size). Based on patch by Amaury Forgeot d'Arc. - -- Issue #20105: the codec exception chaining now correctly sets the - traceback of the original exception as its __traceback__ attribute. - -- Issue #17481: inspect.getfullargspec() now uses inspect.signature() API. - -- Issue #15304: concurrent.futures.wait() can block forever even if - Futures have completed. Patch by Glenn Langford. - -- Issue #14455: plistlib: fix serializing integers in the range - of an unsigned long long but outside of the range of signed long long for - binary plist files. - -IDLE ----- - -- Issue #20406: Use Python application icons for Idle window title bars. - Patch mostly by Serhiy Storchaka. - -- Update the python.gif icon for the Idle classbrowser and pathbowser - from the old green snake to the new blue and yellow snakes. - -- Issue #17721: Remove non-functional configuration dialog help button until we - make it actually gives some help when clicked. Patch by Guilherme Simões. - -Tests ------ - -- Issue #20532: Tests which use _testcapi now are marked as CPython only. - -- Issue #19920: Added tests for TarFile.list(). Based on patch by Vajrasky Kok. - -- Issue #19990: Added tests for the imghdr module. Based on patch by - Claudiu Popa. - -- Issue #20474: Fix test_socket "unexpected success" failures on OS X 10.7+. - -Tools/Demos ------------ - -- Issue #20530: Argument Clinic's signature format has been revised again. - The new syntax is highly human readable while still preventing false - positives. The syntax also extends Python syntax to denote "self" and - positional-only parameters, allowing inspect.Signature objects to be - totally accurate for all supported builtins in Python 3.4. - -- Issue #20456: Argument Clinic now observes the C preprocessor conditional - compilation statements of the C files it parses. When a Clinic block is - inside a conditional code, it adjusts its output to match, including - automatically generating an empty methoddef macro. - -- Issue #20456: Cloned functions in Argument Clinic now use the correct - name, not the name of the function they were cloned from, for text - strings inside generated code. - -- Issue #20456: Fixed Argument Clinic's test suite and "--converters" feature. - -- Issue #20456: Argument Clinic now allows specifying different names - for a parameter in Python and C, using "as" on the parameter line. - -- Issue #20326: Argument Clinic now uses a simple, unique signature to - annotate text signatures in docstrings, resulting in fewer false - positives. "self" parameters are also explicitly marked, allowing - inspect.Signature() to authoritatively detect (and skip) said parameters. - -- Issue #20326: Argument Clinic now generates separate checksums for the - input and output sections of the block, allowing external tools to verify - that the input has not changed (and thus the output is not out-of-date). - -Build ------ - -- Issue #20465: Update SQLite shipped with OS X installer to 3.8.3. - -C-API ------ - -- Issue #20517: Added new functions allowing OSError exceptions to reference - two filenames instead of one: PyErr_SetFromErrnoWithFilenameObjects() and - PyErr_SetExcFromWindowsErrWithFilenameObjects(). - -Documentation -------------- - -- Issue #20488: Change wording to say importlib is *the* implementation of - import instead of just *an* implementation. - -- Issue #6386: Clarify in the tutorial that specifying a symlink to execute - means the directory containing the executed script and not the symlink is - added to sys.path. - - -What's New in Python 3.4.0 Beta 3? -================================== - -Release date: 2014-01-26 - -Core and Builtins ------------------ - -- Issue #20189: Four additional builtin types (PyTypeObject, - PyMethodDescr_Type, _PyMethodWrapper_Type, and PyWrapperDescr_Type) - have been modified to provide introspection information for builtins. - -- Issue #17825: Cursor "^" is correctly positioned for SyntaxError and - IndentationError. - -- Issue #2382: SyntaxError cursor "^" is now written at correct position in most - cases when multibyte characters are in line (before "^"). This still not - works correctly with wide East Asian characters. - -- Issue #18960: The first line of Python script could be executed twice when - the source encoding was specified on the second line. Now the source encoding - declaration on the second line isn't effective if the first line contains - anything except a comment. 'python -x' works now again with files with the - source encoding declarations, and can be used to make Python batch files - on Windows. - -Library -------- - -- asyncio: Various improvements and small changes not all covered by - issues listed below. E.g. wait_for() now cancels the inner task if - the timeout occcurs; tweaked the set of exported symbols; renamed - Empty/Full to QueueEmpty/QueueFull; "with (yield from lock)" now - uses a separate context manager; readexactly() raises if not enough - data was read; PTY support tweaks. - -- Issue #20311: asyncio: Add a granularity attribute to BaseEventLoop: maximum - between the resolution of the BaseEventLoop.time() method and the resolution - of the selector. The granuarility is used in the scheduler to round time and - deadline. - -- Issue #20311: selectors: Add a resolution attribute to BaseSelector. - -- Issue #20189: unittest.mock now no longer assumes that any object for - which it could get an inspect.Signature is a callable written in Python. - Fix courtesy of Michael Foord. - -- Issue #20317: ExitStack.__exit__ could create a self-referential loop if an - exception raised by a cleanup operation already had its context set - correctly (for example, by the @contextmanager decorator). The infinite - loop this caused is now avoided by checking if the expected context is - already set before trying to fix it. - -- Issue #20374: Fix build with GNU readline >= 6.3. - -- Issue #20262: Warnings are raised now when duplicate names are added in the - ZIP file or too long ZIP file comment is truncated. - -- Issue #20165: The unittest module no longer considers tests marked with - @expectedFailure successful if they pass. - -- Issue #18574: Added missing newline in 100-Continue reply from - http.server.BaseHTTPRequestHandler. Patch by Nikolaus Rath. - -- Issue #20270: urllib.urlparse now supports empty ports. - -- Issue #20243: TarFile no longer raise ReadError when opened in write mode. - -- Issue #20238: TarFile opened with external fileobj and "w:gz" mode didn't - write complete output on close. - -- Issue #20245: The open functions in the tarfile module now correctly handle - empty mode. - -- Issue #20242: Fixed basicConfig() format strings for the alternative - formatting styles. Thanks to kespindler for the bug report and patch. - -- Issue #20246: Fix buffer overflow in socket.recvfrom_into. - -- Issues #20206 and #5803: Fix edge case in email.quoprimime.encode where it - truncated lines ending in a character needing encoding but no newline by - using a more efficient algorithm that doesn't have the bug. - -- Issue #19082: Working xmlrpc.server and xmlrpc.client examples. Both in - modules and in documentation. Initial patch contributed by Vajrasky Kok. - -- Issue #20138: The wsgiref.application_uri() and wsgiref.request_uri() - functions now conform to PEP 3333 when handle non-ASCII URLs. - -- Issue #19097: Raise the correct Exception when cgi.FieldStorage is given an - invalid fileobj. - -- Issue #20152: Ported Python/import.c over to Argument Clinic. - -- Issue #13107: argparse and optparse no longer raises an exception when output - a help on environment with too small COLUMNS. Based on patch by - Elazar Gershuni. - -- Issue #20207: Always disable SSLv2 except when PROTOCOL_SSLv2 is explicitly - asked for. - -- Issue #18960: The tokenize module now ignore the source encoding declaration - on the second line if the first line contains anything except a comment. - -- Issue #20078: Reading malformed zipfiles no longer hangs with 100% CPU - consumption. - -- Issue #20113: os.readv() and os.writev() now raise an OSError exception on - error instead of returning -1. - -- Issue #19719: Make importlib.abc.MetaPathFinder.find_module(), - PathEntryFinder.find_loader(), and Loader.load_module() use PEP 451 APIs to - help with backwards-compatibility. - -- Issue #20144: inspect.Signature now supports parsing simple symbolic - constants as parameter default values in __text_signature__. - -- Issue #20072: Fixed multiple errors in tkinter with wantobjects is False. - -- Issue #20229: Avoid plistlib deprecation warning in platform.mac_ver(). - -- Issue #14455: Fix some problems with the new binary plist support in plistlib. - -IDLE ----- - -- Issue #17390: Add Python version to Idle editor window title bar. - Original patches by Edmond Burnett and Kent Johnson. - -- Issue #18960: IDLE now ignores the source encoding declaration on the second - line if the first line contains anything except a comment. - -Tests ------ - -- Issue #20358: Tests for curses.window.overlay and curses.window.overwrite - no longer specify min{row,col} > max{row,col}. - -- Issue #19804: The test_find_mac test in test_uuid is now skipped if the - ifconfig executable is not available. - -- Issue #19886: Use better estimated memory requirements for bigmem tests. - -Tools/Demos ------------ - -- Issue #20390: Argument Clinic's "file" output preset now defaults to - "{dirname}/clinic/{basename}.h". - -- Issue #20390: Argument Clinic's "class" directive syntax has been extended - with two new required arguments: "typedef" and "type_object". - -- Issue #20390: Argument Clinic: If __new__ or __init__ functions didn't use - kwargs (or args), the PyArg_NoKeywords (or PyArg_NoPositional) calls - generated are only run when the type object is an exact match. - -- Issue #20390: Argument Clinic now fails if you have required parameters after - optional parameters. - -- Issue #20390: Argument Clinic converters now have a new template they can - inject code into: "modifiers". Code put there is run in the parsing - function after argument parsing but before the call to the impl. - -- Issue #20376: Argument Clinic now escapes backslashes in docstrings. - -- Issue #20381: Argument Clinic now sanity checks the default argument when - c_default is also specified, providing a nice failure message for - disallowed values. - -- Issue #20189: Argument Clinic now ensures that parser functions for - __new__ are always of type newfunc, the type of the tp_new slot. - Similarly, parser functions for __init__ are now always of type initproc, - the type of tp_init. - -- Issue #20189: Argument Clinic now suppresses the docstring for __new__ - and __init__ functions if no docstring is provided in the input. - -- Issue #20189: Argument Clinic now suppresses the "self" parameter in the - impl for @staticmethod functions. - -- Issue #20294: Argument Clinic now supports argument parsing for __new__ and - __init__ functions. - -- Issue #20299: Argument Clinic custom converters may now change the default - value of c_default and py_default with a class member. - -- Issue #20287: Argument Clinic's output is now configurable, allowing - delaying its output or even redirecting it to a separate file. - -- Issue #20226: Argument Clinic now permits simple expressions - (e.g. "sys.maxsize - 1") as default values for parameters. - -- Issue #19936: Added executable bits or shebang lines to Python scripts which - requires them. Disable executable bits and shebang lines in test and - benchmark files in order to prevent using a random system python, and in - source files of modules which don't provide command line interface. Fixed - shebang lines in the unittestgui and checkpip scripts. - -- Issue #20268: Argument Clinic now supports cloning the parameters and - return converter of existing functions. - -- Issue #20228: Argument Clinic now has special support for class special - methods. - -- Issue #20214: Fixed a number of small issues and documentation errors in - Argument Clinic (see issue for details). - -- Issue #20196: Fixed a bug where Argument Clinic did not generate correct - parsing code for functions with positional-only parameters where all arguments - are optional. - -- Issue #18960: 2to3 and the findnocoding.py script now ignore the source - encoding declaration on the second line if the first line contains anything - except a comment. - -- Issue #19723: The marker comments Argument Clinic uses have been changed - to improve readability. - -- Issue #20157: When Argument Clinic renames a parameter because its name - collides with a C keyword, it no longer exposes that rename to PyArg_Parse. - -- Issue #20141: Improved Argument Clinic's support for the PyArg_Parse "O!" - format unit. - -- Issue #20144: Argument Clinic now supports simple symbolic constants - as parameter default values. - -- Issue #20143: The line numbers reported in Argument Clinic errors are - now more accurate. - -- Issue #20142: Py_buffer variables generated by Argument Clinic are now - initialized with a default value. - -Build ------ - -- Issue #12837: Silence a tautological comparison warning on OS X under Clang in - socketmodule.c. - - -What's New in Python 3.4.0 Beta 2? -================================== - -Release date: 2014-01-05 - -Core and Builtins ------------------ - -- Issue #17432: Drop UCS2 from names of Unicode functions in python3.def. - -- Issue #19526: Exclude all new API from the stable ABI. Exceptions can be - made if a need is demonstrated. - -- Issue #19969: PyBytes_FromFormatV() now raises an OverflowError if "%c" - argument is not in range [0; 255]. - -- Issue #19995: %c, %o, %x, and %X now issue a DeprecationWarning on non-integer - input; reworded docs to clarify that an integer type should define both __int__ - and __index__. - -- Issue #19787: PyThread_set_key_value() now always set the value. In Python - 3.3, the function did nothing if the key already exists (if the current value - is a non-NULL pointer). - -- Issue #14432: Remove the thread state field from the frame structure. Fix a - crash when a generator is created in a C thread that is destroyed while the - generator is still used. The issue was that a generator contains a frame, and - the frame kept a reference to the Python state of the destroyed C thread. The - crash occurs when a trace function is setup. - -- Issue #19576: PyGILState_Ensure() now initializes threads. At startup, Python - has no concrete GIL. If PyGILState_Ensure() is called from a new thread for - the first time and PyEval_InitThreads() was not called yet, a GIL needs to be - created. - -- Issue #17576: Deprecation warning emitted now when __int__() or __index__() - return not int instance. - -- Issue #19932: Fix typo in import.h, missing whitespaces in function prototypes. - -- Issue #19736: Add module-level statvfs constants defined for GNU/glibc - based systems. - -- Issue #20097: Fix bad use of "self" in importlib's WindowsRegistryFinder. - -- Issue #19729: In str.format(), fix recursive expansion in format spec. - -- Issue #19638: Fix possible crash / undefined behaviour from huge (more than 2 - billion characters) input strings in _Py_dg_strtod. - -Library -------- - -- Issue #20154: Deadlock in asyncio.StreamReader.readexactly(). - -- Issue #16113: Remove sha3 module again. - -- Issue #20111: pathlib.Path.with_suffix() now sanity checks the given suffix. - -- Fix breakage in TestSuite.countTestCases() introduced by issue #11798. - -- Issue #20108: Avoid parameter name clash in inspect.getcallargs(). - -- Issue #19918: Fix PurePath.relative_to() under Windows. - -- Issue #19422: Explicitly disallow non-SOCK_STREAM sockets in the ssl - module, rather than silently let them emit clear text data. - -- Issue #20046: Locale alias table no longer contains entities which can be - calculated. Generalized support of the euro modifier. - -- Issue #20027: Fixed locale aliases for devanagari locales. - -- Issue #20067: Tkinter variables now work when wantobjects is false. - -- Issue #19020: Tkinter now uses splitlist() instead of split() in configure - methods. - -- Issue #19744: ensurepip now provides a better error message when Python is - built without SSL/TLS support (pip currently requires that support to run, - even if only operating with local wheel files) - -- Issue #19734: ensurepip now ignores all pip environment variables to avoid - odd behaviour based on user configuration settings - -- Fix TypeError on "setup.py upload --show-response". - -- Issue #20045: Fix "setup.py register --list-classifiers". - -- Issue #18879: When a method is looked up on a temporary file, avoid closing - the file before the method is possibly called. - -- Issue #20037: Avoid crashes when opening a text file late at interpreter - shutdown. - -- Issue #19967: Thanks to the PEP 442, asyncio.Future now uses a - destructor to log uncaught exceptions, instead of the dedicated - _TracebackLogger class. - -- Added a Task.current_task() class method to asyncio. - -- Issue #19850: Set SA_RESTART in asyncio when registering a signal - handler to limit EINTR occurrences. - -- Implemented write flow control in asyncio for proactor event loop (Windows). - -- Change write buffer in asyncio use to avoid O(N**2) behavior. Make - write()/sendto() accept bytearray/memoryview. - -- Issue #20034: Updated alias mapping to most recent locale.alias file - from X.org distribution using makelocalealias.py. - -- Issue #5815: Fixed support for locales with modifiers. Fixed support for - locale encodings with hyphens. - -- Issue #20026: Fix the sqlite module to handle correctly invalid isolation - level (wrong type). - -- Issue #18829: csv.Dialect() now checks type for delimiter, escapechar and - quotechar fields. Original patch by Vajrasky Kok. - -- Issue #19855: uuid.getnode() on Unix now looks on the PATH for the - executables used to find the mac address, with /sbin and /usr/sbin as - fallbacks. - -- Issue #20007: HTTPResponse.read(0) no more prematurely closes connection. - Original patch by Simon Sapin. - -- Issue #19946: multiprocessing now uses runpy to initialize __main__ in - child processes when necessary, allowing it to correctly handle scripts - without suffixes and submodules that use explicit relative imports or - otherwise rely on parent modules being correctly imported prior to - execution. - -- Issue #19921: When Path.mkdir() is called with parents=True, any missing - parent is created with the default permissions, ignoring the mode argument - (mimicking the POSIX "mkdir -p" command). - -- Issue #19887: Improve the Path.resolve() algorithm to support certain - symlink chains. - -- Issue #19912: Fixed numerous bugs in ntpath.splitunc(). - -- Issue #19911: ntpath.splitdrive() now correctly processes the 'İ' character - (U+0130, LATIN CAPITAL LETTER I WITH DOT ABOVE). - -- Issue #19532: python -m compileall with no filename/directory arguments now - respects the -f and -q flags instead of ignoring them. - -- Issue #19623: Fixed writing to unseekable files in the aifc module. - -- Issue #19946: multiprocessing.spawn now raises ImportError when the module to - be used as the main module cannot be imported. - -- Issue #17919: select.poll.register() again works with poll.POLLNVAL on AIX. - Fixed integer overflow in the eventmask parameter. - -- Issue #19063: if a Charset's body_encoding was set to None, the email - package would generate a message claiming the Content-Transfer-Encoding - was 7bit, and produce garbage output for the content. This now works. - A couple of other set_payload mishandlings of non-ASCII are also fixed. - In addition, calling set_payload with a string argument without - specifying a charset now raises an error (this is a new error in 3.4). - -- Issue #15475: Add __sizeof__ implementations for itertools objects. - -- Issue #19944: Fix importlib.find_spec() so it imports parents as needed - and move the function to importlib.util. - -- Issue #19880: Fix a reference leak in unittest.TestCase. Explicitly break - reference cycles between frames and the _Outcome instance. - -- Issue #17429: platform.linux_distribution() now decodes files from the UTF-8 - encoding with the surrogateescape error handler, instead of decoding from the - locale encoding in strict mode. It fixes the function on Fedora 19 which is - probably the first major distribution release with a non-ASCII name. Patch - written by Toshio Kuratomi. - -- Issue #19343: Expose FreeBSD-specific APIs in resource module. Original - patch by Koobs. - -- Issue #19929: Call os.read with 32768 within subprocess.Popen.communicate - rather than 4096 for efficiency. A microbenchmark shows Linux and OS X - both using ~50% less cpu time this way. - -- Issue #19506: Use a memoryview to avoid a data copy when piping data - to stdin within subprocess.Popen.communicate. 5-10% less cpu usage. - -- Issue #19876: selectors unregister() no longer raises ValueError or OSError - if the FD is closed (as long as it was registered). - -- Issue #19908: pathlib now joins relative Windows paths correctly when a drive - is present. Original patch by Antoine Pitrou. - -- Issue #19296: Silence compiler warning in dbm_open - -- Issue #6784: Strings from Python 2 can now be unpickled as bytes - objects by setting the encoding argument of Unpickler to be 'bytes'. - Initial patch by Merlijn van Deen. - -- Issue #19839: Fix regression in bz2 module's handling of non-bzip2 data at - EOF, and analogous bug in lzma module. - -- Issue #19881: Fix pickling bug where cpickle would emit bad pickle data for - large bytes string (i.e., with size greater than 2**32-1). - -- Issue #19138: doctest's IGNORE_EXCEPTION_DETAIL now allows a match when - no exception detail exists (no colon following the exception's name, or - a colon does follow but no text follows the colon). - -- Issue #19927: Add __eq__ to path-based loaders in importlib. - -- Issue #19827: On UNIX, setblocking() and settimeout() methods of - socket.socket can now avoid a second syscall if the ioctl() function can be - used, or if the non-blocking flag of the socket is unchanged. - -- Issue #19785: smtplib now supports SSLContext.check_hostname and server name - indication for TLS/SSL connections. - -- Issue #19784: poplib now supports SSLContext.check_hostname and server name - indication for TLS/SSL connections. - -- Issue #19783: nntplib now supports SSLContext.check_hostname and server name - indication for TLS/SSL connections. - -- Issue #19782: imaplib now supports SSLContext.check_hostname and server name - indication for TLS/SSL connections. - -- Issue #20123: Fix pydoc.synopsis() for "binary" modules. - -- Issue #19834: Support unpickling of exceptions pickled by Python 2. - -- Issue #19781: ftplib now supports SSLContext.check_hostname and server name - indication for TLS/SSL connections. - -- Issue #19509: Add SSLContext.check_hostname to match the peer's certificate - with server_hostname on handshake. - -- Issue #15798: Fixed subprocess.Popen() to no longer fail if file - descriptor 0, 1 or 2 is closed. - -- Issue #17897: Optimized unpickle prefetching. - -- Issue #3693: Make the error message more helpful when the array.array() - constructor is given a str. Move the array module typecode documentation to - the docstring of the constructor. - -- Issue #19088: Fixed incorrect caching of the copyreg module in - object.__reduce__() and object.__reduce_ex__(). - -- Issue #19698: Removed exec_module() methods from - importlib.machinery.BuiltinImporter and ExtensionFileLoader. - -- Issue #18864: Added a setter for ModuleSpec.has_location. - -- Fixed _pickle.Unpickler to not fail when loading empty strings as - persistent IDs. - -- Issue #11480: Fixed copy.copy to work with classes with custom metaclasses. - Patch by Daniel Urban. - -- Issue #6477: Added support for pickling the types of built-in singletons - (i.e., Ellipsis, NotImplemented, None). - -- Issue #19713: Add remaining PEP 451-related deprecations and move away - from using find_module/find_loaer/load_module. - -- Issue #19708: Update pkgutil to use the new importer APIs. - -- Issue #19703: Update pydoc to use the new importer APIs. - -- Issue #19851: Fixed a regression in reloading sub-modules. - -- ssl.create_default_context() sets OP_NO_COMPRESSION to prevent CRIME. - -- Issue #19802: Add socket.SO_PRIORITY. - -- Issue #11508: Fixed uuid.getnode() and uuid.uuid1() on environment with - virtual interface. Original patch by Kent Frazier. - -- Issue #11489: JSON decoder now accepts lone surrogates. - -- Issue #19545: Avoid chained exceptions while passing stray % to - time.strptime(). Initial patch by Claudiu Popa. - -IDLE ----- - -- Issue #20058: sys.stdin.readline() in IDLE now always returns only one line. - -- Issue #19481: print() of string subclass instance in IDLE no longer hangs. - -- Issue #18270: Prevent possible IDLE AttributeError on OS X when no initial - shell window is present. - -Tests ------ - -- Issue #20055: Fix test_shutil under Windows with symlink privileges held. - Patch by Vajrasky Kok. - -- Issue #20070: Don't run test_urllib2net when network resources are not - enabled. - -- Issue #19938: Re-enabled test_bug_1333982 in test_dis, which had been - disabled since 3.0 due to the changes in listcomp handling. - -- Issue #19320: test_tcl no longer fails when wantobjects is false. - -- Issue #19919: Fix flaky SSL test. connect_ex() sometimes returns - EWOULDBLOCK on Windows or VMs hosted on Windows. - -- Issue #19912: Added tests for ntpath.splitunc(). - -- Issue #19828: Fixed test_site when the whole suite is run with -S. - -- Issue #19928: Implemented a test for repr() of cell objects. - -- Issue #19535: Fixed test_docxmlrpc, test_functools, test_inspect, and - test_statistics when python is run with -OO. - -- Issue #19926: Removed unneeded test_main from test_abstract_numbers. - Patch by Vajrasky Kok. - -- Issue #19572: More skipped tests explicitly marked as skipped. - -- Issue #19595, #19987: Re-enabled a long-disabled test in test_winsound. - -- Issue #19588: Fixed tests in test_random that were silently skipped most - of the time. Patch by Julian Gindi. - -Build ------ - -- Issue #19728: Enable pip installation by default on Windows. - -- Issue #16136: Remove VMS support - -- Issue #18215: Add script Tools/ssl/test_multiple_versions.py to compile and - run Python's unit tests with multiple versions of OpenSSL. - -- Issue #19922: define _INCLUDE__STDC_A1_SOURCE in HP-UX to include mbstate_t - for mbrtowc(). - -- 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. - -Documentation -------------- - -- Issue #20265: Updated some parts of the Using Windows document. - -- Issue #20266: Updated some parts of the Windows FAQ. - -- Issue #20255: Updated the about and bugs pages. - -- Issue #20253: Fixed a typo in the ipaddress docs that advertised an - illegal attribute name. Found by INADA Naoki. - -- Issue #18840: Introduce the json module in the tutorial, and de-emphasize - the pickle module. - -- Issue #19845: Updated the Compiling Python on Windows section. - -- Issue #19795: Improved markup of True/False constants. - -Tools/Demos ------------ - -- Issue #19659: Added documentation for Argument Clinic. - -- Issue #19976: Argument Clinic METH_NOARGS functions now always - take two parameters. - - -What's New in Python 3.4.0 Beta 1? -================================== - -Release date: 2013-11-24 - -Core and Builtins ------------------ - -- Use the repr of a module name in more places in import, especially - exceptions. - -- 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 #19183: Implement PEP 456 'secure and interchangeable hash algorithm'. - Python now uses SipHash24 on all major platforms. - -- 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 #17806: Added keyword-argument support for "tabsize" to - str/bytes.expandtabs(). - -- 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 #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 #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 #19514: Deduplicate some _Py_IDENTIFIER declarations. - Patch by Andrei Dorian Duma. - -- Issue #17936: Fix O(n**2) behaviour when adding or removing many subclasses - of a given type. - -- Issue #19428: zipimport now handles errors when reading truncated or invalid - ZIP archive. - -- 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. - -- Issue #19369: Optimized the usage of __length_hint__(). - -- Issue #18603: Ensure that PyOS_mystricmp and PyOS_mystrnicmp are in the - Python executable and not removed by the linker's optimizer. - -- Issue #19306: Add extra hints to the faulthandler module's stack - dumps that these are "upside down". - -Library -------- - -- Issue #3158: doctest can now find doctests in functions and methods - written in C. - -- Issue #13477: Added command line interface to the tarfile module. - Original patch by Berker Peksag. - -- 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. - -- 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(). - -- 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. - -- Issue #13592: Improved the repr for regular expression pattern objects. - Based on patch by Hugo Lopes Tavares. - -- Issue #19641: Added the audioop.byteswap() function to convert big-endian - samples to little-endian and vice versa. - -- Issue #15204: Deprecated the 'U' mode in file-like objects. - -- Issue #17810: Implement PEP 3154, pickle protocol 4. - -- Issue #19668: Added support for the cp1125 encoding. - -- Issue #19689: Add ssl.create_default_context() factory function. It creates - a new SSLContext object with secure default settings. - -- 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. - -- 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. - -- Issue #19673: Add pathlib to the stdlib as a provisional module (PEP 428). - -- 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 #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 #19552: venv now supports bootstrapping pip into virtual environments - -- 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 #19555: Restore sysconfig.get_config_var('SO'), (and the distutils - equivalent) with a DeprecationWarning pointing people at $EXT_SUFFIX. - -- 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 #18294: Fix the zlib module to make it 64-bit safe. - -- Issue #19682: Fix compatibility issue with old version of OpenSSL that - was introduced by Issue #18379. - -- Issue #14455: plistlib now supports binary plists and has an updated API. - -- Issue #19633: Fixed writing not compressed 16- and 32-bit wave files on - big-endian platforms. - -- Issue #18379: SSLSocket.getpeercert() returns CA issuer AIA fields, OCSP - and CRL distribution points. - -- 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 #18775: Add name and block_size attribute to HMAC object. They now - provide the same API elements as non-keyed cryptographic hash functions. - -- Issue #17276: MD5 as default digestmod for HMAC is deprecated. The HMAC - module supports digestmod names, e.g. hmac.HMAC('sha1'). - -- 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 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, - when True, automatically converts all character references. - -- Issue #2927: Added the unescape() function to the html module. - -- Issue #8402: Added the escape() function to the glob module. - -- Issue #17618: Add Base85 and Ascii85 encoding/decoding to the base64 module. - -- Issue #19634: time.strftime("%y") now raises a ValueError on AIX when given a - year before 1900. - -- 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. - -- Fix compilation error under gcc of the ctypes module bundled libffi for arm. - -- Issue #19448: Add private API to SSL module to lookup ASN.1 objects by OID, - NID, short name and long name. - -- Issue #19282: dbm.open now supports the context management protocol. (Inital - patch by Claudiu Popa) - -- Issue #8311: Added support for writing any bytes-like objects in the aifc, - sunau, and wave modules. - -- Issue #5202: Added support for unseekable files in the wave module. - -- 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 Issue #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 #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(). - -- Issue #16037: HTTPMessage.readheaders() raises an HTTPException when more than - 100 headers are read. Adapted from patch by Jyrki Pulliainen. - -- Issue #16040: CVE-2013-1752: nntplib: Limit maximum line lengths to 2048 to - prevent readline() calls from consuming too much memory. Patch by Jyrki - Pulliainen. - -- Issue #16041: CVE-2013-1752: poplib: Limit maximum line lengths to 2048 to - prevent readline() calls from consuming too much memory. Patch by Jyrki - Pulliainen. - -- Issue #17997: Change behavior of ``ssl.match_hostname()`` to follow RFC 6125, - for security reasons. It now doesn't match multiple wildcards nor wildcards - inside IDN fragments. - -- Issue #16039: CVE-2013-1752: Change use of readline in imaplib module to limit - line length. Patch by Emil Lind. - -- Issue #19330: the unnecessary wrapper functions have been removed from the - implementations of the new contextlib.redirect_stdout and - contextlib.suppress context managers, which also ensures they provide - reasonable help() output on instances - -- Issue #19393: Fix symtable.symtable function to not be confused when there are - functions or classes named "top". - -- Issue #18685: Restore re performance to pre-PEP 393 levels. - -- Issue #19339: telnetlib module is now using time.monotonic() when available - to compute timeout. - -- Issue #19399: fix sporadic test_subprocess failure. - -- Issue #13234: Fix os.listdir to work with extended paths on Windows. - Patch by Santoso Wijaya. - -- Issue #19375: The site module adding a "site-python" directory to sys.path, - if it exists, is now deprecated. - -- Issue #19379: Lazily import linecache in the warnings module, to make - startup with warnings faster until a warning gets printed. - -- Issue #19288: Fixed the "in" operator of dbm.gnu databases for string - argument. Original patch by Arfrever Frehtes Taifersar Arahesis. - -- Issue #19287: Fixed the "in" operator of dbm.ndbm databases for string - argument. Original patch by Arfrever Frehtes Taifersar Arahesis. - -- Issue #19327: Fixed the working of regular expressions with too big charset. - -- Issue #17400: New 'is_global' attribute for ipaddress to tell if an address - is allocated by IANA for global or private networks. - -- Issue #19350: Increasing the test coverage of macurl2path. Patch by Colin - Williams. - -- Issue #19365: Optimized the parsing of long replacement string in re.sub*() - functions. - -- Issue #19352: Fix unittest discovery when a module can be reached - through several paths (e.g. under Debian/Ubuntu with virtualenv). - -- Issue #15207: Fix mimetypes to read from correct part of Windows registry - Original patch by Dave Chambers - -- Issue #16595: Add prlimit() to resource module. - -- Issue #19324: Expose Linux-specific constants in resource module. - -- Load SSL's error strings in hashlib. - -- Issue #18527: Upgrade internal copy of zlib to 1.2.8. - -- Issue #19274: Add a filterfunc parameter to PyZipFile.writepy. - -- Issue #8964: fix platform._sys_version to handle IronPython 2.6+. - Patch by Martin Matusiak. - -- Issue #19413: Restore pre-3.3 reload() semantics of re-finding modules. - -- Issue #18958: Improve error message for json.load(s) while passing a string - that starts with a UTF-8 BOM. - -- Issue #19307: Improve error message for json.load(s) while passing objects - of the wrong type. - -- Issue #16038: CVE-2013-1752: ftplib: Limit amount of data read by - limiting the call to readline(). Original patch by Michał - Jastrzębski and Giampaolo Rodola. - -- Issue #17087: Improved the repr for regular expression match objects. - -Tests ------ - -- Issue #19664: test_userdict's repr test no longer depends on the order - of dict elements. - -- 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 as subTests of a unittest TestCase method. - -- Issue #19378: the main dis module tests are now run with both stdout - redirection *and* passing an explicit file parameter - -- Issue #19378: removed the not-actually-helpful assertInstructionMatches - and assertBytecodeExactlyMatches helpers from bytecode_helper - -- Issue #18702: All skipped tests now reported as skipped. - -- Issue #19439: interpreter embedding tests are now executed on Windows - (Patch by Zachary Ware) - -- Issue #19085: Added basic tests for all tkinter widget options. - -- Issue #19384: Fix test_py_compile for root user, patch by Claudiu Popa. - -Documentation -------------- - -- 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. - -Build ------ - -- Issue #19358: "make clinic" now runs the Argument Clinic preprocessor - over all CPython source files. - -- Update SQLite to 3.8.1, xz to 5.0.5, and Tcl/Tk to 8.6.1 on Windows. - -- Issue #16632: Enable DEP and ASLR on Windows. - -- Issue #17791: Drop PREFIX and EXEC_PREFIX definitions from PC/pyconfig.h - -- Add workaround for VS 2010 nmake clean issue. VS 2010 doesn't set up PATH - for nmake.exe correctly. - -- Issue #19550: Implement Windows installer changes of PEP 453 (ensurepip). - -- Issue #19520: Fix compiler warning in the _sha3 module on 32bit Windows. - -- Issue #19356: Avoid using a C variabled named "_self", it's a reserved - word in some C compilers. - -- Issue #15792: Correct build options on Win64. Patch by Jeremy Kloth. - -- Issue #19373: Apply upstream change to Tk 8.5.15 fixing OS X 10.9 - screen refresh problem for OS X installer build. - -- Issue #19649: On OS X, the same set of file names are now installed - in bin directories for all configurations: non-framework vs framework, - and single arch vs universal builds. pythonx.y-32 is now always - installed for 64-bit/32-bit universal builds. The obsolete and - undocumented pythonw* symlinks are no longer installed anywhere. - -- Issue #19553: PEP 453 - "make install" and "make altinstall" now install or - upgrade pip by default, using the bundled pip provided by the new ensurepip - module. A new configure option, --with-ensurepip[=upgrade|install|no], is - available to override the default ensurepip "--upgrade" option. The option - can also be set with "make [alt]install ENSUREPIP=[upgrade|install|no]". - -- Issue #19551: PEP 453 - the OS X installer now installs pip by default. - -- Update third-party libraries for OS X installers: xz 5.0.3 -> 5.0.5, - SQLite 3.7.13 -> 3.8.1 - -- Issue #15663: Revert OS X installer built-in Tcl/Tk support for 3.4.0b1. - Some third-party projects, such as Matplotlib and PIL/Pillow, - depended on being able to build with Tcl and Tk frameworks in - /Library/Frameworks. - -Tools/Demos ------------ - -- Issue #19730: Argument Clinic now supports all the existing PyArg - "format units" as legacy converters, as well as two new features: - "self converters" and the "version" directive. - -- Issue #19552: pyvenv now bootstraps pip into virtual environments by - default (pass --without-pip to request the old behaviour) - -- Issue #19390: Argument Clinic no longer accepts malformed Python - and C ids. - - -What's New in Python 3.4.0 Alpha 4? -=================================== - -Release date: 2013-10-20 - -Core and Builtins ------------------ - -- Issue #19301: Give classes and functions that are explicitly marked global a - global qualname. - -- Issue #19279: UTF-7 decoder no longer produces illegal strings. - -- Issue #16612: Add "Argument Clinic", a compile-time preprocessor for - C files to generate argument parsing code. (See PEP 436.) - -- Issue #18810: Shift stat calls in importlib.machinery.FileFinder such that - the code is optimistic that if something exists in a directory named exactly - like the possible package being searched for that it's in actuality a - directory. - -- Issue #18416: importlib.machinery.PathFinder now treats '' as the cwd and - importlib.machinery.FileFinder no longer special-cases '' to '.'. This leads - to modules imported from cwd to now possess an absolute file path for - __file__ (this does not affect modules specified by path on the CLI but it - does affect -m/runpy). It also allows FileFinder to be more consistent by not - having an edge case. - -- Issue #4555: All exported C symbols are now prefixed with either - "Py" or "_Py". - -- Issue #19219: Speed up marshal.loads(), and make pyc files slightly - (5% to 10%) smaller. - -- Issue #19221: Upgrade Unicode database to version 6.3.0. - -- Issue #16742: The result of the C callback PyOS_ReadlineFunctionPointer must - now be a string allocated by PyMem_RawMalloc() or PyMem_RawRealloc() (or NULL - if an error occurred), instead of a string allocated by PyMem_Malloc() or - PyMem_Realloc(). - -- Issue #19199: Remove ``PyThreadState.tick_counter`` field - -- Fix macro expansion of _PyErr_OCCURRED(), and make sure to use it in at - least one place so as to avoid regressions. - -- Issue #19087: Improve bytearray allocation in order to allow cheap popping - of data at the front (slice deletion). - -- Issue #19014: memoryview.cast() is now allowed on zero-length views. - -- Issue #18690: memoryview is now automatically registered with - collections.abc.Sequence - -- Issue #19078: memoryview now correctly supports the reversed builtin - (Patch by Claudiu Popa) - -Library -------- - -- Issue #17457: unittest test discovery now works with namespace packages. - Patch by Claudiu Popa. - -- Issue #18235: Fix the sysconfig variables LDSHARED and BLDSHARED under AIX. - Patch by David Edelsohn. - -- Issue #18606: Add the new "statistics" module (PEP 450). Contributed - by Steven D'Aprano. - -- Issue #12866: The audioop module now supports 24-bit samples. - -- Issue #19254: Provide an optimized Python implementation of pbkdf2_hmac. - -- Issues #19201, Issue #19222, Issue #19223: Add "x" mode (exclusive creation) - in opening file to bz2, gzip and lzma modules. Patches by Tim Heaney and - Vajrasky Kok. - -- Fix a reference count leak in _sre. - -- Issue #19262: Initial check in of the 'asyncio' package (a.k.a. Tulip, - a.k.a. PEP 3156). There are no docs yet, and the PEP is slightly - out of date with the code. This module will have *provisional* status - in Python 3.4. - -- Issue #19276: Fixed the wave module on 64-bit big-endian platforms. - -- Issue #19266: Rename the new-in-3.4 ``contextlib.ignore`` context manager - to ``contextlib.suppress`` in order to be more consistent with existing - descriptions of that operation elsewhere in the language and standard - library documentation (Patch by Zero Piraeus). - -- Issue #18891: Completed the new email package (provisional) API additions - by adding new classes EmailMessage, MIMEPart, and ContentManager. - -- Issue #18281: Unused stat constants removed from `tarfile`. - -- Issue #18999: Multiprocessing now supports 'contexts' with the same API - as the module, but bound to specified start methods. - -- Issue #18468: The re.split, re.findall, and re.sub functions and the group() - and groups() methods of match object now always return a string or a bytes - object. - -- Issue #18725: The textwrap module now supports truncating multiline text. - -- Issue #18776: atexit callbacks now display their full traceback when they - raise an exception. - -- Issue #17827: Add the missing documentation for ``codecs.encode`` and - ``codecs.decode``. - -- Issue #19218: Rename collections.abc to _collections_abc in order to - speed up interpreter start. - -- Issue #18582: Add 'pbkdf2_hmac' to the hashlib module. It implements PKCS#5 - password-based key derivation functions with HMAC as pseudorandom function. - -- Issue #19131: The aifc module now correctly reads and writes sampwidth of - compressed streams. - -- Issue #19209: Remove import of copyreg from the os module to speed up - interpreter startup. stat_result and statvfs_result are now hard-coded to - reside in the os module. - -- Issue #19205: Don't import the 're' module in site and sysconfig module to - speed up interpreter start. - -- Issue #9548: Add a minimal "_bootlocale" module that is imported by the - _io module instead of the full locale module. - -- Issue #18764: Remove the 'print' alias for the PDB 'p' command so that it no - longer shadows the print function. - -- Issue #19158: A rare race in BoundedSemaphore could allow .release() too - often. - -- Issue #15805: Add contextlib.redirect_stdout(). - -- Issue #18716: Deprecate the formatter module. - -- Issue #10712: 2to3 has a new "asserts" fixer that replaces deprecated names - of unittest methods (e.g. failUnlessEqual -> assertEqual). - -- Issue #18037: 2to3 now escapes ``'\u'`` and ``'\U'`` in native strings. - -- Issue #17839: base64.decodebytes and base64.encodebytes now accept any - object that exports a 1 dimensional array of bytes (this means the same - is now also true for base64_codec) - -- Issue #19132: The pprint module now supports compact mode. - -- Issue #19137: The pprint module now correctly formats instances of set and - frozenset subclasses. - -- Issue #10042: functools.total_ordering now correctly handles - NotImplemented being returned by the underlying comparison function (Patch - by Katie Miller) - -- Issue #19092: contextlib.ExitStack now correctly reraises exceptions - from the __exit__ callbacks of inner context managers (Patch by Hrvoje - Nikšić) - -- Issue #12641: Avoid passing "-mno-cygwin" to the mingw32 compiler, except - when necessary. Patch by Oscar Benjamin. - -- Issue #5845: In site.py, only load readline history from ~/.python_history - if no history has been read already. This avoids double writes to the - history file at shutdown. - -- Properly initialize all fields of a SSL object after allocation. - -- Issue #19095: SSLSocket.getpeercert() now raises ValueError when the - SSL handshake hasn't been done. - -- Issue #4366: Fix building extensions on all platforms when --enable-shared - is used. - -- Issue #19030: Fixed `inspect.getmembers` and `inspect.classify_class_attrs` - to attempt activating descriptors before falling back to a __dict__ search - for faulty descriptors. `inspect.classify_class_attrs` no longer returns - Attributes whose home class is None. - -C API ------ - -- Issue #1772673: The type of `char*` arguments now changed to `const char*`. - -- Issue #16129: Added a `Py_SetStandardStreamEncoding` pre-initialization API - to allow embedding applications like Blender to force a particular - encoding and error handler for the standard IO streams (initial patch by - Bastien Montagne) - -Tests ------ - -- Issue #19275: Fix test_site on AMD64 Snow Leopard - -- Issue #14407: Fix unittest test discovery in test_concurrent_futures. - -- Issue #18919: Unified and extended tests for audio modules: aifc, sunau and - wave. - -- Issue #18714: Added tests for ``pdb.find_function()``. - -Documentation -------------- - -- Issue #18758: Fixed and improved cross-references. - -- Issue #18972: Modernize email examples and use the argparse module in them. - -Build ------ - -- Issue #19130: Correct PCbuild/readme.txt, Python 3.3 and 3.4 require VS 2010. - -- Issue #15663: Update OS X 10.6+ installer to use Tcl/Tk 8.5.15. - -- Issue #14499: Fix several problems with OS X universal build support: - 1. ppc arch detection for extension module builds broke with Xcode 5 - 2. ppc arch detection in configure did not work on OS X 10.4 - 3. -sysroot and -arch flags were unnecessarily duplicated - 4. there was no obvious way to configure an intel-32 only build. - -- Issue #19019: Change the OS X installer build script to use CFLAGS instead - of OPT for special build options. By setting OPT, some compiler-specific - options like -fwrapv were overridden and thus not used, which could result - in broken interpreters when building with clang. - - -What's New in Python 3.4.0 Alpha 3? -=================================== - -Release date: 2013-09-29 - -Core and Builtins ------------------ - -- Issue #18818: The "encodingname" part of PYTHONIOENCODING is now optional. - -- Issue #19098: Prevent overflow in the compiler when the recursion limit is set - absurdly high. - -Library -------- - -- Issue #18929: `inspect.classify_class_attrs()` now correctly finds class - attributes returned by `dir()` that are located in the metaclass. - -- Issue #18950: Fix miscellaneous bugs in the sunau module. - Au_read.readframes() now updates current file position and reads correct - number of frames from multichannel stream. Au_write.writeframesraw() now - correctly updates current file position. Au_read.getnframes() now returns an - integer (as in Python 2). Au_read and Au_write now correctly works with file - object if start file position is not a zero. - -- Issue #18594: The fast path for collections.Counter() was never taken - due to an over-restrictive type check. - -- Issue #19053: ZipExtFile.read1() with non-zero argument no more returns empty - bytes until end of data. - -- logging: added support for Unix domain sockets to SocketHandler and - DatagramHandler. - -- Issue #18996: TestCase.assertEqual() now more cleverly shorten differing - strings in error report. - -- Issue #19034: repr() for tkinter.Tcl_Obj now exposes string reperesentation. - -- Issue #18978: ``urllib.request.Request`` now allows the method to be - indicated on the class and no longer sets it to None in ``__init__``. - -- Issue #18626: the inspect module now offers a basic command line - introspection interface (Initial patch by Claudiu Popa) - -- Issue #3015: Fixed tkinter with wantobject=False. Any Tcl command call - returned empty string. - -- Issue #19037: The mailbox module now makes all changes to maildir files - before moving them into place, to avoid race conditions with other programs - that may be accessing the maildir directory. - -- Issue #14984: On POSIX systems, when netrc is called without a filename - argument (and therefore is reading the user's $HOME/.netrc file), it now - enforces the same security rules as typical ftp clients: the .netrc file must - be owned by the user that owns the process and must not be readable by any - other user. - -- Issue #18873: The tokenize module now detects Python source code encoding - only in comment lines. - -- Issue #17764: Enable http.server to bind to a user specified network - interface. Patch contributed by Malte Swart. - -- Issue #18937: Add an assertLogs() context manager to unittest.TestCase - to ensure that a block of code emits a message using the logging module. - -- Issue #17324: Fix http.server's request handling case on trailing '/'. Patch - contributed by Vajrasky Kok. - -- Issue #19018: The heapq.merge() function no longer suppresses IndexError - in the underlying iterables. - -- Issue #18784: The uuid module no longer attempts to load libc via ctypes.CDLL - if all the necessary functions have already been found in libuuid. Patch by - Evgeny Sologubov. - -- The :envvar:`PYTHONFAULTHANDLER` environment variable now only enables the - faulthandler module if the variable is non-empty. Same behaviour than other - variables like :envvar:`PYTHONDONTWRITEBYTECODE`. - -- Issue #1565525: New function ``traceback.clear_frames`` will clear - the local variables of all the stack frames referenced by a traceback - object. - -Tests ------ - -- Issue #18952: Fix regression in support data downloads introduced when - test.support was converted to a package. Regression noticed by Zachary - Ware. - -IDLE ----- - -- Issue #18873: IDLE now detects Python source code encoding only in comment - lines. - -- Issue #18988: The "Tab" key now works when a word is already autocompleted. - -Documentation -------------- - -- Issue #17003: Unified the size argument names in the io module with common - practice. - -Build ------ - -- Issue #18596: Support the use of address sanity checking in recent versions - of clang and GCC by appropriately marking known false alarms in the small - object allocator. Patch contributed by Dhiru Kholia. - -Tools/Demos ------------ - -- Issue #18873: 2to3 and the findnocoding.py script now detect Python source - code encoding only in comment lines. - - -What's New in Python 3.4.0 Alpha 2? -=================================== - -Release date: 2013-09-09 - -Core and Builtins ------------------ - -- Issue #18942: sys._debugmallocstats() output was damaged on Windows. - -- Issue #18571: Implementation of the PEP 446: file descriptors and file - handles are now created non-inheritable; add functions - os.get/set_inheritable(), os.get/set_handle_inheritable() and - socket.socket.get/set_inheritable(). - -- Issue #11619: The parser and the import machinery do not encode Unicode - filenames anymore on Windows. - -- Issue #18808: Non-daemon threads are now automatically joined when - a sub-interpreter is shutdown (it would previously dump a fatal error). - -- Remove support for compiling on systems without getcwd(). - -- Issue #18774: Remove last bits of GNU PTH thread code and thread_pth.h. - -- Issue #18771: Add optimization to set object lookups to reduce the cost - of hash collisions. The core idea is to inspect a second key/hash pair - for each cache line retrieved. - -- Issue #16105: When a signal handler fails to write to the file descriptor - registered with ``signal.set_wakeup_fd()``, report an exception instead - of ignoring the error. - -- Issue #18722: Remove uses of the "register" keyword in C code. - -- Issue #18667: Add missing "HAVE_FCHOWNAT" symbol to posix._have_functions. - -- Issue #16499: Add command line option for isolated mode. - -- Issue #15301: Parsing fd, uid, and gid parameters for builtins - in Modules/posixmodule.c is now far more robust. - -- Issue #18368: PyOS_StdioReadline() no longer leaks memory when realloc() - fail. - -- Issue #17934: Add a clear() method to frame objects, to help clean up - expensive details (local variables) and break reference cycles. - -- Issue #18780: %-formatting codes %d, %i, and %u now treat int-subclasses - as int (displays value of int-subclass instead of str(int-subclass) ). - -Library -------- - -- Issue #18808: Thread.join() now waits for the underlying thread state to - be destroyed before returning. This prevents unpredictable aborts in - Py_EndInterpreter() when some non-daemon threads are still running. - -- Issue #18458: Prevent crashes with newer versions of libedit. Its readline - emulation has changed from 0-based indexing to 1-based like gnu readline. - -- Issue #18852: Handle case of ``readline.__doc__`` being ``None`` in the new - readline activation code in ``site.py``. - -- Issue #18672: Fixed format specifiers for Py_ssize_t in debugging output in - the _sre module. - -- Issue #18830: inspect.getclasstree() no longer produces duplicate entries even - when input list contains duplicates. - -- Issue #18878: sunau.open now supports the context management protocol. Based on - patches by Claudiu Popa and R. David Murray. - -- Issue #18909: Fix _tkinter.tkapp.interpaddr() on Windows 64-bit, don't cast - 64-bit pointer to long (32 bits). - -- Issue #18876: The FileIO.mode attribute now better reflects the actual mode - under which the file was opened. Patch by Erik Bray. - -- Issue #16853: Add new selectors module. - -- Issue #18882: Add threading.main_thread() function. - -- Issue #18901: The sunau getparams method now returns a namedtuple rather than - a plain tuple. Patch by Claudiu Popa. - -- Issue #17487: The result of the wave getparams method now is pickleable again. - Patch by Claudiu Popa. - -- Issue #18756: os.urandom() now uses a lazily-opened persistent file - descriptor, so as to avoid using many file descriptors when run in - parallel from multiple threads. - -- Issue #18418: After fork(), reinit all threads states, not only active ones. - Patch by A. Jesse Jiryu Davis. - -- Issue #17974: Switch unittest from using getopt to using argparse. - -- Issue #11798: TestSuite now drops references to own tests after execution. - -- Issue #16611: http.cookie now correctly parses the 'secure' and 'httponly' - cookie flags. - -- Issue #11973: Fix a problem in kevent. The flags and fflags fields are now - properly handled as unsigned. - -- Issue #18807: ``pyvenv`` now takes a --copies argument allowing copies - instead of symlinks even where symlinks are available and the default. - -- Issue #18538: ``python -m dis`` now uses argparse for argument processing. - Patch by Michele Orrù. - -- Issue #18394: Close cgi.FieldStorage's optional file. - -- Issue #17702: On error, os.environb now suppresses the exception context - when raising a new KeyError with the original key. - -- Issue #16809: Fixed some tkinter incompabilities with Tcl/Tk 8.6. - -- Issue #16809: Tkinter's splitlist() and split() methods now accept Tcl_Obj - argument. - -- Issue #18324: set_payload now correctly handles binary input. This also - supersedes the previous fixes for #14360, #1717, and #16564. - -- Issue #18794: Add a fileno() method and a closed attribute to select.devpoll - objects. - -- Issue #17119: Fixed integer overflows when processing large strings and tuples - in the tkinter module. - -- Issue #18747: Re-seed OpenSSL's pseudo-random number generator after fork. - A pthread_atfork() parent handler is used to seed the PRNG with pid, time - and some stack data. - -- Issue #8865: Concurrent invocation of select.poll.poll() now raises a - RuntimeError exception. Patch by Christian Schubert. - -- Issue #18777: The ssl module now uses the new CRYPTO_THREADID API of - OpenSSL 1.0.0+ instead of the deprecated CRYPTO id callback function. - -- Issue #18768: Correct doc string of RAND_edg(). Patch by Vajrasky Kok. - -- Issue #18178: Fix ctypes on BSD. dlmalloc.c was compiled twice which broke - malloc weak symbols. - -- Issue #18709: Fix CVE-2013-4238. The SSL module now handles NULL bytes - inside subjectAltName correctly. Formerly the module has used OpenSSL's - GENERAL_NAME_print() function to get the string represention of ASN.1 - strings for ``rfc822Name`` (email), ``dNSName`` (DNS) and - ``uniformResourceIdentifier`` (URI). - -- Issue #18701: Remove support of old CPython versions (<3.0) from C code. - -- Issue #18756: Improve error reporting in os.urandom() when the failure - is due to something else than /dev/urandom not existing (for example, - exhausting the file descriptor limit). - -- Issue #18673: Add O_TMPFILE to os module. O_TMPFILE requires Linux kernel - 3.11 or newer. It's only defined on system with 3.11 uapi headers, too. - -- Issue #18532: Change the builtin hash algorithms' names to lower case names - as promised by hashlib's documentation. - -- Issue #8713: add new spwan and forkserver start methods, and new functions - get_all_start_methods, get_start_method, and set_start_method, to - multiprocessing. - -- Issue #18405: Improve the entropy of crypt.mksalt(). - -- Issue #12015: The tempfile module now uses a suffix of 8 random characters - instead of 6, to reduce the risk of filename collision. The entropy was - reduced when uppercase letters were removed from the charset used to generate - random characters. - -- Issue #18585: Add :func:`textwrap.shorten` to collapse and truncate a - piece of text to a given length. - -- Issue #18598: Tweak exception message for importlib.import_module() to - include the module name when a key argument is missing. - -- Issue #19151: Fix docstring and use of _get_supported_file_loaders() to - reflect 2-tuples. - -- Issue #19152: Add ExtensionFileLoader.get_filename(). - -- Issue #18676: Change 'positive' to 'non-negative' in queue.py put and get - docstrings and ValueError messages. Patch by Zhongyue Luo - -- Fix refcounting issue with extension types in tkinter. - -- Issue #8112: xlmrpc.server's DocXMLRPCServer server no longer raises an error - if methods have annotations; it now correctly displays the annotations. - -- Issue #18600: Added policy argument to email.message.Message.as_string, - and as_bytes and __bytes__ methods to Message. - -- Issue #18671: Output more information when logging exceptions occur. - -- Issue #18621: Prevent the site module's patched builtins from keeping - too many references alive for too long. - -- Issue #4885: Add weakref support to mmap objects. Patch by Valerie Lambert. - -- Issue #8860: Fixed rounding in timedelta constructor. - -- Issue #18849: Fixed a Windows-specific tempfile bug where collision with an - existing directory caused mkstemp and related APIs to fail instead of - retrying. Report and fix by Vlad Shcherbina. - -- Issue #18920: argparse's default destination for the version action (-v, - --version) has also been changed to stdout, to match the Python executable. - -Tests ------ - -- Issue #18623: Factor out the _SuppressCoreFiles context manager into - test.support. Patch by Valerie Lambert. - -- Issue #12037: Fix test_email for desktop Windows. - -- Issue #15507: test_subprocess's test_send_signal could fail if the test - runner were run in an environment where the process inherited an ignore - setting for SIGINT. Restore the SIGINT handler to the desired - KeyboardInterrupt raising one during that test. - -- Issue #16799: Switched from getopt to argparse style in regrtest's argument - parsing. Added more tests for regrtest's argument parsing. - -- Issue #18792: Use "127.0.0.1" or "::1" instead of "localhost" as much as - possible, since "localhost" goes through a DNS lookup under recent Windows - versions. - -IDLE ----- - -- Issue #18489: Add tests for SearchEngine. Original patch by Phil Webster. - -Documentation -------------- - -- Issue #18743: Fix references to non-existant "StringIO" module. - -- Issue #18783: Removed existing mentions of Python long type in docstrings, - error messages and comments. - -Build ------ - -- Issue #1584: Provide configure options to override default search paths for - Tcl and Tk when building _tkinter. - -- Issue #15663: Tcl/Tk 8.5.14 is now included with the OS X 10.6+ 64-/32-bit - installer. It is no longer necessary to install a third-party version of - Tcl/Tk 8.5 to work around the problems in the Apple-supplied Tcl/Tk 8.5 - shipped in OS X 10.6 and later releases. - -Tools/Demos ------------ - -- Issue #18922: Now The Lib/smtpd.py and Tools/i18n/msgfmt.py scripts write - their version strings to stdout, and not to sderr. - - -What's New in Python 3.4.0 Alpha 1? -=================================== - -Release date: 2013-08-03 - -Core and Builtins ------------------ - -- Issue #16741: Fix an error reporting in int(). - -- Issue #17899: Fix rare file descriptor leak in os.listdir(). - -- Issue #10241: Clear extension module dict copies at interpreter shutdown. - Patch by Neil Schemenauer, minimally modified. - -- Issue #9035: ismount now recognises volumes mounted below a drive root - on Windows. Original patch by Atsuo Ishimoto. - -- Issue #18214: Improve finalization of Python modules to avoid setting - their globals to None, in most cases. - -- Issue #18112: PEP 442 implementation (safe object finalization). - -- Issue #18552: Check return value of PyArena_AddPyObject() in - obj2ast_object(). - -- Issue #18560: Fix potential NULL pointer dereference in sum(). - -- Issue #18520: Add a new PyStructSequence_InitType2() function, same than - PyStructSequence_InitType() except that it has a return value (0 on success, - -1 on error). - -- 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 #18408: Fix many various bugs in code handling errors, especially - on memory allocation failure (MemoryError). - -- Issue #18344: Fix potential ref-leaks in _bufferedreader_read_all(). - -- Issue #18342: Use the repr of a module name when an import fails when using - ``from ... import ...``. - -- Issue #17872: Fix a segfault in marshal.load() when input stream returns - more bytes than requested. - -- Issue #18338: `python --version` now prints version string to stdout, and - not to stderr. Patch by Berker Peksag and Michael Dickens. - -- Issue #18426: Fix NULL pointer dereference in C extension import when - PyModule_GetDef() returns an error. - -- Issue #17206: On Windows, increase the stack size from 2 MB to 4.2 MB to fix - a stack overflow in the marshal module (fix a crash in test_marshal). - Patch written by Jeremy Kloth. - -- Issue #3329: Implement the PEP 445: Add new APIs to customize Python memory - allocators. - -- Issue #18328: Reorder ops in PyThreadState_Delete*() functions. Now the - tstate is first removed from TLS and then deallocated. - -- Issue #13483: Use VirtualAlloc in obmalloc on Windows. - -- Issue #18184: PyUnicode_FromFormat() and PyUnicode_FromFormatV() now raise - OverflowError when an argument of %c format is out of range. - -- Issue #18111: The min() and max() functions now support a default argument - to be returned instead of raising a ValueError on an empty sequence. - (Contributed by Julian Berman.) - -- Issue #18137: Detect integer overflow on precision in float.__format__() - and complex.__format__(). - -- Issue #18183: Fix various unicode operations on strings with large unicode - codepoints. - -- Issue #18180: Fix ref leak in _PyImport_GetDynLoadWindows(). - -- Issue #18038: SyntaxError raised during compilation sources with illegal - encoding now always contains an encoding name. - -- Issue #17931: Resolve confusion on Windows between pids and process - handles. - -- Tweak the exception message when the magic number or size value in a bytecode - file is truncated. - -- Issue #17932: Fix an integer overflow issue on Windows 64-bit in iterators: - change the C type of seqiterobject.it_index from long to Py_ssize_t. - -- Issue #18065: Don't set __path__ to the package name for frozen packages. - -- Issue #18088: When reloading a module, unconditionally reset all relevant - attributes on the module (e.g. __name__, __loader__, __package__, __file__, - __cached__). - -- Issue #17937: Try harder to collect cyclic garbage at shutdown. - -- Issue #12370: Prevent class bodies from interfering with the __class__ - closure. - -- Issue #17644: Fix a crash in str.format when curly braces are used in square - brackets. - -- Issue #17237: Fix crash in the ASCII decoder on m68k. - -- Issue #17927: Frame objects kept arguments alive if they had been - copied into a cell, even if the cell was cleared. - -- Issue #1545463: At shutdown, defer finalization of codec modules so - that stderr remains usable. - -- Issue #7330: Implement width and precision (ex: "%5.3s") for the format - string of PyUnicode_FromFormat() function, original patch written by Ysj Ray. - -- Issue #1545463: Global variables caught in reference cycles are now - garbage-collected at shutdown. - -- Issue #17094: Clear stale thread states after fork(). Note that this - is a potentially disruptive change since it may release some system - resources which would otherwise remain perpetually alive (e.g. database - connections kept in thread-local storage). - -- Issue #17408: Avoid using an obsolete instance of the copyreg module when - the interpreter is shutdown and then started again. - -- Issue #5845: Enable tab-completion in the interactive interpreter by - default, thanks to a new sys.__interactivehook__. - -- Issue #17115,17116: Module initialization now includes setting __package__ and - __loader__ attributes to None. - -- Issue #17853: Ensure locals of a class that shadow free variables always win - over the closures. - -- Issue #17863: In the interactive console, don't loop forever if the encoding - can't be fetched from stdin. - -- Issue #17867: Raise an ImportError if __import__ is not found in __builtins__. - -- Issue #18698: Ensure importlib.reload() returns the module out of sys.modules. - -- Issue #17857: Prevent build failures with pre-3.5.0 versions of sqlite3, - such as was shipped with Centos 5 and Mac OS X 10.4. - -- Issue #17413: sys.settrace callbacks were being passed a string instead of an - exception instance for the 'value' element of the arg tuple if the exception - originated from C code; now an exception instance is always provided. - -- Issue #17782: Fix undefined behaviour on platforms where - ``struct timespec``'s "tv_nsec" member is not a C long. - -- Issue #17722: When looking up __round__, resolve descriptors. - -- Issue #16061: Speed up str.replace() for replacing 1-character strings. - -- Issue #17715: Fix segmentation fault from raising an exception in a __trunc__ - method. - -- Issue #17643: Add __callback__ attribute to weakref.ref. - -- Issue #16447: Fixed potential segmentation fault when setting __name__ on a - class. - -- Issue #17669: Fix crash involving finalization of generators using yield from. - -- Issue #14439: Python now prints the traceback on runpy failure at startup. - -- Issue #17469: Fix _Py_GetAllocatedBlocks() and sys.getallocatedblocks() - when running on valgrind. - -- Issue #17619: Make input() check for Ctrl-C correctly on Windows. - -- Issue #17357: Add missing verbosity messages for -v/-vv that were lost during - the importlib transition. - -- Issue #17610: Don't rely on non-standard behavior of the C qsort() function. - -- Issue #17323: The "[X refs, Y blocks]" printed by debug builds has been - disabled by default. It can be re-enabled with the `-X showrefcount` option. - -- Issue #17328: Fix possible refleak in dict.setdefault. - -- Issue #17275: Corrected class name in init error messages of the C version of - BufferedWriter and BufferedRandom. - -- Issue #7963: Fixed misleading error message that issued when object is - called without arguments. - -- Issue #8745: Small speed up zipimport on Windows. Patch by Catalin Iacob. - -- Issue #5308: Raise ValueError when marshalling too large object (a sequence - with size >= 2**31), instead of producing illegal marshal data. - -- Issue #12983: Bytes literals with invalid ``\x`` escape now raise a SyntaxError - and a full traceback including line number. - -- Issue #16967: In function definition, evaluate positional defaults before - keyword-only defaults. - -- Issue #17173: Remove uses of locale-dependent C functions (isalpha() etc.) - in the interpreter. - -- Issue #17137: When an Unicode string is resized, the internal wide character - string (wstr) format is now cleared. - -- Issue #17043: The unicode-internal decoder no longer read past the end of - input buffer. - -- Issue #17098: All modules now have __loader__ set even if they pre-exist the - bootstrapping of importlib. - -- Issue #16979: Fix error handling bugs in the unicode-escape-decode decoder. - -- Issue #16772: The base argument to the int constructor no longer accepts - floats, or other non-integer objects with an __int__ method. Objects - with an __index__ method are now accepted. - -- Issue #10156: In the interpreter's initialization phase, unicode globals - are now initialized dynamically as needed. - -- Issue #16980: Fix processing of escaped non-ascii bytes in the - unicode-escape-decode decoder. - -- Issue #16975: Fix error handling bug in the escape-decode bytes decoder. - -- Issue #14850: Now a charmap decoder treats U+FFFE as "undefined mapping" - in any mapping, not only in a string. - -- Issue #16613: Add *m* argument to ``collections.Chainmap.new_child`` to - allow the new child map to be specified explicitly. - -- Issue #16730: importlib.machinery.FileFinder now no longers raises an - exception when trying to populate its cache and it finds out the directory is - unreadable or has turned into a file. Reported and diagnosed by - David Pritchard. - -- Issue #16906: Fix a logic error that prevented most static strings from being - cleared. - -- Issue #11461: Fix the incremental UTF-16 decoder. Original patch by - Amaury Forgeot d'Arc. - -- Issue #16856: Fix a segmentation fault from calling repr() on a dict with - a key whose repr raise an exception. - -- Issue #16367: Fix FileIO.readall() on Windows for files larger than 2 GB. - -- Issue #16761: Calling int() with base argument only now raises TypeError. - -- Issue #16759: Support the full DWORD (unsigned long) range in Reg2Py - when retrieving a REG_DWORD value. This corrects functions like - winreg.QueryValueEx that may have been returning truncated values. - -- Issue #14420: Support the full DWORD (unsigned long) range in Py2Reg - when passed a REG_DWORD value. Fixes OverflowError in winreg.SetValueEx. - -- Issue #11939: Set the st_dev attribute of stat_result to allow Windows to - take advantage of the os.path.samefile/sameopenfile/samestat implementations - used by other platforms. - -- Issue #16772: The int() constructor's second argument (base) no longer - accepts non integer values. Consistent with the behavior in Python 2. - -- Issue #14470: Remove w9xpopen support per PEP 11. - -- Issue #9856: Replace deprecation warning with raising TypeError - in object.__format__. Patch by Florent Xicluna. - -- Issue #16597: In buffered and text IO, call close() on the underlying stream - if invoking flush() fails. - -- Issue #16722: In the bytes() constructor, try to call __bytes__ on the - argument before __index__. - -- Issue #16421: loading multiple modules from one shared object is now - handled correctly (previously, the first module loaded from that file - was silently returned). Patch by Václav Šmilauer. - -- Issue #16602: When a weakref's target was part of a long deallocation - chain, the object could remain reachable through its weakref even though - its refcount had dropped to zero. - -- Issue #16495: Remove extraneous NULL encoding check from bytes_decode(). - -- Issue #16619: Create NameConstant AST class to represent None, True, and False - literals. As a result, these constants are never loaded at runtime from - builtins. - -- Issue #16455: On FreeBSD and Solaris, if the locale is C, the - ASCII/surrogateescape codec is now used (instead of the locale encoding) to - decode the command line arguments. This change fixes inconsistencies with - os.fsencode() and os.fsdecode(), because these operating systems announce an - ASCII locale encoding, but actually use the ISO-8859-1 encoding in practice. - -- Issue #16562: Optimize dict equality testing. Patch by Serhiy Storchaka. - -- Issue #16588: Silence unused-but-set warnings in Python/thread_pthread - -- Issue #16592: stringlib_bytes_join doesn't raise MemoryError on allocation - failure. - -- Issue #16546: Fix: ast.YieldFrom argument is now mandatory. - -- Issue #16514: Fix regression causing a traceback when sys.path[0] is None - (actually, any non-string or non-bytes type). - -- Issue #16306: Fix multiple error messages when unknown command line - parameters where passed to the interpreter. Patch by Hieu Nguyen. - -- Issue #16215: Fix potential double memory free in str.replace(). Patch - by Serhiy Storchaka. - -- Issue #16290: A float return value from the __complex__ special method is no - longer accepted in the complex() constructor. - -- Issue #16416: On Mac OS X, operating system data are now always - encoded/decoded to/from UTF-8/surrogateescape, instead of the locale encoding - (which may be ASCII if no locale environment variable is set), to avoid - inconsistencies with os.fsencode() and os.fsdecode() functions which are - already using UTF-8/surrogateescape. - -- Issue #16453: Fix equality testing of dead weakref objects. - -- Issue #9535: Fix pending signals that have been received but not yet - handled by Python to not persist after os.fork() in the child process. - -- Issue #14794: Fix slice.indices to return correct results for huge values, - rather than raising OverflowError. - -- Issue #15001: fix segfault on "del sys.modules['__main__']". Patch by Victor - Stinner. - -- Issue #8271: the utf-8 decoder now outputs the correct number of U+FFFD - characters when used with the 'replace' error handler on invalid utf-8 - sequences. Patch by Serhiy Storchaka, tests by Ezio Melotti. - -- Issue #5765: Apply a hard recursion limit in the compiler instead of - blowing the stack and segfaulting. Initial patch by Andrea Griffini. - -- Issue #16402: When slicing a range, fix shadowing of exceptions from - __index__. - -- Issue #16336: fix input checking in the surrogatepass error handler. - Patch by Serhiy Storchaka. - -- Issue #8401: assigning an int to a bytearray slice (e.g. b[3:4] = 5) now - raises an error. - -- Issue #7317: Display full tracebacks when an error occurs asynchronously. - Patch by Alon Horev with update by Alexey Kachayev. - -- Issue #16309: Make PYTHONPATH="" behavior the same as if PYTHONPATH - not set at all. - -- Issue #10189: Improve the error reporting of SyntaxErrors related to global - and nonlocal statements. - -- Fix segfaults on setting __qualname__ on builtin types and attempting to - delete it on any type. - -- Issue #14625: Rewrite the UTF-32 decoder. It is now 3x to 4x faster. Patch - written by Serhiy Storchaka. - -- Issue #16345: Fix an infinite loop when ``fromkeys`` on a dict subclass - received a nonempty dict from the constructor. - -- Issue #16271: Fix strange bugs that resulted from __qualname__ appearing in a - class's __dict__ and on type. - -- Issue #12805: Make bytes.join and bytearray.join faster when the separator - is empty. Patch by Serhiy Storchaka. - -- Issue #6074: Ensure cached bytecode files can always be updated by the - user that created them, even when the source file is read-only. - -- Issue #15958: bytes.join and bytearray.join now accept arbitrary buffer - objects. - -- Issue #14783: Improve int() docstring and switch docstrings for str(), - range(), and slice() to use multi-line signatures. - -- Issue #16160: Subclass support now works for types.SimpleNamespace. - -- Issue #16148: Implement PEP 424, adding operator.length_hint and - PyObject_LengthHint. - -- Upgrade Unicode data (UCD) to version 6.2. - -- Issue #15379: Fix passing of non-BMP characters as integers for the charmap - decoder (already working as unicode strings). Patch by Serhiy Storchaka. - -- Issue #15144: Fix possible integer overflow when handling pointers as integer - values, by using `Py_uintptr_t` instead of `size_t`. Patch by Serhiy - Storchaka. - -- Issue #15965: Explicitly cast `AT_FDCWD` as (int). Required on Solaris 10 - (which defines `AT_FDCWD` as ``0xffd19553``), harmless on other platforms. - -- Issue #15839: Convert SystemErrors in `super()` to RuntimeErrors. - -- Issue #15448: Buffered IO now frees the buffer when closed, instead - of when deallocating. - -- Issue #15846: Fix SystemError which happened when using `ast.parse()` in an - exception handler on code with syntax errors. - -- Issue #15897: zipimport.c doesn't check return value of fseek(). - Patch by Felipe Cruz. - -- Issue #15801: Make sure mappings passed to '%' formatting are actually - subscriptable. - -- Issue #15111: __import__ should propagate ImportError when raised as a - side-effect of a module triggered from using fromlist. - -- Issue #15022: Add pickle and comparison support to types.SimpleNamespace. - -Library -------- - -- Issue #4331: Added functools.partialmethod (Initial patch by Alon Horev) - -- Issue #13461: Fix a crash in the TextIOWrapper.tell method on 64-bit - platforms. Patch by Yogesh Chaudhari. - -- Issue #18681: Fix a NameError in importlib.reload() (noticed by Weizhao Li). - -- Issue #14323: Expanded the number of digits in the coefficients for the - RGB -- YIQ conversions so that they match the FCC NTSC versions. - -- Issue #17998: Fix an internal error in regular expression engine. - -- Issue #17557: Fix os.getgroups() to work with the modified behavior of - getgroups(2) on OS X 10.8. Original patch by Mateusz Lenik. - -- Issue #18608: Avoid keeping a strong reference to the locale module - inside the _io module. - -- Issue #18619: Fix atexit leaking callbacks registered from sub-interpreters, - and make it GC-aware. - -- Issue #15699: The readline module now uses PEP 3121-style module - initialization, so as to reclaim allocated resources (Python callbacks) - at shutdown. Original patch by Robin Schreiber. - -- Issue #17616: wave.open now supports the context management protocol. - -- Issue #18599: Fix name attribute of _sha1.sha1() object. It now returns - 'SHA1' instead of 'SHA'. - -- Issue #13266: Added inspect.unwrap to easily unravel __wrapped__ chains - (initial patch by Daniel Urban and Aaron Iles) - -- Issue #18561: Skip name in ctypes' _build_callargs() if name is NULL. - -- Issue #18559: Fix NULL pointer dereference error in _pickle module - -- Issue #18556: Check the return type of PyUnicode_AsWideChar() in ctype's - U_set(). - -- Issue #17818: aifc.getparams now returns a namedtuple. - -- Issue #18549: Eliminate dead code in socket_ntohl() - -- Issue #18530: Remove additional stat call from posixpath.ismount. - Patch by Alex Gaynor. - -- Issue #18514: Fix unreachable Py_DECREF() call in PyCData_FromBaseObj() - -- Issue #9177: Calling read() or write() now raises ValueError, not - AttributeError, on a closed SSL socket. Patch by Senko Rasic. - -- Issue #18513: Fix behaviour of cmath.rect w.r.t. signed zeros on OS X 10.8 + - gcc. - -- Issue #18479: Changed venv Activate.ps1 to make deactivate a function, and - removed Deactivate.ps1. - -- Issue #18480: Add missing call to PyType_Ready to the _elementtree extension. - -- Issue #17778: Fix test discovery for test_multiprocessing. (Patch by - Zachary Ware.) - -- Issue #18393: The private module _gestalt and private functions - platform._mac_ver_gestalt, platform._mac_ver_lookup and - platform._bcd2str have been removed. This does not affect the public - interface of the platform module. - -- Issue #17482: functools.update_wrapper (and functools.wraps) now set the - __wrapped__ attribute correctly even if the underlying function has a - __wrapped__ attribute set. - -- Issue #18431: The new email header parser now decodes RFC2047 encoded words - in structured headers. - -- Issue #18432: The sched module's queue method was incorrectly returning - an iterator instead of a list. - -- Issue #18044: The new email header parser was mis-parsing encoded words where - an encoded character immediately followed the '?' that follows the CTE - character, resulting in a decoding failure. They are now decoded correctly. - -- Issue #18101: Tcl.split() now process strings nested in a tuple as it - do with byte strings. - -- Issue #18116: getpass was always getting an error when testing /dev/tty, - and thus was always falling back to stdin, and would then raise an exception - if stdin could not be used (such as /dev/null). It also leaked an open file. - All of these issues are now fixed. - -- Issue #17198: Fix a NameError in the dbm module. Patch by Valentina - Mukhamedzhanova. - -- Issue #18013: Fix cgi.FieldStorage to parse the W3C sample form. - -- Issue #18020: improve html.escape speed by an order of magnitude. - Patch by Matt Bryant. - -- Issue #18347: ElementTree's html serializer now preserves the case of - closing tags. - -- Issue #17261: Ensure multiprocessing's proxies use proper address. - -- Issue #18343: faulthandler.register() now keeps the previous signal handler - when the function is called twice, so faulthandler.unregister() restores - correctly the original signal handler. - -- Issue #17097: Make multiprocessing ignore EINTR. - -- Issue #18339: Negative ints keys in unpickler.memo dict no longer cause a - segfault inside the _pickle C extension. - -- Issue #18240: The HMAC module is no longer restricted to bytes and accepts - any bytes-like object, e.g. memoryview. Original patch by Jonas Borgström. - -- Issue #18224: Removed pydoc script from created venv, as it causes problems - on Windows and adds no value over and above python -m pydoc ... - -- Issue #18155: The csv module now correctly handles csv files that use - a delimter character that has a special meaning in regexes, instead of - throwing an exception. - -- Issue #14360: encode_quopri can now be successfully used as an encoder - when constructing a MIMEApplication object. - -- Issue #11390: Add -o and -f command line options to the doctest CLI to - specify doctest options (and convert it to using argparse). - -- Issue #18135: ssl.SSLSocket.write() now raises an OverflowError if the input - string in longer than 2 gigabytes, and ssl.SSLContext.load_cert_chain() - raises a ValueError if the password is longer than 2 gigabytes. The ssl - module does not support partial write. - -- Issue #11016: Add C implementation of the stat module as _stat. - -- Issue #18248: Fix libffi build on AIX. - -- Issue #18259: Declare sethostname in socketmodule.c for AIX - -- Issue #18147: Add diagnostic functions to ssl.SSLContext(). get_ca_list() - lists all loaded CA certificates and cert_store_stats() returns amount of - loaded X.509 certs, X.509 CA certs and CRLs. - -- Issue #18167: cgi.FieldStorage no longer fails to handle multipart/form-data - when ``\r\n`` appears at end of 65535 bytes without other newlines. - -- Issue #18076: Introduce importlib.util.decode_source(). - -- Issue #18357: add tests for dictview set difference. - Patch by Fraser Tweedale. - -- importlib.abc.SourceLoader.get_source() no longer changes SyntaxError or - UnicodeDecodeError into ImportError. - -- Issue #18058, 18057: Make the namespace package loader meet the - importlib.abc.InspectLoader ABC, allowing for namespace packages to work with - runpy. - -- Issue #17177: The imp module is pending deprecation. - -- subprocess: Prevent a possible double close of parent pipe fds when the - subprocess exec runs into an error. Prevent a regular multi-close of the - /dev/null fd when any of stdin, stdout and stderr was set to DEVNULL. - -- Issue #18194: Introduce importlib.util.cache_from_source() and - source_from_cache() while documenting the equivalent functions in imp as - deprecated. - -- Issue #17907: Document imp.new_module() as deprecated in favour of - types.ModuleType. - -- Issue #18192: Introduce importlib.util.MAGIC_NUMBER and document as deprecated - imp.get_magic(). - -- Issue #18149: Add filecmp.clear_cache() to manually clear the filecmp cache. - Patch by Mark Levitt - -- Issue #18193: Add importlib.reload(). - -- Issue #18157: Stop using imp.load_module() in pydoc. - -- Issue #16102: Make uuid._netbios_getnode() work again on Python 3. - -- Issue #17134: Add ssl.enum_cert_store() as interface to Windows' cert store. - -- Issue #18143: Implement ssl.get_default_verify_paths() in order to debug - the default locations for cafile and capath. - -- Issue #17314: Move multiprocessing.forking over to importlib. - -- Issue #11959: SMTPServer and SMTPChannel now take an optional map, use of - which avoids affecting global state. - -- Issue #18109: os.uname() now decodes fields from the locale encoding, and - socket.gethostname() now decodes the hostname from the locale encoding, - instead of using the UTF-8 encoding in strict mode. - -- Issue #18089: Implement importlib.abc.InspectLoader.load_module. - -- Issue #18088: Introduce importlib.abc.Loader.init_module_attrs for setting - module attributes. Leads to the pending deprecation of - importlib.util.module_for_loader. - -- Issue #17403: urllib.parse.robotparser normalizes the urls before adding to - ruleline. This helps in handling certain types invalid urls in a conservative - manner. Patch contributed by Mher Movsisyan. - -- Issue #18070: Have importlib.util.module_for_loader() set attributes - unconditionally in order to properly support reloading. - -- Added importlib.util.module_to_load to return a context manager to provide the - proper module object to load. - -- Issue #18025: Fixed a segfault in io.BufferedIOBase.readinto() when raw - stream's read() returns more bytes than requested. - -- Issue #18011: As was originally intended, base64.b32decode() now raises a - binascii.Error if there are non-b32-alphabet characters present in the input - string, instead of a TypeError. - -- Issue #18072: Implement importlib.abc.InspectLoader.get_code() and - importlib.abc.ExecutionLoader.get_code(). - -- Issue #8240: Set the SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER flag on SSL - sockets. - -- Issue #17269: Workaround for socket.getaddrinfo crash on MacOS X - with port None or "0" and flags AI_NUMERICSERV. - -- Issue #16986: ElementTree now correctly works with string input when the - internal XML encoding is not UTF-8 or US-ASCII. - -- Issue #17996: socket module now exposes AF_LINK constant on BSD and OSX. - -- Issue #17900: Allowed pickling of recursive OrderedDicts. Decreased pickled - size and pickling time. - -- Issue #17914: Add os.cpu_count(). Patch by Yogesh Chaudhari, based on an - initial patch by Trent Nelson. - -- Issue #17812: Fixed quadratic complexity of base64.b32encode(). - Optimize base64.b32encode() and base64.b32decode() (speed up to 3x). - -- Issue #17980: Fix possible abuse of ssl.match_hostname() for denial of - service using certificates with many wildcards (CVE-2013-2099). - -- Issue #15758: Fix FileIO.readall() so it no longer has O(n**2) complexity. - -- Issue #14596: The struct.Struct() objects now use a more compact - implementation. - -- Issue #17981: logging's SysLogHandler now closes the socket when it catches - socket OSErrors. - -- Issue #17964: Fix os.sysconf(): the return type of the C sysconf() function - is long, not int. - -- Fix typos in the multiprocessing module. - -- Issue #17754: Make ctypes.util.find_library() independent of the locale. - -- Issue #17968: Fix memory leak in os.listxattr(). - -- Issue #17606: Fixed support of encoded byte strings in the XMLGenerator - characters() and ignorableWhitespace() methods. Original patch by Sebastian - Ortiz Vasquez. - -- Issue #17732: Ignore distutils.cfg options pertaining to install paths if a - virtual environment is active. - -- Issue #17915: Fix interoperability of xml.sax with file objects returned by - codecs.open(). - -- Issue #16601: Restarting iteration over tarfile really restarts rather - than continuing from where it left off. Patch by Michael Birtwell. - -- Issue #17289: The readline module now plays nicer with external modules - or applications changing the rl_completer_word_break_characters global - variable. Initial patch by Bradley Froehle. - -- Issue #12181: select module: Fix struct kevent definition on OpenBSD 64-bit - platforms. Patch by Federico Schwindt. - -- Issue #11816: multiple improvements to the dis module: get_instructions - generator, ability to redirect output to a file, Bytecode and Instruction - abstractions. Patch by Nick Coghlan, Ryan Kelly and Thomas Kluyver. - -- Issue #13831: Embed stringification of remote traceback in local - traceback raised when pool task raises an exception. - -- Issue #15528: Add weakref.finalize to support finalization using - weakref callbacks. - -- Issue #14173: Avoid crashing when reading a signal handler during - interpreter shutdown. - -- Issue #15902: Fix imp.load_module() accepting None as a file when loading an - extension module. - -- Issue #13721: SSLSocket.getpeercert() and SSLSocket.do_handshake() now - raise an OSError with ENOTCONN, instead of an AttributeError, when the - SSLSocket is not connected. - -- Issue #14679: add an __all__ (that contains only HTMLParser) to html.parser. - -- Issue #17802: Fix an UnboundLocalError in html.parser. Initial tests by - Thomas Barlow. - -- Issue #17358: Modules loaded by imp.load_source() and load_compiled() (and by - extention load_module()) now have a better chance of working when reloaded. - -- Issue #17804: New function ``struct.iter_unpack`` allows for streaming - struct unpacking. - -- Issue #17830: When keyword.py is used to update a keyword file, it now - preserves the line endings of the original file. - -- Issue #17272: Making the urllib.request's Request.full_url a descriptor. - Fixes bugs with assignment to full_url. Patch by Demian Brecht. - -- Issue #17353: Plistlib emitted empty data tags with deeply nested datastructures - -- Issue #11714: Use 'with' statements to assure a Semaphore releases a - condition variable. Original patch by Thomas Rachel. - -- Issue #16624: `subprocess.check_output` now accepts an `input` argument, - allowing the subprocess's stdin to be provided as a (byte) string. - Patch by Zack Weinberg. - -- Issue #17795: Reverted backwards-incompatible change in SysLogHandler with - Unix domain sockets. - -- Issue #16694: Add a pure Python implementation of the operator module. - Patch by Zachary Ware. - -- Issue #11182: remove the unused and undocumented pydoc.Scanner class. - Patch by Martin Morrison. - -- Issue #17741: Add ElementTree.XMLPullParser, an event-driven parser for - non-blocking applications. - -- Issue #17555: Fix ForkAwareThreadLock so that size of after fork - registry does not grow exponentially with generation of process. - -- Issue #17707: fix regression in multiprocessing.Queue's get() method where - it did not block for short timeouts. - -- Issue #17720: Fix the Python implementation of pickle.Unpickler to correctly - process the APPENDS opcode when it is used on non-list objects. - -- Issue #17012: shutil.which() no longer falls back to the PATH environment - variable if an empty path argument is specified. Patch by Serhiy Storchaka. - -- Issue #17710: Fix pickle raising a SystemError on bogus input. - -- Issue #17341: Include the invalid name in the error messages from re about - invalid group names. - -- Issue #17702: os.environ now raises KeyError with the original environment - variable name (str on UNIX), instead of using the encoded name (bytes on - UNIX). - -- Issue #16163: Make the importlib based version of pkgutil.iter_importers - work for submodules. Initial patch by Berker Peksag. - -- Issue #16804: Fix a bug in the 'site' module that caused running - 'python -S -m site' to incorrectly throw an exception. - -- Issue #15480: Remove the deprecated and unused TYPE_INT64 code from marshal. - Initial patch by Daniel Riti. - -- Issue #2118: SMTPException is now a subclass of OSError. - -- Issue #17016: Get rid of possible pointer wraparounds and integer overflows - in the re module. Patch by Nickolai Zeldovich. - -- Issue #16658: add missing return to HTTPConnection.send(). - Patch by Jeff Knupp. - -- Issue #9556: the logging package now allows specifying a time-of-day for a - TimedRotatingFileHandler to rotate. - -- Issue #14971: unittest test discovery no longer gets confused when a function - has a different __name__ than its name in the TestCase class dictionary. - -- Issue #17487: The wave getparams method now returns a namedtuple rather than - a plain tuple. - -- Issue #17675: socket repr() provides local and remote addresses (if any). - Patch by Giampaolo Rodola' - -- Issue #17093: Make the ABCs in importlib.abc provide default values or raise - reasonable exceptions for their methods to make them more amenable to super() - calls. - -- Issue #17566: Make importlib.abc.Loader.module_repr() optional instead of an - abstractmethod; now it raises NotImplementedError so as to be ignored by default. - -- Issue #17678: Remove the use of deprecated method in http/cookiejar.py by - changing the call to get_origin_req_host() to origin_req_host. - -- Issue #17666: Fix reading gzip files with an extra field. - -- Issue #16475: Support object instancing, recursion and interned strings - in marshal - -- Issue #17502: Process DEFAULT values in mock side_effect that returns iterator. - -- Issue #16795: On the ast.arguments object, unify vararg with varargannotation - and kwarg and kwargannotation. Change the column offset of ast.Attribute to be - at the attribute name. - -- Issue #17434: Properly raise a SyntaxError when a string occurs between future - imports. - -- Issue #17117: Import and @importlib.util.set_loader now set __loader__ when - it has a value of None or the attribute doesn't exist. - -- Issue #17032: The "global" in the "NameError: global name 'x' is not defined" - error message has been removed. Patch by Ram Rachum. - -- Issue #18080: When building a C extension module on OS X, if the compiler - is overriden with the CC environment variable, use the new compiler as - the default for linking if LDSHARED is not also overriden. This restores - Distutils behavior introduced in 3.2.3 and inadvertently dropped in 3.3.0. - -- Issue #18113: Fixed a refcount leak in the curses.panel module's - set_userptr() method. Reported by Atsuo Ishimoto. - -- Implement PEP 443 "Single-dispatch generic functions". - -- Implement PEP 435 "Adding an Enum type to the Python standard library". - -- Issue #15596: Faster pickling of unicode strings. - -- Issue #17572: Avoid chained exceptions when passing bad directives to - time.strptime(). Initial patch by Claudiu Popa. - -- Issue #17435: threading.Timer's __init__ method no longer uses mutable - default values for the args and kwargs parameters. - -- Issue #17526: fix an IndexError raised while passing code without filename to - inspect.findsource(). Initial patch by Tyler Doyle. - -- Issue #17540: Added style parameter to logging formatter configuration by dict. - -- Issue #16692: The ssl module now supports TLS 1.1 and TLS 1.2. Initial - patch by Michele Orrù. - -- Issue #17025: multiprocessing: Reduce Queue and SimpleQueue contention. - -- Issue #17536: Add to webbrowser's browser list: www-browser, x-www-browser, - iceweasel, iceape. - -- Issue #17150: pprint now uses line continuations to wrap long string - literals. - -- Issue #17488: Change the subprocess.Popen bufsize parameter default value - from unbuffered (0) to buffering (-1) to match the behavior existing code - expects and match the behavior of the subprocess module in Python 2 to avoid - introducing hard to track down bugs. - -- Issue #17521: Corrected non-enabling of logger following two calls to - fileConfig(). - -- Issue #17508: Corrected logging MemoryHandler configuration in dictConfig() - where the target handler wasn't configured first. - -- Issue #17209: curses.window.get_wch() now correctly handles KeyboardInterrupt - (CTRL+c). - -- Issue #5713: smtplib now handles 421 (closing connection) error codes when - sending mail by closing the socket and reporting the 421 error code via the - exception appropriate to the command that received the error response. - -- Issue #16997: unittest.TestCase now provides a subTest() context manager - to procedurally generate, in an easy way, small test instances. - -- Issue #17485: Also delete the Request Content-Length header if the data - attribute is deleted. (Follow on to issue Issue #16464). - -- Issue #15927: CVS now correctly parses escaped newlines and carriage - when parsing with quoting turned off. - -- Issue #17467: add readline and readlines support to mock_open in - unittest.mock. - -- Issue #13248: removed deprecated and undocumented difflib.isbjunk, - isbpopular. - -- Issue #17192: Update the ctypes module's libffi to v3.0.13. This - specifically addresses a stack misalignment issue on x86 and issues on - some more recent platforms. - -- Issue #8862: Fixed curses cleanup when getkey is interrputed by a signal. - -- Issue #17443: imaplib.IMAP4_stream was using the default unbuffered IO - in subprocess, but the imap code assumes buffered IO. In Python2 this - worked by accident. IMAP4_stream now explicitly uses buffered IO. - -- Issue #17476: Fixed regression relative to Python2 in undocumented pydoc - 'allmethods'; it was missing unbound methods on the class. - -- Issue #17474: Remove the deprecated methods of Request class. - -- Issue #16709: unittest discover order is no-longer filesystem specific. Patch - by Jeff Ramnani. - -- Use the HTTPS PyPI url for upload, overriding any plain HTTP URL in pypirc. - -- Issue #5024: sndhdr.whichhdr now returns the frame count for WAV files - rather than -1. - -- Issue #17460: Remove the strict argument of HTTPConnection and removing the - DeprecationWarning being issued from 3.2 onwards. - -- Issue #16880: Do not assume _imp.load_dynamic() is defined in the imp module. - -- Issue #16389: Fixed a performance regression relative to Python 3.1 in the - caching of compiled regular expressions. - -- Added missing FeedParser and BytesFeedParser to email.parser.__all__. - -- Issue #17431: Fix missing import of BytesFeedParser in email.parser. - -- Issue #12921: http.server's send_error takes an explain argument to send more - information in response. Patch contributed by Karl. - -- Issue #17414: Add timeit, repeat, and default_timer to timeit.__all__. - -- Issue #1285086: Get rid of the refcounting hack and speed up - urllib.parse.unquote() and urllib.parse.unquote_to_bytes(). - -- Issue #17099: Have importlib.find_loader() raise ValueError when __loader__ - is not set, harmonizing with what happens when the attribute is set to None. - -- Expose the O_PATH constant in the os module if it is available. - -- Issue #17368: Fix an off-by-one error in the Python JSON decoder that caused - a failure while decoding empty object literals when object_pairs_hook was - specified. - -- Issue #17385: Fix quadratic behavior in threading.Condition. The FIFO - queue now uses a deque instead of a list. - -- Issue #15806: Add contextlib.ignore(). This creates a context manager to - ignore specified exceptions, replacing the "except SomeException: pass" idiom. - -- Issue #14645: The email generator classes now produce output using the - specified linesep throughout. Previously if the prolog, epilog, or - body were stored with a different linesep, that linesep was used. This - fix corrects an RFC non-compliance issue with smtplib.send_message. - -- Issue #17278: Fix a crash in heapq.heappush() and heapq.heappop() when - the list is being resized concurrently. - -- Issue #16962: Use getdents64 instead of the obsolete getdents syscall - in the subprocess module on Linux. - -- Issue #16935: unittest now counts the module as skipped if it raises SkipTest, - instead of counting it as an error. Patch by Zachary Ware. - -- Issue #17018: Make Process.join() retry if os.waitpid() fails with EINTR. - -- Issue #17223: array module: Fix a crasher when converting an array containing - invalid characters (outside range [U+0000; U+10ffff]) to Unicode: - repr(array), str(array) and array.tounicode(). Patch written by Manuel Jacob. - -- Issue #17197: profile/cProfile modules refactored so that code of run() and - runctx() utility functions is not duplicated in both modules. - -- Issue #14720: sqlite3: Convert datetime microseconds correctly. - Patch by Lowe Thiderman. - -- Issue #15132: Allow a list for the defaultTest argument of - unittest.TestProgram. Patch by Jyrki Pulliainen. - -- Issue #17225: JSON decoder now counts columns in the first line starting - with 1, as in other lines. - -- Issue #6623: Added explicit DeprecationWarning for ftplib.netrc, which has - been deprecated and undocumented for a long time. - -- Issue #13700: Fix byte/string handling in imaplib authentication when an - authobject is specified. - -- Issue #13153: Tkinter functions now raise TclError instead of ValueError when - a string argument contains non-BMP character. - -- Issue #9669: Protect re against infinite loops on zero-width matching in - non-greedy repeat. Patch by Matthew Barnett. - -- Issue #13169: The maximal repetition number in a regular expression has been - increased from 65534 to 2147483647 (on 32-bit platform) or 4294967294 (on - 64-bit). - -- Issue #17143: Fix a missing import in the trace module. Initial patch by - Berker Peksag. - -- Issue #15220: email.feedparser's line splitting algorithm is now simpler and - faster. - -- Issue #16743: Fix mmap overflow check on 32 bit Windows. - -- Issue #16996: webbrowser module now uses shutil.which() to find a - web-browser on the executable search path. - -- Issue #16800: tempfile.gettempdir() no longer left temporary files when - the disk is full. Original patch by Amir Szekely. - -- Issue #17192: Import libffi-3.0.12. - -- Issue #16564: Fixed regression relative to Python2 in the operation of - email.encoders.encode_7or8bit when used with binary data. - -- Issue #17052: unittest discovery should use self.testLoader. - -- Issue #4591: Uid and gid values larger than 2**31 are supported now. - -- Issue #17141: random.vonmisesvariate() no longer hangs for large kappas. - -- Issue #17149: Fix random.vonmisesvariate to always return results in - [0, 2*math.pi]. - -- Issue #1470548: XMLGenerator now works with binary output streams. - -- Issue #6975: os.path.realpath() now correctly resolves multiple nested - symlinks on POSIX platforms. - -- Issue #13773: sqlite3.connect() gets a new `uri` parameter to pass the - filename as a URI, allowing to pass custom options. - -- Issue #16564: Fixed regression relative to Python2 in the operation of - email.encoders.encode_noop when used with binary data. - -- Issue #10355: The mode, name, encoding and newlines properties now work on - SpooledTemporaryFile objects even when they have not yet rolled over. - Obsolete method xreadline (which has never worked in Python 3) has been - removed. - -- Issue #16686: Fixed a lot of bugs in audioop module. Fixed crashes in - avgpp(), maxpp() and ratecv(). Fixed an integer overflow in add(), bias(), - and ratecv(). reverse(), lin2lin() and ratecv() no more lose precision for - 32-bit samples. max() and rms() no more returns a negative result and - various other functions now work correctly with 32-bit sample -0x80000000. - -- Issue #17073: Fix some integer overflows in sqlite3 module. - -- Issue #16723: httplib.HTTPResponse no longer marked closed when the connection - is automatically closed. - -- Issue #15359: Add CAN_BCM protocol support to the socket module. Patch by - Brian Thorne. - -- Issue #16948: Fix quoted printable body encoding for non-latin1 character - sets in the email package. - -- Issue #16811: Fix folding of headers with no value in the provisional email - policies. - -- Issue #17132: Update symbol for "yield from" grammar changes. - -- Issue #17076: Make copying of xattrs more tolerant of missing FS support. - Patch by Thomas Wouters. - -- Issue #17089: Expat parser now correctly works with string input when the - internal XML encoding is not UTF-8 or US-ASCII. It also now accepts bytes - and strings larger than 2 GiB. - -- Issue #6083: Fix multiple segmentation faults occured when PyArg_ParseTuple - parses nested mutating sequence. - -- Issue #5289: Fix ctypes.util.find_library on Solaris. - -- Issue #17106: Fix a segmentation fault in io.TextIOWrapper when an underlying - stream or a decoder produces data of an unexpected type (i.e. when - io.TextIOWrapper initialized with text stream or use bytes-to-bytes codec). - -- Issue #17015: When it has a spec, a Mock object now inspects its signature - when matching calls, so that arguments can be matched positionally or - by name. - -- Issue #15633: httplib.HTTPResponse is now mark closed when the server - sends less than the advertised Content-Length. - -- Issue #12268: The io module file object write methods no longer abort early - when one of its write system calls is interrupted (EINTR). - -- Issue #6972: The zipfile module no longer overwrites files outside of - its destination path when extracting malicious zip files. - -- Issue #4844: ZipFile now raises BadZipFile when opens a ZIP file with an - incomplete "End of Central Directory" record. Original patch by Guilherme - Polo and Alan McIntyre. - -- Issue #17071: Signature.bind() now works when one of the keyword arguments - is named ``self``. - -- Issue #12004: Fix an internal error in PyZipFile when writing an invalid - Python file. Patch by Ben Morgan. - -- Have py_compile use importlib as much as possible to avoid code duplication. - Code now raises FileExistsError if the file path to be used for the - byte-compiled file is a symlink or non-regular file as a warning that import - will not keep the file path type if it writes to that path. - -- Issue #16972: Have site.addpackage() consider already known paths even when - none are explicitly passed in. Bug report and fix by Kirill. - -- Issue #1602133: on Mac OS X a shared library build (``--enable-shared``) - now fills the ``os.environ`` variable correctly. - -- Issue #15505: `unittest.installHandler` no longer assumes SIGINT handler is - set to a callable object. - -- Issue #13454: Fix a crash when deleting an iterator created by itertools.tee() - if all other iterators were very advanced before. - -- Issue #12411: Fix to cgi.parse_multipart to correctly use bytes boundaries - and bytes data. Patch by Jonas Wagner. - -- Issue #16957: shutil.which() no longer searches a bare file name in the - current directory on Unix and no longer searches a relative file path with - a directory part in PATH directories. Patch by Thomas Kluyver. - -- Issue #1159051: GzipFile now raises EOFError when reading a corrupted file - with truncated header or footer. - -- Issue #16993: shutil.which() now preserves the case of the path and extension - on Windows. - -- Issue #16992: On Windows in signal.set_wakeup_fd, validate the file - descriptor argument. - -- Issue #16422: For compatibility with the Python version, the C version of - decimal now uses strings instead of integers for rounding mode constants. - -- Issue #15861: tkinter now correctly works with lists and tuples containing - strings with whitespaces, backslashes or unbalanced braces. - -- Issue #9720: zipfile now writes correct local headers for files larger than - 4 GiB. - -- Issue #16955: Fix the poll() method for multiprocessing's socket - connections on Windows. - -- SSLContext.load_dh_params() now properly closes the input file. - -- Issue #15031: Refactor some .pyc management code to cut down on code - duplication. Thanks to Ronan Lamy for the report and taking an initial stab - at the problem. - -- Issue #16398: Optimize deque.rotate() so that it only moves pointers - and doesn't touch the underlying data with increfs and decrefs. - -- Issue #16900: Issue a ResourceWarning when an ssl socket is left unclosed. - -- Issue #13899: ``\A``, ``\Z``, and ``\B`` now correctly match the A, Z, - and B literals when used inside character classes (e.g. ``'[\A]'``). - Patch by Matthew Barnett. - -- Issue #15545: Fix regression in sqlite3's iterdump method where it was - failing if the connection used a row factory (such as sqlite3.Row) that - produced unsortable objects. (Regression was introduced by fix for 9750). - -- fcntl: add F_DUPFD_CLOEXEC constant, available on Linux 2.6.24+. - -- Issue #15972: Fix error messages when os functions expecting a file name or - file descriptor receive the incorrect type. - -- Issue #8109: The ssl module now has support for server-side SNI, thanks - to a :meth:`SSLContext.set_servername_callback` method. Patch by Daniel - Black. - -- Issue #16860: In tempfile, use O_CLOEXEC when available to set the - close-on-exec flag atomically. - -- Issue #16674: random.getrandbits() is now 20-40% faster for small integers. - -- Issue #16009: JSON error messages now provide more information. - -- Issue #16828: Fix error incorrectly raised by bz2.compress(b'') and - bz2.BZ2Compressor.compress(b''). Initial patch by Martin Packman. - -- Issue #16833: In http.client.HTTPConnection, do not concatenate the request - headers and body when the payload exceeds 16 KB, since it can consume more - memory for no benefit. Patch by Benno Leslie. - -- Issue #16541: tk_setPalette() now works with keyword arguments. - -- Issue #16820: In configparser, `parser.popitem()` no longer raises ValueError. - This makes `parser.clean()` work correctly. - -- Issue #16820: In configparser, ``parser['section'] = {}`` now preserves - section order within the parser. This makes `parser.update()` preserve section - order as well. - -- Issue #16820: In configparser, ``parser['DEFAULT'] = {}`` now correctly - clears previous values stored in the default section. Same goes for - ``parser.update({'DEFAULT': {}})``. - -- Issue #9586: Redefine SEM_FAILED on MacOSX to keep compiler happy. - -- Issue #16787: Increase asyncore and asynchat default output buffers size, to - decrease CPU usage and increase throughput. - -- Issue #10527: make multiprocessing use poll() instead of select() if available. - -- Issue #16688: Now regexes contained backreferences correctly work with - non-ASCII strings. Patch by Matthew Barnett. - -- Issue #16486: Make aifc files act as context managers. - -- Issue #16485: Now file descriptors are closed if file header patching failed - on closing an aifc file. - -- Issue #16640: Run less code under a lock in sched module. - -- Issue #16165: sched.scheduler.run() no longer blocks a scheduler for other - threads. - -- Issue #16641: Default values of sched.scheduler.enter() are no longer - modifiable. - -- Issue #16618: Make glob.glob match consistently across strings and bytes - regarding leading dots. Patch by Serhiy Storchaka. - -- Issue #16788: Add samestat to Lib/ntpath.py - -- Issue #16713: Parsing of 'tel' urls using urlparse separates params from - path. - -- Issue #16443: Add docstrings to regular expression match objects. - Patch by Anton Kasyanov. - -- Issue #15701: Fix HTTPError info method call to return the headers information. - -- Issue #16752: Add a missing import to modulefinder. Patch by Berker Peksag. - -- Issue #16646: ftplib.FTP.makeport() might lose socket error details. - (patch by Serhiy Storchaka) - -- Issue #16626: Fix infinite recursion in glob.glob() on Windows when the - pattern contains a wildcard in the drive or UNC path. Patch by Serhiy - Storchaka. - -- Issue #15783: Except for the number methods, the C version of decimal now - supports all None default values present in decimal.py. These values were - largely undocumented. - -- Issue #11175: argparse.FileType now accepts encoding and errors - arguments. Patch by Lucas Maystre. - -- Issue #16488: epoll() objects now support the `with` statement. Patch - by Serhiy Storchaka. - -- Issue #16298: In HTTPResponse.read(), close the socket when there is no - Content-Length and the incoming stream is finished. Patch by Eran - Rundstein. - -- Issue #16049: Add abc.ABC class to enable the use of inheritance to create - ABCs, rather than the more cumbersome metaclass=ABCMeta. Patch by Bruno - Dupuis. - -- Expose the TCP_FASTOPEN and MSG_FASTOPEN flags in socket when they're - available. - -- Issue #15701: Add a .headers attribute to urllib.error.HTTPError. Patch - contributed by Berker Peksag. - -- Issue #15872: Fix 3.3 regression introduced by the new fd-based shutil.rmtree - that caused it to not ignore certain errors when ignore_errors was set. - Patch by Alessandro Moura and Serhiy Storchaka. - -- Issue #16248: Disable code execution from the user's home directory by - tkinter when the -E flag is passed to Python. Patch by Zachary Ware. - -- Issue #13390: New function :func:`sys.getallocatedblocks()` returns the - number of memory blocks currently allocated. - -- Issue #16628: Fix a memory leak in ctypes.resize(). - -- Issue #13614: Fix setup.py register failure with invalid rst in description. - Patch by Julien Courteau and Pierre Paul Lefebvre. - -- Issue #13512: Create ~/.pypirc securely (CVE-2011-4944). Initial patch by - Philip Jenvey, tested by Mageia and Debian. - -- Issue #7719: Make distutils ignore ``.nfs*`` files instead of choking later - on. Initial patch by SilentGhost and Jeff Ramnani. - -- Issue #13120: Allow to call pdb.set_trace() from thread. - Patch by Ilya Sandler. - -- Issue #16585: Make CJK encoders support error handlers that return bytes per - PEP 383. - -- Issue #10182: The re module doesn't truncate indices to 32 bits anymore. - Patch by Serhiy Storchaka. - -- Issue #16333: use (",", ": ") as default separator in json when indent is - specified, to avoid trailing whitespace. Patch by Serhiy Storchaka. - -- Issue #16573: In 2to3, treat enumerate() like a consuming call, so superfluous - list() calls aren't added to filter(), map(), and zip() which are directly - passed enumerate(). - -- Issue #16464: Reset the Content-Length header when a urllib Request is reused - with new data. - -- Issue #12848: The pure Python pickle implementation now treats object - lengths as unsigned 32-bit integers, like the C implementation does. - Patch by Serhiy Storchaka. - -- Issue #16423: urllib.request now has support for ``data:`` URLs. Patch by - Mathias Panzenböck. - -- Issue #4473: Add a POP3.stls() to switch a clear-text POP3 session into - an encrypted POP3 session, on supported servers. Patch by Lorenzo Catucci. - -- Issue #4473: Add a POP3.capa() method to query the capabilities advertised - by the POP3 server. Patch by Lorenzo Catucci. - -- Issue #4473: Ensure the socket is shutdown cleanly in POP3.close(). - Patch by Lorenzo Catucci. - -- Issue #16522: added FAIL_FAST flag to doctest. - -- Issue #15627: Add the importlib.abc.InspectLoader.source_to_code() method. - -- Issue #16408: Fix file descriptors not being closed in error conditions - in the zipfile module. Patch by Serhiy Storchaka. - -- Issue #14631: Add a new :class:`weakref.WeakMethod` to simulate weak - references to bound methods. - -- Issue #16469: Fix exceptions from float -> Fraction and Decimal -> Fraction - conversions for special values to be consistent with those for float -> int - and Decimal -> int. Patch by Alexey Kachayev. - -- Issue #16481: multiprocessing no longer leaks process handles on Windows. - -- Issue #12428: Add a pure Python implementation of functools.partial(). - Patch by Brian Thorne. - -- Issue #16140: The subprocess module no longer double closes its child - subprocess.PIPE parent file descriptors on child error prior to exec(). - -- Remove a bare print to stdout from the subprocess module that could have - happened if the child process wrote garbage to its pre-exec error pipe. - -- The subprocess module now raises its own SubprocessError instead of a - RuntimeError in various error situations which should not normally happen. - -- Issue #16327: The subprocess module no longer leaks file descriptors - used for stdin/stdout/stderr pipes to the child when fork() fails. - -- Issue #14396: Handle the odd rare case of waitpid returning 0 when not - expected in subprocess.Popen.wait(). - -- Issue #16411: Fix a bug where zlib.decompressobj().flush() might try to access - previously-freed memory. Patch by Serhiy Storchaka. - -- Issue #16357: fix calling accept() on a SSLSocket created through - SSLContext.wrap_socket(). Original patch by Jeff McNeil. - -- Issue #16409: The reporthook callback made by the legacy - urllib.request.urlretrieve API now properly supplies a constant non-zero - block_size as it did in Python 3.2 and 2.7. This matches the behavior of - urllib.request.URLopener.retrieve. - -- Issue #16431: Use the type information when constructing a Decimal subtype - from a Decimal argument. - -- Issue #15641: Clean up deprecated classes from importlib. - Patch by Taras Lyapun. - -- Issue #16350: zlib.decompressobj().decompress() now accumulates data from - successive calls after EOF in unused_data, instead of only saving the argument - to the last call. decompressobj().flush() now correctly sets unused_data and - unconsumed_tail. A bug in the handling of MemoryError when setting the - unconsumed_tail attribute has also been fixed. Patch by Serhiy Storchaka. - -- Issue #12759: sre_parse now raises a proper error when the name of the group - is missing. Initial patch by Serhiy Storchaka. - -- Issue #16152: fix tokenize to ignore whitespace at the end of the code when - no newline is found. Patch by Ned Batchelder. - -- Issue #16284: Prevent keeping unnecessary references to worker functions - in concurrent.futures ThreadPoolExecutor. - -- Issue #16230: Fix a crash in select.select() when one the lists changes - size while iterated on. Patch by Serhiy Storchaka. - -- Issue #16228: Fix a crash in the json module where a list changes size - while it is being encoded. Patch by Serhiy Storchaka. - -- Issue #16351: New function gc.get_stats() returns per-generation collection - statistics. - -- Issue #14897: Enhance error messages of struct.pack and - struct.pack_into. Patch by Matti Mäki. - -- Issue #16316: mimetypes now recognizes the .xz and .txz (.tar.xz) extensions. - Patch by Serhiy Storchaka. - -- Issue #12890: cgitb no longer prints spurious

tags in text - mode when the logdir option is specified. - -- Issue #16307: Fix multiprocessing.Pool.map_async not calling its callbacks. - Patch by Janne Karila. - -- Issue #16305: Fix a segmentation fault occurring when interrupting - math.factorial. - -- Issue #16116: Fix include and library paths to be correct when building C - extensions in venvs. - -- Issue #16245: Fix the value of a few entities in html.entities.html5. - -- Issue #16301: Fix the localhost verification in urllib/request.py for file:// - urls. - -- Issue #16250: Fix the invocations of URLError which had misplaced filename - attribute for exception. - -- Issue #10836: Fix exception raised when file not found in urlretrieve - Initial patch by Ezio Melotti. - -- Issue #14398: Fix size truncation and overflow bugs in the bz2 module. - -- Issue #12692: Fix resource leak in urllib.request when talking to an HTTP - server that does not include a ``Connection: close`` header in its responses. - -- Issue #12034: Fix bogus caching of result in check_GetFinalPathNameByHandle. - Patch by Atsuo Ishimoto. - -- Improve performance of `lzma.LZMAFile` (see also issue #16034). - -- Issue #16220: wsgiref now always calls close() on an iterable response. - Patch by Brent Tubbs. - -- Issue #16270: urllib may hang when used for retrieving files via FTP by using - a context manager. Patch by Giampaolo Rodola'. - -- Issue #16461: Wave library should be able to deal with 4GB wav files, - and sample rate of 44100 Hz. - -- Issue #16176: Properly identify Windows 8 via platform.platform() - -- Issue #16088: BaseHTTPRequestHandler's send_error method includes a - Content-Length header in it's response now. Patch by Antoine Pitrou. - -- Issue #16114: The subprocess module no longer provides a misleading error - message stating that args[0] did not exist when either the cwd or executable - keyword arguments specified a path that did not exist. - -- Issue #16169: Fix ctypes.WinError()'s confusion between errno and winerror. - -- Issue #16110: logging.fileConfig now accepts a pre-initialised ConfigParser - instance. - -- Issue #1492704: shutil.copyfile() raises a distinct SameFileError now if - source and destination are the same file. Patch by Atsuo Ishimoto. - -- Issue #13896: Make shelf instances work with 'with' as context managers. - Original patch by Filip Gruszczyński. - -- Issue #15417: Add support for csh and fish in venv activation scripts. - -- Issue #14377: ElementTree.write and some of the module-level functions have - a new parameter - *short_empty_elements*. It controls how elements with no - contents are emitted. - -- Issue #16089: Allow ElementTree.TreeBuilder to work again with a non-Element - element_factory (fixes a regression in SimpleTAL). - -- Issue #9650: List commonly used format codes in time.strftime and - time.strptime docsttings. Original patch by Mike Hoy. - -- Issue #15452: logging configuration socket listener now has a verify option - that allows an application to apply a verification function to the - received configuration data before it is acted upon. - -- Issue #16034: Fix performance regressions in the new `bz2.BZ2File` - implementation. Initial patch by Serhiy Storchaka. - -- `pty.spawn()` now returns the child process status returned by `os.waitpid()`. - -- Issue #15756: `subprocess.poll()` now properly handles `errno.ECHILD` to - return a returncode of 0 when the child has already exited or cannot be waited - on. - -- Issue #15323: Improve failure message of `Mock.assert_called_once_with()`. - -- Issue #16064: ``unittest -m`` claims executable is "python", not "python3". - -- Issue #12376: Pass on parameters in `TextTestResult.__init__()` super call. - -- Issue #15222: Insert blank line after each message in mbox mailboxes. - -- Issue #16013: Fix `csv.Reader` parsing issue with ending quote characters. - Patch by Serhiy Storchaka. - -- Issue #15421: Fix an OverflowError in `Calendar.itermonthdates()` after - `datetime.MAXYEAR`. Patch by Cédric Krier. - -- Issue #16112: platform.architecture does not correctly escape argument to - /usr/bin/file. Patch by David Benjamin. - -- Issue #15970: `xml.etree.ElementTree` now serializes correctly the empty HTML - elements 'meta' and 'param'. - -- Issue #15842: The `SocketIO.{readable,writable,seekable}` methods now raise - ValueError when the file-like object is closed. Patch by Alessandro Moura. - -- Issue #15876: Fix a refleak in the `curses` module: window.encoding. - -- Issue #15881: Fix `atexit` hook in `multiprocessing`. Original patch by Chris - McDonough. - -- Issue #15841: The readable(), writable() and seekable() methods of - `io.BytesIO` and `io.StringIO` objects now raise ValueError when the object - has been closed. Patch by Alessandro Moura. - -- Issue #15447: Use `subprocess.DEVNULL` in webbrowser, instead of opening - `os.devnull` explicitly and leaving it open. - -- Issue #15509: `webbrowser.UnixBrowser` no longer passes empty arguments to - Popen when ``%action`` substitutions produce empty strings. - -- Issue #12776, issue #11839: Call `argparse` type function (specified by - add_argument) only once. Before, the type function was called twice in the - case where the default was specified and the argument was given as well. This - was especially problematic for the FileType type, as a default file would - always be opened, even if a file argument was specified on the command line. - -- Issue #15906: Fix a regression in argparse caused by the preceding change, - when ``action='append'``, ``type='str'`` and ``default=[]``. - -- Issue #16113: Added sha3 module based on the Keccak reference implementation - 3.2. The `hashlib` module has four additional hash algorithms: `sha3_224`, - `sha3_256`, `sha3_384` and `sha3_512`. As part of the patch some common - code was moved from _hashopenssl.c to hashlib.h. - -- ctypes.call_commethod was removed, since its only usage was in the defunct - samples directory. - -- Issue #16692: Added TLSv1.1 and TLSv1.2 support for the ssl modules. - -- Issue #16832: add abc.get_cache_token() to expose cache validity checking - support in ABCMeta. - -IDLE ----- - -- Issue #18429: Format / Format Paragraph, now works when comment blocks - are selected. As with text blocks, this works best when the selection - only includes complete lines. - -- Issue #18226: Add docstrings and unittests for FormatParagraph.py. - Original patches by Todd Rovito and Phil Webster. - -- Issue #18279: Format - Strip trailing whitespace no longer marks a file as - changed when it has not been changed. This fix followed the addition of a - test file originally written by Phil Webster (the issue's main goal). - -- Issue #7136: In the Idle File menu, "New Window" is renamed "New File". - Patch by Tal Einat, Roget Serwy, and Todd Rovito. - -- Remove dead imports of imp. - -- Issue #18196: Avoid displaying spurious SystemExit tracebacks. - -- Issue #5492: Avoid traceback when exiting IDLE caused by a race condition. - -- Issue #17511: Keep IDLE find dialog open after clicking "Find Next". - Original patch by Sarah K. - -- Issue #18055: Move IDLE off of imp and on to importlib. - -- Issue #15392: Create a unittest framework for IDLE. - Initial patch by Rajagopalasarma Jayakrishnan. - See Lib/idlelib/idle_test/README.txt for how to run Idle tests. - -- Issue #14146: Highlight source line while debugging on Windows. - -- Issue #17838: Allow sys.stdin to be reassigned. - -- Issue #13495: Avoid loading the color delegator twice in IDLE. - -- Issue #17798: Allow IDLE to edit new files when specified on command line. - -- Issue #14735: Update IDLE docs to omit "Control-z on Windows". - -- Issue #17532: Always include Options menu for IDLE on OS X. - Patch by Guilherme Simões. - -- Issue #17585: Fixed IDLE regression. Now closes when using exit() or quit(). - -- Issue #17657: Show full Tk version in IDLE's about dialog. - Patch by Todd Rovito. - -- Issue #17613: Prevent traceback when removing syntax colorizer in IDLE. - -- Issue #1207589: Backwards-compatibility patch for right-click menu in IDLE. - -- Issue #16887: IDLE now accepts Cancel in tabify/untabify dialog box. - -- Issue #17625: In IDLE, close the replace dialog after it is used. - -- Issue #14254: IDLE now handles readline correctly across shell restarts. - -- Issue #17614: IDLE no longer raises exception when quickly closing a file. - -- Issue #6698: IDLE now opens just an editor window when configured to do so. - -- Issue #8900: Using keyboard shortcuts in IDLE to open a file no longer - raises an exception. - -- Issue #6649: Fixed missing exit status in IDLE. Patch by Guilherme Polo. - -- Issue #17114: IDLE now uses non-strict config parser. - -- Issue #9290: In IDLE the sys.std* streams now implement io.TextIOBase - interface and support all mandatory methods and properties. - -- Issue #5066: Update IDLE docs. Patch by Todd Rovito. - -- Issue #16829: IDLE printing no longer fails if there are spaces or other - special characters in the file path. - -- Issue #16491: IDLE now prints chained exception tracebacks. - -- Issue #16819: IDLE method completion now correctly works for bytes literals. - -- Issue #16504: IDLE now catches SyntaxErrors raised by tokenizer. Patch by - Roger Serwy. - -- Issue #16511: Use default IDLE width and height if config param is not valid. - Patch Serhiy Storchaka. - -- Issue #1207589: Add Cut/Copy/Paste items to IDLE right click Context Menu. - Patch by Todd Rovito. - -- Issue #16123: IDLE - deprecate running without a subprocess. - Patch by Roger Serwy. - -Tests ------ - -- Issue #1666318: Add a test that shutil.copytree() retains directory - permissions. Patch by Catherine Devlin. - -- Issue #18273: move the tests in Lib/test/json_tests to Lib/test/test_json - and make them discoverable by unittest. Patch by Zachary Ware. - -- Fix a fcntl test case on KFreeBSD, Debian #708653 (Petr Salinger). - -- Issue #18396: Fix spurious test failure in test_signal on Windows when - faulthandler is enabled (Patch by Jeremy Kloth) - -- Issue #17046: Fix broken test_executable_without_cwd in test_subprocess. - -- Issue #15415: Add new temp_dir() and change_cwd() context managers to - test.support, and refactor temp_cwd() to use them. Patch by Chris Jerdonek. - -- Issue #15494: test.support is now a package rather than a module (Initial - patch by Indra Talip) - -- Issue #17944: test_zipfile now discoverable and uses subclassing to - generate tests for different compression types. Fixed a bug with skipping - some tests due to use of exhausted iterators. - -- Issue #18266: test_largefile now works with unittest test discovery and - supports running only selected tests. Patch by Zachary Ware. - -- Issue #17767: test_locale now works with unittest test discovery. - Original patch by Zachary Ware. - -- Issue #18375: Assume --randomize when --randseed is used for running the - testsuite. - -- Issue #11185: Fix test_wait4 under AIX. Patch by Sébastien Sablé. - -- Issue #18207: Fix test_ssl for some versions of OpenSSL that ignore seconds - in ASN1_TIME fields. - -- Issue #18094: test_uuid no longer reports skipped tests as passed. - -- Issue #17992: Add timeouts to asyncore and asynchat tests so that they won't - accidentally hang. - -- Issue #17833: Fix test_gdb failures seen on machines where debug symbols - for glibc are available (seen on PPC64 Linux). - -- Issue #7855: Add tests for ctypes/winreg for issues found in IronPython. - Initial patch by Dino Viehland. - -- Issue #11078: test___all__ now checks for duplicates in __all__. - Initial patch by R. David Murray. - -- Issue #17712: Fix test_gdb failures on Ubuntu 13.04. - -- Issue #17835: Fix test_io when the default OS pipe buffer size is larger - than one million bytes. - -- Issue #17065: Use process-unique key for winreg tests to avoid failures if - test is run multiple times in parallel (eg: on a buildbot host). - -- Issue #12820: add tests for the xml.dom.minicompat module. - Patch by John Chandler and Phil Connell. - -- Issue #17691: test_univnewlines now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17790: test_set now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17789: test_random now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17779: test_osx_env now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17766: test_iterlen now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17690: test_time now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17692: test_sqlite now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #11995: test_pydoc doesn't import all sys.path modules anymore. - -- Issue #17448: test_sax now skips if there are no xml parsers available - instead of raising an ImportError. - -- Issue #11420: make test suite pass with -B/DONTWRITEBYTECODE set. - Initial patch by Thomas Wouters. - -- Issue #10652: make tcl/tk tests run after __all__ test, patch by - Zachary Ware. - -- Issue #11963: remove human verification from test_parser and test_subprocess. - -- Issue #11732: add a new suppress_crash_popup() context manager to test.support - that disables crash popups on Windows and use it in test_faulthandler and - test_capi. - -- Issue #13898: test_ssl no longer prints a spurious stack trace on Ubuntu. - -- Issue #17283: Share code between `__main__.py` and `regrtest.py` in - `Lib/test`. - -- Issue #17249: convert a test in test_capi to use unittest and reap threads. - -- Issue #17107: Test client-side SNI support in urllib.request thanks to - the new server-side SNI support in the ssl module. Initial patch by - Daniel Black. - -- Issue #17041: Fix testing when Python is configured with the - --without-doc-strings. - -- Issue #16923: Fix ResourceWarnings in test_ssl. - -- Issue #15539: Added regression tests for Tools/scripts/pindent.py. - -- Issue #17479: test_io now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17066: test_robotparser now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17334: test_index now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17333: test_imaplib now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17082: test_dbm* now work with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17079: test_ctypes now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17304: test_hash now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17303: test_future* now work with unittest test discovery. - Patch by Zachary Ware. - -- Issue #17163: test_file now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #16925: test_configparser now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #16918: test_codecs now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #16919: test_crypt now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #16910: test_bytes, test_unicode, and test_userstring now work with - unittest test discovery. Patch by Zachary Ware. - -- Issue #16905: test_warnings now works with unittest test discovery. - Initial patch by Berker Peksag. - -- Issue #16898: test_bufio now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #16888: test_array now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #16896: test_asyncore now works with unittest test discovery. - Patch by Zachary Ware. - -- Issue #16897: test_bisect now works with unittest test discovery. - Initial patch by Zachary Ware. - -- Issue #16852: test_genericpath, test_posixpath, test_ntpath, and test_macpath - now work with unittest test discovery. Patch by Zachary Ware. - -- Issue #16748: test_heapq now works with unittest test discovery. - -- Issue #10646: Tests rearranged for os.samefile/samestat to check for not - just symlinks but also hard links. - -- Issue #15302: Switch regrtest from using getopt to using argparse. - -- Issue #15324: Fix regrtest parsing of --fromfile, --match, and --randomize - options. - -- Issue #16702: test_urllib2_localnet tests now correctly ignores proxies for - localhost tests. - -- Issue #16664: Add regression tests for glob's behaviour concerning entries - starting with a ".". Patch by Sebastian Kreft. - -- Issue #13390: The ``-R`` option to regrtest now also checks for memory - allocation leaks, using :func:`sys.getallocatedblocks()`. - -- Issue #16559: Add more tests for the json module, including some from the - official test suite at json.org. Patch by Serhiy Storchaka. - -- Issue #16661: Fix the `os.getgrouplist()` test by not assuming that it gives - the same output as :command:`id -G`. - -- Issue #16115: Add some tests for the executable argument to - subprocess.Popen(). Initial patch by Kushal Das. - -- Issue #16126: PyErr_Format format mismatch in _testcapimodule.c. - Patch by Serhiy Storchaka. - -- Issue #15304: Fix warning message when `os.chdir()` fails inside - `test.support.temp_cwd()`. Patch by Chris Jerdonek. - -- Issue #15802: Fix test logic in `TestMaildir.test_create_tmp()`. Patch by - Serhiy Storchaka. - -- Issue #15557: Added a test suite for the webbrowser module, thanks to Anton - Barkovsky. - -- Issue #16698: Skip posix test_getgroups when built with OS X - deployment target prior to 10.6. - -Build ------ - -- Issue #16067: Add description into MSI file to replace installer's - temporary name. - -- Issue #18257: Fix readlink usage in python-config. Install the python - version again on Darwin. - -- Issue #18481: Add C coverage reporting with gcov and lcov. A new make target - "coverage-report" creates an instrumented Python build, runs unit tests - and creates a HTML. The report can be updated with "make coverage-lcov". - -- Issue #17845: Clarified the message printed when some module are not built. - -- Issue #18256: Compilation fix for recent AIX releases. Patch by - David Edelsohn. - -- Issue #17547: In configure, explicitly pass -Wformat for the benefit for GCC - 4.8. - -- Issue #15172: Document NASM 2.10+ as requirement for building OpenSSL 1.0.1 - on Windows. - -- Issue #17591: Use lowercase filenames when including Windows header files. - Patch by Roumen Petrov. - -- Issue #17550: Fix the --enable-profiling configure switch. - -- Issue #17425: Build with openssl 1.0.1d on Windows. - -- Issue #16754: Fix the incorrect shared library extension on linux. Introduce - two makefile macros SHLIB_SUFFIX and EXT_SUFFIX. SO now has the value of - SHLIB_SUFFIX again (as in 2.x and 3.1). The SO macro is removed in 3.4. - -- Issue #5033: Fix building of the sqlite3 extension module when the - SQLite library version has "beta" in it. Patch by Andreas Pelme. - -- Issue #17228: Fix building without pymalloc. - -- Issue #3718: Use AC_ARG_VAR to set MACHDEP in configure.ac. - -- Issue #16235: Implement python-config as a shell script. - -- Issue #16769: Remove outdated Visual Studio projects. - -- Issue #17031: Fix running regen in cross builds. - -- Issue #3754: fix typo in pthread AC_CACHE_VAL. - -- Issue #15484: Fix _PYTHON_PROJECT_BASE for srcdir != builddir builds; - use _PYTHON_PROJECT_BASE in distutils/sysconfig.py. - -- Drop support for Windows 2000 (changeset e52df05b496a). - -- Issue #17029: Let h2py search the multiarch system include directory. - -- Issue #16953: Fix socket module compilation on platforms with - HAVE_BROKEN_POLL. Patch by Jeffrey Armstrong. - -- Issue #16320: Remove redundant Makefile dependencies for strings and bytes. - -- Cross compiling needs host and build settings. configure no longer - creates a broken PYTHON_FOR_BUILD variable when --build is missing. - -- Fix cross compiling issue in setup.py, ensure that lib_dirs and inc_dirs are - defined in cross compiling mode, too. - -- Issue #16836: Enable IPv6 support even if IPv6 is disabled on the build host. - -- Issue #16593: Have BSD 'make -s' do the right thing, thanks to Daniel Shahaf - -- Issue #16262: fix out-of-src-tree builds, if mercurial is not installed. - -- Issue #15298: ensure _sysconfigdata is generated in build directory, not - source directory. - -- Issue #15833: Fix a regression in 3.3 that resulted in exceptions being - raised if importlib failed to write byte-compiled files. This affected - attempts to build Python out-of-tree from a read-only source directory. - -- Issue #15923: Fix a mistake in ``asdl_c.py`` that resulted in a TypeError - after 2801bf875a24 (see #15801). - -- Issue #16135: Remove OS/2 support. - -- Issue #15819: Make sure we can build Python out-of-tree from a read-only - source directory. (Somewhat related to issue #9860.) - -- Issue #15587: Enable Tk high-resolution text rendering on Macs with - Retina displays. Applies to Tkinter apps, such as IDLE, on OS X - framework builds linked with Cocoa Tk 8.5. - -- Issue #17161: make install now also installs a python3 man page. - -C-API ------ - -- Issue #18351: Fix various issues in a function in importlib provided to help - PyImport_ExecCodeModuleWithPathnames() (and thus by extension - PyImport_ExecCodeModule() and PyImport_ExecCodeModuleEx()). - -- Issue #9369: The types of `char*` arguments of PyObject_CallFunction() and - PyObject_CallMethod() now changed to `const char*`. Based on patches by - Jörg Müller and Lars Buitinck. - -- Issue #17206: Py_CLEAR(), Py_DECREF(), Py_XINCREF() and Py_XDECREF() now - expand their arguments once instead of multiple times. Patch written by Illia - Polosukhin. - -- Issue #17522: Add the PyGILState_Check() API. - -- Issue #17327: Add PyDict_SetDefault. - -- Issue #16881: Fix Py_ARRAY_LENGTH macro for GCC < 3.1. - -- Issue #16505: Remove unused Py_TPFLAGS_INT_SUBCLASS. - -- Issue #16086: PyTypeObject.tp_flags and PyType_Spec.flags are now unsigned - (unsigned long and unsigned int) to avoid an undefined behaviour with - Py_TPFLAGS_TYPE_SUBCLASS ((1 << 31). PyType_GetFlags() result type is - now unsigned too (unsigned long, instead of long). - -- Issue #16166: Add PY_LITTLE_ENDIAN and PY_BIG_ENDIAN macros and unified - endianness detection and handling. - -Documentation -------------- - -- Issue #17701: Improving strftime documentation. - -- Issue #18440: Clarify that `hash()` can truncate the value returned from an - object's custom `__hash__()` method. - -- Issue #17844: Add links to encoders and decoders for bytes-to-bytes codecs. - -- Issue #14097: improve the "introduction" page of the tutorial. - -- Issue #17977: The documentation for the cadefault argument's default value - in urllib.request.urlopen() is fixed to match the code. - -- Issue #6696: add documentation for the Profile objects, and improve - profile/cProfile docs. Patch by Tom Pinckney. - -- Issue #15940: Specify effect of locale on time functions. - -- Issue #17538: Document XML vulnerabilties - -- Issue #16642: sched.scheduler timefunc initial default is time.monotonic. - Patch by Ramchandra Apte - -- Issue #17047: remove doubled words in docs and docstrings - reported by Serhiy Storchaka and Matthew Barnett. - -- Issue #15465: Document the versioning macros in the C API docs rather than - the standard library docs. Patch by Kushal Das. - -- Issue #16406: Combine the pages for uploading and registering to PyPI. - -- Issue #16403: Document how distutils uses the maintainer field in - PKG-INFO. Patch by Jyrki Pulliainen. - -- Issue #16695: Document how glob handles filenames starting with a - dot. Initial patch by Jyrki Pulliainen. - -- Issue #8890: Stop advertising an insecure practice by replacing uses - of the /tmp directory with better alternatives in the documentation. - Patch by Geoff Wilson. - -- Issue #17203: add long option names to unittest discovery docs. - -- Issue #13094: add "Why do lambdas defined in a loop with different values - all return the same result?" programming FAQ. - -- Issue #14901: Update portions of the Windows FAQ. - Patch by Ashish Nitin Patil. - -- Issue #16267: Better document the 3.3+ approach to combining - @abstractmethod with @staticmethod, @classmethod and @property - -- Issue #15209: Clarify exception chaining description in exceptions module - documentation - -- Issue #15990: Improve argument/parameter documentation. - -- Issue #16209: Move the documentation for the str built-in function to a new - str class entry in the "Text Sequence Type" section. - -- Issue #13538: Improve str() and object.__str__() documentation. - -- Issue #16489: Make it clearer that importlib.find_loader() needs parent - packages to be explicitly imported. - -- Issue #16400: Update the description of which versions of a given package - PyPI displays. - -- Issue #15677: Document that zlib and gzip accept a compression level of 0 to - mean 'no compression'. Patch by Brian Brazil. - -- Issue #16197: Update winreg docstrings and documentation to match code. - Patch by Zachary Ware. - -- Issue #8040: added a version switcher to the documentation. Patch by - Yury Selivanov. - -- Issue #16241: Document -X faulthandler command line option. - Patch by Marek Šuppa. - -- Additional comments and some style changes in the concurrent.futures URL - retrieval example - -- Issue #16115: Improve subprocess.Popen() documentation around args, shell, - and executable arguments. - -- Issue #13498: Clarify docs of os.makedirs()'s exist_ok argument. Done with - great native-speaker help from R. David Murray. - -- Issue #15533: Clarify docs and add tests for `subprocess.Popen()`'s cwd - argument. - -- Issue #15979: Improve timeit documentation. - -- Issue #16036: Improve documentation of built-in `int()`'s signature and - arguments. - -- Issue #15935: Clarification of `argparse` docs, re: add_argument() type and - default arguments. Patch contributed by Chris Jerdonek. - -- Issue #11964: Document a change in v3.2 to the behavior of the indent - parameter of json encoding operations. - -- Issue #15116: Remove references to appscript as it is no longer being - supported. - -Tools/Demos ------------ - -- Issue #18817: Fix a resource warning in Lib/aifc.py demo. Patch by - Vajrasky Kok. - -- Issue #18439: Make patchcheck work on Windows for ACKS, NEWS. - -- Issue #18448: Fix a typo in Tools/demo/eiffel.py. - -- Issue #18457: Fixed saving of formulas and complex numbers in - Tools/demo/ss1.py. - -- Issue #18449: Make Tools/demo/ss1.py work again on Python 3. Patch by - Févry Thibault. - -- Issue #12990: The "Python Launcher" on OSX could not launch python scripts - that have paths that include wide characters. - -- Issue #15239: Make mkstringprep.py work again on Python 3. - -- Issue #17028: Allowed Python arguments to be supplied to the Windows - launcher. - -- Issue #17156: pygettext.py now detects the encoding of source files and - correctly writes and escapes non-ascii characters. - -- Issue #15539: Fix a number of bugs in Tools/scripts/pindent.py. Now - pindent.py works with a "with" statement. pindent.py no longer produces - improper indentation. pindent.py now works with continued lines broken after - "class" or "def" keywords and with continuations at the start of line. - -- Issue #11797: Add a 2to3 fixer that maps reload() to imp.reload(). - -- Issue #10966: Remove the concept of unexpected skipped tests. - -- Issue #9893: Removed the Misc/Vim directory. - -- Removed the Misc/TextMate directory. - -- Issue #16245: Add the Tools/scripts/parse_html5_entities.py script to parse - the list of HTML5 entities and update the html.entities.html5 dictionary. - -- Issue #15378: Fix Tools/unicode/comparecodecs.py. Patch by Serhiy Storchaka. - -- Issue #16549: Make json.tool work again on Python 3 and add tests. - Initial patch by Berker Peksag and Serhiy Storchaka. - -- Issue #13301: use ast.literal_eval() instead of eval() in Tools/i18n/msgfmt.py. - Patch by Serhiy Storchaka. - -Windows -------- - -- Issue #18569: The installer now adds .py to the PATHEXT variable when extensions - are registered. Patch by Paul Moore. - - -What's New in Python 3.3.0? -=========================== - -*Release date: 29-Sep-2012* - -Core and Builtins ------------------ - -- Issue #16046: Fix loading sourceless legacy .pyo files. - -- Issue #16060: Fix refcounting bug when `__trunc__()` returns an object whose - `__int__()` gives a non-integer. Patch by Serhiy Storchaka. - -Extension Modules ------------------ - -- Issue #16012: Fix a regression in pyexpat. The parser's `UseForeignDTD()` - method doesn't require an argument again. - - -What's New in Python 3.3.0 Release Candidate 3? -=============================================== - -*Release date: 23-Sep-2012* - -Core and Builtins ------------------ - -- Issue #15900: Fix reference leak in `PyUnicode_TranslateCharmap()`. - -- Issue #15926: Fix crash after multiple reinitializations of the interpreter. - -- Issue #15895: Fix FILE pointer leak in one error branch of - `PyRun_SimpleFileExFlags()` when filename points to a pyc/pyo file, closeit is - false an and set_main_loader() fails. - -- Fixes for a few crash and memory leak regressions found by Coverity. - -Library -------- - -- Issue #15882: Change `_decimal` to accept any coefficient tuple when - constructing infinities. This is done for backwards compatibility with - decimal.py: Infinity coefficients are undefined in _decimal (in accordance - with the specification). - -- Issue #15925: Fix a regression in `email.util` where the `parsedate()` and - `parsedate_tz()` functions did not return None anymore when the argument could - not be parsed. - -Extension Modules ------------------ - -- Issue #15973: Fix a segmentation fault when comparing datetime timezone - objects. - -- Issue #15977: Fix memory leak in Modules/_ssl.c when the function - _set_npn_protocols() is called multiple times, thanks to Daniel Sommermann. - -- Issue #15969: `faulthandler` module: rename dump_tracebacks_later() to - dump_traceback_later() and cancel_dump_tracebacks_later() to - cancel_dump_traceback_later(). - -- _decimal module: use only C 89 style comments. - - -What's New in Python 3.3.0 Release Candidate 2? -=============================================== - -*Release date: 09-Sep-2012* - -Core and Builtins ------------------ - -- Issue #13992: The trashcan mechanism is now thread-safe. This eliminates - sporadic crashes in multi-thread programs when several long deallocator chains - ran concurrently and involved subclasses of built-in container types. - -- Issue #15784: Modify `OSError`.__str__() to better distinguish between errno - error numbers and Windows error numbers. - -- Issue #15781: Fix two small race conditions in import's module locking. - -Library -------- - -- Issue #17158: Add 'symbols' to help() welcome message; clarify - 'modules spam' messages. - -- Issue #15847: Fix a regression in argparse, which did not accept tuples as - argument lists anymore. - -- Issue #15828: Restore support for C extensions in `imp.load_module()`. - -- Issue #15340: Fix importing the random module when ``/dev/urandom`` cannot be - opened. This was a regression caused by the hash randomization patch. - -- Issue #10650: Deprecate the watchexp parameter of the `Decimal.quantize()` - method. - -- Issue #15785: Modify `window.get_wch()` API of the curses module: return a - character for most keys, and an integer for special keys, instead of always - returning an integer. So it is now possible to distinguish special keys like - keypad keys. - -- Issue #14223: Fix `window.addch()` of the curses module for special characters - like curses.ACS_HLINE: the Python function addch(int) and addch(bytes) is now - calling the C function waddch()/mvwaddch() (as it was done in Python 3.2), - instead of wadd_wch()/mvwadd_wch(). The Python function addch(str) is still - calling the C function wadd_wch()/mvwadd_wch() if the Python curses is linked - to libncursesw. - -Build ------ - -- Issue #15822: Really ensure 2to3 grammar pickles are properly installed - (replaces fixes for Issue #15645). - -Documentation -------------- - -- Issue #15814: The memoryview enhancements in 3.3.0 accidentally permitted the - hashing of multi-dimensional memorviews and memoryviews with multi-byte item - formats. The intended restrictions have now been documented - they will be - correctly enforced in 3.3.1. - - -What's New in Python 3.3.0 Release Candidate 1? -=============================================== - -*Release date: 25-Aug-2012* - -Core and Builtins ------------------ - -- Issue #15573: memoryview comparisons are now performed by value with full - support for any valid struct module format definition. - -- Issue #15316: When an item in the fromlist for `__import__()` doesn't exist, - don't raise an error, but if an exception is raised as part of an import do - let that propagate. - -- Issue #15778: Ensure that ``str(ImportError(msg))`` returns a str even when - msg isn't a str. - -- Issue #2051: Source file permission bits are once again correctly copied to - the cached bytecode file. (The migration to importlib reintroduced this - problem because these was no regression test. A test has been added as part of - this patch) - -- Issue #15761: Fix crash when ``PYTHONEXECUTABLE`` is set on Mac OS X. - -- Issue #15726: Fix incorrect bounds checking in PyState_FindModule. Patch by - Robin Schreiber. - -- Issue #15604: Update uses of `PyObject_IsTrue()` to check for and handle - errors correctly. Patch by Serhiy Storchaka. - -- Issue #14846: `importlib.FileFinder` now handles the case where the directory - being searched is removed after a previous import attempt. - -Library -------- - -- Issue #13370: Ensure that ctypes works on Mac OS X when Python is compiled - using the clang compiler. - -- Issue #13072: The array module's 'u' format code is now deprecated and will be - removed in Python 4.0. - -- Issue #15544: Fix Decimal.__float__ to work with payload-carrying NaNs. - -- Issue #15776: Allow pyvenv to work in existing directory with --clean. - -- Issue #15249: email's BytesGenerator now correctly mangles From lines (when - requested) even if the body contains undecodable bytes. - -- Issue #15777: Fix a refleak in _posixsubprocess. - -- Issue ##665194: Update `email.utils.localtime` to use datetime.astimezone and - correctly handle historic changes in UTC offsets. - -- Issue #15199: Fix JavaScript's default MIME type to application/javascript. - Patch by Bohuslav Kabrda. - -- Issue #12643: `code.InteractiveConsole` now respects `sys.excepthook` when - displaying exceptions. Patch by Aaron Iles. - -- Issue #13579: `string.Formatter` now understands the 'a' conversion specifier. - -- Issue #15595: Fix ``subprocess.Popen(universal_newlines=True)`` for certain - locales (utf-16 and utf-32 family). Patch by Chris Jerdonek. - -- Issue #15477: In cmath and math modules, add workaround for platforms whose - system-supplied log1p function doesn't respect signs of zeros. - -- Issue #15715: `importlib.__import__()` will silence an ImportError when the - use of fromlist leads to a failed import. - -- Issue #14669: Fix pickling of connections and sockets on Mac OS X by - sending/receiving an acknowledgment after file descriptor transfer. - TestPicklingConnection has been reenabled for Mac OS X. - -- Issue #11062: Fix adding a message from file to Babyl mailbox. - -- Issue #15646: Prevent equivalent of a fork bomb when using `multiprocessing` - on Windows without the ``if __name__ == '__main__'`` idiom. - -IDLE ----- - -- Issue #15678: Fix IDLE menus when started from OS X command line (3.3.0b2 - regression). - -Documentation -------------- - -- Touched up the Python 2 to 3 porting guide. - -- Issue #14674: Add a discussion of the `json` module's standard compliance. - Patch by Chris Rebert. - -- Create a 'Concurrent Execution' section in the docs, and split up the - 'Optional Operating System Services' section to use a more user-centric - classification scheme (splitting them across the new CE section, IPC and text - processing). Operating system limitations can be reflected with the Sphinx - ``:platform:`` tag, it doesn't make sense as part of the Table of Contents. - -- Issue #4966: Bring the sequence docs up to date for the Py3k transition and - the many language enhancements since they were original written. - -- The "path importer" misnomer has been replaced with Eric Snow's - more-awkward-but-at-least-not-wrong suggestion of "path based finder" in the - import system reference docs. - -- Issue #15640: Document `importlib.abc.Finder` as deprecated. - -- Issue #15630: Add an example for "continue" stmt in the tutorial. Patch by - Daniel Ellis. - -Tests ------ - -- Issue #15747: ZFS always returns EOPNOTSUPP when attempting to set the - UF_IMMUTABLE flag (via either chflags or lchflags); refactor affected tests in - test_posix.py to account for this. - -- Issue #15285: Refactor the approach for testing connect timeouts using two - external hosts that have been configured specifically for this type of test. - -- Issue #15743: Remove the deprecated method usage in `urllib` tests. Patch by - Jeff Knupp. - -- Issue #15615: Add some tests for the `json` module's handling of invalid input - data. Patch by Kushal Das. - -Build ------ - -- Output lib files for PGO build into PGO directory. - -- Pick up 32-bit launcher from PGO directory on 64-bit PGO build. - -- Drop ``PC\python_nt.h`` as it's not used. Add input dependency on custom - build step. - -- Issue #15511: Drop explicit dependency on pythonxy.lib from _decimal amd64 - configuration. - -- Add missing PGI/PGO configurations for pywlauncher. - -- Issue #15645: Ensure 2to3 grammar pickles are properly installed. - - -What's New in Python 3.3.0 Beta 2? -================================== - -*Release date: 12-Aug-2012* - -Core and Builtins ------------------ - -- Issue #15568: Fix the return value of ``yield from`` when StopIteration is - raised by a custom iterator. - -- Issue #13119: `sys.stdout` and `sys.stderr` are now using "\r\n" newline on - Windows, as Python 2. - -- Issue #15534: Fix the fast-search function for non-ASCII Unicode strings. - -- Issue #15508: Fix the docstring for `__import__()` to have the proper default - value of 0 for 'level' and to not mention negative levels since they are not - supported. - -- Issue #15425: Eliminated traceback noise from more situations involving - importlib. - -- Issue #14578: Support modules registered in the Windows registry again. - -- Issue #15466: Stop using TYPE_INT64 in marshal, to make importlib.h (and other - byte code files) equal between 32-bit and 64-bit systems. - -- Issue #1692335: Move initial exception args assignment to - `BaseException.__new__()` to help pickling of naive subclasses. - -- Issue #12834: Fix `PyBuffer_ToContiguous()` for non-contiguous arrays. - -- Issue #15456: Fix code `__sizeof__()` after #12399 change. Patch by Serhiy - Storchaka. - -- Issue #15404: Refleak in PyMethodObject repr. - -- Issue #15394: An issue in `PyModule_Create()` that caused references to be - leaked on some error paths has been fixed. Patch by Julia Lawall. - -- Issue #15368: An issue that caused bytecode generation to be non-deterministic - has been fixed. - -- Issue #15202: Consistently use the name "follow_symlinks" for new parameters - in os and shutil functions. - -- Issue #15314: ``__main__.__loader__`` is now set correctly during interpreter - startup. - -- Issue #15111: When a module imported using 'from import' has an ImportError - inside itself, don't mask that fact behind a generic ImportError for the - module itself. - -- Issue #15293: Add GC support to the AST base node type. - -- Issue #15291: Fix a memory leak where AST nodes where not properly - deallocated. - -- Issue #15110: Fix the tracebacks generated by "import xxx" to not show the - importlib stack frames. - -- Issue #16369: Global PyTypeObjects not initialized with PyType_Ready(...). - -- Issue #15020: The program name used to search for Python's path is now - "python3" under Unix, not "python". - -- Issue #15897: zipimport.c doesn't check return value of fseek(). - Patch by Felipe Cruz. - -- Issue #15033: Fix the exit status bug when modules invoked using -m switch, - return the proper failure return value (1). Patch contributed by Jeff Knupp. - -- Issue #15229: An `OSError` subclass whose __init__ doesn't call back - OSError.__init__ could produce incomplete instances, leading to crashes when - calling str() on them. - -- Issue #15307: Virtual environments now use symlinks with framework builds on - Mac OS X, like other POSIX builds. - -Library -------- - -- Issue #14590: configparser now correctly strips inline comments when delimiter - occurs earlier without preceding space. - -- Issue #15424: Add a `__sizeof__()` implementation for array objects. Patch by - Ludwig Hähne. - -- Issue #15576: Allow extension modules to act as a package's __init__ module. - -- Issue #15502: Have `importlib.invalidate_caches()` work on `sys.meta_path` - instead of `sys.path_importer_cache`. - -- Issue #15163: Pydoc shouldn't list __loader__ as module data. - -- Issue #15471: Do not use mutable objects as defaults for - `importlib.__import__()`. - -- Issue #15559: To avoid a problematic failure mode when passed to the bytes - constructor, objects in the ipaddress module no longer implement `__index__()` - (they still implement `__int__()` as appropriate). - -- Issue #15546: Fix handling of pathological input data in the peek() and - read1() methods of the BZ2File, GzipFile and LZMAFile classes. - -- Issue #12655: Instead of requiring a custom type, `os.sched_getaffinity()` and - `os.sched_setaffinity()` now use regular sets of integers to represent the - CPUs a process is restricted to. - -- Issue #15538: Fix compilation of the `socket.getnameinfo()` / - `socket.getaddrinfo()` emulation code. Patch by Philipp Hagemeister. - -- Issue #15519: Properly expose WindowsRegistryFinder in importlib (and use the - correct term for it). Original patch by Eric Snow. - -- Issue #15502: Bring the importlib ABCs into line with the current state of the - import protocols given PEP 420. Original patch by Eric Snow. - -- Issue #15499: Launching a webbrowser in Unix used to sleep for a few seconds. - Original patch by Anton Barkovsky. - -- Issue #15463: The faulthandler module truncates strings to 500 characters, - instead of 100, to be able to display long file paths. - -- Issue #6056: Make `multiprocessing` use setblocking(True) on the sockets it - uses. Original patch by J Derek Wilson. - -- Issue #15364: Fix sysconfig.get_config_var('srcdir') to be an absolute path. - -- Issue #15413: `os.times()` had disappeared under Windows. - -- Issue #15402: An issue in the struct module that caused `sys.getsizeof()` to - return incorrect results for struct.Struct instances has been fixed. Initial - patch by Serhiy Storchaka. - -- Issue #15232: When mangle_from is True, `email.Generator` now correctly - mangles lines that start with 'From ' that occur in a MIME preamble or - epilogue. - -- Issue #15094: Incorrectly placed #endif in _tkinter.c. Patch by Serhiy - Storchaka. - -- Issue #13922: `argparse` no longer incorrectly strips '--'s that appear after - the first one. - -- Issue #12353: `argparse` now correctly handles null argument values. - -- Issue #10017, issue #14998: Fix TypeError using pprint on dictionaries with - user-defined types as keys or other unorderable keys. - -- Issue #15397: `inspect.getmodulename()` is now based directly on importlib via - a new `importlib.machinery.all_suffixes()` API. - -- Issue #14635: `telnetlib` will use poll() rather than select() when possible to - avoid failing due to the select() file descriptor limit. - -- Issue #15180: Clarify posixpath.join() error message when mixing str & bytes. - -- Issue #15343: pkgutil now includes an iter_importer_modules implementation for - importlib.machinery.FileFinder (similar to the way it already handled - zipimport.zipimporter). - -- Issue #15314: runpy now sets __main__.__loader__ correctly. - -- Issue #15357: The import emulation in pkgutil is now deprecated. pkgutil uses - importlib internally rather than the emulation. - -- Issue #15233: Python now guarantees that callables registered with the atexit - module will be called in a deterministic order. - -- Issue #15238: `shutil.copystat()` now copies Linux "extended attributes". - -- Issue #15230: runpy.run_path now correctly sets __package__ as described in - the documentation. - -- Issue #15315: Support VS 2010 in distutils cygwincompiler. - -- Issue #15294: Fix a regression in pkgutil.extend_path()'s handling of nested - namespace packages. - -- Issue #15056: `imp.cache_from_source()` and `imp.source_from_cache()` raise - NotImplementedError when `sys.implementation.cache_tag` is set to None. - -- Issue #15256: Grammatical mistake in exception raised by `imp.find_module()`. - -- Issue #5931: `wsgiref` environ variable SERVER_SOFTWARE will specify an - implementation specific term like CPython, Jython instead of generic "Python". - -- Issue #13248: Remove obsolete argument "max_buffer_size" of BufferedWriter and - BufferedRWPair, from the io module. - -- Issue #13248: Remove obsolete argument "version" of `argparse.ArgumentParser`. - -- Issue #14814: Implement more consistent ordering and sorting behaviour for - ipaddress objects. - -- Issue #14814: `ipaddress` network objects correctly return NotImplemented when - compared to arbitrary objects instead of raising TypeError. - -- Issue #14990: Correctly fail with SyntaxError on invalid encoding declaration. - -- Issue #14814: `ipaddress` now provides more informative error messages when - constructing instances directly (changes permitted during beta due to - provisional API status). - -- Issue #15247: `io.FileIO` now raises an error when given a file descriptor - pointing to a directory. - -- Issue #15261: Stop os.stat(fd) crashing on Windows when fd not open. - -- Issue #15166: Implement `imp.get_tag()` using `sys.implementation.cache_tag`. - -- Issue #15210: Catch KeyError when `importlib.__init__()` can't find - _frozen_importlib in sys.modules, not ImportError. - -- Issue #15030: `importlib.abc.PyPycLoader` now supports the new source size - header field in .pyc files. - -- Issue #5346: Preserve permissions of mbox, MMDF and Babyl mailbox files on - flush(). - -- Issue #10571: Fix the "--sign" option of distutils' upload command. Patch by - Jakub Wilk. - -- Issue #9559: If messages were only added, a new file is no longer created and - renamed over the old file when flush() is called on an mbox, MMDF or Babyl - mailbox. - -- Issue #10924: Fixed `crypt.mksalt()` to use a RNG that is suitable for - cryptographic purpose. - -- Issue #15184: Ensure consistent results of OS X configuration tailoring for - universal builds by factoring out common OS X-specific customizations from - sysconfig, distutils.sysconfig, distutils.util, and distutils.unixccompiler - into a new module _osx_support. - -C API ------ - -- Issue #15610: `PyImport_ImportModuleEx()` now uses a 'level' of 0 instead of -1. - -- Issue #15169, issue #14599: Strip out the C implementation of - `imp.source_from_cache()` used by PyImport_ExecCodeModuleWithPathnames() and - used the Python code instead. Leads to PyImport_ExecCodeModuleObject() to not - try to infer the source path from the bytecode path as - PyImport_ExecCodeModuleWithPathnames() does. - -Extension Modules ------------------ - -- Issue #6493: An issue in ctypes on Windows that caused structure bitfields of - type `ctypes.c_uint32` and width 32 to incorrectly be set has been fixed. - -- Issue #15194: Update libffi to the 3.0.11 release. - -IDLE ----- - -- Issue #13052: Fix IDLE crashing when replace string in Search/Replace dialog - ended with ``\``. Patch by Roger Serwy. - -Tools/Demos ------------ - -- Issue #15458: python-config gets a new option --configdir to print the $LIBPL - value. - -- Move importlib.test.benchmark to Tools/importbench. - -- Issue #12605: The gdb hooks for debugging CPython (within Tools/gdb) have been - enhanced to show information on more C frames relevant to CPython within the - "py-bt" and "py-bt-full" commands: - - * C frames that are waiting on the GIL - * C frames that are garbage-collecting - * C frames that are due to the invocation of a PyCFunction - -Documentation -------------- - -- Issue #15041: Update "see also" list in tkinter documentation. - -- Issue #15444: Use proper spelling for non-ASCII contributor names. Patch by - Serhiy Storchaka. - -- Issue #15295: Reorganize and rewrite the documentation on the import system. - -- Issue #15230: Clearly document some of the limitations of the runpy module and - nudge readers towards importlib when appropriate. - -- Issue #15053: Copy Python 3.3 import lock change notice to all relevant - functions in imp instead of just at the top of the relevant section. - -- Issue #15288: Link to the term "loader" in notes in pkgutil about how things - won't work as expected in Python 3.3 and mark the requisite functions as - "changed" since they will no longer work with modules directly imported by - import itself. - -- Issue #13557: Clarify effect of giving two different namespaces to `exec()` or - `execfile()`. - -- Issue #15250: Document that `filecmp.dircmp()` compares files shallowly. Patch - contributed by Chris Jerdonek. - -- Issue #15442: Expose the default list of directories ignored by - `filecmp.dircmp()` as a module attribute, and expand the list to more modern - values. - -Tests ------ - -- Issue #15467: Move helpers for `__sizeof__()` tests into test_support. Patch - by Serhiy Storchaka. - -- Issue #15320: Make iterating the list of tests thread-safe when running tests - in multiprocess mode. Patch by Chris Jerdonek. - -- Issue #15168: Move `importlib.test` to `test.test_importlib`. - -- Issue #15091: Reactivate a test on UNIX which was failing thanks to a - forgotten `importlib.invalidate_caches()` call. - -- Issue #15230: Adopted a more systematic approach in the runpy tests. - -- Issue #15300: Ensure the temporary test working directories are in the same - parent folder when running tests in multiprocess mode from a Python build. - Patch by Chris Jerdonek. - -- Issue #15284: Skip {send,recv}msg tests in test_socket when IPv6 is not - enabled. Patch by Brian Brazil. - -- Issue #15277: Fix a resource leak in support.py when IPv6 is disabled. Patch - by Brian Brazil. - -Build ------ - -- Issue #11715: Fix multiarch detection without having Debian development tools - (dpkg-dev) installed. - -- Issue #15037: Build OS X installers with local copy of ncurses 5.9 libraries - to avoid curses.unget_wch bug present in older versions of ncurses such as - those shipped with OS X. - -- Issue #15560: Fix building _sqlite3 extension on OS X with an SDK. Also, for - OS X installers, ensure consistent sqlite3 behavior and feature availability - by building a local copy of libsqlite3 rather than depending on the wide range - of versions supplied with various OS X releases. - -- Issue #8847: Disable COMDAT folding in Windows PGO builds. - -- Issue #14018: Fix OS X Tcl/Tk framework checking when using OS X SDKs. - -- Issue #16256: OS X installer now sets correct permissions for doc directory. - -- Issue #15431: Add _freeze_importlib project to regenerate importlib.h on - Windows. Patch by Kristján Valur Jónsson. - -- Issue #14197: For OS X framework builds, ensure links to the shared library - are created with the proper ABI suffix. - -- Issue #14330: For cross builds, don't use host python, use host search paths - for host compiler. - -- Issue #15235: Allow Berkley DB versions up to 5.3 to build the dbm module. - -- Issue #15268: Search curses.h in /usr/include/ncursesw. - - -What's New in Python 3.3.0 Beta 1? -================================== - -*Release date: 27-Jun-2012* - -Core and Builtins ------------------ - -- Fix a (most likely) very rare memory leak when calling main() and not being - able to decode a command-line argument. - -- Issue #14815: Use Py_ssize_t instead of long for the object hash, to - preserve all 64 bits of hash on Win64. - -- Issue #12268: File readline, readlines and read() or readall() methods - no longer lose data when an underlying read system call is interrupted. - IOError is no longer raised due to a read system call returning EINTR - from within these methods. - -- Issue #11626: Add _SizeT functions to stable ABI. - -- Issue #15142: Fix reference leak when deallocating instances of types - created using PyType_FromSpec(). - -- Issue #10053: Don't close FDs when FileIO.__init__ fails. Loosely based on - the work by Hirokazu Yamamoto. - -- Issue #15096: Removed support for ur'' as the raw notation isn't - compatible with Python 2.x's raw unicode strings. - -- Issue #13783: Generator objects now use the identifier APIs internally - -- Issue #14874: Restore charmap decoding speed to pre-PEP 393 levels. - Patch by Serhiy Storchaka. - -- Issue #15026: utf-16 encoding is now significantly faster (up to 10x). - Patch by Serhiy Storchaka. - -- Issue #11022: open() and io.TextIOWrapper are now calling - locale.getpreferredencoding(False) instead of locale.getpreferredencoding() - in text mode if the encoding is not specified. Don't change temporary the - locale encoding using locale.setlocale(), use the current locale encoding - instead of the user preferred encoding. - -- Issue #14673: Add Eric Snow's sys.implementation implementation. - -- Issue #15038: Optimize python Locks on Windows. - -Library -------- - -- Issue #12288: Consider '0' and '0.0' as valid initialvalue - for tkinter SimpleDialog. - -- Issue #15512: Add a __sizeof__ implementation for parser. - Patch by Serhiy Storchaka. - -- Issue #15469: Add a __sizeof__ implementation for deque objects. - Patch by Serhiy Storchaka. - -- Issue #15489: Add a __sizeof__ implementation for BytesIO objects. - Patch by Serhiy Storchaka. - -- Issue #15487: Add a __sizeof__ implementation for buffered I/O objects. - Patch by Serhiy Storchaka. - -- Issue #15514: Correct __sizeof__ support for cpu_set. - Patch by Serhiy Storchaka. - -- Issue #15177: Added dir_fd parameter to os.fwalk(). - -- Issue #15061: Re-implemented hmac.compare_digest() in C to prevent further - timing analysis and to support all buffer protocol aware objects as well as - ASCII only str instances safely. - -- Issue #15164: Change return value of platform.uname() from a - plain tuple to a collections.namedtuple. - -- Support Mageia Linux in the platform module. - -- Issue #11678: Support Arch linux in the platform module. - -- Issue #15118: Change return value of os.uname() and os.times() from - plain tuples to immutable iterable objects with named attributes - (structseq objects). - -- Speed up _decimal by another 10-15% by caching the thread local context - that was last accessed. In the pi benchmark (64-bit platform, prec=9), - _decimal is now only 1.5x slower than float. - -- Remove the packaging module, which is not ready for prime time. - -- Issue #15154: Add "dir_fd" parameter to os.rmdir, remove "rmdir" - parameter from os.remove / os.unlink. - -- Issue #4489: Add a shutil.rmtree that isn't susceptible to symlink attacks. - It is used automatically on platforms supporting the necessary os.openat() - and os.unlinkat() functions. Main code by Martin von Löwis. - -- Issue #15156: HTMLParser now uses the new "html.entities.html5" dictionary. - -- Issue #11113: add a new "html5" dictionary containing the named character - references defined by the HTML5 standard and the equivalent Unicode - character(s) to the html.entities module. - -- Issue #15114: the strict mode of HTMLParser and the HTMLParseError exception - are deprecated now that the parser is able to parse invalid markup. - -- Issue #3665: \u and \U escapes are now supported in unicode regular - expressions. Patch by Serhiy Storchaka. - -- Issue #15153: Added inspect.getgeneratorlocals to simplify white box - testing of generator state updates - -- Issue #13062: Added inspect.getclosurevars to simplify testing stateful - closures - -- Issue #11024: Fixes and additional tests for Time2Internaldate. - -- Issue #14626: Large refactoring of functions / parameters in the os module. - Many functions now support "dir_fd" and "follow_symlinks" parameters; - some also support accepting an open file descriptor in place of a path - string. Added os.support_* collections as LBYL helpers. Removed many - functions only previously seen in 3.3 alpha releases (often starting with - "f" or "l", or ending with "at"). Originally suggested by Serhiy Storchaka; - implemented by Larry Hastings. - -- Issue #15008: Implement PEP 362 "Signature Objects". - Patch by Yury Selivanov. - -- Issue: #15138: base64.urlsafe_{en,de}code() are now 3-4x faster. - -- Issue #444582: Add shutil.which, for finding programs on the system path. - Original patch by Erik Demaine, with later iterations by Jan Killian - and Brian Curtin. - -- Issue #14837: SSL errors now have ``library`` and ``reason`` attributes - describing precisely what happened and in which OpenSSL submodule. The - str() of a SSLError is also enhanced accordingly. - -- Issue #9527: datetime.astimezone() method will now supply a class - timezone instance corresponding to the system local timezone when - called with no arguments. - -- Issue #14653: email.utils.mktime_tz() no longer relies on system - mktime() when timezone offest is supplied. - -- Issue #14684: zlib.compressobj() and zlib.decompressobj() now support the use - of predefined compression dictionaries. Original patch by Sam Rushing. - -- Fix GzipFile's handling of filenames given as bytes objects. - -- Issue #14772: Return destination values from some shutil functions. - -- Issue #15064: Implement context manager protocol for multiprocessing types - -- Issue #15101: Make pool finalizer avoid joining current thread. - -- Issue #14657: The frozen instance of importlib used for bootstrap is now - also the module imported as importlib._bootstrap. - -- Issue #14055: Add __sizeof__ support to _elementtree. - -- Issue #15054: A bug in tokenize.tokenize that caused string literals - with 'b' prefixes to be incorrectly tokenized has been fixed. - Patch by Serhiy Storchaka. - -- Issue #15006: Allow equality comparison between naive and aware - time or datetime objects. - -- Issue #15036: Mailbox no longer throws an error if a flush is done - between operations when removing or changing multiple items in mbox, - MMDF, or Babyl mailboxes. - -- Issue #14059: Implement multiprocessing.Barrier. - -- Issue #15061: The inappropriately named hmac.secure_compare has been - renamed to hmac.compare_digest, restricted to operating on bytes inputs - only and had its documentation updated to more accurately reflect both its - intent and its limitations - -- Issue #13841: Make child processes exit using sys.exit() on Windows. - -- Issue #14936: curses_panel was converted to PEP 3121 and PEP 384 API. - Patch by Robin Schreiber. - -- Issue #1667546: On platforms supporting tm_zone and tm_gmtoff fields - in struct tm, time.struct_time objects returned by time.gmtime(), - time.localtime() and time.strptime() functions now have tm_zone and - tm_gmtoff attributes. Original patch by Paul Boddie. - -- Rename adjusted attribute to adjustable in time.get_clock_info() result. - -- Issue #3518: Remove references to non-existent BaseManager.from_address() - method. - -- Issue #13857: Added textwrap.indent() function (initial patch by Ezra - Berch) - -- Issue #2736: Added datetime.timestamp() method. - -- Issue #13854: Make multiprocessing properly handle non-integer - non-string argument to SystemExit. - -- Issue #12157: Make pool.map() empty iterables correctly. Initial - patch by mouad. - -- Issue #11823: disassembly now shows argument counts on calls with keyword args. - -- Issue #14711: os.stat_float_times() has been deprecated. - -- LZMAFile now accepts the modes "rb"/"wb"/"ab" as synonyms of "r"/"w"/"a". - -- The bz2 and lzma modules now each contain an open() function, allowing - compressed files to readily be opened in text mode as well as binary mode. - -- BZ2File.__init__() and LZMAFile.__init__() now accept a file object as their - first argument, rather than requiring a separate "fileobj" argument. - -- gzip.open() now accepts file objects as well as filenames. - -- Issue #14992: os.makedirs(path, exist_ok=True) would raise an OSError - when the path existed and had the S_ISGID mode bit set when it was - not explicitly asked for. This is no longer an exception as mkdir - cannot control if the OS sets that bit for it or not. - -- Issue #14989: Make the CGI enable option to http.server available via command - line. - -- Issue #14987: Add a missing import statement to inspect. - -- Issue #1079: email.header.decode_header now correctly parses all the examples - in RFC2047. There is a necessary visible behavior change: the leading and/or - trailing whitespace on ASCII parts is now preserved. - -- Issue #14969: Better handling of exception chaining in contextlib.ExitStack - -- Issue #14963: Convert contextlib.ExitStack.__exit__ to use an iterative - algorithm (Patch by Alon Horev) - -- Issue #14785: Add sys._debugmallocstats() to help debug low-level memory - allocation issues - -- Issue #14443: Ensure that .py files are byte-compiled with the correct Python - executable within bdist_rpm even on older versions of RPM - -C-API ------ - -- Issue #15146: Add PyType_FromSpecWithBases. Patch by Robin Schreiber. - -- Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Add version - guard for Py_LIMITED_API additions. Patch by Robin Schreiber. - -- Issue #13783: Inadvertent additions to the public C API in the PEP 380 - implementation have either been removed or marked as private interfaces. - -Extension Modules ------------------ - -- Issue #15000: Support the "unique" x32 architecture in _posixsubprocess.c. - -IDLE ----- - -- Issue #9803: Don't close IDLE on saving if breakpoint is open. - Patch by Roger Serwy. - -- Issue #14962: Update text coloring in IDLE shell window after changing - options. Patch by Roger Serwy. - -Documentation -------------- - -- Issue #15176: Clarified behavior, documentation, and implementation - of os.listdir(). - -- Issue #14982: Document that pkgutil's iteration functions require the - non-standard iter_modules() method to be defined by an importer (something - the importlib importers do not define). - -- Issue #15081: Document PyState_FindModule. - Patch by Robin Schreiber. - -- Issue #14814: Added first draft of ipaddress module API reference - -Tests ------ - -- Issue #15187: Bugfix: remove temporary directories test_shutil was leaving - behind. - -- Issue #14769: test_capi now has SkipitemTest, which cleverly checks - for "parity" between PyArg_ParseTuple() and the Python/getargs.c static - function skipitem() for all possible "format units". - -- test_nntplib now tolerates being run from behind NNTP gateways that add - "X-Antivirus" headers to articles - -- Issue #15043: test_gdb is now skipped entirely if gdb security settings - block loading of the gdb hooks - -- Issue #14963: Add test cases for exception handling behaviour - in contextlib.ExitStack (Initial patch by Alon Horev) - -Build ------ - -- Issue #13590: Improve support for OS X Xcode 4: - * Try to avoid building Python or extension modules with problematic - llvm-gcc compiler. - * Since Xcode 4 removes ppc support, extension module builds now - check for ppc compiler support and automatically remove ppc and - ppc64 archs when not available. - * Since Xcode 4 no longer install SDKs in default locations, - extension module builds now revert to using installed headers - and libs if the SDK used to build the interpreter is not - available. - * Update ./configure to use better defaults for universal builds; - in particular, --enable-universalsdk=yes uses the Xcode default - SDK and --with-universal-archs now defaults to "intel" if ppc - not available. - -- Issue #14225: Fix Unicode support for curses (#12567) on OS X - -- Issue #14928: Fix importlib bootstrap issues by using a custom executable - (Modules/_freeze_importlib) to build Python/importlib.h. - - -What's New in Python 3.3.0 Alpha 4? -=================================== - -*Release date: 31-May-2012* - -Core and Builtins ------------------ - -- Issue #14835: Make plistlib output empty arrays & dicts like OS X. - Patch by Sidney San Martín. - -- Issue #14744: Use the new _PyUnicodeWriter internal API to speed up - str%args and str.format(args). - -- Issue #14930: Make memoryview objects weakrefable. - -- Issue #14775: Fix a potential quadratic dict build-up due to the garbage - collector repeatedly trying to untrack dicts. - -- Issue #14857: fix regression in references to PEP 3135 implicit __class__ - closure variable (Reopens issue #12370) - -- Issue #14712 (PEP 405): Virtual environments. Implemented by Vinay Sajip. - -- Issue #14660 (PEP 420): Namespace packages. Implemented by Eric Smith. - -- Issue #14494: Fix __future__.py and its documentation to note that - absolute imports are the default behavior in 3.0 instead of 2.7. - Patch by Sven Marnach. - -- Issue #9260: A finer-grained import lock. Most of the import sequence - now uses per-module locks rather than the global import lock, eliminating - well-known issues with threads and imports. - -- Issue #14624: UTF-16 decoding is now 3x to 4x faster on various inputs. - Patch by Serhiy Storchaka. - -- asdl_seq and asdl_int_seq are now Py_ssize_t sized. - -- Issue #14133 (PEP 415): Implement suppression of __context__ display with an - attribute on BaseException. This replaces the original mechanism of PEP 409. - -- Issue #14417: Mutating a dict during lookup now restarts the lookup instead - of raising a RuntimeError (undoes issue #14205). - -- Issue #14738: Speed-up UTF-8 decoding on non-ASCII data. Patch by Serhiy - Storchaka. - -- Issue #14700: Fix two broken and undefined-behaviour-inducing overflow checks - in old-style string formatting. - -Library -------- - -- Issue #14690: Use monotonic clock instead of system clock in the sched, - subprocess and trace modules. - -- Issue #14443: Tell rpmbuild to use the correct version of Python in - bdist_rpm. Initial patch by Ross Lagerwall. - -- Issue #12515: email now registers a defect if it gets to EOF while parsing - a MIME part without seeing the closing MIME boundary. - -- Issue #1672568: email now always decodes base64 payloads, adding padding and - ignoring non-base64-alphabet characters if needed, and registering defects - for any such problems. - -- Issue #14925: email now registers a defect when the parser decides that there - is a missing header/body separator line. MalformedHeaderDefect, which the - existing code would never actually generate, is deprecated. - -- Issue #10365: File open dialog now works instead of crashing even when - the parent window is closed before the dialog. Patch by Roger Serwy. - -- Issue #8739: Updated smtpd to support RFC 5321, and added support for the - RFC 1870 SIZE extension. - -- Issue #665194: Added a localtime function to email.utils to provide an - aware local datetime for use in setting Date headers. - -- Issue #12586: Added new provisional policies that implement convenient - unicode support for email headers. See What's New for details. - -- Issue #14731: Refactored email Policy framework to support full backward - compatibility with Python 3.2 by default yet allow for the introduction of - new features through new policies. Note that Policy.must_be_7bit is renamed - to cte_type. - -- Issue #14876: Use user-selected font for highlight configuration. - -- Issue #14920: Fix the help(urllib.parse) failure on locale C on terminals. - Have ascii characters in help. - -- Issue #14548: Make multiprocessing finalizers check pid before - running to cope with possibility of gc running just after fork. - -- Issue #14036: Add an additional check to validate that port in urlparse does - not go in illegal range and returns None. - -- Issue #14862: Add missing names to os.__all__ - -- Issue #14875: Use float('inf') instead of float('1e66666') in the json module. - -- Issue #13585: Added contextlib.ExitStack - -- PEP 3144, Issue #14814: Added the ipaddress module - -- Issue #14426: Correct the Date format in Expires attribute of Set-Cookie - Header in Cookie.py. - -- Issue #14588: The types module now provide new_class() and prepare_class() - functions to support PEP 3115 compliant dynamic class creation. Patch by - Daniel Urban and Nick Coghlan. - -- Issue #13152: Allow to specify a custom tabsize for expanding tabs in - textwrap. Patch by John Feuerstein. - -- Issue #14721: Send the correct 'Content-length: 0' header when the body is an - empty string ''. Initial Patch contributed by Arve Knudsen. - -- Issue #14072: Fix parsing of 'tel' URIs in urlparse by making the check for - ports stricter. - -- Issue #9374: Generic parsing of query and fragment portions of url for any - scheme. Supported both by RFC3986 and RFC2396. - -- Issue #14798: Fix the functions in pyclbr to raise an ImportError - when the first part of a dotted name is not a package. Patch by - Xavier de Gaye. - -- Issue #12098: multiprocessing on Windows now starts child processes - using the same sys.flags as the current process. Initial patch by - Sergey Mezentsev. - -- Issue #13031: Small speed-up for tarfile when unzipping tarfiles. - Patch by Justin Peel. - -- Issue #14780: urllib.request.urlopen() now has a ``cadefault`` argument - to use the default certificate store. Initial patch by James Oakley. - -- Issue #14829: Fix bisect and range() indexing with large indices - (>= 2 ** 32) under 64-bit Windows. - -- Issue #14732: The _csv module now uses PEP 3121 module initialization. - Patch by Robin Schreiber. - -- Issue #14809: Add HTTP status codes introduced by RFC 6585 to http.server - and http.client. Patch by EungJun Yi. - -- Issue #14777: tkinter may return undecoded UTF-8 bytes as a string when - accessing the Tk clipboard. Modify clipboad_get() to first request type - UTF8_STRING when no specific type is requested in an X11 windowing - environment, falling back to the current default type STRING if that fails. - Original patch by Thomas Kluyver. - -- Issue #14773: Fix os.fwalk() failing on dangling symlinks. - -- Issue #12541: Be lenient with quotes around Realm field of HTTP Basic - Authentation in urllib2. - -- Issue #14807: move undocumented tarfile.filemode() to stat.filemode() and add - doc entry. Add tarfile.filemode alias with deprecation warning. - -- Issue #13815: TarFile.extractfile() now returns io.BufferedReader objects. - -- Issue #14532: Add a secure_compare() helper to the hmac module, to mitigate - timing attacks. Patch by Jon Oberheide. - -- Add importlib.util.resolve_name(). - -- Issue #14366: Support lzma compression in zip files. - Patch by Serhiy Storchaka. - -- Issue #13959: Introduce importlib.find_loader() and document - imp.find_module/load_module as deprecated. - -- Issue #14082: shutil.copy2() now copies extended attributes, if possible. - Patch by Hynek Schlawack. - -- Issue #13959: Make importlib.abc.FileLoader.load_module()/get_filename() and - importlib.machinery.ExtensionFileLoader.load_module() have their single - argument be optional. Allows for the replacement (and thus deprecation) of - imp.load_source()/load_package()/load_compiled(). - -- Issue #13959: imp.get_suffixes() has been deprecated in favour of the new - attributes on importlib.machinery: SOURCE_SUFFIXES, DEBUG_BYTECODE_SUFFIXES, - OPTIMIZED_BYTECODE_SUFFIXES, BYTECODE_SUFFIXES, and EXTENSION_SUFFIXES. This - led to an indirect deprecation of inspect.getmoduleinfo(). - -- Issue #14662: Prevent shutil failures on OS X when destination does not - support chflag operations. Patch by Hynek Schlawack. - -- Issue #14157: Fix time.strptime failing without a year on February 29th. - Patch by Hynek Schlawack. - -- Issue #14753: Make multiprocessing's handling of negative timeouts - the same as it was in Python 3.2. - -- Issue #14583: Fix importlib bug when a package's __init__.py would first - import one of its modules then raise an error. - -- Issue #14741: Fix missing support for Ellipsis ('...') in parser module. - -- Issue #14697: Fix missing support for set displays and set comprehensions in - parser module. - -- Issue #14701: Fix missing support for 'raise ... from' in parser module. - -- Add support for timeouts to the acquire() methods of - multiprocessing's lock/semaphore/condition proxies. - -- Issue #13989: Add support for text mode to gzip.open(). - -- Issue #14127: The os.stat() result object now provides three additional - fields: st_ctime_ns, st_mtime_ns, and st_atime_ns, providing those times as an - integer with nanosecond resolution. The functions os.utime(), os.lutimes(), - and os.futimes() now accept a new parameter, ns, which accepts mtime and atime - as integers with nanosecond resolution. - -- Issue #14127 and #10148: shutil.copystat now preserves exact mtime and atime - on filesystems providing nanosecond resolution. - -IDLE ----- - -- Issue #14958: Change IDLE systax highlighting to recognize all string and - byte literals supported in Python 3.3. - -- Issue #10997: Prevent a duplicate entry in IDLE's "Recent Files" menu. - -- Issue #14929: Stop IDLE 3.x from closing on Unicode decode errors when - grepping. Patch by Roger Serwy. - -- Issue #12510: Attempting to get invalid tooltip no longer closes IDLE. - Other tooltipss have been corrected or improved and the number of tests - has been tripled. Original patch by Roger Serwy. - -Tools/Demos ------------ - -- Issue #14695: Bring Tools/parser/unparse.py support up to date with - the Python 3.3 Grammar. - -Build ------ - -- Issue #14472: Update .gitignore. Patch by Matej Cepl. - -- Upgrade Windows library versions: bzip 1.0.6, OpenSSL 1.0.1c. - -- Issue #14693: Under non-Windows platforms, hashlib's fallback modules are - always compiled, even if OpenSSL is present at build time. - -- Issue #13210: Windows build now uses VS2010, ported from VS2008. - -C-API ------ - -- Issue #14705: The PyArg_Parse() family of functions now support the 'p' format - unit, which accepts a "boolean predicate" argument. It converts any Python - value into an integer--0 if it is "false", and 1 otherwise. - -Documentation -------------- - -- Issue #14863: Update the documentation of os.fdopen() to reflect the - fact that it's only a thin wrapper around open() anymore. - -- Issue #14588: The language reference now accurately documents the Python 3 - class definition process. Patch by Nick Coghlan. - -- Issue #14943: Correct a default argument value for winreg.OpenKey - and correctly list the argument names in the function's explanation. - - -What's New in Python 3.3.0 Alpha 3? -=================================== - -*Release date: 01-May-2012* - -Core and Builtins ------------------ - -- Issue #14699: Fix calling the classmethod descriptor directly. - -- Issue #14433: Prevent msvcrt crash in interactive prompt when stdin is closed. - -- Issue #14521: Make result of float('nan') and float('-nan') more consistent - across platforms. - -- Issue #14646: __import__() sets __loader__ if the loader did not. - -- Issue #14605: No longer have implicit entries in sys.meta_path. If - sys.meta_path is found to be empty, raise ImportWarning. - -- Issue #14605: No longer have implicit entries in sys.path_hooks. If - sys.path_hooks is found to be empty, a warning will be raised. None is now - inserted into sys.path_importer_cache if no finder was discovered. This also - means imp.NullImporter is no longer implicitly used. - -- Issue #13903: Implement PEP 412. Individual dictionary instances can now share - their keys with other dictionaries. Classes take advantage of this to share - their instance dictionary keys for improved memory and performance. - -- Issue #11603 (again): Setting __repr__ to __str__ now raises a RuntimeError - when repr() or str() is called on such an object. - -- Issue #14658: Fix binding a special method to a builtin implementation of a - special method with a different name. - -- Issue #14630: Fix a memory access bug for instances of a subclass of int - with value 0. - -- Issue #14339: Speed improvements to bin, oct and hex functions. Patch by - Serhiy Storchaka. - -- Issue #14385: It is now possible to use a custom type for the __builtins__ - namespace, instead of a dict. It can be used for sandboxing for example. - Raise also a NameError instead of ImportError if __build_class__ name if not - found in __builtins__. - -- Issue #12599: Be more strict in accepting None compared to a false-like - object for importlib.util.module_for_loader and - importlib.machinery.PathFinder. - -- Issue #14612: Fix jumping around with blocks by setting f_lineno. - -- Issue #14592: Attempting a relative import w/o __package__ or __name__ set in - globals raises a KeyError. - -- Issue #14607: Fix keyword-only arguments which started with ``__``. - -- Issue #10854: The ImportError raised when an extension module on Windows - fails to import now uses the new path and name attributes from - Issue #1559549. - -- Issue #13889: Check and (if necessary) set FPU control word before calling - any of the dtoa.c string <-> float conversion functions, on MSVC builds of - Python. This fixes issues when embedding Python in a Delphi app. - -- __import__() now matches PEP 328 and documentation by defaulting 'index' to 0 - instead of -1 and removing support for negative values. - -- Issue #2377: Make importlib the implementation of __import__(). - -- Issue #1559549: ImportError now has 'name' and 'path' attributes that are set - using keyword arguments to its constructor. They are currently not set by - import as they are meant for use by importlib. - -- Issue #14474: Save and restore exception state in thread.start_new_thread() - while writing error message if the thread leaves a unhandled exception. - -- Issue #13019: Fix potential reference leaks in bytearray.extend(). Patch - by Suman Saha. - -Library -------- - -- Issue #14768: os.path.expanduser('~/a') doesn't works correctly when HOME is '/'. - -- Issue #14371: Support bzip2 in zipfile module. Patch by Serhiy Storchaka. - -- Issue #13183: Fix pdb skipping frames after hitting a breakpoint and running - step. Patch by Xavier de Gaye. - -- Issue #14696: Fix parser module to understand 'nonlocal' declarations. - -- Issue #10941: Fix imaplib.Internaldate2tuple to produce correct result near - the DST transition. Patch by Joe Peterson. - -- Issue #9154: Fix parser module to understand function annotations. - -- Issue #6085: In http.server.py SimpleHTTPServer.address_string returns the - client ip address instead client hostname. Patch by Charles-François Natali. - -- Issue #14309: Deprecate time.clock(), use time.perf_counter() or - time.process_time() instead. - -- Issue #14428: Implement the PEP 418. Add time.get_clock_info(), - time.perf_counter() and time.process_time() functions, and rename - time.steady() to time.monotonic(). - -- Issue #14646: importlib.util.module_for_loader() now sets __loader__ and - __package__ (when possible). - -- Issue #14664: It is now possible to use @unittest.skip{If,Unless} on a - test class that doesn't inherit from TestCase (i.e. a mixin). - -- Issue #4892: multiprocessing Connections can now be transferred over - multiprocessing Connections. Patch by Richard Oudkerk (sbt). - -- Issue #14160: TarFile.extractfile() failed to resolve symbolic links when - the links were not located in an archive subdirectory. - -- Issue #14638: pydoc now treats non-string __name__ values as if they - were missing, instead of raising an error. - -- Issue #13684: Fix httplib tunnel issue of infinite loops for certain sites - which send EOF without trailing \r\n. - -- Issue #14605: Add importlib.abc.FileLoader, importlib.machinery.(FileFinder, - SourceFileLoader, SourcelessFileLoader, ExtensionFileLoader). - -- Issue #13959: imp.cache_from_source()/source_from_cache() now follow - os.path.join()/split() semantics for path manipulation instead of its prior, - custom semantics of caring the right-most path separator forward in path - joining. - -- Issue #2193: Allow ":" character in Cookie NAME values. - -- Issue #14629: tokenizer.detect_encoding will specify the filename in the - SyntaxError exception if found at readline.__self__.name. - -- Issue #14629: Raise SyntaxError in tokenizer.detect_encoding if the - first two lines have non-UTF-8 characters without an encoding declaration. - -- Issue #14308: Fix an exception when a "dummy" thread is in the threading - module's active list after a fork(). - -- Issue #11750: The Windows API functions scattered in the _subprocess and - _multiprocessing.win32 modules now live in a single module "_winapi". - Patch by sbt. - -- Issue #14087: multiprocessing: add Condition.wait_for(). Patch by sbt. - -- Issue #14538: HTMLParser can now parse correctly start tags that contain - a bare '/'. - -- Issue #14452: SysLogHandler no longer inserts a UTF-8 BOM into the message. - -- Issue #14386: Expose the dict_proxy internal type as types.MappingProxyType. - -- Issue #13959: Make imp.reload() always use a module's __loader__ to perform - the reload. - -- Issue #13959: Add imp.py and rename the built-in module to _imp, allowing for - re-implementing parts of the module in pure Python. - -- Issue #13496: Fix potential overflow in bisect.bisect algorithm when applied - to a collection of size > sys.maxsize / 2. - -- Have importlib take advantage of ImportError's new 'name' and 'path' - attributes. - -- Issue #14399: zipfile now recognizes that the archive has been modified even - if only the comment is changed. In addition, the TypeError that results from - trying to set a non-binary value as a comment is now raised at the time - the comment is set rather than at the time the zipfile is written. - -- trace.CoverageResults.is_ignored_filename() now ignores any name that starts - with "<" and ends with ">" instead of special-casing "" and - ". - -- Issue #14295: Add unittest.mock - -- Issue #7652: Add --with-system-libmpdec option to configure for linking - the _decimal module against an installed libmpdec. - -- Issue #14380: MIMEText now defaults to utf-8 when passed non-ASCII unicode - with no charset specified. - -- Issue #10340: asyncore - properly handle EINVAL in dispatcher constructor on - OSX; avoid to call handle_connect in case of a disconnected socket which - was not meant to connect. - -- Issue #14204: The ssl module now has support for the Next Protocol - Negotiation extension, if available in the underlying OpenSSL library. - Patch by Colin Marc. - -- Issue #3035: Unused functions from tkinter are marked as pending deprecated. - -- Issue #12757: Fix the skipping of doctests when python is run with -OO so - that it works in unittest's verbose mode as well as non-verbose mode. - -- Issue #7652: Integrate the decimal floating point libmpdec library to speed - up the decimal module. Performance gains of the new C implementation are - between 10x and 100x, depending on the application. - -- Issue #14269: SMTPD now conforms to the RFC and requires a HELO command - before MAIL, RCPT, or DATA. - -- Issue #13694: asynchronous connect in asyncore.dispatcher does not set addr - attribute. - -- Issue #14344: fixed the repr of email.policy objects. - -- Issue #11686: Added missing entries to email package __all__ lists - (mostly the new Bytes classes). - -- Issue #14335: multiprocessing's custom Pickler subclass now inherits from - the C-accelerated implementation. Patch by sbt. - -- Issue #10484: Fix the CGIHTTPServer's PATH_INFO handling problem. - -- Issue #11199: Fix the with urllib which hangs on particular ftp urls. - -- Improve the memory utilization and speed of functools.lru_cache. - -- Issue #14222: Use the new time.steady() function instead of time.time() for - timeout in queue and threading modules to not be affected of system time - update. - -- Issue #13248: Remove lib2to3.pytree.Base.get_prefix/set_prefix. - -- Issue #14234: CVE-2012-0876: Randomize hashes of xml attributes in the hash - table internal to the pyexpat module's copy of the expat library to avoid a - denial of service due to hash collisions. Patch by David Malcolm with some - modifications by the expat project. - -- Issue #12818: format address no longer needlessly \ escapes ()s in names when - the name ends up being quoted. - -- Issue #14062: BytesGenerator now correctly folds Header objects, - including using linesep when folding. - -- Issue #13839: When invoked on the command-line, the pstats module now - accepts several filenames of profile stat files and merges them all. - Patch by Matt Joiner. - -- Issue #14291: Email now defaults to utf-8 for non-ASCII unicode headers - instead of raising an error. This fixes a regression relative to 2.7. - -- Issue #989712: Support using Tk without a mainloop. - -- Issue #3835: Refuse to use unthreaded Tcl in threaded Python. - -- Issue #2843: Add new Tk API to Tkinter. - -- Issue #14184: Increase the default stack size for secondary threads on - Mac OS X to avoid interpreter crashes when using threads on 10.7. - -- Issue #14180: datetime.date.fromtimestamp(), - datetime.datetime.fromtimestamp() and datetime.datetime.utcfromtimestamp() - now raise an OSError instead of ValueError if localtime() or gmtime() failed. - -- Issue #14180: time.ctime(), gmtime(), time.localtime(), - datetime.date.fromtimestamp(), datetime.datetime.fromtimestamp() and - datetime.datetime.utcfromtimestamp() now raises an OverflowError, instead of - a ValueError, if the timestamp does not fit in time_t. - -- Issue #14180: datetime.datetime.fromtimestamp() and - datetime.datetime.utcfromtimestamp() now round microseconds towards zero - instead of rounding to nearest with ties going away from zero. - -- Issue #10543: Fix unittest test discovery with Jython bytecode files. - -- Issue #1178863: Separate initialisation from setting when initializing - Tkinter.Variables; harmonize exceptions to ValueError; only delete variables - that have not been deleted; assert that variable names are strings. - -- Issue #14104: Implement time.monotonic() on Mac OS X, patch written by - Nicholas Riley. - -- Issue #13394: the aifc module now uses warnings.warn() to signal warnings. - -- Issue #14252: Fix subprocess.Popen.terminate() to not raise an error under - Windows when the child process has already exited. - -- Issue #14223: curses.addch() is no more limited to the range 0-255 when the - Python curses is not linked to libncursesw. It was a regression introduced - in Python 3.3a1. - -- Issue #14168: Check for presence of Element._attrs in minidom before - accessing it. - -- Issue #12328: Fix multiprocessing's use of overlapped I/O on Windows. - Also, add a multiprocessing.connection.wait(rlist, timeout=None) function - for polling multiple objects at once. Patch by sbt. - -- Issue #14007: Accept incomplete TreeBuilder objects (missing start, end, - data or close method) for the Python implementation as well. - Drop the no-op TreeBuilder().xml() method from the C implementation. - -- Issue #14210: pdb now has tab-completion not only for command names, but - also for their arguments, wherever possible. - -- Issue #14310: Sockets can now be with other processes on Windows using - the api socket.socket.share() and socket.fromshare(). - -- Issue #10576: The gc module now has a 'callbacks' member that will get - called when garbage collection takes place. - -Build ------ - -- Issue #14557: Fix extensions build on HP-UX. Patch by Adi Roiban. - -- Issue #14387: Do not include accu.h from Python.h. - -- Issue #14359: Only use O_CLOEXEC in _posixmodule.c if it is defined. - Based on patch from Hervé Coatanhay. - -- Issue #14321: Do not run pgen during the build if files are up to date. - -Documentation -------------- - -- Issue #14034: added the argparse tutorial. - -- Issue #14324: Fix configure tests for cross builds. - -- Issue #14327: Call AC_CANONICAL_HOST in configure.ac and check in - config.{guess,sub}. Don't use uname calls for cross builds. - -Extension Modules ------------------ - -- Issue #9041: An issue in ctypes.c_longdouble, ctypes.c_double, and - ctypes.c_float that caused an incorrect exception to be returned in the - case of overflow has been fixed. - -- Issue #14212: The re module didn't retain a reference to buffers it was - scanning, resulting in segfaults. - -- Issue #14259: The finditer() method of re objects did not take any - keyword arguments, contrary to the documentation. - -- Issue #10142: Support for SEEK_HOLE/SEEK_DATA (for example, under ZFS). - -Tests ------ - -- Issue #14442: Add missing errno import in test_smtplib. - -- Issue #8315: (partial fix) python -m unittest test.test_email now works. - - -What's New in Python 3.3.0 Alpha 1? -=================================== - -*Release date: 05-Mar-2012* - -Core and Builtins ------------------ - -- Issue #14172: Fix reference leak when marshalling a buffer-like object - (other than a bytes object). - -- Issue #13521: dict.setdefault() now does only one lookup for the given key, - making it "atomic" for many purposes. Patch by Filip Gruszczyński. - -- PEP 409, Issue #6210: "raise X from None" is now supported as a means of - suppressing the display of the chained exception context. The chained - context still remains available as the __context__ attribute. - -- Issue #10181: New memoryview implementation fixes multiple ownership - and lifetime issues of dynamically allocated Py_buffer members (#9990) - as well as crashes (#8305, #7433). Many new features have been added - (See whatsnew/3.3), and the documentation has been updated extensively. - The ndarray test object from _testbuffer.c implements all aspects of - PEP-3118, so further development towards the complete implementation - of the PEP can proceed in a test-driven manner. - - Thanks to Nick Coghlan, Antoine Pitrou and Pauli Virtanen for review - and many ideas. - -- Issue #12834: Fix incorrect results of memoryview.tobytes() for - non-contiguous arrays. - -- Issue #5231: Introduce memoryview.cast() method that allows changing - format and shape without making a copy of the underlying memory. - -- Issue #14084: Fix a file descriptor leak when importing a module with a - bad encoding. - -- Upgrade Unicode data to Unicode 6.1. - -- Issue #14040: Remove rarely used file name suffixes for C extensions - (under POSIX mainly). - -- Issue #14051: Allow arbitrary attributes to be set of classmethod and - staticmethod. - -- Issue #13703: oCERT-2011-003: Randomize hashes of str and bytes to protect - against denial of service attacks due to hash collisions within the dict and - set types. Patch by David Malcolm, based on work by Victor Stinner. - -- Issue #13020: Fix a reference leak when allocating a structsequence object - fails. Patch by Suman Saha. - -- Issue #13908: Ready types returned from PyType_FromSpec. - -- Issue #11235: Fix OverflowError when trying to import a source file whose - modification time doesn't fit in a 32-bit timestamp. - -- Issue #12705: A SyntaxError exception is now raised when attempting to - compile multiple statements as a single interactive statement. - -- Fix the builtin module initialization code to store the init function for - future reinitialization. - -- Issue #8052: The posix subprocess module would take a long time closing - all possible file descriptors in the child process rather than just open - file descriptors. It now closes only the open fds if possible for the - default close_fds=True behavior. - -- Issue #13629: Renumber the tokens in token.h so that they match the indexes - into _PyParser_TokenNames. - -- Issue #13752: Add a casefold() method to str. - -- Issue #13761: Add a "flush" keyword argument to the print() function, - used to ensure flushing the output stream. - -- Issue #13645: pyc files now contain the size of the corresponding source - code, to avoid timestamp collisions (especially on filesystems with a low - timestamp resolution) when checking for freshness of the bytecode. - -- PEP 380, Issue #11682: Add "yield from " to support easy delegation to - subgenerators (initial patch by Greg Ewing, integration into 3.3 by - Renaud Blanch, Ryan Kelly, Zbigniew Jędrzejewski-Szmek and Nick Coghlan) - -- Issue #13748: Raw bytes literals can now be written with the ``rb`` prefix - as well as ``br``. - -- Issue #12736: Use full unicode case mappings for upper, lower, and title case. - -- Issue #12760: Add a create mode to open(). Patch by David Townshend. - -- Issue #13738: Simplify implementation of bytes.lower() and bytes.upper(). - -- Issue #13577: Built-in methods and functions now have a __qualname__. - Patch by sbt. - -- Issue #6695: Full garbage collection runs now clear the freelist of set - objects. Initial patch by Matthias Troffaes. - -- Fix OSError.__init__ and OSError.__new__ so that each of them can be - overriden and take additional arguments (followup to issue #12555). - -- Fix the fix for issue #12149: it was incorrect, although it had the side - effect of appearing to resolve the issue. Thanks to Mark Shannon for - noticing. - -- Issue #13505: Pickle bytes objects in a way that is compatible with - Python 2 when using protocols <= 2. - -- Issue #11147: Fix an unused argument in _Py_ANNOTATE_MEMORY_ORDER. (Fix - given by Campbell Barton). - -- Issue #13503: Use a more efficient reduction format for bytearrays with - pickle protocol >= 3. The old reduction format is kept with older protocols - in order to allow unpickling under Python 2. Patch by Irmen de Jong. - -- Issue #7111: Python can now be run without a stdin, stdout or stderr - stream. It was already the case with Python 2. However, the corresponding - sys module entries are now set to None (instead of an unusable file object). - -- Issue #11849: Ensure that free()d memory arenas are really released - on POSIX systems supporting anonymous memory mappings. Patch by - Charles-François Natali. - -- PEP 3155 / issue #13448: Qualified name for classes and functions. - -- Issue #13436: Fix a bogus error message when an AST object was passed - an invalid integer value. - -- Issue #13411: memoryview objects are now hashable when the underlying - object is hashable. - -- Issue #13338: Handle all enumerations in _Py_ANNOTATE_MEMORY_ORDER - to allow compiling extension modules with -Wswitch-enum on gcc. - Initial patch by Floris Bruynooghe. - -- Issue #10227: Add an allocation cache for a single slice object. Patch by - Stefan Behnel. - -- Issue #13393: BufferedReader.read1() now asks the full requested size to - the raw stream instead of limiting itself to the buffer size. - -- Issue #13392: Writing a pyc file should now be atomic under Windows as well. - -- Issue #13333: The UTF-7 decoder now accepts lone surrogates (the encoder - already accepts them). - -- Issue #13389: Full garbage collection passes now clear the freelists for - list and dict objects. They already cleared other freelists in the - interpreter. - -- Issue #13327: Remove the need for an explicit None as the second argument - to os.utime, os.lutimes, os.futimes, os.futimens, os.futimesat, in - order to update to the current time. Also added keyword argument - handling to os.utimensat in order to remove the need for explicit None. - -- Issue #13350: Simplify some C code by replacing most usages of - PyUnicode_Format by PyUnicode_FromFormat. - -- Issue #13342: input() used to ignore sys.stdin's and sys.stdout's unicode - error handler in interactive mode (when calling into PyOS_Readline()). - -- Issue #9896: Add start, stop, and step attributes to range objects. - -- Issue #13343: Fix a SystemError when a lambda expression uses a global - variable in the default value of a keyword-only argument: ``lambda *, - arg=GLOBAL_NAME: None`` - -- Issue #12797: Added custom opener parameter to builtin open() and - FileIO.open(). - -- Issue #10519: Avoid unnecessary recursive function calls in - setobject.c. - -- Issue #10363: Deallocate global locks in Py_Finalize(). - -- Issue #13018: Fix reference leaks in error paths in dictobject.c. - Patch by Suman Saha. - -- Issue #13201: Define '==' and '!=' to compare range objects based on - the sequence of values they define (instead of comparing based on - object identity). - -- Issue #1294232: In a few cases involving metaclass inheritance, the - interpreter would sometimes invoke the wrong metaclass when building a new - class object. These cases now behave correctly. Patch by Daniel Urban. - -- Issue #12753: Add support for Unicode name aliases and named sequences. - Both ``unicodedata.lookup()`` and '\N{...}' now resolve aliases, - and ``unicodedata.lookup()`` resolves named sequences too. - -- Issue #12170: The count(), find(), rfind(), index() and rindex() methods - of bytes and bytearray objects now accept an integer between 0 and 255 - as their first argument. Patch by Petri Lehtinen. - -- Issue #12604: VTRACE macro expanded to no-op in _sre.c to avoid compiler - warnings. Patch by Josh Triplett and Petri Lehtinen. - -- Issue #12281: Rewrite the MBCS codec to handle correctly replace and ignore - error handlers on all Windows versions. The MBCS codec is now supporting all - error handlers, instead of only replace to encode and ignore to decode. - -- Issue #13188: When called without an explicit traceback argument, - generator.throw() now gets the traceback from the passed exception's - ``__traceback__`` attribute. Patch by Petri Lehtinen. - -- Issue #13146: Writing a pyc file is now atomic under POSIX. - -- Issue #7833: Extension modules built using distutils on Windows will no - longer include a "manifest" to prevent them failing at import time in some - embedded situations. - -- PEP 3151 / issue #12555: reworking the OS and IO exception hierarchy. - -- Add internal API for static strings (_Py_identifier et al.). - -- Issue #13063: the Windows error ERROR_NO_DATA (numbered 232 and described - as "The pipe is being closed") is now mapped to POSIX errno EPIPE - (previously EINVAL). - -- Issue #12911: Fix memory consumption when calculating the repr() of huge - tuples or lists. - -- PEP 393: flexible string representation. Thanks to Torsten Becker for the - initial implementation, and Victor Stinner for various bug fixes. - -- Issue #14081: The 'sep' and 'maxsplit' parameter to str.split, bytes.split, - and bytearray.split may now be passed as keyword arguments. - -- Issue #13012: The 'keepends' parameter to str.splitlines may now be passed - as a keyword argument: "my_string.splitlines(keepends=True)". The same - change also applies to bytes.splitlines and bytearray.splitlines. - -- Issue #7732: Don't open a directory as a file anymore while importing a - module. Ignore the direcotry if its name matchs the module name (e.g. - "__init__.py") and raise a ImportError instead. - -- Issue #13021: Missing decref on an error path. Thanks to Suman Saha for - finding the bug and providing a patch. - -- Issue #12973: Fix overflow checks that relied on undefined behaviour in - list_repeat (listobject.c) and islice_next (itertoolsmodule.c). These bugs - caused test failures with recent versions of Clang. - -- Issue #12904: os.utime, os.futimes, os.lutimes, and os.futimesat now write - atime and mtime with nanosecond precision on modern POSIX platforms. - -- Issue #12802: the Windows error ERROR_DIRECTORY (numbered 267) is now - mapped to POSIX errno ENOTDIR (previously EINVAL). - -- Issue #9200: The str.is* methods now work with strings that contain non-BMP - characters even in narrow Unicode builds. - -- Issue #12791: Break reference cycles early when a generator exits with - an exception. - -- Issue #12773: Make __doc__ mutable on user-defined classes. - -- Issue #12766: Raise a ValueError when creating a class with a class variable - that conflicts with a name in __slots__. - -- Issue #12266: Fix str.capitalize() to correctly uppercase/lowercase - titlecased and cased non-letter characters. - -- Issue #12732: In narrow unicode builds, allow Unicode identifiers which fall - outside the BMP. - -- Issue #12575: Validate user-generated AST before it is compiled. - -- Make type(None), type(Ellipsis), and type(NotImplemented) callable. They - return the respective singleton instances. - -- Forbid summing bytes with sum(). - -- Verify the types of AST strings and identifiers provided by the user before - compiling them. - -- Issue #12647: The None object now has a __bool__() method that returns False. - Formerly, bool(None) returned False only because of special case logic - in PyObject_IsTrue(). - -- Issue #12579: str.format_map() now raises a ValueError if used on a - format string that contains positional fields. Initial patch by - Julian Berman. - -- Issue #10271: Allow warnings.showwarning() be any callable. - -- Issue #11627: Fix segfault when __new__ on a exception returns a - non-exception class. - -- Issue #12149: Update the method cache after a type's dictionary gets - cleared by the garbage collector. This fixes a segfault when an instance - and its type get caught in a reference cycle, and the instance's - deallocator calls one of the methods on the type (e.g. when subclassing - IOBase). Diagnosis and patch by Davide Rizzo. - -- Issue #9611, Issue #9015: FileIO.read() clamps the length to INT_MAX on Windows. - -- Issue #9642: Uniformize the tests on the availability of the mbcs codec, add - a new HAVE_MBCS define. - -- Issue #9642: Fix filesystem encoding initialization: use the ANSI code page - on Windows if the mbcs codec is not available, and fail with a fatal error if - we cannot get the locale encoding (if nl_langinfo(CODESET) is not available) - instead of using UTF-8. - -- When a generator yields, do not retain the caller's exception state on the - generator. - -- Issue #12475: Prevent generators from leaking their exception state into the - caller's frame as they return for the last time. - -- Issue #12291: You can now load multiple marshalled objects from a stream, - with other data interleaved between marshalled objects. - -- Issue #12356: When required positional or keyword-only arguments are not - given, produce a informative error message which includes the name(s) of the - missing arguments. - -- Issue #12370: Fix super with no arguments when __class__ is overriden in the - class body. - -- Issue #12084: os.stat on Windows now works properly with relative symbolic - links when called from any directory. - -- Loosen type restrictions on the __dir__ method. __dir__ can now return any - sequence, which will be converted to a list and sorted by dir(). - -- Issue #12265: Make error messages produced by passing an invalid set of - arguments to a function more informative. - -- Issue #12225: Still allow Python to build if Python is not in its hg repo or - mercurial is not installed. - -- Issue #1195: my_fgets() now always clears errors before calling fgets(). Fix - the following case: sys.stdin.read() stopped with CTRL+d (end of file), - raw_input() interrupted by CTRL+c. - -- Issue #12216: Allow unexpected EOF errors to happen on any line of the file. - -- Issue #12199: The TryExcept and TryFinally and AST nodes have been unified - into a Try node. - -- Issue #9670: Increase the default stack size for secondary threads on - Mac OS X and FreeBSD to reduce the chances of a crash instead of a - "maximum recursion depth" RuntimeError exception. - (patch by Ronald Oussoren) - -- Issue #12106: The use of the multiple-with shorthand syntax is now reflected - in the AST. - -- Issue #12190: Try to use the same filename object when compiling unmarshalling - a code objects in the same file. - -- Issue #12166: Move implementations of dir() specialized for various types into - the __dir__() methods of those types. - -- Issue #5715: In socketserver, close the server socket in the child process. - -- Correct lookup of __dir__ on objects. Among other things, this causes errors - besides AttributeError found on lookup to be propagated. - -- Issue #12060: Use sig_atomic_t type and volatile keyword in the signal - module. Patch written by Charles-François Natali. - -- Issue #1746656: Added the if_nameindex, if_indextoname, if_nametoindex - methods to the socket module. - -- Issue #12044: Fixed subprocess.Popen when used as a context manager to - wait for the process to end when exiting the context to avoid unintentionally - leaving zombie processes around. - -- Issue #1195: Fix input() if it is interrupted by CTRL+d and then CTRL+c, - clear the end-of-file indicator after CTRL+d. - -- Issue #1856: Avoid crashes and lockups when daemon threads run while the - interpreter is shutting down; instead, these threads are now killed when - they try to take the GIL. - -- Issue #9756: When calling a method descriptor or a slot wrapper descriptor, - the check of the object type doesn't read the __class__ attribute anymore. - Fix a crash if a class override its __class__ attribute (e.g. a proxy of the - str type). Patch written by Andreas Stührk. - -- Issue #10517: After fork(), reinitialize the TLS used by the PyGILState_* - APIs, to avoid a crash with the pthread implementation in RHEL 5. Patch - by Charles-François Natali. - -- Issue #10914: Initialize correctly the filesystem codec when creating a new - subinterpreter to fix a bootstrap issue with codecs implemented in Python, as - the ISO-8859-15 codec. - -- Issue #11918: OS/2 and VMS are no more supported because of the lack of - maintainer. - -- Issue #6780: fix starts/endswith error message to mention that tuples are - accepted too. - -- Issue #5057: fix a bug in the peepholer that led to non-portable pyc files - between narrow and wide builds while optimizing BINARY_SUBSCR on non-BMP - chars (e.g. "\U00012345"[0]). - -- Issue #11845: Fix typo in rangeobject.c that caused a crash in - compute_slice_indices. Patch by Daniel Urban. - -- Issue #5673: Added a `timeout` keyword argument to subprocess.Popen.wait, - subprocess.Popen.communicated, subprocess.call, subprocess.check_call, and - subprocess.check_output. If the blocking operation takes more than `timeout` - seconds, the `subprocess.TimeoutExpired` exception is raised. - -- Issue #11650: PyOS_StdioReadline() retries fgets() if it was interrupted - (EINTR), for example if the program is stopped with CTRL+z on Mac OS X. Patch - written by Charles-Francois Natali. - -- Issue #9319: Include the filename in "Non-UTF8 code ..." syntax error. - -- Issue #10785: Store the filename as Unicode in the Python parser. - -- Issue #11619: _PyImport_LoadDynamicModule() doesn't encode the path to bytes - on Windows. - -- Issue #10998: Remove mentions of -Q, sys.flags.division_warning and - Py_DivisionWarningFlag left over from Python 2. - -- Issue #11244: Remove an unnecessary peepholer check that was preventing - negative zeros from being constant-folded properly. - -- Issue #11395: io.FileIO().write() clamps the data length to 32,767 bytes on - Windows if the file is a TTY to workaround a Windows bug. The Windows console - returns an error (12: not enough space error) on writing into stdout if - stdout mode is binary and the length is greater than 66,000 bytes (or less, - depending on heap usage). - -- Issue #11320: fix bogus memory management in Modules/getpath.c, leading to - a possible crash when calling Py_SetPath(). - -- Issue #11432: A bug was introduced in subprocess.Popen on posix systems with - 3.2.0 where the stdout or stderr file descriptor being the same as the stdin - file descriptor would raise an exception. webbrowser.open would fail. fixed. - -- Issue #9856: Change object.__format__ with a non-empty format string - to be a DeprecationWarning. In 3.2 it was a PendingDeprecationWarning. - In 3.4 it will be a TypeError. - -- Issue #11244: The peephole optimizer is now able to constant-fold - arbitrarily complex expressions. This also fixes a 3.2 regression where - operations involving negative numbers were not constant-folded. - -- Issue #11450: Don't truncate hg version info in Py_GetBuildInfo() when - there are many tags (e.g. when using mq). Patch by Nadeem Vawda. - -- Issue #11335: Fixed a memory leak in list.sort when the key function - throws an exception. - -- Issue #8923: When a string is encoded to UTF-8 in strict mode, the result is - cached into the object. Examples: str.encode(), str.encode('utf-8'), - PyUnicode_AsUTF8String() and PyUnicode_AsEncodedString(unicode, "utf-8", - NULL). - -- Issue #10829: Refactor PyUnicode_FromFormat(), use the same function to parse - the format string in the 3 steps, fix crashs on invalid format strings. - -- Issue #13007: whichdb should recognize gdbm 1.9 magic numbers. - -- Issue #11286: Raise a ValueError from calling PyMemoryView_FromBuffer with - a buffer struct having a NULL data pointer. - -- Issue #11272: On Windows, input() strips '\r' (and not only '\n'), and - sys.stdin uses universal newline (replace '\r\n' by '\n'). - -- Issue #11828: startswith and endswith now accept None as slice index. - Patch by Torsten Becker. - -- Issue #11168: Remove filename debug variable from PyEval_EvalFrameEx(). - It encoded the Unicode filename to UTF-8, but the encoding fails on - undecodable filename (on surrogate characters) which raises an unexpected - UnicodeEncodeError on recursion limit. - -- Issue #11187: Remove bootstrap code (use ASCII) of - PyUnicode_AsEncodedString(), it was replaced by a better fallback (use the - locale encoding) in PyUnicode_EncodeFSDefault(). - -- Check for NULL result in PyType_FromSpec. - -- Issue #10516: New copy() and clear() methods for lists and bytearrays. - -- Issue #11386: bytearray.pop() now throws IndexError when the bytearray is - empty, instead of OverflowError. - -- Issue #12380: The rjust, ljust and center methods of bytes and bytearray - now accept a bytearray argument. - -Library -------- - -- Issue #14195: An issue that caused weakref.WeakSet instances to incorrectly - return True for a WeakSet instance 'a' in both 'a < a' and 'a > a' has been - fixed. - -- Issue #14166: Pickler objects now have an optional ``dispatch_table`` - attribute which allows to set custom per-pickler reduction functions. - Patch by sbt. - -- Issue #14177: marshal.loads() now raises TypeError when given an unicode - string. Patch by Guilherme Gonçalves. - -- Issue #13550: Remove the debug machinery from the threading module: remove - verbose arguments from all threading classes and functions. - -- Issue #14159: Fix the len() of weak containers (WeakSet, WeakKeyDictionary, - WeakValueDictionary) to return a better approximation when some objects - are dead or dying. Moreover, the implementation is now O(1) rather than - O(n). - -- Issue #11841: Fix comparison bug with 'rc' versions in packaging.version. - Patch by Filip Gruszczyński. - -- Issue #6884: Fix long-standing bugs with MANIFEST.in parsing in distutils - on Windows. Also fixed in packaging. - -- Issue #8033: sqlite3: Fix 64-bit integer handling in user functions - on 32-bit architectures. Initial patch by Philippe Devalkeneer. - -- HTMLParser is now able to handle slashes in the start tag. - -- Issue #13641: Decoding functions in the base64 module now accept ASCII-only - unicode strings. Patch by Catalin Iacob. - -- Issue #14043: Speed up importlib's _FileFinder by at least 8x, and add a - new importlib.invalidate_caches() function. - -- Issue #14001: CVE-2012-0845: xmlrpc: Fix an endless loop in - SimpleXMLRPCServer upon malformed POST request. - -- Issue #13961: Move importlib over to using os.replace() for atomic renaming. - -- Do away with ambiguous level values (as suggested by PEP 328) in - importlib.__import__() by raising ValueError when level < 0. - -- Issue #2489: pty.spawn could consume 100% cpu when it encountered an EOF. - -- Issue #13014: Fix a possible reference leak in SSLSocket.getpeercert(). - -- Issue #13777: Add PF_SYSTEM sockets on OS X. - Patch by Michael Goderbauer. - -- Issue #13015: Fix a possible reference leak in defaultdict.__repr__. - Patch by Suman Saha. - -- Issue #1326113: distutils' and packaging's build_ext commands option now - correctly parses multiple values (separated by whitespace or commas) given - to their --libraries option. - -- Issue #10287: nntplib now queries the server's CAPABILITIES first before - sending MODE READER, and only sends it if not already in READER mode. - Patch by Hynek Schlawack. - -- Issue #13993: HTMLParser is now able to handle broken end tags when - strict=False. - -- Issue #13930: lib2to3 now supports writing converted output files to another - directory tree as well as copying unchanged files and altering the file - suffix. - -- Issue #9750: Fix sqlite3.Connection.iterdump on tables and fields - with a name that is a keyword or contains quotes. Patch by Marko - Kohtala. - -- Issue #10287: nntplib now queries the server's CAPABILITIES again after - authenticating (since the result may change, according to RFC 4643). - Patch by Hynek Schlawack. - -- Issue #13590: On OS X 10.7 and 10.6 with Xcode 4.2, building - Distutils-based packages with C extension modules may fail because - Apple has removed gcc-4.2, the version used to build python.org - 64-bit/32-bit Pythons. If the user does not explicitly override - the default C compiler by setting the CC environment variable, - Distutils will now attempt to compile extension modules with clang - if gcc-4.2 is required but not found. Also as a convenience, if - the user does explicitly set CC, substitute its value as the default - compiler in the Distutils LDSHARED configuration variable for OS X. - (Note, the python.org 32-bit-only Pythons use gcc-4.0 and the 10.4u - SDK, neither of which are available in Xcode 4. This change does not - attempt to override settings to support their use with Xcode 4.) - -- Issue #13960: HTMLParser is now able to handle broken comments when - strict=False. - -- When '' is a path (e.g. in sys.path), make sure __file__ uses the current - working directory instead of '' in importlib. - -- Issue #13609: Add two functions to query the terminal size: - os.get_terminal_size (low level) and shutil.get_terminal_size (high level). - Patch by Zbigniew Jędrzejewski-Szmek. - -- Issue #13845: On Windows, time.time() now uses GetSystemTimeAsFileTime() - instead of ftime() to have a resolution of 100 ns instead of 1 ms (the clock - accuracy is between 0.5 ms and 15 ms). - -- Issue #13846: Add time.monotonic(), monotonic clock. - -- Issue #8184: multiprocessing: On Windows, don't set SO_REUSEADDR on - Connection sockets, and set FILE_FLAG_FIRST_PIPE_INSTANCE on named pipes, to - make sure two listeners can't bind to the same socket/pipe (or any existing - socket/pipe). - -- Issue #10811: Fix recursive usage of cursors. Instead of crashing, - raise a ProgrammingError now. - -- Issue #13734: Add os.fwalk(), a directory walking function yielding file - descriptors. - -- Issue #2945: Make the distutils upload command aware of bdist_rpm products. - -- Issue #13712: pysetup create should not convert package_data to extra_files. - -- Issue #11805: package_data in setup.cfg should allow more than one value. - -- Issue #13676: Handle strings with embedded zeros correctly in sqlite3. - -- Issue #8828: Add new function os.replace(), for cross-platform renaming - with overwriting. - -- Issue #13848: open() and the FileIO constructor now check for NUL - characters in the file name. Patch by Hynek Schlawack. - -- Issue #13806: The size check in audioop decompression functions was too - strict and could reject valid compressed data. Patch by Oleg Plakhotnyuk. - -- Issue #13812: When a multiprocessing Process child raises an exception, - flush stderr after printing the exception traceback. - -- Issue #13885: CVE-2011-3389: the _ssl module would always disable the CBC - IV attack countermeasure. - -- Issue #13847: time.localtime() and time.gmtime() now raise an OSError instead - of ValueError on failure. time.ctime() and time.asctime() now raises an - OSError if localtime() failed. time.clock() now raises a RuntimeError if the - processor time used is not available or its value cannot be represented - -- Issue #13772: In os.symlink() under Windows, do not try to guess the link - target's type (file or directory). The detection was buggy and made the - call non-atomic (therefore prone to race conditions). - -- Issue #6631: Disallow relative file paths in urllib urlopen methods. - -- Issue #13722: Avoid silencing ImportErrors when initializing the codecs - registry. - -- Issue #13781: Fix GzipFile bug that caused an exception to be raised when - opening for writing using a fileobj returned by os.fdopen(). - -- Issue #13803: Under Solaris, distutils doesn't include bitness - in the directory name. - -- Issue #10278: Add time.wallclock() function, monotonic clock. - -- Issue #13809: Fix regression where bz2 module wouldn't work when threads are - disabled. Original patch by Amaury Forgeot d'Arc. - -- Issue #13589: Fix some serialization primitives in the aifc module. - Patch by Oleg Plakhotnyuk. - -- Issue #13642: Unquote before b64encoding user:password during Basic - Authentication. Patch contributed by Joonas Kuorilehto. - -- Issue #12364: Fix a hang in concurrent.futures.ProcessPoolExecutor. - The hang would occur when retrieving the result of a scheduled future after - the executor had been shut down. - -- Issue #13502: threading: Fix a race condition in Event.wait() that made it - return False when the event was set and cleared right after. - -- Issue #9993: When the source and destination are on different filesystems, - and the source is a symlink, shutil.move() now recreates a symlink on the - destination instead of copying the file contents. Patch by Jonathan Niehof - and Hynek Schlawack. - -- Issue #12926: Fix a bug in tarfile's link extraction. - -- Issue #13696: Fix the 302 Relative URL Redirection problem. - -- Issue #13636: Weak ciphers are now disabled by default in the ssl module - (except when SSLv2 is explicitly asked for). - -- Issue #12715: Add an optional symlinks argument to shutil functions - (copyfile, copymode, copystat, copy, copy2). When that parameter is - true, symlinks aren't dereferenced and the operation instead acts on the - symlink itself (or creates one, if relevant). Patch by Hynek Schlawack. - -- Add a flags parameter to select.epoll. - -- Issue #13626: Add support for SSL Diffie-Hellman key exchange, through the - SSLContext.load_dh_params() method and the ssl.OP_SINGLE_DH_USE option. - -- Issue #11006: Don't issue low level warning in subprocess when pipe2() fails. - -- Issue #13620: Support for Chrome browser in webbrowser. Patch contributed - by Arnaud Calmettes. - -- Issue #11829: Fix code execution holes in inspect.getattr_static for - metaclasses with metaclasses. Patch by Andreas Stührk. - -- Issue #12708: Add starmap() and starmap_async() methods (similar to - itertools.starmap()) to multiprocessing.Pool. Patch by Hynek Schlawack. - -- Issue #1785: Fix inspect and pydoc with misbehaving descriptors. - -- Issue #13637: "a2b" functions in the binascii module now accept ASCII-only - unicode strings. - -- Issue #13634: Add support for querying and disabling SSL compression. - -- Issue #13627: Add support for SSL Elliptic Curve-based Diffie-Hellman - key exchange, through the SSLContext.set_ecdh_curve() method and the - ssl.OP_SINGLE_ECDH_USE option. - -- Issue #13635: Add ssl.OP_CIPHER_SERVER_PREFERENCE, so that SSL servers - choose the cipher based on their own preferences, rather than on the - client's. - -- Issue #11813: Fix inspect.getattr_static for modules. Patch by Andreas - Stührk. - -- Issue #7502: Fix equality comparison for DocTestCase instances. Patch by - Cédric Krier. - -- Issue #11870: threading: Properly reinitialize threads internal locks and - condition variables to avoid deadlocks in child processes. - -- Issue #8035: urllib: Fix a bug where the client could remain stuck after a - redirection or an error. - -- Issue #13560: os.strerror() now uses the current locale encoding instead of - UTF-8. - -- Issue #8373: The filesystem path of AF_UNIX sockets now uses the filesystem - encoding and the surrogateescape error handler, rather than UTF-8. Patch - by David Watson. - -- Issue #10350: Read and save errno before calling a function which might - overwrite it. Original patch by Hallvard B Furuseth. - -- Issue #11610: Introduce a more general way to declare abstract properties. - -- Issue #13591: A bug in importlib has been fixed that caused import_module - to load a module twice. - -- Issue #13449 sched.scheduler.run() method has a new "blocking" parameter which - when set to False makes run() execute the scheduled events due to expire - soonest (if any) and then return. Patch by Giampaolo Rodolà. - -- Issue #8684 sched.scheduler class can be safely used in multi-threaded - environments. Patch by Josiah Carlson and Giampaolo Rodolà. - -- Alias resource.error to OSError ala PEP 3151. - -- Issue #5689: Add support for lzma compression to the tarfile module. - -- Issue #13248: Turn 3.2's PendingDeprecationWarning into 3.3's - DeprecationWarning. It covers 'cgi.escape', 'importlib.abc.PyLoader', - 'importlib.abc.PyPycLoader', 'nntplib.NNTP.xgtitle', 'nntplib.NNTP.xpath', - and private attributes of 'smtpd.SMTPChannel'. - -- Issue #5905, Issue #13560: time.strftime() is now using the current locale - encoding, instead of UTF-8, if the wcsftime() function is not available. - -- Issue #13464: Add a readinto() method to http.client.HTTPResponse. Patch - by Jon Kuhn. - -- tarfile.py: Correctly detect bzip2 compressed streams with blocksizes - other than 900k. - -- Issue #13439: Fix many errors in turtle docstrings. - -- Issue #6715: Add a module 'lzma' for compression using the LZMA algorithm. - Thanks to Per Øyvind Karlsen for the initial implementation. - -- Issue #13487: Make inspect.getmodule robust against changes done to - sys.modules while it is iterating over it. - -- Issue #12618: Fix a bug that prevented py_compile from creating byte - compiled files in the current directory. Initial patch by Sjoerd de Vries. - -- Issue #13444: When stdout has been closed explicitly, we should not attempt - to flush it at shutdown and print an error. - -- Issue #12567: The curses module uses Unicode functions for Unicode arguments - when it is linked to the ncurses library. It encodes also Unicode strings to - the locale encoding instead of UTF-8. - -- Issue #12856: Ensure child processes do not inherit the parent's random - seed for filename generation in the tempfile module. Patch by Brian - Harring. - -- Issue #9957: SpooledTemporaryFile.truncate() now accepts an optional size - parameter, as other file-like objects. Patch by Ryan Kelly. - -- Issue #13458: Fix a memory leak in the ssl module when decoding a - certificate with a subjectAltName. Patch by Robert Xiao. - -- Issue #13415: os.unsetenv() doesn't ignore errors anymore. - -- Issue #13245: sched.scheduler class constructor's timefunc and - delayfunct parameters are now optional. - scheduler.enter and scheduler.enterabs methods gained a new kwargs parameter. - Patch contributed by Chris Clark. - -- Issue #12328: Under Windows, refactor handling of Ctrl-C events and - make _multiprocessing.win32.WaitForMultipleObjects interruptible when - the wait_flag parameter is false. Patch by sbt. - -- Issue #13322: Fix BufferedWriter.write() to ensure that BlockingIOError is - raised when the wrapped raw file is non-blocking and the write would block. - Previous code assumed that the raw write() would raise BlockingIOError, but - RawIOBase.write() is defined to returned None when the call would block. - Patch by sbt. - -- Issue #13358: HTMLParser now calls handle_data only once for each CDATA. - -- Issue #4147: minidom's toprettyxml no longer adds whitespace around a text - node when it is the only child of an element. Initial patch by Dan - Kenigsberg. - -- Issue #13374: The Windows bytes API has been deprecated in the os module. Use - Unicode filenames instead of bytes filenames to not depend on the ANSI code - page anymore and to support any filename. - -- Issue #13297: Use bytes type to send and receive binary data through XMLRPC. - -- Issue #6397: Support "/dev/poll" polling objects in select module, - under Solaris & derivatives. - -- Issues #1745761, #755670, #13357, #12629, #1200313: HTMLParser now correctly - handles non-valid attributes, including adjacent and unquoted attributes. - -- Issue #13193: Fix distutils.filelist.FileList and packaging.manifest.Manifest - under Windows. - -- Issue #13384: Remove unnecessary __future__ import in Lib/random.py - -- Issue #13149: Speed up append-only StringIO objects. - -- Issue #13373: multiprocessing.Queue.get() could sometimes block indefinitely - when called with a timeout. Patch by Arnaud Ysmal. - -- Issue #13254: Fix Maildir initialization so that maildir contents - are read correctly. - -- Issue #3067: locale.setlocale() now raises TypeError if the second - argument is an invalid iterable. Its documentation and docstring - were also updated. Initial patch by Jyrki Pulliainen. - -- Issue #13140: Fix the daemon_threads attribute of ThreadingMixIn. - -- Issue #13339: Fix compile error in posixmodule.c due to missing semicolon. - Thanks to Robert Xiao. - -- Byte compilation in packaging is now isolated from the calling Python -B or - -O options, instead of being disallowed under -B or buggy under -O. - -- Issue #10570: curses.putp() and curses.tparm() are now expecting a byte - string, instead of a Unicode string. - -- Issue #13295: http.server now produces valid HTML 4.01 strict. - -- Issue #2892: preserve iterparse events in case of SyntaxError. - -- Issue #13287: urllib.request and urllib.error now contains an __all__ - attribute to expose only relevant classes and functions. Patch by Florent - Xicluna. - -- Issue #670664: Fix HTMLParser to correctly handle the content of - ```` and ````. - -- Issue #10817: Fix urlretrieve function to raise ContentTooShortError even - when reporthook is None. Patch by Jyrki Pulliainen. - -- Fix the xmlrpc.client user agent to return something similar to - urllib.request user agent: "Python-xmlrpc/3.3". - -- Issue #13293: Better error message when trying to marshal bytes using - xmlrpc.client. - -- Issue #13291: NameError in xmlrpc package. - -- Issue #13258: Use callable() built-in in the standard library. - -- Issue #13273: fix a bug that prevented HTMLParser to properly detect some - tags when strict=False. - -- Issue #11183: Add finer-grained exceptions to the ssl module, so that - you don't have to inspect the exception's attributes in the common case. - -- Issue #13216: Add cp65001 codec, the Windows UTF-8 (CP_UTF8). - -- Issue #13226: Add RTLD_xxx constants to the os module. These constants can be - used with sys.setdlopenflags(). - -- Issue #10278: Add clock_getres(), clock_gettime() and CLOCK_xxx constants to - the time module. time.clock_gettime(time.CLOCK_MONOTONIC) provides a - monotonic clock - -- Issue #10332: multiprocessing: fix a race condition when a Pool is closed - before all tasks have completed. - -- Issue #13255: wrong docstrings in array module. - -- Issue #8540: Remove deprecated Context._clamp attribute in Decimal module. - -- Issue #13235: Added DeprecationWarning to logging.warn() method and function. - -- Issue #9168: now smtpd is able to bind privileged port. - -- Issue #12529: fix cgi.parse_header issue on strings with double-quotes and - semicolons together. Patch by Ben Darnell and Petri Lehtinen. - -- Issue #13227: functools.lru_cache() now has a option to distinguish - calls with different argument types. - -- Issue #6090: zipfile raises a ValueError when a document with a timestamp - earlier than 1980 is provided. Patch contributed by Petri Lehtinen. - -- Issue #13150: sysconfig no longer parses the Makefile and config.h files - when imported, instead doing it at build time. This makes importing - sysconfig faster and reduces Python startup time by 20%. - -- Issue #12448: smtplib now flushes stdout while running ``python -m smtplib`` - in order to display the prompt correctly. - -- Issue #12454: The mailbox module is now using ASCII, instead of the locale - encoding, to read and write .mh_sequences files. - -- Issue #13194: zlib.compressobj().copy() and zlib.decompressobj().copy() are - now available on Windows. - -- Issue #1673007: urllib.request now supports HEAD request via new method argument. - Patch contributions by David Stanek, Patrick Westerhoff and Ezio Melotti. - -- Issue #12386: packaging does not fail anymore when writing the RESOURCES - file. - -- Issue #13158: Fix decoding and encoding of GNU tar specific base-256 number - fields in tarfile. - -- Issue #13025: mimetypes is now reading MIME types using the UTF-8 encoding, - instead of the locale encoding. - -- Issue #10653: On Windows, use strftime() instead of wcsftime() because - wcsftime() doesn't format time zone correctly. - -- Issue #13150: The tokenize module doesn't compile large regular expressions - at startup anymore. - -- Issue #11171: Fix distutils.sysconfig.get_makefile_filename when Python was - configured with different prefix and exec-prefix. - -- Issue #11254: Teach distutils and packaging to compile .pyc and .pyo files in - PEP 3147-compliant __pycache__ directories. - -- Issue #7367: Fix pkgutil.walk_paths to skip directories whose - contents cannot be read. - -- Issue #3163: The struct module gets new format characters 'n' and 'N' - supporting C integer types ``ssize_t`` and ``size_t``, respectively. - -- Issue #13099: Fix sqlite3.Cursor.lastrowid under a Turkish locale. - Reported and diagnosed by Thomas Kluyver. - -- Issue #13087: BufferedReader.seek() now always raises UnsupportedOperation - if the underlying raw stream is unseekable, even if the seek could be - satisfied using the internal buffer. Patch by John O'Connor. - -- Issue #7689: Allow pickling of dynamically created classes when their - metaclass is registered with copyreg. Patch by Nicolas M. Thiéry and Craig - Citro. - -- Issue #13034: When decoding some SSL certificates, the subjectAltName - extension could be unreported. - -- Issue #12306: Expose the runtime version of the zlib C library as a constant, - ZLIB_RUNTIME_VERSION, in the zlib module. Patch by Torsten Landschoff. - -- Issue #12959: Add collections.ChainMap to collections.__all__. - -- Issue #8933: distutils' PKG-INFO files and packaging's METADATA files will - now correctly report Metadata-Version: 1.1 instead of 1.0 if a Classifier or - Download-URL field is present. - -- Issue #12567: Add curses.unget_wch() function. Push a character so the next - get_wch() will return it. - -- Issue #9561: distutils and packaging now writes egg-info files using UTF-8, - instead of the locale encoding. - -- Issue #8286: The distutils command sdist will print a warning message instead - of crashing when an invalid path is given in the manifest template. - -- Issue #12841: tarfile unnecessarily checked the existence of numerical user - and group ids on extraction. If one of them did not exist the respective id - of the current user (i.e. root) was used for the file and ownership - information was lost. - -- Issue #12888: Fix a bug in HTMLParser.unescape that prevented it to escape - more than 128 entities. Patch by Peter Otten. - -- Issue #12878: Expose a __dict__ attribute on io.IOBase and its subclasses. - -- Issue #12494: On error, call(), check_call(), check_output() and - getstatusoutput() functions of the subprocess module now kill the process, - read its status (to avoid zombis) and close pipes. - -- Issue #12720: Expose low-level Linux extended file attribute functions in os. - -- Issue #10946: The distutils commands bdist_dumb, bdist_wininst and bdist_msi - now respect a --skip-build option given to bdist. The packaging commands - were fixed too. - -- Issue #12847: Fix a crash with negative PUT and LONG_BINPUT arguments in - the C pickle implementation. - -- Issue #11564: Avoid crashes when trying to pickle huge objects or containers - (more than 2**31 items). Instead, in most cases, an OverflowError is raised. - -- Issue #12287: Fix a stack corruption in ossaudiodev module when the FD is - greater than FD_SETSIZE. - -- Issue #12839: Fix crash in zlib module due to version mismatch. - Fix by Richard M. Tew. - -- Issue #9923: The mailcap module now correctly uses the platform path - separator for the MAILCAP environment variable on non-POSIX platforms. - -- Issue #12835: Follow up to #6560 that unconditionally prevents use of the - unencrypted sendmsg/recvmsg APIs on SSL wrapped sockets. Patch by David - Watson. - -- Issue #12803: SSLContext.load_cert_chain() now accepts a password argument - to be used if the private key is encrypted. Patch by Adam Simpkins. - -- Issue #11657: Fix sending file descriptors over 255 over a multiprocessing - Pipe. - -- Issue #12811: tabnanny.check() now promptly closes checked files. Patch by - Anthony Briggs. - -- Issue #6560: The sendmsg/recvmsg API is now exposed by the socket module - when provided by the underlying platform, supporting processing of - ancillary data in pure Python code. Patch by David Watson and Heiko Wundram. - -- Issue #12326: On Linux, sys.platform doesn't contain the major version - anymore. It is now always 'linux', instead of 'linux2' or 'linux3' depending - on the Linux version used to build Python. - -- Issue #12213: Fix a buffering bug with interleaved reads and writes that - could appear on BufferedRandom streams. - -- Issue #12778: Reduce memory consumption when JSON-encoding a large - container of many small objects. - -- Issue #12650: Fix a race condition where a subprocess.Popen could leak - resources (FD/zombie) when killed at the wrong time. - -- Issue #12744: Fix inefficient representation of integers between 2**31 and - 2**63 on systems with a 64-bit C "long". - -- Issue #12646: Add an 'eof' attribute to zlib.Decompress, to make it easier to - detect truncated input streams. - -- Issue #11513: Fix exception handling ``tarfile.TarFile.gzopen()`` when - the file cannot be opened. - -- Issue #12687: Fix a possible buffering bug when unpickling text mode - (protocol 0, mostly) pickles. - -- Issue #10087: Fix the html output format of the calendar module. - -- Issue #13121: add support for inplace math operators to collections.Counter. - -- Add support for unary plus and unary minus to collections.Counter. - -- Issue #12683: urlparse updated to include svn as schemes that uses relative - paths. (svn from 1.5 onwards support relative path). - -- Issue #12655: Expose functions from sched.h in the os module: sched_yield(), - sched_setscheduler(), sched_getscheduler(), sched_setparam(), - sched_get_min_priority(), sched_get_max_priority(), sched_rr_get_interval(), - sched_getaffinity(), sched_setaffinity(). - -- Add ThreadError to threading.__all__. - -- Issues #11104, #8688: Fix the behavior of distutils' sdist command with - manually-maintained MANIFEST files. - -- Issue #11281: smtplib.STMP gets source_address parameter, which adds the - ability to bind to specific source address on a machine with multiple - interfaces. Patch by Paulo Scardine. - -- Issue #12464: tempfile.TemporaryDirectory.cleanup() should not follow - symlinks: fix it. Patch by Petri Lehtinen. - -- Issue #8887: "pydoc somebuiltin.somemethod" (or help('somebuiltin.somemethod') - in Python code) now finds the doc of the method. - -- Issue #10968: Remove indirection in threading. The public names (Event, - Condition, etc.) used to be factory functions returning instances of hidden - classes (_Event, _Condition, etc.), because (if Guido recalls correctly) this - code pre-dates the ability to subclass extension types. It is now possible - to inherit from these classes, without having to import the private - underscored names like multiprocessing did. - -- Issue #9723: Add shlex.quote functions, to escape filenames and command - lines. - -- Issue #12603: Fix pydoc.synopsis() on files with non-negative st_mtime. - -- Issue #12514: Use try/finally to assure the timeit module restores garbage - collections when it is done. - -- Issue #12607: In subprocess, fix issue where if stdin, stdout or stderr is - given as a low fd, it gets overwritten. - -- Issue #12576: Fix urlopen behavior on sites which do not send (or obfuscates) - ``Connection: close`` header. - -- Issue #12560: Build libpython.so on OpenBSD. Patch by Stefan Sperling. - -- Issue #1813: Fix codec lookup under Turkish locales. - -- Issue #12591: Improve support of "universal newlines" in the subprocess - module: the piped streams can now be properly read from or written to. - -- Issue #12591: Allow io.TextIOWrapper to work with raw IO objects (without - a read1() method), and add a *write_through* parameter to mandate - unbuffered writes. - -- Issue #10883: Fix socket leaks in urllib.request when using FTP. - -- Issue #12592: Make Python build on OpenBSD 5 (and future major releases). - -- Issue #12372: POSIX semaphores are broken on AIX: don't use them. - -- Issue #12551: Provide a get_channel_binding() method on SSL sockets so as - to get channel binding data for the current SSL session (only the - "tls-unique" channel binding is implemented). This allows the implementation - of certain authentication mechanisms such as SCRAM-SHA-1-PLUS. Patch by - Jacek Konieczny. - -- Issue #665194: email.utils now has format_datetime and parsedate_to_datetime - functions, allowing for round tripping of RFC2822 format dates. - -- Issue #12571: Add a plat-linux3 directory mirroring the plat-linux2 - directory, so that "import DLFCN" and other similar imports work on - Linux 3.0. - -- Issue #7484: smtplib no longer puts <> around addresses in VRFY and EXPN - commands; they aren't required and in fact postfix doesn't support that form. - -- Issue #12273: Remove ast.__version__. AST changes can be accounted for by - checking sys.version_info or sys._mercurial. - -- Silence spurious "broken pipe" tracebacks when shutting down a - ProcessPoolExecutor. - -- Fix potential resource leaks in concurrent.futures.ProcessPoolExecutor - by joining all queues and processes when shutdown() is called. - -- Issue #11603: Fix a crash when __str__ is rebound as __repr__. Patch by - Andreas Stührk. - -- Issue #11321: Fix a crash with multiple imports of the _pickle module when - embedding Python. Patch by Andreas Stührk. - -- Issue #6755: Add get_wch() method to curses.window class. Patch by Iñigo - Serna. - -- Add cgi.closelog() function to close the log file. - -- Issue #12502: asyncore: fix polling loop with AF_UNIX sockets. - -- Issue #4376: ctypes now supports nested structures in a endian different than - the parent structure. Patch by Vlad Riscutia. - -- Raise ValueError when attempting to set the _CHUNK_SIZE attribute of a - TextIOWrapper to a huge value, not TypeError. - -- Issue #12504: Close file handles in a timely manner in packaging.database. - This fixes a bug with the remove (uninstall) feature on Windows. - -- Issues #12169 and #10510: Factor out code used by various packaging commands - to make HTTP POST requests, and make sure it uses CRLF. - -- Issue #12016: Multibyte CJK decoders now resynchronize faster. They only - ignore the first byte of an invalid byte sequence. For example, - b'\xff\n'.decode('gb2312', 'replace') gives '\ufffd\n' instead of '\ufffd'. - -- Issue #12459: time.sleep() now raises a ValueError if the sleep length is - negative, instead of an infinite sleep on Windows or raising an IOError on - Linux for example, to have the same behaviour on all platforms. - -- Issue #12451: pydoc: html_getfile() now uses tokenize.open() to support - Python scripts using a encoding different than UTF-8 (read the coding cookie - of the script). - -- Issue #12493: subprocess: Popen.communicate() now also handles EINTR errors - if the process has only one pipe. - -- Issue #12467: warnings: fix a race condition if a warning is emitted at - shutdown, if globals()['__file__'] is None. - -- Issue #12451: pydoc: importfile() now opens the Python script in binary mode, - instead of text mode using the locale encoding, to avoid encoding issues. - -- Issue #12451: runpy: run_path() now opens the Python script in binary mode, - instead of text mode using the locale encoding, to support other encodings - than UTF-8 (scripts using the coding cookie). - -- Issue #12451: xml.dom.pulldom: parse() now opens files in binary mode instead - of the text mode (using the locale encoding) to avoid encoding issues. - -- Issue #12147: Adjust the new-in-3.2 smtplib.send_message method for better - conformance to the RFCs: correctly handle Sender and Resent- headers. - -- Issue #12352: Fix a deadlock in multiprocessing.Heap when a block is freed by - the garbage collector while the Heap lock is held. - -- Issue #12462: time.sleep() now immediately calls the (Python) signal handler - if it is interrupted by a signal, instead of having to wait until the next - instruction. - -- Issue #12442: new shutil.disk_usage function, providing total, used and free - disk space statistics. - -- Issue #12451: The XInclude default loader of xml.etree now decodes files from - UTF-8 instead of the locale encoding if the encoding is not specified. It now - also opens XML files for the parser in binary mode instead of the text mode - to avoid encoding issues. - -- Issue #12451: doctest.debug_script() doesn't create a temporary file - anymore to avoid encoding issues. - -- Issue #12451: pydoc.synopsis() now reads the encoding cookie if available, - to read the Python script from the right encoding. - -- Issue #12451: distutils now opens the setup script in binary mode to read the - encoding cookie, instead of opening it in UTF-8. - -- Issue #9516: On Mac OS X, change Distutils to no longer globally attempt to - check or set the MACOSX_DEPLOYMENT_TARGET environment variable for the - interpreter process. This could cause failures in non-Distutils subprocesses - and was unreliable since tests or user programs could modify the interpreter - environment after Distutils set it. Instead, have Distutils set the - deployment target only in the environment of each build subprocess. It is - still possible to globally override the default by setting - MACOSX_DEPLOYMENT_TARGET before launching the interpreter; its value must be - greater or equal to the default value, the value with which the interpreter - was built. Also, implement the same handling in packaging. - -- Issue #12422: In the copy module, don't store objects that are their own copy - in the memo dict. - -- Issue #12303: Add sigwaitinfo() and sigtimedwait() to the signal module. - -- Issue #12404: Remove C89 incompatible code from mmap module. Patch by Akira - Kitada. - -- Issue #1874: email now detects and reports as a defect the presence of - any CTE other than 7bit, 8bit, or binary on a multipart. - -- Issue #12383: Fix subprocess module with env={}: don't copy the environment - variables, start with an empty environment. - -- Issue #11637: Fix support for importing packaging setup hooks from the - project directory. - -- Issue #6771: Moved the curses.wrapper function from the single-function - wrapper module into __init__, eliminating the module. Since __init__ was - already importing the function to curses.wrapper, there is no API change. - -- Issue #11584: email.header.decode_header no longer fails if the header - passed to it is a Header object, and Header/make_header no longer fail - if given binary unknown-8bit input. - -- Issue #11700: mailbox proxy object close methods can now be called multiple - times without error. - -- Issue #11767: Correct file descriptor leak in mailbox's __getitem__ method. - -- Issue #12133: AbstractHTTPHandler.do_open() of urllib.request closes the HTTP - connection if its getresponse() method fails with a socket error. Patch - written by Ezio Melotti. - -- Issue #12240: Allow multiple setup hooks in packaging's setup.cfg files. - Original patch by Erik Bray. - -- Issue #9284: Allow inspect.findsource() to find the source of doctest - functions. - -- Issue #11595: Fix assorted bugs in packaging.util.cfg_to_args, a - compatibility helper for the distutils-packaging transition. Original patch - by Erik Bray. - -- Issue #12287: In ossaudiodev, check that the device isn't closed in several - methods. - -- Issue #12009: Fixed regression in netrc file comment handling. - -- Issue #12246: Warn and fail when trying to install a third-party project from - an uninstalled Python (built in a source checkout). Original patch by - Tshepang Lekhonkhobe. - -- Issue #10694: zipfile now ignores garbage at the end of a zipfile. - -- Issue #12283: Fixed regression in smtplib quoting of leading dots in DATA. - -- Issue #10424: Argparse now includes the names of the missing required - arguments in the missing arguments error message. - -- Issue #12168: SysLogHandler now allows NUL termination to be controlled using - a new 'append_nul' attribute on the handler. - -- Issue #11583: Speed up os.path.isdir on Windows by using GetFileAttributes - instead of os.stat. - -- Issue #12021: Make mmap's read() method argument optional. Patch by Petri - Lehtinen. - -- Issue #9205: concurrent.futures.ProcessPoolExecutor now detects killed - children and raises BrokenProcessPool in such a situation. Previously it - would reliably freeze/deadlock. - -- Issue #12040: Expose a new attribute ``sentinel`` on instances of - ``multiprocessing.Process``. Also, fix Process.join() to not use polling - anymore, when given a timeout. - -- Issue #11893: Remove obsolete internal wrapper class ``SSLFakeFile`` in the - smtplib module. Patch by Catalin Iacob. - -- Issue #12080: Fix a Decimal.power() case that took an unreasonably long time - to compute. - -- Issue #12221: Remove __version__ attributes from pyexpat, pickle, tarfile, - pydoc, tkinter, and xml.parsers.expat. This were useless version constants - left over from the Mercurial transition - -- Named tuples now work correctly with vars(). - -- Issue #12085: Fix an attribute error in subprocess.Popen destructor if the - constructor has failed, e.g. because of an undeclared keyword argument. Patch - written by Oleg Oshmyan. - -- Issue #12028: Make threading._get_ident() public, rename it to - threading.get_ident() and document it. This function was already used using - _thread.get_ident(). - -- Issue #12171: IncrementalEncoder.reset() of CJK codecs (multibytecodec) calls - encreset() instead of decreset(). - -- Issue #12218: Removed wsgiref.egg-info. - -- Issue #12196: Add pipe2() to the os module. - -- Issue #985064: Make plistlib more resilient to faulty input plists. - Patch by Mher Movsisyan. - -- Issue #1625: BZ2File and bz2.decompress() now support multi-stream files. - Initial patch by Nir Aides. - -- Issue #12175: BufferedReader.read(-1) now calls raw.readall() if available. - -- Issue #12175: FileIO.readall() now only reads the file position and size - once. - -- Issue #12175: RawIOBase.readall() now returns None if read() returns None. - -- Issue #12175: FileIO.readall() now raises a ValueError instead of an IOError - if the file is closed. - -- Issue #11109: New service_action method for BaseServer, used by ForkingMixin - class for cleanup. Initial Patch by Justin Warkentin. - -- Issue #12045: Avoid duplicate execution of command in - ctypes.util._get_soname(). Patch by Sijin Joseph. - -- Issue #10818: Remove the Tk GUI and the serve() function of the pydoc module, - pydoc -g has been deprecated in Python 3.2 and it has a new enhanced web - server. - -- Issue #1441530: In imaplib, read the data in one chunk to speed up large - reads and simplify code. - -- Issue #12070: Fix the Makefile parser of the sysconfig module to handle - correctly references to "bogus variable" (e.g. "prefix=$/opt/python"). - -- Issue #12100: Don't reset incremental encoders of CJK codecs at each call to - their encode() method anymore, but continue to call the reset() method if the - final argument is True. - -- Issue #12049: Add RAND_bytes() and RAND_pseudo_bytes() functions to the ssl - module. - -- Issue #6501: os.device_encoding() returns None on Windows if the application - has no console. - -- Issue #12105: Add O_CLOEXEC to the os module. - -- Issue #12079: Decimal('Infinity').fma(Decimal('0'), (3.91224318126786e+19+0j)) - now raises TypeError (reflecting the invalid type of the 3rd argument) rather - than Decimal.InvalidOperation. - -- Issue #12124: zipimport doesn't keep a reference to zlib.decompress() anymore - to be able to unload the module. - -- Add the packaging module, an improved fork of distutils (also known as - distutils2). - -- Issue #12065: connect_ex() on an SSL socket now returns the original errno - when the socket's timeout expires (it used to return None). - -- Issue #8809: The SMTP_SSL constructor and SMTP.starttls() now support - passing a ``context`` argument pointing to an ssl.SSLContext instance. - Patch by Kasun Herath. - -- Issue #9516: Issue #9516: avoid errors in sysconfig when MACOSX_DEPLOYMENT_TARGET - is set in shell. - -- Issue #8650: Make zlib module 64-bit clean. compress(), decompress() and - their incremental counterparts now raise OverflowError if given an input - larger than 4GB, instead of silently truncating the input and returning - an incorrect result. - -- Issue #12050: zlib.decompressobj().decompress() now clears the unconsumed_tail - attribute when called without a max_length argument. - -- Issue #12062: Fix a flushing bug when doing a certain type of I/O sequence - on a file opened in read+write mode (namely: reading, seeking a bit forward, - writing, then seeking before the previous write but still within buffered - data, and writing again). - -- Issue #9971: Write an optimized implementation of BufferedReader.readinto(). - Patch by John O'Connor. - -- Issue #11799: urllib.request Authentication Handlers will raise a ValueError - when presented with an unsupported Authentication Scheme. Patch contributed - by Yuval Greenfield. - -- Issue #10419, #6011: build_scripts command of distutils handles correctly - non-ASCII path (path to the Python executable). Open and write the script in - binary mode, but ensure that the shebang is decodable from UTF-8 and from the - encoding of the script. - -- Issue #8498: In socket.accept(), allow to specify 0 as a backlog value in - order to accept exactly one connection. Patch by Daniel Evers. - -- Issue #12011: signal.signal() and signal.siginterrupt() raise an OSError, - instead of a RuntimeError: OSError has an errno attribute. - -- Issue #3709: add a flush_headers method to BaseHTTPRequestHandler, which - manages the sending of headers to output stream and flushing the internal - headers buffer. Patch contribution by Andrew Schaaf - -- Issue #11743: Rewrite multiprocessing connection classes in pure Python. - -- Issue #11164: Stop trying to use _xmlplus in the xml module. - -- Issue #11888: Add log2 function to math module. Patch written by Mark - Dickinson. - -- Issue #12012: ssl.PROTOCOL_SSLv2 becomes optional. - -- Issue #8407: The signal handler writes the signal number as a single byte - instead of a nul byte into the wakeup file descriptor. So it is possible to - wait more than one signal and know which signals were raised. - -- Issue #8407: Add pthread_kill(), sigpending() and sigwait() functions to the - signal module. - -- Issue #11927: SMTP_SSL now uses port 465 by default as documented. Patch - by Kasun Herath. - -- Issue #12002: ftplib's abort() method raises TypeError. - -- Issue #11916: Add a number of MacOSX specific definitions to the errno module. - Patch by Pierre Carrier. - -- Issue #11999: fixed sporadic sync failure mailbox.Maildir due to its trying to - detect mtime changes by comparing to the system clock instead of to the - previous value of the mtime. - -- Issue #11072: added MLSD command (RFC-3659) support to ftplib. - -- Issue #8808: The IMAP4_SSL constructor now allows passing an SSLContext - parameter to control parameters of the secure channel. Patch by Sijin - Joseph. - -- ntpath.samefile failed to notice that "a.txt" and "A.TXT" refer to the same - file on Windows XP. As noticed in issue #10684. - -- Issue #12000: When a SSL certificate has a subjectAltName without any - dNSName entry, ssl.match_hostname() should use the subject's commonName. - Patch by Nicolas Bareil. - -- Issue #10775: assertRaises, assertRaisesRegex, assertWarns, and - assertWarnsRegex now accept a keyword argument 'msg' when used as context - managers. Initial patch by Winston Ewert. - -- Issue #10684: shutil.move used to delete a folder on case insensitive - filesystems when the source and destination name where the same except - for the case. - -- Issue #11647: objects created using contextlib.contextmanager now support - more than one call to the function when used as a decorator. Initial patch - by Ysj Ray. - -- Issue #11930: Removed deprecated time.accept2dyear variable. - Removed year >= 1000 restriction from datetime.strftime. - -- logging: don't define QueueListener if Python has no thread support. - -- functools.cmp_to_key() now works with collections.Hashable(). - -- Issue #11277: mmap.mmap() calls fcntl(fd, F_FULLFSYNC) on Mac OS X to get - around a mmap bug with sparse files. Patch written by Steffen Daode Nurpmeso. - -- Issue #8407: Add signal.pthread_sigmask() function to fetch and/or change the - signal mask of the calling thread. - -- Issue #11858: configparser.ExtendedInterpolation expected lower-case section - names. - -- Issue #11324: ConfigParser(interpolation=None) now works correctly. - -- Issue #11811: ssl.get_server_certificate() is now IPv6-compatible. Patch - by Charles-François Natali. - -- Issue #11763: don't use difflib in TestCase.assertMultiLineEqual if the - strings are too long. - -- Issue #11236: getpass.getpass responds to ctrl-c or ctrl-z on terminal. - -- Issue #11856: Speed up parsing of JSON numbers. - -- Issue #11005: threading.RLock()._release_save() raises a RuntimeError if the - lock was not acquired. - -- Issue #11258: Speed up ctypes.util.find_library() under Linux by a factor - of 5 to 10. Initial patch by Jonas H. - -- Issue #11382: Trivial system calls, such as dup() or pipe(), needn't - release the GIL. Patch by Charles-François Natali. - -- Issue #11223: Add threading._info() function providing informations about - the thread implementation. - -- Issue #11731: simplify/enhance email parser/generator API by introducing - policy objects. - -- Issue #11768: The signal handler of the signal module only calls - Py_AddPendingCall() for the first signal to fix a deadlock on reentrant or - parallel calls. PyErr_SetInterrupt() writes also into the wake up file. - -- Issue #11492: fix several issues with header folding in the email package. - -- Issue #11852: Add missing imports and update tests. - -- Issue #11875: collections.OrderedDict's __reduce__ was temporarily - mutating the object instead of just working on a copy. - -- Issue #11467: Fix urlparse behavior when handling urls which contains scheme - specific part only digits. Patch by Santoso Wijaya. - -- collections.Counter().copy() now works correctly for subclasses. - -- Issue #11474: Fix the bug with url2pathname() handling of '/C|/' on Windows. - Patch by Santoso Wijaya. - -- Issue #11684: complete email.parser bytes API by adding BytesHeaderParser. - -- The bz2 module now handles 4GiB+ input buffers correctly. - -- Issue #9233: Fix json.loads('{}') to return a dict (instead of a list), when - _json is not available. - -- Issue #11830: Remove unnecessary introspection code in the decimal module. - -- Issue #11703: urllib2.geturl() does not return correct url when the original - url contains #fragment. - -- Issue #10019: Fixed regression in json module where an indent of 0 stopped - adding newlines and acted instead like 'None'. - -- Issue #11186: pydoc ignores a module if its name contains a surrogate - character in the index of modules. - -- Issue #11815: Use a light-weight SimpleQueue for the result queue in - concurrent.futures.ProcessPoolExecutor. - -- Issue #5162: Treat services like frozen executables to allow child spawning - from multiprocessing.forking on Windows. - -- logging.basicConfig now supports an optional 'handlers' argument taking an - iterable of handlers to be added to the root logger. Additional parameter - checks were also added to basicConfig. - -- Issue #11814: Fix likely typo in multiprocessing.Pool._terminate(). - -- Issue #11747: Fix range formatting in difflib.context_diff() and - difflib.unified_diff(). - -- Issue #8428: Fix a race condition in multiprocessing.Pool when terminating - worker processes: new processes would be spawned while the pool is being - shut down. Patch by Charles-François Natali. - -- Issue #2650: re.escape() no longer escapes the '_'. - -- Issue #11757: select.select() now raises ValueError when a negative timeout - is passed (previously, a select.error with EINVAL would be raised). Patch - by Charles-François Natali. - -- Issue #7311: fix html.parser to accept non-ASCII attribute values. - -- Issue #11605: email.parser.BytesFeedParser was incorrectly converting - multipart subparts with an 8-bit CTE into unicode instead of preserving the - bytes. - -- Issue #1690608: email.util.formataddr is now RFC 2047 aware: it now has a - charset parameter that defaults to utf-8 and is used as the charset for RFC - 2047 encoding when the realname contains non-ASCII characters. - -- Issue #10963: Ensure that subprocess.communicate() never raises EPIPE. - -- Issue #10791: Implement missing method GzipFile.read1(), allowing GzipFile - to be wrapped in a TextIOWrapper. Patch by Nadeem Vawda. - -- Issue #11707: Added a fast C version of functools.cmp_to_key(). - Patch by Filip Gruszczyński. - -- Issue #11688: Add sqlite3.Connection.set_trace_callback(). Patch by - Torsten Landschoff. - -- Issue #11746: Fix SSLContext.load_cert_chain() to accept elliptic curve - private keys. - -- Issue #5863: Rewrite BZ2File in pure Python, and allow it to accept - file-like objects using a new ``fileobj`` constructor argument. Patch by - Nadeem Vawda. - -- unittest.TestCase.assertSameElements has been removed. - -- sys.getfilesystemencoding() raises a RuntimeError if initfsencoding() was not - called yet: detect bootstrap (startup) issues earlier. - -- Issue #11393: Add the new faulthandler module. - -- Issue #11618: Fix the timeout logic in threading.Lock.acquire() under Windows. - -- Removed the 'strict' argument to email.parser.Parser, which has been - deprecated since Python 2.4. - -- Issue #11256: Fix inspect.getcallargs on functions that take only keyword - arguments. - -- Issue #11696: Fix ID generation in msilib. - -- itertools.accumulate now supports an optional *func* argument for - a user-supplied binary function. - -- Issue #11692: Remove unnecessary demo functions in subprocess module. - -- Issue #9696: Fix exception incorrectly raised by xdrlib.Packer.pack_int when - trying to pack a negative (in-range) integer. - -- Issue #11675: multiprocessing.[Raw]Array objects created from an integer size - are now zeroed on creation. This matches the behaviour specified by the - documentation. - -- Issue #7639: Fix short file name generation in bdist_msi - -- Issue #11635: Don't use polling in worker threads and processes launched by - concurrent.futures. - -- Issue #5845: Automatically read readline configuration to enable completion - in interactive mode. - -- Issue #6811: Allow importlib to change a code object's co_filename attribute - to match the path to where the source code currently is, not where the code - object originally came from. - -- Issue #8754: Have importlib use the repr of a module name in error messages. - -- Issue #11591: Prevent "import site" from modifying sys.path when python - was started with -S. - -- collections.namedtuple() now adds a _source attribute to the generated - class. This make the source more accessible than the outdated - "verbose" option which prints to stdout but doesn't make the source - string available. - -- Issue #11371: Mark getopt error messages as localizable. Patch by Filip - Gruszczyński. - -- Issue #11333: Add __slots__ to collections ABCs. - -- Issue #11628: cmp_to_key generated class should use __slots__. - -- Issue #11666: let help() display named tuple attributes and methods - that start with a leading underscore. - -- Issue #11662: Make urllib and urllib2 ignore redirections if the - scheme is not HTTP, HTTPS or FTP (CVE-2011-1521). - -- Issue #5537: Fix time2isoz() and time2netscape() functions of - httplib.cookiejar for expiration year greater than 2038 on 32-bit systems. - -- Issue #4391: Use proper gettext plural forms in optparse. - -- Issue #11127: Raise a TypeError when trying to pickle a socket object. - -- Issue #11563: ``Connection: close`` header is sent by requests using URLOpener - class which helps in closing of sockets after connection is over. Patch - contributions by Jeff McNeil and Nadeem Vawda. - -- Issue #11459: A ``bufsize`` value of 0 in subprocess.Popen() really creates - unbuffered pipes, such that select() works properly on them. - -- Issue #5421: Fix misleading error message when one of socket.sendto()'s - arguments has the wrong type. Patch by Nikita Vetoshkin. - -- Issue #10812: Add some extra posix functions to the os module. - -- Issue #10979: unittest stdout buffering now works with class and module - setup and teardown. - -- Issue #11243: fix the parameter querying methods of Message to work if - the headers contain un-encoded non-ASCII data. - -- Issue #11401: fix handling of headers with no value; this fixes a regression - relative to Python2 and the result is now the same as it was in Python2. - -- Issue #9298: base64 bodies weren't being folded to line lengths less than 78, - which was a regression relative to Python2. Unlike Python2, the last line - of the folded body now ends with a carriage return. - -- Issue #11560: shutil.unpack_archive now correctly handles the format - parameter. Patch by Evan Dandrea. - -- Issue #5870: Add `subprocess.DEVNULL` constant. - -- Issue #11133: fix two cases where inspect.getattr_static can trigger code - execution. Patch by Andreas Stührk. - -- Issue #11569: use absolute path to the sysctl command in multiprocessing to - ensure that it will be found regardless of the shell PATH. This ensures - that multiprocessing.cpu_count works on default installs of MacOSX. - -- Issue #11501: disutils.archive_utils.make_zipfile no longer fails if zlib is - not installed. Instead, the zipfile.ZIP_STORED compression is used to create - the ZipFile. Patch by Natalia B. Bidart. - -- Issue #11289: `smtp.SMTP` class is now a context manager so it can be used - in a `with` statement. Contributed by Giampaolo Rodola. - -- Issue #11554: Fixed support for Japanese codecs; previously the body output - encoding was not done if euc-jp or shift-jis was specified as the charset. - -- Issue #11407: `TestCase.run` returns the result object used or created. - Contributed by Janathan Hartley. - -- Issue #11500: Fixed a bug in the OS X proxy bypass code for fully qualified - IP addresses in the proxy exception list. - -- Issue #11491: dbm.error is no longer raised when dbm.open is called with - the "n" as the flag argument and the file exists. The behavior matches - the documentation and general logic. - -- Issue #1162477: Postel Principle adjustment to email date parsing: handle the - fact that some non-compliant MUAs use '.' instead of ':' in time specs. - -- Issue #11131: Fix sign of zero in decimal.Decimal plus and minus - operations when the rounding mode is ROUND_FLOOR. - -- Issue #9935: Speed up pickling of instances of user-defined classes. - -- Issue #5622: Fix curses.wrapper to raise correct exception if curses - initialization fails. - -- Issue #11408: In threading.Lock.acquire(), only call gettimeofday() when - really necessary. Patch by Charles-François Natali. - -- Issue #11391: Writing to a mmap object created with - ``mmap.PROT_READ|mmap.PROT_EXEC`` would segfault instead of raising a - TypeError. Patch by Charles-François Natali. - -- Issue #9795: add context manager protocol support for nntplib.NNTP class. - -- Issue #11306: mailbox in certain cases adapts to an inability to open - certain files in read-write mode. Previously it detected this by - checking for EACCES, now it also checks for EROFS. - -- Issue #11265: asyncore now correctly handles EPIPE, EBADF and EAGAIN errors - on accept(), send() and recv(). - -- Issue #11377: Deprecate platform.popen() and reimplement it with os.popen(). - -- Issue #8513: On UNIX, subprocess supports bytes command string. - -- Issue #10866: Add socket.sethostname(). Initial patch by Ross Lagerwall. - -- Issue #11140: Lock.release() now raises a RuntimeError when attempting - to release an unacquired lock, as claimed in the threading documentation. - The _thread.error exception is now an alias of RuntimeError. Patch by - Filip Gruszczyński. Patch for _dummy_thread by Aymeric Augustin. - -- Issue #8594: ftplib now provides a source_address parameter to specify which - (address, port) to bind to before connecting. - -- Issue #11326: Add the missing connect_ex() implementation for SSL sockets, - and make it work for non-blocking connects. - -- Issue #11297: Add collections.ChainMap(). - -- Issue #10755: Add the posix.flistdir() function. Patch by Ross Lagerwall. - -- Issue #4761: Add the ``*at()`` family of functions (openat(), etc.) to the - posix module. Patch by Ross Lagerwall. - -- Issue #7322: Trying to read from a socket's file-like object after a timeout - occurred now raises an error instead of silently losing data. - -- Issue #11291: poplib.POP no longer suppresses errors on quit(). - -- Issue #11177: asyncore's create_socket() arguments can now be omitted. - -- Issue #6064: Add a ``daemon`` keyword argument to the threading.Thread - and multiprocessing.Process constructors in order to override the - default behaviour of inheriting the daemonic property from the current - thread/process. - -- Issue #10956: Buffered I/O classes retry reading or writing after a signal - has arrived and the handler returned successfully. - -- Issue #10784: New os.getpriority() and os.setpriority() functions. - -- Issue #11114: Fix catastrophic performance of tell() on text files (up - to 1000x faster in some cases). It is still one to two order of magnitudes - slower than binary tell(). - -- Issue #10882: Add os.sendfile function. - -- Issue #10868: Allow usage of the register method of an ABC as a class - decorator. - -- Issue #11224: Fixed a regression in tarfile that affected the file-like - objects returned by TarFile.extractfile() regarding performance, memory - consumption and failures with the stream interface. - -- Issue #10924: Adding salt and Modular Crypt Format to crypt library. - Moved old C wrapper to _crypt, and added a Python wrapper with - enhanced salt generation and simpler API for password generation. - -- Issue #11074: Make 'tokenize' so it can be reloaded. - -- Issue #11085: Moved collections abstract base classes into a separate - module called collections.abc, following the pattern used by importlib.abc. - For backwards compatibility, the names are imported into the collections - module. - -- Issue #4681: Allow mmap() to work on file sizes and offsets larger than - 4GB, even on 32-bit builds. Initial patch by Ross Lagerwall, adapted for - 32-bit Windows. - -- Issue #11169: compileall module uses repr() to format filenames and paths to - escape surrogate characters and show spaces. - -- Issue #11089: Fix performance issue limiting the use of ConfigParser() - with large config files. - -- Issue #10276: Fix the results of zlib.crc32() and zlib.adler32() on buffers - larger than 4GB. Patch by Nadeem Vawda. - -- Issue #11388: Added a clear() method to MutableSequence - -- Issue #11174: Add argparse.MetavarTypeHelpFormatter, which uses type names - for the names of optional and positional arguments in help messages. - -- Issue #9348: Raise an early error if argparse nargs and metavar don't match. - -- Issue #9026: Fix order of argparse sub-commands in help messages. - -- Issue #9347: Fix formatting for tuples in argparse type= error messages. - -- Issue #12191: Added shutil.chown() to change user and/or group owner of a - given path also specifying their names. - -- Issue #13988: The _elementtree accelerator is used whenever available. - Now xml.etree.cElementTree becomes a deprecated alias to ElementTree. - -Build ------ - -- Issue #6807: Run msisupport.mak earlier. - -- Issue #10580: Minor grammar change in Windows installer. - -- Issue #13326: Clean __pycache__ directories correctly on OpenBSD. - -- PEP 393: the configure option --with-wide-unicode is removed. - -- Issue #12852: Set _XOPEN_SOURCE to 700, instead of 600, to get POSIX 2008 - functions on OpenBSD (e.g. fdopendir). - -- Issue #11863: Remove support for legacy systems deprecated in Python 3.2 - (following PEP 11). These systems are systems using Mach C Threads, - SunOS lightweight processes, GNU pth threads and IRIX threads. - -- Issue #8746: Correct faulty configure checks so that os.chflags() and - os.lchflags() are once again built on systems that support these - functions (BSD and OS X). Also add new stat file flags for OS X - (UF_HIDDEN and UF_COMPRESSED). - -- Issue #10645: Installing Python no longer creates a - Python-X.Y.Z-pyX.Y.egg-info file in the lib-dynload directory. - -- Do not accidentally include the directory containing sqlite.h twice when - building sqlite3. - -- Issue #11217: For 64-bit/32-bit Mac OS X universal framework builds, - ensure "make install" creates symlinks in --prefix bin for the "-32" - files in the framework bin directory like the installer does. - -- Issue #11347: Use --no-as-needed when linking libpython3.so. - -- Issue #11411: Fix 'make DESTDIR=' with a relative destination. - -- Issue #11268: Prevent Mac OS X Installer failure if Documentation - package had previously been installed. - -- Issue #11495: OSF support is eliminated. It was deprecated in Python 3.2. - -IDLE ----- - -- Issue #14409: IDLE now properly executes commands in the Shell window - when it cannot read the normal config files on startup and - has to use the built-in default key bindings. - There was previously a bug in one of the defaults. - -- IDLE can be launched as python -m idlelib - -- Issue #3573: IDLE hangs when passing invalid command line args - (directory(ies) instead of file(s)) (Patch by Guilherme Polo) - -- Issue #14200: IDLE shell crash on printing non-BMP unicode character. - -- Issue #5219: Prevent event handler cascade in IDLE. - -- Issue #964437: Make IDLE help window non-modal. - Patch by Guilherme Polo and Roger Serwy. - -- Issue #13933: IDLE auto-complete did not work with some imported - module, like hashlib. (Patch by Roger Serwy) - -- Issue #13506: Add '' to path for IDLE Shell when started and restarted with Restart Shell. - Original patches by Marco Scataglini and Roger Serwy. - -- Issue #4625: If IDLE cannot write to its recent file or breakpoint files, - display a message popup and continue rather than crash. Original patch by - Roger Serwy. - -- Issue #8641: Update IDLE 3 syntax coloring to recognize b".." and not u"..". - Patch by Tal Einat. - -- Issue #13296: Fix IDLE to clear compile __future__ flags on shell restart. - (Patch by Roger Serwy) - -- Issue #9871: Prevent IDLE 3 crash when given byte stings - with invalid hex escape sequences, like b'\x0'. - (Original patch by Claudiu Popa.) - -- Issue #12636: IDLE reads the coding cookie when executing a Python script. - -- Issue #12540: Prevent zombie IDLE processes on Windows due to changes - in os.kill(). - -- Issue #12590: IDLE editor window now always displays the first line - when opening a long file. With Tk 8.5, the first line was hidden. - -- Issue #11088: don't crash when using F5 to run a script in IDLE on MacOSX - with Tk 8.5. - -- Issue #1028: Tk returns invalid Unicode null in %A: UnicodeDecodeError. - With Tk < 8.5 _tkinter.c:PythonCmd() raised UnicodeDecodeError, caused - IDLE to exit. Converted to valid Unicode null in PythonCmd(). - -- Issue #11718: IDLE's open module dialog couldn't find the __init__.py - file in a package. - -Tools/Demos ------------ - -- Issue #14053: patchcheck.py ("make patchcheck") now works with MQ patches. - Patch by Francisco Martín Brugué. - -- Issue #13930: 2to3 is now able to write its converted output files to another - directory tree as well as copying unchanged files and altering the file - suffix. See its new -o, -W and --add-suffix options. This makes it more - useful in many automated code translation workflows. - -- Issue #13628: python-gdb.py is now able to retrieve more frames in the Python - traceback if Python is optimized. - -- Issue #11996: libpython (gdb), replace "py-bt" command by "py-bt-full" and - add a smarter "py-bt" command printing a classic Python traceback. - -- Issue #11179: Make ccbench work under Python 3.1 and 2.7 again. - -- Issue #10639: reindent.py no longer converts newlines and will raise - an error if attempting to convert a file with mixed newlines. - "--newline" option added to specify new line character. - -Extension Modules ------------------ - -- Issue #16847: Fixed improper use of _PyUnicode_CheckConsistency() in - non-pydebug builds. Several extension modules now compile cleanly when - assert()s are enabled in standard builds (-DDEBUG flag). - -- Issue #13840: The error message produced by ctypes.create_string_buffer - when given a Unicode string has been fixed. - -- Issue #9975: socket: Fix incorrect use of flowinfo and scope_id. Patch by - Vilmos Nebehaj. - -- Issue #7777: socket: Add Reliable Datagram Sockets (PF_RDS) support. - -- Issue #13159: FileIO and BZ2Compressor/BZ2Decompressor now use a linear-time - buffer growth strategy instead of a quadratic-time one. - -- Issue #10141: socket: Add SocketCAN (PF_CAN) support. Initial patch by - Matthias Fuchs, updated by Tiago Gonçalves. - -- Issue #13070: Fix a crash when a TextIOWrapper caught in a reference cycle - would be finalized after the reference to its underlying BufferedRWPair's - writer got cleared by the GC. - -- Issue #12881: ctypes: Fix segfault with large structure field names. - -- Issue #13058: ossaudiodev: fix a file descriptor leak on error. Patch by - Thomas Jarosch. - -- Issue #13013: ctypes: Fix a reference leak in PyCArrayType_from_ctype. - Thanks to Suman Saha for finding the bug and providing a patch. - -- Issue #13022: Fix: _multiprocessing.recvfd() doesn't check that - file descriptor was actually received. - -- Issue #1172711: Add 'long long' support to the array module. - Initial patch by Oren Tirosh and Hirokazu Yamamoto. - -- Issue #12483: ctypes: Fix a crash when the destruction of a callback - object triggers the garbage collector. - -- Issue #12950: Fix passing file descriptors in multiprocessing, under - OpenIndiana/Illumos. - -- Issue #12764: Fix a crash in ctypes when the name of a Structure field is not - a string. - -- Issue #11241: subclasses of ctypes.Array can now be subclassed. - -- Issue #9651: Fix a crash when ctypes.create_string_buffer(0) was passed to - some functions like file.write(). - -- Issue #10309: Define _GNU_SOURCE so that mremap() gets the proper - signature. Without this, architectures where sizeof void* != sizeof int are - broken. Patch given by Hallvard B Furuseth. - -- Issue #12051: Fix segfault in json.dumps() while encoding highly-nested - objects using the C accelerations. - -- Issue #12017: Fix segfault in json.loads() while decoding highly-nested - objects using the C accelerations. - -- Issue #1838: Prevent segfault in ctypes, when _as_parameter_ on a class is set - to an instance of the class. - -Tests ------ - -- Issue #13125: Silence spurious test_lib2to3 output when in non-verbose mode. - Patch by Mikhail Novikov. - -- Issue #13447: Add a test file to host regression tests for bugs in the - scripts found in the Tools directory. - -- Issue #10881: Fix test_site failure with OS X framework builds. - -- Issue #13901: Prevent test_distutils failures on OS X with --enable-shared. - -- Issue #13862: Fix spurious failure in test_zlib due to runtime/compile time - minor versions not matching. - -- Issue #12804: Fix test_socket and test_urllib2net failures when running tests - on a system without internet access. - -- Issue #13726: Fix the ambiguous -S flag in regrtest. It is -o/--slow for slow - tests. - -- Issue #11659: Fix ResourceWarning in test_subprocess introduced by #11459. - Patch by Ben Hayden. - -- Issue #11577: fix ResourceWarning triggered by improved binhex test coverage - -- Issue #11509: Significantly increase test coverage of fileinput. - Patch by Denver Coneybeare at PyCon 2011 Sprints. - -- Issue #11689: Fix a variable scoping error in an sqlite3 test - -- Issue #13786: Remove unimplemented 'trace' long option from regrtest.py. - -- Issue #13725: Fix regrtest to recognize the documented -d flag. - Patch by Erno Tukia. - -- Issue #13304: Skip test case if user site-packages disabled (-s or - PYTHONNOUSERSITE). (Patch by Carl Meyer) - -- Issue #5661: Add a test for ECONNRESET/EPIPE handling to test_asyncore. Patch - by Xavier de Gaye. - -- Issue #13218: Fix test_ssl failures on Debian/Ubuntu. - -- Re-enable lib2to3's test_parser.py tests, though with an expected failure - (see issue #13125). - -- Issue #12656: Add tests for IPv6 and Unix sockets to test_asyncore. - -- Issue #6484: Add unit tests for mailcap module (patch by Gregory Nofi) - -- Issue #11651: Improve the Makefile test targets to run more of the test suite - more quickly. The --multiprocess option is now enabled by default, reducing - the amount of time needed to run the tests. "make test" and "make quicktest" - now include some resource-intensive tests, but no longer run the test suite - twice to check for bugs in .pyc generation. Tools/scripts/run_test.py provides - an easy platform-independent way to run test suite with sensible defaults. - -- Issue #12331: The test suite for the packaging module can now run from an - installed Python. - -- Issue #12331: The test suite for lib2to3 can now run from an installed - Python. - -- Issue #12626: In regrtest, allow to filter tests using a glob filter - with the ``-m`` (or ``--match``) option. This works with all test cases - using the unittest module. This is useful with long test suites - such as test_io or test_subprocess. - -- Issue #12624: It is now possible to fail after the first failure when - running in verbose mode (``-v`` or ``-W``), by using the ``--failfast`` - (or ``-G``) option to regrtest. This is useful with long test suites - such as test_io or test_subprocess. - -- Issue #12587: Correct faulty test file and reference in test_tokenize. - (Patch by Robert Xiao) - -- Issue #12573: Add resource checks for dangling Thread and Process objects. - -- Issue #12549: Correct test_platform to not fail when OS X returns 'x86_64' - as the processor type on some Mac systems. - -- Skip network tests when getaddrinfo() returns EAI_AGAIN, meaning a temporary - failure in name resolution. - -- Issue #11812: Solve transient socket failure to connect to 'localhost' - in test_telnetlib.py. - -- Solved a potential deadlock in test_telnetlib.py. Related to issue #11812. - -- Avoid failing in test_robotparser when mueblesmoraleda.com is flaky and - an overzealous DNS service (e.g. OpenDNS) redirects to a placeholder - Web site. - -- Avoid failing in test_urllibnet.test_bad_address when some overzealous - DNS service (e.g. OpenDNS) resolves a non-existent domain name. The test - is now skipped instead. - -- Issue #12440: When testing whether some bits in SSLContext.options can be - reset, check the version of the OpenSSL headers Python was compiled against, - rather than the runtime version of the OpenSSL library. - -- Issue #11512: Add a test suite for the cgitb module. Patch by Robbie Clemons. - -- Issue #12497: Install test/data to prevent failures of the various codecmaps - tests. - -- Issue #12496: Install test/capath directory to prevent test_connect_capath - testcase failure in test_ssl. - -- Issue #12469: Run wakeup and pending signal tests in a subprocess to run the - test in a fresh process with only one thread and to not change signal - handling of the parent process. - -- Issue #8716: Avoid crashes caused by Aqua Tk on OSX when attempting to run - test_tk or test_ttk_guionly under a username that is not currently logged - in to the console windowserver (as may be the case under buildbot or ssh). - -- Issue #12407: Explicitly skip test_capi.EmbeddingTest under Windows. - -- Issue #12400: regrtest -W doesn't rerun the tests twice anymore, but captures - the output and displays it on failure instead. regrtest -v doesn't print the - error twice anymore if there is only one error. - -- Issue #12141: Install copies of template C module file so that - test_build_ext of test_distutils and test_command_build_ext of - test_packaging are no longer silently skipped when - run outside of a build directory. - -- Issue #8746: Add additional tests for os.chflags() and os.lchflags(). - Patch by Garrett Cooper. - -- Issue #10736: Fix test_ttk test_widgets failures with Cocoa Tk 8.5.9 - 2.8+ on Mac OS X. (Patch by Ronald Oussoren) - -- Issue #12057: Add tests for ISO 2022 codecs (iso2022_jp, iso2022_jp_2, - iso2022_kr). - -- Issue #12096: Fix a race condition in test_threading.test_waitfor(). Patch - written by Charles-François Natali. - -- Issue #11614: import __hello__ prints "Hello World!". Patch written by - Andreas Stührk. - -- Issue #5723: Improve json tests to be executed with and without accelerations. - -- Issue #12041: Make test_wait3 more robust. - -- Issue #11873: Change regex in test_compileall to fix occasional failures when - when the randomly generated temporary path happened to match the regex. - -- Issue #11958: Fix FTP tests for IPv6, bind to "::1" instead of "localhost". - Patch written by Charles-Francois Natali. - -- Issue #8407, #11859: Fix tests of test_io using threads and an alarm: use - pthread_sigmask() to ensure that the SIGALRM signal is received by the main - thread. - -- Issue #11811: Factor out detection of IPv6 support on the current host - and make it available as ``test.support.IPV6_ENABLED``. Patch by - Charles-François Natali. - -- Issue #10914: Add a minimal embedding test to test_capi. - -- Issue #11223: Skip test_lock_acquire_interruption() and - test_rlock_acquire_interruption() of test_threadsignals if a thread lock is - implemented using a POSIX mutex and a POSIX condition variable. A POSIX - condition variable cannot be interrupted by a signal (e.g. on Linux, the - futex system call is restarted). - -- Issue #11790: Fix sporadic failures in test_multiprocessing.WithProcessesTestCondition. - -- Fix possible "file already exists" error when running the tests in parallel. - -- Issue #11719: Fix message about unexpected test_msilib skip on non-Windows - platforms. Patch by Nadeem Vawda. - -- Issue #11727: Add a --timeout option to regrtest: if a test takes more than - TIMEOUT seconds, dumps the traceback of all threads and exits. - -- Issue #11653: fix -W with -j in regrtest. - -- The email test suite now lives in the Lib/test/test_email package. The test - harness code has also been modernized to allow use of new unittest features. - -- regrtest now discovers test packages as well as test modules. - -- Issue #11577: improve test coverage of binhex.py. Patch by Arkady Koplyarov. - -- New test_crashers added to exercise the scripts in the Lib/test/crashers - directory and confirm they fail as expected - -- Issue #11578: added test for the timeit module. Patch by Michael Henry. - -- Issue #11503: improve test coverage of posixpath.py. Patch by Evan Dandrea. - -- Issue #11505: improves test coverage of string.py, increases granularity of - string.Formatter tests. Initial patch by Alicia Arlen. - -- Issue #11548: Improve test coverage of the shutil module. Patch by - Evan Dandrea. - -- Issue #11554: Reactivated test_email_codecs. - -- Issue #11505: improves test coverage of string.py. Patch by Alicia - Arlen - -- Issue #11490: test_subprocess.test_leaking_fds_on_error no longer gives a - false positive if the last directory in the path is inaccessible. - -- Issue #11223: Fix test_threadsignals to fail, not hang, when the - non-semaphore implementation of locks is used under POSIX. - -- Issue #10911: Add tests on CGI with non-ASCII characters. Patch written by - Pierre Quentel. - -- Issue #9931: Fix hangs in GUI tests under Windows in certain conditions. - Patch by Hirokazu Yamamoto. - -- Issue #10512: Properly close sockets under test.test_cgi. - -- Issue #10992: Make tests pass under coverage. - -- Issue #10826: Prevent sporadic failure in test_subprocess on Solaris due - to open door files. - -- Issue #10990: Prevent tests from clobbering a set trace function. - -C-API ------ - -- Issue #13452: PyUnicode_EncodeDecimal() doesn't support error handlers - different than "strict" anymore. The caller was unable to compute the - size of the output buffer: it depends on the error handler. - -- Issue #13560: Add PyUnicode_DecodeLocale(), PyUnicode_DecodeLocaleAndSize() - and PyUnicode_EncodeLocale() functions to the C API to decode/encode from/to - the current locale encoding. - -- Issue #10831: PyUnicode_FromFormat() supports %li, %lli and %zi formats. - -- Issue #11246: Fix PyUnicode_FromFormat("%V") to decode the byte string from - UTF-8 (with replace error handler) instead of ISO-8859-1 (in strict mode). - Patch written by Ray Allen. - -- Issue #10830: Fix PyUnicode_FromFormatV("%c") for non-BMP characters on - narrow build. - -- Add PyObject_GenericGetDict and PyObject_GeneriSetDict. They are generic - implementations for the getter and setter of a ``__dict__`` descriptor of C - types. - -- Issue #13727: Add 3 macros to access PyDateTime_Delta members: - PyDateTime_DELTA_GET_DAYS, PyDateTime_DELTA_GET_SECONDS, - PyDateTime_DELTA_GET_MICROSECONDS. - -- Issue #10542: Add 4 macros to work with surrogates: Py_UNICODE_IS_SURROGATE, - Py_UNICODE_IS_HIGH_SURROGATE, Py_UNICODE_IS_LOW_SURROGATE, - Py_UNICODE_JOIN_SURROGATES. - -- Issue #12724: Add Py_RETURN_NOTIMPLEMENTED macro for returning NotImplemented. - -- PY_PATCHLEVEL_REVISION has been removed, since it's meaningless with - Mercurial. - -- Issue #12173: The first argument of PyImport_ImportModuleLevel is now `const - char *` instead of `char *`. - -- Issue #12380: PyArg_ParseTuple now accepts a bytearray for the 'c' format. - -Documentation -------------- - -- Issue #23006: Improve the documentation and indexing of dict.__missing__. - Add an entry in the language datamodel special methods section. - Revise and index its discussion in the stdtypes mapping/dict section. - -- Issue #13989: Document that GzipFile does not support text mode, and give a - more helpful error message when opened with an invalid mode string. - -- Issue #13921: Undocument and clean up sqlite3.OptimizedUnicode, - which is obsolete in Python 3.x. It's now aliased to str for - backwards compatibility. - -- Issue #12102: Document that buffered files must be flushed before being used - with mmap. Patch by Steffen Daode Nurpmeso. - -- Issue #8982: Improve the documentation for the argparse Namespace object. - -- Issue #9343: Document that argparse parent parsers must be configured before - their children. - -- Issue #13498: Clarify docs of os.makedirs()'s exist_ok argument. Done with - great native-speaker help from R. David Murray. - -- Issues #13491 and #13995: Fix many errors in sqlite3 documentation. - Initial patch for #13491 by Johannes Vogel. - -- Issue #13402: Document absoluteness of sys.executable. - -- Issue #13883: PYTHONCASEOK also works on OS X. - -- Issue #9021: Add an introduction to the copy module documentation. - -- Issue #6005: Examples in the socket library documentation use sendall, where - relevant, instead send method. - -- Issue #12798: Updated the mimetypes documentation. - -- Issue #12949: Document the kwonlyargcount argument for the PyCode_New - C API function. - -- Issue #13513: Fix io.IOBase documentation to correctly link to the - io.IOBase.readline method instead of the readline module. - -- Issue #13237: Reorganise subprocess documentation to emphasise convenience - functions and the most commonly needed arguments to Popen. - -- Issue #13141: Demonstrate recommended style for socketserver examples. - -- Issue #11818: Fix tempfile examples for Python 3. - - -**(For information about older versions, consult the HISTORY file.)** diff --git a/Misc/NEWS.d/3.3.0.rst b/Misc/NEWS.d/3.3.0.rst new file mode 100644 index 00000000000000..7301131b9df70e --- /dev/null +++ b/Misc/NEWS.d/3.3.0.rst @@ -0,0 +1,27 @@ +.. bpo: 16046 +.. date: 7992 +.. nonce: 3_BLo_ +.. release date: 29-Sep-2012 +.. section: Core and Builtins + +Fix loading sourceless legacy .pyo files. + +.. + +.. bpo: 16060 +.. date: 7991 +.. nonce: u00uiP +.. section: Core and Builtins + +Fix refcounting bug when `__trunc__()` returns an object whose `__int__()` +gives a non-integer. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16012 +.. date: 7990 +.. nonce: A0Dlk_ +.. section: Library + +Fix a regression in pyexpat. The parser's `UseForeignDTD()` method doesn't +require an argument again. diff --git a/Misc/NEWS.d/3.3.0a1.rst b/Misc/NEWS.d/3.3.0a1.rst new file mode 100644 index 00000000000000..c1185ec095b3fc --- /dev/null +++ b/Misc/NEWS.d/3.3.0a1.rst @@ -0,0 +1,7646 @@ +.. bpo: 14172 +.. date: 7489 +.. nonce: EIbdxW +.. release date: 05-Mar-2012 +.. section: Core and Builtins + +Fix reference leak when marshalling a buffer-like object (other than a bytes +object). + +.. + +.. bpo: 13521 +.. date: 7488 +.. nonce: L_inbK +.. section: Core and Builtins + +dict.setdefault() now does only one lookup for the given key, making it +"atomic" for many purposes. Patch by Filip Gruszczyński. + +.. + +.. bpo: 0 +.. date: 7487 +.. nonce: Y9s9QE +.. section: Core and Builtins + +PEP 409, Issue #6210: "raise X from None" is now supported as a means of +suppressing the display of the chained exception context. The chained +context still remains available as the __context__ attribute. + +.. + +.. bpo: 10181 +.. date: 7486 +.. nonce: QFiREN +.. section: Core and Builtins + +New memoryview implementation fixes multiple ownership and lifetime issues +of dynamically allocated Py_buffer members (#9990) as well as crashes +(#8305, #7433). Many new features have been added (See whatsnew/3.3), and +the documentation has been updated extensively. The ndarray test object from +_testbuffer.c implements all aspects of PEP-3118, so further development +towards the complete implementation of the PEP can proceed in a test-driven +manner. + +Thanks to Nick Coghlan, Antoine Pitrou and Pauli Virtanen for review and +many ideas. + +.. + +.. bpo: 12834 +.. date: 7485 +.. nonce: lZTD8W +.. section: Core and Builtins + +Fix incorrect results of memoryview.tobytes() for non-contiguous arrays. + +.. + +.. bpo: 5231 +.. date: 7484 +.. nonce: 7QZAi1 +.. section: Core and Builtins + +Introduce memoryview.cast() method that allows changing format and shape +without making a copy of the underlying memory. + +.. + +.. bpo: 14084 +.. date: 7483 +.. nonce: VVBkOk +.. section: Core and Builtins + +Fix a file descriptor leak when importing a module with a bad encoding. + +.. + +.. bpo: 0 +.. date: 7482 +.. nonce: BPfFYz +.. section: Core and Builtins + +Upgrade Unicode data to Unicode 6.1. + +.. + +.. bpo: 14040 +.. date: 7481 +.. nonce: PgP41A +.. section: Core and Builtins + +Remove rarely used file name suffixes for C extensions (under POSIX mainly). + +.. + +.. bpo: 14051 +.. date: 7480 +.. nonce: a174tR +.. section: Core and Builtins + +Allow arbitrary attributes to be set of classmethod and staticmethod. + +.. + +.. bpo: 13703 +.. date: 7479 +.. nonce: bP-Abj +.. section: Core and Builtins + +oCERT-2011-003: Randomize hashes of str and bytes to protect against denial +of service attacks due to hash collisions within the dict and set types. +Patch by David Malcolm, based on work by Victor Stinner. + +.. + +.. bpo: 13020 +.. date: 7478 +.. nonce: 7y51PJ +.. section: Core and Builtins + +Fix a reference leak when allocating a structsequence object fails. Patch +by Suman Saha. + +.. + +.. bpo: 13908 +.. date: 7477 +.. nonce: gY7-0t +.. section: Core and Builtins + +Ready types returned from PyType_FromSpec. + +.. + +.. bpo: 11235 +.. date: 7476 +.. nonce: 6wzkv- +.. section: Core and Builtins + +Fix OverflowError when trying to import a source file whose modification +time doesn't fit in a 32-bit timestamp. + +.. + +.. bpo: 12705 +.. date: 7475 +.. nonce: E1UO3x +.. section: Core and Builtins + +A SyntaxError exception is now raised when attempting to compile multiple +statements as a single interactive statement. + +.. + +.. bpo: 0 +.. date: 7474 +.. nonce: URLqbf +.. section: Core and Builtins + +Fix the builtin module initialization code to store the init function for +future reinitialization. + +.. + +.. bpo: 8052 +.. date: 7473 +.. nonce: i5F_0O +.. section: Core and Builtins + +The posix subprocess module would take a long time closing all possible file +descriptors in the child process rather than just open file descriptors. It +now closes only the open fds if possible for the default close_fds=True +behavior. + +.. + +.. bpo: 13629 +.. date: 7472 +.. nonce: ZzOj6B +.. section: Core and Builtins + +Renumber the tokens in token.h so that they match the indexes into +_PyParser_TokenNames. + +.. + +.. bpo: 13752 +.. date: 7471 +.. nonce: zb4RK_ +.. section: Core and Builtins + +Add a casefold() method to str. + +.. + +.. bpo: 13761 +.. date: 7470 +.. nonce: ZkU_de +.. section: Core and Builtins + +Add a "flush" keyword argument to the print() function, used to ensure +flushing the output stream. + +.. + +.. bpo: 13645 +.. date: 7469 +.. nonce: 7elNwY +.. section: Core and Builtins + +pyc files now contain the size of the corresponding source code, to avoid +timestamp collisions (especially on filesystems with a low timestamp +resolution) when checking for freshness of the bytecode. + +.. + +.. bpo: 0 +.. date: 7468 +.. nonce: PaHwFO +.. section: Core and Builtins + +PEP 380, Issue #11682: Add "yield from " to support easy delegation to +subgenerators (initial patch by Greg Ewing, integration into 3.3 by Renaud +Blanch, Ryan Kelly, Zbigniew Jędrzejewski-Szmek and Nick Coghlan) + +.. + +.. bpo: 13748 +.. date: 7467 +.. nonce: n9rlfR +.. section: Core and Builtins + +Raw bytes literals can now be written with the ``rb`` prefix as well as +``br``. + +.. + +.. bpo: 12736 +.. date: 7466 +.. nonce: l91PiA +.. section: Core and Builtins + +Use full unicode case mappings for upper, lower, and title case. + +.. + +.. bpo: 12760 +.. date: 7465 +.. nonce: ao9dmi +.. section: Core and Builtins + +Add a create mode to open(). Patch by David Townshend. + +.. + +.. bpo: 13738 +.. date: 7464 +.. nonce: M9VOMZ +.. section: Core and Builtins + +Simplify implementation of bytes.lower() and bytes.upper(). + +.. + +.. bpo: 13577 +.. date: 7463 +.. nonce: r9XUQK +.. section: Core and Builtins + +Built-in methods and functions now have a __qualname__. Patch by sbt. + +.. + +.. bpo: 6695 +.. date: 7462 +.. nonce: SH6ELR +.. section: Core and Builtins + +Full garbage collection runs now clear the freelist of set objects. Initial +patch by Matthias Troffaes. + +.. + +.. bpo: 0 +.. date: 7461 +.. nonce: tPq2HD +.. section: Core and Builtins + +Fix OSError.__init__ and OSError.__new__ so that each of them can be +overriden and take additional arguments (followup to issue #12555). + +.. + +.. bpo: 0 +.. date: 7460 +.. nonce: 2J4kRL +.. section: Core and Builtins + +Fix the fix for issue #12149: it was incorrect, although it had the side +effect of appearing to resolve the issue. Thanks to Mark Shannon for +noticing. + +.. + +.. bpo: 13505 +.. date: 7459 +.. nonce: -fVx4a +.. section: Core and Builtins + +Pickle bytes objects in a way that is compatible with Python 2 when using +protocols <= 2. + +.. + +.. bpo: 11147 +.. date: 7458 +.. nonce: GGZMRG +.. section: Core and Builtins + +Fix an unused argument in _Py_ANNOTATE_MEMORY_ORDER. (Fix given by Campbell +Barton). + +.. + +.. bpo: 13503 +.. date: 7457 +.. nonce: CguNef +.. section: Core and Builtins + +Use a more efficient reduction format for bytearrays with pickle protocol >= +3. The old reduction format is kept with older protocols in order to allow +unpickling under Python 2. Patch by Irmen de Jong. + +.. + +.. bpo: 7111 +.. date: 7456 +.. nonce: jT9r7r +.. section: Core and Builtins + +Python can now be run without a stdin, stdout or stderr stream. It was +already the case with Python 2. However, the corresponding sys module +entries are now set to None (instead of an unusable file object). + +.. + +.. bpo: 11849 +.. date: 7455 +.. nonce: CGVEGl +.. section: Core and Builtins + +Ensure that free()d memory arenas are really released on POSIX systems +supporting anonymous memory mappings. Patch by Charles-François Natali. + +.. + +.. bpo: 0 +.. date: 7454 +.. nonce: Qf63qA +.. section: Core and Builtins + +PEP 3155 / issue #13448: Qualified name for classes and functions. + +.. + +.. bpo: 13436 +.. date: 7453 +.. nonce: aJdgA5 +.. section: Core and Builtins + +Fix a bogus error message when an AST object was passed an invalid integer +value. + +.. + +.. bpo: 13411 +.. date: 7452 +.. nonce: ck2a71 +.. section: Core and Builtins + +memoryview objects are now hashable when the underlying object is hashable. + +.. + +.. bpo: 13338 +.. date: 7451 +.. nonce: FFZr2K +.. section: Core and Builtins + +Handle all enumerations in _Py_ANNOTATE_MEMORY_ORDER to allow compiling +extension modules with -Wswitch-enum on gcc. Initial patch by Floris +Bruynooghe. + +.. + +.. bpo: 10227 +.. date: 7450 +.. nonce: 3RxtLE +.. section: Core and Builtins + +Add an allocation cache for a single slice object. Patch by Stefan Behnel. + +.. + +.. bpo: 13393 +.. date: 7449 +.. nonce: e0t8-t +.. section: Core and Builtins + +BufferedReader.read1() now asks the full requested size to the raw stream +instead of limiting itself to the buffer size. + +.. + +.. bpo: 13392 +.. date: 7448 +.. nonce: Vo4LlN +.. section: Core and Builtins + +Writing a pyc file should now be atomic under Windows as well. + +.. + +.. bpo: 13333 +.. date: 7447 +.. nonce: jkzjPN +.. section: Core and Builtins + +The UTF-7 decoder now accepts lone surrogates (the encoder already accepts +them). + +.. + +.. bpo: 13389 +.. date: 7446 +.. nonce: XpcClS +.. section: Core and Builtins + +Full garbage collection passes now clear the freelists for list and dict +objects. They already cleared other freelists in the interpreter. + +.. + +.. bpo: 13327 +.. date: 7445 +.. nonce: IrE-_j +.. section: Core and Builtins + +Remove the need for an explicit None as the second argument to os.utime, +os.lutimes, os.futimes, os.futimens, os.futimesat, in order to update to the +current time. Also added keyword argument handling to os.utimensat in order +to remove the need for explicit None. + +.. + +.. bpo: 13350 +.. date: 7444 +.. nonce: IYeSXA +.. section: Core and Builtins + +Simplify some C code by replacing most usages of PyUnicode_Format by +PyUnicode_FromFormat. + +.. + +.. bpo: 13342 +.. date: 7443 +.. nonce: _ddnpI +.. section: Core and Builtins + +input() used to ignore sys.stdin's and sys.stdout's unicode error handler in +interactive mode (when calling into PyOS_Readline()). + +.. + +.. bpo: 9896 +.. date: 7442 +.. nonce: xYsm94 +.. section: Core and Builtins + +Add start, stop, and step attributes to range objects. + +.. + +.. bpo: 13343 +.. date: 7441 +.. nonce: rrKCUj +.. section: Core and Builtins + +Fix a SystemError when a lambda expression uses a global variable in the +default value of a keyword-only argument: ``lambda *, arg=GLOBAL_NAME: +None`` + +.. + +.. bpo: 12797 +.. date: 7440 +.. nonce: Bx-Rhh +.. section: Core and Builtins + +Added custom opener parameter to builtin open() and FileIO.open(). + +.. + +.. bpo: 10519 +.. date: 7439 +.. nonce: vnPUhZ +.. section: Core and Builtins + +Avoid unnecessary recursive function calls in setobject.c. + +.. + +.. bpo: 10363 +.. date: 7438 +.. nonce: Sa4BVo +.. section: Core and Builtins + +Deallocate global locks in Py_Finalize(). + +.. + +.. bpo: 13018 +.. date: 7437 +.. nonce: WRySxn +.. section: Core and Builtins + +Fix reference leaks in error paths in dictobject.c. Patch by Suman Saha. + +.. + +.. bpo: 13201 +.. date: 7436 +.. nonce: sAT1nr +.. section: Core and Builtins + +Define '==' and '!=' to compare range objects based on the sequence of +values they define (instead of comparing based on object identity). + +.. + +.. bpo: 1294232 +.. date: 7435 +.. nonce: G92P2p +.. section: Core and Builtins + +In a few cases involving metaclass inheritance, the interpreter would +sometimes invoke the wrong metaclass when building a new class object. These +cases now behave correctly. Patch by Daniel Urban. + +.. + +.. bpo: 12753 +.. date: 7434 +.. nonce: jEQ_Mi +.. section: Core and Builtins + +Add support for Unicode name aliases and named sequences. Both +``unicodedata.lookup()`` and '\N{...}' now resolve aliases, and +``unicodedata.lookup()`` resolves named sequences too. + +.. + +.. bpo: 12170 +.. date: 7433 +.. nonce: gjr_dY +.. section: Core and Builtins + +The count(), find(), rfind(), index() and rindex() methods of bytes and +bytearray objects now accept an integer between 0 and 255 as their first +argument. Patch by Petri Lehtinen. + +.. + +.. bpo: 12604 +.. date: 7432 +.. nonce: dDegux +.. section: Core and Builtins + +VTRACE macro expanded to no-op in _sre.c to avoid compiler warnings. Patch +by Josh Triplett and Petri Lehtinen. + +.. + +.. bpo: 12281 +.. date: 7431 +.. nonce: HflTkX +.. section: Core and Builtins + +Rewrite the MBCS codec to handle correctly replace and ignore error handlers +on all Windows versions. The MBCS codec is now supporting all error +handlers, instead of only replace to encode and ignore to decode. + +.. + +.. bpo: 13188 +.. date: 7430 +.. nonce: L3o2X6 +.. section: Core and Builtins + +When called without an explicit traceback argument, generator.throw() now +gets the traceback from the passed exception's ``__traceback__`` attribute. +Patch by Petri Lehtinen. + +.. + +.. bpo: 13146 +.. date: 7429 +.. nonce: DVyExe +.. section: Core and Builtins + +Writing a pyc file is now atomic under POSIX. + +.. + +.. bpo: 7833 +.. date: 7428 +.. nonce: NcSnnJ +.. section: Core and Builtins + +Extension modules built using distutils on Windows will no longer include a +"manifest" to prevent them failing at import time in some embedded +situations. + +.. + +.. bpo: 0 +.. date: 7427 +.. nonce: cOixWQ +.. section: Core and Builtins + +PEP 3151 / issue #12555: reworking the OS and IO exception hierarchy. + +.. + +.. bpo: 0 +.. date: 7426 +.. nonce: jCkmJ2 +.. section: Core and Builtins + +Add internal API for static strings (_Py_identifier et al.). + +.. + +.. bpo: 13063 +.. date: 7425 +.. nonce: M1ythv +.. section: Core and Builtins + +the Windows error ERROR_NO_DATA (numbered 232 and described as "The pipe is +being closed") is now mapped to POSIX errno EPIPE (previously EINVAL). + +.. + +.. bpo: 12911 +.. date: 7424 +.. nonce: eaStd5 +.. section: Core and Builtins + +Fix memory consumption when calculating the repr() of huge tuples or lists. + +.. + +.. bpo: 0 +.. date: 7423 +.. nonce: TX076B +.. section: Core and Builtins + +PEP 393: flexible string representation. Thanks to Torsten Becker for the +initial implementation, and Victor Stinner for various bug fixes. + +.. + +.. bpo: 14081 +.. date: 7422 +.. nonce: RCvMnQ +.. section: Core and Builtins + +The 'sep' and 'maxsplit' parameter to str.split, bytes.split, and +bytearray.split may now be passed as keyword arguments. + +.. + +.. bpo: 13012 +.. date: 7421 +.. nonce: Pgdzzz +.. section: Core and Builtins + +The 'keepends' parameter to str.splitlines may now be passed as a keyword +argument: "my_string.splitlines(keepends=True)". The same change also +applies to bytes.splitlines and bytearray.splitlines. + +.. + +.. bpo: 7732 +.. date: 7420 +.. nonce: lvOdIm +.. section: Core and Builtins + +Don't open a directory as a file anymore while importing a module. Ignore +the direcotry if its name matchs the module name (e.g. "__init__.py") and +raise a ImportError instead. + +.. + +.. bpo: 13021 +.. date: 7419 +.. nonce: Trg0Hn +.. section: Core and Builtins + +Missing decref on an error path. Thanks to Suman Saha for finding the bug +and providing a patch. + +.. + +.. bpo: 12973 +.. date: 7418 +.. nonce: e4aYqm +.. section: Core and Builtins + +Fix overflow checks that relied on undefined behaviour in list_repeat +(listobject.c) and islice_next (itertoolsmodule.c). These bugs caused test +failures with recent versions of Clang. + +.. + +.. bpo: 12904 +.. date: 7417 +.. nonce: qJIaiS +.. section: Core and Builtins + +os.utime, os.futimes, os.lutimes, and os.futimesat now write atime and mtime +with nanosecond precision on modern POSIX platforms. + +.. + +.. bpo: 12802 +.. date: 7416 +.. nonce: 4d4MIG +.. section: Core and Builtins + +the Windows error ERROR_DIRECTORY (numbered 267) is now mapped to POSIX +errno ENOTDIR (previously EINVAL). + +.. + +.. bpo: 9200 +.. date: 7415 +.. nonce: a9QbTm +.. section: Core and Builtins + +The str.is* methods now work with strings that contain non-BMP characters +even in narrow Unicode builds. + +.. + +.. bpo: 12791 +.. date: 7414 +.. nonce: iYGwxc +.. section: Core and Builtins + +Break reference cycles early when a generator exits with an exception. + +.. + +.. bpo: 12773 +.. date: 7413 +.. nonce: cLC6Zy +.. section: Core and Builtins + +Make __doc__ mutable on user-defined classes. + +.. + +.. bpo: 12766 +.. date: 7412 +.. nonce: eWT3Pm +.. section: Core and Builtins + +Raise a ValueError when creating a class with a class variable that +conflicts with a name in __slots__. + +.. + +.. bpo: 12266 +.. date: 7411 +.. nonce: SifsgD +.. section: Core and Builtins + +Fix str.capitalize() to correctly uppercase/lowercase titlecased and cased +non-letter characters. + +.. + +.. bpo: 12732 +.. date: 7410 +.. nonce: x8wK_7 +.. section: Core and Builtins + +In narrow unicode builds, allow Unicode identifiers which fall outside the +BMP. + +.. + +.. bpo: 12575 +.. date: 7409 +.. nonce: gwHPe_ +.. section: Core and Builtins + +Validate user-generated AST before it is compiled. + +.. + +.. bpo: 0 +.. date: 7408 +.. nonce: ySbpe4 +.. section: Core and Builtins + +Make type(None), type(Ellipsis), and type(NotImplemented) callable. They +return the respective singleton instances. + +.. + +.. bpo: 0 +.. date: 7407 +.. nonce: hMvppx +.. section: Core and Builtins + +Forbid summing bytes with sum(). + +.. + +.. bpo: 0 +.. date: 7406 +.. nonce: ekK5i_ +.. section: Core and Builtins + +Verify the types of AST strings and identifiers provided by the user before +compiling them. + +.. + +.. bpo: 12647 +.. date: 7405 +.. nonce: uFzi8V +.. section: Core and Builtins + +The None object now has a __bool__() method that returns False. Formerly, +bool(None) returned False only because of special case logic in +PyObject_IsTrue(). + +.. + +.. bpo: 12579 +.. date: 7404 +.. nonce: 1IV9fF +.. section: Core and Builtins + +str.format_map() now raises a ValueError if used on a format string that +contains positional fields. Initial patch by Julian Berman. + +.. + +.. bpo: 10271 +.. date: 7403 +.. nonce: IgMmt7 +.. section: Core and Builtins + +Allow warnings.showwarning() be any callable. + +.. + +.. bpo: 11627 +.. date: 7402 +.. nonce: ytCeOw +.. section: Core and Builtins + +Fix segfault when __new__ on a exception returns a non-exception class. + +.. + +.. bpo: 12149 +.. date: 7401 +.. nonce: Hjc2bt +.. section: Core and Builtins + +Update the method cache after a type's dictionary gets cleared by the +garbage collector. This fixes a segfault when an instance and its type get +caught in a reference cycle, and the instance's deallocator calls one of the +methods on the type (e.g. when subclassing IOBase). Diagnosis and patch by +Davide Rizzo. + +.. + +.. bpo: 9611 +.. date: 7400 +.. nonce: CZATl_ +.. section: Core and Builtins + +FileIO.read() clamps the length to INT_MAX on Windows. (See also: bpo-9015) + +.. + +.. bpo: 9642 +.. date: 7399 +.. nonce: v4SQuc +.. section: Core and Builtins + +Uniformize the tests on the availability of the mbcs codec, add a new +HAVE_MBCS define. + +.. + +.. bpo: 9642 +.. date: 7398 +.. nonce: 0y1U2x +.. section: Core and Builtins + +Fix filesystem encoding initialization: use the ANSI code page on Windows if +the mbcs codec is not available, and fail with a fatal error if we cannot +get the locale encoding (if nl_langinfo(CODESET) is not available) instead +of using UTF-8. + +.. + +.. bpo: 0 +.. date: 7397 +.. nonce: 4EZiX- +.. section: Core and Builtins + +When a generator yields, do not retain the caller's exception state on the +generator. + +.. + +.. bpo: 12475 +.. date: 7396 +.. nonce: lTWJoJ +.. section: Core and Builtins + +Prevent generators from leaking their exception state into the caller's +frame as they return for the last time. + +.. + +.. bpo: 12291 +.. date: 7395 +.. nonce: cXyNIL +.. section: Core and Builtins + +You can now load multiple marshalled objects from a stream, with other data +interleaved between marshalled objects. + +.. + +.. bpo: 12356 +.. date: 7394 +.. nonce: yh7hqW +.. section: Core and Builtins + +When required positional or keyword-only arguments are not given, produce a +informative error message which includes the name(s) of the missing +arguments. + +.. + +.. bpo: 12370 +.. date: 7393 +.. nonce: qKZlUk +.. section: Core and Builtins + +Fix super with no arguments when __class__ is overriden in the class body. + +.. + +.. bpo: 12084 +.. date: 7392 +.. nonce: n1GJBF +.. section: Core and Builtins + +os.stat on Windows now works properly with relative symbolic links when +called from any directory. + +.. + +.. bpo: 0 +.. date: 7391 +.. nonce: rqj-q7 +.. section: Core and Builtins + +Loosen type restrictions on the __dir__ method. __dir__ can now return any +sequence, which will be converted to a list and sorted by dir(). + +.. + +.. bpo: 12265 +.. date: 7390 +.. nonce: I2_oGy +.. section: Core and Builtins + +Make error messages produced by passing an invalid set of arguments to a +function more informative. + +.. + +.. bpo: 12225 +.. date: 7389 +.. nonce: VVvUqO +.. section: Core and Builtins + +Still allow Python to build if Python is not in its hg repo or mercurial is +not installed. + +.. + +.. bpo: 1195 +.. date: 7388 +.. nonce: Tp_J8Y +.. section: Core and Builtins + +my_fgets() now always clears errors before calling fgets(). Fix the +following case: sys.stdin.read() stopped with CTRL+d (end of file), +raw_input() interrupted by CTRL+c. + +.. + +.. bpo: 12216 +.. date: 7387 +.. nonce: Edw6xv +.. section: Core and Builtins + +Allow unexpected EOF errors to happen on any line of the file. + +.. + +.. bpo: 12199 +.. date: 7386 +.. nonce: oPGGQc +.. section: Core and Builtins + +The TryExcept and TryFinally and AST nodes have been unified into a Try +node. + +.. + +.. bpo: 9670 +.. date: 7385 +.. nonce: D4p50W +.. section: Core and Builtins + +Increase the default stack size for secondary threads on Mac OS X and +FreeBSD to reduce the chances of a crash instead of a "maximum recursion +depth" RuntimeError exception. (patch by Ronald Oussoren) + +.. + +.. bpo: 12106 +.. date: 7384 +.. nonce: 9GzRO0 +.. section: Core and Builtins + +The use of the multiple-with shorthand syntax is now reflected in the AST. + +.. + +.. bpo: 12190 +.. date: 7383 +.. nonce: riY6Gl +.. section: Core and Builtins + +Try to use the same filename object when compiling unmarshalling a code +objects in the same file. + +.. + +.. bpo: 12166 +.. date: 7382 +.. nonce: na7Vys +.. section: Core and Builtins + +Move implementations of dir() specialized for various types into the +__dir__() methods of those types. + +.. + +.. bpo: 5715 +.. date: 7381 +.. nonce: Vs9Y33 +.. section: Core and Builtins + +In socketserver, close the server socket in the child process. + +.. + +.. bpo: 0 +.. date: 7380 +.. nonce: n-R2nr +.. section: Core and Builtins + +Correct lookup of __dir__ on objects. Among other things, this causes errors +besides AttributeError found on lookup to be propagated. + +.. + +.. bpo: 12060 +.. date: 7379 +.. nonce: g_FUU8 +.. section: Core and Builtins + +Use sig_atomic_t type and volatile keyword in the signal module. Patch +written by Charles-François Natali. + +.. + +.. bpo: 1746656 +.. date: 7378 +.. nonce: tqS2BI +.. section: Core and Builtins + +Added the if_nameindex, if_indextoname, if_nametoindex methods to the socket +module. + +.. + +.. bpo: 12044 +.. date: 7377 +.. nonce: BmuRsU +.. section: Core and Builtins + +Fixed subprocess.Popen when used as a context manager to wait for the +process to end when exiting the context to avoid unintentionally leaving +zombie processes around. + +.. + +.. bpo: 1195 +.. date: 7376 +.. nonce: rUvlec +.. section: Core and Builtins + +Fix input() if it is interrupted by CTRL+d and then CTRL+c, clear the end- +of-file indicator after CTRL+d. + +.. + +.. bpo: 1856 +.. date: 7375 +.. nonce: rNKlZ0 +.. section: Core and Builtins + +Avoid crashes and lockups when daemon threads run while the interpreter is +shutting down; instead, these threads are now killed when they try to take +the GIL. + +.. + +.. bpo: 9756 +.. date: 7374 +.. nonce: L962XN +.. section: Core and Builtins + +When calling a method descriptor or a slot wrapper descriptor, the check of +the object type doesn't read the __class__ attribute anymore. Fix a crash if +a class override its __class__ attribute (e.g. a proxy of the str type). +Patch written by Andreas Stührk. + +.. + +.. bpo: 10517 +.. date: 7373 +.. nonce: eHRgPe +.. section: Core and Builtins + +After fork(), reinitialize the TLS used by the PyGILState_* APIs, to avoid a +crash with the pthread implementation in RHEL 5. Patch by Charles-François +Natali. + +.. + +.. bpo: 10914 +.. date: 7372 +.. nonce: awEeE9 +.. section: Core and Builtins + +Initialize correctly the filesystem codec when creating a new subinterpreter +to fix a bootstrap issue with codecs implemented in Python, as the +ISO-8859-15 codec. + +.. + +.. bpo: 11918 +.. date: 7371 +.. nonce: yWsyik +.. section: Core and Builtins + +OS/2 and VMS are no more supported because of the lack of maintainer. + +.. + +.. bpo: 6780 +.. date: 7370 +.. nonce: MS1yFK +.. section: Core and Builtins + +fix starts/endswith error message to mention that tuples are accepted too. + +.. + +.. bpo: 5057 +.. date: 7369 +.. nonce: IXmDaW +.. section: Core and Builtins + +fix a bug in the peepholer that led to non-portable pyc files between narrow +and wide builds while optimizing BINARY_SUBSCR on non-BMP chars (e.g. +"\U00012345"[0]). + +.. + +.. bpo: 11845 +.. date: 7368 +.. nonce: ngWKb1 +.. section: Core and Builtins + +Fix typo in rangeobject.c that caused a crash in compute_slice_indices. +Patch by Daniel Urban. + +.. + +.. bpo: 5673 +.. date: 7367 +.. nonce: dGp29g +.. section: Core and Builtins + +Added a `timeout` keyword argument to subprocess.Popen.wait, +subprocess.Popen.communicated, subprocess.call, subprocess.check_call, and +subprocess.check_output. If the blocking operation takes more than +`timeout` seconds, the `subprocess.TimeoutExpired` exception is raised. + +.. + +.. bpo: 11650 +.. date: 7366 +.. nonce: r47Jvk +.. section: Core and Builtins + +PyOS_StdioReadline() retries fgets() if it was interrupted (EINTR), for +example if the program is stopped with CTRL+z on Mac OS X. Patch written by +Charles-Francois Natali. + +.. + +.. bpo: 9319 +.. date: 7365 +.. nonce: 5iFHdl +.. section: Core and Builtins + +Include the filename in "Non-UTF8 code ..." syntax error. + +.. + +.. bpo: 10785 +.. date: 7364 +.. nonce: KbV-Sq +.. section: Core and Builtins + +Store the filename as Unicode in the Python parser. + +.. + +.. bpo: 11619 +.. date: 7363 +.. nonce: EpEKh2 +.. section: Core and Builtins + +_PyImport_LoadDynamicModule() doesn't encode the path to bytes on Windows. + +.. + +.. bpo: 10998 +.. date: 7362 +.. nonce: icOAMv +.. section: Core and Builtins + +Remove mentions of -Q, sys.flags.division_warning and Py_DivisionWarningFlag +left over from Python 2. + +.. + +.. bpo: 11244 +.. date: 7361 +.. nonce: TiVSZZ +.. section: Core and Builtins + +Remove an unnecessary peepholer check that was preventing negative zeros +from being constant-folded properly. + +.. + +.. bpo: 11395 +.. date: 7360 +.. nonce: Vuabxg +.. section: Core and Builtins + +io.FileIO().write() clamps the data length to 32,767 bytes on Windows if the +file is a TTY to workaround a Windows bug. The Windows console returns an +error (12: not enough space error) on writing into stdout if stdout mode is +binary and the length is greater than 66,000 bytes (or less, depending on +heap usage). + +.. + +.. bpo: 11320 +.. date: 7359 +.. nonce: -ThQCa +.. section: Core and Builtins + +fix bogus memory management in Modules/getpath.c, leading to a possible +crash when calling Py_SetPath(). + +.. + +.. bpo: 11432 +.. date: 7358 +.. nonce: BDhvsw +.. section: Core and Builtins + +A bug was introduced in subprocess.Popen on posix systems with 3.2.0 where +the stdout or stderr file descriptor being the same as the stdin file +descriptor would raise an exception. webbrowser.open would fail. fixed. + +.. + +.. bpo: 9856 +.. date: 7357 +.. nonce: i962fk +.. section: Core and Builtins + +Change object.__format__ with a non-empty format string to be a +DeprecationWarning. In 3.2 it was a PendingDeprecationWarning. In 3.4 it +will be a TypeError. + +.. + +.. bpo: 11244 +.. date: 7356 +.. nonce: lpiV2g +.. section: Core and Builtins + +The peephole optimizer is now able to constant-fold arbitrarily complex +expressions. This also fixes a 3.2 regression where operations involving +negative numbers were not constant-folded. + +.. + +.. bpo: 11450 +.. date: 7355 +.. nonce: ulI9xJ +.. section: Core and Builtins + +Don't truncate hg version info in Py_GetBuildInfo() when there are many tags +(e.g. when using mq). Patch by Nadeem Vawda. + +.. + +.. bpo: 11335 +.. date: 7354 +.. nonce: zNrvqZ +.. section: Core and Builtins + +Fixed a memory leak in list.sort when the key function throws an exception. + +.. + +.. bpo: 8923 +.. date: 7353 +.. nonce: Z1M55I +.. section: Core and Builtins + +When a string is encoded to UTF-8 in strict mode, the result is cached into +the object. Examples: str.encode(), str.encode('utf-8'), +PyUnicode_AsUTF8String() and PyUnicode_AsEncodedString(unicode, "utf-8", +NULL). + +.. + +.. bpo: 10829 +.. date: 7352 +.. nonce: FxQTnG +.. section: Core and Builtins + +Refactor PyUnicode_FromFormat(), use the same function to parse the format +string in the 3 steps, fix crashs on invalid format strings. + +.. + +.. bpo: 13007 +.. date: 7351 +.. nonce: 6OcUii +.. section: Core and Builtins + +whichdb should recognize gdbm 1.9 magic numbers. + +.. + +.. bpo: 11286 +.. date: 7350 +.. nonce: gH7JY2 +.. section: Core and Builtins + +Raise a ValueError from calling PyMemoryView_FromBuffer with a buffer struct +having a NULL data pointer. + +.. + +.. bpo: 11272 +.. date: 7349 +.. nonce: TunnAk +.. section: Core and Builtins + +On Windows, input() strips '\r' (and not only '\n'), and sys.stdin uses +universal newline (replace '\r\n' by '\n'). + +.. + +.. bpo: 11828 +.. date: 7348 +.. nonce: Lc13S7 +.. section: Core and Builtins + +startswith and endswith now accept None as slice index. Patch by Torsten +Becker. + +.. + +.. bpo: 11168 +.. date: 7347 +.. nonce: 15IHEN +.. section: Core and Builtins + +Remove filename debug variable from PyEval_EvalFrameEx(). It encoded the +Unicode filename to UTF-8, but the encoding fails on undecodable filename +(on surrogate characters) which raises an unexpected UnicodeEncodeError on +recursion limit. + +.. + +.. bpo: 11187 +.. date: 7346 +.. nonce: RF722f +.. section: Core and Builtins + +Remove bootstrap code (use ASCII) of PyUnicode_AsEncodedString(), it was +replaced by a better fallback (use the locale encoding) in +PyUnicode_EncodeFSDefault(). + +.. + +.. bpo: 0 +.. date: 7345 +.. nonce: fny7_S +.. section: Core and Builtins + +Check for NULL result in PyType_FromSpec. + +.. + +.. bpo: 10516 +.. date: 7344 +.. nonce: Dx9IO6 +.. section: Core and Builtins + +New copy() and clear() methods for lists and bytearrays. + +.. + +.. bpo: 11386 +.. date: 7343 +.. nonce: wrrB8K +.. section: Core and Builtins + +bytearray.pop() now throws IndexError when the bytearray is empty, instead +of OverflowError. + +.. + +.. bpo: 12380 +.. date: 7342 +.. nonce: sl5Ilr +.. section: Core and Builtins + +The rjust, ljust and center methods of bytes and bytearray now accept a +bytearray argument. + +.. + +.. bpo: 14195 +.. date: 7341 +.. nonce: XpCJYQ +.. section: Library + +An issue that caused weakref.WeakSet instances to incorrectly return True +for a WeakSet instance 'a' in both 'a < a' and 'a > a' has been fixed. + +.. + +.. bpo: 14166 +.. date: 7340 +.. nonce: fcft89 +.. section: Library + +Pickler objects now have an optional ``dispatch_table`` attribute which +allows to set custom per-pickler reduction functions. Patch by sbt. + +.. + +.. bpo: 14177 +.. date: 7339 +.. nonce: YskuFD +.. section: Library + +marshal.loads() now raises TypeError when given an unicode string. Patch by +Guilherme Gonçalves. + +.. + +.. bpo: 13550 +.. date: 7338 +.. nonce: hExG3C +.. section: Library + +Remove the debug machinery from the threading module: remove verbose +arguments from all threading classes and functions. + +.. + +.. bpo: 14159 +.. date: 7337 +.. nonce: bKhLkF +.. section: Library + +Fix the len() of weak containers (WeakSet, WeakKeyDictionary, +WeakValueDictionary) to return a better approximation when some objects are +dead or dying. Moreover, the implementation is now O(1) rather than O(n). + +.. + +.. bpo: 11841 +.. date: 7336 +.. nonce: YAW9qW +.. section: Library + +Fix comparison bug with 'rc' versions in packaging.version. Patch by Filip +Gruszczyński. + +.. + +.. bpo: 6884 +.. date: 7335 +.. nonce: -lAxmo +.. section: Library + +Fix long-standing bugs with MANIFEST.in parsing in distutils on Windows. +Also fixed in packaging. + +.. + +.. bpo: 8033 +.. date: 7334 +.. nonce: vZ-AWU +.. section: Library + +sqlite3: Fix 64-bit integer handling in user functions on 32-bit +architectures. Initial patch by Philippe Devalkeneer. + +.. + +.. bpo: 0 +.. date: 7333 +.. nonce: Apd_xz +.. section: Library + +HTMLParser is now able to handle slashes in the start tag. + +.. + +.. bpo: 13641 +.. date: 7332 +.. nonce: 8ukIOL +.. section: Library + +Decoding functions in the base64 module now accept ASCII-only unicode +strings. Patch by Catalin Iacob. + +.. + +.. bpo: 14043 +.. date: 7331 +.. nonce: _NfA3s +.. section: Library + +Speed up importlib's _FileFinder by at least 8x, and add a new +importlib.invalidate_caches() function. + +.. + +.. bpo: 14001 +.. date: 7330 +.. nonce: Za_h38 +.. section: Library + +CVE-2012-0845: xmlrpc: Fix an endless loop in SimpleXMLRPCServer upon +malformed POST request. + +.. + +.. bpo: 13961 +.. date: 7329 +.. nonce: -8iWm5 +.. section: Library + +Move importlib over to using os.replace() for atomic renaming. + +.. + +.. bpo: 0 +.. date: 7328 +.. nonce: lz9SSu +.. section: Library + +Do away with ambiguous level values (as suggested by PEP 328) in +importlib.__import__() by raising ValueError when level < 0. + +.. + +.. bpo: 2489 +.. date: 7327 +.. nonce: EENP1J +.. section: Library + +pty.spawn could consume 100% cpu when it encountered an EOF. + +.. + +.. bpo: 13014 +.. date: 7326 +.. nonce: bfZLHS +.. section: Library + +Fix a possible reference leak in SSLSocket.getpeercert(). + +.. + +.. bpo: 13777 +.. date: 7325 +.. nonce: SsSNVv +.. section: Library + +Add PF_SYSTEM sockets on OS X. Patch by Michael Goderbauer. + +.. + +.. bpo: 13015 +.. date: 7324 +.. nonce: bxws6S +.. section: Library + +Fix a possible reference leak in defaultdict.__repr__. Patch by Suman Saha. + +.. + +.. bpo: 1326113 +.. date: 7323 +.. nonce: JuJ1F3 +.. section: Library + +distutils' and packaging's build_ext commands option now correctly parses +multiple values (separated by whitespace or commas) given to their +--libraries option. + +.. + +.. bpo: 10287 +.. date: 7322 +.. nonce: L2-2gu +.. section: Library + +nntplib now queries the server's CAPABILITIES first before sending MODE +READER, and only sends it if not already in READER mode. Patch by Hynek +Schlawack. + +.. + +.. bpo: 13993 +.. date: 7321 +.. nonce: YbS9iY +.. section: Library + +HTMLParser is now able to handle broken end tags when strict=False. + +.. + +.. bpo: 13930 +.. date: 7320 +.. nonce: 566-Kx +.. section: Library + +lib2to3 now supports writing converted output files to another directory +tree as well as copying unchanged files and altering the file suffix. + +.. + +.. bpo: 9750 +.. date: 7319 +.. nonce: CsQyVM +.. section: Library + +Fix sqlite3.Connection.iterdump on tables and fields with a name that is a +keyword or contains quotes. Patch by Marko Kohtala. + +.. + +.. bpo: 10287 +.. date: 7318 +.. nonce: CoOp6o +.. section: Library + +nntplib now queries the server's CAPABILITIES again after authenticating +(since the result may change, according to RFC 4643). Patch by Hynek +Schlawack. + +.. + +.. bpo: 13590 +.. date: 7317 +.. nonce: b6Qvrj +.. section: Library + +On OS X 10.7 and 10.6 with Xcode 4.2, building Distutils-based packages with +C extension modules may fail because Apple has removed gcc-4.2, the version +used to build python.org 64-bit/32-bit Pythons. If the user does not +explicitly override the default C compiler by setting the CC environment +variable, Distutils will now attempt to compile extension modules with clang +if gcc-4.2 is required but not found. Also as a convenience, if the user +does explicitly set CC, substitute its value as the default compiler in the +Distutils LDSHARED configuration variable for OS X. (Note, the python.org +32-bit-only Pythons use gcc-4.0 and the 10.4u SDK, neither of which are +available in Xcode 4. This change does not attempt to override settings to +support their use with Xcode 4.) + +.. + +.. bpo: 13960 +.. date: 7316 +.. nonce: WgabCW +.. section: Library + +HTMLParser is now able to handle broken comments when strict=False. + +.. + +.. bpo: 0 +.. date: 7315 +.. nonce: rEkvHU +.. section: Library + +When '' is a path (e.g. in sys.path), make sure __file__ uses the current +working directory instead of '' in importlib. + +.. + +.. bpo: 13609 +.. date: 7314 +.. nonce: QHLCY9 +.. section: Library + +Add two functions to query the terminal size: os.get_terminal_size (low +level) and shutil.get_terminal_size (high level). Patch by Zbigniew +Jędrzejewski-Szmek. + +.. + +.. bpo: 13845 +.. date: 7313 +.. nonce: tUl_Fj +.. section: Library + +On Windows, time.time() now uses GetSystemTimeAsFileTime() instead of +ftime() to have a resolution of 100 ns instead of 1 ms (the clock accuracy +is between 0.5 ms and 15 ms). + +.. + +.. bpo: 13846 +.. date: 7312 +.. nonce: jybi5V +.. section: Library + +Add time.monotonic(), monotonic clock. + +.. + +.. bpo: 8184 +.. date: 7311 +.. nonce: iGHxT1 +.. section: Library + +multiprocessing: On Windows, don't set SO_REUSEADDR on Connection sockets, +and set FILE_FLAG_FIRST_PIPE_INSTANCE on named pipes, to make sure two +listeners can't bind to the same socket/pipe (or any existing socket/pipe). + +.. + +.. bpo: 10811 +.. date: 7310 +.. nonce: m6b_ZC +.. section: Library + +Fix recursive usage of cursors. Instead of crashing, raise a +ProgrammingError now. + +.. + +.. bpo: 13734 +.. date: 7309 +.. nonce: oNGx9P +.. section: Library + +Add os.fwalk(), a directory walking function yielding file descriptors. + +.. + +.. bpo: 2945 +.. date: 7308 +.. nonce: QZCfeH +.. section: Library + +Make the distutils upload command aware of bdist_rpm products. + +.. + +.. bpo: 13712 +.. date: 7307 +.. nonce: TZT3QQ +.. section: Library + +pysetup create should not convert package_data to extra_files. + +.. + +.. bpo: 11805 +.. date: 7306 +.. nonce: VPRRt7 +.. section: Library + +package_data in setup.cfg should allow more than one value. + +.. + +.. bpo: 13676 +.. date: 7305 +.. nonce: IwPgKL +.. section: Library + +Handle strings with embedded zeros correctly in sqlite3. + +.. + +.. bpo: 8828 +.. date: 7304 +.. nonce: OhtMcM +.. section: Library + +Add new function os.replace(), for cross-platform renaming with overwriting. + +.. + +.. bpo: 13848 +.. date: 7303 +.. nonce: xXW1hU +.. section: Library + +open() and the FileIO constructor now check for NUL characters in the file +name. Patch by Hynek Schlawack. + +.. + +.. bpo: 13806 +.. date: 7302 +.. nonce: Y34Lg3 +.. section: Library + +The size check in audioop decompression functions was too strict and could +reject valid compressed data. Patch by Oleg Plakhotnyuk. + +.. + +.. bpo: 13812 +.. date: 7301 +.. nonce: NIY-Po +.. section: Library + +When a multiprocessing Process child raises an exception, flush stderr after +printing the exception traceback. + +.. + +.. bpo: 13885 +.. date: 7300 +.. nonce: fTNryk +.. section: Library + +CVE-2011-3389: the _ssl module would always disable the CBC IV attack +countermeasure. + +.. + +.. bpo: 13847 +.. date: 7299 +.. nonce: Ik2pgR +.. section: Library + +time.localtime() and time.gmtime() now raise an OSError instead of +ValueError on failure. time.ctime() and time.asctime() now raises an OSError +if localtime() failed. time.clock() now raises a RuntimeError if the +processor time used is not available or its value cannot be represented + +.. + +.. bpo: 13772 +.. date: 7298 +.. nonce: KVupSi +.. section: Library + +In os.symlink() under Windows, do not try to guess the link target's type +(file or directory). The detection was buggy and made the call non-atomic +(therefore prone to race conditions). + +.. + +.. bpo: 6631 +.. date: 7297 +.. nonce: FyxhCp +.. section: Library + +Disallow relative file paths in urllib urlopen methods. + +.. + +.. bpo: 13722 +.. date: 7296 +.. nonce: n4Xufh +.. section: Library + +Avoid silencing ImportErrors when initializing the codecs registry. + +.. + +.. bpo: 13781 +.. date: 7295 +.. nonce: Bx-sIy +.. section: Library + +Fix GzipFile bug that caused an exception to be raised when opening for +writing using a fileobj returned by os.fdopen(). + +.. + +.. bpo: 13803 +.. date: 7294 +.. nonce: WnPIts +.. section: Library + +Under Solaris, distutils doesn't include bitness in the directory name. + +.. + +.. bpo: 10278 +.. date: 7293 +.. nonce: cLI3aW +.. section: Library + +Add time.wallclock() function, monotonic clock. + +.. + +.. bpo: 13809 +.. date: 7292 +.. nonce: zwqMZw +.. section: Library + +Fix regression where bz2 module wouldn't work when threads are disabled. +Original patch by Amaury Forgeot d'Arc. + +.. + +.. bpo: 13589 +.. date: 7291 +.. nonce: sQsnEf +.. section: Library + +Fix some serialization primitives in the aifc module. Patch by Oleg +Plakhotnyuk. + +.. + +.. bpo: 13642 +.. date: 7290 +.. nonce: 4YVaQS +.. section: Library + +Unquote before b64encoding user:password during Basic Authentication. Patch +contributed by Joonas Kuorilehto. + +.. + +.. bpo: 12364 +.. date: 7289 +.. nonce: OnVual +.. section: Library + +Fix a hang in concurrent.futures.ProcessPoolExecutor. The hang would occur +when retrieving the result of a scheduled future after the executor had been +shut down. + +.. + +.. bpo: 13502 +.. date: 7288 +.. nonce: Dn8qtt +.. section: Library + +threading: Fix a race condition in Event.wait() that made it return False +when the event was set and cleared right after. + +.. + +.. bpo: 9993 +.. date: 7287 +.. nonce: _cXvpp +.. section: Library + +When the source and destination are on different filesystems, and the source +is a symlink, shutil.move() now recreates a symlink on the destination +instead of copying the file contents. Patch by Jonathan Niehof and Hynek +Schlawack. + +.. + +.. bpo: 12926 +.. date: 7286 +.. nonce: MSqOB2 +.. section: Library + +Fix a bug in tarfile's link extraction. + +.. + +.. bpo: 13696 +.. date: 7285 +.. nonce: bBu5Fk +.. section: Library + +Fix the 302 Relative URL Redirection problem. + +.. + +.. bpo: 13636 +.. date: 7284 +.. nonce: eWRf1t +.. section: Library + +Weak ciphers are now disabled by default in the ssl module (except when +SSLv2 is explicitly asked for). + +.. + +.. bpo: 12715 +.. date: 7283 +.. nonce: RqYLXI +.. section: Library + +Add an optional symlinks argument to shutil functions (copyfile, copymode, +copystat, copy, copy2). When that parameter is true, symlinks aren't +dereferenced and the operation instead acts on the symlink itself (or +creates one, if relevant). Patch by Hynek Schlawack. + +.. + +.. bpo: 0 +.. date: 7282 +.. nonce: gYE9q- +.. section: Library + +Add a flags parameter to select.epoll. + +.. + +.. bpo: 13626 +.. date: 7281 +.. nonce: we7C_R +.. section: Library + +Add support for SSL Diffie-Hellman key exchange, through the +SSLContext.load_dh_params() method and the ssl.OP_SINGLE_DH_USE option. + +.. + +.. bpo: 11006 +.. date: 7280 +.. nonce: 6KuDUa +.. section: Library + +Don't issue low level warning in subprocess when pipe2() fails. + +.. + +.. bpo: 13620 +.. date: 7279 +.. nonce: os2NdM +.. section: Library + +Support for Chrome browser in webbrowser. Patch contributed by Arnaud +Calmettes. + +.. + +.. bpo: 11829 +.. date: 7278 +.. nonce: vH6FxA +.. section: Library + +Fix code execution holes in inspect.getattr_static for metaclasses with +metaclasses. Patch by Andreas Stührk. + +.. + +.. bpo: 12708 +.. date: 7277 +.. nonce: AarraR +.. section: Library + +Add starmap() and starmap_async() methods (similar to itertools.starmap()) +to multiprocessing.Pool. Patch by Hynek Schlawack. + +.. + +.. bpo: 1785 +.. date: 7276 +.. nonce: DKL5I8 +.. section: Library + +Fix inspect and pydoc with misbehaving descriptors. + +.. + +.. bpo: 13637 +.. date: 7275 +.. nonce: 3C-33m +.. section: Library + +"a2b" functions in the binascii module now accept ASCII-only unicode +strings. + +.. + +.. bpo: 13634 +.. date: 7274 +.. nonce: dBF4qW +.. section: Library + +Add support for querying and disabling SSL compression. + +.. + +.. bpo: 13627 +.. date: 7273 +.. nonce: Lk4xYf +.. section: Library + +Add support for SSL Elliptic Curve-based Diffie-Hellman key exchange, +through the SSLContext.set_ecdh_curve() method and the +ssl.OP_SINGLE_ECDH_USE option. + +.. + +.. bpo: 13635 +.. date: 7272 +.. nonce: j9OeLf +.. section: Library + +Add ssl.OP_CIPHER_SERVER_PREFERENCE, so that SSL servers choose the cipher +based on their own preferences, rather than on the client's. + +.. + +.. bpo: 11813 +.. date: 7271 +.. nonce: _NBHv5 +.. section: Library + +Fix inspect.getattr_static for modules. Patch by Andreas Stührk. + +.. + +.. bpo: 7502 +.. date: 7270 +.. nonce: lIMyju +.. section: Library + +Fix equality comparison for DocTestCase instances. Patch by Cédric Krier. + +.. + +.. bpo: 11870 +.. date: 7269 +.. nonce: 85bAB9 +.. section: Library + +threading: Properly reinitialize threads internal locks and condition +variables to avoid deadlocks in child processes. + +.. + +.. bpo: 8035 +.. date: 7268 +.. nonce: yzn_Oa +.. section: Library + +urllib: Fix a bug where the client could remain stuck after a redirection or +an error. + +.. + +.. bpo: 13560 +.. date: 7267 +.. nonce: ZOg9KG +.. section: Library + +os.strerror() now uses the current locale encoding instead of UTF-8. + +.. + +.. bpo: 8373 +.. date: 7266 +.. nonce: F6lhZW +.. section: Library + +The filesystem path of AF_UNIX sockets now uses the filesystem encoding and +the surrogateescape error handler, rather than UTF-8. Patch by David +Watson. + +.. + +.. bpo: 10350 +.. date: 7265 +.. nonce: GIPImg +.. section: Library + +Read and save errno before calling a function which might overwrite it. +Original patch by Hallvard B Furuseth. + +.. + +.. bpo: 11610 +.. date: 7264 +.. nonce: 3IqDr5 +.. section: Library + +Introduce a more general way to declare abstract properties. + +.. + +.. bpo: 13591 +.. date: 7263 +.. nonce: QeA9GX +.. section: Library + +A bug in importlib has been fixed that caused import_module to load a module +twice. + +.. + +.. bpo: 13449 +.. date: 7262 +.. nonce: Iuwk5B +.. section: Library + +sched.scheduler.run() method has a new "blocking" parameter which when set +to False makes run() execute the scheduled events due to expire soonest (if +any) and then return. Patch by Giampaolo Rodolà. + +.. + +.. bpo: 8684 +.. date: 7261 +.. nonce: 1mOWHH +.. section: Library + +sched.scheduler class can be safely used in multi-threaded environments. +Patch by Josiah Carlson and Giampaolo Rodolà. + +.. + +.. bpo: 0 +.. date: 7260 +.. nonce: DjTC3I +.. section: Library + +Alias resource.error to OSError ala PEP 3151. + +.. + +.. bpo: 5689 +.. date: 7259 +.. nonce: CDjEGM +.. section: Library + +Add support for lzma compression to the tarfile module. + +.. + +.. bpo: 13248 +.. date: 7258 +.. nonce: kTLQyB +.. section: Library + +Turn 3.2's PendingDeprecationWarning into 3.3's DeprecationWarning. It +covers 'cgi.escape', 'importlib.abc.PyLoader', 'importlib.abc.PyPycLoader', +'nntplib.NNTP.xgtitle', 'nntplib.NNTP.xpath', and private attributes of +'smtpd.SMTPChannel'. + +.. + +.. bpo: 5905 +.. date: 7257 +.. nonce: fKvZt3 +.. section: Library + +time.strftime() is now using the current locale encoding, instead of UTF-8, +if the wcsftime() function is not available. (See also: bpo-13560) + +.. + +.. bpo: 13464 +.. date: 7256 +.. nonce: RVb-lP +.. section: Library + +Add a readinto() method to http.client.HTTPResponse. Patch by Jon Kuhn. + +.. + +.. bpo: 0 +.. date: 7255 +.. nonce: xZO873 +.. section: Library + +tarfile.py: Correctly detect bzip2 compressed streams with blocksizes other +than 900k. + +.. + +.. bpo: 13439 +.. date: 7254 +.. nonce: H8wdOt +.. section: Library + +Fix many errors in turtle docstrings. + +.. + +.. bpo: 6715 +.. date: 7253 +.. nonce: _I5wbV +.. section: Library + +Add a module 'lzma' for compression using the LZMA algorithm. Thanks to Per +Øyvind Karlsen for the initial implementation. + +.. + +.. bpo: 13487 +.. date: 7252 +.. nonce: tnCtZi +.. section: Library + +Make inspect.getmodule robust against changes done to sys.modules while it +is iterating over it. + +.. + +.. bpo: 12618 +.. date: 7251 +.. nonce: 4vfViQ +.. section: Library + +Fix a bug that prevented py_compile from creating byte compiled files in the +current directory. Initial patch by Sjoerd de Vries. + +.. + +.. bpo: 13444 +.. date: 7250 +.. nonce: 05tB38 +.. section: Library + +When stdout has been closed explicitly, we should not attempt to flush it at +shutdown and print an error. + +.. + +.. bpo: 12567 +.. date: 7249 +.. nonce: UNWMcq +.. section: Library + +The curses module uses Unicode functions for Unicode arguments when it is +linked to the ncurses library. It encodes also Unicode strings to the locale +encoding instead of UTF-8. + +.. + +.. bpo: 12856 +.. date: 7248 +.. nonce: 7eIfN8 +.. section: Library + +Ensure child processes do not inherit the parent's random seed for filename +generation in the tempfile module. Patch by Brian Harring. + +.. + +.. bpo: 9957 +.. date: 7247 +.. nonce: wDigEk +.. section: Library + +SpooledTemporaryFile.truncate() now accepts an optional size parameter, as +other file-like objects. Patch by Ryan Kelly. + +.. + +.. bpo: 13458 +.. date: 7246 +.. nonce: EHyzED +.. section: Library + +Fix a memory leak in the ssl module when decoding a certificate with a +subjectAltName. Patch by Robert Xiao. + +.. + +.. bpo: 13415 +.. date: 7245 +.. nonce: Ap8joO +.. section: Library + +os.unsetenv() doesn't ignore errors anymore. + +.. + +.. bpo: 13245 +.. date: 7244 +.. nonce: FxSKtK +.. section: Library + +sched.scheduler class constructor's timefunc and delayfunct parameters are +now optional. scheduler.enter and scheduler.enterabs methods gained a new +kwargs parameter. Patch contributed by Chris Clark. + +.. + +.. bpo: 12328 +.. date: 7243 +.. nonce: z7LwM4 +.. section: Library + +Under Windows, refactor handling of Ctrl-C events and make +_multiprocessing.win32.WaitForMultipleObjects interruptible when the +wait_flag parameter is false. Patch by sbt. + +.. + +.. bpo: 13322 +.. date: 7242 +.. nonce: Ect89q +.. section: Library + +Fix BufferedWriter.write() to ensure that BlockingIOError is raised when the +wrapped raw file is non-blocking and the write would block. Previous code +assumed that the raw write() would raise BlockingIOError, but +RawIOBase.write() is defined to returned None when the call would block. +Patch by sbt. + +.. + +.. bpo: 13358 +.. date: 7241 +.. nonce: kPO1ja +.. section: Library + +HTMLParser now calls handle_data only once for each CDATA. + +.. + +.. bpo: 4147 +.. date: 7240 +.. nonce: wQbNcw +.. section: Library + +minidom's toprettyxml no longer adds whitespace around a text node when it +is the only child of an element. Initial patch by Dan Kenigsberg. + +.. + +.. bpo: 13374 +.. date: 7239 +.. nonce: A6PdRD +.. section: Library + +The Windows bytes API has been deprecated in the os module. Use Unicode +filenames instead of bytes filenames to not depend on the ANSI code page +anymore and to support any filename. + +.. + +.. bpo: 13297 +.. date: 7238 +.. nonce: uo2s_p +.. section: Library + +Use bytes type to send and receive binary data through XMLRPC. + +.. + +.. bpo: 6397 +.. date: 7237 +.. nonce: gywYD- +.. section: Library + +Support "/dev/poll" polling objects in select module, under Solaris & +derivatives. + +.. + +.. bpo: 1745761 +.. date: 7236 +.. nonce: zfO1ng +.. section: Library + +HTMLParser now correctly handles non-valid attributes, including adjacent +and unquoted attributes. (See also: bpo-755670, bpo-13357, bpo-12629, +bpo-1200313) + +.. + +.. bpo: 13193 +.. date: 7235 +.. nonce: fxIZuD +.. section: Library + +Fix distutils.filelist.FileList and packaging.manifest.Manifest under +Windows. + +.. + +.. bpo: 13384 +.. date: 7234 +.. nonce: wx_SPZ +.. section: Library + +Remove unnecessary __future__ import in Lib/random.py + +.. + +.. bpo: 13149 +.. date: 7233 +.. nonce: wy6pt7 +.. section: Library + +Speed up append-only StringIO objects. + +.. + +.. bpo: 13373 +.. date: 7232 +.. nonce: 8wM3bP +.. section: Library + +multiprocessing.Queue.get() could sometimes block indefinitely when called +with a timeout. Patch by Arnaud Ysmal. + +.. + +.. bpo: 13254 +.. date: 7231 +.. nonce: CKJxT0 +.. section: Library + +Fix Maildir initialization so that maildir contents are read correctly. + +.. + +.. bpo: 3067 +.. date: 7230 +.. nonce: IpKDf8 +.. section: Library + +locale.setlocale() now raises TypeError if the second argument is an invalid +iterable. Its documentation and docstring were also updated. Initial patch +by Jyrki Pulliainen. + +.. + +.. bpo: 13140 +.. date: 7229 +.. nonce: EguPSD +.. section: Library + +Fix the daemon_threads attribute of ThreadingMixIn. + +.. + +.. bpo: 13339 +.. date: 7228 +.. nonce: 3ty5ip +.. section: Library + +Fix compile error in posixmodule.c due to missing semicolon. Thanks to +Robert Xiao. + +.. + +.. bpo: 0 +.. date: 7227 +.. nonce: QSo5ij +.. section: Library + +Byte compilation in packaging is now isolated from the calling Python -B or +-O options, instead of being disallowed under -B or buggy under -O. + +.. + +.. bpo: 10570 +.. date: 7226 +.. nonce: jvnBd5 +.. section: Library + +curses.putp() and curses.tparm() are now expecting a byte string, instead of +a Unicode string. + +.. + +.. bpo: 13295 +.. date: 7225 +.. nonce: wTSBvE +.. section: Library + +http.server now produces valid HTML 4.01 strict. + +.. + +.. bpo: 2892 +.. date: 7224 +.. nonce: kugtRq +.. section: Library + +preserve iterparse events in case of SyntaxError. + +.. + +.. bpo: 13287 +.. date: 7223 +.. nonce: eSYlD8 +.. section: Library + +urllib.request and urllib.error now contains an __all__ attribute to expose +only relevant classes and functions. Patch by Florent Xicluna. + +.. + +.. bpo: 670664 +.. date: 7222 +.. nonce: dPMzKt +.. section: Library + +Fix HTMLParser to correctly handle the content of ```` +and ````. + +.. + +.. bpo: 10817 +.. date: 7221 +.. nonce: 2NZ4yV +.. section: Library + +Fix urlretrieve function to raise ContentTooShortError even when reporthook +is None. Patch by Jyrki Pulliainen. + +.. + +.. bpo: 0 +.. date: 7220 +.. nonce: 9QMqzu +.. section: Library + +Fix the xmlrpc.client user agent to return something similar to +urllib.request user agent: "Python-xmlrpc/3.3". + +.. + +.. bpo: 13293 +.. date: 7219 +.. nonce: I4NsfN +.. section: Library + +Better error message when trying to marshal bytes using xmlrpc.client. + +.. + +.. bpo: 13291 +.. date: 7218 +.. nonce: kr_eYK +.. section: Library + +NameError in xmlrpc package. + +.. + +.. bpo: 13258 +.. date: 7217 +.. nonce: PqfnGc +.. section: Library + +Use callable() built-in in the standard library. + +.. + +.. bpo: 13273 +.. date: 7216 +.. nonce: QnsJc6 +.. section: Library + +fix a bug that prevented HTMLParser to properly detect some tags when +strict=False. + +.. + +.. bpo: 11183 +.. date: 7215 +.. nonce: yoGopX +.. section: Library + +Add finer-grained exceptions to the ssl module, so that you don't have to +inspect the exception's attributes in the common case. + +.. + +.. bpo: 13216 +.. date: 7214 +.. nonce: idAP8q +.. section: Library + +Add cp65001 codec, the Windows UTF-8 (CP_UTF8). + +.. + +.. bpo: 13226 +.. date: 7213 +.. nonce: zi3BMF +.. section: Library + +Add RTLD_xxx constants to the os module. These constants can be used with +sys.setdlopenflags(). + +.. + +.. bpo: 10278 +.. date: 7212 +.. nonce: mnE2RY +.. section: Library + +Add clock_getres(), clock_gettime() and CLOCK_xxx constants to the time +module. time.clock_gettime(time.CLOCK_MONOTONIC) provides a monotonic clock + +.. + +.. bpo: 10332 +.. date: 7211 +.. nonce: E9qFmi +.. section: Library + +multiprocessing: fix a race condition when a Pool is closed before all tasks +have completed. + +.. + +.. bpo: 13255 +.. date: 7210 +.. nonce: UiGxn5 +.. section: Library + +wrong docstrings in array module. + +.. + +.. bpo: 8540 +.. date: 7209 +.. nonce: dyhmYO +.. section: Library + +Remove deprecated Context._clamp attribute in Decimal module. + +.. + +.. bpo: 13235 +.. date: 7208 +.. nonce: AEP8bq +.. section: Library + +Added DeprecationWarning to logging.warn() method and function. + +.. + +.. bpo: 9168 +.. date: 7207 +.. nonce: eLGWkL +.. section: Library + +now smtpd is able to bind privileged port. + +.. + +.. bpo: 12529 +.. date: 7206 +.. nonce: TX2NNI +.. section: Library + +fix cgi.parse_header issue on strings with double-quotes and semicolons +together. Patch by Ben Darnell and Petri Lehtinen. + +.. + +.. bpo: 13227 +.. date: 7205 +.. nonce: CQKvc0 +.. section: Library + +functools.lru_cache() now has a option to distinguish calls with different +argument types. + +.. + +.. bpo: 6090 +.. date: 7204 +.. nonce: 8BVasJ +.. section: Library + +zipfile raises a ValueError when a document with a timestamp earlier than +1980 is provided. Patch contributed by Petri Lehtinen. + +.. + +.. bpo: 13150 +.. date: 7203 +.. nonce: ugPhZN +.. section: Library + +sysconfig no longer parses the Makefile and config.h files when imported, +instead doing it at build time. This makes importing sysconfig faster and +reduces Python startup time by 20%. + +.. + +.. bpo: 12448 +.. date: 7202 +.. nonce: KYsQbN +.. section: Library + +smtplib now flushes stdout while running ``python -m smtplib`` in order to +display the prompt correctly. + +.. + +.. bpo: 12454 +.. date: 7201 +.. nonce: 9rCEZL +.. section: Library + +The mailbox module is now using ASCII, instead of the locale encoding, to +read and write .mh_sequences files. + +.. + +.. bpo: 13194 +.. date: 7200 +.. nonce: b0HQpu +.. section: Library + +zlib.compressobj().copy() and zlib.decompressobj().copy() are now available +on Windows. + +.. + +.. bpo: 1673007 +.. date: 7199 +.. nonce: 0MQxW5 +.. section: Library + +urllib.request now supports HEAD request via new method argument. Patch +contributions by David Stanek, Patrick Westerhoff and Ezio Melotti. + +.. + +.. bpo: 12386 +.. date: 7198 +.. nonce: -p2Mdp +.. section: Library + +packaging does not fail anymore when writing the RESOURCES file. + +.. + +.. bpo: 13158 +.. date: 7197 +.. nonce: q5jmKD +.. section: Library + +Fix decoding and encoding of GNU tar specific base-256 number fields in +tarfile. + +.. + +.. bpo: 13025 +.. date: 7196 +.. nonce: T2J6Cv +.. section: Library + +mimetypes is now reading MIME types using the UTF-8 encoding, instead of the +locale encoding. + +.. + +.. bpo: 10653 +.. date: 7195 +.. nonce: jvmIA9 +.. section: Library + +On Windows, use strftime() instead of wcsftime() because wcsftime() doesn't +format time zone correctly. + +.. + +.. bpo: 13150 +.. date: 7194 +.. nonce: ImOpvU +.. section: Library + +The tokenize module doesn't compile large regular expressions at startup +anymore. + +.. + +.. bpo: 11171 +.. date: 7193 +.. nonce: blc9OU +.. section: Library + +Fix distutils.sysconfig.get_makefile_filename when Python was configured +with different prefix and exec-prefix. + +.. + +.. bpo: 11254 +.. date: 7192 +.. nonce: Ljgs_Y +.. section: Library + +Teach distutils and packaging to compile .pyc and .pyo files in PEP +3147-compliant __pycache__ directories. + +.. + +.. bpo: 7367 +.. date: 7191 +.. nonce: 2xoC41 +.. section: Library + +Fix pkgutil.walk_paths to skip directories whose contents cannot be read. + +.. + +.. bpo: 3163 +.. date: 7190 +.. nonce: FrkEgb +.. section: Library + +The struct module gets new format characters 'n' and 'N' supporting C +integer types ``ssize_t`` and ``size_t``, respectively. + +.. + +.. bpo: 13099 +.. date: 7189 +.. nonce: hhmbgp +.. section: Library + +Fix sqlite3.Cursor.lastrowid under a Turkish locale. Reported and diagnosed +by Thomas Kluyver. + +.. + +.. bpo: 13087 +.. date: 7188 +.. nonce: puG2k1 +.. section: Library + +BufferedReader.seek() now always raises UnsupportedOperation if the +underlying raw stream is unseekable, even if the seek could be satisfied +using the internal buffer. Patch by John O'Connor. + +.. + +.. bpo: 7689 +.. date: 7187 +.. nonce: oLubls +.. section: Library + +Allow pickling of dynamically created classes when their metaclass is +registered with copyreg. Patch by Nicolas M. Thiéry and Craig Citro. + +.. + +.. bpo: 13034 +.. date: 7186 +.. nonce: 6wbYBd +.. section: Library + +When decoding some SSL certificates, the subjectAltName extension could be +unreported. + +.. + +.. bpo: 12306 +.. date: 7185 +.. nonce: aywr5r +.. section: Library + +Expose the runtime version of the zlib C library as a constant, +ZLIB_RUNTIME_VERSION, in the zlib module. Patch by Torsten Landschoff. + +.. + +.. bpo: 12959 +.. date: 7184 +.. nonce: kHI1HM +.. section: Library + +Add collections.ChainMap to collections.__all__. + +.. + +.. bpo: 8933 +.. date: 7183 +.. nonce: zlAZwE +.. section: Library + +distutils' PKG-INFO files and packaging's METADATA files will now correctly +report Metadata-Version: 1.1 instead of 1.0 if a Classifier or Download-URL +field is present. + +.. + +.. bpo: 12567 +.. date: 7182 +.. nonce: rAfZbK +.. section: Library + +Add curses.unget_wch() function. Push a character so the next get_wch() will +return it. + +.. + +.. bpo: 9561 +.. date: 7181 +.. nonce: l9A1VJ +.. section: Library + +distutils and packaging now writes egg-info files using UTF-8, instead of +the locale encoding. + +.. + +.. bpo: 8286 +.. date: 7180 +.. nonce: 9gJAZN +.. section: Library + +The distutils command sdist will print a warning message instead of crashing +when an invalid path is given in the manifest template. + +.. + +.. bpo: 12841 +.. date: 7179 +.. nonce: VRTnfy +.. section: Library + +tarfile unnecessarily checked the existence of numerical user and group ids +on extraction. If one of them did not exist the respective id of the current +user (i.e. root) was used for the file and ownership information was lost. + +.. + +.. bpo: 12888 +.. date: 7178 +.. nonce: P2pxQ6 +.. section: Library + +Fix a bug in HTMLParser.unescape that prevented it to escape more than 128 +entities. Patch by Peter Otten. + +.. + +.. bpo: 12878 +.. date: 7177 +.. nonce: 3vxEcY +.. section: Library + +Expose a __dict__ attribute on io.IOBase and its subclasses. + +.. + +.. bpo: 12494 +.. date: 7176 +.. nonce: Tk-YKz +.. section: Library + +On error, call(), check_call(), check_output() and getstatusoutput() +functions of the subprocess module now kill the process, read its status (to +avoid zombis) and close pipes. + +.. + +.. bpo: 12720 +.. date: 7175 +.. nonce: lPMNRD +.. section: Library + +Expose low-level Linux extended file attribute functions in os. + +.. + +.. bpo: 10946 +.. date: 7174 +.. nonce: c8rjV6 +.. section: Library + +The distutils commands bdist_dumb, bdist_wininst and bdist_msi now respect a +--skip-build option given to bdist. The packaging commands were fixed too. + +.. + +.. bpo: 12847 +.. date: 7173 +.. nonce: neDezj +.. section: Library + +Fix a crash with negative PUT and LONG_BINPUT arguments in the C pickle +implementation. + +.. + +.. bpo: 11564 +.. date: 7172 +.. nonce: s8vjkM +.. section: Library + +Avoid crashes when trying to pickle huge objects or containers (more than +2**31 items). Instead, in most cases, an OverflowError is raised. + +.. + +.. bpo: 12287 +.. date: 7171 +.. nonce: _b1Hy3 +.. section: Library + +Fix a stack corruption in ossaudiodev module when the FD is greater than +FD_SETSIZE. + +.. + +.. bpo: 12839 +.. date: 7170 +.. nonce: YFQywe +.. section: Library + +Fix crash in zlib module due to version mismatch. Fix by Richard M. Tew. + +.. + +.. bpo: 9923 +.. date: 7169 +.. nonce: ah6F7t +.. section: Library + +The mailcap module now correctly uses the platform path separator for the +MAILCAP environment variable on non-POSIX platforms. + +.. + +.. bpo: 12835 +.. date: 7168 +.. nonce: ieA6Kw +.. section: Library + +Follow up to #6560 that unconditionally prevents use of the unencrypted +sendmsg/recvmsg APIs on SSL wrapped sockets. Patch by David Watson. + +.. + +.. bpo: 12803 +.. date: 7167 +.. nonce: 9tH8wT +.. section: Library + +SSLContext.load_cert_chain() now accepts a password argument to be used if +the private key is encrypted. Patch by Adam Simpkins. + +.. + +.. bpo: 11657 +.. date: 7166 +.. nonce: K6NkKs +.. section: Library + +Fix sending file descriptors over 255 over a multiprocessing Pipe. + +.. + +.. bpo: 12811 +.. date: 7165 +.. nonce: ij5oOH +.. section: Library + +tabnanny.check() now promptly closes checked files. Patch by Anthony Briggs. + +.. + +.. bpo: 6560 +.. date: 7164 +.. nonce: E-5r4K +.. section: Library + +The sendmsg/recvmsg API is now exposed by the socket module when provided by +the underlying platform, supporting processing of ancillary data in pure +Python code. Patch by David Watson and Heiko Wundram. + +.. + +.. bpo: 12326 +.. date: 7163 +.. nonce: _EUw4i +.. section: Library + +On Linux, sys.platform doesn't contain the major version anymore. It is now +always 'linux', instead of 'linux2' or 'linux3' depending on the Linux +version used to build Python. + +.. + +.. bpo: 12213 +.. date: 7162 +.. nonce: uu17mW +.. section: Library + +Fix a buffering bug with interleaved reads and writes that could appear on +BufferedRandom streams. + +.. + +.. bpo: 12778 +.. date: 7161 +.. nonce: p_dap7 +.. section: Library + +Reduce memory consumption when JSON-encoding a large container of many small +objects. + +.. + +.. bpo: 12650 +.. date: 7160 +.. nonce: hY2GLb +.. section: Library + +Fix a race condition where a subprocess.Popen could leak resources +(FD/zombie) when killed at the wrong time. + +.. + +.. bpo: 12744 +.. date: 7159 +.. nonce: gW4Lzk +.. section: Library + +Fix inefficient representation of integers between 2**31 and 2**63 on +systems with a 64-bit C "long". + +.. + +.. bpo: 12646 +.. date: 7158 +.. nonce: y_M9T8 +.. section: Library + +Add an 'eof' attribute to zlib.Decompress, to make it easier to detect +truncated input streams. + +.. + +.. bpo: 11513 +.. date: 7157 +.. nonce: BCtVVS +.. section: Library + +Fix exception handling ``tarfile.TarFile.gzopen()`` when the file cannot be +opened. + +.. + +.. bpo: 12687 +.. date: 7156 +.. nonce: vxSpbl +.. section: Library + +Fix a possible buffering bug when unpickling text mode (protocol 0, mostly) +pickles. + +.. + +.. bpo: 10087 +.. date: 7155 +.. nonce: JozXk_ +.. section: Library + +Fix the html output format of the calendar module. + +.. + +.. bpo: 13121 +.. date: 7154 +.. nonce: Wbo0Z9 +.. section: Library + +add support for inplace math operators to collections.Counter. + +.. + +.. bpo: 0 +.. date: 7153 +.. nonce: oX3u5E +.. section: Library + +Add support for unary plus and unary minus to collections.Counter. + +.. + +.. bpo: 12683 +.. date: 7152 +.. nonce: pySdFM +.. section: Library + +urlparse updated to include svn as schemes that uses relative paths. (svn +from 1.5 onwards support relative path). + +.. + +.. bpo: 12655 +.. date: 7151 +.. nonce: 5Ir5JO +.. section: Library + +Expose functions from sched.h in the os module: sched_yield(), +sched_setscheduler(), sched_getscheduler(), sched_setparam(), +sched_get_min_priority(), sched_get_max_priority(), sched_rr_get_interval(), +sched_getaffinity(), sched_setaffinity(). + +.. + +.. bpo: 0 +.. date: 7150 +.. nonce: Bipjct +.. section: Library + +Add ThreadError to threading.__all__. + +.. + +.. bpo: 11104 +.. date: 7149 +.. nonce: EZRzAK +.. section: Library + +Fix the behavior of distutils' sdist command with manually-maintained +MANIFEST files. (See also: bpo-8688) + +.. + +.. bpo: 11281 +.. date: 7148 +.. nonce: dxj7Ic +.. section: Library + +smtplib.STMP gets source_address parameter, which adds the ability to bind +to specific source address on a machine with multiple interfaces. Patch by +Paulo Scardine. + +.. + +.. bpo: 12464 +.. date: 7147 +.. nonce: MOtl8D +.. section: Library + +tempfile.TemporaryDirectory.cleanup() should not follow symlinks: fix it. +Patch by Petri Lehtinen. + +.. + +.. bpo: 8887 +.. date: 7146 +.. nonce: GV2FAG +.. section: Library + +"pydoc somebuiltin.somemethod" (or help('somebuiltin.somemethod') in Python +code) now finds the doc of the method. + +.. + +.. bpo: 10968 +.. date: 7145 +.. nonce: UjmUwW +.. section: Library + +Remove indirection in threading. The public names (Event, Condition, etc.) +used to be factory functions returning instances of hidden classes (_Event, +_Condition, etc.), because (if Guido recalls correctly) this code pre-dates +the ability to subclass extension types. It is now possible to inherit from +these classes, without having to import the private underscored names like +multiprocessing did. + +.. + +.. bpo: 9723 +.. date: 7144 +.. nonce: Eoxq0n +.. section: Library + +Add shlex.quote functions, to escape filenames and command lines. + +.. + +.. bpo: 12603 +.. date: 7143 +.. nonce: wO8DQ8 +.. section: Library + +Fix pydoc.synopsis() on files with non-negative st_mtime. + +.. + +.. bpo: 12514 +.. date: 7142 +.. nonce: e1PR4a +.. section: Library + +Use try/finally to assure the timeit module restores garbage collections +when it is done. + +.. + +.. bpo: 12607 +.. date: 7141 +.. nonce: t5RWHt +.. section: Library + +In subprocess, fix issue where if stdin, stdout or stderr is given as a low +fd, it gets overwritten. + +.. + +.. bpo: 12576 +.. date: 7140 +.. nonce: WqmGwQ +.. section: Library + +Fix urlopen behavior on sites which do not send (or obfuscates) +``Connection: close`` header. + +.. + +.. bpo: 12560 +.. date: 7139 +.. nonce: 9ydkW_ +.. section: Library + +Build libpython.so on OpenBSD. Patch by Stefan Sperling. + +.. + +.. bpo: 1813 +.. date: 7138 +.. nonce: YEClj8 +.. section: Library + +Fix codec lookup under Turkish locales. + +.. + +.. bpo: 12591 +.. date: 7137 +.. nonce: 6smMLs +.. section: Library + +Improve support of "universal newlines" in the subprocess module: the piped +streams can now be properly read from or written to. + +.. + +.. bpo: 12591 +.. date: 7136 +.. nonce: ETdSWV +.. section: Library + +Allow io.TextIOWrapper to work with raw IO objects (without a read1() +method), and add a *write_through* parameter to mandate unbuffered writes. + +.. + +.. bpo: 10883 +.. date: 7135 +.. nonce: EkDmNb +.. section: Library + +Fix socket leaks in urllib.request when using FTP. + +.. + +.. bpo: 12592 +.. date: 7134 +.. nonce: -EZrk3 +.. section: Library + +Make Python build on OpenBSD 5 (and future major releases). + +.. + +.. bpo: 12372 +.. date: 7133 +.. nonce: 7QRSzO +.. section: Library + +POSIX semaphores are broken on AIX: don't use them. + +.. + +.. bpo: 12551 +.. date: 7132 +.. nonce: qzV6gf +.. section: Library + +Provide a get_channel_binding() method on SSL sockets so as to get channel +binding data for the current SSL session (only the "tls-unique" channel +binding is implemented). This allows the implementation of certain +authentication mechanisms such as SCRAM-SHA-1-PLUS. Patch by Jacek +Konieczny. + +.. + +.. bpo: 665194 +.. date: 7131 +.. nonce: D_Nif1 +.. section: Library + +email.utils now has format_datetime and parsedate_to_datetime functions, +allowing for round tripping of RFC2822 format dates. + +.. + +.. bpo: 12571 +.. date: 7130 +.. nonce: qrkjgh +.. section: Library + +Add a plat-linux3 directory mirroring the plat-linux2 directory, so that +"import DLFCN" and other similar imports work on Linux 3.0. + +.. + +.. bpo: 7484 +.. date: 7129 +.. nonce: 0bZoAH +.. section: Library + +smtplib no longer puts <> around addresses in VRFY and EXPN commands; they +aren't required and in fact postfix doesn't support that form. + +.. + +.. bpo: 12273 +.. date: 7128 +.. nonce: 8-Rcvi +.. section: Library + +Remove ast.__version__. AST changes can be accounted for by checking +sys.version_info or sys._mercurial. + +.. + +.. bpo: 0 +.. date: 7127 +.. nonce: nBJcjf +.. section: Library + +Silence spurious "broken pipe" tracebacks when shutting down a +ProcessPoolExecutor. + +.. + +.. bpo: 0 +.. date: 7126 +.. nonce: IaRSlM +.. section: Library + +Fix potential resource leaks in concurrent.futures.ProcessPoolExecutor by +joining all queues and processes when shutdown() is called. + +.. + +.. bpo: 11603 +.. date: 7125 +.. nonce: B016rQ +.. section: Library + +Fix a crash when __str__ is rebound as __repr__. Patch by Andreas Stührk. + +.. + +.. bpo: 11321 +.. date: 7124 +.. nonce: rsmpgY +.. section: Library + +Fix a crash with multiple imports of the _pickle module when embedding +Python. Patch by Andreas Stührk. + +.. + +.. bpo: 6755 +.. date: 7123 +.. nonce: vkDHPt +.. section: Library + +Add get_wch() method to curses.window class. Patch by Iñigo Serna. + +.. + +.. bpo: 0 +.. date: 7122 +.. nonce: JDQ86j +.. section: Library + +Add cgi.closelog() function to close the log file. + +.. + +.. bpo: 12502 +.. date: 7121 +.. nonce: p8Kedr +.. section: Library + +asyncore: fix polling loop with AF_UNIX sockets. + +.. + +.. bpo: 4376 +.. date: 7120 +.. nonce: 4S-uUv +.. section: Library + +ctypes now supports nested structures in a endian different than the parent +structure. Patch by Vlad Riscutia. + +.. + +.. bpo: 0 +.. date: 7119 +.. nonce: IFeQ4p +.. section: Library + +Raise ValueError when attempting to set the _CHUNK_SIZE attribute of a +TextIOWrapper to a huge value, not TypeError. + +.. + +.. bpo: 12504 +.. date: 7118 +.. nonce: DE9Ipi +.. section: Library + +Close file handles in a timely manner in packaging.database. This fixes a +bug with the remove (uninstall) feature on Windows. + +.. + +.. bpo: 12169 +.. date: 7117 +.. nonce: AgXMPs +.. section: Library + +Factor out code used by various packaging commands to make HTTP POST +requests, and make sure it uses CRLF. (See also: bpo-10510) + +.. + +.. bpo: 12016 +.. date: 7116 +.. nonce: HJDsZ9 +.. section: Library + +Multibyte CJK decoders now resynchronize faster. They only ignore the first +byte of an invalid byte sequence. For example, b'\xff\n'.decode('gb2312', +'replace') gives '\ufffd\n' instead of '\ufffd'. + +.. + +.. bpo: 12459 +.. date: 7115 +.. nonce: -fijQQ +.. section: Library + +time.sleep() now raises a ValueError if the sleep length is negative, +instead of an infinite sleep on Windows or raising an IOError on Linux for +example, to have the same behaviour on all platforms. + +.. + +.. bpo: 12451 +.. date: 7114 +.. nonce: rQ7kKi +.. section: Library + +pydoc: html_getfile() now uses tokenize.open() to support Python scripts +using a encoding different than UTF-8 (read the coding cookie of the +script). + +.. + +.. bpo: 12493 +.. date: 7113 +.. nonce: qaPq_Q +.. section: Library + +subprocess: Popen.communicate() now also handles EINTR errors if the process +has only one pipe. + +.. + +.. bpo: 12467 +.. date: 7112 +.. nonce: x0sMKt +.. section: Library + +warnings: fix a race condition if a warning is emitted at shutdown, if +globals()['__file__'] is None. + +.. + +.. bpo: 12451 +.. date: 7111 +.. nonce: n8asmW +.. section: Library + +pydoc: importfile() now opens the Python script in binary mode, instead of +text mode using the locale encoding, to avoid encoding issues. + +.. + +.. bpo: 12451 +.. date: 7110 +.. nonce: 3i1f6- +.. section: Library + +runpy: run_path() now opens the Python script in binary mode, instead of +text mode using the locale encoding, to support other encodings than UTF-8 +(scripts using the coding cookie). + +.. + +.. bpo: 12451 +.. date: 7109 +.. nonce: yZnhXf +.. section: Library + +xml.dom.pulldom: parse() now opens files in binary mode instead of the text +mode (using the locale encoding) to avoid encoding issues. + +.. + +.. bpo: 12147 +.. date: 7108 +.. nonce: iUO_PI +.. section: Library + +Adjust the new-in-3.2 smtplib.send_message method for better conformance to +the RFCs: correctly handle Sender and Resent- headers. + +.. + +.. bpo: 12352 +.. date: 7107 +.. nonce: Htm8Oe +.. section: Library + +Fix a deadlock in multiprocessing.Heap when a block is freed by the garbage +collector while the Heap lock is held. + +.. + +.. bpo: 12462 +.. date: 7106 +.. nonce: DxQNvN +.. section: Library + +time.sleep() now immediately calls the (Python) signal handler if it is +interrupted by a signal, instead of having to wait until the next +instruction. + +.. + +.. bpo: 12442 +.. date: 7105 +.. nonce: NNAjnA +.. section: Library + +new shutil.disk_usage function, providing total, used and free disk space +statistics. + +.. + +.. bpo: 12451 +.. date: 7104 +.. nonce: HCFo86 +.. section: Library + +The XInclude default loader of xml.etree now decodes files from UTF-8 +instead of the locale encoding if the encoding is not specified. It now also +opens XML files for the parser in binary mode instead of the text mode to +avoid encoding issues. + +.. + +.. bpo: 12451 +.. date: 7103 +.. nonce: lSrEUK +.. section: Library + +doctest.debug_script() doesn't create a temporary file anymore to avoid +encoding issues. + +.. + +.. bpo: 12451 +.. date: 7102 +.. nonce: AOrBIY +.. section: Library + +pydoc.synopsis() now reads the encoding cookie if available, to read the +Python script from the right encoding. + +.. + +.. bpo: 12451 +.. date: 7101 +.. nonce: 7d0tCg +.. section: Library + +distutils now opens the setup script in binary mode to read the encoding +cookie, instead of opening it in UTF-8. + +.. + +.. bpo: 9516 +.. date: 7100 +.. nonce: QDNUKB +.. section: Library + +On Mac OS X, change Distutils to no longer globally attempt to check or set +the MACOSX_DEPLOYMENT_TARGET environment variable for the interpreter +process. This could cause failures in non-Distutils subprocesses and was +unreliable since tests or user programs could modify the interpreter +environment after Distutils set it. Instead, have Distutils set the +deployment target only in the environment of each build subprocess. It is +still possible to globally override the default by setting +MACOSX_DEPLOYMENT_TARGET before launching the interpreter; its value must be +greater or equal to the default value, the value with which the interpreter +was built. Also, implement the same handling in packaging. + +.. + +.. bpo: 12422 +.. date: 7099 +.. nonce: F1zSw9 +.. section: Library + +In the copy module, don't store objects that are their own copy in the memo +dict. + +.. + +.. bpo: 12303 +.. date: 7098 +.. nonce: wblNCh +.. section: Library + +Add sigwaitinfo() and sigtimedwait() to the signal module. + +.. + +.. bpo: 12404 +.. date: 7097 +.. nonce: bS5-Qf +.. section: Library + +Remove C89 incompatible code from mmap module. Patch by Akira Kitada. + +.. + +.. bpo: 1874 +.. date: 7096 +.. nonce: InySSQ +.. section: Library + +email now detects and reports as a defect the presence of any CTE other than +7bit, 8bit, or binary on a multipart. + +.. + +.. bpo: 12383 +.. date: 7095 +.. nonce: 5vTBCn +.. section: Library + +Fix subprocess module with env={}: don't copy the environment variables, +start with an empty environment. + +.. + +.. bpo: 11637 +.. date: 7094 +.. nonce: 0xbsOd +.. section: Library + +Fix support for importing packaging setup hooks from the project directory. + +.. + +.. bpo: 6771 +.. date: 7093 +.. nonce: nKVoI9 +.. section: Library + +Moved the curses.wrapper function from the single-function wrapper module +into __init__, eliminating the module. Since __init__ was already importing +the function to curses.wrapper, there is no API change. + +.. + +.. bpo: 11584 +.. date: 7092 +.. nonce: pP115T +.. section: Library + +email.header.decode_header no longer fails if the header passed to it is a +Header object, and Header/make_header no longer fail if given binary +unknown-8bit input. + +.. + +.. bpo: 11700 +.. date: 7091 +.. nonce: 2CdbDP +.. section: Library + +mailbox proxy object close methods can now be called multiple times without +error. + +.. + +.. bpo: 11767 +.. date: 7090 +.. nonce: EKah2p +.. section: Library + +Correct file descriptor leak in mailbox's __getitem__ method. + +.. + +.. bpo: 12133 +.. date: 7089 +.. nonce: Ag9yty +.. section: Library + +AbstractHTTPHandler.do_open() of urllib.request closes the HTTP connection +if its getresponse() method fails with a socket error. Patch written by Ezio +Melotti. + +.. + +.. bpo: 12240 +.. date: 7088 +.. nonce: jttNO6 +.. section: Library + +Allow multiple setup hooks in packaging's setup.cfg files. Original patch by +Erik Bray. + +.. + +.. bpo: 9284 +.. date: 7087 +.. nonce: -NhBcF +.. section: Library + +Allow inspect.findsource() to find the source of doctest functions. + +.. + +.. bpo: 11595 +.. date: 7086 +.. nonce: NQkt35 +.. section: Library + +Fix assorted bugs in packaging.util.cfg_to_args, a compatibility helper for +the distutils-packaging transition. Original patch by Erik Bray. + +.. + +.. bpo: 12287 +.. date: 7085 +.. nonce: PxhzFf +.. section: Library + +In ossaudiodev, check that the device isn't closed in several methods. + +.. + +.. bpo: 12009 +.. date: 7084 +.. nonce: nQPg8Y +.. section: Library + +Fixed regression in netrc file comment handling. + +.. + +.. bpo: 12246 +.. date: 7083 +.. nonce: G9vJ2d +.. section: Library + +Warn and fail when trying to install a third-party project from an +uninstalled Python (built in a source checkout). Original patch by Tshepang +Lekhonkhobe. + +.. + +.. bpo: 10694 +.. date: 7082 +.. nonce: JD6qXr +.. section: Library + +zipfile now ignores garbage at the end of a zipfile. + +.. + +.. bpo: 12283 +.. date: 7081 +.. nonce: OzN3R- +.. section: Library + +Fixed regression in smtplib quoting of leading dots in DATA. + +.. + +.. bpo: 10424 +.. date: 7080 +.. nonce: 9NKvd_ +.. section: Library + +Argparse now includes the names of the missing required arguments in the +missing arguments error message. + +.. + +.. bpo: 12168 +.. date: 7079 +.. nonce: GRVioI +.. section: Library + +SysLogHandler now allows NUL termination to be controlled using a new +'append_nul' attribute on the handler. + +.. + +.. bpo: 11583 +.. date: 7078 +.. nonce: Wu1xMh +.. section: Library + +Speed up os.path.isdir on Windows by using GetFileAttributes instead of +os.stat. + +.. + +.. bpo: 12021 +.. date: 7077 +.. nonce: b_Jq9W +.. section: Library + +Make mmap's read() method argument optional. Patch by Petri Lehtinen. + +.. + +.. bpo: 9205 +.. date: 7076 +.. nonce: IiqgOg +.. section: Library + +concurrent.futures.ProcessPoolExecutor now detects killed children and +raises BrokenProcessPool in such a situation. Previously it would reliably +freeze/deadlock. + +.. + +.. bpo: 12040 +.. date: 7075 +.. nonce: 02V02j +.. section: Library + +Expose a new attribute ``sentinel`` on instances of +``multiprocessing.Process``. Also, fix Process.join() to not use polling +anymore, when given a timeout. + +.. + +.. bpo: 11893 +.. date: 7074 +.. nonce: iMoME1 +.. section: Library + +Remove obsolete internal wrapper class ``SSLFakeFile`` in the smtplib +module. Patch by Catalin Iacob. + +.. + +.. bpo: 12080 +.. date: 7073 +.. nonce: 8OzcSB +.. section: Library + +Fix a Decimal.power() case that took an unreasonably long time to compute. + +.. + +.. bpo: 12221 +.. date: 7072 +.. nonce: 5xT68z +.. section: Library + +Remove __version__ attributes from pyexpat, pickle, tarfile, pydoc, tkinter, +and xml.parsers.expat. This were useless version constants left over from +the Mercurial transition + +.. + +.. bpo: 0 +.. date: 7071 +.. nonce: aMnclC +.. section: Library + +Named tuples now work correctly with vars(). + +.. + +.. bpo: 12085 +.. date: 7070 +.. nonce: cu9-Sp +.. section: Library + +Fix an attribute error in subprocess.Popen destructor if the constructor has +failed, e.g. because of an undeclared keyword argument. Patch written by +Oleg Oshmyan. + +.. + +.. bpo: 12028 +.. date: 7069 +.. nonce: sM5p3N +.. section: Library + +Make threading._get_ident() public, rename it to threading.get_ident() and +document it. This function was already used using _thread.get_ident(). + +.. + +.. bpo: 12171 +.. date: 7068 +.. nonce: _FNzN6 +.. section: Library + +IncrementalEncoder.reset() of CJK codecs (multibytecodec) calls encreset() +instead of decreset(). + +.. + +.. bpo: 12218 +.. date: 7067 +.. nonce: 2aiksQ +.. section: Library + +Removed wsgiref.egg-info. + +.. + +.. bpo: 12196 +.. date: 7066 +.. nonce: xglGPS +.. section: Library + +Add pipe2() to the os module. + +.. + +.. bpo: 985064 +.. date: 7065 +.. nonce: GE6WST +.. section: Library + +Make plistlib more resilient to faulty input plists. Patch by Mher +Movsisyan. + +.. + +.. bpo: 1625 +.. date: 7064 +.. nonce: WPlRjA +.. section: Library + +BZ2File and bz2.decompress() now support multi-stream files. Initial patch +by Nir Aides. + +.. + +.. bpo: 12175 +.. date: 7063 +.. nonce: oUmsve +.. section: Library + +BufferedReader.read(-1) now calls raw.readall() if available. + +.. + +.. bpo: 12175 +.. date: 7062 +.. nonce: TtIm7y +.. section: Library + +FileIO.readall() now only reads the file position and size once. + +.. + +.. bpo: 12175 +.. date: 7061 +.. nonce: 9M55CV +.. section: Library + +RawIOBase.readall() now returns None if read() returns None. + +.. + +.. bpo: 12175 +.. date: 7060 +.. nonce: U3k4iw +.. section: Library + +FileIO.readall() now raises a ValueError instead of an IOError if the file +is closed. + +.. + +.. bpo: 11109 +.. date: 7059 +.. nonce: mYTn5W +.. section: Library + +New service_action method for BaseServer, used by ForkingMixin class for +cleanup. Initial Patch by Justin Warkentin. + +.. + +.. bpo: 12045 +.. date: 7058 +.. nonce: y9PAVO +.. section: Library + +Avoid duplicate execution of command in ctypes.util._get_soname(). Patch by +Sijin Joseph. + +.. + +.. bpo: 10818 +.. date: 7057 +.. nonce: p2OOKt +.. section: Library + +Remove the Tk GUI and the serve() function of the pydoc module, pydoc -g has +been deprecated in Python 3.2 and it has a new enhanced web server. + +.. + +.. bpo: 1441530 +.. date: 7056 +.. nonce: LRBsaM +.. section: Library + +In imaplib, read the data in one chunk to speed up large reads and simplify +code. + +.. + +.. bpo: 12070 +.. date: 7055 +.. nonce: XHrqGH +.. section: Library + +Fix the Makefile parser of the sysconfig module to handle correctly +references to "bogus variable" (e.g. "prefix=$/opt/python"). + +.. + +.. bpo: 12100 +.. date: 7054 +.. nonce: 4sb-gJ +.. section: Library + +Don't reset incremental encoders of CJK codecs at each call to their +encode() method anymore, but continue to call the reset() method if the +final argument is True. + +.. + +.. bpo: 12049 +.. date: 7053 +.. nonce: MLrAfb +.. section: Library + +Add RAND_bytes() and RAND_pseudo_bytes() functions to the ssl module. + +.. + +.. bpo: 6501 +.. date: 7052 +.. nonce: _pBcrH +.. section: Library + +os.device_encoding() returns None on Windows if the application has no +console. + +.. + +.. bpo: 12105 +.. date: 7051 +.. nonce: iqnRFC +.. section: Library + +Add O_CLOEXEC to the os module. + +.. + +.. bpo: 12079 +.. date: 7050 +.. nonce: Pa0Xnc +.. section: Library + +Decimal('Infinity').fma(Decimal('0'), (3.91224318126786e+19+0j)) now raises +TypeError (reflecting the invalid type of the 3rd argument) rather than +Decimal.InvalidOperation. + +.. + +.. bpo: 12124 +.. date: 7049 +.. nonce: qpMI7g +.. section: Library + +zipimport doesn't keep a reference to zlib.decompress() anymore to be able +to unload the module. + +.. + +.. bpo: 0 +.. date: 7048 +.. nonce: MTEU1O +.. section: Library + +Add the packaging module, an improved fork of distutils (also known as +distutils2). + +.. + +.. bpo: 12065 +.. date: 7047 +.. nonce: FBZpyD +.. section: Library + +connect_ex() on an SSL socket now returns the original errno when the +socket's timeout expires (it used to return None). + +.. + +.. bpo: 8809 +.. date: 7046 +.. nonce: mzayBk +.. section: Library + +The SMTP_SSL constructor and SMTP.starttls() now support passing a +``context`` argument pointing to an ssl.SSLContext instance. Patch by Kasun +Herath. + +.. + +.. bpo: 9516 +.. date: 7045 +.. nonce: 1FkfGU +.. section: Library + +avoid errors in sysconfig when MACOSX_DEPLOYMENT_TARGET is set in shell. +(See also: bpo-9516) + +.. + +.. bpo: 8650 +.. date: 7044 +.. nonce: P1nZQt +.. section: Library + +Make zlib module 64-bit clean. compress(), decompress() and their +incremental counterparts now raise OverflowError if given an input larger +than 4GB, instead of silently truncating the input and returning an +incorrect result. + +.. + +.. bpo: 12050 +.. date: 7043 +.. nonce: v6HF9i +.. section: Library + +zlib.decompressobj().decompress() now clears the unconsumed_tail attribute +when called without a max_length argument. + +.. + +.. bpo: 12062 +.. date: 7042 +.. nonce: HAyT5M +.. section: Library + +Fix a flushing bug when doing a certain type of I/O sequence on a file +opened in read+write mode (namely: reading, seeking a bit forward, writing, +then seeking before the previous write but still within buffered data, and +writing again). + +.. + +.. bpo: 9971 +.. date: 7041 +.. nonce: Z-o-9t +.. section: Library + +Write an optimized implementation of BufferedReader.readinto(). Patch by +John O'Connor. + +.. + +.. bpo: 11799 +.. date: 7040 +.. nonce: _Ozr6W +.. section: Library + +urllib.request Authentication Handlers will raise a ValueError when +presented with an unsupported Authentication Scheme. Patch contributed by +Yuval Greenfield. + +.. + +.. bpo: 10419 +.. date: 7039 +.. nonce: OqiKFb +.. section: Library + +build_scripts command of distutils handles correctly non-ASCII path (path to +the Python executable). Open and write the script in binary mode, but ensure +that the shebang is decodable from UTF-8 and from the encoding of the +script. (See also: bpo-6011) + +.. + +.. bpo: 8498 +.. date: 7038 +.. nonce: 5UEPSK +.. section: Library + +In socket.accept(), allow to specify 0 as a backlog value in order to accept +exactly one connection. Patch by Daniel Evers. + +.. + +.. bpo: 12011 +.. date: 7037 +.. nonce: TtS2iR +.. section: Library + +signal.signal() and signal.siginterrupt() raise an OSError, instead of a +RuntimeError: OSError has an errno attribute. + +.. + +.. bpo: 3709 +.. date: 7036 +.. nonce: HqOM_3 +.. section: Library + +add a flush_headers method to BaseHTTPRequestHandler, which manages the +sending of headers to output stream and flushing the internal headers +buffer. Patch contribution by Andrew Schaaf + +.. + +.. bpo: 11743 +.. date: 7035 +.. nonce: 1AlJlQ +.. section: Library + +Rewrite multiprocessing connection classes in pure Python. + +.. + +.. bpo: 11164 +.. date: 7034 +.. nonce: OUjg8d +.. section: Library + +Stop trying to use _xmlplus in the xml module. + +.. + +.. bpo: 11888 +.. date: 7033 +.. nonce: KH8iKl +.. section: Library + +Add log2 function to math module. Patch written by Mark Dickinson. + +.. + +.. bpo: 12012 +.. date: 7032 +.. nonce: raFUoR +.. section: Library + +ssl.PROTOCOL_SSLv2 becomes optional. + +.. + +.. bpo: 8407 +.. date: 7031 +.. nonce: thKVew +.. section: Library + +The signal handler writes the signal number as a single byte instead of a +nul byte into the wakeup file descriptor. So it is possible to wait more +than one signal and know which signals were raised. + +.. + +.. bpo: 8407 +.. date: 7030 +.. nonce: qQClST +.. section: Library + +Add pthread_kill(), sigpending() and sigwait() functions to the signal +module. + +.. + +.. bpo: 11927 +.. date: 7029 +.. nonce: UqvRAV +.. section: Library + +SMTP_SSL now uses port 465 by default as documented. Patch by Kasun Herath. + +.. + +.. bpo: 12002 +.. date: 7028 +.. nonce: ySceLp +.. section: Library + +ftplib's abort() method raises TypeError. + +.. + +.. bpo: 11916 +.. date: 7027 +.. nonce: C6SFtK +.. section: Library + +Add a number of MacOSX specific definitions to the errno module. Patch by +Pierre Carrier. + +.. + +.. bpo: 11999 +.. date: 7026 +.. nonce: aLa-HD +.. section: Library + +fixed sporadic sync failure mailbox.Maildir due to its trying to detect +mtime changes by comparing to the system clock instead of to the previous +value of the mtime. + +.. + +.. bpo: 11072 +.. date: 7025 +.. nonce: _qLz7b +.. section: Library + +added MLSD command (RFC-3659) support to ftplib. + +.. + +.. bpo: 8808 +.. date: 7024 +.. nonce: i3pQ9N +.. section: Library + +The IMAP4_SSL constructor now allows passing an SSLContext parameter to +control parameters of the secure channel. Patch by Sijin Joseph. + +.. + +.. bpo: 0 +.. date: 7023 +.. nonce: asMCib +.. section: Library + +ntpath.samefile failed to notice that "a.txt" and "A.TXT" refer to the same +file on Windows XP. As noticed in issue #10684. + +.. + +.. bpo: 12000 +.. date: 7022 +.. nonce: naVBbY +.. section: Library + +When a SSL certificate has a subjectAltName without any dNSName entry, +ssl.match_hostname() should use the subject's commonName. Patch by Nicolas +Bareil. + +.. + +.. bpo: 10775 +.. date: 7021 +.. nonce: dKr3L1 +.. section: Library + +assertRaises, assertRaisesRegex, assertWarns, and assertWarnsRegex now +accept a keyword argument 'msg' when used as context managers. Initial +patch by Winston Ewert. + +.. + +.. bpo: 10684 +.. date: 7020 +.. nonce: Ctye6o +.. section: Library + +shutil.move used to delete a folder on case insensitive filesystems when the +source and destination name where the same except for the case. + +.. + +.. bpo: 11647 +.. date: 7019 +.. nonce: bQbrSQ +.. section: Library + +objects created using contextlib.contextmanager now support more than one +call to the function when used as a decorator. Initial patch by Ysj Ray. + +.. + +.. bpo: 11930 +.. date: 7018 +.. nonce: SoqpJZ +.. section: Library + +Removed deprecated time.accept2dyear variable. Removed year >= 1000 +restriction from datetime.strftime. + +.. + +.. bpo: 0 +.. date: 7017 +.. nonce: IpkrD1 +.. section: Library + +logging: don't define QueueListener if Python has no thread support. + +.. + +.. bpo: 0 +.. date: 7016 +.. nonce: LjAjbQ +.. section: Library + +functools.cmp_to_key() now works with collections.Hashable(). + +.. + +.. bpo: 11277 +.. date: 7015 +.. nonce: 4nCUxv +.. section: Library + +mmap.mmap() calls fcntl(fd, F_FULLFSYNC) on Mac OS X to get around a mmap +bug with sparse files. Patch written by Steffen Daode Nurpmeso. + +.. + +.. bpo: 8407 +.. date: 7014 +.. nonce: sa_qWj +.. section: Library + +Add signal.pthread_sigmask() function to fetch and/or change the signal mask +of the calling thread. + +.. + +.. bpo: 11858 +.. date: 7013 +.. nonce: d8k_Bq +.. section: Library + +configparser.ExtendedInterpolation expected lower-case section names. + +.. + +.. bpo: 11324 +.. date: 7012 +.. nonce: efNvmn +.. section: Library + +ConfigParser(interpolation=None) now works correctly. + +.. + +.. bpo: 11811 +.. date: 7011 +.. nonce: zPdTcR +.. section: Library + +ssl.get_server_certificate() is now IPv6-compatible. Patch by Charles- +François Natali. + +.. + +.. bpo: 11763 +.. date: 7010 +.. nonce: LPGrnG +.. section: Library + +don't use difflib in TestCase.assertMultiLineEqual if the strings are too +long. + +.. + +.. bpo: 11236 +.. date: 7009 +.. nonce: DyWdnL +.. section: Library + +getpass.getpass responds to ctrl-c or ctrl-z on terminal. + +.. + +.. bpo: 11856 +.. date: 7008 +.. nonce: cOY1P0 +.. section: Library + +Speed up parsing of JSON numbers. + +.. + +.. bpo: 11005 +.. date: 7007 +.. nonce: qK2lXb +.. section: Library + +threading.RLock()._release_save() raises a RuntimeError if the lock was not +acquired. + +.. + +.. bpo: 11258 +.. date: 7006 +.. nonce: ByPGev +.. section: Library + +Speed up ctypes.util.find_library() under Linux by a factor of 5 to 10. +Initial patch by Jonas H. + +.. + +.. bpo: 11382 +.. date: 7005 +.. nonce: nUdK_g +.. section: Library + +Trivial system calls, such as dup() or pipe(), needn't release the GIL. +Patch by Charles-François Natali. + +.. + +.. bpo: 11223 +.. date: 7004 +.. nonce: eTi4MT +.. section: Library + +Add threading._info() function providing informations about the thread +implementation. + +.. + +.. bpo: 11731 +.. date: 7003 +.. nonce: BtJ0ZE +.. section: Library + +simplify/enhance email parser/generator API by introducing policy objects. + +.. + +.. bpo: 11768 +.. date: 7002 +.. nonce: HRg5Hy +.. section: Library + +The signal handler of the signal module only calls Py_AddPendingCall() for +the first signal to fix a deadlock on reentrant or parallel calls. +PyErr_SetInterrupt() writes also into the wake up file. + +.. + +.. bpo: 11492 +.. date: 7001 +.. nonce: Ivqdzz +.. section: Library + +fix several issues with header folding in the email package. + +.. + +.. bpo: 11852 +.. date: 7000 +.. nonce: LXhUki +.. section: Library + +Add missing imports and update tests. + +.. + +.. bpo: 11875 +.. date: 6999 +.. nonce: xFn-yD +.. section: Library + +collections.OrderedDict's __reduce__ was temporarily mutating the object +instead of just working on a copy. + +.. + +.. bpo: 11467 +.. date: 6998 +.. nonce: th8B0N +.. section: Library + +Fix urlparse behavior when handling urls which contains scheme specific part +only digits. Patch by Santoso Wijaya. + +.. + +.. bpo: 0 +.. date: 6997 +.. nonce: MOd782 +.. section: Library + +collections.Counter().copy() now works correctly for subclasses. + +.. + +.. bpo: 11474 +.. date: 6996 +.. nonce: UKTAWA +.. section: Library + +Fix the bug with url2pathname() handling of '/C|/' on Windows. Patch by +Santoso Wijaya. + +.. + +.. bpo: 11684 +.. date: 6995 +.. nonce: izuveW +.. section: Library + +complete email.parser bytes API by adding BytesHeaderParser. + +.. + +.. bpo: 0 +.. date: 6994 +.. nonce: 2EP4gU +.. section: Library + +The bz2 module now handles 4GiB+ input buffers correctly. + +.. + +.. bpo: 9233 +.. date: 6993 +.. nonce: AIRcqi +.. section: Library + +Fix json.loads('{}') to return a dict (instead of a list), when _json is not +available. + +.. + +.. bpo: 11830 +.. date: 6992 +.. nonce: XeNc48 +.. section: Library + +Remove unnecessary introspection code in the decimal module. + +.. + +.. bpo: 11703 +.. date: 6991 +.. nonce: hwI5Mw +.. section: Library + +urllib2.geturl() does not return correct url when the original url contains +#fragment. + +.. + +.. bpo: 10019 +.. date: 6990 +.. nonce: J7QVFU +.. section: Library + +Fixed regression in json module where an indent of 0 stopped adding newlines +and acted instead like 'None'. + +.. + +.. bpo: 11186 +.. date: 6989 +.. nonce: qu3iUb +.. section: Library + +pydoc ignores a module if its name contains a surrogate character in the +index of modules. + +.. + +.. bpo: 11815 +.. date: 6988 +.. nonce: BpBrgi +.. section: Library + +Use a light-weight SimpleQueue for the result queue in +concurrent.futures.ProcessPoolExecutor. + +.. + +.. bpo: 5162 +.. date: 6987 +.. nonce: UYJrO- +.. section: Library + +Treat services like frozen executables to allow child spawning from +multiprocessing.forking on Windows. + +.. + +.. bpo: 0 +.. date: 6986 +.. nonce: XxWMZ2 +.. section: Library + +logging.basicConfig now supports an optional 'handlers' argument taking an +iterable of handlers to be added to the root logger. Additional parameter +checks were also added to basicConfig. + +.. + +.. bpo: 11814 +.. date: 6985 +.. nonce: yh-Xda +.. section: Library + +Fix likely typo in multiprocessing.Pool._terminate(). + +.. + +.. bpo: 11747 +.. date: 6984 +.. nonce: lKOBOF +.. section: Library + +Fix range formatting in difflib.context_diff() and difflib.unified_diff(). + +.. + +.. bpo: 8428 +.. date: 6983 +.. nonce: vVu7J6 +.. section: Library + +Fix a race condition in multiprocessing.Pool when terminating worker +processes: new processes would be spawned while the pool is being shut down. +Patch by Charles-François Natali. + +.. + +.. bpo: 2650 +.. date: 6982 +.. nonce: djYtFZ +.. section: Library + +re.escape() no longer escapes the '_'. + +.. + +.. bpo: 11757 +.. date: 6981 +.. nonce: 3CIyys +.. section: Library + +select.select() now raises ValueError when a negative timeout is passed +(previously, a select.error with EINVAL would be raised). Patch by Charles- +François Natali. + +.. + +.. bpo: 7311 +.. date: 6980 +.. nonce: nkDzzK +.. section: Library + +fix html.parser to accept non-ASCII attribute values. + +.. + +.. bpo: 11605 +.. date: 6979 +.. nonce: abhSAm +.. section: Library + +email.parser.BytesFeedParser was incorrectly converting multipart subparts +with an 8-bit CTE into unicode instead of preserving the bytes. + +.. + +.. bpo: 1690608 +.. date: 6978 +.. nonce: _T2fOa +.. section: Library + +email.util.formataddr is now RFC 2047 aware: it now has a charset parameter +that defaults to utf-8 and is used as the charset for RFC 2047 encoding when +the realname contains non-ASCII characters. + +.. + +.. bpo: 10963 +.. date: 6977 +.. nonce: _J-MW9 +.. section: Library + +Ensure that subprocess.communicate() never raises EPIPE. + +.. + +.. bpo: 10791 +.. date: 6976 +.. nonce: mHfCtE +.. section: Library + +Implement missing method GzipFile.read1(), allowing GzipFile to be wrapped +in a TextIOWrapper. Patch by Nadeem Vawda. + +.. + +.. bpo: 11707 +.. date: 6975 +.. nonce: cmDQZT +.. section: Library + +Added a fast C version of functools.cmp_to_key(). Patch by Filip +Gruszczyński. + +.. + +.. bpo: 11688 +.. date: 6974 +.. nonce: Uuorl0 +.. section: Library + +Add sqlite3.Connection.set_trace_callback(). Patch by Torsten Landschoff. + +.. + +.. bpo: 11746 +.. date: 6973 +.. nonce: kN0IW0 +.. section: Library + +Fix SSLContext.load_cert_chain() to accept elliptic curve private keys. + +.. + +.. bpo: 5863 +.. date: 6972 +.. nonce: ixlLlC +.. section: Library + +Rewrite BZ2File in pure Python, and allow it to accept file-like objects +using a new ``fileobj`` constructor argument. Patch by Nadeem Vawda. + +.. + +.. bpo: 0 +.. date: 6971 +.. nonce: L28oNg +.. section: Library + +unittest.TestCase.assertSameElements has been removed. + +.. + +.. bpo: 0 +.. date: 6970 +.. nonce: qBQpRY +.. section: Library + +sys.getfilesystemencoding() raises a RuntimeError if initfsencoding() was +not called yet: detect bootstrap (startup) issues earlier. + +.. + +.. bpo: 11393 +.. date: 6969 +.. nonce: gBYtdm +.. section: Library + +Add the new faulthandler module. + +.. + +.. bpo: 11618 +.. date: 6968 +.. nonce: PIi14g +.. section: Library + +Fix the timeout logic in threading.Lock.acquire() under Windows. + +.. + +.. bpo: 0 +.. date: 6967 +.. nonce: wWchne +.. section: Library + +Removed the 'strict' argument to email.parser.Parser, which has been +deprecated since Python 2.4. + +.. + +.. bpo: 11256 +.. date: 6966 +.. nonce: AVqrHZ +.. section: Library + +Fix inspect.getcallargs on functions that take only keyword arguments. + +.. + +.. bpo: 11696 +.. date: 6965 +.. nonce: dzz7nM +.. section: Library + +Fix ID generation in msilib. + +.. + +.. bpo: 0 +.. date: 6964 +.. nonce: aKw9Fi +.. section: Library + +itertools.accumulate now supports an optional *func* argument for a user- +supplied binary function. + +.. + +.. bpo: 11692 +.. date: 6963 +.. nonce: aWiGD_ +.. section: Library + +Remove unnecessary demo functions in subprocess module. + +.. + +.. bpo: 9696 +.. date: 6962 +.. nonce: Nh0u8J +.. section: Library + +Fix exception incorrectly raised by xdrlib.Packer.pack_int when trying to +pack a negative (in-range) integer. + +.. + +.. bpo: 11675 +.. date: 6961 +.. nonce: qFfmkU +.. section: Library + +multiprocessing.[Raw]Array objects created from an integer size are now +zeroed on creation. This matches the behaviour specified by the +documentation. + +.. + +.. bpo: 7639 +.. date: 6960 +.. nonce: ttVfZV +.. section: Library + +Fix short file name generation in bdist_msi + +.. + +.. bpo: 11635 +.. date: 6959 +.. nonce: ErmdVh +.. section: Library + +Don't use polling in worker threads and processes launched by +concurrent.futures. + +.. + +.. bpo: 5845 +.. date: 6958 +.. nonce: V5g-10 +.. section: Library + +Automatically read readline configuration to enable completion in +interactive mode. + +.. + +.. bpo: 6811 +.. date: 6957 +.. nonce: P4Ow1B +.. section: Library + +Allow importlib to change a code object's co_filename attribute to match the +path to where the source code currently is, not where the code object +originally came from. + +.. + +.. bpo: 8754 +.. date: 6956 +.. nonce: DgUK1D +.. section: Library + +Have importlib use the repr of a module name in error messages. + +.. + +.. bpo: 11591 +.. date: 6955 +.. nonce: 3MRS7c +.. section: Library + +Prevent "import site" from modifying sys.path when python was started with +-S. + +.. + +.. bpo: 0 +.. date: 6954 +.. nonce: NdkoX9 +.. section: Library + +collections.namedtuple() now adds a _source attribute to the generated +class. This make the source more accessible than the outdated "verbose" +option which prints to stdout but doesn't make the source string available. + +.. + +.. bpo: 11371 +.. date: 6953 +.. nonce: 3bqYOV +.. section: Library + +Mark getopt error messages as localizable. Patch by Filip Gruszczyński. + +.. + +.. bpo: 11333 +.. date: 6952 +.. nonce: JTagBm +.. section: Library + +Add __slots__ to collections ABCs. + +.. + +.. bpo: 11628 +.. date: 6951 +.. nonce: yPBMU_ +.. section: Library + +cmp_to_key generated class should use __slots__. + +.. + +.. bpo: 11666 +.. date: 6950 +.. nonce: Hni56e +.. section: Library + +let help() display named tuple attributes and methods that start with a +leading underscore. + +.. + +.. bpo: 11662 +.. date: 6949 +.. nonce: GpHbgk +.. section: Library + +Make urllib and urllib2 ignore redirections if the scheme is not HTTP, HTTPS +or FTP (CVE-2011-1521). + +.. + +.. bpo: 5537 +.. date: 6948 +.. nonce: q0UE2m +.. section: Library + +Fix time2isoz() and time2netscape() functions of httplib.cookiejar for +expiration year greater than 2038 on 32-bit systems. + +.. + +.. bpo: 4391 +.. date: 6947 +.. nonce: GMIMpz +.. section: Library + +Use proper gettext plural forms in optparse. + +.. + +.. bpo: 11127 +.. date: 6946 +.. nonce: 4GWP_C +.. section: Library + +Raise a TypeError when trying to pickle a socket object. + +.. + +.. bpo: 11563 +.. date: 6945 +.. nonce: 702cVt +.. section: Library + +``Connection: close`` header is sent by requests using URLOpener class which +helps in closing of sockets after connection is over. Patch contributions by +Jeff McNeil and Nadeem Vawda. + +.. + +.. bpo: 11459 +.. date: 6944 +.. nonce: f4i9Bf +.. section: Library + +A ``bufsize`` value of 0 in subprocess.Popen() really creates unbuffered +pipes, such that select() works properly on them. + +.. + +.. bpo: 5421 +.. date: 6943 +.. nonce: 4wp0pz +.. section: Library + +Fix misleading error message when one of socket.sendto()'s arguments has the +wrong type. Patch by Nikita Vetoshkin. + +.. + +.. bpo: 10812 +.. date: 6942 +.. nonce: SDYHye +.. section: Library + +Add some extra posix functions to the os module. + +.. + +.. bpo: 10979 +.. date: 6941 +.. nonce: FjyVrT +.. section: Library + +unittest stdout buffering now works with class and module setup and +teardown. + +.. + +.. bpo: 11243 +.. date: 6940 +.. nonce: _emVe6 +.. section: Library + +fix the parameter querying methods of Message to work if the headers contain +un-encoded non-ASCII data. + +.. + +.. bpo: 11401 +.. date: 6939 +.. nonce: 7UJeno +.. section: Library + +fix handling of headers with no value; this fixes a regression relative to +Python2 and the result is now the same as it was in Python2. + +.. + +.. bpo: 9298 +.. date: 6938 +.. nonce: FZ6yRG +.. section: Library + +base64 bodies weren't being folded to line lengths less than 78, which was a +regression relative to Python2. Unlike Python2, the last line of the folded +body now ends with a carriage return. + +.. + +.. bpo: 11560 +.. date: 6937 +.. nonce: YdCxl_ +.. section: Library + +shutil.unpack_archive now correctly handles the format parameter. Patch by +Evan Dandrea. + +.. + +.. bpo: 5870 +.. date: 6936 +.. nonce: MbVhBZ +.. section: Library + +Add `subprocess.DEVNULL` constant. + +.. + +.. bpo: 11133 +.. date: 6935 +.. nonce: _4ZD-9 +.. section: Library + +fix two cases where inspect.getattr_static can trigger code execution. Patch +by Andreas Stührk. + +.. + +.. bpo: 11569 +.. date: 6934 +.. nonce: fp461F +.. section: Library + +use absolute path to the sysctl command in multiprocessing to ensure that it +will be found regardless of the shell PATH. This ensures that +multiprocessing.cpu_count works on default installs of MacOSX. + +.. + +.. bpo: 11501 +.. date: 6933 +.. nonce: -vZ32Q +.. section: Library + +disutils.archive_utils.make_zipfile no longer fails if zlib is not +installed. Instead, the zipfile.ZIP_STORED compression is used to create the +ZipFile. Patch by Natalia B. Bidart. + +.. + +.. bpo: 11289 +.. date: 6932 +.. nonce: aDbXm5 +.. section: Library + +`smtp.SMTP` class is now a context manager so it can be used in a `with` +statement. Contributed by Giampaolo Rodola. + +.. + +.. bpo: 11554 +.. date: 6931 +.. nonce: MYdNID +.. section: Library + +Fixed support for Japanese codecs; previously the body output encoding was +not done if euc-jp or shift-jis was specified as the charset. + +.. + +.. bpo: 11407 +.. date: 6930 +.. nonce: bSuznF +.. section: Library + +`TestCase.run` returns the result object used or created. Contributed by +Janathan Hartley. + +.. + +.. bpo: 11500 +.. date: 6929 +.. nonce: 4VGZ_H +.. section: Library + +Fixed a bug in the OS X proxy bypass code for fully qualified IP addresses +in the proxy exception list. + +.. + +.. bpo: 11491 +.. date: 6928 +.. nonce: 9AofzL +.. section: Library + +dbm.error is no longer raised when dbm.open is called with the "n" as the +flag argument and the file exists. The behavior matches the documentation +and general logic. + +.. + +.. bpo: 1162477 +.. date: 6927 +.. nonce: IqG00q +.. section: Library + +Postel Principle adjustment to email date parsing: handle the fact that some +non-compliant MUAs use '.' instead of ':' in time specs. + +.. + +.. bpo: 11131 +.. date: 6926 +.. nonce: dFvbxY +.. section: Library + +Fix sign of zero in decimal.Decimal plus and minus operations when the +rounding mode is ROUND_FLOOR. + +.. + +.. bpo: 9935 +.. date: 6925 +.. nonce: ByimAG +.. section: Library + +Speed up pickling of instances of user-defined classes. + +.. + +.. bpo: 5622 +.. date: 6924 +.. nonce: dM7tnW +.. section: Library + +Fix curses.wrapper to raise correct exception if curses initialization +fails. + +.. + +.. bpo: 11408 +.. date: 6923 +.. nonce: 2I9Wug +.. section: Library + +In threading.Lock.acquire(), only call gettimeofday() when really necessary. +Patch by Charles-François Natali. + +.. + +.. bpo: 11391 +.. date: 6922 +.. nonce: hdoRPe +.. section: Library + +Writing to a mmap object created with ``mmap.PROT_READ|mmap.PROT_EXEC`` +would segfault instead of raising a TypeError. Patch by Charles-François +Natali. + +.. + +.. bpo: 9795 +.. date: 6921 +.. nonce: emEJ5A +.. section: Library + +add context manager protocol support for nntplib.NNTP class. + +.. + +.. bpo: 11306 +.. date: 6920 +.. nonce: 2rXDt4 +.. section: Library + +mailbox in certain cases adapts to an inability to open certain files in +read-write mode. Previously it detected this by checking for EACCES, now it +also checks for EROFS. + +.. + +.. bpo: 11265 +.. date: 6919 +.. nonce: Y51oyn +.. section: Library + +asyncore now correctly handles EPIPE, EBADF and EAGAIN errors on accept(), +send() and recv(). + +.. + +.. bpo: 11377 +.. date: 6918 +.. nonce: egHPHS +.. section: Library + +Deprecate platform.popen() and reimplement it with os.popen(). + +.. + +.. bpo: 8513 +.. date: 6917 +.. nonce: h1wmX9 +.. section: Library + +On UNIX, subprocess supports bytes command string. + +.. + +.. bpo: 10866 +.. date: 6916 +.. nonce: u6K21Z +.. section: Library + +Add socket.sethostname(). Initial patch by Ross Lagerwall. + +.. + +.. bpo: 11140 +.. date: 6915 +.. nonce: LHg9_O +.. section: Library + +Lock.release() now raises a RuntimeError when attempting to release an +unacquired lock, as claimed in the threading documentation. The +_thread.error exception is now an alias of RuntimeError. Patch by Filip +Gruszczyński. Patch for _dummy_thread by Aymeric Augustin. + +.. + +.. bpo: 8594 +.. date: 6914 +.. nonce: LUyo_- +.. section: Library + +ftplib now provides a source_address parameter to specify which (address, +port) to bind to before connecting. + +.. + +.. bpo: 11326 +.. date: 6913 +.. nonce: 2GUPyU +.. section: Library + +Add the missing connect_ex() implementation for SSL sockets, and make it +work for non-blocking connects. + +.. + +.. bpo: 11297 +.. date: 6912 +.. nonce: bGgJwA +.. section: Library + +Add collections.ChainMap(). + +.. + +.. bpo: 10755 +.. date: 6911 +.. nonce: 0XO-4U +.. section: Library + +Add the posix.flistdir() function. Patch by Ross Lagerwall. + +.. + +.. bpo: 4761 +.. date: 6910 +.. nonce: Z7tR3t +.. section: Library + +Add the ``*at()`` family of functions (openat(), etc.) to the posix module. +Patch by Ross Lagerwall. + +.. + +.. bpo: 7322 +.. date: 6909 +.. nonce: jfgOL8 +.. section: Library + +Trying to read from a socket's file-like object after a timeout occurred now +raises an error instead of silently losing data. + +.. + +.. bpo: 11291 +.. date: 6908 +.. nonce: NY4uFI +.. section: Library + +poplib.POP no longer suppresses errors on quit(). + +.. + +.. bpo: 11177 +.. date: 6907 +.. nonce: M6R7fe +.. section: Library + +asyncore's create_socket() arguments can now be omitted. + +.. + +.. bpo: 6064 +.. date: 6906 +.. nonce: 4URz7L +.. section: Library + +Add a ``daemon`` keyword argument to the threading.Thread and +multiprocessing.Process constructors in order to override the default +behaviour of inheriting the daemonic property from the current +thread/process. + +.. + +.. bpo: 10956 +.. date: 6905 +.. nonce: ArNOt6 +.. section: Library + +Buffered I/O classes retry reading or writing after a signal has arrived and +the handler returned successfully. + +.. + +.. bpo: 10784 +.. date: 6904 +.. nonce: xKXqdg +.. section: Library + +New os.getpriority() and os.setpriority() functions. + +.. + +.. bpo: 11114 +.. date: 6903 +.. nonce: jQcNdM +.. section: Library + +Fix catastrophic performance of tell() on text files (up to 1000x faster in +some cases). It is still one to two order of magnitudes slower than binary +tell(). + +.. + +.. bpo: 10882 +.. date: 6902 +.. nonce: kxNAqA +.. section: Library + +Add os.sendfile function. + +.. + +.. bpo: 10868 +.. date: 6901 +.. nonce: YrdKiG +.. section: Library + +Allow usage of the register method of an ABC as a class decorator. + +.. + +.. bpo: 11224 +.. date: 6900 +.. nonce: G2n8Hf +.. section: Library + +Fixed a regression in tarfile that affected the file-like objects returned +by TarFile.extractfile() regarding performance, memory consumption and +failures with the stream interface. + +.. + +.. bpo: 10924 +.. date: 6899 +.. nonce: FqL1oP +.. section: Library + +Adding salt and Modular Crypt Format to crypt library. Moved old C wrapper +to _crypt, and added a Python wrapper with enhanced salt generation and +simpler API for password generation. + +.. + +.. bpo: 11074 +.. date: 6898 +.. nonce: mVUwxu +.. section: Library + +Make 'tokenize' so it can be reloaded. + +.. + +.. bpo: 11085 +.. date: 6897 +.. nonce: PKAM9L +.. section: Library + +Moved collections abstract base classes into a separate module called +collections.abc, following the pattern used by importlib.abc. For backwards +compatibility, the names are imported into the collections module. + +.. + +.. bpo: 4681 +.. date: 6896 +.. nonce: I20jgq +.. section: Library + +Allow mmap() to work on file sizes and offsets larger than 4GB, even on +32-bit builds. Initial patch by Ross Lagerwall, adapted for 32-bit Windows. + +.. + +.. bpo: 11169 +.. date: 6895 +.. nonce: ggHFKQ +.. section: Library + +compileall module uses repr() to format filenames and paths to escape +surrogate characters and show spaces. + +.. + +.. bpo: 11089 +.. date: 6894 +.. nonce: 0lBf9j +.. section: Library + +Fix performance issue limiting the use of ConfigParser() with large config +files. + +.. + +.. bpo: 10276 +.. date: 6893 +.. nonce: qVeMft +.. section: Library + +Fix the results of zlib.crc32() and zlib.adler32() on buffers larger than +4GB. Patch by Nadeem Vawda. + +.. + +.. bpo: 11388 +.. date: 6892 +.. nonce: ehK5Tz +.. section: Library + +Added a clear() method to MutableSequence + +.. + +.. bpo: 11174 +.. date: 6891 +.. nonce: if_LrS +.. section: Library + +Add argparse.MetavarTypeHelpFormatter, which uses type names for the names +of optional and positional arguments in help messages. + +.. + +.. bpo: 9348 +.. date: 6890 +.. nonce: zsJPPj +.. section: Library + +Raise an early error if argparse nargs and metavar don't match. + +.. + +.. bpo: 9026 +.. date: 6889 +.. nonce: 2xqEFT +.. section: Library + +Fix order of argparse sub-commands in help messages. + +.. + +.. bpo: 9347 +.. date: 6888 +.. nonce: R8xBsQ +.. section: Library + +Fix formatting for tuples in argparse type= error messages. + +.. + +.. bpo: 12191 +.. date: 6887 +.. nonce: IRs2VK +.. section: Library + +Added shutil.chown() to change user and/or group owner of a given path also +specifying their names. + +.. + +.. bpo: 13988 +.. date: 6886 +.. nonce: vIrAol +.. section: Library + +The _elementtree accelerator is used whenever available. Now +xml.etree.cElementTree becomes a deprecated alias to ElementTree. + +.. + +.. bpo: 6807 +.. date: 6885 +.. nonce: lfskSG +.. section: Build + +Run msisupport.mak earlier. + +.. + +.. bpo: 10580 +.. date: 6884 +.. nonce: GkwWHF +.. section: Build + +Minor grammar change in Windows installer. + +.. + +.. bpo: 13326 +.. date: 6883 +.. nonce: A5vc-h +.. section: Build + +Clean __pycache__ directories correctly on OpenBSD. + +.. + +.. bpo: 0 +.. date: 6882 +.. nonce: X0qbPA +.. section: Build + +PEP 393: the configure option --with-wide-unicode is removed. + +.. + +.. bpo: 12852 +.. date: 6881 +.. nonce: L3yoLo +.. section: Build + +Set _XOPEN_SOURCE to 700, instead of 600, to get POSIX 2008 functions on +OpenBSD (e.g. fdopendir). + +.. + +.. bpo: 11863 +.. date: 6880 +.. nonce: K5wTQP +.. section: Build + +Remove support for legacy systems deprecated in Python 3.2 (following PEP +11). These systems are systems using Mach C Threads, SunOS lightweight +processes, GNU pth threads and IRIX threads. + +.. + +.. bpo: 8746 +.. date: 6879 +.. nonce: 4wBblz +.. section: Build + +Correct faulty configure checks so that os.chflags() and os.lchflags() are +once again built on systems that support these functions (BSD and OS X). +Also add new stat file flags for OS X (UF_HIDDEN and UF_COMPRESSED). + +.. + +.. bpo: 10645 +.. date: 6878 +.. nonce: O0VaIT +.. section: Build + +Installing Python no longer creates a Python-X.Y.Z-pyX.Y.egg-info file in +the lib-dynload directory. + +.. + +.. bpo: 0 +.. date: 6877 +.. nonce: eVQr4T +.. section: Build + +Do not accidentally include the directory containing sqlite.h twice when +building sqlite3. + +.. + +.. bpo: 11217 +.. date: 6876 +.. nonce: mIEwfc +.. section: Build + +For 64-bit/32-bit Mac OS X universal framework builds, ensure "make install" +creates symlinks in --prefix bin for the "-32" files in the framework bin +directory like the installer does. + +.. + +.. bpo: 11347 +.. date: 6875 +.. nonce: mQxebN +.. section: Build + +Use --no-as-needed when linking libpython3.so. + +.. + +.. bpo: 11411 +.. date: 6874 +.. nonce: 1m9fjv +.. section: Build + +Fix 'make DESTDIR=' with a relative destination. + +.. + +.. bpo: 11268 +.. date: 6873 +.. nonce: Lgcka6 +.. section: Build + +Prevent Mac OS X Installer failure if Documentation package had previously +been installed. + +.. + +.. bpo: 11495 +.. date: 6872 +.. nonce: h16zox +.. section: Build + +OSF support is eliminated. It was deprecated in Python 3.2. + +.. + +.. bpo: 14409 +.. date: 6871 +.. nonce: 8SNyRR +.. section: IDLE + +IDLE now properly executes commands in the Shell window when it cannot read +the normal config files on startup and has to use the built-in default key +bindings. There was previously a bug in one of the defaults. + +.. + +.. bpo: 0 +.. date: 6870 +.. nonce: ridGZu +.. section: IDLE + +IDLE can be launched as python -m idlelib + +.. + +.. bpo: 3573 +.. date: 6869 +.. nonce: FIbWrY +.. section: IDLE + +IDLE hangs when passing invalid command line args (directory(ies) instead of +file(s)) (Patch by Guilherme Polo) + +.. + +.. bpo: 14200 +.. date: 6868 +.. nonce: XVdh7w +.. section: IDLE + +IDLE shell crash on printing non-BMP unicode character. + +.. + +.. bpo: 5219 +.. date: 6867 +.. nonce: We72rp +.. section: IDLE + +Prevent event handler cascade in IDLE. + +.. + +.. bpo: 964437 +.. date: 6866 +.. nonce: buwNGK +.. section: IDLE + +Make IDLE help window non-modal. Patch by Guilherme Polo and Roger Serwy. + +.. + +.. bpo: 13933 +.. date: 6865 +.. nonce: 5CAw8l +.. section: IDLE + +IDLE auto-complete did not work with some imported module, like hashlib. +(Patch by Roger Serwy) + +.. + +.. bpo: 13506 +.. date: 6864 +.. nonce: ztXHhD +.. section: IDLE + +Add '' to path for IDLE Shell when started and restarted with Restart Shell. +Original patches by Marco Scataglini and Roger Serwy. + +.. + +.. bpo: 4625 +.. date: 6863 +.. nonce: 0SHZWo +.. section: IDLE + +If IDLE cannot write to its recent file or breakpoint files, display a +message popup and continue rather than crash. Original patch by Roger +Serwy. + +.. + +.. bpo: 8641 +.. date: 6862 +.. nonce: dzqFtr +.. section: IDLE + +Update IDLE 3 syntax coloring to recognize b".." and not u"..". Patch by Tal +Einat. + +.. + +.. bpo: 13296 +.. date: 6861 +.. nonce: bMHIFe +.. section: IDLE + +Fix IDLE to clear compile __future__ flags on shell restart. (Patch by Roger +Serwy) + +.. + +.. bpo: 9871 +.. date: 6860 +.. nonce: ViYtMq +.. section: IDLE + +Prevent IDLE 3 crash when given byte stings with invalid hex escape +sequences, like b'\x0'. (Original patch by Claudiu Popa.) + +.. + +.. bpo: 12636 +.. date: 6859 +.. nonce: TARH29 +.. section: IDLE + +IDLE reads the coding cookie when executing a Python script. + +.. + +.. bpo: 12540 +.. date: 6858 +.. nonce: J18oWI +.. section: IDLE + +Prevent zombie IDLE processes on Windows due to changes in os.kill(). + +.. + +.. bpo: 12590 +.. date: 6857 +.. nonce: dcDjo7 +.. section: IDLE + +IDLE editor window now always displays the first line when opening a long +file. With Tk 8.5, the first line was hidden. + +.. + +.. bpo: 11088 +.. date: 6856 +.. nonce: 08NI5v +.. section: IDLE + +don't crash when using F5 to run a script in IDLE on MacOSX with Tk 8.5. + +.. + +.. bpo: 1028 +.. date: 6855 +.. nonce: 59BMpc +.. section: IDLE + +Tk returns invalid Unicode null in %A: UnicodeDecodeError. With Tk < 8.5 +_tkinter.c:PythonCmd() raised UnicodeDecodeError, caused IDLE to exit. +Converted to valid Unicode null in PythonCmd(). + +.. + +.. bpo: 11718 +.. date: 6854 +.. nonce: giS1iY +.. section: IDLE + +IDLE's open module dialog couldn't find the __init__.py file in a package. + +.. + +.. bpo: 14053 +.. date: 6853 +.. nonce: tR4DDC +.. section: Tools/Demos + +patchcheck.py ("make patchcheck") now works with MQ patches. Patch by +Francisco Martín Brugué. + +.. + +.. bpo: 13930 +.. date: 6852 +.. nonce: jUdfJ- +.. section: Tools/Demos + +2to3 is now able to write its converted output files to another directory +tree as well as copying unchanged files and altering the file suffix. See +its new -o, -W and --add-suffix options. This makes it more useful in many +automated code translation workflows. + +.. + +.. bpo: 13628 +.. date: 6851 +.. nonce: XznUD3 +.. section: Tools/Demos + +python-gdb.py is now able to retrieve more frames in the Python traceback if +Python is optimized. + +.. + +.. bpo: 11996 +.. date: 6850 +.. nonce: 0vXv50 +.. section: Tools/Demos + +libpython (gdb), replace "py-bt" command by "py-bt-full" and add a smarter +"py-bt" command printing a classic Python traceback. + +.. + +.. bpo: 11179 +.. date: 6849 +.. nonce: EdCIMF +.. section: Tools/Demos + +Make ccbench work under Python 3.1 and 2.7 again. + +.. + +.. bpo: 10639 +.. date: 6848 +.. nonce: 49RqQh +.. section: Tools/Demos + +reindent.py no longer converts newlines and will raise an error if +attempting to convert a file with mixed newlines. "--newline" option added +to specify new line character. + +.. + +.. bpo: 16847 +.. date: 6847 +.. nonce: bJAkOo +.. section: Library + +Fixed improper use of _PyUnicode_CheckConsistency() in non-pydebug builds. +Several extension modules now compile cleanly when assert()s are enabled in +standard builds (-DDEBUG flag). + +.. + +.. bpo: 13840 +.. date: 6846 +.. nonce: px8cx7 +.. section: Library + +The error message produced by ctypes.create_string_buffer when given a +Unicode string has been fixed. + +.. + +.. bpo: 9975 +.. date: 6845 +.. nonce: 2SRKp5 +.. section: Library + +socket: Fix incorrect use of flowinfo and scope_id. Patch by Vilmos Nebehaj. + +.. + +.. bpo: 7777 +.. date: 6844 +.. nonce: ir5TxQ +.. section: Library + +socket: Add Reliable Datagram Sockets (PF_RDS) support. + +.. + +.. bpo: 13159 +.. date: 6843 +.. nonce: Y91UZj +.. section: Library + +FileIO and BZ2Compressor/BZ2Decompressor now use a linear-time buffer growth +strategy instead of a quadratic-time one. + +.. + +.. bpo: 10141 +.. date: 6842 +.. nonce: 2Bc-WI +.. section: Library + +socket: Add SocketCAN (PF_CAN) support. Initial patch by Matthias Fuchs, +updated by Tiago Gonçalves. + +.. + +.. bpo: 13070 +.. date: 6841 +.. nonce: zcoYVY +.. section: Library + +Fix a crash when a TextIOWrapper caught in a reference cycle would be +finalized after the reference to its underlying BufferedRWPair's writer got +cleared by the GC. + +.. + +.. bpo: 12881 +.. date: 6840 +.. nonce: IpOO6j +.. section: Library + +ctypes: Fix segfault with large structure field names. + +.. + +.. bpo: 13058 +.. date: 6839 +.. nonce: KJ3kEA +.. section: Library + +ossaudiodev: fix a file descriptor leak on error. Patch by Thomas Jarosch. + +.. + +.. bpo: 13013 +.. date: 6838 +.. nonce: KLH96V +.. section: Library + +ctypes: Fix a reference leak in PyCArrayType_from_ctype. Thanks to Suman +Saha for finding the bug and providing a patch. + +.. + +.. bpo: 13022 +.. date: 6837 +.. nonce: zeo8hs +.. section: Library + +Fix: _multiprocessing.recvfd() doesn't check that file descriptor was +actually received. + +.. + +.. bpo: 1172711 +.. date: 6836 +.. nonce: is5nD7 +.. section: Library + +Add 'long long' support to the array module. Initial patch by Oren Tirosh +and Hirokazu Yamamoto. + +.. + +.. bpo: 12483 +.. date: 6835 +.. nonce: IpGhKV +.. section: Library + +ctypes: Fix a crash when the destruction of a callback object triggers the +garbage collector. + +.. + +.. bpo: 12950 +.. date: 6834 +.. nonce: Z7xl-R +.. section: Library + +Fix passing file descriptors in multiprocessing, under OpenIndiana/Illumos. + +.. + +.. bpo: 12764 +.. date: 6833 +.. nonce: YtBoIj +.. section: Library + +Fix a crash in ctypes when the name of a Structure field is not a string. + +.. + +.. bpo: 11241 +.. date: 6832 +.. nonce: GEE_88 +.. section: Library + +subclasses of ctypes.Array can now be subclassed. + +.. + +.. bpo: 9651 +.. date: 6831 +.. nonce: INPcwf +.. section: Library + +Fix a crash when ctypes.create_string_buffer(0) was passed to some functions +like file.write(). + +.. + +.. bpo: 10309 +.. date: 6830 +.. nonce: -z_Mxz +.. section: Library + +Define _GNU_SOURCE so that mremap() gets the proper signature. Without +this, architectures where sizeof void* != sizeof int are broken. Patch +given by Hallvard B Furuseth. + +.. + +.. bpo: 12051 +.. date: 6829 +.. nonce: 7HjY_U +.. section: Library + +Fix segfault in json.dumps() while encoding highly-nested objects using the +C accelerations. + +.. + +.. bpo: 12017 +.. date: 6828 +.. nonce: w25YNq +.. section: Library + +Fix segfault in json.loads() while decoding highly-nested objects using the +C accelerations. + +.. + +.. bpo: 1838 +.. date: 6827 +.. nonce: EzKU3z +.. section: Library + +Prevent segfault in ctypes, when _as_parameter_ on a class is set to an +instance of the class. + +.. + +.. bpo: 13125 +.. date: 6826 +.. nonce: 8BjUbr +.. section: Tests + +Silence spurious test_lib2to3 output when in non-verbose mode. Patch by +Mikhail Novikov. + +.. + +.. bpo: 13447 +.. date: 6825 +.. nonce: _wys-6 +.. section: Tests + +Add a test file to host regression tests for bugs in the scripts found in +the Tools directory. + +.. + +.. bpo: 10881 +.. date: 6824 +.. nonce: r-D2Ib +.. section: Tests + +Fix test_site failure with OS X framework builds. + +.. + +.. bpo: 13901 +.. date: 6823 +.. nonce: ICKGPH +.. section: Tests + +Prevent test_distutils failures on OS X with --enable-shared. + +.. + +.. bpo: 13862 +.. date: 6822 +.. nonce: LHCO8n +.. section: Tests + +Fix spurious failure in test_zlib due to runtime/compile time minor versions +not matching. + +.. + +.. bpo: 12804 +.. date: 6821 +.. nonce: ELp5o1 +.. section: Tests + +Fix test_socket and test_urllib2net failures when running tests on a system +without internet access. + +.. + +.. bpo: 13726 +.. date: 6820 +.. nonce: xd336V +.. section: Tests + +Fix the ambiguous -S flag in regrtest. It is -o/--slow for slow tests. + +.. + +.. bpo: 11659 +.. date: 6819 +.. nonce: CsfDgK +.. section: Tests + +Fix ResourceWarning in test_subprocess introduced by #11459. Patch by Ben +Hayden. + +.. + +.. bpo: 11577 +.. date: 6818 +.. nonce: 2m2urP +.. section: Tests + +fix ResourceWarning triggered by improved binhex test coverage + +.. + +.. bpo: 11509 +.. date: 6817 +.. nonce: _zr0dM +.. section: Tests + +Significantly increase test coverage of fileinput. Patch by Denver +Coneybeare at PyCon 2011 Sprints. + +.. + +.. bpo: 11689 +.. date: 6816 +.. nonce: OlYa3Q +.. section: Tests + +Fix a variable scoping error in an sqlite3 test + +.. + +.. bpo: 13786 +.. date: 6815 +.. nonce: 9-p3Uu +.. section: Tests + +Remove unimplemented 'trace' long option from regrtest.py. + +.. + +.. bpo: 13725 +.. date: 6814 +.. nonce: A4geK5 +.. section: Tests + +Fix regrtest to recognize the documented -d flag. Patch by Erno Tukia. + +.. + +.. bpo: 13304 +.. date: 6813 +.. nonce: jDDi97 +.. section: Tests + +Skip test case if user site-packages disabled (-s or PYTHONNOUSERSITE). +(Patch by Carl Meyer) + +.. + +.. bpo: 5661 +.. date: 6812 +.. nonce: vU7MD_ +.. section: Tests + +Add a test for ECONNRESET/EPIPE handling to test_asyncore. Patch by Xavier +de Gaye. + +.. + +.. bpo: 13218 +.. date: 6811 +.. nonce: EZ3jnV +.. section: Tests + +Fix test_ssl failures on Debian/Ubuntu. + +.. + +.. bpo: 0 +.. date: 6810 +.. nonce: 4ktvta +.. section: Tests + +Re-enable lib2to3's test_parser.py tests, though with an expected failure +(see issue #13125). + +.. + +.. bpo: 12656 +.. date: 6809 +.. nonce: 8T6sbd +.. section: Tests + +Add tests for IPv6 and Unix sockets to test_asyncore. + +.. + +.. bpo: 6484 +.. date: 6808 +.. nonce: x-PPQs +.. section: Tests + +Add unit tests for mailcap module (patch by Gregory Nofi) + +.. + +.. bpo: 11651 +.. date: 6807 +.. nonce: NwvR8a +.. section: Tests + +Improve the Makefile test targets to run more of the test suite more +quickly. The --multiprocess option is now enabled by default, reducing the +amount of time needed to run the tests. "make test" and "make quicktest" now +include some resource-intensive tests, but no longer run the test suite +twice to check for bugs in .pyc generation. Tools/scripts/run_test.py +provides an easy platform-independent way to run test suite with sensible +defaults. + +.. + +.. bpo: 12331 +.. date: 6806 +.. nonce: UjcxFs +.. section: Tests + +The test suite for the packaging module can now run from an installed +Python. + +.. + +.. bpo: 12331 +.. date: 6805 +.. nonce: ZSPeJW +.. section: Tests + +The test suite for lib2to3 can now run from an installed Python. + +.. + +.. bpo: 12626 +.. date: 6804 +.. nonce: YLsif1 +.. section: Tests + +In regrtest, allow to filter tests using a glob filter with the ``-m`` (or +``--match``) option. This works with all test cases using the unittest +module. This is useful with long test suites such as test_io or +test_subprocess. + +.. + +.. bpo: 12624 +.. date: 6803 +.. nonce: WamK2X +.. section: Tests + +It is now possible to fail after the first failure when running in verbose +mode (``-v`` or ``-W``), by using the ``--failfast`` (or ``-G``) option to +regrtest. This is useful with long test suites such as test_io or +test_subprocess. + +.. + +.. bpo: 12587 +.. date: 6802 +.. nonce: O9yS9y +.. section: Tests + +Correct faulty test file and reference in test_tokenize. (Patch by Robert +Xiao) + +.. + +.. bpo: 12573 +.. date: 6801 +.. nonce: e2wPXo +.. section: Tests + +Add resource checks for dangling Thread and Process objects. + +.. + +.. bpo: 12549 +.. date: 6800 +.. nonce: S4urNL +.. section: Tests + +Correct test_platform to not fail when OS X returns 'x86_64' as the +processor type on some Mac systems. + +.. + +.. bpo: 0 +.. date: 6799 +.. nonce: EofQqr +.. section: Tests + +Skip network tests when getaddrinfo() returns EAI_AGAIN, meaning a temporary +failure in name resolution. + +.. + +.. bpo: 11812 +.. date: 6798 +.. nonce: jeNaCB +.. section: Tests + +Solve transient socket failure to connect to 'localhost' in +test_telnetlib.py. + +.. + +.. bpo: 0 +.. date: 6797 +.. nonce: cUdl39 +.. section: Tests + +Solved a potential deadlock in test_telnetlib.py. Related to issue #11812. + +.. + +.. bpo: 0 +.. date: 6796 +.. nonce: QtTimW +.. section: Tests + +Avoid failing in test_robotparser when mueblesmoraleda.com is flaky and an +overzealous DNS service (e.g. OpenDNS) redirects to a placeholder Web site. + +.. + +.. bpo: 0 +.. date: 6795 +.. nonce: Vvh-2P +.. section: Tests + +Avoid failing in test_urllibnet.test_bad_address when some overzealous DNS +service (e.g. OpenDNS) resolves a non-existent domain name. The test is now +skipped instead. + +.. + +.. bpo: 12440 +.. date: 6794 +.. nonce: wGLIEC +.. section: Tests + +When testing whether some bits in SSLContext.options can be reset, check the +version of the OpenSSL headers Python was compiled against, rather than the +runtime version of the OpenSSL library. + +.. + +.. bpo: 11512 +.. date: 6793 +.. nonce: EM5wvo +.. section: Tests + +Add a test suite for the cgitb module. Patch by Robbie Clemons. + +.. + +.. bpo: 12497 +.. date: 6792 +.. nonce: JuVrt4 +.. section: Tests + +Install test/data to prevent failures of the various codecmaps tests. + +.. + +.. bpo: 12496 +.. date: 6791 +.. nonce: ZoaG3t +.. section: Tests + +Install test/capath directory to prevent test_connect_capath testcase +failure in test_ssl. + +.. + +.. bpo: 12469 +.. date: 6790 +.. nonce: Q76Xcy +.. section: Tests + +Run wakeup and pending signal tests in a subprocess to run the test in a +fresh process with only one thread and to not change signal handling of the +parent process. + +.. + +.. bpo: 8716 +.. date: 6789 +.. nonce: -qUe-z +.. section: Tests + +Avoid crashes caused by Aqua Tk on OSX when attempting to run test_tk or +test_ttk_guionly under a username that is not currently logged in to the +console windowserver (as may be the case under buildbot or ssh). + +.. + +.. bpo: 12407 +.. date: 6788 +.. nonce: nGH9qb +.. section: Tests + +Explicitly skip test_capi.EmbeddingTest under Windows. + +.. + +.. bpo: 12400 +.. date: 6787 +.. nonce: 4MhGgH +.. section: Tests + +regrtest -W doesn't rerun the tests twice anymore, but captures the output +and displays it on failure instead. regrtest -v doesn't print the error +twice anymore if there is only one error. + +.. + +.. bpo: 12141 +.. date: 6786 +.. nonce: stIS2p +.. section: Tests + +Install copies of template C module file so that test_build_ext of +test_distutils and test_command_build_ext of test_packaging are no longer +silently skipped when run outside of a build directory. + +.. + +.. bpo: 8746 +.. date: 6785 +.. nonce: I497O- +.. section: Tests + +Add additional tests for os.chflags() and os.lchflags(). Patch by Garrett +Cooper. + +.. + +.. bpo: 10736 +.. date: 6784 +.. nonce: PHRQ-J +.. section: Tests + +Fix test_ttk test_widgets failures with Cocoa Tk 8.5.9 2.8+ on Mac OS X. +(Patch by Ronald Oussoren) + +.. + +.. bpo: 12057 +.. date: 6783 +.. nonce: 7QVG6T +.. section: Tests + +Add tests for ISO 2022 codecs (iso2022_jp, iso2022_jp_2, iso2022_kr). + +.. + +.. bpo: 12096 +.. date: 6782 +.. nonce: KLmxPC +.. section: Tests + +Fix a race condition in test_threading.test_waitfor(). Patch written by +Charles-François Natali. + +.. + +.. bpo: 11614 +.. date: 6781 +.. nonce: HO7tW9 +.. section: Tests + +import __hello__ prints "Hello World!". Patch written by Andreas Stührk. + +.. + +.. bpo: 5723 +.. date: 6780 +.. nonce: Lfg1OX +.. section: Tests + +Improve json tests to be executed with and without accelerations. + +.. + +.. bpo: 12041 +.. date: 6779 +.. nonce: hTvpFb +.. section: Tests + +Make test_wait3 more robust. + +.. + +.. bpo: 11873 +.. date: 6778 +.. nonce: VVQdC9 +.. section: Tests + +Change regex in test_compileall to fix occasional failures when when the +randomly generated temporary path happened to match the regex. + +.. + +.. bpo: 11958 +.. date: 6777 +.. nonce: JOi0nQ +.. section: Tests + +Fix FTP tests for IPv6, bind to "::1" instead of "localhost". Patch written +by Charles-Francois Natali. + +.. + +.. bpo: 8407 +.. date: 6776 +.. nonce: DJQIVY +.. section: Tests + +Fix tests of test_io using threads and an alarm: use pthread_sigmask() to +ensure that the SIGALRM signal is received by the main thread. (See also: +bpo-11859) + +.. + +.. bpo: 11811 +.. date: 6775 +.. nonce: i7swGp +.. section: Tests + +Factor out detection of IPv6 support on the current host and make it +available as ``test.support.IPV6_ENABLED``. Patch by Charles-François +Natali. + +.. + +.. bpo: 10914 +.. date: 6774 +.. nonce: YxA-mP +.. section: Tests + +Add a minimal embedding test to test_capi. + +.. + +.. bpo: 11223 +.. date: 6773 +.. nonce: vC2Jjc +.. section: Tests + +Skip test_lock_acquire_interruption() and test_rlock_acquire_interruption() +of test_threadsignals if a thread lock is implemented using a POSIX mutex +and a POSIX condition variable. A POSIX condition variable cannot be +interrupted by a signal (e.g. on Linux, the futex system call is restarted). + +.. + +.. bpo: 11790 +.. date: 6772 +.. nonce: hg_Quj +.. section: Tests + +Fix sporadic failures in test_multiprocessing.WithProcessesTestCondition. + +.. + +.. bpo: 0 +.. date: 6771 +.. nonce: vCw1YG +.. section: Tests + +Fix possible "file already exists" error when running the tests in parallel. + +.. + +.. bpo: 11719 +.. date: 6770 +.. nonce: ojamUL +.. section: Tests + +Fix message about unexpected test_msilib skip on non-Windows platforms. +Patch by Nadeem Vawda. + +.. + +.. bpo: 11727 +.. date: 6769 +.. nonce: UgpTZa +.. section: Tests + +Add a --timeout option to regrtest: if a test takes more than TIMEOUT +seconds, dumps the traceback of all threads and exits. + +.. + +.. bpo: 11653 +.. date: 6768 +.. nonce: fuE76Y +.. section: Tests + +fix -W with -j in regrtest. + +.. + +.. bpo: 0 +.. date: 6767 +.. nonce: M-5QhM +.. section: Tests + +The email test suite now lives in the Lib/test/test_email package. The test +harness code has also been modernized to allow use of new unittest features. + +.. + +.. bpo: 0 +.. date: 6766 +.. nonce: 0YnOJ5 +.. section: Tests + +regrtest now discovers test packages as well as test modules. + +.. + +.. bpo: 11577 +.. date: 6765 +.. nonce: dZzsdY +.. section: Tests + +improve test coverage of binhex.py. Patch by Arkady Koplyarov. + +.. + +.. bpo: 0 +.. date: 6764 +.. nonce: 8NI_2P +.. section: Tests + +New test_crashers added to exercise the scripts in the Lib/test/crashers +directory and confirm they fail as expected + +.. + +.. bpo: 11578 +.. date: 6763 +.. nonce: 7o3SVY +.. section: Tests + +added test for the timeit module. Patch by Michael Henry. + +.. + +.. bpo: 11503 +.. date: 6762 +.. nonce: lhqffQ +.. section: Tests + +improve test coverage of posixpath.py. Patch by Evan Dandrea. + +.. + +.. bpo: 11505 +.. date: 6761 +.. nonce: lkarT_ +.. section: Tests + +improves test coverage of string.py, increases granularity of +string.Formatter tests. Initial patch by Alicia Arlen. + +.. + +.. bpo: 11548 +.. date: 6760 +.. nonce: 5zabuP +.. section: Tests + +Improve test coverage of the shutil module. Patch by Evan Dandrea. + +.. + +.. bpo: 11554 +.. date: 6759 +.. nonce: JJwnjN +.. section: Tests + +Reactivated test_email_codecs. + +.. + +.. bpo: 11505 +.. date: 6758 +.. nonce: K__ujC +.. section: Tests + +improves test coverage of string.py. Patch by Alicia Arlen + +.. + +.. bpo: 11490 +.. date: 6757 +.. nonce: KEpwUL +.. section: Tests + +test_subprocess.test_leaking_fds_on_error no longer gives a false positive +if the last directory in the path is inaccessible. + +.. + +.. bpo: 11223 +.. date: 6756 +.. nonce: JDDjCO +.. section: Tests + +Fix test_threadsignals to fail, not hang, when the non-semaphore +implementation of locks is used under POSIX. + +.. + +.. bpo: 10911 +.. date: 6755 +.. nonce: Sqgxdv +.. section: Tests + +Add tests on CGI with non-ASCII characters. Patch written by Pierre Quentel. + +.. + +.. bpo: 9931 +.. date: 6754 +.. nonce: 0Ma8Kr +.. section: Tests + +Fix hangs in GUI tests under Windows in certain conditions. Patch by +Hirokazu Yamamoto. + +.. + +.. bpo: 10512 +.. date: 6753 +.. nonce: uHJ91b +.. section: Tests + +Properly close sockets under test.test_cgi. + +.. + +.. bpo: 10992 +.. date: 6752 +.. nonce: CnkKZh +.. section: Tests + +Make tests pass under coverage. + +.. + +.. bpo: 10826 +.. date: 6751 +.. nonce: fuK__- +.. section: Tests + +Prevent sporadic failure in test_subprocess on Solaris due to open door +files. + +.. + +.. bpo: 10990 +.. date: 6750 +.. nonce: Vhsfed +.. section: Tests + +Prevent tests from clobbering a set trace function. + +.. + +.. bpo: 13452 +.. date: 6749 +.. nonce: 0PXwTA +.. section: C API + +PyUnicode_EncodeDecimal() doesn't support error handlers different than +"strict" anymore. The caller was unable to compute the size of the output +buffer: it depends on the error handler. + +.. + +.. bpo: 13560 +.. date: 6748 +.. nonce: z0A3uk +.. section: C API + +Add PyUnicode_DecodeLocale(), PyUnicode_DecodeLocaleAndSize() and +PyUnicode_EncodeLocale() functions to the C API to decode/encode from/to the +current locale encoding. + +.. + +.. bpo: 10831 +.. date: 6747 +.. nonce: bBTxWl +.. section: C API + +PyUnicode_FromFormat() supports %li, %lli and %zi formats. + +.. + +.. bpo: 11246 +.. date: 6746 +.. nonce: QzMUnD +.. section: C API + +Fix PyUnicode_FromFormat("%V") to decode the byte string from UTF-8 (with +replace error handler) instead of ISO-8859-1 (in strict mode). Patch written +by Ray Allen. + +.. + +.. bpo: 10830 +.. date: 6745 +.. nonce: 40AeF8 +.. section: C API + +Fix PyUnicode_FromFormatV("%c") for non-BMP characters on narrow build. + +.. + +.. bpo: 0 +.. date: 6744 +.. nonce: 6je57R +.. section: C API + +Add PyObject_GenericGetDict and PyObject_GeneriSetDict. They are generic +implementations for the getter and setter of a ``__dict__`` descriptor of C +types. + +.. + +.. bpo: 13727 +.. date: 6743 +.. nonce: ftlTbB +.. section: C API + +Add 3 macros to access PyDateTime_Delta members: PyDateTime_DELTA_GET_DAYS, +PyDateTime_DELTA_GET_SECONDS, PyDateTime_DELTA_GET_MICROSECONDS. + +.. + +.. bpo: 10542 +.. date: 6742 +.. nonce: 5duIOl +.. section: C API + +Add 4 macros to work with surrogates: Py_UNICODE_IS_SURROGATE, +Py_UNICODE_IS_HIGH_SURROGATE, Py_UNICODE_IS_LOW_SURROGATE, +Py_UNICODE_JOIN_SURROGATES. + +.. + +.. bpo: 12724 +.. date: 6741 +.. nonce: UIiFKy +.. section: C API + +Add Py_RETURN_NOTIMPLEMENTED macro for returning NotImplemented. + +.. + +.. bpo: 0 +.. date: 6740 +.. nonce: kBbNiR +.. section: C API + +PY_PATCHLEVEL_REVISION has been removed, since it's meaningless with +Mercurial. + +.. + +.. bpo: 12173 +.. date: 6739 +.. nonce: fjaZHM +.. section: C API + +The first argument of PyImport_ImportModuleLevel is now `const char *` +instead of `char *`. + +.. + +.. bpo: 12380 +.. date: 6738 +.. nonce: FHSIWK +.. section: C API + +PyArg_ParseTuple now accepts a bytearray for the 'c' format. + +.. + +.. bpo: 23006 +.. date: 6737 +.. nonce: B64FC0 +.. section: Documentation + +Improve the documentation and indexing of dict.__missing__. Add an entry in +the language datamodel special methods section. Revise and index its +discussion in the stdtypes mapping/dict section. + +.. + +.. bpo: 13989 +.. date: 6736 +.. nonce: G1WySN +.. section: Documentation + +Document that GzipFile does not support text mode, and give a more helpful +error message when opened with an invalid mode string. + +.. + +.. bpo: 13921 +.. date: 6735 +.. nonce: KGXpXP +.. section: Documentation + +Undocument and clean up sqlite3.OptimizedUnicode, which is obsolete in +Python 3.x. It's now aliased to str for backwards compatibility. + +.. + +.. bpo: 12102 +.. date: 6734 +.. nonce: VJSgGA +.. section: Documentation + +Document that buffered files must be flushed before being used with mmap. +Patch by Steffen Daode Nurpmeso. + +.. + +.. bpo: 8982 +.. date: 6733 +.. nonce: fTONNH +.. section: Documentation + +Improve the documentation for the argparse Namespace object. + +.. + +.. bpo: 9343 +.. date: 6732 +.. nonce: 9T-Qyz +.. section: Documentation + +Document that argparse parent parsers must be configured before their +children. + +.. + +.. bpo: 13498 +.. date: 6731 +.. nonce: LI0aQ4 +.. section: Documentation + +Clarify docs of os.makedirs()'s exist_ok argument. Done with great native- +speaker help from R. David Murray. + +.. + +.. bpo: 13491 +.. date: 6730 +.. nonce: zMFNID +.. section: Documentation + +Fix many errors in sqlite3 documentation. Initial patch for #13491 by +Johannes Vogel. (See also: bpo-13995) + +.. + +.. bpo: 13402 +.. date: 6729 +.. nonce: VSNrG0 +.. section: Documentation + +Document absoluteness of sys.executable. + +.. + +.. bpo: 13883 +.. date: 6728 +.. nonce: 8qbb4D +.. section: Documentation + +PYTHONCASEOK also works on OS X. + +.. + +.. bpo: 9021 +.. date: 6727 +.. nonce: A0WRsT +.. section: Documentation + +Add an introduction to the copy module documentation. + +.. + +.. bpo: 6005 +.. date: 6726 +.. nonce: cy8Z22 +.. section: Documentation + +Examples in the socket library documentation use sendall, where relevant, +instead send method. + +.. + +.. bpo: 12798 +.. date: 6725 +.. nonce: ggdsmY +.. section: Documentation + +Updated the mimetypes documentation. + +.. + +.. bpo: 12949 +.. date: 6724 +.. nonce: ef3vju +.. section: Documentation + +Document the kwonlyargcount argument for the PyCode_New C API function. + +.. + +.. bpo: 13513 +.. date: 6723 +.. nonce: Z6l39q +.. section: Documentation + +Fix io.IOBase documentation to correctly link to the io.IOBase.readline +method instead of the readline module. + +.. + +.. bpo: 13237 +.. date: 6722 +.. nonce: EVVjZK +.. section: Documentation + +Reorganise subprocess documentation to emphasise convenience functions and +the most commonly needed arguments to Popen. + +.. + +.. bpo: 13141 +.. date: 6721 +.. nonce: Z3gxv3 +.. section: Documentation + +Demonstrate recommended style for socketserver examples. + +.. + +.. bpo: 11818 +.. date: 6720 +.. nonce: vB1nfN +.. section: Documentation + +Fix tempfile examples for Python 3. diff --git a/Misc/NEWS.d/3.3.0a2.rst b/Misc/NEWS.d/3.3.0a2.rst new file mode 100644 index 00000000000000..2732392ff09674 --- /dev/null +++ b/Misc/NEWS.d/3.3.0a2.rst @@ -0,0 +1,684 @@ +.. bpo: 1683368 +.. date: 7559 +.. nonce: 6VUt7_ +.. release date: 01-Apr-2012 +.. section: Core and Builtins + +object.__new__ and object.__init__ raise a TypeError if they are passed +arguments and their complementary method is not overridden. + +.. + +.. bpo: 14378 +.. date: 7558 +.. nonce: SYESoz +.. section: Core and Builtins + +Fix compiling ast.ImportFrom nodes with a "__future__" string as the module +name that was not interned. + +.. + +.. bpo: 14331 +.. date: 7557 +.. nonce: xcTH6m +.. section: Core and Builtins + +Use significantly less stack space when importing modules by allocating path +buffers on the heap instead of the stack. + +.. + +.. bpo: 14334 +.. date: 7556 +.. nonce: jfh6Id +.. section: Core and Builtins + +Prevent in a segfault in type.__getattribute__ when it was not passed +strings. + +.. + +.. bpo: 1469629 +.. date: 7555 +.. nonce: ej86Z- +.. section: Core and Builtins + +Allow cycles through an object's __dict__ slot to be collected. (For example +if ``x.__dict__ is x``). + +.. + +.. bpo: 14205 +.. date: 7554 +.. nonce: oOwD6n +.. section: Core and Builtins + +dict lookup raises a RuntimeError if the dict is modified during a lookup. + +.. + +.. bpo: 14220 +.. date: 7553 +.. nonce: jQUaQe +.. section: Core and Builtins + +When a generator is delegating to another iterator with the yield from +syntax, it needs to have its ``gi_running`` flag set to True. + +.. + +.. bpo: 14435 +.. date: 7552 +.. nonce: fqTeXP +.. section: Core and Builtins + +Remove dedicated block allocator from floatobject.c and rely on the +PyObject_Malloc() api like all other objects. + +.. + +.. bpo: 14471 +.. date: 7551 +.. nonce: NQQ20o +.. section: Core and Builtins + +Fix a possible buffer overrun in the winreg module. + +.. + +.. bpo: 14288 +.. date: 7550 +.. nonce: zU3alc +.. section: Core and Builtins + +Allow the serialization of builtin iterators + +.. + +.. bpo: 14300 +.. date: 7549 +.. nonce: EKXEH3 +.. section: Library + +Under Windows, sockets created using socket.dup() now allow overlapped I/O. +Patch by sbt. + +.. + +.. bpo: 13872 +.. date: 7548 +.. nonce: xHvdXX +.. section: Library + +socket.detach() now marks the socket closed (as mirrored in the socket +repr()). Patch by Matt Joiner. + +.. + +.. bpo: 14406 +.. date: 7547 +.. nonce: zdFILX +.. section: Library + +Fix a race condition when using ``concurrent.futures.wait( +return_when=ALL_COMPLETED)``. Patch by Matt Joiner. + +.. + +.. bpo: 5136 +.. date: 7546 +.. nonce: 7H2rv2 +.. section: Library + +deprecate old, unused functions from tkinter. + +.. + +.. bpo: 14416 +.. date: 7545 +.. nonce: UuoZhW +.. section: Library + +syslog now defines the LOG_ODELAY and LOG_AUTHPRIV constants if they are +defined in . + +.. + +.. bpo: 14295 +.. date: 7544 +.. nonce: -_TkX_ +.. section: Library + +Add unittest.mock + +.. + +.. bpo: 7652 +.. date: 7543 +.. nonce: iEr-y0 +.. section: Library + +Add --with-system-libmpdec option to configure for linking the _decimal +module against an installed libmpdec. + +.. + +.. bpo: 14380 +.. date: 7542 +.. nonce: vbD08Y +.. section: Library + +MIMEText now defaults to utf-8 when passed non-ASCII unicode with no charset +specified. + +.. + +.. bpo: 10340 +.. date: 7541 +.. nonce: QZDDK- +.. section: Library + +asyncore - properly handle EINVAL in dispatcher constructor on OSX; avoid to +call handle_connect in case of a disconnected socket which was not meant to +connect. + +.. + +.. bpo: 14204 +.. date: 7540 +.. nonce: rzzuGo +.. section: Library + +The ssl module now has support for the Next Protocol Negotiation extension, +if available in the underlying OpenSSL library. Patch by Colin Marc. + +.. + +.. bpo: 3035 +.. date: 7539 +.. nonce: 8RlPJT +.. section: Library + +Unused functions from tkinter are marked as pending deprecated. + +.. + +.. bpo: 12757 +.. date: 7538 +.. nonce: lfCCKo +.. section: Library + +Fix the skipping of doctests when python is run with -OO so that it works in +unittest's verbose mode as well as non-verbose mode. + +.. + +.. bpo: 7652 +.. date: 7537 +.. nonce: 78v0L0 +.. section: Library + +Integrate the decimal floating point libmpdec library to speed up the +decimal module. Performance gains of the new C implementation are between +10x and 100x, depending on the application. + +.. + +.. bpo: 14269 +.. date: 7536 +.. nonce: xxkPQ3 +.. section: Library + +SMTPD now conforms to the RFC and requires a HELO command before MAIL, RCPT, +or DATA. + +.. + +.. bpo: 13694 +.. date: 7535 +.. nonce: qresWC +.. section: Library + +asynchronous connect in asyncore.dispatcher does not set addr attribute. + +.. + +.. bpo: 14344 +.. date: 7534 +.. nonce: 10T1SA +.. section: Library + +fixed the repr of email.policy objects. + +.. + +.. bpo: 11686 +.. date: 7533 +.. nonce: KKCNSn +.. section: Library + +Added missing entries to email package __all__ lists (mostly the new Bytes +classes). + +.. + +.. bpo: 14335 +.. date: 7532 +.. nonce: V2jcRC +.. section: Library + +multiprocessing's custom Pickler subclass now inherits from the +C-accelerated implementation. Patch by sbt. + +.. + +.. bpo: 10484 +.. date: 7531 +.. nonce: NgDSdJ +.. section: Library + +Fix the CGIHTTPServer's PATH_INFO handling problem. + +.. + +.. bpo: 11199 +.. date: 7530 +.. nonce: UMivCa +.. section: Library + +Fix the with urllib which hangs on particular ftp urls. + +.. + +.. bpo: 0 +.. date: 7529 +.. nonce: Z_Hbwr +.. section: Library + +Improve the memory utilization and speed of functools.lru_cache. + +.. + +.. bpo: 14222 +.. date: 7528 +.. nonce: ERgGnw +.. section: Library + +Use the new time.steady() function instead of time.time() for timeout in +queue and threading modules to not be affected of system time update. + +.. + +.. bpo: 13248 +.. date: 7527 +.. nonce: QDAkYv +.. section: Library + +Remove lib2to3.pytree.Base.get_prefix/set_prefix. + +.. + +.. bpo: 14234 +.. date: 7526 +.. nonce: 3-5k8_ +.. section: Library + +CVE-2012-0876: Randomize hashes of xml attributes in the hash table internal +to the pyexpat module's copy of the expat library to avoid a denial of +service due to hash collisions. Patch by David Malcolm with some +modifications by the expat project. + +.. + +.. bpo: 12818 +.. date: 7525 +.. nonce: phT2cB +.. section: Library + +format address no longer needlessly \ escapes ()s in names when the name +ends up being quoted. + +.. + +.. bpo: 14062 +.. date: 7524 +.. nonce: da3P2T +.. section: Library + +BytesGenerator now correctly folds Header objects, including using linesep +when folding. + +.. + +.. bpo: 13839 +.. date: 7523 +.. nonce: 2p10As +.. section: Library + +When invoked on the command-line, the pstats module now accepts several +filenames of profile stat files and merges them all. Patch by Matt Joiner. + +.. + +.. bpo: 14291 +.. date: 7522 +.. nonce: RC5jhD +.. section: Library + +Email now defaults to utf-8 for non-ASCII unicode headers instead of raising +an error. This fixes a regression relative to 2.7. + +.. + +.. bpo: 989712 +.. date: 7521 +.. nonce: DK9VYH +.. section: Library + +Support using Tk without a mainloop. + +.. + +.. bpo: 3835 +.. date: 7520 +.. nonce: 2J2TSu +.. section: Library + +Refuse to use unthreaded Tcl in threaded Python. + +.. + +.. bpo: 2843 +.. date: 7519 +.. nonce: R6eFw1 +.. section: Library + +Add new Tk API to Tkinter. + +.. + +.. bpo: 14184 +.. date: 7518 +.. nonce: 6AXV0T +.. section: Library + +Increase the default stack size for secondary threads on Mac OS X to avoid +interpreter crashes when using threads on 10.7. + +.. + +.. bpo: 14180 +.. date: 7517 +.. nonce: 6RcdYN +.. section: Library + +datetime.date.fromtimestamp(), datetime.datetime.fromtimestamp() and +datetime.datetime.utcfromtimestamp() now raise an OSError instead of +ValueError if localtime() or gmtime() failed. + +.. + +.. bpo: 14180 +.. date: 7516 +.. nonce: qe2Eei +.. section: Library + +time.ctime(), gmtime(), time.localtime(), datetime.date.fromtimestamp(), +datetime.datetime.fromtimestamp() and datetime.datetime.utcfromtimestamp() +now raises an OverflowError, instead of a ValueError, if the timestamp does +not fit in time_t. + +.. + +.. bpo: 14180 +.. date: 7515 +.. nonce: XzoCLE +.. section: Library + +datetime.datetime.fromtimestamp() and datetime.datetime.utcfromtimestamp() +now round microseconds towards zero instead of rounding to nearest with ties +going away from zero. + +.. + +.. bpo: 10543 +.. date: 7514 +.. nonce: hhj5c8 +.. section: Library + +Fix unittest test discovery with Jython bytecode files. + +.. + +.. bpo: 1178863 +.. date: 7513 +.. nonce: qZwz1u +.. section: Library + +Separate initialisation from setting when initializing Tkinter.Variables; +harmonize exceptions to ValueError; only delete variables that have not been +deleted; assert that variable names are strings. + +.. + +.. bpo: 14104 +.. date: 7512 +.. nonce: OxYNl1 +.. section: Library + +Implement time.monotonic() on Mac OS X, patch written by Nicholas Riley. + +.. + +.. bpo: 13394 +.. date: 7511 +.. nonce: 5-MRTZ +.. section: Library + +the aifc module now uses warnings.warn() to signal warnings. + +.. + +.. bpo: 14252 +.. date: 7510 +.. nonce: -5zjL9 +.. section: Library + +Fix subprocess.Popen.terminate() to not raise an error under Windows when +the child process has already exited. + +.. + +.. bpo: 14223 +.. date: 7509 +.. nonce: J3xsO9 +.. section: Library + +curses.addch() is no more limited to the range 0-255 when the Python curses +is not linked to libncursesw. It was a regression introduced in Python +3.3a1. + +.. + +.. bpo: 14168 +.. date: 7508 +.. nonce: k48rkQ +.. section: Library + +Check for presence of Element._attrs in minidom before accessing it. + +.. + +.. bpo: 12328 +.. date: 7507 +.. nonce: 0ou86A +.. section: Library + +Fix multiprocessing's use of overlapped I/O on Windows. Also, add a +multiprocessing.connection.wait(rlist, timeout=None) function for polling +multiple objects at once. Patch by sbt. + +.. + +.. bpo: 14007 +.. date: 7506 +.. nonce: QgHRiZ +.. section: Library + +Accept incomplete TreeBuilder objects (missing start, end, data or close +method) for the Python implementation as well. Drop the no-op +TreeBuilder().xml() method from the C implementation. + +.. + +.. bpo: 14210 +.. date: 7505 +.. nonce: PDzvZF +.. section: Library + +pdb now has tab-completion not only for command names, but also for their +arguments, wherever possible. + +.. + +.. bpo: 14310 +.. date: 7504 +.. nonce: mho0IY +.. section: Library + +Sockets can now be with other processes on Windows using the api +socket.socket.share() and socket.fromshare(). + +.. + +.. bpo: 10576 +.. date: 7503 +.. nonce: hVfEHY +.. section: Library + +The gc module now has a 'callbacks' member that will get called when garbage +collection takes place. + +.. + +.. bpo: 14557 +.. date: 7502 +.. nonce: UCbIq7 +.. section: Build + +Fix extensions build on HP-UX. Patch by Adi Roiban. + +.. + +.. bpo: 14387 +.. date: 7501 +.. nonce: akFGpn +.. section: Build + +Do not include accu.h from Python.h. + +.. + +.. bpo: 14359 +.. date: 7500 +.. nonce: d8AJnN +.. section: Build + +Only use O_CLOEXEC in _posixmodule.c if it is defined. Based on patch from +Hervé Coatanhay. + +.. + +.. bpo: 14321 +.. date: 7499 +.. nonce: 3fOzVM +.. section: Build + +Do not run pgen during the build if files are up to date. + +.. + +.. bpo: 14034 +.. date: 7498 +.. nonce: 34GDTv +.. section: Documentation + +added the argparse tutorial. + +.. + +.. bpo: 14324 +.. date: 7497 +.. nonce: njGV1Q +.. section: Documentation + +Fix configure tests for cross builds. + +.. + +.. bpo: 14327 +.. date: 7496 +.. nonce: F1iSk5 +.. section: Documentation + +Call AC_CANONICAL_HOST in configure.ac and check in config.{guess,sub}. +Don't use uname calls for cross builds. + +.. + +.. bpo: 9041 +.. date: 7495 +.. nonce: iLXuHK +.. section: Library + +An issue in ctypes.c_longdouble, ctypes.c_double, and ctypes.c_float that +caused an incorrect exception to be returned in the case of overflow has +been fixed. + +.. + +.. bpo: 14212 +.. date: 7494 +.. nonce: 78Bmn2 +.. section: Library + +The re module didn't retain a reference to buffers it was scanning, +resulting in segfaults. + +.. + +.. bpo: 14259 +.. date: 7493 +.. nonce: EG-kwB +.. section: Library + +The finditer() method of re objects did not take any keyword arguments, +contrary to the documentation. + +.. + +.. bpo: 10142 +.. date: 7492 +.. nonce: iHMgqe +.. section: Library + +Support for SEEK_HOLE/SEEK_DATA (for example, under ZFS). + +.. + +.. bpo: 14442 +.. date: 7491 +.. nonce: 9ett0- +.. section: Tests + +Add missing errno import in test_smtplib. + +.. + +.. bpo: 8315 +.. date: 7490 +.. nonce: 2qXCkM +.. section: Tests + +(partial fix) python -m unittest test.test_email now works. diff --git a/Misc/NEWS.d/3.3.0a3.rst b/Misc/NEWS.d/3.3.0a3.rst new file mode 100644 index 00000000000000..3ce1269c3d1fc7 --- /dev/null +++ b/Misc/NEWS.d/3.3.0a3.rst @@ -0,0 +1,730 @@ +.. bpo: 14699 +.. date: 7633 +.. nonce: AuoeMs +.. release date: 01-May-2012 +.. section: Core and Builtins + +Fix calling the classmethod descriptor directly. + +.. + +.. bpo: 14433 +.. date: 7632 +.. nonce: HtSYT- +.. section: Core and Builtins + +Prevent msvcrt crash in interactive prompt when stdin is closed. + +.. + +.. bpo: 14521 +.. date: 7631 +.. nonce: JDzRE4 +.. section: Core and Builtins + +Make result of float('nan') and float('-nan') more consistent across +platforms. + +.. + +.. bpo: 14646 +.. date: 7630 +.. nonce: 19NogB +.. section: Core and Builtins + +__import__() sets __loader__ if the loader did not. + +.. + +.. bpo: 14605 +.. date: 7629 +.. nonce: Psk3ZV +.. section: Core and Builtins + +No longer have implicit entries in sys.meta_path. If sys.meta_path is found +to be empty, raise ImportWarning. + +.. + +.. bpo: 14605 +.. date: 7628 +.. nonce: WVtAi5 +.. section: Core and Builtins + +No longer have implicit entries in sys.path_hooks. If sys.path_hooks is +found to be empty, a warning will be raised. None is now inserted into +sys.path_importer_cache if no finder was discovered. This also means +imp.NullImporter is no longer implicitly used. + +.. + +.. bpo: 13903 +.. date: 7627 +.. nonce: 4z4rf7 +.. section: Core and Builtins + +Implement PEP 412. Individual dictionary instances can now share their keys +with other dictionaries. Classes take advantage of this to share their +instance dictionary keys for improved memory and performance. + +.. + +.. bpo: 11603 +.. date: 7626 +.. nonce: aGsFsn +.. section: Core and Builtins + +Setting __repr__ to __str__ now raises a RuntimeError when repr() or str() +is called on such an object. + +.. + +.. bpo: 14658 +.. date: 7625 +.. nonce: jeSkqL +.. section: Core and Builtins + +Fix binding a special method to a builtin implementation of a special method +with a different name. + +.. + +.. bpo: 14630 +.. date: 7624 +.. nonce: 0bHFSA +.. section: Core and Builtins + +Fix a memory access bug for instances of a subclass of int with value 0. + +.. + +.. bpo: 14339 +.. date: 7623 +.. nonce: QR-MDy +.. section: Core and Builtins + +Speed improvements to bin, oct and hex functions. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 14385 +.. date: 7622 +.. nonce: FD63CN +.. section: Core and Builtins + +It is now possible to use a custom type for the __builtins__ namespace, +instead of a dict. It can be used for sandboxing for example. Raise also a +NameError instead of ImportError if __build_class__ name if not found in +__builtins__. + +.. + +.. bpo: 12599 +.. date: 7621 +.. nonce: Iu99dL +.. section: Core and Builtins + +Be more strict in accepting None compared to a false-like object for +importlib.util.module_for_loader and importlib.machinery.PathFinder. + +.. + +.. bpo: 14612 +.. date: 7620 +.. nonce: uTBlpg +.. section: Core and Builtins + +Fix jumping around with blocks by setting f_lineno. + +.. + +.. bpo: 14592 +.. date: 7619 +.. nonce: 7PB7Zk +.. section: Core and Builtins + +Attempting a relative import w/o __package__ or __name__ set in globals +raises a KeyError. + +.. + +.. bpo: 14607 +.. date: 7618 +.. nonce: YEC4Eu +.. section: Core and Builtins + +Fix keyword-only arguments which started with ``__``. + +.. + +.. bpo: 10854 +.. date: 7617 +.. nonce: -vkFId +.. section: Core and Builtins + +The ImportError raised when an extension module on Windows fails to import +now uses the new path and name attributes from Issue #1559549. + +.. + +.. bpo: 13889 +.. date: 7616 +.. nonce: 5jUbDL +.. section: Core and Builtins + +Check and (if necessary) set FPU control word before calling any of the +dtoa.c string <-> float conversion functions, on MSVC builds of Python. +This fixes issues when embedding Python in a Delphi app. + +.. + +.. bpo: 0 +.. date: 7615 +.. nonce: dHmS-L +.. section: Core and Builtins + +__import__() now matches PEP 328 and documentation by defaulting 'index' to +0 instead of -1 and removing support for negative values. + +.. + +.. bpo: 2377 +.. date: 7614 +.. nonce: 0jsA57 +.. section: Core and Builtins + +Make importlib the implementation of __import__(). + +.. + +.. bpo: 1559549 +.. date: 7613 +.. nonce: krys02 +.. section: Core and Builtins + +ImportError now has 'name' and 'path' attributes that are set using keyword +arguments to its constructor. They are currently not set by import as they +are meant for use by importlib. + +.. + +.. bpo: 14474 +.. date: 7612 +.. nonce: duWZWs +.. section: Core and Builtins + +Save and restore exception state in thread.start_new_thread() while writing +error message if the thread leaves a unhandled exception. + +.. + +.. bpo: 13019 +.. date: 7611 +.. nonce: LYHgJO +.. section: Core and Builtins + +Fix potential reference leaks in bytearray.extend(). Patch by Suman Saha. + +.. + +.. bpo: 14768 +.. date: 7610 +.. nonce: NGBeVQ +.. section: Library + +os.path.expanduser('~/a') doesn't works correctly when HOME is '/'. + +.. + +.. bpo: 14371 +.. date: 7609 +.. nonce: w4YKgU +.. section: Library + +Support bzip2 in zipfile module. Patch by Serhiy Storchaka. + +.. + +.. bpo: 13183 +.. date: 7608 +.. nonce: WXohoU +.. section: Library + +Fix pdb skipping frames after hitting a breakpoint and running step. Patch +by Xavier de Gaye. + +.. + +.. bpo: 14696 +.. date: 7607 +.. nonce: 6sKxyV +.. section: Library + +Fix parser module to understand 'nonlocal' declarations. + +.. + +.. bpo: 10941 +.. date: 7606 +.. nonce: T2_m5t +.. section: Library + +Fix imaplib.Internaldate2tuple to produce correct result near the DST +transition. Patch by Joe Peterson. + +.. + +.. bpo: 9154 +.. date: 7605 +.. nonce: l5Z37S +.. section: Library + +Fix parser module to understand function annotations. + +.. + +.. bpo: 6085 +.. date: 7604 +.. nonce: K59hDR +.. section: Library + +In http.server.py SimpleHTTPServer.address_string returns the client ip +address instead client hostname. Patch by Charles-François Natali. + +.. + +.. bpo: 14309 +.. date: 7603 +.. nonce: 0TEhbF +.. section: Library + +Deprecate time.clock(), use time.perf_counter() or time.process_time() +instead. + +.. + +.. bpo: 14428 +.. date: 7602 +.. nonce: HY9aE6 +.. section: Library + +Implement the PEP 418. Add time.get_clock_info(), time.perf_counter() and +time.process_time() functions, and rename time.steady() to time.monotonic(). + +.. + +.. bpo: 14646 +.. date: 7601 +.. nonce: kSPenl +.. section: Library + +importlib.util.module_for_loader() now sets __loader__ and __package__ (when +possible). + +.. + +.. bpo: 14664 +.. date: 7600 +.. nonce: pdyfQE +.. section: Library + +It is now possible to use @unittest.skip{If,Unless} on a test class that +doesn't inherit from TestCase (i.e. a mixin). + +.. + +.. bpo: 4892 +.. date: 7599 +.. nonce: XAcc2_ +.. section: Library + +multiprocessing Connections can now be transferred over multiprocessing +Connections. Patch by Richard Oudkerk (sbt). + +.. + +.. bpo: 14160 +.. date: 7598 +.. nonce: eP9a5e +.. section: Library + +TarFile.extractfile() failed to resolve symbolic links when the links were +not located in an archive subdirectory. + +.. + +.. bpo: 14638 +.. date: 7597 +.. nonce: cfMimX +.. section: Library + +pydoc now treats non-string __name__ values as if they were missing, instead +of raising an error. + +.. + +.. bpo: 13684 +.. date: 7596 +.. nonce: GMakQh +.. section: Library + +Fix httplib tunnel issue of infinite loops for certain sites which send EOF +without trailing \r\n. + +.. + +.. bpo: 14605 +.. date: 7595 +.. nonce: 0oYc81 +.. section: Library + +Add importlib.abc.FileLoader, importlib.machinery.(FileFinder, +SourceFileLoader, SourcelessFileLoader, ExtensionFileLoader). + +.. + +.. bpo: 13959 +.. date: 7594 +.. nonce: q2O_A_ +.. section: Library + +imp.cache_from_source()/source_from_cache() now follow +os.path.join()/split() semantics for path manipulation instead of its prior, +custom semantics of caring the right-most path separator forward in path +joining. + +.. + +.. bpo: 2193 +.. date: 7593 +.. nonce: EwmaL0 +.. section: Library + +Allow ":" character in Cookie NAME values. + +.. + +.. bpo: 14629 +.. date: 7592 +.. nonce: CT9YOf +.. section: Library + +tokenizer.detect_encoding will specify the filename in the SyntaxError +exception if found at readline.__self__.name. + +.. + +.. bpo: 14629 +.. date: 7591 +.. nonce: NmM4VS +.. section: Library + +Raise SyntaxError in tokenizer.detect_encoding if the first two lines have +non-UTF-8 characters without an encoding declaration. + +.. + +.. bpo: 14308 +.. date: 7590 +.. nonce: VI_YtW +.. section: Library + +Fix an exception when a "dummy" thread is in the threading module's active +list after a fork(). + +.. + +.. bpo: 11750 +.. date: 7589 +.. nonce: zqcMd9 +.. section: Library + +The Windows API functions scattered in the _subprocess and +_multiprocessing.win32 modules now live in a single module "_winapi". Patch +by sbt. + +.. + +.. bpo: 14087 +.. date: 7588 +.. nonce: jLqw-6 +.. section: Library + +multiprocessing: add Condition.wait_for(). Patch by sbt. + +.. + +.. bpo: 14538 +.. date: 7587 +.. nonce: l61eIV +.. section: Library + +HTMLParser can now parse correctly start tags that contain a bare '/'. + +.. + +.. bpo: 14452 +.. date: 7586 +.. nonce: TPNgz8 +.. section: Library + +SysLogHandler no longer inserts a UTF-8 BOM into the message. + +.. + +.. bpo: 14386 +.. date: 7585 +.. nonce: 98-5AW +.. section: Library + +Expose the dict_proxy internal type as types.MappingProxyType. + +.. + +.. bpo: 13959 +.. date: 7584 +.. nonce: lhqW73 +.. section: Library + +Make imp.reload() always use a module's __loader__ to perform the reload. + +.. + +.. bpo: 13959 +.. date: 7583 +.. nonce: -UuY7L +.. section: Library + +Add imp.py and rename the built-in module to _imp, allowing for re- +implementing parts of the module in pure Python. + +.. + +.. bpo: 13496 +.. date: 7582 +.. nonce: ZTq6yk +.. section: Library + +Fix potential overflow in bisect.bisect algorithm when applied to a +collection of size > sys.maxsize / 2. + +.. + +.. bpo: 0 +.. date: 7581 +.. nonce: bW_hJ4 +.. section: Library + +Have importlib take advantage of ImportError's new 'name' and 'path' +attributes. + +.. + +.. bpo: 14399 +.. date: 7580 +.. nonce: aGumG7 +.. section: Library + +zipfile now recognizes that the archive has been modified even if only the +comment is changed. In addition, the TypeError that results from trying to +set a non-binary value as a comment is now raised at the time the comment is +set rather than at the time the zipfile is written. + +.. + +.. bpo: 0 +.. date: 7579 +.. nonce: hVFHSa +.. section: Library + +trace.CoverageResults.is_ignored_filename() now ignores any name that starts +with "<" and ends with ">" instead of special-casing "" and +"= 2 ** 32) under 64-bit +Windows. + +.. + +.. bpo: 14732 +.. date: 7671 +.. nonce: 3fMRiU +.. section: Library + +The _csv module now uses PEP 3121 module initialization. Patch by Robin +Schreiber. + +.. + +.. bpo: 14809 +.. date: 7670 +.. nonce: IdiSIH +.. section: Library + +Add HTTP status codes introduced by RFC 6585 to http.server and http.client. +Patch by EungJun Yi. + +.. + +.. bpo: 14777 +.. date: 7669 +.. nonce: hOLi4A +.. section: Library + +tkinter may return undecoded UTF-8 bytes as a string when accessing the Tk +clipboard. Modify clipboad_get() to first request type UTF8_STRING when no +specific type is requested in an X11 windowing environment, falling back to +the current default type STRING if that fails. Original patch by Thomas +Kluyver. + +.. + +.. bpo: 14773 +.. date: 7668 +.. nonce: gWImyJ +.. section: Library + +Fix os.fwalk() failing on dangling symlinks. + +.. + +.. bpo: 12541 +.. date: 7667 +.. nonce: Np6NxR +.. section: Library + +Be lenient with quotes around Realm field of HTTP Basic Authentation in +urllib2. + +.. + +.. bpo: 14807 +.. date: 7666 +.. nonce: DQuJr9 +.. section: Library + +move undocumented tarfile.filemode() to stat.filemode() and add doc entry. +Add tarfile.filemode alias with deprecation warning. + +.. + +.. bpo: 13815 +.. date: 7665 +.. nonce: nQCfus +.. section: Library + +TarFile.extractfile() now returns io.BufferedReader objects. + +.. + +.. bpo: 14532 +.. date: 7664 +.. nonce: RR8WDH +.. section: Library + +Add a secure_compare() helper to the hmac module, to mitigate timing +attacks. Patch by Jon Oberheide. + +.. + +.. bpo: 0 +.. date: 7663 +.. nonce: kzXdSX +.. section: Library + +Add importlib.util.resolve_name(). + +.. + +.. bpo: 14366 +.. date: 7662 +.. nonce: AnbUP0 +.. section: Library + +Support lzma compression in zip files. Patch by Serhiy Storchaka. + +.. + +.. bpo: 13959 +.. date: 7661 +.. nonce: VIJwXJ +.. section: Library + +Introduce importlib.find_loader() and document imp.find_module/load_module +as deprecated. + +.. + +.. bpo: 14082 +.. date: 7660 +.. nonce: jgCzs3 +.. section: Library + +shutil.copy2() now copies extended attributes, if possible. Patch by Hynek +Schlawack. + +.. + +.. bpo: 13959 +.. date: 7659 +.. nonce: CCfPrG +.. section: Library + +Make importlib.abc.FileLoader.load_module()/get_filename() and +importlib.machinery.ExtensionFileLoader.load_module() have their single +argument be optional. Allows for the replacement (and thus deprecation) of +imp.load_source()/load_package()/load_compiled(). + +.. + +.. bpo: 13959 +.. date: 7658 +.. nonce: Kl6QSe +.. section: Library + +imp.get_suffixes() has been deprecated in favour of the new attributes on +importlib.machinery: SOURCE_SUFFIXES, DEBUG_BYTECODE_SUFFIXES, +OPTIMIZED_BYTECODE_SUFFIXES, BYTECODE_SUFFIXES, and EXTENSION_SUFFIXES. This +led to an indirect deprecation of inspect.getmoduleinfo(). + +.. + +.. bpo: 14662 +.. date: 7657 +.. nonce: kBgGen +.. section: Library + +Prevent shutil failures on OS X when destination does not support chflag +operations. Patch by Hynek Schlawack. + +.. + +.. bpo: 14157 +.. date: 7656 +.. nonce: QVP6vO +.. section: Library + +Fix time.strptime failing without a year on February 29th. Patch by Hynek +Schlawack. + +.. + +.. bpo: 14753 +.. date: 7655 +.. nonce: axZ7-L +.. section: Library + +Make multiprocessing's handling of negative timeouts the same as it was in +Python 3.2. + +.. + +.. bpo: 14583 +.. date: 7654 +.. nonce: QKYopE +.. section: Library + +Fix importlib bug when a package's __init__.py would first import one of its +modules then raise an error. + +.. + +.. bpo: 14741 +.. date: 7653 +.. nonce: IaSwPq +.. section: Library + +Fix missing support for Ellipsis ('...') in parser module. + +.. + +.. bpo: 14697 +.. date: 7652 +.. nonce: JOYLPW +.. section: Library + +Fix missing support for set displays and set comprehensions in parser +module. + +.. + +.. bpo: 14701 +.. date: 7651 +.. nonce: Meb6lW +.. section: Library + +Fix missing support for 'raise ... from' in parser module. + +.. + +.. bpo: 0 +.. date: 7650 +.. nonce: wf3uxo +.. section: Library + +Add support for timeouts to the acquire() methods of multiprocessing's +lock/semaphore/condition proxies. + +.. + +.. bpo: 13989 +.. date: 7649 +.. nonce: 5E3_xK +.. section: Library + +Add support for text mode to gzip.open(). + +.. + +.. bpo: 14127 +.. date: 7648 +.. nonce: sWvoou +.. section: Library + +The os.stat() result object now provides three additional fields: +st_ctime_ns, st_mtime_ns, and st_atime_ns, providing those times as an +integer with nanosecond resolution. The functions os.utime(), os.lutimes(), +and os.futimes() now accept a new parameter, ns, which accepts mtime and +atime as integers with nanosecond resolution. + +.. + +.. bpo: 14127 +.. date: 7647 +.. nonce: rdG9eC +.. section: Library + +shutil.copystat now preserves exact mtime and atime on filesystems providing +nanosecond resolution. (See also: bpo-10148) + +.. + +.. bpo: 14958 +.. date: 7646 +.. nonce: bMisLB +.. section: IDLE + +Change IDLE systax highlighting to recognize all string and byte literals +supported in Python 3.3. + +.. + +.. bpo: 10997 +.. date: 7645 +.. nonce: D59Zo_ +.. section: IDLE + +Prevent a duplicate entry in IDLE's "Recent Files" menu. + +.. + +.. bpo: 14929 +.. date: 7644 +.. nonce: Aet5nc +.. section: IDLE + +Stop IDLE 3.x from closing on Unicode decode errors when grepping. Patch by +Roger Serwy. + +.. + +.. bpo: 12510 +.. date: 7643 +.. nonce: 4lv3RD +.. section: IDLE + +Attempting to get invalid tooltip no longer closes IDLE. Other tooltipss +have been corrected or improved and the number of tests has been tripled. +Original patch by Roger Serwy. + +.. + +.. bpo: 14695 +.. date: 7642 +.. nonce: BE5pE- +.. section: Tools/Demos + +Bring Tools/parser/unparse.py support up to date with the Python 3.3 +Grammar. + +.. + +.. bpo: 14472 +.. date: 7641 +.. nonce: KWzSni +.. section: Build + +Update .gitignore. Patch by Matej Cepl. + +.. + +.. bpo: 0 +.. date: 7640 +.. nonce: MbKrTb +.. section: Build + +Upgrade Windows library versions: bzip 1.0.6, OpenSSL 1.0.1c. + +.. + +.. bpo: 14693 +.. date: 7639 +.. nonce: __K1i7 +.. section: Build + +Under non-Windows platforms, hashlib's fallback modules are always compiled, +even if OpenSSL is present at build time. + +.. + +.. bpo: 13210 +.. date: 7638 +.. nonce: 7vR33E +.. section: Build + +Windows build now uses VS2010, ported from VS2008. + +.. + +.. bpo: 14705 +.. date: 7637 +.. nonce: rThBL5 +.. section: C API + +The PyArg_Parse() family of functions now support the 'p' format unit, which +accepts a "boolean predicate" argument. It converts any Python value into +an integer--0 if it is "false", and 1 otherwise. + +.. + +.. bpo: 14863 +.. date: 7636 +.. nonce: OHttZr +.. section: Documentation + +Update the documentation of os.fdopen() to reflect the fact that it's only a +thin wrapper around open() anymore. + +.. + +.. bpo: 14588 +.. date: 7635 +.. nonce: VLRx_E +.. section: Documentation + +The language reference now accurately documents the Python 3 class +definition process. Patch by Nick Coghlan. + +.. + +.. bpo: 14943 +.. date: 7634 +.. nonce: SrEzZ7 +.. section: Documentation + +Correct a default argument value for winreg.OpenKey and correctly list the +argument names in the function's explanation. diff --git a/Misc/NEWS.d/3.3.0b1.rst b/Misc/NEWS.d/3.3.0b1.rst new file mode 100644 index 00000000000000..60a6a85f469314 --- /dev/null +++ b/Misc/NEWS.d/3.3.0b1.rst @@ -0,0 +1,944 @@ +.. bpo: 0 +.. date: 7811 +.. nonce: W5Dg6D +.. release date: 27-Jun-2012 +.. section: Core and Builtins + +Fix a (most likely) very rare memory leak when calling main() and not being +able to decode a command-line argument. + +.. + +.. bpo: 14815 +.. date: 7810 +.. nonce: 45V0nb +.. section: Core and Builtins + +Use Py_ssize_t instead of long for the object hash, to preserve all 64 bits +of hash on Win64. + +.. + +.. bpo: 12268 +.. date: 7809 +.. nonce: Fa6oWZ +.. section: Core and Builtins + +File readline, readlines and read() or readall() methods no longer lose data +when an underlying read system call is interrupted. IOError is no longer +raised due to a read system call returning EINTR from within these methods. + +.. + +.. bpo: 11626 +.. date: 7808 +.. nonce: Cz1C0D +.. section: Core and Builtins + +Add _SizeT functions to stable ABI. + +.. + +.. bpo: 15142 +.. date: 7807 +.. nonce: 5oTAbU +.. section: Core and Builtins + +Fix reference leak when deallocating instances of types created using +PyType_FromSpec(). + +.. + +.. bpo: 10053 +.. date: 7806 +.. nonce: rOxp0i +.. section: Core and Builtins + +Don't close FDs when FileIO.__init__ fails. Loosely based on the work by +Hirokazu Yamamoto. + +.. + +.. bpo: 15096 +.. date: 7805 +.. nonce: -vHRNP +.. section: Core and Builtins + +Removed support for ur'' as the raw notation isn't compatible with Python +2.x's raw unicode strings. + +.. + +.. bpo: 13783 +.. date: 7804 +.. nonce: oAPO08 +.. section: Core and Builtins + +Generator objects now use the identifier APIs internally + +.. + +.. bpo: 14874 +.. date: 7803 +.. nonce: KWh9rA +.. section: Core and Builtins + +Restore charmap decoding speed to pre-PEP 393 levels. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15026 +.. date: 7802 +.. nonce: iJiLbE +.. section: Core and Builtins + +utf-16 encoding is now significantly faster (up to 10x). Patch by Serhiy +Storchaka. + +.. + +.. bpo: 11022 +.. date: 7801 +.. nonce: iWeA3q +.. section: Core and Builtins + +open() and io.TextIOWrapper are now calling +locale.getpreferredencoding(False) instead of locale.getpreferredencoding() +in text mode if the encoding is not specified. Don't change temporary the +locale encoding using locale.setlocale(), use the current locale encoding +instead of the user preferred encoding. + +.. + +.. bpo: 14673 +.. date: 7800 +.. nonce: 39dCQW +.. section: Core and Builtins + +Add Eric Snow's sys.implementation implementation. + +.. + +.. bpo: 15038 +.. date: 7799 +.. nonce: MfnJgf +.. section: Core and Builtins + +Optimize python Locks on Windows. + +.. + +.. bpo: 12288 +.. date: 7798 +.. nonce: EeBUVC +.. section: Library + +Consider '0' and '0.0' as valid initialvalue for tkinter SimpleDialog. + +.. + +.. bpo: 15512 +.. date: 7797 +.. nonce: JO3bbV +.. section: Library + +Add a __sizeof__ implementation for parser. Patch by Serhiy Storchaka. + +.. + +.. bpo: 15469 +.. date: 7796 +.. nonce: eFsJXX +.. section: Library + +Add a __sizeof__ implementation for deque objects. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15489 +.. date: 7795 +.. nonce: P9-vH9 +.. section: Library + +Add a __sizeof__ implementation for BytesIO objects. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15487 +.. date: 7794 +.. nonce: vtEBtw +.. section: Library + +Add a __sizeof__ implementation for buffered I/O objects. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15514 +.. date: 7793 +.. nonce: LrtaLi +.. section: Library + +Correct __sizeof__ support for cpu_set. Patch by Serhiy Storchaka. + +.. + +.. bpo: 15177 +.. date: 7792 +.. nonce: mugCse +.. section: Library + +Added dir_fd parameter to os.fwalk(). + +.. + +.. bpo: 15061 +.. date: 7791 +.. nonce: Tdc4LD +.. section: Library + +Re-implemented hmac.compare_digest() in C to prevent further timing analysis +and to support all buffer protocol aware objects as well as ASCII only str +instances safely. + +.. + +.. bpo: 15164 +.. date: 7790 +.. nonce: Cf_2-u +.. section: Library + +Change return value of platform.uname() from a plain tuple to a +collections.namedtuple. + +.. + +.. bpo: 0 +.. date: 7789 +.. nonce: pyCKJV +.. section: Library + +Support Mageia Linux in the platform module. + +.. + +.. bpo: 11678 +.. date: 7788 +.. nonce: nRPz5B +.. section: Library + +Support Arch linux in the platform module. + +.. + +.. bpo: 15118 +.. date: 7787 +.. nonce: Gwp7ck +.. section: Library + +Change return value of os.uname() and os.times() from plain tuples to +immutable iterable objects with named attributes (structseq objects). + +.. + +.. bpo: 0 +.. date: 7786 +.. nonce: t7_10R +.. section: Library + +Speed up _decimal by another 10-15% by caching the thread local context that +was last accessed. In the pi benchmark (64-bit platform, prec=9), _decimal +is now only 1.5x slower than float. + +.. + +.. bpo: 0 +.. date: 7785 +.. nonce: DfxA5d +.. section: Library + +Remove the packaging module, which is not ready for prime time. + +.. + +.. bpo: 15154 +.. date: 7784 +.. nonce: 6DL5F6 +.. section: Library + +Add "dir_fd" parameter to os.rmdir, remove "rmdir" parameter from os.remove +/ os.unlink. + +.. + +.. bpo: 4489 +.. date: 7783 +.. nonce: 80FMx7 +.. section: Library + +Add a shutil.rmtree that isn't susceptible to symlink attacks. It is used +automatically on platforms supporting the necessary os.openat() and +os.unlinkat() functions. Main code by Martin von Löwis. + +.. + +.. bpo: 15156 +.. date: 7782 +.. nonce: PZwcLE +.. section: Library + +HTMLParser now uses the new "html.entities.html5" dictionary. + +.. + +.. bpo: 11113 +.. date: 7781 +.. nonce: lFZ9C8 +.. section: Library + +add a new "html5" dictionary containing the named character references +defined by the HTML5 standard and the equivalent Unicode character(s) to the +html.entities module. + +.. + +.. bpo: 15114 +.. date: 7780 +.. nonce: Lgl5HS +.. section: Library + +the strict mode of HTMLParser and the HTMLParseError exception are +deprecated now that the parser is able to parse invalid markup. + +.. + +.. bpo: 3665 +.. date: 7779 +.. nonce: JdTN3o +.. section: Library + +\u and \U escapes are now supported in unicode regular expressions. Patch +by Serhiy Storchaka. + +.. + +.. bpo: 15153 +.. date: 7778 +.. nonce: 7Erki6 +.. section: Library + +Added inspect.getgeneratorlocals to simplify white box testing of generator +state updates + +.. + +.. bpo: 13062 +.. date: 7777 +.. nonce: E3N4GG +.. section: Library + +Added inspect.getclosurevars to simplify testing stateful closures + +.. + +.. bpo: 11024 +.. date: 7776 +.. nonce: sIkKrN +.. section: Library + +Fixes and additional tests for Time2Internaldate. + +.. + +.. bpo: 14626 +.. date: 7775 +.. nonce: YaNACw +.. section: Library + +Large refactoring of functions / parameters in the os module. Many functions +now support "dir_fd" and "follow_symlinks" parameters; some also support +accepting an open file descriptor in place of a path string. Added +os.support_* collections as LBYL helpers. Removed many functions only +previously seen in 3.3 alpha releases (often starting with "f" or "l", or +ending with "at"). Originally suggested by Serhiy Storchaka; implemented by +Larry Hastings. + +.. + +.. bpo: 15008 +.. date: 7774 +.. nonce: uNEUW0 +.. section: Library + +Implement PEP 362 "Signature Objects". Patch by Yury Selivanov. + +.. + +.. bpo: 15138 +.. date: 7773 +.. nonce: 46GZd_ +.. section: Library + +base64.urlsafe_{en,de}code() are now 3-4x faster. + +.. + +.. bpo: 444582 +.. date: 7772 +.. nonce: 5WoE2u +.. section: Library + +Add shutil.which, for finding programs on the system path. Original patch by +Erik Demaine, with later iterations by Jan Killian and Brian Curtin. + +.. + +.. bpo: 14837 +.. date: 7771 +.. nonce: vbThDc +.. section: Library + +SSL errors now have ``library`` and ``reason`` attributes describing +precisely what happened and in which OpenSSL submodule. The str() of a +SSLError is also enhanced accordingly. + +.. + +.. bpo: 9527 +.. date: 7770 +.. nonce: XkoH17 +.. section: Library + +datetime.astimezone() method will now supply a class timezone instance +corresponding to the system local timezone when called with no arguments. + +.. + +.. bpo: 14653 +.. date: 7769 +.. nonce: wxr1Hp +.. section: Library + +email.utils.mktime_tz() no longer relies on system mktime() when timezone +offest is supplied. + +.. + +.. bpo: 14684 +.. date: 7768 +.. nonce: OID9fT +.. section: Library + +zlib.compressobj() and zlib.decompressobj() now support the use of +predefined compression dictionaries. Original patch by Sam Rushing. + +.. + +.. bpo: 0 +.. date: 7767 +.. nonce: FbQz2w +.. section: Library + +Fix GzipFile's handling of filenames given as bytes objects. + +.. + +.. bpo: 14772 +.. date: 7766 +.. nonce: V7wcfU +.. section: Library + +Return destination values from some shutil functions. + +.. + +.. bpo: 15064 +.. date: 7765 +.. nonce: wPnVMo +.. section: Library + +Implement context manager protocol for multiprocessing types + +.. + +.. bpo: 15101 +.. date: 7764 +.. nonce: IWvk9X +.. section: Library + +Make pool finalizer avoid joining current thread. + +.. + +.. bpo: 14657 +.. date: 7763 +.. nonce: 8vzCOZ +.. section: Library + +The frozen instance of importlib used for bootstrap is now also the module +imported as importlib._bootstrap. + +.. + +.. bpo: 14055 +.. date: 7762 +.. nonce: ZbpXDl +.. section: Library + +Add __sizeof__ support to _elementtree. + +.. + +.. bpo: 15054 +.. date: 7761 +.. nonce: ksFSjl +.. section: Library + +A bug in tokenize.tokenize that caused string literals with 'b' prefixes to +be incorrectly tokenized has been fixed. Patch by Serhiy Storchaka. + +.. + +.. bpo: 15006 +.. date: 7760 +.. nonce: dsEK8l +.. section: Library + +Allow equality comparison between naive and aware time or datetime objects. + +.. + +.. bpo: 15036 +.. date: 7759 +.. nonce: Mhm512 +.. section: Library + +Mailbox no longer throws an error if a flush is done between operations when +removing or changing multiple items in mbox, MMDF, or Babyl mailboxes. + +.. + +.. bpo: 14059 +.. date: 7758 +.. nonce: XZqDyi +.. section: Library + +Implement multiprocessing.Barrier. + +.. + +.. bpo: 15061 +.. date: 7757 +.. nonce: tO-GpZ +.. section: Library + +The inappropriately named hmac.secure_compare has been renamed to +hmac.compare_digest, restricted to operating on bytes inputs only and had +its documentation updated to more accurately reflect both its intent and its +limitations + +.. + +.. bpo: 13841 +.. date: 7756 +.. nonce: -L7_Vz +.. section: Library + +Make child processes exit using sys.exit() on Windows. + +.. + +.. bpo: 14936 +.. date: 7755 +.. nonce: dWJWXJ +.. section: Library + +curses_panel was converted to PEP 3121 and PEP 384 API. Patch by Robin +Schreiber. + +.. + +.. bpo: 1667546 +.. date: 7754 +.. nonce: 0Ml07f +.. section: Library + +On platforms supporting tm_zone and tm_gmtoff fields in struct tm, +time.struct_time objects returned by time.gmtime(), time.localtime() and +time.strptime() functions now have tm_zone and tm_gmtoff attributes. +Original patch by Paul Boddie. + +.. + +.. bpo: 0 +.. date: 7753 +.. nonce: yI710S +.. section: Library + +Rename adjusted attribute to adjustable in time.get_clock_info() result. + +.. + +.. bpo: 3518 +.. date: 7752 +.. nonce: sAhuMS +.. section: Library + +Remove references to non-existent BaseManager.from_address() method. + +.. + +.. bpo: 13857 +.. date: 7751 +.. nonce: nM4Pjv +.. section: Library + +Added textwrap.indent() function (initial patch by Ezra Berch) + +.. + +.. bpo: 2736 +.. date: 7750 +.. nonce: 3ntjsv +.. section: Library + +Added datetime.timestamp() method. + +.. + +.. bpo: 13854 +.. date: 7749 +.. nonce: ms8PU3 +.. section: Library + +Make multiprocessing properly handle non-integer non-string argument to +SystemExit. + +.. + +.. bpo: 12157 +.. date: 7748 +.. nonce: awxWQJ +.. section: Library + +Make pool.map() empty iterables correctly. Initial patch by mouad. + +.. + +.. bpo: 11823 +.. date: 7747 +.. nonce: OYVwDs +.. section: Library + +disassembly now shows argument counts on calls with keyword args. + +.. + +.. bpo: 14711 +.. date: 7746 +.. nonce: Msj3S3 +.. section: Library + +os.stat_float_times() has been deprecated. + +.. + +.. bpo: 0 +.. date: 7745 +.. nonce: vKEq1w +.. section: Library + +LZMAFile now accepts the modes "rb"/"wb"/"ab" as synonyms of "r"/"w"/"a". + +.. + +.. bpo: 0 +.. date: 7744 +.. nonce: ic3GYd +.. section: Library + +The bz2 and lzma modules now each contain an open() function, allowing +compressed files to readily be opened in text mode as well as binary mode. + +.. + +.. bpo: 0 +.. date: 7743 +.. nonce: JZXYUZ +.. section: Library + +BZ2File.__init__() and LZMAFile.__init__() now accept a file object as their +first argument, rather than requiring a separate "fileobj" argument. + +.. + +.. bpo: 0 +.. date: 7742 +.. nonce: yr4hFr +.. section: Library + +gzip.open() now accepts file objects as well as filenames. + +.. + +.. bpo: 14992 +.. date: 7741 +.. nonce: BZpm2F +.. section: Library + +os.makedirs(path, exist_ok=True) would raise an OSError when the path +existed and had the S_ISGID mode bit set when it was not explicitly asked +for. This is no longer an exception as mkdir cannot control if the OS sets +that bit for it or not. + +.. + +.. bpo: 14989 +.. date: 7740 +.. nonce: ctDCrK +.. section: Library + +Make the CGI enable option to http.server available via command line. + +.. + +.. bpo: 14987 +.. date: 7739 +.. nonce: jqZ71e +.. section: Library + +Add a missing import statement to inspect. + +.. + +.. bpo: 1079 +.. date: 7738 +.. nonce: D5DJz8 +.. section: Library + +email.header.decode_header now correctly parses all the examples in RFC2047. +There is a necessary visible behavior change: the leading and/or trailing +whitespace on ASCII parts is now preserved. + +.. + +.. bpo: 14969 +.. date: 7737 +.. nonce: VBSxHs +.. section: Library + +Better handling of exception chaining in contextlib.ExitStack + +.. + +.. bpo: 14963 +.. date: 7736 +.. nonce: --tMTo +.. section: Library + +Convert contextlib.ExitStack.__exit__ to use an iterative algorithm (Patch +by Alon Horev) + +.. + +.. bpo: 14785 +.. date: 7735 +.. nonce: fYs65U +.. section: Library + +Add sys._debugmallocstats() to help debug low-level memory allocation issues + +.. + +.. bpo: 14443 +.. date: 7734 +.. nonce: p-bqtq +.. section: Library + +Ensure that .py files are byte-compiled with the correct Python executable +within bdist_rpm even on older versions of RPM + +.. + +.. bpo: 15146 +.. date: 7733 +.. nonce: 2Jz2so +.. section: C API + +Add PyType_FromSpecWithBases. Patch by Robin Schreiber. + +.. + +.. bpo: 15042 +.. date: 7732 +.. nonce: kYm4US +.. section: C API + +Add PyState_AddModule and PyState_RemoveModule. Add version guard for +Py_LIMITED_API additions. Patch by Robin Schreiber. + +.. + +.. bpo: 13783 +.. date: 7731 +.. nonce: g0bioG +.. section: C API + +Inadvertent additions to the public C API in the PEP 380 implementation have +either been removed or marked as private interfaces. + +.. + +.. bpo: 15000 +.. date: 7730 +.. nonce: 8XUbk3 +.. section: Library + +Support the "unique" x32 architecture in _posixsubprocess.c. + +.. + +.. bpo: 9803 +.. date: 7729 +.. nonce: lJhnei +.. section: IDLE + +Don't close IDLE on saving if breakpoint is open. Patch by Roger Serwy. + +.. + +.. bpo: 14962 +.. date: 7728 +.. nonce: W_t8Sw +.. section: IDLE + +Update text coloring in IDLE shell window after changing options. Patch by +Roger Serwy. + +.. + +.. bpo: 15176 +.. date: 7727 +.. nonce: HgYfxh +.. section: Documentation + +Clarified behavior, documentation, and implementation of os.listdir(). + +.. + +.. bpo: 14982 +.. date: 7726 +.. nonce: xKhYZ8 +.. section: Documentation + +Document that pkgutil's iteration functions require the non-standard +iter_modules() method to be defined by an importer (something the importlib +importers do not define). + +.. + +.. bpo: 15081 +.. date: 7725 +.. nonce: aCqyXV +.. section: Documentation + +Document PyState_FindModule. Patch by Robin Schreiber. + +.. + +.. bpo: 14814 +.. date: 7724 +.. nonce: La_dla +.. section: Documentation + +Added first draft of ipaddress module API reference + +.. + +.. bpo: 15187 +.. date: 7723 +.. nonce: bw-thN +.. section: Tests + +Bugfix: remove temporary directories test_shutil was leaving behind. + +.. + +.. bpo: 14769 +.. date: 7722 +.. nonce: WxaMcY +.. section: Tests + +test_capi now has SkipitemTest, which cleverly checks for "parity" between +PyArg_ParseTuple() and the Python/getargs.c static function skipitem() for +all possible "format units". + +.. + +.. bpo: 0 +.. date: 7721 +.. nonce: sQs1l0 +.. section: Tests + +test_nntplib now tolerates being run from behind NNTP gateways that add +"X-Antivirus" headers to articles + +.. + +.. bpo: 15043 +.. date: 7720 +.. nonce: R2j8Hb +.. section: Tests + +test_gdb is now skipped entirely if gdb security settings block loading of +the gdb hooks + +.. + +.. bpo: 14963 +.. date: 7719 +.. nonce: ds1Xe1 +.. section: Tests + +Add test cases for exception handling behaviour in contextlib.ExitStack +(Initial patch by Alon Horev) + +.. + +.. bpo: 13590 +.. date: 7718 +.. nonce: A_UtOA +.. section: Build + +Improve support for OS X Xcode 4: * Try to avoid building Python or +extension modules with problematic llvm-gcc compiler. * Since Xcode 4 +removes ppc support, extension module builds now check for ppc compiler +support and automatically remove ppc and ppc64 archs when not available. +* Since Xcode 4 no longer install SDKs in default locations, extension +module builds now revert to using installed headers and libs if the SDK +used to build the interpreter is not available. * Update ./configure +to use better defaults for universal builds; in particular, --enable- +universalsdk=yes uses the Xcode default SDK and --with-universal-archs +now defaults to "intel" if ppc not available. + +.. + +.. bpo: 14225 +.. date: 7717 +.. nonce: OrLFhQ +.. section: Build + +Fix Unicode support for curses (#12567) on OS X + +.. + +.. bpo: 14928 +.. date: 7716 +.. nonce: nAGpn8 +.. section: Build + +Fix importlib bootstrap issues by using a custom executable +(Modules/_freeze_importlib) to build Python/importlib.h. diff --git a/Misc/NEWS.d/3.3.0b2.rst b/Misc/NEWS.d/3.3.0b2.rst new file mode 100644 index 00000000000000..1fabf5caa1aae4 --- /dev/null +++ b/Misc/NEWS.d/3.3.0b2.rst @@ -0,0 +1,1117 @@ +.. bpo: 15568 +.. date: 7925 +.. nonce: 5EtMDi +.. release date: 12-Aug-2012 +.. section: Core and Builtins + +Fix the return value of ``yield from`` when StopIteration is raised by a +custom iterator. + +.. + +.. bpo: 13119 +.. date: 7924 +.. nonce: aseW65 +.. section: Core and Builtins + +`sys.stdout` and `sys.stderr` are now using "\r\n" newline on Windows, as +Python 2. + +.. + +.. bpo: 15534 +.. date: 7923 +.. nonce: 4Pyohe +.. section: Core and Builtins + +Fix the fast-search function for non-ASCII Unicode strings. + +.. + +.. bpo: 15508 +.. date: 7922 +.. nonce: KU2qVb +.. section: Core and Builtins + +Fix the docstring for `__import__()` to have the proper default value of 0 +for 'level' and to not mention negative levels since they are not supported. + +.. + +.. bpo: 15425 +.. date: 7921 +.. nonce: zCIhUA +.. section: Core and Builtins + +Eliminated traceback noise from more situations involving importlib. + +.. + +.. bpo: 14578 +.. date: 7920 +.. nonce: h-xy3r +.. section: Core and Builtins + +Support modules registered in the Windows registry again. + +.. + +.. bpo: 15466 +.. date: 7919 +.. nonce: 1DQAG_ +.. section: Core and Builtins + +Stop using TYPE_INT64 in marshal, to make importlib.h (and other byte code +files) equal between 32-bit and 64-bit systems. + +.. + +.. bpo: 1692335 +.. date: 7918 +.. nonce: BrUd_4 +.. section: Core and Builtins + +Move initial exception args assignment to `BaseException.__new__()` to help +pickling of naive subclasses. + +.. + +.. bpo: 12834 +.. date: 7917 +.. nonce: 2LoP3_ +.. section: Core and Builtins + +Fix `PyBuffer_ToContiguous()` for non-contiguous arrays. + +.. + +.. bpo: 15456 +.. date: 7916 +.. nonce: bOiKDB +.. section: Core and Builtins + +Fix code `__sizeof__()` after #12399 change. Patch by Serhiy Storchaka. + +.. + +.. bpo: 15404 +.. date: 7915 +.. nonce: KGT7_K +.. section: Core and Builtins + +Refleak in PyMethodObject repr. + +.. + +.. bpo: 15394 +.. date: 7914 +.. nonce: polWKA +.. section: Core and Builtins + +An issue in `PyModule_Create()` that caused references to be leaked on some +error paths has been fixed. Patch by Julia Lawall. + +.. + +.. bpo: 15368 +.. date: 7913 +.. nonce: l0rbQ4 +.. section: Core and Builtins + +An issue that caused bytecode generation to be non-deterministic has been +fixed. + +.. + +.. bpo: 15202 +.. date: 7912 +.. nonce: K02yPx +.. section: Core and Builtins + +Consistently use the name "follow_symlinks" for new parameters in os and +shutil functions. + +.. + +.. bpo: 15314 +.. date: 7911 +.. nonce: T3keLz +.. section: Core and Builtins + +``__main__.__loader__`` is now set correctly during interpreter startup. + +.. + +.. bpo: 15111 +.. date: 7910 +.. nonce: 1YYX9k +.. section: Core and Builtins + +When a module imported using 'from import' has an ImportError inside itself, +don't mask that fact behind a generic ImportError for the module itself. + +.. + +.. bpo: 15293 +.. date: 7909 +.. nonce: V0da2s +.. section: Core and Builtins + +Add GC support to the AST base node type. + +.. + +.. bpo: 15291 +.. date: 7908 +.. nonce: EZLsML +.. section: Core and Builtins + +Fix a memory leak where AST nodes where not properly deallocated. + +.. + +.. bpo: 15110 +.. date: 7907 +.. nonce: bZ0pao +.. section: Core and Builtins + +Fix the tracebacks generated by "import xxx" to not show the importlib stack +frames. + +.. + +.. bpo: 16369 +.. date: 7906 +.. nonce: GtRTux +.. section: Core and Builtins + +Global PyTypeObjects not initialized with PyType_Ready(...). + +.. + +.. bpo: 15020 +.. date: 7905 +.. nonce: 6h6cc- +.. section: Core and Builtins + +The program name used to search for Python's path is now "python3" under +Unix, not "python". + +.. + +.. bpo: 15897 +.. date: 7904 +.. nonce: GQpoBE +.. section: Core and Builtins + +zipimport.c doesn't check return value of fseek(). Patch by Felipe Cruz. + +.. + +.. bpo: 15033 +.. date: 7903 +.. nonce: gKl1Eg +.. section: Core and Builtins + +Fix the exit status bug when modules invoked using -m switch, return the +proper failure return value (1). Patch contributed by Jeff Knupp. + +.. + +.. bpo: 15229 +.. date: 7902 +.. nonce: hUWTFh +.. section: Core and Builtins + +An `OSError` subclass whose __init__ doesn't call back OSError.__init__ +could produce incomplete instances, leading to crashes when calling str() on +them. + +.. + +.. bpo: 15307 +.. date: 7901 +.. nonce: mFzbP4 +.. section: Core and Builtins + +Virtual environments now use symlinks with framework builds on Mac OS X, +like other POSIX builds. + +.. + +.. bpo: 14590 +.. date: 7900 +.. nonce: RPPwGW +.. section: Library + +configparser now correctly strips inline comments when delimiter occurs +earlier without preceding space. + +.. + +.. bpo: 15424 +.. date: 7899 +.. nonce: w6orRE +.. section: Library + +Add a `__sizeof__()` implementation for array objects. Patch by Ludwig +Hähne. + +.. + +.. bpo: 15576 +.. date: 7898 +.. nonce: twIC1T +.. section: Library + +Allow extension modules to act as a package's __init__ module. + +.. + +.. bpo: 15502 +.. date: 7897 +.. nonce: GTqgJP +.. section: Library + +Have `importlib.invalidate_caches()` work on `sys.meta_path` instead of +`sys.path_importer_cache`. + +.. + +.. bpo: 15163 +.. date: 7896 +.. nonce: EbXsEd +.. section: Library + +Pydoc shouldn't list __loader__ as module data. + +.. + +.. bpo: 15471 +.. date: 7895 +.. nonce: v2y8Qp +.. section: Library + +Do not use mutable objects as defaults for `importlib.__import__()`. + +.. + +.. bpo: 15559 +.. date: 7894 +.. nonce: VHs94w +.. section: Library + +To avoid a problematic failure mode when passed to the bytes constructor, +objects in the ipaddress module no longer implement `__index__()` (they +still implement `__int__()` as appropriate). + +.. + +.. bpo: 15546 +.. date: 7893 +.. nonce: 7Rbh2v +.. section: Library + +Fix handling of pathological input data in the peek() and read1() methods of +the BZ2File, GzipFile and LZMAFile classes. + +.. + +.. bpo: 12655 +.. date: 7892 +.. nonce: ZAyp7B +.. section: Library + +Instead of requiring a custom type, `os.sched_getaffinity()` and +`os.sched_setaffinity()` now use regular sets of integers to represent the +CPUs a process is restricted to. + +.. + +.. bpo: 15538 +.. date: 7891 +.. nonce: gWWn3s +.. section: Library + +Fix compilation of the `socket.getnameinfo()` / `socket.getaddrinfo()` +emulation code. Patch by Philipp Hagemeister. + +.. + +.. bpo: 15519 +.. date: 7890 +.. nonce: 2yTG4N +.. section: Library + +Properly expose WindowsRegistryFinder in importlib (and use the correct term +for it). Original patch by Eric Snow. + +.. + +.. bpo: 15502 +.. date: 7889 +.. nonce: _ap4my +.. section: Library + +Bring the importlib ABCs into line with the current state of the import +protocols given PEP 420. Original patch by Eric Snow. + +.. + +.. bpo: 15499 +.. date: 7888 +.. nonce: TRAS0u +.. section: Library + +Launching a webbrowser in Unix used to sleep for a few seconds. Original +patch by Anton Barkovsky. + +.. + +.. bpo: 15463 +.. date: 7887 +.. nonce: _sPf0r +.. section: Library + +The faulthandler module truncates strings to 500 characters, instead of 100, +to be able to display long file paths. + +.. + +.. bpo: 6056 +.. date: 7886 +.. nonce: nOnpDY +.. section: Library + +Make `multiprocessing` use setblocking(True) on the sockets it uses. +Original patch by J Derek Wilson. + +.. + +.. bpo: 15364 +.. date: 7885 +.. nonce: OM4nfW +.. section: Library + +Fix sysconfig.get_config_var('srcdir') to be an absolute path. + +.. + +.. bpo: 15413 +.. date: 7884 +.. nonce: mADROy +.. section: Library + +`os.times()` had disappeared under Windows. + +.. + +.. bpo: 15402 +.. date: 7883 +.. nonce: RTpYl_ +.. section: Library + +An issue in the struct module that caused `sys.getsizeof()` to return +incorrect results for struct.Struct instances has been fixed. Initial patch +by Serhiy Storchaka. + +.. + +.. bpo: 15232 +.. date: 7882 +.. nonce: AKjzKL +.. section: Library + +When mangle_from is True, `email.Generator` now correctly mangles lines that +start with 'From ' that occur in a MIME preamble or epilogue. + +.. + +.. bpo: 15094 +.. date: 7881 +.. nonce: _4f99s +.. section: Library + +Incorrectly placed #endif in _tkinter.c. Patch by Serhiy Storchaka. + +.. + +.. bpo: 13922 +.. date: 7880 +.. nonce: Bv_D0W +.. section: Library + +`argparse` no longer incorrectly strips '--'s that appear after the first +one. + +.. + +.. bpo: 12353 +.. date: 7879 +.. nonce: fYrcGJ +.. section: Library + +`argparse` now correctly handles null argument values. + +.. + +.. bpo: 10017 +.. date: 7878 +.. nonce: CswD6I +.. section: Library + +Fix TypeError using pprint on dictionaries with user-defined types as keys +or other unorderable keys. (See also: bpo-14998) + +.. + +.. bpo: 15397 +.. date: 7877 +.. nonce: xaA9nH +.. section: Library + +`inspect.getmodulename()` is now based directly on importlib via a new +`importlib.machinery.all_suffixes()` API. + +.. + +.. bpo: 14635 +.. date: 7876 +.. nonce: oyc5AR +.. section: Library + +`telnetlib` will use poll() rather than select() when possible to avoid +failing due to the select() file descriptor limit. + +.. + +.. bpo: 15180 +.. date: 7875 +.. nonce: CPeO5l +.. section: Library + +Clarify posixpath.join() error message when mixing str & bytes. + +.. + +.. bpo: 15343 +.. date: 7874 +.. nonce: zT5uuJ +.. section: Library + +pkgutil now includes an iter_importer_modules implementation for +importlib.machinery.FileFinder (similar to the way it already handled +zipimport.zipimporter). + +.. + +.. bpo: 15314 +.. date: 7873 +.. nonce: 1kHyrO +.. section: Library + +runpy now sets __main__.__loader__ correctly. + +.. + +.. bpo: 15357 +.. date: 7872 +.. nonce: fCWRb1 +.. section: Library + +The import emulation in pkgutil is now deprecated. pkgutil uses importlib +internally rather than the emulation. + +.. + +.. bpo: 15233 +.. date: 7871 +.. nonce: 8YQW0- +.. section: Library + +Python now guarantees that callables registered with the atexit module will +be called in a deterministic order. + +.. + +.. bpo: 15238 +.. date: 7870 +.. nonce: hBKF6z +.. section: Library + +`shutil.copystat()` now copies Linux "extended attributes". + +.. + +.. bpo: 15230 +.. date: 7869 +.. nonce: hF8Df5 +.. section: Library + +runpy.run_path now correctly sets __package__ as described in the +documentation. + +.. + +.. bpo: 15315 +.. date: 7868 +.. nonce: MDcIoC +.. section: Library + +Support VS 2010 in distutils cygwincompiler. + +.. + +.. bpo: 15294 +.. date: 7867 +.. nonce: s_sHkY +.. section: Library + +Fix a regression in pkgutil.extend_path()'s handling of nested namespace +packages. + +.. + +.. bpo: 15056 +.. date: 7866 +.. nonce: _hOdjz +.. section: Library + +`imp.cache_from_source()` and `imp.source_from_cache()` raise +NotImplementedError when `sys.implementation.cache_tag` is set to None. + +.. + +.. bpo: 15256 +.. date: 7865 +.. nonce: j5YTHm +.. section: Library + +Grammatical mistake in exception raised by `imp.find_module()`. + +.. + +.. bpo: 5931 +.. date: 7864 +.. nonce: VKqYde +.. section: Library + +`wsgiref` environ variable SERVER_SOFTWARE will specify an implementation +specific term like CPython, Jython instead of generic "Python". + +.. + +.. bpo: 13248 +.. date: 7863 +.. nonce: N0Q9xt +.. section: Library + +Remove obsolete argument "max_buffer_size" of BufferedWriter and +BufferedRWPair, from the io module. + +.. + +.. bpo: 13248 +.. date: 7862 +.. nonce: _3vbnO +.. section: Library + +Remove obsolete argument "version" of `argparse.ArgumentParser`. + +.. + +.. bpo: 14814 +.. date: 7861 +.. nonce: W1kVVL +.. section: Library + +Implement more consistent ordering and sorting behaviour for ipaddress +objects. + +.. + +.. bpo: 14814 +.. date: 7860 +.. nonce: I6pgMy +.. section: Library + +`ipaddress` network objects correctly return NotImplemented when compared to +arbitrary objects instead of raising TypeError. + +.. + +.. bpo: 14990 +.. date: 7859 +.. nonce: -Zc9sh +.. section: Library + +Correctly fail with SyntaxError on invalid encoding declaration. + +.. + +.. bpo: 14814 +.. date: 7858 +.. nonce: jojpI0 +.. section: Library + +`ipaddress` now provides more informative error messages when constructing +instances directly (changes permitted during beta due to provisional API +status). + +.. + +.. bpo: 15247 +.. date: 7857 +.. nonce: LPO5XB +.. section: Library + +`io.FileIO` now raises an error when given a file descriptor pointing to a +directory. + +.. + +.. bpo: 15261 +.. date: 7856 +.. nonce: XiGTFG +.. section: Library + +Stop os.stat(fd) crashing on Windows when fd not open. + +.. + +.. bpo: 15166 +.. date: 7855 +.. nonce: R5xIH3 +.. section: Library + +Implement `imp.get_tag()` using `sys.implementation.cache_tag`. + +.. + +.. bpo: 15210 +.. date: 7854 +.. nonce: SOwAHs +.. section: Library + +Catch KeyError when `importlib.__init__()` can't find _frozen_importlib in +sys.modules, not ImportError. + +.. + +.. bpo: 15030 +.. date: 7853 +.. nonce: x8Nujl +.. section: Library + +`importlib.abc.PyPycLoader` now supports the new source size header field in +.pyc files. + +.. + +.. bpo: 5346 +.. date: 7852 +.. nonce: pFwRO0 +.. section: Library + +Preserve permissions of mbox, MMDF and Babyl mailbox files on flush(). + +.. + +.. bpo: 10571 +.. date: 7851 +.. nonce: X5MB7m +.. section: Library + +Fix the "--sign" option of distutils' upload command. Patch by Jakub Wilk. + +.. + +.. bpo: 9559 +.. date: 7850 +.. nonce: j_O5FY +.. section: Library + +If messages were only added, a new file is no longer created and renamed +over the old file when flush() is called on an mbox, MMDF or Babyl mailbox. + +.. + +.. bpo: 10924 +.. date: 7849 +.. nonce: hzTAWl +.. section: Library + +Fixed `crypt.mksalt()` to use a RNG that is suitable for cryptographic +purpose. + +.. + +.. bpo: 15184 +.. date: 7848 +.. nonce: _o9qHk +.. section: Library + +Ensure consistent results of OS X configuration tailoring for universal +builds by factoring out common OS X-specific customizations from sysconfig, +distutils.sysconfig, distutils.util, and distutils.unixccompiler into a new +module _osx_support. + +.. + +.. bpo: 15610 +.. date: 7847 +.. nonce: 9i-ogW +.. section: C API + +`PyImport_ImportModuleEx()` now uses a 'level' of 0 instead of -1. + +.. + +.. bpo: 15169 +.. date: 7846 +.. nonce: TiQMCK +.. section: C API + +Strip out the C implementation of `imp.source_from_cache()` used by +PyImport_ExecCodeModuleWithPathnames() and used the Python code instead. +Leads to PyImport_ExecCodeModuleObject() to not try to infer the source path +from the bytecode path as PyImport_ExecCodeModuleWithPathnames() does. (See +also: bpo-14599) + +.. + +.. bpo: 6493 +.. date: 7845 +.. nonce: TsfKuQ +.. section: Library + +An issue in ctypes on Windows that caused structure bitfields of type +`ctypes.c_uint32` and width 32 to incorrectly be set has been fixed. + +.. + +.. bpo: 15194 +.. date: 7844 +.. nonce: X7uUdw +.. section: Library + +Update libffi to the 3.0.11 release. + +.. + +.. bpo: 13052 +.. date: 7843 +.. nonce: uLYm16 +.. section: IDLE + +Fix IDLE crashing when replace string in Search/Replace dialog ended with +``\``. Patch by Roger Serwy. + +.. + +.. bpo: 15458 +.. date: 7842 +.. nonce: yqKQVd +.. section: Tools/Demos + +python-config gets a new option --configdir to print the $LIBPL value. + +.. + +.. bpo: 0 +.. date: 7841 +.. nonce: GMHP1o +.. section: Tools/Demos + +Move importlib.test.benchmark to Tools/importbench. + +.. + +.. bpo: 12605 +.. date: 7840 +.. nonce: GsN07w +.. section: Tools/Demos + +The gdb hooks for debugging CPython (within Tools/gdb) have been enhanced to +show information on more C frames relevant to CPython within the "py-bt" and +"py-bt-full" commands: + +* C frames that are waiting on the GIL +* C frames that are garbage-collecting +* C frames that are due to the invocation of a PyCFunction + +.. + +.. bpo: 15041 +.. date: 7839 +.. nonce: nMyhwF +.. section: Documentation + +Update "see also" list in tkinter documentation. + +.. + +.. bpo: 15444 +.. date: 7838 +.. nonce: VpoVrT +.. section: Documentation + +Use proper spelling for non-ASCII contributor names. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15295 +.. date: 7837 +.. nonce: 74vVdW +.. section: Documentation + +Reorganize and rewrite the documentation on the import system. + +.. + +.. bpo: 15230 +.. date: 7836 +.. nonce: gSl9Ew +.. section: Documentation + +Clearly document some of the limitations of the runpy module and nudge +readers towards importlib when appropriate. + +.. + +.. bpo: 15053 +.. date: 7835 +.. nonce: Icoig1 +.. section: Documentation + +Copy Python 3.3 import lock change notice to all relevant functions in imp +instead of just at the top of the relevant section. + +.. + +.. bpo: 15288 +.. date: 7834 +.. nonce: S9JauN +.. section: Documentation + +Link to the term "loader" in notes in pkgutil about how things won't work as +expected in Python 3.3 and mark the requisite functions as "changed" since +they will no longer work with modules directly imported by import itself. + +.. + +.. bpo: 13557 +.. date: 7833 +.. nonce: hxoRWL +.. section: Documentation + +Clarify effect of giving two different namespaces to `exec()` or +`execfile()`. + +.. + +.. bpo: 15250 +.. date: 7832 +.. nonce: 1UQaan +.. section: Documentation + +Document that `filecmp.dircmp()` compares files shallowly. Patch contributed +by Chris Jerdonek. + +.. + +.. bpo: 15442 +.. date: 7831 +.. nonce: xkvBID +.. section: Documentation + +Expose the default list of directories ignored by `filecmp.dircmp()` as a +module attribute, and expand the list to more modern values. + +.. + +.. bpo: 15467 +.. date: 7830 +.. nonce: 18o7uj +.. section: Tests + +Move helpers for `__sizeof__()` tests into test_support. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15320 +.. date: 7829 +.. nonce: D9sGMO +.. section: Tests + +Make iterating the list of tests thread-safe when running tests in +multiprocess mode. Patch by Chris Jerdonek. + +.. + +.. bpo: 15168 +.. date: 7828 +.. nonce: 5Wgbv5 +.. section: Tests + +Move `importlib.test` to `test.test_importlib`. + +.. + +.. bpo: 15091 +.. date: 7827 +.. nonce: 66ZPS6 +.. section: Tests + +Reactivate a test on UNIX which was failing thanks to a forgotten +`importlib.invalidate_caches()` call. + +.. + +.. bpo: 15230 +.. date: 7826 +.. nonce: WoWqyy +.. section: Tests + +Adopted a more systematic approach in the runpy tests. + +.. + +.. bpo: 15300 +.. date: 7825 +.. nonce: Gh3GXC +.. section: Tests + +Ensure the temporary test working directories are in the same parent folder +when running tests in multiprocess mode from a Python build. Patch by Chris +Jerdonek. + +.. + +.. bpo: 15284 +.. date: 7824 +.. nonce: eNb_mn +.. section: Tests + +Skip {send,recv}msg tests in test_socket when IPv6 is not enabled. Patch by +Brian Brazil. + +.. + +.. bpo: 15277 +.. date: 7823 +.. nonce: EIIXc8 +.. section: Tests + +Fix a resource leak in support.py when IPv6 is disabled. Patch by Brian +Brazil. + +.. + +.. bpo: 11715 +.. date: 7822 +.. nonce: n-NQIf +.. section: Build + +Fix multiarch detection without having Debian development tools (dpkg-dev) +installed. + +.. + +.. bpo: 15037 +.. date: 7821 +.. nonce: SNQtrw +.. section: Build + +Build OS X installers with local copy of ncurses 5.9 libraries to avoid +curses.unget_wch bug present in older versions of ncurses such as those +shipped with OS X. + +.. + +.. bpo: 15560 +.. date: 7820 +.. nonce: VpYY1z +.. section: Build + +Fix building _sqlite3 extension on OS X with an SDK. Also, for OS X +installers, ensure consistent sqlite3 behavior and feature availability by +building a local copy of libsqlite3 rather than depending on the wide range +of versions supplied with various OS X releases. + +.. + +.. bpo: 8847 +.. date: 7819 +.. nonce: lqI_r8 +.. section: Build + +Disable COMDAT folding in Windows PGO builds. + +.. + +.. bpo: 14018 +.. date: 7818 +.. nonce: RHawO_ +.. section: Build + +Fix OS X Tcl/Tk framework checking when using OS X SDKs. + +.. + +.. bpo: 16256 +.. date: 7817 +.. nonce: vrx66r +.. section: Build + +OS X installer now sets correct permissions for doc directory. + +.. + +.. bpo: 15431 +.. date: 7816 +.. nonce: veQwgP +.. section: Build + +Add _freeze_importlib project to regenerate importlib.h on Windows. Patch by +Kristján Valur Jónsson. + +.. + +.. bpo: 14197 +.. date: 7815 +.. nonce: Jyukle +.. section: Build + +For OS X framework builds, ensure links to the shared library are created +with the proper ABI suffix. + +.. + +.. bpo: 14330 +.. date: 7814 +.. nonce: DrQcsD +.. section: Build + +For cross builds, don't use host python, use host search paths for host +compiler. + +.. + +.. bpo: 15235 +.. date: 7813 +.. nonce: kDP-3- +.. section: Build + +Allow Berkley DB versions up to 5.3 to build the dbm module. + +.. + +.. bpo: 15268 +.. date: 7812 +.. nonce: xCKPyN +.. section: Build + +Search curses.h in /usr/include/ncursesw. diff --git a/Misc/NEWS.d/3.3.0rc1.rst b/Misc/NEWS.d/3.3.0rc1.rst new file mode 100644 index 00000000000000..4f9d08db11efb0 --- /dev/null +++ b/Misc/NEWS.d/3.3.0rc1.rst @@ -0,0 +1,411 @@ +.. bpo: 15573 +.. date: 7967 +.. nonce: 6-QAPO +.. release date: 25-Aug-2012 +.. section: Core and Builtins + +memoryview comparisons are now performed by value with full support for any +valid struct module format definition. + +.. + +.. bpo: 15316 +.. date: 7966 +.. nonce: kFKLpQ +.. section: Core and Builtins + +When an item in the fromlist for `__import__()` doesn't exist, don't raise +an error, but if an exception is raised as part of an import do let that +propagate. + +.. + +.. bpo: 15778 +.. date: 7965 +.. nonce: URaMpQ +.. section: Core and Builtins + +Ensure that ``str(ImportError(msg))`` returns a str even when msg isn't a +str. + +.. + +.. bpo: 2051 +.. date: 7964 +.. nonce: ATEUvX +.. section: Core and Builtins + +Source file permission bits are once again correctly copied to the cached +bytecode file. (The migration to importlib reintroduced this problem because +these was no regression test. A test has been added as part of this patch) + +.. + +.. bpo: 15761 +.. date: 7963 +.. nonce: PLrF5o +.. section: Core and Builtins + +Fix crash when ``PYTHONEXECUTABLE`` is set on Mac OS X. + +.. + +.. bpo: 15726 +.. date: 7962 +.. nonce: PC56aB +.. section: Core and Builtins + +Fix incorrect bounds checking in PyState_FindModule. Patch by Robin +Schreiber. + +.. + +.. bpo: 15604 +.. date: 7961 +.. nonce: SJAkFr +.. section: Core and Builtins + +Update uses of `PyObject_IsTrue()` to check for and handle errors correctly. +Patch by Serhiy Storchaka. + +.. + +.. bpo: 14846 +.. date: 7960 +.. nonce: jI2Zl_ +.. section: Core and Builtins + +`importlib.FileFinder` now handles the case where the directory being +searched is removed after a previous import attempt. + +.. + +.. bpo: 13370 +.. date: 7959 +.. nonce: KobXSZ +.. section: Library + +Ensure that ctypes works on Mac OS X when Python is compiled using the clang +compiler. + +.. + +.. bpo: 13072 +.. date: 7958 +.. nonce: HlsZI- +.. section: Library + +The array module's 'u' format code is now deprecated and will be removed in +Python 4.0. + +.. + +.. bpo: 15544 +.. date: 7957 +.. nonce: 3QjWdU +.. section: Library + +Fix Decimal.__float__ to work with payload-carrying NaNs. + +.. + +.. bpo: 15776 +.. date: 7956 +.. nonce: --Euj0 +.. section: Library + +Allow pyvenv to work in existing directory with --clean. + +.. + +.. bpo: 15249 +.. date: 7955 +.. nonce: ho-Io6 +.. section: Library + +email's BytesGenerator now correctly mangles From lines (when requested) +even if the body contains undecodable bytes. + +.. + +.. bpo: 15777 +.. date: 7954 +.. nonce: AVmvaJ +.. section: Library + +Fix a refleak in _posixsubprocess. + +.. + +.. bpo: 665194 +.. date: 7953 +.. nonce: AECTWV +.. section: Library + +Update `email.utils.localtime` to use datetime.astimezone and correctly +handle historic changes in UTC offsets. + +.. + +.. bpo: 15199 +.. date: 7952 +.. nonce: iOOV1X +.. section: Library + +Fix JavaScript's default MIME type to application/javascript. Patch by +Bohuslav Kabrda. + +.. + +.. bpo: 12643 +.. date: 7951 +.. nonce: Jy2fyw +.. section: Library + +`code.InteractiveConsole` now respects `sys.excepthook` when displaying +exceptions. Patch by Aaron Iles. + +.. + +.. bpo: 13579 +.. date: 7950 +.. nonce: SqZ8Sq +.. section: Library + +`string.Formatter` now understands the 'a' conversion specifier. + +.. + +.. bpo: 15595 +.. date: 7949 +.. nonce: dk1eKQ +.. section: Library + +Fix ``subprocess.Popen(universal_newlines=True)`` for certain locales +(utf-16 and utf-32 family). Patch by Chris Jerdonek. + +.. + +.. bpo: 15477 +.. date: 7948 +.. nonce: 9gGqPw +.. section: Library + +In cmath and math modules, add workaround for platforms whose system- +supplied log1p function doesn't respect signs of zeros. + +.. + +.. bpo: 15715 +.. date: 7947 +.. nonce: 3g_xGx +.. section: Library + +`importlib.__import__()` will silence an ImportError when the use of +fromlist leads to a failed import. + +.. + +.. bpo: 14669 +.. date: 7946 +.. nonce: mVYj1T +.. section: Library + +Fix pickling of connections and sockets on Mac OS X by sending/receiving an +acknowledgment after file descriptor transfer. TestPicklingConnection has +been reenabled for Mac OS X. + +.. + +.. bpo: 11062 +.. date: 7945 +.. nonce: ZhTF21 +.. section: Library + +Fix adding a message from file to Babyl mailbox. + +.. + +.. bpo: 15646 +.. date: 7944 +.. nonce: bzzL5z +.. section: Library + +Prevent equivalent of a fork bomb when using `multiprocessing` on Windows +without the ``if __name__ == '__main__'`` idiom. + +.. + +.. bpo: 15678 +.. date: 7943 +.. nonce: Uq5eEl +.. section: IDLE + +Fix IDLE menus when started from OS X command line (3.3.0b2 regression). + +.. + +.. bpo: 0 +.. date: 7942 +.. nonce: 2necKS +.. section: Documentation + +Touched up the Python 2 to 3 porting guide. + +.. + +.. bpo: 14674 +.. date: 7941 +.. nonce: VC9ve3 +.. section: Documentation + +Add a discussion of the `json` module's standard compliance. Patch by Chris +Rebert. + +.. + +.. bpo: 0 +.. date: 7940 +.. nonce: BGYuhC +.. section: Documentation + +Create a 'Concurrent Execution' section in the docs, and split up the +'Optional Operating System Services' section to use a more user-centric +classification scheme (splitting them across the new CE section, IPC and +text processing). Operating system limitations can be reflected with the +Sphinx ``:platform:`` tag, it doesn't make sense as part of the Table of +Contents. + +.. + +.. bpo: 4966 +.. date: 7939 +.. nonce: -5pabe +.. section: Documentation + +Bring the sequence docs up to date for the Py3k transition and the many +language enhancements since they were original written. + +.. + +.. bpo: 0 +.. date: 7938 +.. nonce: jD4Bea +.. section: Documentation + +The "path importer" misnomer has been replaced with Eric Snow's more- +awkward-but-at-least-not-wrong suggestion of "path based finder" in the +import system reference docs. + +.. + +.. bpo: 15640 +.. date: 7937 +.. nonce: qijhlP +.. section: Documentation + +Document `importlib.abc.Finder` as deprecated. + +.. + +.. bpo: 15630 +.. date: 7936 +.. nonce: 1E1IGr +.. section: Documentation + +Add an example for "continue" stmt in the tutorial. Patch by Daniel Ellis. + +.. + +.. bpo: 15747 +.. date: 7935 +.. nonce: An6Xbj +.. section: Tests + +ZFS always returns EOPNOTSUPP when attempting to set the UF_IMMUTABLE flag +(via either chflags or lchflags); refactor affected tests in test_posix.py +to account for this. + +.. + +.. bpo: 15285 +.. date: 7934 +.. nonce: rJh9vn +.. section: Tests + +Refactor the approach for testing connect timeouts using two external hosts +that have been configured specifically for this type of test. + +.. + +.. bpo: 15743 +.. date: 7933 +.. nonce: k_VrGz +.. section: Tests + +Remove the deprecated method usage in `urllib` tests. Patch by Jeff Knupp. + +.. + +.. bpo: 15615 +.. date: 7932 +.. nonce: pjU4Wf +.. section: Tests + +Add some tests for the `json` module's handling of invalid input data. +Patch by Kushal Das. + +.. + +.. bpo: 0 +.. date: 7931 +.. nonce: SVSrkA +.. section: Build + +Output lib files for PGO build into PGO directory. + +.. + +.. bpo: 0 +.. date: 7930 +.. nonce: KlXR19 +.. section: Build + +Pick up 32-bit launcher from PGO directory on 64-bit PGO build. + +.. + +.. bpo: 0 +.. date: 7929 +.. nonce: rErpCh +.. section: Build + +Drop ``PC\python_nt.h`` as it's not used. Add input dependency on custom +build step. + +.. + +.. bpo: 15511 +.. date: 7928 +.. nonce: Fli23V +.. section: Build + +Drop explicit dependency on pythonxy.lib from _decimal amd64 configuration. + +.. + +.. bpo: 0 +.. date: 7927 +.. nonce: UI3Nwa +.. section: Build + +Add missing PGI/PGO configurations for pywlauncher. + +.. + +.. bpo: 15645 +.. date: 7926 +.. nonce: aLjenQ +.. section: Build + +Ensure 2to3 grammar pickles are properly installed. diff --git a/Misc/NEWS.d/3.3.0rc2.rst b/Misc/NEWS.d/3.3.0rc2.rst new file mode 100644 index 00000000000000..e8c3d2fef3bb97 --- /dev/null +++ b/Misc/NEWS.d/3.3.0rc2.rst @@ -0,0 +1,122 @@ +.. bpo: 13992 +.. date: 7979 +.. nonce: NtESXo +.. release date: 09-Sep-2012 +.. section: Core and Builtins + +The trashcan mechanism is now thread-safe. This eliminates sporadic crashes +in multi-thread programs when several long deallocator chains ran +concurrently and involved subclasses of built-in container types. + +.. + +.. bpo: 15784 +.. date: 7978 +.. nonce: zeVMus +.. section: Core and Builtins + +Modify `OSError`.__str__() to better distinguish between errno error numbers +and Windows error numbers. + +.. + +.. bpo: 15781 +.. date: 7977 +.. nonce: kNkd0Y +.. section: Core and Builtins + +Fix two small race conditions in import's module locking. + +.. + +.. bpo: 17158 +.. date: 7976 +.. nonce: vU3389 +.. section: Library + +Add 'symbols' to help() welcome message; clarify 'modules spam' messages. + +.. + +.. bpo: 15847 +.. date: 7975 +.. nonce: kB0FUD +.. section: Library + +Fix a regression in argparse, which did not accept tuples as argument lists +anymore. + +.. + +.. bpo: 15828 +.. date: 7974 +.. nonce: EW3Br7 +.. section: Library + +Restore support for C extensions in `imp.load_module()`. + +.. + +.. bpo: 15340 +.. date: 7973 +.. nonce: ThJxoy +.. section: Library + +Fix importing the random module when ``/dev/urandom`` cannot be opened. +This was a regression caused by the hash randomization patch. + +.. + +.. bpo: 10650 +.. date: 7972 +.. nonce: FImkq4 +.. section: Library + +Deprecate the watchexp parameter of the `Decimal.quantize()` method. + +.. + +.. bpo: 15785 +.. date: 7971 +.. nonce: VZfOJY +.. section: Library + +Modify `window.get_wch()` API of the curses module: return a character for +most keys, and an integer for special keys, instead of always returning an +integer. So it is now possible to distinguish special keys like keypad keys. + +.. + +.. bpo: 14223 +.. date: 7970 +.. nonce: oVuUDj +.. section: Library + +Fix `window.addch()` of the curses module for special characters like +curses.ACS_HLINE: the Python function addch(int) and addch(bytes) is now +calling the C function waddch()/mvwaddch() (as it was done in Python 3.2), +instead of wadd_wch()/mvwadd_wch(). The Python function addch(str) is still +calling the C function wadd_wch()/mvwadd_wch() if the Python curses is +linked to libncursesw. + +.. + +.. bpo: 15822 +.. date: 7969 +.. nonce: SNlKd9 +.. section: Build + +Really ensure 2to3 grammar pickles are properly installed (replaces fixes +for Issue #15645). + +.. + +.. bpo: 15814 +.. date: 7968 +.. nonce: JleLly +.. section: Documentation + +The memoryview enhancements in 3.3.0 accidentally permitted the hashing of +multi-dimensional memorviews and memoryviews with multi-byte item formats. +The intended restrictions have now been documented - they will be correctly +enforced in 3.3.1. diff --git a/Misc/NEWS.d/3.3.0rc3.rst b/Misc/NEWS.d/3.3.0rc3.rst new file mode 100644 index 00000000000000..408790823e06df --- /dev/null +++ b/Misc/NEWS.d/3.3.0rc3.rst @@ -0,0 +1,98 @@ +.. bpo: 15900 +.. date: 7989 +.. nonce: yot4lz +.. release date: 23-Sep-2012 +.. section: Core and Builtins + +Fix reference leak in `PyUnicode_TranslateCharmap()`. + +.. + +.. bpo: 15926 +.. date: 7988 +.. nonce: g2IIQa +.. section: Core and Builtins + +Fix crash after multiple reinitializations of the interpreter. + +.. + +.. bpo: 15895 +.. date: 7987 +.. nonce: KirUDy +.. section: Core and Builtins + +Fix FILE pointer leak in one error branch of `PyRun_SimpleFileExFlags()` +when filename points to a pyc/pyo file, closeit is false an and +set_main_loader() fails. + +.. + +.. bpo: 0 +.. date: 7986 +.. nonce: MMXe9c +.. section: Core and Builtins + +Fixes for a few crash and memory leak regressions found by Coverity. + +.. + +.. bpo: 15882 +.. date: 7985 +.. nonce: tDRdOi +.. section: Library + +Change `_decimal` to accept any coefficient tuple when constructing +infinities. This is done for backwards compatibility with decimal.py: +Infinity coefficients are undefined in _decimal (in accordance with the +specification). + +.. + +.. bpo: 15925 +.. date: 7984 +.. nonce: ar8SuV +.. section: Library + +Fix a regression in `email.util` where the `parsedate()` and +`parsedate_tz()` functions did not return None anymore when the argument +could not be parsed. + +.. + +.. bpo: 15973 +.. date: 7983 +.. nonce: y4zCIp +.. section: Library + +Fix a segmentation fault when comparing datetime timezone objects. + +.. + +.. bpo: 15977 +.. date: 7982 +.. nonce: TElugq +.. section: Library + +Fix memory leak in Modules/_ssl.c when the function _set_npn_protocols() is +called multiple times, thanks to Daniel Sommermann. + +.. + +.. bpo: 15969 +.. date: 7981 +.. nonce: dX5BRm +.. section: Library + +`faulthandler` module: rename dump_tracebacks_later() to +dump_traceback_later() and cancel_dump_tracebacks_later() to +cancel_dump_traceback_later(). + +.. + +.. bpo: 0 +.. date: 7980 +.. nonce: ZqEirp +.. section: Library + +_decimal module: use only C 89 style comments. diff --git a/Misc/NEWS.d/3.4.0.rst b/Misc/NEWS.d/3.4.0.rst new file mode 100644 index 00000000000000..03bd0235651ef7 --- /dev/null +++ b/Misc/NEWS.d/3.4.0.rst @@ -0,0 +1,17 @@ +.. bpo: 20939 +.. date: 9341 +.. nonce: MX5O4e +.. release date: 2014-03-16 +.. section: Library + +Fix test_geturl failure in test_urllibnet due to new redirect of +http://www.python.org/ to https://www.python.org. + +.. + +.. bpo: 0 +.. date: 9340 +.. nonce: 1hrH2G +.. section: Documentation + +Merge in all documentation changes since branching 3.4.0rc1. diff --git a/Misc/NEWS.d/3.4.0a1.rst b/Misc/NEWS.d/3.4.0a1.rst new file mode 100644 index 00000000000000..1860e4d46df480 --- /dev/null +++ b/Misc/NEWS.d/3.4.0a1.rst @@ -0,0 +1,7206 @@ +.. bpo: 16741 +.. date: 8734 +.. nonce: bBBAqs +.. release date: 2013-08-03 +.. section: Core and Builtins + +Fix an error reporting in int(). + +.. + +.. bpo: 17899 +.. date: 8733 +.. nonce: Asq8mo +.. section: Core and Builtins + +Fix rare file descriptor leak in os.listdir(). + +.. + +.. bpo: 10241 +.. date: 8732 +.. nonce: V_nZk4 +.. section: Core and Builtins + +Clear extension module dict copies at interpreter shutdown. Patch by Neil +Schemenauer, minimally modified. + +.. + +.. bpo: 9035 +.. date: 8731 +.. nonce: Cx3O-7 +.. section: Core and Builtins + +ismount now recognises volumes mounted below a drive root on Windows. +Original patch by Atsuo Ishimoto. + +.. + +.. bpo: 18214 +.. date: 8730 +.. nonce: K8wQAM +.. section: Core and Builtins + +Improve finalization of Python modules to avoid setting their globals to +None, in most cases. + +.. + +.. bpo: 18112 +.. date: 8729 +.. nonce: 2Oph_E +.. section: Core and Builtins + +PEP 442 implementation (safe object finalization). + +.. + +.. bpo: 18552 +.. date: 8728 +.. nonce: hbrQHu +.. section: Core and Builtins + +Check return value of PyArena_AddPyObject() in obj2ast_object(). + +.. + +.. bpo: 18560 +.. date: 8727 +.. nonce: 5q_c1C +.. section: Core and Builtins + +Fix potential NULL pointer dereference in sum(). + +.. + +.. bpo: 18520 +.. date: 8726 +.. nonce: JY197j +.. section: Core and Builtins + +Add a new PyStructSequence_InitType2() function, same than +PyStructSequence_InitType() except that it has a return value (0 on success, +-1 on error). + +.. + +.. bpo: 15905 +.. date: 8725 +.. nonce: RG-KXt +.. section: Core and Builtins + +Fix theoretical buffer overflow in handling of sys.argv[0], prefix and +exec_prefix if the operation system does not obey MAXPATHLEN. + +.. + +.. bpo: 18408 +.. date: 8724 +.. nonce: w526wJ +.. section: Core and Builtins + +Fix many various bugs in code handling errors, especially on memory +allocation failure (MemoryError). + +.. + +.. bpo: 18344 +.. date: 8723 +.. nonce: QFOn66 +.. section: Core and Builtins + +Fix potential ref-leaks in _bufferedreader_read_all(). + +.. + +.. bpo: 18342 +.. date: 8722 +.. nonce: PkhUGS +.. section: Core and Builtins + +Use the repr of a module name when an import fails when using ``from ... +import ...``. + +.. + +.. bpo: 17872 +.. date: 8721 +.. nonce: P_Eal- +.. section: Core and Builtins + +Fix a segfault in marshal.load() when input stream returns more bytes than +requested. + +.. + +.. bpo: 18338 +.. date: 8720 +.. nonce: dhKNX2 +.. section: Core and Builtins + +`python --version` now prints version string to stdout, and not to stderr. +Patch by Berker Peksag and Michael Dickens. + +.. + +.. bpo: 18426 +.. date: 8719 +.. nonce: NdnL3v +.. section: Core and Builtins + +Fix NULL pointer dereference in C extension import when PyModule_GetDef() +returns an error. + +.. + +.. bpo: 17206 +.. date: 8718 +.. nonce: eT7Ywa +.. section: Core and Builtins + +On Windows, increase the stack size from 2 MB to 4.2 MB to fix a stack +overflow in the marshal module (fix a crash in test_marshal). Patch written +by Jeremy Kloth. + +.. + +.. bpo: 3329 +.. date: 8717 +.. nonce: 9PzUjS +.. section: Core and Builtins + +Implement the PEP 445: Add new APIs to customize Python memory allocators. + +.. + +.. bpo: 18328 +.. date: 8716 +.. nonce: JHuF3K +.. section: Core and Builtins + +Reorder ops in PyThreadState_Delete*() functions. Now the tstate is first +removed from TLS and then deallocated. + +.. + +.. bpo: 13483 +.. date: 8715 +.. nonce: hc6skP +.. section: Core and Builtins + +Use VirtualAlloc in obmalloc on Windows. + +.. + +.. bpo: 18184 +.. date: 8714 +.. nonce: xLNVG3 +.. section: Core and Builtins + +PyUnicode_FromFormat() and PyUnicode_FromFormatV() now raise OverflowError +when an argument of %c format is out of range. + +.. + +.. bpo: 18111 +.. date: 8713 +.. nonce: 73CZdq +.. section: Core and Builtins + +The min() and max() functions now support a default argument to be returned +instead of raising a ValueError on an empty sequence. (Contributed by Julian +Berman.) + +.. + +.. bpo: 18137 +.. date: 8712 +.. nonce: a_Vsor +.. section: Core and Builtins + +Detect integer overflow on precision in float.__format__() and +complex.__format__(). + +.. + +.. bpo: 18183 +.. date: 8711 +.. nonce: v68GC2 +.. section: Core and Builtins + +Fix various unicode operations on strings with large unicode codepoints. + +.. + +.. bpo: 18180 +.. date: 8710 +.. nonce: GqAflm +.. section: Core and Builtins + +Fix ref leak in _PyImport_GetDynLoadWindows(). + +.. + +.. bpo: 18038 +.. date: 8709 +.. nonce: Q8prhd +.. section: Core and Builtins + +SyntaxError raised during compilation sources with illegal encoding now +always contains an encoding name. + +.. + +.. bpo: 17931 +.. date: 8708 +.. nonce: FCMg_f +.. section: Core and Builtins + +Resolve confusion on Windows between pids and process handles. + +.. + +.. bpo: 0 +.. date: 8707 +.. nonce: Kzwq2I +.. section: Core and Builtins + +Tweak the exception message when the magic number or size value in a +bytecode file is truncated. + +.. + +.. bpo: 17932 +.. date: 8706 +.. nonce: Y5Sfd4 +.. section: Core and Builtins + +Fix an integer overflow issue on Windows 64-bit in iterators: change the C +type of seqiterobject.it_index from long to Py_ssize_t. + +.. + +.. bpo: 18065 +.. date: 8705 +.. nonce: tMRL_r +.. section: Core and Builtins + +Don't set __path__ to the package name for frozen packages. + +.. + +.. bpo: 18088 +.. date: 8704 +.. nonce: 0wObC2 +.. section: Core and Builtins + +When reloading a module, unconditionally reset all relevant attributes on +the module (e.g. __name__, __loader__, __package__, __file__, __cached__). + +.. + +.. bpo: 17937 +.. date: 8703 +.. nonce: xCh9n7 +.. section: Core and Builtins + +Try harder to collect cyclic garbage at shutdown. + +.. + +.. bpo: 12370 +.. date: 8702 +.. nonce: 6tvbpM +.. section: Core and Builtins + +Prevent class bodies from interfering with the __class__ closure. + +.. + +.. bpo: 17644 +.. date: 8701 +.. nonce: OuMIFJ +.. section: Core and Builtins + +Fix a crash in str.format when curly braces are used in square brackets. + +.. + +.. bpo: 17237 +.. date: 8700 +.. nonce: cF-0Zw +.. section: Core and Builtins + +Fix crash in the ASCII decoder on m68k. + +.. + +.. bpo: 17927 +.. date: 8699 +.. nonce: w21Pnm +.. section: Core and Builtins + +Frame objects kept arguments alive if they had been copied into a cell, even +if the cell was cleared. + +.. + +.. bpo: 1545463 +.. date: 8698 +.. nonce: ChdQTJ +.. section: Core and Builtins + +At shutdown, defer finalization of codec modules so that stderr remains +usable. + +.. + +.. bpo: 7330 +.. date: 8697 +.. nonce: _GTI9L +.. section: Core and Builtins + +Implement width and precision (ex: "%5.3s") for the format string of +PyUnicode_FromFormat() function, original patch written by Ysj Ray. + +.. + +.. bpo: 1545463 +.. date: 8696 +.. nonce: 5O00l2 +.. section: Core and Builtins + +Global variables caught in reference cycles are now garbage-collected at +shutdown. + +.. + +.. bpo: 17094 +.. date: 8695 +.. nonce: Uc8zDO +.. section: Core and Builtins + +Clear stale thread states after fork(). Note that this is a potentially +disruptive change since it may release some system resources which would +otherwise remain perpetually alive (e.g. database connections kept in +thread-local storage). + +.. + +.. bpo: 17408 +.. date: 8694 +.. nonce: mfHmrB +.. section: Core and Builtins + +Avoid using an obsolete instance of the copyreg module when the interpreter +is shutdown and then started again. + +.. + +.. bpo: 5845 +.. date: 8693 +.. nonce: Ws1eJX +.. section: Core and Builtins + +Enable tab-completion in the interactive interpreter by default, thanks to a +new sys.__interactivehook__. + +.. + +.. bpo: 17115 +.. date: 8692 +.. nonce: UWAXqy +.. section: Core and Builtins + +Module initialization now includes setting __package__ and __loader__ +attributes to None. (See also: bpo-17116) + +.. + +.. bpo: 17853 +.. date: 8691 +.. nonce: 7_fwd1 +.. section: Core and Builtins + +Ensure locals of a class that shadow free variables always win over the +closures. + +.. + +.. bpo: 17863 +.. date: 8690 +.. nonce: 3PTJAD +.. section: Core and Builtins + +In the interactive console, don't loop forever if the encoding can't be +fetched from stdin. + +.. + +.. bpo: 17867 +.. date: 8689 +.. nonce: DrmXe2 +.. section: Core and Builtins + +Raise an ImportError if __import__ is not found in __builtins__. + +.. + +.. bpo: 18698 +.. date: 8688 +.. nonce: q9QV4u +.. section: Core and Builtins + +Ensure importlib.reload() returns the module out of sys.modules. + +.. + +.. bpo: 17857 +.. date: 8687 +.. nonce: 7cCKDk +.. section: Core and Builtins + +Prevent build failures with pre-3.5.0 versions of sqlite3, such as was +shipped with Centos 5 and Mac OS X 10.4. + +.. + +.. bpo: 17413 +.. date: 8686 +.. nonce: Nt_U0G +.. section: Core and Builtins + +sys.settrace callbacks were being passed a string instead of an exception +instance for the 'value' element of the arg tuple if the exception +originated from C code; now an exception instance is always provided. + +.. + +.. bpo: 17782 +.. date: 8685 +.. nonce: HwEf1N +.. section: Core and Builtins + +Fix undefined behaviour on platforms where ``struct timespec``'s "tv_nsec" +member is not a C long. + +.. + +.. bpo: 17722 +.. date: 8684 +.. nonce: SJ2O7r +.. section: Core and Builtins + +When looking up __round__, resolve descriptors. + +.. + +.. bpo: 16061 +.. date: 8683 +.. nonce: 4LQQlk +.. section: Core and Builtins + +Speed up str.replace() for replacing 1-character strings. + +.. + +.. bpo: 17715 +.. date: 8682 +.. nonce: gZ33Sm +.. section: Core and Builtins + +Fix segmentation fault from raising an exception in a __trunc__ method. + +.. + +.. bpo: 17643 +.. date: 8681 +.. nonce: O1HaFZ +.. section: Core and Builtins + +Add __callback__ attribute to weakref.ref. + +.. + +.. bpo: 16447 +.. date: 8680 +.. nonce: Nqypja +.. section: Core and Builtins + +Fixed potential segmentation fault when setting __name__ on a class. + +.. + +.. bpo: 17669 +.. date: 8679 +.. nonce: TkSpEF +.. section: Core and Builtins + +Fix crash involving finalization of generators using yield from. + +.. + +.. bpo: 14439 +.. date: 8678 +.. nonce: AK0wtz +.. section: Core and Builtins + +Python now prints the traceback on runpy failure at startup. + +.. + +.. bpo: 17469 +.. date: 8677 +.. nonce: Y2sqTK +.. section: Core and Builtins + +Fix _Py_GetAllocatedBlocks() and sys.getallocatedblocks() when running on +valgrind. + +.. + +.. bpo: 17619 +.. date: 8676 +.. nonce: nQqD2x +.. section: Core and Builtins + +Make input() check for Ctrl-C correctly on Windows. + +.. + +.. bpo: 17357 +.. date: 8675 +.. nonce: _xDD4K +.. section: Core and Builtins + +Add missing verbosity messages for -v/-vv that were lost during the +importlib transition. + +.. + +.. bpo: 17610 +.. date: 8674 +.. nonce: QpIzEB +.. section: Core and Builtins + +Don't rely on non-standard behavior of the C qsort() function. + +.. + +.. bpo: 17323 +.. date: 8673 +.. nonce: TozBFg +.. section: Core and Builtins + +The "[X refs, Y blocks]" printed by debug builds has been disabled by +default. It can be re-enabled with the `-X showrefcount` option. + +.. + +.. bpo: 17328 +.. date: 8672 +.. nonce: 5JxFnr +.. section: Core and Builtins + +Fix possible refleak in dict.setdefault. + +.. + +.. bpo: 17275 +.. date: 8671 +.. nonce: Aqerft +.. section: Core and Builtins + +Corrected class name in init error messages of the C version of +BufferedWriter and BufferedRandom. + +.. + +.. bpo: 7963 +.. date: 8670 +.. nonce: FWJtUT +.. section: Core and Builtins + +Fixed misleading error message that issued when object is called without +arguments. + +.. + +.. bpo: 8745 +.. date: 8669 +.. nonce: 7K11Uf +.. section: Core and Builtins + +Small speed up zipimport on Windows. Patch by Catalin Iacob. + +.. + +.. bpo: 5308 +.. date: 8668 +.. nonce: s5uAbP +.. section: Core and Builtins + +Raise ValueError when marshalling too large object (a sequence with size >= +2**31), instead of producing illegal marshal data. + +.. + +.. bpo: 12983 +.. date: 8667 +.. nonce: 9igtJf +.. section: Core and Builtins + +Bytes literals with invalid ``\x`` escape now raise a SyntaxError and a full +traceback including line number. + +.. + +.. bpo: 16967 +.. date: 8666 +.. nonce: UYSqkX +.. section: Core and Builtins + +In function definition, evaluate positional defaults before keyword-only +defaults. + +.. + +.. bpo: 17173 +.. date: 8665 +.. nonce: -KwwJ2 +.. section: Core and Builtins + +Remove uses of locale-dependent C functions (isalpha() etc.) in the +interpreter. + +.. + +.. bpo: 17137 +.. date: 8664 +.. nonce: NI_n7A +.. section: Core and Builtins + +When an Unicode string is resized, the internal wide character string (wstr) +format is now cleared. + +.. + +.. bpo: 17043 +.. date: 8663 +.. nonce: 4OVhGk +.. section: Core and Builtins + +The unicode-internal decoder no longer read past the end of input buffer. + +.. + +.. bpo: 17098 +.. date: 8662 +.. nonce: hppfYX +.. section: Core and Builtins + +All modules now have __loader__ set even if they pre-exist the bootstrapping +of importlib. + +.. + +.. bpo: 16979 +.. date: 8661 +.. nonce: jTR3Oe +.. section: Core and Builtins + +Fix error handling bugs in the unicode-escape-decode decoder. + +.. + +.. bpo: 16772 +.. date: 8660 +.. nonce: 8qUxMn +.. section: Core and Builtins + +The base argument to the int constructor no longer accepts floats, or other +non-integer objects with an __int__ method. Objects with an __index__ +method are now accepted. + +.. + +.. bpo: 10156 +.. date: 8659 +.. nonce: iEZGhY +.. section: Core and Builtins + +In the interpreter's initialization phase, unicode globals are now +initialized dynamically as needed. + +.. + +.. bpo: 16980 +.. date: 8658 +.. nonce: e2jDb2 +.. section: Core and Builtins + +Fix processing of escaped non-ascii bytes in the unicode-escape-decode +decoder. + +.. + +.. bpo: 16975 +.. date: 8657 +.. nonce: MfvORJ +.. section: Core and Builtins + +Fix error handling bug in the escape-decode bytes decoder. + +.. + +.. bpo: 14850 +.. date: 8656 +.. nonce: yScInY +.. section: Core and Builtins + +Now a charmap decoder treats U+FFFE as "undefined mapping" in any mapping, +not only in a string. + +.. + +.. bpo: 16613 +.. date: 8655 +.. nonce: 8V5m-H +.. section: Core and Builtins + +Add *m* argument to ``collections.Chainmap.new_child`` to allow the new +child map to be specified explicitly. + +.. + +.. bpo: 16730 +.. date: 8654 +.. nonce: X_pIAe +.. section: Core and Builtins + +importlib.machinery.FileFinder now no longers raises an exception when +trying to populate its cache and it finds out the directory is unreadable or +has turned into a file. Reported and diagnosed by David Pritchard. + +.. + +.. bpo: 16906 +.. date: 8653 +.. nonce: 3kn92w +.. section: Core and Builtins + +Fix a logic error that prevented most static strings from being cleared. + +.. + +.. bpo: 11461 +.. date: 8652 +.. nonce: xwn_Zw +.. section: Core and Builtins + +Fix the incremental UTF-16 decoder. Original patch by Amaury Forgeot d'Arc. + +.. + +.. bpo: 16856 +.. date: 8651 +.. nonce: _alafL +.. section: Core and Builtins + +Fix a segmentation fault from calling repr() on a dict with a key whose repr +raise an exception. + +.. + +.. bpo: 16367 +.. date: 8650 +.. nonce: lewlCg +.. section: Core and Builtins + +Fix FileIO.readall() on Windows for files larger than 2 GB. + +.. + +.. bpo: 16761 +.. date: 8649 +.. nonce: bZqaqq +.. section: Core and Builtins + +Calling int() with base argument only now raises TypeError. + +.. + +.. bpo: 16759 +.. date: 8648 +.. nonce: U0-CFS +.. section: Core and Builtins + +Support the full DWORD (unsigned long) range in Reg2Py when retrieving a +REG_DWORD value. This corrects functions like winreg.QueryValueEx that may +have been returning truncated values. + +.. + +.. bpo: 14420 +.. date: 8647 +.. nonce: P8fmk8 +.. section: Core and Builtins + +Support the full DWORD (unsigned long) range in Py2Reg when passed a +REG_DWORD value. Fixes OverflowError in winreg.SetValueEx. + +.. + +.. bpo: 11939 +.. date: 8646 +.. nonce: rjfRMW +.. section: Core and Builtins + +Set the st_dev attribute of stat_result to allow Windows to take advantage +of the os.path.samefile/sameopenfile/samestat implementations used by other +platforms. + +.. + +.. bpo: 16772 +.. date: 8645 +.. nonce: XI5NvS +.. section: Core and Builtins + +The int() constructor's second argument (base) no longer accepts non integer +values. Consistent with the behavior in Python 2. + +.. + +.. bpo: 14470 +.. date: 8644 +.. nonce: Qn1nFM +.. section: Core and Builtins + +Remove w9xpopen support per PEP 11. + +.. + +.. bpo: 9856 +.. date: 8643 +.. nonce: 5huiiZ +.. section: Core and Builtins + +Replace deprecation warning with raising TypeError in object.__format__. +Patch by Florent Xicluna. + +.. + +.. bpo: 16597 +.. date: 8642 +.. nonce: z8uMEN +.. section: Core and Builtins + +In buffered and text IO, call close() on the underlying stream if invoking +flush() fails. + +.. + +.. bpo: 16722 +.. date: 8641 +.. nonce: HXliz2 +.. section: Core and Builtins + +In the bytes() constructor, try to call __bytes__ on the argument before +__index__. + +.. + +.. bpo: 16421 +.. date: 8640 +.. nonce: Y9A84i +.. section: Core and Builtins + +loading multiple modules from one shared object is now handled correctly +(previously, the first module loaded from that file was silently returned). +Patch by Václav Šmilauer. + +.. + +.. bpo: 16602 +.. date: 8639 +.. nonce: FjnLTD +.. section: Core and Builtins + +When a weakref's target was part of a long deallocation chain, the object +could remain reachable through its weakref even though its refcount had +dropped to zero. + +.. + +.. bpo: 16495 +.. date: 8638 +.. nonce: HCGy9Q +.. section: Core and Builtins + +Remove extraneous NULL encoding check from bytes_decode(). + +.. + +.. bpo: 16619 +.. date: 8637 +.. nonce: STDaB4 +.. section: Core and Builtins + +Create NameConstant AST class to represent None, True, and False literals. +As a result, these constants are never loaded at runtime from builtins. + +.. + +.. bpo: 16455 +.. date: 8636 +.. nonce: chBHs2 +.. section: Core and Builtins + +On FreeBSD and Solaris, if the locale is C, the ASCII/surrogateescape codec +is now used (instead of the locale encoding) to decode the command line +arguments. This change fixes inconsistencies with os.fsencode() and +os.fsdecode(), because these operating systems announce an ASCII locale +encoding, but actually use the ISO-8859-1 encoding in practice. + +.. + +.. bpo: 16562 +.. date: 8635 +.. nonce: IR_Kj7 +.. section: Core and Builtins + +Optimize dict equality testing. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16588 +.. date: 8634 +.. nonce: YKgxOa +.. section: Core and Builtins + +Silence unused-but-set warnings in Python/thread_pthread + +.. + +.. bpo: 16592 +.. date: 8633 +.. nonce: QVZPAM +.. section: Core and Builtins + +stringlib_bytes_join doesn't raise MemoryError on allocation failure. + +.. + +.. bpo: 16546 +.. date: 8632 +.. nonce: LXZuCC +.. section: Core and Builtins + +Fix: ast.YieldFrom argument is now mandatory. + +.. + +.. bpo: 16514 +.. date: 8631 +.. nonce: NoxJ7R +.. section: Core and Builtins + +Fix regression causing a traceback when sys.path[0] is None (actually, any +non-string or non-bytes type). + +.. + +.. bpo: 16306 +.. date: 8630 +.. nonce: H29SXn +.. section: Core and Builtins + +Fix multiple error messages when unknown command line parameters where +passed to the interpreter. Patch by Hieu Nguyen. + +.. + +.. bpo: 16215 +.. date: 8629 +.. nonce: hoWMgb +.. section: Core and Builtins + +Fix potential double memory free in str.replace(). Patch by Serhiy +Storchaka. + +.. + +.. bpo: 16290 +.. date: 8628 +.. nonce: aCFQF9 +.. section: Core and Builtins + +A float return value from the __complex__ special method is no longer +accepted in the complex() constructor. + +.. + +.. bpo: 16416 +.. date: 8627 +.. nonce: v9EtVT +.. section: Core and Builtins + +On Mac OS X, operating system data are now always encoded/decoded to/from +UTF-8/surrogateescape, instead of the locale encoding (which may be ASCII if +no locale environment variable is set), to avoid inconsistencies with +os.fsencode() and os.fsdecode() functions which are already using +UTF-8/surrogateescape. + +.. + +.. bpo: 16453 +.. date: 8626 +.. nonce: 0Zm9en +.. section: Core and Builtins + +Fix equality testing of dead weakref objects. + +.. + +.. bpo: 9535 +.. date: 8625 +.. nonce: hkixPD +.. section: Core and Builtins + +Fix pending signals that have been received but not yet handled by Python to +not persist after os.fork() in the child process. + +.. + +.. bpo: 14794 +.. date: 8624 +.. nonce: lc6bpg +.. section: Core and Builtins + +Fix slice.indices to return correct results for huge values, rather than +raising OverflowError. + +.. + +.. bpo: 15001 +.. date: 8623 +.. nonce: oD3gtX +.. section: Core and Builtins + +fix segfault on "del sys.modules['__main__']". Patch by Victor Stinner. + +.. + +.. bpo: 8271 +.. date: 8622 +.. nonce: 1qiQia +.. section: Core and Builtins + +the utf-8 decoder now outputs the correct number of U+FFFD characters when +used with the 'replace' error handler on invalid utf-8 sequences. Patch by +Serhiy Storchaka, tests by Ezio Melotti. + +.. + +.. bpo: 5765 +.. date: 8621 +.. nonce: YFFijP +.. section: Core and Builtins + +Apply a hard recursion limit in the compiler instead of blowing the stack +and segfaulting. Initial patch by Andrea Griffini. + +.. + +.. bpo: 16402 +.. date: 8620 +.. nonce: j73Ooz +.. section: Core and Builtins + +When slicing a range, fix shadowing of exceptions from __index__. + +.. + +.. bpo: 16336 +.. date: 8619 +.. nonce: JaupVb +.. section: Core and Builtins + +fix input checking in the surrogatepass error handler. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 8401 +.. date: 8618 +.. nonce: TslRZr +.. section: Core and Builtins + +assigning an int to a bytearray slice (e.g. b[3:4] = 5) now raises an error. + +.. + +.. bpo: 7317 +.. date: 8617 +.. nonce: 0ogGME +.. section: Core and Builtins + +Display full tracebacks when an error occurs asynchronously. Patch by Alon +Horev with update by Alexey Kachayev. + +.. + +.. bpo: 16309 +.. date: 8616 +.. nonce: i2KrDU +.. section: Core and Builtins + +Make PYTHONPATH="" behavior the same as if PYTHONPATH not set at all. + +.. + +.. bpo: 10189 +.. date: 8615 +.. nonce: 3tsml3 +.. section: Core and Builtins + +Improve the error reporting of SyntaxErrors related to global and nonlocal +statements. + +.. + +.. bpo: 0 +.. date: 8614 +.. nonce: iqyUxO +.. section: Core and Builtins + +Fix segfaults on setting __qualname__ on builtin types and attempting to +delete it on any type. + +.. + +.. bpo: 14625 +.. date: 8613 +.. nonce: FHSRMM +.. section: Core and Builtins + +Rewrite the UTF-32 decoder. It is now 3x to 4x faster. Patch written by +Serhiy Storchaka. + +.. + +.. bpo: 16345 +.. date: 8612 +.. nonce: azvPpP +.. section: Core and Builtins + +Fix an infinite loop when ``fromkeys`` on a dict subclass received a +nonempty dict from the constructor. + +.. + +.. bpo: 16271 +.. date: 8611 +.. nonce: ALsJdN +.. section: Core and Builtins + +Fix strange bugs that resulted from __qualname__ appearing in a class's +__dict__ and on type. + +.. + +.. bpo: 12805 +.. date: 8610 +.. nonce: 0u9UGE +.. section: Core and Builtins + +Make bytes.join and bytearray.join faster when the separator is empty. +Patch by Serhiy Storchaka. + +.. + +.. bpo: 6074 +.. date: 8609 +.. nonce: CXlveH +.. section: Core and Builtins + +Ensure cached bytecode files can always be updated by the user that created +them, even when the source file is read-only. + +.. + +.. bpo: 15958 +.. date: 8608 +.. nonce: 0MDv_n +.. section: Core and Builtins + +bytes.join and bytearray.join now accept arbitrary buffer objects. + +.. + +.. bpo: 14783 +.. date: 8607 +.. nonce: bv7z1_ +.. section: Core and Builtins + +Improve int() docstring and switch docstrings for str(), range(), and +slice() to use multi-line signatures. + +.. + +.. bpo: 16160 +.. date: 8606 +.. nonce: NKBYGr +.. section: Core and Builtins + +Subclass support now works for types.SimpleNamespace. + +.. + +.. bpo: 16148 +.. date: 8605 +.. nonce: tRekKP +.. section: Core and Builtins + +Implement PEP 424, adding operator.length_hint and PyObject_LengthHint. + +.. + +.. bpo: 0 +.. date: 8604 +.. nonce: J74Dx4 +.. section: Core and Builtins + +Upgrade Unicode data (UCD) to version 6.2. + +.. + +.. bpo: 15379 +.. date: 8603 +.. nonce: Ix2NTb +.. section: Core and Builtins + +Fix passing of non-BMP characters as integers for the charmap decoder +(already working as unicode strings). Patch by Serhiy Storchaka. + +.. + +.. bpo: 15144 +.. date: 8602 +.. nonce: ENBWTp +.. section: Core and Builtins + +Fix possible integer overflow when handling pointers as integer values, by +using `Py_uintptr_t` instead of `size_t`. Patch by Serhiy Storchaka. + +.. + +.. bpo: 15965 +.. date: 8601 +.. nonce: kbbwZh +.. section: Core and Builtins + +Explicitly cast `AT_FDCWD` as (int). Required on Solaris 10 (which defines +`AT_FDCWD` as ``0xffd19553``), harmless on other platforms. + +.. + +.. bpo: 15839 +.. date: 8600 +.. nonce: upi9Zr +.. section: Core and Builtins + +Convert SystemErrors in `super()` to RuntimeErrors. + +.. + +.. bpo: 15448 +.. date: 8599 +.. nonce: dj1nDm +.. section: Core and Builtins + +Buffered IO now frees the buffer when closed, instead of when deallocating. + +.. + +.. bpo: 15846 +.. date: 8598 +.. nonce: fkKoxl +.. section: Core and Builtins + +Fix SystemError which happened when using `ast.parse()` in an exception +handler on code with syntax errors. + +.. + +.. bpo: 15897 +.. date: 8597 +.. nonce: GQpoBE +.. section: Core and Builtins + +zipimport.c doesn't check return value of fseek(). Patch by Felipe Cruz. + +.. + +.. bpo: 15801 +.. date: 8596 +.. nonce: gpcQV3 +.. section: Core and Builtins + +Make sure mappings passed to '%' formatting are actually subscriptable. + +.. + +.. bpo: 15111 +.. date: 8595 +.. nonce: hM48LB +.. section: Core and Builtins + +__import__ should propagate ImportError when raised as a side-effect of a +module triggered from using fromlist. + +.. + +.. bpo: 15022 +.. date: 8594 +.. nonce: VevUbS +.. section: Core and Builtins + +Add pickle and comparison support to types.SimpleNamespace. + +.. + +.. bpo: 4331 +.. date: 8593 +.. nonce: Ua1fF0 +.. section: Library + +Added functools.partialmethod (Initial patch by Alon Horev) + +.. + +.. bpo: 13461 +.. date: 8592 +.. nonce: nLeS2R +.. section: Library + +Fix a crash in the TextIOWrapper.tell method on 64-bit platforms. Patch by +Yogesh Chaudhari. + +.. + +.. bpo: 18681 +.. date: 8591 +.. nonce: 8Oug5y +.. section: Library + +Fix a NameError in importlib.reload() (noticed by Weizhao Li). + +.. + +.. bpo: 14323 +.. date: 8590 +.. nonce: Sp7tzh +.. section: Library + +Expanded the number of digits in the coefficients for the RGB -- YIQ +conversions so that they match the FCC NTSC versions. + +.. + +.. bpo: 17998 +.. date: 8589 +.. nonce: hIbru5 +.. section: Library + +Fix an internal error in regular expression engine. + +.. + +.. bpo: 17557 +.. date: 8588 +.. nonce: s6BEMI +.. section: Library + +Fix os.getgroups() to work with the modified behavior of getgroups(2) on OS +X 10.8. Original patch by Mateusz Lenik. + +.. + +.. bpo: 18608 +.. date: 8587 +.. nonce: iLz2V4 +.. section: Library + +Avoid keeping a strong reference to the locale module inside the _io module. + +.. + +.. bpo: 18619 +.. date: 8586 +.. nonce: sj_OcY +.. section: Library + +Fix atexit leaking callbacks registered from sub-interpreters, and make it +GC-aware. + +.. + +.. bpo: 15699 +.. date: 8585 +.. nonce: tRg3Ny +.. section: Library + +The readline module now uses PEP 3121-style module initialization, so as to +reclaim allocated resources (Python callbacks) at shutdown. Original patch +by Robin Schreiber. + +.. + +.. bpo: 17616 +.. date: 8584 +.. nonce: BZCSg_ +.. section: Library + +wave.open now supports the context management protocol. + +.. + +.. bpo: 18599 +.. date: 8583 +.. nonce: OLGDK_ +.. section: Library + +Fix name attribute of _sha1.sha1() object. It now returns 'SHA1' instead of +'SHA'. + +.. + +.. bpo: 13266 +.. date: 8582 +.. nonce: vWxl34 +.. section: Library + +Added inspect.unwrap to easily unravel __wrapped__ chains (initial patch by +Daniel Urban and Aaron Iles) + +.. + +.. bpo: 18561 +.. date: 8581 +.. nonce: vgaf-k +.. section: Library + +Skip name in ctypes' _build_callargs() if name is NULL. + +.. + +.. bpo: 18559 +.. date: 8580 +.. nonce: svR01x +.. section: Library + +Fix NULL pointer dereference error in _pickle module + +.. + +.. bpo: 18556 +.. date: 8579 +.. nonce: -3Wtbg +.. section: Library + +Check the return type of PyUnicode_AsWideChar() in ctype's U_set(). + +.. + +.. bpo: 17818 +.. date: 8578 +.. nonce: zyqY5Z +.. section: Library + +aifc.getparams now returns a namedtuple. + +.. + +.. bpo: 18549 +.. date: 8577 +.. nonce: DfZaOD +.. section: Library + +Eliminate dead code in socket_ntohl() + +.. + +.. bpo: 18530 +.. date: 8576 +.. nonce: roUGYs +.. section: Library + +Remove additional stat call from posixpath.ismount. Patch by Alex Gaynor. + +.. + +.. bpo: 18514 +.. date: 8575 +.. nonce: byuxVK +.. section: Library + +Fix unreachable Py_DECREF() call in PyCData_FromBaseObj() + +.. + +.. bpo: 9177 +.. date: 8574 +.. nonce: 0NCpHI +.. section: Library + +Calling read() or write() now raises ValueError, not AttributeError, on a +closed SSL socket. Patch by Senko Rasic. + +.. + +.. bpo: 18513 +.. date: 8573 +.. nonce: 12JUZi +.. section: Library + +Fix behaviour of cmath.rect w.r.t. signed zeros on OS X 10.8 + gcc. + +.. + +.. bpo: 18479 +.. date: 8572 +.. nonce: CLFAeo +.. section: Library + +Changed venv Activate.ps1 to make deactivate a function, and removed +Deactivate.ps1. + +.. + +.. bpo: 18480 +.. date: 8571 +.. nonce: JoDjBC +.. section: Library + +Add missing call to PyType_Ready to the _elementtree extension. + +.. + +.. bpo: 17778 +.. date: 8570 +.. nonce: odXAnT +.. section: Library + +Fix test discovery for test_multiprocessing. (Patch by Zachary Ware.) + +.. + +.. bpo: 18393 +.. date: 8569 +.. nonce: J5Ss7D +.. section: Library + +The private module _gestalt and private functions platform._mac_ver_gestalt, +platform._mac_ver_lookup and platform._bcd2str have been removed. This does +not affect the public interface of the platform module. + +.. + +.. bpo: 17482 +.. date: 8568 +.. nonce: HSxNCy +.. section: Library + +functools.update_wrapper (and functools.wraps) now set the __wrapped__ +attribute correctly even if the underlying function has a __wrapped__ +attribute set. + +.. + +.. bpo: 18431 +.. date: 8567 +.. nonce: 4TWlLe +.. section: Library + +The new email header parser now decodes RFC2047 encoded words in structured +headers. + +.. + +.. bpo: 18432 +.. date: 8566 +.. nonce: 3KWObr +.. section: Library + +The sched module's queue method was incorrectly returning an iterator +instead of a list. + +.. + +.. bpo: 18044 +.. date: 8565 +.. nonce: -TYxNg +.. section: Library + +The new email header parser was mis-parsing encoded words where an encoded +character immediately followed the '?' that follows the CTE character, +resulting in a decoding failure. They are now decoded correctly. + +.. + +.. bpo: 18101 +.. date: 8564 +.. nonce: Y9oAK1 +.. section: Library + +Tcl.split() now process strings nested in a tuple as it do with byte +strings. + +.. + +.. bpo: 18116 +.. date: 8563 +.. nonce: ZOamPj +.. section: Library + +getpass was always getting an error when testing /dev/tty, and thus was +always falling back to stdin, and would then raise an exception if stdin +could not be used (such as /dev/null). It also leaked an open file. All of +these issues are now fixed. + +.. + +.. bpo: 17198 +.. date: 8562 +.. nonce: MZjVaU +.. section: Library + +Fix a NameError in the dbm module. Patch by Valentina Mukhamedzhanova. + +.. + +.. bpo: 18013 +.. date: 8561 +.. nonce: wzBMJh +.. section: Library + +Fix cgi.FieldStorage to parse the W3C sample form. + +.. + +.. bpo: 18020 +.. date: 8560 +.. nonce: eN5fLA +.. section: Library + +improve html.escape speed by an order of magnitude. Patch by Matt Bryant. + +.. + +.. bpo: 18347 +.. date: 8559 +.. nonce: r98Yh- +.. section: Library + +ElementTree's html serializer now preserves the case of closing tags. + +.. + +.. bpo: 17261 +.. date: 8558 +.. nonce: FBzLVh +.. section: Library + +Ensure multiprocessing's proxies use proper address. + +.. + +.. bpo: 18343 +.. date: 8557 +.. nonce: hHmlM5 +.. section: Library + +faulthandler.register() now keeps the previous signal handler when the +function is called twice, so faulthandler.unregister() restores correctly +the original signal handler. + +.. + +.. bpo: 17097 +.. date: 8556 +.. nonce: npje1S +.. section: Library + +Make multiprocessing ignore EINTR. + +.. + +.. bpo: 18339 +.. date: 8555 +.. nonce: tawrrh +.. section: Library + +Negative ints keys in unpickler.memo dict no longer cause a segfault inside +the _pickle C extension. + +.. + +.. bpo: 18240 +.. date: 8554 +.. nonce: Um--C2 +.. section: Library + +The HMAC module is no longer restricted to bytes and accepts any bytes-like +object, e.g. memoryview. Original patch by Jonas Borgström. + +.. + +.. bpo: 18224 +.. date: 8553 +.. nonce: QcraR9 +.. section: Library + +Removed pydoc script from created venv, as it causes problems on Windows and +adds no value over and above python -m pydoc ... + +.. + +.. bpo: 18155 +.. date: 8552 +.. nonce: RNn8WU +.. section: Library + +The csv module now correctly handles csv files that use a delimter character +that has a special meaning in regexes, instead of throwing an exception. + +.. + +.. bpo: 14360 +.. date: 8551 +.. nonce: bn3mJY +.. section: Library + +encode_quopri can now be successfully used as an encoder when constructing a +MIMEApplication object. + +.. + +.. bpo: 11390 +.. date: 8550 +.. nonce: KD6eql +.. section: Library + +Add -o and -f command line options to the doctest CLI to specify doctest +options (and convert it to using argparse). + +.. + +.. bpo: 18135 +.. date: 8549 +.. nonce: NUPrSU +.. section: Library + +ssl.SSLSocket.write() now raises an OverflowError if the input string in +longer than 2 gigabytes, and ssl.SSLContext.load_cert_chain() raises a +ValueError if the password is longer than 2 gigabytes. The ssl module does +not support partial write. + +.. + +.. bpo: 11016 +.. date: 8548 +.. nonce: w7C0Pf +.. section: Library + +Add C implementation of the stat module as _stat. + +.. + +.. bpo: 18248 +.. date: 8547 +.. nonce: SFH5BJ +.. section: Library + +Fix libffi build on AIX. + +.. + +.. bpo: 18259 +.. date: 8546 +.. nonce: _GlBhr +.. section: Library + +Declare sethostname in socketmodule.c for AIX + +.. + +.. bpo: 18147 +.. date: 8545 +.. nonce: SwrMZ0 +.. section: Library + +Add diagnostic functions to ssl.SSLContext(). get_ca_list() lists all loaded +CA certificates and cert_store_stats() returns amount of loaded X.509 certs, +X.509 CA certs and CRLs. + +.. + +.. bpo: 18167 +.. date: 8544 +.. nonce: ZeSV0k +.. section: Library + +cgi.FieldStorage no longer fails to handle multipart/form-data when ``\r\n`` +appears at end of 65535 bytes without other newlines. + +.. + +.. bpo: 18076 +.. date: 8543 +.. nonce: 4lL63W +.. section: Library + +Introduce importlib.util.decode_source(). + +.. + +.. bpo: 18357 +.. date: 8542 +.. nonce: jRiyQA +.. section: Library + +add tests for dictview set difference. Patch by Fraser Tweedale. + +.. + +.. bpo: 0 +.. date: 8541 +.. nonce: 8RBFdG +.. section: Library + +importlib.abc.SourceLoader.get_source() no longer changes SyntaxError or +UnicodeDecodeError into ImportError. + +.. + +.. bpo: 18058 +.. date: 8540 +.. nonce: rfXwQL +.. section: Library + +Make the namespace package loader meet the importlib.abc.InspectLoader ABC, +allowing for namespace packages to work with runpy. (See also: bpo-18057) + +.. + +.. bpo: 17177 +.. date: 8539 +.. nonce: S7sdI_ +.. section: Library + +The imp module is pending deprecation. + +.. + +.. bpo: 0 +.. date: 8538 +.. nonce: Y71ClT +.. section: Library + +subprocess: Prevent a possible double close of parent pipe fds when the +subprocess exec runs into an error. Prevent a regular multi-close of the +/dev/null fd when any of stdin, stdout and stderr was set to DEVNULL. + +.. + +.. bpo: 18194 +.. date: 8537 +.. nonce: -jAlVj +.. section: Library + +Introduce importlib.util.cache_from_source() and source_from_cache() while +documenting the equivalent functions in imp as deprecated. + +.. + +.. bpo: 17907 +.. date: 8536 +.. nonce: yz9wrd +.. section: Library + +Document imp.new_module() as deprecated in favour of types.ModuleType. + +.. + +.. bpo: 18192 +.. date: 8535 +.. nonce: R4NYan +.. section: Library + +Introduce importlib.util.MAGIC_NUMBER and document as deprecated +imp.get_magic(). + +.. + +.. bpo: 18149 +.. date: 8534 +.. nonce: pYRXFc +.. section: Library + +Add filecmp.clear_cache() to manually clear the filecmp cache. Patch by Mark +Levitt + +.. + +.. bpo: 18193 +.. date: 8533 +.. nonce: Hi1c_l +.. section: Library + +Add importlib.reload(). + +.. + +.. bpo: 18157 +.. date: 8532 +.. nonce: 3qhsTW +.. section: Library + +Stop using imp.load_module() in pydoc. + +.. + +.. bpo: 16102 +.. date: 8531 +.. nonce: Ue82lF +.. section: Library + +Make uuid._netbios_getnode() work again on Python 3. + +.. + +.. bpo: 17134 +.. date: 8530 +.. nonce: 2FXUYZ +.. section: Library + +Add ssl.enum_cert_store() as interface to Windows' cert store. + +.. + +.. bpo: 18143 +.. date: 8529 +.. nonce: qot9pC +.. section: Library + +Implement ssl.get_default_verify_paths() in order to debug the default +locations for cafile and capath. + +.. + +.. bpo: 17314 +.. date: 8528 +.. nonce: EgLvA7 +.. section: Library + +Move multiprocessing.forking over to importlib. + +.. + +.. bpo: 11959 +.. date: 8527 +.. nonce: KvHon- +.. section: Library + +SMTPServer and SMTPChannel now take an optional map, use of which avoids +affecting global state. + +.. + +.. bpo: 18109 +.. date: 8526 +.. nonce: ix7u1y +.. section: Library + +os.uname() now decodes fields from the locale encoding, and +socket.gethostname() now decodes the hostname from the locale encoding, +instead of using the UTF-8 encoding in strict mode. + +.. + +.. bpo: 18089 +.. date: 8525 +.. nonce: f8TdL7 +.. section: Library + +Implement importlib.abc.InspectLoader.load_module. + +.. + +.. bpo: 18088 +.. date: 8524 +.. nonce: G6H6Z2 +.. section: Library + +Introduce importlib.abc.Loader.init_module_attrs for setting module +attributes. Leads to the pending deprecation of +importlib.util.module_for_loader. + +.. + +.. bpo: 17403 +.. date: 8523 +.. nonce: gtIhUd +.. section: Library + +urllib.parse.robotparser normalizes the urls before adding to ruleline. This +helps in handling certain types invalid urls in a conservative manner. Patch +contributed by Mher Movsisyan. + +.. + +.. bpo: 18070 +.. date: 8522 +.. nonce: ocj8nr +.. section: Library + +Have importlib.util.module_for_loader() set attributes unconditionally in +order to properly support reloading. + +.. + +.. bpo: 0 +.. date: 8521 +.. nonce: J5E4J_ +.. section: Library + +Added importlib.util.module_to_load to return a context manager to provide +the proper module object to load. + +.. + +.. bpo: 18025 +.. date: 8520 +.. nonce: i8mW0x +.. section: Library + +Fixed a segfault in io.BufferedIOBase.readinto() when raw stream's read() +returns more bytes than requested. + +.. + +.. bpo: 18011 +.. date: 8519 +.. nonce: lvv4RQ +.. section: Library + +As was originally intended, base64.b32decode() now raises a binascii.Error +if there are non-b32-alphabet characters present in the input string, +instead of a TypeError. + +.. + +.. bpo: 18072 +.. date: 8518 +.. nonce: id8KzR +.. section: Library + +Implement importlib.abc.InspectLoader.get_code() and +importlib.abc.ExecutionLoader.get_code(). + +.. + +.. bpo: 8240 +.. date: 8517 +.. nonce: XMOgJe +.. section: Library + +Set the SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER flag on SSL sockets. + +.. + +.. bpo: 17269 +.. date: 8516 +.. nonce: 7LxyKz +.. section: Library + +Workaround for socket.getaddrinfo crash on MacOS X with port None or "0" and +flags AI_NUMERICSERV. + +.. + +.. bpo: 16986 +.. date: 8515 +.. nonce: htN8mZ +.. section: Library + +ElementTree now correctly works with string input when the internal XML +encoding is not UTF-8 or US-ASCII. + +.. + +.. bpo: 17996 +.. date: 8514 +.. nonce: JRofiI +.. section: Library + +socket module now exposes AF_LINK constant on BSD and OSX. + +.. + +.. bpo: 17900 +.. date: 8513 +.. nonce: KONBQp +.. section: Library + +Allowed pickling of recursive OrderedDicts. Decreased pickled size and +pickling time. + +.. + +.. bpo: 17914 +.. date: 8512 +.. nonce: a7CBRm +.. section: Library + +Add os.cpu_count(). Patch by Yogesh Chaudhari, based on an initial patch by +Trent Nelson. + +.. + +.. bpo: 17812 +.. date: 8511 +.. nonce: WW32FE +.. section: Library + +Fixed quadratic complexity of base64.b32encode(). Optimize +base64.b32encode() and base64.b32decode() (speed up to 3x). + +.. + +.. bpo: 17980 +.. date: 8510 +.. nonce: oLLRCS +.. section: Library + +Fix possible abuse of ssl.match_hostname() for denial of service using +certificates with many wildcards (CVE-2013-2099). + +.. + +.. bpo: 15758 +.. date: 8509 +.. nonce: jcf1UW +.. section: Library + +Fix FileIO.readall() so it no longer has O(n**2) complexity. + +.. + +.. bpo: 14596 +.. date: 8508 +.. nonce: _L9ARc +.. section: Library + +The struct.Struct() objects now use a more compact implementation. + +.. + +.. bpo: 17981 +.. date: 8507 +.. nonce: 6UZcQZ +.. section: Library + +logging's SysLogHandler now closes the socket when it catches socket +OSErrors. + +.. + +.. bpo: 17964 +.. date: 8506 +.. nonce: fypN2L +.. section: Library + +Fix os.sysconf(): the return type of the C sysconf() function is long, not +int. + +.. + +.. bpo: 0 +.. date: 8505 +.. nonce: 9OGCJH +.. section: Library + +Fix typos in the multiprocessing module. + +.. + +.. bpo: 17754 +.. date: 8504 +.. nonce: xa6Bc3 +.. section: Library + +Make ctypes.util.find_library() independent of the locale. + +.. + +.. bpo: 17968 +.. date: 8503 +.. nonce: nY_hjb +.. section: Library + +Fix memory leak in os.listxattr(). + +.. + +.. bpo: 17606 +.. date: 8502 +.. nonce: KiLlUm +.. section: Library + +Fixed support of encoded byte strings in the XMLGenerator characters() and +ignorableWhitespace() methods. Original patch by Sebastian Ortiz Vasquez. + +.. + +.. bpo: 17732 +.. date: 8501 +.. nonce: nVRMov +.. section: Library + +Ignore distutils.cfg options pertaining to install paths if a virtual +environment is active. + +.. + +.. bpo: 17915 +.. date: 8500 +.. nonce: ugMGeG +.. section: Library + +Fix interoperability of xml.sax with file objects returned by codecs.open(). + +.. + +.. bpo: 16601 +.. date: 8499 +.. nonce: nolAu_ +.. section: Library + +Restarting iteration over tarfile really restarts rather than continuing +from where it left off. Patch by Michael Birtwell. + +.. + +.. bpo: 17289 +.. date: 8498 +.. nonce: NPHOks +.. section: Library + +The readline module now plays nicer with external modules or applications +changing the rl_completer_word_break_characters global variable. Initial +patch by Bradley Froehle. + +.. + +.. bpo: 12181 +.. date: 8497 +.. nonce: Dq2moC +.. section: Library + +select module: Fix struct kevent definition on OpenBSD 64-bit platforms. +Patch by Federico Schwindt. + +.. + +.. bpo: 11816 +.. date: 8496 +.. nonce: sv6zV1 +.. section: Library + +multiple improvements to the dis module: get_instructions generator, ability +to redirect output to a file, Bytecode and Instruction abstractions. Patch +by Nick Coghlan, Ryan Kelly and Thomas Kluyver. + +.. + +.. bpo: 13831 +.. date: 8495 +.. nonce: 2ERopR +.. section: Library + +Embed stringification of remote traceback in local traceback raised when +pool task raises an exception. + +.. + +.. bpo: 15528 +.. date: 8494 +.. nonce: EwXcQD +.. section: Library + +Add weakref.finalize to support finalization using weakref callbacks. + +.. + +.. bpo: 14173 +.. date: 8493 +.. nonce: mZM9Pr +.. section: Library + +Avoid crashing when reading a signal handler during interpreter shutdown. + +.. + +.. bpo: 15902 +.. date: 8492 +.. nonce: 3XIl24 +.. section: Library + +Fix imp.load_module() accepting None as a file when loading an extension +module. + +.. + +.. bpo: 13721 +.. date: 8491 +.. nonce: _1u_jf +.. section: Library + +SSLSocket.getpeercert() and SSLSocket.do_handshake() now raise an OSError +with ENOTCONN, instead of an AttributeError, when the SSLSocket is not +connected. + +.. + +.. bpo: 14679 +.. date: 8490 +.. nonce: XSBn-L +.. section: Library + +add an __all__ (that contains only HTMLParser) to html.parser. + +.. + +.. bpo: 17802 +.. date: 8489 +.. nonce: ztoqWb +.. section: Library + +Fix an UnboundLocalError in html.parser. Initial tests by Thomas Barlow. + +.. + +.. bpo: 17358 +.. date: 8488 +.. nonce: kyf-Ix +.. section: Library + +Modules loaded by imp.load_source() and load_compiled() (and by extention +load_module()) now have a better chance of working when reloaded. + +.. + +.. bpo: 17804 +.. date: 8487 +.. nonce: 3ehiC3 +.. section: Library + +New function ``struct.iter_unpack`` allows for streaming struct unpacking. + +.. + +.. bpo: 17830 +.. date: 8486 +.. nonce: guxczO +.. section: Library + +When keyword.py is used to update a keyword file, it now preserves the line +endings of the original file. + +.. + +.. bpo: 17272 +.. date: 8485 +.. nonce: UdNBlq +.. section: Library + +Making the urllib.request's Request.full_url a descriptor. Fixes bugs with +assignment to full_url. Patch by Demian Brecht. + +.. + +.. bpo: 17353 +.. date: 8484 +.. nonce: 6Wiqfl +.. section: Library + +Plistlib emitted empty data tags with deeply nested datastructures + +.. + +.. bpo: 11714 +.. date: 8483 +.. nonce: EZxzYl +.. section: Library + +Use 'with' statements to assure a Semaphore releases a condition variable. +Original patch by Thomas Rachel. + +.. + +.. bpo: 16624 +.. date: 8482 +.. nonce: fEhnPS +.. section: Library + +`subprocess.check_output` now accepts an `input` argument, allowing the +subprocess's stdin to be provided as a (byte) string. Patch by Zack +Weinberg. + +.. + +.. bpo: 17795 +.. date: 8481 +.. nonce: IgVwMv +.. section: Library + +Reverted backwards-incompatible change in SysLogHandler with Unix domain +sockets. + +.. + +.. bpo: 16694 +.. date: 8480 +.. nonce: rHrtHr +.. section: Library + +Add a pure Python implementation of the operator module. Patch by Zachary +Ware. + +.. + +.. bpo: 11182 +.. date: 8479 +.. nonce: FEuMiq +.. section: Library + +remove the unused and undocumented pydoc.Scanner class. Patch by Martin +Morrison. + +.. + +.. bpo: 17741 +.. date: 8478 +.. nonce: nAezWJ +.. section: Library + +Add ElementTree.XMLPullParser, an event-driven parser for non-blocking +applications. + +.. + +.. bpo: 17555 +.. date: 8477 +.. nonce: 9klJCB +.. section: Library + +Fix ForkAwareThreadLock so that size of after fork registry does not grow +exponentially with generation of process. + +.. + +.. bpo: 17707 +.. date: 8476 +.. nonce: jX-JqL +.. section: Library + +fix regression in multiprocessing.Queue's get() method where it did not +block for short timeouts. + +.. + +.. bpo: 17720 +.. date: 8475 +.. nonce: mMh9Hz +.. section: Library + +Fix the Python implementation of pickle.Unpickler to correctly process the +APPENDS opcode when it is used on non-list objects. + +.. + +.. bpo: 17012 +.. date: 8474 +.. nonce: EW-5OU +.. section: Library + +shutil.which() no longer falls back to the PATH environment variable if an +empty path argument is specified. Patch by Serhiy Storchaka. + +.. + +.. bpo: 17710 +.. date: 8473 +.. nonce: OCzZ2n +.. section: Library + +Fix pickle raising a SystemError on bogus input. + +.. + +.. bpo: 17341 +.. date: 8472 +.. nonce: DI-1AO +.. section: Library + +Include the invalid name in the error messages from re about invalid group +names. + +.. + +.. bpo: 17702 +.. date: 8471 +.. nonce: ySqg1b +.. section: Library + +os.environ now raises KeyError with the original environment variable name +(str on UNIX), instead of using the encoded name (bytes on UNIX). + +.. + +.. bpo: 16163 +.. date: 8470 +.. nonce: 3aay4D +.. section: Library + +Make the importlib based version of pkgutil.iter_importers work for +submodules. Initial patch by Berker Peksag. + +.. + +.. bpo: 16804 +.. date: 8469 +.. nonce: vK8Q1B +.. section: Library + +Fix a bug in the 'site' module that caused running 'python -S -m site' to +incorrectly throw an exception. + +.. + +.. bpo: 15480 +.. date: 8468 +.. nonce: RMEmOd +.. section: Library + +Remove the deprecated and unused TYPE_INT64 code from marshal. Initial patch +by Daniel Riti. + +.. + +.. bpo: 2118 +.. date: 8467 +.. nonce: jsDIem +.. section: Library + +SMTPException is now a subclass of OSError. + +.. + +.. bpo: 17016 +.. date: 8466 +.. nonce: lQnMI8 +.. section: Library + +Get rid of possible pointer wraparounds and integer overflows in the re +module. Patch by Nickolai Zeldovich. + +.. + +.. bpo: 16658 +.. date: 8465 +.. nonce: WgAKmI +.. section: Library + +add missing return to HTTPConnection.send(). Patch by Jeff Knupp. + +.. + +.. bpo: 9556 +.. date: 8464 +.. nonce: Dk30j0 +.. section: Library + +the logging package now allows specifying a time-of-day for a +TimedRotatingFileHandler to rotate. + +.. + +.. bpo: 14971 +.. date: 8463 +.. nonce: cc8xNA +.. section: Library + +unittest test discovery no longer gets confused when a function has a +different __name__ than its name in the TestCase class dictionary. + +.. + +.. bpo: 17487 +.. date: 8462 +.. nonce: pP4v4C +.. section: Library + +The wave getparams method now returns a namedtuple rather than a plain +tuple. + +.. + +.. bpo: 17675 +.. date: 8461 +.. nonce: -A8oHC +.. section: Library + +socket repr() provides local and remote addresses (if any). Patch by +Giampaolo Rodola' + +.. + +.. bpo: 17093 +.. date: 8460 +.. nonce: M-IcJ- +.. section: Library + +Make the ABCs in importlib.abc provide default values or raise reasonable +exceptions for their methods to make them more amenable to super() calls. + +.. + +.. bpo: 17566 +.. date: 8459 +.. nonce: dqA1rg +.. section: Library + +Make importlib.abc.Loader.module_repr() optional instead of an +abstractmethod; now it raises NotImplementedError so as to be ignored by +default. + +.. + +.. bpo: 17678 +.. date: 8458 +.. nonce: PZfAGl +.. section: Library + +Remove the use of deprecated method in http/cookiejar.py by changing the +call to get_origin_req_host() to origin_req_host. + +.. + +.. bpo: 17666 +.. date: 8457 +.. nonce: L8Gq8u +.. section: Library + +Fix reading gzip files with an extra field. + +.. + +.. bpo: 16475 +.. date: 8456 +.. nonce: aNp-kL +.. section: Library + +Support object instancing, recursion and interned strings in marshal + +.. + +.. bpo: 17502 +.. date: 8455 +.. nonce: yOccrz +.. section: Library + +Process DEFAULT values in mock side_effect that returns iterator. + +.. + +.. bpo: 16795 +.. date: 8454 +.. nonce: zi6RPl +.. section: Library + +On the ast.arguments object, unify vararg with varargannotation and kwarg +and kwargannotation. Change the column offset of ast.Attribute to be at the +attribute name. + +.. + +.. bpo: 17434 +.. date: 8453 +.. nonce: bctYsc +.. section: Library + +Properly raise a SyntaxError when a string occurs between future imports. + +.. + +.. bpo: 17117 +.. date: 8452 +.. nonce: 2wgWhb +.. section: Library + +Import and @importlib.util.set_loader now set __loader__ when it has a value +of None or the attribute doesn't exist. + +.. + +.. bpo: 17032 +.. date: 8451 +.. nonce: FKHNgX +.. section: Library + +The "global" in the "NameError: global name 'x' is not defined" error +message has been removed. Patch by Ram Rachum. + +.. + +.. bpo: 18080 +.. date: 8450 +.. nonce: 98cUEc +.. section: Library + +When building a C extension module on OS X, if the compiler is overriden +with the CC environment variable, use the new compiler as the default for +linking if LDSHARED is not also overriden. This restores Distutils behavior +introduced in 3.2.3 and inadvertently dropped in 3.3.0. + +.. + +.. bpo: 18113 +.. date: 8449 +.. nonce: 7w81KJ +.. section: Library + +Fixed a refcount leak in the curses.panel module's set_userptr() method. +Reported by Atsuo Ishimoto. + +.. + +.. bpo: 0 +.. date: 8448 +.. nonce: t5hfCI +.. section: Library + +Implement PEP 443 "Single-dispatch generic functions". + +.. + +.. bpo: 0 +.. date: 8447 +.. nonce: U2ylaI +.. section: Library + +Implement PEP 435 "Adding an Enum type to the Python standard library". + +.. + +.. bpo: 15596 +.. date: 8446 +.. nonce: 0NKCQv +.. section: Library + +Faster pickling of unicode strings. + +.. + +.. bpo: 17572 +.. date: 8445 +.. nonce: 98CntI +.. section: Library + +Avoid chained exceptions when passing bad directives to time.strptime(). +Initial patch by Claudiu Popa. + +.. + +.. bpo: 17435 +.. date: 8444 +.. nonce: 167Uzu +.. section: Library + +threading.Timer's __init__ method no longer uses mutable default values for +the args and kwargs parameters. + +.. + +.. bpo: 17526 +.. date: 8443 +.. nonce: wiYvlk +.. section: Library + +fix an IndexError raised while passing code without filename to +inspect.findsource(). Initial patch by Tyler Doyle. + +.. + +.. bpo: 17540 +.. date: 8442 +.. nonce: 0FlRFl +.. section: Library + +Added style parameter to logging formatter configuration by dict. + +.. + +.. bpo: 16692 +.. date: 8441 +.. nonce: 1HPMSd +.. section: Library + +The ssl module now supports TLS 1.1 and TLS 1.2. Initial patch by Michele +Orrù. + +.. + +.. bpo: 17025 +.. date: 8440 +.. nonce: 2cO-DW +.. section: Library + +multiprocessing: Reduce Queue and SimpleQueue contention. + +.. + +.. bpo: 17536 +.. date: 8439 +.. nonce: PLE2RC +.. section: Library + +Add to webbrowser's browser list: www-browser, x-www-browser, iceweasel, +iceape. + +.. + +.. bpo: 17150 +.. date: 8438 +.. nonce: cs1ti6 +.. section: Library + +pprint now uses line continuations to wrap long string literals. + +.. + +.. bpo: 17488 +.. date: 8437 +.. nonce: ODub-T +.. section: Library + +Change the subprocess.Popen bufsize parameter default value from unbuffered +(0) to buffering (-1) to match the behavior existing code expects and match +the behavior of the subprocess module in Python 2 to avoid introducing hard +to track down bugs. + +.. + +.. bpo: 17521 +.. date: 8436 +.. nonce: rDGKe7 +.. section: Library + +Corrected non-enabling of logger following two calls to fileConfig(). + +.. + +.. bpo: 17508 +.. date: 8435 +.. nonce: B0KwKx +.. section: Library + +Corrected logging MemoryHandler configuration in dictConfig() where the +target handler wasn't configured first. + +.. + +.. bpo: 17209 +.. date: 8434 +.. nonce: w9J1io +.. section: Library + +curses.window.get_wch() now correctly handles KeyboardInterrupt (CTRL+c). + +.. + +.. bpo: 5713 +.. date: 8433 +.. nonce: SuN3vQ +.. section: Library + +smtplib now handles 421 (closing connection) error codes when sending mail +by closing the socket and reporting the 421 error code via the exception +appropriate to the command that received the error response. + +.. + +.. bpo: 16997 +.. date: 8432 +.. nonce: vtxNkx +.. section: Library + +unittest.TestCase now provides a subTest() context manager to procedurally +generate, in an easy way, small test instances. + +.. + +.. bpo: 17485 +.. date: 8431 +.. nonce: coQ2Mv +.. section: Library + +Also delete the Request Content-Length header if the data attribute is +deleted. (Follow on to issue Issue #16464). + +.. + +.. bpo: 15927 +.. date: 8430 +.. nonce: YpppEm +.. section: Library + +CVS now correctly parses escaped newlines and carriage when parsing with +quoting turned off. + +.. + +.. bpo: 17467 +.. date: 8429 +.. nonce: XLE6Ww +.. section: Library + +add readline and readlines support to mock_open in unittest.mock. + +.. + +.. bpo: 13248 +.. date: 8428 +.. nonce: YnMTCa +.. section: Library + +removed deprecated and undocumented difflib.isbjunk, isbpopular. + +.. + +.. bpo: 17192 +.. date: 8427 +.. nonce: U0oKFo +.. section: Library + +Update the ctypes module's libffi to v3.0.13. This specifically addresses a +stack misalignment issue on x86 and issues on some more recent platforms. + +.. + +.. bpo: 8862 +.. date: 8426 +.. nonce: WkppFP +.. section: Library + +Fixed curses cleanup when getkey is interrputed by a signal. + +.. + +.. bpo: 17443 +.. date: 8425 +.. nonce: _ARDbV +.. section: Library + +imaplib.IMAP4_stream was using the default unbuffered IO in subprocess, but +the imap code assumes buffered IO. In Python2 this worked by accident. +IMAP4_stream now explicitly uses buffered IO. + +.. + +.. bpo: 17476 +.. date: 8424 +.. nonce: Vs3Ky0 +.. section: Library + +Fixed regression relative to Python2 in undocumented pydoc 'allmethods'; it +was missing unbound methods on the class. + +.. + +.. bpo: 17474 +.. date: 8423 +.. nonce: y7hWoH +.. section: Library + +Remove the deprecated methods of Request class. + +.. + +.. bpo: 16709 +.. date: 8422 +.. nonce: 03AeYP +.. section: Library + +unittest discover order is no-longer filesystem specific. Patch by Jeff +Ramnani. + +.. + +.. bpo: 0 +.. date: 8421 +.. nonce: 4ymwbY +.. section: Library + +Use the HTTPS PyPI url for upload, overriding any plain HTTP URL in pypirc. + +.. + +.. bpo: 5024 +.. date: 8420 +.. nonce: 4cj0qD +.. section: Library + +sndhdr.whichhdr now returns the frame count for WAV files rather than -1. + +.. + +.. bpo: 17460 +.. date: 8419 +.. nonce: EQquZ6 +.. section: Library + +Remove the strict argument of HTTPConnection and removing the +DeprecationWarning being issued from 3.2 onwards. + +.. + +.. bpo: 16880 +.. date: 8418 +.. nonce: VYBbI- +.. section: Library + +Do not assume _imp.load_dynamic() is defined in the imp module. + +.. + +.. bpo: 16389 +.. date: 8417 +.. nonce: uQ4z93 +.. section: Library + +Fixed a performance regression relative to Python 3.1 in the caching of +compiled regular expressions. + +.. + +.. bpo: 0 +.. date: 8416 +.. nonce: VWrGFv +.. section: Library + +Added missing FeedParser and BytesFeedParser to email.parser.__all__. + +.. + +.. bpo: 17431 +.. date: 8415 +.. nonce: nID-Rk +.. section: Library + +Fix missing import of BytesFeedParser in email.parser. + +.. + +.. bpo: 12921 +.. date: 8414 +.. nonce: TksQ6K +.. section: Library + +http.server's send_error takes an explain argument to send more information +in response. Patch contributed by Karl. + +.. + +.. bpo: 17414 +.. date: 8413 +.. nonce: lOLLCV +.. section: Library + +Add timeit, repeat, and default_timer to timeit.__all__. + +.. + +.. bpo: 1285086 +.. date: 8412 +.. nonce: RN9orX +.. section: Library + +Get rid of the refcounting hack and speed up urllib.parse.unquote() and +urllib.parse.unquote_to_bytes(). + +.. + +.. bpo: 17099 +.. date: 8411 +.. nonce: CfR4FA +.. section: Library + +Have importlib.find_loader() raise ValueError when __loader__ is not set, +harmonizing with what happens when the attribute is set to None. + +.. + +.. bpo: 0 +.. date: 8410 +.. nonce: a1ikiC +.. section: Library + +Expose the O_PATH constant in the os module if it is available. + +.. + +.. bpo: 17368 +.. date: 8409 +.. nonce: y8QiJd +.. section: Library + +Fix an off-by-one error in the Python JSON decoder that caused a failure +while decoding empty object literals when object_pairs_hook was specified. + +.. + +.. bpo: 17385 +.. date: 8408 +.. nonce: vuRrxn +.. section: Library + +Fix quadratic behavior in threading.Condition. The FIFO queue now uses a +deque instead of a list. + +.. + +.. bpo: 15806 +.. date: 8407 +.. nonce: vWRkOo +.. section: Library + +Add contextlib.ignore(). This creates a context manager to ignore specified +exceptions, replacing the "except SomeException: pass" idiom. + +.. + +.. bpo: 14645 +.. date: 8406 +.. nonce: FevIjz +.. section: Library + +The email generator classes now produce output using the specified linesep +throughout. Previously if the prolog, epilog, or body were stored with a +different linesep, that linesep was used. This fix corrects an RFC non- +compliance issue with smtplib.send_message. + +.. + +.. bpo: 17278 +.. date: 8405 +.. nonce: pOF4An +.. section: Library + +Fix a crash in heapq.heappush() and heapq.heappop() when the list is being +resized concurrently. + +.. + +.. bpo: 16962 +.. date: 8404 +.. nonce: 4mCLOO +.. section: Library + +Use getdents64 instead of the obsolete getdents syscall in the subprocess +module on Linux. + +.. + +.. bpo: 16935 +.. date: 8403 +.. nonce: ykjyut +.. section: Library + +unittest now counts the module as skipped if it raises SkipTest, instead of +counting it as an error. Patch by Zachary Ware. + +.. + +.. bpo: 17018 +.. date: 8402 +.. nonce: l8_sa8 +.. section: Library + +Make Process.join() retry if os.waitpid() fails with EINTR. + +.. + +.. bpo: 17223 +.. date: 8401 +.. nonce: gzcSyh +.. section: Library + +array module: Fix a crasher when converting an array containing invalid +characters (outside range [U+0000; U+10ffff]) to Unicode: repr(array), +str(array) and array.tounicode(). Patch written by Manuel Jacob. + +.. + +.. bpo: 17197 +.. date: 8400 +.. nonce: 8BMC_8 +.. section: Library + +profile/cProfile modules refactored so that code of run() and runctx() +utility functions is not duplicated in both modules. + +.. + +.. bpo: 14720 +.. date: 8399 +.. nonce: rjT0OJ +.. section: Library + +sqlite3: Convert datetime microseconds correctly. Patch by Lowe Thiderman. + +.. + +.. bpo: 15132 +.. date: 8398 +.. nonce: kC6tTe +.. section: Library + +Allow a list for the defaultTest argument of unittest.TestProgram. Patch by +Jyrki Pulliainen. + +.. + +.. bpo: 17225 +.. date: 8397 +.. nonce: Z396fN +.. section: Library + +JSON decoder now counts columns in the first line starting with 1, as in +other lines. + +.. + +.. bpo: 6623 +.. date: 8396 +.. nonce: eWizvk +.. section: Library + +Added explicit DeprecationWarning for ftplib.netrc, which has been +deprecated and undocumented for a long time. + +.. + +.. bpo: 13700 +.. date: 8395 +.. nonce: sfJ2nZ +.. section: Library + +Fix byte/string handling in imaplib authentication when an authobject is +specified. + +.. + +.. bpo: 13153 +.. date: 8394 +.. nonce: DW27xH +.. section: Library + +Tkinter functions now raise TclError instead of ValueError when a string +argument contains non-BMP character. + +.. + +.. bpo: 9669 +.. date: 8393 +.. nonce: Td9alB +.. section: Library + +Protect re against infinite loops on zero-width matching in non-greedy +repeat. Patch by Matthew Barnett. + +.. + +.. bpo: 13169 +.. date: 8392 +.. nonce: txDMgH +.. section: Library + +The maximal repetition number in a regular expression has been increased +from 65534 to 2147483647 (on 32-bit platform) or 4294967294 (on 64-bit). + +.. + +.. bpo: 17143 +.. date: 8391 +.. nonce: HLnFxv +.. section: Library + +Fix a missing import in the trace module. Initial patch by Berker Peksag. + +.. + +.. bpo: 15220 +.. date: 8390 +.. nonce: 7GI-FE +.. section: Library + +email.feedparser's line splitting algorithm is now simpler and faster. + +.. + +.. bpo: 16743 +.. date: 8389 +.. nonce: 7vwfDN +.. section: Library + +Fix mmap overflow check on 32 bit Windows. + +.. + +.. bpo: 16996 +.. date: 8388 +.. nonce: HEPEjp +.. section: Library + +webbrowser module now uses shutil.which() to find a web-browser on the +executable search path. + +.. + +.. bpo: 16800 +.. date: 8387 +.. nonce: HxSo58 +.. section: Library + +tempfile.gettempdir() no longer left temporary files when the disk is full. +Original patch by Amir Szekely. + +.. + +.. bpo: 17192 +.. date: 8386 +.. nonce: f8i9hd +.. section: Library + +Import libffi-3.0.12. + +.. + +.. bpo: 16564 +.. date: 8385 +.. nonce: KBvsbB +.. section: Library + +Fixed regression relative to Python2 in the operation of +email.encoders.encode_7or8bit when used with binary data. + +.. + +.. bpo: 17052 +.. date: 8384 +.. nonce: TEWdzQ +.. section: Library + +unittest discovery should use self.testLoader. + +.. + +.. bpo: 4591 +.. date: 8383 +.. nonce: 9wJlD8 +.. section: Library + +Uid and gid values larger than 2**31 are supported now. + +.. + +.. bpo: 17141 +.. date: 8382 +.. nonce: wvMZ5Q +.. section: Library + +random.vonmisesvariate() no longer hangs for large kappas. + +.. + +.. bpo: 17149 +.. date: 8381 +.. nonce: _hUd7T +.. section: Library + +Fix random.vonmisesvariate to always return results in [0, 2*math.pi]. + +.. + +.. bpo: 1470548 +.. date: 8380 +.. nonce: vqnyer +.. section: Library + +XMLGenerator now works with binary output streams. + +.. + +.. bpo: 6975 +.. date: 8379 +.. nonce: 4GoPXW +.. section: Library + +os.path.realpath() now correctly resolves multiple nested symlinks on POSIX +platforms. + +.. + +.. bpo: 13773 +.. date: 8378 +.. nonce: 2L-koI +.. section: Library + +sqlite3.connect() gets a new `uri` parameter to pass the filename as a URI, +allowing to pass custom options. + +.. + +.. bpo: 16564 +.. date: 8377 +.. nonce: 5RdAXG +.. section: Library + +Fixed regression relative to Python2 in the operation of +email.encoders.encode_noop when used with binary data. + +.. + +.. bpo: 10355 +.. date: 8376 +.. nonce: s_RAWf +.. section: Library + +The mode, name, encoding and newlines properties now work on +SpooledTemporaryFile objects even when they have not yet rolled over. +Obsolete method xreadline (which has never worked in Python 3) has been +removed. + +.. + +.. bpo: 16686 +.. date: 8375 +.. nonce: zT_bpe +.. section: Library + +Fixed a lot of bugs in audioop module. Fixed crashes in avgpp(), maxpp() +and ratecv(). Fixed an integer overflow in add(), bias(), and ratecv(). +reverse(), lin2lin() and ratecv() no more lose precision for 32-bit samples. +max() and rms() no more returns a negative result and various other +functions now work correctly with 32-bit sample -0x80000000. + +.. + +.. bpo: 17073 +.. date: 8374 +.. nonce: wlCar1 +.. section: Library + +Fix some integer overflows in sqlite3 module. + +.. + +.. bpo: 16723 +.. date: 8373 +.. nonce: q1Cw-s +.. section: Library + +httplib.HTTPResponse no longer marked closed when the connection is +automatically closed. + +.. + +.. bpo: 15359 +.. date: 8372 +.. nonce: UDphxr +.. section: Library + +Add CAN_BCM protocol support to the socket module. Patch by Brian Thorne. + +.. + +.. bpo: 16948 +.. date: 8371 +.. nonce: 8mm-53 +.. section: Library + +Fix quoted printable body encoding for non-latin1 character sets in the +email package. + +.. + +.. bpo: 16811 +.. date: 8370 +.. nonce: rlH6y6 +.. section: Library + +Fix folding of headers with no value in the provisional email policies. + +.. + +.. bpo: 17132 +.. date: 8369 +.. nonce: ebpN0J +.. section: Library + +Update symbol for "yield from" grammar changes. + +.. + +.. bpo: 17076 +.. date: 8368 +.. nonce: IOhR77 +.. section: Library + +Make copying of xattrs more tolerant of missing FS support. Patch by Thomas +Wouters. + +.. + +.. bpo: 17089 +.. date: 8367 +.. nonce: Z3-kED +.. section: Library + +Expat parser now correctly works with string input when the internal XML +encoding is not UTF-8 or US-ASCII. It also now accepts bytes and strings +larger than 2 GiB. + +.. + +.. bpo: 6083 +.. date: 8366 +.. nonce: 5_NDqv +.. section: Library + +Fix multiple segmentation faults occured when PyArg_ParseTuple parses nested +mutating sequence. + +.. + +.. bpo: 5289 +.. date: 8365 +.. nonce: 4azz2m +.. section: Library + +Fix ctypes.util.find_library on Solaris. + +.. + +.. bpo: 17106 +.. date: 8364 +.. nonce: -2_cbV +.. section: Library + +Fix a segmentation fault in io.TextIOWrapper when an underlying stream or a +decoder produces data of an unexpected type (i.e. when io.TextIOWrapper +initialized with text stream or use bytes-to-bytes codec). + +.. + +.. bpo: 17015 +.. date: 8363 +.. nonce: SzigPI +.. section: Library + +When it has a spec, a Mock object now inspects its signature when matching +calls, so that arguments can be matched positionally or by name. + +.. + +.. bpo: 15633 +.. date: 8362 +.. nonce: t407yZ +.. section: Library + +httplib.HTTPResponse is now mark closed when the server sends less than the +advertised Content-Length. + +.. + +.. bpo: 12268 +.. date: 8361 +.. nonce: sIHfGM +.. section: Library + +The io module file object write methods no longer abort early when one of +its write system calls is interrupted (EINTR). + +.. + +.. bpo: 6972 +.. date: 8360 +.. nonce: e2Lq4T +.. section: Library + +The zipfile module no longer overwrites files outside of its destination +path when extracting malicious zip files. + +.. + +.. bpo: 4844 +.. date: 8359 +.. nonce: ascNW4 +.. section: Library + +ZipFile now raises BadZipFile when opens a ZIP file with an incomplete "End +of Central Directory" record. Original patch by Guilherme Polo and Alan +McIntyre. + +.. + +.. bpo: 17071 +.. date: 8358 +.. nonce: kRQAey +.. section: Library + +Signature.bind() now works when one of the keyword arguments is named +``self``. + +.. + +.. bpo: 12004 +.. date: 8357 +.. nonce: SAEl1I +.. section: Library + +Fix an internal error in PyZipFile when writing an invalid Python file. +Patch by Ben Morgan. + +.. + +.. bpo: 0 +.. date: 8356 +.. nonce: 4OOKnh +.. section: Library + +Have py_compile use importlib as much as possible to avoid code duplication. +Code now raises FileExistsError if the file path to be used for the byte- +compiled file is a symlink or non-regular file as a warning that import will +not keep the file path type if it writes to that path. + +.. + +.. bpo: 16972 +.. date: 8355 +.. nonce: nEo5JN +.. section: Library + +Have site.addpackage() consider already known paths even when none are +explicitly passed in. Bug report and fix by Kirill. + +.. + +.. bpo: 1602133 +.. date: 8354 +.. nonce: lYqpUo +.. section: Library + +on Mac OS X a shared library build (``--enable-shared``) now fills the +``os.environ`` variable correctly. + +.. + +.. bpo: 15505 +.. date: 8353 +.. nonce: -pH9Mh +.. section: Library + +`unittest.installHandler` no longer assumes SIGINT handler is set to a +callable object. + +.. + +.. bpo: 13454 +.. date: 8352 +.. nonce: 81rUI- +.. section: Library + +Fix a crash when deleting an iterator created by itertools.tee() if all +other iterators were very advanced before. + +.. + +.. bpo: 12411 +.. date: 8351 +.. nonce: cw1MdL +.. section: Library + +Fix to cgi.parse_multipart to correctly use bytes boundaries and bytes data. +Patch by Jonas Wagner. + +.. + +.. bpo: 16957 +.. date: 8350 +.. nonce: ne-gBj +.. section: Library + +shutil.which() no longer searches a bare file name in the current directory +on Unix and no longer searches a relative file path with a directory part in +PATH directories. Patch by Thomas Kluyver. + +.. + +.. bpo: 1159051 +.. date: 8349 +.. nonce: 1KBJ6M +.. section: Library + +GzipFile now raises EOFError when reading a corrupted file with truncated +header or footer. + +.. + +.. bpo: 16993 +.. date: 8348 +.. nonce: L3OmWx +.. section: Library + +shutil.which() now preserves the case of the path and extension on Windows. + +.. + +.. bpo: 16992 +.. date: 8347 +.. nonce: s_RXIM +.. section: Library + +On Windows in signal.set_wakeup_fd, validate the file descriptor argument. + +.. + +.. bpo: 16422 +.. date: 8346 +.. nonce: SNwB1o +.. section: Library + +For compatibility with the Python version, the C version of decimal now uses +strings instead of integers for rounding mode constants. + +.. + +.. bpo: 15861 +.. date: 8345 +.. nonce: gGkxCM +.. section: Library + +tkinter now correctly works with lists and tuples containing strings with +whitespaces, backslashes or unbalanced braces. + +.. + +.. bpo: 9720 +.. date: 8344 +.. nonce: XPXDks +.. section: Library + +zipfile now writes correct local headers for files larger than 4 GiB. + +.. + +.. bpo: 16955 +.. date: 8343 +.. nonce: VD_jpc +.. section: Library + +Fix the poll() method for multiprocessing's socket connections on Windows. + +.. + +.. bpo: 0 +.. date: 8342 +.. nonce: PoQ__t +.. section: Library + +SSLContext.load_dh_params() now properly closes the input file. + +.. + +.. bpo: 15031 +.. date: 8341 +.. nonce: an2pG1 +.. section: Library + +Refactor some .pyc management code to cut down on code duplication. Thanks +to Ronan Lamy for the report and taking an initial stab at the problem. + +.. + +.. bpo: 16398 +.. date: 8340 +.. nonce: JU7cL4 +.. section: Library + +Optimize deque.rotate() so that it only moves pointers and doesn't touch the +underlying data with increfs and decrefs. + +.. + +.. bpo: 16900 +.. date: 8339 +.. nonce: oyyCUi +.. section: Library + +Issue a ResourceWarning when an ssl socket is left unclosed. + +.. + +.. bpo: 13899 +.. date: 8338 +.. nonce: PJ5tHf +.. section: Library + +``\A``, ``\Z``, and ``\B`` now correctly match the A, Z, and B literals when +used inside character classes (e.g. ``'[\A]'``). Patch by Matthew Barnett. + +.. + +.. bpo: 15545 +.. date: 8337 +.. nonce: FCBNNV +.. section: Library + +Fix regression in sqlite3's iterdump method where it was failing if the +connection used a row factory (such as sqlite3.Row) that produced unsortable +objects. (Regression was introduced by fix for 9750). + +.. + +.. bpo: 0 +.. date: 8336 +.. nonce: dEUst7 +.. section: Library + +fcntl: add F_DUPFD_CLOEXEC constant, available on Linux 2.6.24+. + +.. + +.. bpo: 15972 +.. date: 8335 +.. nonce: G3_6id +.. section: Library + +Fix error messages when os functions expecting a file name or file +descriptor receive the incorrect type. + +.. + +.. bpo: 8109 +.. date: 8334 +.. nonce: CbDLHH +.. section: Library + +The ssl module now has support for server-side SNI, thanks to a +:meth:`SSLContext.set_servername_callback` method. Patch by Daniel Black. + +.. + +.. bpo: 16860 +.. date: 8333 +.. nonce: W9CpNg +.. section: Library + +In tempfile, use O_CLOEXEC when available to set the close-on-exec flag +atomically. + +.. + +.. bpo: 16674 +.. date: 8332 +.. nonce: Q8wDpT +.. section: Library + +random.getrandbits() is now 20-40% faster for small integers. + +.. + +.. bpo: 16009 +.. date: 8331 +.. nonce: tTmrs1 +.. section: Library + +JSON error messages now provide more information. + +.. + +.. bpo: 16828 +.. date: 8330 +.. nonce: uSGRTZ +.. section: Library + +Fix error incorrectly raised by bz2.compress(b'') and +bz2.BZ2Compressor.compress(b''). Initial patch by Martin Packman. + +.. + +.. bpo: 16833 +.. date: 8329 +.. nonce: g0QSh5 +.. section: Library + +In http.client.HTTPConnection, do not concatenate the request headers and +body when the payload exceeds 16 KB, since it can consume more memory for no +benefit. Patch by Benno Leslie. + +.. + +.. bpo: 16541 +.. date: 8328 +.. nonce: rfIhAb +.. section: Library + +tk_setPalette() now works with keyword arguments. + +.. + +.. bpo: 16820 +.. date: 8327 +.. nonce: e27ceV +.. section: Library + +In configparser, `parser.popitem()` no longer raises ValueError. This makes +`parser.clean()` work correctly. + +.. + +.. bpo: 16820 +.. date: 8326 +.. nonce: eSaGa4 +.. section: Library + +In configparser, ``parser['section'] = {}`` now preserves section order +within the parser. This makes `parser.update()` preserve section order as +well. + +.. + +.. bpo: 16820 +.. date: 8325 +.. nonce: yk3gzb +.. section: Library + +In configparser, ``parser['DEFAULT'] = {}`` now correctly clears previous +values stored in the default section. Same goes for +``parser.update({'DEFAULT': {}})``. + +.. + +.. bpo: 9586 +.. date: 8324 +.. nonce: 9tuKgR +.. section: Library + +Redefine SEM_FAILED on MacOSX to keep compiler happy. + +.. + +.. bpo: 16787 +.. date: 8323 +.. nonce: H5R03d +.. section: Library + +Increase asyncore and asynchat default output buffers size, to decrease CPU +usage and increase throughput. + +.. + +.. bpo: 10527 +.. date: 8322 +.. nonce: 7btVvN +.. section: Library + +make multiprocessing use poll() instead of select() if available. + +.. + +.. bpo: 16688 +.. date: 8321 +.. nonce: V4uNMo +.. section: Library + +Now regexes contained backreferences correctly work with non-ASCII strings. +Patch by Matthew Barnett. + +.. + +.. bpo: 16486 +.. date: 8320 +.. nonce: bfM62e +.. section: Library + +Make aifc files act as context managers. + +.. + +.. bpo: 16485 +.. date: 8319 +.. nonce: aUJyTZ +.. section: Library + +Now file descriptors are closed if file header patching failed on closing an +aifc file. + +.. + +.. bpo: 16640 +.. date: 8318 +.. nonce: uijEnP +.. section: Library + +Run less code under a lock in sched module. + +.. + +.. bpo: 16165 +.. date: 8317 +.. nonce: QuZOIy +.. section: Library + +sched.scheduler.run() no longer blocks a scheduler for other threads. + +.. + +.. bpo: 16641 +.. date: 8316 +.. nonce: JYpAhs +.. section: Library + +Default values of sched.scheduler.enter() are no longer modifiable. + +.. + +.. bpo: 16618 +.. date: 8315 +.. nonce: lo3BQu +.. section: Library + +Make glob.glob match consistently across strings and bytes regarding leading +dots. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16788 +.. date: 8314 +.. nonce: Os6OJu +.. section: Library + +Add samestat to Lib/ntpath.py + +.. + +.. bpo: 16713 +.. date: 8313 +.. nonce: Mq84Hq +.. section: Library + +Parsing of 'tel' urls using urlparse separates params from path. + +.. + +.. bpo: 16443 +.. date: 8312 +.. nonce: SnGosi +.. section: Library + +Add docstrings to regular expression match objects. Patch by Anton Kasyanov. + +.. + +.. bpo: 15701 +.. date: 8311 +.. nonce: rAh1Sy +.. section: Library + +Fix HTTPError info method call to return the headers information. + +.. + +.. bpo: 16752 +.. date: 8310 +.. nonce: gIWkHK +.. section: Library + +Add a missing import to modulefinder. Patch by Berker Peksag. + +.. + +.. bpo: 16646 +.. date: 8309 +.. nonce: Tc3vsq +.. section: Library + +ftplib.FTP.makeport() might lose socket error details. (patch by Serhiy +Storchaka) + +.. + +.. bpo: 16626 +.. date: 8308 +.. nonce: P9xKcu +.. section: Library + +Fix infinite recursion in glob.glob() on Windows when the pattern contains a +wildcard in the drive or UNC path. Patch by Serhiy Storchaka. + +.. + +.. bpo: 15783 +.. date: 8307 +.. nonce: y8LbED +.. section: Library + +Except for the number methods, the C version of decimal now supports all +None default values present in decimal.py. These values were largely +undocumented. + +.. + +.. bpo: 11175 +.. date: 8306 +.. nonce: T80G4_ +.. section: Library + +argparse.FileType now accepts encoding and errors arguments. Patch by Lucas +Maystre. + +.. + +.. bpo: 16488 +.. date: 8305 +.. nonce: SeOkz0 +.. section: Library + +epoll() objects now support the `with` statement. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 16298 +.. date: 8304 +.. nonce: kN3o52 +.. section: Library + +In HTTPResponse.read(), close the socket when there is no Content-Length and +the incoming stream is finished. Patch by Eran Rundstein. + +.. + +.. bpo: 16049 +.. date: 8303 +.. nonce: HeaoM8 +.. section: Library + +Add abc.ABC class to enable the use of inheritance to create ABCs, rather +than the more cumbersome metaclass=ABCMeta. Patch by Bruno Dupuis. + +.. + +.. bpo: 0 +.. date: 8302 +.. nonce: 0T54b0 +.. section: Library + +Expose the TCP_FASTOPEN and MSG_FASTOPEN flags in socket when they're +available. + +.. + +.. bpo: 15701 +.. date: 8301 +.. nonce: 7KaZjl +.. section: Library + +Add a .headers attribute to urllib.error.HTTPError. Patch contributed by +Berker Peksag. + +.. + +.. bpo: 15872 +.. date: 8300 +.. nonce: hPj0NT +.. section: Library + +Fix 3.3 regression introduced by the new fd-based shutil.rmtree that caused +it to not ignore certain errors when ignore_errors was set. Patch by +Alessandro Moura and Serhiy Storchaka. + +.. + +.. bpo: 16248 +.. date: 8299 +.. nonce: yOopnt +.. section: Library + +Disable code execution from the user's home directory by tkinter when the -E +flag is passed to Python. Patch by Zachary Ware. + +.. + +.. bpo: 13390 +.. date: 8298 +.. nonce: Oj2WC_ +.. section: Library + +New function :func:`sys.getallocatedblocks()` returns the number of memory +blocks currently allocated. + +.. + +.. bpo: 16628 +.. date: 8297 +.. nonce: qnWML3 +.. section: Library + +Fix a memory leak in ctypes.resize(). + +.. + +.. bpo: 13614 +.. date: 8296 +.. nonce: buqA2j +.. section: Library + +Fix setup.py register failure with invalid rst in description. Patch by +Julien Courteau and Pierre Paul Lefebvre. + +.. + +.. bpo: 13512 +.. date: 8295 +.. nonce: KW8Du9 +.. section: Library + +Create ~/.pypirc securely (CVE-2011-4944). Initial patch by Philip Jenvey, +tested by Mageia and Debian. + +.. + +.. bpo: 7719 +.. date: 8294 +.. nonce: O-kdp6 +.. section: Library + +Make distutils ignore ``.nfs*`` files instead of choking later on. Initial +patch by SilentGhost and Jeff Ramnani. + +.. + +.. bpo: 13120 +.. date: 8293 +.. nonce: XjAzio +.. section: Library + +Allow to call pdb.set_trace() from thread. Patch by Ilya Sandler. + +.. + +.. bpo: 16585 +.. date: 8292 +.. nonce: f_MHWg +.. section: Library + +Make CJK encoders support error handlers that return bytes per PEP 383. + +.. + +.. bpo: 10182 +.. date: 8291 +.. nonce: 0nH79H +.. section: Library + +The re module doesn't truncate indices to 32 bits anymore. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 16333 +.. date: 8290 +.. nonce: 8YUVkp +.. section: Library + +use (",", ": ") as default separator in json when indent is specified, to +avoid trailing whitespace. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16573 +.. date: 8289 +.. nonce: kKjx72 +.. section: Library + +In 2to3, treat enumerate() like a consuming call, so superfluous list() +calls aren't added to filter(), map(), and zip() which are directly passed +enumerate(). + +.. + +.. bpo: 16464 +.. date: 8288 +.. nonce: fcgAzt +.. section: Library + +Reset the Content-Length header when a urllib Request is reused with new +data. + +.. + +.. bpo: 12848 +.. date: 8287 +.. nonce: gGAbLz +.. section: Library + +The pure Python pickle implementation now treats object lengths as unsigned +32-bit integers, like the C implementation does. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16423 +.. date: 8286 +.. nonce: ZVmUs3 +.. section: Library + +urllib.request now has support for ``data:`` URLs. Patch by Mathias +Panzenböck. + +.. + +.. bpo: 4473 +.. date: 8285 +.. nonce: 3tTGZx +.. section: Library + +Add a POP3.stls() to switch a clear-text POP3 session into an encrypted POP3 +session, on supported servers. Patch by Lorenzo Catucci. + +.. + +.. bpo: 4473 +.. date: 8284 +.. nonce: BcE9oH +.. section: Library + +Add a POP3.capa() method to query the capabilities advertised by the POP3 +server. Patch by Lorenzo Catucci. + +.. + +.. bpo: 4473 +.. date: 8283 +.. nonce: dU-l8q +.. section: Library + +Ensure the socket is shutdown cleanly in POP3.close(). Patch by Lorenzo +Catucci. + +.. + +.. bpo: 16522 +.. date: 8282 +.. nonce: NIzWem +.. section: Library + +added FAIL_FAST flag to doctest. + +.. + +.. bpo: 15627 +.. date: 8281 +.. nonce: 4PHtp9 +.. section: Library + +Add the importlib.abc.InspectLoader.source_to_code() method. + +.. + +.. bpo: 16408 +.. date: 8280 +.. nonce: iqzks4 +.. section: Library + +Fix file descriptors not being closed in error conditions in the zipfile +module. Patch by Serhiy Storchaka. + +.. + +.. bpo: 14631 +.. date: 8279 +.. nonce: -GSQmy +.. section: Library + +Add a new :class:`weakref.WeakMethod` to simulate weak references to bound +methods. + +.. + +.. bpo: 16469 +.. date: 8278 +.. nonce: Od7MLh +.. section: Library + +Fix exceptions from float -> Fraction and Decimal -> Fraction conversions +for special values to be consistent with those for float -> int and Decimal +-> int. Patch by Alexey Kachayev. + +.. + +.. bpo: 16481 +.. date: 8277 +.. nonce: TsOri8 +.. section: Library + +multiprocessing no longer leaks process handles on Windows. + +.. + +.. bpo: 12428 +.. date: 8276 +.. nonce: wo0Z3V +.. section: Library + +Add a pure Python implementation of functools.partial(). Patch by Brian +Thorne. + +.. + +.. bpo: 16140 +.. date: 8275 +.. nonce: lszQfR +.. section: Library + +The subprocess module no longer double closes its child subprocess.PIPE +parent file descriptors on child error prior to exec(). + +.. + +.. bpo: 0 +.. date: 8274 +.. nonce: G2vxaZ +.. section: Library + +Remove a bare print to stdout from the subprocess module that could have +happened if the child process wrote garbage to its pre-exec error pipe. + +.. + +.. bpo: 0 +.. date: 8273 +.. nonce: Kf0oN- +.. section: Library + +The subprocess module now raises its own SubprocessError instead of a +RuntimeError in various error situations which should not normally happen. + +.. + +.. bpo: 16327 +.. date: 8272 +.. nonce: uVAHv3 +.. section: Library + +The subprocess module no longer leaks file descriptors used for +stdin/stdout/stderr pipes to the child when fork() fails. + +.. + +.. bpo: 14396 +.. date: 8271 +.. nonce: aUgPuV +.. section: Library + +Handle the odd rare case of waitpid returning 0 when not expected in +subprocess.Popen.wait(). + +.. + +.. bpo: 16411 +.. date: 8270 +.. nonce: 9Mn07O +.. section: Library + +Fix a bug where zlib.decompressobj().flush() might try to access previously- +freed memory. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16357 +.. date: 8269 +.. nonce: JSAbxU +.. section: Library + +fix calling accept() on a SSLSocket created through +SSLContext.wrap_socket(). Original patch by Jeff McNeil. + +.. + +.. bpo: 16409 +.. date: 8268 +.. nonce: Q4-W9i +.. section: Library + +The reporthook callback made by the legacy urllib.request.urlretrieve API +now properly supplies a constant non-zero block_size as it did in Python 3.2 +and 2.7. This matches the behavior of urllib.request.URLopener.retrieve. + +.. + +.. bpo: 16431 +.. date: 8267 +.. nonce: e4cPCA +.. section: Library + +Use the type information when constructing a Decimal subtype from a Decimal +argument. + +.. + +.. bpo: 15641 +.. date: 8266 +.. nonce: vCK1I7 +.. section: Library + +Clean up deprecated classes from importlib. Patch by Taras Lyapun. + +.. + +.. bpo: 16350 +.. date: 8265 +.. nonce: b77tF6 +.. section: Library + +zlib.decompressobj().decompress() now accumulates data from successive calls +after EOF in unused_data, instead of only saving the argument to the last +call. decompressobj().flush() now correctly sets unused_data and +unconsumed_tail. A bug in the handling of MemoryError when setting the +unconsumed_tail attribute has also been fixed. Patch by Serhiy Storchaka. + +.. + +.. bpo: 12759 +.. date: 8264 +.. nonce: c7p8aw +.. section: Library + +sre_parse now raises a proper error when the name of the group is missing. +Initial patch by Serhiy Storchaka. + +.. + +.. bpo: 16152 +.. date: 8263 +.. nonce: Lypvsp +.. section: Library + +fix tokenize to ignore whitespace at the end of the code when no newline is +found. Patch by Ned Batchelder. + +.. + +.. bpo: 16284 +.. date: 8262 +.. nonce: fNPApL +.. section: Library + +Prevent keeping unnecessary references to worker functions in +concurrent.futures ThreadPoolExecutor. + +.. + +.. bpo: 16230 +.. date: 8261 +.. nonce: DC1cQ_ +.. section: Library + +Fix a crash in select.select() when one the lists changes size while +iterated on. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16228 +.. date: 8260 +.. nonce: zsna-8 +.. section: Library + +Fix a crash in the json module where a list changes size while it is being +encoded. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16351 +.. date: 8259 +.. nonce: pm5Uwv +.. section: Library + +New function gc.get_stats() returns per-generation collection statistics. + +.. + +.. bpo: 14897 +.. date: 8258 +.. nonce: OGbALj +.. section: Library + +Enhance error messages of struct.pack and struct.pack_into. Patch by Matti +Mäki. + +.. + +.. bpo: 16316 +.. date: 8257 +.. nonce: JuyfbK +.. section: Library + +mimetypes now recognizes the .xz and .txz (.tar.xz) extensions. Patch by +Serhiy Storchaka. + +.. + +.. bpo: 12890 +.. date: 8256 +.. nonce: kDaDxa +.. section: Library + +cgitb no longer prints spurious

tags in text mode when the logdir option +is specified. + +.. + +.. bpo: 16307 +.. date: 8255 +.. nonce: a50VwB +.. section: Library + +Fix multiprocessing.Pool.map_async not calling its callbacks. Patch by Janne +Karila. + +.. + +.. bpo: 16305 +.. date: 8254 +.. nonce: 16wmhi +.. section: Library + +Fix a segmentation fault occurring when interrupting math.factorial. + +.. + +.. bpo: 16116 +.. date: 8253 +.. nonce: vgGtQF +.. section: Library + +Fix include and library paths to be correct when building C extensions in +venvs. + +.. + +.. bpo: 16245 +.. date: 8252 +.. nonce: kJSC-a +.. section: Library + +Fix the value of a few entities in html.entities.html5. + +.. + +.. bpo: 16301 +.. date: 8251 +.. nonce: t0fnjV +.. section: Library + +Fix the localhost verification in urllib/request.py for file:// urls. + +.. + +.. bpo: 16250 +.. date: 8250 +.. nonce: ieVkF0 +.. section: Library + +Fix the invocations of URLError which had misplaced filename attribute for +exception. + +.. + +.. bpo: 10836 +.. date: 8249 +.. nonce: Jh2ffY +.. section: Library + +Fix exception raised when file not found in urlretrieve Initial patch by +Ezio Melotti. + +.. + +.. bpo: 14398 +.. date: 8248 +.. nonce: jPT4ME +.. section: Library + +Fix size truncation and overflow bugs in the bz2 module. + +.. + +.. bpo: 12692 +.. date: 8247 +.. nonce: 2Mzlsy +.. section: Library + +Fix resource leak in urllib.request when talking to an HTTP server that does +not include a ``Connection: close`` header in its responses. + +.. + +.. bpo: 12034 +.. date: 8246 +.. nonce: btn3x3 +.. section: Library + +Fix bogus caching of result in check_GetFinalPathNameByHandle. Patch by +Atsuo Ishimoto. + +.. + +.. bpo: 0 +.. date: 8245 +.. nonce: D_nbXg +.. section: Library + +Improve performance of `lzma.LZMAFile` (see also issue #16034). + +.. + +.. bpo: 16220 +.. date: 8244 +.. nonce: KAtvbg +.. section: Library + +wsgiref now always calls close() on an iterable response. Patch by Brent +Tubbs. + +.. + +.. bpo: 16270 +.. date: 8243 +.. nonce: O-WZPm +.. section: Library + +urllib may hang when used for retrieving files via FTP by using a context +manager. Patch by Giampaolo Rodola'. + +.. + +.. bpo: 16461 +.. date: 8242 +.. nonce: 4XLB7L +.. section: Library + +Wave library should be able to deal with 4GB wav files, and sample rate of +44100 Hz. + +.. + +.. bpo: 16176 +.. date: 8241 +.. nonce: iZz-x5 +.. section: Library + +Properly identify Windows 8 via platform.platform() + +.. + +.. bpo: 16088 +.. date: 8240 +.. nonce: xlvl5i +.. section: Library + +BaseHTTPRequestHandler's send_error method includes a Content-Length header +in it's response now. Patch by Antoine Pitrou. + +.. + +.. bpo: 16114 +.. date: 8239 +.. nonce: 99pl4N +.. section: Library + +The subprocess module no longer provides a misleading error message stating +that args[0] did not exist when either the cwd or executable keyword +arguments specified a path that did not exist. + +.. + +.. bpo: 16169 +.. date: 8238 +.. nonce: zjnL7m +.. section: Library + +Fix ctypes.WinError()'s confusion between errno and winerror. + +.. + +.. bpo: 16110 +.. date: 8237 +.. nonce: fJpUiF +.. section: Library + +logging.fileConfig now accepts a pre-initialised ConfigParser instance. + +.. + +.. bpo: 1492704 +.. date: 8236 +.. nonce: 9rDdhr +.. section: Library + +shutil.copyfile() raises a distinct SameFileError now if source and +destination are the same file. Patch by Atsuo Ishimoto. + +.. + +.. bpo: 13896 +.. date: 8235 +.. nonce: iM0TJp +.. section: Library + +Make shelf instances work with 'with' as context managers. Original patch by +Filip Gruszczyński. + +.. + +.. bpo: 15417 +.. date: 8234 +.. nonce: Rd0mDH +.. section: Library + +Add support for csh and fish in venv activation scripts. + +.. + +.. bpo: 14377 +.. date: 8233 +.. nonce: P85CJN +.. section: Library + +ElementTree.write and some of the module-level functions have a new +parameter - *short_empty_elements*. It controls how elements with no +contents are emitted. + +.. + +.. bpo: 16089 +.. date: 8232 +.. nonce: L9jCK7 +.. section: Library + +Allow ElementTree.TreeBuilder to work again with a non-Element +element_factory (fixes a regression in SimpleTAL). + +.. + +.. bpo: 9650 +.. date: 8231 +.. nonce: cENePt +.. section: Library + +List commonly used format codes in time.strftime and time.strptime +docsttings. Original patch by Mike Hoy. + +.. + +.. bpo: 15452 +.. date: 8230 +.. nonce: qqK1EO +.. section: Library + +logging configuration socket listener now has a verify option that allows an +application to apply a verification function to the received configuration +data before it is acted upon. + +.. + +.. bpo: 16034 +.. date: 8229 +.. nonce: E_ZhP2 +.. section: Library + +Fix performance regressions in the new `bz2.BZ2File` implementation. +Initial patch by Serhiy Storchaka. + +.. + +.. bpo: 0 +.. date: 8228 +.. nonce: f4R5V2 +.. section: Library + +`pty.spawn()` now returns the child process status returned by +`os.waitpid()`. + +.. + +.. bpo: 15756 +.. date: 8227 +.. nonce: WAeC4R +.. section: Library + +`subprocess.poll()` now properly handles `errno.ECHILD` to return a +returncode of 0 when the child has already exited or cannot be waited on. + +.. + +.. bpo: 15323 +.. date: 8226 +.. nonce: L4bD_6 +.. section: Library + +Improve failure message of `Mock.assert_called_once_with()`. + +.. + +.. bpo: 16064 +.. date: 8225 +.. nonce: oSOZ0F +.. section: Library + +``unittest -m`` claims executable is "python", not "python3". + +.. + +.. bpo: 12376 +.. date: 8224 +.. nonce: XQz0f2 +.. section: Library + +Pass on parameters in `TextTestResult.__init__()` super call. + +.. + +.. bpo: 15222 +.. date: 8223 +.. nonce: 1KFZ58 +.. section: Library + +Insert blank line after each message in mbox mailboxes. + +.. + +.. bpo: 16013 +.. date: 8222 +.. nonce: QtdOeT +.. section: Library + +Fix `csv.Reader` parsing issue with ending quote characters. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15421 +.. date: 8221 +.. nonce: bS-Hq5 +.. section: Library + +Fix an OverflowError in `Calendar.itermonthdates()` after +`datetime.MAXYEAR`. Patch by Cédric Krier. + +.. + +.. bpo: 16112 +.. date: 8220 +.. nonce: 7UQthq +.. section: Library + +platform.architecture does not correctly escape argument to /usr/bin/file. +Patch by David Benjamin. + +.. + +.. bpo: 15970 +.. date: 8219 +.. nonce: -hD9Ha +.. section: Library + +`xml.etree.ElementTree` now serializes correctly the empty HTML elements +'meta' and 'param'. + +.. + +.. bpo: 15842 +.. date: 8218 +.. nonce: _Kzj4o +.. section: Library + +The `SocketIO.{readable,writable,seekable}` methods now raise ValueError +when the file-like object is closed. Patch by Alessandro Moura. + +.. + +.. bpo: 15876 +.. date: 8217 +.. nonce: hMWNMn +.. section: Library + +Fix a refleak in the `curses` module: window.encoding. + +.. + +.. bpo: 15881 +.. date: 8216 +.. nonce: 0CCbVo +.. section: Library + +Fix `atexit` hook in `multiprocessing`. Original patch by Chris McDonough. + +.. + +.. bpo: 15841 +.. date: 8215 +.. nonce: UVh8eH +.. section: Library + +The readable(), writable() and seekable() methods of `io.BytesIO` and +`io.StringIO` objects now raise ValueError when the object has been closed. +Patch by Alessandro Moura. + +.. + +.. bpo: 15447 +.. date: 8214 +.. nonce: bdNIb1 +.. section: Library + +Use `subprocess.DEVNULL` in webbrowser, instead of opening `os.devnull` +explicitly and leaving it open. + +.. + +.. bpo: 15509 +.. date: 8213 +.. nonce: q1hQFS +.. section: Library + +`webbrowser.UnixBrowser` no longer passes empty arguments to Popen when +``%action`` substitutions produce empty strings. + +.. + +.. bpo: 12776 +.. date: 8212 +.. nonce: XiJzFk +.. section: Library + +Call `argparse` type function (specified by add_argument) only once. Before, +the type function was called twice in the case where the default was +specified and the argument was given as well. This was especially +problematic for the FileType type, as a default file would always be opened, +even if a file argument was specified on the command line. (See also: +bpo-11839) + +.. + +.. bpo: 15906 +.. date: 8211 +.. nonce: qeshwx +.. section: Library + +Fix a regression in argparse caused by the preceding change, when +``action='append'``, ``type='str'`` and ``default=[]``. + +.. + +.. bpo: 16113 +.. date: 8210 +.. nonce: tpf8Os +.. section: Library + +Added sha3 module based on the Keccak reference implementation 3.2. The +`hashlib` module has four additional hash algorithms: `sha3_224`, +`sha3_256`, `sha3_384` and `sha3_512`. As part of the patch some common code +was moved from _hashopenssl.c to hashlib.h. + +.. + +.. bpo: 0 +.. date: 8209 +.. nonce: t35X7X +.. section: Library + +ctypes.call_commethod was removed, since its only usage was in the defunct +samples directory. + +.. + +.. bpo: 16692 +.. date: 8208 +.. nonce: Hh7vnr +.. section: Library + +Added TLSv1.1 and TLSv1.2 support for the ssl modules. + +.. + +.. bpo: 16832 +.. date: 8207 +.. nonce: D7LpUw +.. section: Library + +add abc.get_cache_token() to expose cache validity checking support in +ABCMeta. + +.. + +.. bpo: 18429 +.. date: 8206 +.. nonce: F1lTq1 +.. section: IDLE + +Format / Format Paragraph, now works when comment blocks are selected. As +with text blocks, this works best when the selection only includes complete +lines. + +.. + +.. bpo: 18226 +.. date: 8205 +.. nonce: 5HtrW1 +.. section: IDLE + +Add docstrings and unittests for FormatParagraph.py. Original patches by +Todd Rovito and Phil Webster. + +.. + +.. bpo: 18279 +.. date: 8204 +.. nonce: UoF-oR +.. section: IDLE + +Format - Strip trailing whitespace no longer marks a file as changed when it +has not been changed. This fix followed the addition of a test file +originally written by Phil Webster (the issue's main goal). + +.. + +.. bpo: 7136 +.. date: 8203 +.. nonce: 7horQf +.. section: IDLE + +In the Idle File menu, "New Window" is renamed "New File". Patch by Tal +Einat, Roget Serwy, and Todd Rovito. + +.. + +.. bpo: 0 +.. date: 8202 +.. nonce: OsJiav +.. section: IDLE + +Remove dead imports of imp. + +.. + +.. bpo: 18196 +.. date: 8201 +.. nonce: hyO7x0 +.. section: IDLE + +Avoid displaying spurious SystemExit tracebacks. + +.. + +.. bpo: 5492 +.. date: 8200 +.. nonce: LCx7lq +.. section: IDLE + +Avoid traceback when exiting IDLE caused by a race condition. + +.. + +.. bpo: 17511 +.. date: 8199 +.. nonce: 6XqdTH +.. section: IDLE + +Keep IDLE find dialog open after clicking "Find Next". Original patch by +Sarah K. + +.. + +.. bpo: 18055 +.. date: 8198 +.. nonce: e6MZXb +.. section: IDLE + +Move IDLE off of imp and on to importlib. + +.. + +.. bpo: 15392 +.. date: 8197 +.. nonce: ukT_lg +.. section: IDLE + +Create a unittest framework for IDLE. Initial patch by Rajagopalasarma +Jayakrishnan. See Lib/idlelib/idle_test/README.txt for how to run Idle +tests. + +.. + +.. bpo: 14146 +.. date: 8196 +.. nonce: -n5gzd +.. section: IDLE + +Highlight source line while debugging on Windows. + +.. + +.. bpo: 17838 +.. date: 8195 +.. nonce: -DDdhT +.. section: IDLE + +Allow sys.stdin to be reassigned. + +.. + +.. bpo: 13495 +.. date: 8194 +.. nonce: CqEc2d +.. section: IDLE + +Avoid loading the color delegator twice in IDLE. + +.. + +.. bpo: 17798 +.. date: 8193 +.. nonce: PVfMob +.. section: IDLE + +Allow IDLE to edit new files when specified on command line. + +.. + +.. bpo: 14735 +.. date: 8192 +.. nonce: lbbw49 +.. section: IDLE + +Update IDLE docs to omit "Control-z on Windows". + +.. + +.. bpo: 17532 +.. date: 8191 +.. nonce: wgA70Z +.. section: IDLE + +Always include Options menu for IDLE on OS X. Patch by Guilherme Simões. + +.. + +.. bpo: 17585 +.. date: 8190 +.. nonce: oXlcVX +.. section: IDLE + +Fixed IDLE regression. Now closes when using exit() or quit(). + +.. + +.. bpo: 17657 +.. date: 8189 +.. nonce: rGfxNo +.. section: IDLE + +Show full Tk version in IDLE's about dialog. Patch by Todd Rovito. + +.. + +.. bpo: 17613 +.. date: 8188 +.. nonce: MfAJ31 +.. section: IDLE + +Prevent traceback when removing syntax colorizer in IDLE. + +.. + +.. bpo: 1207589 +.. date: 8187 +.. nonce: wqzkjh +.. section: IDLE + +Backwards-compatibility patch for right-click menu in IDLE. + +.. + +.. bpo: 16887 +.. date: 8186 +.. nonce: -tb-0g +.. section: IDLE + +IDLE now accepts Cancel in tabify/untabify dialog box. + +.. + +.. bpo: 17625 +.. date: 8185 +.. nonce: SoDm9J +.. section: IDLE + +In IDLE, close the replace dialog after it is used. + +.. + +.. bpo: 14254 +.. date: 8184 +.. nonce: heeMG- +.. section: IDLE + +IDLE now handles readline correctly across shell restarts. + +.. + +.. bpo: 17614 +.. date: 8183 +.. nonce: 9pmpYW +.. section: IDLE + +IDLE no longer raises exception when quickly closing a file. + +.. + +.. bpo: 6698 +.. date: 8182 +.. nonce: fXoiv2 +.. section: IDLE + +IDLE now opens just an editor window when configured to do so. + +.. + +.. bpo: 8900 +.. date: 8181 +.. nonce: jkW99r +.. section: IDLE + +Using keyboard shortcuts in IDLE to open a file no longer raises an +exception. + +.. + +.. bpo: 6649 +.. date: 8180 +.. nonce: uwGice +.. section: IDLE + +Fixed missing exit status in IDLE. Patch by Guilherme Polo. + +.. + +.. bpo: 17114 +.. date: 8179 +.. nonce: vKMHae +.. section: IDLE + +IDLE now uses non-strict config parser. + +.. + +.. bpo: 9290 +.. date: 8178 +.. nonce: Msbacw +.. section: IDLE + +In IDLE the sys.std* streams now implement io.TextIOBase interface and +support all mandatory methods and properties. + +.. + +.. bpo: 5066 +.. date: 8177 +.. nonce: 005zjD +.. section: IDLE + +Update IDLE docs. Patch by Todd Rovito. + +.. + +.. bpo: 16829 +.. date: 8176 +.. nonce: u44Uel +.. section: IDLE + +IDLE printing no longer fails if there are spaces or other special +characters in the file path. + +.. + +.. bpo: 16491 +.. date: 8175 +.. nonce: xeXwAA +.. section: IDLE + +IDLE now prints chained exception tracebacks. + +.. + +.. bpo: 16819 +.. date: 8174 +.. nonce: xEntNh +.. section: IDLE + +IDLE method completion now correctly works for bytes literals. + +.. + +.. bpo: 16504 +.. date: 8173 +.. nonce: othtN_ +.. section: IDLE + +IDLE now catches SyntaxErrors raised by tokenizer. Patch by Roger Serwy. + +.. + +.. bpo: 16511 +.. date: 8172 +.. nonce: yFDlh7 +.. section: IDLE + +Use default IDLE width and height if config param is not valid. Patch Serhiy +Storchaka. + +.. + +.. bpo: 1207589 +.. date: 8171 +.. nonce: 0bmiue +.. section: IDLE + +Add Cut/Copy/Paste items to IDLE right click Context Menu. Patch by Todd +Rovito. + +.. + +.. bpo: 16123 +.. date: 8170 +.. nonce: btKEXc +.. section: IDLE + +IDLE - deprecate running without a subprocess. Patch by Roger Serwy. + +.. + +.. bpo: 1666318 +.. date: 8169 +.. nonce: OPrK2i +.. section: Tests + +Add a test that shutil.copytree() retains directory permissions. Patch by +Catherine Devlin. + +.. + +.. bpo: 18273 +.. date: 8168 +.. nonce: t4fyCm +.. section: Tests + +move the tests in Lib/test/json_tests to Lib/test/test_json and make them +discoverable by unittest. Patch by Zachary Ware. + +.. + +.. bpo: 0 +.. date: 8167 +.. nonce: wExQ77 +.. section: Tests + +Fix a fcntl test case on KFreeBSD, Debian #708653 (Petr Salinger). + +.. + +.. bpo: 18396 +.. date: 8166 +.. nonce: 3gPC49 +.. section: Tests + +Fix spurious test failure in test_signal on Windows when faulthandler is +enabled (Patch by Jeremy Kloth) + +.. + +.. bpo: 17046 +.. date: 8165 +.. nonce: mQoh7R +.. section: Tests + +Fix broken test_executable_without_cwd in test_subprocess. + +.. + +.. bpo: 15415 +.. date: 8164 +.. nonce: u-UTrH +.. section: Tests + +Add new temp_dir() and change_cwd() context managers to test.support, and +refactor temp_cwd() to use them. Patch by Chris Jerdonek. + +.. + +.. bpo: 15494 +.. date: 8163 +.. nonce: 52m-vd +.. section: Tests + +test.support is now a package rather than a module (Initial patch by Indra +Talip) + +.. + +.. bpo: 17944 +.. date: 8162 +.. nonce: 6e9wcJ +.. section: Tests + +test_zipfile now discoverable and uses subclassing to generate tests for +different compression types. Fixed a bug with skipping some tests due to +use of exhausted iterators. + +.. + +.. bpo: 18266 +.. date: 8161 +.. nonce: Fs0fT4 +.. section: Tests + +test_largefile now works with unittest test discovery and supports running +only selected tests. Patch by Zachary Ware. + +.. + +.. bpo: 17767 +.. date: 8160 +.. nonce: rObwV7 +.. section: Tests + +test_locale now works with unittest test discovery. Original patch by +Zachary Ware. + +.. + +.. bpo: 18375 +.. date: 8159 +.. nonce: yMrtSQ +.. section: Tests + +Assume --randomize when --randseed is used for running the testsuite. + +.. + +.. bpo: 11185 +.. date: 8158 +.. nonce: McIHeT +.. section: Tests + +Fix test_wait4 under AIX. Patch by Sébastien Sablé. + +.. + +.. bpo: 18207 +.. date: 8157 +.. nonce: QN93aB +.. section: Tests + +Fix test_ssl for some versions of OpenSSL that ignore seconds in ASN1_TIME +fields. + +.. + +.. bpo: 18094 +.. date: 8156 +.. nonce: EDwnjd +.. section: Tests + +test_uuid no longer reports skipped tests as passed. + +.. + +.. bpo: 17992 +.. date: 8155 +.. nonce: UQQWYc +.. section: Tests + +Add timeouts to asyncore and asynchat tests so that they won't accidentally +hang. + +.. + +.. bpo: 17833 +.. date: 8154 +.. nonce: AqQAlk +.. section: Tests + +Fix test_gdb failures seen on machines where debug symbols for glibc are +available (seen on PPC64 Linux). + +.. + +.. bpo: 7855 +.. date: 8153 +.. nonce: ZbX91d +.. section: Tests + +Add tests for ctypes/winreg for issues found in IronPython. Initial patch by +Dino Viehland. + +.. + +.. bpo: 11078 +.. date: 8152 +.. nonce: TuZjxB +.. section: Tests + +test___all__ now checks for duplicates in __all__. Initial patch by R. David +Murray. + +.. + +.. bpo: 17712 +.. date: 8151 +.. nonce: RqkHUB +.. section: Tests + +Fix test_gdb failures on Ubuntu 13.04. + +.. + +.. bpo: 17835 +.. date: 8150 +.. nonce: mJdR71 +.. section: Tests + +Fix test_io when the default OS pipe buffer size is larger than one million +bytes. + +.. + +.. bpo: 17065 +.. date: 8149 +.. nonce: rql8lF +.. section: Tests + +Use process-unique key for winreg tests to avoid failures if test is run +multiple times in parallel (eg: on a buildbot host). + +.. + +.. bpo: 12820 +.. date: 8148 +.. nonce: HATljf +.. section: Tests + +add tests for the xml.dom.minicompat module. Patch by John Chandler and Phil +Connell. + +.. + +.. bpo: 17691 +.. date: 8147 +.. nonce: KHFcyE +.. section: Tests + +test_univnewlines now works with unittest test discovery. Patch by Zachary +Ware. + +.. + +.. bpo: 17790 +.. date: 8146 +.. nonce: JJXcrD +.. section: Tests + +test_set now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17789 +.. date: 8145 +.. nonce: ILUl9_ +.. section: Tests + +test_random now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17779 +.. date: 8144 +.. nonce: f61EJr +.. section: Tests + +test_osx_env now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17766 +.. date: 8143 +.. nonce: fGhYwN +.. section: Tests + +test_iterlen now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17690 +.. date: 8142 +.. nonce: Tm3Owh +.. section: Tests + +test_time now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17692 +.. date: 8141 +.. nonce: 6eSLWJ +.. section: Tests + +test_sqlite now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 11995 +.. date: 8140 +.. nonce: varfN1 +.. section: Tests + +test_pydoc doesn't import all sys.path modules anymore. + +.. + +.. bpo: 17448 +.. date: 8139 +.. nonce: E2kxQS +.. section: Tests + +test_sax now skips if there are no xml parsers available instead of raising +an ImportError. + +.. + +.. bpo: 11420 +.. date: 8138 +.. nonce: J5oaxT +.. section: Tests + +make test suite pass with -B/DONTWRITEBYTECODE set. Initial patch by Thomas +Wouters. + +.. + +.. bpo: 10652 +.. date: 8137 +.. nonce: hWhWD_ +.. section: Tests + +make tcl/tk tests run after __all__ test, patch by Zachary Ware. + +.. + +.. bpo: 11963 +.. date: 8136 +.. nonce: _g8d_g +.. section: Tests + +remove human verification from test_parser and test_subprocess. + +.. + +.. bpo: 11732 +.. date: 8135 +.. nonce: c8z-Dq +.. section: Tests + +add a new suppress_crash_popup() context manager to test.support that +disables crash popups on Windows and use it in test_faulthandler and +test_capi. + +.. + +.. bpo: 13898 +.. date: 8134 +.. nonce: HeB5Ep +.. section: Tests + +test_ssl no longer prints a spurious stack trace on Ubuntu. + +.. + +.. bpo: 17283 +.. date: 8133 +.. nonce: rDD37m +.. section: Tests + +Share code between `__main__.py` and `regrtest.py` in `Lib/test`. + +.. + +.. bpo: 17249 +.. date: 8132 +.. nonce: wGvw7G +.. section: Tests + +convert a test in test_capi to use unittest and reap threads. + +.. + +.. bpo: 17107 +.. date: 8131 +.. nonce: rQeSWM +.. section: Tests + +Test client-side SNI support in urllib.request thanks to the new server-side +SNI support in the ssl module. Initial patch by Daniel Black. + +.. + +.. bpo: 17041 +.. date: 8130 +.. nonce: QNrBhm +.. section: Tests + +Fix testing when Python is configured with the --without-doc-strings. + +.. + +.. bpo: 16923 +.. date: 8129 +.. nonce: gK2bSh +.. section: Tests + +Fix ResourceWarnings in test_ssl. + +.. + +.. bpo: 15539 +.. date: 8128 +.. nonce: a1_G0Q +.. section: Tests + +Added regression tests for Tools/scripts/pindent.py. + +.. + +.. bpo: 17479 +.. date: 8127 +.. nonce: e2vj2q +.. section: Tests + +test_io now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17066 +.. date: 8126 +.. nonce: 6axkCO +.. section: Tests + +test_robotparser now works with unittest test discovery. Patch by Zachary +Ware. + +.. + +.. bpo: 17334 +.. date: 8125 +.. nonce: hOeO8N +.. section: Tests + +test_index now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17333 +.. date: 8124 +.. nonce: wKzaNc +.. section: Tests + +test_imaplib now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17082 +.. date: 8123 +.. nonce: B-o8aq +.. section: Tests + +test_dbm* now work with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17079 +.. date: 8122 +.. nonce: Uz1Ysh +.. section: Tests + +test_ctypes now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17304 +.. date: 8121 +.. nonce: HUHsX_ +.. section: Tests + +test_hash now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17303 +.. date: 8120 +.. nonce: TGUnon +.. section: Tests + +test_future* now work with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 17163 +.. date: 8119 +.. nonce: RtwHDs +.. section: Tests + +test_file now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16925 +.. date: 8118 +.. nonce: SMQSIJ +.. section: Tests + +test_configparser now works with unittest test discovery. Patch by Zachary +Ware. + +.. + +.. bpo: 16918 +.. date: 8117 +.. nonce: Dw6bfJ +.. section: Tests + +test_codecs now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16919 +.. date: 8116 +.. nonce: RD7mec +.. section: Tests + +test_crypt now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16910 +.. date: 8115 +.. nonce: awigr8 +.. section: Tests + +test_bytes, test_unicode, and test_userstring now work with unittest test +discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16905 +.. date: 8114 +.. nonce: 8SuIFn +.. section: Tests + +test_warnings now works with unittest test discovery. Initial patch by +Berker Peksag. + +.. + +.. bpo: 16898 +.. date: 8113 +.. nonce: 1pNH58 +.. section: Tests + +test_bufio now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16888 +.. date: 8112 +.. nonce: yWvMUM +.. section: Tests + +test_array now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16896 +.. date: 8111 +.. nonce: 8uLSFW +.. section: Tests + +test_asyncore now works with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16897 +.. date: 8110 +.. nonce: aEwG-R +.. section: Tests + +test_bisect now works with unittest test discovery. Initial patch by Zachary +Ware. + +.. + +.. bpo: 16852 +.. date: 8109 +.. nonce: z4zef9 +.. section: Tests + +test_genericpath, test_posixpath, test_ntpath, and test_macpath now work +with unittest test discovery. Patch by Zachary Ware. + +.. + +.. bpo: 16748 +.. date: 8108 +.. nonce: 74HpRw +.. section: Tests + +test_heapq now works with unittest test discovery. + +.. + +.. bpo: 10646 +.. date: 8107 +.. nonce: -n9wSX +.. section: Tests + +Tests rearranged for os.samefile/samestat to check for not just symlinks but +also hard links. + +.. + +.. bpo: 15302 +.. date: 8106 +.. nonce: nohKYA +.. section: Tests + +Switch regrtest from using getopt to using argparse. + +.. + +.. bpo: 15324 +.. date: 8105 +.. nonce: mcS3I3 +.. section: Tests + +Fix regrtest parsing of --fromfile, --match, and --randomize options. + +.. + +.. bpo: 16702 +.. date: 8104 +.. nonce: 3Xf_t- +.. section: Tests + +test_urllib2_localnet tests now correctly ignores proxies for localhost +tests. + +.. + +.. bpo: 16664 +.. date: 8103 +.. nonce: CxbZwX +.. section: Tests + +Add regression tests for glob's behaviour concerning entries starting with a +".". Patch by Sebastian Kreft. + +.. + +.. bpo: 13390 +.. date: 8102 +.. nonce: CRkOlc +.. section: Tests + +The ``-R`` option to regrtest now also checks for memory allocation leaks, +using :func:`sys.getallocatedblocks()`. + +.. + +.. bpo: 16559 +.. date: 8101 +.. nonce: JvxWbq +.. section: Tests + +Add more tests for the json module, including some from the official test +suite at json.org. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16661 +.. date: 8100 +.. nonce: Qn2hnC +.. section: Tests + +Fix the `os.getgrouplist()` test by not assuming that it gives the same +output as :command:`id -G`. + +.. + +.. bpo: 16115 +.. date: 8099 +.. nonce: vhK6oh +.. section: Tests + +Add some tests for the executable argument to subprocess.Popen(). Initial +patch by Kushal Das. + +.. + +.. bpo: 16126 +.. date: 8098 +.. nonce: blh5K0 +.. section: Tests + +PyErr_Format format mismatch in _testcapimodule.c. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15304 +.. date: 8097 +.. nonce: DhyMtI +.. section: Tests + +Fix warning message when `os.chdir()` fails inside +`test.support.temp_cwd()`. Patch by Chris Jerdonek. + +.. + +.. bpo: 15802 +.. date: 8096 +.. nonce: 1duwD4 +.. section: Tests + +Fix test logic in `TestMaildir.test_create_tmp()`. Patch by Serhiy +Storchaka. + +.. + +.. bpo: 15557 +.. date: 8095 +.. nonce: H9Mhea +.. section: Tests + +Added a test suite for the webbrowser module, thanks to Anton Barkovsky. + +.. + +.. bpo: 16698 +.. date: 8094 +.. nonce: RgmYjY +.. section: Tests + +Skip posix test_getgroups when built with OS X deployment target prior to +10.6. + +.. + +.. bpo: 16067 +.. date: 8093 +.. nonce: A9L5PU +.. section: Build + +Add description into MSI file to replace installer's temporary name. + +.. + +.. bpo: 18257 +.. date: 8092 +.. nonce: E-TNPc +.. section: Build + +Fix readlink usage in python-config. Install the python version again on +Darwin. + +.. + +.. bpo: 18481 +.. date: 8091 +.. nonce: Is1C3p +.. section: Build + +Add C coverage reporting with gcov and lcov. A new make target "coverage- +report" creates an instrumented Python build, runs unit tests and creates a +HTML. The report can be updated with "make coverage-lcov". + +.. + +.. bpo: 17845 +.. date: 8090 +.. nonce: kMmKYt +.. section: Build + +Clarified the message printed when some module are not built. + +.. + +.. bpo: 18256 +.. date: 8089 +.. nonce: PiEkYT +.. section: Build + +Compilation fix for recent AIX releases. Patch by David Edelsohn. + +.. + +.. bpo: 17547 +.. date: 8088 +.. nonce: yVllRd +.. section: Build + +In configure, explicitly pass -Wformat for the benefit for GCC 4.8. + +.. + +.. bpo: 15172 +.. date: 8087 +.. nonce: CpJRf2 +.. section: Build + +Document NASM 2.10+ as requirement for building OpenSSL 1.0.1 on Windows. + +.. + +.. bpo: 17591 +.. date: 8086 +.. nonce: e9az4p +.. section: Build + +Use lowercase filenames when including Windows header files. Patch by Roumen +Petrov. + +.. + +.. bpo: 17550 +.. date: 8085 +.. nonce: zn8gOk +.. section: Build + +Fix the --enable-profiling configure switch. + +.. + +.. bpo: 17425 +.. date: 8084 +.. nonce: Ix2fQh +.. section: Build + +Build with openssl 1.0.1d on Windows. + +.. + +.. bpo: 16754 +.. date: 8083 +.. nonce: fLN-7H +.. section: Build + +Fix the incorrect shared library extension on linux. Introduce two makefile +macros SHLIB_SUFFIX and EXT_SUFFIX. SO now has the value of SHLIB_SUFFIX +again (as in 2.x and 3.1). The SO macro is removed in 3.4. + +.. + +.. bpo: 5033 +.. date: 8082 +.. nonce: HKAgDA +.. section: Build + +Fix building of the sqlite3 extension module when the SQLite library version +has "beta" in it. Patch by Andreas Pelme. + +.. + +.. bpo: 17228 +.. date: 8081 +.. nonce: CCkAM0 +.. section: Build + +Fix building without pymalloc. + +.. + +.. bpo: 3718 +.. date: 8080 +.. nonce: n6-Cv2 +.. section: Build + +Use AC_ARG_VAR to set MACHDEP in configure.ac. + +.. + +.. bpo: 16235 +.. date: 8079 +.. nonce: u8Yi12 +.. section: Build + +Implement python-config as a shell script. + +.. + +.. bpo: 16769 +.. date: 8078 +.. nonce: bK11Wq +.. section: Build + +Remove outdated Visual Studio projects. + +.. + +.. bpo: 17031 +.. date: 8077 +.. nonce: 947KBS +.. section: Build + +Fix running regen in cross builds. + +.. + +.. bpo: 3754 +.. date: 8076 +.. nonce: sUdOUp +.. section: Build + +fix typo in pthread AC_CACHE_VAL. + +.. + +.. bpo: 15484 +.. date: 8075 +.. nonce: CgA5fS +.. section: Build + +Fix _PYTHON_PROJECT_BASE for srcdir != builddir builds; use +_PYTHON_PROJECT_BASE in distutils/sysconfig.py. + +.. + +.. bpo: 0 +.. date: 8074 +.. nonce: eLqyZu +.. section: Build + +Drop support for Windows 2000 (changeset e52df05b496a). + +.. + +.. bpo: 17029 +.. date: 8073 +.. nonce: dUd1NT +.. section: Build + +Let h2py search the multiarch system include directory. + +.. + +.. bpo: 16953 +.. date: 8072 +.. nonce: tW1KVY +.. section: Build + +Fix socket module compilation on platforms with HAVE_BROKEN_POLL. Patch by +Jeffrey Armstrong. + +.. + +.. bpo: 16320 +.. date: 8071 +.. nonce: wSizMv +.. section: Build + +Remove redundant Makefile dependencies for strings and bytes. + +.. + +.. bpo: 0 +.. date: 8070 +.. nonce: WRrrlF +.. section: Build + +Cross compiling needs host and build settings. configure no longer creates a +broken PYTHON_FOR_BUILD variable when --build is missing. + +.. + +.. bpo: 0 +.. date: 8069 +.. nonce: R2awqG +.. section: Build + +Fix cross compiling issue in setup.py, ensure that lib_dirs and inc_dirs are +defined in cross compiling mode, too. + +.. + +.. bpo: 16836 +.. date: 8068 +.. nonce: JZ-zO7 +.. section: Build + +Enable IPv6 support even if IPv6 is disabled on the build host. + +.. + +.. bpo: 16593 +.. date: 8067 +.. nonce: mS-VZr +.. section: Build + +Have BSD 'make -s' do the right thing, thanks to Daniel Shahaf + +.. + +.. bpo: 16262 +.. date: 8066 +.. nonce: puaCXo +.. section: Build + +fix out-of-src-tree builds, if mercurial is not installed. + +.. + +.. bpo: 15298 +.. date: 8065 +.. nonce: xiQHlO +.. section: Build + +ensure _sysconfigdata is generated in build directory, not source directory. + +.. + +.. bpo: 15833 +.. date: 8064 +.. nonce: tqz7oy +.. section: Build + +Fix a regression in 3.3 that resulted in exceptions being raised if +importlib failed to write byte-compiled files. This affected attempts to +build Python out-of-tree from a read-only source directory. + +.. + +.. bpo: 15923 +.. date: 8063 +.. nonce: a2-GWK +.. section: Build + +Fix a mistake in ``asdl_c.py`` that resulted in a TypeError after +2801bf875a24 (see #15801). + +.. + +.. bpo: 16135 +.. date: 8062 +.. nonce: G5PgZc +.. section: Build + +Remove OS/2 support. + +.. + +.. bpo: 15819 +.. date: 8061 +.. nonce: VE2bTI +.. section: Build + +Make sure we can build Python out-of-tree from a read-only source directory. +(Somewhat related to issue #9860.) + +.. + +.. bpo: 15587 +.. date: 8060 +.. nonce: gR7vei +.. section: Build + +Enable Tk high-resolution text rendering on Macs with Retina displays. +Applies to Tkinter apps, such as IDLE, on OS X framework builds linked with +Cocoa Tk 8.5. + +.. + +.. bpo: 17161 +.. date: 8059 +.. nonce: AT7PDZ +.. section: Build + +make install now also installs a python3 man page. + +.. + +.. bpo: 18351 +.. date: 8058 +.. nonce: pODT4P +.. section: C API + +Fix various issues in a function in importlib provided to help +PyImport_ExecCodeModuleWithPathnames() (and thus by extension +PyImport_ExecCodeModule() and PyImport_ExecCodeModuleEx()). + +.. + +.. bpo: 9369 +.. date: 8057 +.. nonce: z_ZQqc +.. section: C API + +The types of `char*` arguments of PyObject_CallFunction() and +PyObject_CallMethod() now changed to `const char*`. Based on patches by +Jörg Müller and Lars Buitinck. + +.. + +.. bpo: 17206 +.. date: 8056 +.. nonce: yljYPd +.. section: C API + +Py_CLEAR(), Py_DECREF(), Py_XINCREF() and Py_XDECREF() now expand their +arguments once instead of multiple times. Patch written by Illia +Polosukhin. + +.. + +.. bpo: 17522 +.. date: 8055 +.. nonce: 7R55LY +.. section: C API + +Add the PyGILState_Check() API. + +.. + +.. bpo: 17327 +.. date: 8054 +.. nonce: PVFW3J +.. section: C API + +Add PyDict_SetDefault. + +.. + +.. bpo: 16881 +.. date: 8053 +.. nonce: 8SMude +.. section: C API + +Fix Py_ARRAY_LENGTH macro for GCC < 3.1. + +.. + +.. bpo: 16505 +.. date: 8052 +.. nonce: NiEndF +.. section: C API + +Remove unused Py_TPFLAGS_INT_SUBCLASS. + +.. + +.. bpo: 16086 +.. date: 8051 +.. nonce: z-DFqk +.. section: C API + +PyTypeObject.tp_flags and PyType_Spec.flags are now unsigned (unsigned long +and unsigned int) to avoid an undefined behaviour with +Py_TPFLAGS_TYPE_SUBCLASS ((1 << 31). PyType_GetFlags() result type is now +unsigned too (unsigned long, instead of long). + +.. + +.. bpo: 16166 +.. date: 8050 +.. nonce: PDTSqL +.. section: C API + +Add PY_LITTLE_ENDIAN and PY_BIG_ENDIAN macros and unified endianness +detection and handling. + +.. + +.. bpo: 17701 +.. date: 8049 +.. nonce: FtTZ66 +.. section: Documentation + +Improving strftime documentation. + +.. + +.. bpo: 18440 +.. date: 8048 +.. nonce: LyvSOC +.. section: Documentation + +Clarify that `hash()` can truncate the value returned from an object's +custom `__hash__()` method. + +.. + +.. bpo: 17844 +.. date: 8047 +.. nonce: V3aWU6 +.. section: Documentation + +Add links to encoders and decoders for bytes-to-bytes codecs. + +.. + +.. bpo: 14097 +.. date: 8046 +.. nonce: xeOs59 +.. section: Documentation + +improve the "introduction" page of the tutorial. + +.. + +.. bpo: 17977 +.. date: 8045 +.. nonce: 5f6eWJ +.. section: Documentation + +The documentation for the cadefault argument's default value in +urllib.request.urlopen() is fixed to match the code. + +.. + +.. bpo: 6696 +.. date: 8044 +.. nonce: -aRVrf +.. section: Documentation + +add documentation for the Profile objects, and improve profile/cProfile +docs. Patch by Tom Pinckney. + +.. + +.. bpo: 15940 +.. date: 8043 +.. nonce: XL62xu +.. section: Documentation + +Specify effect of locale on time functions. + +.. + +.. bpo: 17538 +.. date: 8042 +.. nonce: M8FVLz +.. section: Documentation + +Document XML vulnerabilties + +.. + +.. bpo: 16642 +.. date: 8041 +.. nonce: Cee7KE +.. section: Documentation + +sched.scheduler timefunc initial default is time.monotonic. Patch by +Ramchandra Apte + +.. + +.. bpo: 17047 +.. date: 8040 +.. nonce: sVzpby +.. section: Documentation + +remove doubled words in docs and docstrings reported by Serhiy Storchaka and +Matthew Barnett. + +.. + +.. bpo: 15465 +.. date: 8039 +.. nonce: yN2tkV +.. section: Documentation + +Document the versioning macros in the C API docs rather than the standard +library docs. Patch by Kushal Das. + +.. + +.. bpo: 16406 +.. date: 8038 +.. nonce: Q6DEK3 +.. section: Documentation + +Combine the pages for uploading and registering to PyPI. + +.. + +.. bpo: 16403 +.. date: 8037 +.. nonce: wPuYgA +.. section: Documentation + +Document how distutils uses the maintainer field in PKG-INFO. Patch by Jyrki +Pulliainen. + +.. + +.. bpo: 16695 +.. date: 8036 +.. nonce: O3-q4k +.. section: Documentation + +Document how glob handles filenames starting with a dot. Initial patch by +Jyrki Pulliainen. + +.. + +.. bpo: 8890 +.. date: 8035 +.. nonce: ldKgWT +.. section: Documentation + +Stop advertising an insecure practice by replacing uses of the /tmp +directory with better alternatives in the documentation. Patch by Geoff +Wilson. + +.. + +.. bpo: 17203 +.. date: 8034 +.. nonce: b42JWx +.. section: Documentation + +add long option names to unittest discovery docs. + +.. + +.. bpo: 13094 +.. date: 8033 +.. nonce: ujdNxz +.. section: Documentation + +add "Why do lambdas defined in a loop with different values all return the +same result?" programming FAQ. + +.. + +.. bpo: 14901 +.. date: 8032 +.. nonce: o_thZo +.. section: Documentation + +Update portions of the Windows FAQ. Patch by Ashish Nitin Patil. + +.. + +.. bpo: 16267 +.. date: 8031 +.. nonce: SSKvue +.. section: Documentation + +Better document the 3.3+ approach to combining @abstractmethod with +@staticmethod, @classmethod and @property + +.. + +.. bpo: 15209 +.. date: 8030 +.. nonce: w1UuQK +.. section: Documentation + +Clarify exception chaining description in exceptions module documentation + +.. + +.. bpo: 15990 +.. date: 8029 +.. nonce: 41C5_M +.. section: Documentation + +Improve argument/parameter documentation. + +.. + +.. bpo: 16209 +.. date: 8028 +.. nonce: 8-hM8N +.. section: Documentation + +Move the documentation for the str built-in function to a new str class +entry in the "Text Sequence Type" section. + +.. + +.. bpo: 13538 +.. date: 8027 +.. nonce: 6bfAto +.. section: Documentation + +Improve str() and object.__str__() documentation. + +.. + +.. bpo: 16489 +.. date: 8026 +.. nonce: N4Xo3- +.. section: Documentation + +Make it clearer that importlib.find_loader() needs parent packages to be +explicitly imported. + +.. + +.. bpo: 16400 +.. date: 8025 +.. nonce: kDLZRV +.. section: Documentation + +Update the description of which versions of a given package PyPI displays. + +.. + +.. bpo: 15677 +.. date: 8024 +.. nonce: _0vY-h +.. section: Documentation + +Document that zlib and gzip accept a compression level of 0 to mean 'no +compression'. Patch by Brian Brazil. + +.. + +.. bpo: 16197 +.. date: 8023 +.. nonce: LT1sjI +.. section: Documentation + +Update winreg docstrings and documentation to match code. Patch by Zachary +Ware. + +.. + +.. bpo: 8040 +.. date: 8022 +.. nonce: R8VAys +.. section: Documentation + +added a version switcher to the documentation. Patch by Yury Selivanov. + +.. + +.. bpo: 16241 +.. date: 8021 +.. nonce: LfdE7f +.. section: Documentation + +Document -X faulthandler command line option. Patch by Marek Šuppa. + +.. + +.. bpo: 0 +.. date: 8020 +.. nonce: tWKgrg +.. section: Documentation + +Additional comments and some style changes in the concurrent.futures URL +retrieval example + +.. + +.. bpo: 16115 +.. date: 8019 +.. nonce: Ba1MH_ +.. section: Documentation + +Improve subprocess.Popen() documentation around args, shell, and executable +arguments. + +.. + +.. bpo: 13498 +.. date: 8018 +.. nonce: LI0aQ4 +.. section: Documentation + +Clarify docs of os.makedirs()'s exist_ok argument. Done with great native- +speaker help from R. David Murray. + +.. + +.. bpo: 15533 +.. date: 8017 +.. nonce: oRcsqW +.. section: Documentation + +Clarify docs and add tests for `subprocess.Popen()`'s cwd argument. + +.. + +.. bpo: 15979 +.. date: 8016 +.. nonce: UATtRZ +.. section: Documentation + +Improve timeit documentation. + +.. + +.. bpo: 16036 +.. date: 8015 +.. nonce: ITDZx_ +.. section: Documentation + +Improve documentation of built-in `int()`'s signature and arguments. + +.. + +.. bpo: 15935 +.. date: 8014 +.. nonce: 49QYHM +.. section: Documentation + +Clarification of `argparse` docs, re: add_argument() type and default +arguments. Patch contributed by Chris Jerdonek. + +.. + +.. bpo: 11964 +.. date: 8013 +.. nonce: TswBww +.. section: Documentation + +Document a change in v3.2 to the behavior of the indent parameter of json +encoding operations. + +.. + +.. bpo: 15116 +.. date: 8012 +.. nonce: uDQI_8 +.. section: Documentation + +Remove references to appscript as it is no longer being supported. + +.. + +.. bpo: 18817 +.. date: 8011 +.. nonce: b4b2nk +.. section: Tools/Demos + +Fix a resource warning in Lib/aifc.py demo. Patch by Vajrasky Kok. + +.. + +.. bpo: 18439 +.. date: 8010 +.. nonce: W9DxeL +.. section: Tools/Demos + +Make patchcheck work on Windows for ACKS, NEWS. + +.. + +.. bpo: 18448 +.. date: 8009 +.. nonce: eLT81k +.. section: Tools/Demos + +Fix a typo in Tools/demo/eiffel.py. + +.. + +.. bpo: 18457 +.. date: 8008 +.. nonce: fTGIAR +.. section: Tools/Demos + +Fixed saving of formulas and complex numbers in Tools/demo/ss1.py. + +.. + +.. bpo: 18449 +.. date: 8007 +.. nonce: ufcaWC +.. section: Tools/Demos + +Make Tools/demo/ss1.py work again on Python 3. Patch by Févry Thibault. + +.. + +.. bpo: 12990 +.. date: 8006 +.. nonce: E1geL- +.. section: Tools/Demos + +The "Python Launcher" on OSX could not launch python scripts that have paths +that include wide characters. + +.. + +.. bpo: 15239 +.. date: 8005 +.. nonce: uzPBlK +.. section: Tools/Demos + +Make mkstringprep.py work again on Python 3. + +.. + +.. bpo: 17028 +.. date: 8004 +.. nonce: d0Ryfg +.. section: Tools/Demos + +Allowed Python arguments to be supplied to the Windows launcher. + +.. + +.. bpo: 17156 +.. date: 8003 +.. nonce: zmokst +.. section: Tools/Demos + +pygettext.py now detects the encoding of source files and correctly writes +and escapes non-ascii characters. + +.. + +.. bpo: 15539 +.. date: 8002 +.. nonce: 6bqqV- +.. section: Tools/Demos + +Fix a number of bugs in Tools/scripts/pindent.py. Now pindent.py works with +a "with" statement. pindent.py no longer produces improper indentation. +pindent.py now works with continued lines broken after "class" or "def" +keywords and with continuations at the start of line. + +.. + +.. bpo: 11797 +.. date: 8001 +.. nonce: 2UOmWr +.. section: Tools/Demos + +Add a 2to3 fixer that maps reload() to imp.reload(). + +.. + +.. bpo: 10966 +.. date: 8000 +.. nonce: WsfpDc +.. section: Tools/Demos + +Remove the concept of unexpected skipped tests. + +.. + +.. bpo: 9893 +.. date: 7999 +.. nonce: pJeYiB +.. section: Tools/Demos + +Removed the Misc/Vim directory. + +.. + +.. bpo: 0 +.. date: 7998 +.. nonce: mdt8FR +.. section: Tools/Demos + +Removed the Misc/TextMate directory. + +.. + +.. bpo: 16245 +.. date: 7997 +.. nonce: eZNpI- +.. section: Tools/Demos + +Add the Tools/scripts/parse_html5_entities.py script to parse the list of +HTML5 entities and update the html.entities.html5 dictionary. + +.. + +.. bpo: 15378 +.. date: 7996 +.. nonce: IO1T92 +.. section: Tools/Demos + +Fix Tools/unicode/comparecodecs.py. Patch by Serhiy Storchaka. + +.. + +.. bpo: 16549 +.. date: 7995 +.. nonce: 2Pj5iC +.. section: Tools/Demos + +Make json.tool work again on Python 3 and add tests. Initial patch by Berker +Peksag and Serhiy Storchaka. + +.. + +.. bpo: 13301 +.. date: 7994 +.. nonce: A4WOk5 +.. section: Tools/Demos + +use ast.literal_eval() instead of eval() in Tools/i18n/msgfmt.py. Patch by +Serhiy Storchaka. + +.. + +.. bpo: 18569 +.. date: 7993 +.. nonce: 0L-xR0 +.. section: Windows + +The installer now adds .py to the PATHEXT variable when extensions are +registered. Patch by Paul Moore. diff --git a/Misc/NEWS.d/3.4.0a2.rst b/Misc/NEWS.d/3.4.0a2.rst new file mode 100644 index 00000000000000..782283506c98e4 --- /dev/null +++ b/Misc/NEWS.d/3.4.0a2.rst @@ -0,0 +1,788 @@ +.. bpo: 18942 +.. date: 8814 +.. nonce: xpMQx7 +.. release date: 2013-09-09 +.. section: Core and Builtins + +sys._debugmallocstats() output was damaged on Windows. + +.. + +.. bpo: 18571 +.. date: 8813 +.. nonce: hvNoE2 +.. section: Core and Builtins + +Implementation of the PEP 446: file descriptors and file handles are now +created non-inheritable; add functions os.get/set_inheritable(), +os.get/set_handle_inheritable() and socket.socket.get/set_inheritable(). + +.. + +.. bpo: 11619 +.. date: 8812 +.. nonce: r2uijI +.. section: Core and Builtins + +The parser and the import machinery do not encode Unicode filenames anymore +on Windows. + +.. + +.. bpo: 18808 +.. date: 8811 +.. nonce: DicDIV +.. section: Core and Builtins + +Non-daemon threads are now automatically joined when a sub-interpreter is +shutdown (it would previously dump a fatal error). + +.. + +.. bpo: 0 +.. date: 8810 +.. nonce: FDR7CW +.. section: Core and Builtins + +Remove support for compiling on systems without getcwd(). + +.. + +.. bpo: 18774 +.. date: 8809 +.. nonce: 4hnKQ1 +.. section: Core and Builtins + +Remove last bits of GNU PTH thread code and thread_pth.h. + +.. + +.. bpo: 18771 +.. date: 8808 +.. nonce: gPhE3D +.. section: Core and Builtins + +Add optimization to set object lookups to reduce the cost of hash +collisions. The core idea is to inspect a second key/hash pair for each +cache line retrieved. + +.. + +.. bpo: 16105 +.. date: 8807 +.. nonce: L1PWWk +.. section: Core and Builtins + +When a signal handler fails to write to the file descriptor registered with +``signal.set_wakeup_fd()``, report an exception instead of ignoring the +error. + +.. + +.. bpo: 18722 +.. date: 8806 +.. nonce: 6O_dyg +.. section: Core and Builtins + +Remove uses of the "register" keyword in C code. + +.. + +.. bpo: 18667 +.. date: 8805 +.. nonce: xycqzn +.. section: Core and Builtins + +Add missing "HAVE_FCHOWNAT" symbol to posix._have_functions. + +.. + +.. bpo: 16499 +.. date: 8804 +.. nonce: BoV9L7 +.. section: Core and Builtins + +Add command line option for isolated mode. + +.. + +.. bpo: 15301 +.. date: 8803 +.. nonce: rov_YS +.. section: Core and Builtins + +Parsing fd, uid, and gid parameters for builtins in Modules/posixmodule.c is +now far more robust. + +.. + +.. bpo: 18368 +.. date: 8802 +.. nonce: eZ-IVt +.. section: Core and Builtins + +PyOS_StdioReadline() no longer leaks memory when realloc() fail. + +.. + +.. bpo: 17934 +.. date: 8801 +.. nonce: R2hCWw +.. section: Core and Builtins + +Add a clear() method to frame objects, to help clean up expensive details +(local variables) and break reference cycles. + +.. + +.. bpo: 18780 +.. date: 8800 +.. nonce: cRO6Nc +.. section: Core and Builtins + +%-formatting codes %d, %i, and %u now treat int-subclasses as int (displays +value of int-subclass instead of str(int-subclass) ). + +.. + +.. bpo: 18808 +.. date: 8799 +.. nonce: rKe4pf +.. section: Library + +Thread.join() now waits for the underlying thread state to be destroyed +before returning. This prevents unpredictable aborts in Py_EndInterpreter() +when some non-daemon threads are still running. + +.. + +.. bpo: 18458 +.. date: 8798 +.. nonce: XphzAu +.. section: Library + +Prevent crashes with newer versions of libedit. Its readline emulation has +changed from 0-based indexing to 1-based like gnu readline. + +.. + +.. bpo: 18852 +.. date: 8797 +.. nonce: x1dLH9 +.. section: Library + +Handle case of ``readline.__doc__`` being ``None`` in the new readline +activation code in ``site.py``. + +.. + +.. bpo: 18672 +.. date: 8796 +.. nonce: CIblDh +.. section: Library + +Fixed format specifiers for Py_ssize_t in debugging output in the _sre +module. + +.. + +.. bpo: 18830 +.. date: 8795 +.. nonce: 1kmGPa +.. section: Library + +inspect.getclasstree() no longer produces duplicate entries even when input +list contains duplicates. + +.. + +.. bpo: 18878 +.. date: 8794 +.. nonce: VuQM8h +.. section: Library + +sunau.open now supports the context management protocol. Based on patches +by Claudiu Popa and R. David Murray. + +.. + +.. bpo: 18909 +.. date: 8793 +.. nonce: XSu98N +.. section: Library + +Fix _tkinter.tkapp.interpaddr() on Windows 64-bit, don't cast 64-bit pointer +to long (32 bits). + +.. + +.. bpo: 18876 +.. date: 8792 +.. nonce: 30Ist9 +.. section: Library + +The FileIO.mode attribute now better reflects the actual mode under which +the file was opened. Patch by Erik Bray. + +.. + +.. bpo: 16853 +.. date: 8791 +.. nonce: HyyMyr +.. section: Library + +Add new selectors module. + +.. + +.. bpo: 18882 +.. date: 8790 +.. nonce: Z9cjmU +.. section: Library + +Add threading.main_thread() function. + +.. + +.. bpo: 18901 +.. date: 8789 +.. nonce: CRT02s +.. section: Library + +The sunau getparams method now returns a namedtuple rather than a plain +tuple. Patch by Claudiu Popa. + +.. + +.. bpo: 17487 +.. date: 8788 +.. nonce: EziBDf +.. section: Library + +The result of the wave getparams method now is pickleable again. Patch by +Claudiu Popa. + +.. + +.. bpo: 18756 +.. date: 8787 +.. nonce: DS8ILK +.. section: Library + +os.urandom() now uses a lazily-opened persistent file descriptor, so as to +avoid using many file descriptors when run in parallel from multiple +threads. + +.. + +.. bpo: 18418 +.. date: 8786 +.. nonce: _SFG8w +.. section: Library + +After fork(), reinit all threads states, not only active ones. Patch by A. +Jesse Jiryu Davis. + +.. + +.. bpo: 17974 +.. date: 8785 +.. nonce: mo7MP0 +.. section: Library + +Switch unittest from using getopt to using argparse. + +.. + +.. bpo: 11798 +.. date: 8784 +.. nonce: 0AnJcy +.. section: Library + +TestSuite now drops references to own tests after execution. + +.. + +.. bpo: 16611 +.. date: 8783 +.. nonce: aHrYR1 +.. section: Library + +http.cookie now correctly parses the 'secure' and 'httponly' cookie flags. + +.. + +.. bpo: 11973 +.. date: 8782 +.. nonce: uPtBvG +.. section: Library + +Fix a problem in kevent. The flags and fflags fields are now properly +handled as unsigned. + +.. + +.. bpo: 18807 +.. date: 8781 +.. nonce: TnD-vF +.. section: Library + +``pyvenv`` now takes a --copies argument allowing copies instead of symlinks +even where symlinks are available and the default. + +.. + +.. bpo: 18538 +.. date: 8780 +.. nonce: wuWw4M +.. section: Library + +``python -m dis`` now uses argparse for argument processing. Patch by +Michele Orrù. + +.. + +.. bpo: 18394 +.. date: 8779 +.. nonce: 6pOClT +.. section: Library + +Close cgi.FieldStorage's optional file. + +.. + +.. bpo: 17702 +.. date: 8778 +.. nonce: TDPIyM +.. section: Library + +On error, os.environb now suppresses the exception context when raising a +new KeyError with the original key. + +.. + +.. bpo: 16809 +.. date: 8777 +.. nonce: NrXQBx +.. section: Library + +Fixed some tkinter incompabilities with Tcl/Tk 8.6. + +.. + +.. bpo: 16809 +.. date: 8776 +.. nonce: WqSHdP +.. section: Library + +Tkinter's splitlist() and split() methods now accept Tcl_Obj argument. + +.. + +.. bpo: 18324 +.. date: 8775 +.. nonce: 0vkj_r +.. section: Library + +set_payload now correctly handles binary input. This also supersedes the +previous fixes for #14360, #1717, and #16564. + +.. + +.. bpo: 18794 +.. date: 8774 +.. nonce: A0pB9X +.. section: Library + +Add a fileno() method and a closed attribute to select.devpoll objects. + +.. + +.. bpo: 17119 +.. date: 8773 +.. nonce: KfZ3-l +.. section: Library + +Fixed integer overflows when processing large strings and tuples in the +tkinter module. + +.. + +.. bpo: 18747 +.. date: 8772 +.. nonce: tPZkbG +.. section: Library + +Re-seed OpenSSL's pseudo-random number generator after fork. A +pthread_atfork() parent handler is used to seed the PRNG with pid, time and +some stack data. + +.. + +.. bpo: 8865 +.. date: 8771 +.. nonce: cKBSJh +.. section: Library + +Concurrent invocation of select.poll.poll() now raises a RuntimeError +exception. Patch by Christian Schubert. + +.. + +.. bpo: 18777 +.. date: 8770 +.. nonce: VLsjOw +.. section: Library + +The ssl module now uses the new CRYPTO_THREADID API of OpenSSL 1.0.0+ +instead of the deprecated CRYPTO id callback function. + +.. + +.. bpo: 18768 +.. date: 8769 +.. nonce: r3TSCo +.. section: Library + +Correct doc string of RAND_edg(). Patch by Vajrasky Kok. + +.. + +.. bpo: 18178 +.. date: 8768 +.. nonce: i4hnf- +.. section: Library + +Fix ctypes on BSD. dlmalloc.c was compiled twice which broke malloc weak +symbols. + +.. + +.. bpo: 18709 +.. date: 8767 +.. nonce: txXrAc +.. section: Library + +Fix CVE-2013-4238. The SSL module now handles NULL bytes inside +subjectAltName correctly. Formerly the module has used OpenSSL's +GENERAL_NAME_print() function to get the string represention of ASN.1 +strings for ``rfc822Name`` (email), ``dNSName`` (DNS) and +``uniformResourceIdentifier`` (URI). + +.. + +.. bpo: 18701 +.. date: 8766 +.. nonce: nlDK3r +.. section: Library + +Remove support of old CPython versions (<3.0) from C code. + +.. + +.. bpo: 18756 +.. date: 8765 +.. nonce: moRUfX +.. section: Library + +Improve error reporting in os.urandom() when the failure is due to something +else than /dev/urandom not existing (for example, exhausting the file +descriptor limit). + +.. + +.. bpo: 18673 +.. date: 8764 +.. nonce: fZ5WYI +.. section: Library + +Add O_TMPFILE to os module. O_TMPFILE requires Linux kernel 3.11 or newer. +It's only defined on system with 3.11 uapi headers, too. + +.. + +.. bpo: 18532 +.. date: 8763 +.. nonce: 2hh1ms +.. section: Library + +Change the builtin hash algorithms' names to lower case names as promised by +hashlib's documentation. + +.. + +.. bpo: 8713 +.. date: 8762 +.. nonce: BFXgYS +.. section: Library + +add new spwan and forkserver start methods, and new functions +get_all_start_methods, get_start_method, and set_start_method, to +multiprocessing. + +.. + +.. bpo: 18405 +.. date: 8761 +.. nonce: z6flbp +.. section: Library + +Improve the entropy of crypt.mksalt(). + +.. + +.. bpo: 12015 +.. date: 8760 +.. nonce: wImE9r +.. section: Library + +The tempfile module now uses a suffix of 8 random characters instead of 6, +to reduce the risk of filename collision. The entropy was reduced when +uppercase letters were removed from the charset used to generate random +characters. + +.. + +.. bpo: 18585 +.. date: 8759 +.. nonce: fooJpB +.. section: Library + +Add :func:`textwrap.shorten` to collapse and truncate a piece of text to a +given length. + +.. + +.. bpo: 18598 +.. date: 8758 +.. nonce: KRZlim +.. section: Library + +Tweak exception message for importlib.import_module() to include the module +name when a key argument is missing. + +.. + +.. bpo: 19151 +.. date: 8757 +.. nonce: 2MrIlH +.. section: Library + +Fix docstring and use of _get_supported_file_loaders() to reflect 2-tuples. + +.. + +.. bpo: 19152 +.. date: 8756 +.. nonce: 2VYxzU +.. section: Library + +Add ExtensionFileLoader.get_filename(). + +.. + +.. bpo: 18676 +.. date: 8755 +.. nonce: WAq1iB +.. section: Library + +Change 'positive' to 'non-negative' in queue.py put and get docstrings and +ValueError messages. Patch by Zhongyue Luo + +.. + +.. bpo: 0 +.. date: 8754 +.. nonce: Q7tLxE +.. section: Library + +Fix refcounting issue with extension types in tkinter. + +.. + +.. bpo: 8112 +.. date: 8753 +.. nonce: J4M-dG +.. section: Library + +xlmrpc.server's DocXMLRPCServer server no longer raises an error if methods +have annotations; it now correctly displays the annotations. + +.. + +.. bpo: 18600 +.. date: 8752 +.. nonce: lnNy-j +.. section: Library + +Added policy argument to email.message.Message.as_string, and as_bytes and +__bytes__ methods to Message. + +.. + +.. bpo: 18671 +.. date: 8751 +.. nonce: ip02-u +.. section: Library + +Output more information when logging exceptions occur. + +.. + +.. bpo: 18621 +.. date: 8750 +.. nonce: uGY0Dw +.. section: Library + +Prevent the site module's patched builtins from keeping too many references +alive for too long. + +.. + +.. bpo: 4885 +.. date: 8749 +.. nonce: tdRzg0 +.. section: Library + +Add weakref support to mmap objects. Patch by Valerie Lambert. + +.. + +.. bpo: 8860 +.. date: 8748 +.. nonce: g3CWcZ +.. section: Library + +Fixed rounding in timedelta constructor. + +.. + +.. bpo: 18849 +.. date: 8747 +.. nonce: Q0kF0R +.. section: Library + +Fixed a Windows-specific tempfile bug where collision with an existing +directory caused mkstemp and related APIs to fail instead of retrying. +Report and fix by Vlad Shcherbina. + +.. + +.. bpo: 18920 +.. date: 8746 +.. nonce: ymifXY +.. section: Library + +argparse's default destination for the version action (-v, --version) has +also been changed to stdout, to match the Python executable. + +.. + +.. bpo: 18623 +.. date: 8745 +.. nonce: ac3L1h +.. section: Tests + +Factor out the _SuppressCoreFiles context manager into test.support. Patch +by Valerie Lambert. + +.. + +.. bpo: 12037 +.. date: 8744 +.. nonce: pcCgBV +.. section: Tests + +Fix test_email for desktop Windows. + +.. + +.. bpo: 15507 +.. date: 8743 +.. nonce: 3_em_8 +.. section: Tests + +test_subprocess's test_send_signal could fail if the test runner were run in +an environment where the process inherited an ignore setting for SIGINT. +Restore the SIGINT handler to the desired KeyboardInterrupt raising one +during that test. + +.. + +.. bpo: 16799 +.. date: 8742 +.. nonce: Z_fDrt +.. section: Tests + +Switched from getopt to argparse style in regrtest's argument parsing. +Added more tests for regrtest's argument parsing. + +.. + +.. bpo: 18792 +.. date: 8741 +.. nonce: 5RkYdK +.. section: Tests + +Use "127.0.0.1" or "::1" instead of "localhost" as much as possible, since +"localhost" goes through a DNS lookup under recent Windows versions. + +.. + +.. bpo: 18489 +.. date: 8740 +.. nonce: nOvxOH +.. section: IDLE + +Add tests for SearchEngine. Original patch by Phil Webster. + +.. + +.. bpo: 18743 +.. date: 8739 +.. nonce: PXRtAK +.. section: Documentation + +Fix references to non-existant "StringIO" module. + +.. + +.. bpo: 18783 +.. date: 8738 +.. nonce: n5K5vI +.. section: Documentation + +Removed existing mentions of Python long type in docstrings, error messages +and comments. + +.. + +.. bpo: 1584 +.. date: 8737 +.. nonce: Lh1ZOs +.. section: Build + +Provide configure options to override default search paths for Tcl and Tk +when building _tkinter. + +.. + +.. bpo: 15663 +.. date: 8736 +.. nonce: VJKYGf +.. section: Build + +Tcl/Tk 8.5.14 is now included with the OS X 10.6+ 64-/32-bit installer. It +is no longer necessary to install a third-party version of Tcl/Tk 8.5 to +work around the problems in the Apple-supplied Tcl/Tk 8.5 shipped in OS X +10.6 and later releases. + +.. + +.. bpo: 18922 +.. date: 8735 +.. nonce: xCUCW0 +.. section: Tools/Demos + +Now The Lib/smtpd.py and Tools/i18n/msgfmt.py scripts write their version +strings to stdout, and not to sderr. diff --git a/Misc/NEWS.d/3.4.0a3.rst b/Misc/NEWS.d/3.4.0a3.rst new file mode 100644 index 00000000000000..2f5b9667c6f104 --- /dev/null +++ b/Misc/NEWS.d/3.4.0a3.rst @@ -0,0 +1,283 @@ +.. bpo: 18818 +.. date: 8842 +.. nonce: fsZ51D +.. release date: 2013-09-29 +.. section: Core and Builtins + +The "encodingname" part of PYTHONIOENCODING is now optional. + +.. + +.. bpo: 19098 +.. date: 8841 +.. nonce: 5XU9uv +.. section: Core and Builtins + +Prevent overflow in the compiler when the recursion limit is set absurdly +high. + +.. + +.. bpo: 18929 +.. date: 8840 +.. nonce: xt9_At +.. section: Library + +`inspect.classify_class_attrs()` now correctly finds class attributes +returned by `dir()` that are located in the metaclass. + +.. + +.. bpo: 18950 +.. date: 8839 +.. nonce: DHn3qf +.. section: Library + +Fix miscellaneous bugs in the sunau module. Au_read.readframes() now updates +current file position and reads correct number of frames from multichannel +stream. Au_write.writeframesraw() now correctly updates current file +position. Au_read.getnframes() now returns an integer (as in Python 2). +Au_read and Au_write now correctly works with file object if start file +position is not a zero. + +.. + +.. bpo: 18594 +.. date: 8838 +.. nonce: Dm34qD +.. section: Library + +The fast path for collections.Counter() was never taken due to an over- +restrictive type check. + +.. + +.. bpo: 19053 +.. date: 8837 +.. nonce: DkcFZ8 +.. section: Library + +ZipExtFile.read1() with non-zero argument no more returns empty bytes until +end of data. + +.. + +.. bpo: 0 +.. date: 8836 +.. nonce: x-7joT +.. section: Library + +logging: added support for Unix domain sockets to SocketHandler and +DatagramHandler. + +.. + +.. bpo: 18996 +.. date: 8835 +.. nonce: 1Waotx +.. section: Library + +TestCase.assertEqual() now more cleverly shorten differing strings in error +report. + +.. + +.. bpo: 19034 +.. date: 8834 +.. nonce: S5MyMF +.. section: Library + +repr() for tkinter.Tcl_Obj now exposes string reperesentation. + +.. + +.. bpo: 18978 +.. date: 8833 +.. nonce: qyLkAY +.. section: Library + +``urllib.request.Request`` now allows the method to be indicated on the +class and no longer sets it to None in ``__init__``. + +.. + +.. bpo: 18626 +.. date: 8832 +.. nonce: X3HiU3 +.. section: Library + +the inspect module now offers a basic command line introspection interface +(Initial patch by Claudiu Popa) + +.. + +.. bpo: 3015 +.. date: 8831 +.. nonce: Db5Zwa +.. section: Library + +Fixed tkinter with wantobject=False. Any Tcl command call returned empty +string. + +.. + +.. bpo: 19037 +.. date: 8830 +.. nonce: OfBhoU +.. section: Library + +The mailbox module now makes all changes to maildir files before moving them +into place, to avoid race conditions with other programs that may be +accessing the maildir directory. + +.. + +.. bpo: 14984 +.. date: 8829 +.. nonce: iRbFp4 +.. section: Library + +On POSIX systems, when netrc is called without a filename argument (and +therefore is reading the user's $HOME/.netrc file), it now enforces the same +security rules as typical ftp clients: the .netrc file must be owned by the +user that owns the process and must not be readable by any other user. + +.. + +.. bpo: 18873 +.. date: 8828 +.. nonce: 3ezwXm +.. section: Library + +The tokenize module now detects Python source code encoding only in comment +lines. + +.. + +.. bpo: 17764 +.. date: 8827 +.. nonce: czuuKO +.. section: Library + +Enable http.server to bind to a user specified network interface. Patch +contributed by Malte Swart. + +.. + +.. bpo: 18937 +.. date: 8826 +.. nonce: bcvKgi +.. section: Library + +Add an assertLogs() context manager to unittest.TestCase to ensure that a +block of code emits a message using the logging module. + +.. + +.. bpo: 17324 +.. date: 8825 +.. nonce: 0PkOTi +.. section: Library + +Fix http.server's request handling case on trailing '/'. Patch contributed +by Vajrasky Kok. + +.. + +.. bpo: 19018 +.. date: 8824 +.. nonce: mntKOW +.. section: Library + +The heapq.merge() function no longer suppresses IndexError in the underlying +iterables. + +.. + +.. bpo: 18784 +.. date: 8823 +.. nonce: dtzGbX +.. section: Library + +The uuid module no longer attempts to load libc via ctypes.CDLL if all the +necessary functions have already been found in libuuid. Patch by Evgeny +Sologubov. + +.. + +.. bpo: 0 +.. date: 8822 +.. nonce: 22MCfN +.. section: Library + +The :envvar:`PYTHONFAULTHANDLER` environment variable now only enables the +faulthandler module if the variable is non-empty. Same behaviour than other +variables like :envvar:`PYTHONDONTWRITEBYTECODE`. + +.. + +.. bpo: 1565525 +.. date: 8821 +.. nonce: 0rVMB7 +.. section: Library + +New function ``traceback.clear_frames`` will clear the local variables of +all the stack frames referenced by a traceback object. + +.. + +.. bpo: 18952 +.. date: 8820 +.. nonce: ysovuf +.. section: Tests + +Fix regression in support data downloads introduced when test.support was +converted to a package. Regression noticed by Zachary Ware. + +.. + +.. bpo: 18873 +.. date: 8819 +.. nonce: dyLPY9 +.. section: IDLE + +IDLE now detects Python source code encoding only in comment lines. + +.. + +.. bpo: 18988 +.. date: 8818 +.. nonce: 6CpesW +.. section: IDLE + +The "Tab" key now works when a word is already autocompleted. + +.. + +.. bpo: 17003 +.. date: 8817 +.. nonce: eQGdny +.. section: Documentation + +Unified the size argument names in the io module with common practice. + +.. + +.. bpo: 18596 +.. date: 8816 +.. nonce: TMPNJZ +.. section: Build + +Support the use of address sanity checking in recent versions of clang and +GCC by appropriately marking known false alarms in the small object +allocator. Patch contributed by Dhiru Kholia. + +.. + +.. bpo: 18873 +.. date: 8815 +.. nonce: i_1Tf_ +.. section: Tools/Demos + +2to3 and the findnocoding.py script now detect Python source code encoding +only in comment lines. diff --git a/Misc/NEWS.d/3.4.0a4.rst b/Misc/NEWS.d/3.4.0a4.rst new file mode 100644 index 00000000000000..586d3e676f9628 --- /dev/null +++ b/Misc/NEWS.d/3.4.0a4.rst @@ -0,0 +1,659 @@ +.. bpo: 19301 +.. date: 8909 +.. nonce: xZv71d +.. release date: 2013-10-20 +.. section: Core and Builtins + +Give classes and functions that are explicitly marked global a global +qualname. + +.. + +.. bpo: 19279 +.. date: 8908 +.. nonce: VVzqJy +.. section: Core and Builtins + +UTF-7 decoder no longer produces illegal strings. + +.. + +.. bpo: 16612 +.. date: 8907 +.. nonce: 8bgX-E +.. section: Core and Builtins + +Add "Argument Clinic", a compile-time preprocessor for C files to generate +argument parsing code. (See PEP 436.) + +.. + +.. bpo: 18810 +.. date: 8906 +.. nonce: tQAzk_ +.. section: Core and Builtins + +Shift stat calls in importlib.machinery.FileFinder such that the code is +optimistic that if something exists in a directory named exactly like the +possible package being searched for that it's in actuality a directory. + +.. + +.. bpo: 18416 +.. date: 8905 +.. nonce: 5mWnIr +.. section: Core and Builtins + +importlib.machinery.PathFinder now treats '' as the cwd and +importlib.machinery.FileFinder no longer special-cases '' to '.'. This leads +to modules imported from cwd to now possess an absolute file path for +__file__ (this does not affect modules specified by path on the CLI but it +does affect -m/runpy). It also allows FileFinder to be more consistent by +not having an edge case. + +.. + +.. bpo: 4555 +.. date: 8904 +.. nonce: mOxiRO +.. section: Core and Builtins + +All exported C symbols are now prefixed with either "Py" or "_Py". + +.. + +.. bpo: 19219 +.. date: 8903 +.. nonce: _H8xTK +.. section: Core and Builtins + +Speed up marshal.loads(), and make pyc files slightly (5% to 10%) smaller. + +.. + +.. bpo: 19221 +.. date: 8902 +.. nonce: Y7d-d9 +.. section: Core and Builtins + +Upgrade Unicode database to version 6.3.0. + +.. + +.. bpo: 16742 +.. date: 8901 +.. nonce: vmmba7 +.. section: Core and Builtins + +The result of the C callback PyOS_ReadlineFunctionPointer must now be a +string allocated by PyMem_RawMalloc() or PyMem_RawRealloc() (or NULL if an +error occurred), instead of a string allocated by PyMem_Malloc() or +PyMem_Realloc(). + +.. + +.. bpo: 19199 +.. date: 8900 +.. nonce: HZHjaz +.. section: Core and Builtins + +Remove ``PyThreadState.tick_counter`` field + +.. + +.. bpo: 0 +.. date: 8899 +.. nonce: 5kIB0G +.. section: Core and Builtins + +Fix macro expansion of _PyErr_OCCURRED(), and make sure to use it in at +least one place so as to avoid regressions. + +.. + +.. bpo: 19087 +.. date: 8898 +.. nonce: gdUdnV +.. section: Core and Builtins + +Improve bytearray allocation in order to allow cheap popping of data at the +front (slice deletion). + +.. + +.. bpo: 19014 +.. date: 8897 +.. nonce: y4w-XY +.. section: Core and Builtins + +memoryview.cast() is now allowed on zero-length views. + +.. + +.. bpo: 18690 +.. date: 8896 +.. nonce: CS9avj +.. section: Core and Builtins + +memoryview is now automatically registered with collections.abc.Sequence + +.. + +.. bpo: 19078 +.. date: 8895 +.. nonce: PQhOCk +.. section: Core and Builtins + +memoryview now correctly supports the reversed builtin (Patch by Claudiu +Popa) + +.. + +.. bpo: 17457 +.. date: 8894 +.. nonce: TeaU1w +.. section: Library + +unittest test discovery now works with namespace packages. Patch by Claudiu +Popa. + +.. + +.. bpo: 18235 +.. date: 8893 +.. nonce: LdBO1h +.. section: Library + +Fix the sysconfig variables LDSHARED and BLDSHARED under AIX. Patch by David +Edelsohn. + +.. + +.. bpo: 18606 +.. date: 8892 +.. nonce: CIapUf +.. section: Library + +Add the new "statistics" module (PEP 450). Contributed by Steven D'Aprano. + +.. + +.. bpo: 12866 +.. date: 8891 +.. nonce: 7c7GGc +.. section: Library + +The audioop module now supports 24-bit samples. + +.. + +.. bpo: 19254 +.. date: 8890 +.. nonce: hq_ejm +.. section: Library + +Provide an optimized Python implementation of pbkdf2_hmac. + +.. + +.. bpo: 19201 +.. date: 8889 +.. nonce: OY6_PP +.. section: Library + +Add "x" mode (exclusive creation) in opening file to bz2, gzip and lzma +modules. Patches by Tim Heaney and Vajrasky Kok. (See also: bpo-19222, +bpo-19223) + +.. + +.. bpo: 0 +.. date: 8888 +.. nonce: dSKPsn +.. section: Library + +Fix a reference count leak in _sre. + +.. + +.. bpo: 19262 +.. date: 8887 +.. nonce: fNsTCq +.. section: Library + +Initial check in of the 'asyncio' package (a.k.a. Tulip, a.k.a. PEP 3156). +There are no docs yet, and the PEP is slightly out of date with the code. +This module will have *provisional* status in Python 3.4. + +.. + +.. bpo: 19276 +.. date: 8886 +.. nonce: Y69Qmv +.. section: Library + +Fixed the wave module on 64-bit big-endian platforms. + +.. + +.. bpo: 19266 +.. date: 8885 +.. nonce: an8EiY +.. section: Library + +Rename the new-in-3.4 ``contextlib.ignore`` context manager to +``contextlib.suppress`` in order to be more consistent with existing +descriptions of that operation elsewhere in the language and standard +library documentation (Patch by Zero Piraeus). + +.. + +.. bpo: 18891 +.. date: 8884 +.. nonce: 4TroDn +.. section: Library + +Completed the new email package (provisional) API additions by adding new +classes EmailMessage, MIMEPart, and ContentManager. + +.. + +.. bpo: 18281 +.. date: 8883 +.. nonce: 1FnfEW +.. section: Library + +Unused stat constants removed from `tarfile`. + +.. + +.. bpo: 18999 +.. date: 8882 +.. nonce: -2OZju +.. section: Library + +Multiprocessing now supports 'contexts' with the same API as the module, but +bound to specified start methods. + +.. + +.. bpo: 18468 +.. date: 8881 +.. nonce: 8a1TVz +.. section: Library + +The re.split, re.findall, and re.sub functions and the group() and groups() +methods of match object now always return a string or a bytes object. + +.. + +.. bpo: 18725 +.. date: 8880 +.. nonce: zkMEqo +.. section: Library + +The textwrap module now supports truncating multiline text. + +.. + +.. bpo: 18776 +.. date: 8879 +.. nonce: Y-0SKr +.. section: Library + +atexit callbacks now display their full traceback when they raise an +exception. + +.. + +.. bpo: 17827 +.. date: 8878 +.. nonce: HJGFDL +.. section: Library + +Add the missing documentation for ``codecs.encode`` and ``codecs.decode``. + +.. + +.. bpo: 19218 +.. date: 8877 +.. nonce: Cd2omk +.. section: Library + +Rename collections.abc to _collections_abc in order to speed up interpreter +start. + +.. + +.. bpo: 18582 +.. date: 8876 +.. nonce: hn0YhD +.. section: Library + +Add 'pbkdf2_hmac' to the hashlib module. It implements PKCS#5 password-based +key derivation functions with HMAC as pseudorandom function. + +.. + +.. bpo: 19131 +.. date: 8875 +.. nonce: eZXzpr +.. section: Library + +The aifc module now correctly reads and writes sampwidth of compressed +streams. + +.. + +.. bpo: 19209 +.. date: 8874 +.. nonce: 3Hyd-- +.. section: Library + +Remove import of copyreg from the os module to speed up interpreter startup. +stat_result and statvfs_result are now hard-coded to reside in the os +module. + +.. + +.. bpo: 19205 +.. date: 8873 +.. nonce: yrFzJn +.. section: Library + +Don't import the 're' module in site and sysconfig module to speed up +interpreter start. + +.. + +.. bpo: 9548 +.. date: 8872 +.. nonce: nhTqHw +.. section: Library + +Add a minimal "_bootlocale" module that is imported by the _io module +instead of the full locale module. + +.. + +.. bpo: 18764 +.. date: 8871 +.. nonce: rbnhLA +.. section: Library + +Remove the 'print' alias for the PDB 'p' command so that it no longer +shadows the print function. + +.. + +.. bpo: 19158 +.. date: 8870 +.. nonce: GvkZuU +.. section: Library + +A rare race in BoundedSemaphore could allow .release() too often. + +.. + +.. bpo: 15805 +.. date: 8869 +.. nonce: F_Ubx0 +.. section: Library + +Add contextlib.redirect_stdout(). + +.. + +.. bpo: 18716 +.. date: 8868 +.. nonce: L9QcWX +.. section: Library + +Deprecate the formatter module. + +.. + +.. bpo: 10712 +.. date: 8867 +.. nonce: rnd0oc +.. section: Library + +2to3 has a new "asserts" fixer that replaces deprecated names of unittest +methods (e.g. failUnlessEqual -> assertEqual). + +.. + +.. bpo: 18037 +.. date: 8866 +.. nonce: 7XGs8m +.. section: Library + +2to3 now escapes ``'\u'`` and ``'\U'`` in native strings. + +.. + +.. bpo: 17839 +.. date: 8865 +.. nonce: EyWhFu +.. section: Library + +base64.decodebytes and base64.encodebytes now accept any object that exports +a 1 dimensional array of bytes (this means the same is now also true for +base64_codec) + +.. + +.. bpo: 19132 +.. date: 8864 +.. nonce: ADBW6c +.. section: Library + +The pprint module now supports compact mode. + +.. + +.. bpo: 19137 +.. date: 8863 +.. nonce: Iuit_M +.. section: Library + +The pprint module now correctly formats instances of set and frozenset +subclasses. + +.. + +.. bpo: 10042 +.. date: 8862 +.. nonce: AH33zP +.. section: Library + +functools.total_ordering now correctly handles NotImplemented being returned +by the underlying comparison function (Patch by Katie Miller) + +.. + +.. bpo: 19092 +.. date: 8861 +.. nonce: Z7dea9 +.. section: Library + +contextlib.ExitStack now correctly reraises exceptions from the __exit__ +callbacks of inner context managers (Patch by Hrvoje Nikšić) + +.. + +.. bpo: 12641 +.. date: 8860 +.. nonce: r9sIyX +.. section: Library + +Avoid passing "-mno-cygwin" to the mingw32 compiler, except when necessary. +Patch by Oscar Benjamin. + +.. + +.. bpo: 5845 +.. date: 8859 +.. nonce: obzVIH +.. section: Library + +In site.py, only load readline history from ~/.python_history if no history +has been read already. This avoids double writes to the history file at +shutdown. + +.. + +.. bpo: 0 +.. date: 8858 +.. nonce: 08TsG5 +.. section: Library + +Properly initialize all fields of a SSL object after allocation. + +.. + +.. bpo: 19095 +.. date: 8857 +.. nonce: qZGvAs +.. section: Library + +SSLSocket.getpeercert() now raises ValueError when the SSL handshake hasn't +been done. + +.. + +.. bpo: 4366 +.. date: 8856 +.. nonce: lDEdfK +.. section: Library + +Fix building extensions on all platforms when --enable-shared is used. + +.. + +.. bpo: 19030 +.. date: 8855 +.. nonce: uKvvJF +.. section: Library + +Fixed `inspect.getmembers` and `inspect.classify_class_attrs` to attempt +activating descriptors before falling back to a __dict__ search for faulty +descriptors. `inspect.classify_class_attrs` no longer returns Attributes +whose home class is None. + +.. + +.. bpo: 1772673 +.. date: 8854 +.. nonce: 5cdzx1 +.. section: C API + +The type of `char*` arguments now changed to `const char*`. + +.. + +.. bpo: 16129 +.. date: 8853 +.. nonce: 8zyucl +.. section: C API + +Added a `Py_SetStandardStreamEncoding` pre-initialization API to allow +embedding applications like Blender to force a particular encoding and error +handler for the standard IO streams (initial patch by Bastien Montagne) + +.. + +.. bpo: 19275 +.. date: 8852 +.. nonce: uboiiw +.. section: Tests + +Fix test_site on AMD64 Snow Leopard + +.. + +.. bpo: 14407 +.. date: 8851 +.. nonce: -tmRl9 +.. section: Tests + +Fix unittest test discovery in test_concurrent_futures. + +.. + +.. bpo: 18919 +.. date: 8850 +.. nonce: cEkIuG +.. section: Tests + +Unified and extended tests for audio modules: aifc, sunau and wave. + +.. + +.. bpo: 18714 +.. date: 8849 +.. nonce: tcsRe- +.. section: Tests + +Added tests for ``pdb.find_function()``. + +.. + +.. bpo: 18758 +.. date: 8848 +.. nonce: hMCi7Z +.. section: Documentation + +Fixed and improved cross-references. + +.. + +.. bpo: 18972 +.. date: 8847 +.. nonce: iFwRVt +.. section: Documentation + +Modernize email examples and use the argparse module in them. + +.. + +.. bpo: 19130 +.. date: 8846 +.. nonce: 7l54jz +.. section: Build + +Correct PCbuild/readme.txt, Python 3.3 and 3.4 require VS 2010. + +.. + +.. bpo: 15663 +.. date: 8845 +.. nonce: 72Jlq0 +.. section: Build + +Update OS X 10.6+ installer to use Tcl/Tk 8.5.15. + +.. + +.. bpo: 14499 +.. date: 8844 +.. nonce: 5ipy19 +.. section: Build + +Fix several problems with OS X universal build support: 1. ppc arch +detection for extension module builds broke with Xcode 5 2. ppc arch +detection in configure did not work on OS X 10.4 3. -sysroot and -arch +flags were unnecessarily duplicated 4. there was no obvious way to +configure an intel-32 only build. + +.. + +.. bpo: 19019 +.. date: 8843 +.. nonce: 5W7lw_ +.. section: Build + +Change the OS X installer build script to use CFLAGS instead of OPT for +special build options. By setting OPT, some compiler-specific options like +-fwrapv were overridden and thus not used, which could result in broken +interpreters when building with clang. diff --git a/Misc/NEWS.d/3.4.0b1.rst b/Misc/NEWS.d/3.4.0b1.rst new file mode 100644 index 00000000000000..66775137dbb067 --- /dev/null +++ b/Misc/NEWS.d/3.4.0b1.rst @@ -0,0 +1,1451 @@ +.. bpo: 0 +.. date: 9056 +.. nonce: HZ3bne +.. release date: 2013-11-24 +.. section: Core and Builtins + +Use the repr of a module name in more places in import, especially +exceptions. + +.. + +.. bpo: 19619 +.. date: 9055 +.. nonce: p4mly- +.. section: Core and Builtins + +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) + +.. + +.. bpo: 19183 +.. date: 9054 +.. nonce: uRQl7Q +.. section: Core and Builtins + +Implement PEP 456 'secure and interchangeable hash algorithm'. Python now +uses SipHash24 on all major platforms. + +.. + +.. bpo: 12892 +.. date: 9053 +.. nonce: TBN6AI +.. section: Core and Builtins + +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. + +.. + +.. bpo: 17806 +.. date: 9052 +.. nonce: Mkg_9s +.. section: Core and Builtins + +Added keyword-argument support for "tabsize" to str/bytes.expandtabs(). + +.. + +.. bpo: 17828 +.. date: 9051 +.. nonce: -sD57u +.. section: Core and Builtins + +Output type errors in str.encode(), bytes.decode() and bytearray.decode() +now direct users to codecs.encode() or codecs.decode() as appropriate. + +.. + +.. bpo: 17828 +.. date: 9050 +.. nonce: k-Stau +.. section: Core and Builtins + +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. + +.. + +.. bpo: 19466 +.. date: 9049 +.. nonce: l0a3mh +.. section: Core and Builtins + +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. + +.. + +.. bpo: 19514 +.. date: 9048 +.. nonce: FfR4kF +.. section: Core and Builtins + +Deduplicate some _Py_IDENTIFIER declarations. Patch by Andrei Dorian Duma. + +.. + +.. bpo: 17936 +.. date: 9047 +.. nonce: Vva8kQ +.. section: Core and Builtins + +Fix O(n**2) behaviour when adding or removing many subclasses of a given +type. + +.. + +.. bpo: 19428 +.. date: 9046 +.. nonce: wN6Oyz +.. section: Core and Builtins + +zipimport now handles errors when reading truncated or invalid ZIP archive. + +.. + +.. bpo: 18408 +.. date: 9045 +.. nonce: IDTlVz +.. section: Core and Builtins + +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. + +.. + +.. bpo: 19369 +.. date: 9044 +.. nonce: 19W2nG +.. section: Core and Builtins + +Optimized the usage of __length_hint__(). + +.. + +.. bpo: 18603 +.. date: 9043 +.. nonce: 7SMyAQ +.. section: Core and Builtins + +Ensure that PyOS_mystricmp and PyOS_mystrnicmp are in the Python executable +and not removed by the linker's optimizer. + +.. + +.. bpo: 19306 +.. date: 9042 +.. nonce: PYfqS6 +.. section: Core and Builtins + +Add extra hints to the faulthandler module's stack dumps that these are +"upside down". + +.. + +.. bpo: 3158 +.. date: 9041 +.. nonce: Uuris9 +.. section: Library + +doctest can now find doctests in functions and methods written in C. + +.. + +.. bpo: 13477 +.. date: 9040 +.. nonce: KYiO6P +.. section: Library + +Added command line interface to the tarfile module. Original patch by Berker +Peksag. + +.. + +.. bpo: 19674 +.. date: 9039 +.. nonce: wDLXgw +.. section: Library + +inspect.signature() now produces a correct signature for some builtins. + +.. + +.. bpo: 19722 +.. date: 9038 +.. nonce: pZvdfi +.. section: Library + +Added opcode.stack_effect(), which computes the stack effect of bytecode +instructions. + +.. + +.. bpo: 19735 +.. date: 9037 +.. nonce: 4JGp9S +.. section: Library + +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(). + +.. + +.. bpo: 16203 +.. date: 9036 +.. nonce: Obg29F +.. section: Library + +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. + +.. + +.. bpo: 13592 +.. date: 9035 +.. nonce: LI-pVN +.. section: Library + +Improved the repr for regular expression pattern objects. Based on patch by +Hugo Lopes Tavares. + +.. + +.. bpo: 19641 +.. date: 9034 +.. nonce: S_oEqp +.. section: Library + +Added the audioop.byteswap() function to convert big-endian samples to +little-endian and vice versa. + +.. + +.. bpo: 15204 +.. date: 9033 +.. nonce: bICOJc +.. section: Library + +Deprecated the 'U' mode in file-like objects. + +.. + +.. bpo: 17810 +.. date: 9032 +.. nonce: eJrPc5 +.. section: Library + +Implement PEP 3154, pickle protocol 4. + +.. + +.. bpo: 19668 +.. date: 9031 +.. nonce: e177xD +.. section: Library + +Added support for the cp1125 encoding. + +.. + +.. bpo: 19689 +.. date: 9030 +.. nonce: ucsUkZ +.. section: Library + +Add ssl.create_default_context() factory function. It creates a new +SSLContext object with secure default settings. + +.. + +.. bpo: 19727 +.. date: 9029 +.. nonce: 7z890j +.. section: Library + +os.utime(..., None) is now potentially more precise under Windows. + +.. + +.. bpo: 17201 +.. date: 9028 +.. nonce: x3oEjg +.. section: Library + +ZIP64 extensions now are enabled by default. Patch by William Mallard. + +.. + +.. bpo: 19292 +.. date: 9027 +.. nonce: SRsZqK +.. section: Library + +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. + +.. + +.. bpo: 19673 +.. date: 9026 +.. nonce: cbMrgH +.. section: Library + +Add pathlib to the stdlib as a provisional module (PEP 428). + +.. + +.. bpo: 16596 +.. date: 9025 +.. nonce: Fk4mD0 +.. section: Library + +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.) + +.. + +.. bpo: 17916 +.. date: 9024 +.. nonce: NhM62k +.. section: Library + +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). + +.. + +.. bpo: 19552 +.. date: 9023 +.. nonce: YLwRGR +.. section: Library + +venv now supports bootstrapping pip into virtual environments + +.. + +.. bpo: 17134 +.. date: 9022 +.. nonce: 59bg3U +.. section: Library + +Finalize interface to Windows' certificate store. Cert and CRL enumeration +are now two functions. enum_certificates() also returns purpose flags as set +of OIDs. + +.. + +.. bpo: 19555 +.. date: 9021 +.. nonce: Cl1wp9 +.. section: Library + +Restore sysconfig.get_config_var('SO'), (and the distutils equivalent) with +a DeprecationWarning pointing people at $EXT_SUFFIX. + +.. + +.. bpo: 8813 +.. date: 9020 +.. nonce: eOLgxE +.. section: Library + +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. + +.. + +.. bpo: 18294 +.. date: 9019 +.. nonce: hCjVbY +.. section: Library + +Fix the zlib module to make it 64-bit safe. + +.. + +.. bpo: 19682 +.. date: 9018 +.. nonce: Ruo2jD +.. section: Library + +Fix compatibility issue with old version of OpenSSL that was introduced by +Issue #18379. + +.. + +.. bpo: 14455 +.. date: 9017 +.. nonce: p3C8TR +.. section: Library + +plistlib now supports binary plists and has an updated API. + +.. + +.. bpo: 19633 +.. date: 9016 +.. nonce: XJNQit +.. section: Library + +Fixed writing not compressed 16- and 32-bit wave files on big-endian +platforms. + +.. + +.. bpo: 18379 +.. date: 9015 +.. nonce: 6MEkk8 +.. section: Library + +SSLSocket.getpeercert() returns CA issuer AIA fields, OCSP and CRL +distribution points. + +.. + +.. bpo: 18138 +.. date: 9014 +.. nonce: Xt0I1D +.. section: Library + +Implement cadata argument of SSLContext.load_verify_location() to load CA +certificates and CRL from memory. It supports PEM and DER encoded strings. + +.. + +.. bpo: 18775 +.. date: 9013 +.. nonce: Q0s2iT +.. section: Library + +Add name and block_size attribute to HMAC object. They now provide the same +API elements as non-keyed cryptographic hash functions. + +.. + +.. bpo: 17276 +.. date: 9012 +.. nonce: Rusj_j +.. section: Library + +MD5 as default digestmod for HMAC is deprecated. The HMAC module supports +digestmod names, e.g. hmac.HMAC('sha1'). + +.. + +.. bpo: 19449 +.. date: 9011 +.. nonce: F2TbC_ +.. section: Library + +in csv's writerow, handle non-string keys when generating the error message +that certain keys are not in the 'fieldnames' list. + +.. + +.. bpo: 13633 +.. date: 9010 +.. nonce: 1AJC3w +.. section: Library + +Added a new convert_charrefs keyword arg to HTMLParser that, when True, +automatically converts all character references. + +.. + +.. bpo: 2927 +.. date: 9009 +.. nonce: 5t4wCh +.. section: Library + +Added the unescape() function to the html module. + +.. + +.. bpo: 8402 +.. date: 9008 +.. nonce: -VPGJN +.. section: Library + +Added the escape() function to the glob module. + +.. + +.. bpo: 17618 +.. date: 9007 +.. nonce: OI2l3J +.. section: Library + +Add Base85 and Ascii85 encoding/decoding to the base64 module. + +.. + +.. bpo: 19634 +.. date: 9006 +.. nonce: -pzaWO +.. section: Library + +time.strftime("%y") now raises a ValueError on AIX when given a year before +1900. + +.. + +.. bpo: 0 +.. date: 9005 +.. nonce: -1Tvel +.. section: Library + +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. + +.. + +.. bpo: 0 +.. date: 9004 +.. nonce: pmUthH +.. section: Library + +Fix compilation error under gcc of the ctypes module bundled libffi for arm. + +.. + +.. bpo: 19448 +.. date: 9003 +.. nonce: oHsofd +.. section: Library + +Add private API to SSL module to lookup ASN.1 objects by OID, NID, short +name and long name. + +.. + +.. bpo: 19282 +.. date: 9002 +.. nonce: 3nF4NV +.. section: Library + +dbm.open now supports the context management protocol. (Inital patch by +Claudiu Popa) + +.. + +.. bpo: 8311 +.. date: 9001 +.. nonce: 1h-XNN +.. section: Library + +Added support for writing any bytes-like objects in the aifc, sunau, and +wave modules. + +.. + +.. bpo: 5202 +.. date: 9000 +.. nonce: Qmv91E +.. section: Library + +Added support for unseekable files in the wave module. + +.. + +.. bpo: 19544 +.. date: 8999 +.. nonce: KA-RHQ +.. section: Library + +Restore global option to ignore ~/.pydistutils.cfg in Distutils, +accidentally removed in backout of distutils2 changes. (See also: bpo-1180) + +.. + +.. bpo: 19523 +.. date: 8998 +.. nonce: tNiY9i +.. section: Library + +Closed FileHandler leak which occurred when delay was set. + +.. + +.. bpo: 19544 +.. date: 8997 +.. nonce: vFbcTR +.. section: Library + +Restore support for --user and --group parameters to sdist command +accidentally rolled back as part of the distutils2 rollback. (See also: +bpo-6516) + +.. + +.. bpo: 13674 +.. date: 8996 +.. nonce: EIYe4u +.. section: Library + +Prevented time.strftime from crashing on Windows when given a year before +1900 and a format of %y. + +.. + +.. bpo: 19406 +.. date: 8995 +.. nonce: _vGZ47 +.. section: Library + +implementation of the ensurepip module (part of PEP 453). Patch by Donald +Stufft and Nick Coghlan. + +.. + +.. bpo: 19544 +.. date: 8994 +.. nonce: NJk1xH +.. section: Library + +Restore use of urllib over http allowing use of http_proxy for Distutils +upload command, a feature accidentally lost in the rollback of distutils2. +(See also: bpo-6286) + +.. + +.. bpo: 19544 +.. date: 8993 +.. nonce: ZtCJGn +.. section: Library + +Restore the read_pkg_file method to distutils.dist.DistributionMetadata +accidentally removed in the undo of distutils2. (See also: bpo-7457) + +.. + +.. bpo: 16685 +.. date: 8992 +.. nonce: qc5QWm +.. section: Library + +Added support for any bytes-like objects in the audioop module. Removed +support for strings. + +.. + +.. bpo: 7171 +.. date: 8991 +.. nonce: irjmxW +.. section: Library + +Add Windows implementation of ``inet_ntop`` and ``inet_pton`` to socket +module. Patch by Atsuo Ishimoto. + +.. + +.. bpo: 19261 +.. date: 8990 +.. nonce: MDxLbN +.. section: Library + +Added support for writing 24-bit samples in the sunau module. + +.. + +.. bpo: 1097797 +.. date: 8989 +.. nonce: s8FvuZ +.. section: Library + +Added CP273 encoding, used on IBM mainframes in Germany and Austria. +Mapping provided by Michael Bierenfeld. + +.. + +.. bpo: 1575020 +.. date: 8988 +.. nonce: skWyvl +.. section: Library + +Fixed support of 24-bit wave files on big-endian platforms. + +.. + +.. bpo: 19378 +.. date: 8987 +.. nonce: 1XDVqS +.. section: Library + +Fixed a number of cases in the dis module where the new "file" parameter was +not being honoured correctly + +.. + +.. bpo: 19378 +.. date: 8986 +.. nonce: s_AkzU +.. section: Library + +Removed the "dis.Bytecode.show_info" method + +.. + +.. bpo: 19378 +.. date: 8985 +.. nonce: mEYzGf +.. section: Library + +Renamed the "dis.Bytecode.display_code" method to "dis.Bytecode.dis" and +converted it to returning a string rather than printing output. + +.. + +.. bpo: 19378 +.. date: 8984 +.. nonce: zuYjXC +.. section: Library + +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. + +.. + +.. bpo: 18678 +.. date: 8983 +.. nonce: 7wTha_ +.. section: Library + +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. + +.. + +.. bpo: 6157 +.. date: 8982 +.. nonce: SpFEy2 +.. section: Library + +Fixed tkinter.Text.debug(). tkinter.Text.bbox() now raises TypeError +instead of TclError on wrong number of arguments. Original patch by +Guilherme Polo. + +.. + +.. bpo: 10197 +.. date: 8981 +.. nonce: 6uq2Xn +.. section: Library + +Rework subprocess.get[status]output to use subprocess functionality and thus +to work on Windows. Patch by Nick Coghlan + +.. + +.. bpo: 6160 +.. date: 8980 +.. nonce: Mr5UuA +.. section: Library + +The bbox() method of tkinter.Spinbox now returns a tuple of integers instead +of a string. Based on patch by Guilherme Polo. + +.. + +.. bpo: 19403 +.. date: 8979 +.. nonce: rJUF8f +.. section: Library + +contextlib.redirect_stdout is now reentrant + +.. + +.. bpo: 19286 +.. date: 8978 +.. nonce: TUZetF +.. section: Library + +Directories in ``package_data`` are no longer added to the filelist, +preventing failure outlined in the ticket. + +.. + +.. bpo: 19480 +.. date: 8977 +.. nonce: MY3dmW +.. section: Library + +HTMLParser now accepts all valid start-tag names as defined by the HTML5 +standard. + +.. + +.. bpo: 15114 +.. date: 8976 +.. nonce: MuB2Yy +.. section: Library + +The html.parser module now raises a DeprecationWarning when the strict +argument of HTMLParser or the HTMLParser.error method are used. + +.. + +.. bpo: 19410 +.. date: 8975 +.. nonce: OU3U4K +.. section: Library + +Undo the special-casing removal of '' for importlib.machinery.FileFinder. + +.. + +.. bpo: 19424 +.. date: 8974 +.. nonce: vYBdnZ +.. section: Library + +Fix the warnings module to accept filename containing surrogate characters. + +.. + +.. bpo: 19435 +.. date: 8973 +.. nonce: kXqMz3 +.. section: Library + +Fix directory traversal attack on CGIHttpRequestHandler. + +.. + +.. bpo: 19227 +.. date: 8972 +.. nonce: yGdfN6 +.. section: Library + +Remove pthread_atfork() handler. The handler was added to solve #18747 but +has caused issues. + +.. + +.. bpo: 19420 +.. date: 8971 +.. nonce: gxcqnT +.. section: Library + +Fix reference leak in module initalization code of _hashopenssl.c + +.. + +.. bpo: 19329 +.. date: 8970 +.. nonce: f3o3tr +.. section: Library + +Optimized compiling charsets in regular expressions. + +.. + +.. bpo: 19227 +.. date: 8969 +.. nonce: -dpnbn +.. section: Library + +Try to fix deadlocks caused by re-seeding then OpenSSL pseudo-random number +generator on fork(). + +.. + +.. bpo: 16037 +.. date: 8968 +.. nonce: cxufSm +.. section: Library + +HTTPMessage.readheaders() raises an HTTPException when more than 100 headers +are read. Adapted from patch by Jyrki Pulliainen. + +.. + +.. bpo: 16040 +.. date: 8967 +.. nonce: xg3xlX +.. section: Library + +CVE-2013-1752: nntplib: Limit maximum line lengths to 2048 to prevent +readline() calls from consuming too much memory. Patch by Jyrki Pulliainen. + +.. + +.. bpo: 16041 +.. date: 8966 +.. nonce: XFY0lr +.. section: Library + +CVE-2013-1752: poplib: Limit maximum line lengths to 2048 to prevent +readline() calls from consuming too much memory. Patch by Jyrki Pulliainen. + +.. + +.. bpo: 17997 +.. date: 8965 +.. nonce: sJUozx +.. section: Library + +Change behavior of ``ssl.match_hostname()`` to follow RFC 6125, for security +reasons. It now doesn't match multiple wildcards nor wildcards inside IDN +fragments. + +.. + +.. bpo: 16039 +.. date: 8964 +.. nonce: ipafYi +.. section: Library + +CVE-2013-1752: Change use of readline in imaplib module to limit line +length. Patch by Emil Lind. + +.. + +.. bpo: 19330 +.. date: 8963 +.. nonce: -pfViq +.. section: Library + +the unnecessary wrapper functions have been removed from the implementations +of the new contextlib.redirect_stdout and contextlib.suppress context +managers, which also ensures they provide reasonable help() output on +instances + +.. + +.. bpo: 19393 +.. date: 8962 +.. nonce: ytbAwl +.. section: Library + +Fix symtable.symtable function to not be confused when there are functions +or classes named "top". + +.. + +.. bpo: 18685 +.. date: 8961 +.. nonce: R0OJ2- +.. section: Library + +Restore re performance to pre-PEP 393 levels. + +.. + +.. bpo: 19339 +.. date: 8960 +.. nonce: kxMuh2 +.. section: Library + +telnetlib module is now using time.monotonic() when available to compute +timeout. + +.. + +.. bpo: 19399 +.. date: 8959 +.. nonce: ofrcCx +.. section: Library + +fix sporadic test_subprocess failure. + +.. + +.. bpo: 13234 +.. date: 8958 +.. nonce: uuePvu +.. section: Library + +Fix os.listdir to work with extended paths on Windows. Patch by Santoso +Wijaya. + +.. + +.. bpo: 19375 +.. date: 8957 +.. nonce: Kbkj5C +.. section: Library + +The site module adding a "site-python" directory to sys.path, if it exists, +is now deprecated. + +.. + +.. bpo: 19379 +.. date: 8956 +.. nonce: jOblDO +.. section: Library + +Lazily import linecache in the warnings module, to make startup with +warnings faster until a warning gets printed. + +.. + +.. bpo: 19288 +.. date: 8955 +.. nonce: nKDzgw +.. section: Library + +Fixed the "in" operator of dbm.gnu databases for string argument. Original +patch by Arfrever Frehtes Taifersar Arahesis. + +.. + +.. bpo: 19287 +.. date: 8954 +.. nonce: IVl3jY +.. section: Library + +Fixed the "in" operator of dbm.ndbm databases for string argument. Original +patch by Arfrever Frehtes Taifersar Arahesis. + +.. + +.. bpo: 19327 +.. date: 8953 +.. nonce: S7Xvxs +.. section: Library + +Fixed the working of regular expressions with too big charset. + +.. + +.. bpo: 17400 +.. date: 8952 +.. nonce: 8BUFmy +.. section: Library + +New 'is_global' attribute for ipaddress to tell if an address is allocated +by IANA for global or private networks. + +.. + +.. bpo: 19350 +.. date: 8951 +.. nonce: MCCKjK +.. section: Library + +Increasing the test coverage of macurl2path. Patch by Colin Williams. + +.. + +.. bpo: 19365 +.. date: 8950 +.. nonce: ZBG2Mi +.. section: Library + +Optimized the parsing of long replacement string in re.sub*() functions. + +.. + +.. bpo: 19352 +.. date: 8949 +.. nonce: 3TfAkY +.. section: Library + +Fix unittest discovery when a module can be reached through several paths +(e.g. under Debian/Ubuntu with virtualenv). + +.. + +.. bpo: 15207 +.. date: 8948 +.. nonce: piOBBi +.. section: Library + +Fix mimetypes to read from correct part of Windows registry Original patch +by Dave Chambers + +.. + +.. bpo: 16595 +.. date: 8947 +.. nonce: Be5Hga +.. section: Library + +Add prlimit() to resource module. + +.. + +.. bpo: 19324 +.. date: 8946 +.. nonce: e0cvlt +.. section: Library + +Expose Linux-specific constants in resource module. + +.. + +.. bpo: 0 +.. date: 8945 +.. nonce: sxxiug +.. section: Library + +Load SSL's error strings in hashlib. + +.. + +.. bpo: 18527 +.. date: 8944 +.. nonce: fA-A37 +.. section: Library + +Upgrade internal copy of zlib to 1.2.8. + +.. + +.. bpo: 19274 +.. date: 8943 +.. nonce: i8khqy +.. section: Library + +Add a filterfunc parameter to PyZipFile.writepy. + +.. + +.. bpo: 8964 +.. date: 8942 +.. nonce: dzU2FB +.. section: Library + +fix platform._sys_version to handle IronPython 2.6+. Patch by Martin +Matusiak. + +.. + +.. bpo: 19413 +.. date: 8941 +.. nonce: 2Niic6 +.. section: Library + +Restore pre-3.3 reload() semantics of re-finding modules. + +.. + +.. bpo: 18958 +.. date: 8940 +.. nonce: AoIQm9 +.. section: Library + +Improve error message for json.load(s) while passing a string that starts +with a UTF-8 BOM. + +.. + +.. bpo: 19307 +.. date: 8939 +.. nonce: iFye0G +.. section: Library + +Improve error message for json.load(s) while passing objects of the wrong +type. + +.. + +.. bpo: 16038 +.. date: 8938 +.. nonce: TZGbSo +.. section: Library + +CVE-2013-1752: ftplib: Limit amount of data read by limiting the call to +readline(). Original patch by Michał Jastrzębski and Giampaolo Rodola. + +.. + +.. bpo: 17087 +.. date: 8937 +.. nonce: A3XA7C +.. section: Library + +Improved the repr for regular expression match objects. + +.. + +.. bpo: 19664 +.. date: 8936 +.. nonce: Nw449E +.. section: Tests + +test_userdict's repr test no longer depends on the order of dict elements. + +.. + +.. bpo: 19440 +.. date: 8935 +.. nonce: BW6mI9 +.. section: Tests + +Clean up test_capi by removing an unnecessary __future__ import, converting +from test_main to unittest.main, and running the _testcapi module tests as +subTests of a unittest TestCase method. + +.. + +.. bpo: 19378 +.. date: 8934 +.. nonce: zeWIz0 +.. section: Tests + +the main dis module tests are now run with both stdout redirection *and* +passing an explicit file parameter + +.. + +.. bpo: 19378 +.. date: 8933 +.. nonce: MOkpfA +.. section: Tests + +removed the not-actually-helpful assertInstructionMatches and +assertBytecodeExactlyMatches helpers from bytecode_helper + +.. + +.. bpo: 18702 +.. date: 8932 +.. nonce: 91BEkZ +.. section: Tests + +All skipped tests now reported as skipped. + +.. + +.. bpo: 19439 +.. date: 8931 +.. nonce: J96-Vv +.. section: Tests + +interpreter embedding tests are now executed on Windows (Patch by Zachary +Ware) + +.. + +.. bpo: 19085 +.. date: 8930 +.. nonce: Gcl9XX +.. section: Tests + +Added basic tests for all tkinter widget options. + +.. + +.. bpo: 19384 +.. date: 8929 +.. nonce: v6r_8A +.. section: Tests + +Fix test_py_compile for root user, patch by Claudiu Popa. + +.. + +.. bpo: 18326 +.. date: 8928 +.. nonce: juaetA +.. section: Documentation + +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. + +.. + +.. bpo: 19358 +.. date: 8927 +.. nonce: 80ySM- +.. section: Build + +"make clinic" now runs the Argument Clinic preprocessor over all CPython +source files. + +.. + +.. bpo: 0 +.. date: 8926 +.. nonce: -GnKfJ +.. section: Build + +Update SQLite to 3.8.1, xz to 5.0.5, and Tcl/Tk to 8.6.1 on Windows. + +.. + +.. bpo: 16632 +.. date: 8925 +.. nonce: BiQhFA +.. section: Build + +Enable DEP and ASLR on Windows. + +.. + +.. bpo: 17791 +.. date: 8924 +.. nonce: fExj5r +.. section: Build + +Drop PREFIX and EXEC_PREFIX definitions from PC/pyconfig.h + +.. + +.. bpo: 0 +.. date: 8923 +.. nonce: uI77cH +.. section: Build + +Add workaround for VS 2010 nmake clean issue. VS 2010 doesn't set up PATH +for nmake.exe correctly. + +.. + +.. bpo: 19550 +.. date: 8922 +.. nonce: MLDPnk +.. section: Build + +Implement Windows installer changes of PEP 453 (ensurepip). + +.. + +.. bpo: 19520 +.. date: 8921 +.. nonce: KBn7ff +.. section: Build + +Fix compiler warning in the _sha3 module on 32bit Windows. + +.. + +.. bpo: 19356 +.. date: 8920 +.. nonce: lHamQS +.. section: Build + +Avoid using a C variabled named "_self", it's a reserved word in some C +compilers. + +.. + +.. bpo: 15792 +.. date: 8919 +.. nonce: Rx4fV2 +.. section: Build + +Correct build options on Win64. Patch by Jeremy Kloth. + +.. + +.. bpo: 19373 +.. date: 8918 +.. nonce: Gxnb8v +.. section: Build + +Apply upstream change to Tk 8.5.15 fixing OS X 10.9 screen refresh problem +for OS X installer build. + +.. + +.. bpo: 19649 +.. date: 8917 +.. nonce: yuZ3xq +.. section: Build + +On OS X, the same set of file names are now installed in bin directories for +all configurations: non-framework vs framework, and single arch vs universal +builds. pythonx.y-32 is now always installed for 64-bit/32-bit universal +builds. The obsolete and undocumented pythonw* symlinks are no longer +installed anywhere. + +.. + +.. bpo: 19553 +.. date: 8916 +.. nonce: JY6pHm +.. section: Build + +PEP 453 - "make install" and "make altinstall" now install or upgrade pip by +default, using the bundled pip provided by the new ensurepip module. A new +configure option, --with-ensurepip[=upgrade|install|no], is available to +override the default ensurepip "--upgrade" option. The option can also be +set with "make [alt]install ENSUREPIP=[upgrade|install|no]". + +.. + +.. bpo: 19551 +.. date: 8915 +.. nonce: Co7ZOp +.. section: Build + +PEP 453 - the OS X installer now installs pip by default. + +.. + +.. bpo: 0 +.. date: 8914 +.. nonce: kxcK-F +.. section: Build + +Update third-party libraries for OS X installers: xz 5.0.3 -> 5.0.5, SQLite +3.7.13 -> 3.8.1 + +.. + +.. bpo: 15663 +.. date: 8913 +.. nonce: f91_wP +.. section: Build + +Revert OS X installer built-in Tcl/Tk support for 3.4.0b1. Some third-party +projects, such as Matplotlib and PIL/Pillow, depended on being able to build +with Tcl and Tk frameworks in /Library/Frameworks. + +.. + +.. bpo: 19730 +.. date: 8912 +.. nonce: B7hBq7 +.. section: Tools/Demos + +Argument Clinic now supports all the existing PyArg "format units" as legacy +converters, as well as two new features: "self converters" and the "version" +directive. + +.. + +.. bpo: 19552 +.. date: 8911 +.. nonce: zuitRR +.. section: Tools/Demos + +pyvenv now bootstraps pip into virtual environments by default (pass +--without-pip to request the old behaviour) + +.. + +.. bpo: 19390 +.. date: 8910 +.. nonce: CROPNO +.. section: Tools/Demos + +Argument Clinic no longer accepts malformed Python and C ids. diff --git a/Misc/NEWS.d/3.4.0b2.rst b/Misc/NEWS.d/3.4.0b2.rst new file mode 100644 index 00000000000000..038670c031b0b6 --- /dev/null +++ b/Misc/NEWS.d/3.4.0b2.rst @@ -0,0 +1,1197 @@ +.. bpo: 17432 +.. date: 9179 +.. nonce: mmNI4f +.. release date: 2014-01-05 +.. section: Core and Builtins + +Drop UCS2 from names of Unicode functions in python3.def. + +.. + +.. bpo: 19526 +.. date: 9178 +.. nonce: 9WWttQ +.. section: Core and Builtins + +Exclude all new API from the stable ABI. Exceptions can be made if a need is +demonstrated. + +.. + +.. bpo: 19969 +.. date: 9177 +.. nonce: mmRsrB +.. section: Core and Builtins + +PyBytes_FromFormatV() now raises an OverflowError if "%c" argument is not in +range [0; 255]. + +.. + +.. bpo: 19995 +.. date: 9176 +.. nonce: gQHtAc +.. section: Core and Builtins + +%c, %o, %x, and %X now issue a DeprecationWarning on non-integer input; +reworded docs to clarify that an integer type should define both __int__ and +__index__. + +.. + +.. bpo: 19787 +.. date: 9175 +.. nonce: tAMy-H +.. section: Core and Builtins + +PyThread_set_key_value() now always set the value. In Python 3.3, the +function did nothing if the key already exists (if the current value is a +non-NULL pointer). + +.. + +.. bpo: 14432 +.. date: 9174 +.. nonce: yov4oy +.. section: Core and Builtins + +Remove the thread state field from the frame structure. Fix a crash when a +generator is created in a C thread that is destroyed while the generator is +still used. The issue was that a generator contains a frame, and the frame +kept a reference to the Python state of the destroyed C thread. The crash +occurs when a trace function is setup. + +.. + +.. bpo: 19576 +.. date: 9173 +.. nonce: b_UtIp +.. section: Core and Builtins + +PyGILState_Ensure() now initializes threads. At startup, Python has no +concrete GIL. If PyGILState_Ensure() is called from a new thread for the +first time and PyEval_InitThreads() was not called yet, a GIL needs to be +created. + +.. + +.. bpo: 17576 +.. date: 9172 +.. nonce: ukzqsg +.. section: Core and Builtins + +Deprecation warning emitted now when __int__() or __index__() return not int +instance. + +.. + +.. bpo: 19932 +.. date: 9171 +.. nonce: ZU_tXW +.. section: Core and Builtins + +Fix typo in import.h, missing whitespaces in function prototypes. + +.. + +.. bpo: 19736 +.. date: 9170 +.. nonce: j35rNX +.. section: Core and Builtins + +Add module-level statvfs constants defined for GNU/glibc based systems. + +.. + +.. bpo: 20097 +.. date: 9169 +.. nonce: _L-Wql +.. section: Core and Builtins + +Fix bad use of "self" in importlib's WindowsRegistryFinder. + +.. + +.. bpo: 19729 +.. date: 9168 +.. nonce: HmZThe +.. section: Core and Builtins + +In str.format(), fix recursive expansion in format spec. + +.. + +.. bpo: 19638 +.. date: 9167 +.. nonce: lh5Awt +.. section: Core and Builtins + +Fix possible crash / undefined behaviour from huge (more than 2 billion +characters) input strings in _Py_dg_strtod. + +.. + +.. bpo: 20154 +.. date: 9166 +.. nonce: 5JyK0Q +.. section: Library + +Deadlock in asyncio.StreamReader.readexactly(). + +.. + +.. bpo: 16113 +.. date: 9165 +.. nonce: 2gaEPO +.. section: Library + +Remove sha3 module again. + +.. + +.. bpo: 20111 +.. date: 9164 +.. nonce: NsoIDi +.. section: Library + +pathlib.Path.with_suffix() now sanity checks the given suffix. + +.. + +.. bpo: 0 +.. date: 9163 +.. nonce: 6LOl16 +.. section: Library + +Fix breakage in TestSuite.countTestCases() introduced by issue #11798. + +.. + +.. bpo: 20108 +.. date: 9162 +.. nonce: HxuC0s +.. section: Library + +Avoid parameter name clash in inspect.getcallargs(). + +.. + +.. bpo: 19918 +.. date: 9161 +.. nonce: SciMAd +.. section: Library + +Fix PurePath.relative_to() under Windows. + +.. + +.. bpo: 19422 +.. date: 9160 +.. nonce: 1dRaPS +.. section: Library + +Explicitly disallow non-SOCK_STREAM sockets in the ssl module, rather than +silently let them emit clear text data. + +.. + +.. bpo: 20046 +.. date: 9159 +.. nonce: NkWtze +.. section: Library + +Locale alias table no longer contains entities which can be calculated. +Generalized support of the euro modifier. + +.. + +.. bpo: 20027 +.. date: 9158 +.. nonce: dtB7OG +.. section: Library + +Fixed locale aliases for devanagari locales. + +.. + +.. bpo: 20067 +.. date: 9157 +.. nonce: MlnlYd +.. section: Library + +Tkinter variables now work when wantobjects is false. + +.. + +.. bpo: 19020 +.. date: 9156 +.. nonce: _16K__ +.. section: Library + +Tkinter now uses splitlist() instead of split() in configure methods. + +.. + +.. bpo: 19744 +.. date: 9155 +.. nonce: frub3A +.. section: Library + +ensurepip now provides a better error message when Python is built without +SSL/TLS support (pip currently requires that support to run, even if only +operating with local wheel files) + +.. + +.. bpo: 19734 +.. date: 9154 +.. nonce: jHpBF- +.. section: Library + +ensurepip now ignores all pip environment variables to avoid odd behaviour +based on user configuration settings + +.. + +.. bpo: 0 +.. date: 9153 +.. nonce: d5LOJv +.. section: Library + +Fix TypeError on "setup.py upload --show-response". + +.. + +.. bpo: 20045 +.. date: 9152 +.. nonce: fdKDSA +.. section: Library + +Fix "setup.py register --list-classifiers". + +.. + +.. bpo: 18879 +.. date: 9151 +.. nonce: CEiozo +.. section: Library + +When a method is looked up on a temporary file, avoid closing the file +before the method is possibly called. + +.. + +.. bpo: 20037 +.. date: 9150 +.. nonce: Mnn2jV +.. section: Library + +Avoid crashes when opening a text file late at interpreter shutdown. + +.. + +.. bpo: 19967 +.. date: 9149 +.. nonce: 0zAW9L +.. section: Library + +Thanks to the PEP 442, asyncio.Future now uses a destructor to log uncaught +exceptions, instead of the dedicated _TracebackLogger class. + +.. + +.. bpo: 0 +.. date: 9148 +.. nonce: Gqaj5f +.. section: Library + +Added a Task.current_task() class method to asyncio. + +.. + +.. bpo: 19850 +.. date: 9147 +.. nonce: WPTJDe +.. section: Library + +Set SA_RESTART in asyncio when registering a signal handler to limit EINTR +occurrences. + +.. + +.. bpo: 0 +.. date: 9146 +.. nonce: JivAZe +.. section: Library + +Implemented write flow control in asyncio for proactor event loop (Windows). + +.. + +.. bpo: 0 +.. date: 9145 +.. nonce: WBY2wl +.. section: Library + +Change write buffer in asyncio use to avoid O(N**2) behavior. Make +write()/sendto() accept bytearray/memoryview. + +.. + +.. bpo: 20034 +.. date: 9144 +.. nonce: GlYpNX +.. section: Library + +Updated alias mapping to most recent locale.alias file from X.org +distribution using makelocalealias.py. + +.. + +.. bpo: 5815 +.. date: 9143 +.. nonce: FxSb0P +.. section: Library + +Fixed support for locales with modifiers. Fixed support for locale +encodings with hyphens. + +.. + +.. bpo: 20026 +.. date: 9142 +.. nonce: KO1jB6 +.. section: Library + +Fix the sqlite module to handle correctly invalid isolation level (wrong +type). + +.. + +.. bpo: 18829 +.. date: 9141 +.. nonce: QPwJFn +.. section: Library + +csv.Dialect() now checks type for delimiter, escapechar and quotechar +fields. Original patch by Vajrasky Kok. + +.. + +.. bpo: 19855 +.. date: 9140 +.. nonce: TtBUO6 +.. section: Library + +uuid.getnode() on Unix now looks on the PATH for the executables used to +find the mac address, with /sbin and /usr/sbin as fallbacks. + +.. + +.. bpo: 20007 +.. date: 9139 +.. nonce: IaSnPo +.. section: Library + +HTTPResponse.read(0) no more prematurely closes connection. Original patch +by Simon Sapin. + +.. + +.. bpo: 19946 +.. date: 9138 +.. nonce: hcbn92 +.. section: Library + +multiprocessing now uses runpy to initialize __main__ in child processes +when necessary, allowing it to correctly handle scripts without suffixes and +submodules that use explicit relative imports or otherwise rely on parent +modules being correctly imported prior to execution. + +.. + +.. bpo: 19921 +.. date: 9137 +.. nonce: LGeNky +.. section: Library + +When Path.mkdir() is called with parents=True, any missing parent is created +with the default permissions, ignoring the mode argument (mimicking the +POSIX "mkdir -p" command). + +.. + +.. bpo: 19887 +.. date: 9136 +.. nonce: 2jM2qA +.. section: Library + +Improve the Path.resolve() algorithm to support certain symlink chains. + +.. + +.. bpo: 19912 +.. date: 9135 +.. nonce: TviIPi +.. section: Library + +Fixed numerous bugs in ntpath.splitunc(). + +.. + +.. bpo: 19911 +.. date: 9134 +.. nonce: w1QmnT +.. section: Library + +ntpath.splitdrive() now correctly processes the 'İ' character (U+0130, LATIN +CAPITAL LETTER I WITH DOT ABOVE). + +.. + +.. bpo: 19532 +.. date: 9133 +.. nonce: vCt7bh +.. section: Library + +python -m compileall with no filename/directory arguments now respects the +-f and -q flags instead of ignoring them. + +.. + +.. bpo: 19623 +.. date: 9132 +.. nonce: zv4rIL +.. section: Library + +Fixed writing to unseekable files in the aifc module. + +.. + +.. bpo: 19946 +.. date: 9131 +.. nonce: b4Js6X +.. section: Library + +multiprocessing.spawn now raises ImportError when the module to be used as +the main module cannot be imported. + +.. + +.. bpo: 17919 +.. date: 9130 +.. nonce: H5iGXv +.. section: Library + +select.poll.register() again works with poll.POLLNVAL on AIX. Fixed integer +overflow in the eventmask parameter. + +.. + +.. bpo: 19063 +.. date: 9129 +.. nonce: pQzK1K +.. section: Library + +if a Charset's body_encoding was set to None, the email package would +generate a message claiming the Content-Transfer-Encoding was 7bit, and +produce garbage output for the content. This now works. A couple of other +set_payload mishandlings of non-ASCII are also fixed. In addition, calling +set_payload with a string argument without specifying a charset now raises +an error (this is a new error in 3.4). + +.. + +.. bpo: 15475 +.. date: 9128 +.. nonce: -vqlm1 +.. section: Library + +Add __sizeof__ implementations for itertools objects. + +.. + +.. bpo: 19944 +.. date: 9127 +.. nonce: XxQU2O +.. section: Library + +Fix importlib.find_spec() so it imports parents as needed and move the +function to importlib.util. + +.. + +.. bpo: 19880 +.. date: 9126 +.. nonce: wJls1u +.. section: Library + +Fix a reference leak in unittest.TestCase. Explicitly break reference cycles +between frames and the _Outcome instance. + +.. + +.. bpo: 17429 +.. date: 9125 +.. nonce: dlZP0_ +.. section: Library + +platform.linux_distribution() now decodes files from the UTF-8 encoding with +the surrogateescape error handler, instead of decoding from the locale +encoding in strict mode. It fixes the function on Fedora 19 which is +probably the first major distribution release with a non-ASCII name. Patch +written by Toshio Kuratomi. + +.. + +.. bpo: 19343 +.. date: 9124 +.. nonce: La15PA +.. section: Library + +Expose FreeBSD-specific APIs in resource module. Original patch by Koobs. + +.. + +.. bpo: 19929 +.. date: 9123 +.. nonce: BZDeEj +.. section: Library + +Call os.read with 32768 within subprocess.Popen.communicate rather than 4096 +for efficiency. A microbenchmark shows Linux and OS X both using ~50% less +cpu time this way. + +.. + +.. bpo: 19506 +.. date: 9122 +.. nonce: GteUMC +.. section: Library + +Use a memoryview to avoid a data copy when piping data to stdin within +subprocess.Popen.communicate. 5-10% less cpu usage. + +.. + +.. bpo: 19876 +.. date: 9121 +.. nonce: 2YXHY- +.. section: Library + +selectors unregister() no longer raises ValueError or OSError if the FD is +closed (as long as it was registered). + +.. + +.. bpo: 19908 +.. date: 9120 +.. nonce: rOsMVQ +.. section: Library + +pathlib now joins relative Windows paths correctly when a drive is present. +Original patch by Antoine Pitrou. + +.. + +.. bpo: 19296 +.. date: 9119 +.. nonce: WVPZAK +.. section: Library + +Silence compiler warning in dbm_open + +.. + +.. bpo: 6784 +.. date: 9118 +.. nonce: uxEt6F +.. section: Library + +Strings from Python 2 can now be unpickled as bytes objects by setting the +encoding argument of Unpickler to be 'bytes'. Initial patch by Merlijn van +Deen. + +.. + +.. bpo: 19839 +.. date: 9117 +.. nonce: qfP0k5 +.. section: Library + +Fix regression in bz2 module's handling of non-bzip2 data at EOF, and +analogous bug in lzma module. + +.. + +.. bpo: 19881 +.. date: 9116 +.. nonce: NKrKAh +.. section: Library + +Fix pickling bug where cpickle would emit bad pickle data for large bytes +string (i.e., with size greater than 2**32-1). + +.. + +.. bpo: 19138 +.. date: 9115 +.. nonce: xwKrX_ +.. section: Library + +doctest's IGNORE_EXCEPTION_DETAIL now allows a match when no exception +detail exists (no colon following the exception's name, or a colon does +follow but no text follows the colon). + +.. + +.. bpo: 19927 +.. date: 9114 +.. nonce: ZijD-E +.. section: Library + +Add __eq__ to path-based loaders in importlib. + +.. + +.. bpo: 19827 +.. date: 9113 +.. nonce: KBYfyd +.. section: Library + +On UNIX, setblocking() and settimeout() methods of socket.socket can now +avoid a second syscall if the ioctl() function can be used, or if the non- +blocking flag of the socket is unchanged. + +.. + +.. bpo: 19785 +.. date: 9112 +.. nonce: dTWAof +.. section: Library + +smtplib now supports SSLContext.check_hostname and server name indication +for TLS/SSL connections. + +.. + +.. bpo: 19784 +.. date: 9111 +.. nonce: t85DbS +.. section: Library + +poplib now supports SSLContext.check_hostname and server name indication for +TLS/SSL connections. + +.. + +.. bpo: 19783 +.. date: 9110 +.. nonce: VRsf8d +.. section: Library + +nntplib now supports SSLContext.check_hostname and server name indication +for TLS/SSL connections. + +.. + +.. bpo: 19782 +.. date: 9109 +.. nonce: 7jF-re +.. section: Library + +imaplib now supports SSLContext.check_hostname and server name indication +for TLS/SSL connections. + +.. + +.. bpo: 20123 +.. date: 9108 +.. nonce: o-MHVk +.. section: Library + +Fix pydoc.synopsis() for "binary" modules. + +.. + +.. bpo: 19834 +.. date: 9107 +.. nonce: rlFmTq +.. section: Library + +Support unpickling of exceptions pickled by Python 2. + +.. + +.. bpo: 19781 +.. date: 9106 +.. nonce: 4ZiyRb +.. section: Library + +ftplib now supports SSLContext.check_hostname and server name indication for +TLS/SSL connections. + +.. + +.. bpo: 19509 +.. date: 9105 +.. nonce: I2qj0u +.. section: Library + +Add SSLContext.check_hostname to match the peer's certificate with +server_hostname on handshake. + +.. + +.. bpo: 15798 +.. date: 9104 +.. nonce: 1bxNCP +.. section: Library + +Fixed subprocess.Popen() to no longer fail if file descriptor 0, 1 or 2 is +closed. + +.. + +.. bpo: 17897 +.. date: 9103 +.. nonce: 0iKzvE +.. section: Library + +Optimized unpickle prefetching. + +.. + +.. bpo: 3693 +.. date: 9102 +.. nonce: _c0s5z +.. section: Library + +Make the error message more helpful when the array.array() constructor is +given a str. Move the array module typecode documentation to the docstring +of the constructor. + +.. + +.. bpo: 19088 +.. date: 9101 +.. nonce: JBKVzp +.. section: Library + +Fixed incorrect caching of the copyreg module in object.__reduce__() and +object.__reduce_ex__(). + +.. + +.. bpo: 19698 +.. date: 9100 +.. nonce: Xcq8uC +.. section: Library + +Removed exec_module() methods from importlib.machinery.BuiltinImporter and +ExtensionFileLoader. + +.. + +.. bpo: 18864 +.. date: 9099 +.. nonce: 2CR2Xi +.. section: Library + +Added a setter for ModuleSpec.has_location. + +.. + +.. bpo: 0 +.. date: 9098 +.. nonce: UKWITk +.. section: Library + +Fixed _pickle.Unpickler to not fail when loading empty strings as persistent +IDs. + +.. + +.. bpo: 11480 +.. date: 9097 +.. nonce: qkIZLG +.. section: Library + +Fixed copy.copy to work with classes with custom metaclasses. Patch by +Daniel Urban. + +.. + +.. bpo: 6477 +.. date: 9096 +.. nonce: nK1lHr +.. section: Library + +Added support for pickling the types of built-in singletons (i.e., Ellipsis, +NotImplemented, None). + +.. + +.. bpo: 19713 +.. date: 9095 +.. nonce: UhiUKc +.. section: Library + +Add remaining PEP 451-related deprecations and move away from using +find_module/find_loaer/load_module. + +.. + +.. bpo: 19708 +.. date: 9094 +.. nonce: HJuToY +.. section: Library + +Update pkgutil to use the new importer APIs. + +.. + +.. bpo: 19703 +.. date: 9093 +.. nonce: pLtVYQ +.. section: Library + +Update pydoc to use the new importer APIs. + +.. + +.. bpo: 19851 +.. date: 9092 +.. nonce: 4HQZWz +.. section: Library + +Fixed a regression in reloading sub-modules. + +.. + +.. bpo: 0 +.. date: 9091 +.. nonce: 3H16yn +.. section: Library + +ssl.create_default_context() sets OP_NO_COMPRESSION to prevent CRIME. + +.. + +.. bpo: 19802 +.. date: 9090 +.. nonce: PswaEk +.. section: Library + +Add socket.SO_PRIORITY. + +.. + +.. bpo: 11508 +.. date: 9089 +.. nonce: fx7Abs +.. section: Library + +Fixed uuid.getnode() and uuid.uuid1() on environment with virtual interface. +Original patch by Kent Frazier. + +.. + +.. bpo: 11489 +.. date: 9088 +.. nonce: 3ZQHi8 +.. section: Library + +JSON decoder now accepts lone surrogates. + +.. + +.. bpo: 19545 +.. date: 9087 +.. nonce: 1FBY5Z +.. section: Library + +Avoid chained exceptions while passing stray % to time.strptime(). Initial +patch by Claudiu Popa. + +.. + +.. bpo: 20058 +.. date: 9086 +.. nonce: KnDlhH +.. section: IDLE + +sys.stdin.readline() in IDLE now always returns only one line. + +.. + +.. bpo: 19481 +.. date: 9085 +.. nonce: BNkHOm +.. section: IDLE + +print() of string subclass instance in IDLE no longer hangs. + +.. + +.. bpo: 18270 +.. date: 9084 +.. nonce: lu6dRW +.. section: IDLE + +Prevent possible IDLE AttributeError on OS X when no initial shell window is +present. + +.. + +.. bpo: 20055 +.. date: 9083 +.. nonce: iE7yU6 +.. section: Tests + +Fix test_shutil under Windows with symlink privileges held. Patch by +Vajrasky Kok. + +.. + +.. bpo: 20070 +.. date: 9082 +.. nonce: HpyZrQ +.. section: Tests + +Don't run test_urllib2net when network resources are not enabled. + +.. + +.. bpo: 19938 +.. date: 9081 +.. nonce: 2iLiKJ +.. section: Tests + +Re-enabled test_bug_1333982 in test_dis, which had been disabled since 3.0 +due to the changes in listcomp handling. + +.. + +.. bpo: 19320 +.. date: 9080 +.. nonce: 9x_cw5 +.. section: Tests + +test_tcl no longer fails when wantobjects is false. + +.. + +.. bpo: 19919 +.. date: 9079 +.. nonce: N9bnWv +.. section: Tests + +Fix flaky SSL test. connect_ex() sometimes returns EWOULDBLOCK on Windows or +VMs hosted on Windows. + +.. + +.. bpo: 19912 +.. date: 9078 +.. nonce: NmE9ZX +.. section: Tests + +Added tests for ntpath.splitunc(). + +.. + +.. bpo: 19828 +.. date: 9077 +.. nonce: f5HrFG +.. section: Tests + +Fixed test_site when the whole suite is run with -S. + +.. + +.. bpo: 19928 +.. date: 9076 +.. nonce: dwOQ95 +.. section: Tests + +Implemented a test for repr() of cell objects. + +.. + +.. bpo: 19535 +.. date: 9075 +.. nonce: 9ZtpA7 +.. section: Tests + +Fixed test_docxmlrpc, test_functools, test_inspect, and test_statistics when +python is run with -OO. + +.. + +.. bpo: 19926 +.. date: 9074 +.. nonce: fkWjtw +.. section: Tests + +Removed unneeded test_main from test_abstract_numbers. Patch by Vajrasky +Kok. + +.. + +.. bpo: 19572 +.. date: 9073 +.. nonce: _65KAy +.. section: Tests + +More skipped tests explicitly marked as skipped. + +.. + +.. bpo: 19595 +.. date: 9072 +.. nonce: q5oNE_ +.. section: Tests + +Re-enabled a long-disabled test in test_winsound. (See also: bpo-19987) + +.. + +.. bpo: 19588 +.. date: 9071 +.. nonce: EXKxpC +.. section: Tests + +Fixed tests in test_random that were silently skipped most of the time. +Patch by Julian Gindi. + +.. + +.. bpo: 19728 +.. date: 9070 +.. nonce: q1zXeT +.. section: Build + +Enable pip installation by default on Windows. + +.. + +.. bpo: 16136 +.. date: 9069 +.. nonce: FQGvGl +.. section: Build + +Remove VMS support + +.. + +.. bpo: 18215 +.. date: 9068 +.. nonce: yw2j0l +.. section: Build + +Add script Tools/ssl/test_multiple_versions.py to compile and run Python's +unit tests with multiple versions of OpenSSL. + +.. + +.. bpo: 19922 +.. date: 9067 +.. nonce: cG30aH +.. section: Build + +define _INCLUDE__STDC_A1_SOURCE in HP-UX to include mbstate_t for mbrtowc(). + +.. + +.. bpo: 19788 +.. date: 9066 +.. nonce: P7qrFB +.. section: Build + +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. + +.. + +.. bpo: 20265 +.. date: 9065 +.. nonce: J7Xxm7 +.. section: Documentation + +Updated some parts of the Using Windows document. + +.. + +.. bpo: 20266 +.. date: 9064 +.. nonce: CieiXa +.. section: Documentation + +Updated some parts of the Windows FAQ. + +.. + +.. bpo: 20255 +.. date: 9063 +.. nonce: SnYjEP +.. section: Documentation + +Updated the about and bugs pages. + +.. + +.. bpo: 20253 +.. date: 9062 +.. nonce: nbp6uJ +.. section: Documentation + +Fixed a typo in the ipaddress docs that advertised an illegal attribute +name. Found by INADA Naoki. + +.. + +.. bpo: 18840 +.. date: 9061 +.. nonce: _2UItV +.. section: Documentation + +Introduce the json module in the tutorial, and de-emphasize the pickle +module. + +.. + +.. bpo: 19845 +.. date: 9060 +.. nonce: luj-oI +.. section: Documentation + +Updated the Compiling Python on Windows section. + +.. + +.. bpo: 19795 +.. date: 9059 +.. nonce: z5sbe1 +.. section: Documentation + +Improved markup of True/False constants. + +.. + +.. bpo: 19659 +.. date: 9058 +.. nonce: kghZl0 +.. section: Tools/Demos + +Added documentation for Argument Clinic. + +.. + +.. bpo: 19976 +.. date: 9057 +.. nonce: My60GG +.. section: Tools/Demos + +Argument Clinic METH_NOARGS functions now always take two parameters. diff --git a/Misc/NEWS.d/3.4.0b3.rst b/Misc/NEWS.d/3.4.0b3.rst new file mode 100644 index 00000000000000..2b8e38652d8c79 --- /dev/null +++ b/Misc/NEWS.d/3.4.0b3.rst @@ -0,0 +1,665 @@ +.. bpo: 20189 +.. date: 9245 +.. nonce: OIbmmo +.. release date: 2014-01-26 +.. section: Core and Builtins + +Four additional builtin types (PyTypeObject, PyMethodDescr_Type, +_PyMethodWrapper_Type, and PyWrapperDescr_Type) have been modified to +provide introspection information for builtins. + +.. + +.. bpo: 17825 +.. date: 9244 +.. nonce: toRoZf +.. section: Core and Builtins + +Cursor "^" is correctly positioned for SyntaxError and IndentationError. + +.. + +.. bpo: 2382 +.. date: 9243 +.. nonce: kL_Sgg +.. section: Core and Builtins + +SyntaxError cursor "^" is now written at correct position in most cases when +multibyte characters are in line (before "^"). This still not works +correctly with wide East Asian characters. + +.. + +.. bpo: 18960 +.. date: 9242 +.. nonce: lhfZNw +.. section: Core and Builtins + +The first line of Python script could be executed twice when the source +encoding was specified on the second line. Now the source encoding +declaration on the second line isn't effective if the first line contains +anything except a comment. 'python -x' works now again with files with the +source encoding declarations, and can be used to make Python batch files on +Windows. + +.. + +.. bpo: 0 +.. date: 9241 +.. nonce: GB7eBz +.. section: Library + +asyncio: Various improvements and small changes not all covered by issues +listed below. E.g. wait_for() now cancels the inner task if the timeout +occcurs; tweaked the set of exported symbols; renamed Empty/Full to +QueueEmpty/QueueFull; "with (yield from lock)" now uses a separate context +manager; readexactly() raises if not enough data was read; PTY support +tweaks. + +.. + +.. bpo: 20311 +.. date: 9240 +.. nonce: -6LF_t +.. section: Library + +asyncio: Add a granularity attribute to BaseEventLoop: maximum between the +resolution of the BaseEventLoop.time() method and the resolution of the +selector. The granuarility is used in the scheduler to round time and +deadline. + +.. + +.. bpo: 20311 +.. date: 9239 +.. nonce: JgE5j7 +.. section: Library + +selectors: Add a resolution attribute to BaseSelector. + +.. + +.. bpo: 20189 +.. date: 9238 +.. nonce: L9IuSm +.. section: Library + +unittest.mock now no longer assumes that any object for which it could get +an inspect.Signature is a callable written in Python. Fix courtesy of +Michael Foord. + +.. + +.. bpo: 20317 +.. date: 9237 +.. nonce: 9JI93M +.. section: Library + +ExitStack.__exit__ could create a self-referential loop if an exception +raised by a cleanup operation already had its context set correctly (for +example, by the @contextmanager decorator). The infinite loop this caused is +now avoided by checking if the expected context is already set before trying +to fix it. + +.. + +.. bpo: 20374 +.. date: 9236 +.. nonce: EWofHb +.. section: Library + +Fix build with GNU readline >= 6.3. + +.. + +.. bpo: 20262 +.. date: 9235 +.. nonce: co0t1R +.. section: Library + +Warnings are raised now when duplicate names are added in the ZIP file or +too long ZIP file comment is truncated. + +.. + +.. bpo: 20165 +.. date: 9234 +.. nonce: PyLZUR +.. section: Library + +The unittest module no longer considers tests marked with @expectedFailure +successful if they pass. + +.. + +.. bpo: 18574 +.. date: 9233 +.. nonce: 28Z8aX +.. section: Library + +Added missing newline in 100-Continue reply from +http.server.BaseHTTPRequestHandler. Patch by Nikolaus Rath. + +.. + +.. bpo: 20270 +.. date: 9232 +.. nonce: Z2Cks9 +.. section: Library + +urllib.urlparse now supports empty ports. + +.. + +.. bpo: 20243 +.. date: 9231 +.. nonce: nApKCK +.. section: Library + +TarFile no longer raise ReadError when opened in write mode. + +.. + +.. bpo: 20238 +.. date: 9230 +.. nonce: qojq-l +.. section: Library + +TarFile opened with external fileobj and "w:gz" mode didn't write complete +output on close. + +.. + +.. bpo: 20245 +.. date: 9229 +.. nonce: 93kf_h +.. section: Library + +The open functions in the tarfile module now correctly handle empty mode. + +.. + +.. bpo: 20242 +.. date: 9228 +.. nonce: yvmL9l +.. section: Library + +Fixed basicConfig() format strings for the alternative formatting styles. +Thanks to kespindler for the bug report and patch. + +.. + +.. bpo: 20246 +.. date: 9227 +.. nonce: CC8uTq +.. section: Library + +Fix buffer overflow in socket.recvfrom_into. + +.. + +.. bpo: 20206 +.. date: 9226 +.. nonce: CtFEMz +.. section: Library + +Fix edge case in email.quoprimime.encode where it truncated lines ending in +a character needing encoding but no newline by using a more efficient +algorithm that doesn't have the bug. (See also: bpo-5803) + +.. + +.. bpo: 19082 +.. date: 9225 +.. nonce: idZnK7 +.. section: Library + +Working xmlrpc.server and xmlrpc.client examples. Both in modules and in +documentation. Initial patch contributed by Vajrasky Kok. + +.. + +.. bpo: 20138 +.. date: 9224 +.. nonce: A4c9qc +.. section: Library + +The wsgiref.application_uri() and wsgiref.request_uri() functions now +conform to PEP 3333 when handle non-ASCII URLs. + +.. + +.. bpo: 19097 +.. date: 9223 +.. nonce: 5aGg0o +.. section: Library + +Raise the correct Exception when cgi.FieldStorage is given an invalid +fileobj. + +.. + +.. bpo: 20152 +.. date: 9222 +.. nonce: eqfltY +.. section: Library + +Ported Python/import.c over to Argument Clinic. + +.. + +.. bpo: 13107 +.. date: 9221 +.. nonce: YgEEME +.. section: Library + +argparse and optparse no longer raises an exception when output a help on +environment with too small COLUMNS. Based on patch by Elazar Gershuni. + +.. + +.. bpo: 20207 +.. date: 9220 +.. nonce: ziIyF1 +.. section: Library + +Always disable SSLv2 except when PROTOCOL_SSLv2 is explicitly asked for. + +.. + +.. bpo: 18960 +.. date: 9219 +.. nonce: _8qsXn +.. section: Library + +The tokenize module now ignore the source encoding declaration on the second +line if the first line contains anything except a comment. + +.. + +.. bpo: 20078 +.. date: 9218 +.. nonce: 4FYvd_ +.. section: Library + +Reading malformed zipfiles no longer hangs with 100% CPU consumption. + +.. + +.. bpo: 20113 +.. date: 9217 +.. nonce: T6DWMh +.. section: Library + +os.readv() and os.writev() now raise an OSError exception on error instead +of returning -1. + +.. + +.. bpo: 19719 +.. date: 9216 +.. nonce: 1yF3Hm +.. section: Library + +Make importlib.abc.MetaPathFinder.find_module(), +PathEntryFinder.find_loader(), and Loader.load_module() use PEP 451 APIs to +help with backwards-compatibility. + +.. + +.. bpo: 20144 +.. date: 9215 +.. nonce: UDSyaK +.. section: Library + +inspect.Signature now supports parsing simple symbolic constants as +parameter default values in __text_signature__. + +.. + +.. bpo: 20072 +.. date: 9214 +.. nonce: FzVG15 +.. section: Library + +Fixed multiple errors in tkinter with wantobjects is False. + +.. + +.. bpo: 20229 +.. date: 9213 +.. nonce: WCDCjt +.. section: Library + +Avoid plistlib deprecation warning in platform.mac_ver(). + +.. + +.. bpo: 14455 +.. date: 9212 +.. nonce: CDaul1 +.. section: Library + +Fix some problems with the new binary plist support in plistlib. + +.. + +.. bpo: 17390 +.. date: 9211 +.. nonce: 9m6ZhV +.. section: IDLE + +Add Python version to Idle editor window title bar. Original patches by +Edmond Burnett and Kent Johnson. + +.. + +.. bpo: 18960 +.. date: 9210 +.. nonce: d87SuA +.. section: IDLE + +IDLE now ignores the source encoding declaration on the second line if the +first line contains anything except a comment. + +.. + +.. bpo: 20358 +.. date: 9209 +.. nonce: e2PP3S +.. section: Tests + +Tests for curses.window.overlay and curses.window.overwrite no longer +specify min{row,col} > max{row,col}. + +.. + +.. bpo: 19804 +.. date: 9208 +.. nonce: xIHIl7 +.. section: Tests + +The test_find_mac test in test_uuid is now skipped if the ifconfig +executable is not available. + +.. + +.. bpo: 19886 +.. date: 9207 +.. nonce: nqDFRC +.. section: Tests + +Use better estimated memory requirements for bigmem tests. + +.. + +.. bpo: 20390 +.. date: 9206 +.. nonce: QXEDu6 +.. section: Tools/Demos + +Argument Clinic's "file" output preset now defaults to +"{dirname}/clinic/{basename}.h". + +.. + +.. bpo: 20390 +.. date: 9205 +.. nonce: 7f_5Hn +.. section: Tools/Demos + +Argument Clinic's "class" directive syntax has been extended with two new +required arguments: "typedef" and "type_object". + +.. + +.. bpo: 20390 +.. date: 9204 +.. nonce: mDzhDq +.. section: Tools/Demos + +Argument Clinic: If __new__ or __init__ functions didn't use kwargs (or +args), the PyArg_NoKeywords (or PyArg_NoPositional) calls generated are only +run when the type object is an exact match. + +.. + +.. bpo: 20390 +.. date: 9203 +.. nonce: Feo6X8 +.. section: Tools/Demos + +Argument Clinic now fails if you have required parameters after optional +parameters. + +.. + +.. bpo: 20390 +.. date: 9202 +.. nonce: DrPQn0 +.. section: Tools/Demos + +Argument Clinic converters now have a new template they can inject code +into: "modifiers". Code put there is run in the parsing function after +argument parsing but before the call to the impl. + +.. + +.. bpo: 20376 +.. date: 9201 +.. nonce: Xq3E4A +.. section: Tools/Demos + +Argument Clinic now escapes backslashes in docstrings. + +.. + +.. bpo: 20381 +.. date: 9200 +.. nonce: _wqg4- +.. section: Tools/Demos + +Argument Clinic now sanity checks the default argument when c_default is +also specified, providing a nice failure message for disallowed values. + +.. + +.. bpo: 20189 +.. date: 9199 +.. nonce: zdiKDh +.. section: Tools/Demos + +Argument Clinic now ensures that parser functions for __new__ are always of +type newfunc, the type of the tp_new slot. Similarly, parser functions for +__init__ are now always of type initproc, the type of tp_init. + +.. + +.. bpo: 20189 +.. date: 9198 +.. nonce: a1Tfvj +.. section: Tools/Demos + +Argument Clinic now suppresses the docstring for __new__ and __init__ +functions if no docstring is provided in the input. + +.. + +.. bpo: 20189 +.. date: 9197 +.. nonce: uWF8XZ +.. section: Tools/Demos + +Argument Clinic now suppresses the "self" parameter in the impl for +@staticmethod functions. + +.. + +.. bpo: 20294 +.. date: 9196 +.. nonce: XeuO9b +.. section: Tools/Demos + +Argument Clinic now supports argument parsing for __new__ and __init__ +functions. + +.. + +.. bpo: 20299 +.. date: 9195 +.. nonce: yLslQI +.. section: Tools/Demos + +Argument Clinic custom converters may now change the default value of +c_default and py_default with a class member. + +.. + +.. bpo: 20287 +.. date: 9194 +.. nonce: ACjrv7 +.. section: Tools/Demos + +Argument Clinic's output is now configurable, allowing delaying its output +or even redirecting it to a separate file. + +.. + +.. bpo: 20226 +.. date: 9193 +.. nonce: GKAbRe +.. section: Tools/Demos + +Argument Clinic now permits simple expressions (e.g. "sys.maxsize - 1") as +default values for parameters. + +.. + +.. bpo: 19936 +.. date: 9192 +.. nonce: BLtXkq +.. section: Tools/Demos + +Added executable bits or shebang lines to Python scripts which requires +them. Disable executable bits and shebang lines in test and benchmark files +in order to prevent using a random system python, and in source files of +modules which don't provide command line interface. Fixed shebang lines in +the unittestgui and checkpip scripts. + +.. + +.. bpo: 20268 +.. date: 9191 +.. nonce: _-GWRe +.. section: Tools/Demos + +Argument Clinic now supports cloning the parameters and return converter of +existing functions. + +.. + +.. bpo: 20228 +.. date: 9190 +.. nonce: pQeW8t +.. section: Tools/Demos + +Argument Clinic now has special support for class special methods. + +.. + +.. bpo: 20214 +.. date: 9189 +.. nonce: OoBv_8 +.. section: Tools/Demos + +Fixed a number of small issues and documentation errors in Argument Clinic +(see issue for details). + +.. + +.. bpo: 20196 +.. date: 9188 +.. nonce: BhK2gF +.. section: Tools/Demos + +Fixed a bug where Argument Clinic did not generate correct parsing code for +functions with positional-only parameters where all arguments are optional. + +.. + +.. bpo: 18960 +.. date: 9187 +.. nonce: vONLqA +.. section: Tools/Demos + +2to3 and the findnocoding.py script now ignore the source encoding +declaration on the second line if the first line contains anything except a +comment. + +.. + +.. bpo: 19723 +.. date: 9186 +.. nonce: LApk5w +.. section: Tools/Demos + +The marker comments Argument Clinic uses have been changed to improve +readability. + +.. + +.. bpo: 20157 +.. date: 9185 +.. nonce: SvrlOc +.. section: Tools/Demos + +When Argument Clinic renames a parameter because its name collides with a C +keyword, it no longer exposes that rename to PyArg_Parse. + +.. + +.. bpo: 20141 +.. date: 9184 +.. nonce: uYixKR +.. section: Tools/Demos + +Improved Argument Clinic's support for the PyArg_Parse "O!" format unit. + +.. + +.. bpo: 20144 +.. date: 9183 +.. nonce: jUfrSz +.. section: Tools/Demos + +Argument Clinic now supports simple symbolic constants as parameter default +values. + +.. + +.. bpo: 20143 +.. date: 9182 +.. nonce: XvGuQk +.. section: Tools/Demos + +The line numbers reported in Argument Clinic errors are now more accurate. + +.. + +.. bpo: 20142 +.. date: 9181 +.. nonce: FdECT9 +.. section: Tools/Demos + +Py_buffer variables generated by Argument Clinic are now initialized with a +default value. + +.. + +.. bpo: 12837 +.. date: 9180 +.. nonce: nsgduf +.. section: Build + +Silence a tautological comparison warning on OS X under Clang in +socketmodule.c. diff --git a/Misc/NEWS.d/3.4.0rc1.rst b/Misc/NEWS.d/3.4.0rc1.rst new file mode 100644 index 00000000000000..65c237e8e16c24 --- /dev/null +++ b/Misc/NEWS.d/3.4.0rc1.rst @@ -0,0 +1,715 @@ +.. bpo: 19255 +.. date: 9315 +.. nonce: eED7PV +.. release date: 2014-02-10 +.. section: Core and Builtins + +The builtins module is restored to initial value before cleaning other +modules. The sys and builtins modules are cleaned last. + +.. + +.. bpo: 20588 +.. date: 9314 +.. nonce: Yibtu_ +.. section: Core and Builtins + +Make Python-ast.c C89 compliant. + +.. + +.. bpo: 20437 +.. date: 9313 +.. nonce: Dmstts +.. section: Core and Builtins + +Fixed 22 potential bugs when deleting objects references. + +.. + +.. bpo: 20500 +.. date: 9312 +.. nonce: BJiIvW +.. section: Core and Builtins + +Displaying an exception at interpreter shutdown no longer risks triggering +an assertion failure in PyObject_Str. + +.. + +.. bpo: 20538 +.. date: 9311 +.. nonce: 7FRDsi +.. section: Core and Builtins + +UTF-7 incremental decoder produced inconsistent string when input was +truncated in BASE64 section. + +.. + +.. bpo: 20404 +.. date: 9310 +.. nonce: 9dU6on +.. section: Core and Builtins + +io.TextIOWrapper (and hence the open() builtin) now uses the internal codec +marking system added for issue #19619 to throw LookupError for known non- +text encodings at stream construction time. The existing output type checks +remain in place to deal with unmarked third party codecs. + +.. + +.. bpo: 17162 +.. date: 9309 +.. nonce: p4Q-Hw +.. section: Core and Builtins + +Add PyType_GetSlot. + +.. + +.. bpo: 20162 +.. date: 9308 +.. nonce: u8qICT +.. section: Core and Builtins + +Fix an alignment issue in the siphash24() hash function which caused a crash +on PowerPC 64-bit (ppc64). + +.. + +.. bpo: 20530 +.. date: 9307 +.. nonce: LXsfhK +.. section: Library + +The signatures for slot builtins have been updated to reflect the fact that +they only accept positional-only arguments. + +.. + +.. bpo: 20517 +.. date: 9306 +.. nonce: 81zuY3 +.. section: Library + +Functions in the os module that accept two filenames now register both +filenames in the exception on failure. + +.. + +.. bpo: 20563 +.. date: 9305 +.. nonce: VTqHq5 +.. section: Library + +The ipaddress module API is now considered stable. + +.. + +.. bpo: 14983 +.. date: 9304 +.. nonce: H_gs8w +.. section: Library + +email.generator now always adds a line end after each MIME boundary marker, +instead of doing so only when there is an epilogue. This fixes an RFC +compliance bug and solves an issue with signed MIME parts. + +.. + +.. bpo: 20540 +.. date: 9303 +.. nonce: rhK6IW +.. section: Library + +Fix a performance regression (vs. Python 3.2) when layering a +multiprocessing Connection over a TCP socket. For small payloads, Nagle's +algorithm would introduce idle delays before the entire transmission of a +message. + +.. + +.. bpo: 16983 +.. date: 9302 +.. nonce: MoPgVQ +.. section: Library + +the new email header parsing code will now decode encoded words that are +(incorrectly) surrounded by quotes, and register a defect. + +.. + +.. bpo: 19772 +.. date: 9301 +.. nonce: pRi-Hm +.. section: Library + +email.generator no longer mutates the message object when doing a down- +transform from 8bit to 7bit CTEs. + +.. + +.. bpo: 20536 +.. date: 9300 +.. nonce: YWe5TG +.. section: Library + +the statistics module now correctly handle Decimal instances with positive +exponents + +.. + +.. bpo: 18805 +.. date: 9299 +.. nonce: fBdyY2 +.. section: Library + +the netmask/hostmask parsing in ipaddress now more reliably filters out +illegal values and correctly allows any valid prefix length. + +.. + +.. bpo: 20481 +.. date: 9298 +.. nonce: ycaV9P +.. section: Library + +For at least Python 3.4, the statistics module will require that all inputs +for a single operation be of a single consistent type, or else a mixed of +ints and a single other consistent type. This avoids some interoperability +issues that arose with the previous approach of coercing to a suitable +common type. + +.. + +.. bpo: 20478 +.. date: 9297 +.. nonce: LVoG5Q +.. section: Library + +the statistics module now treats collections.Counter inputs like any other +iterable. + +.. + +.. bpo: 17369 +.. date: 9296 +.. nonce: ZBFAd4 +.. section: Library + +get_filename was raising an exception if the filename parameter's RFC2231 +encoding was broken in certain ways. This was a regression relative to +python2. + +.. + +.. bpo: 20013 +.. date: 9295 +.. nonce: erNy8V +.. section: Library + +Some imap servers disconnect if the current mailbox is deleted, and imaplib +did not handle that case gracefully. Now it handles the 'bye' correctly. + +.. + +.. bpo: 20531 +.. date: 9294 +.. nonce: yz_zOY +.. section: Library + +Revert 3.4 version of fix for #19063, and apply the 3.3 version. That is, +do *not* raise an error if unicode is passed to +email.message.Message.set_payload. + +.. + +.. bpo: 20476 +.. date: 9293 +.. nonce: VhH-Lc +.. section: Library + +If a non-compat32 policy is used with any of the email parsers, EmailMessage +is now used as the factory class. The factory class should really come from +the policy; that will get fixed in 3.5. + +.. + +.. bpo: 19920 +.. date: 9292 +.. nonce: _fEm-X +.. section: Library + +TarFile.list() no longer fails when outputs a listing containing non- +encodable characters. Based on patch by Vajrasky Kok. + +.. + +.. bpo: 20515 +.. date: 9291 +.. nonce: JrEnar +.. section: Library + +Fix NULL pointer dereference introduced by issue #20368. + +.. + +.. bpo: 19186 +.. date: 9290 +.. nonce: cuiicK +.. section: Library + +Restore namespacing of expat symbols inside the pyexpat module. + +.. + +.. bpo: 20053 +.. date: 9289 +.. nonce: vy5u-i +.. section: Library + +ensurepip (and hence venv) are no longer affected by the settings in the +default pip configuration file. + +.. + +.. bpo: 20426 +.. date: 9288 +.. nonce: f0ozAP +.. section: Library + +When passing the re.DEBUG flag, re.compile() displays the debug output every +time it is called, regardless of the compilation cache. + +.. + +.. bpo: 20368 +.. date: 9287 +.. nonce: I8sm7u +.. section: Library + +The null character now correctly passed from Tcl to Python. Improved error +handling in variables-related commands. + +.. + +.. bpo: 20435 +.. date: 9286 +.. nonce: _UNhlH +.. section: Library + +Fix _pyio.StringIO.getvalue() to take into account newline translation +settings. + +.. + +.. bpo: 0 +.. date: 9285 +.. nonce: 2Jcf1f +.. section: Library + +tracemalloc: Fix slicing traces and fix slicing a traceback. + +.. + +.. bpo: 20354 +.. date: 9284 +.. nonce: kn2Ns9 +.. section: Library + +Fix an alignment issue in the tracemalloc module on 64-bit platforms. Bug +seen on 64-bit Linux when using "make profile-opt". + +.. + +.. bpo: 17159 +.. date: 9283 +.. nonce: c2P911 +.. section: Library + +inspect.signature now accepts duck types of functions, which adds support +for Cython functions. Initial patch by Stefan Behnel. + +.. + +.. bpo: 18801 +.. date: 9282 +.. nonce: Tm4jxb +.. section: Library + +Fix inspect.classify_class_attrs to correctly classify object.__new__ and +object.__init__. + +.. + +.. bpo: 0 +.. date: 9281 +.. nonce: 3eFjFu +.. section: Library + +Fixed cmath.isinf's name in its argument parsing code. + +.. + +.. bpo: 20311 +.. date: 9280 +.. nonce: f1lBLr +.. section: Library + +poll and epoll now round the timeout away from zero, instead of rounding +towards zero, in select and selectors modules: select.epoll.poll(), +selectors.PollSelector.poll() and selectors.EpollSelector.poll(). For +example, a timeout of one microsecond (1e-6) is now rounded to one +millisecondi (1e-3), instead of being rounded to zero. However, the +granularity property and asyncio's resolution feature were removed again. +(See also: bpo-20452) + +.. + +.. bpo: 0 +.. date: 9279 +.. nonce: qcxztP +.. section: Library + +asyncio: Some refactoring; various fixes; add write flow control to unix +pipes; Future.set_exception() instantiates the exception argument if it is a +class; improved proactor pipe transport; support wait_for(f, None); don't +log broken/disconnected pipes; use ValueError instead of assert for +forbidden subprocess_{shell,exec} arguments; added a convenience API for +subprocess management; added StreamReader.at_eof(); properly handle +duplicate coroutines/futures in gather(), wait(), as_completed(); use a +bytearray for buffering in StreamReader; and more. + +.. + +.. bpo: 20288 +.. date: 9278 +.. nonce: 6zUZe3 +.. section: Library + +fix handling of invalid numeric charrefs in HTMLParser. + +.. + +.. bpo: 20424 +.. date: 9277 +.. nonce: deh6LJ +.. section: Library + +Python implementation of io.StringIO now supports lone surrogates. + +.. + +.. bpo: 20308 +.. date: 9276 +.. nonce: lquugc +.. section: Library + +inspect.signature now works on classes without user-defined __init__ or +__new__ methods. + +.. + +.. bpo: 20372 +.. date: 9275 +.. nonce: Mn_S78 +.. section: Library + +inspect.getfile (and a bunch of other inspect functions that use it) doesn't +crash with unexpected AttributeError on classes defined in C without +__module__. + +.. + +.. bpo: 20356 +.. date: 9274 +.. nonce: rD04St +.. section: Library + +inspect.signature formatting uses '/' to separate positional-only parameters +from others. + +.. + +.. bpo: 20223 +.. date: 9273 +.. nonce: y3icbD +.. section: Library + +inspect.signature now supports methods defined with +functools.partialmethods. + +.. + +.. bpo: 19456 +.. date: 9272 +.. nonce: 6HhsFx +.. section: Library + +ntpath.join() now joins relative paths correctly when a drive is present. + +.. + +.. bpo: 19077 +.. date: 9271 +.. nonce: xrOYHl +.. section: Library + +tempfile.TemporaryDirectory cleanup no longer fails when called during +shutdown. Emitting resource warning in __del__ no longer fails. Original +patch by Antoine Pitrou. + +.. + +.. bpo: 20394 +.. date: 9270 +.. nonce: HzRZRc +.. section: Library + +Silence Coverity warning in audioop module. + +.. + +.. bpo: 20367 +.. date: 9269 +.. nonce: K0bFqf +.. section: Library + +Fix behavior of concurrent.futures.as_completed() for duplicate arguments. +Patch by Glenn Langford. + +.. + +.. bpo: 8260 +.. date: 9268 +.. nonce: nf7gg9 +.. section: Library + +The read(), readline() and readlines() methods of codecs.StreamReader +returned incomplete data when were called after readline() or read(size). +Based on patch by Amaury Forgeot d'Arc. + +.. + +.. bpo: 20105 +.. date: 9267 +.. nonce: foel6V +.. section: Library + +the codec exception chaining now correctly sets the traceback of the +original exception as its __traceback__ attribute. + +.. + +.. bpo: 17481 +.. date: 9266 +.. nonce: RrGlJS +.. section: Library + +inspect.getfullargspec() now uses inspect.signature() API. + +.. + +.. bpo: 15304 +.. date: 9265 +.. nonce: GfZ2Sa +.. section: Library + +concurrent.futures.wait() can block forever even if Futures have completed. +Patch by Glenn Langford. + +.. + +.. bpo: 14455 +.. date: 9264 +.. nonce: bk3GTQ +.. section: Library + +plistlib: fix serializing integers in the range of an unsigned long long but +outside of the range of signed long long for binary plist files. + +.. + +.. bpo: 20406 +.. date: 9263 +.. nonce: AgBe_5 +.. section: IDLE + +Use Python application icons for Idle window title bars. Patch mostly by +Serhiy Storchaka. + +.. + +.. bpo: 0 +.. date: 9262 +.. nonce: FTwP_j +.. section: IDLE + +Update the python.gif icon for the Idle classbrowser and pathbowser from the +old green snake to the new blue and yellow snakes. + +.. + +.. bpo: 17721 +.. date: 9261 +.. nonce: 8Jh8C1 +.. section: IDLE + +Remove non-functional configuration dialog help button until we make it +actually gives some help when clicked. Patch by Guilherme Simões. + +.. + +.. bpo: 20532 +.. date: 9260 +.. nonce: qsOt4d +.. section: Tests + +Tests which use _testcapi now are marked as CPython only. + +.. + +.. bpo: 19920 +.. date: 9259 +.. nonce: suOIC7 +.. section: Tests + +Added tests for TarFile.list(). Based on patch by Vajrasky Kok. + +.. + +.. bpo: 19990 +.. date: 9258 +.. nonce: Lp1MVj +.. section: Tests + +Added tests for the imghdr module. Based on patch by Claudiu Popa. + +.. + +.. bpo: 20474 +.. date: 9257 +.. nonce: Jm7xrk +.. section: Tests + +Fix test_socket "unexpected success" failures on OS X 10.7+. + +.. + +.. bpo: 20530 +.. date: 9256 +.. nonce: dqn540 +.. section: Tools/Demos + +Argument Clinic's signature format has been revised again. The new syntax is +highly human readable while still preventing false positives. The syntax +also extends Python syntax to denote "self" and positional-only parameters, +allowing inspect.Signature objects to be totally accurate for all supported +builtins in Python 3.4. + +.. + +.. bpo: 20456 +.. date: 9255 +.. nonce: RA_zxP +.. section: Tools/Demos + +Argument Clinic now observes the C preprocessor conditional compilation +statements of the C files it parses. When a Clinic block is inside a +conditional code, it adjusts its output to match, including automatically +generating an empty methoddef macro. + +.. + +.. bpo: 20456 +.. date: 9254 +.. nonce: tYeVw1 +.. section: Tools/Demos + +Cloned functions in Argument Clinic now use the correct name, not the name +of the function they were cloned from, for text strings inside generated +code. + +.. + +.. bpo: 20456 +.. date: 9253 +.. nonce: vG6PXO +.. section: Tools/Demos + +Fixed Argument Clinic's test suite and "--converters" feature. + +.. + +.. bpo: 20456 +.. date: 9252 +.. nonce: E-qgFP +.. section: Tools/Demos + +Argument Clinic now allows specifying different names for a parameter in +Python and C, using "as" on the parameter line. + +.. + +.. bpo: 20326 +.. date: 9251 +.. nonce: 1nRUAK +.. section: Tools/Demos + +Argument Clinic now uses a simple, unique signature to annotate text +signatures in docstrings, resulting in fewer false positives. "self" +parameters are also explicitly marked, allowing inspect.Signature() to +authoritatively detect (and skip) said parameters. + +.. + +.. bpo: 20326 +.. date: 9250 +.. nonce: eVlPqt +.. section: Tools/Demos + +Argument Clinic now generates separate checksums for the input and output +sections of the block, allowing external tools to verify that the input has +not changed (and thus the output is not out-of-date). + +.. + +.. bpo: 20465 +.. date: 9249 +.. nonce: 6xLtE3 +.. section: Build + +Update SQLite shipped with OS X installer to 3.8.3. + +.. + +.. bpo: 20517 +.. date: 9248 +.. nonce: PHWtoF +.. section: C API + +Added new functions allowing OSError exceptions to reference two filenames +instead of one: PyErr_SetFromErrnoWithFilenameObjects() and +PyErr_SetExcFromWindowsErrWithFilenameObjects(). + +.. + +.. bpo: 20488 +.. date: 9247 +.. nonce: csO04J +.. section: Documentation + +Change wording to say importlib is *the* implementation of import instead of +just *an* implementation. + +.. + +.. bpo: 6386 +.. date: 9246 +.. nonce: TO2sFS +.. section: Documentation + +Clarify in the tutorial that specifying a symlink to execute means the +directory containing the executed script and not the symlink is added to +sys.path. diff --git a/Misc/NEWS.d/3.4.0rc2.rst b/Misc/NEWS.d/3.4.0rc2.rst new file mode 100644 index 00000000000000..776715c82f0510 --- /dev/null +++ b/Misc/NEWS.d/3.4.0rc2.rst @@ -0,0 +1,177 @@ +.. bpo: 20625 +.. date: 9332 +.. nonce: IA5Cu9 +.. release date: 2014-02-23 +.. section: Core and Builtins + +Parameter names in __annotations__ were not mangled properly. Discovered by +Jonas Wielicki, patch by Yury Selivanov. + +.. + +.. bpo: 20261 +.. date: 9331 +.. nonce: xyA9tG +.. section: Core and Builtins + +In pickle, lookup __getnewargs__ and __getnewargs_ex__ on the type of the +object. + +.. + +.. bpo: 20619 +.. date: 9330 +.. nonce: GtdhSO +.. section: Core and Builtins + +Give the AST nodes of keyword-only arguments a column and line number. + +.. + +.. bpo: 20526 +.. date: 9329 +.. nonce: wZEy32 +.. section: Core and Builtins + +Revert changes of issue #19466 which introduces a regression: don't clear +anymore the state of Python threads early during the Python shutdown. + +.. + +.. bpo: 20710 +.. date: 9328 +.. nonce: byega8 +.. section: Library + +The pydoc summary line no longer displays the "self" parameter for bound +methods. + +.. + +.. bpo: 20566 +.. date: 9327 +.. nonce: R8yrPZ +.. section: Library + +Change asyncio.as_completed() to use a Queue, to avoid O(N**2) behavior. + +.. + +.. bpo: 20704 +.. date: 9326 +.. nonce: QQ4uy4 +.. section: Library + +Implement new debug API in asyncio. Add new methods +BaseEventLoop.set_debug() and BaseEventLoop.get_debug(). Add support for +setting 'asyncio.tasks._DEBUG' variable with 'PYTHONASYNCIODEBUG' +environment variable. + +.. + +.. bpo: 0 +.. date: 9325 +.. nonce: Ocnov- +.. section: Library + +asyncio: Refactoring and fixes: BaseEventLoop.sock_connect() raises an error +if the address is not resolved; use __slots__ in Handle and TimerHandle; +as_completed() and wait() raise TypeError if the passed list of Futures is a +single Future; call_soon() and other 'call_*()' functions raise TypeError if +the passed callback is a coroutine function; _ProactorBasePipeTransport uses +_FlowControlMixin; WriteTransport.set_write_buffer_size() calls +_maybe_pause_protocol() to consider pausing receiving if the watermark +limits have changed; fix _check_resolved_address() for IPv6 address; and +other minor improvements, along with multiple documentation updates. + +.. + +.. bpo: 20684 +.. date: 9324 +.. nonce: EArKf9 +.. section: Library + +Fix inspect.getfullargspec() to not to follow __wrapped__ chains. Make its +behaviour consistent with bound methods first argument. Patch by Nick +Coghlan and Yury Selivanov. + +.. + +.. bpo: 20681 +.. date: 9323 +.. nonce: O8EUu8 +.. section: Library + +Add new error handling API in asyncio. New APIs: +loop.set_exception_handler(), loop.default_exception_handler(), and +loop.call_exception_handler(). + +.. + +.. bpo: 20673 +.. date: 9322 +.. nonce: bLJpSo +.. section: Library + +Implement support for UNIX Domain Sockets in asyncio. New APIs: +loop.create_unix_connection(), loop.create_unix_server(), +streams.open_unix_connection(), and streams.start_unix_server(). + +.. + +.. bpo: 20616 +.. date: 9321 +.. nonce: 9fIygg +.. section: Library + +Add a format() method to tracemalloc.Traceback. + +.. + +.. bpo: 19744 +.. date: 9320 +.. nonce: fL4Brl +.. section: Library + +the ensurepip installation step now just prints a warning to stderr rather +than failing outright if SSL/TLS is unavailable. This allows local +installation of POSIX builds without SSL/TLS support. + +.. + +.. bpo: 20594 +.. date: 9319 +.. nonce: BVHxPd +.. section: Library + +Avoid name clash with the libc function posix_close. + +.. + +.. bpo: 20641 +.. date: 9318 +.. nonce: kAo-M- +.. section: Build + +Run MSI custom actions (pip installation, pyc compilation) with the +NoImpersonate flag, to support elevated execution (UAC). + +.. + +.. bpo: 20221 +.. date: 9317 +.. nonce: _yAetK +.. section: Build + +Removed conflicting (or circular) hypot definition when compiled with VS +2010 or above. Initial patch by Tabrez Mohammed. + +.. + +.. bpo: 20609 +.. date: 9316 +.. nonce: IMbrDQ +.. section: Build + +Restored the ability to build 64-bit Windows binaries on 32-bit Windows, +which was broken by the change in issue #19788. diff --git a/Misc/NEWS.d/3.4.0rc3.rst b/Misc/NEWS.d/3.4.0rc3.rst new file mode 100644 index 00000000000000..4e98334f7a0960 --- /dev/null +++ b/Misc/NEWS.d/3.4.0rc3.rst @@ -0,0 +1,66 @@ +.. bpo: 20786 +.. date: 9339 +.. nonce: M_2OYE +.. release date: 2014-03-09 +.. section: Core and Builtins + +Fix signatures for dict.__delitem__ and property.__delete__ builtins. + +.. + +.. bpo: 20839 +.. date: 9338 +.. nonce: SNn1MY +.. section: Library + +Don't trigger a DeprecationWarning in the still supported +pkgutil.get_loader() API when __loader__ isn't set on a module (nor when +pkgutil.find_loader() is called directly). + +.. + +.. bpo: 14512 +.. date: 9337 +.. nonce: y7vmx3 +.. section: Build + +Launch pydoc -b instead of pydocgui.pyw on Windows. + +.. + +.. bpo: 20748 +.. date: 9336 +.. nonce: HbDp_u +.. section: Build + +Uninstalling pip does not leave behind the pyc of the uninstaller anymore. + +.. + +.. bpo: 20568 +.. date: 9335 +.. nonce: ZvMU8d +.. section: Build + +The Windows installer now installs the unversioned ``pip`` command in +addition to the versioned ``pip3`` and ``pip3.4`` commands. + +.. + +.. bpo: 20757 +.. date: 9334 +.. nonce: BGFT6U +.. section: Build + +The ensurepip helper for the Windows uninstaller now skips uninstalling pip +(rather than failing) if the user has updated pip to a different version +from the one bundled with ensurepip. + +.. + +.. bpo: 20465 +.. date: 9333 +.. nonce: iemVBC +.. section: Build + +Update OS X and Windows installer builds to use SQLite 3.8.3.1. diff --git a/Misc/NEWS.d/3.4.1.rst b/Misc/NEWS.d/3.4.1.rst new file mode 100644 index 00000000000000..c6dfb71bd4fb34 --- /dev/null +++ b/Misc/NEWS.d/3.4.1.rst @@ -0,0 +1,117 @@ +.. bpo: 21418 +.. date: 9446 +.. nonce: z9jp1_ +.. release date: 2014-05-18 +.. section: Core and Builtins + +Fix a crash in the builtin function super() when called without argument and +without current frame (ex: embedded Python). + +.. + +.. bpo: 21425 +.. date: 9445 +.. nonce: i3Teb8 +.. section: Core and Builtins + +Fix flushing of standard streams in the interactive interpreter. + +.. + +.. bpo: 21435 +.. date: 9444 +.. nonce: ZojVOT +.. section: Core and Builtins + +In rare cases, when running finalizers on objects in cyclic trash a bad +pointer dereference could occur due to a subtle flaw in internal iteration +logic. + +.. + +.. bpo: 10744 +.. date: 9443 +.. nonce: kfV0wm +.. section: Library + +Fix PEP 3118 format strings on ctypes objects with a nontrivial shape. + +.. + +.. bpo: 20998 +.. date: 9442 +.. nonce: fkxpXI +.. section: Library + +Fixed re.fullmatch() of repeated single character pattern with ignore case. +Original patch by Matthew Barnett. + +.. + +.. bpo: 21075 +.. date: 9441 +.. nonce: f_hmEh +.. section: Library + +fileinput.FileInput now reads bytes from standard stream if binary mode is +specified. Patch by Sam Kimbrel. + +.. + +.. bpo: 21396 +.. date: 9440 +.. nonce: cqO6DN +.. section: Library + +Fix TextIOWrapper(..., write_through=True) to not force a flush() on the +underlying binary stream. Patch by akira. + +.. + +.. bpo: 21470 +.. date: 9439 +.. nonce: uH-yCD +.. section: Library + +Do a better job seeding the random number generator by using enough bytes to +span the full state space of the Mersenne Twister. + +.. + +.. bpo: 21398 +.. date: 9438 +.. nonce: nOXq5V +.. section: Library + +Fix an unicode error in the pydoc pager when the documentation contains +characters not encodable to the stdout encoding. + +.. + +.. bpo: 17756 +.. date: 9437 +.. nonce: LLfbfU +.. section: Tests + +Fix test_code test when run from the installed location. + +.. + +.. bpo: 17752 +.. date: 9436 +.. nonce: P8iG44 +.. section: Tests + +Fix distutils tests when run from the installed location. + +.. + +.. bpo: 18104 +.. date: 9435 +.. nonce: 8Fj9Pf +.. section: IDLE + +Add idlelib/idle_test/htest.py with a few sample tests to begin +consolidating and improving human-validated tests of Idle. Change other +files as needed to work with htest. Running the module as __main__ runs all +tests. diff --git a/Misc/NEWS.d/3.4.1rc1.rst b/Misc/NEWS.d/3.4.1rc1.rst new file mode 100644 index 00000000000000..3d1229e4cd9214 --- /dev/null +++ b/Misc/NEWS.d/3.4.1rc1.rst @@ -0,0 +1,913 @@ +.. bpo: 21274 +.. date: 9434 +.. nonce: fVGfwq +.. release date: 2014-05-05 +.. section: Core and Builtins + +Define PATH_MAX for GNU/Hurd in Python/pythonrun.c. + +.. + +.. bpo: 21209 +.. date: 9433 +.. nonce: nMljFr +.. section: Core and Builtins + +Fix sending tuples to custom generator objects with the yield from syntax. + +.. + +.. bpo: 21134 +.. date: 9432 +.. nonce: ZL4SKo +.. section: Core and Builtins + +Fix segfault when str is called on an uninitialized UnicodeEncodeError, +UnicodeDecodeError, or UnicodeTranslateError object. + +.. + +.. bpo: 19537 +.. date: 9431 +.. nonce: AkuC_J +.. section: Core and Builtins + +Fix PyUnicode_DATA() alignment under m68k. Patch by Andreas Schwab. + +.. + +.. bpo: 20929 +.. date: 9430 +.. nonce: 9NlUR7 +.. section: Core and Builtins + +Add a type cast to avoid shifting a negative number. + +.. + +.. bpo: 20731 +.. date: 9429 +.. nonce: _03SZg +.. section: Core and Builtins + +Properly position in source code files even if they are opened in text mode. +Patch by Serhiy Storchaka. + +.. + +.. bpo: 20637 +.. date: 9428 +.. nonce: ppYU0o +.. section: Core and Builtins + +Key-sharing now also works for instance dictionaries of subclasses. Patch +by Peter Ingebretson. + +.. + +.. bpo: 12546 +.. date: 9427 +.. nonce: 09naZ9 +.. section: Core and Builtins + +Allow ``\x00`` to be used as a fill character when using str, int, float, +and complex __format__ methods. + +.. + +.. bpo: 13598 +.. date: 9426 +.. nonce: GJelrw +.. section: Core and Builtins + +Modify string.Formatter to support auto-numbering of replacement fields. It +now matches the behavior of str.format() in this regard. Patches by Phil +Elson and Ramchandra Apte. + +.. + +.. bpo: 21088 +.. date: 9425 +.. nonce: WOg7Xy +.. section: Library + +Bugfix for curses.window.addch() regression in 3.4.0. In porting to Argument +Clinic, the first two arguments were reversed. + +.. + +.. bpo: 21469 +.. date: 9424 +.. nonce: _fFGuq +.. section: Library + +Reduced the risk of false positives in robotparser by checking to make sure +that robots.txt has been read or does not exist prior to returning True in +can_fetch(). + +.. + +.. bpo: 21321 +.. date: 9423 +.. nonce: wUkTON +.. section: Library + +itertools.islice() now releases the reference to the source iterator when +the slice is exhausted. Patch by Anton Afanasyev. + +.. + +.. bpo: 9815 +.. date: 9422 +.. nonce: 52FPlI +.. section: Library + +assertRaises now tries to clear references to local variables in the +exception's traceback. + +.. + +.. bpo: 13204 +.. date: 9421 +.. nonce: ZPKA5g +.. section: Library + +Calling sys.flags.__new__ would crash the interpreter, now it raises a +TypeError. + +.. + +.. bpo: 19385 +.. date: 9420 +.. nonce: PexO_g +.. section: Library + +Make operations on a closed dbm.dumb database always raise the same +exception. + +.. + +.. bpo: 21207 +.. date: 9419 +.. nonce: Hr72AB +.. section: Library + +Detect when the os.urandom cached fd has been closed or replaced, and open +it anew. + +.. + +.. bpo: 21291 +.. date: 9418 +.. nonce: 5sSLWN +.. section: Library + +subprocess's Popen.wait() is now thread safe so that multiple threads may be +calling wait() or poll() on a Popen instance at the same time without losing +the Popen.returncode value. + +.. + +.. bpo: 21127 +.. date: 9417 +.. nonce: A1aBjG +.. section: Library + +Path objects can now be instantiated from str subclass instances (such as +``numpy.str_``). + +.. + +.. bpo: 15002 +.. date: 9416 +.. nonce: qorYDe +.. section: Library + +urllib.response object to use _TemporaryFileWrapper (and +_TemporaryFileCloser) facility. Provides a better way to handle file +descriptor close. Patch contributed by Christian Theune. + +.. + +.. bpo: 12220 +.. date: 9415 +.. nonce: U25uE9 +.. section: Library + +mindom now raises a custom ValueError indicating it doesn't support spaces +in URIs instead of letting a 'split' ValueError bubble up. + +.. + +.. bpo: 21239 +.. date: 9414 +.. nonce: EalCNt +.. section: Library + +patch.stopall() didn't work deterministically when the same name was patched +more than once. + +.. + +.. bpo: 21222 +.. date: 9413 +.. nonce: G6MQBP +.. section: Library + +Passing name keyword argument to mock.create_autospec now works. + +.. + +.. bpo: 21197 +.. date: 9412 +.. nonce: Gzfqdl +.. section: Library + +Add lib64 -> lib symlink in venvs on 64-bit non-OS X POSIX. + +.. + +.. bpo: 17498 +.. date: 9411 +.. nonce: LR9xyb +.. section: Library + +Some SMTP servers disconnect after certain errors, violating strict RFC +conformance. Instead of losing the error code when we issue the subsequent +RSET, smtplib now returns the error code and defers raising the +SMTPServerDisconnected error until the next command is issued. + +.. + +.. bpo: 17826 +.. date: 9410 +.. nonce: z0zMRV +.. section: Library + +setting an iterable side_effect on a mock function created by +create_autospec now works. Patch by Kushal Das. + +.. + +.. bpo: 7776 +.. date: 9409 +.. nonce: K5S2Pe +.. section: Library + +Fix ``Host:`` header and reconnection when using +http.client.HTTPConnection.set_tunnel(). Patch by Nikolaus Rath. + +.. + +.. bpo: 20968 +.. date: 9408 +.. nonce: 53Aagz +.. section: Library + +unittest.mock.MagicMock now supports division. Patch by Johannes Baiter. + +.. + +.. bpo: 21529 +.. date: 9407 +.. nonce: 57R_Fc +.. section: Library + +Fix arbitrary memory access in JSONDecoder.raw_decode with a negative second +parameter. Bug reported by Guido Vranken. (See also: CVE-2014-4616) + +.. + +.. bpo: 21169 +.. date: 9406 +.. nonce: KE7B0M +.. section: Library + +getpass now handles non-ascii characters that the input stream encoding +cannot encode by re-encoding using the replace error handler. + +.. + +.. bpo: 21171 +.. date: 9405 +.. nonce: iUbV9S +.. section: Library + +Fixed undocumented filter API of the rot13 codec. Patch by Berker Peksag. + +.. + +.. bpo: 21172 +.. date: 9404 +.. nonce: dQ7yY7 +.. section: Library + +isinstance check relaxed from dict to collections.Mapping. + +.. + +.. bpo: 21155 +.. date: 9403 +.. nonce: JSKEE7 +.. section: Library + +asyncio.EventLoop.create_unix_server() now raises a ValueError if path and +sock are specified at the same time. + +.. + +.. bpo: 21149 +.. date: 9402 +.. nonce: cnjwMR +.. section: Library + +Improved thread-safety in logging cleanup during interpreter shutdown. +Thanks to Devin Jeanpierre for the patch. + +.. + +.. bpo: 20145 +.. date: 9401 +.. nonce: FP5FY0 +.. section: Library + +`assertRaisesRegex` and `assertWarnsRegex` now raise a TypeError if the +second argument is not a string or compiled regex. + +.. + +.. bpo: 21058 +.. date: 9400 +.. nonce: IhluPP +.. section: Library + +Fix a leak of file descriptor in :func:`tempfile.NamedTemporaryFile`, close +the file descriptor if :func:`io.open` fails + +.. + +.. bpo: 21200 +.. date: 9399 +.. nonce: Kht8yD +.. section: Library + +Return None from pkgutil.get_loader() when __spec__ is missing. + +.. + +.. bpo: 21013 +.. date: 9398 +.. nonce: 3s8Ic0 +.. section: Library + +Enhance ssl.create_default_context() when used for server side sockets to +provide better security by default. + +.. + +.. bpo: 20633 +.. date: 9397 +.. nonce: 6kaPjT +.. section: Library + +Replace relative import by absolute import. + +.. + +.. bpo: 20980 +.. date: 9396 +.. nonce: cYszHY +.. section: Library + +Stop wrapping exception when using ThreadPool. + +.. + +.. bpo: 21082 +.. date: 9395 +.. nonce: GLzGlV +.. section: Library + +In os.makedirs, do not set the process-wide umask. Note this changes +behavior of makedirs when exist_ok=True. + +.. + +.. bpo: 20990 +.. date: 9394 +.. nonce: PBfjW3 +.. section: Library + +Fix issues found by pyflakes for multiprocessing. + +.. + +.. bpo: 21015 +.. date: 9393 +.. nonce: xnwWAH +.. section: Library + +SSL contexts will now automatically select an elliptic curve for ECDH key +exchange on OpenSSL 1.0.2 and later, and otherwise default to "prime256v1". + +.. + +.. bpo: 20995 +.. date: 9392 +.. nonce: YfhicZ +.. section: Library + +Enhance default ciphers used by the ssl module to enable better security an +prioritize perfect forward secrecy. + +.. + +.. bpo: 20884 +.. date: 9391 +.. nonce: qNmub_ +.. section: Library + +Don't assume that __file__ is defined on importlib.__init__. + +.. + +.. bpo: 21499 +.. date: 9390 +.. nonce: wU4OBi +.. section: Library + +Ignore __builtins__ in several test_importlib.test_api tests. + +.. + +.. bpo: 20879 +.. date: 9389 +.. nonce: myeYdq +.. section: Library + +Delay the initialization of encoding and decoding tables for base32, ascii85 +and base85 codecs in the base64 module, and delay the initialization of the +unquote_to_bytes() table of the urllib.parse module, to not waste memory if +these modules are not used. + +.. + +.. bpo: 19157 +.. date: 9388 +.. nonce: V1-XhC +.. section: Library + +Include the broadcast address in the usuable hosts for IPv6 in ipaddress. + +.. + +.. bpo: 11599 +.. date: 9387 +.. nonce: 9QOXf4 +.. section: Library + +When an external command (e.g. compiler) fails, distutils now prints out the +whole command line (instead of just the command name) if the environment +variable DISTUTILS_DEBUG is set. + +.. + +.. bpo: 4931 +.. date: 9386 +.. nonce: uF10hr +.. section: Library + +distutils should not produce unhelpful "error: None" messages anymore. +distutils.util.grok_environment_error is kept but doc-deprecated. + +.. + +.. bpo: 20875 +.. date: 9385 +.. nonce: IjfI5V +.. section: Library + +Prevent possible gzip "'read' is not defined" NameError. Patch by Claudiu +Popa. + +.. + +.. bpo: 11558 +.. date: 9384 +.. nonce: pxrsmq +.. section: Library + +``email.message.Message.attach`` now returns a more useful error message if +``attach`` is called on a message for which ``is_multipart`` is False. + +.. + +.. bpo: 20283 +.. date: 9383 +.. nonce: v0Vs9V +.. section: Library + +RE pattern methods now accept the string keyword parameters as documented. +The pattern and source keyword parameters are left as deprecated aliases. + +.. + +.. bpo: 20778 +.. date: 9382 +.. nonce: g_fAGI +.. section: Library + +Fix modulefinder to work with bytecode-only modules. + +.. + +.. bpo: 20791 +.. date: 9381 +.. nonce: n_zrkc +.. section: Library + +copy.copy() now doesn't make a copy when the input is a bytes object. +Initial patch by Peter Otten. + +.. + +.. bpo: 19748 +.. date: 9380 +.. nonce: kiA171 +.. section: Library + +On AIX, time.mktime() now raises an OverflowError for year outsize range +[1902; 2037]. + +.. + +.. bpo: 20816 +.. date: 9379 +.. nonce: DFMEgN +.. section: Library + +Fix inspect.getcallargs() to raise correct TypeError for missing keyword- +only arguments. Patch by Jeremiah Lowin. + +.. + +.. bpo: 20817 +.. date: 9378 +.. nonce: O5XyZB +.. section: Library + +Fix inspect.getcallargs() to fail correctly if more than 3 arguments are +missing. Patch by Jeremiah Lowin. + +.. + +.. bpo: 6676 +.. date: 9377 +.. nonce: CJu5On +.. section: Library + +Ensure a meaningful exception is raised when attempting to parse more than +one XML document per pyexpat xmlparser instance. (Original patches by +Hirokazu Yamamoto and Amaury Forgeot d'Arc, with suggested wording by David +Gutteridge) + +.. + +.. bpo: 21117 +.. date: 9376 +.. nonce: hyH7EK +.. section: Library + +Fix inspect.signature to better support functools.partial. Due to the +specifics of functools.partial implementation, positional-or-keyword +arguments passed as keyword arguments become keyword-only. + +.. + +.. bpo: 21209 +.. date: 9375 +.. nonce: wRE7Dn +.. section: Library + +Fix asyncio.tasks.CoroWrapper to workaround a bug in yield-from +implementation in CPythons prior to 3.4.1. + +.. + +.. bpo: 0 +.. date: 9374 +.. nonce: Q1I78Z +.. section: Library + +asyncio: Add gi_{frame,running,code} properties to CoroWrapper (upstream +issue #163). + +.. + +.. bpo: 21311 +.. date: 9373 +.. nonce: JsDF8H +.. section: Library + +Avoid exception in _osx_support with non-standard compiler configurations. +Patch by John Szakmeister. + +.. + +.. bpo: 11571 +.. date: 9372 +.. nonce: RPeGNo +.. section: Library + +Ensure that the turtle window becomes the topmost window when launched on OS +X. + +.. + +.. bpo: 21276 +.. date: 9371 +.. nonce: JkfhvQ +.. section: Library + +posixmodule: Don't define USE_XATTRS on KFreeBSD and the Hurd. + +.. + +.. bpo: 21226 +.. date: 9370 +.. nonce: pzGmG1 +.. section: Library + +Set up modules properly in PyImport_ExecCodeModuleObject (and friends). + +.. + +.. bpo: 21139 +.. date: 9369 +.. nonce: kqetng +.. section: IDLE + +Change default paragraph width to 72, the PEP 8 recommendation. + +.. + +.. bpo: 21284 +.. date: 9368 +.. nonce: KKJfmv +.. section: IDLE + +Paragraph reformat test passes after user changes reformat width. + +.. + +.. bpo: 17654 +.. date: 9367 +.. nonce: NbzhNS +.. section: IDLE + +Ensure IDLE menus are customized properly on OS X for non-framework builds +and for all variants of Tk. + +.. + +.. bpo: 0 +.. date: 9366 +.. nonce: QfpS73 +.. section: Build + +The Windows build now includes OpenSSL 1.0.1g + +.. + +.. bpo: 21285 +.. date: 9365 +.. nonce: cU9p2E +.. section: Build + +Refactor and fix curses configure check to always search in a ncursesw +directory. + +.. + +.. bpo: 15234 +.. date: 9364 +.. nonce: vlM720 +.. section: Build + +For BerkelyDB and Sqlite, only add the found library and include directories +if they aren't already being searched. This avoids an explicit runtime +library dependency. + +.. + +.. bpo: 20644 +.. date: 9363 +.. nonce: aV0zq7 +.. section: Build + +OS X installer build support for documentation build changes in 3.4.1: +assume externally supplied sphinx-build is available in /usr/bin. + +.. + +.. bpo: 20942 +.. date: 9362 +.. nonce: qHLJ5- +.. section: C API + +PyImport_ImportFrozenModuleObject() no longer sets __file__ to match what +importlib does; this affects _frozen_importlib as well as any module loaded +using imp.init_frozen(). + +.. + +.. bpo: 17386 +.. date: 9361 +.. nonce: ivaGLb +.. section: Documentation + +Expanded functionality of the ``Doc/make.bat`` script to make it much more +comparable to ``Doc/Makefile``. + +.. + +.. bpo: 21043 +.. date: 9360 +.. nonce: oEOC8O +.. section: Documentation + +Remove the recommendation for specific CA organizations and to mention the +ability to load the OS certificates. + +.. + +.. bpo: 20765 +.. date: 9359 +.. nonce: Rv3GgV +.. section: Documentation + +Add missing documentation for PurePath.with_name() and +PurePath.with_suffix(). + +.. + +.. bpo: 19407 +.. date: 9358 +.. nonce: mRyNnG +.. section: Documentation + +New package installation and distribution guides based on the Python +Packaging Authority tools. Existing guides have been retained as legacy +links from the distutils docs, as they still contain some required reference +material for tool developers that isn't recorded anywhere else. + +.. + +.. bpo: 19697 +.. date: 9357 +.. nonce: 2jMQBP +.. section: Documentation + +Document cases where __main__.__spec__ is None. + +.. + +.. bpo: 18604 +.. date: 9356 +.. nonce: Q00Xrj +.. section: Tests + +Consolidated checks for GUI availability. All platforms now at least check +whether Tk can be instantiated when the GUI resource is requested. + +.. + +.. bpo: 21275 +.. date: 9355 +.. nonce: lI5FkX +.. section: Tests + +Fix a socket test on KFreeBSD. + +.. + +.. bpo: 21223 +.. date: 9354 +.. nonce: lMY6ka +.. section: Tests + +Pass test_site/test_startup_imports when some of the extensions are built as +builtins. + +.. + +.. bpo: 20635 +.. date: 9353 +.. nonce: mzWmoS +.. section: Tests + +Added tests for Tk geometry managers. + +.. + +.. bpo: 0 +.. date: 9352 +.. nonce: E5XNqr +.. section: Tests + +Add test case for freeze. + +.. + +.. bpo: 20743 +.. date: 9351 +.. nonce: hxZQUf +.. section: Tests + +Fix a reference leak in test_tcl. + +.. + +.. bpo: 21097 +.. date: 9350 +.. nonce: gsUesm +.. section: Tests + +Move test_namespace_pkgs into test_importlib. + +.. + +.. bpo: 20939 +.. date: 9349 +.. nonce: x3KQ35 +.. section: Tests + +Avoid various network test failures due to new redirect of +http://www.python.org/ to https://www.python.org: use http://www.example.com +instead. + +.. + +.. bpo: 20668 +.. date: 9348 +.. nonce: IWjOSC +.. section: Tests + +asyncio tests no longer rely on tests.txt file. (Patch by Vajrasky Kok) + +.. + +.. bpo: 21093 +.. date: 9347 +.. nonce: CcpRim +.. section: Tests + +Prevent failures of ctypes test_macholib on OS X if a copy of libz exists in +$HOME/lib or /usr/local/lib. + +.. + +.. bpo: 0 +.. date: 9346 +.. nonce: _-ge-g +.. section: Tools/Demos + +Add support for ``yield from`` to 2to3. + +.. + +.. bpo: 0 +.. date: 9345 +.. nonce: dpFbyZ +.. section: Tools/Demos + +Add support for the PEP 465 matrix multiplication operator to 2to3. + +.. + +.. bpo: 16047 +.. date: 9344 +.. nonce: IsgTzm +.. section: Tools/Demos + +Fix module exception list and __file__ handling in freeze. Patch by Meador +Inge. + +.. + +.. bpo: 11824 +.. date: 9343 +.. nonce: OBWc3T +.. section: Tools/Demos + +Consider ABI tags in freeze. Patch by Meador Inge. + +.. + +.. bpo: 20535 +.. date: 9342 +.. nonce: 0qkvZZ +.. section: Tools/Demos + +PYTHONWARNING no longer affects the run_tests.py script. Patch by Arfrever +Frehtes Taifersar Arahesis. diff --git a/Misc/NEWS.d/3.4.2.rst b/Misc/NEWS.d/3.4.2.rst new file mode 100644 index 00000000000000..eb9544d0c9f476 --- /dev/null +++ b/Misc/NEWS.d/3.4.2.rst @@ -0,0 +1,77 @@ +.. bpo: 10510 +.. date: 9589 +.. nonce: N-ntcD +.. release date: 2014-10-06 +.. section: Library + +distutils register and upload methods now use HTML standards compliant CRLF +line endings. + +.. + +.. bpo: 9850 +.. date: 9588 +.. nonce: D-UnVi +.. section: Library + +Fixed macpath.join() for empty first component. Patch by Oleg Oshmyan. + +.. + +.. bpo: 22427 +.. date: 9587 +.. nonce: TZ5S_u +.. section: Library + +TemporaryDirectory no longer attempts to clean up twice when used in the +with statement in generator. + +.. + +.. bpo: 20912 +.. date: 9586 +.. nonce: cAq3mZ +.. section: Library + +Now directories added to ZIP file have correct Unix and MS-DOS directory +attributes. + +.. + +.. bpo: 21866 +.. date: 9585 +.. nonce: hSc4wM +.. section: Library + +ZipFile.close() no longer writes ZIP64 central directory records if +allowZip64 is false. + +.. + +.. bpo: 22415 +.. date: 9584 +.. nonce: xJLAvI +.. section: Library + +Fixed debugging output of the GROUPREF_EXISTS opcode in the re module. +Removed trailing spaces in debugging output. + +.. + +.. bpo: 22423 +.. date: 9583 +.. nonce: Rtb4oT +.. section: Library + +Unhandled exception in thread no longer causes unhandled AttributeError when +sys.stderr is None. + +.. + +.. bpo: 21332 +.. date: 9582 +.. nonce: Gwxwlr +.. section: Library + +Ensure that ``bufsize=1`` in subprocess.Popen() selects line buffering, +rather than block buffering. Patch by Akira Li. diff --git a/Misc/NEWS.d/3.4.2rc1.rst b/Misc/NEWS.d/3.4.2rc1.rst new file mode 100644 index 00000000000000..219eaa00d784a0 --- /dev/null +++ b/Misc/NEWS.d/3.4.2rc1.rst @@ -0,0 +1,1332 @@ +.. bpo: 22258 +.. date: 9581 +.. nonce: tVwANS +.. release date: 2014-09-22 +.. section: Core and Builtins + +Fix the the internal function set_inheritable() on Illumos. This platform +exposes the function ``ioctl(FIOCLEX)``, but calling it fails with errno is +ENOTTY: "Inappropriate ioctl for device". set_inheritable() now falls back +to the slower ``fcntl()`` (``F_GETFD`` and then ``F_SETFD``). + +.. + +.. bpo: 21669 +.. date: 9580 +.. nonce: DFDrBA +.. section: Core and Builtins + +With the aid of heuristics in SyntaxError.__init__, the parser now attempts +to generate more meaningful (or at least more search engine friendly) error +messages when "exec" and "print" are used as statements. + +.. + +.. bpo: 21642 +.. date: 9579 +.. nonce: -lWoKz +.. section: Core and Builtins + +In the conditional if-else expression, allow an integer written with no +space between itself and the ``else`` keyword (e.g. ``True if 42else +False``) to be valid syntax. + +.. + +.. bpo: 21523 +.. date: 9578 +.. nonce: f_PPYO +.. section: Core and Builtins + +Fix over-pessimistic computation of the stack effect of some opcodes in the +compiler. This also fixes a quadratic compilation time issue noticeable +when compiling code with a large number of "and" and "or" operators. + +.. + +.. bpo: 21091 +.. date: 9577 +.. nonce: uNtYPQ +.. section: Library + +Fix API bug: email.message.EmailMessage.is_attachment is now a method. +Since EmailMessage is provisional, we can change the API in a maintenance +release, but we use a trick to remain backward compatible with 3.4.0/1. + +.. + +.. bpo: 21079 +.. date: 9576 +.. nonce: czVcL8 +.. section: Library + +Fix email.message.EmailMessage.is_attachment to return the correct result +when the header has parameters as well as a value. + +.. + +.. bpo: 22247 +.. date: 9575 +.. nonce: sGIpR3 +.. section: Library + +Add NNTPError to nntplib.__all__. + +.. + +.. bpo: 4180 +.. date: 9574 +.. nonce: QBx0JK +.. section: Library + +The warnings registries are now reset when the filters are modified. + +.. + +.. bpo: 22419 +.. date: 9573 +.. nonce: FqH4aC +.. section: Library + +Limit the length of incoming HTTP request in wsgiref server to 65536 bytes +and send a 414 error code for higher lengths. Patch contributed by Devin +Cook. + +.. + +.. bpo: 0 +.. date: 9572 +.. nonce: y7r3O2 +.. section: Library + +Lax cookie parsing in http.cookies could be a security issue when combined +with non-standard cookie handling in some Web browsers. Reported by Sergey +Bobrov. + +.. + +.. bpo: 22384 +.. date: 9571 +.. nonce: -Nl4He +.. section: Library + +An exception in Tkinter callback no longer crashes the program when it is +run with pythonw.exe. + +.. + +.. bpo: 22168 +.. date: 9570 +.. nonce: vLeKWC +.. section: Library + +Prevent turtle AttributeError with non-default Canvas on OS X. + +.. + +.. bpo: 21147 +.. date: 9569 +.. nonce: kXNoOn +.. section: Library + +sqlite3 now raises an exception if the request contains a null character +instead of truncate it. Based on patch by Victor Stinner. + +.. + +.. bpo: 21951 +.. date: 9568 +.. nonce: 3vS4LK +.. section: Library + +Fixed a crash in Tkinter on AIX when called Tcl command with empty string or +tuple argument. + +.. + +.. bpo: 21951 +.. date: 9567 +.. nonce: _CCC4v +.. section: Library + +Tkinter now most likely raises MemoryError instead of crash if the memory +allocation fails. + +.. + +.. bpo: 22338 +.. date: 9566 +.. nonce: rKlCMz +.. section: Library + +Fix a crash in the json module on memory allocation failure. + +.. + +.. bpo: 22226 +.. date: 9565 +.. nonce: T1ZMPY +.. section: Library + +First letter no longer is stripped from the "status" key in the result of +Treeview.heading(). + +.. + +.. bpo: 19524 +.. date: 9564 +.. nonce: EQJjlF +.. section: Library + +Fixed resource leak in the HTTP connection when an invalid response is +received. Patch by Martin Panter. + +.. + +.. bpo: 22051 +.. date: 9563 +.. nonce: cUjFqL +.. section: Library + +turtledemo no longer reloads examples to re-run them. Initialization of +variables and gui setup should be done in main(), which is called each time +a demo is run, but not on import. + +.. + +.. bpo: 21933 +.. date: 9562 +.. nonce: IhMjN1 +.. section: Library + +Turtledemo users can change the code font size with a menu selection or +control(command) '-' or '+' or control-mousewheel. Original patch by Lita +Cho. + +.. + +.. bpo: 21597 +.. date: 9561 +.. nonce: aPTCWJ +.. section: Library + +The separator between the turtledemo text pane and the drawing canvas can +now be grabbed and dragged with a mouse. The code text pane can be widened +to easily view or copy the full width of the text. The canvas can be +widened on small screens. Original patches by Jan Kanis and Lita Cho. + +.. + +.. bpo: 18132 +.. date: 9560 +.. nonce: 2R2nwM +.. section: Library + +Turtledemo buttons no longer disappear when the window is shrunk. Original +patches by Jan Kanis and Lita Cho. + +.. + +.. bpo: 22216 +.. date: 9559 +.. nonce: Cmalu6 +.. section: Library + +smtplib now resets its state more completely after a quit. The most obvious +consequence of the previous behavior was a STARTTLS failure during a +connect/starttls/quit/connect/starttls sequence. + +.. + +.. bpo: 22185 +.. date: 9558 +.. nonce: 1SCCIK +.. section: Library + +Fix an occasional RuntimeError in threading.Condition.wait() caused by +mutation of the waiters queue without holding the lock. Patch by Doug +Zongker. + +.. + +.. bpo: 22182 +.. date: 9557 +.. nonce: 5EG1Bc +.. section: Library + +Use e.args to unpack exceptions correctly in distutils.file_util.move_file. +Patch by Claudiu Popa. + +.. + +.. bpo: 0 +.. date: 9556 +.. nonce: zBfe8J +.. section: Library + +The webbrowser module now uses subprocess's start_new_session=True rather +than a potentially risky preexec_fn=os.setsid call. + +.. + +.. bpo: 22236 +.. date: 9555 +.. nonce: 1utXkg +.. section: Library + +Fixed Tkinter images copying operations in NoDefaultRoot mode. + +.. + +.. bpo: 22191 +.. date: 9554 +.. nonce: PWX4GO +.. section: Library + +Fix warnings.__all__. + +.. + +.. bpo: 15696 +.. date: 9553 +.. nonce: PTwXYJ +.. section: Library + +Add a __sizeof__ implementation for mmap objects on Windows. + +.. + +.. bpo: 22068 +.. date: 9552 +.. nonce: wCdaW0 +.. section: Library + +Avoided reference loops with Variables and Fonts in Tkinter. + +.. + +.. bpo: 22165 +.. date: 9551 +.. nonce: J1np4o +.. section: Library + +SimpleHTTPRequestHandler now supports undecodable file names. + +.. + +.. bpo: 8797 +.. date: 9550 +.. nonce: aJcIPu +.. section: Library + +Raise HTTPError on failed Basic Authentication immediately. Initial patch by +Sam Bull. + +.. + +.. bpo: 20729 +.. date: 9549 +.. nonce: I-1Lap +.. section: Library + +Restored the use of lazy iterkeys()/itervalues()/iteritems() in the mailbox +module. + +.. + +.. bpo: 21448 +.. date: 9548 +.. nonce: THJSYB +.. section: Library + +Changed FeedParser feed() to avoid O(N**2) behavior when parsing long line. +Original patch by Raymond Hettinger. + +.. + +.. bpo: 22184 +.. date: 9547 +.. nonce: UCbSOt +.. section: Library + +The functools LRU Cache decorator factory now gives an earlier and clearer +error message when the user forgets the required parameters. + +.. + +.. bpo: 17923 +.. date: 9546 +.. nonce: YI_QjG +.. section: Library + +glob() patterns ending with a slash no longer match non-dirs on AIX. Based +on patch by Delhallt. + +.. + +.. bpo: 21121 +.. date: 9545 +.. nonce: ZLsRil +.. section: Library + +Don't force 3rd party C extensions to be built with -Werror=declaration- +after-statement. + +.. + +.. bpo: 21975 +.. date: 9544 +.. nonce: MI8ntO +.. section: Library + +Fixed crash when using uninitialized sqlite3.Row (in particular when +unpickling pickled sqlite3.Row). sqlite3.Row is now initialized in the +__new__() method. + +.. + +.. bpo: 21580 +.. date: 9543 +.. nonce: QCkeUh +.. section: Library + +Now Tkinter correctly handles bytes arguments passed to Tk. In particular +this allows to initialize images from binary data. + +.. + +.. bpo: 17172 +.. date: 9542 +.. nonce: R_LI_2 +.. section: Library + +Make turtledemo start as active on OS X even when run with subprocess. +Patch by Lita Cho. + +.. + +.. bpo: 21704 +.. date: 9541 +.. nonce: gL3ikj +.. section: Library + +Fix build error for _multiprocessing when semaphores are not available. +Patch by Arfrever Frehtes Taifersar Arahesis. + +.. + +.. bpo: 0 +.. date: 9540 +.. nonce: G25tq3 +.. section: Library + +Fix repr(_socket.socket) on Windows 64-bit: don't fail with OverflowError on +closed socket. repr(socket.socket) already works fine. + +.. + +.. bpo: 16133 +.. date: 9539 +.. nonce: tYuYQF +.. section: Library + +The asynchat.async_chat.handle_read() method now ignores BlockingIOError +exceptions. + +.. + +.. bpo: 22044 +.. date: 9538 +.. nonce: t09GRU +.. section: Library + +Fixed premature DECREF in call_tzinfo_method. Patch by Tom Flanagan. + +.. + +.. bpo: 19884 +.. date: 9537 +.. nonce: 6cbo0V +.. section: Library + +readline: Disable the meta modifier key if stdout is not a terminal to not +write the ANSI sequence "\033[1034h" into stdout. This sequence is used on +some terminal (ex: TERM=xterm-256color") to enable support of 8 bit +characters. + +.. + +.. bpo: 21888 +.. date: 9536 +.. nonce: danlpz +.. section: Library + +plistlib's load() and loads() now work if the fmt parameter is specified. + +.. + +.. bpo: 21044 +.. date: 9535 +.. nonce: 16xo9u +.. section: Library + +tarfile.open() now handles fileobj with an integer 'name' attribute. Based +on patch by Antoine Pietri. + +.. + +.. bpo: 21867 +.. date: 9534 +.. nonce: Ui-F3o +.. section: Library + +Prevent turtle crash due to invalid undo buffer size. + +.. + +.. bpo: 19076 +.. date: 9533 +.. nonce: xCoIai +.. section: Library + +Don't pass the redundant 'file' argument to self.error(). + +.. + +.. bpo: 21942 +.. date: 9532 +.. nonce: TLOS41 +.. section: Library + +Fixed source file viewing in pydoc's server mode on Windows. + +.. + +.. bpo: 11259 +.. date: 9531 +.. nonce: GxfYnE +.. section: Library + +asynchat.async_chat().set_terminator() now raises a ValueError if the number +of received bytes is negative. + +.. + +.. bpo: 12523 +.. date: 9530 +.. nonce: XBdAky +.. section: Library + +asynchat.async_chat.push() now raises a TypeError if it doesn't get a bytes +string + +.. + +.. bpo: 21707 +.. date: 9529 +.. nonce: rrY_wd +.. section: Library + +Add missing kwonlyargcount argument to ModuleFinder.replace_paths_in_code(). + +.. + +.. bpo: 20639 +.. date: 9528 +.. nonce: YdvOpp +.. section: Library + +calling Path.with_suffix('') allows removing the suffix again. Patch by +July Tikhonov. + +.. + +.. bpo: 21714 +.. date: 9527 +.. nonce: HhkGXW +.. section: Library + +Disallow the construction of invalid paths using Path.with_name(). Original +patch by Antony Lee. + +.. + +.. bpo: 21897 +.. date: 9526 +.. nonce: kiOGHe +.. section: Library + +Fix a crash with the f_locals attribute with closure variables when +frame.clear() has been called. + +.. + +.. bpo: 21151 +.. date: 9525 +.. nonce: o7IuiD +.. section: Library + +Fixed a segfault in the winreg module when ``None`` is passed as a +``REG_BINARY`` value to SetValueEx. Patch by John Ehresman. + +.. + +.. bpo: 21090 +.. date: 9524 +.. nonce: 20Ooif +.. section: Library + +io.FileIO.readall() does not ignore I/O errors anymore. Before, it ignored +I/O errors if at least the first C call read() succeed. + +.. + +.. bpo: 21781 +.. date: 9523 +.. nonce: u_oiv9 +.. section: Library + +ssl.RAND_add() now supports strings longer than 2 GB. + +.. + +.. bpo: 11453 +.. date: 9522 +.. nonce: 53Gr_R +.. section: Library + +asyncore: emit a ResourceWarning when an unclosed file_wrapper object is +destroyed. The destructor now closes the file if needed. The close() method +can now be called twice: the second call does nothing. + +.. + +.. bpo: 21858 +.. date: 9521 +.. nonce: 0hbFBG +.. section: Library + +Better handling of Python exceptions in the sqlite3 module. + +.. + +.. bpo: 21476 +.. date: 9520 +.. nonce: VN-5pW +.. section: Library + +Make sure the email.parser.BytesParser TextIOWrapper is discarded after +parsing, so the input file isn't unexpectedly closed. + +.. + +.. bpo: 21729 +.. date: 9519 +.. nonce: dk7o_U +.. section: Library + +Used the "with" statement in the dbm.dumb module to ensure files closing. +Patch by Claudiu Popa. + +.. + +.. bpo: 21491 +.. date: 9518 +.. nonce: Zxmut- +.. section: Library + +socketserver: Fix a race condition in child processes reaping. + +.. + +.. bpo: 21832 +.. date: 9517 +.. nonce: PBA0Uu +.. section: Library + +Require named tuple inputs to be exact strings. + +.. + +.. bpo: 19145 +.. date: 9516 +.. nonce: cRrKpW +.. section: Library + +The times argument for itertools.repeat now handles negative values the same +way for keyword arguments as it does for positional arguments. + +.. + +.. bpo: 21812 +.. date: 9515 +.. nonce: 6T4FsQ +.. section: Library + +turtle.shapetransform did not tranform the turtle on the first call. (Issue +identified and fixed by Lita Cho.) + +.. + +.. bpo: 21635 +.. date: 9514 +.. nonce: ET3OJZ +.. section: Library + +The difflib SequenceMatcher.get_matching_blocks() method cache didn't match +the actual result. The former was a list of tuples and the latter was a +list of named tuples. + +.. + +.. bpo: 21722 +.. date: 9513 +.. nonce: WTHuRy +.. section: Library + +The distutils "upload" command now exits with a non-zero return code when +uploading fails. Patch by Martin Dengler. + +.. + +.. bpo: 21723 +.. date: 9512 +.. nonce: r86fwb +.. section: Library + +asyncio.Queue: support any type of number (ex: float) for the maximum size. +Patch written by Vajrasky Kok. + +.. + +.. bpo: 21326 +.. date: 9511 +.. nonce: Y6iW3s +.. section: Library + +Add a new is_closed() method to asyncio.BaseEventLoop. run_forever() and +run_until_complete() methods of asyncio.BaseEventLoop now raise an exception +if the event loop was closed. + +.. + +.. bpo: 21774 +.. date: 9510 +.. nonce: vxORUY +.. section: Library + +Fixed NameError for an incorrect variable reference in the XML Minidom code +for creating processing instructions. (Found and fixed by Claudiu Popa.) + +.. + +.. bpo: 21766 +.. date: 9509 +.. nonce: 0xk_xC +.. section: Library + +Prevent a security hole in CGIHTTPServer by URL unquoting paths before +checking for a CGI script at that path. + +.. + +.. bpo: 21310 +.. date: 9508 +.. nonce: 2mjByJ +.. section: Library + +Fixed possible resource leak in failed open(). + +.. + +.. bpo: 21677 +.. date: 9507 +.. nonce: 58CDDD +.. section: Library + +Fixed chaining nonnormalized exceptions in io close() methods. + +.. + +.. bpo: 11709 +.. date: 9506 +.. nonce: JdObvL +.. section: Library + +Fix the pydoc.help function to not fail when sys.stdin is not a valid file. + +.. + +.. bpo: 13223 +.. date: 9505 +.. nonce: 9AzEbN +.. section: Library + +Fix pydoc.writedoc so that the HTML documentation for methods that use +'self' in the example code is generated correctly. + +.. + +.. bpo: 21463 +.. date: 9504 +.. nonce: 09PsgH +.. section: Library + +In urllib.request, fix pruning of the FTP cache. + +.. + +.. bpo: 21618 +.. date: 9503 +.. nonce: 3Z7WS3 +.. section: Library + +The subprocess module could fail to close open fds that were inherited by +the calling process and already higher than POSIX resource limits would +otherwise allow. On systems with a functioning /proc/self/fd or /dev/fd +interface the max is now ignored and all fds are closed. + +.. + +.. bpo: 21552 +.. date: 9502 +.. nonce: uVy4tM +.. section: Library + +Fixed possible integer overflow of too long string lengths in the tkinter +module on 64-bit platforms. + +.. + +.. bpo: 14315 +.. date: 9501 +.. nonce: YzZzS8 +.. section: Library + +The zipfile module now ignores extra fields in the central directory that +are too short to be parsed instead of letting a struct.unpack error bubble +up as this "bad data" appears in many real world zip files in the wild and +is ignored by other zip tools. + +.. + +.. bpo: 21402 +.. date: 9500 +.. nonce: 51vDXt +.. section: Library + +tkinter.ttk now works when default root window is not set. + +.. + +.. bpo: 10203 +.. date: 9499 +.. nonce: zgr0hh +.. section: Library + +sqlite3.Row now truly supports sequence protocol. In particular it supports +reverse() and negative indices. Original patch by Claudiu Popa. + +.. + +.. bpo: 18807 +.. date: 9498 +.. nonce: XP7p8B +.. section: Library + +If copying (no symlinks) specified for a venv, then the python interpreter +aliases (python, python3) are now created by copying rather than symlinking. + +.. + +.. bpo: 14710 +.. date: 9497 +.. nonce: x7-soG +.. section: Library + +pkgutil.get_loader() no longer raises an exception when None is found in +sys.modules. + +.. + +.. bpo: 14710 +.. date: 9496 +.. nonce: ZWaxa5 +.. section: Library + +pkgutil.find_loader() no longer raises an exception when a module doesn't +exist. + +.. + +.. bpo: 21481 +.. date: 9495 +.. nonce: YDrlf7 +.. section: Library + +Argparse equality and inequality tests now return NotImplemented when +comparing to an unknown type. + +.. + +.. bpo: 8743 +.. date: 9494 +.. nonce: I6_2r3 +.. section: Library + +Fix interoperability between set objects and the collections.Set() abstract +base class. + +.. + +.. bpo: 13355 +.. date: 9493 +.. nonce: gCByXK +.. section: Library + +random.triangular() no longer fails with a ZeroDivisionError when low equals +high. + +.. + +.. bpo: 21538 +.. date: 9492 +.. nonce: Q60FWA +.. section: Library + +The plistlib module now supports loading of binary plist files when +reference or offset size is not a power of two. + +.. + +.. bpo: 21801 +.. date: 9491 +.. nonce: rzfhYl +.. section: Library + +Validate that __signature__ is None or an instance of Signature. + +.. + +.. bpo: 21923 +.. date: 9490 +.. nonce: hXnoZa +.. section: Library + +Prevent AttributeError in distutils.sysconfig.customize_compiler due to +possible uninitialized _config_vars. + +.. + +.. bpo: 21323 +.. date: 9489 +.. nonce: quiWfl +.. section: Library + +Fix http.server to again handle scripts in CGI subdirectories, broken by the +fix for security issue #19435. Patch by Zach Byrne. + +.. + +.. bpo: 22176 +.. date: 9488 +.. nonce: rgbRyg +.. section: Library + +Update the ctypes module's libffi to v3.1. This release adds support for +the Linux AArch64 and POWERPC ELF ABIv2 little endian architectures. + +.. + +.. bpo: 15661 +.. date: 9487 +.. nonce: i1O-4J +.. section: Build + +python.org OS X installers are now distributed as signed installer packages +compatible with the Gatekeeper security feature. + +.. + +.. bpo: 21958 +.. date: 9486 +.. nonce: 3rq4qR +.. section: Build + +Define HAVE_ROUND when building with Visual Studio 2013 and above. Patch by +Zachary Turner. + +.. + +.. bpo: 15759 +.. date: 9485 +.. nonce: iGLR6O +.. section: Build + +"make suspicious", "make linkcheck" and "make doctest" in Doc/ now display +special message when and only when there are failures. + +.. + +.. bpo: 17095 +.. date: 9484 +.. nonce: -XEBIU +.. section: Build + +Fix Modules/Setup *shared* support. + +.. + +.. bpo: 21811 +.. date: 9483 +.. nonce: 3_Xyr- +.. section: Build + +Anticipated fixes to support OS X versions > 10.9. + +.. + +.. bpo: 21166 +.. date: 9482 +.. nonce: KAl7aO +.. section: Build + +Prevent possible segfaults and other random failures of python --generate- +posix-vars in pybuilddir.txt build target. + +.. + +.. bpo: 17390 +.. date: 9481 +.. nonce: I4vHFh +.. section: IDLE + +Adjust Editor window title; remove 'Python', move version to end. + +.. + +.. bpo: 14105 +.. date: 9480 +.. nonce: 0YozkO +.. section: IDLE + +Idle debugger breakpoints no longer disappear when inseting or deleting +lines. + +.. + +.. bpo: 17172 +.. date: 9479 +.. nonce: R8jkU1 +.. section: IDLE + +Turtledemo can now be run from Idle. Currently, the entry is on the Help +menu, but it may move to Run. Patch by Ramchandra Apt and Lita Cho. + +.. + +.. bpo: 21765 +.. date: 9478 +.. nonce: JyiDbd +.. section: IDLE + +Add support for non-ascii identifiers to HyperParser. + +.. + +.. bpo: 21940 +.. date: 9477 +.. nonce: VlIRz7 +.. section: IDLE + +Add unittest for WidgetRedirector. Initial patch by Saimadhav Heblikar. + +.. + +.. bpo: 18592 +.. date: 9476 +.. nonce: sMG-SZ +.. section: IDLE + +Add unittest for SearchDialogBase. Patch by Phil Webster. + +.. + +.. bpo: 21694 +.. date: 9475 +.. nonce: 1oLmRo +.. section: IDLE + +Add unittest for ParenMatch. Patch by Saimadhav Heblikar. + +.. + +.. bpo: 21686 +.. date: 9474 +.. nonce: TAkFB0 +.. section: IDLE + +add unittest for HyperParser. Original patch by Saimadhav Heblikar. + +.. + +.. bpo: 12387 +.. date: 9473 +.. nonce: XO7Ozk +.. section: IDLE + +Add missing upper(lower)case versions of default Windows key bindings for +Idle so Caps Lock does not disable them. Patch by Roger Serwy. + +.. + +.. bpo: 21695 +.. date: 9472 +.. nonce: g-t0Tm +.. section: IDLE + +Closing a Find-in-files output window while the search is still in progress +no longer closes Idle. + +.. + +.. bpo: 18910 +.. date: 9471 +.. nonce: ke8lMK +.. section: IDLE + +Add unittest for textView. Patch by Phil Webster. + +.. + +.. bpo: 18292 +.. date: 9470 +.. nonce: ks_3wm +.. section: IDLE + +Add unittest for AutoExpand. Patch by Saihadhav Heblikar. + +.. + +.. bpo: 18409 +.. date: 9469 +.. nonce: 7fe-aK +.. section: IDLE + +Add unittest for AutoComplete. Patch by Phil Webster. + +.. + +.. bpo: 22166 +.. date: 9468 +.. nonce: sZYhmv +.. section: Tests + +With the assistance of a new internal _codecs._forget_codec helping +function, test_codecs now clears the encoding caches to avoid the appearance +of a reference leak + +.. + +.. bpo: 22236 +.. date: 9467 +.. nonce: ginJSI +.. section: Tests + +Tkinter tests now don't reuse default root window. New root window is +created for every test class. + +.. + +.. bpo: 20746 +.. date: 9466 +.. nonce: N2pzAY +.. section: Tests + +Fix test_pdb to run in refleak mode (-R). Patch by Xavier de Gaye. + +.. + +.. bpo: 22060 +.. date: 9465 +.. nonce: TduJNO +.. section: Tests + +test_ctypes has been somewhat cleaned up and simplified; it now uses +unittest test discovery to find its tests. + +.. + +.. bpo: 22104 +.. date: 9464 +.. nonce: -YYDup +.. section: Tests + +regrtest.py no longer holds a reference to the suite of tests loaded from +test modules that don't define test_main(). + +.. + +.. bpo: 22002 +.. date: 9463 +.. nonce: jpiaA2 +.. section: Tests + +Added ``load_package_tests`` function to test.support and used it to +implement/augment test discovery in test_asyncio, test_email, +test_importlib, test_json, and test_tools. + +.. + +.. bpo: 21976 +.. date: 9462 +.. nonce: Slq6se +.. section: Tests + +Fix test_ssl to accept LibreSSL version strings. Thanks to William Orr. + +.. + +.. bpo: 21918 +.. date: 9461 +.. nonce: QTFFSj +.. section: Tests + +Converted test_tools from a module to a package containing separate test +files for each tested script. + +.. + +.. bpo: 20155 +.. date: 9460 +.. nonce: nphzS3 +.. section: Tests + +Changed HTTP method names in failing tests in test_httpservers so that +packet filtering software (specifically Windows Base Filtering Engine) does +not interfere with the transaction semantics expected by the tests. + +.. + +.. bpo: 19493 +.. date: 9459 +.. nonce: SwbzLQ +.. section: Tests + +Refactored the ctypes test package to skip tests explicitly rather than +silently. + +.. + +.. bpo: 18492 +.. date: 9458 +.. nonce: ylPRU7 +.. section: Tests + +All resources are now allowed when tests are not run by regrtest.py. + +.. + +.. bpo: 21634 +.. date: 9457 +.. nonce: Eng06F +.. section: Tests + +Fix pystone micro-benchmark: use floor division instead of true division to +benchmark integers instead of floating point numbers. Set pystone version to +1.2. Patch written by Lennart Regebro. + +.. + +.. bpo: 21605 +.. date: 9456 +.. nonce: qsLV8d +.. section: Tests + +Added tests for Tkinter images. + +.. + +.. bpo: 21493 +.. date: 9455 +.. nonce: NqhRsy +.. section: Tests + +Added test for ntpath.expanduser(). Original patch by Claudiu Popa. + +.. + +.. bpo: 19925 +.. date: 9454 +.. nonce: dhMx08 +.. section: Tests + +Added tests for the spwd module. Original patch by Vajrasky Kok. + +.. + +.. bpo: 21522 +.. date: 9453 +.. nonce: b-VwFW +.. section: Tests + +Added Tkinter tests for Listbox.itemconfigure(), +PanedWindow.paneconfigure(), and Menu.entryconfigure(). + +.. + +.. bpo: 21777 +.. date: 9452 +.. nonce: dtQCWV +.. section: Documentation + +The binary sequence methods on bytes and bytearray are now documented +explicitly, rather than assuming users will be able to derive the expected +behaviour from the behaviour of the corresponding str methods. + +.. + +.. bpo: 21671 +.. date: 9451 +.. nonce: LvzZ52 +.. section: Windows + +The bundled version of OpenSSL has been updated to 1.0.1i. (See also: +bpo-22160, CVE-2014-0224) + +.. + +.. bpo: 10747 +.. date: 9450 +.. nonce: LTWhLn +.. section: Windows + +Use versioned labels in the Windows start menu. Patch by Olive Kilburn. + +.. + +.. bpo: 22201 +.. date: 9449 +.. nonce: k1Awbh +.. section: Tools/Demos + +Command-line interface of the zipfile module now correctly extracts ZIP +files with directory entries. Patch by Ryan Wilson. + +.. + +.. bpo: 21906 +.. date: 9448 +.. nonce: ZsKy9v +.. section: Tools/Demos + +Make Tools/scripts/md5sum.py work in Python 3. Patch by Zachary Ware. + +.. + +.. bpo: 21629 +.. date: 9447 +.. nonce: 9kZmQl +.. section: Tools/Demos + +Fix Argument Clinic's "--converters" feature. diff --git a/Misc/NEWS.d/3.4.3.rst b/Misc/NEWS.d/3.4.3.rst new file mode 100644 index 00000000000000..69de3267b7fe69 --- /dev/null +++ b/Misc/NEWS.d/3.4.3.rst @@ -0,0 +1,1238 @@ +.. bpo: 22735 +.. date: 9717 +.. nonce: mFEX9n +.. release date: 2015-02-23 +.. section: Core and Builtins + +Fix many edge cases (including crashes) involving custom mro() +implementations. + +.. + +.. bpo: 22896 +.. date: 9716 +.. nonce: xSDAHK +.. section: Core and Builtins + +Avoid using PyObject_AsCharBuffer(), PyObject_AsReadBuffer() and +PyObject_AsWriteBuffer(). + +.. + +.. bpo: 21295 +.. date: 9715 +.. nonce: LYq9nF +.. section: Core and Builtins + +Revert some changes (issue #16795) to AST line numbers and column offsets +that constituted a regression. + +.. + +.. bpo: 21408 +.. date: 9714 +.. nonce: Lz6P3P +.. section: Core and Builtins + +The default __ne__() now returns NotImplemented if __eq__() returned +NotImplemented. Original patch by Martin Panter. + +.. + +.. bpo: 23321 +.. date: 9713 +.. nonce: HQelge +.. section: Core and Builtins + +Fixed a crash in str.decode() when error handler returned replacment string +longer than mailformed input data. + +.. + +.. bpo: 23048 +.. date: 9712 +.. nonce: X5BUd3 +.. section: Core and Builtins + +Fix jumping out of an infinite while loop in the pdb. + +.. + +.. bpo: 20335 +.. date: 9711 +.. nonce: YcAPOs +.. section: Core and Builtins + +bytes constructor now raises TypeError when encoding or errors is specified +with non-string argument. Based on patch by Renaud Blanch. + +.. + +.. bpo: 22335 +.. date: 9710 +.. nonce: DWsXiy +.. section: Core and Builtins + +Fix crash when trying to enlarge a bytearray to 0x7fffffff bytes on a 32-bit +platform. + +.. + +.. bpo: 22653 +.. date: 9709 +.. nonce: pCNlpv +.. section: Core and Builtins + +Fix an assertion failure in debug mode when doing a reentrant dict insertion +in debug mode. + +.. + +.. bpo: 22643 +.. date: 9708 +.. nonce: xv8xev +.. section: Core and Builtins + +Fix integer overflow in Unicode case operations (upper, lower, title, +swapcase, casefold). + +.. + +.. bpo: 22604 +.. date: 9707 +.. nonce: yii-It +.. section: Core and Builtins + +Fix assertion error in debug mode when dividing a complex number by +(nan+0j). + +.. + +.. bpo: 22470 +.. date: 9706 +.. nonce: igrgN2 +.. section: Core and Builtins + +Fixed integer overflow issues in "backslashreplace", "xmlcharrefreplace", +and "surrogatepass" error handlers. + +.. + +.. bpo: 22520 +.. date: 9705 +.. nonce: ZPJXSq +.. section: Core and Builtins + +Fix overflow checking when generating the repr of a unicode object. + +.. + +.. bpo: 22519 +.. date: 9704 +.. nonce: xvJVg0 +.. section: Core and Builtins + +Fix overflow checking in PyBytes_Repr. + +.. + +.. bpo: 22518 +.. date: 9703 +.. nonce: C9T6ed +.. section: Core and Builtins + +Fix integer overflow issues in latin-1 encoding. + +.. + +.. bpo: 23165 +.. date: 9702 +.. nonce: lk8uCE +.. section: Core and Builtins + +Perform overflow checks before allocating memory in the _Py_char2wchar +function. + +.. + +.. bpo: 23399 +.. date: 9701 +.. nonce: hXMYgA +.. section: Library + +pyvenv creates relative symlinks where possible. + +.. + +.. bpo: 23099 +.. date: 9700 +.. nonce: ZASrUo +.. section: Library + +Closing io.BytesIO with exported buffer is rejected now to prevent +corrupting exported buffer. + +.. + +.. bpo: 23363 +.. date: 9699 +.. nonce: -koaol +.. section: Library + +Fix possible overflow in itertools.permutations. + +.. + +.. bpo: 23364 +.. date: 9698 +.. nonce: 3yBV-6 +.. section: Library + +Fix possible overflow in itertools.product. + +.. + +.. bpo: 23366 +.. date: 9697 +.. nonce: tyAfm8 +.. section: Library + +Fixed possible integer overflow in itertools.combinations. + +.. + +.. bpo: 23369 +.. date: 9696 +.. nonce: nqChyE +.. section: Library + +Fixed possible integer overflow in _json.encode_basestring_ascii. + +.. + +.. bpo: 23353 +.. date: 9695 +.. nonce: Iytkpc +.. section: Library + +Fix the exception handling of generators in PyEval_EvalFrameEx(). At entry, +save or swap the exception state even if PyEval_EvalFrameEx() is called with +throwflag=0. At exit, the exception state is now always restored or swapped, +not only if why is WHY_YIELD or WHY_RETURN. Patch co-written with Antoine +Pitrou. + +.. + +.. bpo: 18518 +.. date: 9694 +.. nonce: JXgicC +.. section: Library + +timeit now rejects statements which can't be compiled outside a function or +a loop (e.g. "return" or "break"). + +.. + +.. bpo: 23094 +.. date: 9693 +.. nonce: -8AXSi +.. section: Library + +Fixed readline with frames in Python implementation of pickle. + +.. + +.. bpo: 23268 +.. date: 9692 +.. nonce: ATtRa5 +.. section: Library + +Fixed bugs in the comparison of ipaddress classes. + +.. + +.. bpo: 21408 +.. date: 9691 +.. nonce: 0rI6tx +.. section: Library + +Removed incorrect implementations of __ne__() which didn't returned +NotImplemented if __eq__() returned NotImplemented. The default __ne__() +now works correctly. + +.. + +.. bpo: 19996 +.. date: 9690 +.. nonce: 2-SiMf +.. section: Library + +:class:`email.feedparser.FeedParser` now handles (malformed) headers with no +key rather than assuming the body has started. + +.. + +.. bpo: 23248 +.. date: 9689 +.. nonce: FjcyCP +.. section: Library + +Update ssl error codes from latest OpenSSL git master. + +.. + +.. bpo: 23098 +.. date: 9688 +.. nonce: 7VwF3K +.. section: Library + +64-bit dev_t is now supported in the os module. + +.. + +.. bpo: 23250 +.. date: 9687 +.. nonce: qNGAUf +.. section: Library + +In the http.cookies module, capitalize "HttpOnly" and "Secure" as they are +written in the standard. + +.. + +.. bpo: 23063 +.. date: 9686 +.. nonce: 9-UJRs +.. section: Library + +In the disutils' check command, fix parsing of reST with code or code-block +directives. + +.. + +.. bpo: 23209 +.. date: 9685 +.. nonce: IXUHjK +.. section: Library + +selectors.BaseSelector.close() now clears its internal reference to the +selector mapping to break a reference cycle. Initial patch written by Martin +Richard. (See also: bpo-23225) + +.. + +.. bpo: 21356 +.. date: 9684 +.. nonce: 8NY75J +.. section: Library + +Make ssl.RAND_egd() optional to support LibreSSL. The availability of the +function is checked during the compilation. Patch written by Bernard Spil. + +.. + +.. bpo: 20896 +.. date: 9683 +.. nonce: jg267Y +.. section: Library + +The :func:`ssl.get_server_certificate` function now uses the +:data:`~ssl.PROTOCOL_SSLv23` protocol by default, not +:data:`~ssl.PROTOCOL_SSLv3`, for maximum compatibility and support platforms +where :data:`~ssl.PROTOCOL_SSLv3` support is disabled. (See also: bpo-22935) + +.. + +.. bpo: 23111 +.. date: 9682 +.. nonce: A34IA4 +.. section: Library + +In the ftplib, make ssl.PROTOCOL_SSLv23 the default protocol version. + +.. + +.. bpo: 23132 +.. date: 9681 +.. nonce: KpXKjm +.. section: Library + +Mitigate regression in speed and clarity in functools.total_ordering. + +.. + +.. bpo: 22585 +.. date: 9680 +.. nonce: F4BkNo +.. section: Library + +On OpenBSD 5.6 and newer, os.urandom() now calls getentropy(), instead of +reading /dev/urandom, to get pseudo-random bytes. + +.. + +.. bpo: 23112 +.. date: 9679 +.. nonce: dZGf82 +.. section: Library + +Fix SimpleHTTPServer to correctly carry the query string and fragment when +it redirects to add a trailing slash. + +.. + +.. bpo: 23093 +.. date: 9678 +.. nonce: cP7OqD +.. section: Library + +In the io, module allow more operations to work on detached streams. + +.. + +.. bpo: 19104 +.. date: 9677 +.. nonce: _eIThy +.. section: Library + +pprint now produces evaluable output for wrapped strings. + +.. + +.. bpo: 23071 +.. date: 9676 +.. nonce: 3BSqF7 +.. section: Library + +Added missing names to codecs.__all__. Patch by Martin Panter. + +.. + +.. bpo: 15513 +.. date: 9675 +.. nonce: 7yVnRE +.. section: Library + +Added a __sizeof__ implementation for pickle classes. + +.. + +.. bpo: 19858 +.. date: 9674 +.. nonce: cqOlIt +.. section: Library + +pickletools.optimize() now aware of the MEMOIZE opcode, can produce more +compact result and no longer produces invalid output if input data contains +MEMOIZE opcodes together with PUT or BINPUT opcodes. + +.. + +.. bpo: 22095 +.. date: 9673 +.. nonce: iISzxM +.. section: Library + +Fixed HTTPConnection.set_tunnel with default port. The port value in the +host header was set to "None". Patch by Demian Brecht. + +.. + +.. bpo: 23016 +.. date: 9672 +.. nonce: LyrPd_ +.. section: Library + +A warning no longer produces an AttributeError when the program is run with +pythonw.exe. + +.. + +.. bpo: 21775 +.. date: 9671 +.. nonce: Lg9w0U +.. section: Library + +shutil.copytree(): fix crash when copying to VFAT. An exception handler +assumed that that OSError objects always have a 'winerror' attribute. That +is not the case, so the exception handler itself raised AttributeError when +run on Linux (and, presumably, any other non-Windows OS). Patch by Greg +Ward. + +.. + +.. bpo: 1218234 +.. date: 9670 +.. nonce: 4GcoQK +.. section: Library + +Fix inspect.getsource() to load updated source of reloaded module. Initial +patch by Berker Peksag. + +.. + +.. bpo: 22959 +.. date: 9669 +.. nonce: Vxt3EP +.. section: Library + +In the constructor of http.client.HTTPSConnection, prefer the context's +check_hostname attribute over the *check_hostname* parameter. + +.. + +.. bpo: 16043 +.. date: 9668 +.. nonce: TGIC7t +.. section: Library + +Add a default limit for the amount of data xmlrpclib.gzip_decode will +return. This resolves CVE-2013-1753. + +.. + +.. bpo: 22966 +.. date: 9667 +.. nonce: zIxDrT +.. section: Library + +Fix __pycache__ pyc file name clobber when pyc_compile is asked to compile a +source file containing multiple dots in the source file name. + +.. + +.. bpo: 21971 +.. date: 9666 +.. nonce: XlTc22 +.. section: Library + +Update turtledemo doc and add module to the index. + +.. + +.. bpo: 21032 +.. date: 9665 +.. nonce: wxT_41 +.. section: Library + +Fixed socket leak if HTTPConnection.getresponse() fails. Original patch by +Martin Panter. + +.. + +.. bpo: 22960 +.. date: 9664 +.. nonce: 2VDILT +.. section: Library + +Add a context argument to xmlrpclib.ServerProxy constructor. + +.. + +.. bpo: 22915 +.. date: 9663 +.. nonce: 709UAo +.. section: Library + +SAX parser now supports files opened with file descriptor or bytes path. + +.. + +.. bpo: 22609 +.. date: 9662 +.. nonce: mmLoeb +.. section: Library + +Constructors and update methods of mapping classes in the collections module +now accept the self keyword argument. + +.. + +.. bpo: 22788 +.. date: 9661 +.. nonce: vofL9e +.. section: Library + +Add *context* parameter to logging.handlers.HTTPHandler. + +.. + +.. bpo: 22921 +.. date: 9660 +.. nonce: a4wx1C +.. section: Library + +Allow SSLContext to take the *hostname* parameter even if OpenSSL doesn't +support SNI. + +.. + +.. bpo: 22894 +.. date: 9659 +.. nonce: 4AkwPA +.. section: Library + +TestCase.subTest() would cause the test suite to be stopped when in failfast +mode, even in the absence of failures. + +.. + +.. bpo: 22638 +.. date: 9658 +.. nonce: Ur73gJ +.. section: Library + +SSLv3 is now disabled throughout the standard library. It can still be +enabled by instantiating a SSLContext manually. + +.. + +.. bpo: 22370 +.. date: 9657 +.. nonce: j4y21u +.. section: Library + +Windows detection in pathlib is now more robust. + +.. + +.. bpo: 22841 +.. date: 9656 +.. nonce: 8wpk7T +.. section: Library + +Reject coroutines in asyncio add_signal_handler(). Patch by Ludovic.Gasc. + +.. + +.. bpo: 22849 +.. date: 9655 +.. nonce: AqBPyj +.. section: Library + +Fix possible double free in the io.TextIOWrapper constructor. + +.. + +.. bpo: 12728 +.. date: 9654 +.. nonce: rHZmXO +.. section: Library + +Different Unicode characters having the same uppercase but different +lowercase are now matched in case-insensitive regular expressions. + +.. + +.. bpo: 22821 +.. date: 9653 +.. nonce: 30cQ-U +.. section: Library + +Fixed fcntl() with integer argument on 64-bit big-endian platforms. + +.. + +.. bpo: 22406 +.. date: 9652 +.. nonce: sPlVbI +.. section: Library + +Fixed the uu_codec codec incorrectly ported to 3.x. Based on patch by Martin +Panter. + +.. + +.. bpo: 17293 +.. date: 9651 +.. nonce: Hk06bO +.. section: Library + +uuid.getnode() now determines MAC address on AIX using netstat. Based on +patch by Aivars Kalvāns. + +.. + +.. bpo: 22769 +.. date: 9650 +.. nonce: PunnvQ +.. section: Library + +Fixed ttk.Treeview.tag_has() when called without arguments. + +.. + +.. bpo: 22417 +.. date: 9649 +.. nonce: To4b7U +.. section: Library + +Verify certificates by default in httplib (PEP 476). + +.. + +.. bpo: 22775 +.. date: 9648 +.. nonce: V5aCUz +.. section: Library + +Fixed unpickling of http.cookies.SimpleCookie with protocol 2 and above. +Patch by Tim Graham. + +.. + +.. bpo: 22366 +.. date: 9647 +.. nonce: u1xjUp +.. section: Library + +urllib.request.urlopen will accept a context object (SSLContext) as an +argument which will then used be for HTTPS connection. Patch by Alex Gaynor. + +.. + +.. bpo: 22776 +.. date: 9646 +.. nonce: xNcRse +.. section: Library + +Brought excluded code into the scope of a try block in SysLogHandler.emit(). + +.. + +.. bpo: 22665 +.. date: 9645 +.. nonce: j6Jlp8 +.. section: Library + +Add missing get_terminal_size and SameFileError to shutil.__all__. + +.. + +.. bpo: 17381 +.. date: 9644 +.. nonce: 4J5yv7 +.. section: Library + +Fixed handling of case-insensitive ranges in regular expressions. + +.. + +.. bpo: 22410 +.. date: 9643 +.. nonce: 99YFdd +.. section: Library + +Module level functions in the re module now cache compiled locale-dependent +regular expressions taking into account the locale. + +.. + +.. bpo: 22759 +.. date: 9642 +.. nonce: BJPdiL +.. section: Library + +Query methods on pathlib.Path() (exists(), is_dir(), etc.) now return False +when the underlying stat call raises NotADirectoryError. + +.. + +.. bpo: 8876 +.. date: 9641 +.. nonce: A83Av4 +.. section: Library + +distutils now falls back to copying files when hard linking doesn't work. +This allows use with special filesystems such as VirtualBox shared folders. + +.. + +.. bpo: 18853 +.. date: 9640 +.. nonce: 76DrPD +.. section: Library + +Fixed ResourceWarning in shlex.__nain__. + +.. + +.. bpo: 9351 +.. date: 9639 +.. nonce: u5UI-6 +.. section: Library + +Defaults set with set_defaults on an argparse subparser are no longer +ignored when also set on the parent parser. + +.. + +.. bpo: 21991 +.. date: 9638 +.. nonce: Mkm0IN +.. section: Library + +Make email.headerregistry's header 'params' attributes be read-only +(MappingProxyType). Previously the dictionary was modifiable but a new one +was created on each access of the attribute. + +.. + +.. bpo: 22641 +.. date: 9637 +.. nonce: m0ldtl +.. section: Library + +In asyncio, the default SSL context for client connections is now created +using ssl.create_default_context(), for stronger security. + +.. + +.. bpo: 22435 +.. date: 9636 +.. nonce: Mrmeio +.. section: Library + +Fix a file descriptor leak when SocketServer bind fails. + +.. + +.. bpo: 13096 +.. date: 9635 +.. nonce: rsailB +.. section: Library + +Fixed segfault in CTypes POINTER handling of large values. + +.. + +.. bpo: 11694 +.. date: 9634 +.. nonce: JuDrch +.. section: Library + +Raise ConversionError in xdrlib as documented. Patch by Filip Gruszczyński +and Claudiu Popa. + +.. + +.. bpo: 22462 +.. date: 9633 +.. nonce: 1h4Kpr +.. section: Library + +Fix pyexpat's creation of a dummy frame to make it appear in exception +tracebacks. + +.. + +.. bpo: 21173 +.. date: 9632 +.. nonce: egkbEx +.. section: Library + +Fix len() on a WeakKeyDictionary when .clear() was called with an iterator +alive. + +.. + +.. bpo: 11866 +.. date: 9631 +.. nonce: xrvbIC +.. section: Library + +Eliminated race condition in the computation of names for new threads. + +.. + +.. bpo: 21905 +.. date: 9630 +.. nonce: coKyRo +.. section: Library + +Avoid RuntimeError in pickle.whichmodule() when sys.modules is mutated while +iterating. Patch by Olivier Grisel. + +.. + +.. bpo: 22219 +.. date: 9629 +.. nonce: l9Enh9 +.. section: Library + +The zipfile module CLI now adds entries for directories (including empty +directories) in ZIP file. + +.. + +.. bpo: 22449 +.. date: 9628 +.. nonce: nFW_Fl +.. section: Library + +In the ssl.SSLContext.load_default_certs, consult the environmental +variables SSL_CERT_DIR and SSL_CERT_FILE on Windows. + +.. + +.. bpo: 20076 +.. date: 9627 +.. nonce: -7OIVB +.. section: Library + +Added non derived UTF-8 aliases to locale aliases table. + +.. + +.. bpo: 20079 +.. date: 9626 +.. nonce: qM949O +.. section: Library + +Added locales supported in glibc 2.18 to locale alias table. + +.. + +.. bpo: 22396 +.. date: 9625 +.. nonce: cQSizA +.. section: Library + +On 32-bit AIX platform, don't expose os.posix_fadvise() nor +os.posix_fallocate() because their prototypes in system headers are wrong. + +.. + +.. bpo: 22517 +.. date: 9624 +.. nonce: SOfMig +.. section: Library + +When a io.BufferedRWPair object is deallocated, clear its weakrefs. + +.. + +.. bpo: 22448 +.. date: 9623 +.. nonce: fAapvE +.. section: Library + +Improve canceled timer handles cleanup to prevent unbound memory usage. +Patch by Joshua Moore-Oliva. + +.. + +.. bpo: 23009 +.. date: 9622 +.. nonce: -sW7gk +.. section: Library + +Make sure selectors.EpollSelecrtor.select() works when no FD is registered. + +.. + +.. bpo: 20577 +.. date: 9621 +.. nonce: Y71IMj +.. section: IDLE + +Configuration of the max line length for the FormatParagraph extension has +been moved from the General tab of the Idle preferences dialog to the +FormatParagraph tab of the Config Extensions dialog. Patch by Tal Einat. + +.. + +.. bpo: 16893 +.. date: 9620 +.. nonce: JfHAA4 +.. section: IDLE + +Update Idle doc chapter to match current Idle and add new information. + +.. + +.. bpo: 3068 +.. date: 9619 +.. nonce: TYjXTA +.. section: IDLE + +Add Idle extension configuration dialog to Options menu. Changes are written +to HOME/.idlerc/config-extensions.cfg. Original patch by Tal Einat. + +.. + +.. bpo: 16233 +.. date: 9618 +.. nonce: sOadNo +.. section: IDLE + +A module browser (File : Class Browser, Alt+C) requires an editor window +with a filename. When Class Browser is requested otherwise, from a shell, +output window, or 'Untitled' editor, Idle no longer displays an error box. +It now pops up an Open Module box (Alt+M). If a valid name is entered and a +module is opened, a corresponding browser is also opened. + +.. + +.. bpo: 4832 +.. date: 9617 +.. nonce: GRKi9M +.. section: IDLE + +Save As to type Python files automatically adds .py to the name you enter +(even if your system does not display it). Some systems automatically add +.txt when type is Text files. + +.. + +.. bpo: 21986 +.. date: 9616 +.. nonce: 04GUv2 +.. section: IDLE + +Code objects are not normally pickled by the pickle module. To match this, +they are no longer pickled when running under Idle. + +.. + +.. bpo: 23180 +.. date: 9615 +.. nonce: cE_89F +.. section: IDLE + +Rename IDLE "Windows" menu item to "Window". Patch by Al Sweigart. + +.. + +.. bpo: 23392 +.. date: 9614 +.. nonce: Pe7_WK +.. section: Tests + +Added tests for marshal C API that works with FILE*. + +.. + +.. bpo: 18982 +.. date: 9613 +.. nonce: TynSM6 +.. section: Tests + +Add tests for CLI of the calendar module. + +.. + +.. bpo: 19548 +.. date: 9612 +.. nonce: 25Kxq_ +.. section: Tests + +Added some additional checks to test_codecs to ensure that statements in the +updated documentation remain accurate. Patch by Martin Panter. + +.. + +.. bpo: 22838 +.. date: 9611 +.. nonce: VZBtZg +.. section: Tests + +All test_re tests now work with unittest test discovery. + +.. + +.. bpo: 22173 +.. date: 9610 +.. nonce: dxIIVx +.. section: Tests + +Update lib2to3 tests to use unittest test discovery. + +.. + +.. bpo: 16000 +.. date: 9609 +.. nonce: Y7O6TP +.. section: Tests + +Convert test_curses to use unittest. + +.. + +.. bpo: 21456 +.. date: 9608 +.. nonce: Axsw43 +.. section: Tests + +Skip two tests in test_urllib2net.py if _ssl module not present. Patch by +Remi Pointel. + +.. + +.. bpo: 22770 +.. date: 9607 +.. nonce: FxAh91 +.. section: Tests + +Prevent some Tk segfaults on OS X when running gui tests. + +.. + +.. bpo: 23211 +.. date: 9606 +.. nonce: Bc-QfJ +.. section: Tests + +Workaround test_logging failure on some OS X 10.6 systems. + +.. + +.. bpo: 23345 +.. date: 9605 +.. nonce: HIGBKx +.. section: Tests + +Prevent test_ssl failures with large OpenSSL patch level values (like +0.9.8zc). + +.. + +.. bpo: 22289 +.. date: 9604 +.. nonce: ybGcC- +.. section: Tests + +Prevent test_urllib2net failures due to ftp connection timeout. + +.. + +.. bpo: 15506 +.. date: 9603 +.. nonce: nh8KlR +.. section: Build + +Use standard PKG_PROG_PKG_CONFIG autoconf macro in the configure script. + +.. + +.. bpo: 22935 +.. date: 9602 +.. nonce: -vY3lc +.. section: Build + +Allow the ssl module to be compiled if openssl doesn't support SSL 3. + +.. + +.. bpo: 16537 +.. date: 9601 +.. nonce: llFo71 +.. section: Build + +Check whether self.extensions is empty in setup.py. Patch by Jonathan +Hosmer. + +.. + +.. bpo: 18096 +.. date: 9600 +.. nonce: ELyAUJ +.. section: Build + +Fix library order returned by python-config. + +.. + +.. bpo: 17219 +.. date: 9599 +.. nonce: q8ueQ0 +.. section: Build + +Add library build dir for Python extension cross-builds. + +.. + +.. bpo: 17128 +.. date: 9598 +.. nonce: ez_XMv +.. section: Build + +Use private version of OpenSSL for 3.4.3 OS X 10.5+ installer. + +.. + +.. bpo: 22079 +.. date: 9597 +.. nonce: zhs2qM +.. section: C API + +PyType_Ready() now checks that statically allocated type has no dynamically +allocated bases. + +.. + +.. bpo: 19548 +.. date: 9596 +.. nonce: yOX8sS +.. section: Documentation + +Update the codecs module documentation to better cover the distinction +between text encodings and other codecs, together with other clarifications. +Patch by Martin Panter. + +.. + +.. bpo: 22914 +.. date: 9595 +.. nonce: T6aGB3 +.. section: Documentation + +Update the Python 2/3 porting HOWTO to describe a more automated approach. + +.. + +.. bpo: 21514 +.. date: 9594 +.. nonce: 1H16T6 +.. section: Documentation + +The documentation of the json module now refers to new JSON RFC 7159 instead +of obsoleted RFC 4627. + +.. + +.. bpo: 22314 +.. date: 9593 +.. nonce: ws6xsH +.. section: Tools/Demos + +pydoc now works when the LINES environment variable is set. + +.. + +.. bpo: 17896 +.. date: 9592 +.. nonce: o79rHM +.. section: Windows + +The Windows build scripts now expect external library sources to be in +``PCbuild\..\externals`` rather than ``PCbuild\..\..``. + +.. + +.. bpo: 17717 +.. date: 9591 +.. nonce: y1zoye +.. section: Windows + +The Windows build scripts now use a copy of NASM pulled from svn.python.org +to build OpenSSL. + +.. + +.. bpo: 22644 +.. date: 9590 +.. nonce: gosBki +.. section: Windows + +The bundled version of OpenSSL has been updated to 1.0.1j. diff --git a/Misc/NEWS.d/3.4.4.rst b/Misc/NEWS.d/3.4.4.rst new file mode 100644 index 00000000000000..c51c99c364ceb5 --- /dev/null +++ b/Misc/NEWS.d/3.4.4.rst @@ -0,0 +1,7 @@ +.. bpo: 25844 +.. date: 9970 +.. nonce: 6W5geO +.. release date: 2015/12/20 +.. section: Windows + +Corrected =/== typo potentially leading to crash in launcher. diff --git a/Misc/NEWS.d/3.4.4rc1.rst b/Misc/NEWS.d/3.4.4rc1.rst new file mode 100644 index 00000000000000..9fa0847595f966 --- /dev/null +++ b/Misc/NEWS.d/3.4.4rc1.rst @@ -0,0 +1,2504 @@ +.. bpo: 25709 +.. date: 9969 +.. nonce: WwGm2k +.. release date: 2015/12/06 +.. section: Core and Builtins + +Fixed problem with in-place string concatenation and utf-8 cache. + +.. + +.. bpo: 24097 +.. date: 9968 +.. nonce: Vt4E-i +.. section: Core and Builtins + +Fixed crash in object.__reduce__() if slot name is freed inside __getattr__. + +.. + +.. bpo: 24731 +.. date: 9967 +.. nonce: h9-hnz +.. section: Core and Builtins + +Fixed crash on converting objects with special methods __bytes__, __trunc__, +and __float__ returning instances of subclasses of bytes, int, and float to +subclasses of bytes, int, and float correspondingly. + +.. + +.. bpo: 25388 +.. date: 9966 +.. nonce: zm3uuQ +.. section: Core and Builtins + +Fixed tokenizer crash when processing undecodable source code with a null +byte. + +.. + +.. bpo: 22995 +.. date: 9965 +.. nonce: 90kpuP +.. section: Core and Builtins + +Default implementation of __reduce__ and __reduce_ex__ now rejects builtin +types with not defined __new__. + +.. + +.. bpo: 24802 +.. date: 9964 +.. nonce: Qie066 +.. section: Core and Builtins + +Avoid buffer overreads when int(), float(), compile(), exec() and eval() are +passed bytes-like objects. These objects are not necessarily terminated by +a null byte, but the functions assumed they were. + +.. + +.. bpo: 24402 +.. date: 9963 +.. nonce: MAgi3X +.. section: Core and Builtins + +Fix input() to prompt to the redirected stdout when sys.stdout.fileno() +fails. + +.. + +.. bpo: 24806 +.. date: 9962 +.. nonce: Nb0znT +.. section: Core and Builtins + +Prevent builtin types that are not allowed to be subclassed from being +subclassed through multiple inheritance. + +.. + +.. bpo: 24848 +.. date: 9961 +.. nonce: HlUSuy +.. section: Core and Builtins + +Fixed a number of bugs in UTF-7 decoding of misformed data. + +.. + +.. bpo: 25280 +.. date: 9960 +.. nonce: ivTMwd +.. section: Core and Builtins + +Import trace messages emitted in verbose (-v) mode are no longer formatted +twice. + +.. + +.. bpo: 25003 +.. date: 9959 +.. nonce: -bdxOl +.. section: Core and Builtins + +os.urandom() doesn't use getentropy() on Solaris because getentropy() is +blocking, whereas os.urandom() should not block. getentropy() is supported +since Solaris 11.3. + +.. + +.. bpo: 25182 +.. date: 9958 +.. nonce: gBDq-T +.. section: Core and Builtins + +The stdprinter (used as sys.stderr before the io module is imported at +startup) now uses the backslashreplace error handler. + +.. + +.. bpo: 24891 +.. date: 9957 +.. nonce: ddVmHS +.. section: Core and Builtins + +Fix a race condition at Python startup if the file descriptor of stdin (0), +stdout (1) or stderr (2) is closed while Python is creating sys.stdin, +sys.stdout and sys.stderr objects. These attributes are now set to None if +the creation of the object failed, instead of raising an OSError exception. +Initial patch written by Marco Paolini. + +.. + +.. bpo: 21167 +.. date: 9956 +.. nonce: uom-Dq +.. section: Core and Builtins + +NAN operations are now handled correctly when python is compiled with ICC +even if -fp-model strict is not specified. + +.. + +.. bpo: 4395 +.. date: 9955 +.. nonce: JpT0k7 +.. section: Core and Builtins + +Better testing and documentation of binary operators. Patch by Martin +Panter. + +.. + +.. bpo: 24467 +.. date: 9954 +.. nonce: BAJ80- +.. section: Core and Builtins + +Fixed possible buffer over-read in bytearray. The bytearray object now +always allocates place for trailing null byte and it's buffer now is always +null-terminated. + +.. + +.. bpo: 24115 +.. date: 9953 +.. nonce: y9e_MO +.. section: Core and Builtins + +Update uses of PyObject_IsTrue(), PyObject_Not(), PyObject_IsInstance(), +PyObject_RichCompareBool() and _PyDict_Contains() to check for and handle +errors correctly. + +.. + +.. bpo: 24257 +.. date: 9952 +.. nonce: UBxshR +.. section: Core and Builtins + +Fixed system error in the comparison of faked types.SimpleNamespace. + +.. + +.. bpo: 22939 +.. date: 9951 +.. nonce: DWA9ls +.. section: Core and Builtins + +Fixed integer overflow in iterator object. Patch by Clement Rouault. + +.. + +.. bpo: 23985 +.. date: 9950 +.. nonce: eezPxO +.. section: Core and Builtins + +Fix a possible buffer overrun when deleting a slice from the front of a +bytearray and then appending some other bytes data. + +.. + +.. bpo: 24102 +.. date: 9949 +.. nonce: 9T6h3m +.. section: Core and Builtins + +Fixed exception type checking in standard error handlers. + +.. + +.. bpo: 23757 +.. date: 9948 +.. nonce: Q9kwY_ +.. section: Core and Builtins + +PySequence_Tuple() incorrectly called the concrete list API when the data +was a list subclass. + +.. + +.. bpo: 24407 +.. date: 9947 +.. nonce: GmCBB3 +.. section: Core and Builtins + +Fix crash when dict is mutated while being updated. + +.. + +.. bpo: 24096 +.. date: 9946 +.. nonce: a_Rap7 +.. section: Core and Builtins + +Make warnings.warn_explicit more robust against mutation of the +warnings.filters list. + +.. + +.. bpo: 23996 +.. date: 9945 +.. nonce: znqcT8 +.. section: Core and Builtins + +Avoid a crash when a delegated generator raises an unnormalized +StopIteration exception. Patch by Stefan Behnel. + +.. + +.. bpo: 24022 +.. date: 9944 +.. nonce: 1l8YBm +.. section: Core and Builtins + +Fix tokenizer crash when processing undecodable source code. + +.. + +.. bpo: 23309 +.. date: 9943 +.. nonce: Wfnsnz +.. section: Core and Builtins + +Avoid a deadlock at shutdown if a daemon thread is aborted while it is +holding a lock to a buffered I/O object, and the main thread tries to use +the same I/O object (typically stdout or stderr). A fatal error is emitted +instead. + +.. + +.. bpo: 22977 +.. date: 9942 +.. nonce: hutEse +.. section: Core and Builtins + +Fixed formatting Windows error messages on Wine. Patch by Martin Panter. + +.. + +.. bpo: 23803 +.. date: 9941 +.. nonce: xFvKSx +.. section: Core and Builtins + +Fixed str.partition() and str.rpartition() when a separator is wider then +partitioned string. + +.. + +.. bpo: 23192 +.. date: 9940 +.. nonce: QKqdow +.. section: Core and Builtins + +Fixed generator lambdas. Patch by Bruno Cauet. + +.. + +.. bpo: 23629 +.. date: 9939 +.. nonce: r9Mt2C +.. section: Core and Builtins + +Fix the default __sizeof__ implementation for variable-sized objects. + +.. + +.. bpo: 24044 +.. date: 9938 +.. nonce: H7vb6- +.. section: Core and Builtins + +Fix possible null pointer dereference in list.sort in out of memory +conditions. + +.. + +.. bpo: 21354 +.. date: 9937 +.. nonce: ZZTe1E +.. section: Core and Builtins + +PyCFunction_New function is exposed by python DLL again. + +.. + +.. bpo: 24903 +.. date: 9936 +.. nonce: 3LBdzb +.. section: Library + +Fix regression in number of arguments compileall accepts when '-d' is +specified. The check on the number of arguments has been dropped completely +as it never worked correctly anyway. + +.. + +.. bpo: 25764 +.. date: 9935 +.. nonce: 7WWG07 +.. section: Library + +In the subprocess module, preserve any exception caused by fork() failure +when preexec_fn is used. + +.. + +.. bpo: 6478 +.. date: 9934 +.. nonce: -Bi9Hb +.. section: Library + +_strptime's regexp cache now is reset after changing timezone with +time.tzset(). + +.. + +.. bpo: 25177 +.. date: 9933 +.. nonce: aNR4Ha +.. section: Library + +Fixed problem with the mean of very small and very large numbers. As a side +effect, statistics.mean and statistics.variance should be significantly +faster. + +.. + +.. bpo: 25718 +.. date: 9932 +.. nonce: D9mHZF +.. section: Library + +Fixed copying object with state with boolean value is false. + +.. + +.. bpo: 10131 +.. date: 9931 +.. nonce: a7tptz +.. section: Library + +Fixed deep copying of minidom documents. Based on patch by Marian Ganisin. + +.. + +.. bpo: 25725 +.. date: 9930 +.. nonce: XIKv3R +.. section: Library + +Fixed a reference leak in pickle.loads() when unpickling invalid data +including tuple instructions. + +.. + +.. bpo: 25663 +.. date: 9929 +.. nonce: Ofwfqa +.. section: Library + +In the Readline completer, avoid listing duplicate global names, and search +the global namespace before searching builtins. + +.. + +.. bpo: 25688 +.. date: 9928 +.. nonce: 8P1HOv +.. section: Library + +Fixed file leak in ElementTree.iterparse() raising an error. + +.. + +.. bpo: 23914 +.. date: 9927 +.. nonce: 1sEz4J +.. section: Library + +Fixed SystemError raised by unpickler on broken pickle data. + +.. + +.. bpo: 25691 +.. date: 9926 +.. nonce: ZEaapY +.. section: Library + +Fixed crash on deleting ElementTree.Element attributes. + +.. + +.. bpo: 25624 +.. date: 9925 +.. nonce: ed-fM0 +.. section: Library + +ZipFile now always writes a ZIP_STORED header for directory entries. Patch +by Dingyuan Wang. + +.. + +.. bpo: 25583 +.. date: 9924 +.. nonce: Gk-cim +.. section: Library + +Avoid incorrect errors raised by os.makedirs(exist_ok=True) when the OS +gives priority to errors such as EACCES over EEXIST. + +.. + +.. bpo: 25593 +.. date: 9923 +.. nonce: 56uegI +.. section: Library + +Change semantics of EventLoop.stop() in asyncio. + +.. + +.. bpo: 6973 +.. date: 9922 +.. nonce: nl5cHt +.. section: Library + +When we know a subprocess.Popen process has died, do not allow the +send_signal(), terminate(), or kill() methods to do anything as they could +potentially signal a different process. + +.. + +.. bpo: 25578 +.. date: 9921 +.. nonce: G6S-ft +.. section: Library + +Fix (another) memory leak in SSLSocket.getpeercer(). + +.. + +.. bpo: 25590 +.. date: 9920 +.. nonce: aCt-yW +.. section: Library + +In the Readline completer, only call getattr() once per attribute. + +.. + +.. bpo: 25498 +.. date: 9919 +.. nonce: 75n0LF +.. section: Library + +Fix a crash when garbage-collecting ctypes objects created by wrapping a +memoryview. This was a regression made in 3.4.3. Based on patch by +Eryksun. + +.. + +.. bpo: 18010 +.. date: 9918 +.. nonce: Azyf1C +.. section: Library + +Fix the pydoc web server's module search function to handle exceptions from +importing packages. + +.. + +.. bpo: 25510 +.. date: 9917 +.. nonce: 79g7LA +.. section: Library + +fileinput.FileInput.readline() now returns b'' instead of '' at the end if +the FileInput was opened with binary mode. Patch by Ryosuke Ito. + +.. + +.. bpo: 25530 +.. date: 9916 +.. nonce: hDFkwu +.. section: Library + +Disable the vulnerable SSLv3 protocol by default when creating +ssl.SSLContext. + +.. + +.. bpo: 25569 +.. date: 9915 +.. nonce: CfvQjK +.. section: Library + +Fix memory leak in SSLSocket.getpeercert(). + +.. + +.. bpo: 21827 +.. date: 9914 +.. nonce: k2oreR +.. section: Library + +Fixed textwrap.dedent() for the case when largest common whitespace is a +substring of smallest leading whitespace. Based on patch by Robert Li. + +.. + +.. bpo: 25471 +.. date: 9913 +.. nonce: T0A02M +.. section: Library + +Sockets returned from accept() shouldn't appear to be nonblocking. + +.. + +.. bpo: 25441 +.. date: 9912 +.. nonce: d7zph6 +.. section: Library + +asyncio: Raise error from drain() when socket is closed. + +.. + +.. bpo: 25411 +.. date: 9911 +.. nonce: qsJTCb +.. section: Library + +Improved Unicode support in SMTPHandler through better use of the email +package. Thanks to user simon04 for the patch. + +.. + +.. bpo: 25380 +.. date: 9910 +.. nonce: sKZ6-I +.. section: Library + +Fixed protocol for the STACK_GLOBAL opcode in pickletools.opcodes. + +.. + +.. bpo: 23972 +.. date: 9909 +.. nonce: s2g30g +.. section: Library + +Updates asyncio datagram create method allowing reuseport and reuseaddr +socket options to be set prior to binding the socket. Mirroring the existing +asyncio create_server method the reuseaddr option for datagram sockets +defaults to True if the O/S is 'posix' (except if the platform is Cygwin). +Patch by Chris Laws. + +.. + +.. bpo: 25304 +.. date: 9908 +.. nonce: CsmLyI +.. section: Library + +Add asyncio.run_coroutine_threadsafe(). This lets you submit a coroutine to +a loop from another thread, returning a concurrent.futures.Future. By +Vincent Michel. + +.. + +.. bpo: 25319 +.. date: 9907 +.. nonce: iyuglv +.. section: Library + +When threading.Event is reinitialized, the underlying condition should use a +regular lock rather than a recursive lock. + +.. + +.. bpo: 25232 +.. date: 9906 +.. nonce: KhKjCE +.. section: Library + +Fix CGIRequestHandler to split the query from the URL at the first question +mark (?) rather than the last. Patch from Xiang Zhang. + +.. + +.. bpo: 24657 +.. date: 9905 +.. nonce: h2Ag7y +.. section: Library + +Prevent CGIRequestHandler from collapsing slashes in the query part of the +URL as if it were a path. Patch from Xiang Zhang. + +.. + +.. bpo: 22958 +.. date: 9904 +.. nonce: Ebu7Gl +.. section: Library + +Constructor and update method of weakref.WeakValueDictionary now accept the +self and the dict keyword arguments. + +.. + +.. bpo: 22609 +.. date: 9903 +.. nonce: fV7hdV +.. section: Library + +Constructor of collections.UserDict now accepts the self keyword argument. + +.. + +.. bpo: 25262 +.. date: 9902 +.. nonce: pQS5cB +.. section: Library + +Added support for BINBYTES8 opcode in Python implementation of unpickler. +Highest 32 bits of 64-bit size for BINUNICODE8 and BINBYTES8 opcodes no +longer silently ignored on 32-bit platforms in C implementation. + +.. + +.. bpo: 25034 +.. date: 9901 +.. nonce: eGvOIb +.. section: Library + +Fix string.Formatter problem with auto-numbering and nested format_specs. +Patch by Anthon van der Neut. + +.. + +.. bpo: 25233 +.. date: 9900 +.. nonce: EdZV9x +.. section: Library + +Rewrite the guts of asyncio.Queue and asyncio.Semaphore to be more +understandable and correct. + +.. + +.. bpo: 23600 +.. date: 9899 +.. nonce: 7J_RD5 +.. section: Library + +Default implementation of tzinfo.fromutc() was returning wrong results in +some cases. + +.. + +.. bpo: 25203 +.. date: 9898 +.. nonce: IgDEbt +.. section: Library + +Failed readline.set_completer_delims() no longer left the module in +inconsistent state. + +.. + +.. bpo: 0 +.. date: 9897 +.. nonce: ww9QSm +.. section: Library + +Prevent overflow in _Unpickler_Read. + +.. + +.. bpo: 25047 +.. date: 9896 +.. nonce: kc8tqx +.. section: Library + +The XML encoding declaration written by Element Tree now respects the letter +case given by the user. This restores the ability to write encoding names in +uppercase like "UTF-8", which worked in Python 2. + +.. + +.. bpo: 19143 +.. date: 9895 +.. nonce: 76SBSO +.. section: Library + +platform module now reads Windows version from kernel32.dll to avoid +compatibility shims. + +.. + +.. bpo: 23517 +.. date: 9894 +.. nonce: T1dqBS +.. section: Library + +Fix rounding in fromtimestamp() and utcfromtimestamp() methods of +datetime.datetime: microseconds are now rounded to nearest with ties going +to nearest even integer (ROUND_HALF_EVEN), instead of being rounding towards +zero (ROUND_DOWN). It's important that these methods use the same rounding +mode than datetime.timedelta to keep the property: (datetime(1970,1,1) + +timedelta(seconds=t)) == datetime.utcfromtimestamp(t). It also the rounding +mode used by round(float) for example. + +.. + +.. bpo: 24684 +.. date: 9893 +.. nonce: t4T77O +.. section: Library + +socket.socket.getaddrinfo() now calls PyUnicode_AsEncodedString() instead of +calling the encode() method of the host, to handle correctly custom string +with an encode() method which doesn't return a byte string. The encoder of +the IDNA codec is now called directly instead of calling the encode() method +of the string. + +.. + +.. bpo: 24982 +.. date: 9892 +.. nonce: sGMMAR +.. section: Library + +shutil.make_archive() with the "zip" format now adds entries for directories +(including empty directories) in ZIP file. + +.. + +.. bpo: 24857 +.. date: 9891 +.. nonce: PpJWZ9 +.. section: Library + +Comparing call_args to a long sequence now correctly returns a boolean +result instead of raising an exception. Patch by A Kaptur. + +.. + +.. bpo: 25019 +.. date: 9890 +.. nonce: JQJlOZ +.. section: Library + +Fixed a crash caused by setting non-string key of expat parser. Based on +patch by John Leitch. + +.. + +.. bpo: 24917 +.. date: 9889 +.. nonce: xaQocz +.. section: Library + +time_strftime() buffer over-read. + +.. + +.. bpo: 23144 +.. date: 9888 +.. nonce: cLf67X +.. section: Library + +Make sure that HTMLParser.feed() returns all the data, even when +convert_charrefs is True. + +.. + +.. bpo: 16180 +.. date: 9887 +.. nonce: 6IUcNS +.. section: Library + +Exit pdb if file has syntax error, instead of trapping user in an infinite +loop. Patch by Xavier de Gaye. + +.. + +.. bpo: 21112 +.. date: 9886 +.. nonce: vSFU1r +.. section: Library + +Fix regression in unittest.expectedFailure on subclasses. Patch from Berker +Peksag. + +.. + +.. bpo: 24931 +.. date: 9885 +.. nonce: 4vKoWJ +.. section: Library + +Instances of subclasses of namedtuples have their own __dict__ which breaks +the inherited __dict__ property and breaks the _asdict() method. Removed the +__dict__ property to prevent the conflict and fixed _asdict(). + +.. + +.. bpo: 24764 +.. date: 9884 +.. nonce: QwFZ2S +.. section: Library + +cgi.FieldStorage.read_multi() now ignores the Content-Length header in part +headers. Patch written by Peter Landry and reviewed by Pierre Quentel. + +.. + +.. bpo: 24774 +.. date: 9883 +.. nonce: xLbskG +.. section: Library + +Fix docstring in http.server.test. Patch from Chiu-Hsiang Hsu. + +.. + +.. bpo: 21159 +.. date: 9882 +.. nonce: ochL5W +.. section: Library + +Improve message in configparser.InterpolationMissingOptionError. Patch from +Łukasz Langa. + +.. + +.. bpo: 23888 +.. date: 9881 +.. nonce: 7gw4oO +.. section: Library + +Handle fractional time in cookie expiry. Patch by ssh. + +.. + +.. bpo: 23004 +.. date: 9880 +.. nonce: xswcPm +.. section: Library + +mock_open() now reads binary data correctly when the type of read_data is +bytes. Initial patch by Aaron Hill. + +.. + +.. bpo: 23652 +.. date: 9879 +.. nonce: DKQ_7t +.. section: Library + +Make it possible to compile the select module against the libc headers from +the Linux Standard Base, which do not include some EPOLL macros. Patch by +Matt Frank. + +.. + +.. bpo: 22932 +.. date: 9878 +.. nonce: mPclSJ +.. section: Library + +Fix timezones in email.utils.formatdate. Patch from Dmitry Shachnev. + +.. + +.. bpo: 23779 +.. date: 9877 +.. nonce: ET4JJP +.. section: Library + +imaplib raises TypeError if authenticator tries to abort. Patch from Craig +Holmquist. + +.. + +.. bpo: 23319 +.. date: 9876 +.. nonce: FXyUH- +.. section: Library + +Fix ctypes.BigEndianStructure, swap correctly bytes. Patch written by +Matthieu Gautier. + +.. + +.. bpo: 23254 +.. date: 9875 +.. nonce: zNiy1X +.. section: Library + +Document how to close the TCPServer listening socket. Patch from Martin +Panter. + +.. + +.. bpo: 19450 +.. date: 9874 +.. nonce: VG7T-L +.. section: Library + +Update Windows and OS X installer builds to use SQLite 3.8.11. + +.. + +.. bpo: 23441 +.. date: 9873 +.. nonce: JXt2Yt +.. section: Library + +rcompleter now prints a tab character instead of displaying possible +completions for an empty word. Initial patch by Martin Sekera. + +.. + +.. bpo: 24735 +.. date: 9872 +.. nonce: tGudHm +.. section: Library + +Fix invalid memory access in itertools.combinations_with_replacement(). + +.. + +.. bpo: 17527 +.. date: 9871 +.. nonce: ve9fyw +.. section: Library + +Add PATCH to wsgiref.validator. Patch from Luca Sbardella. + +.. + +.. bpo: 24683 +.. date: 9870 +.. nonce: aJdWEv +.. section: Library + +Fixed crashes in _json functions called with arguments of inappropriate +type. + +.. + +.. bpo: 21697 +.. date: 9869 +.. nonce: jpATha +.. section: Library + +shutil.copytree() now correctly handles symbolic links that point to +directories. Patch by Eduardo Seabra and Thomas Kluyver. + +.. + +.. bpo: 24620 +.. date: 9868 +.. nonce: rrnxB- +.. section: Library + +Random.setstate() now validates the value of state last element. + +.. + +.. bpo: 22153 +.. date: 9867 +.. nonce: 6n6yld +.. section: Library + +Improve unittest docs. Patch from Martin Panter and evilzero. + +.. + +.. bpo: 24206 +.. date: 9866 +.. nonce: ffkVHH +.. section: Library + +Fixed __eq__ and __ne__ methods of inspect classes. + +.. + +.. bpo: 21750 +.. date: 9865 +.. nonce: _Ycvgi +.. section: Library + +mock_open.read_data can now be read from each instance, as it could in +Python 3.3. + +.. + +.. bpo: 23247 +.. date: 9864 +.. nonce: nN-K74 +.. section: Library + +Fix a crash in the StreamWriter.reset() of CJK codecs. + +.. + +.. bpo: 18622 +.. date: 9863 +.. nonce: i6nCCW +.. section: Library + +unittest.mock.mock_open().reset_mock would recurse infinitely. Patch from +Nicola Palumbo and Laurent De Buyst. + +.. + +.. bpo: 24608 +.. date: 9862 +.. nonce: 0TndL0 +.. section: Library + +chunk.Chunk.read() now always returns bytes, not str. + +.. + +.. bpo: 18684 +.. date: 9861 +.. nonce: S2es0F +.. section: Library + +Fixed reading out of the buffer in the re module. + +.. + +.. bpo: 24259 +.. date: 9860 +.. nonce: vMAi1A +.. section: Library + +tarfile now raises a ReadError if an archive is truncated inside a data +segment. + +.. + +.. bpo: 24552 +.. date: 9859 +.. nonce: VTO6sf +.. section: Library + +Fix use after free in an error case of the _pickle module. + +.. + +.. bpo: 24514 +.. date: 9858 +.. nonce: _xRb2r +.. section: Library + +tarfile now tolerates number fields consisting of only whitespace. + +.. + +.. bpo: 19176 +.. date: 9857 +.. nonce: 8V6nOK +.. section: Library + +Fixed doctype() related bugs in C implementation of ElementTree. A +deprecation warning no longer issued by XMLParser subclass with default +doctype() method. Direct call of doctype() now issues a warning. Parser's +doctype() now is not called if target's doctype() is called. Based on patch +by Martin Panter. + +.. + +.. bpo: 20387 +.. date: 9856 +.. nonce: aAbWbQ +.. section: Library + +Restore semantic round-trip correctness in tokenize/untokenize for tab- +indented blocks. + +.. + +.. bpo: 24456 +.. date: 9855 +.. nonce: yYSd2u +.. section: Library + +Fixed possible buffer over-read in adpcm2lin() and lin2adpcm() functions of +the audioop module. + +.. + +.. bpo: 24336 +.. date: 9854 +.. nonce: 4a5y1m +.. section: Library + +The contextmanager decorator now works with functions with keyword arguments +called "func" and "self". Patch by Martin Panter. + +.. + +.. bpo: 24489 +.. date: 9853 +.. nonce: GJnMcW +.. section: Library + +ensure a previously set C errno doesn't disturb cmath.polar(). + +.. + +.. bpo: 5633 +.. date: 9852 +.. nonce: JNzKZq +.. section: Library + +Fixed timeit when the statement is a string and the setup is not. + +.. + +.. bpo: 24326 +.. date: 9851 +.. nonce: 4t_6Gy +.. section: Library + +Fixed audioop.ratecv() with non-default weightB argument. Original patch by +David Moore. + +.. + +.. bpo: 23840 +.. date: 9850 +.. nonce: mtSbqO +.. section: Library + +tokenize.open() now closes the temporary binary file on error to fix a +resource warning. + +.. + +.. bpo: 24257 +.. date: 9849 +.. nonce: L_efq0 +.. section: Library + +Fixed segmentation fault in sqlite3.Row constructor with faked cursor type. + +.. + +.. bpo: 22107 +.. date: 9848 +.. nonce: 2F8k4W +.. section: Library + +tempfile.gettempdir() and tempfile.mkdtemp() now try again when a directory +with the chosen name already exists on Windows as well as on Unix. +tempfile.mkstemp() now fails early if parent directory is not valid (not +exists or is a file) on Windows. + +.. + +.. bpo: 6598 +.. date: 9847 +.. nonce: JdZNDt +.. section: Library + +Increased time precision and random number range in email.utils.make_msgid() +to strengthen the uniqueness of the message ID. + +.. + +.. bpo: 24091 +.. date: 9846 +.. nonce: Jw0-wj +.. section: Library + +Fixed various crashes in corner cases in C implementation of ElementTree. + +.. + +.. bpo: 21931 +.. date: 9845 +.. nonce: t6lGxY +.. section: Library + +msilib.FCICreate() now raises TypeError in the case of a bad argument +instead of a ValueError with a bogus FCI error number. Patch by Jeffrey +Armstrong. + +.. + +.. bpo: 23796 +.. date: 9844 +.. nonce: JJmUnc +.. section: Library + +peek and read1 methods of BufferedReader now raise ValueError if they called +on a closed object. Patch by John Hergenroeder. + +.. + +.. bpo: 24521 +.. date: 9843 +.. nonce: bn4U-y +.. section: Library + +Fix possible integer overflows in the pickle module. + +.. + +.. bpo: 22931 +.. date: 9842 +.. nonce: 4CuWYD +.. section: Library + +Allow '[' and ']' in cookie values. + +.. + +.. bpo: 20274 +.. date: 9841 +.. nonce: hBst4M +.. section: Library + +Remove ignored and erroneous "kwargs" parameters from three METH_VARARGS +methods on _sqlite.Connection. + +.. + +.. bpo: 24094 +.. date: 9840 +.. nonce: 7T-u7k +.. section: Library + +Fix possible crash in json.encode with poorly behaved dict subclasses. + +.. + +.. bpo: 0 +.. date: 9839 +.. nonce: oVpSpG +.. section: Library + +Asyncio issue 222 / PR 231 (Victor Stinner) -- fix @coroutine functions +without __name__. + +.. + +.. bpo: 9246 +.. date: 9838 +.. nonce: oM-Ikk +.. section: Library + +On POSIX, os.getcwd() now supports paths longer than 1025 bytes. Patch +written by William Orr. + +.. + +.. bpo: 0 +.. date: 9837 +.. nonce: fgX8Qe +.. section: Library + +The keywords attribute of functools.partial is now always a dictionary. + +.. + +.. bpo: 24099 +.. date: 9836 +.. nonce: eLk6AB +.. section: Library + +Fix free-after-use bug in heapq's siftup and siftdown functions. (See also: +bpo-24100, bpo-24101) + +.. + +.. bpo: 0 +.. date: 9835 +.. nonce: OuI94b +.. section: Library + +Backport collections.deque fixes from Python 3.5. Prevents reentrant +badness during deletion by deferring the decref until the container has been +restored to a consistent state. + +.. + +.. bpo: 23008 +.. date: 9834 +.. nonce: OZFCd- +.. section: Library + +Fixed resolving attributes with boolean value is False in pydoc. + +.. + +.. bpo: 0 +.. date: 9833 +.. nonce: qpVFD6 +.. section: Library + +Fix asyncio issue 235: LifoQueue and PriorityQueue's put didn't increment +unfinished tasks (this bug was introduced in 3.4.3 when JoinableQueue was +merged with Queue). + +.. + +.. bpo: 23908 +.. date: 9832 +.. nonce: jIfoyT +.. section: Library + +os functions now reject paths with embedded null character on Windows +instead of silently truncate them. + +.. + +.. bpo: 23728 +.. date: 9831 +.. nonce: YBmQmV +.. section: Library + +binascii.crc_hqx() could return an integer outside of the range 0-0xffff for +empty data. + +.. + +.. bpo: 23811 +.. date: 9830 +.. nonce: B6tzf9 +.. section: Library + +Add missing newline to the PyCompileError error message. Patch by Alex +Shkop. + +.. + +.. bpo: 17898 +.. date: 9829 +.. nonce: EsbCnX +.. section: Library + +Fix exception in gettext.py when parsing certain plural forms. + +.. + +.. bpo: 22982 +.. date: 9828 +.. nonce: xYmG62 +.. section: Library + +Improve BOM handling when seeking to multiple positions of a writable text +file. + +.. + +.. bpo: 23865 +.. date: 9827 +.. nonce: PtSLgU +.. section: Library + +close() methods in multiple modules now are idempotent and more robust at +shutdown. If they need to release multiple resources, all are released even +if errors occur. + +.. + +.. bpo: 23881 +.. date: 9826 +.. nonce: yZjl4b +.. section: Library + +urllib.request.ftpwrapper constructor now closes the socket if the FTP +connection failed to fix a ResourceWarning. + +.. + +.. bpo: 23400 +.. date: 9825 +.. nonce: JSh9Z3 +.. section: Library + +Raise same exception on both Python 2 and 3 if sem_open is not available. +Patch by Davin Potts. + +.. + +.. bpo: 15133 +.. date: 9824 +.. nonce: C0QfV8 +.. section: Library + +_tkinter.tkapp.getboolean() now supports Tcl_Obj and always returns bool. +tkinter.BooleanVar now validates input values (accepted bool, int, str, and +Tcl_Obj). tkinter.BooleanVar.get() now always returns bool. + +.. + +.. bpo: 23338 +.. date: 9823 +.. nonce: ZYMGN1 +.. section: Library + +Fixed formatting ctypes error messages on Cygwin. Patch by Makoto Kato. + +.. + +.. bpo: 16840 +.. date: 9822 +.. nonce: kKIhPm +.. section: Library + +Tkinter now supports 64-bit integers added in Tcl 8.4 and arbitrary +precision integers added in Tcl 8.5. + +.. + +.. bpo: 23834 +.. date: 9821 +.. nonce: fX3TF4 +.. section: Library + +Fix socket.sendto(), use the C Py_ssize_t type to store the result of +sendto() instead of the C int type. + +.. + +.. bpo: 21526 +.. date: 9820 +.. nonce: QQEXrR +.. section: Library + +Tkinter now supports new boolean type in Tcl 8.5. + +.. + +.. bpo: 23838 +.. date: 9819 +.. nonce: IX6FPX +.. section: Library + +linecache now clears the cache and returns an empty result on MemoryError. + +.. + +.. bpo: 18473 +.. date: 9818 +.. nonce: 89RHm- +.. section: Library + +Fixed 2to3 and 3to2 compatible pickle mappings. Fixed ambigious reverse +mappings. Added many new mappings. Import mapping is no longer applied to +modules already mapped with full name mapping. + +.. + +.. bpo: 23745 +.. date: 9817 +.. nonce: E00Bml +.. section: Library + +The new email header parser now handles duplicate MIME parameter names +without error, similar to how get_param behaves. + +.. + +.. bpo: 23792 +.. date: 9816 +.. nonce: Kfm9-f +.. section: Library + +Ignore KeyboardInterrupt when the pydoc pager is active. This mimics the +behavior of the standard unix pagers, and prevents pipepager from shutting +down while the pager itself is still running. + +.. + +.. bpo: 23742 +.. date: 9815 +.. nonce: _EkAIa +.. section: Library + +ntpath.expandvars() no longer loses unbalanced single quotes. + +.. + +.. bpo: 21802 +.. date: 9814 +.. nonce: ygSM2A +.. section: Library + +The reader in BufferedRWPair now is closed even when closing writer failed +in BufferedRWPair.close(). + +.. + +.. bpo: 23671 +.. date: 9813 +.. nonce: N8nc23 +.. section: Library + +string.Template now allows to specify the "self" parameter as keyword +argument. string.Formatter now allows to specify the "self" and the +"format_string" parameters as keyword arguments. + +.. + +.. bpo: 21560 +.. date: 9812 +.. nonce: lqfYv8 +.. section: Library + +An attempt to write a data of wrong type no longer cause GzipFile +corruption. Original patch by Wolfgang Maier. + +.. + +.. bpo: 23647 +.. date: 9811 +.. nonce: pX2qrx +.. section: Library + +Increase impalib's MAXLINE to accommodate modern mailbox sizes. + +.. + +.. bpo: 23539 +.. date: 9810 +.. nonce: 5BVUim +.. section: Library + +If body is None, http.client.HTTPConnection.request now sets Content-Length +to 0 for PUT, POST, and PATCH headers to avoid 411 errors from some web +servers. + +.. + +.. bpo: 22351 +.. date: 9809 +.. nonce: agB8Y3 +.. section: Library + +The nntplib.NNTP constructor no longer leaves the connection and socket open +until the garbage collector cleans them up. Patch by Martin Panter. + +.. + +.. bpo: 23136 +.. date: 9808 +.. nonce: 1bnpnb +.. section: Library + +_strptime now uniformly handles all days in week 0, including Dec 30 of +previous year. Based on patch by Jim Carroll. + +.. + +.. bpo: 23700 +.. date: 9807 +.. nonce: VfnWwi +.. section: Library + +Iterator of NamedTemporaryFile now keeps a reference to NamedTemporaryFile +instance. Patch by Bohuslav Kabrda. + +.. + +.. bpo: 22903 +.. date: 9806 +.. nonce: 2GjTHY +.. section: Library + +The fake test case created by unittest.loader when it fails importing a test +module is now picklable. + +.. + +.. bpo: 23568 +.. date: 9805 +.. nonce: ffzJc7 +.. section: Library + +Add rdivmod support to MagicMock() objects. Patch by Håkan Lövdahl. + +.. + +.. bpo: 23138 +.. date: 9804 +.. nonce: 4vMoMZ +.. section: Library + +Fixed parsing cookies with absent keys or values in cookiejar. Patch by +Demian Brecht. + +.. + +.. bpo: 23051 +.. date: 9803 +.. nonce: Vi5tCZ +.. section: Library + +multiprocessing.Pool methods imap() and imap_unordered() now handle +exceptions raised by an iterator. Patch by Alon Diamant and Davin Potts. + +.. + +.. bpo: 22928 +.. date: 9802 +.. nonce: q2TmY0 +.. section: Library + +Disabled HTTP header injections in http.client. Original patch by Demian +Brecht. + +.. + +.. bpo: 23615 +.. date: 9801 +.. nonce: 5Kx9k5 +.. section: Library + +Modules bz2, tarfile and tokenize now can be reloaded with imp.reload(). +Patch by Thomas Kluyver. + +.. + +.. bpo: 23476 +.. date: 9800 +.. nonce: 82QV9I +.. section: Library + +In the ssl module, enable OpenSSL's X509_V_FLAG_TRUSTED_FIRST flag on +certificate stores when it is available. + +.. + +.. bpo: 23576 +.. date: 9799 +.. nonce: 98F-PP +.. section: Library + +Avoid stalling in SSL reads when EOF has been reached in the SSL layer but +the underlying connection hasn't been closed. + +.. + +.. bpo: 23504 +.. date: 9798 +.. nonce: o31h5I +.. section: Library + +Added an __all__ to the types module. + +.. + +.. bpo: 20204 +.. date: 9797 +.. nonce: DorA4b +.. section: Library + +Added the __module__ attribute to _tkinter classes. + +.. + +.. bpo: 23521 +.. date: 9796 +.. nonce: 0UEjfm +.. section: Library + +Corrected pure python implementation of timedelta division. + +Eliminated OverflowError from timedelta * float for some floats; Corrected +rounding in timedlta true division. + +.. + +.. bpo: 21619 +.. date: 9795 +.. nonce: uL0SZh +.. section: Library + +Popen objects no longer leave a zombie after exit in the with statement if +the pipe was broken. Patch by Martin Panter. + +.. + +.. bpo: 6639 +.. date: 9794 +.. nonce: rmjUmG +.. section: Library + +Module-level turtle functions no longer raise TclError after closing the +window. + +.. + +.. bpo: 814253 +.. date: 9793 +.. nonce: AJWDsY +.. section: Library + +Warnings now are raised when group references and conditional group +references are used in lookbehind assertions in regular expressions. (See +also: bpo-9179) + +.. + +.. bpo: 23215 +.. date: 9792 +.. nonce: VHVSVX +.. section: Library + +Multibyte codecs with custom error handlers that ignores errors consumed too +much memory and raised SystemError or MemoryError. Original patch by Aleksi +Torhamo. + +.. + +.. bpo: 5700 +.. date: 9791 +.. nonce: iA5yzL +.. section: Library + +io.FileIO() called flush() after closing the file. flush() was not called in +close() if closefd=False. + +.. + +.. bpo: 23374 +.. date: 9790 +.. nonce: 8A9LuZ +.. section: Library + +Fixed pydoc failure with non-ASCII files when stdout encoding differs from +file system encoding (e.g. on Mac OS). + +.. + +.. bpo: 23481 +.. date: 9789 +.. nonce: ZWwliG +.. section: Library + +Remove RC4 from the SSL module's default cipher list. + +.. + +.. bpo: 21548 +.. date: 9788 +.. nonce: CmO_Yh +.. section: Library + +Fix pydoc.synopsis() and pydoc.apropos() on modules with empty docstrings. + +.. + +.. bpo: 22885 +.. date: 9787 +.. nonce: p8FnYk +.. section: Library + +Fixed arbitrary code execution vulnerability in the dbm.dumb module. +Original patch by Claudiu Popa. + +.. + +.. bpo: 23146 +.. date: 9786 +.. nonce: PW-O3u +.. section: Library + +Fix mishandling of absolute Windows paths with forward slashes in pathlib. + +.. + +.. bpo: 23421 +.. date: 9785 +.. nonce: eckzoV +.. section: Library + +Fixed compression in tarfile CLI. Patch by wdv4758h. + +.. + +.. bpo: 23367 +.. date: 9784 +.. nonce: kHnFiz +.. section: Library + +Fix possible overflows in the unicodedata module. + +.. + +.. bpo: 23361 +.. date: 9783 +.. nonce: I_w0-z +.. section: Library + +Fix possible overflow in Windows subprocess creation code. + +.. + +.. bpo: 23801 +.. date: 9782 +.. nonce: jyJK3z +.. section: Library + +Fix issue where cgi.FieldStorage did not always ignore the entire preamble +to a multipart body. + +.. + +.. bpo: 23310 +.. date: 9781 +.. nonce: GXmFMR +.. section: Library + +Fix MagicMock's initializer to work with __methods__, just like +configure_mock(). Patch by Kasia Jachim. + +.. + +.. bpo: 0 +.. date: 9780 +.. nonce: MjNdSC +.. section: Library + +asyncio: New event loop APIs: set_task_factory() and get_task_factory(). + +.. + +.. bpo: 0 +.. date: 9779 +.. nonce: rVcHXp +.. section: Library + +asyncio: async() function is deprecated in favour of ensure_future(). + +.. + +.. bpo: 23898 +.. date: 9778 +.. nonce: OSiZie +.. section: Library + +Fix inspect.classify_class_attrs() to support attributes with overloaded +__eq__ and __bool__. Patch by Mike Bayer. + +.. + +.. bpo: 24298 +.. date: 9777 +.. nonce: u_TaxI +.. section: Library + +Fix inspect.signature() to correctly unwrap wrappers around bound methods. + +.. + +.. bpo: 23572 +.. date: 9776 +.. nonce: QhQ9RD +.. section: Library + +Fixed functools.singledispatch on classes with falsy metaclasses. Patch by +Ethan Furman. + +.. + +.. bpo: 15348 +.. date: 9775 +.. nonce: d1Fg01 +.. section: IDLE + +Stop the debugger engine (normally in a user process) before closing the +debugger window (running in the IDLE process). This prevents the +RuntimeErrors that were being caught and ignored. + +.. + +.. bpo: 24455 +.. date: 9774 +.. nonce: x6YqtE +.. section: IDLE + +Prevent IDLE from hanging when a) closing the shell while the debugger is +active (15347); b) closing the debugger with the [X] button (15348); and c) +activating the debugger when already active (24455). The patch by Mark +Roseman does this by making two changes. 1. Suspend and resume the +gui.interaction method with the tcl vwait mechanism intended for this +purpose (instead of root.mainloop & .quit). 2. In gui.run, allow any +existing interaction to terminate first. + +.. + +.. bpo: 0 +.. date: 9773 +.. nonce: Yp9LRY +.. section: IDLE + +Change 'The program' to 'Your program' in an IDLE 'kill program?' message to +make it clearer that the program referred to is the currently running user +program, not IDLE itself. + +.. + +.. bpo: 24750 +.. date: 9772 +.. nonce: xgsi-K +.. section: IDLE + +Improve the appearance of the IDLE editor window status bar. Patch by Mark +Roseman. + +.. + +.. bpo: 25313 +.. date: 9771 +.. nonce: xMXHpO +.. section: IDLE + +Change the handling of new built-in text color themes to better address the +compatibility problem introduced by the addition of IDLE Dark. Consistently +use the revised idleConf.CurrentTheme everywhere in idlelib. + +.. + +.. bpo: 24782 +.. date: 9770 +.. nonce: PCsWad +.. section: IDLE + +Extension configuration is now a tab in the IDLE Preferences dialog rather +than a separate dialog. The former tabs are now a sorted list. Patch by +Mark Roseman. + +.. + +.. bpo: 22726 +.. date: 9769 +.. nonce: x8T0dA +.. section: IDLE + +Re-activate the config dialog help button with some content about the other +buttons and the new IDLE Dark theme. + +.. + +.. bpo: 24820 +.. date: 9768 +.. nonce: TFPJhr +.. section: IDLE + +IDLE now has an 'IDLE Dark' built-in text color theme. It is more or less +IDLE Classic inverted, with a cobalt blue background. Strings, comments, +keywords, ... are still green, red, orange, ... . To use it with IDLEs +released before November 2015, hit the 'Save as New Custom Theme' button and +enter a new name, such as 'Custom Dark'. The custom theme will work with +any IDLE release, and can be modified. + +.. + +.. bpo: 25224 +.. date: 9767 +.. nonce: 5Llwo4 +.. section: IDLE + +README.txt is now an idlelib index for IDLE developers and curious users. +The previous user content is now in the IDLE doc chapter. 'IDLE' now means +'Integrated Development and Learning Environment'. + +.. + +.. bpo: 24820 +.. date: 9766 +.. nonce: ZUz9Fn +.. section: IDLE + +Users can now set breakpoint colors in Settings -> Custom Highlighting. +Original patch by Mark Roseman. + +.. + +.. bpo: 24972 +.. date: 9765 +.. nonce: uc0uNo +.. section: IDLE + +Inactive selection background now matches active selection background, as +configured by users, on all systems. Found items are now always highlighted +on Windows. Initial patch by Mark Roseman. + +.. + +.. bpo: 24570 +.. date: 9764 +.. nonce: s3EkNn +.. section: IDLE + +Idle: make calltip and completion boxes appear on Macs affected by a tk +regression. Initial patch by Mark Roseman. + +.. + +.. bpo: 24988 +.. date: 9763 +.. nonce: tXqq4T +.. section: IDLE + +Idle ScrolledList context menus (used in debugger) now work on Mac Aqua. +Patch by Mark Roseman. + +.. + +.. bpo: 24801 +.. date: 9762 +.. nonce: -bj_Ou +.. section: IDLE + +Make right-click for context menu work on Mac Aqua. Patch by Mark Roseman. + +.. + +.. bpo: 25173 +.. date: 9761 +.. nonce: EZzrPg +.. section: IDLE + +Associate tkinter messageboxes with a specific widget. For Mac OSX, make +them a 'sheet'. Patch by Mark Roseman. + +.. + +.. bpo: 25198 +.. date: 9760 +.. nonce: -j_BV7 +.. section: IDLE + +Enhance the initial html viewer now used for Idle Help. * Properly indent +fixed-pitch text (patch by Mark Roseman). * Give code snippet a very Sphinx- +like light blueish-gray background. * Re-use initial width and height set by +users for shell and editor. * When the Table of Contents (TOC) menu is used, +put the section header at the top of the screen. + +.. + +.. bpo: 25225 +.. date: 9759 +.. nonce: 9pvdq6 +.. section: IDLE + +Condense and rewrite Idle doc section on text colors. + +.. + +.. bpo: 21995 +.. date: 9758 +.. nonce: C5Rmzx +.. section: IDLE + +Explain some differences between IDLE and console Python. + +.. + +.. bpo: 22820 +.. date: 9757 +.. nonce: hix_8X +.. section: IDLE + +Explain need for *print* when running file from Idle editor. + +.. + +.. bpo: 25224 +.. date: 9756 +.. nonce: UVMYQq +.. section: IDLE + +Doc: augment Idle feature list and no-subprocess section. + +.. + +.. bpo: 25219 +.. date: 9755 +.. nonce: 8_9DYg +.. section: IDLE + +Update doc for Idle command line options. Some were missing and notes were +not correct. + +.. + +.. bpo: 24861 +.. date: 9754 +.. nonce: Ecg2yT +.. section: IDLE + +Most of idlelib is private and subject to change. Use idleib.idle.* to start +Idle. See idlelib.__init__.__doc__. + +.. + +.. bpo: 25199 +.. date: 9753 +.. nonce: ih7yY3 +.. section: IDLE + +Idle: add synchronization comments for future maintainers. + +.. + +.. bpo: 16893 +.. date: 9752 +.. nonce: bZtPgJ +.. section: IDLE + +Replace help.txt with help.html for Idle doc display. The new +idlelib/help.html is rstripped Doc/build/html/library/idle.html. It looks +better than help.txt and will better document Idle as released. The tkinter +html viewer that works for this file was written by Mark Roseman. The now +unused EditorWindow.HelpDialog class and helt.txt file are deprecated. + +.. + +.. bpo: 24199 +.. date: 9751 +.. nonce: VKnZEv +.. section: IDLE + +Deprecate unused idlelib.idlever with possible removal in 3.6. + +.. + +.. bpo: 24790 +.. date: 9750 +.. nonce: hD1hlj +.. section: IDLE + +Remove extraneous code (which also create 2 & 3 conflicts). + +.. + +.. bpo: 23672 +.. date: 9749 +.. nonce: 8td2se +.. section: IDLE + +Allow Idle to edit and run files with astral chars in name. Patch by Mohd +Sanad Zaki Rizvi. + +.. + +.. bpo: 24745 +.. date: 9748 +.. nonce: edbziT +.. section: IDLE + +Idle editor default font. Switch from Courier to platform-sensitive +TkFixedFont. This should not affect current customized font selections. If +there is a problem, edit $HOME/.idlerc/config-main.cfg and remove 'fontxxx' +entries from [Editor Window]. Patch by Mark Roseman. + +.. + +.. bpo: 21192 +.. date: 9747 +.. nonce: CdbipH +.. section: IDLE + +Idle editor. When a file is run, put its name in the restart bar. Do not +print false prompts. Original patch by Adnan Umer. + +.. + +.. bpo: 13884 +.. date: 9746 +.. nonce: vVcO1E +.. section: IDLE + +Idle menus. Remove tearoff lines. Patch by Roger Serwy. + +.. + +.. bpo: 23184 +.. date: 9745 +.. nonce: G_Cp9v +.. section: IDLE + +remove unused names and imports in idlelib. Initial patch by Al Sweigart. + +.. + +.. bpo: 25616 +.. date: 9744 +.. nonce: Qr-60p +.. section: Tests + +Tests for OrderedDict are extracted from test_collections into separate file +test_ordered_dict. + +.. + +.. bpo: 25099 +.. date: 9743 +.. nonce: tJQOWx +.. section: Tests + +Make test_compileall not fail when an entry on sys.path cannot be written to +(commonly seen in administrative installs on Windows). + +.. + +.. bpo: 24751 +.. date: 9742 +.. nonce: pL2pbj +.. section: Tests + +When running regrtest with the ``-w`` command line option, a test run is no +longer marked as a failure if all tests succeed when re-run. + +.. + +.. bpo: 21520 +.. date: 9741 +.. nonce: FKtvmQ +.. section: Tests + +test_zipfile no longer fails if the word 'bad' appears anywhere in the name +of the current directory. + +.. + +.. bpo: 23799 +.. date: 9740 +.. nonce: XU2xDw +.. section: Tests + +Added test.support.start_threads() for running and cleaning up multiple +threads. + +.. + +.. bpo: 22390 +.. date: 9739 +.. nonce: UPVFnq +.. section: Tests + +test.regrtest now emits a warning if temporary files or directories are left +after running a test. + +.. + +.. bpo: 23583 +.. date: 9738 +.. nonce: bY8AbM +.. section: Tests + +Added tests for standard IO streams in IDLE. + +.. + +.. bpo: 23445 +.. date: 9737 +.. nonce: 7fmkYO +.. section: Build + +pydebug builds now use "gcc -Og" where possible, to make the resulting +executable faster. + +.. + +.. bpo: 24603 +.. date: 9736 +.. nonce: u0K8F- +.. section: Build + +Update Windows builds to use OpenSSL1.0.2d and OS X 10.5 installer to use +OpenSSL 1.0.2e. + +.. + +.. bpo: 23998 +.. date: 9735 +.. nonce: z7mlLW +.. section: C API + +PyImport_ReInitLock() now checks for lock allocation error + +.. + +.. bpo: 12067 +.. date: 9734 +.. nonce: nLD2M- +.. section: Documentation + +Rewrite Comparisons section in the Expressions chapter of the language +reference. Some of the details of comparing mixed types were incorrect or +ambiguous. NotImplemented is only relevant at a lower level than the +Expressions chapter. Added details of comparing range() objects, and default +behaviour and consistency suggestions for user-defined classes. Patch from +Andy Maier. + +.. + +.. bpo: 24952 +.. date: 9733 +.. nonce: RHhFPE +.. section: Documentation + +Clarify the default size argument of stack_size() in the "threading" and +"_thread" modules. Patch from Mattip. + +.. + +.. bpo: 24808 +.. date: 9732 +.. nonce: ux_TKt +.. section: Documentation + +Update the types of some PyTypeObject fields. Patch by Joseph Weston. + +.. + +.. bpo: 22812 +.. date: 9731 +.. nonce: kLCF0G +.. section: Documentation + +Fix unittest discovery examples. Patch from Pam McA'Nulty. + +.. + +.. bpo: 24129 +.. date: 9730 +.. nonce: Imr54z +.. section: Documentation + +Clarify the reference documentation for name resolution. This includes +removing the assumption that readers will be familiar with the name +resolution scheme Python used prior to the introduction of lexical scoping +for function namespaces. Patch by Ivan Levkivskyi. + +.. + +.. bpo: 20769 +.. date: 9729 +.. nonce: ZUc9z9 +.. section: Documentation + +Improve reload() docs. Patch by Dorian Pula. + +.. + +.. bpo: 23589 +.. date: 9728 +.. nonce: rjU421 +.. section: Documentation + +Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan. + +.. + +.. bpo: 24729 +.. date: 9727 +.. nonce: PH3A9p +.. section: Documentation + +Correct IO tutorial to match implementation regarding encoding parameter to +open function. + +.. + +.. bpo: 24351 +.. date: 9726 +.. nonce: XeSVl5 +.. section: Documentation + +Clarify what is meant by "identifier" in the context of string.Template +instances. + +.. + +.. bpo: 22155 +.. date: 9725 +.. nonce: 9EbOit +.. section: Documentation + +Add File Handlers subsection with createfilehandler to tkinter doc. Remove +obsolete example from FAQ. Patch by Martin Panter. + +.. + +.. bpo: 24029 +.. date: 9724 +.. nonce: M2Bnks +.. section: Documentation + +Document the name binding behavior for submodule imports. + +.. + +.. bpo: 24077 +.. date: 9723 +.. nonce: 48QXOw +.. section: Documentation + +Fix typo in man page for -I command option: -s, not -S. + +.. + +.. bpo: 25440 +.. date: 9722 +.. nonce: 5xhyGr +.. section: Tools/Demos + +Fix output of python-config --extension-suffix. + +.. + +.. bpo: 23330 +.. date: 9721 +.. nonce: LTlKDp +.. section: Tools/Demos + +h2py now supports arbitrary filenames in #include. + +.. + +.. bpo: 24031 +.. date: 9720 +.. nonce: duGo88 +.. section: Tools/Demos + +make patchcheck now supports git checkouts, too. + +.. + +.. bpo: 24306 +.. date: 9719 +.. nonce: OJn7Rb +.. section: Windows + +Sets component ID for launcher to match 3.5 and later to avoid downgrading. + +.. + +.. bpo: 25022 +.. date: 9718 +.. nonce: vAt_zr +.. section: Windows + +Removed very outdated PC/example_nt/ directory. diff --git a/Misc/NEWS.d/3.4.5.rst b/Misc/NEWS.d/3.4.5.rst new file mode 100644 index 00000000000000..a98fac5d709553 --- /dev/null +++ b/Misc/NEWS.d/3.4.5.rst @@ -0,0 +1,7 @@ +.. bpo: 26867 +.. date: 9982 +.. nonce: QPSyP5 +.. release date: 2016-06-26 +.. section: Tests + +Ubuntu's openssl OP_NO_SSLv3 is forced on by default; fix test. diff --git a/Misc/NEWS.d/3.4.5rc1.rst b/Misc/NEWS.d/3.4.5rc1.rst new file mode 100644 index 00000000000000..bbed1a1af99061 --- /dev/null +++ b/Misc/NEWS.d/3.4.5rc1.rst @@ -0,0 +1,101 @@ +.. bpo: 26478 +.. date: 9981 +.. nonce: n0dB8e +.. release date: 2016-06-11 +.. section: Core and Builtins + +Fix semantic bugs when using binary operators with dictionary views and +tuples. + +.. + +.. bpo: 26171 +.. date: 9980 +.. nonce: 8SaQEa +.. section: Core and Builtins + +Fix possible integer overflow and heap corruption in zipimporter.get_data(). + +.. + +.. bpo: 26556 +.. date: 9979 +.. nonce: v5j2uL +.. section: Library + +Update expat to 2.1.1, fixes CVE-2015-1283. + +.. + +.. bpo: 0 +.. date: 9978 +.. nonce: qP8WT- +.. section: Library + +Fix TLS stripping vulnerability in smptlib, CVE-2016-0772. Reported by Team +Oststrom + +.. + +.. bpo: 25939 +.. date: 9977 +.. nonce: I-qK2E +.. section: Library + +On Windows open the cert store readonly in ssl.enum_certificates. + +.. + +.. bpo: 26012 +.. date: 9976 +.. nonce: KC-JIr +.. section: Library + +Don't traverse into symlinks for ** pattern in pathlib.Path.[r]glob(). + +.. + +.. bpo: 24120 +.. date: 9975 +.. nonce: Yiwa0h +.. section: Library + +Ignore PermissionError when traversing a tree with pathlib.Path.[r]glob(). +Patch by Ulrich Petri. + +.. + +.. bpo: 0 +.. date: 9974 +.. nonce: rtZyid +.. section: Library + +Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu Davis. + +.. + +.. bpo: 0 +.. date: 9973 +.. nonce: R3C9Tn +.. section: Library + +Add asyncio.timeout() context manager. + +.. + +.. bpo: 26050 +.. date: 9972 +.. nonce: sclyvk +.. section: Library + +Add asyncio.StreamReader.readuntil() method. Patch by Марк Коренберг. + +.. + +.. bpo: 25940 +.. date: 9971 +.. nonce: PgiLVN +.. section: Tests + +Changed test_ssl to use self-signed.pythontest.net. This avoids relying on +svn.python.org, which recently changed root certificate. diff --git a/Misc/NEWS.d/3.4.6.rst b/Misc/NEWS.d/3.4.6.rst new file mode 100644 index 00000000000000..89e0bc23769784 --- /dev/null +++ b/Misc/NEWS.d/3.4.6.rst @@ -0,0 +1,7 @@ +.. bpo: 0 +.. date: 9995 +.. no changes: True +.. nonce: 9jLltj +.. release date: 2017-01-17 + +There were no changes between 3.4.6rc1 and 3.4.6 final. diff --git a/Misc/NEWS.d/3.4.6rc1.rst b/Misc/NEWS.d/3.4.6rc1.rst new file mode 100644 index 00000000000000..229ee48bcfee59 --- /dev/null +++ b/Misc/NEWS.d/3.4.6rc1.rst @@ -0,0 +1,114 @@ +.. bpo: 28648 +.. date: 9994 +.. nonce: z7B52W +.. release date: 2017-01-02 +.. section: Core and Builtins + +Fixed crash in Py_DecodeLocale() in debug build on Mac OS X when decode +astral characters. Patch by Xiang Zhang. + +.. + +.. bpo: 28426 +.. date: 9993 +.. nonce: E_quyK +.. section: Core and Builtins + +Fixed potential crash in PyUnicode_AsDecodedObject() in debug build. + +.. + +.. bpo: 28563 +.. date: 9992 +.. nonce: iweEiw +.. section: Library + +Fixed possible DoS and arbitrary code execution when handle plural form +selections in the gettext module. The expression parser now supports exact +syntax supported by GNU gettext. + +.. + +.. bpo: 0 +.. date: 9991 +.. nonce: Ny9oPv +.. section: Library + +In the curses module, raise an error if window.getstr() or window.instr() is +passed a negative value. + +.. + +.. bpo: 27783 +.. date: 9990 +.. nonce: 6fCCY9 +.. section: Library + +Fix possible usage of uninitialized memory in operator.methodcaller. + +.. + +.. bpo: 27774 +.. date: 9989 +.. nonce: FDcik1 +.. section: Library + +Fix possible Py_DECREF on unowned object in _sre. + +.. + +.. bpo: 27760 +.. date: 9988 +.. nonce: gxMjp4 +.. section: Library + +Fix possible integer overflow in binascii.b2a_qp. + +.. + +.. bpo: 27758 +.. date: 9987 +.. nonce: x9DC4R +.. section: Library + +Fix possible integer overflow in the _csv module for large record lengths. + +.. + +.. bpo: 27568 +.. date: 9986 +.. nonce: OnuO9s +.. section: Library + +Prevent HTTPoxy attack (CVE-2016-1000110). Ignore the HTTP_PROXY variable +when REQUEST_METHOD environment is set, which indicates that the script is +in CGI mode. + +.. + +.. bpo: 27759 +.. date: 9985 +.. nonce: qpMDGq +.. section: Library + +Fix selectors incorrectly retain invalid file descriptors. Patch by Mark +Williams. + +.. + +.. bpo: 28248 +.. date: 9984 +.. nonce: RYLa4f +.. section: Build + +Update Windows build to use OpenSSL 1.0.2j. + +.. + +.. bpo: 27369 +.. date: 9983 +.. nonce: LG7U2D +.. section: Tests + +In test_pyexpat, avoid testing an error message detail that changed in Expat +2.2.0. diff --git a/Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst b/Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst new file mode 100644 index 00000000000000..da5b8d1a2cac2b --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst @@ -0,0 +1,3 @@ +Fixed various segfaults with dict when input collections are mutated during +searching, inserting or comparing. Based on patches by Duane Griffin and +Tim Mitchell. diff --git a/Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst b/Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst new file mode 100644 index 00000000000000..ea4046ead7de0d --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst @@ -0,0 +1,2 @@ +Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a +third-party asyncio-based replacement. diff --git a/Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst b/Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst new file mode 100644 index 00000000000000..f21375d16d7916 --- /dev/null +++ b/Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst @@ -0,0 +1,2 @@ +Remove 3DES from ssl module's default cipher list to counter measure sweet32 +attack (CVE-2016-2183). diff --git a/Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst b/Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst new file mode 100644 index 00000000000000..2c764439a09bb5 --- /dev/null +++ b/Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst @@ -0,0 +1,4 @@ +.. original section: Library + +Prevent environment variables injection in subprocess on Windows. Prevent +passing other invalid environment variables and command arguments. From e9a74c416cb89a0d329995ff3e60c498adb2f689 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Sun, 23 Jul 2017 17:59:56 -0700 Subject: [PATCH 13/24] blurb release for 3.4.7rc1. --- Misc/NEWS.d/3.4.7rc1.rst | 99 +++++++++++++++++++ .../Core and Builtins/04.bpo-27945.p29r3O.rst | 3 - .../2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst | 1 - .../Documentation/03.bpo-25008.CeIzyU.rst | 2 - .../next/Library/01.bpo-27850.kIVQ0m.rst | 2 - .../next/Security/02.bpo-30730.ZF8XGV.rst | 4 - .../2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst | 4 - .../2017-07-11-22-07-03.bpo-26657.wvpzFD.rst | 3 - .../2017-07-11-22-25-24.bpo-30694.oOf3Er.rst | 8 -- .../2017-07-11-22-26-48.bpo-29591.cOeMX-.rst | 3 - 10 files changed, 99 insertions(+), 30 deletions(-) create mode 100644 Misc/NEWS.d/3.4.7rc1.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst delete mode 100644 Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst delete mode 100644 Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst delete mode 100644 Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst delete mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst delete mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst delete mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst delete mode 100644 Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst diff --git a/Misc/NEWS.d/3.4.7rc1.rst b/Misc/NEWS.d/3.4.7rc1.rst new file mode 100644 index 00000000000000..16ad0ffe07e0f4 --- /dev/null +++ b/Misc/NEWS.d/3.4.7rc1.rst @@ -0,0 +1,99 @@ +.. bpo: 29591 +.. date: 2017-07-11-22-26-48 +.. nonce: cOeMX- +.. release date: 2017-07-23 +.. section: Security + +Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and +CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more +information. + +.. + +.. bpo: 30694 +.. date: 2017-07-11-22-25-24 +.. nonce: oOf3Er +.. section: Security + +Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security +vulnerabilities including: CVE-2017-9233 (External entity infinite loop +DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix +regression bugs from 2.2.0's fix to CVE-2016-0718) and CVE-2012-0876 +(Counter hash flooding with SipHash). Note: the CVE-2016-5300 (Use os- +specific entropy sources like getrandom) doesn't impact Python, since Python +already gets entropy from the OS to set the expat secret using +``XML_SetHashSalt()``. + +.. + +.. bpo: 26657 +.. date: 2017-07-11-22-07-03 +.. nonce: wvpzFD +.. section: Security + +Fix directory traversal vulnerability with http.server on Windows. This +fixes a regression that was introduced in 3.3.4rc1 and 3.4.0rc1. Based on +patch by Philipp Hagemeister. + +.. + +.. bpo: 30500 +.. date: 2017-07-11-22-02-51 +.. nonce: wXUrkQ +.. section: Security + +Fix urllib.parse.splithost() to correctly parse fragments. For example, +``splithost('//127.0.0.1#@evil.com/')`` now correctly returns the +``127.0.0.1`` host, instead of treating ``@evil.com`` as the host in an +authentification (``login@host``). + +.. + +.. bpo: 30730 +.. date: 02 +.. nonce: ZF8XGV +.. original section: Library +.. section: Security + +Prevent environment variables injection in subprocess on Windows. Prevent +passing other invalid environment variables and command arguments. + +.. + +.. bpo: 26617 +.. date: 2017-07-15-13-55-22 +.. nonce: Gh5LvN +.. section: Core and Builtins + +Fix crash when GC runs during weakref callbacks. + +.. + +.. bpo: 27945 +.. date: 04 +.. nonce: p29r3O +.. section: Core and Builtins + +Fixed various segfaults with dict when input collections are mutated during +searching, inserting or comparing. Based on patches by Duane Griffin and +Tim Mitchell. + +.. + +.. bpo: 27850 +.. date: 01 +.. nonce: kIVQ0m +.. section: Library + +Remove 3DES from ssl module's default cipher list to counter measure sweet32 +attack (CVE-2016-2183). + +.. + +.. bpo: 25008 +.. date: 03 +.. nonce: CeIzyU +.. section: Documentation + +Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a +third-party asyncio-based replacement. diff --git a/Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst b/Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst deleted file mode 100644 index da5b8d1a2cac2b..00000000000000 --- a/Misc/NEWS.d/next/Core and Builtins/04.bpo-27945.p29r3O.rst +++ /dev/null @@ -1,3 +0,0 @@ -Fixed various segfaults with dict when input collections are mutated during -searching, inserting or comparing. Based on patches by Duane Griffin and -Tim Mitchell. diff --git a/Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst b/Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst deleted file mode 100644 index c3a41396df8f53..00000000000000 --- a/Misc/NEWS.d/next/Core and Builtins/2017-07-15-13-55-22.bpo-26617.Gh5LvN.rst +++ /dev/null @@ -1 +0,0 @@ -Fix crash when GC runs during weakref callbacks. diff --git a/Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst b/Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst deleted file mode 100644 index ea4046ead7de0d..00000000000000 --- a/Misc/NEWS.d/next/Documentation/03.bpo-25008.CeIzyU.rst +++ /dev/null @@ -1,2 +0,0 @@ -Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a -third-party asyncio-based replacement. diff --git a/Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst b/Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst deleted file mode 100644 index f21375d16d7916..00000000000000 --- a/Misc/NEWS.d/next/Library/01.bpo-27850.kIVQ0m.rst +++ /dev/null @@ -1,2 +0,0 @@ -Remove 3DES from ssl module's default cipher list to counter measure sweet32 -attack (CVE-2016-2183). diff --git a/Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst b/Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst deleted file mode 100644 index 2c764439a09bb5..00000000000000 --- a/Misc/NEWS.d/next/Security/02.bpo-30730.ZF8XGV.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. original section: Library - -Prevent environment variables injection in subprocess on Windows. Prevent -passing other invalid environment variables and command arguments. diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst deleted file mode 100644 index 6570e709d6bfac..00000000000000 --- a/Misc/NEWS.d/next/Security/2017-07-11-22-02-51.bpo-30500.wXUrkQ.rst +++ /dev/null @@ -1,4 +0,0 @@ -Fix urllib.parse.splithost() to correctly parse fragments. For example, -``splithost('//127.0.0.1#@evil.com/')`` now correctly returns the -``127.0.0.1`` host, instead of treating ``@evil.com`` as the host in an -authentification (``login@host``). diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst deleted file mode 100644 index ac1dc14d061a7b..00000000000000 --- a/Misc/NEWS.d/next/Security/2017-07-11-22-07-03.bpo-26657.wvpzFD.rst +++ /dev/null @@ -1,3 +0,0 @@ -Fix directory traversal vulnerability with http.server on Windows. This -fixes a regression that was introduced in 3.3.4rc1 and 3.4.0rc1. Based on -patch by Philipp Hagemeister. diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst deleted file mode 100644 index ee2c0a5c35b160..00000000000000 --- a/Misc/NEWS.d/next/Security/2017-07-11-22-25-24.bpo-30694.oOf3Er.rst +++ /dev/null @@ -1,8 +0,0 @@ -Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security -vulnerabilities including: CVE-2017-9233 (External entity infinite loop -DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix -regression bugs from 2.2.0's fix to CVE-2016-0718) and CVE-2012-0876 -(Counter hash flooding with SipHash). Note: the CVE-2016-5300 (Use os- -specific entropy sources like getrandom) doesn't impact Python, since Python -already gets entropy from the OS to set the expat secret using -``XML_SetHashSalt()``. diff --git a/Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst b/Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst deleted file mode 100644 index ca740bb1b11a6a..00000000000000 --- a/Misc/NEWS.d/next/Security/2017-07-11-22-26-48.bpo-29591.cOeMX-.rst +++ /dev/null @@ -1,3 +0,0 @@ -Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and -CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more -information. From 961168d3e785d99ebd4fb9fdf8803642b8669d26 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Sun, 23 Jul 2017 18:11:33 -0700 Subject: [PATCH 14/24] Update pydoc topics and susp-ignored for 3.4.7rc1. --- Doc/tools/susp-ignored.csv | 2 +- Lib/pydoc_data/topics.py | 12941 ++++++++++++++++++++++++++++++++++- 2 files changed, 12864 insertions(+), 79 deletions(-) diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv index 032531d3cb7121..32e21f0dce4d0e 100644 --- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -281,7 +281,7 @@ whatsnew/3.2,,:location,zope9-location = ${zope9:location} whatsnew/3.2,,:prefix,zope-conf = ${custom:prefix}/etc/zope.conf whatsnew/changelog,,:platform,:platform: whatsnew/changelog,,:gz,": TarFile opened with external fileobj and ""w:gz"" mode didn't" -whatsnew/changelog,,:PythonCmd,"With Tk < 8.5 _tkinter.c:PythonCmd() raised UnicodeDecodeError, caused" +whatsnew/changelog,,:PythonCmd,"Tk < 8.5 _tkinter.c:PythonCmd() raised UnicodeDecodeError, caused IDLE to" whatsnew/changelog,,::,": Fix FTP tests for IPv6, bind to ""::1"" instead of ""localhost""." whatsnew/changelog,,::,": Use ""127.0.0.1"" or ""::1"" instead of ""localhost"" as much as" whatsnew/changelog,,:password,user:password diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py index 1cc4ef555e59a8..81464b0832345a 100644 --- a/Lib/pydoc_data/topics.py +++ b/Lib/pydoc_data/topics.py @@ -1,79 +1,12864 @@ # -*- coding: utf-8 -*- -# Autogenerated by Sphinx on Sun Jan 1 22:08:13 2017 -topics = {'assert': u'\nThe "assert" statement\n**********************\n\nAssert statements are a convenient way to insert debugging assertions\ninto a program:\n\n assert_stmt ::= "assert" expression ["," expression]\n\nThe simple form, "assert expression", is equivalent to\n\n if __debug__:\n if not expression: raise AssertionError\n\nThe extended form, "assert expression1, expression2", is equivalent to\n\n if __debug__:\n if not expression1: raise AssertionError(expression2)\n\nThese equivalences assume that "__debug__" and "AssertionError" refer\nto the built-in variables with those names. In the current\nimplementation, the built-in variable "__debug__" is "True" under\nnormal circumstances, "False" when optimization is requested (command\nline option -O). The current code generator emits no code for an\nassert statement when optimization is requested at compile time. Note\nthat it is unnecessary to include the source code for the expression\nthat failed in the error message; it will be displayed as part of the\nstack trace.\n\nAssignments to "__debug__" are illegal. The value for the built-in\nvariable is determined when the interpreter starts.\n', - 'assignment': u'\nAssignment statements\n*********************\n\nAssignment statements are used to (re)bind names to values and to\nmodify attributes or items of mutable objects:\n\n assignment_stmt ::= (target_list "=")+ (expression_list | yield_expression)\n target_list ::= target ("," target)* [","]\n target ::= identifier\n | "(" target_list ")"\n | "[" target_list "]"\n | attributeref\n | subscription\n | slicing\n | "*" target\n\n(See section *Primaries* for the syntax definitions for\n*attributeref*, *subscription*, and *slicing*.)\n\nAn assignment statement evaluates the expression list (remember that\nthis can be a single expression or a comma-separated list, the latter\nyielding a tuple) and assigns the single resulting object to each of\nthe target lists, from left to right.\n\nAssignment is defined recursively depending on the form of the target\n(list). When a target is part of a mutable object (an attribute\nreference, subscription or slicing), the mutable object must\nultimately perform the assignment and decide about its validity, and\nmay raise an exception if the assignment is unacceptable. The rules\nobserved by various types and the exceptions raised are given with the\ndefinition of the object types (see section *The standard type\nhierarchy*).\n\nAssignment of an object to a target list, optionally enclosed in\nparentheses or square brackets, is recursively defined as follows.\n\n* If the target list is a single target: The object is assigned to\n that target.\n\n* If the target list is a comma-separated list of targets: The\n object must be an iterable with the same number of items as there\n are targets in the target list, and the items are assigned, from\n left to right, to the corresponding targets.\n\n * If the target list contains one target prefixed with an\n asterisk, called a "starred" target: The object must be a sequence\n with at least as many items as there are targets in the target\n list, minus one. The first items of the sequence are assigned,\n from left to right, to the targets before the starred target. The\n final items of the sequence are assigned to the targets after the\n starred target. A list of the remaining items in the sequence is\n then assigned to the starred target (the list can be empty).\n\n * Else: The object must be a sequence with the same number of\n items as there are targets in the target list, and the items are\n assigned, from left to right, to the corresponding targets.\n\nAssignment of an object to a single target is recursively defined as\nfollows.\n\n* If the target is an identifier (name):\n\n * If the name does not occur in a "global" or "nonlocal" statement\n in the current code block: the name is bound to the object in the\n current local namespace.\n\n * Otherwise: the name is bound to the object in the global\n namespace or the outer namespace determined by "nonlocal",\n respectively.\n\n The name is rebound if it was already bound. This may cause the\n reference count for the object previously bound to the name to reach\n zero, causing the object to be deallocated and its destructor (if it\n has one) to be called.\n\n* If the target is a target list enclosed in parentheses or in\n square brackets: The object must be an iterable with the same number\n of items as there are targets in the target list, and its items are\n assigned, from left to right, to the corresponding targets.\n\n* If the target is an attribute reference: The primary expression in\n the reference is evaluated. It should yield an object with\n assignable attributes; if this is not the case, "TypeError" is\n raised. That object is then asked to assign the assigned object to\n the given attribute; if it cannot perform the assignment, it raises\n an exception (usually but not necessarily "AttributeError").\n\n Note: If the object is a class instance and the attribute reference\n occurs on both sides of the assignment operator, the RHS expression,\n "a.x" can access either an instance attribute or (if no instance\n attribute exists) a class attribute. The LHS target "a.x" is always\n set as an instance attribute, creating it if necessary. Thus, the\n two occurrences of "a.x" do not necessarily refer to the same\n attribute: if the RHS expression refers to a class attribute, the\n LHS creates a new instance attribute as the target of the\n assignment:\n\n class Cls:\n x = 3 # class variable\n inst = Cls()\n inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x as 3\n\n This description does not necessarily apply to descriptor\n attributes, such as properties created with "property()".\n\n* If the target is a subscription: The primary expression in the\n reference is evaluated. It should yield either a mutable sequence\n object (such as a list) or a mapping object (such as a dictionary).\n Next, the subscript expression is evaluated.\n\n If the primary is a mutable sequence object (such as a list), the\n subscript must yield an integer. If it is negative, the sequence\'s\n length is added to it. The resulting value must be a nonnegative\n integer less than the sequence\'s length, and the sequence is asked\n to assign the assigned object to its item with that index. If the\n index is out of range, "IndexError" is raised (assignment to a\n subscripted sequence cannot add new items to a list).\n\n If the primary is a mapping object (such as a dictionary), the\n subscript must have a type compatible with the mapping\'s key type,\n and the mapping is then asked to create a key/datum pair which maps\n the subscript to the assigned object. This can either replace an\n existing key/value pair with the same key value, or insert a new\n key/value pair (if no key with the same value existed).\n\n For user-defined objects, the "__setitem__()" method is called with\n appropriate arguments.\n\n* If the target is a slicing: The primary expression in the\n reference is evaluated. It should yield a mutable sequence object\n (such as a list). The assigned object should be a sequence object\n of the same type. Next, the lower and upper bound expressions are\n evaluated, insofar they are present; defaults are zero and the\n sequence\'s length. The bounds should evaluate to integers. If\n either bound is negative, the sequence\'s length is added to it. The\n resulting bounds are clipped to lie between zero and the sequence\'s\n length, inclusive. Finally, the sequence object is asked to replace\n the slice with the items of the assigned sequence. The length of\n the slice may be different from the length of the assigned sequence,\n thus changing the length of the target sequence, if the target\n sequence allows it.\n\n**CPython implementation detail:** In the current implementation, the\nsyntax for targets is taken to be the same as for expressions, and\ninvalid syntax is rejected during the code generation phase, causing\nless detailed error messages.\n\nAlthough the definition of assignment implies that overlaps between\nthe left-hand side and the right-hand side are \'simultanenous\' (for\nexample "a, b = b, a" swaps two variables), overlaps *within* the\ncollection of assigned-to variables occur left-to-right, sometimes\nresulting in confusion. For instance, the following program prints\n"[0, 2]":\n\n x = [0, 1]\n i = 0\n i, x[i] = 1, 2 # i is updated, then x[i] is updated\n print(x)\n\nSee also: **PEP 3132** - Extended Iterable Unpacking\n\n The specification for the "*target" feature.\n\n\nAugmented assignment statements\n===============================\n\nAugmented assignment is the combination, in a single statement, of a\nbinary operation and an assignment statement:\n\n augmented_assignment_stmt ::= augtarget augop (expression_list | yield_expression)\n augtarget ::= identifier | attributeref | subscription | slicing\n augop ::= "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="\n | ">>=" | "<<=" | "&=" | "^=" | "|="\n\n(See section *Primaries* for the syntax definitions of the last three\nsymbols.)\n\nAn augmented assignment evaluates the target (which, unlike normal\nassignment statements, cannot be an unpacking) and the expression\nlist, performs the binary operation specific to the type of assignment\non the two operands, and assigns the result to the original target.\nThe target is only evaluated once.\n\nAn augmented assignment expression like "x += 1" can be rewritten as\n"x = x + 1" to achieve a similar, but not exactly equal effect. In the\naugmented version, "x" is only evaluated once. Also, when possible,\nthe actual operation is performed *in-place*, meaning that rather than\ncreating a new object and assigning that to the target, the old object\nis modified instead.\n\nUnlike normal assignments, augmented assignments evaluate the left-\nhand side *before* evaluating the right-hand side. For example, "a[i]\n+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and performs\nthe addition, and lastly, it writes the result back to "a[i]".\n\nWith the exception of assigning to tuples and multiple targets in a\nsingle statement, the assignment done by augmented assignment\nstatements is handled the same way as normal assignments. Similarly,\nwith the exception of the possible *in-place* behavior, the binary\noperation performed by augmented assignment is the same as the normal\nbinary operations.\n\nFor targets which are attribute references, the same *caveat about\nclass and instance attributes* applies as for regular assignments.\n', - 'atom-identifiers': u'\nIdentifiers (Names)\n*******************\n\nAn identifier occurring as an atom is a name. See section\n*Identifiers and keywords* for lexical definition and section *Naming\nand binding* for documentation of naming and binding.\n\nWhen the name is bound to an object, evaluation of the atom yields\nthat object. When a name is not bound, an attempt to evaluate it\nraises a "NameError" exception.\n\n**Private name mangling:** When an identifier that textually occurs in\na class definition begins with two or more underscore characters and\ndoes not end in two or more underscores, it is considered a *private\nname* of that class. Private names are transformed to a longer form\nbefore code is generated for them. The transformation inserts the\nclass name, with leading underscores removed and a single underscore\ninserted, in front of the name. For example, the identifier "__spam"\noccurring in a class named "Ham" will be transformed to "_Ham__spam".\nThis transformation is independent of the syntactical context in which\nthe identifier is used. If the transformed name is extremely long\n(longer than 255 characters), implementation defined truncation may\nhappen. If the class name consists only of underscores, no\ntransformation is done.\n', - 'atom-literals': u"\nLiterals\n********\n\nPython supports string and bytes literals and various numeric\nliterals:\n\n literal ::= stringliteral | bytesliteral\n | integer | floatnumber | imagnumber\n\nEvaluation of a literal yields an object of the given type (string,\nbytes, integer, floating point number, complex number) with the given\nvalue. The value may be approximated in the case of floating point\nand imaginary (complex) literals. See section *Literals* for details.\n\nAll literals correspond to immutable data types, and hence the\nobject's identity is less important than its value. Multiple\nevaluations of literals with the same value (either the same\noccurrence in the program text or a different occurrence) may obtain\nthe same object or a different object with the same value.\n", - 'attribute-access': u'\nCustomizing attribute access\n****************************\n\nThe following methods can be defined to customize the meaning of\nattribute access (use of, assignment to, or deletion of "x.name") for\nclass instances.\n\nobject.__getattr__(self, name)\n\n Called when an attribute lookup has not found the attribute in the\n usual places (i.e. it is not an instance attribute nor is it found\n in the class tree for "self"). "name" is the attribute name. This\n method should return the (computed) attribute value or raise an\n "AttributeError" exception.\n\n Note that if the attribute is found through the normal mechanism,\n "__getattr__()" is not called. (This is an intentional asymmetry\n between "__getattr__()" and "__setattr__()".) This is done both for\n efficiency reasons and because otherwise "__getattr__()" would have\n no way to access other attributes of the instance. Note that at\n least for instance variables, you can fake total control by not\n inserting any values in the instance attribute dictionary (but\n instead inserting them in another object). See the\n "__getattribute__()" method below for a way to actually get total\n control over attribute access.\n\nobject.__getattribute__(self, name)\n\n Called unconditionally to implement attribute accesses for\n instances of the class. If the class also defines "__getattr__()",\n the latter will not be called unless "__getattribute__()" either\n calls it explicitly or raises an "AttributeError". This method\n should return the (computed) attribute value or raise an\n "AttributeError" exception. In order to avoid infinite recursion in\n this method, its implementation should always call the base class\n method with the same name to access any attributes it needs, for\n example, "object.__getattribute__(self, name)".\n\n Note: This method may still be bypassed when looking up special\n methods as the result of implicit invocation via language syntax\n or built-in functions. See *Special method lookup*.\n\nobject.__setattr__(self, name, value)\n\n Called when an attribute assignment is attempted. This is called\n instead of the normal mechanism (i.e. store the value in the\n instance dictionary). *name* is the attribute name, *value* is the\n value to be assigned to it.\n\n If "__setattr__()" wants to assign to an instance attribute, it\n should call the base class method with the same name, for example,\n "object.__setattr__(self, name, value)".\n\nobject.__delattr__(self, name)\n\n Like "__setattr__()" but for attribute deletion instead of\n assignment. This should only be implemented if "del obj.name" is\n meaningful for the object.\n\nobject.__dir__(self)\n\n Called when "dir()" is called on the object. A sequence must be\n returned. "dir()" converts the returned sequence to a list and\n sorts it.\n\n\nImplementing Descriptors\n========================\n\nThe following methods only apply when an instance of the class\ncontaining the method (a so-called *descriptor* class) appears in an\n*owner* class (the descriptor must be in either the owner\'s class\ndictionary or in the class dictionary for one of its parents). In the\nexamples below, "the attribute" refers to the attribute whose name is\nthe key of the property in the owner class\' "__dict__".\n\nobject.__get__(self, instance, owner)\n\n Called to get the attribute of the owner class (class attribute\n access) or of an instance of that class (instance attribute\n access). *owner* is always the owner class, while *instance* is the\n instance that the attribute was accessed through, or "None" when\n the attribute is accessed through the *owner*. This method should\n return the (computed) attribute value or raise an "AttributeError"\n exception.\n\nobject.__set__(self, instance, value)\n\n Called to set the attribute on an instance *instance* of the owner\n class to a new value, *value*.\n\nobject.__delete__(self, instance)\n\n Called to delete the attribute on an instance *instance* of the\n owner class.\n\nThe attribute "__objclass__" is interpreted by the "inspect" module as\nspecifying the class where this object was defined (setting this\nappropriately can assist in runtime introspection of dynamic class\nattributes). For callables, it may indicate that an instance of the\ngiven type (or a subclass) is expected or required as the first\npositional argument (for example, CPython sets this attribute for\nunbound methods that are implemented in C).\n\n\nInvoking Descriptors\n====================\n\nIn general, a descriptor is an object attribute with "binding\nbehavior", one whose attribute access has been overridden by methods\nin the descriptor protocol: "__get__()", "__set__()", and\n"__delete__()". If any of those methods are defined for an object, it\nis said to be a descriptor.\n\nThe default behavior for attribute access is to get, set, or delete\nthe attribute from an object\'s dictionary. For instance, "a.x" has a\nlookup chain starting with "a.__dict__[\'x\']", then\n"type(a).__dict__[\'x\']", and continuing through the base classes of\n"type(a)" excluding metaclasses.\n\nHowever, if the looked-up value is an object defining one of the\ndescriptor methods, then Python may override the default behavior and\ninvoke the descriptor method instead. Where this occurs in the\nprecedence chain depends on which descriptor methods were defined and\nhow they were called.\n\nThe starting point for descriptor invocation is a binding, "a.x". How\nthe arguments are assembled depends on "a":\n\nDirect Call\n The simplest and least common call is when user code directly\n invokes a descriptor method: "x.__get__(a)".\n\nInstance Binding\n If binding to an object instance, "a.x" is transformed into the\n call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n\nClass Binding\n If binding to a class, "A.x" is transformed into the call:\n "A.__dict__[\'x\'].__get__(None, A)".\n\nSuper Binding\n If "a" is an instance of "super", then the binding "super(B,\n obj).m()" searches "obj.__class__.__mro__" for the base class "A"\n immediately preceding "B" and then invokes the descriptor with the\n call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n\nFor instance bindings, the precedence of descriptor invocation depends\non the which descriptor methods are defined. A descriptor can define\nany combination of "__get__()", "__set__()" and "__delete__()". If it\ndoes not define "__get__()", then accessing the attribute will return\nthe descriptor object itself unless there is a value in the object\'s\ninstance dictionary. If the descriptor defines "__set__()" and/or\n"__delete__()", it is a data descriptor; if it defines neither, it is\na non-data descriptor. Normally, data descriptors define both\n"__get__()" and "__set__()", while non-data descriptors have just the\n"__get__()" method. Data descriptors with "__set__()" and "__get__()"\ndefined always override a redefinition in an instance dictionary. In\ncontrast, non-data descriptors can be overridden by instances.\n\nPython methods (including "staticmethod()" and "classmethod()") are\nimplemented as non-data descriptors. Accordingly, instances can\nredefine and override methods. This allows individual instances to\nacquire behaviors that differ from other instances of the same class.\n\nThe "property()" function is implemented as a data descriptor.\nAccordingly, instances cannot override the behavior of a property.\n\n\n__slots__\n=========\n\nBy default, instances of classes have a dictionary for attribute\nstorage. This wastes space for objects having very few instance\nvariables. The space consumption can become acute when creating large\nnumbers of instances.\n\nThe default can be overridden by defining *__slots__* in a class\ndefinition. The *__slots__* declaration takes a sequence of instance\nvariables and reserves just enough space in each instance to hold a\nvalue for each variable. Space is saved because *__dict__* is not\ncreated for each instance.\n\nobject.__slots__\n\n This class variable can be assigned a string, iterable, or sequence\n of strings with variable names used by instances. *__slots__*\n reserves space for the declared variables and prevents the\n automatic creation of *__dict__* and *__weakref__* for each\n instance.\n\n\nNotes on using *__slots__*\n--------------------------\n\n* When inheriting from a class without *__slots__*, the *__dict__*\n attribute of that class will always be accessible, so a *__slots__*\n definition in the subclass is meaningless.\n\n* Without a *__dict__* variable, instances cannot be assigned new\n variables not listed in the *__slots__* definition. Attempts to\n assign to an unlisted variable name raises "AttributeError". If\n dynamic assignment of new variables is desired, then add\n "\'__dict__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* Without a *__weakref__* variable for each instance, classes\n defining *__slots__* do not support weak references to its\n instances. If weak reference support is needed, then add\n "\'__weakref__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* *__slots__* are implemented at the class level by creating\n descriptors (*Implementing Descriptors*) for each variable name. As\n a result, class attributes cannot be used to set default values for\n instance variables defined by *__slots__*; otherwise, the class\n attribute would overwrite the descriptor assignment.\n\n* The action of a *__slots__* declaration is limited to the class\n where it is defined. As a result, subclasses will have a *__dict__*\n unless they also define *__slots__* (which must only contain names\n of any *additional* slots).\n\n* If a class defines a slot also defined in a base class, the\n instance variable defined by the base class slot is inaccessible\n (except by retrieving its descriptor directly from the base class).\n This renders the meaning of the program undefined. In the future, a\n check may be added to prevent this.\n\n* Nonempty *__slots__* does not work for classes derived from\n "variable-length" built-in types such as "int", "bytes" and "tuple".\n\n* Any non-string iterable may be assigned to *__slots__*. Mappings\n may also be used; however, in the future, special meaning may be\n assigned to the values corresponding to each key.\n\n* *__class__* assignment works only if both classes have the same\n *__slots__*.\n', - 'attribute-references': u'\nAttribute references\n********************\n\nAn attribute reference is a primary followed by a period and a name:\n\n attributeref ::= primary "." identifier\n\nThe primary must evaluate to an object of a type that supports\nattribute references, which most objects do. This object is then\nasked to produce the attribute whose name is the identifier. This\nproduction can be customized by overriding the "__getattr__()" method.\nIf this attribute is not available, the exception "AttributeError" is\nraised. Otherwise, the type and value of the object produced is\ndetermined by the object. Multiple evaluations of the same attribute\nreference may yield different objects.\n', - 'augassign': u'\nAugmented assignment statements\n*******************************\n\nAugmented assignment is the combination, in a single statement, of a\nbinary operation and an assignment statement:\n\n augmented_assignment_stmt ::= augtarget augop (expression_list | yield_expression)\n augtarget ::= identifier | attributeref | subscription | slicing\n augop ::= "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="\n | ">>=" | "<<=" | "&=" | "^=" | "|="\n\n(See section *Primaries* for the syntax definitions of the last three\nsymbols.)\n\nAn augmented assignment evaluates the target (which, unlike normal\nassignment statements, cannot be an unpacking) and the expression\nlist, performs the binary operation specific to the type of assignment\non the two operands, and assigns the result to the original target.\nThe target is only evaluated once.\n\nAn augmented assignment expression like "x += 1" can be rewritten as\n"x = x + 1" to achieve a similar, but not exactly equal effect. In the\naugmented version, "x" is only evaluated once. Also, when possible,\nthe actual operation is performed *in-place*, meaning that rather than\ncreating a new object and assigning that to the target, the old object\nis modified instead.\n\nUnlike normal assignments, augmented assignments evaluate the left-\nhand side *before* evaluating the right-hand side. For example, "a[i]\n+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and performs\nthe addition, and lastly, it writes the result back to "a[i]".\n\nWith the exception of assigning to tuples and multiple targets in a\nsingle statement, the assignment done by augmented assignment\nstatements is handled the same way as normal assignments. Similarly,\nwith the exception of the possible *in-place* behavior, the binary\noperation performed by augmented assignment is the same as the normal\nbinary operations.\n\nFor targets which are attribute references, the same *caveat about\nclass and instance attributes* applies as for regular assignments.\n', - 'binary': u'\nBinary arithmetic operations\n****************************\n\nThe binary arithmetic operations have the conventional priority\nlevels. Note that some of these operations also apply to certain non-\nnumeric types. Apart from the power operator, there are only two\nlevels, one for multiplicative operators and one for additive\noperators:\n\n m_expr ::= u_expr | m_expr "*" u_expr | m_expr "//" u_expr | m_expr "/" u_expr\n | m_expr "%" u_expr\n a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n\nThe "*" (multiplication) operator yields the product of its arguments.\nThe arguments must either both be numbers, or one argument must be an\ninteger and the other must be a sequence. In the former case, the\nnumbers are converted to a common type and then multiplied together.\nIn the latter case, sequence repetition is performed; a negative\nrepetition factor yields an empty sequence.\n\nThe "/" (division) and "//" (floor division) operators yield the\nquotient of their arguments. The numeric arguments are first\nconverted to a common type. Division of integers yields a float, while\nfloor division of integers results in an integer; the result is that\nof mathematical division with the \'floor\' function applied to the\nresult. Division by zero raises the "ZeroDivisionError" exception.\n\nThe "%" (modulo) operator yields the remainder from the division of\nthe first argument by the second. The numeric arguments are first\nconverted to a common type. A zero right argument raises the\n"ZeroDivisionError" exception. The arguments may be floating point\nnumbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals "4*0.7 +\n0.34".) The modulo operator always yields a result with the same sign\nas its second operand (or zero); the absolute value of the result is\nstrictly smaller than the absolute value of the second operand [1].\n\nThe floor division and modulo operators are connected by the following\nidentity: "x == (x//y)*y + (x%y)". Floor division and modulo are also\nconnected with the built-in function "divmod()": "divmod(x, y) ==\n(x//y, x%y)". [2].\n\nIn addition to performing the modulo operation on numbers, the "%"\noperator is also overloaded by string objects to perform old-style\nstring formatting (also known as interpolation). The syntax for\nstring formatting is described in the Python Library Reference,\nsection *printf-style String Formatting*.\n\nThe floor division operator, the modulo operator, and the "divmod()"\nfunction are not defined for complex numbers. Instead, convert to a\nfloating point number using the "abs()" function if appropriate.\n\nThe "+" (addition) operator yields the sum of its arguments. The\narguments must either both be numbers or both be sequences of the same\ntype. In the former case, the numbers are converted to a common type\nand then added together. In the latter case, the sequences are\nconcatenated.\n\nThe "-" (subtraction) operator yields the difference of its arguments.\nThe numeric arguments are first converted to a common type.\n', - 'bitwise': u'\nBinary bitwise operations\n*************************\n\nEach of the three bitwise operations has a different priority level:\n\n and_expr ::= shift_expr | and_expr "&" shift_expr\n xor_expr ::= and_expr | xor_expr "^" and_expr\n or_expr ::= xor_expr | or_expr "|" xor_expr\n\nThe "&" operator yields the bitwise AND of its arguments, which must\nbe integers.\n\nThe "^" operator yields the bitwise XOR (exclusive OR) of its\narguments, which must be integers.\n\nThe "|" operator yields the bitwise (inclusive) OR of its arguments,\nwhich must be integers.\n', - 'bltin-code-objects': u'\nCode Objects\n************\n\nCode objects are used by the implementation to represent "pseudo-\ncompiled" executable Python code such as a function body. They differ\nfrom function objects because they don\'t contain a reference to their\nglobal execution environment. Code objects are returned by the built-\nin "compile()" function and can be extracted from function objects\nthrough their "__code__" attribute. See also the "code" module.\n\nA code object can be executed or evaluated by passing it (instead of a\nsource string) to the "exec()" or "eval()" built-in functions.\n\nSee *The standard type hierarchy* for more information.\n', - 'bltin-ellipsis-object': u'\nThe Ellipsis Object\n*******************\n\nThis object is commonly used by slicing (see *Slicings*). It supports\nno special operations. There is exactly one ellipsis object, named\n"Ellipsis" (a built-in name). "type(Ellipsis)()" produces the\n"Ellipsis" singleton.\n\nIt is written as "Ellipsis" or "...".\n', - 'bltin-null-object': u'\nThe Null Object\n***************\n\nThis object is returned by functions that don\'t explicitly return a\nvalue. It supports no special operations. There is exactly one null\nobject, named "None" (a built-in name). "type(None)()" produces the\nsame singleton.\n\nIt is written as "None".\n', - 'bltin-type-objects': u'\nType Objects\n************\n\nType objects represent the various object types. An object\'s type is\naccessed by the built-in function "type()". There are no special\noperations on types. The standard module "types" defines names for\nall standard built-in types.\n\nTypes are written like this: "".\n', - 'booleans': u'\nBoolean operations\n******************\n\n or_test ::= and_test | or_test "or" and_test\n and_test ::= not_test | and_test "and" not_test\n not_test ::= comparison | "not" not_test\n\nIn the context of Boolean operations, and also when expressions are\nused by control flow statements, the following values are interpreted\nas false: "False", "None", numeric zero of all types, and empty\nstrings and containers (including strings, tuples, lists,\ndictionaries, sets and frozensets). All other values are interpreted\nas true. User-defined objects can customize their truth value by\nproviding a "__bool__()" method.\n\nThe operator "not" yields "True" if its argument is false, "False"\notherwise.\n\nThe expression "x and y" first evaluates *x*; if *x* is false, its\nvalue is returned; otherwise, *y* is evaluated and the resulting value\nis returned.\n\nThe expression "x or y" first evaluates *x*; if *x* is true, its value\nis returned; otherwise, *y* is evaluated and the resulting value is\nreturned.\n\n(Note that neither "and" nor "or" restrict the value and type they\nreturn to "False" and "True", but rather return the last evaluated\nargument. This is sometimes useful, e.g., if "s" is a string that\nshould be replaced by a default value if it is empty, the expression\n"s or \'foo\'" yields the desired value. Because "not" has to create a\nnew value, it returns a boolean value regardless of the type of its\nargument (for example, "not \'foo\'" produces "False" rather than "\'\'".)\n', - 'break': u'\nThe "break" statement\n*********************\n\n break_stmt ::= "break"\n\n"break" may only occur syntactically nested in a "for" or "while"\nloop, but not nested in a function or class definition within that\nloop.\n\nIt terminates the nearest enclosing loop, skipping the optional "else"\nclause if the loop has one.\n\nIf a "for" loop is terminated by "break", the loop control target\nkeeps its current value.\n\nWhen "break" passes control out of a "try" statement with a "finally"\nclause, that "finally" clause is executed before really leaving the\nloop.\n', - 'callable-types': u'\nEmulating callable objects\n**************************\n\nobject.__call__(self[, args...])\n\n Called when the instance is "called" as a function; if this method\n is defined, "x(arg1, arg2, ...)" is a shorthand for\n "x.__call__(arg1, arg2, ...)".\n', - 'calls': u'\nCalls\n*****\n\nA call calls a callable object (e.g., a *function*) with a possibly\nempty series of *arguments*:\n\n call ::= primary "(" [argument_list [","] | comprehension] ")"\n argument_list ::= positional_arguments ["," keyword_arguments]\n ["," "*" expression] ["," keyword_arguments]\n ["," "**" expression]\n | keyword_arguments ["," "*" expression]\n ["," keyword_arguments] ["," "**" expression]\n | "*" expression ["," keyword_arguments] ["," "**" expression]\n | "**" expression\n positional_arguments ::= expression ("," expression)*\n keyword_arguments ::= keyword_item ("," keyword_item)*\n keyword_item ::= identifier "=" expression\n\nAn optional trailing comma may be present after the positional and\nkeyword arguments but does not affect the semantics.\n\nThe primary must evaluate to a callable object (user-defined\nfunctions, built-in functions, methods of built-in objects, class\nobjects, methods of class instances, and all objects having a\n"__call__()" method are callable). All argument expressions are\nevaluated before the call is attempted. Please refer to section\n*Function definitions* for the syntax of formal *parameter* lists.\n\nIf keyword arguments are present, they are first converted to\npositional arguments, as follows. First, a list of unfilled slots is\ncreated for the formal parameters. If there are N positional\narguments, they are placed in the first N slots. Next, for each\nkeyword argument, the identifier is used to determine the\ncorresponding slot (if the identifier is the same as the first formal\nparameter name, the first slot is used, and so on). If the slot is\nalready filled, a "TypeError" exception is raised. Otherwise, the\nvalue of the argument is placed in the slot, filling it (even if the\nexpression is "None", it fills the slot). When all arguments have\nbeen processed, the slots that are still unfilled are filled with the\ncorresponding default value from the function definition. (Default\nvalues are calculated, once, when the function is defined; thus, a\nmutable object such as a list or dictionary used as default value will\nbe shared by all calls that don\'t specify an argument value for the\ncorresponding slot; this should usually be avoided.) If there are any\nunfilled slots for which no default value is specified, a "TypeError"\nexception is raised. Otherwise, the list of filled slots is used as\nthe argument list for the call.\n\n**CPython implementation detail:** An implementation may provide\nbuilt-in functions whose positional parameters do not have names, even\nif they are \'named\' for the purpose of documentation, and which\ntherefore cannot be supplied by keyword. In CPython, this is the case\nfor functions implemented in C that use "PyArg_ParseTuple()" to parse\ntheir arguments.\n\nIf there are more positional arguments than there are formal parameter\nslots, a "TypeError" exception is raised, unless a formal parameter\nusing the syntax "*identifier" is present; in this case, that formal\nparameter receives a tuple containing the excess positional arguments\n(or an empty tuple if there were no excess positional arguments).\n\nIf any keyword argument does not correspond to a formal parameter\nname, a "TypeError" exception is raised, unless a formal parameter\nusing the syntax "**identifier" is present; in this case, that formal\nparameter receives a dictionary containing the excess keyword\narguments (using the keywords as keys and the argument values as\ncorresponding values), or a (new) empty dictionary if there were no\nexcess keyword arguments.\n\nIf the syntax "*expression" appears in the function call, "expression"\nmust evaluate to an iterable. Elements from this iterable are treated\nas if they were additional positional arguments; if there are\npositional arguments *x1*, ..., *xN*, and "expression" evaluates to a\nsequence *y1*, ..., *yM*, this is equivalent to a call with M+N\npositional arguments *x1*, ..., *xN*, *y1*, ..., *yM*.\n\nA consequence of this is that although the "*expression" syntax may\nappear *after* some keyword arguments, it is processed *before* the\nkeyword arguments (and the "**expression" argument, if any -- see\nbelow). So:\n\n >>> def f(a, b):\n ... print(a, b)\n ...\n >>> f(b=1, *(2,))\n 2 1\n >>> f(a=1, *(2,))\n Traceback (most recent call last):\n File "", line 1, in ?\n TypeError: f() got multiple values for keyword argument \'a\'\n >>> f(1, *(2,))\n 1 2\n\nIt is unusual for both keyword arguments and the "*expression" syntax\nto be used in the same call, so in practice this confusion does not\narise.\n\nIf the syntax "**expression" appears in the function call,\n"expression" must evaluate to a mapping, the contents of which are\ntreated as additional keyword arguments. In the case of a keyword\nappearing in both "expression" and as an explicit keyword argument, a\n"TypeError" exception is raised.\n\nFormal parameters using the syntax "*identifier" or "**identifier"\ncannot be used as positional argument slots or as keyword argument\nnames.\n\nA call always returns some value, possibly "None", unless it raises an\nexception. How this value is computed depends on the type of the\ncallable object.\n\nIf it is---\n\na user-defined function:\n The code block for the function is executed, passing it the\n argument list. The first thing the code block will do is bind the\n formal parameters to the arguments; this is described in section\n *Function definitions*. When the code block executes a "return"\n statement, this specifies the return value of the function call.\n\na built-in function or method:\n The result is up to the interpreter; see *Built-in Functions* for\n the descriptions of built-in functions and methods.\n\na class object:\n A new instance of that class is returned.\n\na class instance method:\n The corresponding user-defined function is called, with an argument\n list that is one longer than the argument list of the call: the\n instance becomes the first argument.\n\na class instance:\n The class must define a "__call__()" method; the effect is then the\n same as if that method was called.\n', - 'class': u'\nClass definitions\n*****************\n\nA class definition defines a class object (see section *The standard\ntype hierarchy*):\n\n classdef ::= [decorators] "class" classname [inheritance] ":" suite\n inheritance ::= "(" [parameter_list] ")"\n classname ::= identifier\n\nA class definition is an executable statement. The inheritance list\nusually gives a list of base classes (see *Customizing class creation*\nfor more advanced uses), so each item in the list should evaluate to a\nclass object which allows subclassing. Classes without an inheritance\nlist inherit, by default, from the base class "object"; hence,\n\n class Foo:\n pass\n\nis equivalent to\n\n class Foo(object):\n pass\n\nThe class\'s suite is then executed in a new execution frame (see\n*Naming and binding*), using a newly created local namespace and the\noriginal global namespace. (Usually, the suite contains mostly\nfunction definitions.) When the class\'s suite finishes execution, its\nexecution frame is discarded but its local namespace is saved. [4] A\nclass object is then created using the inheritance list for the base\nclasses and the saved local namespace for the attribute dictionary.\nThe class name is bound to this class object in the original local\nnamespace.\n\nClass creation can be customized heavily using *metaclasses*.\n\nClasses can also be decorated: just like when decorating functions,\n\n @f1(arg)\n @f2\n class Foo: pass\n\nis equivalent to\n\n class Foo: pass\n Foo = f1(arg)(f2(Foo))\n\nThe evaluation rules for the decorator expressions are the same as for\nfunction decorators. The result must be a class object, which is then\nbound to the class name.\n\n**Programmer\'s note:** Variables defined in the class definition are\nclass attributes; they are shared by instances. Instance attributes\ncan be set in a method with "self.name = value". Both class and\ninstance attributes are accessible through the notation ""self.name"",\nand an instance attribute hides a class attribute with the same name\nwhen accessed in this way. Class attributes can be used as defaults\nfor instance attributes, but using mutable values there can lead to\nunexpected results. *Descriptors* can be used to create instance\nvariables with different implementation details.\n\nSee also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n Class Decorators\n\n-[ Footnotes ]-\n\n[1] The exception is propagated to the invocation stack unless\n there is a "finally" clause which happens to raise another\n exception. That new exception causes the old one to be lost.\n\n[2] Currently, control "flows off the end" except in the case of\n an exception or the execution of a "return", "continue", or\n "break" statement.\n\n[3] A string literal appearing as the first statement in the\n function body is transformed into the function\'s "__doc__"\n attribute and therefore the function\'s *docstring*.\n\n[4] A string literal appearing as the first statement in the class\n body is transformed into the namespace\'s "__doc__" item and\n therefore the class\'s *docstring*.\n', - 'comparisons': u'\nComparisons\n***********\n\nUnlike C, all comparison operations in Python have the same priority,\nwhich is lower than that of any arithmetic, shifting or bitwise\noperation. Also unlike C, expressions like "a < b < c" have the\ninterpretation that is conventional in mathematics:\n\n comparison ::= or_expr ( comp_operator or_expr )*\n comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n | "is" ["not"] | ["not"] "in"\n\nComparisons yield boolean values: "True" or "False".\n\nComparisons can be chained arbitrarily, e.g., "x < y <= z" is\nequivalent to "x < y and y <= z", except that "y" is evaluated only\nonce (but in both cases "z" is not evaluated at all when "x < y" is\nfound to be false).\n\nFormally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*,\n*op2*, ..., *opN* are comparison operators, then "a op1 b op2 c ... y\nopN z" is equivalent to "a op1 b and b op2 c and ... y opN z", except\nthat each expression is evaluated at most once.\n\nNote that "a op1 b op2 c" doesn\'t imply any kind of comparison between\n*a* and *c*, so that, e.g., "x < y > z" is perfectly legal (though\nperhaps not pretty).\n\n\nValue comparisons\n=================\n\nThe operators "<", ">", "==", ">=", "<=", and "!=" compare the values\nof two objects. The objects do not need to have the same type.\n\nChapter *Objects, values and types* states that objects have a value\n(in addition to type and identity). The value of an object is a\nrather abstract notion in Python: For example, there is no canonical\naccess method for an object\'s value. Also, there is no requirement\nthat the value of an object should be constructed in a particular way,\ne.g. comprised of all its data attributes. Comparison operators\nimplement a particular notion of what the value of an object is. One\ncan think of them as defining the value of an object indirectly, by\nmeans of their comparison implementation.\n\nBecause all types are (direct or indirect) subtypes of "object", they\ninherit the default comparison behavior from "object". Types can\ncustomize their comparison behavior by implementing *rich comparison\nmethods* like "__lt__()", described in *Basic customization*.\n\nThe default behavior for equality comparison ("==" and "!=") is based\non the identity of the objects. Hence, equality comparison of\ninstances with the same identity results in equality, and equality\ncomparison of instances with different identities results in\ninequality. A motivation for this default behavior is the desire that\nall objects should be reflexive (i.e. "x is y" implies "x == y").\n\nA default order comparison ("<", ">", "<=", and ">=") is not provided;\nan attempt raises "TypeError". A motivation for this default behavior\nis the lack of a similar invariant as for equality.\n\nThe behavior of the default equality comparison, that instances with\ndifferent identities are always unequal, may be in contrast to what\ntypes will need that have a sensible definition of object value and\nvalue-based equality. Such types will need to customize their\ncomparison behavior, and in fact, a number of built-in types have done\nthat.\n\nThe following list describes the comparison behavior of the most\nimportant built-in types.\n\n* Numbers of built-in numeric types (*Numeric Types --- int, float,\n complex*) and of the standard library types "fractions.Fraction" and\n "decimal.Decimal" can be compared within and across their types,\n with the restriction that complex numbers do not support order\n comparison. Within the limits of the types involved, they compare\n mathematically (algorithmically) correct without loss of precision.\n\n The not-a-number values "float(\'NaN\')" and "Decimal(\'NaN\')" are\n special. They are identical to themselves ("x is x" is true) but\n are not equal to themselves ("x == x" is false). Additionally,\n comparing any number to a not-a-number value will return "False".\n For example, both "3 < float(\'NaN\')" and "float(\'NaN\') < 3" will\n return "False".\n\n* Binary sequences (instances of "bytes" or "bytearray") can be\n compared within and across their types. They compare\n lexicographically using the numeric values of their elements.\n\n* Strings (instances of "str") compare lexicographically using the\n numerical Unicode code points (the result of the built-in function\n "ord()") of their characters. [3]\n\n Strings and binary sequences cannot be directly compared.\n\n* Sequences (instances of "tuple", "list", or "range") can be\n compared only within each of their types, with the restriction that\n ranges do not support order comparison. Equality comparison across\n these types results in unequality, and ordering comparison across\n these types raises "TypeError".\n\n Sequences compare lexicographically using comparison of\n corresponding elements, whereby reflexivity of the elements is\n enforced.\n\n In enforcing reflexivity of elements, the comparison of collections\n assumes that for a collection element "x", "x == x" is always true.\n Based on that assumption, element identity is compared first, and\n element comparison is performed only for distinct elements. This\n approach yields the same result as a strict element comparison\n would, if the compared elements are reflexive. For non-reflexive\n elements, the result is different than for strict element\n comparison, and may be surprising: The non-reflexive not-a-number\n values for example result in the following comparison behavior when\n used in a list:\n\n >>> nan = float(\'NaN\')\n >>> nan is nan\n True\n >>> nan == nan\n False <-- the defined non-reflexive behavior of NaN\n >>> [nan] == [nan]\n True <-- list enforces reflexivity and tests identity first\n\n Lexicographical comparison between built-in collections works as\n follows:\n\n * For two collections to compare equal, they must be of the same\n type, have the same length, and each pair of corresponding\n elements must compare equal (for example, "[1,2] == (1,2)" is\n false because the type is not the same).\n\n * Collections that support order comparison are ordered the same\n as their first unequal elements (for example, "[1,2,x] <= [1,2,y]"\n has the same value as "x <= y"). If a corresponding element does\n not exist, the shorter collection is ordered first (for example,\n "[1,2] < [1,2,3]" is true).\n\n* Mappings (instances of "dict") compare equal if and only if they\n have equal *(key, value)* pairs. Equality comparison of the keys and\n elements enforces reflexivity.\n\n Order comparisons ("<", ">", "<=", and ">=") raise "TypeError".\n\n* Sets (instances of "set" or "frozenset") can be compared within\n and across their types.\n\n They define order comparison operators to mean subset and superset\n tests. Those relations do not define total orderings (for example,\n the two sets "{1,2}" and "{2,3}" are not equal, nor subsets of one\n another, nor supersets of one another). Accordingly, sets are not\n appropriate arguments for functions which depend on total ordering\n (for example, "min()", "max()", and "sorted()" produce undefined\n results given a list of sets as inputs).\n\n Comparison of sets enforces reflexivity of its elements.\n\n* Most other built-in types have no comparison methods implemented,\n so they inherit the default comparison behavior.\n\nUser-defined classes that customize their comparison behavior should\nfollow some consistency rules, if possible:\n\n* Equality comparison should be reflexive. In other words, identical\n objects should compare equal:\n\n "x is y" implies "x == y"\n\n* Comparison should be symmetric. In other words, the following\n expressions should have the same result:\n\n "x == y" and "y == x"\n\n "x != y" and "y != x"\n\n "x < y" and "y > x"\n\n "x <= y" and "y >= x"\n\n* Comparison should be transitive. The following (non-exhaustive)\n examples illustrate that:\n\n "x > y and y > z" implies "x > z"\n\n "x < y and y <= z" implies "x < z"\n\n* Inverse comparison should result in the boolean negation. In other\n words, the following expressions should have the same result:\n\n "x == y" and "not x != y"\n\n "x < y" and "not x >= y" (for total ordering)\n\n "x > y" and "not x <= y" (for total ordering)\n\n The last two expressions apply to totally ordered collections (e.g.\n to sequences, but not to sets or mappings). See also the\n "total_ordering()" decorator.\n\nPython does not enforce these consistency rules. In fact, the\nnot-a-number values are an example for not following these rules.\n\n\nMembership test operations\n==========================\n\nThe operators "in" and "not in" test for membership. "x in s"\nevaluates to true if *x* is a member of *s*, and false otherwise. "x\nnot in s" returns the negation of "x in s". All built-in sequences\nand set types support this as well as dictionary, for which "in" tests\nwhether the dictionary has a given key. For container types such as\nlist, tuple, set, frozenset, dict, or collections.deque, the\nexpression "x in y" is equivalent to "any(x is e or x == e for e in\ny)".\n\nFor the string and bytes types, "x in y" is true if and only if *x* is\na substring of *y*. An equivalent test is "y.find(x) != -1". Empty\nstrings are always considered to be a substring of any other string,\nso """ in "abc"" will return "True".\n\nFor user-defined classes which define the "__contains__()" method, "x\nin y" is true if and only if "y.__contains__(x)" is true.\n\nFor user-defined classes which do not define "__contains__()" but do\ndefine "__iter__()", "x in y" is true if some value "z" with "x == z"\nis produced while iterating over "y". If an exception is raised\nduring the iteration, it is as if "in" raised that exception.\n\nLastly, the old-style iteration protocol is tried: if a class defines\n"__getitem__()", "x in y" is true if and only if there is a non-\nnegative integer index *i* such that "x == y[i]", and all lower\ninteger indices do not raise "IndexError" exception. (If any other\nexception is raised, it is as if "in" raised that exception).\n\nThe operator "not in" is defined to have the inverse true value of\n"in".\n\n\nIdentity comparisons\n====================\n\nThe operators "is" and "is not" test for object identity: "x is y" is\ntrue if and only if *x* and *y* are the same object. "x is not y"\nyields the inverse truth value. [4]\n', - 'compound': u'\nCompound statements\n*******************\n\nCompound statements contain (groups of) other statements; they affect\nor control the execution of those other statements in some way. In\ngeneral, compound statements span multiple lines, although in simple\nincarnations a whole compound statement may be contained in one line.\n\nThe "if", "while" and "for" statements implement traditional control\nflow constructs. "try" specifies exception handlers and/or cleanup\ncode for a group of statements, while the "with" statement allows the\nexecution of initialization and finalization code around a block of\ncode. Function and class definitions are also syntactically compound\nstatements.\n\nA compound statement consists of one or more \'clauses.\' A clause\nconsists of a header and a \'suite.\' The clause headers of a\nparticular compound statement are all at the same indentation level.\nEach clause header begins with a uniquely identifying keyword and ends\nwith a colon. A suite is a group of statements controlled by a\nclause. A suite can be one or more semicolon-separated simple\nstatements on the same line as the header, following the header\'s\ncolon, or it can be one or more indented statements on subsequent\nlines. Only the latter form of a suite can contain nested compound\nstatements; the following is illegal, mostly because it wouldn\'t be\nclear to which "if" clause a following "else" clause would belong:\n\n if test1: if test2: print(x)\n\nAlso note that the semicolon binds tighter than the colon in this\ncontext, so that in the following example, either all or none of the\n"print()" calls are executed:\n\n if x < y < z: print(x); print(y); print(z)\n\nSummarizing:\n\n compound_stmt ::= if_stmt\n | while_stmt\n | for_stmt\n | try_stmt\n | with_stmt\n | funcdef\n | classdef\n suite ::= stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT\n statement ::= stmt_list NEWLINE | compound_stmt\n stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n\nNote that statements always end in a "NEWLINE" possibly followed by a\n"DEDENT". Also note that optional continuation clauses always begin\nwith a keyword that cannot start a statement, thus there are no\nambiguities (the \'dangling "else"\' problem is solved in Python by\nrequiring nested "if" statements to be indented).\n\nThe formatting of the grammar rules in the following sections places\neach clause on a separate line for clarity.\n\n\nThe "if" statement\n==================\n\nThe "if" statement is used for conditional execution:\n\n if_stmt ::= "if" expression ":" suite\n ( "elif" expression ":" suite )*\n ["else" ":" suite]\n\nIt selects exactly one of the suites by evaluating the expressions one\nby one until one is found to be true (see section *Boolean operations*\nfor the definition of true and false); then that suite is executed\n(and no other part of the "if" statement is executed or evaluated).\nIf all expressions are false, the suite of the "else" clause, if\npresent, is executed.\n\n\nThe "while" statement\n=====================\n\nThe "while" statement is used for repeated execution as long as an\nexpression is true:\n\n while_stmt ::= "while" expression ":" suite\n ["else" ":" suite]\n\nThis repeatedly tests the expression and, if it is true, executes the\nfirst suite; if the expression is false (which may be the first time\nit is tested) the suite of the "else" clause, if present, is executed\nand the loop terminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and goes back\nto testing the expression.\n\n\nThe "for" statement\n===================\n\nThe "for" statement is used to iterate over the elements of a sequence\n(such as a string, tuple or list) or other iterable object:\n\n for_stmt ::= "for" target_list "in" expression_list ":" suite\n ["else" ":" suite]\n\nThe expression list is evaluated once; it should yield an iterable\nobject. An iterator is created for the result of the\n"expression_list". The suite is then executed once for each item\nprovided by the iterator, in the order returned by the iterator. Each\nitem in turn is assigned to the target list using the standard rules\nfor assignments (see *Assignment statements*), and then the suite is\nexecuted. When the items are exhausted (which is immediately when the\nsequence is empty or an iterator raises a "StopIteration" exception),\nthe suite in the "else" clause, if present, is executed, and the loop\nterminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and continues\nwith the next item, or with the "else" clause if there is no next\nitem.\n\nThe for-loop makes assignments to the variables(s) in the target list.\nThis overwrites all previous assignments to those variables including\nthose made in the suite of the for-loop:\n\n for i in range(10):\n print(i)\n i = 5 # this will not affect the for-loop\n # because i will be overwritten with the next\n # index in the range\n\nNames in the target list are not deleted when the loop is finished,\nbut if the sequence is empty, they will not have been assigned to at\nall by the loop. Hint: the built-in function "range()" returns an\niterator of integers suitable to emulate the effect of Pascal\'s "for i\n:= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n\nNote: There is a subtlety when the sequence is being modified by the\n loop (this can only occur for mutable sequences, i.e. lists). An\n internal counter is used to keep track of which item is used next,\n and this is incremented on each iteration. When this counter has\n reached the length of the sequence the loop terminates. This means\n that if the suite deletes the current (or a previous) item from the\n sequence, the next item will be skipped (since it gets the index of\n the current item which has already been treated). Likewise, if the\n suite inserts an item in the sequence before the current item, the\n current item will be treated again the next time through the loop.\n This can lead to nasty bugs that can be avoided by making a\n temporary copy using a slice of the whole sequence, e.g.,\n\n for x in a[:]:\n if x < 0: a.remove(x)\n\n\nThe "try" statement\n===================\n\nThe "try" statement specifies exception handlers and/or cleanup code\nfor a group of statements:\n\n try_stmt ::= try1_stmt | try2_stmt\n try1_stmt ::= "try" ":" suite\n ("except" [expression ["as" identifier]] ":" suite)+\n ["else" ":" suite]\n ["finally" ":" suite]\n try2_stmt ::= "try" ":" suite\n "finally" ":" suite\n\nThe "except" clause(s) specify one or more exception handlers. When no\nexception occurs in the "try" clause, no exception handler is\nexecuted. When an exception occurs in the "try" suite, a search for an\nexception handler is started. This search inspects the except clauses\nin turn until one is found that matches the exception. An expression-\nless except clause, if present, must be last; it matches any\nexception. For an except clause with an expression, that expression\nis evaluated, and the clause matches the exception if the resulting\nobject is "compatible" with the exception. An object is compatible\nwith an exception if it is the class or a base class of the exception\nobject or a tuple containing an item compatible with the exception.\n\nIf no except clause matches the exception, the search for an exception\nhandler continues in the surrounding code and on the invocation stack.\n[1]\n\nIf the evaluation of an expression in the header of an except clause\nraises an exception, the original search for a handler is canceled and\na search starts for the new exception in the surrounding code and on\nthe call stack (it is treated as if the entire "try" statement raised\nthe exception).\n\nWhen a matching except clause is found, the exception is assigned to\nthe target specified after the "as" keyword in that except clause, if\npresent, and the except clause\'s suite is executed. All except\nclauses must have an executable block. When the end of this block is\nreached, execution continues normally after the entire try statement.\n(This means that if two nested handlers exist for the same exception,\nand the exception occurs in the try clause of the inner handler, the\nouter handler will not handle the exception.)\n\nWhen an exception has been assigned using "as target", it is cleared\nat the end of the except clause. This is as if\n\n except E as N:\n foo\n\nwas translated to\n\n except E as N:\n try:\n foo\n finally:\n del N\n\nThis means the exception must be assigned to a different name to be\nable to refer to it after the except clause. Exceptions are cleared\nbecause with the traceback attached to them, they form a reference\ncycle with the stack frame, keeping all locals in that frame alive\nuntil the next garbage collection occurs.\n\nBefore an except clause\'s suite is executed, details about the\nexception are stored in the "sys" module and can be accessed via\n"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of the\nexception class, the exception instance and a traceback object (see\nsection *The standard type hierarchy*) identifying the point in the\nprogram where the exception occurred. "sys.exc_info()" values are\nrestored to their previous values (before the call) when returning\nfrom a function that handled an exception.\n\nThe optional "else" clause is executed if and when control flows off\nthe end of the "try" clause. [2] Exceptions in the "else" clause are\nnot handled by the preceding "except" clauses.\n\nIf "finally" is present, it specifies a \'cleanup\' handler. The "try"\nclause is executed, including any "except" and "else" clauses. If an\nexception occurs in any of the clauses and is not handled, the\nexception is temporarily saved. The "finally" clause is executed. If\nthere is a saved exception it is re-raised at the end of the "finally"\nclause. If the "finally" clause raises another exception, the saved\nexception is set as the context of the new exception. If the "finally"\nclause executes a "return" or "break" statement, the saved exception\nis discarded:\n\n >>> def f():\n ... try:\n ... 1/0\n ... finally:\n ... return 42\n ...\n >>> f()\n 42\n\nThe exception information is not available to the program during\nexecution of the "finally" clause.\n\nWhen a "return", "break" or "continue" statement is executed in the\n"try" suite of a "try"..."finally" statement, the "finally" clause is\nalso executed \'on the way out.\' A "continue" statement is illegal in\nthe "finally" clause. (The reason is a problem with the current\nimplementation --- this restriction may be lifted in the future).\n\nThe return value of a function is determined by the last "return"\nstatement executed. Since the "finally" clause always executes, a\n"return" statement executed in the "finally" clause will always be the\nlast one executed:\n\n >>> def foo():\n ... try:\n ... return \'try\'\n ... finally:\n ... return \'finally\'\n ...\n >>> foo()\n \'finally\'\n\nAdditional information on exceptions can be found in section\n*Exceptions*, and information on using the "raise" statement to\ngenerate exceptions may be found in section *The raise statement*.\n\n\nThe "with" statement\n====================\n\nThe "with" statement is used to wrap the execution of a block with\nmethods defined by a context manager (see section *With Statement\nContext Managers*). This allows common "try"..."except"..."finally"\nusage patterns to be encapsulated for convenient reuse.\n\n with_stmt ::= "with" with_item ("," with_item)* ":" suite\n with_item ::= expression ["as" target]\n\nThe execution of the "with" statement with one "item" proceeds as\nfollows:\n\n1. The context expression (the expression given in the "with_item")\n is evaluated to obtain a context manager.\n\n2. The context manager\'s "__exit__()" is loaded for later use.\n\n3. The context manager\'s "__enter__()" method is invoked.\n\n4. If a target was included in the "with" statement, the return\n value from "__enter__()" is assigned to it.\n\n Note: The "with" statement guarantees that if the "__enter__()"\n method returns without an error, then "__exit__()" will always be\n called. Thus, if an error occurs during the assignment to the\n target list, it will be treated the same as an error occurring\n within the suite would be. See step 6 below.\n\n5. The suite is executed.\n\n6. The context manager\'s "__exit__()" method is invoked. If an\n exception caused the suite to be exited, its type, value, and\n traceback are passed as arguments to "__exit__()". Otherwise, three\n "None" arguments are supplied.\n\n If the suite was exited due to an exception, and the return value\n from the "__exit__()" method was false, the exception is reraised.\n If the return value was true, the exception is suppressed, and\n execution continues with the statement following the "with"\n statement.\n\n If the suite was exited for any reason other than an exception, the\n return value from "__exit__()" is ignored, and execution proceeds\n at the normal location for the kind of exit that was taken.\n\nWith more than one item, the context managers are processed as if\nmultiple "with" statements were nested:\n\n with A() as a, B() as b:\n suite\n\nis equivalent to\n\n with A() as a:\n with B() as b:\n suite\n\nChanged in version 3.1: Support for multiple context expressions.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n\n\nFunction definitions\n====================\n\nA function definition defines a user-defined function object (see\nsection *The standard type hierarchy*):\n\n funcdef ::= [decorators] "def" funcname "(" [parameter_list] ")" ["->" expression] ":" suite\n decorators ::= decorator+\n decorator ::= "@" dotted_name ["(" [parameter_list [","]] ")"] NEWLINE\n dotted_name ::= identifier ("." identifier)*\n parameter_list ::= (defparameter ",")*\n | "*" [parameter] ("," defparameter)* ["," "**" parameter]\n | "**" parameter\n | defparameter [","] )\n parameter ::= identifier [":" expression]\n defparameter ::= parameter ["=" expression]\n funcname ::= identifier\n\nA function definition is an executable statement. Its execution binds\nthe function name in the current local namespace to a function object\n(a wrapper around the executable code for the function). This\nfunction object contains a reference to the current global namespace\nas the global namespace to be used when the function is called.\n\nThe function definition does not execute the function body; this gets\nexecuted only when the function is called. [3]\n\nA function definition may be wrapped by one or more *decorator*\nexpressions. Decorator expressions are evaluated when the function is\ndefined, in the scope that contains the function definition. The\nresult must be a callable, which is invoked with the function object\nas the only argument. The returned value is bound to the function name\ninstead of the function object. Multiple decorators are applied in\nnested fashion. For example, the following code\n\n @f1(arg)\n @f2\n def func(): pass\n\nis equivalent to\n\n def func(): pass\n func = f1(arg)(f2(func))\n\nWhen one or more *parameters* have the form *parameter* "="\n*expression*, the function is said to have "default parameter values."\nFor a parameter with a default value, the corresponding *argument* may\nbe omitted from a call, in which case the parameter\'s default value is\nsubstituted. If a parameter has a default value, all following\nparameters up until the ""*"" must also have a default value --- this\nis a syntactic restriction that is not expressed by the grammar.\n\n**Default parameter values are evaluated from left to right when the\nfunction definition is executed.** This means that the expression is\nevaluated once, when the function is defined, and that the same "pre-\ncomputed" value is used for each call. This is especially important\nto understand when a default parameter is a mutable object, such as a\nlist or a dictionary: if the function modifies the object (e.g. by\nappending an item to a list), the default value is in effect modified.\nThis is generally not what was intended. A way around this is to use\n"None" as the default, and explicitly test for it in the body of the\nfunction, e.g.:\n\n def whats_on_the_telly(penguin=None):\n if penguin is None:\n penguin = []\n penguin.append("property of the zoo")\n return penguin\n\nFunction call semantics are described in more detail in section\n*Calls*. A function call always assigns values to all parameters\nmentioned in the parameter list, either from position arguments, from\nkeyword arguments, or from default values. If the form\n""*identifier"" is present, it is initialized to a tuple receiving any\nexcess positional parameters, defaulting to the empty tuple. If the\nform ""**identifier"" is present, it is initialized to a new\ndictionary receiving any excess keyword arguments, defaulting to a new\nempty dictionary. Parameters after ""*"" or ""*identifier"" are\nkeyword-only parameters and may only be passed used keyword arguments.\n\nParameters may have annotations of the form "": expression"" following\nthe parameter name. Any parameter may have an annotation even those\nof the form "*identifier" or "**identifier". Functions may have\n"return" annotation of the form ""-> expression"" after the parameter\nlist. These annotations can be any valid Python expression and are\nevaluated when the function definition is executed. Annotations may\nbe evaluated in a different order than they appear in the source code.\nThe presence of annotations does not change the semantics of a\nfunction. The annotation values are available as values of a\ndictionary keyed by the parameters\' names in the "__annotations__"\nattribute of the function object.\n\nIt is also possible to create anonymous functions (functions not bound\nto a name), for immediate use in expressions. This uses lambda\nexpressions, described in section *Lambdas*. Note that the lambda\nexpression is merely a shorthand for a simplified function definition;\na function defined in a ""def"" statement can be passed around or\nassigned to another name just like a function defined by a lambda\nexpression. The ""def"" form is actually more powerful since it\nallows the execution of multiple statements and annotations.\n\n**Programmer\'s note:** Functions are first-class objects. A ""def""\nstatement executed inside a function definition defines a local\nfunction that can be returned or passed around. Free variables used\nin the nested function can access the local variables of the function\ncontaining the def. See section *Naming and binding* for details.\n\nSee also: **PEP 3107** - Function Annotations\n\n The original specification for function annotations.\n\n\nClass definitions\n=================\n\nA class definition defines a class object (see section *The standard\ntype hierarchy*):\n\n classdef ::= [decorators] "class" classname [inheritance] ":" suite\n inheritance ::= "(" [parameter_list] ")"\n classname ::= identifier\n\nA class definition is an executable statement. The inheritance list\nusually gives a list of base classes (see *Customizing class creation*\nfor more advanced uses), so each item in the list should evaluate to a\nclass object which allows subclassing. Classes without an inheritance\nlist inherit, by default, from the base class "object"; hence,\n\n class Foo:\n pass\n\nis equivalent to\n\n class Foo(object):\n pass\n\nThe class\'s suite is then executed in a new execution frame (see\n*Naming and binding*), using a newly created local namespace and the\noriginal global namespace. (Usually, the suite contains mostly\nfunction definitions.) When the class\'s suite finishes execution, its\nexecution frame is discarded but its local namespace is saved. [4] A\nclass object is then created using the inheritance list for the base\nclasses and the saved local namespace for the attribute dictionary.\nThe class name is bound to this class object in the original local\nnamespace.\n\nClass creation can be customized heavily using *metaclasses*.\n\nClasses can also be decorated: just like when decorating functions,\n\n @f1(arg)\n @f2\n class Foo: pass\n\nis equivalent to\n\n class Foo: pass\n Foo = f1(arg)(f2(Foo))\n\nThe evaluation rules for the decorator expressions are the same as for\nfunction decorators. The result must be a class object, which is then\nbound to the class name.\n\n**Programmer\'s note:** Variables defined in the class definition are\nclass attributes; they are shared by instances. Instance attributes\ncan be set in a method with "self.name = value". Both class and\ninstance attributes are accessible through the notation ""self.name"",\nand an instance attribute hides a class attribute with the same name\nwhen accessed in this way. Class attributes can be used as defaults\nfor instance attributes, but using mutable values there can lead to\nunexpected results. *Descriptors* can be used to create instance\nvariables with different implementation details.\n\nSee also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n Class Decorators\n\n-[ Footnotes ]-\n\n[1] The exception is propagated to the invocation stack unless\n there is a "finally" clause which happens to raise another\n exception. That new exception causes the old one to be lost.\n\n[2] Currently, control "flows off the end" except in the case of\n an exception or the execution of a "return", "continue", or\n "break" statement.\n\n[3] A string literal appearing as the first statement in the\n function body is transformed into the function\'s "__doc__"\n attribute and therefore the function\'s *docstring*.\n\n[4] A string literal appearing as the first statement in the class\n body is transformed into the namespace\'s "__doc__" item and\n therefore the class\'s *docstring*.\n', - 'context-managers': u'\nWith Statement Context Managers\n*******************************\n\nA *context manager* is an object that defines the runtime context to\nbe established when executing a "with" statement. The context manager\nhandles the entry into, and the exit from, the desired runtime context\nfor the execution of the block of code. Context managers are normally\ninvoked using the "with" statement (described in section *The with\nstatement*), but can also be used by directly invoking their methods.\n\nTypical uses of context managers include saving and restoring various\nkinds of global state, locking and unlocking resources, closing opened\nfiles, etc.\n\nFor more information on context managers, see *Context Manager Types*.\n\nobject.__enter__(self)\n\n Enter the runtime context related to this object. The "with"\n statement will bind this method\'s return value to the target(s)\n specified in the "as" clause of the statement, if any.\n\nobject.__exit__(self, exc_type, exc_value, traceback)\n\n Exit the runtime context related to this object. The parameters\n describe the exception that caused the context to be exited. If the\n context was exited without an exception, all three arguments will\n be "None".\n\n If an exception is supplied, and the method wishes to suppress the\n exception (i.e., prevent it from being propagated), it should\n return a true value. Otherwise, the exception will be processed\n normally upon exit from this method.\n\n Note that "__exit__()" methods should not reraise the passed-in\n exception; this is the caller\'s responsibility.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n', - 'continue': u'\nThe "continue" statement\n************************\n\n continue_stmt ::= "continue"\n\n"continue" may only occur syntactically nested in a "for" or "while"\nloop, but not nested in a function or class definition or "finally"\nclause within that loop. It continues with the next cycle of the\nnearest enclosing loop.\n\nWhen "continue" passes control out of a "try" statement with a\n"finally" clause, that "finally" clause is executed before really\nstarting the next loop cycle.\n', - 'conversions': u'\nArithmetic conversions\n**********************\n\nWhen a description of an arithmetic operator below uses the phrase\n"the numeric arguments are converted to a common type," this means\nthat the operator implementation for built-in types works as follows:\n\n* If either argument is a complex number, the other is converted to\n complex;\n\n* otherwise, if either argument is a floating point number, the\n other is converted to floating point;\n\n* otherwise, both must be integers and no conversion is necessary.\n\nSome additional rules apply for certain operators (e.g., a string as a\nleft argument to the \'%\' operator). Extensions must define their own\nconversion behavior.\n', - 'customization': u'\nBasic customization\n*******************\n\nobject.__new__(cls[, ...])\n\n Called to create a new instance of class *cls*. "__new__()" is a\n static method (special-cased so you need not declare it as such)\n that takes the class of which an instance was requested as its\n first argument. The remaining arguments are those passed to the\n object constructor expression (the call to the class). The return\n value of "__new__()" should be the new object instance (usually an\n instance of *cls*).\n\n Typical implementations create a new instance of the class by\n invoking the superclass\'s "__new__()" method using\n "super(currentclass, cls).__new__(cls[, ...])" with appropriate\n arguments and then modifying the newly-created instance as\n necessary before returning it.\n\n If "__new__()" returns an instance of *cls*, then the new\n instance\'s "__init__()" method will be invoked like\n "__init__(self[, ...])", where *self* is the new instance and the\n remaining arguments are the same as were passed to "__new__()".\n\n If "__new__()" does not return an instance of *cls*, then the new\n instance\'s "__init__()" method will not be invoked.\n\n "__new__()" is intended mainly to allow subclasses of immutable\n types (like int, str, or tuple) to customize instance creation. It\n is also commonly overridden in custom metaclasses in order to\n customize class creation.\n\nobject.__init__(self[, ...])\n\n Called after the instance has been created (by "__new__()"), but\n before it is returned to the caller. The arguments are those\n passed to the class constructor expression. If a base class has an\n "__init__()" method, the derived class\'s "__init__()" method, if\n any, must explicitly call it to ensure proper initialization of the\n base class part of the instance; for example:\n "BaseClass.__init__(self, [args...])".\n\n Because "__new__()" and "__init__()" work together in constructing\n objects ("__new__()" to create it, and "__init__()" to customise\n it), no non-"None" value may be returned by "__init__()"; doing so\n will cause a "TypeError" to be raised at runtime.\n\nobject.__del__(self)\n\n Called when the instance is about to be destroyed. This is also\n called a destructor. If a base class has a "__del__()" method, the\n derived class\'s "__del__()" method, if any, must explicitly call it\n to ensure proper deletion of the base class part of the instance.\n Note that it is possible (though not recommended!) for the\n "__del__()" method to postpone destruction of the instance by\n creating a new reference to it. It may then be called at a later\n time when this new reference is deleted. It is not guaranteed that\n "__del__()" methods are called for objects that still exist when\n the interpreter exits.\n\n Note: "del x" doesn\'t directly call "x.__del__()" --- the former\n decrements the reference count for "x" by one, and the latter is\n only called when "x"\'s reference count reaches zero. Some common\n situations that may prevent the reference count of an object from\n going to zero include: circular references between objects (e.g.,\n a doubly-linked list or a tree data structure with parent and\n child pointers); a reference to the object on the stack frame of\n a function that caught an exception (the traceback stored in\n "sys.exc_info()[2]" keeps the stack frame alive); or a reference\n to the object on the stack frame that raised an unhandled\n exception in interactive mode (the traceback stored in\n "sys.last_traceback" keeps the stack frame alive). The first\n situation can only be remedied by explicitly breaking the cycles;\n the second can be resolved by freeing the reference to the\n traceback object when it is no longer useful, and the third can\n be resolved by storing "None" in "sys.last_traceback". Circular\n references which are garbage are detected and cleaned up when the\n cyclic garbage collector is enabled (it\'s on by default). Refer\n to the documentation for the "gc" module for more information\n about this topic.\n\n Warning: Due to the precarious circumstances under which\n "__del__()" methods are invoked, exceptions that occur during\n their execution are ignored, and a warning is printed to\n "sys.stderr" instead. Also, when "__del__()" is invoked in\n response to a module being deleted (e.g., when execution of the\n program is done), other globals referenced by the "__del__()"\n method may already have been deleted or in the process of being\n torn down (e.g. the import machinery shutting down). For this\n reason, "__del__()" methods should do the absolute minimum needed\n to maintain external invariants. Starting with version 1.5,\n Python guarantees that globals whose name begins with a single\n underscore are deleted from their module before other globals are\n deleted; if no other references to such globals exist, this may\n help in assuring that imported modules are still available at the\n time when the "__del__()" method is called.\n\nobject.__repr__(self)\n\n Called by the "repr()" built-in function to compute the "official"\n string representation of an object. If at all possible, this\n should look like a valid Python expression that could be used to\n recreate an object with the same value (given an appropriate\n environment). If this is not possible, a string of the form\n "<...some useful description...>" should be returned. The return\n value must be a string object. If a class defines "__repr__()" but\n not "__str__()", then "__repr__()" is also used when an "informal"\n string representation of instances of that class is required.\n\n This is typically used for debugging, so it is important that the\n representation is information-rich and unambiguous.\n\nobject.__str__(self)\n\n Called by "str(object)" and the built-in functions "format()" and\n "print()" to compute the "informal" or nicely printable string\n representation of an object. The return value must be a *string*\n object.\n\n This method differs from "object.__repr__()" in that there is no\n expectation that "__str__()" return a valid Python expression: a\n more convenient or concise representation can be used.\n\n The default implementation defined by the built-in type "object"\n calls "object.__repr__()".\n\nobject.__bytes__(self)\n\n Called by "bytes()" to compute a byte-string representation of an\n object. This should return a "bytes" object.\n\nobject.__format__(self, format_spec)\n\n Called by the "format()" built-in function (and by extension, the\n "str.format()" method of class "str") to produce a "formatted"\n string representation of an object. The "format_spec" argument is a\n string that contains a description of the formatting options\n desired. The interpretation of the "format_spec" argument is up to\n the type implementing "__format__()", however most classes will\n either delegate formatting to one of the built-in types, or use a\n similar formatting option syntax.\n\n See *Format Specification Mini-Language* for a description of the\n standard formatting syntax.\n\n The return value must be a string object.\n\n Changed in version 3.4: The __format__ method of "object" itself\n raises a "TypeError" if passed any non-empty string.\n\nobject.__lt__(self, other)\nobject.__le__(self, other)\nobject.__eq__(self, other)\nobject.__ne__(self, other)\nobject.__gt__(self, other)\nobject.__ge__(self, other)\n\n These are the so-called "rich comparison" methods. The\n correspondence between operator symbols and method names is as\n follows: "xy" calls\n "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n\n A rich comparison method may return the singleton "NotImplemented"\n if it does not implement the operation for a given pair of\n arguments. By convention, "False" and "True" are returned for a\n successful comparison. However, these methods can return any value,\n so if the comparison operator is used in a Boolean context (e.g.,\n in the condition of an "if" statement), Python will call "bool()"\n on the value to determine if the result is true or false.\n\n By default, "__ne__()" delegates to "__eq__()" and inverts the\n result unless it is "NotImplemented". There are no other implied\n relationships among the comparison operators, for example, the\n truth of "(x.__hash__".\n\n If a class that does not override "__eq__()" wishes to suppress\n hash support, it should include "__hash__ = None" in the class\n definition. A class which defines its own "__hash__()" that\n explicitly raises a "TypeError" would be incorrectly identified as\n hashable by an "isinstance(obj, collections.Hashable)" call.\n\n Note: By default, the "__hash__()" values of str, bytes and\n datetime objects are "salted" with an unpredictable random value.\n Although they remain constant within an individual Python\n process, they are not predictable between repeated invocations of\n Python.This is intended to provide protection against a denial-\n of-service caused by carefully-chosen inputs that exploit the\n worst case performance of a dict insertion, O(n^2) complexity.\n See http://www.ocert.org/advisories/ocert-2011-003.html for\n details.Changing hash values affects the iteration order of\n dicts, sets and other mappings. Python has never made guarantees\n about this ordering (and it typically varies between 32-bit and\n 64-bit builds).See also "PYTHONHASHSEED".\n\n Changed in version 3.3: Hash randomization is enabled by default.\n\nobject.__bool__(self)\n\n Called to implement truth value testing and the built-in operation\n "bool()"; should return "False" or "True". When this method is not\n defined, "__len__()" is called, if it is defined, and the object is\n considered true if its result is nonzero. If a class defines\n neither "__len__()" nor "__bool__()", all its instances are\n considered true.\n', - 'debugger': u'\n"pdb" --- The Python Debugger\n*****************************\n\n**Source code:** Lib/pdb.py\n\n======================================================================\n\nThe module "pdb" defines an interactive source code debugger for\nPython programs. It supports setting (conditional) breakpoints and\nsingle stepping at the source line level, inspection of stack frames,\nsource code listing, and evaluation of arbitrary Python code in the\ncontext of any stack frame. It also supports post-mortem debugging\nand can be called under program control.\n\nThe debugger is extensible -- it is actually defined as the class\n"Pdb". This is currently undocumented but easily understood by reading\nthe source. The extension interface uses the modules "bdb" and "cmd".\n\nThe debugger\'s prompt is "(Pdb)". Typical usage to run a program under\ncontrol of the debugger is:\n\n >>> import pdb\n >>> import mymodule\n >>> pdb.run(\'mymodule.test()\')\n > (0)?()\n (Pdb) continue\n > (1)?()\n (Pdb) continue\n NameError: \'spam\'\n > (1)?()\n (Pdb)\n\nChanged in version 3.3: Tab-completion via the "readline" module is\navailable for commands and command arguments, e.g. the current global\nand local names are offered as arguments of the "p" command.\n\n"pdb.py" can also be invoked as a script to debug other scripts. For\nexample:\n\n python3 -m pdb myscript.py\n\nWhen invoked as a script, pdb will automatically enter post-mortem\ndebugging if the program being debugged exits abnormally. After post-\nmortem debugging (or after normal exit of the program), pdb will\nrestart the program. Automatic restarting preserves pdb\'s state (such\nas breakpoints) and in most cases is more useful than quitting the\ndebugger upon program\'s exit.\n\nNew in version 3.2: "pdb.py" now accepts a "-c" option that executes\ncommands as if given in a ".pdbrc" file, see *Debugger Commands*.\n\nThe typical usage to break into the debugger from a running program is\nto insert\n\n import pdb; pdb.set_trace()\n\nat the location you want to break into the debugger. You can then\nstep through the code following this statement, and continue running\nwithout the debugger using the "continue" command.\n\nThe typical usage to inspect a crashed program is:\n\n >>> import pdb\n >>> import mymodule\n >>> mymodule.test()\n Traceback (most recent call last):\n File "", line 1, in ?\n File "./mymodule.py", line 4, in test\n test2()\n File "./mymodule.py", line 3, in test2\n print(spam)\n NameError: spam\n >>> pdb.pm()\n > ./mymodule.py(3)test2()\n -> print(spam)\n (Pdb)\n\nThe module defines the following functions; each enters the debugger\nin a slightly different way:\n\npdb.run(statement, globals=None, locals=None)\n\n Execute the *statement* (given as a string or a code object) under\n debugger control. The debugger prompt appears before any code is\n executed; you can set breakpoints and type "continue", or you can\n step through the statement using "step" or "next" (all these\n commands are explained below). The optional *globals* and *locals*\n arguments specify the environment in which the code is executed; by\n default the dictionary of the module "__main__" is used. (See the\n explanation of the built-in "exec()" or "eval()" functions.)\n\npdb.runeval(expression, globals=None, locals=None)\n\n Evaluate the *expression* (given as a string or a code object)\n under debugger control. When "runeval()" returns, it returns the\n value of the expression. Otherwise this function is similar to\n "run()".\n\npdb.runcall(function, *args, **kwds)\n\n Call the *function* (a function or method object, not a string)\n with the given arguments. When "runcall()" returns, it returns\n whatever the function call returned. The debugger prompt appears\n as soon as the function is entered.\n\npdb.set_trace()\n\n Enter the debugger at the calling stack frame. This is useful to\n hard-code a breakpoint at a given point in a program, even if the\n code is not otherwise being debugged (e.g. when an assertion\n fails).\n\npdb.post_mortem(traceback=None)\n\n Enter post-mortem debugging of the given *traceback* object. If no\n *traceback* is given, it uses the one of the exception that is\n currently being handled (an exception must be being handled if the\n default is to be used).\n\npdb.pm()\n\n Enter post-mortem debugging of the traceback found in\n "sys.last_traceback".\n\nThe "run*" functions and "set_trace()" are aliases for instantiating\nthe "Pdb" class and calling the method of the same name. If you want\nto access further features, you have to do this yourself:\n\nclass class pdb.Pdb(completekey=\'tab\', stdin=None, stdout=None, skip=None, nosigint=False)\n\n "Pdb" is the debugger class.\n\n The *completekey*, *stdin* and *stdout* arguments are passed to the\n underlying "cmd.Cmd" class; see the description there.\n\n The *skip* argument, if given, must be an iterable of glob-style\n module name patterns. The debugger will not step into frames that\n originate in a module that matches one of these patterns. [1]\n\n By default, Pdb sets a handler for the SIGINT signal (which is sent\n when the user presses "Ctrl-C" on the console) when you give a\n "continue" command. This allows you to break into the debugger\n again by pressing "Ctrl-C". If you want Pdb not to touch the\n SIGINT handler, set *nosigint* tot true.\n\n Example call to enable tracing with *skip*:\n\n import pdb; pdb.Pdb(skip=[\'django.*\']).set_trace()\n\n New in version 3.1: The *skip* argument.\n\n New in version 3.2: The *nosigint* argument. Previously, a SIGINT\n handler was never set by Pdb.\n\n run(statement, globals=None, locals=None)\n runeval(expression, globals=None, locals=None)\n runcall(function, *args, **kwds)\n set_trace()\n\n See the documentation for the functions explained above.\n\n\nDebugger Commands\n=================\n\nThe commands recognized by the debugger are listed below. Most\ncommands can be abbreviated to one or two letters as indicated; e.g.\n"h(elp)" means that either "h" or "help" can be used to enter the help\ncommand (but not "he" or "hel", nor "H" or "Help" or "HELP").\nArguments to commands must be separated by whitespace (spaces or\ntabs). Optional arguments are enclosed in square brackets ("[]") in\nthe command syntax; the square brackets must not be typed.\nAlternatives in the command syntax are separated by a vertical bar\n("|").\n\nEntering a blank line repeats the last command entered. Exception: if\nthe last command was a "list" command, the next 11 lines are listed.\n\nCommands that the debugger doesn\'t recognize are assumed to be Python\nstatements and are executed in the context of the program being\ndebugged. Python statements can also be prefixed with an exclamation\npoint ("!"). This is a powerful way to inspect the program being\ndebugged; it is even possible to change a variable or call a function.\nWhen an exception occurs in such a statement, the exception name is\nprinted but the debugger\'s state is not changed.\n\nThe debugger supports *aliases*. Aliases can have parameters which\nallows one a certain level of adaptability to the context under\nexamination.\n\nMultiple commands may be entered on a single line, separated by ";;".\n(A single ";" is not used as it is the separator for multiple commands\nin a line that is passed to the Python parser.) No intelligence is\napplied to separating the commands; the input is split at the first\n";;" pair, even if it is in the middle of a quoted string.\n\nIf a file ".pdbrc" exists in the user\'s home directory or in the\ncurrent directory, it is read in and executed as if it had been typed\nat the debugger prompt. This is particularly useful for aliases. If\nboth files exist, the one in the home directory is read first and\naliases defined there can be overridden by the local file.\n\nChanged in version 3.2: ".pdbrc" can now contain commands that\ncontinue debugging, such as "continue" or "next". Previously, these\ncommands had no effect.\n\nh(elp) [command]\n\n Without argument, print the list of available commands. With a\n *command* as argument, print help about that command. "help pdb"\n displays the full documentation (the docstring of the "pdb"\n module). Since the *command* argument must be an identifier, "help\n exec" must be entered to get help on the "!" command.\n\nw(here)\n\n Print a stack trace, with the most recent frame at the bottom. An\n arrow indicates the current frame, which determines the context of\n most commands.\n\nd(own) [count]\n\n Move the current frame *count* (default one) levels down in the\n stack trace (to a newer frame).\n\nu(p) [count]\n\n Move the current frame *count* (default one) levels up in the stack\n trace (to an older frame).\n\nb(reak) [([filename:]lineno | function) [, condition]]\n\n With a *lineno* argument, set a break there in the current file.\n With a *function* argument, set a break at the first executable\n statement within that function. The line number may be prefixed\n with a filename and a colon, to specify a breakpoint in another\n file (probably one that hasn\'t been loaded yet). The file is\n searched on "sys.path". Note that each breakpoint is assigned a\n number to which all the other breakpoint commands refer.\n\n If a second argument is present, it is an expression which must\n evaluate to true before the breakpoint is honored.\n\n Without argument, list all breaks, including for each breakpoint,\n the number of times that breakpoint has been hit, the current\n ignore count, and the associated condition if any.\n\ntbreak [([filename:]lineno | function) [, condition]]\n\n Temporary breakpoint, which is removed automatically when it is\n first hit. The arguments are the same as for "break".\n\ncl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n\n With a *filename:lineno* argument, clear all the breakpoints at\n this line. With a space separated list of breakpoint numbers, clear\n those breakpoints. Without argument, clear all breaks (but first\n ask confirmation).\n\ndisable [bpnumber [bpnumber ...]]\n\n Disable the breakpoints given as a space separated list of\n breakpoint numbers. Disabling a breakpoint means it cannot cause\n the program to stop execution, but unlike clearing a breakpoint, it\n remains in the list of breakpoints and can be (re-)enabled.\n\nenable [bpnumber [bpnumber ...]]\n\n Enable the breakpoints specified.\n\nignore bpnumber [count]\n\n Set the ignore count for the given breakpoint number. If count is\n omitted, the ignore count is set to 0. A breakpoint becomes active\n when the ignore count is zero. When non-zero, the count is\n decremented each time the breakpoint is reached and the breakpoint\n is not disabled and any associated condition evaluates to true.\n\ncondition bpnumber [condition]\n\n Set a new *condition* for the breakpoint, an expression which must\n evaluate to true before the breakpoint is honored. If *condition*\n is absent, any existing condition is removed; i.e., the breakpoint\n is made unconditional.\n\ncommands [bpnumber]\n\n Specify a list of commands for breakpoint number *bpnumber*. The\n commands themselves appear on the following lines. Type a line\n containing just "end" to terminate the commands. An example:\n\n (Pdb) commands 1\n (com) p some_variable\n (com) end\n (Pdb)\n\n To remove all commands from a breakpoint, type commands and follow\n it immediately with "end"; that is, give no commands.\n\n With no *bpnumber* argument, commands refers to the last breakpoint\n set.\n\n You can use breakpoint commands to start your program up again.\n Simply use the continue command, or step, or any other command that\n resumes execution.\n\n Specifying any command resuming execution (currently continue,\n step, next, return, jump, quit and their abbreviations) terminates\n the command list (as if that command was immediately followed by\n end). This is because any time you resume execution (even with a\n simple next or step), you may encounter another breakpoint--which\n could have its own command list, leading to ambiguities about which\n list to execute.\n\n If you use the \'silent\' command in the command list, the usual\n message about stopping at a breakpoint is not printed. This may be\n desirable for breakpoints that are to print a specific message and\n then continue. If none of the other commands print anything, you\n see no sign that the breakpoint was reached.\n\ns(tep)\n\n Execute the current line, stop at the first possible occasion\n (either in a function that is called or on the next line in the\n current function).\n\nn(ext)\n\n Continue execution until the next line in the current function is\n reached or it returns. (The difference between "next" and "step"\n is that "step" stops inside a called function, while "next"\n executes called functions at (nearly) full speed, only stopping at\n the next line in the current function.)\n\nunt(il) [lineno]\n\n Without argument, continue execution until the line with a number\n greater than the current one is reached.\n\n With a line number, continue execution until a line with a number\n greater or equal to that is reached. In both cases, also stop when\n the current frame returns.\n\n Changed in version 3.2: Allow giving an explicit line number.\n\nr(eturn)\n\n Continue execution until the current function returns.\n\nc(ont(inue))\n\n Continue execution, only stop when a breakpoint is encountered.\n\nj(ump) lineno\n\n Set the next line that will be executed. Only available in the\n bottom-most frame. This lets you jump back and execute code again,\n or jump forward to skip code that you don\'t want to run.\n\n It should be noted that not all jumps are allowed -- for instance\n it is not possible to jump into the middle of a "for" loop or out\n of a "finally" clause.\n\nl(ist) [first[, last]]\n\n List source code for the current file. Without arguments, list 11\n lines around the current line or continue the previous listing.\n With "." as argument, list 11 lines around the current line. With\n one argument, list 11 lines around at that line. With two\n arguments, list the given range; if the second argument is less\n than the first, it is interpreted as a count.\n\n The current line in the current frame is indicated by "->". If an\n exception is being debugged, the line where the exception was\n originally raised or propagated is indicated by ">>", if it differs\n from the current line.\n\n New in version 3.2: The ">>" marker.\n\nll | longlist\n\n List all source code for the current function or frame.\n Interesting lines are marked as for "list".\n\n New in version 3.2.\n\na(rgs)\n\n Print the argument list of the current function.\n\np expression\n\n Evaluate the *expression* in the current context and print its\n value.\n\n Note: "print()" can also be used, but is not a debugger command\n --- this executes the Python "print()" function.\n\npp expression\n\n Like the "p" command, except the value of the expression is pretty-\n printed using the "pprint" module.\n\nwhatis expression\n\n Print the type of the *expression*.\n\nsource expression\n\n Try to get source code for the given object and display it.\n\n New in version 3.2.\n\ndisplay [expression]\n\n Display the value of the expression if it changed, each time\n execution stops in the current frame.\n\n Without expression, list all display expressions for the current\n frame.\n\n New in version 3.2.\n\nundisplay [expression]\n\n Do not display the expression any more in the current frame.\n Without expression, clear all display expressions for the current\n frame.\n\n New in version 3.2.\n\ninteract\n\n Start an interative interpreter (using the "code" module) whose\n global namespace contains all the (global and local) names found in\n the current scope.\n\n New in version 3.2.\n\nalias [name [command]]\n\n Create an alias called *name* that executes *command*. The command\n must *not* be enclosed in quotes. Replaceable parameters can be\n indicated by "%1", "%2", and so on, while "%*" is replaced by all\n the parameters. If no command is given, the current alias for\n *name* is shown. If no arguments are given, all aliases are listed.\n\n Aliases may be nested and can contain anything that can be legally\n typed at the pdb prompt. Note that internal pdb commands *can* be\n overridden by aliases. Such a command is then hidden until the\n alias is removed. Aliasing is recursively applied to the first\n word of the command line; all other words in the line are left\n alone.\n\n As an example, here are two useful aliases (especially when placed\n in the ".pdbrc" file):\n\n # Print instance variables (usage "pi classInst")\n alias pi for k in %1.__dict__.keys(): print("%1.",k,"=",%1.__dict__[k])\n # Print instance variables in self\n alias ps pi self\n\nunalias name\n\n Delete the specified alias.\n\n! statement\n\n Execute the (one-line) *statement* in the context of the current\n stack frame. The exclamation point can be omitted unless the first\n word of the statement resembles a debugger command. To set a\n global variable, you can prefix the assignment command with a\n "global" statement on the same line, e.g.:\n\n (Pdb) global list_options; list_options = [\'-l\']\n (Pdb)\n\nrun [args ...]\nrestart [args ...]\n\n Restart the debugged Python program. If an argument is supplied,\n it is split with "shlex" and the result is used as the new\n "sys.argv". History, breakpoints, actions and debugger options are\n preserved. "restart" is an alias for "run".\n\nq(uit)\n\n Quit from the debugger. The program being executed is aborted.\n\n-[ Footnotes ]-\n\n[1] Whether a frame is considered to originate in a certain module\n is determined by the "__name__" in the frame globals.\n', - 'del': u'\nThe "del" statement\n*******************\n\n del_stmt ::= "del" target_list\n\nDeletion is recursively defined very similar to the way assignment is\ndefined. Rather than spelling it out in full details, here are some\nhints.\n\nDeletion of a target list recursively deletes each target, from left\nto right.\n\nDeletion of a name removes the binding of that name from the local or\nglobal namespace, depending on whether the name occurs in a "global"\nstatement in the same code block. If the name is unbound, a\n"NameError" exception will be raised.\n\nDeletion of attribute references, subscriptions and slicings is passed\nto the primary object involved; deletion of a slicing is in general\nequivalent to assignment of an empty slice of the right type (but even\nthis is determined by the sliced object).\n\nChanged in version 3.2: Previously it was illegal to delete a name\nfrom the local namespace if it occurs as a free variable in a nested\nblock.\n', - 'dict': u'\nDictionary displays\n*******************\n\nA dictionary display is a possibly empty series of key/datum pairs\nenclosed in curly braces:\n\n dict_display ::= "{" [key_datum_list | dict_comprehension] "}"\n key_datum_list ::= key_datum ("," key_datum)* [","]\n key_datum ::= expression ":" expression\n dict_comprehension ::= expression ":" expression comp_for\n\nA dictionary display yields a new dictionary object.\n\nIf a comma-separated sequence of key/datum pairs is given, they are\nevaluated from left to right to define the entries of the dictionary:\neach key object is used as a key into the dictionary to store the\ncorresponding datum. This means that you can specify the same key\nmultiple times in the key/datum list, and the final dictionary\'s value\nfor that key will be the last one given.\n\nA dict comprehension, in contrast to list and set comprehensions,\nneeds two expressions separated with a colon followed by the usual\n"for" and "if" clauses. When the comprehension is run, the resulting\nkey and value elements are inserted in the new dictionary in the order\nthey are produced.\n\nRestrictions on the types of the key values are listed earlier in\nsection *The standard type hierarchy*. (To summarize, the key type\nshould be *hashable*, which excludes all mutable objects.) Clashes\nbetween duplicate keys are not detected; the last datum (textually\nrightmost in the display) stored for a given key value prevails.\n', - 'dynamic-features': u'\nInteraction with dynamic features\n*********************************\n\nName resolution of free variables occurs at runtime, not at compile\ntime. This means that the following code will print 42:\n\n i = 10\n def f():\n print(i)\n i = 42\n f()\n\nThere are several cases where Python statements are illegal when used\nin conjunction with nested scopes that contain free variables.\n\nIf a variable is referenced in an enclosing scope, it is illegal to\ndelete the name. An error will be reported at compile time.\n\nThe "eval()" and "exec()" functions do not have access to the full\nenvironment for resolving names. Names may be resolved in the local\nand global namespaces of the caller. Free variables are not resolved\nin the nearest enclosing namespace, but in the global namespace. [1]\nThe "exec()" and "eval()" functions have optional arguments to\noverride the global and local namespace. If only one namespace is\nspecified, it is used for both.\n', - 'else': u'\nThe "if" statement\n******************\n\nThe "if" statement is used for conditional execution:\n\n if_stmt ::= "if" expression ":" suite\n ( "elif" expression ":" suite )*\n ["else" ":" suite]\n\nIt selects exactly one of the suites by evaluating the expressions one\nby one until one is found to be true (see section *Boolean operations*\nfor the definition of true and false); then that suite is executed\n(and no other part of the "if" statement is executed or evaluated).\nIf all expressions are false, the suite of the "else" clause, if\npresent, is executed.\n', - 'exceptions': u'\nExceptions\n**********\n\nExceptions are a means of breaking out of the normal flow of control\nof a code block in order to handle errors or other exceptional\nconditions. An exception is *raised* at the point where the error is\ndetected; it may be *handled* by the surrounding code block or by any\ncode block that directly or indirectly invoked the code block where\nthe error occurred.\n\nThe Python interpreter raises an exception when it detects a run-time\nerror (such as division by zero). A Python program can also\nexplicitly raise an exception with the "raise" statement. Exception\nhandlers are specified with the "try" ... "except" statement. The\n"finally" clause of such a statement can be used to specify cleanup\ncode which does not handle the exception, but is executed whether an\nexception occurred or not in the preceding code.\n\nPython uses the "termination" model of error handling: an exception\nhandler can find out what happened and continue execution at an outer\nlevel, but it cannot repair the cause of the error and retry the\nfailing operation (except by re-entering the offending piece of code\nfrom the top).\n\nWhen an exception is not handled at all, the interpreter terminates\nexecution of the program, or returns to its interactive main loop. In\neither case, it prints a stack backtrace, except when the exception is\n"SystemExit".\n\nExceptions are identified by class instances. The "except" clause is\nselected depending on the class of the instance: it must reference the\nclass of the instance or a base class thereof. The instance can be\nreceived by the handler and can carry additional information about the\nexceptional condition.\n\nNote: Exception messages are not part of the Python API. Their\n contents may change from one version of Python to the next without\n warning and should not be relied on by code which will run under\n multiple versions of the interpreter.\n\nSee also the description of the "try" statement in section *The try\nstatement* and "raise" statement in section *The raise statement*.\n\n-[ Footnotes ]-\n\n[1] This limitation occurs because the code that is executed by\n these operations is not available at the time the module is\n compiled.\n', - 'execmodel': u'\nExecution model\n***************\n\n\nStructure of a program\n======================\n\nA Python program is constructed from code blocks. A *block* is a piece\nof Python program text that is executed as a unit. The following are\nblocks: a module, a function body, and a class definition. Each\ncommand typed interactively is a block. A script file (a file given\nas standard input to the interpreter or specified as a command line\nargument to the interpreter) is a code block. A script command (a\ncommand specified on the interpreter command line with the \'**-c**\'\noption) is a code block. The string argument passed to the built-in\nfunctions "eval()" and "exec()" is a code block.\n\nA code block is executed in an *execution frame*. A frame contains\nsome administrative information (used for debugging) and determines\nwhere and how execution continues after the code block\'s execution has\ncompleted.\n\n\nNaming and binding\n==================\n\n\nBinding of names\n----------------\n\n*Names* refer to objects. Names are introduced by name binding\noperations.\n\nThe following constructs bind names: formal parameters to functions,\n"import" statements, class and function definitions (these bind the\nclass or function name in the defining block), and targets that are\nidentifiers if occurring in an assignment, "for" loop header, or after\n"as" in a "with" statement or "except" clause. The "import" statement\nof the form "from ... import *" binds all names defined in the\nimported module, except those beginning with an underscore. This form\nmay only be used at the module level.\n\nA target occurring in a "del" statement is also considered bound for\nthis purpose (though the actual semantics are to unbind the name).\n\nEach assignment or import statement occurs within a block defined by a\nclass or function definition or at the module level (the top-level\ncode block).\n\nIf a name is bound in a block, it is a local variable of that block,\nunless declared as "nonlocal" or "global". If a name is bound at the\nmodule level, it is a global variable. (The variables of the module\ncode block are local and global.) If a variable is used in a code\nblock but not defined there, it is a *free variable*.\n\nEach occurrence of a name in the program text refers to the *binding*\nof that name established by the following name resolution rules.\n\n\nResolution of names\n-------------------\n\nA *scope* defines the visibility of a name within a block. If a local\nvariable is defined in a block, its scope includes that block. If the\ndefinition occurs in a function block, the scope extends to any blocks\ncontained within the defining one, unless a contained block introduces\na different binding for the name.\n\nWhen a name is used in a code block, it is resolved using the nearest\nenclosing scope. The set of all such scopes visible to a code block\nis called the block\'s *environment*.\n\nWhen a name is not found at all, a "NameError" exception is raised. If\nthe current scope is a function scope, and the name refers to a local\nvariable that has not yet been bound to a value at the point where the\nname is used, an "UnboundLocalError" exception is raised.\n"UnboundLocalError" is a subclass of "NameError".\n\nIf a name binding operation occurs anywhere within a code block, all\nuses of the name within the block are treated as references to the\ncurrent block. This can lead to errors when a name is used within a\nblock before it is bound. This rule is subtle. Python lacks\ndeclarations and allows name binding operations to occur anywhere\nwithin a code block. The local variables of a code block can be\ndetermined by scanning the entire text of the block for name binding\noperations.\n\nIf the "global" statement occurs within a block, all uses of the name\nspecified in the statement refer to the binding of that name in the\ntop-level namespace. Names are resolved in the top-level namespace by\nsearching the global namespace, i.e. the namespace of the module\ncontaining the code block, and the builtins namespace, the namespace\nof the module "builtins". The global namespace is searched first. If\nthe name is not found there, the builtins namespace is searched. The\n"global" statement must precede all uses of the name.\n\nThe "global" statement has the same scope as a name binding operation\nin the same block. If the nearest enclosing scope for a free variable\ncontains a global statement, the free variable is treated as a global.\n\nThe "nonlocal" statement causes corresponding names to refer to\npreviously bound variables in the nearest enclosing function scope.\n"SyntaxError" is raised at compile time if the given name does not\nexist in any enclosing function scope.\n\nThe namespace for a module is automatically created the first time a\nmodule is imported. The main module for a script is always called\n"__main__".\n\nClass definition blocks and arguments to "exec()" and "eval()" are\nspecial in the context of name resolution. A class definition is an\nexecutable statement that may use and define names. These references\nfollow the normal rules for name resolution with an exception that\nunbound local variables are looked up in the global namespace. The\nnamespace of the class definition becomes the attribute dictionary of\nthe class. The scope of names defined in a class block is limited to\nthe class block; it does not extend to the code blocks of methods --\nthis includes comprehensions and generator expressions since they are\nimplemented using a function scope. This means that the following\nwill fail:\n\n class A:\n a = 42\n b = list(a + i for i in range(10))\n\n\nBuiltins and restricted execution\n---------------------------------\n\nThe builtins namespace associated with the execution of a code block\nis actually found by looking up the name "__builtins__" in its global\nnamespace; this should be a dictionary or a module (in the latter case\nthe module\'s dictionary is used). By default, when in the "__main__"\nmodule, "__builtins__" is the built-in module "builtins"; when in any\nother module, "__builtins__" is an alias for the dictionary of the\n"builtins" module itself. "__builtins__" can be set to a user-created\ndictionary to create a weak form of restricted execution.\n\n**CPython implementation detail:** Users should not touch\n"__builtins__"; it is strictly an implementation detail. Users\nwanting to override values in the builtins namespace should "import"\nthe "builtins" module and modify its attributes appropriately.\n\n\nInteraction with dynamic features\n---------------------------------\n\nName resolution of free variables occurs at runtime, not at compile\ntime. This means that the following code will print 42:\n\n i = 10\n def f():\n print(i)\n i = 42\n f()\n\nThere are several cases where Python statements are illegal when used\nin conjunction with nested scopes that contain free variables.\n\nIf a variable is referenced in an enclosing scope, it is illegal to\ndelete the name. An error will be reported at compile time.\n\nThe "eval()" and "exec()" functions do not have access to the full\nenvironment for resolving names. Names may be resolved in the local\nand global namespaces of the caller. Free variables are not resolved\nin the nearest enclosing namespace, but in the global namespace. [1]\nThe "exec()" and "eval()" functions have optional arguments to\noverride the global and local namespace. If only one namespace is\nspecified, it is used for both.\n\n\nExceptions\n==========\n\nExceptions are a means of breaking out of the normal flow of control\nof a code block in order to handle errors or other exceptional\nconditions. An exception is *raised* at the point where the error is\ndetected; it may be *handled* by the surrounding code block or by any\ncode block that directly or indirectly invoked the code block where\nthe error occurred.\n\nThe Python interpreter raises an exception when it detects a run-time\nerror (such as division by zero). A Python program can also\nexplicitly raise an exception with the "raise" statement. Exception\nhandlers are specified with the "try" ... "except" statement. The\n"finally" clause of such a statement can be used to specify cleanup\ncode which does not handle the exception, but is executed whether an\nexception occurred or not in the preceding code.\n\nPython uses the "termination" model of error handling: an exception\nhandler can find out what happened and continue execution at an outer\nlevel, but it cannot repair the cause of the error and retry the\nfailing operation (except by re-entering the offending piece of code\nfrom the top).\n\nWhen an exception is not handled at all, the interpreter terminates\nexecution of the program, or returns to its interactive main loop. In\neither case, it prints a stack backtrace, except when the exception is\n"SystemExit".\n\nExceptions are identified by class instances. The "except" clause is\nselected depending on the class of the instance: it must reference the\nclass of the instance or a base class thereof. The instance can be\nreceived by the handler and can carry additional information about the\nexceptional condition.\n\nNote: Exception messages are not part of the Python API. Their\n contents may change from one version of Python to the next without\n warning and should not be relied on by code which will run under\n multiple versions of the interpreter.\n\nSee also the description of the "try" statement in section *The try\nstatement* and "raise" statement in section *The raise statement*.\n\n-[ Footnotes ]-\n\n[1] This limitation occurs because the code that is executed by\n these operations is not available at the time the module is\n compiled.\n', - 'exprlists': u'\nExpression lists\n****************\n\n expression_list ::= expression ( "," expression )* [","]\n\nAn expression list containing at least one comma yields a tuple. The\nlength of the tuple is the number of expressions in the list. The\nexpressions are evaluated from left to right.\n\nThe trailing comma is required only to create a single tuple (a.k.a. a\n*singleton*); it is optional in all other cases. A single expression\nwithout a trailing comma doesn\'t create a tuple, but rather yields the\nvalue of that expression. (To create an empty tuple, use an empty pair\nof parentheses: "()".)\n', - 'floating': u'\nFloating point literals\n***********************\n\nFloating point literals are described by the following lexical\ndefinitions:\n\n floatnumber ::= pointfloat | exponentfloat\n pointfloat ::= [intpart] fraction | intpart "."\n exponentfloat ::= (intpart | pointfloat) exponent\n intpart ::= digit+\n fraction ::= "." digit+\n exponent ::= ("e" | "E") ["+" | "-"] digit+\n\nNote that the integer and exponent parts are always interpreted using\nradix 10. For example, "077e010" is legal, and denotes the same number\nas "77e10". The allowed range of floating point literals is\nimplementation-dependent. Some examples of floating point literals:\n\n 3.14 10. .001 1e100 3.14e-10 0e0\n\nNote that numeric literals do not include a sign; a phrase like "-1"\nis actually an expression composed of the unary operator "-" and the\nliteral "1".\n', - 'for': u'\nThe "for" statement\n*******************\n\nThe "for" statement is used to iterate over the elements of a sequence\n(such as a string, tuple or list) or other iterable object:\n\n for_stmt ::= "for" target_list "in" expression_list ":" suite\n ["else" ":" suite]\n\nThe expression list is evaluated once; it should yield an iterable\nobject. An iterator is created for the result of the\n"expression_list". The suite is then executed once for each item\nprovided by the iterator, in the order returned by the iterator. Each\nitem in turn is assigned to the target list using the standard rules\nfor assignments (see *Assignment statements*), and then the suite is\nexecuted. When the items are exhausted (which is immediately when the\nsequence is empty or an iterator raises a "StopIteration" exception),\nthe suite in the "else" clause, if present, is executed, and the loop\nterminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and continues\nwith the next item, or with the "else" clause if there is no next\nitem.\n\nThe for-loop makes assignments to the variables(s) in the target list.\nThis overwrites all previous assignments to those variables including\nthose made in the suite of the for-loop:\n\n for i in range(10):\n print(i)\n i = 5 # this will not affect the for-loop\n # because i will be overwritten with the next\n # index in the range\n\nNames in the target list are not deleted when the loop is finished,\nbut if the sequence is empty, they will not have been assigned to at\nall by the loop. Hint: the built-in function "range()" returns an\niterator of integers suitable to emulate the effect of Pascal\'s "for i\n:= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n\nNote: There is a subtlety when the sequence is being modified by the\n loop (this can only occur for mutable sequences, i.e. lists). An\n internal counter is used to keep track of which item is used next,\n and this is incremented on each iteration. When this counter has\n reached the length of the sequence the loop terminates. This means\n that if the suite deletes the current (or a previous) item from the\n sequence, the next item will be skipped (since it gets the index of\n the current item which has already been treated). Likewise, if the\n suite inserts an item in the sequence before the current item, the\n current item will be treated again the next time through the loop.\n This can lead to nasty bugs that can be avoided by making a\n temporary copy using a slice of the whole sequence, e.g.,\n\n for x in a[:]:\n if x < 0: a.remove(x)\n', - 'formatstrings': u'\nFormat String Syntax\n********************\n\nThe "str.format()" method and the "Formatter" class share the same\nsyntax for format strings (although in the case of "Formatter",\nsubclasses can define their own format string syntax).\n\nFormat strings contain "replacement fields" surrounded by curly braces\n"{}". Anything that is not contained in braces is considered literal\ntext, which is copied unchanged to the output. If you need to include\na brace character in the literal text, it can be escaped by doubling:\n"{{" and "}}".\n\nThe grammar for a replacement field is as follows:\n\n replacement_field ::= "{" [field_name] ["!" conversion] [":" format_spec] "}"\n field_name ::= arg_name ("." attribute_name | "[" element_index "]")*\n arg_name ::= [identifier | integer]\n attribute_name ::= identifier\n element_index ::= integer | index_string\n index_string ::= +\n conversion ::= "r" | "s" | "a"\n format_spec ::= \n\nIn less formal terms, the replacement field can start with a\n*field_name* that specifies the object whose value is to be formatted\nand inserted into the output instead of the replacement field. The\n*field_name* is optionally followed by a *conversion* field, which is\npreceded by an exclamation point "\'!\'", and a *format_spec*, which is\npreceded by a colon "\':\'". These specify a non-default format for the\nreplacement value.\n\nSee also the *Format Specification Mini-Language* section.\n\nThe *field_name* itself begins with an *arg_name* that is either a\nnumber or a keyword. If it\'s a number, it refers to a positional\nargument, and if it\'s a keyword, it refers to a named keyword\nargument. If the numerical arg_names in a format string are 0, 1, 2,\n... in sequence, they can all be omitted (not just some) and the\nnumbers 0, 1, 2, ... will be automatically inserted in that order.\nBecause *arg_name* is not quote-delimited, it is not possible to\nspecify arbitrary dictionary keys (e.g., the strings "\'10\'" or\n"\':-]\'") within a format string. The *arg_name* can be followed by any\nnumber of index or attribute expressions. An expression of the form\n"\'.name\'" selects the named attribute using "getattr()", while an\nexpression of the form "\'[index]\'" does an index lookup using\n"__getitem__()".\n\nChanged in version 3.1: The positional argument specifiers can be\nomitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n\nSome simple format string examples:\n\n "First, thou shalt count to {0}" # References first positional argument\n "Bring me a {}" # Implicitly references the first positional argument\n "From {} to {}" # Same as "From {0} to {1}"\n "My quest is {name}" # References keyword argument \'name\'\n "Weight in tons {0.weight}" # \'weight\' attribute of first positional arg\n "Units destroyed: {players[0]}" # First element of keyword argument \'players\'.\n\nThe *conversion* field causes a type coercion before formatting.\nNormally, the job of formatting a value is done by the "__format__()"\nmethod of the value itself. However, in some cases it is desirable to\nforce a type to be formatted as a string, overriding its own\ndefinition of formatting. By converting the value to a string before\ncalling "__format__()", the normal formatting logic is bypassed.\n\nThree conversion flags are currently supported: "\'!s\'" which calls\n"str()" on the value, "\'!r\'" which calls "repr()" and "\'!a\'" which\ncalls "ascii()".\n\nSome examples:\n\n "Harold\'s a clever {0!s}" # Calls str() on the argument first\n "Bring out the holy {name!r}" # Calls repr() on the argument first\n "More {!a}" # Calls ascii() on the argument first\n\nThe *format_spec* field contains a specification of how the value\nshould be presented, including such details as field width, alignment,\npadding, decimal precision and so on. Each value type can define its\nown "formatting mini-language" or interpretation of the *format_spec*.\n\nMost built-in types support a common formatting mini-language, which\nis described in the next section.\n\nA *format_spec* field can also include nested replacement fields\nwithin it. These nested replacement fields can contain only a field\nname; conversion flags and format specifications are not allowed. The\nreplacement fields within the format_spec are substituted before the\n*format_spec* string is interpreted. This allows the formatting of a\nvalue to be dynamically specified.\n\nSee the *Format examples* section for some examples.\n\n\nFormat Specification Mini-Language\n==================================\n\n"Format specifications" are used within replacement fields contained\nwithin a format string to define how individual values are presented\n(see *Format String Syntax*). They can also be passed directly to the\nbuilt-in "format()" function. Each formattable type may define how\nthe format specification is to be interpreted.\n\nMost built-in types implement the following options for format\nspecifications, although some of the formatting options are only\nsupported by the numeric types.\n\nA general convention is that an empty format string ("""") produces\nthe same result as if you had called "str()" on the value. A non-empty\nformat string typically modifies the result.\n\nThe general form of a *standard format specifier* is:\n\n format_spec ::= [[fill]align][sign][#][0][width][,][.precision][type]\n fill ::= \n align ::= "<" | ">" | "=" | "^"\n sign ::= "+" | "-" | " "\n width ::= integer\n precision ::= integer\n type ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n\nIf a valid *align* value is specified, it can be preceded by a *fill*\ncharacter that can be any character and defaults to a space if\nomitted. Note that it is not possible to use "{" and "}" as *fill*\nchar while using the "str.format()" method; this limitation however\ndoesn\'t affect the "format()" function.\n\nThe meaning of the various alignment options is as follows:\n\n +-----------+------------------------------------------------------------+\n | Option | Meaning |\n +===========+============================================================+\n | "\'<\'" | Forces the field to be left-aligned within the available |\n | | space (this is the default for most objects). |\n +-----------+------------------------------------------------------------+\n | "\'>\'" | Forces the field to be right-aligned within the available |\n | | space (this is the default for numbers). |\n +-----------+------------------------------------------------------------+\n | "\'=\'" | Forces the padding to be placed after the sign (if any) |\n | | but before the digits. This is used for printing fields |\n | | in the form \'+000000120\'. This alignment option is only |\n | | valid for numeric types. |\n +-----------+------------------------------------------------------------+\n | "\'^\'" | Forces the field to be centered within the available |\n | | space. |\n +-----------+------------------------------------------------------------+\n\nNote that unless a minimum field width is defined, the field width\nwill always be the same size as the data to fill it, so that the\nalignment option has no meaning in this case.\n\nThe *sign* option is only valid for number types, and can be one of\nthe following:\n\n +-----------+------------------------------------------------------------+\n | Option | Meaning |\n +===========+============================================================+\n | "\'+\'" | indicates that a sign should be used for both positive as |\n | | well as negative numbers. |\n +-----------+------------------------------------------------------------+\n | "\'-\'" | indicates that a sign should be used only for negative |\n | | numbers (this is the default behavior). |\n +-----------+------------------------------------------------------------+\n | space | indicates that a leading space should be used on positive |\n | | numbers, and a minus sign on negative numbers. |\n +-----------+------------------------------------------------------------+\n\nThe "\'#\'" option causes the "alternate form" to be used for the\nconversion. The alternate form is defined differently for different\ntypes. This option is only valid for integer, float, complex and\nDecimal types. For integers, when binary, octal, or hexadecimal output\nis used, this option adds the prefix respective "\'0b\'", "\'0o\'", or\n"\'0x\'" to the output value. For floats, complex and Decimal the\nalternate form causes the result of the conversion to always contain a\ndecimal-point character, even if no digits follow it. Normally, a\ndecimal-point character appears in the result of these conversions\nonly if a digit follows it. In addition, for "\'g\'" and "\'G\'"\nconversions, trailing zeros are not removed from the result.\n\nThe "\',\'" option signals the use of a comma for a thousands separator.\nFor a locale aware separator, use the "\'n\'" integer presentation type\ninstead.\n\nChanged in version 3.1: Added the "\',\'" option (see also **PEP 378**).\n\n*width* is a decimal integer defining the minimum field width. If not\nspecified, then the field width will be determined by the content.\n\nPreceding the *width* field by a zero ("\'0\'") character enables sign-\naware zero-padding for numeric types. This is equivalent to a *fill*\ncharacter of "\'0\'" with an *alignment* type of "\'=\'".\n\nThe *precision* is a decimal number indicating how many digits should\nbe displayed after the decimal point for a floating point value\nformatted with "\'f\'" and "\'F\'", or before and after the decimal point\nfor a floating point value formatted with "\'g\'" or "\'G\'". For non-\nnumber types the field indicates the maximum field size - in other\nwords, how many characters will be used from the field content. The\n*precision* is not allowed for integer values.\n\nFinally, the *type* determines how the data should be presented.\n\nThe available string presentation types are:\n\n +-----------+------------------------------------------------------------+\n | Type | Meaning |\n +===========+============================================================+\n | "\'s\'" | String format. This is the default type for strings and |\n | | may be omitted. |\n +-----------+------------------------------------------------------------+\n | None | The same as "\'s\'". |\n +-----------+------------------------------------------------------------+\n\nThe available integer presentation types are:\n\n +-----------+------------------------------------------------------------+\n | Type | Meaning |\n +===========+============================================================+\n | "\'b\'" | Binary format. Outputs the number in base 2. |\n +-----------+------------------------------------------------------------+\n | "\'c\'" | Character. Converts the integer to the corresponding |\n | | unicode character before printing. |\n +-----------+------------------------------------------------------------+\n | "\'d\'" | Decimal Integer. Outputs the number in base 10. |\n +-----------+------------------------------------------------------------+\n | "\'o\'" | Octal format. Outputs the number in base 8. |\n +-----------+------------------------------------------------------------+\n | "\'x\'" | Hex format. Outputs the number in base 16, using lower- |\n | | case letters for the digits above 9. |\n +-----------+------------------------------------------------------------+\n | "\'X\'" | Hex format. Outputs the number in base 16, using upper- |\n | | case letters for the digits above 9. |\n +-----------+------------------------------------------------------------+\n | "\'n\'" | Number. This is the same as "\'d\'", except that it uses the |\n | | current locale setting to insert the appropriate number |\n | | separator characters. |\n +-----------+------------------------------------------------------------+\n | None | The same as "\'d\'". |\n +-----------+------------------------------------------------------------+\n\nIn addition to the above presentation types, integers can be formatted\nwith the floating point presentation types listed below (except "\'n\'"\nand None). When doing so, "float()" is used to convert the integer to\na floating point number before formatting.\n\nThe available presentation types for floating point and decimal values\nare:\n\n +-----------+------------------------------------------------------------+\n | Type | Meaning |\n +===========+============================================================+\n | "\'e\'" | Exponent notation. Prints the number in scientific |\n | | notation using the letter \'e\' to indicate the exponent. |\n | | The default precision is "6". |\n +-----------+------------------------------------------------------------+\n | "\'E\'" | Exponent notation. Same as "\'e\'" except it uses an upper |\n | | case \'E\' as the separator character. |\n +-----------+------------------------------------------------------------+\n | "\'f\'" | Fixed point. Displays the number as a fixed-point number. |\n | | The default precision is "6". |\n +-----------+------------------------------------------------------------+\n | "\'F\'" | Fixed point. Same as "\'f\'", but converts "nan" to "NAN" |\n | | and "inf" to "INF". |\n +-----------+------------------------------------------------------------+\n | "\'g\'" | General format. For a given precision "p >= 1", this |\n | | rounds the number to "p" significant digits and then |\n | | formats the result in either fixed-point format or in |\n | | scientific notation, depending on its magnitude. The |\n | | precise rules are as follows: suppose that the result |\n | | formatted with presentation type "\'e\'" and precision "p-1" |\n | | would have exponent "exp". Then if "-4 <= exp < p", the |\n | | number is formatted with presentation type "\'f\'" and |\n | | precision "p-1-exp". Otherwise, the number is formatted |\n | | with presentation type "\'e\'" and precision "p-1". In both |\n | | cases insignificant trailing zeros are removed from the |\n | | significand, and the decimal point is also removed if |\n | | there are no remaining digits following it. Positive and |\n | | negative infinity, positive and negative zero, and nans, |\n | | are formatted as "inf", "-inf", "0", "-0" and "nan" |\n | | respectively, regardless of the precision. A precision of |\n | | "0" is treated as equivalent to a precision of "1". The |\n | | default precision is "6". |\n +-----------+------------------------------------------------------------+\n | "\'G\'" | General format. Same as "\'g\'" except switches to "\'E\'" if |\n | | the number gets too large. The representations of infinity |\n | | and NaN are uppercased, too. |\n +-----------+------------------------------------------------------------+\n | "\'n\'" | Number. This is the same as "\'g\'", except that it uses the |\n | | current locale setting to insert the appropriate number |\n | | separator characters. |\n +-----------+------------------------------------------------------------+\n | "\'%\'" | Percentage. Multiplies the number by 100 and displays in |\n | | fixed ("\'f\'") format, followed by a percent sign. |\n +-----------+------------------------------------------------------------+\n | None | Similar to "\'g\'", except that fixed-point notation, when |\n | | used, has at least one digit past the decimal point. The |\n | | default precision is as high as needed to represent the |\n | | particular value. The overall effect is to match the |\n | | output of "str()" as altered by the other format |\n | | modifiers. |\n +-----------+------------------------------------------------------------+\n\n\nFormat examples\n===============\n\nThis section contains examples of the new format syntax and comparison\nwith the old "%"-formatting.\n\nIn most of the cases the syntax is similar to the old "%"-formatting,\nwith the addition of the "{}" and with ":" used instead of "%". For\nexample, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n\nThe new format syntax also supports new and different options, shown\nin the follow examples.\n\nAccessing arguments by position:\n\n >>> \'{0}, {1}, {2}\'.format(\'a\', \'b\', \'c\')\n \'a, b, c\'\n >>> \'{}, {}, {}\'.format(\'a\', \'b\', \'c\') # 3.1+ only\n \'a, b, c\'\n >>> \'{2}, {1}, {0}\'.format(\'a\', \'b\', \'c\')\n \'c, b, a\'\n >>> \'{2}, {1}, {0}\'.format(*\'abc\') # unpacking argument sequence\n \'c, b, a\'\n >>> \'{0}{1}{0}\'.format(\'abra\', \'cad\') # arguments\' indices can be repeated\n \'abracadabra\'\n\nAccessing arguments by name:\n\n >>> \'Coordinates: {latitude}, {longitude}\'.format(latitude=\'37.24N\', longitude=\'-115.81W\')\n \'Coordinates: 37.24N, -115.81W\'\n >>> coord = {\'latitude\': \'37.24N\', \'longitude\': \'-115.81W\'}\n >>> \'Coordinates: {latitude}, {longitude}\'.format(**coord)\n \'Coordinates: 37.24N, -115.81W\'\n\nAccessing arguments\' attributes:\n\n >>> c = 3-5j\n >>> (\'The complex number {0} is formed from the real part {0.real} \'\n ... \'and the imaginary part {0.imag}.\').format(c)\n \'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.\'\n >>> class Point:\n ... def __init__(self, x, y):\n ... self.x, self.y = x, y\n ... def __str__(self):\n ... return \'Point({self.x}, {self.y})\'.format(self=self)\n ...\n >>> str(Point(4, 2))\n \'Point(4, 2)\'\n\nAccessing arguments\' items:\n\n >>> coord = (3, 5)\n >>> \'X: {0[0]}; Y: {0[1]}\'.format(coord)\n \'X: 3; Y: 5\'\n\nReplacing "%s" and "%r":\n\n >>> "repr() shows quotes: {!r}; str() doesn\'t: {!s}".format(\'test1\', \'test2\')\n "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n\nAligning the text and specifying a width:\n\n >>> \'{:<30}\'.format(\'left aligned\')\n \'left aligned \'\n >>> \'{:>30}\'.format(\'right aligned\')\n \' right aligned\'\n >>> \'{:^30}\'.format(\'centered\')\n \' centered \'\n >>> \'{:*^30}\'.format(\'centered\') # use \'*\' as a fill char\n \'***********centered***********\'\n\nReplacing "%+f", "%-f", and "% f" and specifying a sign:\n\n >>> \'{:+f}; {:+f}\'.format(3.14, -3.14) # show it always\n \'+3.140000; -3.140000\'\n >>> \'{: f}; {: f}\'.format(3.14, -3.14) # show a space for positive numbers\n \' 3.140000; -3.140000\'\n >>> \'{:-f}; {:-f}\'.format(3.14, -3.14) # show only the minus -- same as \'{:f}; {:f}\'\n \'3.140000; -3.140000\'\n\nReplacing "%x" and "%o" and converting the value to different bases:\n\n >>> # format also supports binary numbers\n >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)\n \'int: 42; hex: 2a; oct: 52; bin: 101010\'\n >>> # with 0x, 0o, or 0b as prefix:\n >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)\n \'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010\'\n\nUsing the comma as a thousands separator:\n\n >>> \'{:,}\'.format(1234567890)\n \'1,234,567,890\'\n\nExpressing a percentage:\n\n >>> points = 19\n >>> total = 22\n >>> \'Correct answers: {:.2%}\'.format(points/total)\n \'Correct answers: 86.36%\'\n\nUsing type-specific formatting:\n\n >>> import datetime\n >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n >>> \'{:%Y-%m-%d %H:%M:%S}\'.format(d)\n \'2010-07-04 12:15:58\'\n\nNesting arguments and more complex examples:\n\n >>> for align, text in zip(\'<^>\', [\'left\', \'center\', \'right\']):\n ... \'{0:{fill}{align}16}\'.format(text, fill=align, align=align)\n ...\n \'left<<<<<<<<<<<<\'\n \'^^^^^center^^^^^\'\n \'>>>>>>>>>>>right\'\n >>>\n >>> octets = [192, 168, 0, 1]\n >>> \'{:02X}{:02X}{:02X}{:02X}\'.format(*octets)\n \'C0A80001\'\n >>> int(_, 16)\n 3232235521\n >>>\n >>> width = 5\n >>> for num in range(5,12): #doctest: +NORMALIZE_WHITESPACE\n ... for base in \'dXob\':\n ... print(\'{0:{width}{base}}\'.format(num, base=base, width=width), end=\' \')\n ... print()\n ...\n 5 5 5 101\n 6 6 6 110\n 7 7 7 111\n 8 8 10 1000\n 9 9 11 1001\n 10 A 12 1010\n 11 B 13 1011\n', - 'function': u'\nFunction definitions\n********************\n\nA function definition defines a user-defined function object (see\nsection *The standard type hierarchy*):\n\n funcdef ::= [decorators] "def" funcname "(" [parameter_list] ")" ["->" expression] ":" suite\n decorators ::= decorator+\n decorator ::= "@" dotted_name ["(" [parameter_list [","]] ")"] NEWLINE\n dotted_name ::= identifier ("." identifier)*\n parameter_list ::= (defparameter ",")*\n | "*" [parameter] ("," defparameter)* ["," "**" parameter]\n | "**" parameter\n | defparameter [","] )\n parameter ::= identifier [":" expression]\n defparameter ::= parameter ["=" expression]\n funcname ::= identifier\n\nA function definition is an executable statement. Its execution binds\nthe function name in the current local namespace to a function object\n(a wrapper around the executable code for the function). This\nfunction object contains a reference to the current global namespace\nas the global namespace to be used when the function is called.\n\nThe function definition does not execute the function body; this gets\nexecuted only when the function is called. [3]\n\nA function definition may be wrapped by one or more *decorator*\nexpressions. Decorator expressions are evaluated when the function is\ndefined, in the scope that contains the function definition. The\nresult must be a callable, which is invoked with the function object\nas the only argument. The returned value is bound to the function name\ninstead of the function object. Multiple decorators are applied in\nnested fashion. For example, the following code\n\n @f1(arg)\n @f2\n def func(): pass\n\nis equivalent to\n\n def func(): pass\n func = f1(arg)(f2(func))\n\nWhen one or more *parameters* have the form *parameter* "="\n*expression*, the function is said to have "default parameter values."\nFor a parameter with a default value, the corresponding *argument* may\nbe omitted from a call, in which case the parameter\'s default value is\nsubstituted. If a parameter has a default value, all following\nparameters up until the ""*"" must also have a default value --- this\nis a syntactic restriction that is not expressed by the grammar.\n\n**Default parameter values are evaluated from left to right when the\nfunction definition is executed.** This means that the expression is\nevaluated once, when the function is defined, and that the same "pre-\ncomputed" value is used for each call. This is especially important\nto understand when a default parameter is a mutable object, such as a\nlist or a dictionary: if the function modifies the object (e.g. by\nappending an item to a list), the default value is in effect modified.\nThis is generally not what was intended. A way around this is to use\n"None" as the default, and explicitly test for it in the body of the\nfunction, e.g.:\n\n def whats_on_the_telly(penguin=None):\n if penguin is None:\n penguin = []\n penguin.append("property of the zoo")\n return penguin\n\nFunction call semantics are described in more detail in section\n*Calls*. A function call always assigns values to all parameters\nmentioned in the parameter list, either from position arguments, from\nkeyword arguments, or from default values. If the form\n""*identifier"" is present, it is initialized to a tuple receiving any\nexcess positional parameters, defaulting to the empty tuple. If the\nform ""**identifier"" is present, it is initialized to a new\ndictionary receiving any excess keyword arguments, defaulting to a new\nempty dictionary. Parameters after ""*"" or ""*identifier"" are\nkeyword-only parameters and may only be passed used keyword arguments.\n\nParameters may have annotations of the form "": expression"" following\nthe parameter name. Any parameter may have an annotation even those\nof the form "*identifier" or "**identifier". Functions may have\n"return" annotation of the form ""-> expression"" after the parameter\nlist. These annotations can be any valid Python expression and are\nevaluated when the function definition is executed. Annotations may\nbe evaluated in a different order than they appear in the source code.\nThe presence of annotations does not change the semantics of a\nfunction. The annotation values are available as values of a\ndictionary keyed by the parameters\' names in the "__annotations__"\nattribute of the function object.\n\nIt is also possible to create anonymous functions (functions not bound\nto a name), for immediate use in expressions. This uses lambda\nexpressions, described in section *Lambdas*. Note that the lambda\nexpression is merely a shorthand for a simplified function definition;\na function defined in a ""def"" statement can be passed around or\nassigned to another name just like a function defined by a lambda\nexpression. The ""def"" form is actually more powerful since it\nallows the execution of multiple statements and annotations.\n\n**Programmer\'s note:** Functions are first-class objects. A ""def""\nstatement executed inside a function definition defines a local\nfunction that can be returned or passed around. Free variables used\nin the nested function can access the local variables of the function\ncontaining the def. See section *Naming and binding* for details.\n\nSee also: **PEP 3107** - Function Annotations\n\n The original specification for function annotations.\n', - 'global': u'\nThe "global" statement\n**********************\n\n global_stmt ::= "global" identifier ("," identifier)*\n\nThe "global" statement is a declaration which holds for the entire\ncurrent code block. It means that the listed identifiers are to be\ninterpreted as globals. It would be impossible to assign to a global\nvariable without "global", although free variables may refer to\nglobals without being declared global.\n\nNames listed in a "global" statement must not be used in the same code\nblock textually preceding that "global" statement.\n\nNames listed in a "global" statement must not be defined as formal\nparameters or in a "for" loop control target, "class" definition,\nfunction definition, or "import" statement.\n\n**CPython implementation detail:** The current implementation does not\nenforce the two restrictions, but programs should not abuse this\nfreedom, as future implementations may enforce them or silently change\nthe meaning of the program.\n\n**Programmer\'s note:** the "global" is a directive to the parser. It\napplies only to code parsed at the same time as the "global"\nstatement. In particular, a "global" statement contained in a string\nor code object supplied to the built-in "exec()" function does not\naffect the code block *containing* the function call, and code\ncontained in such a string is unaffected by "global" statements in the\ncode containing the function call. The same applies to the "eval()"\nand "compile()" functions.\n', - 'id-classes': u'\nReserved classes of identifiers\n*******************************\n\nCertain classes of identifiers (besides keywords) have special\nmeanings. These classes are identified by the patterns of leading and\ntrailing underscore characters:\n\n"_*"\n Not imported by "from module import *". The special identifier "_"\n is used in the interactive interpreter to store the result of the\n last evaluation; it is stored in the "builtins" module. When not\n in interactive mode, "_" has no special meaning and is not defined.\n See section *The import statement*.\n\n Note: The name "_" is often used in conjunction with\n internationalization; refer to the documentation for the\n "gettext" module for more information on this convention.\n\n"__*__"\n System-defined names. These names are defined by the interpreter\n and its implementation (including the standard library). Current\n system names are discussed in the *Special method names* section\n and elsewhere. More will likely be defined in future versions of\n Python. *Any* use of "__*__" names, in any context, that does not\n follow explicitly documented use, is subject to breakage without\n warning.\n\n"__*"\n Class-private names. Names in this category, when used within the\n context of a class definition, are re-written to use a mangled form\n to help avoid name clashes between "private" attributes of base and\n derived classes. See section *Identifiers (Names)*.\n', - 'identifiers': u'\nIdentifiers and keywords\n************************\n\nIdentifiers (also referred to as *names*) are described by the\nfollowing lexical definitions.\n\nThe syntax of identifiers in Python is based on the Unicode standard\nannex UAX-31, with elaboration and changes as defined below; see also\n**PEP 3131** for further details.\n\nWithin the ASCII range (U+0001..U+007F), the valid characters for\nidentifiers are the same as in Python 2.x: the uppercase and lowercase\nletters "A" through "Z", the underscore "_" and, except for the first\ncharacter, the digits "0" through "9".\n\nPython 3.0 introduces additional characters from outside the ASCII\nrange (see **PEP 3131**). For these characters, the classification\nuses the version of the Unicode Character Database as included in the\n"unicodedata" module.\n\nIdentifiers are unlimited in length. Case is significant.\n\n identifier ::= xid_start xid_continue*\n id_start ::= \n id_continue ::= \n xid_start ::= \n xid_continue ::= \n\nThe Unicode category codes mentioned above stand for:\n\n* *Lu* - uppercase letters\n\n* *Ll* - lowercase letters\n\n* *Lt* - titlecase letters\n\n* *Lm* - modifier letters\n\n* *Lo* - other letters\n\n* *Nl* - letter numbers\n\n* *Mn* - nonspacing marks\n\n* *Mc* - spacing combining marks\n\n* *Nd* - decimal numbers\n\n* *Pc* - connector punctuations\n\n* *Other_ID_Start* - explicit list of characters in PropList.txt to\n support backwards compatibility\n\n* *Other_ID_Continue* - likewise\n\nAll identifiers are converted into the normal form NFKC while parsing;\ncomparison of identifiers is based on NFKC.\n\nA non-normative HTML file listing all valid identifier characters for\nUnicode 4.1 can be found at http://www.dcl.hpi.uni-\npotsdam.de/home/loewis/table-3131.html.\n\n\nKeywords\n========\n\nThe following identifiers are used as reserved words, or *keywords* of\nthe language, and cannot be used as ordinary identifiers. They must\nbe spelled exactly as written here:\n\n False class finally is return\n None continue for lambda try\n True def from nonlocal while\n and del global not with\n as elif if or yield\n assert else import pass\n break except in raise\n\n\nReserved classes of identifiers\n===============================\n\nCertain classes of identifiers (besides keywords) have special\nmeanings. These classes are identified by the patterns of leading and\ntrailing underscore characters:\n\n"_*"\n Not imported by "from module import *". The special identifier "_"\n is used in the interactive interpreter to store the result of the\n last evaluation; it is stored in the "builtins" module. When not\n in interactive mode, "_" has no special meaning and is not defined.\n See section *The import statement*.\n\n Note: The name "_" is often used in conjunction with\n internationalization; refer to the documentation for the\n "gettext" module for more information on this convention.\n\n"__*__"\n System-defined names. These names are defined by the interpreter\n and its implementation (including the standard library). Current\n system names are discussed in the *Special method names* section\n and elsewhere. More will likely be defined in future versions of\n Python. *Any* use of "__*__" names, in any context, that does not\n follow explicitly documented use, is subject to breakage without\n warning.\n\n"__*"\n Class-private names. Names in this category, when used within the\n context of a class definition, are re-written to use a mangled form\n to help avoid name clashes between "private" attributes of base and\n derived classes. See section *Identifiers (Names)*.\n', - 'if': u'\nThe "if" statement\n******************\n\nThe "if" statement is used for conditional execution:\n\n if_stmt ::= "if" expression ":" suite\n ( "elif" expression ":" suite )*\n ["else" ":" suite]\n\nIt selects exactly one of the suites by evaluating the expressions one\nby one until one is found to be true (see section *Boolean operations*\nfor the definition of true and false); then that suite is executed\n(and no other part of the "if" statement is executed or evaluated).\nIf all expressions are false, the suite of the "else" clause, if\npresent, is executed.\n', - 'imaginary': u'\nImaginary literals\n******************\n\nImaginary literals are described by the following lexical definitions:\n\n imagnumber ::= (floatnumber | intpart) ("j" | "J")\n\nAn imaginary literal yields a complex number with a real part of 0.0.\nComplex numbers are represented as a pair of floating point numbers\nand have the same restrictions on their range. To create a complex\nnumber with a nonzero real part, add a floating point number to it,\ne.g., "(3+4j)". Some examples of imaginary literals:\n\n 3.14j 10.j 10j .001j 1e100j 3.14e-10j\n', - 'import': u'\nThe "import" statement\n**********************\n\n import_stmt ::= "import" module ["as" name] ( "," module ["as" name] )*\n | "from" relative_module "import" identifier ["as" name]\n ( "," identifier ["as" name] )*\n | "from" relative_module "import" "(" identifier ["as" name]\n ( "," identifier ["as" name] )* [","] ")"\n | "from" module "import" "*"\n module ::= (identifier ".")* identifier\n relative_module ::= "."* module | "."+\n name ::= identifier\n\nThe basic import statement (no "from" clause) is executed in two\nsteps:\n\n1. find a module, loading and initializing it if necessary\n\n2. define a name or names in the local namespace for the scope\n where the "import" statement occurs.\n\nWhen the statement contains multiple clauses (separated by commas) the\ntwo steps are carried out separately for each clause, just as though\nthe clauses had been separated out into individiual import statements.\n\nThe details of the first step, finding and loading modules are\ndescribed in greater detail in the section on the *import system*,\nwhich also describes the various types of packages and modules that\ncan be imported, as well as all the hooks that can be used to\ncustomize the import system. Note that failures in this step may\nindicate either that the module could not be located, *or* that an\nerror occurred while initializing the module, which includes execution\nof the module\'s code.\n\nIf the requested module is retrieved successfully, it will be made\navailable in the local namespace in one of three ways:\n\n* If the module name is followed by "as", then the name following\n "as" is bound directly to the imported module.\n\n* If no other name is specified, and the module being imported is a\n top level module, the module\'s name is bound in the local namespace\n as a reference to the imported module\n\n* If the module being imported is *not* a top level module, then the\n name of the top level package that contains the module is bound in\n the local namespace as a reference to the top level package. The\n imported module must be accessed using its full qualified name\n rather than directly\n\nThe "from" form uses a slightly more complex process:\n\n1. find the module specified in the "from" clause, loading and\n initializing it if necessary;\n\n2. for each of the identifiers specified in the "import" clauses:\n\n 1. check if the imported module has an attribute by that name\n\n 2. if not, attempt to import a submodule with that name and then\n check the imported module again for that attribute\n\n 3. if the attribute is not found, "ImportError" is raised.\n\n 4. otherwise, a reference to that value is stored in the local\n namespace, using the name in the "as" clause if it is present,\n otherwise using the attribute name\n\nExamples:\n\n import foo # foo imported and bound locally\n import foo.bar.baz # foo.bar.baz imported, foo bound locally\n import foo.bar.baz as fbb # foo.bar.baz imported and bound as fbb\n from foo.bar import baz # foo.bar.baz imported and bound as baz\n from foo import attr # foo imported and foo.attr bound as attr\n\nIf the list of identifiers is replaced by a star ("\'*\'"), all public\nnames defined in the module are bound in the local namespace for the\nscope where the "import" statement occurs.\n\nThe *public names* defined by a module are determined by checking the\nmodule\'s namespace for a variable named "__all__"; if defined, it must\nbe a sequence of strings which are names defined or imported by that\nmodule. The names given in "__all__" are all considered public and\nare required to exist. If "__all__" is not defined, the set of public\nnames includes all names found in the module\'s namespace which do not\nbegin with an underscore character ("\'_\'"). "__all__" should contain\nthe entire public API. It is intended to avoid accidentally exporting\nitems that are not part of the API (such as library modules which were\nimported and used within the module).\n\nThe wild card form of import --- "from module import *" --- is only\nallowed at the module level. Attempting to use it in class or\nfunction definitions will raise a "SyntaxError".\n\nWhen specifying what module to import you do not have to specify the\nabsolute name of the module. When a module or package is contained\nwithin another package it is possible to make a relative import within\nthe same top package without having to mention the package name. By\nusing leading dots in the specified module or package after "from" you\ncan specify how high to traverse up the current package hierarchy\nwithout specifying exact names. One leading dot means the current\npackage where the module making the import exists. Two dots means up\none package level. Three dots is up two levels, etc. So if you execute\n"from . import mod" from a module in the "pkg" package then you will\nend up importing "pkg.mod". If you execute "from ..subpkg2 import mod"\nfrom within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\nspecification for relative imports is contained within **PEP 328**.\n\n"importlib.import_module()" is provided to support applications that\ndetermine dynamically the modules to be loaded.\n\n\nFuture statements\n=================\n\nA *future statement* is a directive to the compiler that a particular\nmodule should be compiled using syntax or semantics that will be\navailable in a specified future release of Python where the feature\nbecomes standard.\n\nThe future statement is intended to ease migration to future versions\nof Python that introduce incompatible changes to the language. It\nallows use of the new features on a per-module basis before the\nrelease in which the feature becomes standard.\n\n future_statement ::= "from" "__future__" "import" feature ["as" name]\n ("," feature ["as" name])*\n | "from" "__future__" "import" "(" feature ["as" name]\n ("," feature ["as" name])* [","] ")"\n feature ::= identifier\n name ::= identifier\n\nA future statement must appear near the top of the module. The only\nlines that can appear before a future statement are:\n\n* the module docstring (if any),\n\n* comments,\n\n* blank lines, and\n\n* other future statements.\n\nThe features recognized by Python 3.0 are "absolute_import",\n"division", "generators", "unicode_literals", "print_function",\n"nested_scopes" and "with_statement". They are all redundant because\nthey are always enabled, and only kept for backwards compatibility.\n\nA future statement is recognized and treated specially at compile\ntime: Changes to the semantics of core constructs are often\nimplemented by generating different code. It may even be the case\nthat a new feature introduces new incompatible syntax (such as a new\nreserved word), in which case the compiler may need to parse the\nmodule differently. Such decisions cannot be pushed off until\nruntime.\n\nFor any given release, the compiler knows which feature names have\nbeen defined, and raises a compile-time error if a future statement\ncontains a feature not known to it.\n\nThe direct runtime semantics are the same as for any import statement:\nthere is a standard module "__future__", described later, and it will\nbe imported in the usual way at the time the future statement is\nexecuted.\n\nThe interesting runtime semantics depend on the specific feature\nenabled by the future statement.\n\nNote that there is nothing special about the statement:\n\n import __future__ [as name]\n\nThat is not a future statement; it\'s an ordinary import statement with\nno special semantics or syntax restrictions.\n\nCode compiled by calls to the built-in functions "exec()" and\n"compile()" that occur in a module "M" containing a future statement\nwill, by default, use the new syntax or semantics associated with the\nfuture statement. This can be controlled by optional arguments to\n"compile()" --- see the documentation of that function for details.\n\nA future statement typed at an interactive interpreter prompt will\ntake effect for the rest of the interpreter session. If an\ninterpreter is started with the *-i* option, is passed a script name\nto execute, and the script includes a future statement, it will be in\neffect in the interactive session started after the script is\nexecuted.\n\nSee also: **PEP 236** - Back to the __future__\n\n The original proposal for the __future__ mechanism.\n', - 'in': u'\nMembership test operations\n**************************\n\nThe operators "in" and "not in" test for membership. "x in s"\nevaluates to true if *x* is a member of *s*, and false otherwise. "x\nnot in s" returns the negation of "x in s". All built-in sequences\nand set types support this as well as dictionary, for which "in" tests\nwhether the dictionary has a given key. For container types such as\nlist, tuple, set, frozenset, dict, or collections.deque, the\nexpression "x in y" is equivalent to "any(x is e or x == e for e in\ny)".\n\nFor the string and bytes types, "x in y" is true if and only if *x* is\na substring of *y*. An equivalent test is "y.find(x) != -1". Empty\nstrings are always considered to be a substring of any other string,\nso """ in "abc"" will return "True".\n\nFor user-defined classes which define the "__contains__()" method, "x\nin y" is true if and only if "y.__contains__(x)" is true.\n\nFor user-defined classes which do not define "__contains__()" but do\ndefine "__iter__()", "x in y" is true if some value "z" with "x == z"\nis produced while iterating over "y". If an exception is raised\nduring the iteration, it is as if "in" raised that exception.\n\nLastly, the old-style iteration protocol is tried: if a class defines\n"__getitem__()", "x in y" is true if and only if there is a non-\nnegative integer index *i* such that "x == y[i]", and all lower\ninteger indices do not raise "IndexError" exception. (If any other\nexception is raised, it is as if "in" raised that exception).\n\nThe operator "not in" is defined to have the inverse true value of\n"in".\n', - 'integers': u'\nInteger literals\n****************\n\nInteger literals are described by the following lexical definitions:\n\n integer ::= decimalinteger | octinteger | hexinteger | bininteger\n decimalinteger ::= nonzerodigit digit* | "0"+\n nonzerodigit ::= "1"..."9"\n digit ::= "0"..."9"\n octinteger ::= "0" ("o" | "O") octdigit+\n hexinteger ::= "0" ("x" | "X") hexdigit+\n bininteger ::= "0" ("b" | "B") bindigit+\n octdigit ::= "0"..."7"\n hexdigit ::= digit | "a"..."f" | "A"..."F"\n bindigit ::= "0" | "1"\n\nThere is no limit for the length of integer literals apart from what\ncan be stored in available memory.\n\nNote that leading zeros in a non-zero decimal number are not allowed.\nThis is for disambiguation with C-style octal literals, which Python\nused before version 3.0.\n\nSome examples of integer literals:\n\n 7 2147483647 0o177 0b100110111\n 3 79228162514264337593543950336 0o377 0xdeadbeef\n', - 'lambda': u'\nLambdas\n*******\n\n lambda_expr ::= "lambda" [parameter_list]: expression\n lambda_expr_nocond ::= "lambda" [parameter_list]: expression_nocond\n\nLambda expressions (sometimes called lambda forms) are used to create\nanonymous functions. The expression "lambda arguments: expression"\nyields a function object. The unnamed object behaves like a function\nobject defined with\n\n def (arguments):\n return expression\n\nSee section *Function definitions* for the syntax of parameter lists.\nNote that functions created with lambda expressions cannot contain\nstatements or annotations.\n', - 'lists': u'\nList displays\n*************\n\nA list display is a possibly empty series of expressions enclosed in\nsquare brackets:\n\n list_display ::= "[" [expression_list | comprehension] "]"\n\nA list display yields a new list object, the contents being specified\nby either a list of expressions or a comprehension. When a comma-\nseparated list of expressions is supplied, its elements are evaluated\nfrom left to right and placed into the list object in that order.\nWhen a comprehension is supplied, the list is constructed from the\nelements resulting from the comprehension.\n', - 'naming': u'\nNaming and binding\n******************\n\n\nBinding of names\n================\n\n*Names* refer to objects. Names are introduced by name binding\noperations.\n\nThe following constructs bind names: formal parameters to functions,\n"import" statements, class and function definitions (these bind the\nclass or function name in the defining block), and targets that are\nidentifiers if occurring in an assignment, "for" loop header, or after\n"as" in a "with" statement or "except" clause. The "import" statement\nof the form "from ... import *" binds all names defined in the\nimported module, except those beginning with an underscore. This form\nmay only be used at the module level.\n\nA target occurring in a "del" statement is also considered bound for\nthis purpose (though the actual semantics are to unbind the name).\n\nEach assignment or import statement occurs within a block defined by a\nclass or function definition or at the module level (the top-level\ncode block).\n\nIf a name is bound in a block, it is a local variable of that block,\nunless declared as "nonlocal" or "global". If a name is bound at the\nmodule level, it is a global variable. (The variables of the module\ncode block are local and global.) If a variable is used in a code\nblock but not defined there, it is a *free variable*.\n\nEach occurrence of a name in the program text refers to the *binding*\nof that name established by the following name resolution rules.\n\n\nResolution of names\n===================\n\nA *scope* defines the visibility of a name within a block. If a local\nvariable is defined in a block, its scope includes that block. If the\ndefinition occurs in a function block, the scope extends to any blocks\ncontained within the defining one, unless a contained block introduces\na different binding for the name.\n\nWhen a name is used in a code block, it is resolved using the nearest\nenclosing scope. The set of all such scopes visible to a code block\nis called the block\'s *environment*.\n\nWhen a name is not found at all, a "NameError" exception is raised. If\nthe current scope is a function scope, and the name refers to a local\nvariable that has not yet been bound to a value at the point where the\nname is used, an "UnboundLocalError" exception is raised.\n"UnboundLocalError" is a subclass of "NameError".\n\nIf a name binding operation occurs anywhere within a code block, all\nuses of the name within the block are treated as references to the\ncurrent block. This can lead to errors when a name is used within a\nblock before it is bound. This rule is subtle. Python lacks\ndeclarations and allows name binding operations to occur anywhere\nwithin a code block. The local variables of a code block can be\ndetermined by scanning the entire text of the block for name binding\noperations.\n\nIf the "global" statement occurs within a block, all uses of the name\nspecified in the statement refer to the binding of that name in the\ntop-level namespace. Names are resolved in the top-level namespace by\nsearching the global namespace, i.e. the namespace of the module\ncontaining the code block, and the builtins namespace, the namespace\nof the module "builtins". The global namespace is searched first. If\nthe name is not found there, the builtins namespace is searched. The\n"global" statement must precede all uses of the name.\n\nThe "global" statement has the same scope as a name binding operation\nin the same block. If the nearest enclosing scope for a free variable\ncontains a global statement, the free variable is treated as a global.\n\nThe "nonlocal" statement causes corresponding names to refer to\npreviously bound variables in the nearest enclosing function scope.\n"SyntaxError" is raised at compile time if the given name does not\nexist in any enclosing function scope.\n\nThe namespace for a module is automatically created the first time a\nmodule is imported. The main module for a script is always called\n"__main__".\n\nClass definition blocks and arguments to "exec()" and "eval()" are\nspecial in the context of name resolution. A class definition is an\nexecutable statement that may use and define names. These references\nfollow the normal rules for name resolution with an exception that\nunbound local variables are looked up in the global namespace. The\nnamespace of the class definition becomes the attribute dictionary of\nthe class. The scope of names defined in a class block is limited to\nthe class block; it does not extend to the code blocks of methods --\nthis includes comprehensions and generator expressions since they are\nimplemented using a function scope. This means that the following\nwill fail:\n\n class A:\n a = 42\n b = list(a + i for i in range(10))\n\n\nBuiltins and restricted execution\n=================================\n\nThe builtins namespace associated with the execution of a code block\nis actually found by looking up the name "__builtins__" in its global\nnamespace; this should be a dictionary or a module (in the latter case\nthe module\'s dictionary is used). By default, when in the "__main__"\nmodule, "__builtins__" is the built-in module "builtins"; when in any\nother module, "__builtins__" is an alias for the dictionary of the\n"builtins" module itself. "__builtins__" can be set to a user-created\ndictionary to create a weak form of restricted execution.\n\n**CPython implementation detail:** Users should not touch\n"__builtins__"; it is strictly an implementation detail. Users\nwanting to override values in the builtins namespace should "import"\nthe "builtins" module and modify its attributes appropriately.\n\n\nInteraction with dynamic features\n=================================\n\nName resolution of free variables occurs at runtime, not at compile\ntime. This means that the following code will print 42:\n\n i = 10\n def f():\n print(i)\n i = 42\n f()\n\nThere are several cases where Python statements are illegal when used\nin conjunction with nested scopes that contain free variables.\n\nIf a variable is referenced in an enclosing scope, it is illegal to\ndelete the name. An error will be reported at compile time.\n\nThe "eval()" and "exec()" functions do not have access to the full\nenvironment for resolving names. Names may be resolved in the local\nand global namespaces of the caller. Free variables are not resolved\nin the nearest enclosing namespace, but in the global namespace. [1]\nThe "exec()" and "eval()" functions have optional arguments to\noverride the global and local namespace. If only one namespace is\nspecified, it is used for both.\n', - 'nonlocal': u'\nThe "nonlocal" statement\n************************\n\n nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n\nThe "nonlocal" statement causes the listed identifiers to refer to\npreviously bound variables in the nearest enclosing scope excluding\nglobals. This is important because the default behavior for binding is\nto search the local namespace first. The statement allows\nencapsulated code to rebind variables outside of the local scope\nbesides the global (module) scope.\n\nNames listed in a "nonlocal" statement, unlike those listed in a\n"global" statement, must refer to pre-existing bindings in an\nenclosing scope (the scope in which a new binding should be created\ncannot be determined unambiguously).\n\nNames listed in a "nonlocal" statement must not collide with pre-\nexisting bindings in the local scope.\n\nSee also: **PEP 3104** - Access to Names in Outer Scopes\n\n The specification for the "nonlocal" statement.\n', - 'numbers': u'\nNumeric literals\n****************\n\nThere are three types of numeric literals: integers, floating point\nnumbers, and imaginary numbers. There are no complex literals\n(complex numbers can be formed by adding a real number and an\nimaginary number).\n\nNote that numeric literals do not include a sign; a phrase like "-1"\nis actually an expression composed of the unary operator \'"-"\' and the\nliteral "1".\n', - 'numeric-types': u'\nEmulating numeric types\n***********************\n\nThe following methods can be defined to emulate numeric objects.\nMethods corresponding to operations that are not supported by the\nparticular kind of number implemented (e.g., bitwise operations for\nnon-integral numbers) should be left undefined.\n\nobject.__add__(self, other)\nobject.__sub__(self, other)\nobject.__mul__(self, other)\nobject.__truediv__(self, other)\nobject.__floordiv__(self, other)\nobject.__mod__(self, other)\nobject.__divmod__(self, other)\nobject.__pow__(self, other[, modulo])\nobject.__lshift__(self, other)\nobject.__rshift__(self, other)\nobject.__and__(self, other)\nobject.__xor__(self, other)\nobject.__or__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|"). For instance, to evaluate the\n expression "x + y", where *x* is an instance of a class that has an\n "__add__()" method, "x.__add__(y)" is called. The "__divmod__()"\n method should be the equivalent to using "__floordiv__()" and\n "__mod__()"; it should not be related to "__truediv__()". Note\n that "__pow__()" should be defined to accept an optional third\n argument if the ternary version of the built-in "pow()" function is\n to be supported.\n\n If one of those methods does not support the operation with the\n supplied arguments, it should return "NotImplemented".\n\nobject.__radd__(self, other)\nobject.__rsub__(self, other)\nobject.__rmul__(self, other)\nobject.__rtruediv__(self, other)\nobject.__rfloordiv__(self, other)\nobject.__rmod__(self, other)\nobject.__rdivmod__(self, other)\nobject.__rpow__(self, other)\nobject.__rlshift__(self, other)\nobject.__rrshift__(self, other)\nobject.__rand__(self, other)\nobject.__rxor__(self, other)\nobject.__ror__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|") with reflected (swapped) operands.\n These functions are only called if the left operand does not\n support the corresponding operation and the operands are of\n different types. [2] For instance, to evaluate the expression "x -\n y", where *y* is an instance of a class that has an "__rsub__()"\n method, "y.__rsub__(x)" is called if "x.__sub__(y)" returns\n *NotImplemented*.\n\n Note that ternary "pow()" will not try calling "__rpow__()" (the\n coercion rules would become too complicated).\n\n Note: If the right operand\'s type is a subclass of the left\n operand\'s type and that subclass provides the reflected method\n for the operation, this method will be called before the left\n operand\'s non-reflected method. This behavior allows subclasses\n to override their ancestors\' operations.\n\nobject.__iadd__(self, other)\nobject.__isub__(self, other)\nobject.__imul__(self, other)\nobject.__itruediv__(self, other)\nobject.__ifloordiv__(self, other)\nobject.__imod__(self, other)\nobject.__ipow__(self, other[, modulo])\nobject.__ilshift__(self, other)\nobject.__irshift__(self, other)\nobject.__iand__(self, other)\nobject.__ixor__(self, other)\nobject.__ior__(self, other)\n\n These methods are called to implement the augmented arithmetic\n assignments ("+=", "-=", "*=", "/=", "//=", "%=", "**=", "<<=",\n ">>=", "&=", "^=", "|="). These methods should attempt to do the\n operation in-place (modifying *self*) and return the result (which\n could be, but does not have to be, *self*). If a specific method\n is not defined, the augmented assignment falls back to the normal\n methods. For instance, if *x* is an instance of a class with an\n "__iadd__()" method, "x += y" is equivalent to "x = x.__iadd__(y)"\n . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are considered, as\n with the evaluation of "x + y". In certain situations, augmented\n assignment can result in unexpected errors (see *Why does\n a_tuple[i] += [\'item\'] raise an exception when the addition\n works?*), but this behavior is in fact part of the data model.\n\nobject.__neg__(self)\nobject.__pos__(self)\nobject.__abs__(self)\nobject.__invert__(self)\n\n Called to implement the unary arithmetic operations ("-", "+",\n "abs()" and "~").\n\nobject.__complex__(self)\nobject.__int__(self)\nobject.__float__(self)\nobject.__round__(self[, n])\n\n Called to implement the built-in functions "complex()", "int()",\n "float()" and "round()". Should return a value of the appropriate\n type.\n\nobject.__index__(self)\n\n Called to implement "operator.index()", and whenever Python needs\n to losslessly convert the numeric object to an integer object (such\n as in slicing, or in the built-in "bin()", "hex()" and "oct()"\n functions). Presence of this method indicates that the numeric\n object is an integer type. Must return an integer.\n\n Note: In order to have a coherent integer type class, when\n "__index__()" is defined "__int__()" should also be defined, and\n both should return the same value.\n', - 'objects': u'\nObjects, values and types\n*************************\n\n*Objects* are Python\'s abstraction for data. All data in a Python\nprogram is represented by objects or by relations between objects. (In\na sense, and in conformance to Von Neumann\'s model of a "stored\nprogram computer," code is also represented by objects.)\n\nEvery object has an identity, a type and a value. An object\'s\n*identity* never changes once it has been created; you may think of it\nas the object\'s address in memory. The \'"is"\' operator compares the\nidentity of two objects; the "id()" function returns an integer\nrepresenting its identity.\n\n**CPython implementation detail:** For CPython, "id(x)" is the memory\naddress where "x" is stored.\n\nAn object\'s type determines the operations that the object supports\n(e.g., "does it have a length?") and also defines the possible values\nfor objects of that type. The "type()" function returns an object\'s\ntype (which is an object itself). Like its identity, an object\'s\n*type* is also unchangeable. [1]\n\nThe *value* of some objects can change. Objects whose value can\nchange are said to be *mutable*; objects whose value is unchangeable\nonce they are created are called *immutable*. (The value of an\nimmutable container object that contains a reference to a mutable\nobject can change when the latter\'s value is changed; however the\ncontainer is still considered immutable, because the collection of\nobjects it contains cannot be changed. So, immutability is not\nstrictly the same as having an unchangeable value, it is more subtle.)\nAn object\'s mutability is determined by its type; for instance,\nnumbers, strings and tuples are immutable, while dictionaries and\nlists are mutable.\n\nObjects are never explicitly destroyed; however, when they become\nunreachable they may be garbage-collected. An implementation is\nallowed to postpone garbage collection or omit it altogether --- it is\na matter of implementation quality how garbage collection is\nimplemented, as long as no objects are collected that are still\nreachable.\n\n**CPython implementation detail:** CPython currently uses a reference-\ncounting scheme with (optional) delayed detection of cyclically linked\ngarbage, which collects most objects as soon as they become\nunreachable, but is not guaranteed to collect garbage containing\ncircular references. See the documentation of the "gc" module for\ninformation on controlling the collection of cyclic garbage. Other\nimplementations act differently and CPython may change. Do not depend\non immediate finalization of objects when they become unreachable (so\nyou should always close files explicitly).\n\nNote that the use of the implementation\'s tracing or debugging\nfacilities may keep objects alive that would normally be collectable.\nAlso note that catching an exception with a \'"try"..."except"\'\nstatement may keep objects alive.\n\nSome objects contain references to "external" resources such as open\nfiles or windows. It is understood that these resources are freed\nwhen the object is garbage-collected, but since garbage collection is\nnot guaranteed to happen, such objects also provide an explicit way to\nrelease the external resource, usually a "close()" method. Programs\nare strongly recommended to explicitly close such objects. The\n\'"try"..."finally"\' statement and the \'"with"\' statement provide\nconvenient ways to do this.\n\nSome objects contain references to other objects; these are called\n*containers*. Examples of containers are tuples, lists and\ndictionaries. The references are part of a container\'s value. In\nmost cases, when we talk about the value of a container, we imply the\nvalues, not the identities of the contained objects; however, when we\ntalk about the mutability of a container, only the identities of the\nimmediately contained objects are implied. So, if an immutable\ncontainer (like a tuple) contains a reference to a mutable object, its\nvalue changes if that mutable object is changed.\n\nTypes affect almost all aspects of object behavior. Even the\nimportance of object identity is affected in some sense: for immutable\ntypes, operations that compute new values may actually return a\nreference to any existing object with the same type and value, while\nfor mutable objects this is not allowed. E.g., after "a = 1; b = 1",\n"a" and "b" may or may not refer to the same object with the value\none, depending on the implementation, but after "c = []; d = []", "c"\nand "d" are guaranteed to refer to two different, unique, newly\ncreated empty lists. (Note that "c = d = []" assigns the same object\nto both "c" and "d".)\n', - 'operator-summary': u'\nOperator precedence\n*******************\n\nThe following table summarizes the operator precedence in Python, from\nlowest precedence (least binding) to highest precedence (most\nbinding). Operators in the same box have the same precedence. Unless\nthe syntax is explicitly given, operators are binary. Operators in\nthe same box group left to right (except for exponentiation, which\ngroups from right to left).\n\nNote that comparisons, membership tests, and identity tests, all have\nthe same precedence and have a left-to-right chaining feature as\ndescribed in the *Comparisons* section.\n\n+-------------------------------------------------+---------------------------------------+\n| Operator | Description |\n+=================================================+=======================================+\n| "lambda" | Lambda expression |\n+-------------------------------------------------+---------------------------------------+\n| "if" -- "else" | Conditional expression |\n+-------------------------------------------------+---------------------------------------+\n| "or" | Boolean OR |\n+-------------------------------------------------+---------------------------------------+\n| "and" | Boolean AND |\n+-------------------------------------------------+---------------------------------------+\n| "not" "x" | Boolean NOT |\n+-------------------------------------------------+---------------------------------------+\n| "in", "not in", "is", "is not", "<", "<=", ">", | Comparisons, including membership |\n| ">=", "!=", "==" | tests and identity tests |\n+-------------------------------------------------+---------------------------------------+\n| "|" | Bitwise OR |\n+-------------------------------------------------+---------------------------------------+\n| "^" | Bitwise XOR |\n+-------------------------------------------------+---------------------------------------+\n| "&" | Bitwise AND |\n+-------------------------------------------------+---------------------------------------+\n| "<<", ">>" | Shifts |\n+-------------------------------------------------+---------------------------------------+\n| "+", "-" | Addition and subtraction |\n+-------------------------------------------------+---------------------------------------+\n| "*", "/", "//", "%" | Multiplication, division, remainder |\n| | [5] |\n+-------------------------------------------------+---------------------------------------+\n| "+x", "-x", "~x" | Positive, negative, bitwise NOT |\n+-------------------------------------------------+---------------------------------------+\n| "**" | Exponentiation [6] |\n+-------------------------------------------------+---------------------------------------+\n| "x[index]", "x[index:index]", | Subscription, slicing, call, |\n| "x(arguments...)", "x.attribute" | attribute reference |\n+-------------------------------------------------+---------------------------------------+\n| "(expressions...)", "[expressions...]", "{key: | Binding or tuple display, list |\n| value...}", "{expressions...}" | display, dictionary display, set |\n| | display |\n+-------------------------------------------------+---------------------------------------+\n\n-[ Footnotes ]-\n\n[1] While "abs(x%y) < abs(y)" is true mathematically, for floats\n it may not be true numerically due to roundoff. For example, and\n assuming a platform on which a Python float is an IEEE 754 double-\n precision number, in order that "-1e-100 % 1e100" have the same\n sign as "1e100", the computed result is "-1e-100 + 1e100", which\n is numerically exactly equal to "1e100". The function\n "math.fmod()" returns a result whose sign matches the sign of the\n first argument instead, and so returns "-1e-100" in this case.\n Which approach is more appropriate depends on the application.\n\n[2] If x is very close to an exact integer multiple of y, it\'s\n possible for "x//y" to be one larger than "(x-x%y)//y" due to\n rounding. In such cases, Python returns the latter result, in\n order to preserve that "divmod(x,y)[0] * y + x % y" be very close\n to "x".\n\n[3] The Unicode standard distinguishes between *code points* (e.g.\n U+0041) and *abstract characters* (e.g. "LATIN CAPITAL LETTER A").\n While most abstract characters in Unicode are only represented\n using one code point, there is a number of abstract characters\n that can in addition be represented using a sequence of more than\n one code point. For example, the abstract character "LATIN\n CAPITAL LETTER C WITH CEDILLA" can be represented as a single\n *precomposed character* at code position U+00C7, or as a sequence\n of a *base character* at code position U+0043 (LATIN CAPITAL\n LETTER C), followed by a *combining character* at code position\n U+0327 (COMBINING CEDILLA).\n\n The comparison operators on strings compare at the level of\n Unicode code points. This may be counter-intuitive to humans. For\n example, ""\\u00C7" == "\\u0043\\u0327"" is "False", even though both\n strings represent the same abstract character "LATIN CAPITAL\n LETTER C WITH CEDILLA".\n\n To compare strings at the level of abstract characters (that is,\n in a way intuitive to humans), use "unicodedata.normalize()".\n\n[4] Due to automatic garbage-collection, free lists, and the\n dynamic nature of descriptors, you may notice seemingly unusual\n behaviour in certain uses of the "is" operator, like those\n involving comparisons between instance methods, or constants.\n Check their documentation for more info.\n\n[5] The "%" operator is also used for string formatting; the same\n precedence applies.\n\n[6] The power operator "**" binds less tightly than an arithmetic\n or bitwise unary operator on its right, that is, "2**-1" is "0.5".\n', - 'pass': u'\nThe "pass" statement\n********************\n\n pass_stmt ::= "pass"\n\n"pass" is a null operation --- when it is executed, nothing happens.\nIt is useful as a placeholder when a statement is required\nsyntactically, but no code needs to be executed, for example:\n\n def f(arg): pass # a function that does nothing (yet)\n\n class C: pass # a class with no methods (yet)\n', - 'power': u'\nThe power operator\n******************\n\nThe power operator binds more tightly than unary operators on its\nleft; it binds less tightly than unary operators on its right. The\nsyntax is:\n\n power ::= primary ["**" u_expr]\n\nThus, in an unparenthesized sequence of power and unary operators, the\noperators are evaluated from right to left (this does not constrain\nthe evaluation order for the operands): "-1**2" results in "-1".\n\nThe power operator has the same semantics as the built-in "pow()"\nfunction, when called with two arguments: it yields its left argument\nraised to the power of its right argument. The numeric arguments are\nfirst converted to a common type, and the result is of that type.\n\nFor int operands, the result has the same type as the operands unless\nthe second argument is negative; in that case, all arguments are\nconverted to float and a float result is delivered. For example,\n"10**2" returns "100", but "10**-2" returns "0.01".\n\nRaising "0.0" to a negative power results in a "ZeroDivisionError".\nRaising a negative number to a fractional power results in a "complex"\nnumber. (In earlier versions it raised a "ValueError".)\n', - 'raise': u'\nThe "raise" statement\n*********************\n\n raise_stmt ::= "raise" [expression ["from" expression]]\n\nIf no expressions are present, "raise" re-raises the last exception\nthat was active in the current scope. If no exception is active in\nthe current scope, a "RuntimeError" exception is raised indicating\nthat this is an error.\n\nOtherwise, "raise" evaluates the first expression as the exception\nobject. It must be either a subclass or an instance of\n"BaseException". If it is a class, the exception instance will be\nobtained when needed by instantiating the class with no arguments.\n\nThe *type* of the exception is the exception instance\'s class, the\n*value* is the instance itself.\n\nA traceback object is normally created automatically when an exception\nis raised and attached to it as the "__traceback__" attribute, which\nis writable. You can create an exception and set your own traceback in\none step using the "with_traceback()" exception method (which returns\nthe same exception instance, with its traceback set to its argument),\nlike so:\n\n raise Exception("foo occurred").with_traceback(tracebackobj)\n\nThe "from" clause is used for exception chaining: if given, the second\n*expression* must be another exception class or instance, which will\nthen be attached to the raised exception as the "__cause__" attribute\n(which is writable). If the raised exception is not handled, both\nexceptions will be printed:\n\n >>> try:\n ... print(1 / 0)\n ... except Exception as exc:\n ... raise RuntimeError("Something bad happened") from exc\n ...\n Traceback (most recent call last):\n File "", line 2, in \n ZeroDivisionError: int division or modulo by zero\n\n The above exception was the direct cause of the following exception:\n\n Traceback (most recent call last):\n File "", line 4, in \n RuntimeError: Something bad happened\n\nA similar mechanism works implicitly if an exception is raised inside\nan exception handler or a "finally" clause: the previous exception is\nthen attached as the new exception\'s "__context__" attribute:\n\n >>> try:\n ... print(1 / 0)\n ... except:\n ... raise RuntimeError("Something bad happened")\n ...\n Traceback (most recent call last):\n File "", line 2, in \n ZeroDivisionError: int division or modulo by zero\n\n During handling of the above exception, another exception occurred:\n\n Traceback (most recent call last):\n File "", line 4, in \n RuntimeError: Something bad happened\n\nAdditional information on exceptions can be found in section\n*Exceptions*, and information about handling exceptions is in section\n*The try statement*.\n', - 'return': u'\nThe "return" statement\n**********************\n\n return_stmt ::= "return" [expression_list]\n\n"return" may only occur syntactically nested in a function definition,\nnot within a nested class definition.\n\nIf an expression list is present, it is evaluated, else "None" is\nsubstituted.\n\n"return" leaves the current function call with the expression list (or\n"None") as return value.\n\nWhen "return" passes control out of a "try" statement with a "finally"\nclause, that "finally" clause is executed before really leaving the\nfunction.\n\nIn a generator function, the "return" statement indicates that the\ngenerator is done and will cause "StopIteration" to be raised. The\nreturned value (if any) is used as an argument to construct\n"StopIteration" and becomes the "StopIteration.value" attribute.\n', - 'sequence-types': u'\nEmulating container types\n*************************\n\nThe following methods can be defined to implement container objects.\nContainers usually are sequences (such as lists or tuples) or mappings\n(like dictionaries), but can represent other containers as well. The\nfirst set of methods is used either to emulate a sequence or to\nemulate a mapping; the difference is that for a sequence, the\nallowable keys should be the integers *k* for which "0 <= k < N" where\n*N* is the length of the sequence, or slice objects, which define a\nrange of items. It is also recommended that mappings provide the\nmethods "keys()", "values()", "items()", "get()", "clear()",\n"setdefault()", "pop()", "popitem()", "copy()", and "update()"\nbehaving similar to those for Python\'s standard dictionary objects.\nThe "collections" module provides a "MutableMapping" abstract base\nclass to help create those methods from a base set of "__getitem__()",\n"__setitem__()", "__delitem__()", and "keys()". Mutable sequences\nshould provide methods "append()", "count()", "index()", "extend()",\n"insert()", "pop()", "remove()", "reverse()" and "sort()", like Python\nstandard list objects. Finally, sequence types should implement\naddition (meaning concatenation) and multiplication (meaning\nrepetition) by defining the methods "__add__()", "__radd__()",\n"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" described\nbelow; they should not define other numerical operators. It is\nrecommended that both mappings and sequences implement the\n"__contains__()" method to allow efficient use of the "in" operator;\nfor mappings, "in" should search the mapping\'s keys; for sequences, it\nshould search through the values. It is further recommended that both\nmappings and sequences implement the "__iter__()" method to allow\nefficient iteration through the container; for mappings, "__iter__()"\nshould be the same as "keys()"; for sequences, it should iterate\nthrough the values.\n\nobject.__len__(self)\n\n Called to implement the built-in function "len()". Should return\n the length of the object, an integer ">=" 0. Also, an object that\n doesn\'t define a "__bool__()" method and whose "__len__()" method\n returns zero is considered to be false in a Boolean context.\n\nobject.__length_hint__(self)\n\n Called to implement "operator.length_hint()". Should return an\n estimated length for the object (which may be greater or less than\n the actual length). The length must be an integer ">=" 0. This\n method is purely an optimization and is never required for\n correctness.\n\n New in version 3.4.\n\nNote: Slicing is done exclusively with the following three methods.\n A call like\n\n a[1:2] = b\n\n is translated to\n\n a[slice(1, 2, None)] = b\n\n and so forth. Missing slice items are always filled in with "None".\n\nobject.__getitem__(self, key)\n\n Called to implement evaluation of "self[key]". For sequence types,\n the accepted keys should be integers and slice objects. Note that\n the special interpretation of negative indexes (if the class wishes\n to emulate a sequence type) is up to the "__getitem__()" method. If\n *key* is of an inappropriate type, "TypeError" may be raised; if of\n a value outside the set of indexes for the sequence (after any\n special interpretation of negative values), "IndexError" should be\n raised. For mapping types, if *key* is missing (not in the\n container), "KeyError" should be raised.\n\n Note: "for" loops expect that an "IndexError" will be raised for\n illegal indexes to allow proper detection of the end of the\n sequence.\n\nobject.__missing__(self, key)\n\n Called by "dict"."__getitem__()" to implement "self[key]" for dict\n subclasses when key is not in the dictionary.\n\nobject.__setitem__(self, key, value)\n\n Called to implement assignment to "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support changes to the values for keys, or if new keys\n can be added, or for sequences if elements can be replaced. The\n same exceptions should be raised for improper *key* values as for\n the "__getitem__()" method.\n\nobject.__delitem__(self, key)\n\n Called to implement deletion of "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support removal of keys, or for sequences if elements\n can be removed from the sequence. The same exceptions should be\n raised for improper *key* values as for the "__getitem__()" method.\n\nobject.__iter__(self)\n\n This method is called when an iterator is required for a container.\n This method should return a new iterator object that can iterate\n over all the objects in the container. For mappings, it should\n iterate over the keys of the container.\n\n Iterator objects also need to implement this method; they are\n required to return themselves. For more information on iterator\n objects, see *Iterator Types*.\n\nobject.__reversed__(self)\n\n Called (if present) by the "reversed()" built-in to implement\n reverse iteration. It should return a new iterator object that\n iterates over all the objects in the container in reverse order.\n\n If the "__reversed__()" method is not provided, the "reversed()"\n built-in will fall back to using the sequence protocol ("__len__()"\n and "__getitem__()"). Objects that support the sequence protocol\n should only provide "__reversed__()" if they can provide an\n implementation that is more efficient than the one provided by\n "reversed()".\n\nThe membership test operators ("in" and "not in") are normally\nimplemented as an iteration through a sequence. However, container\nobjects can supply the following special method with a more efficient\nimplementation, which also does not require the object be a sequence.\n\nobject.__contains__(self, item)\n\n Called to implement membership test operators. Should return true\n if *item* is in *self*, false otherwise. For mapping objects, this\n should consider the keys of the mapping rather than the values or\n the key-item pairs.\n\n For objects that don\'t define "__contains__()", the membership test\n first tries iteration via "__iter__()", then the old sequence\n iteration protocol via "__getitem__()", see *this section in the\n language reference*.\n', - 'shifting': u'\nShifting operations\n*******************\n\nThe shifting operations have lower priority than the arithmetic\noperations:\n\n shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n\nThese operators accept integers as arguments. They shift the first\nargument to the left or right by the number of bits given by the\nsecond argument.\n\nA right shift by *n* bits is defined as floor division by "pow(2,n)".\nA left shift by *n* bits is defined as multiplication with "pow(2,n)".\n\nNote: In the current implementation, the right-hand operand is\n required to be at most "sys.maxsize". If the right-hand operand is\n larger than "sys.maxsize" an "OverflowError" exception is raised.\n', - 'slicings': u'\nSlicings\n********\n\nA slicing selects a range of items in a sequence object (e.g., a\nstring, tuple or list). Slicings may be used as expressions or as\ntargets in assignment or "del" statements. The syntax for a slicing:\n\n slicing ::= primary "[" slice_list "]"\n slice_list ::= slice_item ("," slice_item)* [","]\n slice_item ::= expression | proper_slice\n proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" [stride] ]\n lower_bound ::= expression\n upper_bound ::= expression\n stride ::= expression\n\nThere is ambiguity in the formal syntax here: anything that looks like\nan expression list also looks like a slice list, so any subscription\ncan be interpreted as a slicing. Rather than further complicating the\nsyntax, this is disambiguated by defining that in this case the\ninterpretation as a subscription takes priority over the\ninterpretation as a slicing (this is the case if the slice list\ncontains no proper slice).\n\nThe semantics for a slicing are as follows. The primary is indexed\n(using the same "__getitem__()" method as normal subscription) with a\nkey that is constructed from the slice list, as follows. If the slice\nlist contains at least one comma, the key is a tuple containing the\nconversion of the slice items; otherwise, the conversion of the lone\nslice item is the key. The conversion of a slice item that is an\nexpression is that expression. The conversion of a proper slice is a\nslice object (see section *The standard type hierarchy*) whose\n"start", "stop" and "step" attributes are the values of the\nexpressions given as lower bound, upper bound and stride,\nrespectively, substituting "None" for missing expressions.\n', - 'specialattrs': u'\nSpecial Attributes\n******************\n\nThe implementation adds a few special read-only attributes to several\nobject types, where they are relevant. Some of these are not reported\nby the "dir()" built-in function.\n\nobject.__dict__\n\n A dictionary or other mapping object used to store an object\'s\n (writable) attributes.\n\ninstance.__class__\n\n The class to which a class instance belongs.\n\nclass.__bases__\n\n The tuple of base classes of a class object.\n\nclass.__name__\n\n The name of the class or type.\n\nclass.__qualname__\n\n The *qualified name* of the class or type.\n\n New in version 3.3.\n\nclass.__mro__\n\n This attribute is a tuple of classes that are considered when\n looking for base classes during method resolution.\n\nclass.mro()\n\n This method can be overridden by a metaclass to customize the\n method resolution order for its instances. It is called at class\n instantiation, and its result is stored in "__mro__".\n\nclass.__subclasses__()\n\n Each class keeps a list of weak references to its immediate\n subclasses. This method returns a list of all those references\n still alive. Example:\n\n >>> int.__subclasses__()\n []\n\n-[ Footnotes ]-\n\n[1] Additional information on these special methods may be found\n in the Python Reference Manual (*Basic customization*).\n\n[2] As a consequence, the list "[1, 2]" is considered equal to\n "[1.0, 2.0]", and similarly for tuples.\n\n[3] They must have since the parser can\'t tell the type of the\n operands.\n\n[4] Cased characters are those with general category property\n being one of "Lu" (Letter, uppercase), "Ll" (Letter, lowercase),\n or "Lt" (Letter, titlecase).\n\n[5] To format only a tuple you should therefore provide a\n singleton tuple whose only element is the tuple to be formatted.\n', - 'specialnames': u'\nSpecial method names\n********************\n\nA class can implement certain operations that are invoked by special\nsyntax (such as arithmetic operations or subscripting and slicing) by\ndefining methods with special names. This is Python\'s approach to\n*operator overloading*, allowing classes to define their own behavior\nwith respect to language operators. For instance, if a class defines\na method named "__getitem__()", and "x" is an instance of this class,\nthen "x[i]" is roughly equivalent to "type(x).__getitem__(x, i)".\nExcept where mentioned, attempts to execute an operation raise an\nexception when no appropriate method is defined (typically\n"AttributeError" or "TypeError").\n\nWhen implementing a class that emulates any built-in type, it is\nimportant that the emulation only be implemented to the degree that it\nmakes sense for the object being modelled. For example, some\nsequences may work well with retrieval of individual elements, but\nextracting a slice may not make sense. (One example of this is the\n"NodeList" interface in the W3C\'s Document Object Model.)\n\n\nBasic customization\n===================\n\nobject.__new__(cls[, ...])\n\n Called to create a new instance of class *cls*. "__new__()" is a\n static method (special-cased so you need not declare it as such)\n that takes the class of which an instance was requested as its\n first argument. The remaining arguments are those passed to the\n object constructor expression (the call to the class). The return\n value of "__new__()" should be the new object instance (usually an\n instance of *cls*).\n\n Typical implementations create a new instance of the class by\n invoking the superclass\'s "__new__()" method using\n "super(currentclass, cls).__new__(cls[, ...])" with appropriate\n arguments and then modifying the newly-created instance as\n necessary before returning it.\n\n If "__new__()" returns an instance of *cls*, then the new\n instance\'s "__init__()" method will be invoked like\n "__init__(self[, ...])", where *self* is the new instance and the\n remaining arguments are the same as were passed to "__new__()".\n\n If "__new__()" does not return an instance of *cls*, then the new\n instance\'s "__init__()" method will not be invoked.\n\n "__new__()" is intended mainly to allow subclasses of immutable\n types (like int, str, or tuple) to customize instance creation. It\n is also commonly overridden in custom metaclasses in order to\n customize class creation.\n\nobject.__init__(self[, ...])\n\n Called after the instance has been created (by "__new__()"), but\n before it is returned to the caller. The arguments are those\n passed to the class constructor expression. If a base class has an\n "__init__()" method, the derived class\'s "__init__()" method, if\n any, must explicitly call it to ensure proper initialization of the\n base class part of the instance; for example:\n "BaseClass.__init__(self, [args...])".\n\n Because "__new__()" and "__init__()" work together in constructing\n objects ("__new__()" to create it, and "__init__()" to customise\n it), no non-"None" value may be returned by "__init__()"; doing so\n will cause a "TypeError" to be raised at runtime.\n\nobject.__del__(self)\n\n Called when the instance is about to be destroyed. This is also\n called a destructor. If a base class has a "__del__()" method, the\n derived class\'s "__del__()" method, if any, must explicitly call it\n to ensure proper deletion of the base class part of the instance.\n Note that it is possible (though not recommended!) for the\n "__del__()" method to postpone destruction of the instance by\n creating a new reference to it. It may then be called at a later\n time when this new reference is deleted. It is not guaranteed that\n "__del__()" methods are called for objects that still exist when\n the interpreter exits.\n\n Note: "del x" doesn\'t directly call "x.__del__()" --- the former\n decrements the reference count for "x" by one, and the latter is\n only called when "x"\'s reference count reaches zero. Some common\n situations that may prevent the reference count of an object from\n going to zero include: circular references between objects (e.g.,\n a doubly-linked list or a tree data structure with parent and\n child pointers); a reference to the object on the stack frame of\n a function that caught an exception (the traceback stored in\n "sys.exc_info()[2]" keeps the stack frame alive); or a reference\n to the object on the stack frame that raised an unhandled\n exception in interactive mode (the traceback stored in\n "sys.last_traceback" keeps the stack frame alive). The first\n situation can only be remedied by explicitly breaking the cycles;\n the second can be resolved by freeing the reference to the\n traceback object when it is no longer useful, and the third can\n be resolved by storing "None" in "sys.last_traceback". Circular\n references which are garbage are detected and cleaned up when the\n cyclic garbage collector is enabled (it\'s on by default). Refer\n to the documentation for the "gc" module for more information\n about this topic.\n\n Warning: Due to the precarious circumstances under which\n "__del__()" methods are invoked, exceptions that occur during\n their execution are ignored, and a warning is printed to\n "sys.stderr" instead. Also, when "__del__()" is invoked in\n response to a module being deleted (e.g., when execution of the\n program is done), other globals referenced by the "__del__()"\n method may already have been deleted or in the process of being\n torn down (e.g. the import machinery shutting down). For this\n reason, "__del__()" methods should do the absolute minimum needed\n to maintain external invariants. Starting with version 1.5,\n Python guarantees that globals whose name begins with a single\n underscore are deleted from their module before other globals are\n deleted; if no other references to such globals exist, this may\n help in assuring that imported modules are still available at the\n time when the "__del__()" method is called.\n\nobject.__repr__(self)\n\n Called by the "repr()" built-in function to compute the "official"\n string representation of an object. If at all possible, this\n should look like a valid Python expression that could be used to\n recreate an object with the same value (given an appropriate\n environment). If this is not possible, a string of the form\n "<...some useful description...>" should be returned. The return\n value must be a string object. If a class defines "__repr__()" but\n not "__str__()", then "__repr__()" is also used when an "informal"\n string representation of instances of that class is required.\n\n This is typically used for debugging, so it is important that the\n representation is information-rich and unambiguous.\n\nobject.__str__(self)\n\n Called by "str(object)" and the built-in functions "format()" and\n "print()" to compute the "informal" or nicely printable string\n representation of an object. The return value must be a *string*\n object.\n\n This method differs from "object.__repr__()" in that there is no\n expectation that "__str__()" return a valid Python expression: a\n more convenient or concise representation can be used.\n\n The default implementation defined by the built-in type "object"\n calls "object.__repr__()".\n\nobject.__bytes__(self)\n\n Called by "bytes()" to compute a byte-string representation of an\n object. This should return a "bytes" object.\n\nobject.__format__(self, format_spec)\n\n Called by the "format()" built-in function (and by extension, the\n "str.format()" method of class "str") to produce a "formatted"\n string representation of an object. The "format_spec" argument is a\n string that contains a description of the formatting options\n desired. The interpretation of the "format_spec" argument is up to\n the type implementing "__format__()", however most classes will\n either delegate formatting to one of the built-in types, or use a\n similar formatting option syntax.\n\n See *Format Specification Mini-Language* for a description of the\n standard formatting syntax.\n\n The return value must be a string object.\n\n Changed in version 3.4: The __format__ method of "object" itself\n raises a "TypeError" if passed any non-empty string.\n\nobject.__lt__(self, other)\nobject.__le__(self, other)\nobject.__eq__(self, other)\nobject.__ne__(self, other)\nobject.__gt__(self, other)\nobject.__ge__(self, other)\n\n These are the so-called "rich comparison" methods. The\n correspondence between operator symbols and method names is as\n follows: "xy" calls\n "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n\n A rich comparison method may return the singleton "NotImplemented"\n if it does not implement the operation for a given pair of\n arguments. By convention, "False" and "True" are returned for a\n successful comparison. However, these methods can return any value,\n so if the comparison operator is used in a Boolean context (e.g.,\n in the condition of an "if" statement), Python will call "bool()"\n on the value to determine if the result is true or false.\n\n By default, "__ne__()" delegates to "__eq__()" and inverts the\n result unless it is "NotImplemented". There are no other implied\n relationships among the comparison operators, for example, the\n truth of "(x.__hash__".\n\n If a class that does not override "__eq__()" wishes to suppress\n hash support, it should include "__hash__ = None" in the class\n definition. A class which defines its own "__hash__()" that\n explicitly raises a "TypeError" would be incorrectly identified as\n hashable by an "isinstance(obj, collections.Hashable)" call.\n\n Note: By default, the "__hash__()" values of str, bytes and\n datetime objects are "salted" with an unpredictable random value.\n Although they remain constant within an individual Python\n process, they are not predictable between repeated invocations of\n Python.This is intended to provide protection against a denial-\n of-service caused by carefully-chosen inputs that exploit the\n worst case performance of a dict insertion, O(n^2) complexity.\n See http://www.ocert.org/advisories/ocert-2011-003.html for\n details.Changing hash values affects the iteration order of\n dicts, sets and other mappings. Python has never made guarantees\n about this ordering (and it typically varies between 32-bit and\n 64-bit builds).See also "PYTHONHASHSEED".\n\n Changed in version 3.3: Hash randomization is enabled by default.\n\nobject.__bool__(self)\n\n Called to implement truth value testing and the built-in operation\n "bool()"; should return "False" or "True". When this method is not\n defined, "__len__()" is called, if it is defined, and the object is\n considered true if its result is nonzero. If a class defines\n neither "__len__()" nor "__bool__()", all its instances are\n considered true.\n\n\nCustomizing attribute access\n============================\n\nThe following methods can be defined to customize the meaning of\nattribute access (use of, assignment to, or deletion of "x.name") for\nclass instances.\n\nobject.__getattr__(self, name)\n\n Called when an attribute lookup has not found the attribute in the\n usual places (i.e. it is not an instance attribute nor is it found\n in the class tree for "self"). "name" is the attribute name. This\n method should return the (computed) attribute value or raise an\n "AttributeError" exception.\n\n Note that if the attribute is found through the normal mechanism,\n "__getattr__()" is not called. (This is an intentional asymmetry\n between "__getattr__()" and "__setattr__()".) This is done both for\n efficiency reasons and because otherwise "__getattr__()" would have\n no way to access other attributes of the instance. Note that at\n least for instance variables, you can fake total control by not\n inserting any values in the instance attribute dictionary (but\n instead inserting them in another object). See the\n "__getattribute__()" method below for a way to actually get total\n control over attribute access.\n\nobject.__getattribute__(self, name)\n\n Called unconditionally to implement attribute accesses for\n instances of the class. If the class also defines "__getattr__()",\n the latter will not be called unless "__getattribute__()" either\n calls it explicitly or raises an "AttributeError". This method\n should return the (computed) attribute value or raise an\n "AttributeError" exception. In order to avoid infinite recursion in\n this method, its implementation should always call the base class\n method with the same name to access any attributes it needs, for\n example, "object.__getattribute__(self, name)".\n\n Note: This method may still be bypassed when looking up special\n methods as the result of implicit invocation via language syntax\n or built-in functions. See *Special method lookup*.\n\nobject.__setattr__(self, name, value)\n\n Called when an attribute assignment is attempted. This is called\n instead of the normal mechanism (i.e. store the value in the\n instance dictionary). *name* is the attribute name, *value* is the\n value to be assigned to it.\n\n If "__setattr__()" wants to assign to an instance attribute, it\n should call the base class method with the same name, for example,\n "object.__setattr__(self, name, value)".\n\nobject.__delattr__(self, name)\n\n Like "__setattr__()" but for attribute deletion instead of\n assignment. This should only be implemented if "del obj.name" is\n meaningful for the object.\n\nobject.__dir__(self)\n\n Called when "dir()" is called on the object. A sequence must be\n returned. "dir()" converts the returned sequence to a list and\n sorts it.\n\n\nImplementing Descriptors\n------------------------\n\nThe following methods only apply when an instance of the class\ncontaining the method (a so-called *descriptor* class) appears in an\n*owner* class (the descriptor must be in either the owner\'s class\ndictionary or in the class dictionary for one of its parents). In the\nexamples below, "the attribute" refers to the attribute whose name is\nthe key of the property in the owner class\' "__dict__".\n\nobject.__get__(self, instance, owner)\n\n Called to get the attribute of the owner class (class attribute\n access) or of an instance of that class (instance attribute\n access). *owner* is always the owner class, while *instance* is the\n instance that the attribute was accessed through, or "None" when\n the attribute is accessed through the *owner*. This method should\n return the (computed) attribute value or raise an "AttributeError"\n exception.\n\nobject.__set__(self, instance, value)\n\n Called to set the attribute on an instance *instance* of the owner\n class to a new value, *value*.\n\nobject.__delete__(self, instance)\n\n Called to delete the attribute on an instance *instance* of the\n owner class.\n\nThe attribute "__objclass__" is interpreted by the "inspect" module as\nspecifying the class where this object was defined (setting this\nappropriately can assist in runtime introspection of dynamic class\nattributes). For callables, it may indicate that an instance of the\ngiven type (or a subclass) is expected or required as the first\npositional argument (for example, CPython sets this attribute for\nunbound methods that are implemented in C).\n\n\nInvoking Descriptors\n--------------------\n\nIn general, a descriptor is an object attribute with "binding\nbehavior", one whose attribute access has been overridden by methods\nin the descriptor protocol: "__get__()", "__set__()", and\n"__delete__()". If any of those methods are defined for an object, it\nis said to be a descriptor.\n\nThe default behavior for attribute access is to get, set, or delete\nthe attribute from an object\'s dictionary. For instance, "a.x" has a\nlookup chain starting with "a.__dict__[\'x\']", then\n"type(a).__dict__[\'x\']", and continuing through the base classes of\n"type(a)" excluding metaclasses.\n\nHowever, if the looked-up value is an object defining one of the\ndescriptor methods, then Python may override the default behavior and\ninvoke the descriptor method instead. Where this occurs in the\nprecedence chain depends on which descriptor methods were defined and\nhow they were called.\n\nThe starting point for descriptor invocation is a binding, "a.x". How\nthe arguments are assembled depends on "a":\n\nDirect Call\n The simplest and least common call is when user code directly\n invokes a descriptor method: "x.__get__(a)".\n\nInstance Binding\n If binding to an object instance, "a.x" is transformed into the\n call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n\nClass Binding\n If binding to a class, "A.x" is transformed into the call:\n "A.__dict__[\'x\'].__get__(None, A)".\n\nSuper Binding\n If "a" is an instance of "super", then the binding "super(B,\n obj).m()" searches "obj.__class__.__mro__" for the base class "A"\n immediately preceding "B" and then invokes the descriptor with the\n call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n\nFor instance bindings, the precedence of descriptor invocation depends\non the which descriptor methods are defined. A descriptor can define\nany combination of "__get__()", "__set__()" and "__delete__()". If it\ndoes not define "__get__()", then accessing the attribute will return\nthe descriptor object itself unless there is a value in the object\'s\ninstance dictionary. If the descriptor defines "__set__()" and/or\n"__delete__()", it is a data descriptor; if it defines neither, it is\na non-data descriptor. Normally, data descriptors define both\n"__get__()" and "__set__()", while non-data descriptors have just the\n"__get__()" method. Data descriptors with "__set__()" and "__get__()"\ndefined always override a redefinition in an instance dictionary. In\ncontrast, non-data descriptors can be overridden by instances.\n\nPython methods (including "staticmethod()" and "classmethod()") are\nimplemented as non-data descriptors. Accordingly, instances can\nredefine and override methods. This allows individual instances to\nacquire behaviors that differ from other instances of the same class.\n\nThe "property()" function is implemented as a data descriptor.\nAccordingly, instances cannot override the behavior of a property.\n\n\n__slots__\n---------\n\nBy default, instances of classes have a dictionary for attribute\nstorage. This wastes space for objects having very few instance\nvariables. The space consumption can become acute when creating large\nnumbers of instances.\n\nThe default can be overridden by defining *__slots__* in a class\ndefinition. The *__slots__* declaration takes a sequence of instance\nvariables and reserves just enough space in each instance to hold a\nvalue for each variable. Space is saved because *__dict__* is not\ncreated for each instance.\n\nobject.__slots__\n\n This class variable can be assigned a string, iterable, or sequence\n of strings with variable names used by instances. *__slots__*\n reserves space for the declared variables and prevents the\n automatic creation of *__dict__* and *__weakref__* for each\n instance.\n\n\nNotes on using *__slots__*\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* When inheriting from a class without *__slots__*, the *__dict__*\n attribute of that class will always be accessible, so a *__slots__*\n definition in the subclass is meaningless.\n\n* Without a *__dict__* variable, instances cannot be assigned new\n variables not listed in the *__slots__* definition. Attempts to\n assign to an unlisted variable name raises "AttributeError". If\n dynamic assignment of new variables is desired, then add\n "\'__dict__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* Without a *__weakref__* variable for each instance, classes\n defining *__slots__* do not support weak references to its\n instances. If weak reference support is needed, then add\n "\'__weakref__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* *__slots__* are implemented at the class level by creating\n descriptors (*Implementing Descriptors*) for each variable name. As\n a result, class attributes cannot be used to set default values for\n instance variables defined by *__slots__*; otherwise, the class\n attribute would overwrite the descriptor assignment.\n\n* The action of a *__slots__* declaration is limited to the class\n where it is defined. As a result, subclasses will have a *__dict__*\n unless they also define *__slots__* (which must only contain names\n of any *additional* slots).\n\n* If a class defines a slot also defined in a base class, the\n instance variable defined by the base class slot is inaccessible\n (except by retrieving its descriptor directly from the base class).\n This renders the meaning of the program undefined. In the future, a\n check may be added to prevent this.\n\n* Nonempty *__slots__* does not work for classes derived from\n "variable-length" built-in types such as "int", "bytes" and "tuple".\n\n* Any non-string iterable may be assigned to *__slots__*. Mappings\n may also be used; however, in the future, special meaning may be\n assigned to the values corresponding to each key.\n\n* *__class__* assignment works only if both classes have the same\n *__slots__*.\n\n\nCustomizing class creation\n==========================\n\nBy default, classes are constructed using "type()". The class body is\nexecuted in a new namespace and the class name is bound locally to the\nresult of "type(name, bases, namespace)".\n\nThe class creation process can be customised by passing the\n"metaclass" keyword argument in the class definition line, or by\ninheriting from an existing class that included such an argument. In\nthe following example, both "MyClass" and "MySubclass" are instances\nof "Meta":\n\n class Meta(type):\n pass\n\n class MyClass(metaclass=Meta):\n pass\n\n class MySubclass(MyClass):\n pass\n\nAny other keyword arguments that are specified in the class definition\nare passed through to all metaclass operations described below.\n\nWhen a class definition is executed, the following steps occur:\n\n* the appropriate metaclass is determined\n\n* the class namespace is prepared\n\n* the class body is executed\n\n* the class object is created\n\n\nDetermining the appropriate metaclass\n-------------------------------------\n\nThe appropriate metaclass for a class definition is determined as\nfollows:\n\n* if no bases and no explicit metaclass are given, then "type()" is\n used\n\n* if an explicit metaclass is given and it is *not* an instance of\n "type()", then it is used directly as the metaclass\n\n* if an instance of "type()" is given as the explicit metaclass, or\n bases are defined, then the most derived metaclass is used\n\nThe most derived metaclass is selected from the explicitly specified\nmetaclass (if any) and the metaclasses (i.e. "type(cls)") of all\nspecified base classes. The most derived metaclass is one which is a\nsubtype of *all* of these candidate metaclasses. If none of the\ncandidate metaclasses meets that criterion, then the class definition\nwill fail with "TypeError".\n\n\nPreparing the class namespace\n-----------------------------\n\nOnce the appropriate metaclass has been identified, then the class\nnamespace is prepared. If the metaclass has a "__prepare__" attribute,\nit is called as "namespace = metaclass.__prepare__(name, bases,\n**kwds)" (where the additional keyword arguments, if any, come from\nthe class definition).\n\nIf the metaclass has no "__prepare__" attribute, then the class\nnamespace is initialised as an empty "dict()" instance.\n\nSee also: **PEP 3115** - Metaclasses in Python 3000\n\n Introduced the "__prepare__" namespace hook\n\n\nExecuting the class body\n------------------------\n\nThe class body is executed (approximately) as "exec(body, globals(),\nnamespace)". The key difference from a normal call to "exec()" is that\nlexical scoping allows the class body (including any methods) to\nreference names from the current and outer scopes when the class\ndefinition occurs inside a function.\n\nHowever, even when the class definition occurs inside the function,\nmethods defined inside the class still cannot see names defined at the\nclass scope. Class variables must be accessed through the first\nparameter of instance or class methods, and cannot be accessed at all\nfrom static methods.\n\n\nCreating the class object\n-------------------------\n\nOnce the class namespace has been populated by executing the class\nbody, the class object is created by calling "metaclass(name, bases,\nnamespace, **kwds)" (the additional keywords passed here are the same\nas those passed to "__prepare__").\n\nThis class object is the one that will be referenced by the zero-\nargument form of "super()". "__class__" is an implicit closure\nreference created by the compiler if any methods in a class body refer\nto either "__class__" or "super". This allows the zero argument form\nof "super()" to correctly identify the class being defined based on\nlexical scoping, while the class or instance that was used to make the\ncurrent call is identified based on the first argument passed to the\nmethod.\n\nAfter the class object is created, it is passed to the class\ndecorators included in the class definition (if any) and the resulting\nobject is bound in the local namespace as the defined class.\n\nSee also: **PEP 3135** - New super\n\n Describes the implicit "__class__" closure reference\n\n\nMetaclass example\n-----------------\n\nThe potential uses for metaclasses are boundless. Some ideas that have\nbeen explored include logging, interface checking, automatic\ndelegation, automatic property creation, proxies, frameworks, and\nautomatic resource locking/synchronization.\n\nHere is an example of a metaclass that uses an\n"collections.OrderedDict" to remember the order that class variables\nare defined:\n\n class OrderedClass(type):\n\n @classmethod\n def __prepare__(metacls, name, bases, **kwds):\n return collections.OrderedDict()\n\n def __new__(cls, name, bases, namespace, **kwds):\n result = type.__new__(cls, name, bases, dict(namespace))\n result.members = tuple(namespace)\n return result\n\n class A(metaclass=OrderedClass):\n def one(self): pass\n def two(self): pass\n def three(self): pass\n def four(self): pass\n\n >>> A.members\n (\'__module__\', \'one\', \'two\', \'three\', \'four\')\n\nWhen the class definition for *A* gets executed, the process begins\nwith calling the metaclass\'s "__prepare__()" method which returns an\nempty "collections.OrderedDict". That mapping records the methods and\nattributes of *A* as they are defined within the body of the class\nstatement. Once those definitions are executed, the ordered dictionary\nis fully populated and the metaclass\'s "__new__()" method gets\ninvoked. That method builds the new type and it saves the ordered\ndictionary keys in an attribute called "members".\n\n\nCustomizing instance and subclass checks\n========================================\n\nThe following methods are used to override the default behavior of the\n"isinstance()" and "issubclass()" built-in functions.\n\nIn particular, the metaclass "abc.ABCMeta" implements these methods in\norder to allow the addition of Abstract Base Classes (ABCs) as\n"virtual base classes" to any class or type (including built-in\ntypes), including other ABCs.\n\nclass.__instancecheck__(self, instance)\n\n Return true if *instance* should be considered a (direct or\n indirect) instance of *class*. If defined, called to implement\n "isinstance(instance, class)".\n\nclass.__subclasscheck__(self, subclass)\n\n Return true if *subclass* should be considered a (direct or\n indirect) subclass of *class*. If defined, called to implement\n "issubclass(subclass, class)".\n\nNote that these methods are looked up on the type (metaclass) of a\nclass. They cannot be defined as class methods in the actual class.\nThis is consistent with the lookup of special methods that are called\non instances, only in this case the instance is itself a class.\n\nSee also: **PEP 3119** - Introducing Abstract Base Classes\n\n Includes the specification for customizing "isinstance()" and\n "issubclass()" behavior through "__instancecheck__()" and\n "__subclasscheck__()", with motivation for this functionality in\n the context of adding Abstract Base Classes (see the "abc"\n module) to the language.\n\n\nEmulating callable objects\n==========================\n\nobject.__call__(self[, args...])\n\n Called when the instance is "called" as a function; if this method\n is defined, "x(arg1, arg2, ...)" is a shorthand for\n "x.__call__(arg1, arg2, ...)".\n\n\nEmulating container types\n=========================\n\nThe following methods can be defined to implement container objects.\nContainers usually are sequences (such as lists or tuples) or mappings\n(like dictionaries), but can represent other containers as well. The\nfirst set of methods is used either to emulate a sequence or to\nemulate a mapping; the difference is that for a sequence, the\nallowable keys should be the integers *k* for which "0 <= k < N" where\n*N* is the length of the sequence, or slice objects, which define a\nrange of items. It is also recommended that mappings provide the\nmethods "keys()", "values()", "items()", "get()", "clear()",\n"setdefault()", "pop()", "popitem()", "copy()", and "update()"\nbehaving similar to those for Python\'s standard dictionary objects.\nThe "collections" module provides a "MutableMapping" abstract base\nclass to help create those methods from a base set of "__getitem__()",\n"__setitem__()", "__delitem__()", and "keys()". Mutable sequences\nshould provide methods "append()", "count()", "index()", "extend()",\n"insert()", "pop()", "remove()", "reverse()" and "sort()", like Python\nstandard list objects. Finally, sequence types should implement\naddition (meaning concatenation) and multiplication (meaning\nrepetition) by defining the methods "__add__()", "__radd__()",\n"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" described\nbelow; they should not define other numerical operators. It is\nrecommended that both mappings and sequences implement the\n"__contains__()" method to allow efficient use of the "in" operator;\nfor mappings, "in" should search the mapping\'s keys; for sequences, it\nshould search through the values. It is further recommended that both\nmappings and sequences implement the "__iter__()" method to allow\nefficient iteration through the container; for mappings, "__iter__()"\nshould be the same as "keys()"; for sequences, it should iterate\nthrough the values.\n\nobject.__len__(self)\n\n Called to implement the built-in function "len()". Should return\n the length of the object, an integer ">=" 0. Also, an object that\n doesn\'t define a "__bool__()" method and whose "__len__()" method\n returns zero is considered to be false in a Boolean context.\n\nobject.__length_hint__(self)\n\n Called to implement "operator.length_hint()". Should return an\n estimated length for the object (which may be greater or less than\n the actual length). The length must be an integer ">=" 0. This\n method is purely an optimization and is never required for\n correctness.\n\n New in version 3.4.\n\nNote: Slicing is done exclusively with the following three methods.\n A call like\n\n a[1:2] = b\n\n is translated to\n\n a[slice(1, 2, None)] = b\n\n and so forth. Missing slice items are always filled in with "None".\n\nobject.__getitem__(self, key)\n\n Called to implement evaluation of "self[key]". For sequence types,\n the accepted keys should be integers and slice objects. Note that\n the special interpretation of negative indexes (if the class wishes\n to emulate a sequence type) is up to the "__getitem__()" method. If\n *key* is of an inappropriate type, "TypeError" may be raised; if of\n a value outside the set of indexes for the sequence (after any\n special interpretation of negative values), "IndexError" should be\n raised. For mapping types, if *key* is missing (not in the\n container), "KeyError" should be raised.\n\n Note: "for" loops expect that an "IndexError" will be raised for\n illegal indexes to allow proper detection of the end of the\n sequence.\n\nobject.__missing__(self, key)\n\n Called by "dict"."__getitem__()" to implement "self[key]" for dict\n subclasses when key is not in the dictionary.\n\nobject.__setitem__(self, key, value)\n\n Called to implement assignment to "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support changes to the values for keys, or if new keys\n can be added, or for sequences if elements can be replaced. The\n same exceptions should be raised for improper *key* values as for\n the "__getitem__()" method.\n\nobject.__delitem__(self, key)\n\n Called to implement deletion of "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support removal of keys, or for sequences if elements\n can be removed from the sequence. The same exceptions should be\n raised for improper *key* values as for the "__getitem__()" method.\n\nobject.__iter__(self)\n\n This method is called when an iterator is required for a container.\n This method should return a new iterator object that can iterate\n over all the objects in the container. For mappings, it should\n iterate over the keys of the container.\n\n Iterator objects also need to implement this method; they are\n required to return themselves. For more information on iterator\n objects, see *Iterator Types*.\n\nobject.__reversed__(self)\n\n Called (if present) by the "reversed()" built-in to implement\n reverse iteration. It should return a new iterator object that\n iterates over all the objects in the container in reverse order.\n\n If the "__reversed__()" method is not provided, the "reversed()"\n built-in will fall back to using the sequence protocol ("__len__()"\n and "__getitem__()"). Objects that support the sequence protocol\n should only provide "__reversed__()" if they can provide an\n implementation that is more efficient than the one provided by\n "reversed()".\n\nThe membership test operators ("in" and "not in") are normally\nimplemented as an iteration through a sequence. However, container\nobjects can supply the following special method with a more efficient\nimplementation, which also does not require the object be a sequence.\n\nobject.__contains__(self, item)\n\n Called to implement membership test operators. Should return true\n if *item* is in *self*, false otherwise. For mapping objects, this\n should consider the keys of the mapping rather than the values or\n the key-item pairs.\n\n For objects that don\'t define "__contains__()", the membership test\n first tries iteration via "__iter__()", then the old sequence\n iteration protocol via "__getitem__()", see *this section in the\n language reference*.\n\n\nEmulating numeric types\n=======================\n\nThe following methods can be defined to emulate numeric objects.\nMethods corresponding to operations that are not supported by the\nparticular kind of number implemented (e.g., bitwise operations for\nnon-integral numbers) should be left undefined.\n\nobject.__add__(self, other)\nobject.__sub__(self, other)\nobject.__mul__(self, other)\nobject.__truediv__(self, other)\nobject.__floordiv__(self, other)\nobject.__mod__(self, other)\nobject.__divmod__(self, other)\nobject.__pow__(self, other[, modulo])\nobject.__lshift__(self, other)\nobject.__rshift__(self, other)\nobject.__and__(self, other)\nobject.__xor__(self, other)\nobject.__or__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|"). For instance, to evaluate the\n expression "x + y", where *x* is an instance of a class that has an\n "__add__()" method, "x.__add__(y)" is called. The "__divmod__()"\n method should be the equivalent to using "__floordiv__()" and\n "__mod__()"; it should not be related to "__truediv__()". Note\n that "__pow__()" should be defined to accept an optional third\n argument if the ternary version of the built-in "pow()" function is\n to be supported.\n\n If one of those methods does not support the operation with the\n supplied arguments, it should return "NotImplemented".\n\nobject.__radd__(self, other)\nobject.__rsub__(self, other)\nobject.__rmul__(self, other)\nobject.__rtruediv__(self, other)\nobject.__rfloordiv__(self, other)\nobject.__rmod__(self, other)\nobject.__rdivmod__(self, other)\nobject.__rpow__(self, other)\nobject.__rlshift__(self, other)\nobject.__rrshift__(self, other)\nobject.__rand__(self, other)\nobject.__rxor__(self, other)\nobject.__ror__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|") with reflected (swapped) operands.\n These functions are only called if the left operand does not\n support the corresponding operation and the operands are of\n different types. [2] For instance, to evaluate the expression "x -\n y", where *y* is an instance of a class that has an "__rsub__()"\n method, "y.__rsub__(x)" is called if "x.__sub__(y)" returns\n *NotImplemented*.\n\n Note that ternary "pow()" will not try calling "__rpow__()" (the\n coercion rules would become too complicated).\n\n Note: If the right operand\'s type is a subclass of the left\n operand\'s type and that subclass provides the reflected method\n for the operation, this method will be called before the left\n operand\'s non-reflected method. This behavior allows subclasses\n to override their ancestors\' operations.\n\nobject.__iadd__(self, other)\nobject.__isub__(self, other)\nobject.__imul__(self, other)\nobject.__itruediv__(self, other)\nobject.__ifloordiv__(self, other)\nobject.__imod__(self, other)\nobject.__ipow__(self, other[, modulo])\nobject.__ilshift__(self, other)\nobject.__irshift__(self, other)\nobject.__iand__(self, other)\nobject.__ixor__(self, other)\nobject.__ior__(self, other)\n\n These methods are called to implement the augmented arithmetic\n assignments ("+=", "-=", "*=", "/=", "//=", "%=", "**=", "<<=",\n ">>=", "&=", "^=", "|="). These methods should attempt to do the\n operation in-place (modifying *self*) and return the result (which\n could be, but does not have to be, *self*). If a specific method\n is not defined, the augmented assignment falls back to the normal\n methods. For instance, if *x* is an instance of a class with an\n "__iadd__()" method, "x += y" is equivalent to "x = x.__iadd__(y)"\n . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are considered, as\n with the evaluation of "x + y". In certain situations, augmented\n assignment can result in unexpected errors (see *Why does\n a_tuple[i] += [\'item\'] raise an exception when the addition\n works?*), but this behavior is in fact part of the data model.\n\nobject.__neg__(self)\nobject.__pos__(self)\nobject.__abs__(self)\nobject.__invert__(self)\n\n Called to implement the unary arithmetic operations ("-", "+",\n "abs()" and "~").\n\nobject.__complex__(self)\nobject.__int__(self)\nobject.__float__(self)\nobject.__round__(self[, n])\n\n Called to implement the built-in functions "complex()", "int()",\n "float()" and "round()". Should return a value of the appropriate\n type.\n\nobject.__index__(self)\n\n Called to implement "operator.index()", and whenever Python needs\n to losslessly convert the numeric object to an integer object (such\n as in slicing, or in the built-in "bin()", "hex()" and "oct()"\n functions). Presence of this method indicates that the numeric\n object is an integer type. Must return an integer.\n\n Note: In order to have a coherent integer type class, when\n "__index__()" is defined "__int__()" should also be defined, and\n both should return the same value.\n\n\nWith Statement Context Managers\n===============================\n\nA *context manager* is an object that defines the runtime context to\nbe established when executing a "with" statement. The context manager\nhandles the entry into, and the exit from, the desired runtime context\nfor the execution of the block of code. Context managers are normally\ninvoked using the "with" statement (described in section *The with\nstatement*), but can also be used by directly invoking their methods.\n\nTypical uses of context managers include saving and restoring various\nkinds of global state, locking and unlocking resources, closing opened\nfiles, etc.\n\nFor more information on context managers, see *Context Manager Types*.\n\nobject.__enter__(self)\n\n Enter the runtime context related to this object. The "with"\n statement will bind this method\'s return value to the target(s)\n specified in the "as" clause of the statement, if any.\n\nobject.__exit__(self, exc_type, exc_value, traceback)\n\n Exit the runtime context related to this object. The parameters\n describe the exception that caused the context to be exited. If the\n context was exited without an exception, all three arguments will\n be "None".\n\n If an exception is supplied, and the method wishes to suppress the\n exception (i.e., prevent it from being propagated), it should\n return a true value. Otherwise, the exception will be processed\n normally upon exit from this method.\n\n Note that "__exit__()" methods should not reraise the passed-in\n exception; this is the caller\'s responsibility.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n\n\nSpecial method lookup\n=====================\n\nFor custom classes, implicit invocations of special methods are only\nguaranteed to work correctly if defined on an object\'s type, not in\nthe object\'s instance dictionary. That behaviour is the reason why\nthe following code raises an exception:\n\n >>> class C:\n ... pass\n ...\n >>> c = C()\n >>> c.__len__ = lambda: 5\n >>> len(c)\n Traceback (most recent call last):\n File "", line 1, in \n TypeError: object of type \'C\' has no len()\n\nThe rationale behind this behaviour lies with a number of special\nmethods such as "__hash__()" and "__repr__()" that are implemented by\nall objects, including type objects. If the implicit lookup of these\nmethods used the conventional lookup process, they would fail when\ninvoked on the type object itself:\n\n >>> 1 .__hash__() == hash(1)\n True\n >>> int.__hash__() == hash(int)\n Traceback (most recent call last):\n File "", line 1, in \n TypeError: descriptor \'__hash__\' of \'int\' object needs an argument\n\nIncorrectly attempting to invoke an unbound method of a class in this\nway is sometimes referred to as \'metaclass confusion\', and is avoided\nby bypassing the instance when looking up special methods:\n\n >>> type(1).__hash__(1) == hash(1)\n True\n >>> type(int).__hash__(int) == hash(int)\n True\n\nIn addition to bypassing any instance attributes in the interest of\ncorrectness, implicit special method lookup generally also bypasses\nthe "__getattribute__()" method even of the object\'s metaclass:\n\n >>> class Meta(type):\n ... def __getattribute__(*args):\n ... print("Metaclass getattribute invoked")\n ... return type.__getattribute__(*args)\n ...\n >>> class C(object, metaclass=Meta):\n ... def __len__(self):\n ... return 10\n ... def __getattribute__(*args):\n ... print("Class getattribute invoked")\n ... return object.__getattribute__(*args)\n ...\n >>> c = C()\n >>> c.__len__() # Explicit lookup via instance\n Class getattribute invoked\n 10\n >>> type(c).__len__(c) # Explicit lookup via type\n Metaclass getattribute invoked\n 10\n >>> len(c) # Implicit lookup\n 10\n\nBypassing the "__getattribute__()" machinery in this fashion provides\nsignificant scope for speed optimisations within the interpreter, at\nthe cost of some flexibility in the handling of special methods (the\nspecial method *must* be set on the class object itself in order to be\nconsistently invoked by the interpreter).\n\n-[ Footnotes ]-\n\n[1] It *is* possible in some cases to change an object\'s type,\n under certain controlled conditions. It generally isn\'t a good\n idea though, since it can lead to some very strange behaviour if\n it is handled incorrectly.\n\n[2] For operands of the same type, it is assumed that if the non-\n reflected method (such as "__add__()") fails the operation is not\n supported, which is why the reflected method is not called.\n', - 'string-methods': u'\nString Methods\n**************\n\nStrings implement all of the *common* sequence operations, along with\nthe additional methods described below.\n\nStrings also support two styles of string formatting, one providing a\nlarge degree of flexibility and customization (see "str.format()",\n*Format String Syntax* and *String Formatting*) and the other based on\nC "printf" style formatting that handles a narrower range of types and\nis slightly harder to use correctly, but is often faster for the cases\nit can handle (*printf-style String Formatting*).\n\nThe *Text Processing Services* section of the standard library covers\na number of other modules that provide various text related utilities\n(including regular expression support in the "re" module).\n\nstr.capitalize()\n\n Return a copy of the string with its first character capitalized\n and the rest lowercased.\n\nstr.casefold()\n\n Return a casefolded copy of the string. Casefolded strings may be\n used for caseless matching.\n\n Casefolding is similar to lowercasing but more aggressive because\n it is intended to remove all case distinctions in a string. For\n example, the German lowercase letter "\'\xdf\'" is equivalent to ""ss"".\n Since it is already lowercase, "lower()" would do nothing to "\'\xdf\'";\n "casefold()" converts it to ""ss"".\n\n The casefolding algorithm is described in section 3.13 of the\n Unicode Standard.\n\n New in version 3.3.\n\nstr.center(width[, fillchar])\n\n Return centered in a string of length *width*. Padding is done\n using the specified *fillchar* (default is an ASCII space). The\n original string is returned if *width* is less than or equal to\n "len(s)".\n\nstr.count(sub[, start[, end]])\n\n Return the number of non-overlapping occurrences of substring *sub*\n in the range [*start*, *end*]. Optional arguments *start* and\n *end* are interpreted as in slice notation.\n\nstr.encode(encoding="utf-8", errors="strict")\n\n Return an encoded version of the string as a bytes object. Default\n encoding is "\'utf-8\'". *errors* may be given to set a different\n error handling scheme. The default for *errors* is "\'strict\'",\n meaning that encoding errors raise a "UnicodeError". Other possible\n values are "\'ignore\'", "\'replace\'", "\'xmlcharrefreplace\'",\n "\'backslashreplace\'" and any other name registered via\n "codecs.register_error()", see section *Error Handlers*. For a list\n of possible encodings, see section *Standard Encodings*.\n\n Changed in version 3.1: Support for keyword arguments added.\n\nstr.endswith(suffix[, start[, end]])\n\n Return "True" if the string ends with the specified *suffix*,\n otherwise return "False". *suffix* can also be a tuple of suffixes\n to look for. With optional *start*, test beginning at that\n position. With optional *end*, stop comparing at that position.\n\nstr.expandtabs(tabsize=8)\n\n Return a copy of the string where all tab characters are replaced\n by one or more spaces, depending on the current column and the\n given tab size. Tab positions occur every *tabsize* characters\n (default is 8, giving tab positions at columns 0, 8, 16 and so on).\n To expand the string, the current column is set to zero and the\n string is examined character by character. If the character is a\n tab ("\\t"), one or more space characters are inserted in the result\n until the current column is equal to the next tab position. (The\n tab character itself is not copied.) If the character is a newline\n ("\\n") or return ("\\r"), it is copied and the current column is\n reset to zero. Any other character is copied unchanged and the\n current column is incremented by one regardless of how the\n character is represented when printed.\n\n >>> \'01\\t012\\t0123\\t01234\'.expandtabs()\n \'01 012 0123 01234\'\n >>> \'01\\t012\\t0123\\t01234\'.expandtabs(4)\n \'01 012 0123 01234\'\n\nstr.find(sub[, start[, end]])\n\n Return the lowest index in the string where substring *sub* is\n found within the slice "s[start:end]". Optional arguments *start*\n and *end* are interpreted as in slice notation. Return "-1" if\n *sub* is not found.\n\n Note: The "find()" method should be used only if you need to know\n the position of *sub*. To check if *sub* is a substring or not,\n use the "in" operator:\n\n >>> \'Py\' in \'Python\'\n True\n\nstr.format(*args, **kwargs)\n\n Perform a string formatting operation. The string on which this\n method is called can contain literal text or replacement fields\n delimited by braces "{}". Each replacement field contains either\n the numeric index of a positional argument, or the name of a\n keyword argument. Returns a copy of the string where each\n replacement field is replaced with the string value of the\n corresponding argument.\n\n >>> "The sum of 1 + 2 is {0}".format(1+2)\n \'The sum of 1 + 2 is 3\'\n\n See *Format String Syntax* for a description of the various\n formatting options that can be specified in format strings.\n\nstr.format_map(mapping)\n\n Similar to "str.format(**mapping)", except that "mapping" is used\n directly and not copied to a "dict". This is useful if for example\n "mapping" is a dict subclass:\n\n >>> class Default(dict):\n ... def __missing__(self, key):\n ... return key\n ...\n >>> \'{name} was born in {country}\'.format_map(Default(name=\'Guido\'))\n \'Guido was born in country\'\n\n New in version 3.2.\n\nstr.index(sub[, start[, end]])\n\n Like "find()", but raise "ValueError" when the substring is not\n found.\n\nstr.isalnum()\n\n Return true if all characters in the string are alphanumeric and\n there is at least one character, false otherwise. A character "c"\n is alphanumeric if one of the following returns "True":\n "c.isalpha()", "c.isdecimal()", "c.isdigit()", or "c.isnumeric()".\n\nstr.isalpha()\n\n Return true if all characters in the string are alphabetic and\n there is at least one character, false otherwise. Alphabetic\n characters are those characters defined in the Unicode character\n database as "Letter", i.e., those with general category property\n being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is\n different from the "Alphabetic" property defined in the Unicode\n Standard.\n\nstr.isdecimal()\n\n Return true if all characters in the string are decimal characters\n and there is at least one character, false otherwise. Decimal\n characters are those from general category "Nd". This category\n includes digit characters, and all characters that can be used to\n form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC DIGIT ZERO.\n\nstr.isdigit()\n\n Return true if all characters in the string are digits and there is\n at least one character, false otherwise. Digits include decimal\n characters and digits that need special handling, such as the\n compatibility superscript digits. Formally, a digit is a character\n that has the property value Numeric_Type=Digit or\n Numeric_Type=Decimal.\n\nstr.isidentifier()\n\n Return true if the string is a valid identifier according to the\n language definition, section *Identifiers and keywords*.\n\n Use "keyword.iskeyword()" to test for reserved identifiers such as\n "def" and "class".\n\nstr.islower()\n\n Return true if all cased characters [4] in the string are lowercase\n and there is at least one cased character, false otherwise.\n\nstr.isnumeric()\n\n Return true if all characters in the string are numeric characters,\n and there is at least one character, false otherwise. Numeric\n characters include digit characters, and all characters that have\n the Unicode numeric value property, e.g. U+2155, VULGAR FRACTION\n ONE FIFTH. Formally, numeric characters are those with the\n property value Numeric_Type=Digit, Numeric_Type=Decimal or\n Numeric_Type=Numeric.\n\nstr.isprintable()\n\n Return true if all characters in the string are printable or the\n string is empty, false otherwise. Nonprintable characters are\n those characters defined in the Unicode character database as\n "Other" or "Separator", excepting the ASCII space (0x20) which is\n considered printable. (Note that printable characters in this\n context are those which should not be escaped when "repr()" is\n invoked on a string. It has no bearing on the handling of strings\n written to "sys.stdout" or "sys.stderr".)\n\nstr.isspace()\n\n Return true if there are only whitespace characters in the string\n and there is at least one character, false otherwise. Whitespace\n characters are those characters defined in the Unicode character\n database as "Other" or "Separator" and those with bidirectional\n property being one of "WS", "B", or "S".\n\nstr.istitle()\n\n Return true if the string is a titlecased string and there is at\n least one character, for example uppercase characters may only\n follow uncased characters and lowercase characters only cased ones.\n Return false otherwise.\n\nstr.isupper()\n\n Return true if all cased characters [4] in the string are uppercase\n and there is at least one cased character, false otherwise.\n\nstr.join(iterable)\n\n Return a string which is the concatenation of the strings in the\n *iterable* *iterable*. A "TypeError" will be raised if there are\n any non-string values in *iterable*, including "bytes" objects.\n The separator between elements is the string providing this method.\n\nstr.ljust(width[, fillchar])\n\n Return the string left justified in a string of length *width*.\n Padding is done using the specified *fillchar* (default is an ASCII\n space). The original string is returned if *width* is less than or\n equal to "len(s)".\n\nstr.lower()\n\n Return a copy of the string with all the cased characters [4]\n converted to lowercase.\n\n The lowercasing algorithm used is described in section 3.13 of the\n Unicode Standard.\n\nstr.lstrip([chars])\n\n Return a copy of the string with leading characters removed. The\n *chars* argument is a string specifying the set of characters to be\n removed. If omitted or "None", the *chars* argument defaults to\n removing whitespace. The *chars* argument is not a prefix; rather,\n all combinations of its values are stripped:\n\n >>> \' spacious \'.lstrip()\n \'spacious \'\n >>> \'www.example.com\'.lstrip(\'cmowz.\')\n \'example.com\'\n\nstatic str.maketrans(x[, y[, z]])\n\n This static method returns a translation table usable for\n "str.translate()".\n\n If there is only one argument, it must be a dictionary mapping\n Unicode ordinals (integers) or characters (strings of length 1) to\n Unicode ordinals, strings (of arbitrary lengths) or None.\n Character keys will then be converted to ordinals.\n\n If there are two arguments, they must be strings of equal length,\n and in the resulting dictionary, each character in x will be mapped\n to the character at the same position in y. If there is a third\n argument, it must be a string, whose characters will be mapped to\n None in the result.\n\nstr.partition(sep)\n\n Split the string at the first occurrence of *sep*, and return a\n 3-tuple containing the part before the separator, the separator\n itself, and the part after the separator. If the separator is not\n found, return a 3-tuple containing the string itself, followed by\n two empty strings.\n\nstr.replace(old, new[, count])\n\n Return a copy of the string with all occurrences of substring *old*\n replaced by *new*. If the optional argument *count* is given, only\n the first *count* occurrences are replaced.\n\nstr.rfind(sub[, start[, end]])\n\n Return the highest index in the string where substring *sub* is\n found, such that *sub* is contained within "s[start:end]".\n Optional arguments *start* and *end* are interpreted as in slice\n notation. Return "-1" on failure.\n\nstr.rindex(sub[, start[, end]])\n\n Like "rfind()" but raises "ValueError" when the substring *sub* is\n not found.\n\nstr.rjust(width[, fillchar])\n\n Return the string right justified in a string of length *width*.\n Padding is done using the specified *fillchar* (default is an ASCII\n space). The original string is returned if *width* is less than or\n equal to "len(s)".\n\nstr.rpartition(sep)\n\n Split the string at the last occurrence of *sep*, and return a\n 3-tuple containing the part before the separator, the separator\n itself, and the part after the separator. If the separator is not\n found, return a 3-tuple containing two empty strings, followed by\n the string itself.\n\nstr.rsplit(sep=None, maxsplit=-1)\n\n Return a list of the words in the string, using *sep* as the\n delimiter string. If *maxsplit* is given, at most *maxsplit* splits\n are done, the *rightmost* ones. If *sep* is not specified or\n "None", any whitespace string is a separator. Except for splitting\n from the right, "rsplit()" behaves like "split()" which is\n described in detail below.\n\nstr.rstrip([chars])\n\n Return a copy of the string with trailing characters removed. The\n *chars* argument is a string specifying the set of characters to be\n removed. If omitted or "None", the *chars* argument defaults to\n removing whitespace. The *chars* argument is not a suffix; rather,\n all combinations of its values are stripped:\n\n >>> \' spacious \'.rstrip()\n \' spacious\'\n >>> \'mississippi\'.rstrip(\'ipz\')\n \'mississ\'\n\nstr.split(sep=None, maxsplit=-1)\n\n Return a list of the words in the string, using *sep* as the\n delimiter string. If *maxsplit* is given, at most *maxsplit*\n splits are done (thus, the list will have at most "maxsplit+1"\n elements). If *maxsplit* is not specified or "-1", then there is\n no limit on the number of splits (all possible splits are made).\n\n If *sep* is given, consecutive delimiters are not grouped together\n and are deemed to delimit empty strings (for example,\n "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', \'2\']"). The *sep* argument\n may consist of multiple characters (for example,\n "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', \'3\']"). Splitting an\n empty string with a specified separator returns "[\'\']".\n\n For example:\n\n >>> \'1,2,3\'.split(\',\')\n [\'1\', \'2\', \'3\']\n >>> \'1,2,3\'.split(\',\', maxsplit=1)\n [\'1\', \'2,3\']\n >>> \'1,2,,3,\'.split(\',\')\n [\'1\', \'2\', \'\', \'3\', \'\']\n\n If *sep* is not specified or is "None", a different splitting\n algorithm is applied: runs of consecutive whitespace are regarded\n as a single separator, and the result will contain no empty strings\n at the start or end if the string has leading or trailing\n whitespace. Consequently, splitting an empty string or a string\n consisting of just whitespace with a "None" separator returns "[]".\n\n For example:\n\n >>> \'1 2 3\'.split()\n [\'1\', \'2\', \'3\']\n >>> \'1 2 3\'.split(maxsplit=1)\n [\'1\', \'2 3\']\n >>> \' 1 2 3 \'.split()\n [\'1\', \'2\', \'3\']\n\nstr.splitlines([keepends])\n\n Return a list of the lines in the string, breaking at line\n boundaries. Line breaks are not included in the resulting list\n unless *keepends* is given and true.\n\n This method splits on the following line boundaries. In\n particular, the boundaries are a superset of *universal newlines*.\n\n +-------------------------+-------------------------------+\n | Representation | Description |\n +=========================+===============================+\n | "\\n" | Line Feed |\n +-------------------------+-------------------------------+\n | "\\r" | Carriage Return |\n +-------------------------+-------------------------------+\n | "\\r\\n" | Carriage Return + Line Feed |\n +-------------------------+-------------------------------+\n | "\\v" or "\\x0b" | Line Tabulation |\n +-------------------------+-------------------------------+\n | "\\f" or "\\x0c" | Form Feed |\n +-------------------------+-------------------------------+\n | "\\x1c" | File Separator |\n +-------------------------+-------------------------------+\n | "\\x1d" | Group Separator |\n +-------------------------+-------------------------------+\n | "\\x1e" | Record Separator |\n +-------------------------+-------------------------------+\n | "\\x85" | Next Line (C1 Control Code) |\n +-------------------------+-------------------------------+\n | "\\u2028" | Line Separator |\n +-------------------------+-------------------------------+\n | "\\u2029" | Paragraph Separator |\n +-------------------------+-------------------------------+\n\n Changed in version 3.2: "\\v" and "\\f" added to list of line\n boundaries.\n\n For example:\n\n >>> \'ab c\\n\\nde fg\\rkl\\r\\n\'.splitlines()\n [\'ab c\', \'\', \'de fg\', \'kl\']\n >>> \'ab c\\n\\nde fg\\rkl\\r\\n\'.splitlines(keepends=True)\n [\'ab c\\n\', \'\\n\', \'de fg\\r\', \'kl\\r\\n\']\n\n Unlike "split()" when a delimiter string *sep* is given, this\n method returns an empty list for the empty string, and a terminal\n line break does not result in an extra line:\n\n >>> "".splitlines()\n []\n >>> "One line\\n".splitlines()\n [\'One line\']\n\n For comparison, "split(\'\\n\')" gives:\n\n >>> \'\'.split(\'\\n\')\n [\'\']\n >>> \'Two lines\\n\'.split(\'\\n\')\n [\'Two lines\', \'\']\n\nstr.startswith(prefix[, start[, end]])\n\n Return "True" if string starts with the *prefix*, otherwise return\n "False". *prefix* can also be a tuple of prefixes to look for.\n With optional *start*, test string beginning at that position.\n With optional *end*, stop comparing string at that position.\n\nstr.strip([chars])\n\n Return a copy of the string with the leading and trailing\n characters removed. The *chars* argument is a string specifying the\n set of characters to be removed. If omitted or "None", the *chars*\n argument defaults to removing whitespace. The *chars* argument is\n not a prefix or suffix; rather, all combinations of its values are\n stripped:\n\n >>> \' spacious \'.strip()\n \'spacious\'\n >>> \'www.example.com\'.strip(\'cmowz.\')\n \'example\'\n\nstr.swapcase()\n\n Return a copy of the string with uppercase characters converted to\n lowercase and vice versa. Note that it is not necessarily true that\n "s.swapcase().swapcase() == s".\n\nstr.title()\n\n Return a titlecased version of the string where words start with an\n uppercase character and the remaining characters are lowercase.\n\n For example:\n\n >>> \'Hello world\'.title()\n \'Hello World\'\n\n The algorithm uses a simple language-independent definition of a\n word as groups of consecutive letters. The definition works in\n many contexts but it means that apostrophes in contractions and\n possessives form word boundaries, which may not be the desired\n result:\n\n >>> "they\'re bill\'s friends from the UK".title()\n "They\'Re Bill\'S Friends From The Uk"\n\n A workaround for apostrophes can be constructed using regular\n expressions:\n\n >>> import re\n >>> def titlecase(s):\n ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n ... lambda mo: mo.group(0)[0].upper() +\n ... mo.group(0)[1:].lower(),\n ... s)\n ...\n >>> titlecase("they\'re bill\'s friends.")\n "They\'re Bill\'s Friends."\n\nstr.translate(table)\n\n Return a copy of the string in which each character has been mapped\n through the given translation table. The table must be an object\n that implements indexing via "__getitem__()", typically a *mapping*\n or *sequence*. When indexed by a Unicode ordinal (an integer), the\n table object can do any of the following: return a Unicode ordinal\n or a string, to map the character to one or more other characters;\n return "None", to delete the character from the return string; or\n raise a "LookupError" exception, to map the character to itself.\n\n You can use "str.maketrans()" to create a translation map from\n character-to-character mappings in different formats.\n\n See also the "codecs" module for a more flexible approach to custom\n character mappings.\n\nstr.upper()\n\n Return a copy of the string with all the cased characters [4]\n converted to uppercase. Note that "str.upper().isupper()" might be\n "False" if "s" contains uncased characters or if the Unicode\n category of the resulting character(s) is not "Lu" (Letter,\n uppercase), but e.g. "Lt" (Letter, titlecase).\n\n The uppercasing algorithm used is described in section 3.13 of the\n Unicode Standard.\n\nstr.zfill(width)\n\n Return a copy of the string left filled with ASCII "\'0\'" digits to\n make a string of length *width*. A leading sign prefix\n ("\'+\'"/"\'-\'") is handled by inserting the padding *after* the sign\n character rather than before. The original string is returned if\n *width* is less than or equal to "len(s)".\n\n For example:\n\n >>> "42".zfill(5)\n \'00042\'\n >>> "-42".zfill(5)\n \'-0042\'\n', - 'strings': u'\nString and Bytes literals\n*************************\n\nString literals are described by the following lexical definitions:\n\n stringliteral ::= [stringprefix](shortstring | longstring)\n stringprefix ::= "r" | "u" | "R" | "U"\n shortstring ::= "\'" shortstringitem* "\'" | \'"\' shortstringitem* \'"\'\n longstring ::= "\'\'\'" longstringitem* "\'\'\'" | \'"""\' longstringitem* \'"""\'\n shortstringitem ::= shortstringchar | stringescapeseq\n longstringitem ::= longstringchar | stringescapeseq\n shortstringchar ::= \n longstringchar ::= \n stringescapeseq ::= "\\" \n\n bytesliteral ::= bytesprefix(shortbytes | longbytes)\n bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"\n shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' shortbytesitem* \'"\'\n longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' longbytesitem* \'"""\'\n shortbytesitem ::= shortbyteschar | bytesescapeseq\n longbytesitem ::= longbyteschar | bytesescapeseq\n shortbyteschar ::= \n longbyteschar ::= \n bytesescapeseq ::= "\\" \n\nOne syntactic restriction not indicated by these productions is that\nwhitespace is not allowed between the "stringprefix" or "bytesprefix"\nand the rest of the literal. The source character set is defined by\nthe encoding declaration; it is UTF-8 if no encoding declaration is\ngiven in the source file; see section *Encoding declarations*.\n\nIn plain English: Both types of literals can be enclosed in matching\nsingle quotes ("\'") or double quotes ("""). They can also be enclosed\nin matching groups of three single or double quotes (these are\ngenerally referred to as *triple-quoted strings*). The backslash\n("\\") character is used to escape characters that otherwise have a\nspecial meaning, such as newline, backslash itself, or the quote\ncharacter.\n\nBytes literals are always prefixed with "\'b\'" or "\'B\'"; they produce\nan instance of the "bytes" type instead of the "str" type. They may\nonly contain ASCII characters; bytes with a numeric value of 128 or\ngreater must be expressed with escapes.\n\nAs of Python 3.3 it is possible again to prefix string literals with a\n"u" prefix to simplify maintenance of dual 2.x and 3.x codebases.\n\nBoth string and bytes literals may optionally be prefixed with a\nletter "\'r\'" or "\'R\'"; such strings are called *raw strings* and treat\nbackslashes as literal characters. As a result, in string literals,\n"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated specially.\nGiven that Python 2.x\'s raw unicode literals behave differently than\nPython 3.x\'s the "\'ur\'" syntax is not supported.\n\nNew in version 3.3: The "\'rb\'" prefix of raw bytes literals has been\nadded as a synonym of "\'br\'".\n\nNew in version 3.3: Support for the unicode legacy literal\n("u\'value\'") was reintroduced to simplify the maintenance of dual\nPython 2.x and 3.x codebases. See **PEP 414** for more information.\n\nIn triple-quoted literals, unescaped newlines and quotes are allowed\n(and are retained), except that three unescaped quotes in a row\nterminate the literal. (A "quote" is the character used to open the\nliteral, i.e. either "\'" or """.)\n\nUnless an "\'r\'" or "\'R\'" prefix is present, escape sequences in string\nand bytes literals are interpreted according to rules similar to those\nused by Standard C. The recognized escape sequences are:\n\n+-------------------+-----------------------------------+---------+\n| Escape Sequence | Meaning | Notes |\n+===================+===================================+=========+\n| "\\newline" | Backslash and newline ignored | |\n+-------------------+-----------------------------------+---------+\n| "\\\\" | Backslash ("\\") | |\n+-------------------+-----------------------------------+---------+\n| "\\\'" | Single quote ("\'") | |\n+-------------------+-----------------------------------+---------+\n| "\\"" | Double quote (""") | |\n+-------------------+-----------------------------------+---------+\n| "\\a" | ASCII Bell (BEL) | |\n+-------------------+-----------------------------------+---------+\n| "\\b" | ASCII Backspace (BS) | |\n+-------------------+-----------------------------------+---------+\n| "\\f" | ASCII Formfeed (FF) | |\n+-------------------+-----------------------------------+---------+\n| "\\n" | ASCII Linefeed (LF) | |\n+-------------------+-----------------------------------+---------+\n| "\\r" | ASCII Carriage Return (CR) | |\n+-------------------+-----------------------------------+---------+\n| "\\t" | ASCII Horizontal Tab (TAB) | |\n+-------------------+-----------------------------------+---------+\n| "\\v" | ASCII Vertical Tab (VT) | |\n+-------------------+-----------------------------------+---------+\n| "\\ooo" | Character with octal value *ooo* | (1,3) |\n+-------------------+-----------------------------------+---------+\n| "\\xhh" | Character with hex value *hh* | (2,3) |\n+-------------------+-----------------------------------+---------+\n\nEscape sequences only recognized in string literals are:\n\n+-------------------+-----------------------------------+---------+\n| Escape Sequence | Meaning | Notes |\n+===================+===================================+=========+\n| "\\N{name}" | Character named *name* in the | (4) |\n| | Unicode database | |\n+-------------------+-----------------------------------+---------+\n| "\\uxxxx" | Character with 16-bit hex value | (5) |\n| | *xxxx* | |\n+-------------------+-----------------------------------+---------+\n| "\\Uxxxxxxxx" | Character with 32-bit hex value | (6) |\n| | *xxxxxxxx* | |\n+-------------------+-----------------------------------+---------+\n\nNotes:\n\n1. As in Standard C, up to three octal digits are accepted.\n\n2. Unlike in Standard C, exactly two hex digits are required.\n\n3. In a bytes literal, hexadecimal and octal escapes denote the\n byte with the given value. In a string literal, these escapes\n denote a Unicode character with the given value.\n\n4. Changed in version 3.3: Support for name aliases [1] has been\n added.\n\n5. Individual code units which form parts of a surrogate pair can\n be encoded using this escape sequence. Exactly four hex digits are\n required.\n\n6. Any Unicode character can be encoded this way. Exactly eight\n hex digits are required.\n\nUnlike Standard C, all unrecognized escape sequences are left in the\nstring unchanged, i.e., *the backslash is left in the result*. (This\nbehavior is useful when debugging: if an escape sequence is mistyped,\nthe resulting output is more easily recognized as broken.) It is also\nimportant to note that the escape sequences only recognized in string\nliterals fall into the category of unrecognized escapes for bytes\nliterals.\n\nEven in a raw literal, quotes can be escaped with a backslash, but the\nbackslash remains in the result; for example, "r"\\""" is a valid\nstring literal consisting of two characters: a backslash and a double\nquote; "r"\\"" is not a valid string literal (even a raw string cannot\nend in an odd number of backslashes). Specifically, *a raw literal\ncannot end in a single backslash* (since the backslash would escape\nthe following quote character). Note also that a single backslash\nfollowed by a newline is interpreted as those two characters as part\nof the literal, *not* as a line continuation.\n', - 'subscriptions': u'\nSubscriptions\n*************\n\nA subscription selects an item of a sequence (string, tuple or list)\nor mapping (dictionary) object:\n\n subscription ::= primary "[" expression_list "]"\n\nThe primary must evaluate to an object that supports subscription\n(lists or dictionaries for example). User-defined objects can support\nsubscription by defining a "__getitem__()" method.\n\nFor built-in objects, there are two types of objects that support\nsubscription:\n\nIf the primary is a mapping, the expression list must evaluate to an\nobject whose value is one of the keys of the mapping, and the\nsubscription selects the value in the mapping that corresponds to that\nkey. (The expression list is a tuple except if it has exactly one\nitem.)\n\nIf the primary is a sequence, the expression (list) must evaluate to\nan integer or a slice (as discussed in the following section).\n\nThe formal syntax makes no special provision for negative indices in\nsequences; however, built-in sequences all provide a "__getitem__()"\nmethod that interprets negative indices by adding the length of the\nsequence to the index (so that "x[-1]" selects the last item of "x").\nThe resulting value must be a nonnegative integer less than the number\nof items in the sequence, and the subscription selects the item whose\nindex is that value (counting from zero). Since the support for\nnegative indices and slicing occurs in the object\'s "__getitem__()"\nmethod, subclasses overriding this method will need to explicitly add\nthat support.\n\nA string\'s items are characters. A character is not a separate data\ntype but a string of exactly one character.\n', - 'truth': u'\nTruth Value Testing\n*******************\n\nAny object can be tested for truth value, for use in an "if" or\n"while" condition or as operand of the Boolean operations below. The\nfollowing values are considered false:\n\n* "None"\n\n* "False"\n\n* zero of any numeric type, for example, "0", "0.0", "0j".\n\n* any empty sequence, for example, "\'\'", "()", "[]".\n\n* any empty mapping, for example, "{}".\n\n* instances of user-defined classes, if the class defines a\n "__bool__()" or "__len__()" method, when that method returns the\n integer zero or "bool" value "False". [1]\n\nAll other values are considered true --- so objects of many types are\nalways true.\n\nOperations and built-in functions that have a Boolean result always\nreturn "0" or "False" for false and "1" or "True" for true, unless\notherwise stated. (Important exception: the Boolean operations "or"\nand "and" always return one of their operands.)\n', - 'try': u'\nThe "try" statement\n*******************\n\nThe "try" statement specifies exception handlers and/or cleanup code\nfor a group of statements:\n\n try_stmt ::= try1_stmt | try2_stmt\n try1_stmt ::= "try" ":" suite\n ("except" [expression ["as" identifier]] ":" suite)+\n ["else" ":" suite]\n ["finally" ":" suite]\n try2_stmt ::= "try" ":" suite\n "finally" ":" suite\n\nThe "except" clause(s) specify one or more exception handlers. When no\nexception occurs in the "try" clause, no exception handler is\nexecuted. When an exception occurs in the "try" suite, a search for an\nexception handler is started. This search inspects the except clauses\nin turn until one is found that matches the exception. An expression-\nless except clause, if present, must be last; it matches any\nexception. For an except clause with an expression, that expression\nis evaluated, and the clause matches the exception if the resulting\nobject is "compatible" with the exception. An object is compatible\nwith an exception if it is the class or a base class of the exception\nobject or a tuple containing an item compatible with the exception.\n\nIf no except clause matches the exception, the search for an exception\nhandler continues in the surrounding code and on the invocation stack.\n[1]\n\nIf the evaluation of an expression in the header of an except clause\nraises an exception, the original search for a handler is canceled and\na search starts for the new exception in the surrounding code and on\nthe call stack (it is treated as if the entire "try" statement raised\nthe exception).\n\nWhen a matching except clause is found, the exception is assigned to\nthe target specified after the "as" keyword in that except clause, if\npresent, and the except clause\'s suite is executed. All except\nclauses must have an executable block. When the end of this block is\nreached, execution continues normally after the entire try statement.\n(This means that if two nested handlers exist for the same exception,\nand the exception occurs in the try clause of the inner handler, the\nouter handler will not handle the exception.)\n\nWhen an exception has been assigned using "as target", it is cleared\nat the end of the except clause. This is as if\n\n except E as N:\n foo\n\nwas translated to\n\n except E as N:\n try:\n foo\n finally:\n del N\n\nThis means the exception must be assigned to a different name to be\nable to refer to it after the except clause. Exceptions are cleared\nbecause with the traceback attached to them, they form a reference\ncycle with the stack frame, keeping all locals in that frame alive\nuntil the next garbage collection occurs.\n\nBefore an except clause\'s suite is executed, details about the\nexception are stored in the "sys" module and can be accessed via\n"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of the\nexception class, the exception instance and a traceback object (see\nsection *The standard type hierarchy*) identifying the point in the\nprogram where the exception occurred. "sys.exc_info()" values are\nrestored to their previous values (before the call) when returning\nfrom a function that handled an exception.\n\nThe optional "else" clause is executed if and when control flows off\nthe end of the "try" clause. [2] Exceptions in the "else" clause are\nnot handled by the preceding "except" clauses.\n\nIf "finally" is present, it specifies a \'cleanup\' handler. The "try"\nclause is executed, including any "except" and "else" clauses. If an\nexception occurs in any of the clauses and is not handled, the\nexception is temporarily saved. The "finally" clause is executed. If\nthere is a saved exception it is re-raised at the end of the "finally"\nclause. If the "finally" clause raises another exception, the saved\nexception is set as the context of the new exception. If the "finally"\nclause executes a "return" or "break" statement, the saved exception\nis discarded:\n\n >>> def f():\n ... try:\n ... 1/0\n ... finally:\n ... return 42\n ...\n >>> f()\n 42\n\nThe exception information is not available to the program during\nexecution of the "finally" clause.\n\nWhen a "return", "break" or "continue" statement is executed in the\n"try" suite of a "try"..."finally" statement, the "finally" clause is\nalso executed \'on the way out.\' A "continue" statement is illegal in\nthe "finally" clause. (The reason is a problem with the current\nimplementation --- this restriction may be lifted in the future).\n\nThe return value of a function is determined by the last "return"\nstatement executed. Since the "finally" clause always executes, a\n"return" statement executed in the "finally" clause will always be the\nlast one executed:\n\n >>> def foo():\n ... try:\n ... return \'try\'\n ... finally:\n ... return \'finally\'\n ...\n >>> foo()\n \'finally\'\n\nAdditional information on exceptions can be found in section\n*Exceptions*, and information on using the "raise" statement to\ngenerate exceptions may be found in section *The raise statement*.\n', - 'types': u'\nThe standard type hierarchy\n***************************\n\nBelow is a list of the types that are built into Python. Extension\nmodules (written in C, Java, or other languages, depending on the\nimplementation) can define additional types. Future versions of\nPython may add types to the type hierarchy (e.g., rational numbers,\nefficiently stored arrays of integers, etc.), although such additions\nwill often be provided via the standard library instead.\n\nSome of the type descriptions below contain a paragraph listing\n\'special attributes.\' These are attributes that provide access to the\nimplementation and are not intended for general use. Their definition\nmay change in the future.\n\nNone\n This type has a single value. There is a single object with this\n value. This object is accessed through the built-in name "None". It\n is used to signify the absence of a value in many situations, e.g.,\n it is returned from functions that don\'t explicitly return\n anything. Its truth value is false.\n\nNotImplemented\n This type has a single value. There is a single object with this\n value. This object is accessed through the built-in name\n "NotImplemented". Numeric methods and rich comparison methods\n should return this value if they do not implement the operation for\n the operands provided. (The interpreter will then try the\n reflected operation, or some other fallback, depending on the\n operator.) Its truth value is true.\n\n See *Implementing the arithmetic operations* for more details.\n\nEllipsis\n This type has a single value. There is a single object with this\n value. This object is accessed through the literal "..." or the\n built-in name "Ellipsis". Its truth value is true.\n\n"numbers.Number"\n These are created by numeric literals and returned as results by\n arithmetic operators and arithmetic built-in functions. Numeric\n objects are immutable; once created their value never changes.\n Python numbers are of course strongly related to mathematical\n numbers, but subject to the limitations of numerical representation\n in computers.\n\n Python distinguishes between integers, floating point numbers, and\n complex numbers:\n\n "numbers.Integral"\n These represent elements from the mathematical set of integers\n (positive and negative).\n\n There are two types of integers:\n\n Integers ("int")\n\n These represent numbers in an unlimited range, subject to\n available (virtual) memory only. For the purpose of shift\n and mask operations, a binary representation is assumed, and\n negative numbers are represented in a variant of 2\'s\n complement which gives the illusion of an infinite string of\n sign bits extending to the left.\n\n Booleans ("bool")\n These represent the truth values False and True. The two\n objects representing the values "False" and "True" are the\n only Boolean objects. The Boolean type is a subtype of the\n integer type, and Boolean values behave like the values 0 and\n 1, respectively, in almost all contexts, the exception being\n that when converted to a string, the strings ""False"" or\n ""True"" are returned, respectively.\n\n The rules for integer representation are intended to give the\n most meaningful interpretation of shift and mask operations\n involving negative integers.\n\n "numbers.Real" ("float")\n These represent machine-level double precision floating point\n numbers. You are at the mercy of the underlying machine\n architecture (and C or Java implementation) for the accepted\n range and handling of overflow. Python does not support single-\n precision floating point numbers; the savings in processor and\n memory usage that are usually the reason for using these are\n dwarfed by the overhead of using objects in Python, so there is\n no reason to complicate the language with two kinds of floating\n point numbers.\n\n "numbers.Complex" ("complex")\n These represent complex numbers as a pair of machine-level\n double precision floating point numbers. The same caveats apply\n as for floating point numbers. The real and imaginary parts of a\n complex number "z" can be retrieved through the read-only\n attributes "z.real" and "z.imag".\n\nSequences\n These represent finite ordered sets indexed by non-negative\n numbers. The built-in function "len()" returns the number of items\n of a sequence. When the length of a sequence is *n*, the index set\n contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence *a* is\n selected by "a[i]".\n\n Sequences also support slicing: "a[i:j]" selects all items with\n index *k* such that *i* "<=" *k* "<" *j*. When used as an\n expression, a slice is a sequence of the same type. This implies\n that the index set is renumbered so that it starts at 0.\n\n Some sequences also support "extended slicing" with a third "step"\n parameter: "a[i:j:k]" selects all items of *a* with index *x* where\n "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n\n Sequences are distinguished according to their mutability:\n\n Immutable sequences\n An object of an immutable sequence type cannot change once it is\n created. (If the object contains references to other objects,\n these other objects may be mutable and may be changed; however,\n the collection of objects directly referenced by an immutable\n object cannot change.)\n\n The following types are immutable sequences:\n\n Strings\n A string is a sequence of values that represent Unicode code\n points. All the code points in the range "U+0000 - U+10FFFF"\n can be represented in a string. Python doesn\'t have a "char"\n type; instead, every code point in the string is represented\n as a string object with length "1". The built-in function\n "ord()" converts a code point from its string form to an\n integer in the range "0 - 10FFFF"; "chr()" converts an\n integer in the range "0 - 10FFFF" to the corresponding length\n "1" string object. "str.encode()" can be used to convert a\n "str" to "bytes" using the given text encoding, and\n "bytes.decode()" can be used to achieve the opposite.\n\n Tuples\n The items of a tuple are arbitrary Python objects. Tuples of\n two or more items are formed by comma-separated lists of\n expressions. A tuple of one item (a \'singleton\') can be\n formed by affixing a comma to an expression (an expression by\n itself does not create a tuple, since parentheses must be\n usable for grouping of expressions). An empty tuple can be\n formed by an empty pair of parentheses.\n\n Bytes\n A bytes object is an immutable array. The items are 8-bit\n bytes, represented by integers in the range 0 <= x < 256.\n Bytes literals (like "b\'abc\'") and the built-in function\n "bytes()" can be used to construct bytes objects. Also,\n bytes objects can be decoded to strings via the "decode()"\n method.\n\n Mutable sequences\n Mutable sequences can be changed after they are created. The\n subscription and slicing notations can be used as the target of\n assignment and "del" (delete) statements.\n\n There are currently two intrinsic mutable sequence types:\n\n Lists\n The items of a list are arbitrary Python objects. Lists are\n formed by placing a comma-separated list of expressions in\n square brackets. (Note that there are no special cases needed\n to form lists of length 0 or 1.)\n\n Byte Arrays\n A bytearray object is a mutable array. They are created by\n the built-in "bytearray()" constructor. Aside from being\n mutable (and hence unhashable), byte arrays otherwise provide\n the same interface and functionality as immutable bytes\n objects.\n\n The extension module "array" provides an additional example of a\n mutable sequence type, as does the "collections" module.\n\nSet types\n These represent unordered, finite sets of unique, immutable\n objects. As such, they cannot be indexed by any subscript. However,\n they can be iterated over, and the built-in function "len()"\n returns the number of items in a set. Common uses for sets are fast\n membership testing, removing duplicates from a sequence, and\n computing mathematical operations such as intersection, union,\n difference, and symmetric difference.\n\n For set elements, the same immutability rules apply as for\n dictionary keys. Note that numeric types obey the normal rules for\n numeric comparison: if two numbers compare equal (e.g., "1" and\n "1.0"), only one of them can be contained in a set.\n\n There are currently two intrinsic set types:\n\n Sets\n These represent a mutable set. They are created by the built-in\n "set()" constructor and can be modified afterwards by several\n methods, such as "add()".\n\n Frozen sets\n These represent an immutable set. They are created by the\n built-in "frozenset()" constructor. As a frozenset is immutable\n and *hashable*, it can be used again as an element of another\n set, or as a dictionary key.\n\nMappings\n These represent finite sets of objects indexed by arbitrary index\n sets. The subscript notation "a[k]" selects the item indexed by "k"\n from the mapping "a"; this can be used in expressions and as the\n target of assignments or "del" statements. The built-in function\n "len()" returns the number of items in a mapping.\n\n There is currently a single intrinsic mapping type:\n\n Dictionaries\n These represent finite sets of objects indexed by nearly\n arbitrary values. The only types of values not acceptable as\n keys are values containing lists or dictionaries or other\n mutable types that are compared by value rather than by object\n identity, the reason being that the efficient implementation of\n dictionaries requires a key\'s hash value to remain constant.\n Numeric types used for keys obey the normal rules for numeric\n comparison: if two numbers compare equal (e.g., "1" and "1.0")\n then they can be used interchangeably to index the same\n dictionary entry.\n\n Dictionaries are mutable; they can be created by the "{...}"\n notation (see section *Dictionary displays*).\n\n The extension modules "dbm.ndbm" and "dbm.gnu" provide\n additional examples of mapping types, as does the "collections"\n module.\n\nCallable types\n These are the types to which the function call operation (see\n section *Calls*) can be applied:\n\n User-defined functions\n A user-defined function object is created by a function\n definition (see section *Function definitions*). It should be\n called with an argument list containing the same number of items\n as the function\'s formal parameter list.\n\n Special attributes:\n\n +---------------------------+---------------------------------+-------------+\n | Attribute | Meaning | |\n +===========================+=================================+=============+\n | "__doc__" | The function\'s documentation | Writable |\n | | string, or "None" if | |\n | | unavailable; not inherited by | |\n | | subclasses | |\n +---------------------------+---------------------------------+-------------+\n | "__name__" | The function\'s name | Writable |\n +---------------------------+---------------------------------+-------------+\n | "__qualname__" | The function\'s *qualified name* | Writable |\n | | New in version 3.3. | |\n +---------------------------+---------------------------------+-------------+\n | "__module__" | The name of the module the | Writable |\n | | function was defined in, or | |\n | | "None" if unavailable. | |\n +---------------------------+---------------------------------+-------------+\n | "__defaults__" | A tuple containing default | Writable |\n | | argument values for those | |\n | | arguments that have defaults, | |\n | | or "None" if no arguments have | |\n | | a default value | |\n +---------------------------+---------------------------------+-------------+\n | "__code__" | The code object representing | Writable |\n | | the compiled function body. | |\n +---------------------------+---------------------------------+-------------+\n | "__globals__" | A reference to the dictionary | Read-only |\n | | that holds the function\'s | |\n | | global variables --- the global | |\n | | namespace of the module in | |\n | | which the function was defined. | |\n +---------------------------+---------------------------------+-------------+\n | "__dict__" | The namespace supporting | Writable |\n | | arbitrary function attributes. | |\n +---------------------------+---------------------------------+-------------+\n | "__closure__" | "None" or a tuple of cells that | Read-only |\n | | contain bindings for the | |\n | | function\'s free variables. | |\n +---------------------------+---------------------------------+-------------+\n | "__annotations__" | A dict containing annotations | Writable |\n | | of parameters. The keys of the | |\n | | dict are the parameter names, | |\n | | and "\'return\'" for the return | |\n | | annotation, if provided. | |\n +---------------------------+---------------------------------+-------------+\n | "__kwdefaults__" | A dict containing defaults for | Writable |\n | | keyword-only parameters. | |\n +---------------------------+---------------------------------+-------------+\n\n Most of the attributes labelled "Writable" check the type of the\n assigned value.\n\n Function objects also support getting and setting arbitrary\n attributes, which can be used, for example, to attach metadata\n to functions. Regular attribute dot-notation is used to get and\n set such attributes. *Note that the current implementation only\n supports function attributes on user-defined functions. Function\n attributes on built-in functions may be supported in the\n future.*\n\n Additional information about a function\'s definition can be\n retrieved from its code object; see the description of internal\n types below.\n\n Instance methods\n An instance method object combines a class, a class instance and\n any callable object (normally a user-defined function).\n\n Special read-only attributes: "__self__" is the class instance\n object, "__func__" is the function object; "__doc__" is the\n method\'s documentation (same as "__func__.__doc__"); "__name__"\n is the method name (same as "__func__.__name__"); "__module__"\n is the name of the module the method was defined in, or "None"\n if unavailable.\n\n Methods also support accessing (but not setting) the arbitrary\n function attributes on the underlying function object.\n\n User-defined method objects may be created when getting an\n attribute of a class (perhaps via an instance of that class), if\n that attribute is a user-defined function object or a class\n method object.\n\n When an instance method object is created by retrieving a user-\n defined function object from a class via one of its instances,\n its "__self__" attribute is the instance, and the method object\n is said to be bound. The new method\'s "__func__" attribute is\n the original function object.\n\n When a user-defined method object is created by retrieving\n another method object from a class or instance, the behaviour is\n the same as for a function object, except that the "__func__"\n attribute of the new instance is not the original method object\n but its "__func__" attribute.\n\n When an instance method object is created by retrieving a class\n method object from a class or instance, its "__self__" attribute\n is the class itself, and its "__func__" attribute is the\n function object underlying the class method.\n\n When an instance method object is called, the underlying\n function ("__func__") is called, inserting the class instance\n ("__self__") in front of the argument list. For instance, when\n "C" is a class which contains a definition for a function "f()",\n and "x" is an instance of "C", calling "x.f(1)" is equivalent to\n calling "C.f(x, 1)".\n\n When an instance method object is derived from a class method\n object, the "class instance" stored in "__self__" will actually\n be the class itself, so that calling either "x.f(1)" or "C.f(1)"\n is equivalent to calling "f(C,1)" where "f" is the underlying\n function.\n\n Note that the transformation from function object to instance\n method object happens each time the attribute is retrieved from\n the instance. In some cases, a fruitful optimization is to\n assign the attribute to a local variable and call that local\n variable. Also notice that this transformation only happens for\n user-defined functions; other callable objects (and all non-\n callable objects) are retrieved without transformation. It is\n also important to note that user-defined functions which are\n attributes of a class instance are not converted to bound\n methods; this *only* happens when the function is an attribute\n of the class.\n\n Generator functions\n A function or method which uses the "yield" statement (see\n section *The yield statement*) is called a *generator function*.\n Such a function, when called, always returns an iterator object\n which can be used to execute the body of the function: calling\n the iterator\'s "iterator.__next__()" method will cause the\n function to execute until it provides a value using the "yield"\n statement. When the function executes a "return" statement or\n falls off the end, a "StopIteration" exception is raised and the\n iterator will have reached the end of the set of values to be\n returned.\n\n Built-in functions\n A built-in function object is a wrapper around a C function.\n Examples of built-in functions are "len()" and "math.sin()"\n ("math" is a standard built-in module). The number and type of\n the arguments are determined by the C function. Special read-\n only attributes: "__doc__" is the function\'s documentation\n string, or "None" if unavailable; "__name__" is the function\'s\n name; "__self__" is set to "None" (but see the next item);\n "__module__" is the name of the module the function was defined\n in or "None" if unavailable.\n\n Built-in methods\n This is really a different disguise of a built-in function, this\n time containing an object passed to the C function as an\n implicit extra argument. An example of a built-in method is\n "alist.append()", assuming *alist* is a list object. In this\n case, the special read-only attribute "__self__" is set to the\n object denoted by *alist*.\n\n Classes\n Classes are callable. These objects normally act as factories\n for new instances of themselves, but variations are possible for\n class types that override "__new__()". The arguments of the\n call are passed to "__new__()" and, in the typical case, to\n "__init__()" to initialize the new instance.\n\n Class Instances\n Instances of arbitrary classes can be made callable by defining\n a "__call__()" method in their class.\n\nModules\n Modules are a basic organizational unit of Python code, and are\n created by the *import system* as invoked either by the "import"\n statement (see "import"), or by calling functions such as\n "importlib.import_module()" and built-in "__import__()". A module\n object has a namespace implemented by a dictionary object (this is\n the dictionary referenced by the "__globals__" attribute of\n functions defined in the module). Attribute references are\n translated to lookups in this dictionary, e.g., "m.x" is equivalent\n to "m.__dict__["x"]". A module object does not contain the code\n object used to initialize the module (since it isn\'t needed once\n the initialization is done).\n\n Attribute assignment updates the module\'s namespace dictionary,\n e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n\n Special read-only attribute: "__dict__" is the module\'s namespace\n as a dictionary object.\n\n **CPython implementation detail:** Because of the way CPython\n clears module dictionaries, the module dictionary will be cleared\n when the module falls out of scope even if the dictionary still has\n live references. To avoid this, copy the dictionary or keep the\n module around while using its dictionary directly.\n\n Predefined (writable) attributes: "__name__" is the module\'s name;\n "__doc__" is the module\'s documentation string, or "None" if\n unavailable; "__file__" is the pathname of the file from which the\n module was loaded, if it was loaded from a file. The "__file__"\n attribute may be missing for certain types of modules, such as C\n modules that are statically linked into the interpreter; for\n extension modules loaded dynamically from a shared library, it is\n the pathname of the shared library file.\n\nCustom classes\n Custom class types are typically created by class definitions (see\n section *Class definitions*). A class has a namespace implemented\n by a dictionary object. Class attribute references are translated\n to lookups in this dictionary, e.g., "C.x" is translated to\n "C.__dict__["x"]" (although there are a number of hooks which allow\n for other means of locating attributes). When the attribute name is\n not found there, the attribute search continues in the base\n classes. This search of the base classes uses the C3 method\n resolution order which behaves correctly even in the presence of\n \'diamond\' inheritance structures where there are multiple\n inheritance paths leading back to a common ancestor. Additional\n details on the C3 MRO used by Python can be found in the\n documentation accompanying the 2.3 release at\n https://www.python.org/download/releases/2.3/mro/.\n\n When a class attribute reference (for class "C", say) would yield a\n class method object, it is transformed into an instance method\n object whose "__self__" attributes is "C". When it would yield a\n static method object, it is transformed into the object wrapped by\n the static method object. See section *Implementing Descriptors*\n for another way in which attributes retrieved from a class may\n differ from those actually contained in its "__dict__".\n\n Class attribute assignments update the class\'s dictionary, never\n the dictionary of a base class.\n\n A class object can be called (see above) to yield a class instance\n (see below).\n\n Special attributes: "__name__" is the class name; "__module__" is\n the module name in which the class was defined; "__dict__" is the\n dictionary containing the class\'s namespace; "__bases__" is a tuple\n (possibly empty or a singleton) containing the base classes, in the\n order of their occurrence in the base class list; "__doc__" is the\n class\'s documentation string, or None if undefined.\n\nClass instances\n A class instance is created by calling a class object (see above).\n A class instance has a namespace implemented as a dictionary which\n is the first place in which attribute references are searched.\n When an attribute is not found there, and the instance\'s class has\n an attribute by that name, the search continues with the class\n attributes. If a class attribute is found that is a user-defined\n function object, it is transformed into an instance method object\n whose "__self__" attribute is the instance. Static method and\n class method objects are also transformed; see above under\n "Classes". See section *Implementing Descriptors* for another way\n in which attributes of a class retrieved via its instances may\n differ from the objects actually stored in the class\'s "__dict__".\n If no class attribute is found, and the object\'s class has a\n "__getattr__()" method, that is called to satisfy the lookup.\n\n Attribute assignments and deletions update the instance\'s\n dictionary, never a class\'s dictionary. If the class has a\n "__setattr__()" or "__delattr__()" method, this is called instead\n of updating the instance dictionary directly.\n\n Class instances can pretend to be numbers, sequences, or mappings\n if they have methods with certain special names. See section\n *Special method names*.\n\n Special attributes: "__dict__" is the attribute dictionary;\n "__class__" is the instance\'s class.\n\nI/O objects (also known as file objects)\n A *file object* represents an open file. Various shortcuts are\n available to create file objects: the "open()" built-in function,\n and also "os.popen()", "os.fdopen()", and the "makefile()" method\n of socket objects (and perhaps by other functions or methods\n provided by extension modules).\n\n The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n initialized to file objects corresponding to the interpreter\'s\n standard input, output and error streams; they are all open in text\n mode and therefore follow the interface defined by the\n "io.TextIOBase" abstract class.\n\nInternal types\n A few types used internally by the interpreter are exposed to the\n user. Their definitions may change with future versions of the\n interpreter, but they are mentioned here for completeness.\n\n Code objects\n Code objects represent *byte-compiled* executable Python code,\n or *bytecode*. The difference between a code object and a\n function object is that the function object contains an explicit\n reference to the function\'s globals (the module in which it was\n defined), while a code object contains no context; also the\n default argument values are stored in the function object, not\n in the code object (because they represent values calculated at\n run-time). Unlike function objects, code objects are immutable\n and contain no references (directly or indirectly) to mutable\n objects.\n\n Special read-only attributes: "co_name" gives the function name;\n "co_argcount" is the number of positional arguments (including\n arguments with default values); "co_nlocals" is the number of\n local variables used by the function (including arguments);\n "co_varnames" is a tuple containing the names of the local\n variables (starting with the argument names); "co_cellvars" is a\n tuple containing the names of local variables that are\n referenced by nested functions; "co_freevars" is a tuple\n containing the names of free variables; "co_code" is a string\n representing the sequence of bytecode instructions; "co_consts"\n is a tuple containing the literals used by the bytecode;\n "co_names" is a tuple containing the names used by the bytecode;\n "co_filename" is the filename from which the code was compiled;\n "co_firstlineno" is the first line number of the function;\n "co_lnotab" is a string encoding the mapping from bytecode\n offsets to line numbers (for details see the source code of the\n interpreter); "co_stacksize" is the required stack size\n (including local variables); "co_flags" is an integer encoding a\n number of flags for the interpreter.\n\n The following flag bits are defined for "co_flags": bit "0x04"\n is set if the function uses the "*arguments" syntax to accept an\n arbitrary number of positional arguments; bit "0x08" is set if\n the function uses the "**keywords" syntax to accept arbitrary\n keyword arguments; bit "0x20" is set if the function is a\n generator.\n\n Future feature declarations ("from __future__ import division")\n also use bits in "co_flags" to indicate whether a code object\n was compiled with a particular feature enabled: bit "0x2000" is\n set if the function was compiled with future division enabled;\n bits "0x10" and "0x1000" were used in earlier versions of\n Python.\n\n Other bits in "co_flags" are reserved for internal use.\n\n If a code object represents a function, the first item in\n "co_consts" is the documentation string of the function, or\n "None" if undefined.\n\n Frame objects\n Frame objects represent execution frames. They may occur in\n traceback objects (see below).\n\n Special read-only attributes: "f_back" is to the previous stack\n frame (towards the caller), or "None" if this is the bottom\n stack frame; "f_code" is the code object being executed in this\n frame; "f_locals" is the dictionary used to look up local\n variables; "f_globals" is used for global variables;\n "f_builtins" is used for built-in (intrinsic) names; "f_lasti"\n gives the precise instruction (this is an index into the\n bytecode string of the code object).\n\n Special writable attributes: "f_trace", if not "None", is a\n function called at the start of each source code line (this is\n used by the debugger); "f_lineno" is the current line number of\n the frame --- writing to this from within a trace function jumps\n to the given line (only for the bottom-most frame). A debugger\n can implement a Jump command (aka Set Next Statement) by writing\n to f_lineno.\n\n Frame objects support one method:\n\n frame.clear()\n\n This method clears all references to local variables held by\n the frame. Also, if the frame belonged to a generator, the\n generator is finalized. This helps break reference cycles\n involving frame objects (for example when catching an\n exception and storing its traceback for later use).\n\n "RuntimeError" is raised if the frame is currently executing.\n\n New in version 3.4.\n\n Traceback objects\n Traceback objects represent a stack trace of an exception. A\n traceback object is created when an exception occurs. When the\n search for an exception handler unwinds the execution stack, at\n each unwound level a traceback object is inserted in front of\n the current traceback. When an exception handler is entered,\n the stack trace is made available to the program. (See section\n *The try statement*.) It is accessible as the third item of the\n tuple returned by "sys.exc_info()". When the program contains no\n suitable handler, the stack trace is written (nicely formatted)\n to the standard error stream; if the interpreter is interactive,\n it is also made available to the user as "sys.last_traceback".\n\n Special read-only attributes: "tb_next" is the next level in the\n stack trace (towards the frame where the exception occurred), or\n "None" if there is no next level; "tb_frame" points to the\n execution frame of the current level; "tb_lineno" gives the line\n number where the exception occurred; "tb_lasti" indicates the\n precise instruction. The line number and last instruction in\n the traceback may differ from the line number of its frame\n object if the exception occurred in a "try" statement with no\n matching except clause or with a finally clause.\n\n Slice objects\n Slice objects are used to represent slices for "__getitem__()"\n methods. They are also created by the built-in "slice()"\n function.\n\n Special read-only attributes: "start" is the lower bound; "stop"\n is the upper bound; "step" is the step value; each is "None" if\n omitted. These attributes can have any type.\n\n Slice objects support one method:\n\n slice.indices(self, length)\n\n This method takes a single integer argument *length* and\n computes information about the slice that the slice object\n would describe if applied to a sequence of *length* items.\n It returns a tuple of three integers; respectively these are\n the *start* and *stop* indices and the *step* or stride\n length of the slice. Missing or out-of-bounds indices are\n handled in a manner consistent with regular slices.\n\n Static method objects\n Static method objects provide a way of defeating the\n transformation of function objects to method objects described\n above. A static method object is a wrapper around any other\n object, usually a user-defined method object. When a static\n method object is retrieved from a class or a class instance, the\n object actually returned is the wrapped object, which is not\n subject to any further transformation. Static method objects are\n not themselves callable, although the objects they wrap usually\n are. Static method objects are created by the built-in\n "staticmethod()" constructor.\n\n Class method objects\n A class method object, like a static method object, is a wrapper\n around another object that alters the way in which that object\n is retrieved from classes and class instances. The behaviour of\n class method objects upon such retrieval is described above,\n under "User-defined methods". Class method objects are created\n by the built-in "classmethod()" constructor.\n', - 'typesfunctions': u'\nFunctions\n*********\n\nFunction objects are created by function definitions. The only\noperation on a function object is to call it: "func(argument-list)".\n\nThere are really two flavors of function objects: built-in functions\nand user-defined functions. Both support the same operation (to call\nthe function), but the implementation is different, hence the\ndifferent object types.\n\nSee *Function definitions* for more information.\n', - 'typesmapping': u'\nMapping Types --- "dict"\n************************\n\nA *mapping* object maps *hashable* values to arbitrary objects.\nMappings are mutable objects. There is currently only one standard\nmapping type, the *dictionary*. (For other containers see the built-\nin "list", "set", and "tuple" classes, and the "collections" module.)\n\nA dictionary\'s keys are *almost* arbitrary values. Values that are\nnot *hashable*, that is, values containing lists, dictionaries or\nother mutable types (that are compared by value rather than by object\nidentity) may not be used as keys. Numeric types used for keys obey\nthe normal rules for numeric comparison: if two numbers compare equal\n(such as "1" and "1.0") then they can be used interchangeably to index\nthe same dictionary entry. (Note however, that since computers store\nfloating-point numbers as approximations it is usually unwise to use\nthem as dictionary keys.)\n\nDictionaries can be created by placing a comma-separated list of "key:\nvalue" pairs within braces, for example: "{\'jack\': 4098, \'sjoerd\':\n4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the "dict"\nconstructor.\n\nclass class dict(**kwarg)\nclass class dict(mapping, **kwarg)\nclass class dict(iterable, **kwarg)\n\n Return a new dictionary initialized from an optional positional\n argument and a possibly empty set of keyword arguments.\n\n If no positional argument is given, an empty dictionary is created.\n If a positional argument is given and it is a mapping object, a\n dictionary is created with the same key-value pairs as the mapping\n object. Otherwise, the positional argument must be an *iterable*\n object. Each item in the iterable must itself be an iterable with\n exactly two objects. The first object of each item becomes a key\n in the new dictionary, and the second object the corresponding\n value. If a key occurs more than once, the last value for that key\n becomes the corresponding value in the new dictionary.\n\n If keyword arguments are given, the keyword arguments and their\n values are added to the dictionary created from the positional\n argument. If a key being added is already present, the value from\n the keyword argument replaces the value from the positional\n argument.\n\n To illustrate, the following examples all return a dictionary equal\n to "{"one": 1, "two": 2, "three": 3}":\n\n >>> a = dict(one=1, two=2, three=3)\n >>> b = {\'one\': 1, \'two\': 2, \'three\': 3}\n >>> c = dict(zip([\'one\', \'two\', \'three\'], [1, 2, 3]))\n >>> d = dict([(\'two\', 2), (\'one\', 1), (\'three\', 3)])\n >>> e = dict({\'three\': 3, \'one\': 1, \'two\': 2})\n >>> a == b == c == d == e\n True\n\n Providing keyword arguments as in the first example only works for\n keys that are valid Python identifiers. Otherwise, any valid keys\n can be used.\n\n These are the operations that dictionaries support (and therefore,\n custom mapping types should support too):\n\n len(d)\n\n Return the number of items in the dictionary *d*.\n\n d[key]\n\n Return the item of *d* with key *key*. Raises a "KeyError" if\n *key* is not in the map.\n\n If a subclass of dict defines a method "__missing__()" and *key*\n is not present, the "d[key]" operation calls that method with\n the key *key* as argument. The "d[key]" operation then returns\n or raises whatever is returned or raised by the\n "__missing__(key)" call. No other operations or methods invoke\n "__missing__()". If "__missing__()" is not defined, "KeyError"\n is raised. "__missing__()" must be a method; it cannot be an\n instance variable:\n\n >>> class Counter(dict):\n ... def __missing__(self, key):\n ... return 0\n >>> c = Counter()\n >>> c[\'red\']\n 0\n >>> c[\'red\'] += 1\n >>> c[\'red\']\n 1\n\n The example above shows part of the implementation of\n "collections.Counter". A different "__missing__" method is used\n by "collections.defaultdict".\n\n d[key] = value\n\n Set "d[key]" to *value*.\n\n del d[key]\n\n Remove "d[key]" from *d*. Raises a "KeyError" if *key* is not\n in the map.\n\n key in d\n\n Return "True" if *d* has a key *key*, else "False".\n\n key not in d\n\n Equivalent to "not key in d".\n\n iter(d)\n\n Return an iterator over the keys of the dictionary. This is a\n shortcut for "iter(d.keys())".\n\n clear()\n\n Remove all items from the dictionary.\n\n copy()\n\n Return a shallow copy of the dictionary.\n\n classmethod fromkeys(seq[, value])\n\n Create a new dictionary with keys from *seq* and values set to\n *value*.\n\n "fromkeys()" is a class method that returns a new dictionary.\n *value* defaults to "None".\n\n get(key[, default])\n\n Return the value for *key* if *key* is in the dictionary, else\n *default*. If *default* is not given, it defaults to "None", so\n that this method never raises a "KeyError".\n\n items()\n\n Return a new view of the dictionary\'s items ("(key, value)"\n pairs). See the *documentation of view objects*.\n\n keys()\n\n Return a new view of the dictionary\'s keys. See the\n *documentation of view objects*.\n\n pop(key[, default])\n\n If *key* is in the dictionary, remove it and return its value,\n else return *default*. If *default* is not given and *key* is\n not in the dictionary, a "KeyError" is raised.\n\n popitem()\n\n Remove and return an arbitrary "(key, value)" pair from the\n dictionary.\n\n "popitem()" is useful to destructively iterate over a\n dictionary, as often used in set algorithms. If the dictionary\n is empty, calling "popitem()" raises a "KeyError".\n\n setdefault(key[, default])\n\n If *key* is in the dictionary, return its value. If not, insert\n *key* with a value of *default* and return *default*. *default*\n defaults to "None".\n\n update([other])\n\n Update the dictionary with the key/value pairs from *other*,\n overwriting existing keys. Return "None".\n\n "update()" accepts either another dictionary object or an\n iterable of key/value pairs (as tuples or other iterables of\n length two). If keyword arguments are specified, the dictionary\n is then updated with those key/value pairs: "d.update(red=1,\n blue=2)".\n\n values()\n\n Return a new view of the dictionary\'s values. See the\n *documentation of view objects*.\n\n Dictionaries compare equal if and only if they have the same "(key,\n value)" pairs. Order comparisons (\'<\', \'<=\', \'>=\', \'>\') raise\n "TypeError".\n\nSee also: "types.MappingProxyType" can be used to create a read-only\n view of a "dict".\n\n\nDictionary view objects\n=======================\n\nThe objects returned by "dict.keys()", "dict.values()" and\n"dict.items()" are *view objects*. They provide a dynamic view on the\ndictionary\'s entries, which means that when the dictionary changes,\nthe view reflects these changes.\n\nDictionary views can be iterated over to yield their respective data,\nand support membership tests:\n\nlen(dictview)\n\n Return the number of entries in the dictionary.\n\niter(dictview)\n\n Return an iterator over the keys, values or items (represented as\n tuples of "(key, value)") in the dictionary.\n\n Keys and values are iterated over in an arbitrary order which is\n non-random, varies across Python implementations, and depends on\n the dictionary\'s history of insertions and deletions. If keys,\n values and items views are iterated over with no intervening\n modifications to the dictionary, the order of items will directly\n correspond. This allows the creation of "(value, key)" pairs using\n "zip()": "pairs = zip(d.values(), d.keys())". Another way to\n create the same list is "pairs = [(v, k) for (k, v) in d.items()]".\n\n Iterating views while adding or deleting entries in the dictionary\n may raise a "RuntimeError" or fail to iterate over all entries.\n\nx in dictview\n\n Return "True" if *x* is in the underlying dictionary\'s keys, values\n or items (in the latter case, *x* should be a "(key, value)"\n tuple).\n\nKeys views are set-like since their entries are unique and hashable.\nIf all values are hashable, so that "(key, value)" pairs are unique\nand hashable, then the items view is also set-like. (Values views are\nnot treated as set-like since the entries are generally not unique.)\nFor set-like views, all of the operations defined for the abstract\nbase class "collections.abc.Set" are available (for example, "==",\n"<", or "^").\n\nAn example of dictionary view usage:\n\n >>> dishes = {\'eggs\': 2, \'sausage\': 1, \'bacon\': 1, \'spam\': 500}\n >>> keys = dishes.keys()\n >>> values = dishes.values()\n\n >>> # iteration\n >>> n = 0\n >>> for val in values:\n ... n += val\n >>> print(n)\n 504\n\n >>> # keys and values are iterated over in the same order\n >>> list(keys)\n [\'eggs\', \'bacon\', \'sausage\', \'spam\']\n >>> list(values)\n [2, 1, 1, 500]\n\n >>> # view objects are dynamic and reflect dict changes\n >>> del dishes[\'eggs\']\n >>> del dishes[\'sausage\']\n >>> list(keys)\n [\'spam\', \'bacon\']\n\n >>> # set operations\n >>> keys & {\'eggs\', \'bacon\', \'salad\'}\n {\'bacon\'}\n >>> keys ^ {\'sausage\', \'juice\'}\n {\'juice\', \'sausage\', \'bacon\', \'spam\'}\n', - 'typesmethods': u'\nMethods\n*******\n\nMethods are functions that are called using the attribute notation.\nThere are two flavors: built-in methods (such as "append()" on lists)\nand class instance methods. Built-in methods are described with the\ntypes that support them.\n\nIf you access a method (a function defined in a class namespace)\nthrough an instance, you get a special object: a *bound method* (also\ncalled *instance method*) object. When called, it will add the "self"\nargument to the argument list. Bound methods have two special read-\nonly attributes: "m.__self__" is the object on which the method\noperates, and "m.__func__" is the function implementing the method.\nCalling "m(arg-1, arg-2, ..., arg-n)" is completely equivalent to\ncalling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n\nLike function objects, bound method objects support getting arbitrary\nattributes. However, since method attributes are actually stored on\nthe underlying function object ("meth.__func__"), setting method\nattributes on bound methods is disallowed. Attempting to set an\nattribute on a method results in an "AttributeError" being raised. In\norder to set a method attribute, you need to explicitly set it on the\nunderlying function object:\n\n >>> class C:\n ... def method(self):\n ... pass\n ...\n >>> c = C()\n >>> c.method.whoami = \'my name is method\' # can\'t set on the method\n Traceback (most recent call last):\n File "", line 1, in \n AttributeError: \'method\' object has no attribute \'whoami\'\n >>> c.method.__func__.whoami = \'my name is method\'\n >>> c.method.whoami\n \'my name is method\'\n\nSee *The standard type hierarchy* for more information.\n', - 'typesmodules': u'\nModules\n*******\n\nThe only special operation on a module is attribute access: "m.name",\nwhere *m* is a module and *name* accesses a name defined in *m*\'s\nsymbol table. Module attributes can be assigned to. (Note that the\n"import" statement is not, strictly speaking, an operation on a module\nobject; "import foo" does not require a module object named *foo* to\nexist, rather it requires an (external) *definition* for a module\nnamed *foo* somewhere.)\n\nA special attribute of every module is "__dict__". This is the\ndictionary containing the module\'s symbol table. Modifying this\ndictionary will actually change the module\'s symbol table, but direct\nassignment to the "__dict__" attribute is not possible (you can write\n"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but you can\'t\nwrite "m.__dict__ = {}"). Modifying "__dict__" directly is not\nrecommended.\n\nModules built into the interpreter are written like this: "". If loaded from a file, they are written as\n"".\n', - 'typesseq': u'\nSequence Types --- "list", "tuple", "range"\n*******************************************\n\nThere are three basic sequence types: lists, tuples, and range\nobjects. Additional sequence types tailored for processing of *binary\ndata* and *text strings* are described in dedicated sections.\n\n\nCommon Sequence Operations\n==========================\n\nThe operations in the following table are supported by most sequence\ntypes, both mutable and immutable. The "collections.abc.Sequence" ABC\nis provided to make it easier to correctly implement these operations\non custom sequence types.\n\nThis table lists the sequence operations sorted in ascending priority.\nIn the table, *s* and *t* are sequences of the same type, *n*, *i*,\n*j* and *k* are integers and *x* is an arbitrary object that meets any\ntype and value restrictions imposed by *s*.\n\nThe "in" and "not in" operations have the same priorities as the\ncomparison operations. The "+" (concatenation) and "*" (repetition)\noperations have the same priority as the corresponding numeric\noperations.\n\n+----------------------------+----------------------------------+------------+\n| Operation | Result | Notes |\n+============================+==================================+============+\n| "x in s" | "True" if an item of *s* is | (1) |\n| | equal to *x*, else "False" | |\n+----------------------------+----------------------------------+------------+\n| "x not in s" | "False" if an item of *s* is | (1) |\n| | equal to *x*, else "True" | |\n+----------------------------+----------------------------------+------------+\n| "s + t" | the concatenation of *s* and *t* | (6)(7) |\n+----------------------------+----------------------------------+------------+\n| "s * n" or "n * s" | equivalent to adding *s* to | (2)(7) |\n| | itself *n* times | |\n+----------------------------+----------------------------------+------------+\n| "s[i]" | *i*th item of *s*, origin 0 | (3) |\n+----------------------------+----------------------------------+------------+\n| "s[i:j]" | slice of *s* from *i* to *j* | (3)(4) |\n+----------------------------+----------------------------------+------------+\n| "s[i:j:k]" | slice of *s* from *i* to *j* | (3)(5) |\n| | with step *k* | |\n+----------------------------+----------------------------------+------------+\n| "len(s)" | length of *s* | |\n+----------------------------+----------------------------------+------------+\n| "min(s)" | smallest item of *s* | |\n+----------------------------+----------------------------------+------------+\n| "max(s)" | largest item of *s* | |\n+----------------------------+----------------------------------+------------+\n| "s.index(x[, i[, j]])" | index of the first occurrence of | (8) |\n| | *x* in *s* (at or after index | |\n| | *i* and before index *j*) | |\n+----------------------------+----------------------------------+------------+\n| "s.count(x)" | total number of occurrences of | |\n| | *x* in *s* | |\n+----------------------------+----------------------------------+------------+\n\nSequences of the same type also support comparisons. In particular,\ntuples and lists are compared lexicographically by comparing\ncorresponding elements. This means that to compare equal, every\nelement must compare equal and the two sequences must be of the same\ntype and have the same length. (For full details see *Comparisons* in\nthe language reference.)\n\nNotes:\n\n1. While the "in" and "not in" operations are used only for simple\n containment testing in the general case, some specialised sequences\n (such as "str", "bytes" and "bytearray") also use them for\n subsequence testing:\n\n >>> "gg" in "eggs"\n True\n\n2. Values of *n* less than "0" are treated as "0" (which yields an\n empty sequence of the same type as *s*). Note that items in the\n sequence *s* are not copied; they are referenced multiple times.\n This often haunts new Python programmers; consider:\n\n >>> lists = [[]] * 3\n >>> lists\n [[], [], []]\n >>> lists[0].append(3)\n >>> lists\n [[3], [3], [3]]\n\n What has happened is that "[[]]" is a one-element list containing\n an empty list, so all three elements of "[[]] * 3" are references\n to this single empty list. Modifying any of the elements of\n "lists" modifies this single list. You can create a list of\n different lists this way:\n\n >>> lists = [[] for i in range(3)]\n >>> lists[0].append(3)\n >>> lists[1].append(5)\n >>> lists[2].append(7)\n >>> lists\n [[3], [5], [7]]\n\n Further explanation is available in the FAQ entry *How do I create\n a multidimensional list?*.\n\n3. If *i* or *j* is negative, the index is relative to the end of\n the string: "len(s) + i" or "len(s) + j" is substituted. But note\n that "-0" is still "0".\n\n4. The slice of *s* from *i* to *j* is defined as the sequence of\n items with index *k* such that "i <= k < j". If *i* or *j* is\n greater than "len(s)", use "len(s)". If *i* is omitted or "None",\n use "0". If *j* is omitted or "None", use "len(s)". If *i* is\n greater than or equal to *j*, the slice is empty.\n\n5. The slice of *s* from *i* to *j* with step *k* is defined as the\n sequence of items with index "x = i + n*k" such that "0 <= n <\n (j-i)/k". In other words, the indices are "i", "i+k", "i+2*k",\n "i+3*k" and so on, stopping when *j* is reached (but never\n including *j*). If *i* or *j* is greater than "len(s)", use\n "len(s)". If *i* or *j* are omitted or "None", they become "end"\n values (which end depends on the sign of *k*). Note, *k* cannot be\n zero. If *k* is "None", it is treated like "1".\n\n6. Concatenating immutable sequences always results in a new\n object. This means that building up a sequence by repeated\n concatenation will have a quadratic runtime cost in the total\n sequence length. To get a linear runtime cost, you must switch to\n one of the alternatives below:\n\n * if concatenating "str" objects, you can build a list and use\n "str.join()" at the end or else write to an "io.StringIO"\n instance and retrieve its value when complete\n\n * if concatenating "bytes" objects, you can similarly use\n "bytes.join()" or "io.BytesIO", or you can do in-place\n concatenation with a "bytearray" object. "bytearray" objects are\n mutable and have an efficient overallocation mechanism\n\n * if concatenating "tuple" objects, extend a "list" instead\n\n * for other types, investigate the relevant class documentation\n\n7. Some sequence types (such as "range") only support item\n sequences that follow specific patterns, and hence don\'t support\n sequence concatenation or repetition.\n\n8. "index" raises "ValueError" when *x* is not found in *s*. When\n supported, the additional arguments to the index method allow\n efficient searching of subsections of the sequence. Passing the\n extra arguments is roughly equivalent to using "s[i:j].index(x)",\n only without copying any data and with the returned index being\n relative to the start of the sequence rather than the start of the\n slice.\n\n\nImmutable Sequence Types\n========================\n\nThe only operation that immutable sequence types generally implement\nthat is not also implemented by mutable sequence types is support for\nthe "hash()" built-in.\n\nThis support allows immutable sequences, such as "tuple" instances, to\nbe used as "dict" keys and stored in "set" and "frozenset" instances.\n\nAttempting to hash an immutable sequence that contains unhashable\nvalues will result in "TypeError".\n\n\nMutable Sequence Types\n======================\n\nThe operations in the following table are defined on mutable sequence\ntypes. The "collections.abc.MutableSequence" ABC is provided to make\nit easier to correctly implement these operations on custom sequence\ntypes.\n\nIn the table *s* is an instance of a mutable sequence type, *t* is any\niterable object and *x* is an arbitrary object that meets any type and\nvalue restrictions imposed by *s* (for example, "bytearray" only\naccepts integers that meet the value restriction "0 <= x <= 255").\n\n+--------------------------------+----------------------------------+-----------------------+\n| Operation | Result | Notes |\n+================================+==================================+=======================+\n| "s[i] = x" | item *i* of *s* is replaced by | |\n| | *x* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j] = t" | slice of *s* from *i* to *j* is | |\n| | replaced by the contents of the | |\n| | iterable *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j]" | same as "s[i:j] = []" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j:k] = t" | the elements of "s[i:j:k]" are | (1) |\n| | replaced by those of *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j:k]" | removes the elements of | |\n| | "s[i:j:k]" from the list | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.append(x)" | appends *x* to the end of the | |\n| | sequence (same as | |\n| | "s[len(s):len(s)] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.clear()" | removes all items from "s" (same | (5) |\n| | as "del s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.copy()" | creates a shallow copy of "s" | (5) |\n| | (same as "s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.extend(t)" or "s += t" | extends *s* with the contents of | |\n| | *t* (for the most part the same | |\n| | as "s[len(s):len(s)] = t") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s *= n" | updates *s* with its contents | (6) |\n| | repeated *n* times | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.insert(i, x)" | inserts *x* into *s* at the | |\n| | index given by *i* (same as | |\n| | "s[i:i] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.pop([i])" | retrieves the item at *i* and | (2) |\n| | also removes it from *s* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.remove(x)" | remove the first item from *s* | (3) |\n| | where "s[i] == x" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.reverse()" | reverses the items of *s* in | (4) |\n| | place | |\n+--------------------------------+----------------------------------+-----------------------+\n\nNotes:\n\n1. *t* must have the same length as the slice it is replacing.\n\n2. The optional argument *i* defaults to "-1", so that by default\n the last item is removed and returned.\n\n3. "remove" raises "ValueError" when *x* is not found in *s*.\n\n4. The "reverse()" method modifies the sequence in place for\n economy of space when reversing a large sequence. To remind users\n that it operates by side effect, it does not return the reversed\n sequence.\n\n5. "clear()" and "copy()" are included for consistency with the\n interfaces of mutable containers that don\'t support slicing\n operations (such as "dict" and "set")\n\n New in version 3.3: "clear()" and "copy()" methods.\n\n6. The value *n* is an integer, or an object implementing\n "__index__()". Zero and negative values of *n* clear the sequence.\n Items in the sequence are not copied; they are referenced multiple\n times, as explained for "s * n" under *Common Sequence Operations*.\n\n\nLists\n=====\n\nLists are mutable sequences, typically used to store collections of\nhomogeneous items (where the precise degree of similarity will vary by\napplication).\n\nclass class list([iterable])\n\n Lists may be constructed in several ways:\n\n * Using a pair of square brackets to denote the empty list: "[]"\n\n * Using square brackets, separating items with commas: "[a]",\n "[a, b, c]"\n\n * Using a list comprehension: "[x for x in iterable]"\n\n * Using the type constructor: "list()" or "list(iterable)"\n\n The constructor builds a list whose items are the same and in the\n same order as *iterable*\'s items. *iterable* may be either a\n sequence, a container that supports iteration, or an iterator\n object. If *iterable* is already a list, a copy is made and\n returned, similar to "iterable[:]". For example, "list(\'abc\')"\n returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" returns "[1, 2,\n 3]". If no argument is given, the constructor creates a new empty\n list, "[]".\n\n Many other operations also produce lists, including the "sorted()"\n built-in.\n\n Lists implement all of the *common* and *mutable* sequence\n operations. Lists also provide the following additional method:\n\n sort(*, key=None, reverse=None)\n\n This method sorts the list in place, using only "<" comparisons\n between items. Exceptions are not suppressed - if any comparison\n operations fail, the entire sort operation will fail (and the\n list will likely be left in a partially modified state).\n\n "sort()" accepts two arguments that can only be passed by\n keyword (*keyword-only arguments*):\n\n *key* specifies a function of one argument that is used to\n extract a comparison key from each list element (for example,\n "key=str.lower"). The key corresponding to each item in the list\n is calculated once and then used for the entire sorting process.\n The default value of "None" means that list items are sorted\n directly without calculating a separate key value.\n\n The "functools.cmp_to_key()" utility is available to convert a\n 2.x style *cmp* function to a *key* function.\n\n *reverse* is a boolean value. If set to "True", then the list\n elements are sorted as if each comparison were reversed.\n\n This method modifies the sequence in place for economy of space\n when sorting a large sequence. To remind users that it operates\n by side effect, it does not return the sorted sequence (use\n "sorted()" to explicitly request a new sorted list instance).\n\n The "sort()" method is guaranteed to be stable. A sort is\n stable if it guarantees not to change the relative order of\n elements that compare equal --- this is helpful for sorting in\n multiple passes (for example, sort by department, then by salary\n grade).\n\n **CPython implementation detail:** While a list is being sorted,\n the effect of attempting to mutate, or even inspect, the list is\n undefined. The C implementation of Python makes the list appear\n empty for the duration, and raises "ValueError" if it can detect\n that the list has been mutated during a sort.\n\n\nTuples\n======\n\nTuples are immutable sequences, typically used to store collections of\nheterogeneous data (such as the 2-tuples produced by the "enumerate()"\nbuilt-in). Tuples are also used for cases where an immutable sequence\nof homogeneous data is needed (such as allowing storage in a "set" or\n"dict" instance).\n\nclass class tuple([iterable])\n\n Tuples may be constructed in a number of ways:\n\n * Using a pair of parentheses to denote the empty tuple: "()"\n\n * Using a trailing comma for a singleton tuple: "a," or "(a,)"\n\n * Separating items with commas: "a, b, c" or "(a, b, c)"\n\n * Using the "tuple()" built-in: "tuple()" or "tuple(iterable)"\n\n The constructor builds a tuple whose items are the same and in the\n same order as *iterable*\'s items. *iterable* may be either a\n sequence, a container that supports iteration, or an iterator\n object. If *iterable* is already a tuple, it is returned\n unchanged. For example, "tuple(\'abc\')" returns "(\'a\', \'b\', \'c\')"\n and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument is\n given, the constructor creates a new empty tuple, "()".\n\n Note that it is actually the comma which makes a tuple, not the\n parentheses. The parentheses are optional, except in the empty\n tuple case, or when they are needed to avoid syntactic ambiguity.\n For example, "f(a, b, c)" is a function call with three arguments,\n while "f((a, b, c))" is a function call with a 3-tuple as the sole\n argument.\n\n Tuples implement all of the *common* sequence operations.\n\nFor heterogeneous collections of data where access by name is clearer\nthan access by index, "collections.namedtuple()" may be a more\nappropriate choice than a simple tuple object.\n\n\nRanges\n======\n\nThe "range" type represents an immutable sequence of numbers and is\ncommonly used for looping a specific number of times in "for" loops.\n\nclass class range(stop)\nclass class range(start, stop[, step])\n\n The arguments to the range constructor must be integers (either\n built-in "int" or any object that implements the "__index__"\n special method). If the *step* argument is omitted, it defaults to\n "1". If the *start* argument is omitted, it defaults to "0". If\n *step* is zero, "ValueError" is raised.\n\n For a positive *step*, the contents of a range "r" are determined\n by the formula "r[i] = start + step*i" where "i >= 0" and "r[i] <\n stop".\n\n For a negative *step*, the contents of the range are still\n determined by the formula "r[i] = start + step*i", but the\n constraints are "i >= 0" and "r[i] > stop".\n\n A range object will be empty if "r[0]" does not meet the value\n constraint. Ranges do support negative indices, but these are\n interpreted as indexing from the end of the sequence determined by\n the positive indices.\n\n Ranges containing absolute values larger than "sys.maxsize" are\n permitted but some features (such as "len()") may raise\n "OverflowError".\n\n Range examples:\n\n >>> list(range(10))\n [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n >>> list(range(1, 11))\n [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n >>> list(range(0, 30, 5))\n [0, 5, 10, 15, 20, 25]\n >>> list(range(0, 10, 3))\n [0, 3, 6, 9]\n >>> list(range(0, -10, -1))\n [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n >>> list(range(0))\n []\n >>> list(range(1, 0))\n []\n\n Ranges implement all of the *common* sequence operations except\n concatenation and repetition (due to the fact that range objects\n can only represent sequences that follow a strict pattern and\n repetition and concatenation will usually violate that pattern).\n\nThe advantage of the "range" type over a regular "list" or "tuple" is\nthat a "range" object will always take the same (small) amount of\nmemory, no matter the size of the range it represents (as it only\nstores the "start", "stop" and "step" values, calculating individual\nitems and subranges as needed).\n\nRange objects implement the "collections.abc.Sequence" ABC, and\nprovide features such as containment tests, element index lookup,\nslicing and support for negative indices (see *Sequence Types ---\nlist, tuple, range*):\n\n>>> r = range(0, 20, 2)\n>>> r\nrange(0, 20, 2)\n>>> 11 in r\nFalse\n>>> 10 in r\nTrue\n>>> r.index(10)\n5\n>>> r[5]\n10\n>>> r[:5]\nrange(0, 10, 2)\n>>> r[-1]\n18\n\nTesting range objects for equality with "==" and "!=" compares them as\nsequences. That is, two range objects are considered equal if they\nrepresent the same sequence of values. (Note that two range objects\nthat compare equal might have different "start", "stop" and "step"\nattributes, for example "range(0) == range(2, 1, 3)" or "range(0, 3,\n2) == range(0, 4, 2)".)\n\nChanged in version 3.2: Implement the Sequence ABC. Support slicing\nand negative indices. Test "int" objects for membership in constant\ntime instead of iterating through all items.\n\nChanged in version 3.3: Define \'==\' and \'!=\' to compare range objects\nbased on the sequence of values they define (instead of comparing\nbased on object identity).\n\nNew in version 3.3: The "start", "stop" and "step" attributes.\n', - 'typesseq-mutable': u'\nMutable Sequence Types\n**********************\n\nThe operations in the following table are defined on mutable sequence\ntypes. The "collections.abc.MutableSequence" ABC is provided to make\nit easier to correctly implement these operations on custom sequence\ntypes.\n\nIn the table *s* is an instance of a mutable sequence type, *t* is any\niterable object and *x* is an arbitrary object that meets any type and\nvalue restrictions imposed by *s* (for example, "bytearray" only\naccepts integers that meet the value restriction "0 <= x <= 255").\n\n+--------------------------------+----------------------------------+-----------------------+\n| Operation | Result | Notes |\n+================================+==================================+=======================+\n| "s[i] = x" | item *i* of *s* is replaced by | |\n| | *x* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j] = t" | slice of *s* from *i* to *j* is | |\n| | replaced by the contents of the | |\n| | iterable *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j]" | same as "s[i:j] = []" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j:k] = t" | the elements of "s[i:j:k]" are | (1) |\n| | replaced by those of *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j:k]" | removes the elements of | |\n| | "s[i:j:k]" from the list | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.append(x)" | appends *x* to the end of the | |\n| | sequence (same as | |\n| | "s[len(s):len(s)] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.clear()" | removes all items from "s" (same | (5) |\n| | as "del s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.copy()" | creates a shallow copy of "s" | (5) |\n| | (same as "s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.extend(t)" or "s += t" | extends *s* with the contents of | |\n| | *t* (for the most part the same | |\n| | as "s[len(s):len(s)] = t") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s *= n" | updates *s* with its contents | (6) |\n| | repeated *n* times | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.insert(i, x)" | inserts *x* into *s* at the | |\n| | index given by *i* (same as | |\n| | "s[i:i] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.pop([i])" | retrieves the item at *i* and | (2) |\n| | also removes it from *s* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.remove(x)" | remove the first item from *s* | (3) |\n| | where "s[i] == x" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.reverse()" | reverses the items of *s* in | (4) |\n| | place | |\n+--------------------------------+----------------------------------+-----------------------+\n\nNotes:\n\n1. *t* must have the same length as the slice it is replacing.\n\n2. The optional argument *i* defaults to "-1", so that by default\n the last item is removed and returned.\n\n3. "remove" raises "ValueError" when *x* is not found in *s*.\n\n4. The "reverse()" method modifies the sequence in place for\n economy of space when reversing a large sequence. To remind users\n that it operates by side effect, it does not return the reversed\n sequence.\n\n5. "clear()" and "copy()" are included for consistency with the\n interfaces of mutable containers that don\'t support slicing\n operations (such as "dict" and "set")\n\n New in version 3.3: "clear()" and "copy()" methods.\n\n6. The value *n* is an integer, or an object implementing\n "__index__()". Zero and negative values of *n* clear the sequence.\n Items in the sequence are not copied; they are referenced multiple\n times, as explained for "s * n" under *Common Sequence Operations*.\n', - 'unary': u'\nUnary arithmetic and bitwise operations\n***************************************\n\nAll unary arithmetic and bitwise operations have the same priority:\n\n u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n\nThe unary "-" (minus) operator yields the negation of its numeric\nargument.\n\nThe unary "+" (plus) operator yields its numeric argument unchanged.\n\nThe unary "~" (invert) operator yields the bitwise inversion of its\ninteger argument. The bitwise inversion of "x" is defined as\n"-(x+1)". It only applies to integral numbers.\n\nIn all three cases, if the argument does not have the proper type, a\n"TypeError" exception is raised.\n', - 'while': u'\nThe "while" statement\n*********************\n\nThe "while" statement is used for repeated execution as long as an\nexpression is true:\n\n while_stmt ::= "while" expression ":" suite\n ["else" ":" suite]\n\nThis repeatedly tests the expression and, if it is true, executes the\nfirst suite; if the expression is false (which may be the first time\nit is tested) the suite of the "else" clause, if present, is executed\nand the loop terminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and goes back\nto testing the expression.\n', - 'with': u'\nThe "with" statement\n********************\n\nThe "with" statement is used to wrap the execution of a block with\nmethods defined by a context manager (see section *With Statement\nContext Managers*). This allows common "try"..."except"..."finally"\nusage patterns to be encapsulated for convenient reuse.\n\n with_stmt ::= "with" with_item ("," with_item)* ":" suite\n with_item ::= expression ["as" target]\n\nThe execution of the "with" statement with one "item" proceeds as\nfollows:\n\n1. The context expression (the expression given in the "with_item")\n is evaluated to obtain a context manager.\n\n2. The context manager\'s "__exit__()" is loaded for later use.\n\n3. The context manager\'s "__enter__()" method is invoked.\n\n4. If a target was included in the "with" statement, the return\n value from "__enter__()" is assigned to it.\n\n Note: The "with" statement guarantees that if the "__enter__()"\n method returns without an error, then "__exit__()" will always be\n called. Thus, if an error occurs during the assignment to the\n target list, it will be treated the same as an error occurring\n within the suite would be. See step 6 below.\n\n5. The suite is executed.\n\n6. The context manager\'s "__exit__()" method is invoked. If an\n exception caused the suite to be exited, its type, value, and\n traceback are passed as arguments to "__exit__()". Otherwise, three\n "None" arguments are supplied.\n\n If the suite was exited due to an exception, and the return value\n from the "__exit__()" method was false, the exception is reraised.\n If the return value was true, the exception is suppressed, and\n execution continues with the statement following the "with"\n statement.\n\n If the suite was exited for any reason other than an exception, the\n return value from "__exit__()" is ignored, and execution proceeds\n at the normal location for the kind of exit that was taken.\n\nWith more than one item, the context managers are processed as if\nmultiple "with" statements were nested:\n\n with A() as a, B() as b:\n suite\n\nis equivalent to\n\n with A() as a:\n with B() as b:\n suite\n\nChanged in version 3.1: Support for multiple context expressions.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n', - 'yield': u'\nThe "yield" statement\n*********************\n\n yield_stmt ::= yield_expression\n\nA "yield" statement is semantically equivalent to a *yield\nexpression*. The yield statement can be used to omit the parentheses\nthat would otherwise be required in the equivalent yield expression\nstatement. For example, the yield statements\n\n yield \n yield from \n\nare equivalent to the yield expression statements\n\n (yield )\n (yield from )\n\nYield expressions and statements are only used when defining a\n*generator* function, and are only used in the body of the generator\nfunction. Using yield in a function definition is sufficient to cause\nthat definition to create a generator function instead of a normal\nfunction.\n\nFor full details of "yield" semantics, refer to the *Yield\nexpressions* section.\n'} +# Autogenerated by Sphinx on Sun Jul 23 18:11:02 2017 +topics = {'assert': '\n' + 'The "assert" statement\n' + '**********************\n' + '\n' + 'Assert statements are a convenient way to insert debugging ' + 'assertions\n' + 'into a program:\n' + '\n' + ' assert_stmt ::= "assert" expression ["," expression]\n' + '\n' + 'The simple form, "assert expression", is equivalent to\n' + '\n' + ' if __debug__:\n' + ' if not expression: raise AssertionError\n' + '\n' + 'The extended form, "assert expression1, expression2", is ' + 'equivalent to\n' + '\n' + ' if __debug__:\n' + ' if not expression1: raise AssertionError(expression2)\n' + '\n' + 'These equivalences assume that "__debug__" and "AssertionError" ' + 'refer\n' + 'to the built-in variables with those names. In the current\n' + 'implementation, the built-in variable "__debug__" is "True" ' + 'under\n' + 'normal circumstances, "False" when optimization is requested ' + '(command\n' + 'line option -O). The current code generator emits no code for ' + 'an\n' + 'assert statement when optimization is requested at compile ' + 'time. Note\n' + 'that it is unnecessary to include the source code for the ' + 'expression\n' + 'that failed in the error message; it will be displayed as part ' + 'of the\n' + 'stack trace.\n' + '\n' + 'Assignments to "__debug__" are illegal. The value for the ' + 'built-in\n' + 'variable is determined when the interpreter starts.\n', + 'assignment': '\n' + 'Assignment statements\n' + '*********************\n' + '\n' + 'Assignment statements are used to (re)bind names to values ' + 'and to\n' + 'modify attributes or items of mutable objects:\n' + '\n' + ' assignment_stmt ::= (target_list "=")+ (expression_list | ' + 'yield_expression)\n' + ' target_list ::= target ("," target)* [","]\n' + ' target ::= identifier\n' + ' | "(" target_list ")"\n' + ' | "[" target_list "]"\n' + ' | attributeref\n' + ' | subscription\n' + ' | slicing\n' + ' | "*" target\n' + '\n' + '(See section *Primaries* for the syntax definitions for\n' + '*attributeref*, *subscription*, and *slicing*.)\n' + '\n' + 'An assignment statement evaluates the expression list ' + '(remember that\n' + 'this can be a single expression or a comma-separated list, ' + 'the latter\n' + 'yielding a tuple) and assigns the single resulting object to ' + 'each of\n' + 'the target lists, from left to right.\n' + '\n' + 'Assignment is defined recursively depending on the form of ' + 'the target\n' + '(list). When a target is part of a mutable object (an ' + 'attribute\n' + 'reference, subscription or slicing), the mutable object ' + 'must\n' + 'ultimately perform the assignment and decide about its ' + 'validity, and\n' + 'may raise an exception if the assignment is unacceptable. ' + 'The rules\n' + 'observed by various types and the exceptions raised are ' + 'given with the\n' + 'definition of the object types (see section *The standard ' + 'type\n' + 'hierarchy*).\n' + '\n' + 'Assignment of an object to a target list, optionally ' + 'enclosed in\n' + 'parentheses or square brackets, is recursively defined as ' + 'follows.\n' + '\n' + '* If the target list is a single target: The object is ' + 'assigned to\n' + ' that target.\n' + '\n' + '* If the target list is a comma-separated list of targets: ' + 'The\n' + ' object must be an iterable with the same number of items ' + 'as there\n' + ' are targets in the target list, and the items are ' + 'assigned, from\n' + ' left to right, to the corresponding targets.\n' + '\n' + ' * If the target list contains one target prefixed with an\n' + ' asterisk, called a "starred" target: The object must be ' + 'a sequence\n' + ' with at least as many items as there are targets in the ' + 'target\n' + ' list, minus one. The first items of the sequence are ' + 'assigned,\n' + ' from left to right, to the targets before the starred ' + 'target. The\n' + ' final items of the sequence are assigned to the targets ' + 'after the\n' + ' starred target. A list of the remaining items in the ' + 'sequence is\n' + ' then assigned to the starred target (the list can be ' + 'empty).\n' + '\n' + ' * Else: The object must be a sequence with the same number ' + 'of\n' + ' items as there are targets in the target list, and the ' + 'items are\n' + ' assigned, from left to right, to the corresponding ' + 'targets.\n' + '\n' + 'Assignment of an object to a single target is recursively ' + 'defined as\n' + 'follows.\n' + '\n' + '* If the target is an identifier (name):\n' + '\n' + ' * If the name does not occur in a "global" or "nonlocal" ' + 'statement\n' + ' in the current code block: the name is bound to the ' + 'object in the\n' + ' current local namespace.\n' + '\n' + ' * Otherwise: the name is bound to the object in the ' + 'global\n' + ' namespace or the outer namespace determined by ' + '"nonlocal",\n' + ' respectively.\n' + '\n' + ' The name is rebound if it was already bound. This may ' + 'cause the\n' + ' reference count for the object previously bound to the ' + 'name to reach\n' + ' zero, causing the object to be deallocated and its ' + 'destructor (if it\n' + ' has one) to be called.\n' + '\n' + '* If the target is a target list enclosed in parentheses or ' + 'in\n' + ' square brackets: The object must be an iterable with the ' + 'same number\n' + ' of items as there are targets in the target list, and its ' + 'items are\n' + ' assigned, from left to right, to the corresponding ' + 'targets.\n' + '\n' + '* If the target is an attribute reference: The primary ' + 'expression in\n' + ' the reference is evaluated. It should yield an object ' + 'with\n' + ' assignable attributes; if this is not the case, ' + '"TypeError" is\n' + ' raised. That object is then asked to assign the assigned ' + 'object to\n' + ' the given attribute; if it cannot perform the assignment, ' + 'it raises\n' + ' an exception (usually but not necessarily ' + '"AttributeError").\n' + '\n' + ' Note: If the object is a class instance and the attribute ' + 'reference\n' + ' occurs on both sides of the assignment operator, the RHS ' + 'expression,\n' + ' "a.x" can access either an instance attribute or (if no ' + 'instance\n' + ' attribute exists) a class attribute. The LHS target "a.x" ' + 'is always\n' + ' set as an instance attribute, creating it if necessary. ' + 'Thus, the\n' + ' two occurrences of "a.x" do not necessarily refer to the ' + 'same\n' + ' attribute: if the RHS expression refers to a class ' + 'attribute, the\n' + ' LHS creates a new instance attribute as the target of the\n' + ' assignment:\n' + '\n' + ' class Cls:\n' + ' x = 3 # class variable\n' + ' inst = Cls()\n' + ' inst.x = inst.x + 1 # writes inst.x as 4 leaving ' + 'Cls.x as 3\n' + '\n' + ' This description does not necessarily apply to descriptor\n' + ' attributes, such as properties created with "property()".\n' + '\n' + '* If the target is a subscription: The primary expression in ' + 'the\n' + ' reference is evaluated. It should yield either a mutable ' + 'sequence\n' + ' object (such as a list) or a mapping object (such as a ' + 'dictionary).\n' + ' Next, the subscript expression is evaluated.\n' + '\n' + ' If the primary is a mutable sequence object (such as a ' + 'list), the\n' + ' subscript must yield an integer. If it is negative, the ' + "sequence's\n" + ' length is added to it. The resulting value must be a ' + 'nonnegative\n' + " integer less than the sequence's length, and the sequence " + 'is asked\n' + ' to assign the assigned object to its item with that ' + 'index. If the\n' + ' index is out of range, "IndexError" is raised (assignment ' + 'to a\n' + ' subscripted sequence cannot add new items to a list).\n' + '\n' + ' If the primary is a mapping object (such as a dictionary), ' + 'the\n' + " subscript must have a type compatible with the mapping's " + 'key type,\n' + ' and the mapping is then asked to create a key/datum pair ' + 'which maps\n' + ' the subscript to the assigned object. This can either ' + 'replace an\n' + ' existing key/value pair with the same key value, or insert ' + 'a new\n' + ' key/value pair (if no key with the same value existed).\n' + '\n' + ' For user-defined objects, the "__setitem__()" method is ' + 'called with\n' + ' appropriate arguments.\n' + '\n' + '* If the target is a slicing: The primary expression in the\n' + ' reference is evaluated. It should yield a mutable ' + 'sequence object\n' + ' (such as a list). The assigned object should be a ' + 'sequence object\n' + ' of the same type. Next, the lower and upper bound ' + 'expressions are\n' + ' evaluated, insofar they are present; defaults are zero and ' + 'the\n' + " sequence's length. The bounds should evaluate to " + 'integers. If\n' + " either bound is negative, the sequence's length is added " + 'to it. The\n' + ' resulting bounds are clipped to lie between zero and the ' + "sequence's\n" + ' length, inclusive. Finally, the sequence object is asked ' + 'to replace\n' + ' the slice with the items of the assigned sequence. The ' + 'length of\n' + ' the slice may be different from the length of the assigned ' + 'sequence,\n' + ' thus changing the length of the target sequence, if the ' + 'target\n' + ' sequence allows it.\n' + '\n' + '**CPython implementation detail:** In the current ' + 'implementation, the\n' + 'syntax for targets is taken to be the same as for ' + 'expressions, and\n' + 'invalid syntax is rejected during the code generation phase, ' + 'causing\n' + 'less detailed error messages.\n' + '\n' + 'Although the definition of assignment implies that overlaps ' + 'between\n' + 'the left-hand side and the right-hand side are ' + "'simultanenous' (for\n" + 'example "a, b = b, a" swaps two variables), overlaps ' + '*within* the\n' + 'collection of assigned-to variables occur left-to-right, ' + 'sometimes\n' + 'resulting in confusion. For instance, the following program ' + 'prints\n' + '"[0, 2]":\n' + '\n' + ' x = [0, 1]\n' + ' i = 0\n' + ' i, x[i] = 1, 2 # i is updated, then x[i] is ' + 'updated\n' + ' print(x)\n' + '\n' + 'See also: **PEP 3132** - Extended Iterable Unpacking\n' + '\n' + ' The specification for the "*target" feature.\n' + '\n' + '\n' + 'Augmented assignment statements\n' + '===============================\n' + '\n' + 'Augmented assignment is the combination, in a single ' + 'statement, of a\n' + 'binary operation and an assignment statement:\n' + '\n' + ' augmented_assignment_stmt ::= augtarget augop ' + '(expression_list | yield_expression)\n' + ' augtarget ::= identifier | attributeref | ' + 'subscription | slicing\n' + ' augop ::= "+=" | "-=" | "*=" | "/=" | ' + '"//=" | "%=" | "**="\n' + ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' + '\n' + '(See section *Primaries* for the syntax definitions of the ' + 'last three\n' + 'symbols.)\n' + '\n' + 'An augmented assignment evaluates the target (which, unlike ' + 'normal\n' + 'assignment statements, cannot be an unpacking) and the ' + 'expression\n' + 'list, performs the binary operation specific to the type of ' + 'assignment\n' + 'on the two operands, and assigns the result to the original ' + 'target.\n' + 'The target is only evaluated once.\n' + '\n' + 'An augmented assignment expression like "x += 1" can be ' + 'rewritten as\n' + '"x = x + 1" to achieve a similar, but not exactly equal ' + 'effect. In the\n' + 'augmented version, "x" is only evaluated once. Also, when ' + 'possible,\n' + 'the actual operation is performed *in-place*, meaning that ' + 'rather than\n' + 'creating a new object and assigning that to the target, the ' + 'old object\n' + 'is modified instead.\n' + '\n' + 'Unlike normal assignments, augmented assignments evaluate ' + 'the left-\n' + 'hand side *before* evaluating the right-hand side. For ' + 'example, "a[i]\n' + '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' + 'performs\n' + 'the addition, and lastly, it writes the result back to ' + '"a[i]".\n' + '\n' + 'With the exception of assigning to tuples and multiple ' + 'targets in a\n' + 'single statement, the assignment done by augmented ' + 'assignment\n' + 'statements is handled the same way as normal assignments. ' + 'Similarly,\n' + 'with the exception of the possible *in-place* behavior, the ' + 'binary\n' + 'operation performed by augmented assignment is the same as ' + 'the normal\n' + 'binary operations.\n' + '\n' + 'For targets which are attribute references, the same *caveat ' + 'about\n' + 'class and instance attributes* applies as for regular ' + 'assignments.\n', + 'atom-identifiers': '\n' + 'Identifiers (Names)\n' + '*******************\n' + '\n' + 'An identifier occurring as an atom is a name. See ' + 'section\n' + '*Identifiers and keywords* for lexical definition and ' + 'section *Naming\n' + 'and binding* for documentation of naming and binding.\n' + '\n' + 'When the name is bound to an object, evaluation of the ' + 'atom yields\n' + 'that object. When a name is not bound, an attempt to ' + 'evaluate it\n' + 'raises a "NameError" exception.\n' + '\n' + '**Private name mangling:** When an identifier that ' + 'textually occurs in\n' + 'a class definition begins with two or more underscore ' + 'characters and\n' + 'does not end in two or more underscores, it is ' + 'considered a *private\n' + 'name* of that class. Private names are transformed to ' + 'a longer form\n' + 'before code is generated for them. The transformation ' + 'inserts the\n' + 'class name, with leading underscores removed and a ' + 'single underscore\n' + 'inserted, in front of the name. For example, the ' + 'identifier "__spam"\n' + 'occurring in a class named "Ham" will be transformed ' + 'to "_Ham__spam".\n' + 'This transformation is independent of the syntactical ' + 'context in which\n' + 'the identifier is used. If the transformed name is ' + 'extremely long\n' + '(longer than 255 characters), implementation defined ' + 'truncation may\n' + 'happen. If the class name consists only of ' + 'underscores, no\n' + 'transformation is done.\n', + 'atom-literals': '\n' + 'Literals\n' + '********\n' + '\n' + 'Python supports string and bytes literals and various ' + 'numeric\n' + 'literals:\n' + '\n' + ' literal ::= stringliteral | bytesliteral\n' + ' | integer | floatnumber | imagnumber\n' + '\n' + 'Evaluation of a literal yields an object of the given ' + 'type (string,\n' + 'bytes, integer, floating point number, complex number) ' + 'with the given\n' + 'value. The value may be approximated in the case of ' + 'floating point\n' + 'and imaginary (complex) literals. See section *Literals* ' + 'for details.\n' + '\n' + 'All literals correspond to immutable data types, and ' + 'hence the\n' + "object's identity is less important than its value. " + 'Multiple\n' + 'evaluations of literals with the same value (either the ' + 'same\n' + 'occurrence in the program text or a different occurrence) ' + 'may obtain\n' + 'the same object or a different object with the same ' + 'value.\n', + 'attribute-access': '\n' + 'Customizing attribute access\n' + '****************************\n' + '\n' + 'The following methods can be defined to customize the ' + 'meaning of\n' + 'attribute access (use of, assignment to, or deletion ' + 'of "x.name") for\n' + 'class instances.\n' + '\n' + 'object.__getattr__(self, name)\n' + '\n' + ' Called when an attribute lookup has not found the ' + 'attribute in the\n' + ' usual places (i.e. it is not an instance attribute ' + 'nor is it found\n' + ' in the class tree for "self"). "name" is the ' + 'attribute name. This\n' + ' method should return the (computed) attribute value ' + 'or raise an\n' + ' "AttributeError" exception.\n' + '\n' + ' Note that if the attribute is found through the ' + 'normal mechanism,\n' + ' "__getattr__()" is not called. (This is an ' + 'intentional asymmetry\n' + ' between "__getattr__()" and "__setattr__()".) This ' + 'is done both for\n' + ' efficiency reasons and because otherwise ' + '"__getattr__()" would have\n' + ' no way to access other attributes of the instance. ' + 'Note that at\n' + ' least for instance variables, you can fake total ' + 'control by not\n' + ' inserting any values in the instance attribute ' + 'dictionary (but\n' + ' instead inserting them in another object). See ' + 'the\n' + ' "__getattribute__()" method below for a way to ' + 'actually get total\n' + ' control over attribute access.\n' + '\n' + 'object.__getattribute__(self, name)\n' + '\n' + ' Called unconditionally to implement attribute ' + 'accesses for\n' + ' instances of the class. If the class also defines ' + '"__getattr__()",\n' + ' the latter will not be called unless ' + '"__getattribute__()" either\n' + ' calls it explicitly or raises an "AttributeError". ' + 'This method\n' + ' should return the (computed) attribute value or ' + 'raise an\n' + ' "AttributeError" exception. In order to avoid ' + 'infinite recursion in\n' + ' this method, its implementation should always call ' + 'the base class\n' + ' method with the same name to access any attributes ' + 'it needs, for\n' + ' example, "object.__getattribute__(self, name)".\n' + '\n' + ' Note: This method may still be bypassed when ' + 'looking up special\n' + ' methods as the result of implicit invocation via ' + 'language syntax\n' + ' or built-in functions. See *Special method ' + 'lookup*.\n' + '\n' + 'object.__setattr__(self, name, value)\n' + '\n' + ' Called when an attribute assignment is attempted. ' + 'This is called\n' + ' instead of the normal mechanism (i.e. store the ' + 'value in the\n' + ' instance dictionary). *name* is the attribute name, ' + '*value* is the\n' + ' value to be assigned to it.\n' + '\n' + ' If "__setattr__()" wants to assign to an instance ' + 'attribute, it\n' + ' should call the base class method with the same ' + 'name, for example,\n' + ' "object.__setattr__(self, name, value)".\n' + '\n' + 'object.__delattr__(self, name)\n' + '\n' + ' Like "__setattr__()" but for attribute deletion ' + 'instead of\n' + ' assignment. This should only be implemented if ' + '"del obj.name" is\n' + ' meaningful for the object.\n' + '\n' + 'object.__dir__(self)\n' + '\n' + ' Called when "dir()" is called on the object. A ' + 'sequence must be\n' + ' returned. "dir()" converts the returned sequence to ' + 'a list and\n' + ' sorts it.\n' + '\n' + '\n' + 'Implementing Descriptors\n' + '========================\n' + '\n' + 'The following methods only apply when an instance of ' + 'the class\n' + 'containing the method (a so-called *descriptor* class) ' + 'appears in an\n' + '*owner* class (the descriptor must be in either the ' + "owner's class\n" + 'dictionary or in the class dictionary for one of its ' + 'parents). In the\n' + 'examples below, "the attribute" refers to the ' + 'attribute whose name is\n' + "the key of the property in the owner class' " + '"__dict__".\n' + '\n' + 'object.__get__(self, instance, owner)\n' + '\n' + ' Called to get the attribute of the owner class ' + '(class attribute\n' + ' access) or of an instance of that class (instance ' + 'attribute\n' + ' access). *owner* is always the owner class, while ' + '*instance* is the\n' + ' instance that the attribute was accessed through, ' + 'or "None" when\n' + ' the attribute is accessed through the *owner*. ' + 'This method should\n' + ' return the (computed) attribute value or raise an ' + '"AttributeError"\n' + ' exception.\n' + '\n' + 'object.__set__(self, instance, value)\n' + '\n' + ' Called to set the attribute on an instance ' + '*instance* of the owner\n' + ' class to a new value, *value*.\n' + '\n' + 'object.__delete__(self, instance)\n' + '\n' + ' Called to delete the attribute on an instance ' + '*instance* of the\n' + ' owner class.\n' + '\n' + 'The attribute "__objclass__" is interpreted by the ' + '"inspect" module as\n' + 'specifying the class where this object was defined ' + '(setting this\n' + 'appropriately can assist in runtime introspection of ' + 'dynamic class\n' + 'attributes). For callables, it may indicate that an ' + 'instance of the\n' + 'given type (or a subclass) is expected or required as ' + 'the first\n' + 'positional argument (for example, CPython sets this ' + 'attribute for\n' + 'unbound methods that are implemented in C).\n' + '\n' + '\n' + 'Invoking Descriptors\n' + '====================\n' + '\n' + 'In general, a descriptor is an object attribute with ' + '"binding\n' + 'behavior", one whose attribute access has been ' + 'overridden by methods\n' + 'in the descriptor protocol: "__get__()", "__set__()", ' + 'and\n' + '"__delete__()". If any of those methods are defined ' + 'for an object, it\n' + 'is said to be a descriptor.\n' + '\n' + 'The default behavior for attribute access is to get, ' + 'set, or delete\n' + "the attribute from an object's dictionary. For " + 'instance, "a.x" has a\n' + 'lookup chain starting with "a.__dict__[\'x\']", then\n' + '"type(a).__dict__[\'x\']", and continuing through the ' + 'base classes of\n' + '"type(a)" excluding metaclasses.\n' + '\n' + 'However, if the looked-up value is an object defining ' + 'one of the\n' + 'descriptor methods, then Python may override the ' + 'default behavior and\n' + 'invoke the descriptor method instead. Where this ' + 'occurs in the\n' + 'precedence chain depends on which descriptor methods ' + 'were defined and\n' + 'how they were called.\n' + '\n' + 'The starting point for descriptor invocation is a ' + 'binding, "a.x". How\n' + 'the arguments are assembled depends on "a":\n' + '\n' + 'Direct Call\n' + ' The simplest and least common call is when user ' + 'code directly\n' + ' invokes a descriptor method: "x.__get__(a)".\n' + '\n' + 'Instance Binding\n' + ' If binding to an object instance, "a.x" is ' + 'transformed into the\n' + ' call: "type(a).__dict__[\'x\'].__get__(a, ' + 'type(a))".\n' + '\n' + 'Class Binding\n' + ' If binding to a class, "A.x" is transformed into ' + 'the call:\n' + ' "A.__dict__[\'x\'].__get__(None, A)".\n' + '\n' + 'Super Binding\n' + ' If "a" is an instance of "super", then the binding ' + '"super(B,\n' + ' obj).m()" searches "obj.__class__.__mro__" for the ' + 'base class "A"\n' + ' immediately preceding "B" and then invokes the ' + 'descriptor with the\n' + ' call: "A.__dict__[\'m\'].__get__(obj, ' + 'obj.__class__)".\n' + '\n' + 'For instance bindings, the precedence of descriptor ' + 'invocation depends\n' + 'on the which descriptor methods are defined. A ' + 'descriptor can define\n' + 'any combination of "__get__()", "__set__()" and ' + '"__delete__()". If it\n' + 'does not define "__get__()", then accessing the ' + 'attribute will return\n' + 'the descriptor object itself unless there is a value ' + "in the object's\n" + 'instance dictionary. If the descriptor defines ' + '"__set__()" and/or\n' + '"__delete__()", it is a data descriptor; if it defines ' + 'neither, it is\n' + 'a non-data descriptor. Normally, data descriptors ' + 'define both\n' + '"__get__()" and "__set__()", while non-data ' + 'descriptors have just the\n' + '"__get__()" method. Data descriptors with "__set__()" ' + 'and "__get__()"\n' + 'defined always override a redefinition in an instance ' + 'dictionary. In\n' + 'contrast, non-data descriptors can be overridden by ' + 'instances.\n' + '\n' + 'Python methods (including "staticmethod()" and ' + '"classmethod()") are\n' + 'implemented as non-data descriptors. Accordingly, ' + 'instances can\n' + 'redefine and override methods. This allows individual ' + 'instances to\n' + 'acquire behaviors that differ from other instances of ' + 'the same class.\n' + '\n' + 'The "property()" function is implemented as a data ' + 'descriptor.\n' + 'Accordingly, instances cannot override the behavior of ' + 'a property.\n' + '\n' + '\n' + '__slots__\n' + '=========\n' + '\n' + 'By default, instances of classes have a dictionary for ' + 'attribute\n' + 'storage. This wastes space for objects having very ' + 'few instance\n' + 'variables. The space consumption can become acute ' + 'when creating large\n' + 'numbers of instances.\n' + '\n' + 'The default can be overridden by defining *__slots__* ' + 'in a class\n' + 'definition. The *__slots__* declaration takes a ' + 'sequence of instance\n' + 'variables and reserves just enough space in each ' + 'instance to hold a\n' + 'value for each variable. Space is saved because ' + '*__dict__* is not\n' + 'created for each instance.\n' + '\n' + 'object.__slots__\n' + '\n' + ' This class variable can be assigned a string, ' + 'iterable, or sequence\n' + ' of strings with variable names used by instances. ' + '*__slots__*\n' + ' reserves space for the declared variables and ' + 'prevents the\n' + ' automatic creation of *__dict__* and *__weakref__* ' + 'for each\n' + ' instance.\n' + '\n' + '\n' + 'Notes on using *__slots__*\n' + '--------------------------\n' + '\n' + '* When inheriting from a class without *__slots__*, ' + 'the *__dict__*\n' + ' attribute of that class will always be accessible, ' + 'so a *__slots__*\n' + ' definition in the subclass is meaningless.\n' + '\n' + '* Without a *__dict__* variable, instances cannot be ' + 'assigned new\n' + ' variables not listed in the *__slots__* definition. ' + 'Attempts to\n' + ' assign to an unlisted variable name raises ' + '"AttributeError". If\n' + ' dynamic assignment of new variables is desired, then ' + 'add\n' + ' "\'__dict__\'" to the sequence of strings in the ' + '*__slots__*\n' + ' declaration.\n' + '\n' + '* Without a *__weakref__* variable for each instance, ' + 'classes\n' + ' defining *__slots__* do not support weak references ' + 'to its\n' + ' instances. If weak reference support is needed, then ' + 'add\n' + ' "\'__weakref__\'" to the sequence of strings in the ' + '*__slots__*\n' + ' declaration.\n' + '\n' + '* *__slots__* are implemented at the class level by ' + 'creating\n' + ' descriptors (*Implementing Descriptors*) for each ' + 'variable name. As\n' + ' a result, class attributes cannot be used to set ' + 'default values for\n' + ' instance variables defined by *__slots__*; ' + 'otherwise, the class\n' + ' attribute would overwrite the descriptor ' + 'assignment.\n' + '\n' + '* The action of a *__slots__* declaration is limited ' + 'to the class\n' + ' where it is defined. As a result, subclasses will ' + 'have a *__dict__*\n' + ' unless they also define *__slots__* (which must only ' + 'contain names\n' + ' of any *additional* slots).\n' + '\n' + '* If a class defines a slot also defined in a base ' + 'class, the\n' + ' instance variable defined by the base class slot is ' + 'inaccessible\n' + ' (except by retrieving its descriptor directly from ' + 'the base class).\n' + ' This renders the meaning of the program undefined. ' + 'In the future, a\n' + ' check may be added to prevent this.\n' + '\n' + '* Nonempty *__slots__* does not work for classes ' + 'derived from\n' + ' "variable-length" built-in types such as "int", ' + '"bytes" and "tuple".\n' + '\n' + '* Any non-string iterable may be assigned to ' + '*__slots__*. Mappings\n' + ' may also be used; however, in the future, special ' + 'meaning may be\n' + ' assigned to the values corresponding to each key.\n' + '\n' + '* *__class__* assignment works only if both classes ' + 'have the same\n' + ' *__slots__*.\n', + 'attribute-references': '\n' + 'Attribute references\n' + '********************\n' + '\n' + 'An attribute reference is a primary followed by a ' + 'period and a name:\n' + '\n' + ' attributeref ::= primary "." identifier\n' + '\n' + 'The primary must evaluate to an object of a type ' + 'that supports\n' + 'attribute references, which most objects do. This ' + 'object is then\n' + 'asked to produce the attribute whose name is the ' + 'identifier. This\n' + 'production can be customized by overriding the ' + '"__getattr__()" method.\n' + 'If this attribute is not available, the exception ' + '"AttributeError" is\n' + 'raised. Otherwise, the type and value of the ' + 'object produced is\n' + 'determined by the object. Multiple evaluations of ' + 'the same attribute\n' + 'reference may yield different objects.\n', + 'augassign': '\n' + 'Augmented assignment statements\n' + '*******************************\n' + '\n' + 'Augmented assignment is the combination, in a single ' + 'statement, of a\n' + 'binary operation and an assignment statement:\n' + '\n' + ' augmented_assignment_stmt ::= augtarget augop ' + '(expression_list | yield_expression)\n' + ' augtarget ::= identifier | attributeref | ' + 'subscription | slicing\n' + ' augop ::= "+=" | "-=" | "*=" | "/=" | ' + '"//=" | "%=" | "**="\n' + ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' + '\n' + '(See section *Primaries* for the syntax definitions of the ' + 'last three\n' + 'symbols.)\n' + '\n' + 'An augmented assignment evaluates the target (which, unlike ' + 'normal\n' + 'assignment statements, cannot be an unpacking) and the ' + 'expression\n' + 'list, performs the binary operation specific to the type of ' + 'assignment\n' + 'on the two operands, and assigns the result to the original ' + 'target.\n' + 'The target is only evaluated once.\n' + '\n' + 'An augmented assignment expression like "x += 1" can be ' + 'rewritten as\n' + '"x = x + 1" to achieve a similar, but not exactly equal ' + 'effect. In the\n' + 'augmented version, "x" is only evaluated once. Also, when ' + 'possible,\n' + 'the actual operation is performed *in-place*, meaning that ' + 'rather than\n' + 'creating a new object and assigning that to the target, the ' + 'old object\n' + 'is modified instead.\n' + '\n' + 'Unlike normal assignments, augmented assignments evaluate the ' + 'left-\n' + 'hand side *before* evaluating the right-hand side. For ' + 'example, "a[i]\n' + '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' + 'performs\n' + 'the addition, and lastly, it writes the result back to ' + '"a[i]".\n' + '\n' + 'With the exception of assigning to tuples and multiple ' + 'targets in a\n' + 'single statement, the assignment done by augmented ' + 'assignment\n' + 'statements is handled the same way as normal assignments. ' + 'Similarly,\n' + 'with the exception of the possible *in-place* behavior, the ' + 'binary\n' + 'operation performed by augmented assignment is the same as ' + 'the normal\n' + 'binary operations.\n' + '\n' + 'For targets which are attribute references, the same *caveat ' + 'about\n' + 'class and instance attributes* applies as for regular ' + 'assignments.\n', + 'binary': '\n' + 'Binary arithmetic operations\n' + '****************************\n' + '\n' + 'The binary arithmetic operations have the conventional priority\n' + 'levels. Note that some of these operations also apply to ' + 'certain non-\n' + 'numeric types. Apart from the power operator, there are only ' + 'two\n' + 'levels, one for multiplicative operators and one for additive\n' + 'operators:\n' + '\n' + ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "//" u_expr | ' + 'm_expr "/" u_expr\n' + ' | m_expr "%" u_expr\n' + ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' + '\n' + 'The "*" (multiplication) operator yields the product of its ' + 'arguments.\n' + 'The arguments must either both be numbers, or one argument must ' + 'be an\n' + 'integer and the other must be a sequence. In the former case, ' + 'the\n' + 'numbers are converted to a common type and then multiplied ' + 'together.\n' + 'In the latter case, sequence repetition is performed; a ' + 'negative\n' + 'repetition factor yields an empty sequence.\n' + '\n' + 'The "/" (division) and "//" (floor division) operators yield ' + 'the\n' + 'quotient of their arguments. The numeric arguments are first\n' + 'converted to a common type. Division of integers yields a float, ' + 'while\n' + 'floor division of integers results in an integer; the result is ' + 'that\n' + "of mathematical division with the 'floor' function applied to " + 'the\n' + 'result. Division by zero raises the "ZeroDivisionError" ' + 'exception.\n' + '\n' + 'The "%" (modulo) operator yields the remainder from the division ' + 'of\n' + 'the first argument by the second. The numeric arguments are ' + 'first\n' + 'converted to a common type. A zero right argument raises the\n' + '"ZeroDivisionError" exception. The arguments may be floating ' + 'point\n' + 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals ' + '"4*0.7 +\n' + '0.34".) The modulo operator always yields a result with the ' + 'same sign\n' + 'as its second operand (or zero); the absolute value of the ' + 'result is\n' + 'strictly smaller than the absolute value of the second operand ' + '[1].\n' + '\n' + 'The floor division and modulo operators are connected by the ' + 'following\n' + 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo ' + 'are also\n' + 'connected with the built-in function "divmod()": "divmod(x, y) ' + '==\n' + '(x//y, x%y)". [2].\n' + '\n' + 'In addition to performing the modulo operation on numbers, the ' + '"%"\n' + 'operator is also overloaded by string objects to perform ' + 'old-style\n' + 'string formatting (also known as interpolation). The syntax ' + 'for\n' + 'string formatting is described in the Python Library Reference,\n' + 'section *printf-style String Formatting*.\n' + '\n' + 'The floor division operator, the modulo operator, and the ' + '"divmod()"\n' + 'function are not defined for complex numbers. Instead, convert ' + 'to a\n' + 'floating point number using the "abs()" function if ' + 'appropriate.\n' + '\n' + 'The "+" (addition) operator yields the sum of its arguments. ' + 'The\n' + 'arguments must either both be numbers or both be sequences of ' + 'the same\n' + 'type. In the former case, the numbers are converted to a common ' + 'type\n' + 'and then added together. In the latter case, the sequences are\n' + 'concatenated.\n' + '\n' + 'The "-" (subtraction) operator yields the difference of its ' + 'arguments.\n' + 'The numeric arguments are first converted to a common type.\n', + 'bitwise': '\n' + 'Binary bitwise operations\n' + '*************************\n' + '\n' + 'Each of the three bitwise operations has a different priority ' + 'level:\n' + '\n' + ' and_expr ::= shift_expr | and_expr "&" shift_expr\n' + ' xor_expr ::= and_expr | xor_expr "^" and_expr\n' + ' or_expr ::= xor_expr | or_expr "|" xor_expr\n' + '\n' + 'The "&" operator yields the bitwise AND of its arguments, which ' + 'must\n' + 'be integers.\n' + '\n' + 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' + 'arguments, which must be integers.\n' + '\n' + 'The "|" operator yields the bitwise (inclusive) OR of its ' + 'arguments,\n' + 'which must be integers.\n', + 'bltin-code-objects': '\n' + 'Code Objects\n' + '************\n' + '\n' + 'Code objects are used by the implementation to ' + 'represent "pseudo-\n' + 'compiled" executable Python code such as a function ' + 'body. They differ\n' + "from function objects because they don't contain a " + 'reference to their\n' + 'global execution environment. Code objects are ' + 'returned by the built-\n' + 'in "compile()" function and can be extracted from ' + 'function objects\n' + 'through their "__code__" attribute. See also the ' + '"code" module.\n' + '\n' + 'A code object can be executed or evaluated by ' + 'passing it (instead of a\n' + 'source string) to the "exec()" or "eval()" built-in ' + 'functions.\n' + '\n' + 'See *The standard type hierarchy* for more ' + 'information.\n', + 'bltin-ellipsis-object': '\n' + 'The Ellipsis Object\n' + '*******************\n' + '\n' + 'This object is commonly used by slicing (see ' + '*Slicings*). It supports\n' + 'no special operations. There is exactly one ' + 'ellipsis object, named\n' + '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' + 'produces the\n' + '"Ellipsis" singleton.\n' + '\n' + 'It is written as "Ellipsis" or "...".\n', + 'bltin-null-object': '\n' + 'The Null Object\n' + '***************\n' + '\n' + "This object is returned by functions that don't " + 'explicitly return a\n' + 'value. It supports no special operations. There is ' + 'exactly one null\n' + 'object, named "None" (a built-in name). ' + '"type(None)()" produces the\n' + 'same singleton.\n' + '\n' + 'It is written as "None".\n', + 'bltin-type-objects': '\n' + 'Type Objects\n' + '************\n' + '\n' + 'Type objects represent the various object types. An ' + "object's type is\n" + 'accessed by the built-in function "type()". There ' + 'are no special\n' + 'operations on types. The standard module "types" ' + 'defines names for\n' + 'all standard built-in types.\n' + '\n' + 'Types are written like this: "".\n', + 'booleans': '\n' + 'Boolean operations\n' + '******************\n' + '\n' + ' or_test ::= and_test | or_test "or" and_test\n' + ' and_test ::= not_test | and_test "and" not_test\n' + ' not_test ::= comparison | "not" not_test\n' + '\n' + 'In the context of Boolean operations, and also when ' + 'expressions are\n' + 'used by control flow statements, the following values are ' + 'interpreted\n' + 'as false: "False", "None", numeric zero of all types, and ' + 'empty\n' + 'strings and containers (including strings, tuples, lists,\n' + 'dictionaries, sets and frozensets). All other values are ' + 'interpreted\n' + 'as true. User-defined objects can customize their truth value ' + 'by\n' + 'providing a "__bool__()" method.\n' + '\n' + 'The operator "not" yields "True" if its argument is false, ' + '"False"\n' + 'otherwise.\n' + '\n' + 'The expression "x and y" first evaluates *x*; if *x* is false, ' + 'its\n' + 'value is returned; otherwise, *y* is evaluated and the ' + 'resulting value\n' + 'is returned.\n' + '\n' + 'The expression "x or y" first evaluates *x*; if *x* is true, ' + 'its value\n' + 'is returned; otherwise, *y* is evaluated and the resulting ' + 'value is\n' + 'returned.\n' + '\n' + '(Note that neither "and" nor "or" restrict the value and type ' + 'they\n' + 'return to "False" and "True", but rather return the last ' + 'evaluated\n' + 'argument. This is sometimes useful, e.g., if "s" is a string ' + 'that\n' + 'should be replaced by a default value if it is empty, the ' + 'expression\n' + '"s or \'foo\'" yields the desired value. Because "not" has to ' + 'create a\n' + 'new value, it returns a boolean value regardless of the type ' + 'of its\n' + 'argument (for example, "not \'foo\'" produces "False" rather ' + 'than "\'\'".)\n', + 'break': '\n' + 'The "break" statement\n' + '*********************\n' + '\n' + ' break_stmt ::= "break"\n' + '\n' + '"break" may only occur syntactically nested in a "for" or ' + '"while"\n' + 'loop, but not nested in a function or class definition within ' + 'that\n' + 'loop.\n' + '\n' + 'It terminates the nearest enclosing loop, skipping the optional ' + '"else"\n' + 'clause if the loop has one.\n' + '\n' + 'If a "for" loop is terminated by "break", the loop control ' + 'target\n' + 'keeps its current value.\n' + '\n' + 'When "break" passes control out of a "try" statement with a ' + '"finally"\n' + 'clause, that "finally" clause is executed before really leaving ' + 'the\n' + 'loop.\n', + 'callable-types': '\n' + 'Emulating callable objects\n' + '**************************\n' + '\n' + 'object.__call__(self[, args...])\n' + '\n' + ' Called when the instance is "called" as a function; ' + 'if this method\n' + ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' + ' "x.__call__(arg1, arg2, ...)".\n', + 'calls': '\n' + 'Calls\n' + '*****\n' + '\n' + 'A call calls a callable object (e.g., a *function*) with a ' + 'possibly\n' + 'empty series of *arguments*:\n' + '\n' + ' call ::= primary "(" [argument_list [","] | ' + 'comprehension] ")"\n' + ' argument_list ::= positional_arguments ["," ' + 'keyword_arguments]\n' + ' ["," "*" expression] ["," ' + 'keyword_arguments]\n' + ' ["," "**" expression]\n' + ' | keyword_arguments ["," "*" expression]\n' + ' ["," keyword_arguments] ["," "**" ' + 'expression]\n' + ' | "*" expression ["," keyword_arguments] ' + '["," "**" expression]\n' + ' | "**" expression\n' + ' positional_arguments ::= expression ("," expression)*\n' + ' keyword_arguments ::= keyword_item ("," keyword_item)*\n' + ' keyword_item ::= identifier "=" expression\n' + '\n' + 'An optional trailing comma may be present after the positional ' + 'and\n' + 'keyword arguments but does not affect the semantics.\n' + '\n' + 'The primary must evaluate to a callable object (user-defined\n' + 'functions, built-in functions, methods of built-in objects, ' + 'class\n' + 'objects, methods of class instances, and all objects having a\n' + '"__call__()" method are callable). All argument expressions are\n' + 'evaluated before the call is attempted. Please refer to section\n' + '*Function definitions* for the syntax of formal *parameter* ' + 'lists.\n' + '\n' + 'If keyword arguments are present, they are first converted to\n' + 'positional arguments, as follows. First, a list of unfilled ' + 'slots is\n' + 'created for the formal parameters. If there are N positional\n' + 'arguments, they are placed in the first N slots. Next, for each\n' + 'keyword argument, the identifier is used to determine the\n' + 'corresponding slot (if the identifier is the same as the first ' + 'formal\n' + 'parameter name, the first slot is used, and so on). If the slot ' + 'is\n' + 'already filled, a "TypeError" exception is raised. Otherwise, ' + 'the\n' + 'value of the argument is placed in the slot, filling it (even if ' + 'the\n' + 'expression is "None", it fills the slot). When all arguments ' + 'have\n' + 'been processed, the slots that are still unfilled are filled with ' + 'the\n' + 'corresponding default value from the function definition. ' + '(Default\n' + 'values are calculated, once, when the function is defined; thus, ' + 'a\n' + 'mutable object such as a list or dictionary used as default value ' + 'will\n' + "be shared by all calls that don't specify an argument value for " + 'the\n' + 'corresponding slot; this should usually be avoided.) If there ' + 'are any\n' + 'unfilled slots for which no default value is specified, a ' + '"TypeError"\n' + 'exception is raised. Otherwise, the list of filled slots is used ' + 'as\n' + 'the argument list for the call.\n' + '\n' + '**CPython implementation detail:** An implementation may provide\n' + 'built-in functions whose positional parameters do not have names, ' + 'even\n' + "if they are 'named' for the purpose of documentation, and which\n" + 'therefore cannot be supplied by keyword. In CPython, this is the ' + 'case\n' + 'for functions implemented in C that use "PyArg_ParseTuple()" to ' + 'parse\n' + 'their arguments.\n' + '\n' + 'If there are more positional arguments than there are formal ' + 'parameter\n' + 'slots, a "TypeError" exception is raised, unless a formal ' + 'parameter\n' + 'using the syntax "*identifier" is present; in this case, that ' + 'formal\n' + 'parameter receives a tuple containing the excess positional ' + 'arguments\n' + '(or an empty tuple if there were no excess positional ' + 'arguments).\n' + '\n' + 'If any keyword argument does not correspond to a formal ' + 'parameter\n' + 'name, a "TypeError" exception is raised, unless a formal ' + 'parameter\n' + 'using the syntax "**identifier" is present; in this case, that ' + 'formal\n' + 'parameter receives a dictionary containing the excess keyword\n' + 'arguments (using the keywords as keys and the argument values as\n' + 'corresponding values), or a (new) empty dictionary if there were ' + 'no\n' + 'excess keyword arguments.\n' + '\n' + 'If the syntax "*expression" appears in the function call, ' + '"expression"\n' + 'must evaluate to an iterable. Elements from this iterable are ' + 'treated\n' + 'as if they were additional positional arguments; if there are\n' + 'positional arguments *x1*, ..., *xN*, and "expression" evaluates ' + 'to a\n' + 'sequence *y1*, ..., *yM*, this is equivalent to a call with M+N\n' + 'positional arguments *x1*, ..., *xN*, *y1*, ..., *yM*.\n' + '\n' + 'A consequence of this is that although the "*expression" syntax ' + 'may\n' + 'appear *after* some keyword arguments, it is processed *before* ' + 'the\n' + 'keyword arguments (and the "**expression" argument, if any -- ' + 'see\n' + 'below). So:\n' + '\n' + ' >>> def f(a, b):\n' + ' ... print(a, b)\n' + ' ...\n' + ' >>> f(b=1, *(2,))\n' + ' 2 1\n' + ' >>> f(a=1, *(2,))\n' + ' Traceback (most recent call last):\n' + ' File "", line 1, in ?\n' + " TypeError: f() got multiple values for keyword argument 'a'\n" + ' >>> f(1, *(2,))\n' + ' 1 2\n' + '\n' + 'It is unusual for both keyword arguments and the "*expression" ' + 'syntax\n' + 'to be used in the same call, so in practice this confusion does ' + 'not\n' + 'arise.\n' + '\n' + 'If the syntax "**expression" appears in the function call,\n' + '"expression" must evaluate to a mapping, the contents of which ' + 'are\n' + 'treated as additional keyword arguments. In the case of a ' + 'keyword\n' + 'appearing in both "expression" and as an explicit keyword ' + 'argument, a\n' + '"TypeError" exception is raised.\n' + '\n' + 'Formal parameters using the syntax "*identifier" or ' + '"**identifier"\n' + 'cannot be used as positional argument slots or as keyword ' + 'argument\n' + 'names.\n' + '\n' + 'A call always returns some value, possibly "None", unless it ' + 'raises an\n' + 'exception. How this value is computed depends on the type of ' + 'the\n' + 'callable object.\n' + '\n' + 'If it is---\n' + '\n' + 'a user-defined function:\n' + ' The code block for the function is executed, passing it the\n' + ' argument list. The first thing the code block will do is bind ' + 'the\n' + ' formal parameters to the arguments; this is described in ' + 'section\n' + ' *Function definitions*. When the code block executes a ' + '"return"\n' + ' statement, this specifies the return value of the function ' + 'call.\n' + '\n' + 'a built-in function or method:\n' + ' The result is up to the interpreter; see *Built-in Functions* ' + 'for\n' + ' the descriptions of built-in functions and methods.\n' + '\n' + 'a class object:\n' + ' A new instance of that class is returned.\n' + '\n' + 'a class instance method:\n' + ' The corresponding user-defined function is called, with an ' + 'argument\n' + ' list that is one longer than the argument list of the call: ' + 'the\n' + ' instance becomes the first argument.\n' + '\n' + 'a class instance:\n' + ' The class must define a "__call__()" method; the effect is ' + 'then the\n' + ' same as if that method was called.\n', + 'class': '\n' + 'Class definitions\n' + '*****************\n' + '\n' + 'A class definition defines a class object (see section *The ' + 'standard\n' + 'type hierarchy*):\n' + '\n' + ' classdef ::= [decorators] "class" classname [inheritance] ' + '":" suite\n' + ' inheritance ::= "(" [parameter_list] ")"\n' + ' classname ::= identifier\n' + '\n' + 'A class definition is an executable statement. The inheritance ' + 'list\n' + 'usually gives a list of base classes (see *Customizing class ' + 'creation*\n' + 'for more advanced uses), so each item in the list should evaluate ' + 'to a\n' + 'class object which allows subclassing. Classes without an ' + 'inheritance\n' + 'list inherit, by default, from the base class "object"; hence,\n' + '\n' + ' class Foo:\n' + ' pass\n' + '\n' + 'is equivalent to\n' + '\n' + ' class Foo(object):\n' + ' pass\n' + '\n' + "The class's suite is then executed in a new execution frame (see\n" + '*Naming and binding*), using a newly created local namespace and ' + 'the\n' + 'original global namespace. (Usually, the suite contains mostly\n' + "function definitions.) When the class's suite finishes " + 'execution, its\n' + 'execution frame is discarded but its local namespace is saved. ' + '[4] A\n' + 'class object is then created using the inheritance list for the ' + 'base\n' + 'classes and the saved local namespace for the attribute ' + 'dictionary.\n' + 'The class name is bound to this class object in the original ' + 'local\n' + 'namespace.\n' + '\n' + 'Class creation can be customized heavily using *metaclasses*.\n' + '\n' + 'Classes can also be decorated: just like when decorating ' + 'functions,\n' + '\n' + ' @f1(arg)\n' + ' @f2\n' + ' class Foo: pass\n' + '\n' + 'is equivalent to\n' + '\n' + ' class Foo: pass\n' + ' Foo = f1(arg)(f2(Foo))\n' + '\n' + 'The evaluation rules for the decorator expressions are the same ' + 'as for\n' + 'function decorators. The result must be a class object, which is ' + 'then\n' + 'bound to the class name.\n' + '\n' + "**Programmer's note:** Variables defined in the class definition " + 'are\n' + 'class attributes; they are shared by instances. Instance ' + 'attributes\n' + 'can be set in a method with "self.name = value". Both class and\n' + 'instance attributes are accessible through the notation ' + '""self.name"",\n' + 'and an instance attribute hides a class attribute with the same ' + 'name\n' + 'when accessed in this way. Class attributes can be used as ' + 'defaults\n' + 'for instance attributes, but using mutable values there can lead ' + 'to\n' + 'unexpected results. *Descriptors* can be used to create ' + 'instance\n' + 'variables with different implementation details.\n' + '\n' + 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n' + ' Class Decorators\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] The exception is propagated to the invocation stack unless\n' + ' there is a "finally" clause which happens to raise another\n' + ' exception. That new exception causes the old one to be lost.\n' + '\n' + '[2] Currently, control "flows off the end" except in the case of\n' + ' an exception or the execution of a "return", "continue", or\n' + ' "break" statement.\n' + '\n' + '[3] A string literal appearing as the first statement in the\n' + ' function body is transformed into the function\'s "__doc__"\n' + " attribute and therefore the function's *docstring*.\n" + '\n' + '[4] A string literal appearing as the first statement in the ' + 'class\n' + ' body is transformed into the namespace\'s "__doc__" item and\n' + " therefore the class's *docstring*.\n", + 'comparisons': '\n' + 'Comparisons\n' + '***********\n' + '\n' + 'Unlike C, all comparison operations in Python have the same ' + 'priority,\n' + 'which is lower than that of any arithmetic, shifting or ' + 'bitwise\n' + 'operation. Also unlike C, expressions like "a < b < c" ' + 'have the\n' + 'interpretation that is conventional in mathematics:\n' + '\n' + ' comparison ::= or_expr ( comp_operator or_expr )*\n' + ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' + ' | "is" ["not"] | ["not"] "in"\n' + '\n' + 'Comparisons yield boolean values: "True" or "False".\n' + '\n' + 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" ' + 'is\n' + 'equivalent to "x < y and y <= z", except that "y" is ' + 'evaluated only\n' + 'once (but in both cases "z" is not evaluated at all when "x ' + '< y" is\n' + 'found to be false).\n' + '\n' + 'Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions ' + 'and *op1*,\n' + '*op2*, ..., *opN* are comparison operators, then "a op1 b ' + 'op2 c ... y\n' + 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' + 'z", except\n' + 'that each expression is evaluated at most once.\n' + '\n' + 'Note that "a op1 b op2 c" doesn\'t imply any kind of ' + 'comparison between\n' + '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' + '(though\n' + 'perhaps not pretty).\n' + '\n' + '\n' + 'Value comparisons\n' + '=================\n' + '\n' + 'The operators "<", ">", "==", ">=", "<=", and "!=" compare ' + 'the values\n' + 'of two objects. The objects do not need to have the same ' + 'type.\n' + '\n' + 'Chapter *Objects, values and types* states that objects ' + 'have a value\n' + '(in addition to type and identity). The value of an object ' + 'is a\n' + 'rather abstract notion in Python: For example, there is no ' + 'canonical\n' + "access method for an object's value. Also, there is no " + 'requirement\n' + 'that the value of an object should be constructed in a ' + 'particular way,\n' + 'e.g. comprised of all its data attributes. Comparison ' + 'operators\n' + 'implement a particular notion of what the value of an ' + 'object is. One\n' + 'can think of them as defining the value of an object ' + 'indirectly, by\n' + 'means of their comparison implementation.\n' + '\n' + 'Because all types are (direct or indirect) subtypes of ' + '"object", they\n' + 'inherit the default comparison behavior from "object". ' + 'Types can\n' + 'customize their comparison behavior by implementing *rich ' + 'comparison\n' + 'methods* like "__lt__()", described in *Basic ' + 'customization*.\n' + '\n' + 'The default behavior for equality comparison ("==" and ' + '"!=") is based\n' + 'on the identity of the objects. Hence, equality comparison ' + 'of\n' + 'instances with the same identity results in equality, and ' + 'equality\n' + 'comparison of instances with different identities results ' + 'in\n' + 'inequality. A motivation for this default behavior is the ' + 'desire that\n' + 'all objects should be reflexive (i.e. "x is y" implies "x ' + '== y").\n' + '\n' + 'A default order comparison ("<", ">", "<=", and ">=") is ' + 'not provided;\n' + 'an attempt raises "TypeError". A motivation for this ' + 'default behavior\n' + 'is the lack of a similar invariant as for equality.\n' + '\n' + 'The behavior of the default equality comparison, that ' + 'instances with\n' + 'different identities are always unequal, may be in contrast ' + 'to what\n' + 'types will need that have a sensible definition of object ' + 'value and\n' + 'value-based equality. Such types will need to customize ' + 'their\n' + 'comparison behavior, and in fact, a number of built-in ' + 'types have done\n' + 'that.\n' + '\n' + 'The following list describes the comparison behavior of the ' + 'most\n' + 'important built-in types.\n' + '\n' + '* Numbers of built-in numeric types (*Numeric Types --- ' + 'int, float,\n' + ' complex*) and of the standard library types ' + '"fractions.Fraction" and\n' + ' "decimal.Decimal" can be compared within and across their ' + 'types,\n' + ' with the restriction that complex numbers do not support ' + 'order\n' + ' comparison. Within the limits of the types involved, ' + 'they compare\n' + ' mathematically (algorithmically) correct without loss of ' + 'precision.\n' + '\n' + ' The not-a-number values "float(\'NaN\')" and ' + '"Decimal(\'NaN\')" are\n' + ' special. They are identical to themselves ("x is x" is ' + 'true) but\n' + ' are not equal to themselves ("x == x" is false). ' + 'Additionally,\n' + ' comparing any number to a not-a-number value will return ' + '"False".\n' + ' For example, both "3 < float(\'NaN\')" and ' + '"float(\'NaN\') < 3" will\n' + ' return "False".\n' + '\n' + '* Binary sequences (instances of "bytes" or "bytearray") ' + 'can be\n' + ' compared within and across their types. They compare\n' + ' lexicographically using the numeric values of their ' + 'elements.\n' + '\n' + '* Strings (instances of "str") compare lexicographically ' + 'using the\n' + ' numerical Unicode code points (the result of the built-in ' + 'function\n' + ' "ord()") of their characters. [3]\n' + '\n' + ' Strings and binary sequences cannot be directly ' + 'compared.\n' + '\n' + '* Sequences (instances of "tuple", "list", or "range") can ' + 'be\n' + ' compared only within each of their types, with the ' + 'restriction that\n' + ' ranges do not support order comparison. Equality ' + 'comparison across\n' + ' these types results in unequality, and ordering ' + 'comparison across\n' + ' these types raises "TypeError".\n' + '\n' + ' Sequences compare lexicographically using comparison of\n' + ' corresponding elements, whereby reflexivity of the ' + 'elements is\n' + ' enforced.\n' + '\n' + ' In enforcing reflexivity of elements, the comparison of ' + 'collections\n' + ' assumes that for a collection element "x", "x == x" is ' + 'always true.\n' + ' Based on that assumption, element identity is compared ' + 'first, and\n' + ' element comparison is performed only for distinct ' + 'elements. This\n' + ' approach yields the same result as a strict element ' + 'comparison\n' + ' would, if the compared elements are reflexive. For ' + 'non-reflexive\n' + ' elements, the result is different than for strict ' + 'element\n' + ' comparison, and may be surprising: The non-reflexive ' + 'not-a-number\n' + ' values for example result in the following comparison ' + 'behavior when\n' + ' used in a list:\n' + '\n' + " >>> nan = float('NaN')\n" + ' >>> nan is nan\n' + ' True\n' + ' >>> nan == nan\n' + ' False <-- the defined non-reflexive ' + 'behavior of NaN\n' + ' >>> [nan] == [nan]\n' + ' True <-- list enforces reflexivity ' + 'and tests identity first\n' + '\n' + ' Lexicographical comparison between built-in collections ' + 'works as\n' + ' follows:\n' + '\n' + ' * For two collections to compare equal, they must be of ' + 'the same\n' + ' type, have the same length, and each pair of ' + 'corresponding\n' + ' elements must compare equal (for example, "[1,2] == ' + '(1,2)" is\n' + ' false because the type is not the same).\n' + '\n' + ' * Collections that support order comparison are ordered ' + 'the same\n' + ' as their first unequal elements (for example, "[1,2,x] ' + '<= [1,2,y]"\n' + ' has the same value as "x <= y"). If a corresponding ' + 'element does\n' + ' not exist, the shorter collection is ordered first (for ' + 'example,\n' + ' "[1,2] < [1,2,3]" is true).\n' + '\n' + '* Mappings (instances of "dict") compare equal if and only ' + 'if they\n' + ' have equal *(key, value)* pairs. Equality comparison of ' + 'the keys and\n' + ' elements enforces reflexivity.\n' + '\n' + ' Order comparisons ("<", ">", "<=", and ">=") raise ' + '"TypeError".\n' + '\n' + '* Sets (instances of "set" or "frozenset") can be compared ' + 'within\n' + ' and across their types.\n' + '\n' + ' They define order comparison operators to mean subset and ' + 'superset\n' + ' tests. Those relations do not define total orderings ' + '(for example,\n' + ' the two sets "{1,2}" and "{2,3}" are not equal, nor ' + 'subsets of one\n' + ' another, nor supersets of one another). Accordingly, ' + 'sets are not\n' + ' appropriate arguments for functions which depend on total ' + 'ordering\n' + ' (for example, "min()", "max()", and "sorted()" produce ' + 'undefined\n' + ' results given a list of sets as inputs).\n' + '\n' + ' Comparison of sets enforces reflexivity of its elements.\n' + '\n' + '* Most other built-in types have no comparison methods ' + 'implemented,\n' + ' so they inherit the default comparison behavior.\n' + '\n' + 'User-defined classes that customize their comparison ' + 'behavior should\n' + 'follow some consistency rules, if possible:\n' + '\n' + '* Equality comparison should be reflexive. In other words, ' + 'identical\n' + ' objects should compare equal:\n' + '\n' + ' "x is y" implies "x == y"\n' + '\n' + '* Comparison should be symmetric. In other words, the ' + 'following\n' + ' expressions should have the same result:\n' + '\n' + ' "x == y" and "y == x"\n' + '\n' + ' "x != y" and "y != x"\n' + '\n' + ' "x < y" and "y > x"\n' + '\n' + ' "x <= y" and "y >= x"\n' + '\n' + '* Comparison should be transitive. The following ' + '(non-exhaustive)\n' + ' examples illustrate that:\n' + '\n' + ' "x > y and y > z" implies "x > z"\n' + '\n' + ' "x < y and y <= z" implies "x < z"\n' + '\n' + '* Inverse comparison should result in the boolean negation. ' + 'In other\n' + ' words, the following expressions should have the same ' + 'result:\n' + '\n' + ' "x == y" and "not x != y"\n' + '\n' + ' "x < y" and "not x >= y" (for total ordering)\n' + '\n' + ' "x > y" and "not x <= y" (for total ordering)\n' + '\n' + ' The last two expressions apply to totally ordered ' + 'collections (e.g.\n' + ' to sequences, but not to sets or mappings). See also the\n' + ' "total_ordering()" decorator.\n' + '\n' + 'Python does not enforce these consistency rules. In fact, ' + 'the\n' + 'not-a-number values are an example for not following these ' + 'rules.\n' + '\n' + '\n' + 'Membership test operations\n' + '==========================\n' + '\n' + 'The operators "in" and "not in" test for membership. "x in ' + 's"\n' + 'evaluates to true if *x* is a member of *s*, and false ' + 'otherwise. "x\n' + 'not in s" returns the negation of "x in s". All built-in ' + 'sequences\n' + 'and set types support this as well as dictionary, for which ' + '"in" tests\n' + 'whether the dictionary has a given key. For container types ' + 'such as\n' + 'list, tuple, set, frozenset, dict, or collections.deque, ' + 'the\n' + 'expression "x in y" is equivalent to "any(x is e or x == e ' + 'for e in\n' + 'y)".\n' + '\n' + 'For the string and bytes types, "x in y" is true if and ' + 'only if *x* is\n' + 'a substring of *y*. An equivalent test is "y.find(x) != ' + '-1". Empty\n' + 'strings are always considered to be a substring of any ' + 'other string,\n' + 'so """ in "abc"" will return "True".\n' + '\n' + 'For user-defined classes which define the "__contains__()" ' + 'method, "x\n' + 'in y" is true if and only if "y.__contains__(x)" is true.\n' + '\n' + 'For user-defined classes which do not define ' + '"__contains__()" but do\n' + 'define "__iter__()", "x in y" is true if some value "z" ' + 'with "x == z"\n' + 'is produced while iterating over "y". If an exception is ' + 'raised\n' + 'during the iteration, it is as if "in" raised that ' + 'exception.\n' + '\n' + 'Lastly, the old-style iteration protocol is tried: if a ' + 'class defines\n' + '"__getitem__()", "x in y" is true if and only if there is a ' + 'non-\n' + 'negative integer index *i* such that "x == y[i]", and all ' + 'lower\n' + 'integer indices do not raise "IndexError" exception. (If ' + 'any other\n' + 'exception is raised, it is as if "in" raised that ' + 'exception).\n' + '\n' + 'The operator "not in" is defined to have the inverse true ' + 'value of\n' + '"in".\n' + '\n' + '\n' + 'Identity comparisons\n' + '====================\n' + '\n' + 'The operators "is" and "is not" test for object identity: ' + '"x is y" is\n' + 'true if and only if *x* and *y* are the same object. "x is ' + 'not y"\n' + 'yields the inverse truth value. [4]\n', + 'compound': '\n' + 'Compound statements\n' + '*******************\n' + '\n' + 'Compound statements contain (groups of) other statements; they ' + 'affect\n' + 'or control the execution of those other statements in some ' + 'way. In\n' + 'general, compound statements span multiple lines, although in ' + 'simple\n' + 'incarnations a whole compound statement may be contained in ' + 'one line.\n' + '\n' + 'The "if", "while" and "for" statements implement traditional ' + 'control\n' + 'flow constructs. "try" specifies exception handlers and/or ' + 'cleanup\n' + 'code for a group of statements, while the "with" statement ' + 'allows the\n' + 'execution of initialization and finalization code around a ' + 'block of\n' + 'code. Function and class definitions are also syntactically ' + 'compound\n' + 'statements.\n' + '\n' + "A compound statement consists of one or more 'clauses.' A " + 'clause\n' + "consists of a header and a 'suite.' The clause headers of a\n" + 'particular compound statement are all at the same indentation ' + 'level.\n' + 'Each clause header begins with a uniquely identifying keyword ' + 'and ends\n' + 'with a colon. A suite is a group of statements controlled by ' + 'a\n' + 'clause. A suite can be one or more semicolon-separated ' + 'simple\n' + 'statements on the same line as the header, following the ' + "header's\n" + 'colon, or it can be one or more indented statements on ' + 'subsequent\n' + 'lines. Only the latter form of a suite can contain nested ' + 'compound\n' + 'statements; the following is illegal, mostly because it ' + "wouldn't be\n" + 'clear to which "if" clause a following "else" clause would ' + 'belong:\n' + '\n' + ' if test1: if test2: print(x)\n' + '\n' + 'Also note that the semicolon binds tighter than the colon in ' + 'this\n' + 'context, so that in the following example, either all or none ' + 'of the\n' + '"print()" calls are executed:\n' + '\n' + ' if x < y < z: print(x); print(y); print(z)\n' + '\n' + 'Summarizing:\n' + '\n' + ' compound_stmt ::= if_stmt\n' + ' | while_stmt\n' + ' | for_stmt\n' + ' | try_stmt\n' + ' | with_stmt\n' + ' | funcdef\n' + ' | classdef\n' + ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' + 'statement+ DEDENT\n' + ' statement ::= stmt_list NEWLINE | compound_stmt\n' + ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n' + '\n' + 'Note that statements always end in a "NEWLINE" possibly ' + 'followed by a\n' + '"DEDENT". Also note that optional continuation clauses always ' + 'begin\n' + 'with a keyword that cannot start a statement, thus there are ' + 'no\n' + 'ambiguities (the \'dangling "else"\' problem is solved in ' + 'Python by\n' + 'requiring nested "if" statements to be indented).\n' + '\n' + 'The formatting of the grammar rules in the following sections ' + 'places\n' + 'each clause on a separate line for clarity.\n' + '\n' + '\n' + 'The "if" statement\n' + '==================\n' + '\n' + 'The "if" statement is used for conditional execution:\n' + '\n' + ' if_stmt ::= "if" expression ":" suite\n' + ' ( "elif" expression ":" suite )*\n' + ' ["else" ":" suite]\n' + '\n' + 'It selects exactly one of the suites by evaluating the ' + 'expressions one\n' + 'by one until one is found to be true (see section *Boolean ' + 'operations*\n' + 'for the definition of true and false); then that suite is ' + 'executed\n' + '(and no other part of the "if" statement is executed or ' + 'evaluated).\n' + 'If all expressions are false, the suite of the "else" clause, ' + 'if\n' + 'present, is executed.\n' + '\n' + '\n' + 'The "while" statement\n' + '=====================\n' + '\n' + 'The "while" statement is used for repeated execution as long ' + 'as an\n' + 'expression is true:\n' + '\n' + ' while_stmt ::= "while" expression ":" suite\n' + ' ["else" ":" suite]\n' + '\n' + 'This repeatedly tests the expression and, if it is true, ' + 'executes the\n' + 'first suite; if the expression is false (which may be the ' + 'first time\n' + 'it is tested) the suite of the "else" clause, if present, is ' + 'executed\n' + 'and the loop terminates.\n' + '\n' + 'A "break" statement executed in the first suite terminates the ' + 'loop\n' + 'without executing the "else" clause\'s suite. A "continue" ' + 'statement\n' + 'executed in the first suite skips the rest of the suite and ' + 'goes back\n' + 'to testing the expression.\n' + '\n' + '\n' + 'The "for" statement\n' + '===================\n' + '\n' + 'The "for" statement is used to iterate over the elements of a ' + 'sequence\n' + '(such as a string, tuple or list) or other iterable object:\n' + '\n' + ' for_stmt ::= "for" target_list "in" expression_list ":" ' + 'suite\n' + ' ["else" ":" suite]\n' + '\n' + 'The expression list is evaluated once; it should yield an ' + 'iterable\n' + 'object. An iterator is created for the result of the\n' + '"expression_list". The suite is then executed once for each ' + 'item\n' + 'provided by the iterator, in the order returned by the ' + 'iterator. Each\n' + 'item in turn is assigned to the target list using the standard ' + 'rules\n' + 'for assignments (see *Assignment statements*), and then the ' + 'suite is\n' + 'executed. When the items are exhausted (which is immediately ' + 'when the\n' + 'sequence is empty or an iterator raises a "StopIteration" ' + 'exception),\n' + 'the suite in the "else" clause, if present, is executed, and ' + 'the loop\n' + 'terminates.\n' + '\n' + 'A "break" statement executed in the first suite terminates the ' + 'loop\n' + 'without executing the "else" clause\'s suite. A "continue" ' + 'statement\n' + 'executed in the first suite skips the rest of the suite and ' + 'continues\n' + 'with the next item, or with the "else" clause if there is no ' + 'next\n' + 'item.\n' + '\n' + 'The for-loop makes assignments to the variables(s) in the ' + 'target list.\n' + 'This overwrites all previous assignments to those variables ' + 'including\n' + 'those made in the suite of the for-loop:\n' + '\n' + ' for i in range(10):\n' + ' print(i)\n' + ' i = 5 # this will not affect the for-loop\n' + ' # because i will be overwritten with ' + 'the next\n' + ' # index in the range\n' + '\n' + 'Names in the target list are not deleted when the loop is ' + 'finished,\n' + 'but if the sequence is empty, they will not have been assigned ' + 'to at\n' + 'all by the loop. Hint: the built-in function "range()" ' + 'returns an\n' + 'iterator of integers suitable to emulate the effect of ' + 'Pascal\'s "for i\n' + ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' + '2]".\n' + '\n' + 'Note: There is a subtlety when the sequence is being modified ' + 'by the\n' + ' loop (this can only occur for mutable sequences, i.e. ' + 'lists). An\n' + ' internal counter is used to keep track of which item is used ' + 'next,\n' + ' and this is incremented on each iteration. When this ' + 'counter has\n' + ' reached the length of the sequence the loop terminates. ' + 'This means\n' + ' that if the suite deletes the current (or a previous) item ' + 'from the\n' + ' sequence, the next item will be skipped (since it gets the ' + 'index of\n' + ' the current item which has already been treated). Likewise, ' + 'if the\n' + ' suite inserts an item in the sequence before the current ' + 'item, the\n' + ' current item will be treated again the next time through the ' + 'loop.\n' + ' This can lead to nasty bugs that can be avoided by making a\n' + ' temporary copy using a slice of the whole sequence, e.g.,\n' + '\n' + ' for x in a[:]:\n' + ' if x < 0: a.remove(x)\n' + '\n' + '\n' + 'The "try" statement\n' + '===================\n' + '\n' + 'The "try" statement specifies exception handlers and/or ' + 'cleanup code\n' + 'for a group of statements:\n' + '\n' + ' try_stmt ::= try1_stmt | try2_stmt\n' + ' try1_stmt ::= "try" ":" suite\n' + ' ("except" [expression ["as" identifier]] ":" ' + 'suite)+\n' + ' ["else" ":" suite]\n' + ' ["finally" ":" suite]\n' + ' try2_stmt ::= "try" ":" suite\n' + ' "finally" ":" suite\n' + '\n' + 'The "except" clause(s) specify one or more exception handlers. ' + 'When no\n' + 'exception occurs in the "try" clause, no exception handler is\n' + 'executed. When an exception occurs in the "try" suite, a ' + 'search for an\n' + 'exception handler is started. This search inspects the except ' + 'clauses\n' + 'in turn until one is found that matches the exception. An ' + 'expression-\n' + 'less except clause, if present, must be last; it matches any\n' + 'exception. For an except clause with an expression, that ' + 'expression\n' + 'is evaluated, and the clause matches the exception if the ' + 'resulting\n' + 'object is "compatible" with the exception. An object is ' + 'compatible\n' + 'with an exception if it is the class or a base class of the ' + 'exception\n' + 'object or a tuple containing an item compatible with the ' + 'exception.\n' + '\n' + 'If no except clause matches the exception, the search for an ' + 'exception\n' + 'handler continues in the surrounding code and on the ' + 'invocation stack.\n' + '[1]\n' + '\n' + 'If the evaluation of an expression in the header of an except ' + 'clause\n' + 'raises an exception, the original search for a handler is ' + 'canceled and\n' + 'a search starts for the new exception in the surrounding code ' + 'and on\n' + 'the call stack (it is treated as if the entire "try" statement ' + 'raised\n' + 'the exception).\n' + '\n' + 'When a matching except clause is found, the exception is ' + 'assigned to\n' + 'the target specified after the "as" keyword in that except ' + 'clause, if\n' + "present, and the except clause's suite is executed. All " + 'except\n' + 'clauses must have an executable block. When the end of this ' + 'block is\n' + 'reached, execution continues normally after the entire try ' + 'statement.\n' + '(This means that if two nested handlers exist for the same ' + 'exception,\n' + 'and the exception occurs in the try clause of the inner ' + 'handler, the\n' + 'outer handler will not handle the exception.)\n' + '\n' + 'When an exception has been assigned using "as target", it is ' + 'cleared\n' + 'at the end of the except clause. This is as if\n' + '\n' + ' except E as N:\n' + ' foo\n' + '\n' + 'was translated to\n' + '\n' + ' except E as N:\n' + ' try:\n' + ' foo\n' + ' finally:\n' + ' del N\n' + '\n' + 'This means the exception must be assigned to a different name ' + 'to be\n' + 'able to refer to it after the except clause. Exceptions are ' + 'cleared\n' + 'because with the traceback attached to them, they form a ' + 'reference\n' + 'cycle with the stack frame, keeping all locals in that frame ' + 'alive\n' + 'until the next garbage collection occurs.\n' + '\n' + "Before an except clause's suite is executed, details about " + 'the\n' + 'exception are stored in the "sys" module and can be accessed ' + 'via\n' + '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple ' + 'consisting of the\n' + 'exception class, the exception instance and a traceback object ' + '(see\n' + 'section *The standard type hierarchy*) identifying the point ' + 'in the\n' + 'program where the exception occurred. "sys.exc_info()" values ' + 'are\n' + 'restored to their previous values (before the call) when ' + 'returning\n' + 'from a function that handled an exception.\n' + '\n' + 'The optional "else" clause is executed if and when control ' + 'flows off\n' + 'the end of the "try" clause. [2] Exceptions in the "else" ' + 'clause are\n' + 'not handled by the preceding "except" clauses.\n' + '\n' + 'If "finally" is present, it specifies a \'cleanup\' handler. ' + 'The "try"\n' + 'clause is executed, including any "except" and "else" ' + 'clauses. If an\n' + 'exception occurs in any of the clauses and is not handled, ' + 'the\n' + 'exception is temporarily saved. The "finally" clause is ' + 'executed. If\n' + 'there is a saved exception it is re-raised at the end of the ' + '"finally"\n' + 'clause. If the "finally" clause raises another exception, the ' + 'saved\n' + 'exception is set as the context of the new exception. If the ' + '"finally"\n' + 'clause executes a "return" or "break" statement, the saved ' + 'exception\n' + 'is discarded:\n' + '\n' + ' >>> def f():\n' + ' ... try:\n' + ' ... 1/0\n' + ' ... finally:\n' + ' ... return 42\n' + ' ...\n' + ' >>> f()\n' + ' 42\n' + '\n' + 'The exception information is not available to the program ' + 'during\n' + 'execution of the "finally" clause.\n' + '\n' + 'When a "return", "break" or "continue" statement is executed ' + 'in the\n' + '"try" suite of a "try"..."finally" statement, the "finally" ' + 'clause is\n' + 'also executed \'on the way out.\' A "continue" statement is ' + 'illegal in\n' + 'the "finally" clause. (The reason is a problem with the ' + 'current\n' + 'implementation --- this restriction may be lifted in the ' + 'future).\n' + '\n' + 'The return value of a function is determined by the last ' + '"return"\n' + 'statement executed. Since the "finally" clause always ' + 'executes, a\n' + '"return" statement executed in the "finally" clause will ' + 'always be the\n' + 'last one executed:\n' + '\n' + ' >>> def foo():\n' + ' ... try:\n' + " ... return 'try'\n" + ' ... finally:\n' + " ... return 'finally'\n" + ' ...\n' + ' >>> foo()\n' + " 'finally'\n" + '\n' + 'Additional information on exceptions can be found in section\n' + '*Exceptions*, and information on using the "raise" statement ' + 'to\n' + 'generate exceptions may be found in section *The raise ' + 'statement*.\n' + '\n' + '\n' + 'The "with" statement\n' + '====================\n' + '\n' + 'The "with" statement is used to wrap the execution of a block ' + 'with\n' + 'methods defined by a context manager (see section *With ' + 'Statement\n' + 'Context Managers*). This allows common ' + '"try"..."except"..."finally"\n' + 'usage patterns to be encapsulated for convenient reuse.\n' + '\n' + ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' + ' with_item ::= expression ["as" target]\n' + '\n' + 'The execution of the "with" statement with one "item" proceeds ' + 'as\n' + 'follows:\n' + '\n' + '1. The context expression (the expression given in the ' + '"with_item")\n' + ' is evaluated to obtain a context manager.\n' + '\n' + '2. The context manager\'s "__exit__()" is loaded for later ' + 'use.\n' + '\n' + '3. The context manager\'s "__enter__()" method is invoked.\n' + '\n' + '4. If a target was included in the "with" statement, the ' + 'return\n' + ' value from "__enter__()" is assigned to it.\n' + '\n' + ' Note: The "with" statement guarantees that if the ' + '"__enter__()"\n' + ' method returns without an error, then "__exit__()" will ' + 'always be\n' + ' called. Thus, if an error occurs during the assignment to ' + 'the\n' + ' target list, it will be treated the same as an error ' + 'occurring\n' + ' within the suite would be. See step 6 below.\n' + '\n' + '5. The suite is executed.\n' + '\n' + '6. The context manager\'s "__exit__()" method is invoked. If ' + 'an\n' + ' exception caused the suite to be exited, its type, value, ' + 'and\n' + ' traceback are passed as arguments to "__exit__()". ' + 'Otherwise, three\n' + ' "None" arguments are supplied.\n' + '\n' + ' If the suite was exited due to an exception, and the return ' + 'value\n' + ' from the "__exit__()" method was false, the exception is ' + 'reraised.\n' + ' If the return value was true, the exception is suppressed, ' + 'and\n' + ' execution continues with the statement following the ' + '"with"\n' + ' statement.\n' + '\n' + ' If the suite was exited for any reason other than an ' + 'exception, the\n' + ' return value from "__exit__()" is ignored, and execution ' + 'proceeds\n' + ' at the normal location for the kind of exit that was ' + 'taken.\n' + '\n' + 'With more than one item, the context managers are processed as ' + 'if\n' + 'multiple "with" statements were nested:\n' + '\n' + ' with A() as a, B() as b:\n' + ' suite\n' + '\n' + 'is equivalent to\n' + '\n' + ' with A() as a:\n' + ' with B() as b:\n' + ' suite\n' + '\n' + 'Changed in version 3.1: Support for multiple context ' + 'expressions.\n' + '\n' + 'See also: **PEP 0343** - The "with" statement\n' + '\n' + ' The specification, background, and examples for the ' + 'Python "with"\n' + ' statement.\n' + '\n' + '\n' + 'Function definitions\n' + '====================\n' + '\n' + 'A function definition defines a user-defined function object ' + '(see\n' + 'section *The standard type hierarchy*):\n' + '\n' + ' funcdef ::= [decorators] "def" funcname "(" ' + '[parameter_list] ")" ["->" expression] ":" suite\n' + ' decorators ::= decorator+\n' + ' decorator ::= "@" dotted_name ["(" [parameter_list ' + '[","]] ")"] NEWLINE\n' + ' dotted_name ::= identifier ("." identifier)*\n' + ' parameter_list ::= (defparameter ",")*\n' + ' | "*" [parameter] ("," defparameter)* ' + '["," "**" parameter]\n' + ' | "**" parameter\n' + ' | defparameter [","] )\n' + ' parameter ::= identifier [":" expression]\n' + ' defparameter ::= parameter ["=" expression]\n' + ' funcname ::= identifier\n' + '\n' + 'A function definition is an executable statement. Its ' + 'execution binds\n' + 'the function name in the current local namespace to a function ' + 'object\n' + '(a wrapper around the executable code for the function). ' + 'This\n' + 'function object contains a reference to the current global ' + 'namespace\n' + 'as the global namespace to be used when the function is ' + 'called.\n' + '\n' + 'The function definition does not execute the function body; ' + 'this gets\n' + 'executed only when the function is called. [3]\n' + '\n' + 'A function definition may be wrapped by one or more ' + '*decorator*\n' + 'expressions. Decorator expressions are evaluated when the ' + 'function is\n' + 'defined, in the scope that contains the function definition. ' + 'The\n' + 'result must be a callable, which is invoked with the function ' + 'object\n' + 'as the only argument. The returned value is bound to the ' + 'function name\n' + 'instead of the function object. Multiple decorators are ' + 'applied in\n' + 'nested fashion. For example, the following code\n' + '\n' + ' @f1(arg)\n' + ' @f2\n' + ' def func(): pass\n' + '\n' + 'is equivalent to\n' + '\n' + ' def func(): pass\n' + ' func = f1(arg)(f2(func))\n' + '\n' + 'When one or more *parameters* have the form *parameter* "="\n' + '*expression*, the function is said to have "default parameter ' + 'values."\n' + 'For a parameter with a default value, the corresponding ' + '*argument* may\n' + "be omitted from a call, in which case the parameter's default " + 'value is\n' + 'substituted. If a parameter has a default value, all ' + 'following\n' + 'parameters up until the ""*"" must also have a default value ' + '--- this\n' + 'is a syntactic restriction that is not expressed by the ' + 'grammar.\n' + '\n' + '**Default parameter values are evaluated from left to right ' + 'when the\n' + 'function definition is executed.** This means that the ' + 'expression is\n' + 'evaluated once, when the function is defined, and that the ' + 'same "pre-\n' + 'computed" value is used for each call. This is especially ' + 'important\n' + 'to understand when a default parameter is a mutable object, ' + 'such as a\n' + 'list or a dictionary: if the function modifies the object ' + '(e.g. by\n' + 'appending an item to a list), the default value is in effect ' + 'modified.\n' + 'This is generally not what was intended. A way around this is ' + 'to use\n' + '"None" as the default, and explicitly test for it in the body ' + 'of the\n' + 'function, e.g.:\n' + '\n' + ' def whats_on_the_telly(penguin=None):\n' + ' if penguin is None:\n' + ' penguin = []\n' + ' penguin.append("property of the zoo")\n' + ' return penguin\n' + '\n' + 'Function call semantics are described in more detail in ' + 'section\n' + '*Calls*. A function call always assigns values to all ' + 'parameters\n' + 'mentioned in the parameter list, either from position ' + 'arguments, from\n' + 'keyword arguments, or from default values. If the form\n' + '""*identifier"" is present, it is initialized to a tuple ' + 'receiving any\n' + 'excess positional parameters, defaulting to the empty tuple. ' + 'If the\n' + 'form ""**identifier"" is present, it is initialized to a new\n' + 'dictionary receiving any excess keyword arguments, defaulting ' + 'to a new\n' + 'empty dictionary. Parameters after ""*"" or ""*identifier"" ' + 'are\n' + 'keyword-only parameters and may only be passed used keyword ' + 'arguments.\n' + '\n' + 'Parameters may have annotations of the form "": expression"" ' + 'following\n' + 'the parameter name. Any parameter may have an annotation even ' + 'those\n' + 'of the form "*identifier" or "**identifier". Functions may ' + 'have\n' + '"return" annotation of the form ""-> expression"" after the ' + 'parameter\n' + 'list. These annotations can be any valid Python expression ' + 'and are\n' + 'evaluated when the function definition is executed. ' + 'Annotations may\n' + 'be evaluated in a different order than they appear in the ' + 'source code.\n' + 'The presence of annotations does not change the semantics of ' + 'a\n' + 'function. The annotation values are available as values of a\n' + "dictionary keyed by the parameters' names in the " + '"__annotations__"\n' + 'attribute of the function object.\n' + '\n' + 'It is also possible to create anonymous functions (functions ' + 'not bound\n' + 'to a name), for immediate use in expressions. This uses ' + 'lambda\n' + 'expressions, described in section *Lambdas*. Note that the ' + 'lambda\n' + 'expression is merely a shorthand for a simplified function ' + 'definition;\n' + 'a function defined in a ""def"" statement can be passed around ' + 'or\n' + 'assigned to another name just like a function defined by a ' + 'lambda\n' + 'expression. The ""def"" form is actually more powerful since ' + 'it\n' + 'allows the execution of multiple statements and annotations.\n' + '\n' + "**Programmer's note:** Functions are first-class objects. A " + '""def""\n' + 'statement executed inside a function definition defines a ' + 'local\n' + 'function that can be returned or passed around. Free ' + 'variables used\n' + 'in the nested function can access the local variables of the ' + 'function\n' + 'containing the def. See section *Naming and binding* for ' + 'details.\n' + '\n' + 'See also: **PEP 3107** - Function Annotations\n' + '\n' + ' The original specification for function annotations.\n' + '\n' + '\n' + 'Class definitions\n' + '=================\n' + '\n' + 'A class definition defines a class object (see section *The ' + 'standard\n' + 'type hierarchy*):\n' + '\n' + ' classdef ::= [decorators] "class" classname ' + '[inheritance] ":" suite\n' + ' inheritance ::= "(" [parameter_list] ")"\n' + ' classname ::= identifier\n' + '\n' + 'A class definition is an executable statement. The ' + 'inheritance list\n' + 'usually gives a list of base classes (see *Customizing class ' + 'creation*\n' + 'for more advanced uses), so each item in the list should ' + 'evaluate to a\n' + 'class object which allows subclassing. Classes without an ' + 'inheritance\n' + 'list inherit, by default, from the base class "object"; ' + 'hence,\n' + '\n' + ' class Foo:\n' + ' pass\n' + '\n' + 'is equivalent to\n' + '\n' + ' class Foo(object):\n' + ' pass\n' + '\n' + "The class's suite is then executed in a new execution frame " + '(see\n' + '*Naming and binding*), using a newly created local namespace ' + 'and the\n' + 'original global namespace. (Usually, the suite contains ' + 'mostly\n' + "function definitions.) When the class's suite finishes " + 'execution, its\n' + 'execution frame is discarded but its local namespace is saved. ' + '[4] A\n' + 'class object is then created using the inheritance list for ' + 'the base\n' + 'classes and the saved local namespace for the attribute ' + 'dictionary.\n' + 'The class name is bound to this class object in the original ' + 'local\n' + 'namespace.\n' + '\n' + 'Class creation can be customized heavily using *metaclasses*.\n' + '\n' + 'Classes can also be decorated: just like when decorating ' + 'functions,\n' + '\n' + ' @f1(arg)\n' + ' @f2\n' + ' class Foo: pass\n' + '\n' + 'is equivalent to\n' + '\n' + ' class Foo: pass\n' + ' Foo = f1(arg)(f2(Foo))\n' + '\n' + 'The evaluation rules for the decorator expressions are the ' + 'same as for\n' + 'function decorators. The result must be a class object, which ' + 'is then\n' + 'bound to the class name.\n' + '\n' + "**Programmer's note:** Variables defined in the class " + 'definition are\n' + 'class attributes; they are shared by instances. Instance ' + 'attributes\n' + 'can be set in a method with "self.name = value". Both class ' + 'and\n' + 'instance attributes are accessible through the notation ' + '""self.name"",\n' + 'and an instance attribute hides a class attribute with the ' + 'same name\n' + 'when accessed in this way. Class attributes can be used as ' + 'defaults\n' + 'for instance attributes, but using mutable values there can ' + 'lead to\n' + 'unexpected results. *Descriptors* can be used to create ' + 'instance\n' + 'variables with different implementation details.\n' + '\n' + 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** ' + '-\n' + ' Class Decorators\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] The exception is propagated to the invocation stack ' + 'unless\n' + ' there is a "finally" clause which happens to raise ' + 'another\n' + ' exception. That new exception causes the old one to be ' + 'lost.\n' + '\n' + '[2] Currently, control "flows off the end" except in the case ' + 'of\n' + ' an exception or the execution of a "return", "continue", ' + 'or\n' + ' "break" statement.\n' + '\n' + '[3] A string literal appearing as the first statement in the\n' + " function body is transformed into the function's " + '"__doc__"\n' + " attribute and therefore the function's *docstring*.\n" + '\n' + '[4] A string literal appearing as the first statement in the ' + 'class\n' + ' body is transformed into the namespace\'s "__doc__" item ' + 'and\n' + " therefore the class's *docstring*.\n", + 'context-managers': '\n' + 'With Statement Context Managers\n' + '*******************************\n' + '\n' + 'A *context manager* is an object that defines the ' + 'runtime context to\n' + 'be established when executing a "with" statement. The ' + 'context manager\n' + 'handles the entry into, and the exit from, the desired ' + 'runtime context\n' + 'for the execution of the block of code. Context ' + 'managers are normally\n' + 'invoked using the "with" statement (described in ' + 'section *The with\n' + 'statement*), but can also be used by directly invoking ' + 'their methods.\n' + '\n' + 'Typical uses of context managers include saving and ' + 'restoring various\n' + 'kinds of global state, locking and unlocking ' + 'resources, closing opened\n' + 'files, etc.\n' + '\n' + 'For more information on context managers, see *Context ' + 'Manager Types*.\n' + '\n' + 'object.__enter__(self)\n' + '\n' + ' Enter the runtime context related to this object. ' + 'The "with"\n' + " statement will bind this method's return value to " + 'the target(s)\n' + ' specified in the "as" clause of the statement, if ' + 'any.\n' + '\n' + 'object.__exit__(self, exc_type, exc_value, traceback)\n' + '\n' + ' Exit the runtime context related to this object. ' + 'The parameters\n' + ' describe the exception that caused the context to ' + 'be exited. If the\n' + ' context was exited without an exception, all three ' + 'arguments will\n' + ' be "None".\n' + '\n' + ' If an exception is supplied, and the method wishes ' + 'to suppress the\n' + ' exception (i.e., prevent it from being propagated), ' + 'it should\n' + ' return a true value. Otherwise, the exception will ' + 'be processed\n' + ' normally upon exit from this method.\n' + '\n' + ' Note that "__exit__()" methods should not reraise ' + 'the passed-in\n' + " exception; this is the caller's responsibility.\n" + '\n' + 'See also: **PEP 0343** - The "with" statement\n' + '\n' + ' The specification, background, and examples for ' + 'the Python "with"\n' + ' statement.\n', + 'continue': '\n' + 'The "continue" statement\n' + '************************\n' + '\n' + ' continue_stmt ::= "continue"\n' + '\n' + '"continue" may only occur syntactically nested in a "for" or ' + '"while"\n' + 'loop, but not nested in a function or class definition or ' + '"finally"\n' + 'clause within that loop. It continues with the next cycle of ' + 'the\n' + 'nearest enclosing loop.\n' + '\n' + 'When "continue" passes control out of a "try" statement with ' + 'a\n' + '"finally" clause, that "finally" clause is executed before ' + 'really\n' + 'starting the next loop cycle.\n', + 'conversions': '\n' + 'Arithmetic conversions\n' + '**********************\n' + '\n' + 'When a description of an arithmetic operator below uses the ' + 'phrase\n' + '"the numeric arguments are converted to a common type," ' + 'this means\n' + 'that the operator implementation for built-in types works ' + 'as follows:\n' + '\n' + '* If either argument is a complex number, the other is ' + 'converted to\n' + ' complex;\n' + '\n' + '* otherwise, if either argument is a floating point number, ' + 'the\n' + ' other is converted to floating point;\n' + '\n' + '* otherwise, both must be integers and no conversion is ' + 'necessary.\n' + '\n' + 'Some additional rules apply for certain operators (e.g., a ' + 'string as a\n' + "left argument to the '%' operator). Extensions must define " + 'their own\n' + 'conversion behavior.\n', + 'customization': '\n' + 'Basic customization\n' + '*******************\n' + '\n' + 'object.__new__(cls[, ...])\n' + '\n' + ' Called to create a new instance of class *cls*. ' + '"__new__()" is a\n' + ' static method (special-cased so you need not declare ' + 'it as such)\n' + ' that takes the class of which an instance was ' + 'requested as its\n' + ' first argument. The remaining arguments are those ' + 'passed to the\n' + ' object constructor expression (the call to the ' + 'class). The return\n' + ' value of "__new__()" should be the new object instance ' + '(usually an\n' + ' instance of *cls*).\n' + '\n' + ' Typical implementations create a new instance of the ' + 'class by\n' + ' invoking the superclass\'s "__new__()" method using\n' + ' "super(currentclass, cls).__new__(cls[, ...])" with ' + 'appropriate\n' + ' arguments and then modifying the newly-created ' + 'instance as\n' + ' necessary before returning it.\n' + '\n' + ' If "__new__()" returns an instance of *cls*, then the ' + 'new\n' + ' instance\'s "__init__()" method will be invoked like\n' + ' "__init__(self[, ...])", where *self* is the new ' + 'instance and the\n' + ' remaining arguments are the same as were passed to ' + '"__new__()".\n' + '\n' + ' If "__new__()" does not return an instance of *cls*, ' + 'then the new\n' + ' instance\'s "__init__()" method will not be invoked.\n' + '\n' + ' "__new__()" is intended mainly to allow subclasses of ' + 'immutable\n' + ' types (like int, str, or tuple) to customize instance ' + 'creation. It\n' + ' is also commonly overridden in custom metaclasses in ' + 'order to\n' + ' customize class creation.\n' + '\n' + 'object.__init__(self[, ...])\n' + '\n' + ' Called after the instance has been created (by ' + '"__new__()"), but\n' + ' before it is returned to the caller. The arguments ' + 'are those\n' + ' passed to the class constructor expression. If a base ' + 'class has an\n' + ' "__init__()" method, the derived class\'s "__init__()" ' + 'method, if\n' + ' any, must explicitly call it to ensure proper ' + 'initialization of the\n' + ' base class part of the instance; for example:\n' + ' "BaseClass.__init__(self, [args...])".\n' + '\n' + ' Because "__new__()" and "__init__()" work together in ' + 'constructing\n' + ' objects ("__new__()" to create it, and "__init__()" to ' + 'customise\n' + ' it), no non-"None" value may be returned by ' + '"__init__()"; doing so\n' + ' will cause a "TypeError" to be raised at runtime.\n' + '\n' + 'object.__del__(self)\n' + '\n' + ' Called when the instance is about to be destroyed. ' + 'This is also\n' + ' called a destructor. If a base class has a ' + '"__del__()" method, the\n' + ' derived class\'s "__del__()" method, if any, must ' + 'explicitly call it\n' + ' to ensure proper deletion of the base class part of ' + 'the instance.\n' + ' Note that it is possible (though not recommended!) for ' + 'the\n' + ' "__del__()" method to postpone destruction of the ' + 'instance by\n' + ' creating a new reference to it. It may then be called ' + 'at a later\n' + ' time when this new reference is deleted. It is not ' + 'guaranteed that\n' + ' "__del__()" methods are called for objects that still ' + 'exist when\n' + ' the interpreter exits.\n' + '\n' + ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' + 'the former\n' + ' decrements the reference count for "x" by one, and ' + 'the latter is\n' + ' only called when "x"\'s reference count reaches ' + 'zero. Some common\n' + ' situations that may prevent the reference count of ' + 'an object from\n' + ' going to zero include: circular references between ' + 'objects (e.g.,\n' + ' a doubly-linked list or a tree data structure with ' + 'parent and\n' + ' child pointers); a reference to the object on the ' + 'stack frame of\n' + ' a function that caught an exception (the traceback ' + 'stored in\n' + ' "sys.exc_info()[2]" keeps the stack frame alive); or ' + 'a reference\n' + ' to the object on the stack frame that raised an ' + 'unhandled\n' + ' exception in interactive mode (the traceback stored ' + 'in\n' + ' "sys.last_traceback" keeps the stack frame alive). ' + 'The first\n' + ' situation can only be remedied by explicitly ' + 'breaking the cycles;\n' + ' the second can be resolved by freeing the reference ' + 'to the\n' + ' traceback object when it is no longer useful, and ' + 'the third can\n' + ' be resolved by storing "None" in ' + '"sys.last_traceback". Circular\n' + ' references which are garbage are detected and ' + 'cleaned up when the\n' + " cyclic garbage collector is enabled (it's on by " + 'default). Refer\n' + ' to the documentation for the "gc" module for more ' + 'information\n' + ' about this topic.\n' + '\n' + ' Warning: Due to the precarious circumstances under ' + 'which\n' + ' "__del__()" methods are invoked, exceptions that ' + 'occur during\n' + ' their execution are ignored, and a warning is ' + 'printed to\n' + ' "sys.stderr" instead. Also, when "__del__()" is ' + 'invoked in\n' + ' response to a module being deleted (e.g., when ' + 'execution of the\n' + ' program is done), other globals referenced by the ' + '"__del__()"\n' + ' method may already have been deleted or in the ' + 'process of being\n' + ' torn down (e.g. the import machinery shutting ' + 'down). For this\n' + ' reason, "__del__()" methods should do the absolute ' + 'minimum needed\n' + ' to maintain external invariants. Starting with ' + 'version 1.5,\n' + ' Python guarantees that globals whose name begins ' + 'with a single\n' + ' underscore are deleted from their module before ' + 'other globals are\n' + ' deleted; if no other references to such globals ' + 'exist, this may\n' + ' help in assuring that imported modules are still ' + 'available at the\n' + ' time when the "__del__()" method is called.\n' + '\n' + 'object.__repr__(self)\n' + '\n' + ' Called by the "repr()" built-in function to compute ' + 'the "official"\n' + ' string representation of an object. If at all ' + 'possible, this\n' + ' should look like a valid Python expression that could ' + 'be used to\n' + ' recreate an object with the same value (given an ' + 'appropriate\n' + ' environment). If this is not possible, a string of ' + 'the form\n' + ' "<...some useful description...>" should be returned. ' + 'The return\n' + ' value must be a string object. If a class defines ' + '"__repr__()" but\n' + ' not "__str__()", then "__repr__()" is also used when ' + 'an "informal"\n' + ' string representation of instances of that class is ' + 'required.\n' + '\n' + ' This is typically used for debugging, so it is ' + 'important that the\n' + ' representation is information-rich and unambiguous.\n' + '\n' + 'object.__str__(self)\n' + '\n' + ' Called by "str(object)" and the built-in functions ' + '"format()" and\n' + ' "print()" to compute the "informal" or nicely ' + 'printable string\n' + ' representation of an object. The return value must be ' + 'a *string*\n' + ' object.\n' + '\n' + ' This method differs from "object.__repr__()" in that ' + 'there is no\n' + ' expectation that "__str__()" return a valid Python ' + 'expression: a\n' + ' more convenient or concise representation can be ' + 'used.\n' + '\n' + ' The default implementation defined by the built-in ' + 'type "object"\n' + ' calls "object.__repr__()".\n' + '\n' + 'object.__bytes__(self)\n' + '\n' + ' Called by "bytes()" to compute a byte-string ' + 'representation of an\n' + ' object. This should return a "bytes" object.\n' + '\n' + 'object.__format__(self, format_spec)\n' + '\n' + ' Called by the "format()" built-in function (and by ' + 'extension, the\n' + ' "str.format()" method of class "str") to produce a ' + '"formatted"\n' + ' string representation of an object. The "format_spec" ' + 'argument is a\n' + ' string that contains a description of the formatting ' + 'options\n' + ' desired. The interpretation of the "format_spec" ' + 'argument is up to\n' + ' the type implementing "__format__()", however most ' + 'classes will\n' + ' either delegate formatting to one of the built-in ' + 'types, or use a\n' + ' similar formatting option syntax.\n' + '\n' + ' See *Format Specification Mini-Language* for a ' + 'description of the\n' + ' standard formatting syntax.\n' + '\n' + ' The return value must be a string object.\n' + '\n' + ' Changed in version 3.4: The __format__ method of ' + '"object" itself\n' + ' raises a "TypeError" if passed any non-empty string.\n' + '\n' + 'object.__lt__(self, other)\n' + 'object.__le__(self, other)\n' + 'object.__eq__(self, other)\n' + 'object.__ne__(self, other)\n' + 'object.__gt__(self, other)\n' + 'object.__ge__(self, other)\n' + '\n' + ' These are the so-called "rich comparison" methods. ' + 'The\n' + ' correspondence between operator symbols and method ' + 'names is as\n' + ' follows: "xy" calls\n' + ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' + '\n' + ' A rich comparison method may return the singleton ' + '"NotImplemented"\n' + ' if it does not implement the operation for a given ' + 'pair of\n' + ' arguments. By convention, "False" and "True" are ' + 'returned for a\n' + ' successful comparison. However, these methods can ' + 'return any value,\n' + ' so if the comparison operator is used in a Boolean ' + 'context (e.g.,\n' + ' in the condition of an "if" statement), Python will ' + 'call "bool()"\n' + ' on the value to determine if the result is true or ' + 'false.\n' + '\n' + ' By default, "__ne__()" delegates to "__eq__()" and ' + 'inverts the\n' + ' result unless it is "NotImplemented". There are no ' + 'other implied\n' + ' relationships among the comparison operators, for ' + 'example, the\n' + ' truth of "(x.__hash__".\n' + '\n' + ' If a class that does not override "__eq__()" wishes to ' + 'suppress\n' + ' hash support, it should include "__hash__ = None" in ' + 'the class\n' + ' definition. A class which defines its own "__hash__()" ' + 'that\n' + ' explicitly raises a "TypeError" would be incorrectly ' + 'identified as\n' + ' hashable by an "isinstance(obj, collections.Hashable)" ' + 'call.\n' + '\n' + ' Note: By default, the "__hash__()" values of str, ' + 'bytes and\n' + ' datetime objects are "salted" with an unpredictable ' + 'random value.\n' + ' Although they remain constant within an individual ' + 'Python\n' + ' process, they are not predictable between repeated ' + 'invocations of\n' + ' Python.This is intended to provide protection ' + 'against a denial-\n' + ' of-service caused by carefully-chosen inputs that ' + 'exploit the\n' + ' worst case performance of a dict insertion, O(n^2) ' + 'complexity.\n' + ' See ' + 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' + ' details.Changing hash values affects the iteration ' + 'order of\n' + ' dicts, sets and other mappings. Python has never ' + 'made guarantees\n' + ' about this ordering (and it typically varies between ' + '32-bit and\n' + ' 64-bit builds).See also "PYTHONHASHSEED".\n' + '\n' + ' Changed in version 3.3: Hash randomization is enabled ' + 'by default.\n' + '\n' + 'object.__bool__(self)\n' + '\n' + ' Called to implement truth value testing and the ' + 'built-in operation\n' + ' "bool()"; should return "False" or "True". When this ' + 'method is not\n' + ' defined, "__len__()" is called, if it is defined, and ' + 'the object is\n' + ' considered true if its result is nonzero. If a class ' + 'defines\n' + ' neither "__len__()" nor "__bool__()", all its ' + 'instances are\n' + ' considered true.\n', + 'debugger': '\n' + '"pdb" --- The Python Debugger\n' + '*****************************\n' + '\n' + '**Source code:** Lib/pdb.py\n' + '\n' + '======================================================================\n' + '\n' + 'The module "pdb" defines an interactive source code debugger ' + 'for\n' + 'Python programs. It supports setting (conditional) ' + 'breakpoints and\n' + 'single stepping at the source line level, inspection of stack ' + 'frames,\n' + 'source code listing, and evaluation of arbitrary Python code ' + 'in the\n' + 'context of any stack frame. It also supports post-mortem ' + 'debugging\n' + 'and can be called under program control.\n' + '\n' + 'The debugger is extensible -- it is actually defined as the ' + 'class\n' + '"Pdb". This is currently undocumented but easily understood by ' + 'reading\n' + 'the source. The extension interface uses the modules "bdb" ' + 'and "cmd".\n' + '\n' + 'The debugger\'s prompt is "(Pdb)". Typical usage to run a ' + 'program under\n' + 'control of the debugger is:\n' + '\n' + ' >>> import pdb\n' + ' >>> import mymodule\n' + " >>> pdb.run('mymodule.test()')\n" + ' > (0)?()\n' + ' (Pdb) continue\n' + ' > (1)?()\n' + ' (Pdb) continue\n' + " NameError: 'spam'\n" + ' > (1)?()\n' + ' (Pdb)\n' + '\n' + 'Changed in version 3.3: Tab-completion via the "readline" ' + 'module is\n' + 'available for commands and command arguments, e.g. the current ' + 'global\n' + 'and local names are offered as arguments of the "p" command.\n' + '\n' + '"pdb.py" can also be invoked as a script to debug other ' + 'scripts. For\n' + 'example:\n' + '\n' + ' python3 -m pdb myscript.py\n' + '\n' + 'When invoked as a script, pdb will automatically enter ' + 'post-mortem\n' + 'debugging if the program being debugged exits abnormally. ' + 'After post-\n' + 'mortem debugging (or after normal exit of the program), pdb ' + 'will\n' + "restart the program. Automatic restarting preserves pdb's " + 'state (such\n' + 'as breakpoints) and in most cases is more useful than quitting ' + 'the\n' + "debugger upon program's exit.\n" + '\n' + 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' + 'executes\n' + 'commands as if given in a ".pdbrc" file, see *Debugger ' + 'Commands*.\n' + '\n' + 'The typical usage to break into the debugger from a running ' + 'program is\n' + 'to insert\n' + '\n' + ' import pdb; pdb.set_trace()\n' + '\n' + 'at the location you want to break into the debugger. You can ' + 'then\n' + 'step through the code following this statement, and continue ' + 'running\n' + 'without the debugger using the "continue" command.\n' + '\n' + 'The typical usage to inspect a crashed program is:\n' + '\n' + ' >>> import pdb\n' + ' >>> import mymodule\n' + ' >>> mymodule.test()\n' + ' Traceback (most recent call last):\n' + ' File "", line 1, in ?\n' + ' File "./mymodule.py", line 4, in test\n' + ' test2()\n' + ' File "./mymodule.py", line 3, in test2\n' + ' print(spam)\n' + ' NameError: spam\n' + ' >>> pdb.pm()\n' + ' > ./mymodule.py(3)test2()\n' + ' -> print(spam)\n' + ' (Pdb)\n' + '\n' + 'The module defines the following functions; each enters the ' + 'debugger\n' + 'in a slightly different way:\n' + '\n' + 'pdb.run(statement, globals=None, locals=None)\n' + '\n' + ' Execute the *statement* (given as a string or a code ' + 'object) under\n' + ' debugger control. The debugger prompt appears before any ' + 'code is\n' + ' executed; you can set breakpoints and type "continue", or ' + 'you can\n' + ' step through the statement using "step" or "next" (all ' + 'these\n' + ' commands are explained below). The optional *globals* and ' + '*locals*\n' + ' arguments specify the environment in which the code is ' + 'executed; by\n' + ' default the dictionary of the module "__main__" is used. ' + '(See the\n' + ' explanation of the built-in "exec()" or "eval()" ' + 'functions.)\n' + '\n' + 'pdb.runeval(expression, globals=None, locals=None)\n' + '\n' + ' Evaluate the *expression* (given as a string or a code ' + 'object)\n' + ' under debugger control. When "runeval()" returns, it ' + 'returns the\n' + ' value of the expression. Otherwise this function is ' + 'similar to\n' + ' "run()".\n' + '\n' + 'pdb.runcall(function, *args, **kwds)\n' + '\n' + ' Call the *function* (a function or method object, not a ' + 'string)\n' + ' with the given arguments. When "runcall()" returns, it ' + 'returns\n' + ' whatever the function call returned. The debugger prompt ' + 'appears\n' + ' as soon as the function is entered.\n' + '\n' + 'pdb.set_trace()\n' + '\n' + ' Enter the debugger at the calling stack frame. This is ' + 'useful to\n' + ' hard-code a breakpoint at a given point in a program, even ' + 'if the\n' + ' code is not otherwise being debugged (e.g. when an ' + 'assertion\n' + ' fails).\n' + '\n' + 'pdb.post_mortem(traceback=None)\n' + '\n' + ' Enter post-mortem debugging of the given *traceback* ' + 'object. If no\n' + ' *traceback* is given, it uses the one of the exception that ' + 'is\n' + ' currently being handled (an exception must be being handled ' + 'if the\n' + ' default is to be used).\n' + '\n' + 'pdb.pm()\n' + '\n' + ' Enter post-mortem debugging of the traceback found in\n' + ' "sys.last_traceback".\n' + '\n' + 'The "run*" functions and "set_trace()" are aliases for ' + 'instantiating\n' + 'the "Pdb" class and calling the method of the same name. If ' + 'you want\n' + 'to access further features, you have to do this yourself:\n' + '\n' + "class class pdb.Pdb(completekey='tab', stdin=None, " + 'stdout=None, skip=None, nosigint=False)\n' + '\n' + ' "Pdb" is the debugger class.\n' + '\n' + ' The *completekey*, *stdin* and *stdout* arguments are ' + 'passed to the\n' + ' underlying "cmd.Cmd" class; see the description there.\n' + '\n' + ' The *skip* argument, if given, must be an iterable of ' + 'glob-style\n' + ' module name patterns. The debugger will not step into ' + 'frames that\n' + ' originate in a module that matches one of these patterns. ' + '[1]\n' + '\n' + ' By default, Pdb sets a handler for the SIGINT signal (which ' + 'is sent\n' + ' when the user presses "Ctrl-C" on the console) when you ' + 'give a\n' + ' "continue" command. This allows you to break into the ' + 'debugger\n' + ' again by pressing "Ctrl-C". If you want Pdb not to touch ' + 'the\n' + ' SIGINT handler, set *nosigint* tot true.\n' + '\n' + ' Example call to enable tracing with *skip*:\n' + '\n' + " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" + '\n' + ' New in version 3.1: The *skip* argument.\n' + '\n' + ' New in version 3.2: The *nosigint* argument. Previously, a ' + 'SIGINT\n' + ' handler was never set by Pdb.\n' + '\n' + ' run(statement, globals=None, locals=None)\n' + ' runeval(expression, globals=None, locals=None)\n' + ' runcall(function, *args, **kwds)\n' + ' set_trace()\n' + '\n' + ' See the documentation for the functions explained ' + 'above.\n' + '\n' + '\n' + 'Debugger Commands\n' + '=================\n' + '\n' + 'The commands recognized by the debugger are listed below. ' + 'Most\n' + 'commands can be abbreviated to one or two letters as ' + 'indicated; e.g.\n' + '"h(elp)" means that either "h" or "help" can be used to enter ' + 'the help\n' + 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' + 'Arguments to commands must be separated by whitespace (spaces ' + 'or\n' + 'tabs). Optional arguments are enclosed in square brackets ' + '("[]") in\n' + 'the command syntax; the square brackets must not be typed.\n' + 'Alternatives in the command syntax are separated by a vertical ' + 'bar\n' + '("|").\n' + '\n' + 'Entering a blank line repeats the last command entered. ' + 'Exception: if\n' + 'the last command was a "list" command, the next 11 lines are ' + 'listed.\n' + '\n' + "Commands that the debugger doesn't recognize are assumed to be " + 'Python\n' + 'statements and are executed in the context of the program ' + 'being\n' + 'debugged. Python statements can also be prefixed with an ' + 'exclamation\n' + 'point ("!"). This is a powerful way to inspect the program ' + 'being\n' + 'debugged; it is even possible to change a variable or call a ' + 'function.\n' + 'When an exception occurs in such a statement, the exception ' + 'name is\n' + "printed but the debugger's state is not changed.\n" + '\n' + 'The debugger supports *aliases*. Aliases can have parameters ' + 'which\n' + 'allows one a certain level of adaptability to the context ' + 'under\n' + 'examination.\n' + '\n' + 'Multiple commands may be entered on a single line, separated ' + 'by ";;".\n' + '(A single ";" is not used as it is the separator for multiple ' + 'commands\n' + 'in a line that is passed to the Python parser.) No ' + 'intelligence is\n' + 'applied to separating the commands; the input is split at the ' + 'first\n' + '";;" pair, even if it is in the middle of a quoted string.\n' + '\n' + 'If a file ".pdbrc" exists in the user\'s home directory or in ' + 'the\n' + 'current directory, it is read in and executed as if it had ' + 'been typed\n' + 'at the debugger prompt. This is particularly useful for ' + 'aliases. If\n' + 'both files exist, the one in the home directory is read first ' + 'and\n' + 'aliases defined there can be overridden by the local file.\n' + '\n' + 'Changed in version 3.2: ".pdbrc" can now contain commands ' + 'that\n' + 'continue debugging, such as "continue" or "next". Previously, ' + 'these\n' + 'commands had no effect.\n' + '\n' + 'h(elp) [command]\n' + '\n' + ' Without argument, print the list of available commands. ' + 'With a\n' + ' *command* as argument, print help about that command. ' + '"help pdb"\n' + ' displays the full documentation (the docstring of the ' + '"pdb"\n' + ' module). Since the *command* argument must be an ' + 'identifier, "help\n' + ' exec" must be entered to get help on the "!" command.\n' + '\n' + 'w(here)\n' + '\n' + ' Print a stack trace, with the most recent frame at the ' + 'bottom. An\n' + ' arrow indicates the current frame, which determines the ' + 'context of\n' + ' most commands.\n' + '\n' + 'd(own) [count]\n' + '\n' + ' Move the current frame *count* (default one) levels down in ' + 'the\n' + ' stack trace (to a newer frame).\n' + '\n' + 'u(p) [count]\n' + '\n' + ' Move the current frame *count* (default one) levels up in ' + 'the stack\n' + ' trace (to an older frame).\n' + '\n' + 'b(reak) [([filename:]lineno | function) [, condition]]\n' + '\n' + ' With a *lineno* argument, set a break there in the current ' + 'file.\n' + ' With a *function* argument, set a break at the first ' + 'executable\n' + ' statement within that function. The line number may be ' + 'prefixed\n' + ' with a filename and a colon, to specify a breakpoint in ' + 'another\n' + " file (probably one that hasn't been loaded yet). The file " + 'is\n' + ' searched on "sys.path". Note that each breakpoint is ' + 'assigned a\n' + ' number to which all the other breakpoint commands refer.\n' + '\n' + ' If a second argument is present, it is an expression which ' + 'must\n' + ' evaluate to true before the breakpoint is honored.\n' + '\n' + ' Without argument, list all breaks, including for each ' + 'breakpoint,\n' + ' the number of times that breakpoint has been hit, the ' + 'current\n' + ' ignore count, and the associated condition if any.\n' + '\n' + 'tbreak [([filename:]lineno | function) [, condition]]\n' + '\n' + ' Temporary breakpoint, which is removed automatically when ' + 'it is\n' + ' first hit. The arguments are the same as for "break".\n' + '\n' + 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n' + '\n' + ' With a *filename:lineno* argument, clear all the ' + 'breakpoints at\n' + ' this line. With a space separated list of breakpoint ' + 'numbers, clear\n' + ' those breakpoints. Without argument, clear all breaks (but ' + 'first\n' + ' ask confirmation).\n' + '\n' + 'disable [bpnumber [bpnumber ...]]\n' + '\n' + ' Disable the breakpoints given as a space separated list of\n' + ' breakpoint numbers. Disabling a breakpoint means it cannot ' + 'cause\n' + ' the program to stop execution, but unlike clearing a ' + 'breakpoint, it\n' + ' remains in the list of breakpoints and can be ' + '(re-)enabled.\n' + '\n' + 'enable [bpnumber [bpnumber ...]]\n' + '\n' + ' Enable the breakpoints specified.\n' + '\n' + 'ignore bpnumber [count]\n' + '\n' + ' Set the ignore count for the given breakpoint number. If ' + 'count is\n' + ' omitted, the ignore count is set to 0. A breakpoint ' + 'becomes active\n' + ' when the ignore count is zero. When non-zero, the count ' + 'is\n' + ' decremented each time the breakpoint is reached and the ' + 'breakpoint\n' + ' is not disabled and any associated condition evaluates to ' + 'true.\n' + '\n' + 'condition bpnumber [condition]\n' + '\n' + ' Set a new *condition* for the breakpoint, an expression ' + 'which must\n' + ' evaluate to true before the breakpoint is honored. If ' + '*condition*\n' + ' is absent, any existing condition is removed; i.e., the ' + 'breakpoint\n' + ' is made unconditional.\n' + '\n' + 'commands [bpnumber]\n' + '\n' + ' Specify a list of commands for breakpoint number ' + '*bpnumber*. The\n' + ' commands themselves appear on the following lines. Type a ' + 'line\n' + ' containing just "end" to terminate the commands. An ' + 'example:\n' + '\n' + ' (Pdb) commands 1\n' + ' (com) p some_variable\n' + ' (com) end\n' + ' (Pdb)\n' + '\n' + ' To remove all commands from a breakpoint, type commands and ' + 'follow\n' + ' it immediately with "end"; that is, give no commands.\n' + '\n' + ' With no *bpnumber* argument, commands refers to the last ' + 'breakpoint\n' + ' set.\n' + '\n' + ' You can use breakpoint commands to start your program up ' + 'again.\n' + ' Simply use the continue command, or step, or any other ' + 'command that\n' + ' resumes execution.\n' + '\n' + ' Specifying any command resuming execution (currently ' + 'continue,\n' + ' step, next, return, jump, quit and their abbreviations) ' + 'terminates\n' + ' the command list (as if that command was immediately ' + 'followed by\n' + ' end). This is because any time you resume execution (even ' + 'with a\n' + ' simple next or step), you may encounter another ' + 'breakpoint--which\n' + ' could have its own command list, leading to ambiguities ' + 'about which\n' + ' list to execute.\n' + '\n' + " If you use the 'silent' command in the command list, the " + 'usual\n' + ' message about stopping at a breakpoint is not printed. ' + 'This may be\n' + ' desirable for breakpoints that are to print a specific ' + 'message and\n' + ' then continue. If none of the other commands print ' + 'anything, you\n' + ' see no sign that the breakpoint was reached.\n' + '\n' + 's(tep)\n' + '\n' + ' Execute the current line, stop at the first possible ' + 'occasion\n' + ' (either in a function that is called or on the next line in ' + 'the\n' + ' current function).\n' + '\n' + 'n(ext)\n' + '\n' + ' Continue execution until the next line in the current ' + 'function is\n' + ' reached or it returns. (The difference between "next" and ' + '"step"\n' + ' is that "step" stops inside a called function, while ' + '"next"\n' + ' executes called functions at (nearly) full speed, only ' + 'stopping at\n' + ' the next line in the current function.)\n' + '\n' + 'unt(il) [lineno]\n' + '\n' + ' Without argument, continue execution until the line with a ' + 'number\n' + ' greater than the current one is reached.\n' + '\n' + ' With a line number, continue execution until a line with a ' + 'number\n' + ' greater or equal to that is reached. In both cases, also ' + 'stop when\n' + ' the current frame returns.\n' + '\n' + ' Changed in version 3.2: Allow giving an explicit line ' + 'number.\n' + '\n' + 'r(eturn)\n' + '\n' + ' Continue execution until the current function returns.\n' + '\n' + 'c(ont(inue))\n' + '\n' + ' Continue execution, only stop when a breakpoint is ' + 'encountered.\n' + '\n' + 'j(ump) lineno\n' + '\n' + ' Set the next line that will be executed. Only available in ' + 'the\n' + ' bottom-most frame. This lets you jump back and execute ' + 'code again,\n' + " or jump forward to skip code that you don't want to run.\n" + '\n' + ' It should be noted that not all jumps are allowed -- for ' + 'instance\n' + ' it is not possible to jump into the middle of a "for" loop ' + 'or out\n' + ' of a "finally" clause.\n' + '\n' + 'l(ist) [first[, last]]\n' + '\n' + ' List source code for the current file. Without arguments, ' + 'list 11\n' + ' lines around the current line or continue the previous ' + 'listing.\n' + ' With "." as argument, list 11 lines around the current ' + 'line. With\n' + ' one argument, list 11 lines around at that line. With two\n' + ' arguments, list the given range; if the second argument is ' + 'less\n' + ' than the first, it is interpreted as a count.\n' + '\n' + ' The current line in the current frame is indicated by ' + '"->". If an\n' + ' exception is being debugged, the line where the exception ' + 'was\n' + ' originally raised or propagated is indicated by ">>", if it ' + 'differs\n' + ' from the current line.\n' + '\n' + ' New in version 3.2: The ">>" marker.\n' + '\n' + 'll | longlist\n' + '\n' + ' List all source code for the current function or frame.\n' + ' Interesting lines are marked as for "list".\n' + '\n' + ' New in version 3.2.\n' + '\n' + 'a(rgs)\n' + '\n' + ' Print the argument list of the current function.\n' + '\n' + 'p expression\n' + '\n' + ' Evaluate the *expression* in the current context and print ' + 'its\n' + ' value.\n' + '\n' + ' Note: "print()" can also be used, but is not a debugger ' + 'command\n' + ' --- this executes the Python "print()" function.\n' + '\n' + 'pp expression\n' + '\n' + ' Like the "p" command, except the value of the expression is ' + 'pretty-\n' + ' printed using the "pprint" module.\n' + '\n' + 'whatis expression\n' + '\n' + ' Print the type of the *expression*.\n' + '\n' + 'source expression\n' + '\n' + ' Try to get source code for the given object and display ' + 'it.\n' + '\n' + ' New in version 3.2.\n' + '\n' + 'display [expression]\n' + '\n' + ' Display the value of the expression if it changed, each ' + 'time\n' + ' execution stops in the current frame.\n' + '\n' + ' Without expression, list all display expressions for the ' + 'current\n' + ' frame.\n' + '\n' + ' New in version 3.2.\n' + '\n' + 'undisplay [expression]\n' + '\n' + ' Do not display the expression any more in the current ' + 'frame.\n' + ' Without expression, clear all display expressions for the ' + 'current\n' + ' frame.\n' + '\n' + ' New in version 3.2.\n' + '\n' + 'interact\n' + '\n' + ' Start an interative interpreter (using the "code" module) ' + 'whose\n' + ' global namespace contains all the (global and local) names ' + 'found in\n' + ' the current scope.\n' + '\n' + ' New in version 3.2.\n' + '\n' + 'alias [name [command]]\n' + '\n' + ' Create an alias called *name* that executes *command*. The ' + 'command\n' + ' must *not* be enclosed in quotes. Replaceable parameters ' + 'can be\n' + ' indicated by "%1", "%2", and so on, while "%*" is replaced ' + 'by all\n' + ' the parameters. If no command is given, the current alias ' + 'for\n' + ' *name* is shown. If no arguments are given, all aliases are ' + 'listed.\n' + '\n' + ' Aliases may be nested and can contain anything that can be ' + 'legally\n' + ' typed at the pdb prompt. Note that internal pdb commands ' + '*can* be\n' + ' overridden by aliases. Such a command is then hidden until ' + 'the\n' + ' alias is removed. Aliasing is recursively applied to the ' + 'first\n' + ' word of the command line; all other words in the line are ' + 'left\n' + ' alone.\n' + '\n' + ' As an example, here are two useful aliases (especially when ' + 'placed\n' + ' in the ".pdbrc" file):\n' + '\n' + ' # Print instance variables (usage "pi classInst")\n' + ' alias pi for k in %1.__dict__.keys(): ' + 'print("%1.",k,"=",%1.__dict__[k])\n' + ' # Print instance variables in self\n' + ' alias ps pi self\n' + '\n' + 'unalias name\n' + '\n' + ' Delete the specified alias.\n' + '\n' + '! statement\n' + '\n' + ' Execute the (one-line) *statement* in the context of the ' + 'current\n' + ' stack frame. The exclamation point can be omitted unless ' + 'the first\n' + ' word of the statement resembles a debugger command. To set ' + 'a\n' + ' global variable, you can prefix the assignment command with ' + 'a\n' + ' "global" statement on the same line, e.g.:\n' + '\n' + " (Pdb) global list_options; list_options = ['-l']\n" + ' (Pdb)\n' + '\n' + 'run [args ...]\n' + 'restart [args ...]\n' + '\n' + ' Restart the debugged Python program. If an argument is ' + 'supplied,\n' + ' it is split with "shlex" and the result is used as the new\n' + ' "sys.argv". History, breakpoints, actions and debugger ' + 'options are\n' + ' preserved. "restart" is an alias for "run".\n' + '\n' + 'q(uit)\n' + '\n' + ' Quit from the debugger. The program being executed is ' + 'aborted.\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] Whether a frame is considered to originate in a certain ' + 'module\n' + ' is determined by the "__name__" in the frame globals.\n', + 'del': '\n' + 'The "del" statement\n' + '*******************\n' + '\n' + ' del_stmt ::= "del" target_list\n' + '\n' + 'Deletion is recursively defined very similar to the way assignment ' + 'is\n' + 'defined. Rather than spelling it out in full details, here are ' + 'some\n' + 'hints.\n' + '\n' + 'Deletion of a target list recursively deletes each target, from ' + 'left\n' + 'to right.\n' + '\n' + 'Deletion of a name removes the binding of that name from the local ' + 'or\n' + 'global namespace, depending on whether the name occurs in a ' + '"global"\n' + 'statement in the same code block. If the name is unbound, a\n' + '"NameError" exception will be raised.\n' + '\n' + 'Deletion of attribute references, subscriptions and slicings is ' + 'passed\n' + 'to the primary object involved; deletion of a slicing is in ' + 'general\n' + 'equivalent to assignment of an empty slice of the right type (but ' + 'even\n' + 'this is determined by the sliced object).\n' + '\n' + 'Changed in version 3.2: Previously it was illegal to delete a name\n' + 'from the local namespace if it occurs as a free variable in a ' + 'nested\n' + 'block.\n', + 'dict': '\n' + 'Dictionary displays\n' + '*******************\n' + '\n' + 'A dictionary display is a possibly empty series of key/datum ' + 'pairs\n' + 'enclosed in curly braces:\n' + '\n' + ' dict_display ::= "{" [key_datum_list | ' + 'dict_comprehension] "}"\n' + ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' + ' key_datum ::= expression ":" expression\n' + ' dict_comprehension ::= expression ":" expression comp_for\n' + '\n' + 'A dictionary display yields a new dictionary object.\n' + '\n' + 'If a comma-separated sequence of key/datum pairs is given, they ' + 'are\n' + 'evaluated from left to right to define the entries of the ' + 'dictionary:\n' + 'each key object is used as a key into the dictionary to store the\n' + 'corresponding datum. This means that you can specify the same ' + 'key\n' + "multiple times in the key/datum list, and the final dictionary's " + 'value\n' + 'for that key will be the last one given.\n' + '\n' + 'A dict comprehension, in contrast to list and set comprehensions,\n' + 'needs two expressions separated with a colon followed by the ' + 'usual\n' + '"for" and "if" clauses. When the comprehension is run, the ' + 'resulting\n' + 'key and value elements are inserted in the new dictionary in the ' + 'order\n' + 'they are produced.\n' + '\n' + 'Restrictions on the types of the key values are listed earlier in\n' + 'section *The standard type hierarchy*. (To summarize, the key ' + 'type\n' + 'should be *hashable*, which excludes all mutable objects.) ' + 'Clashes\n' + 'between duplicate keys are not detected; the last datum ' + '(textually\n' + 'rightmost in the display) stored for a given key value prevails.\n', + 'dynamic-features': '\n' + 'Interaction with dynamic features\n' + '*********************************\n' + '\n' + 'Name resolution of free variables occurs at runtime, ' + 'not at compile\n' + 'time. This means that the following code will print ' + '42:\n' + '\n' + ' i = 10\n' + ' def f():\n' + ' print(i)\n' + ' i = 42\n' + ' f()\n' + '\n' + 'There are several cases where Python statements are ' + 'illegal when used\n' + 'in conjunction with nested scopes that contain free ' + 'variables.\n' + '\n' + 'If a variable is referenced in an enclosing scope, it ' + 'is illegal to\n' + 'delete the name. An error will be reported at compile ' + 'time.\n' + '\n' + 'The "eval()" and "exec()" functions do not have access ' + 'to the full\n' + 'environment for resolving names. Names may be ' + 'resolved in the local\n' + 'and global namespaces of the caller. Free variables ' + 'are not resolved\n' + 'in the nearest enclosing namespace, but in the global ' + 'namespace. [1]\n' + 'The "exec()" and "eval()" functions have optional ' + 'arguments to\n' + 'override the global and local namespace. If only one ' + 'namespace is\n' + 'specified, it is used for both.\n', + 'else': '\n' + 'The "if" statement\n' + '******************\n' + '\n' + 'The "if" statement is used for conditional execution:\n' + '\n' + ' if_stmt ::= "if" expression ":" suite\n' + ' ( "elif" expression ":" suite )*\n' + ' ["else" ":" suite]\n' + '\n' + 'It selects exactly one of the suites by evaluating the expressions ' + 'one\n' + 'by one until one is found to be true (see section *Boolean ' + 'operations*\n' + 'for the definition of true and false); then that suite is ' + 'executed\n' + '(and no other part of the "if" statement is executed or ' + 'evaluated).\n' + 'If all expressions are false, the suite of the "else" clause, if\n' + 'present, is executed.\n', + 'exceptions': '\n' + 'Exceptions\n' + '**********\n' + '\n' + 'Exceptions are a means of breaking out of the normal flow of ' + 'control\n' + 'of a code block in order to handle errors or other ' + 'exceptional\n' + 'conditions. An exception is *raised* at the point where the ' + 'error is\n' + 'detected; it may be *handled* by the surrounding code block ' + 'or by any\n' + 'code block that directly or indirectly invoked the code ' + 'block where\n' + 'the error occurred.\n' + '\n' + 'The Python interpreter raises an exception when it detects a ' + 'run-time\n' + 'error (such as division by zero). A Python program can ' + 'also\n' + 'explicitly raise an exception with the "raise" statement. ' + 'Exception\n' + 'handlers are specified with the "try" ... "except" ' + 'statement. The\n' + '"finally" clause of such a statement can be used to specify ' + 'cleanup\n' + 'code which does not handle the exception, but is executed ' + 'whether an\n' + 'exception occurred or not in the preceding code.\n' + '\n' + 'Python uses the "termination" model of error handling: an ' + 'exception\n' + 'handler can find out what happened and continue execution at ' + 'an outer\n' + 'level, but it cannot repair the cause of the error and retry ' + 'the\n' + 'failing operation (except by re-entering the offending piece ' + 'of code\n' + 'from the top).\n' + '\n' + 'When an exception is not handled at all, the interpreter ' + 'terminates\n' + 'execution of the program, or returns to its interactive main ' + 'loop. In\n' + 'either case, it prints a stack backtrace, except when the ' + 'exception is\n' + '"SystemExit".\n' + '\n' + 'Exceptions are identified by class instances. The "except" ' + 'clause is\n' + 'selected depending on the class of the instance: it must ' + 'reference the\n' + 'class of the instance or a base class thereof. The instance ' + 'can be\n' + 'received by the handler and can carry additional information ' + 'about the\n' + 'exceptional condition.\n' + '\n' + 'Note: Exception messages are not part of the Python API. ' + 'Their\n' + ' contents may change from one version of Python to the next ' + 'without\n' + ' warning and should not be relied on by code which will run ' + 'under\n' + ' multiple versions of the interpreter.\n' + '\n' + 'See also the description of the "try" statement in section ' + '*The try\n' + 'statement* and "raise" statement in section *The raise ' + 'statement*.\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] This limitation occurs because the code that is executed ' + 'by\n' + ' these operations is not available at the time the module ' + 'is\n' + ' compiled.\n', + 'execmodel': '\n' + 'Execution model\n' + '***************\n' + '\n' + '\n' + 'Structure of a program\n' + '======================\n' + '\n' + 'A Python program is constructed from code blocks. A *block* ' + 'is a piece\n' + 'of Python program text that is executed as a unit. The ' + 'following are\n' + 'blocks: a module, a function body, and a class definition. ' + 'Each\n' + 'command typed interactively is a block. A script file (a ' + 'file given\n' + 'as standard input to the interpreter or specified as a ' + 'command line\n' + 'argument to the interpreter) is a code block. A script ' + 'command (a\n' + 'command specified on the interpreter command line with the ' + "'**-c**'\n" + 'option) is a code block. The string argument passed to the ' + 'built-in\n' + 'functions "eval()" and "exec()" is a code block.\n' + '\n' + 'A code block is executed in an *execution frame*. A frame ' + 'contains\n' + 'some administrative information (used for debugging) and ' + 'determines\n' + "where and how execution continues after the code block's " + 'execution has\n' + 'completed.\n' + '\n' + '\n' + 'Naming and binding\n' + '==================\n' + '\n' + '\n' + 'Binding of names\n' + '----------------\n' + '\n' + '*Names* refer to objects. Names are introduced by name ' + 'binding\n' + 'operations.\n' + '\n' + 'The following constructs bind names: formal parameters to ' + 'functions,\n' + '"import" statements, class and function definitions (these ' + 'bind the\n' + 'class or function name in the defining block), and targets ' + 'that are\n' + 'identifiers if occurring in an assignment, "for" loop header, ' + 'or after\n' + '"as" in a "with" statement or "except" clause. The "import" ' + 'statement\n' + 'of the form "from ... import *" binds all names defined in ' + 'the\n' + 'imported module, except those beginning with an underscore. ' + 'This form\n' + 'may only be used at the module level.\n' + '\n' + 'A target occurring in a "del" statement is also considered ' + 'bound for\n' + 'this purpose (though the actual semantics are to unbind the ' + 'name).\n' + '\n' + 'Each assignment or import statement occurs within a block ' + 'defined by a\n' + 'class or function definition or at the module level (the ' + 'top-level\n' + 'code block).\n' + '\n' + 'If a name is bound in a block, it is a local variable of that ' + 'block,\n' + 'unless declared as "nonlocal" or "global". If a name is ' + 'bound at the\n' + 'module level, it is a global variable. (The variables of the ' + 'module\n' + 'code block are local and global.) If a variable is used in a ' + 'code\n' + 'block but not defined there, it is a *free variable*.\n' + '\n' + 'Each occurrence of a name in the program text refers to the ' + '*binding*\n' + 'of that name established by the following name resolution ' + 'rules.\n' + '\n' + '\n' + 'Resolution of names\n' + '-------------------\n' + '\n' + 'A *scope* defines the visibility of a name within a block. ' + 'If a local\n' + 'variable is defined in a block, its scope includes that ' + 'block. If the\n' + 'definition occurs in a function block, the scope extends to ' + 'any blocks\n' + 'contained within the defining one, unless a contained block ' + 'introduces\n' + 'a different binding for the name.\n' + '\n' + 'When a name is used in a code block, it is resolved using the ' + 'nearest\n' + 'enclosing scope. The set of all such scopes visible to a ' + 'code block\n' + "is called the block's *environment*.\n" + '\n' + 'When a name is not found at all, a "NameError" exception is ' + 'raised. If\n' + 'the current scope is a function scope, and the name refers to ' + 'a local\n' + 'variable that has not yet been bound to a value at the point ' + 'where the\n' + 'name is used, an "UnboundLocalError" exception is raised.\n' + '"UnboundLocalError" is a subclass of "NameError".\n' + '\n' + 'If a name binding operation occurs anywhere within a code ' + 'block, all\n' + 'uses of the name within the block are treated as references ' + 'to the\n' + 'current block. This can lead to errors when a name is used ' + 'within a\n' + 'block before it is bound. This rule is subtle. Python ' + 'lacks\n' + 'declarations and allows name binding operations to occur ' + 'anywhere\n' + 'within a code block. The local variables of a code block can ' + 'be\n' + 'determined by scanning the entire text of the block for name ' + 'binding\n' + 'operations.\n' + '\n' + 'If the "global" statement occurs within a block, all uses of ' + 'the name\n' + 'specified in the statement refer to the binding of that name ' + 'in the\n' + 'top-level namespace. Names are resolved in the top-level ' + 'namespace by\n' + 'searching the global namespace, i.e. the namespace of the ' + 'module\n' + 'containing the code block, and the builtins namespace, the ' + 'namespace\n' + 'of the module "builtins". The global namespace is searched ' + 'first. If\n' + 'the name is not found there, the builtins namespace is ' + 'searched. The\n' + '"global" statement must precede all uses of the name.\n' + '\n' + 'The "global" statement has the same scope as a name binding ' + 'operation\n' + 'in the same block. If the nearest enclosing scope for a free ' + 'variable\n' + 'contains a global statement, the free variable is treated as ' + 'a global.\n' + '\n' + 'The "nonlocal" statement causes corresponding names to refer ' + 'to\n' + 'previously bound variables in the nearest enclosing function ' + 'scope.\n' + '"SyntaxError" is raised at compile time if the given name ' + 'does not\n' + 'exist in any enclosing function scope.\n' + '\n' + 'The namespace for a module is automatically created the first ' + 'time a\n' + 'module is imported. The main module for a script is always ' + 'called\n' + '"__main__".\n' + '\n' + 'Class definition blocks and arguments to "exec()" and ' + '"eval()" are\n' + 'special in the context of name resolution. A class definition ' + 'is an\n' + 'executable statement that may use and define names. These ' + 'references\n' + 'follow the normal rules for name resolution with an exception ' + 'that\n' + 'unbound local variables are looked up in the global ' + 'namespace. The\n' + 'namespace of the class definition becomes the attribute ' + 'dictionary of\n' + 'the class. The scope of names defined in a class block is ' + 'limited to\n' + 'the class block; it does not extend to the code blocks of ' + 'methods --\n' + 'this includes comprehensions and generator expressions since ' + 'they are\n' + 'implemented using a function scope. This means that the ' + 'following\n' + 'will fail:\n' + '\n' + ' class A:\n' + ' a = 42\n' + ' b = list(a + i for i in range(10))\n' + '\n' + '\n' + 'Builtins and restricted execution\n' + '---------------------------------\n' + '\n' + 'The builtins namespace associated with the execution of a ' + 'code block\n' + 'is actually found by looking up the name "__builtins__" in ' + 'its global\n' + 'namespace; this should be a dictionary or a module (in the ' + 'latter case\n' + "the module's dictionary is used). By default, when in the " + '"__main__"\n' + 'module, "__builtins__" is the built-in module "builtins"; ' + 'when in any\n' + 'other module, "__builtins__" is an alias for the dictionary ' + 'of the\n' + '"builtins" module itself. "__builtins__" can be set to a ' + 'user-created\n' + 'dictionary to create a weak form of restricted execution.\n' + '\n' + '**CPython implementation detail:** Users should not touch\n' + '"__builtins__"; it is strictly an implementation detail. ' + 'Users\n' + 'wanting to override values in the builtins namespace should ' + '"import"\n' + 'the "builtins" module and modify its attributes ' + 'appropriately.\n' + '\n' + '\n' + 'Interaction with dynamic features\n' + '---------------------------------\n' + '\n' + 'Name resolution of free variables occurs at runtime, not at ' + 'compile\n' + 'time. This means that the following code will print 42:\n' + '\n' + ' i = 10\n' + ' def f():\n' + ' print(i)\n' + ' i = 42\n' + ' f()\n' + '\n' + 'There are several cases where Python statements are illegal ' + 'when used\n' + 'in conjunction with nested scopes that contain free ' + 'variables.\n' + '\n' + 'If a variable is referenced in an enclosing scope, it is ' + 'illegal to\n' + 'delete the name. An error will be reported at compile time.\n' + '\n' + 'The "eval()" and "exec()" functions do not have access to the ' + 'full\n' + 'environment for resolving names. Names may be resolved in ' + 'the local\n' + 'and global namespaces of the caller. Free variables are not ' + 'resolved\n' + 'in the nearest enclosing namespace, but in the global ' + 'namespace. [1]\n' + 'The "exec()" and "eval()" functions have optional arguments ' + 'to\n' + 'override the global and local namespace. If only one ' + 'namespace is\n' + 'specified, it is used for both.\n' + '\n' + '\n' + 'Exceptions\n' + '==========\n' + '\n' + 'Exceptions are a means of breaking out of the normal flow of ' + 'control\n' + 'of a code block in order to handle errors or other ' + 'exceptional\n' + 'conditions. An exception is *raised* at the point where the ' + 'error is\n' + 'detected; it may be *handled* by the surrounding code block ' + 'or by any\n' + 'code block that directly or indirectly invoked the code block ' + 'where\n' + 'the error occurred.\n' + '\n' + 'The Python interpreter raises an exception when it detects a ' + 'run-time\n' + 'error (such as division by zero). A Python program can also\n' + 'explicitly raise an exception with the "raise" statement. ' + 'Exception\n' + 'handlers are specified with the "try" ... "except" ' + 'statement. The\n' + '"finally" clause of such a statement can be used to specify ' + 'cleanup\n' + 'code which does not handle the exception, but is executed ' + 'whether an\n' + 'exception occurred or not in the preceding code.\n' + '\n' + 'Python uses the "termination" model of error handling: an ' + 'exception\n' + 'handler can find out what happened and continue execution at ' + 'an outer\n' + 'level, but it cannot repair the cause of the error and retry ' + 'the\n' + 'failing operation (except by re-entering the offending piece ' + 'of code\n' + 'from the top).\n' + '\n' + 'When an exception is not handled at all, the interpreter ' + 'terminates\n' + 'execution of the program, or returns to its interactive main ' + 'loop. In\n' + 'either case, it prints a stack backtrace, except when the ' + 'exception is\n' + '"SystemExit".\n' + '\n' + 'Exceptions are identified by class instances. The "except" ' + 'clause is\n' + 'selected depending on the class of the instance: it must ' + 'reference the\n' + 'class of the instance or a base class thereof. The instance ' + 'can be\n' + 'received by the handler and can carry additional information ' + 'about the\n' + 'exceptional condition.\n' + '\n' + 'Note: Exception messages are not part of the Python API. ' + 'Their\n' + ' contents may change from one version of Python to the next ' + 'without\n' + ' warning and should not be relied on by code which will run ' + 'under\n' + ' multiple versions of the interpreter.\n' + '\n' + 'See also the description of the "try" statement in section ' + '*The try\n' + 'statement* and "raise" statement in section *The raise ' + 'statement*.\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] This limitation occurs because the code that is executed ' + 'by\n' + ' these operations is not available at the time the module ' + 'is\n' + ' compiled.\n', + 'exprlists': '\n' + 'Expression lists\n' + '****************\n' + '\n' + ' expression_list ::= expression ( "," expression )* [","]\n' + '\n' + 'An expression list containing at least one comma yields a ' + 'tuple. The\n' + 'length of the tuple is the number of expressions in the ' + 'list. The\n' + 'expressions are evaluated from left to right.\n' + '\n' + 'The trailing comma is required only to create a single tuple ' + '(a.k.a. a\n' + '*singleton*); it is optional in all other cases. A single ' + 'expression\n' + "without a trailing comma doesn't create a tuple, but rather " + 'yields the\n' + 'value of that expression. (To create an empty tuple, use an ' + 'empty pair\n' + 'of parentheses: "()".)\n', + 'floating': '\n' + 'Floating point literals\n' + '***********************\n' + '\n' + 'Floating point literals are described by the following ' + 'lexical\n' + 'definitions:\n' + '\n' + ' floatnumber ::= pointfloat | exponentfloat\n' + ' pointfloat ::= [intpart] fraction | intpart "."\n' + ' exponentfloat ::= (intpart | pointfloat) exponent\n' + ' intpart ::= digit+\n' + ' fraction ::= "." digit+\n' + ' exponent ::= ("e" | "E") ["+" | "-"] digit+\n' + '\n' + 'Note that the integer and exponent parts are always ' + 'interpreted using\n' + 'radix 10. For example, "077e010" is legal, and denotes the ' + 'same number\n' + 'as "77e10". The allowed range of floating point literals is\n' + 'implementation-dependent. Some examples of floating point ' + 'literals:\n' + '\n' + ' 3.14 10. .001 1e100 3.14e-10 0e0\n' + '\n' + 'Note that numeric literals do not include a sign; a phrase ' + 'like "-1"\n' + 'is actually an expression composed of the unary operator "-" ' + 'and the\n' + 'literal "1".\n', + 'for': '\n' + 'The "for" statement\n' + '*******************\n' + '\n' + 'The "for" statement is used to iterate over the elements of a ' + 'sequence\n' + '(such as a string, tuple or list) or other iterable object:\n' + '\n' + ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n' + ' ["else" ":" suite]\n' + '\n' + 'The expression list is evaluated once; it should yield an iterable\n' + 'object. An iterator is created for the result of the\n' + '"expression_list". The suite is then executed once for each item\n' + 'provided by the iterator, in the order returned by the iterator. ' + 'Each\n' + 'item in turn is assigned to the target list using the standard ' + 'rules\n' + 'for assignments (see *Assignment statements*), and then the suite ' + 'is\n' + 'executed. When the items are exhausted (which is immediately when ' + 'the\n' + 'sequence is empty or an iterator raises a "StopIteration" ' + 'exception),\n' + 'the suite in the "else" clause, if present, is executed, and the ' + 'loop\n' + 'terminates.\n' + '\n' + 'A "break" statement executed in the first suite terminates the ' + 'loop\n' + 'without executing the "else" clause\'s suite. A "continue" ' + 'statement\n' + 'executed in the first suite skips the rest of the suite and ' + 'continues\n' + 'with the next item, or with the "else" clause if there is no next\n' + 'item.\n' + '\n' + 'The for-loop makes assignments to the variables(s) in the target ' + 'list.\n' + 'This overwrites all previous assignments to those variables ' + 'including\n' + 'those made in the suite of the for-loop:\n' + '\n' + ' for i in range(10):\n' + ' print(i)\n' + ' i = 5 # this will not affect the for-loop\n' + ' # because i will be overwritten with the ' + 'next\n' + ' # index in the range\n' + '\n' + 'Names in the target list are not deleted when the loop is ' + 'finished,\n' + 'but if the sequence is empty, they will not have been assigned to ' + 'at\n' + 'all by the loop. Hint: the built-in function "range()" returns an\n' + "iterator of integers suitable to emulate the effect of Pascal's " + '"for i\n' + ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' + '2]".\n' + '\n' + 'Note: There is a subtlety when the sequence is being modified by ' + 'the\n' + ' loop (this can only occur for mutable sequences, i.e. lists). ' + 'An\n' + ' internal counter is used to keep track of which item is used ' + 'next,\n' + ' and this is incremented on each iteration. When this counter ' + 'has\n' + ' reached the length of the sequence the loop terminates. This ' + 'means\n' + ' that if the suite deletes the current (or a previous) item from ' + 'the\n' + ' sequence, the next item will be skipped (since it gets the index ' + 'of\n' + ' the current item which has already been treated). Likewise, if ' + 'the\n' + ' suite inserts an item in the sequence before the current item, ' + 'the\n' + ' current item will be treated again the next time through the ' + 'loop.\n' + ' This can lead to nasty bugs that can be avoided by making a\n' + ' temporary copy using a slice of the whole sequence, e.g.,\n' + '\n' + ' for x in a[:]:\n' + ' if x < 0: a.remove(x)\n', + 'formatstrings': '\n' + 'Format String Syntax\n' + '********************\n' + '\n' + 'The "str.format()" method and the "Formatter" class share ' + 'the same\n' + 'syntax for format strings (although in the case of ' + '"Formatter",\n' + 'subclasses can define their own format string syntax).\n' + '\n' + 'Format strings contain "replacement fields" surrounded by ' + 'curly braces\n' + '"{}". Anything that is not contained in braces is ' + 'considered literal\n' + 'text, which is copied unchanged to the output. If you ' + 'need to include\n' + 'a brace character in the literal text, it can be escaped ' + 'by doubling:\n' + '"{{" and "}}".\n' + '\n' + 'The grammar for a replacement field is as follows:\n' + '\n' + ' replacement_field ::= "{" [field_name] ["!" ' + 'conversion] [":" format_spec] "}"\n' + ' field_name ::= arg_name ("." attribute_name ' + '| "[" element_index "]")*\n' + ' arg_name ::= [identifier | integer]\n' + ' attribute_name ::= identifier\n' + ' element_index ::= integer | index_string\n' + ' index_string ::= +\n' + ' conversion ::= "r" | "s" | "a"\n' + ' format_spec ::= \n' + '\n' + 'In less formal terms, the replacement field can start ' + 'with a\n' + '*field_name* that specifies the object whose value is to ' + 'be formatted\n' + 'and inserted into the output instead of the replacement ' + 'field. The\n' + '*field_name* is optionally followed by a *conversion* ' + 'field, which is\n' + 'preceded by an exclamation point "\'!\'", and a ' + '*format_spec*, which is\n' + 'preceded by a colon "\':\'". These specify a non-default ' + 'format for the\n' + 'replacement value.\n' + '\n' + 'See also the *Format Specification Mini-Language* ' + 'section.\n' + '\n' + 'The *field_name* itself begins with an *arg_name* that is ' + 'either a\n' + "number or a keyword. If it's a number, it refers to a " + 'positional\n' + "argument, and if it's a keyword, it refers to a named " + 'keyword\n' + 'argument. If the numerical arg_names in a format string ' + 'are 0, 1, 2,\n' + '... in sequence, they can all be omitted (not just some) ' + 'and the\n' + 'numbers 0, 1, 2, ... will be automatically inserted in ' + 'that order.\n' + 'Because *arg_name* is not quote-delimited, it is not ' + 'possible to\n' + 'specify arbitrary dictionary keys (e.g., the strings ' + '"\'10\'" or\n' + '"\':-]\'") within a format string. The *arg_name* can be ' + 'followed by any\n' + 'number of index or attribute expressions. An expression ' + 'of the form\n' + '"\'.name\'" selects the named attribute using ' + '"getattr()", while an\n' + 'expression of the form "\'[index]\'" does an index lookup ' + 'using\n' + '"__getitem__()".\n' + '\n' + 'Changed in version 3.1: The positional argument ' + 'specifiers can be\n' + 'omitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n' + '\n' + 'Some simple format string examples:\n' + '\n' + ' "First, thou shalt count to {0}" # References first ' + 'positional argument\n' + ' "Bring me a {}" # Implicitly ' + 'references the first positional argument\n' + ' "From {} to {}" # Same as "From {0} ' + 'to {1}"\n' + ' "My quest is {name}" # References keyword ' + "argument 'name'\n" + ' "Weight in tons {0.weight}" # \'weight\' ' + 'attribute of first positional arg\n' + ' "Units destroyed: {players[0]}" # First element of ' + "keyword argument 'players'.\n" + '\n' + 'The *conversion* field causes a type coercion before ' + 'formatting.\n' + 'Normally, the job of formatting a value is done by the ' + '"__format__()"\n' + 'method of the value itself. However, in some cases it is ' + 'desirable to\n' + 'force a type to be formatted as a string, overriding its ' + 'own\n' + 'definition of formatting. By converting the value to a ' + 'string before\n' + 'calling "__format__()", the normal formatting logic is ' + 'bypassed.\n' + '\n' + 'Three conversion flags are currently supported: "\'!s\'" ' + 'which calls\n' + '"str()" on the value, "\'!r\'" which calls "repr()" and ' + '"\'!a\'" which\n' + 'calls "ascii()".\n' + '\n' + 'Some examples:\n' + '\n' + ' "Harold\'s a clever {0!s}" # Calls str() on the ' + 'argument first\n' + ' "Bring out the holy {name!r}" # Calls repr() on the ' + 'argument first\n' + ' "More {!a}" # Calls ascii() on ' + 'the argument first\n' + '\n' + 'The *format_spec* field contains a specification of how ' + 'the value\n' + 'should be presented, including such details as field ' + 'width, alignment,\n' + 'padding, decimal precision and so on. Each value type ' + 'can define its\n' + 'own "formatting mini-language" or interpretation of the ' + '*format_spec*.\n' + '\n' + 'Most built-in types support a common formatting ' + 'mini-language, which\n' + 'is described in the next section.\n' + '\n' + 'A *format_spec* field can also include nested replacement ' + 'fields\n' + 'within it. These nested replacement fields can contain ' + 'only a field\n' + 'name; conversion flags and format specifications are not ' + 'allowed. The\n' + 'replacement fields within the format_spec are substituted ' + 'before the\n' + '*format_spec* string is interpreted. This allows the ' + 'formatting of a\n' + 'value to be dynamically specified.\n' + '\n' + 'See the *Format examples* section for some examples.\n' + '\n' + '\n' + 'Format Specification Mini-Language\n' + '==================================\n' + '\n' + '"Format specifications" are used within replacement ' + 'fields contained\n' + 'within a format string to define how individual values ' + 'are presented\n' + '(see *Format String Syntax*). They can also be passed ' + 'directly to the\n' + 'built-in "format()" function. Each formattable type may ' + 'define how\n' + 'the format specification is to be interpreted.\n' + '\n' + 'Most built-in types implement the following options for ' + 'format\n' + 'specifications, although some of the formatting options ' + 'are only\n' + 'supported by the numeric types.\n' + '\n' + 'A general convention is that an empty format string ' + '("""") produces\n' + 'the same result as if you had called "str()" on the ' + 'value. A non-empty\n' + 'format string typically modifies the result.\n' + '\n' + 'The general form of a *standard format specifier* is:\n' + '\n' + ' format_spec ::= ' + '[[fill]align][sign][#][0][width][,][.precision][type]\n' + ' fill ::= \n' + ' align ::= "<" | ">" | "=" | "^"\n' + ' sign ::= "+" | "-" | " "\n' + ' width ::= integer\n' + ' precision ::= integer\n' + ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' + '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' + '\n' + 'If a valid *align* value is specified, it can be preceded ' + 'by a *fill*\n' + 'character that can be any character and defaults to a ' + 'space if\n' + 'omitted. Note that it is not possible to use "{" and "}" ' + 'as *fill*\n' + 'char while using the "str.format()" method; this ' + 'limitation however\n' + 'doesn\'t affect the "format()" function.\n' + '\n' + 'The meaning of the various alignment options is as ' + 'follows:\n' + '\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | Option | ' + 'Meaning ' + '|\n' + ' ' + '+===========+============================================================+\n' + ' | "\'<\'" | Forces the field to be left-aligned ' + 'within the available |\n' + ' | | space (this is the default for most ' + 'objects). |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'>\'" | Forces the field to be right-aligned ' + 'within the available |\n' + ' | | space (this is the default for ' + 'numbers). |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'=\'" | Forces the padding to be placed after ' + 'the sign (if any) |\n' + ' | | but before the digits. This is used for ' + 'printing fields |\n' + " | | in the form '+000000120'. This alignment " + 'option is only |\n' + ' | | valid for numeric ' + 'types. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'^\'" | Forces the field to be centered within ' + 'the available |\n' + ' | | ' + 'space. ' + '|\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + '\n' + 'Note that unless a minimum field width is defined, the ' + 'field width\n' + 'will always be the same size as the data to fill it, so ' + 'that the\n' + 'alignment option has no meaning in this case.\n' + '\n' + 'The *sign* option is only valid for number types, and can ' + 'be one of\n' + 'the following:\n' + '\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | Option | ' + 'Meaning ' + '|\n' + ' ' + '+===========+============================================================+\n' + ' | "\'+\'" | indicates that a sign should be used ' + 'for both positive as |\n' + ' | | well as negative ' + 'numbers. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'-\'" | indicates that a sign should be used ' + 'only for negative |\n' + ' | | numbers (this is the default ' + 'behavior). |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | space | indicates that a leading space should be ' + 'used on positive |\n' + ' | | numbers, and a minus sign on negative ' + 'numbers. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + '\n' + 'The "\'#\'" option causes the "alternate form" to be used ' + 'for the\n' + 'conversion. The alternate form is defined differently ' + 'for different\n' + 'types. This option is only valid for integer, float, ' + 'complex and\n' + 'Decimal types. For integers, when binary, octal, or ' + 'hexadecimal output\n' + 'is used, this option adds the prefix respective "\'0b\'", ' + '"\'0o\'", or\n' + '"\'0x\'" to the output value. For floats, complex and ' + 'Decimal the\n' + 'alternate form causes the result of the conversion to ' + 'always contain a\n' + 'decimal-point character, even if no digits follow it. ' + 'Normally, a\n' + 'decimal-point character appears in the result of these ' + 'conversions\n' + 'only if a digit follows it. In addition, for "\'g\'" and ' + '"\'G\'"\n' + 'conversions, trailing zeros are not removed from the ' + 'result.\n' + '\n' + 'The "\',\'" option signals the use of a comma for a ' + 'thousands separator.\n' + 'For a locale aware separator, use the "\'n\'" integer ' + 'presentation type\n' + 'instead.\n' + '\n' + 'Changed in version 3.1: Added the "\',\'" option (see ' + 'also **PEP 378**).\n' + '\n' + '*width* is a decimal integer defining the minimum field ' + 'width. If not\n' + 'specified, then the field width will be determined by the ' + 'content.\n' + '\n' + 'Preceding the *width* field by a zero ("\'0\'") character ' + 'enables sign-\n' + 'aware zero-padding for numeric types. This is equivalent ' + 'to a *fill*\n' + 'character of "\'0\'" with an *alignment* type of ' + '"\'=\'".\n' + '\n' + 'The *precision* is a decimal number indicating how many ' + 'digits should\n' + 'be displayed after the decimal point for a floating point ' + 'value\n' + 'formatted with "\'f\'" and "\'F\'", or before and after ' + 'the decimal point\n' + 'for a floating point value formatted with "\'g\'" or ' + '"\'G\'". For non-\n' + 'number types the field indicates the maximum field size - ' + 'in other\n' + 'words, how many characters will be used from the field ' + 'content. The\n' + '*precision* is not allowed for integer values.\n' + '\n' + 'Finally, the *type* determines how the data should be ' + 'presented.\n' + '\n' + 'The available string presentation types are:\n' + '\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | Type | ' + 'Meaning ' + '|\n' + ' ' + '+===========+============================================================+\n' + ' | "\'s\'" | String format. This is the default ' + 'type for strings and |\n' + ' | | may be ' + 'omitted. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | None | The same as ' + '"\'s\'". |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + '\n' + 'The available integer presentation types are:\n' + '\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | Type | ' + 'Meaning ' + '|\n' + ' ' + '+===========+============================================================+\n' + ' | "\'b\'" | Binary format. Outputs the number in ' + 'base 2. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'c\'" | Character. Converts the integer to the ' + 'corresponding |\n' + ' | | unicode character before ' + 'printing. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'d\'" | Decimal Integer. Outputs the number in ' + 'base 10. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'o\'" | Octal format. Outputs the number in ' + 'base 8. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'x\'" | Hex format. Outputs the number in base ' + '16, using lower- |\n' + ' | | case letters for the digits above ' + '9. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'X\'" | Hex format. Outputs the number in base ' + '16, using upper- |\n' + ' | | case letters for the digits above ' + '9. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'n\'" | Number. This is the same as "\'d\'", ' + 'except that it uses the |\n' + ' | | current locale setting to insert the ' + 'appropriate number |\n' + ' | | separator ' + 'characters. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | None | The same as ' + '"\'d\'". |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + '\n' + 'In addition to the above presentation types, integers can ' + 'be formatted\n' + 'with the floating point presentation types listed below ' + '(except "\'n\'"\n' + 'and None). When doing so, "float()" is used to convert ' + 'the integer to\n' + 'a floating point number before formatting.\n' + '\n' + 'The available presentation types for floating point and ' + 'decimal values\n' + 'are:\n' + '\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | Type | ' + 'Meaning ' + '|\n' + ' ' + '+===========+============================================================+\n' + ' | "\'e\'" | Exponent notation. Prints the number ' + 'in scientific |\n' + " | | notation using the letter 'e' to " + 'indicate the exponent. |\n' + ' | | The default precision is ' + '"6". |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' + 'except it uses an upper |\n' + " | | case 'E' as the separator " + 'character. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'f\'" | Fixed point. Displays the number as a ' + 'fixed-point number. |\n' + ' | | The default precision is ' + '"6". |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'F\'" | Fixed point. Same as "\'f\'", but ' + 'converts "nan" to "NAN" |\n' + ' | | and "inf" to ' + '"INF". |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'g\'" | General format. For a given precision ' + '"p >= 1", this |\n' + ' | | rounds the number to "p" significant ' + 'digits and then |\n' + ' | | formats the result in either fixed-point ' + 'format or in |\n' + ' | | scientific notation, depending on its ' + 'magnitude. The |\n' + ' | | precise rules are as follows: suppose ' + 'that the result |\n' + ' | | formatted with presentation type "\'e\'" ' + 'and precision "p-1" |\n' + ' | | would have exponent "exp". Then if "-4 ' + '<= exp < p", the |\n' + ' | | number is formatted with presentation ' + 'type "\'f\'" and |\n' + ' | | precision "p-1-exp". Otherwise, the ' + 'number is formatted |\n' + ' | | with presentation type "\'e\'" and ' + 'precision "p-1". In both |\n' + ' | | cases insignificant trailing zeros are ' + 'removed from the |\n' + ' | | significand, and the decimal point is ' + 'also removed if |\n' + ' | | there are no remaining digits following ' + 'it. Positive and |\n' + ' | | negative infinity, positive and negative ' + 'zero, and nans, |\n' + ' | | are formatted as "inf", "-inf", "0", ' + '"-0" and "nan" |\n' + ' | | respectively, regardless of the ' + 'precision. A precision of |\n' + ' | | "0" is treated as equivalent to a ' + 'precision of "1". The |\n' + ' | | default precision is ' + '"6". |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'G\'" | General format. Same as "\'g\'" except ' + 'switches to "\'E\'" if |\n' + ' | | the number gets too large. The ' + 'representations of infinity |\n' + ' | | and NaN are uppercased, ' + 'too. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'n\'" | Number. This is the same as "\'g\'", ' + 'except that it uses the |\n' + ' | | current locale setting to insert the ' + 'appropriate number |\n' + ' | | separator ' + 'characters. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | "\'%\'" | Percentage. Multiplies the number by ' + '100 and displays in |\n' + ' | | fixed ("\'f\'") format, followed by a ' + 'percent sign. |\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + ' | None | Similar to "\'g\'", except that ' + 'fixed-point notation, when |\n' + ' | | used, has at least one digit past the ' + 'decimal point. The |\n' + ' | | default precision is as high as needed ' + 'to represent the |\n' + ' | | particular value. The overall effect is ' + 'to match the |\n' + ' | | output of "str()" as altered by the ' + 'other format |\n' + ' | | ' + 'modifiers. ' + '|\n' + ' ' + '+-----------+------------------------------------------------------------+\n' + '\n' + '\n' + 'Format examples\n' + '===============\n' + '\n' + 'This section contains examples of the new format syntax ' + 'and comparison\n' + 'with the old "%"-formatting.\n' + '\n' + 'In most of the cases the syntax is similar to the old ' + '"%"-formatting,\n' + 'with the addition of the "{}" and with ":" used instead ' + 'of "%". For\n' + 'example, "\'%03.2f\'" can be translated to ' + '"\'{:03.2f}\'".\n' + '\n' + 'The new format syntax also supports new and different ' + 'options, shown\n' + 'in the follow examples.\n' + '\n' + 'Accessing arguments by position:\n' + '\n' + " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" + " 'a, b, c'\n" + " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" + " 'a, b, c'\n" + " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" + " 'c, b, a'\n" + " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking " + 'argument sequence\n' + " 'c, b, a'\n" + " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' " + 'indices can be repeated\n' + " 'abracadabra'\n" + '\n' + 'Accessing arguments by name:\n' + '\n' + " >>> 'Coordinates: {latitude}, " + "{longitude}'.format(latitude='37.24N', " + "longitude='-115.81W')\n" + " 'Coordinates: 37.24N, -115.81W'\n" + " >>> coord = {'latitude': '37.24N', 'longitude': " + "'-115.81W'}\n" + " >>> 'Coordinates: {latitude}, " + "{longitude}'.format(**coord)\n" + " 'Coordinates: 37.24N, -115.81W'\n" + '\n' + "Accessing arguments' attributes:\n" + '\n' + ' >>> c = 3-5j\n' + " >>> ('The complex number {0} is formed from the real " + "part {0.real} '\n" + " ... 'and the imaginary part {0.imag}.').format(c)\n" + " 'The complex number (3-5j) is formed from the real " + "part 3.0 and the imaginary part -5.0.'\n" + ' >>> class Point:\n' + ' ... def __init__(self, x, y):\n' + ' ... self.x, self.y = x, y\n' + ' ... def __str__(self):\n' + " ... return 'Point({self.x}, " + "{self.y})'.format(self=self)\n" + ' ...\n' + ' >>> str(Point(4, 2))\n' + " 'Point(4, 2)'\n" + '\n' + "Accessing arguments' items:\n" + '\n' + ' >>> coord = (3, 5)\n' + " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" + " 'X: 3; Y: 5'\n" + '\n' + 'Replacing "%s" and "%r":\n' + '\n' + ' >>> "repr() shows quotes: {!r}; str() doesn\'t: ' + '{!s}".format(\'test1\', \'test2\')\n' + ' "repr() shows quotes: \'test1\'; str() doesn\'t: ' + 'test2"\n' + '\n' + 'Aligning the text and specifying a width:\n' + '\n' + " >>> '{:<30}'.format('left aligned')\n" + " 'left aligned '\n" + " >>> '{:>30}'.format('right aligned')\n" + " ' right aligned'\n" + " >>> '{:^30}'.format('centered')\n" + " ' centered '\n" + " >>> '{:*^30}'.format('centered') # use '*' as a fill " + 'char\n' + " '***********centered***********'\n" + '\n' + 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n' + '\n' + " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it " + 'always\n' + " '+3.140000; -3.140000'\n" + " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space " + 'for positive numbers\n' + " ' 3.140000; -3.140000'\n" + " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only " + "the minus -- same as '{:f}; {:f}'\n" + " '3.140000; -3.140000'\n" + '\n' + 'Replacing "%x" and "%o" and converting the value to ' + 'different bases:\n' + '\n' + ' >>> # format also supports binary numbers\n' + ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: ' + '{0:b}".format(42)\n' + " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n" + ' >>> # with 0x, 0o, or 0b as prefix:\n' + ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: ' + '{0:#b}".format(42)\n' + " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n" + '\n' + 'Using the comma as a thousands separator:\n' + '\n' + " >>> '{:,}'.format(1234567890)\n" + " '1,234,567,890'\n" + '\n' + 'Expressing a percentage:\n' + '\n' + ' >>> points = 19\n' + ' >>> total = 22\n' + " >>> 'Correct answers: {:.2%}'.format(points/total)\n" + " 'Correct answers: 86.36%'\n" + '\n' + 'Using type-specific formatting:\n' + '\n' + ' >>> import datetime\n' + ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n' + " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n" + " '2010-07-04 12:15:58'\n" + '\n' + 'Nesting arguments and more complex examples:\n' + '\n' + " >>> for align, text in zip('<^>', ['left', 'center', " + "'right']):\n" + " ... '{0:{fill}{align}16}'.format(text, fill=align, " + 'align=align)\n' + ' ...\n' + " 'left<<<<<<<<<<<<'\n" + " '^^^^^center^^^^^'\n" + " '>>>>>>>>>>>right'\n" + ' >>>\n' + ' >>> octets = [192, 168, 0, 1]\n' + " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n" + " 'C0A80001'\n" + ' >>> int(_, 16)\n' + ' 3232235521\n' + ' >>>\n' + ' >>> width = 5\n' + ' >>> for num in range(5,12): #doctest: ' + '+NORMALIZE_WHITESPACE\n' + " ... for base in 'dXob':\n" + " ... print('{0:{width}{base}}'.format(num, " + "base=base, width=width), end=' ')\n" + ' ... print()\n' + ' ...\n' + ' 5 5 5 101\n' + ' 6 6 6 110\n' + ' 7 7 7 111\n' + ' 8 8 10 1000\n' + ' 9 9 11 1001\n' + ' 10 A 12 1010\n' + ' 11 B 13 1011\n', + 'function': '\n' + 'Function definitions\n' + '********************\n' + '\n' + 'A function definition defines a user-defined function object ' + '(see\n' + 'section *The standard type hierarchy*):\n' + '\n' + ' funcdef ::= [decorators] "def" funcname "(" ' + '[parameter_list] ")" ["->" expression] ":" suite\n' + ' decorators ::= decorator+\n' + ' decorator ::= "@" dotted_name ["(" [parameter_list ' + '[","]] ")"] NEWLINE\n' + ' dotted_name ::= identifier ("." identifier)*\n' + ' parameter_list ::= (defparameter ",")*\n' + ' | "*" [parameter] ("," defparameter)* ' + '["," "**" parameter]\n' + ' | "**" parameter\n' + ' | defparameter [","] )\n' + ' parameter ::= identifier [":" expression]\n' + ' defparameter ::= parameter ["=" expression]\n' + ' funcname ::= identifier\n' + '\n' + 'A function definition is an executable statement. Its ' + 'execution binds\n' + 'the function name in the current local namespace to a function ' + 'object\n' + '(a wrapper around the executable code for the function). ' + 'This\n' + 'function object contains a reference to the current global ' + 'namespace\n' + 'as the global namespace to be used when the function is ' + 'called.\n' + '\n' + 'The function definition does not execute the function body; ' + 'this gets\n' + 'executed only when the function is called. [3]\n' + '\n' + 'A function definition may be wrapped by one or more ' + '*decorator*\n' + 'expressions. Decorator expressions are evaluated when the ' + 'function is\n' + 'defined, in the scope that contains the function definition. ' + 'The\n' + 'result must be a callable, which is invoked with the function ' + 'object\n' + 'as the only argument. The returned value is bound to the ' + 'function name\n' + 'instead of the function object. Multiple decorators are ' + 'applied in\n' + 'nested fashion. For example, the following code\n' + '\n' + ' @f1(arg)\n' + ' @f2\n' + ' def func(): pass\n' + '\n' + 'is equivalent to\n' + '\n' + ' def func(): pass\n' + ' func = f1(arg)(f2(func))\n' + '\n' + 'When one or more *parameters* have the form *parameter* "="\n' + '*expression*, the function is said to have "default parameter ' + 'values."\n' + 'For a parameter with a default value, the corresponding ' + '*argument* may\n' + "be omitted from a call, in which case the parameter's default " + 'value is\n' + 'substituted. If a parameter has a default value, all ' + 'following\n' + 'parameters up until the ""*"" must also have a default value ' + '--- this\n' + 'is a syntactic restriction that is not expressed by the ' + 'grammar.\n' + '\n' + '**Default parameter values are evaluated from left to right ' + 'when the\n' + 'function definition is executed.** This means that the ' + 'expression is\n' + 'evaluated once, when the function is defined, and that the ' + 'same "pre-\n' + 'computed" value is used for each call. This is especially ' + 'important\n' + 'to understand when a default parameter is a mutable object, ' + 'such as a\n' + 'list or a dictionary: if the function modifies the object ' + '(e.g. by\n' + 'appending an item to a list), the default value is in effect ' + 'modified.\n' + 'This is generally not what was intended. A way around this is ' + 'to use\n' + '"None" as the default, and explicitly test for it in the body ' + 'of the\n' + 'function, e.g.:\n' + '\n' + ' def whats_on_the_telly(penguin=None):\n' + ' if penguin is None:\n' + ' penguin = []\n' + ' penguin.append("property of the zoo")\n' + ' return penguin\n' + '\n' + 'Function call semantics are described in more detail in ' + 'section\n' + '*Calls*. A function call always assigns values to all ' + 'parameters\n' + 'mentioned in the parameter list, either from position ' + 'arguments, from\n' + 'keyword arguments, or from default values. If the form\n' + '""*identifier"" is present, it is initialized to a tuple ' + 'receiving any\n' + 'excess positional parameters, defaulting to the empty tuple. ' + 'If the\n' + 'form ""**identifier"" is present, it is initialized to a new\n' + 'dictionary receiving any excess keyword arguments, defaulting ' + 'to a new\n' + 'empty dictionary. Parameters after ""*"" or ""*identifier"" ' + 'are\n' + 'keyword-only parameters and may only be passed used keyword ' + 'arguments.\n' + '\n' + 'Parameters may have annotations of the form "": expression"" ' + 'following\n' + 'the parameter name. Any parameter may have an annotation even ' + 'those\n' + 'of the form "*identifier" or "**identifier". Functions may ' + 'have\n' + '"return" annotation of the form ""-> expression"" after the ' + 'parameter\n' + 'list. These annotations can be any valid Python expression ' + 'and are\n' + 'evaluated when the function definition is executed. ' + 'Annotations may\n' + 'be evaluated in a different order than they appear in the ' + 'source code.\n' + 'The presence of annotations does not change the semantics of ' + 'a\n' + 'function. The annotation values are available as values of a\n' + "dictionary keyed by the parameters' names in the " + '"__annotations__"\n' + 'attribute of the function object.\n' + '\n' + 'It is also possible to create anonymous functions (functions ' + 'not bound\n' + 'to a name), for immediate use in expressions. This uses ' + 'lambda\n' + 'expressions, described in section *Lambdas*. Note that the ' + 'lambda\n' + 'expression is merely a shorthand for a simplified function ' + 'definition;\n' + 'a function defined in a ""def"" statement can be passed around ' + 'or\n' + 'assigned to another name just like a function defined by a ' + 'lambda\n' + 'expression. The ""def"" form is actually more powerful since ' + 'it\n' + 'allows the execution of multiple statements and annotations.\n' + '\n' + "**Programmer's note:** Functions are first-class objects. A " + '""def""\n' + 'statement executed inside a function definition defines a ' + 'local\n' + 'function that can be returned or passed around. Free ' + 'variables used\n' + 'in the nested function can access the local variables of the ' + 'function\n' + 'containing the def. See section *Naming and binding* for ' + 'details.\n' + '\n' + 'See also: **PEP 3107** - Function Annotations\n' + '\n' + ' The original specification for function annotations.\n', + 'global': '\n' + 'The "global" statement\n' + '**********************\n' + '\n' + ' global_stmt ::= "global" identifier ("," identifier)*\n' + '\n' + 'The "global" statement is a declaration which holds for the ' + 'entire\n' + 'current code block. It means that the listed identifiers are to ' + 'be\n' + 'interpreted as globals. It would be impossible to assign to a ' + 'global\n' + 'variable without "global", although free variables may refer to\n' + 'globals without being declared global.\n' + '\n' + 'Names listed in a "global" statement must not be used in the ' + 'same code\n' + 'block textually preceding that "global" statement.\n' + '\n' + 'Names listed in a "global" statement must not be defined as ' + 'formal\n' + 'parameters or in a "for" loop control target, "class" ' + 'definition,\n' + 'function definition, or "import" statement.\n' + '\n' + '**CPython implementation detail:** The current implementation ' + 'does not\n' + 'enforce the two restrictions, but programs should not abuse ' + 'this\n' + 'freedom, as future implementations may enforce them or silently ' + 'change\n' + 'the meaning of the program.\n' + '\n' + '**Programmer\'s note:** the "global" is a directive to the ' + 'parser. It\n' + 'applies only to code parsed at the same time as the "global"\n' + 'statement. In particular, a "global" statement contained in a ' + 'string\n' + 'or code object supplied to the built-in "exec()" function does ' + 'not\n' + 'affect the code block *containing* the function call, and code\n' + 'contained in such a string is unaffected by "global" statements ' + 'in the\n' + 'code containing the function call. The same applies to the ' + '"eval()"\n' + 'and "compile()" functions.\n', + 'id-classes': '\n' + 'Reserved classes of identifiers\n' + '*******************************\n' + '\n' + 'Certain classes of identifiers (besides keywords) have ' + 'special\n' + 'meanings. These classes are identified by the patterns of ' + 'leading and\n' + 'trailing underscore characters:\n' + '\n' + '"_*"\n' + ' Not imported by "from module import *". The special ' + 'identifier "_"\n' + ' is used in the interactive interpreter to store the ' + 'result of the\n' + ' last evaluation; it is stored in the "builtins" module. ' + 'When not\n' + ' in interactive mode, "_" has no special meaning and is ' + 'not defined.\n' + ' See section *The import statement*.\n' + '\n' + ' Note: The name "_" is often used in conjunction with\n' + ' internationalization; refer to the documentation for ' + 'the\n' + ' "gettext" module for more information on this ' + 'convention.\n' + '\n' + '"__*__"\n' + ' System-defined names. These names are defined by the ' + 'interpreter\n' + ' and its implementation (including the standard library). ' + 'Current\n' + ' system names are discussed in the *Special method names* ' + 'section\n' + ' and elsewhere. More will likely be defined in future ' + 'versions of\n' + ' Python. *Any* use of "__*__" names, in any context, that ' + 'does not\n' + ' follow explicitly documented use, is subject to breakage ' + 'without\n' + ' warning.\n' + '\n' + '"__*"\n' + ' Class-private names. Names in this category, when used ' + 'within the\n' + ' context of a class definition, are re-written to use a ' + 'mangled form\n' + ' to help avoid name clashes between "private" attributes ' + 'of base and\n' + ' derived classes. See section *Identifiers (Names)*.\n', + 'identifiers': '\n' + 'Identifiers and keywords\n' + '************************\n' + '\n' + 'Identifiers (also referred to as *names*) are described by ' + 'the\n' + 'following lexical definitions.\n' + '\n' + 'The syntax of identifiers in Python is based on the Unicode ' + 'standard\n' + 'annex UAX-31, with elaboration and changes as defined ' + 'below; see also\n' + '**PEP 3131** for further details.\n' + '\n' + 'Within the ASCII range (U+0001..U+007F), the valid ' + 'characters for\n' + 'identifiers are the same as in Python 2.x: the uppercase ' + 'and lowercase\n' + 'letters "A" through "Z", the underscore "_" and, except for ' + 'the first\n' + 'character, the digits "0" through "9".\n' + '\n' + 'Python 3.0 introduces additional characters from outside ' + 'the ASCII\n' + 'range (see **PEP 3131**). For these characters, the ' + 'classification\n' + 'uses the version of the Unicode Character Database as ' + 'included in the\n' + '"unicodedata" module.\n' + '\n' + 'Identifiers are unlimited in length. Case is significant.\n' + '\n' + ' identifier ::= xid_start xid_continue*\n' + ' id_start ::= \n' + ' id_continue ::= \n' + ' xid_start ::= \n' + ' xid_continue ::= \n' + '\n' + 'The Unicode category codes mentioned above stand for:\n' + '\n' + '* *Lu* - uppercase letters\n' + '\n' + '* *Ll* - lowercase letters\n' + '\n' + '* *Lt* - titlecase letters\n' + '\n' + '* *Lm* - modifier letters\n' + '\n' + '* *Lo* - other letters\n' + '\n' + '* *Nl* - letter numbers\n' + '\n' + '* *Mn* - nonspacing marks\n' + '\n' + '* *Mc* - spacing combining marks\n' + '\n' + '* *Nd* - decimal numbers\n' + '\n' + '* *Pc* - connector punctuations\n' + '\n' + '* *Other_ID_Start* - explicit list of characters in ' + 'PropList.txt to\n' + ' support backwards compatibility\n' + '\n' + '* *Other_ID_Continue* - likewise\n' + '\n' + 'All identifiers are converted into the normal form NFKC ' + 'while parsing;\n' + 'comparison of identifiers is based on NFKC.\n' + '\n' + 'A non-normative HTML file listing all valid identifier ' + 'characters for\n' + 'Unicode 4.1 can be found at http://www.dcl.hpi.uni-\n' + 'potsdam.de/home/loewis/table-3131.html.\n' + '\n' + '\n' + 'Keywords\n' + '========\n' + '\n' + 'The following identifiers are used as reserved words, or ' + '*keywords* of\n' + 'the language, and cannot be used as ordinary identifiers. ' + 'They must\n' + 'be spelled exactly as written here:\n' + '\n' + ' False class finally is return\n' + ' None continue for lambda try\n' + ' True def from nonlocal while\n' + ' and del global not with\n' + ' as elif if or yield\n' + ' assert else import pass\n' + ' break except in raise\n' + '\n' + '\n' + 'Reserved classes of identifiers\n' + '===============================\n' + '\n' + 'Certain classes of identifiers (besides keywords) have ' + 'special\n' + 'meanings. These classes are identified by the patterns of ' + 'leading and\n' + 'trailing underscore characters:\n' + '\n' + '"_*"\n' + ' Not imported by "from module import *". The special ' + 'identifier "_"\n' + ' is used in the interactive interpreter to store the ' + 'result of the\n' + ' last evaluation; it is stored in the "builtins" module. ' + 'When not\n' + ' in interactive mode, "_" has no special meaning and is ' + 'not defined.\n' + ' See section *The import statement*.\n' + '\n' + ' Note: The name "_" is often used in conjunction with\n' + ' internationalization; refer to the documentation for ' + 'the\n' + ' "gettext" module for more information on this ' + 'convention.\n' + '\n' + '"__*__"\n' + ' System-defined names. These names are defined by the ' + 'interpreter\n' + ' and its implementation (including the standard ' + 'library). Current\n' + ' system names are discussed in the *Special method names* ' + 'section\n' + ' and elsewhere. More will likely be defined in future ' + 'versions of\n' + ' Python. *Any* use of "__*__" names, in any context, ' + 'that does not\n' + ' follow explicitly documented use, is subject to breakage ' + 'without\n' + ' warning.\n' + '\n' + '"__*"\n' + ' Class-private names. Names in this category, when used ' + 'within the\n' + ' context of a class definition, are re-written to use a ' + 'mangled form\n' + ' to help avoid name clashes between "private" attributes ' + 'of base and\n' + ' derived classes. See section *Identifiers (Names)*.\n', + 'if': '\n' + 'The "if" statement\n' + '******************\n' + '\n' + 'The "if" statement is used for conditional execution:\n' + '\n' + ' if_stmt ::= "if" expression ":" suite\n' + ' ( "elif" expression ":" suite )*\n' + ' ["else" ":" suite]\n' + '\n' + 'It selects exactly one of the suites by evaluating the expressions ' + 'one\n' + 'by one until one is found to be true (see section *Boolean ' + 'operations*\n' + 'for the definition of true and false); then that suite is executed\n' + '(and no other part of the "if" statement is executed or evaluated).\n' + 'If all expressions are false, the suite of the "else" clause, if\n' + 'present, is executed.\n', + 'imaginary': '\n' + 'Imaginary literals\n' + '******************\n' + '\n' + 'Imaginary literals are described by the following lexical ' + 'definitions:\n' + '\n' + ' imagnumber ::= (floatnumber | intpart) ("j" | "J")\n' + '\n' + 'An imaginary literal yields a complex number with a real part ' + 'of 0.0.\n' + 'Complex numbers are represented as a pair of floating point ' + 'numbers\n' + 'and have the same restrictions on their range. To create a ' + 'complex\n' + 'number with a nonzero real part, add a floating point number ' + 'to it,\n' + 'e.g., "(3+4j)". Some examples of imaginary literals:\n' + '\n' + ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j\n', + 'import': '\n' + 'The "import" statement\n' + '**********************\n' + '\n' + ' import_stmt ::= "import" module ["as" name] ( "," module ' + '["as" name] )*\n' + ' | "from" relative_module "import" identifier ' + '["as" name]\n' + ' ( "," identifier ["as" name] )*\n' + ' | "from" relative_module "import" "(" ' + 'identifier ["as" name]\n' + ' ( "," identifier ["as" name] )* [","] ")"\n' + ' | "from" module "import" "*"\n' + ' module ::= (identifier ".")* identifier\n' + ' relative_module ::= "."* module | "."+\n' + ' name ::= identifier\n' + '\n' + 'The basic import statement (no "from" clause) is executed in ' + 'two\n' + 'steps:\n' + '\n' + '1. find a module, loading and initializing it if necessary\n' + '\n' + '2. define a name or names in the local namespace for the scope\n' + ' where the "import" statement occurs.\n' + '\n' + 'When the statement contains multiple clauses (separated by ' + 'commas) the\n' + 'two steps are carried out separately for each clause, just as ' + 'though\n' + 'the clauses had been separated out into individiual import ' + 'statements.\n' + '\n' + 'The details of the first step, finding and loading modules are\n' + 'described in greater detail in the section on the *import ' + 'system*,\n' + 'which also describes the various types of packages and modules ' + 'that\n' + 'can be imported, as well as all the hooks that can be used to\n' + 'customize the import system. Note that failures in this step ' + 'may\n' + 'indicate either that the module could not be located, *or* that ' + 'an\n' + 'error occurred while initializing the module, which includes ' + 'execution\n' + "of the module's code.\n" + '\n' + 'If the requested module is retrieved successfully, it will be ' + 'made\n' + 'available in the local namespace in one of three ways:\n' + '\n' + '* If the module name is followed by "as", then the name ' + 'following\n' + ' "as" is bound directly to the imported module.\n' + '\n' + '* If no other name is specified, and the module being imported ' + 'is a\n' + " top level module, the module's name is bound in the local " + 'namespace\n' + ' as a reference to the imported module\n' + '\n' + '* If the module being imported is *not* a top level module, then ' + 'the\n' + ' name of the top level package that contains the module is ' + 'bound in\n' + ' the local namespace as a reference to the top level package. ' + 'The\n' + ' imported module must be accessed using its full qualified ' + 'name\n' + ' rather than directly\n' + '\n' + 'The "from" form uses a slightly more complex process:\n' + '\n' + '1. find the module specified in the "from" clause, loading and\n' + ' initializing it if necessary;\n' + '\n' + '2. for each of the identifiers specified in the "import" ' + 'clauses:\n' + '\n' + ' 1. check if the imported module has an attribute by that ' + 'name\n' + '\n' + ' 2. if not, attempt to import a submodule with that name and ' + 'then\n' + ' check the imported module again for that attribute\n' + '\n' + ' 3. if the attribute is not found, "ImportError" is raised.\n' + '\n' + ' 4. otherwise, a reference to that value is stored in the ' + 'local\n' + ' namespace, using the name in the "as" clause if it is ' + 'present,\n' + ' otherwise using the attribute name\n' + '\n' + 'Examples:\n' + '\n' + ' import foo # foo imported and bound locally\n' + ' import foo.bar.baz # foo.bar.baz imported, foo bound ' + 'locally\n' + ' import foo.bar.baz as fbb # foo.bar.baz imported and bound ' + 'as fbb\n' + ' from foo.bar import baz # foo.bar.baz imported and bound ' + 'as baz\n' + ' from foo import attr # foo imported and foo.attr bound ' + 'as attr\n' + '\n' + 'If the list of identifiers is replaced by a star ("\'*\'"), all ' + 'public\n' + 'names defined in the module are bound in the local namespace for ' + 'the\n' + 'scope where the "import" statement occurs.\n' + '\n' + 'The *public names* defined by a module are determined by ' + 'checking the\n' + 'module\'s namespace for a variable named "__all__"; if defined, ' + 'it must\n' + 'be a sequence of strings which are names defined or imported by ' + 'that\n' + 'module. The names given in "__all__" are all considered public ' + 'and\n' + 'are required to exist. If "__all__" is not defined, the set of ' + 'public\n' + "names includes all names found in the module's namespace which " + 'do not\n' + 'begin with an underscore character ("\'_\'"). "__all__" should ' + 'contain\n' + 'the entire public API. It is intended to avoid accidentally ' + 'exporting\n' + 'items that are not part of the API (such as library modules ' + 'which were\n' + 'imported and used within the module).\n' + '\n' + 'The wild card form of import --- "from module import *" --- is ' + 'only\n' + 'allowed at the module level. Attempting to use it in class or\n' + 'function definitions will raise a "SyntaxError".\n' + '\n' + 'When specifying what module to import you do not have to specify ' + 'the\n' + 'absolute name of the module. When a module or package is ' + 'contained\n' + 'within another package it is possible to make a relative import ' + 'within\n' + 'the same top package without having to mention the package name. ' + 'By\n' + 'using leading dots in the specified module or package after ' + '"from" you\n' + 'can specify how high to traverse up the current package ' + 'hierarchy\n' + 'without specifying exact names. One leading dot means the ' + 'current\n' + 'package where the module making the import exists. Two dots ' + 'means up\n' + 'one package level. Three dots is up two levels, etc. So if you ' + 'execute\n' + '"from . import mod" from a module in the "pkg" package then you ' + 'will\n' + 'end up importing "pkg.mod". If you execute "from ..subpkg2 ' + 'import mod"\n' + 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". ' + 'The\n' + 'specification for relative imports is contained within **PEP ' + '328**.\n' + '\n' + '"importlib.import_module()" is provided to support applications ' + 'that\n' + 'determine dynamically the modules to be loaded.\n' + '\n' + '\n' + 'Future statements\n' + '=================\n' + '\n' + 'A *future statement* is a directive to the compiler that a ' + 'particular\n' + 'module should be compiled using syntax or semantics that will ' + 'be\n' + 'available in a specified future release of Python where the ' + 'feature\n' + 'becomes standard.\n' + '\n' + 'The future statement is intended to ease migration to future ' + 'versions\n' + 'of Python that introduce incompatible changes to the language. ' + 'It\n' + 'allows use of the new features on a per-module basis before the\n' + 'release in which the feature becomes standard.\n' + '\n' + ' future_statement ::= "from" "__future__" "import" feature ' + '["as" name]\n' + ' ("," feature ["as" name])*\n' + ' | "from" "__future__" "import" "(" ' + 'feature ["as" name]\n' + ' ("," feature ["as" name])* [","] ")"\n' + ' feature ::= identifier\n' + ' name ::= identifier\n' + '\n' + 'A future statement must appear near the top of the module. The ' + 'only\n' + 'lines that can appear before a future statement are:\n' + '\n' + '* the module docstring (if any),\n' + '\n' + '* comments,\n' + '\n' + '* blank lines, and\n' + '\n' + '* other future statements.\n' + '\n' + 'The features recognized by Python 3.0 are "absolute_import",\n' + '"division", "generators", "unicode_literals", "print_function",\n' + '"nested_scopes" and "with_statement". They are all redundant ' + 'because\n' + 'they are always enabled, and only kept for backwards ' + 'compatibility.\n' + '\n' + 'A future statement is recognized and treated specially at ' + 'compile\n' + 'time: Changes to the semantics of core constructs are often\n' + 'implemented by generating different code. It may even be the ' + 'case\n' + 'that a new feature introduces new incompatible syntax (such as a ' + 'new\n' + 'reserved word), in which case the compiler may need to parse ' + 'the\n' + 'module differently. Such decisions cannot be pushed off until\n' + 'runtime.\n' + '\n' + 'For any given release, the compiler knows which feature names ' + 'have\n' + 'been defined, and raises a compile-time error if a future ' + 'statement\n' + 'contains a feature not known to it.\n' + '\n' + 'The direct runtime semantics are the same as for any import ' + 'statement:\n' + 'there is a standard module "__future__", described later, and it ' + 'will\n' + 'be imported in the usual way at the time the future statement ' + 'is\n' + 'executed.\n' + '\n' + 'The interesting runtime semantics depend on the specific ' + 'feature\n' + 'enabled by the future statement.\n' + '\n' + 'Note that there is nothing special about the statement:\n' + '\n' + ' import __future__ [as name]\n' + '\n' + "That is not a future statement; it's an ordinary import " + 'statement with\n' + 'no special semantics or syntax restrictions.\n' + '\n' + 'Code compiled by calls to the built-in functions "exec()" and\n' + '"compile()" that occur in a module "M" containing a future ' + 'statement\n' + 'will, by default, use the new syntax or semantics associated ' + 'with the\n' + 'future statement. This can be controlled by optional arguments ' + 'to\n' + '"compile()" --- see the documentation of that function for ' + 'details.\n' + '\n' + 'A future statement typed at an interactive interpreter prompt ' + 'will\n' + 'take effect for the rest of the interpreter session. If an\n' + 'interpreter is started with the *-i* option, is passed a script ' + 'name\n' + 'to execute, and the script includes a future statement, it will ' + 'be in\n' + 'effect in the interactive session started after the script is\n' + 'executed.\n' + '\n' + 'See also: **PEP 236** - Back to the __future__\n' + '\n' + ' The original proposal for the __future__ mechanism.\n', + 'in': '\n' + 'Membership test operations\n' + '**************************\n' + '\n' + 'The operators "in" and "not in" test for membership. "x in s"\n' + 'evaluates to true if *x* is a member of *s*, and false otherwise. ' + '"x\n' + 'not in s" returns the negation of "x in s". All built-in sequences\n' + 'and set types support this as well as dictionary, for which "in" ' + 'tests\n' + 'whether the dictionary has a given key. For container types such as\n' + 'list, tuple, set, frozenset, dict, or collections.deque, the\n' + 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n' + 'y)".\n' + '\n' + 'For the string and bytes types, "x in y" is true if and only if *x* ' + 'is\n' + 'a substring of *y*. An equivalent test is "y.find(x) != -1". ' + 'Empty\n' + 'strings are always considered to be a substring of any other ' + 'string,\n' + 'so """ in "abc"" will return "True".\n' + '\n' + 'For user-defined classes which define the "__contains__()" method, ' + '"x\n' + 'in y" is true if and only if "y.__contains__(x)" is true.\n' + '\n' + 'For user-defined classes which do not define "__contains__()" but ' + 'do\n' + 'define "__iter__()", "x in y" is true if some value "z" with "x == ' + 'z"\n' + 'is produced while iterating over "y". If an exception is raised\n' + 'during the iteration, it is as if "in" raised that exception.\n' + '\n' + 'Lastly, the old-style iteration protocol is tried: if a class ' + 'defines\n' + '"__getitem__()", "x in y" is true if and only if there is a non-\n' + 'negative integer index *i* such that "x == y[i]", and all lower\n' + 'integer indices do not raise "IndexError" exception. (If any other\n' + 'exception is raised, it is as if "in" raised that exception).\n' + '\n' + 'The operator "not in" is defined to have the inverse true value of\n' + '"in".\n', + 'integers': '\n' + 'Integer literals\n' + '****************\n' + '\n' + 'Integer literals are described by the following lexical ' + 'definitions:\n' + '\n' + ' integer ::= decimalinteger | octinteger | hexinteger ' + '| bininteger\n' + ' decimalinteger ::= nonzerodigit digit* | "0"+\n' + ' nonzerodigit ::= "1"..."9"\n' + ' digit ::= "0"..."9"\n' + ' octinteger ::= "0" ("o" | "O") octdigit+\n' + ' hexinteger ::= "0" ("x" | "X") hexdigit+\n' + ' bininteger ::= "0" ("b" | "B") bindigit+\n' + ' octdigit ::= "0"..."7"\n' + ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' + ' bindigit ::= "0" | "1"\n' + '\n' + 'There is no limit for the length of integer literals apart ' + 'from what\n' + 'can be stored in available memory.\n' + '\n' + 'Note that leading zeros in a non-zero decimal number are not ' + 'allowed.\n' + 'This is for disambiguation with C-style octal literals, which ' + 'Python\n' + 'used before version 3.0.\n' + '\n' + 'Some examples of integer literals:\n' + '\n' + ' 7 2147483647 0o177 ' + '0b100110111\n' + ' 3 79228162514264337593543950336 0o377 ' + '0xdeadbeef\n', + 'lambda': '\n' + 'Lambdas\n' + '*******\n' + '\n' + ' lambda_expr ::= "lambda" [parameter_list]: expression\n' + ' lambda_expr_nocond ::= "lambda" [parameter_list]: ' + 'expression_nocond\n' + '\n' + 'Lambda expressions (sometimes called lambda forms) are used to ' + 'create\n' + 'anonymous functions. The expression "lambda arguments: ' + 'expression"\n' + 'yields a function object. The unnamed object behaves like a ' + 'function\n' + 'object defined with\n' + '\n' + ' def (arguments):\n' + ' return expression\n' + '\n' + 'See section *Function definitions* for the syntax of parameter ' + 'lists.\n' + 'Note that functions created with lambda expressions cannot ' + 'contain\n' + 'statements or annotations.\n', + 'lists': '\n' + 'List displays\n' + '*************\n' + '\n' + 'A list display is a possibly empty series of expressions enclosed ' + 'in\n' + 'square brackets:\n' + '\n' + ' list_display ::= "[" [expression_list | comprehension] "]"\n' + '\n' + 'A list display yields a new list object, the contents being ' + 'specified\n' + 'by either a list of expressions or a comprehension. When a ' + 'comma-\n' + 'separated list of expressions is supplied, its elements are ' + 'evaluated\n' + 'from left to right and placed into the list object in that ' + 'order.\n' + 'When a comprehension is supplied, the list is constructed from ' + 'the\n' + 'elements resulting from the comprehension.\n', + 'naming': '\n' + 'Naming and binding\n' + '******************\n' + '\n' + '\n' + 'Binding of names\n' + '================\n' + '\n' + '*Names* refer to objects. Names are introduced by name binding\n' + 'operations.\n' + '\n' + 'The following constructs bind names: formal parameters to ' + 'functions,\n' + '"import" statements, class and function definitions (these bind ' + 'the\n' + 'class or function name in the defining block), and targets that ' + 'are\n' + 'identifiers if occurring in an assignment, "for" loop header, or ' + 'after\n' + '"as" in a "with" statement or "except" clause. The "import" ' + 'statement\n' + 'of the form "from ... import *" binds all names defined in the\n' + 'imported module, except those beginning with an underscore. ' + 'This form\n' + 'may only be used at the module level.\n' + '\n' + 'A target occurring in a "del" statement is also considered bound ' + 'for\n' + 'this purpose (though the actual semantics are to unbind the ' + 'name).\n' + '\n' + 'Each assignment or import statement occurs within a block ' + 'defined by a\n' + 'class or function definition or at the module level (the ' + 'top-level\n' + 'code block).\n' + '\n' + 'If a name is bound in a block, it is a local variable of that ' + 'block,\n' + 'unless declared as "nonlocal" or "global". If a name is bound ' + 'at the\n' + 'module level, it is a global variable. (The variables of the ' + 'module\n' + 'code block are local and global.) If a variable is used in a ' + 'code\n' + 'block but not defined there, it is a *free variable*.\n' + '\n' + 'Each occurrence of a name in the program text refers to the ' + '*binding*\n' + 'of that name established by the following name resolution ' + 'rules.\n' + '\n' + '\n' + 'Resolution of names\n' + '===================\n' + '\n' + 'A *scope* defines the visibility of a name within a block. If a ' + 'local\n' + 'variable is defined in a block, its scope includes that block. ' + 'If the\n' + 'definition occurs in a function block, the scope extends to any ' + 'blocks\n' + 'contained within the defining one, unless a contained block ' + 'introduces\n' + 'a different binding for the name.\n' + '\n' + 'When a name is used in a code block, it is resolved using the ' + 'nearest\n' + 'enclosing scope. The set of all such scopes visible to a code ' + 'block\n' + "is called the block's *environment*.\n" + '\n' + 'When a name is not found at all, a "NameError" exception is ' + 'raised. If\n' + 'the current scope is a function scope, and the name refers to a ' + 'local\n' + 'variable that has not yet been bound to a value at the point ' + 'where the\n' + 'name is used, an "UnboundLocalError" exception is raised.\n' + '"UnboundLocalError" is a subclass of "NameError".\n' + '\n' + 'If a name binding operation occurs anywhere within a code block, ' + 'all\n' + 'uses of the name within the block are treated as references to ' + 'the\n' + 'current block. This can lead to errors when a name is used ' + 'within a\n' + 'block before it is bound. This rule is subtle. Python lacks\n' + 'declarations and allows name binding operations to occur ' + 'anywhere\n' + 'within a code block. The local variables of a code block can ' + 'be\n' + 'determined by scanning the entire text of the block for name ' + 'binding\n' + 'operations.\n' + '\n' + 'If the "global" statement occurs within a block, all uses of the ' + 'name\n' + 'specified in the statement refer to the binding of that name in ' + 'the\n' + 'top-level namespace. Names are resolved in the top-level ' + 'namespace by\n' + 'searching the global namespace, i.e. the namespace of the ' + 'module\n' + 'containing the code block, and the builtins namespace, the ' + 'namespace\n' + 'of the module "builtins". The global namespace is searched ' + 'first. If\n' + 'the name is not found there, the builtins namespace is ' + 'searched. The\n' + '"global" statement must precede all uses of the name.\n' + '\n' + 'The "global" statement has the same scope as a name binding ' + 'operation\n' + 'in the same block. If the nearest enclosing scope for a free ' + 'variable\n' + 'contains a global statement, the free variable is treated as a ' + 'global.\n' + '\n' + 'The "nonlocal" statement causes corresponding names to refer to\n' + 'previously bound variables in the nearest enclosing function ' + 'scope.\n' + '"SyntaxError" is raised at compile time if the given name does ' + 'not\n' + 'exist in any enclosing function scope.\n' + '\n' + 'The namespace for a module is automatically created the first ' + 'time a\n' + 'module is imported. The main module for a script is always ' + 'called\n' + '"__main__".\n' + '\n' + 'Class definition blocks and arguments to "exec()" and "eval()" ' + 'are\n' + 'special in the context of name resolution. A class definition is ' + 'an\n' + 'executable statement that may use and define names. These ' + 'references\n' + 'follow the normal rules for name resolution with an exception ' + 'that\n' + 'unbound local variables are looked up in the global namespace. ' + 'The\n' + 'namespace of the class definition becomes the attribute ' + 'dictionary of\n' + 'the class. The scope of names defined in a class block is ' + 'limited to\n' + 'the class block; it does not extend to the code blocks of ' + 'methods --\n' + 'this includes comprehensions and generator expressions since ' + 'they are\n' + 'implemented using a function scope. This means that the ' + 'following\n' + 'will fail:\n' + '\n' + ' class A:\n' + ' a = 42\n' + ' b = list(a + i for i in range(10))\n' + '\n' + '\n' + 'Builtins and restricted execution\n' + '=================================\n' + '\n' + 'The builtins namespace associated with the execution of a code ' + 'block\n' + 'is actually found by looking up the name "__builtins__" in its ' + 'global\n' + 'namespace; this should be a dictionary or a module (in the ' + 'latter case\n' + "the module's dictionary is used). By default, when in the " + '"__main__"\n' + 'module, "__builtins__" is the built-in module "builtins"; when ' + 'in any\n' + 'other module, "__builtins__" is an alias for the dictionary of ' + 'the\n' + '"builtins" module itself. "__builtins__" can be set to a ' + 'user-created\n' + 'dictionary to create a weak form of restricted execution.\n' + '\n' + '**CPython implementation detail:** Users should not touch\n' + '"__builtins__"; it is strictly an implementation detail. Users\n' + 'wanting to override values in the builtins namespace should ' + '"import"\n' + 'the "builtins" module and modify its attributes appropriately.\n' + '\n' + '\n' + 'Interaction with dynamic features\n' + '=================================\n' + '\n' + 'Name resolution of free variables occurs at runtime, not at ' + 'compile\n' + 'time. This means that the following code will print 42:\n' + '\n' + ' i = 10\n' + ' def f():\n' + ' print(i)\n' + ' i = 42\n' + ' f()\n' + '\n' + 'There are several cases where Python statements are illegal when ' + 'used\n' + 'in conjunction with nested scopes that contain free variables.\n' + '\n' + 'If a variable is referenced in an enclosing scope, it is illegal ' + 'to\n' + 'delete the name. An error will be reported at compile time.\n' + '\n' + 'The "eval()" and "exec()" functions do not have access to the ' + 'full\n' + 'environment for resolving names. Names may be resolved in the ' + 'local\n' + 'and global namespaces of the caller. Free variables are not ' + 'resolved\n' + 'in the nearest enclosing namespace, but in the global ' + 'namespace. [1]\n' + 'The "exec()" and "eval()" functions have optional arguments to\n' + 'override the global and local namespace. If only one namespace ' + 'is\n' + 'specified, it is used for both.\n', + 'nonlocal': '\n' + 'The "nonlocal" statement\n' + '************************\n' + '\n' + ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' + '\n' + 'The "nonlocal" statement causes the listed identifiers to ' + 'refer to\n' + 'previously bound variables in the nearest enclosing scope ' + 'excluding\n' + 'globals. This is important because the default behavior for ' + 'binding is\n' + 'to search the local namespace first. The statement allows\n' + 'encapsulated code to rebind variables outside of the local ' + 'scope\n' + 'besides the global (module) scope.\n' + '\n' + 'Names listed in a "nonlocal" statement, unlike those listed in ' + 'a\n' + '"global" statement, must refer to pre-existing bindings in an\n' + 'enclosing scope (the scope in which a new binding should be ' + 'created\n' + 'cannot be determined unambiguously).\n' + '\n' + 'Names listed in a "nonlocal" statement must not collide with ' + 'pre-\n' + 'existing bindings in the local scope.\n' + '\n' + 'See also: **PEP 3104** - Access to Names in Outer Scopes\n' + '\n' + ' The specification for the "nonlocal" statement.\n', + 'numbers': '\n' + 'Numeric literals\n' + '****************\n' + '\n' + 'There are three types of numeric literals: integers, floating ' + 'point\n' + 'numbers, and imaginary numbers. There are no complex literals\n' + '(complex numbers can be formed by adding a real number and an\n' + 'imaginary number).\n' + '\n' + 'Note that numeric literals do not include a sign; a phrase like ' + '"-1"\n' + 'is actually an expression composed of the unary operator ' + '\'"-"\' and the\n' + 'literal "1".\n', + 'numeric-types': '\n' + 'Emulating numeric types\n' + '***********************\n' + '\n' + 'The following methods can be defined to emulate numeric ' + 'objects.\n' + 'Methods corresponding to operations that are not ' + 'supported by the\n' + 'particular kind of number implemented (e.g., bitwise ' + 'operations for\n' + 'non-integral numbers) should be left undefined.\n' + '\n' + 'object.__add__(self, other)\n' + 'object.__sub__(self, other)\n' + 'object.__mul__(self, other)\n' + 'object.__truediv__(self, other)\n' + 'object.__floordiv__(self, other)\n' + 'object.__mod__(self, other)\n' + 'object.__divmod__(self, other)\n' + 'object.__pow__(self, other[, modulo])\n' + 'object.__lshift__(self, other)\n' + 'object.__rshift__(self, other)\n' + 'object.__and__(self, other)\n' + 'object.__xor__(self, other)\n' + 'object.__or__(self, other)\n' + '\n' + ' These methods are called to implement the binary ' + 'arithmetic\n' + ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' + '"pow()",\n' + ' "**", "<<", ">>", "&", "^", "|"). For instance, to ' + 'evaluate the\n' + ' expression "x + y", where *x* is an instance of a ' + 'class that has an\n' + ' "__add__()" method, "x.__add__(y)" is called. The ' + '"__divmod__()"\n' + ' method should be the equivalent to using ' + '"__floordiv__()" and\n' + ' "__mod__()"; it should not be related to ' + '"__truediv__()". Note\n' + ' that "__pow__()" should be defined to accept an ' + 'optional third\n' + ' argument if the ternary version of the built-in ' + '"pow()" function is\n' + ' to be supported.\n' + '\n' + ' If one of those methods does not support the operation ' + 'with the\n' + ' supplied arguments, it should return ' + '"NotImplemented".\n' + '\n' + 'object.__radd__(self, other)\n' + 'object.__rsub__(self, other)\n' + 'object.__rmul__(self, other)\n' + 'object.__rtruediv__(self, other)\n' + 'object.__rfloordiv__(self, other)\n' + 'object.__rmod__(self, other)\n' + 'object.__rdivmod__(self, other)\n' + 'object.__rpow__(self, other)\n' + 'object.__rlshift__(self, other)\n' + 'object.__rrshift__(self, other)\n' + 'object.__rand__(self, other)\n' + 'object.__rxor__(self, other)\n' + 'object.__ror__(self, other)\n' + '\n' + ' These methods are called to implement the binary ' + 'arithmetic\n' + ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' + '"pow()",\n' + ' "**", "<<", ">>", "&", "^", "|") with reflected ' + '(swapped) operands.\n' + ' These functions are only called if the left operand ' + 'does not\n' + ' support the corresponding operation and the operands ' + 'are of\n' + ' different types. [2] For instance, to evaluate the ' + 'expression "x -\n' + ' y", where *y* is an instance of a class that has an ' + '"__rsub__()"\n' + ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' + 'returns\n' + ' *NotImplemented*.\n' + '\n' + ' Note that ternary "pow()" will not try calling ' + '"__rpow__()" (the\n' + ' coercion rules would become too complicated).\n' + '\n' + " Note: If the right operand's type is a subclass of the " + 'left\n' + " operand's type and that subclass provides the " + 'reflected method\n' + ' for the operation, this method will be called before ' + 'the left\n' + " operand's non-reflected method. This behavior " + 'allows subclasses\n' + " to override their ancestors' operations.\n" + '\n' + 'object.__iadd__(self, other)\n' + 'object.__isub__(self, other)\n' + 'object.__imul__(self, other)\n' + 'object.__itruediv__(self, other)\n' + 'object.__ifloordiv__(self, other)\n' + 'object.__imod__(self, other)\n' + 'object.__ipow__(self, other[, modulo])\n' + 'object.__ilshift__(self, other)\n' + 'object.__irshift__(self, other)\n' + 'object.__iand__(self, other)\n' + 'object.__ixor__(self, other)\n' + 'object.__ior__(self, other)\n' + '\n' + ' These methods are called to implement the augmented ' + 'arithmetic\n' + ' assignments ("+=", "-=", "*=", "/=", "//=", "%=", ' + '"**=", "<<=",\n' + ' ">>=", "&=", "^=", "|="). These methods should ' + 'attempt to do the\n' + ' operation in-place (modifying *self*) and return the ' + 'result (which\n' + ' could be, but does not have to be, *self*). If a ' + 'specific method\n' + ' is not defined, the augmented assignment falls back to ' + 'the normal\n' + ' methods. For instance, if *x* is an instance of a ' + 'class with an\n' + ' "__iadd__()" method, "x += y" is equivalent to "x = ' + 'x.__iadd__(y)"\n' + ' . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are ' + 'considered, as\n' + ' with the evaluation of "x + y". In certain situations, ' + 'augmented\n' + ' assignment can result in unexpected errors (see *Why ' + 'does\n' + " a_tuple[i] += ['item'] raise an exception when the " + 'addition\n' + ' works?*), but this behavior is in fact part of the ' + 'data model.\n' + '\n' + 'object.__neg__(self)\n' + 'object.__pos__(self)\n' + 'object.__abs__(self)\n' + 'object.__invert__(self)\n' + '\n' + ' Called to implement the unary arithmetic operations ' + '("-", "+",\n' + ' "abs()" and "~").\n' + '\n' + 'object.__complex__(self)\n' + 'object.__int__(self)\n' + 'object.__float__(self)\n' + 'object.__round__(self[, n])\n' + '\n' + ' Called to implement the built-in functions ' + '"complex()", "int()",\n' + ' "float()" and "round()". Should return a value of the ' + 'appropriate\n' + ' type.\n' + '\n' + 'object.__index__(self)\n' + '\n' + ' Called to implement "operator.index()", and whenever ' + 'Python needs\n' + ' to losslessly convert the numeric object to an integer ' + 'object (such\n' + ' as in slicing, or in the built-in "bin()", "hex()" and ' + '"oct()"\n' + ' functions). Presence of this method indicates that the ' + 'numeric\n' + ' object is an integer type. Must return an integer.\n' + '\n' + ' Note: In order to have a coherent integer type class, ' + 'when\n' + ' "__index__()" is defined "__int__()" should also be ' + 'defined, and\n' + ' both should return the same value.\n', + 'objects': '\n' + 'Objects, values and types\n' + '*************************\n' + '\n' + "*Objects* are Python's abstraction for data. All data in a " + 'Python\n' + 'program is represented by objects or by relations between ' + 'objects. (In\n' + "a sense, and in conformance to Von Neumann's model of a " + '"stored\n' + 'program computer," code is also represented by objects.)\n' + '\n' + "Every object has an identity, a type and a value. An object's\n" + '*identity* never changes once it has been created; you may ' + 'think of it\n' + 'as the object\'s address in memory. The \'"is"\' operator ' + 'compares the\n' + 'identity of two objects; the "id()" function returns an ' + 'integer\n' + 'representing its identity.\n' + '\n' + '**CPython implementation detail:** For CPython, "id(x)" is the ' + 'memory\n' + 'address where "x" is stored.\n' + '\n' + "An object's type determines the operations that the object " + 'supports\n' + '(e.g., "does it have a length?") and also defines the possible ' + 'values\n' + 'for objects of that type. The "type()" function returns an ' + "object's\n" + 'type (which is an object itself). Like its identity, an ' + "object's\n" + '*type* is also unchangeable. [1]\n' + '\n' + 'The *value* of some objects can change. Objects whose value ' + 'can\n' + 'change are said to be *mutable*; objects whose value is ' + 'unchangeable\n' + 'once they are created are called *immutable*. (The value of an\n' + 'immutable container object that contains a reference to a ' + 'mutable\n' + "object can change when the latter's value is changed; however " + 'the\n' + 'container is still considered immutable, because the collection ' + 'of\n' + 'objects it contains cannot be changed. So, immutability is ' + 'not\n' + 'strictly the same as having an unchangeable value, it is more ' + 'subtle.)\n' + "An object's mutability is determined by its type; for " + 'instance,\n' + 'numbers, strings and tuples are immutable, while dictionaries ' + 'and\n' + 'lists are mutable.\n' + '\n' + 'Objects are never explicitly destroyed; however, when they ' + 'become\n' + 'unreachable they may be garbage-collected. An implementation ' + 'is\n' + 'allowed to postpone garbage collection or omit it altogether ' + '--- it is\n' + 'a matter of implementation quality how garbage collection is\n' + 'implemented, as long as no objects are collected that are ' + 'still\n' + 'reachable.\n' + '\n' + '**CPython implementation detail:** CPython currently uses a ' + 'reference-\n' + 'counting scheme with (optional) delayed detection of cyclically ' + 'linked\n' + 'garbage, which collects most objects as soon as they become\n' + 'unreachable, but is not guaranteed to collect garbage ' + 'containing\n' + 'circular references. See the documentation of the "gc" module ' + 'for\n' + 'information on controlling the collection of cyclic garbage. ' + 'Other\n' + 'implementations act differently and CPython may change. Do not ' + 'depend\n' + 'on immediate finalization of objects when they become ' + 'unreachable (so\n' + 'you should always close files explicitly).\n' + '\n' + "Note that the use of the implementation's tracing or debugging\n" + 'facilities may keep objects alive that would normally be ' + 'collectable.\n' + 'Also note that catching an exception with a ' + '\'"try"..."except"\'\n' + 'statement may keep objects alive.\n' + '\n' + 'Some objects contain references to "external" resources such as ' + 'open\n' + 'files or windows. It is understood that these resources are ' + 'freed\n' + 'when the object is garbage-collected, but since garbage ' + 'collection is\n' + 'not guaranteed to happen, such objects also provide an explicit ' + 'way to\n' + 'release the external resource, usually a "close()" method. ' + 'Programs\n' + 'are strongly recommended to explicitly close such objects. ' + 'The\n' + '\'"try"..."finally"\' statement and the \'"with"\' statement ' + 'provide\n' + 'convenient ways to do this.\n' + '\n' + 'Some objects contain references to other objects; these are ' + 'called\n' + '*containers*. Examples of containers are tuples, lists and\n' + "dictionaries. The references are part of a container's value. " + 'In\n' + 'most cases, when we talk about the value of a container, we ' + 'imply the\n' + 'values, not the identities of the contained objects; however, ' + 'when we\n' + 'talk about the mutability of a container, only the identities ' + 'of the\n' + 'immediately contained objects are implied. So, if an ' + 'immutable\n' + 'container (like a tuple) contains a reference to a mutable ' + 'object, its\n' + 'value changes if that mutable object is changed.\n' + '\n' + 'Types affect almost all aspects of object behavior. Even the\n' + 'importance of object identity is affected in some sense: for ' + 'immutable\n' + 'types, operations that compute new values may actually return ' + 'a\n' + 'reference to any existing object with the same type and value, ' + 'while\n' + 'for mutable objects this is not allowed. E.g., after "a = 1; b ' + '= 1",\n' + '"a" and "b" may or may not refer to the same object with the ' + 'value\n' + 'one, depending on the implementation, but after "c = []; d = ' + '[]", "c"\n' + 'and "d" are guaranteed to refer to two different, unique, ' + 'newly\n' + 'created empty lists. (Note that "c = d = []" assigns the same ' + 'object\n' + 'to both "c" and "d".)\n', + 'operator-summary': '\n' + 'Operator precedence\n' + '*******************\n' + '\n' + 'The following table summarizes the operator precedence ' + 'in Python, from\n' + 'lowest precedence (least binding) to highest ' + 'precedence (most\n' + 'binding). Operators in the same box have the same ' + 'precedence. Unless\n' + 'the syntax is explicitly given, operators are binary. ' + 'Operators in\n' + 'the same box group left to right (except for ' + 'exponentiation, which\n' + 'groups from right to left).\n' + '\n' + 'Note that comparisons, membership tests, and identity ' + 'tests, all have\n' + 'the same precedence and have a left-to-right chaining ' + 'feature as\n' + 'described in the *Comparisons* section.\n' + '\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| Operator | ' + 'Description |\n' + '+=================================================+=======================================+\n' + '| "lambda" | ' + 'Lambda expression |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "if" -- "else" | ' + 'Conditional expression |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "or" | ' + 'Boolean OR |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "and" | ' + 'Boolean AND |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "not" "x" | ' + 'Boolean NOT |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "in", "not in", "is", "is not", "<", "<=", ">", | ' + 'Comparisons, including membership |\n' + '| ">=", "!=", "==" | ' + 'tests and identity tests |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "|" | ' + 'Bitwise OR |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "^" | ' + 'Bitwise XOR |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "&" | ' + 'Bitwise AND |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "<<", ">>" | ' + 'Shifts |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "+", "-" | ' + 'Addition and subtraction |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "*", "/", "//", "%" | ' + 'Multiplication, division, remainder |\n' + '| | ' + '[5] |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "+x", "-x", "~x" | ' + 'Positive, negative, bitwise NOT |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "**" | ' + 'Exponentiation [6] |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "x[index]", "x[index:index]", | ' + 'Subscription, slicing, call, |\n' + '| "x(arguments...)", "x.attribute" | ' + 'attribute reference |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '| "(expressions...)", "[expressions...]", "{key: | ' + 'Binding or tuple display, list |\n' + '| value...}", "{expressions...}" | ' + 'display, dictionary display, set |\n' + '| | ' + 'display |\n' + '+-------------------------------------------------+---------------------------------------+\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] While "abs(x%y) < abs(y)" is true mathematically, ' + 'for floats\n' + ' it may not be true numerically due to roundoff. ' + 'For example, and\n' + ' assuming a platform on which a Python float is an ' + 'IEEE 754 double-\n' + ' precision number, in order that "-1e-100 % 1e100" ' + 'have the same\n' + ' sign as "1e100", the computed result is "-1e-100 + ' + '1e100", which\n' + ' is numerically exactly equal to "1e100". The ' + 'function\n' + ' "math.fmod()" returns a result whose sign matches ' + 'the sign of the\n' + ' first argument instead, and so returns "-1e-100" ' + 'in this case.\n' + ' Which approach is more appropriate depends on the ' + 'application.\n' + '\n' + '[2] If x is very close to an exact integer multiple of ' + "y, it's\n" + ' possible for "x//y" to be one larger than ' + '"(x-x%y)//y" due to\n' + ' rounding. In such cases, Python returns the ' + 'latter result, in\n' + ' order to preserve that "divmod(x,y)[0] * y + x % ' + 'y" be very close\n' + ' to "x".\n' + '\n' + '[3] The Unicode standard distinguishes between *code ' + 'points* (e.g.\n' + ' U+0041) and *abstract characters* (e.g. "LATIN ' + 'CAPITAL LETTER A").\n' + ' While most abstract characters in Unicode are only ' + 'represented\n' + ' using one code point, there is a number of ' + 'abstract characters\n' + ' that can in addition be represented using a ' + 'sequence of more than\n' + ' one code point. For example, the abstract ' + 'character "LATIN\n' + ' CAPITAL LETTER C WITH CEDILLA" can be represented ' + 'as a single\n' + ' *precomposed character* at code position U+00C7, ' + 'or as a sequence\n' + ' of a *base character* at code position U+0043 ' + '(LATIN CAPITAL\n' + ' LETTER C), followed by a *combining character* at ' + 'code position\n' + ' U+0327 (COMBINING CEDILLA).\n' + '\n' + ' The comparison operators on strings compare at the ' + 'level of\n' + ' Unicode code points. This may be counter-intuitive ' + 'to humans. For\n' + ' example, ""\\u00C7" == "\\u0043\\u0327"" is ' + '"False", even though both\n' + ' strings represent the same abstract character ' + '"LATIN CAPITAL\n' + ' LETTER C WITH CEDILLA".\n' + '\n' + ' To compare strings at the level of abstract ' + 'characters (that is,\n' + ' in a way intuitive to humans), use ' + '"unicodedata.normalize()".\n' + '\n' + '[4] Due to automatic garbage-collection, free lists, ' + 'and the\n' + ' dynamic nature of descriptors, you may notice ' + 'seemingly unusual\n' + ' behaviour in certain uses of the "is" operator, ' + 'like those\n' + ' involving comparisons between instance methods, or ' + 'constants.\n' + ' Check their documentation for more info.\n' + '\n' + '[5] The "%" operator is also used for string ' + 'formatting; the same\n' + ' precedence applies.\n' + '\n' + '[6] The power operator "**" binds less tightly than an ' + 'arithmetic\n' + ' or bitwise unary operator on its right, that is, ' + '"2**-1" is "0.5".\n', + 'pass': '\n' + 'The "pass" statement\n' + '********************\n' + '\n' + ' pass_stmt ::= "pass"\n' + '\n' + '"pass" is a null operation --- when it is executed, nothing ' + 'happens.\n' + 'It is useful as a placeholder when a statement is required\n' + 'syntactically, but no code needs to be executed, for example:\n' + '\n' + ' def f(arg): pass # a function that does nothing (yet)\n' + '\n' + ' class C: pass # a class with no methods (yet)\n', + 'power': '\n' + 'The power operator\n' + '******************\n' + '\n' + 'The power operator binds more tightly than unary operators on ' + 'its\n' + 'left; it binds less tightly than unary operators on its right. ' + 'The\n' + 'syntax is:\n' + '\n' + ' power ::= primary ["**" u_expr]\n' + '\n' + 'Thus, in an unparenthesized sequence of power and unary ' + 'operators, the\n' + 'operators are evaluated from right to left (this does not ' + 'constrain\n' + 'the evaluation order for the operands): "-1**2" results in "-1".\n' + '\n' + 'The power operator has the same semantics as the built-in ' + '"pow()"\n' + 'function, when called with two arguments: it yields its left ' + 'argument\n' + 'raised to the power of its right argument. The numeric arguments ' + 'are\n' + 'first converted to a common type, and the result is of that ' + 'type.\n' + '\n' + 'For int operands, the result has the same type as the operands ' + 'unless\n' + 'the second argument is negative; in that case, all arguments are\n' + 'converted to float and a float result is delivered. For example,\n' + '"10**2" returns "100", but "10**-2" returns "0.01".\n' + '\n' + 'Raising "0.0" to a negative power results in a ' + '"ZeroDivisionError".\n' + 'Raising a negative number to a fractional power results in a ' + '"complex"\n' + 'number. (In earlier versions it raised a "ValueError".)\n', + 'raise': '\n' + 'The "raise" statement\n' + '*********************\n' + '\n' + ' raise_stmt ::= "raise" [expression ["from" expression]]\n' + '\n' + 'If no expressions are present, "raise" re-raises the last ' + 'exception\n' + 'that was active in the current scope. If no exception is active ' + 'in\n' + 'the current scope, a "RuntimeError" exception is raised ' + 'indicating\n' + 'that this is an error.\n' + '\n' + 'Otherwise, "raise" evaluates the first expression as the ' + 'exception\n' + 'object. It must be either a subclass or an instance of\n' + '"BaseException". If it is a class, the exception instance will ' + 'be\n' + 'obtained when needed by instantiating the class with no ' + 'arguments.\n' + '\n' + "The *type* of the exception is the exception instance's class, " + 'the\n' + '*value* is the instance itself.\n' + '\n' + 'A traceback object is normally created automatically when an ' + 'exception\n' + 'is raised and attached to it as the "__traceback__" attribute, ' + 'which\n' + 'is writable. You can create an exception and set your own ' + 'traceback in\n' + 'one step using the "with_traceback()" exception method (which ' + 'returns\n' + 'the same exception instance, with its traceback set to its ' + 'argument),\n' + 'like so:\n' + '\n' + ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' + '\n' + 'The "from" clause is used for exception chaining: if given, the ' + 'second\n' + '*expression* must be another exception class or instance, which ' + 'will\n' + 'then be attached to the raised exception as the "__cause__" ' + 'attribute\n' + '(which is writable). If the raised exception is not handled, ' + 'both\n' + 'exceptions will be printed:\n' + '\n' + ' >>> try:\n' + ' ... print(1 / 0)\n' + ' ... except Exception as exc:\n' + ' ... raise RuntimeError("Something bad happened") from exc\n' + ' ...\n' + ' Traceback (most recent call last):\n' + ' File "", line 2, in \n' + ' ZeroDivisionError: int division or modulo by zero\n' + '\n' + ' The above exception was the direct cause of the following ' + 'exception:\n' + '\n' + ' Traceback (most recent call last):\n' + ' File "", line 4, in \n' + ' RuntimeError: Something bad happened\n' + '\n' + 'A similar mechanism works implicitly if an exception is raised ' + 'inside\n' + 'an exception handler or a "finally" clause: the previous ' + 'exception is\n' + 'then attached as the new exception\'s "__context__" attribute:\n' + '\n' + ' >>> try:\n' + ' ... print(1 / 0)\n' + ' ... except:\n' + ' ... raise RuntimeError("Something bad happened")\n' + ' ...\n' + ' Traceback (most recent call last):\n' + ' File "", line 2, in \n' + ' ZeroDivisionError: int division or modulo by zero\n' + '\n' + ' During handling of the above exception, another exception ' + 'occurred:\n' + '\n' + ' Traceback (most recent call last):\n' + ' File "", line 4, in \n' + ' RuntimeError: Something bad happened\n' + '\n' + 'Additional information on exceptions can be found in section\n' + '*Exceptions*, and information about handling exceptions is in ' + 'section\n' + '*The try statement*.\n', + 'return': '\n' + 'The "return" statement\n' + '**********************\n' + '\n' + ' return_stmt ::= "return" [expression_list]\n' + '\n' + '"return" may only occur syntactically nested in a function ' + 'definition,\n' + 'not within a nested class definition.\n' + '\n' + 'If an expression list is present, it is evaluated, else "None" ' + 'is\n' + 'substituted.\n' + '\n' + '"return" leaves the current function call with the expression ' + 'list (or\n' + '"None") as return value.\n' + '\n' + 'When "return" passes control out of a "try" statement with a ' + '"finally"\n' + 'clause, that "finally" clause is executed before really leaving ' + 'the\n' + 'function.\n' + '\n' + 'In a generator function, the "return" statement indicates that ' + 'the\n' + 'generator is done and will cause "StopIteration" to be raised. ' + 'The\n' + 'returned value (if any) is used as an argument to construct\n' + '"StopIteration" and becomes the "StopIteration.value" ' + 'attribute.\n', + 'sequence-types': '\n' + 'Emulating container types\n' + '*************************\n' + '\n' + 'The following methods can be defined to implement ' + 'container objects.\n' + 'Containers usually are sequences (such as lists or ' + 'tuples) or mappings\n' + '(like dictionaries), but can represent other containers ' + 'as well. The\n' + 'first set of methods is used either to emulate a ' + 'sequence or to\n' + 'emulate a mapping; the difference is that for a ' + 'sequence, the\n' + 'allowable keys should be the integers *k* for which "0 ' + '<= k < N" where\n' + '*N* is the length of the sequence, or slice objects, ' + 'which define a\n' + 'range of items. It is also recommended that mappings ' + 'provide the\n' + 'methods "keys()", "values()", "items()", "get()", ' + '"clear()",\n' + '"setdefault()", "pop()", "popitem()", "copy()", and ' + '"update()"\n' + "behaving similar to those for Python's standard " + 'dictionary objects.\n' + 'The "collections" module provides a "MutableMapping" ' + 'abstract base\n' + 'class to help create those methods from a base set of ' + '"__getitem__()",\n' + '"__setitem__()", "__delitem__()", and "keys()". Mutable ' + 'sequences\n' + 'should provide methods "append()", "count()", "index()", ' + '"extend()",\n' + '"insert()", "pop()", "remove()", "reverse()" and ' + '"sort()", like Python\n' + 'standard list objects. Finally, sequence types should ' + 'implement\n' + 'addition (meaning concatenation) and multiplication ' + '(meaning\n' + 'repetition) by defining the methods "__add__()", ' + '"__radd__()",\n' + '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' + 'described\n' + 'below; they should not define other numerical ' + 'operators. It is\n' + 'recommended that both mappings and sequences implement ' + 'the\n' + '"__contains__()" method to allow efficient use of the ' + '"in" operator;\n' + 'for mappings, "in" should search the mapping\'s keys; ' + 'for sequences, it\n' + 'should search through the values. It is further ' + 'recommended that both\n' + 'mappings and sequences implement the "__iter__()" method ' + 'to allow\n' + 'efficient iteration through the container; for mappings, ' + '"__iter__()"\n' + 'should be the same as "keys()"; for sequences, it should ' + 'iterate\n' + 'through the values.\n' + '\n' + 'object.__len__(self)\n' + '\n' + ' Called to implement the built-in function "len()". ' + 'Should return\n' + ' the length of the object, an integer ">=" 0. Also, ' + 'an object that\n' + ' doesn\'t define a "__bool__()" method and whose ' + '"__len__()" method\n' + ' returns zero is considered to be false in a Boolean ' + 'context.\n' + '\n' + 'object.__length_hint__(self)\n' + '\n' + ' Called to implement "operator.length_hint()". Should ' + 'return an\n' + ' estimated length for the object (which may be greater ' + 'or less than\n' + ' the actual length). The length must be an integer ' + '">=" 0. This\n' + ' method is purely an optimization and is never ' + 'required for\n' + ' correctness.\n' + '\n' + ' New in version 3.4.\n' + '\n' + 'Note: Slicing is done exclusively with the following ' + 'three methods.\n' + ' A call like\n' + '\n' + ' a[1:2] = b\n' + '\n' + ' is translated to\n' + '\n' + ' a[slice(1, 2, None)] = b\n' + '\n' + ' and so forth. Missing slice items are always filled ' + 'in with "None".\n' + '\n' + 'object.__getitem__(self, key)\n' + '\n' + ' Called to implement evaluation of "self[key]". For ' + 'sequence types,\n' + ' the accepted keys should be integers and slice ' + 'objects. Note that\n' + ' the special interpretation of negative indexes (if ' + 'the class wishes\n' + ' to emulate a sequence type) is up to the ' + '"__getitem__()" method. If\n' + ' *key* is of an inappropriate type, "TypeError" may be ' + 'raised; if of\n' + ' a value outside the set of indexes for the sequence ' + '(after any\n' + ' special interpretation of negative values), ' + '"IndexError" should be\n' + ' raised. For mapping types, if *key* is missing (not ' + 'in the\n' + ' container), "KeyError" should be raised.\n' + '\n' + ' Note: "for" loops expect that an "IndexError" will be ' + 'raised for\n' + ' illegal indexes to allow proper detection of the ' + 'end of the\n' + ' sequence.\n' + '\n' + 'object.__missing__(self, key)\n' + '\n' + ' Called by "dict"."__getitem__()" to implement ' + '"self[key]" for dict\n' + ' subclasses when key is not in the dictionary.\n' + '\n' + 'object.__setitem__(self, key, value)\n' + '\n' + ' Called to implement assignment to "self[key]". Same ' + 'note as for\n' + ' "__getitem__()". This should only be implemented for ' + 'mappings if\n' + ' the objects support changes to the values for keys, ' + 'or if new keys\n' + ' can be added, or for sequences if elements can be ' + 'replaced. The\n' + ' same exceptions should be raised for improper *key* ' + 'values as for\n' + ' the "__getitem__()" method.\n' + '\n' + 'object.__delitem__(self, key)\n' + '\n' + ' Called to implement deletion of "self[key]". Same ' + 'note as for\n' + ' "__getitem__()". This should only be implemented for ' + 'mappings if\n' + ' the objects support removal of keys, or for sequences ' + 'if elements\n' + ' can be removed from the sequence. The same ' + 'exceptions should be\n' + ' raised for improper *key* values as for the ' + '"__getitem__()" method.\n' + '\n' + 'object.__iter__(self)\n' + '\n' + ' This method is called when an iterator is required ' + 'for a container.\n' + ' This method should return a new iterator object that ' + 'can iterate\n' + ' over all the objects in the container. For mappings, ' + 'it should\n' + ' iterate over the keys of the container.\n' + '\n' + ' Iterator objects also need to implement this method; ' + 'they are\n' + ' required to return themselves. For more information ' + 'on iterator\n' + ' objects, see *Iterator Types*.\n' + '\n' + 'object.__reversed__(self)\n' + '\n' + ' Called (if present) by the "reversed()" built-in to ' + 'implement\n' + ' reverse iteration. It should return a new iterator ' + 'object that\n' + ' iterates over all the objects in the container in ' + 'reverse order.\n' + '\n' + ' If the "__reversed__()" method is not provided, the ' + '"reversed()"\n' + ' built-in will fall back to using the sequence ' + 'protocol ("__len__()"\n' + ' and "__getitem__()"). Objects that support the ' + 'sequence protocol\n' + ' should only provide "__reversed__()" if they can ' + 'provide an\n' + ' implementation that is more efficient than the one ' + 'provided by\n' + ' "reversed()".\n' + '\n' + 'The membership test operators ("in" and "not in") are ' + 'normally\n' + 'implemented as an iteration through a sequence. ' + 'However, container\n' + 'objects can supply the following special method with a ' + 'more efficient\n' + 'implementation, which also does not require the object ' + 'be a sequence.\n' + '\n' + 'object.__contains__(self, item)\n' + '\n' + ' Called to implement membership test operators. ' + 'Should return true\n' + ' if *item* is in *self*, false otherwise. For mapping ' + 'objects, this\n' + ' should consider the keys of the mapping rather than ' + 'the values or\n' + ' the key-item pairs.\n' + '\n' + ' For objects that don\'t define "__contains__()", the ' + 'membership test\n' + ' first tries iteration via "__iter__()", then the old ' + 'sequence\n' + ' iteration protocol via "__getitem__()", see *this ' + 'section in the\n' + ' language reference*.\n', + 'shifting': '\n' + 'Shifting operations\n' + '*******************\n' + '\n' + 'The shifting operations have lower priority than the ' + 'arithmetic\n' + 'operations:\n' + '\n' + ' shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n' + '\n' + 'These operators accept integers as arguments. They shift the ' + 'first\n' + 'argument to the left or right by the number of bits given by ' + 'the\n' + 'second argument.\n' + '\n' + 'A right shift by *n* bits is defined as floor division by ' + '"pow(2,n)".\n' + 'A left shift by *n* bits is defined as multiplication with ' + '"pow(2,n)".\n' + '\n' + 'Note: In the current implementation, the right-hand operand ' + 'is\n' + ' required to be at most "sys.maxsize". If the right-hand ' + 'operand is\n' + ' larger than "sys.maxsize" an "OverflowError" exception is ' + 'raised.\n', + 'slicings': '\n' + 'Slicings\n' + '********\n' + '\n' + 'A slicing selects a range of items in a sequence object (e.g., ' + 'a\n' + 'string, tuple or list). Slicings may be used as expressions ' + 'or as\n' + 'targets in assignment or "del" statements. The syntax for a ' + 'slicing:\n' + '\n' + ' slicing ::= primary "[" slice_list "]"\n' + ' slice_list ::= slice_item ("," slice_item)* [","]\n' + ' slice_item ::= expression | proper_slice\n' + ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" ' + '[stride] ]\n' + ' lower_bound ::= expression\n' + ' upper_bound ::= expression\n' + ' stride ::= expression\n' + '\n' + 'There is ambiguity in the formal syntax here: anything that ' + 'looks like\n' + 'an expression list also looks like a slice list, so any ' + 'subscription\n' + 'can be interpreted as a slicing. Rather than further ' + 'complicating the\n' + 'syntax, this is disambiguated by defining that in this case ' + 'the\n' + 'interpretation as a subscription takes priority over the\n' + 'interpretation as a slicing (this is the case if the slice ' + 'list\n' + 'contains no proper slice).\n' + '\n' + 'The semantics for a slicing are as follows. The primary is ' + 'indexed\n' + '(using the same "__getitem__()" method as normal subscription) ' + 'with a\n' + 'key that is constructed from the slice list, as follows. If ' + 'the slice\n' + 'list contains at least one comma, the key is a tuple ' + 'containing the\n' + 'conversion of the slice items; otherwise, the conversion of ' + 'the lone\n' + 'slice item is the key. The conversion of a slice item that is ' + 'an\n' + 'expression is that expression. The conversion of a proper ' + 'slice is a\n' + 'slice object (see section *The standard type hierarchy*) ' + 'whose\n' + '"start", "stop" and "step" attributes are the values of the\n' + 'expressions given as lower bound, upper bound and stride,\n' + 'respectively, substituting "None" for missing expressions.\n', + 'specialattrs': '\n' + 'Special Attributes\n' + '******************\n' + '\n' + 'The implementation adds a few special read-only attributes ' + 'to several\n' + 'object types, where they are relevant. Some of these are ' + 'not reported\n' + 'by the "dir()" built-in function.\n' + '\n' + 'object.__dict__\n' + '\n' + ' A dictionary or other mapping object used to store an ' + "object's\n" + ' (writable) attributes.\n' + '\n' + 'instance.__class__\n' + '\n' + ' The class to which a class instance belongs.\n' + '\n' + 'class.__bases__\n' + '\n' + ' The tuple of base classes of a class object.\n' + '\n' + 'class.__name__\n' + '\n' + ' The name of the class or type.\n' + '\n' + 'class.__qualname__\n' + '\n' + ' The *qualified name* of the class or type.\n' + '\n' + ' New in version 3.3.\n' + '\n' + 'class.__mro__\n' + '\n' + ' This attribute is a tuple of classes that are ' + 'considered when\n' + ' looking for base classes during method resolution.\n' + '\n' + 'class.mro()\n' + '\n' + ' This method can be overridden by a metaclass to ' + 'customize the\n' + ' method resolution order for its instances. It is ' + 'called at class\n' + ' instantiation, and its result is stored in "__mro__".\n' + '\n' + 'class.__subclasses__()\n' + '\n' + ' Each class keeps a list of weak references to its ' + 'immediate\n' + ' subclasses. This method returns a list of all those ' + 'references\n' + ' still alive. Example:\n' + '\n' + ' >>> int.__subclasses__()\n' + " []\n" + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] Additional information on these special methods may be ' + 'found\n' + ' in the Python Reference Manual (*Basic ' + 'customization*).\n' + '\n' + '[2] As a consequence, the list "[1, 2]" is considered ' + 'equal to\n' + ' "[1.0, 2.0]", and similarly for tuples.\n' + '\n' + "[3] They must have since the parser can't tell the type of " + 'the\n' + ' operands.\n' + '\n' + '[4] Cased characters are those with general category ' + 'property\n' + ' being one of "Lu" (Letter, uppercase), "Ll" (Letter, ' + 'lowercase),\n' + ' or "Lt" (Letter, titlecase).\n' + '\n' + '[5] To format only a tuple you should therefore provide a\n' + ' singleton tuple whose only element is the tuple to be ' + 'formatted.\n', + 'specialnames': '\n' + 'Special method names\n' + '********************\n' + '\n' + 'A class can implement certain operations that are invoked ' + 'by special\n' + 'syntax (such as arithmetic operations or subscripting and ' + 'slicing) by\n' + "defining methods with special names. This is Python's " + 'approach to\n' + '*operator overloading*, allowing classes to define their ' + 'own behavior\n' + 'with respect to language operators. For instance, if a ' + 'class defines\n' + 'a method named "__getitem__()", and "x" is an instance of ' + 'this class,\n' + 'then "x[i]" is roughly equivalent to ' + '"type(x).__getitem__(x, i)".\n' + 'Except where mentioned, attempts to execute an operation ' + 'raise an\n' + 'exception when no appropriate method is defined ' + '(typically\n' + '"AttributeError" or "TypeError").\n' + '\n' + 'When implementing a class that emulates any built-in type, ' + 'it is\n' + 'important that the emulation only be implemented to the ' + 'degree that it\n' + 'makes sense for the object being modelled. For example, ' + 'some\n' + 'sequences may work well with retrieval of individual ' + 'elements, but\n' + 'extracting a slice may not make sense. (One example of ' + 'this is the\n' + '"NodeList" interface in the W3C\'s Document Object ' + 'Model.)\n' + '\n' + '\n' + 'Basic customization\n' + '===================\n' + '\n' + 'object.__new__(cls[, ...])\n' + '\n' + ' Called to create a new instance of class *cls*. ' + '"__new__()" is a\n' + ' static method (special-cased so you need not declare it ' + 'as such)\n' + ' that takes the class of which an instance was requested ' + 'as its\n' + ' first argument. The remaining arguments are those ' + 'passed to the\n' + ' object constructor expression (the call to the class). ' + 'The return\n' + ' value of "__new__()" should be the new object instance ' + '(usually an\n' + ' instance of *cls*).\n' + '\n' + ' Typical implementations create a new instance of the ' + 'class by\n' + ' invoking the superclass\'s "__new__()" method using\n' + ' "super(currentclass, cls).__new__(cls[, ...])" with ' + 'appropriate\n' + ' arguments and then modifying the newly-created instance ' + 'as\n' + ' necessary before returning it.\n' + '\n' + ' If "__new__()" returns an instance of *cls*, then the ' + 'new\n' + ' instance\'s "__init__()" method will be invoked like\n' + ' "__init__(self[, ...])", where *self* is the new ' + 'instance and the\n' + ' remaining arguments are the same as were passed to ' + '"__new__()".\n' + '\n' + ' If "__new__()" does not return an instance of *cls*, ' + 'then the new\n' + ' instance\'s "__init__()" method will not be invoked.\n' + '\n' + ' "__new__()" is intended mainly to allow subclasses of ' + 'immutable\n' + ' types (like int, str, or tuple) to customize instance ' + 'creation. It\n' + ' is also commonly overridden in custom metaclasses in ' + 'order to\n' + ' customize class creation.\n' + '\n' + 'object.__init__(self[, ...])\n' + '\n' + ' Called after the instance has been created (by ' + '"__new__()"), but\n' + ' before it is returned to the caller. The arguments are ' + 'those\n' + ' passed to the class constructor expression. If a base ' + 'class has an\n' + ' "__init__()" method, the derived class\'s "__init__()" ' + 'method, if\n' + ' any, must explicitly call it to ensure proper ' + 'initialization of the\n' + ' base class part of the instance; for example:\n' + ' "BaseClass.__init__(self, [args...])".\n' + '\n' + ' Because "__new__()" and "__init__()" work together in ' + 'constructing\n' + ' objects ("__new__()" to create it, and "__init__()" to ' + 'customise\n' + ' it), no non-"None" value may be returned by ' + '"__init__()"; doing so\n' + ' will cause a "TypeError" to be raised at runtime.\n' + '\n' + 'object.__del__(self)\n' + '\n' + ' Called when the instance is about to be destroyed. ' + 'This is also\n' + ' called a destructor. If a base class has a "__del__()" ' + 'method, the\n' + ' derived class\'s "__del__()" method, if any, must ' + 'explicitly call it\n' + ' to ensure proper deletion of the base class part of the ' + 'instance.\n' + ' Note that it is possible (though not recommended!) for ' + 'the\n' + ' "__del__()" method to postpone destruction of the ' + 'instance by\n' + ' creating a new reference to it. It may then be called ' + 'at a later\n' + ' time when this new reference is deleted. It is not ' + 'guaranteed that\n' + ' "__del__()" methods are called for objects that still ' + 'exist when\n' + ' the interpreter exits.\n' + '\n' + ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' + 'the former\n' + ' decrements the reference count for "x" by one, and ' + 'the latter is\n' + ' only called when "x"\'s reference count reaches ' + 'zero. Some common\n' + ' situations that may prevent the reference count of an ' + 'object from\n' + ' going to zero include: circular references between ' + 'objects (e.g.,\n' + ' a doubly-linked list or a tree data structure with ' + 'parent and\n' + ' child pointers); a reference to the object on the ' + 'stack frame of\n' + ' a function that caught an exception (the traceback ' + 'stored in\n' + ' "sys.exc_info()[2]" keeps the stack frame alive); or ' + 'a reference\n' + ' to the object on the stack frame that raised an ' + 'unhandled\n' + ' exception in interactive mode (the traceback stored ' + 'in\n' + ' "sys.last_traceback" keeps the stack frame alive). ' + 'The first\n' + ' situation can only be remedied by explicitly breaking ' + 'the cycles;\n' + ' the second can be resolved by freeing the reference ' + 'to the\n' + ' traceback object when it is no longer useful, and the ' + 'third can\n' + ' be resolved by storing "None" in ' + '"sys.last_traceback". Circular\n' + ' references which are garbage are detected and cleaned ' + 'up when the\n' + " cyclic garbage collector is enabled (it's on by " + 'default). Refer\n' + ' to the documentation for the "gc" module for more ' + 'information\n' + ' about this topic.\n' + '\n' + ' Warning: Due to the precarious circumstances under ' + 'which\n' + ' "__del__()" methods are invoked, exceptions that ' + 'occur during\n' + ' their execution are ignored, and a warning is printed ' + 'to\n' + ' "sys.stderr" instead. Also, when "__del__()" is ' + 'invoked in\n' + ' response to a module being deleted (e.g., when ' + 'execution of the\n' + ' program is done), other globals referenced by the ' + '"__del__()"\n' + ' method may already have been deleted or in the ' + 'process of being\n' + ' torn down (e.g. the import machinery shutting down). ' + 'For this\n' + ' reason, "__del__()" methods should do the absolute ' + 'minimum needed\n' + ' to maintain external invariants. Starting with ' + 'version 1.5,\n' + ' Python guarantees that globals whose name begins with ' + 'a single\n' + ' underscore are deleted from their module before other ' + 'globals are\n' + ' deleted; if no other references to such globals ' + 'exist, this may\n' + ' help in assuring that imported modules are still ' + 'available at the\n' + ' time when the "__del__()" method is called.\n' + '\n' + 'object.__repr__(self)\n' + '\n' + ' Called by the "repr()" built-in function to compute the ' + '"official"\n' + ' string representation of an object. If at all ' + 'possible, this\n' + ' should look like a valid Python expression that could ' + 'be used to\n' + ' recreate an object with the same value (given an ' + 'appropriate\n' + ' environment). If this is not possible, a string of the ' + 'form\n' + ' "<...some useful description...>" should be returned. ' + 'The return\n' + ' value must be a string object. If a class defines ' + '"__repr__()" but\n' + ' not "__str__()", then "__repr__()" is also used when an ' + '"informal"\n' + ' string representation of instances of that class is ' + 'required.\n' + '\n' + ' This is typically used for debugging, so it is ' + 'important that the\n' + ' representation is information-rich and unambiguous.\n' + '\n' + 'object.__str__(self)\n' + '\n' + ' Called by "str(object)" and the built-in functions ' + '"format()" and\n' + ' "print()" to compute the "informal" or nicely printable ' + 'string\n' + ' representation of an object. The return value must be ' + 'a *string*\n' + ' object.\n' + '\n' + ' This method differs from "object.__repr__()" in that ' + 'there is no\n' + ' expectation that "__str__()" return a valid Python ' + 'expression: a\n' + ' more convenient or concise representation can be used.\n' + '\n' + ' The default implementation defined by the built-in type ' + '"object"\n' + ' calls "object.__repr__()".\n' + '\n' + 'object.__bytes__(self)\n' + '\n' + ' Called by "bytes()" to compute a byte-string ' + 'representation of an\n' + ' object. This should return a "bytes" object.\n' + '\n' + 'object.__format__(self, format_spec)\n' + '\n' + ' Called by the "format()" built-in function (and by ' + 'extension, the\n' + ' "str.format()" method of class "str") to produce a ' + '"formatted"\n' + ' string representation of an object. The "format_spec" ' + 'argument is a\n' + ' string that contains a description of the formatting ' + 'options\n' + ' desired. The interpretation of the "format_spec" ' + 'argument is up to\n' + ' the type implementing "__format__()", however most ' + 'classes will\n' + ' either delegate formatting to one of the built-in ' + 'types, or use a\n' + ' similar formatting option syntax.\n' + '\n' + ' See *Format Specification Mini-Language* for a ' + 'description of the\n' + ' standard formatting syntax.\n' + '\n' + ' The return value must be a string object.\n' + '\n' + ' Changed in version 3.4: The __format__ method of ' + '"object" itself\n' + ' raises a "TypeError" if passed any non-empty string.\n' + '\n' + 'object.__lt__(self, other)\n' + 'object.__le__(self, other)\n' + 'object.__eq__(self, other)\n' + 'object.__ne__(self, other)\n' + 'object.__gt__(self, other)\n' + 'object.__ge__(self, other)\n' + '\n' + ' These are the so-called "rich comparison" methods. The\n' + ' correspondence between operator symbols and method ' + 'names is as\n' + ' follows: "xy" calls\n' + ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' + '\n' + ' A rich comparison method may return the singleton ' + '"NotImplemented"\n' + ' if it does not implement the operation for a given pair ' + 'of\n' + ' arguments. By convention, "False" and "True" are ' + 'returned for a\n' + ' successful comparison. However, these methods can ' + 'return any value,\n' + ' so if the comparison operator is used in a Boolean ' + 'context (e.g.,\n' + ' in the condition of an "if" statement), Python will ' + 'call "bool()"\n' + ' on the value to determine if the result is true or ' + 'false.\n' + '\n' + ' By default, "__ne__()" delegates to "__eq__()" and ' + 'inverts the\n' + ' result unless it is "NotImplemented". There are no ' + 'other implied\n' + ' relationships among the comparison operators, for ' + 'example, the\n' + ' truth of "(x.__hash__".\n' + '\n' + ' If a class that does not override "__eq__()" wishes to ' + 'suppress\n' + ' hash support, it should include "__hash__ = None" in ' + 'the class\n' + ' definition. A class which defines its own "__hash__()" ' + 'that\n' + ' explicitly raises a "TypeError" would be incorrectly ' + 'identified as\n' + ' hashable by an "isinstance(obj, collections.Hashable)" ' + 'call.\n' + '\n' + ' Note: By default, the "__hash__()" values of str, bytes ' + 'and\n' + ' datetime objects are "salted" with an unpredictable ' + 'random value.\n' + ' Although they remain constant within an individual ' + 'Python\n' + ' process, they are not predictable between repeated ' + 'invocations of\n' + ' Python.This is intended to provide protection against ' + 'a denial-\n' + ' of-service caused by carefully-chosen inputs that ' + 'exploit the\n' + ' worst case performance of a dict insertion, O(n^2) ' + 'complexity.\n' + ' See ' + 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' + ' details.Changing hash values affects the iteration ' + 'order of\n' + ' dicts, sets and other mappings. Python has never ' + 'made guarantees\n' + ' about this ordering (and it typically varies between ' + '32-bit and\n' + ' 64-bit builds).See also "PYTHONHASHSEED".\n' + '\n' + ' Changed in version 3.3: Hash randomization is enabled ' + 'by default.\n' + '\n' + 'object.__bool__(self)\n' + '\n' + ' Called to implement truth value testing and the ' + 'built-in operation\n' + ' "bool()"; should return "False" or "True". When this ' + 'method is not\n' + ' defined, "__len__()" is called, if it is defined, and ' + 'the object is\n' + ' considered true if its result is nonzero. If a class ' + 'defines\n' + ' neither "__len__()" nor "__bool__()", all its instances ' + 'are\n' + ' considered true.\n' + '\n' + '\n' + 'Customizing attribute access\n' + '============================\n' + '\n' + 'The following methods can be defined to customize the ' + 'meaning of\n' + 'attribute access (use of, assignment to, or deletion of ' + '"x.name") for\n' + 'class instances.\n' + '\n' + 'object.__getattr__(self, name)\n' + '\n' + ' Called when an attribute lookup has not found the ' + 'attribute in the\n' + ' usual places (i.e. it is not an instance attribute nor ' + 'is it found\n' + ' in the class tree for "self"). "name" is the attribute ' + 'name. This\n' + ' method should return the (computed) attribute value or ' + 'raise an\n' + ' "AttributeError" exception.\n' + '\n' + ' Note that if the attribute is found through the normal ' + 'mechanism,\n' + ' "__getattr__()" is not called. (This is an intentional ' + 'asymmetry\n' + ' between "__getattr__()" and "__setattr__()".) This is ' + 'done both for\n' + ' efficiency reasons and because otherwise ' + '"__getattr__()" would have\n' + ' no way to access other attributes of the instance. ' + 'Note that at\n' + ' least for instance variables, you can fake total ' + 'control by not\n' + ' inserting any values in the instance attribute ' + 'dictionary (but\n' + ' instead inserting them in another object). See the\n' + ' "__getattribute__()" method below for a way to actually ' + 'get total\n' + ' control over attribute access.\n' + '\n' + 'object.__getattribute__(self, name)\n' + '\n' + ' Called unconditionally to implement attribute accesses ' + 'for\n' + ' instances of the class. If the class also defines ' + '"__getattr__()",\n' + ' the latter will not be called unless ' + '"__getattribute__()" either\n' + ' calls it explicitly or raises an "AttributeError". This ' + 'method\n' + ' should return the (computed) attribute value or raise ' + 'an\n' + ' "AttributeError" exception. In order to avoid infinite ' + 'recursion in\n' + ' this method, its implementation should always call the ' + 'base class\n' + ' method with the same name to access any attributes it ' + 'needs, for\n' + ' example, "object.__getattribute__(self, name)".\n' + '\n' + ' Note: This method may still be bypassed when looking up ' + 'special\n' + ' methods as the result of implicit invocation via ' + 'language syntax\n' + ' or built-in functions. See *Special method lookup*.\n' + '\n' + 'object.__setattr__(self, name, value)\n' + '\n' + ' Called when an attribute assignment is attempted. This ' + 'is called\n' + ' instead of the normal mechanism (i.e. store the value ' + 'in the\n' + ' instance dictionary). *name* is the attribute name, ' + '*value* is the\n' + ' value to be assigned to it.\n' + '\n' + ' If "__setattr__()" wants to assign to an instance ' + 'attribute, it\n' + ' should call the base class method with the same name, ' + 'for example,\n' + ' "object.__setattr__(self, name, value)".\n' + '\n' + 'object.__delattr__(self, name)\n' + '\n' + ' Like "__setattr__()" but for attribute deletion instead ' + 'of\n' + ' assignment. This should only be implemented if "del ' + 'obj.name" is\n' + ' meaningful for the object.\n' + '\n' + 'object.__dir__(self)\n' + '\n' + ' Called when "dir()" is called on the object. A sequence ' + 'must be\n' + ' returned. "dir()" converts the returned sequence to a ' + 'list and\n' + ' sorts it.\n' + '\n' + '\n' + 'Implementing Descriptors\n' + '------------------------\n' + '\n' + 'The following methods only apply when an instance of the ' + 'class\n' + 'containing the method (a so-called *descriptor* class) ' + 'appears in an\n' + '*owner* class (the descriptor must be in either the ' + "owner's class\n" + 'dictionary or in the class dictionary for one of its ' + 'parents). In the\n' + 'examples below, "the attribute" refers to the attribute ' + 'whose name is\n' + 'the key of the property in the owner class\' "__dict__".\n' + '\n' + 'object.__get__(self, instance, owner)\n' + '\n' + ' Called to get the attribute of the owner class (class ' + 'attribute\n' + ' access) or of an instance of that class (instance ' + 'attribute\n' + ' access). *owner* is always the owner class, while ' + '*instance* is the\n' + ' instance that the attribute was accessed through, or ' + '"None" when\n' + ' the attribute is accessed through the *owner*. This ' + 'method should\n' + ' return the (computed) attribute value or raise an ' + '"AttributeError"\n' + ' exception.\n' + '\n' + 'object.__set__(self, instance, value)\n' + '\n' + ' Called to set the attribute on an instance *instance* ' + 'of the owner\n' + ' class to a new value, *value*.\n' + '\n' + 'object.__delete__(self, instance)\n' + '\n' + ' Called to delete the attribute on an instance ' + '*instance* of the\n' + ' owner class.\n' + '\n' + 'The attribute "__objclass__" is interpreted by the ' + '"inspect" module as\n' + 'specifying the class where this object was defined ' + '(setting this\n' + 'appropriately can assist in runtime introspection of ' + 'dynamic class\n' + 'attributes). For callables, it may indicate that an ' + 'instance of the\n' + 'given type (or a subclass) is expected or required as the ' + 'first\n' + 'positional argument (for example, CPython sets this ' + 'attribute for\n' + 'unbound methods that are implemented in C).\n' + '\n' + '\n' + 'Invoking Descriptors\n' + '--------------------\n' + '\n' + 'In general, a descriptor is an object attribute with ' + '"binding\n' + 'behavior", one whose attribute access has been overridden ' + 'by methods\n' + 'in the descriptor protocol: "__get__()", "__set__()", ' + 'and\n' + '"__delete__()". If any of those methods are defined for an ' + 'object, it\n' + 'is said to be a descriptor.\n' + '\n' + 'The default behavior for attribute access is to get, set, ' + 'or delete\n' + "the attribute from an object's dictionary. For instance, " + '"a.x" has a\n' + 'lookup chain starting with "a.__dict__[\'x\']", then\n' + '"type(a).__dict__[\'x\']", and continuing through the base ' + 'classes of\n' + '"type(a)" excluding metaclasses.\n' + '\n' + 'However, if the looked-up value is an object defining one ' + 'of the\n' + 'descriptor methods, then Python may override the default ' + 'behavior and\n' + 'invoke the descriptor method instead. Where this occurs ' + 'in the\n' + 'precedence chain depends on which descriptor methods were ' + 'defined and\n' + 'how they were called.\n' + '\n' + 'The starting point for descriptor invocation is a binding, ' + '"a.x". How\n' + 'the arguments are assembled depends on "a":\n' + '\n' + 'Direct Call\n' + ' The simplest and least common call is when user code ' + 'directly\n' + ' invokes a descriptor method: "x.__get__(a)".\n' + '\n' + 'Instance Binding\n' + ' If binding to an object instance, "a.x" is transformed ' + 'into the\n' + ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' + '\n' + 'Class Binding\n' + ' If binding to a class, "A.x" is transformed into the ' + 'call:\n' + ' "A.__dict__[\'x\'].__get__(None, A)".\n' + '\n' + 'Super Binding\n' + ' If "a" is an instance of "super", then the binding ' + '"super(B,\n' + ' obj).m()" searches "obj.__class__.__mro__" for the base ' + 'class "A"\n' + ' immediately preceding "B" and then invokes the ' + 'descriptor with the\n' + ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n' + '\n' + 'For instance bindings, the precedence of descriptor ' + 'invocation depends\n' + 'on the which descriptor methods are defined. A descriptor ' + 'can define\n' + 'any combination of "__get__()", "__set__()" and ' + '"__delete__()". If it\n' + 'does not define "__get__()", then accessing the attribute ' + 'will return\n' + 'the descriptor object itself unless there is a value in ' + "the object's\n" + 'instance dictionary. If the descriptor defines ' + '"__set__()" and/or\n' + '"__delete__()", it is a data descriptor; if it defines ' + 'neither, it is\n' + 'a non-data descriptor. Normally, data descriptors define ' + 'both\n' + '"__get__()" and "__set__()", while non-data descriptors ' + 'have just the\n' + '"__get__()" method. Data descriptors with "__set__()" and ' + '"__get__()"\n' + 'defined always override a redefinition in an instance ' + 'dictionary. In\n' + 'contrast, non-data descriptors can be overridden by ' + 'instances.\n' + '\n' + 'Python methods (including "staticmethod()" and ' + '"classmethod()") are\n' + 'implemented as non-data descriptors. Accordingly, ' + 'instances can\n' + 'redefine and override methods. This allows individual ' + 'instances to\n' + 'acquire behaviors that differ from other instances of the ' + 'same class.\n' + '\n' + 'The "property()" function is implemented as a data ' + 'descriptor.\n' + 'Accordingly, instances cannot override the behavior of a ' + 'property.\n' + '\n' + '\n' + '__slots__\n' + '---------\n' + '\n' + 'By default, instances of classes have a dictionary for ' + 'attribute\n' + 'storage. This wastes space for objects having very few ' + 'instance\n' + 'variables. The space consumption can become acute when ' + 'creating large\n' + 'numbers of instances.\n' + '\n' + 'The default can be overridden by defining *__slots__* in a ' + 'class\n' + 'definition. The *__slots__* declaration takes a sequence ' + 'of instance\n' + 'variables and reserves just enough space in each instance ' + 'to hold a\n' + 'value for each variable. Space is saved because ' + '*__dict__* is not\n' + 'created for each instance.\n' + '\n' + 'object.__slots__\n' + '\n' + ' This class variable can be assigned a string, iterable, ' + 'or sequence\n' + ' of strings with variable names used by instances. ' + '*__slots__*\n' + ' reserves space for the declared variables and prevents ' + 'the\n' + ' automatic creation of *__dict__* and *__weakref__* for ' + 'each\n' + ' instance.\n' + '\n' + '\n' + 'Notes on using *__slots__*\n' + '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' + '\n' + '* When inheriting from a class without *__slots__*, the ' + '*__dict__*\n' + ' attribute of that class will always be accessible, so a ' + '*__slots__*\n' + ' definition in the subclass is meaningless.\n' + '\n' + '* Without a *__dict__* variable, instances cannot be ' + 'assigned new\n' + ' variables not listed in the *__slots__* definition. ' + 'Attempts to\n' + ' assign to an unlisted variable name raises ' + '"AttributeError". If\n' + ' dynamic assignment of new variables is desired, then ' + 'add\n' + ' "\'__dict__\'" to the sequence of strings in the ' + '*__slots__*\n' + ' declaration.\n' + '\n' + '* Without a *__weakref__* variable for each instance, ' + 'classes\n' + ' defining *__slots__* do not support weak references to ' + 'its\n' + ' instances. If weak reference support is needed, then ' + 'add\n' + ' "\'__weakref__\'" to the sequence of strings in the ' + '*__slots__*\n' + ' declaration.\n' + '\n' + '* *__slots__* are implemented at the class level by ' + 'creating\n' + ' descriptors (*Implementing Descriptors*) for each ' + 'variable name. As\n' + ' a result, class attributes cannot be used to set default ' + 'values for\n' + ' instance variables defined by *__slots__*; otherwise, ' + 'the class\n' + ' attribute would overwrite the descriptor assignment.\n' + '\n' + '* The action of a *__slots__* declaration is limited to ' + 'the class\n' + ' where it is defined. As a result, subclasses will have ' + 'a *__dict__*\n' + ' unless they also define *__slots__* (which must only ' + 'contain names\n' + ' of any *additional* slots).\n' + '\n' + '* If a class defines a slot also defined in a base class, ' + 'the\n' + ' instance variable defined by the base class slot is ' + 'inaccessible\n' + ' (except by retrieving its descriptor directly from the ' + 'base class).\n' + ' This renders the meaning of the program undefined. In ' + 'the future, a\n' + ' check may be added to prevent this.\n' + '\n' + '* Nonempty *__slots__* does not work for classes derived ' + 'from\n' + ' "variable-length" built-in types such as "int", "bytes" ' + 'and "tuple".\n' + '\n' + '* Any non-string iterable may be assigned to *__slots__*. ' + 'Mappings\n' + ' may also be used; however, in the future, special ' + 'meaning may be\n' + ' assigned to the values corresponding to each key.\n' + '\n' + '* *__class__* assignment works only if both classes have ' + 'the same\n' + ' *__slots__*.\n' + '\n' + '\n' + 'Customizing class creation\n' + '==========================\n' + '\n' + 'By default, classes are constructed using "type()". The ' + 'class body is\n' + 'executed in a new namespace and the class name is bound ' + 'locally to the\n' + 'result of "type(name, bases, namespace)".\n' + '\n' + 'The class creation process can be customised by passing ' + 'the\n' + '"metaclass" keyword argument in the class definition line, ' + 'or by\n' + 'inheriting from an existing class that included such an ' + 'argument. In\n' + 'the following example, both "MyClass" and "MySubclass" are ' + 'instances\n' + 'of "Meta":\n' + '\n' + ' class Meta(type):\n' + ' pass\n' + '\n' + ' class MyClass(metaclass=Meta):\n' + ' pass\n' + '\n' + ' class MySubclass(MyClass):\n' + ' pass\n' + '\n' + 'Any other keyword arguments that are specified in the ' + 'class definition\n' + 'are passed through to all metaclass operations described ' + 'below.\n' + '\n' + 'When a class definition is executed, the following steps ' + 'occur:\n' + '\n' + '* the appropriate metaclass is determined\n' + '\n' + '* the class namespace is prepared\n' + '\n' + '* the class body is executed\n' + '\n' + '* the class object is created\n' + '\n' + '\n' + 'Determining the appropriate metaclass\n' + '-------------------------------------\n' + '\n' + 'The appropriate metaclass for a class definition is ' + 'determined as\n' + 'follows:\n' + '\n' + '* if no bases and no explicit metaclass are given, then ' + '"type()" is\n' + ' used\n' + '\n' + '* if an explicit metaclass is given and it is *not* an ' + 'instance of\n' + ' "type()", then it is used directly as the metaclass\n' + '\n' + '* if an instance of "type()" is given as the explicit ' + 'metaclass, or\n' + ' bases are defined, then the most derived metaclass is ' + 'used\n' + '\n' + 'The most derived metaclass is selected from the explicitly ' + 'specified\n' + 'metaclass (if any) and the metaclasses (i.e. "type(cls)") ' + 'of all\n' + 'specified base classes. The most derived metaclass is one ' + 'which is a\n' + 'subtype of *all* of these candidate metaclasses. If none ' + 'of the\n' + 'candidate metaclasses meets that criterion, then the class ' + 'definition\n' + 'will fail with "TypeError".\n' + '\n' + '\n' + 'Preparing the class namespace\n' + '-----------------------------\n' + '\n' + 'Once the appropriate metaclass has been identified, then ' + 'the class\n' + 'namespace is prepared. If the metaclass has a ' + '"__prepare__" attribute,\n' + 'it is called as "namespace = metaclass.__prepare__(name, ' + 'bases,\n' + '**kwds)" (where the additional keyword arguments, if any, ' + 'come from\n' + 'the class definition).\n' + '\n' + 'If the metaclass has no "__prepare__" attribute, then the ' + 'class\n' + 'namespace is initialised as an empty "dict()" instance.\n' + '\n' + 'See also: **PEP 3115** - Metaclasses in Python 3000\n' + '\n' + ' Introduced the "__prepare__" namespace hook\n' + '\n' + '\n' + 'Executing the class body\n' + '------------------------\n' + '\n' + 'The class body is executed (approximately) as "exec(body, ' + 'globals(),\n' + 'namespace)". The key difference from a normal call to ' + '"exec()" is that\n' + 'lexical scoping allows the class body (including any ' + 'methods) to\n' + 'reference names from the current and outer scopes when the ' + 'class\n' + 'definition occurs inside a function.\n' + '\n' + 'However, even when the class definition occurs inside the ' + 'function,\n' + 'methods defined inside the class still cannot see names ' + 'defined at the\n' + 'class scope. Class variables must be accessed through the ' + 'first\n' + 'parameter of instance or class methods, and cannot be ' + 'accessed at all\n' + 'from static methods.\n' + '\n' + '\n' + 'Creating the class object\n' + '-------------------------\n' + '\n' + 'Once the class namespace has been populated by executing ' + 'the class\n' + 'body, the class object is created by calling ' + '"metaclass(name, bases,\n' + 'namespace, **kwds)" (the additional keywords passed here ' + 'are the same\n' + 'as those passed to "__prepare__").\n' + '\n' + 'This class object is the one that will be referenced by ' + 'the zero-\n' + 'argument form of "super()". "__class__" is an implicit ' + 'closure\n' + 'reference created by the compiler if any methods in a ' + 'class body refer\n' + 'to either "__class__" or "super". This allows the zero ' + 'argument form\n' + 'of "super()" to correctly identify the class being defined ' + 'based on\n' + 'lexical scoping, while the class or instance that was used ' + 'to make the\n' + 'current call is identified based on the first argument ' + 'passed to the\n' + 'method.\n' + '\n' + 'After the class object is created, it is passed to the ' + 'class\n' + 'decorators included in the class definition (if any) and ' + 'the resulting\n' + 'object is bound in the local namespace as the defined ' + 'class.\n' + '\n' + 'See also: **PEP 3135** - New super\n' + '\n' + ' Describes the implicit "__class__" closure reference\n' + '\n' + '\n' + 'Metaclass example\n' + '-----------------\n' + '\n' + 'The potential uses for metaclasses are boundless. Some ' + 'ideas that have\n' + 'been explored include logging, interface checking, ' + 'automatic\n' + 'delegation, automatic property creation, proxies, ' + 'frameworks, and\n' + 'automatic resource locking/synchronization.\n' + '\n' + 'Here is an example of a metaclass that uses an\n' + '"collections.OrderedDict" to remember the order that class ' + 'variables\n' + 'are defined:\n' + '\n' + ' class OrderedClass(type):\n' + '\n' + ' @classmethod\n' + ' def __prepare__(metacls, name, bases, **kwds):\n' + ' return collections.OrderedDict()\n' + '\n' + ' def __new__(cls, name, bases, namespace, **kwds):\n' + ' result = type.__new__(cls, name, bases, ' + 'dict(namespace))\n' + ' result.members = tuple(namespace)\n' + ' return result\n' + '\n' + ' class A(metaclass=OrderedClass):\n' + ' def one(self): pass\n' + ' def two(self): pass\n' + ' def three(self): pass\n' + ' def four(self): pass\n' + '\n' + ' >>> A.members\n' + " ('__module__', 'one', 'two', 'three', 'four')\n" + '\n' + 'When the class definition for *A* gets executed, the ' + 'process begins\n' + 'with calling the metaclass\'s "__prepare__()" method which ' + 'returns an\n' + 'empty "collections.OrderedDict". That mapping records the ' + 'methods and\n' + 'attributes of *A* as they are defined within the body of ' + 'the class\n' + 'statement. Once those definitions are executed, the ' + 'ordered dictionary\n' + 'is fully populated and the metaclass\'s "__new__()" method ' + 'gets\n' + 'invoked. That method builds the new type and it saves the ' + 'ordered\n' + 'dictionary keys in an attribute called "members".\n' + '\n' + '\n' + 'Customizing instance and subclass checks\n' + '========================================\n' + '\n' + 'The following methods are used to override the default ' + 'behavior of the\n' + '"isinstance()" and "issubclass()" built-in functions.\n' + '\n' + 'In particular, the metaclass "abc.ABCMeta" implements ' + 'these methods in\n' + 'order to allow the addition of Abstract Base Classes ' + '(ABCs) as\n' + '"virtual base classes" to any class or type (including ' + 'built-in\n' + 'types), including other ABCs.\n' + '\n' + 'class.__instancecheck__(self, instance)\n' + '\n' + ' Return true if *instance* should be considered a ' + '(direct or\n' + ' indirect) instance of *class*. If defined, called to ' + 'implement\n' + ' "isinstance(instance, class)".\n' + '\n' + 'class.__subclasscheck__(self, subclass)\n' + '\n' + ' Return true if *subclass* should be considered a ' + '(direct or\n' + ' indirect) subclass of *class*. If defined, called to ' + 'implement\n' + ' "issubclass(subclass, class)".\n' + '\n' + 'Note that these methods are looked up on the type ' + '(metaclass) of a\n' + 'class. They cannot be defined as class methods in the ' + 'actual class.\n' + 'This is consistent with the lookup of special methods that ' + 'are called\n' + 'on instances, only in this case the instance is itself a ' + 'class.\n' + '\n' + 'See also: **PEP 3119** - Introducing Abstract Base ' + 'Classes\n' + '\n' + ' Includes the specification for customizing ' + '"isinstance()" and\n' + ' "issubclass()" behavior through "__instancecheck__()" ' + 'and\n' + ' "__subclasscheck__()", with motivation for this ' + 'functionality in\n' + ' the context of adding Abstract Base Classes (see the ' + '"abc"\n' + ' module) to the language.\n' + '\n' + '\n' + 'Emulating callable objects\n' + '==========================\n' + '\n' + 'object.__call__(self[, args...])\n' + '\n' + ' Called when the instance is "called" as a function; if ' + 'this method\n' + ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' + ' "x.__call__(arg1, arg2, ...)".\n' + '\n' + '\n' + 'Emulating container types\n' + '=========================\n' + '\n' + 'The following methods can be defined to implement ' + 'container objects.\n' + 'Containers usually are sequences (such as lists or tuples) ' + 'or mappings\n' + '(like dictionaries), but can represent other containers as ' + 'well. The\n' + 'first set of methods is used either to emulate a sequence ' + 'or to\n' + 'emulate a mapping; the difference is that for a sequence, ' + 'the\n' + 'allowable keys should be the integers *k* for which "0 <= ' + 'k < N" where\n' + '*N* is the length of the sequence, or slice objects, which ' + 'define a\n' + 'range of items. It is also recommended that mappings ' + 'provide the\n' + 'methods "keys()", "values()", "items()", "get()", ' + '"clear()",\n' + '"setdefault()", "pop()", "popitem()", "copy()", and ' + '"update()"\n' + "behaving similar to those for Python's standard dictionary " + 'objects.\n' + 'The "collections" module provides a "MutableMapping" ' + 'abstract base\n' + 'class to help create those methods from a base set of ' + '"__getitem__()",\n' + '"__setitem__()", "__delitem__()", and "keys()". Mutable ' + 'sequences\n' + 'should provide methods "append()", "count()", "index()", ' + '"extend()",\n' + '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' + 'like Python\n' + 'standard list objects. Finally, sequence types should ' + 'implement\n' + 'addition (meaning concatenation) and multiplication ' + '(meaning\n' + 'repetition) by defining the methods "__add__()", ' + '"__radd__()",\n' + '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' + 'described\n' + 'below; they should not define other numerical operators. ' + 'It is\n' + 'recommended that both mappings and sequences implement ' + 'the\n' + '"__contains__()" method to allow efficient use of the "in" ' + 'operator;\n' + 'for mappings, "in" should search the mapping\'s keys; for ' + 'sequences, it\n' + 'should search through the values. It is further ' + 'recommended that both\n' + 'mappings and sequences implement the "__iter__()" method ' + 'to allow\n' + 'efficient iteration through the container; for mappings, ' + '"__iter__()"\n' + 'should be the same as "keys()"; for sequences, it should ' + 'iterate\n' + 'through the values.\n' + '\n' + 'object.__len__(self)\n' + '\n' + ' Called to implement the built-in function "len()". ' + 'Should return\n' + ' the length of the object, an integer ">=" 0. Also, an ' + 'object that\n' + ' doesn\'t define a "__bool__()" method and whose ' + '"__len__()" method\n' + ' returns zero is considered to be false in a Boolean ' + 'context.\n' + '\n' + 'object.__length_hint__(self)\n' + '\n' + ' Called to implement "operator.length_hint()". Should ' + 'return an\n' + ' estimated length for the object (which may be greater ' + 'or less than\n' + ' the actual length). The length must be an integer ">=" ' + '0. This\n' + ' method is purely an optimization and is never required ' + 'for\n' + ' correctness.\n' + '\n' + ' New in version 3.4.\n' + '\n' + 'Note: Slicing is done exclusively with the following three ' + 'methods.\n' + ' A call like\n' + '\n' + ' a[1:2] = b\n' + '\n' + ' is translated to\n' + '\n' + ' a[slice(1, 2, None)] = b\n' + '\n' + ' and so forth. Missing slice items are always filled in ' + 'with "None".\n' + '\n' + 'object.__getitem__(self, key)\n' + '\n' + ' Called to implement evaluation of "self[key]". For ' + 'sequence types,\n' + ' the accepted keys should be integers and slice ' + 'objects. Note that\n' + ' the special interpretation of negative indexes (if the ' + 'class wishes\n' + ' to emulate a sequence type) is up to the ' + '"__getitem__()" method. If\n' + ' *key* is of an inappropriate type, "TypeError" may be ' + 'raised; if of\n' + ' a value outside the set of indexes for the sequence ' + '(after any\n' + ' special interpretation of negative values), ' + '"IndexError" should be\n' + ' raised. For mapping types, if *key* is missing (not in ' + 'the\n' + ' container), "KeyError" should be raised.\n' + '\n' + ' Note: "for" loops expect that an "IndexError" will be ' + 'raised for\n' + ' illegal indexes to allow proper detection of the end ' + 'of the\n' + ' sequence.\n' + '\n' + 'object.__missing__(self, key)\n' + '\n' + ' Called by "dict"."__getitem__()" to implement ' + '"self[key]" for dict\n' + ' subclasses when key is not in the dictionary.\n' + '\n' + 'object.__setitem__(self, key, value)\n' + '\n' + ' Called to implement assignment to "self[key]". Same ' + 'note as for\n' + ' "__getitem__()". This should only be implemented for ' + 'mappings if\n' + ' the objects support changes to the values for keys, or ' + 'if new keys\n' + ' can be added, or for sequences if elements can be ' + 'replaced. The\n' + ' same exceptions should be raised for improper *key* ' + 'values as for\n' + ' the "__getitem__()" method.\n' + '\n' + 'object.__delitem__(self, key)\n' + '\n' + ' Called to implement deletion of "self[key]". Same note ' + 'as for\n' + ' "__getitem__()". This should only be implemented for ' + 'mappings if\n' + ' the objects support removal of keys, or for sequences ' + 'if elements\n' + ' can be removed from the sequence. The same exceptions ' + 'should be\n' + ' raised for improper *key* values as for the ' + '"__getitem__()" method.\n' + '\n' + 'object.__iter__(self)\n' + '\n' + ' This method is called when an iterator is required for ' + 'a container.\n' + ' This method should return a new iterator object that ' + 'can iterate\n' + ' over all the objects in the container. For mappings, ' + 'it should\n' + ' iterate over the keys of the container.\n' + '\n' + ' Iterator objects also need to implement this method; ' + 'they are\n' + ' required to return themselves. For more information on ' + 'iterator\n' + ' objects, see *Iterator Types*.\n' + '\n' + 'object.__reversed__(self)\n' + '\n' + ' Called (if present) by the "reversed()" built-in to ' + 'implement\n' + ' reverse iteration. It should return a new iterator ' + 'object that\n' + ' iterates over all the objects in the container in ' + 'reverse order.\n' + '\n' + ' If the "__reversed__()" method is not provided, the ' + '"reversed()"\n' + ' built-in will fall back to using the sequence protocol ' + '("__len__()"\n' + ' and "__getitem__()"). Objects that support the ' + 'sequence protocol\n' + ' should only provide "__reversed__()" if they can ' + 'provide an\n' + ' implementation that is more efficient than the one ' + 'provided by\n' + ' "reversed()".\n' + '\n' + 'The membership test operators ("in" and "not in") are ' + 'normally\n' + 'implemented as an iteration through a sequence. However, ' + 'container\n' + 'objects can supply the following special method with a ' + 'more efficient\n' + 'implementation, which also does not require the object be ' + 'a sequence.\n' + '\n' + 'object.__contains__(self, item)\n' + '\n' + ' Called to implement membership test operators. Should ' + 'return true\n' + ' if *item* is in *self*, false otherwise. For mapping ' + 'objects, this\n' + ' should consider the keys of the mapping rather than the ' + 'values or\n' + ' the key-item pairs.\n' + '\n' + ' For objects that don\'t define "__contains__()", the ' + 'membership test\n' + ' first tries iteration via "__iter__()", then the old ' + 'sequence\n' + ' iteration protocol via "__getitem__()", see *this ' + 'section in the\n' + ' language reference*.\n' + '\n' + '\n' + 'Emulating numeric types\n' + '=======================\n' + '\n' + 'The following methods can be defined to emulate numeric ' + 'objects.\n' + 'Methods corresponding to operations that are not supported ' + 'by the\n' + 'particular kind of number implemented (e.g., bitwise ' + 'operations for\n' + 'non-integral numbers) should be left undefined.\n' + '\n' + 'object.__add__(self, other)\n' + 'object.__sub__(self, other)\n' + 'object.__mul__(self, other)\n' + 'object.__truediv__(self, other)\n' + 'object.__floordiv__(self, other)\n' + 'object.__mod__(self, other)\n' + 'object.__divmod__(self, other)\n' + 'object.__pow__(self, other[, modulo])\n' + 'object.__lshift__(self, other)\n' + 'object.__rshift__(self, other)\n' + 'object.__and__(self, other)\n' + 'object.__xor__(self, other)\n' + 'object.__or__(self, other)\n' + '\n' + ' These methods are called to implement the binary ' + 'arithmetic\n' + ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' + '"pow()",\n' + ' "**", "<<", ">>", "&", "^", "|"). For instance, to ' + 'evaluate the\n' + ' expression "x + y", where *x* is an instance of a class ' + 'that has an\n' + ' "__add__()" method, "x.__add__(y)" is called. The ' + '"__divmod__()"\n' + ' method should be the equivalent to using ' + '"__floordiv__()" and\n' + ' "__mod__()"; it should not be related to ' + '"__truediv__()". Note\n' + ' that "__pow__()" should be defined to accept an ' + 'optional third\n' + ' argument if the ternary version of the built-in "pow()" ' + 'function is\n' + ' to be supported.\n' + '\n' + ' If one of those methods does not support the operation ' + 'with the\n' + ' supplied arguments, it should return "NotImplemented".\n' + '\n' + 'object.__radd__(self, other)\n' + 'object.__rsub__(self, other)\n' + 'object.__rmul__(self, other)\n' + 'object.__rtruediv__(self, other)\n' + 'object.__rfloordiv__(self, other)\n' + 'object.__rmod__(self, other)\n' + 'object.__rdivmod__(self, other)\n' + 'object.__rpow__(self, other)\n' + 'object.__rlshift__(self, other)\n' + 'object.__rrshift__(self, other)\n' + 'object.__rand__(self, other)\n' + 'object.__rxor__(self, other)\n' + 'object.__ror__(self, other)\n' + '\n' + ' These methods are called to implement the binary ' + 'arithmetic\n' + ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' + '"pow()",\n' + ' "**", "<<", ">>", "&", "^", "|") with reflected ' + '(swapped) operands.\n' + ' These functions are only called if the left operand ' + 'does not\n' + ' support the corresponding operation and the operands ' + 'are of\n' + ' different types. [2] For instance, to evaluate the ' + 'expression "x -\n' + ' y", where *y* is an instance of a class that has an ' + '"__rsub__()"\n' + ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' + 'returns\n' + ' *NotImplemented*.\n' + '\n' + ' Note that ternary "pow()" will not try calling ' + '"__rpow__()" (the\n' + ' coercion rules would become too complicated).\n' + '\n' + " Note: If the right operand's type is a subclass of the " + 'left\n' + " operand's type and that subclass provides the " + 'reflected method\n' + ' for the operation, this method will be called before ' + 'the left\n' + " operand's non-reflected method. This behavior allows " + 'subclasses\n' + " to override their ancestors' operations.\n" + '\n' + 'object.__iadd__(self, other)\n' + 'object.__isub__(self, other)\n' + 'object.__imul__(self, other)\n' + 'object.__itruediv__(self, other)\n' + 'object.__ifloordiv__(self, other)\n' + 'object.__imod__(self, other)\n' + 'object.__ipow__(self, other[, modulo])\n' + 'object.__ilshift__(self, other)\n' + 'object.__irshift__(self, other)\n' + 'object.__iand__(self, other)\n' + 'object.__ixor__(self, other)\n' + 'object.__ior__(self, other)\n' + '\n' + ' These methods are called to implement the augmented ' + 'arithmetic\n' + ' assignments ("+=", "-=", "*=", "/=", "//=", "%=", ' + '"**=", "<<=",\n' + ' ">>=", "&=", "^=", "|="). These methods should attempt ' + 'to do the\n' + ' operation in-place (modifying *self*) and return the ' + 'result (which\n' + ' could be, but does not have to be, *self*). If a ' + 'specific method\n' + ' is not defined, the augmented assignment falls back to ' + 'the normal\n' + ' methods. For instance, if *x* is an instance of a ' + 'class with an\n' + ' "__iadd__()" method, "x += y" is equivalent to "x = ' + 'x.__iadd__(y)"\n' + ' . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are ' + 'considered, as\n' + ' with the evaluation of "x + y". In certain situations, ' + 'augmented\n' + ' assignment can result in unexpected errors (see *Why ' + 'does\n' + " a_tuple[i] += ['item'] raise an exception when the " + 'addition\n' + ' works?*), but this behavior is in fact part of the data ' + 'model.\n' + '\n' + 'object.__neg__(self)\n' + 'object.__pos__(self)\n' + 'object.__abs__(self)\n' + 'object.__invert__(self)\n' + '\n' + ' Called to implement the unary arithmetic operations ' + '("-", "+",\n' + ' "abs()" and "~").\n' + '\n' + 'object.__complex__(self)\n' + 'object.__int__(self)\n' + 'object.__float__(self)\n' + 'object.__round__(self[, n])\n' + '\n' + ' Called to implement the built-in functions "complex()", ' + '"int()",\n' + ' "float()" and "round()". Should return a value of the ' + 'appropriate\n' + ' type.\n' + '\n' + 'object.__index__(self)\n' + '\n' + ' Called to implement "operator.index()", and whenever ' + 'Python needs\n' + ' to losslessly convert the numeric object to an integer ' + 'object (such\n' + ' as in slicing, or in the built-in "bin()", "hex()" and ' + '"oct()"\n' + ' functions). Presence of this method indicates that the ' + 'numeric\n' + ' object is an integer type. Must return an integer.\n' + '\n' + ' Note: In order to have a coherent integer type class, ' + 'when\n' + ' "__index__()" is defined "__int__()" should also be ' + 'defined, and\n' + ' both should return the same value.\n' + '\n' + '\n' + 'With Statement Context Managers\n' + '===============================\n' + '\n' + 'A *context manager* is an object that defines the runtime ' + 'context to\n' + 'be established when executing a "with" statement. The ' + 'context manager\n' + 'handles the entry into, and the exit from, the desired ' + 'runtime context\n' + 'for the execution of the block of code. Context managers ' + 'are normally\n' + 'invoked using the "with" statement (described in section ' + '*The with\n' + 'statement*), but can also be used by directly invoking ' + 'their methods.\n' + '\n' + 'Typical uses of context managers include saving and ' + 'restoring various\n' + 'kinds of global state, locking and unlocking resources, ' + 'closing opened\n' + 'files, etc.\n' + '\n' + 'For more information on context managers, see *Context ' + 'Manager Types*.\n' + '\n' + 'object.__enter__(self)\n' + '\n' + ' Enter the runtime context related to this object. The ' + '"with"\n' + " statement will bind this method's return value to the " + 'target(s)\n' + ' specified in the "as" clause of the statement, if any.\n' + '\n' + 'object.__exit__(self, exc_type, exc_value, traceback)\n' + '\n' + ' Exit the runtime context related to this object. The ' + 'parameters\n' + ' describe the exception that caused the context to be ' + 'exited. If the\n' + ' context was exited without an exception, all three ' + 'arguments will\n' + ' be "None".\n' + '\n' + ' If an exception is supplied, and the method wishes to ' + 'suppress the\n' + ' exception (i.e., prevent it from being propagated), it ' + 'should\n' + ' return a true value. Otherwise, the exception will be ' + 'processed\n' + ' normally upon exit from this method.\n' + '\n' + ' Note that "__exit__()" methods should not reraise the ' + 'passed-in\n' + " exception; this is the caller's responsibility.\n" + '\n' + 'See also: **PEP 0343** - The "with" statement\n' + '\n' + ' The specification, background, and examples for the ' + 'Python "with"\n' + ' statement.\n' + '\n' + '\n' + 'Special method lookup\n' + '=====================\n' + '\n' + 'For custom classes, implicit invocations of special ' + 'methods are only\n' + "guaranteed to work correctly if defined on an object's " + 'type, not in\n' + "the object's instance dictionary. That behaviour is the " + 'reason why\n' + 'the following code raises an exception:\n' + '\n' + ' >>> class C:\n' + ' ... pass\n' + ' ...\n' + ' >>> c = C()\n' + ' >>> c.__len__ = lambda: 5\n' + ' >>> len(c)\n' + ' Traceback (most recent call last):\n' + ' File "", line 1, in \n' + " TypeError: object of type 'C' has no len()\n" + '\n' + 'The rationale behind this behaviour lies with a number of ' + 'special\n' + 'methods such as "__hash__()" and "__repr__()" that are ' + 'implemented by\n' + 'all objects, including type objects. If the implicit ' + 'lookup of these\n' + 'methods used the conventional lookup process, they would ' + 'fail when\n' + 'invoked on the type object itself:\n' + '\n' + ' >>> 1 .__hash__() == hash(1)\n' + ' True\n' + ' >>> int.__hash__() == hash(int)\n' + ' Traceback (most recent call last):\n' + ' File "", line 1, in \n' + " TypeError: descriptor '__hash__' of 'int' object needs " + 'an argument\n' + '\n' + 'Incorrectly attempting to invoke an unbound method of a ' + 'class in this\n' + "way is sometimes referred to as 'metaclass confusion', and " + 'is avoided\n' + 'by bypassing the instance when looking up special ' + 'methods:\n' + '\n' + ' >>> type(1).__hash__(1) == hash(1)\n' + ' True\n' + ' >>> type(int).__hash__(int) == hash(int)\n' + ' True\n' + '\n' + 'In addition to bypassing any instance attributes in the ' + 'interest of\n' + 'correctness, implicit special method lookup generally also ' + 'bypasses\n' + 'the "__getattribute__()" method even of the object\'s ' + 'metaclass:\n' + '\n' + ' >>> class Meta(type):\n' + ' ... def __getattribute__(*args):\n' + ' ... print("Metaclass getattribute invoked")\n' + ' ... return type.__getattribute__(*args)\n' + ' ...\n' + ' >>> class C(object, metaclass=Meta):\n' + ' ... def __len__(self):\n' + ' ... return 10\n' + ' ... def __getattribute__(*args):\n' + ' ... print("Class getattribute invoked")\n' + ' ... return object.__getattribute__(*args)\n' + ' ...\n' + ' >>> c = C()\n' + ' >>> c.__len__() # Explicit lookup via ' + 'instance\n' + ' Class getattribute invoked\n' + ' 10\n' + ' >>> type(c).__len__(c) # Explicit lookup via ' + 'type\n' + ' Metaclass getattribute invoked\n' + ' 10\n' + ' >>> len(c) # Implicit lookup\n' + ' 10\n' + '\n' + 'Bypassing the "__getattribute__()" machinery in this ' + 'fashion provides\n' + 'significant scope for speed optimisations within the ' + 'interpreter, at\n' + 'the cost of some flexibility in the handling of special ' + 'methods (the\n' + 'special method *must* be set on the class object itself in ' + 'order to be\n' + 'consistently invoked by the interpreter).\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + "[1] It *is* possible in some cases to change an object's " + 'type,\n' + ' under certain controlled conditions. It generally ' + "isn't a good\n" + ' idea though, since it can lead to some very strange ' + 'behaviour if\n' + ' it is handled incorrectly.\n' + '\n' + '[2] For operands of the same type, it is assumed that if ' + 'the non-\n' + ' reflected method (such as "__add__()") fails the ' + 'operation is not\n' + ' supported, which is why the reflected method is not ' + 'called.\n', + 'string-methods': '\n' + 'String Methods\n' + '**************\n' + '\n' + 'Strings implement all of the *common* sequence ' + 'operations, along with\n' + 'the additional methods described below.\n' + '\n' + 'Strings also support two styles of string formatting, ' + 'one providing a\n' + 'large degree of flexibility and customization (see ' + '"str.format()",\n' + '*Format String Syntax* and *String Formatting*) and the ' + 'other based on\n' + 'C "printf" style formatting that handles a narrower ' + 'range of types and\n' + 'is slightly harder to use correctly, but is often faster ' + 'for the cases\n' + 'it can handle (*printf-style String Formatting*).\n' + '\n' + 'The *Text Processing Services* section of the standard ' + 'library covers\n' + 'a number of other modules that provide various text ' + 'related utilities\n' + '(including regular expression support in the "re" ' + 'module).\n' + '\n' + 'str.capitalize()\n' + '\n' + ' Return a copy of the string with its first character ' + 'capitalized\n' + ' and the rest lowercased.\n' + '\n' + 'str.casefold()\n' + '\n' + ' Return a casefolded copy of the string. Casefolded ' + 'strings may be\n' + ' used for caseless matching.\n' + '\n' + ' Casefolding is similar to lowercasing but more ' + 'aggressive because\n' + ' it is intended to remove all case distinctions in a ' + 'string. For\n' + ' example, the German lowercase letter "\'ß\'" is ' + 'equivalent to ""ss"".\n' + ' Since it is already lowercase, "lower()" would do ' + 'nothing to "\'ß\'";\n' + ' "casefold()" converts it to ""ss"".\n' + '\n' + ' The casefolding algorithm is described in section ' + '3.13 of the\n' + ' Unicode Standard.\n' + '\n' + ' New in version 3.3.\n' + '\n' + 'str.center(width[, fillchar])\n' + '\n' + ' Return centered in a string of length *width*. ' + 'Padding is done\n' + ' using the specified *fillchar* (default is an ASCII ' + 'space). The\n' + ' original string is returned if *width* is less than ' + 'or equal to\n' + ' "len(s)".\n' + '\n' + 'str.count(sub[, start[, end]])\n' + '\n' + ' Return the number of non-overlapping occurrences of ' + 'substring *sub*\n' + ' in the range [*start*, *end*]. Optional arguments ' + '*start* and\n' + ' *end* are interpreted as in slice notation.\n' + '\n' + 'str.encode(encoding="utf-8", errors="strict")\n' + '\n' + ' Return an encoded version of the string as a bytes ' + 'object. Default\n' + ' encoding is "\'utf-8\'". *errors* may be given to set ' + 'a different\n' + ' error handling scheme. The default for *errors* is ' + '"\'strict\'",\n' + ' meaning that encoding errors raise a "UnicodeError". ' + 'Other possible\n' + ' values are "\'ignore\'", "\'replace\'", ' + '"\'xmlcharrefreplace\'",\n' + ' "\'backslashreplace\'" and any other name registered ' + 'via\n' + ' "codecs.register_error()", see section *Error ' + 'Handlers*. For a list\n' + ' of possible encodings, see section *Standard ' + 'Encodings*.\n' + '\n' + ' Changed in version 3.1: Support for keyword arguments ' + 'added.\n' + '\n' + 'str.endswith(suffix[, start[, end]])\n' + '\n' + ' Return "True" if the string ends with the specified ' + '*suffix*,\n' + ' otherwise return "False". *suffix* can also be a ' + 'tuple of suffixes\n' + ' to look for. With optional *start*, test beginning ' + 'at that\n' + ' position. With optional *end*, stop comparing at ' + 'that position.\n' + '\n' + 'str.expandtabs(tabsize=8)\n' + '\n' + ' Return a copy of the string where all tab characters ' + 'are replaced\n' + ' by one or more spaces, depending on the current ' + 'column and the\n' + ' given tab size. Tab positions occur every *tabsize* ' + 'characters\n' + ' (default is 8, giving tab positions at columns 0, 8, ' + '16 and so on).\n' + ' To expand the string, the current column is set to ' + 'zero and the\n' + ' string is examined character by character. If the ' + 'character is a\n' + ' tab ("\\t"), one or more space characters are ' + 'inserted in the result\n' + ' until the current column is equal to the next tab ' + 'position. (The\n' + ' tab character itself is not copied.) If the ' + 'character is a newline\n' + ' ("\\n") or return ("\\r"), it is copied and the ' + 'current column is\n' + ' reset to zero. Any other character is copied ' + 'unchanged and the\n' + ' current column is incremented by one regardless of ' + 'how the\n' + ' character is represented when printed.\n' + '\n' + " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n" + " '01 012 0123 01234'\n" + " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n" + " '01 012 0123 01234'\n" + '\n' + 'str.find(sub[, start[, end]])\n' + '\n' + ' Return the lowest index in the string where substring ' + '*sub* is\n' + ' found within the slice "s[start:end]". Optional ' + 'arguments *start*\n' + ' and *end* are interpreted as in slice notation. ' + 'Return "-1" if\n' + ' *sub* is not found.\n' + '\n' + ' Note: The "find()" method should be used only if you ' + 'need to know\n' + ' the position of *sub*. To check if *sub* is a ' + 'substring or not,\n' + ' use the "in" operator:\n' + '\n' + " >>> 'Py' in 'Python'\n" + ' True\n' + '\n' + 'str.format(*args, **kwargs)\n' + '\n' + ' Perform a string formatting operation. The string on ' + 'which this\n' + ' method is called can contain literal text or ' + 'replacement fields\n' + ' delimited by braces "{}". Each replacement field ' + 'contains either\n' + ' the numeric index of a positional argument, or the ' + 'name of a\n' + ' keyword argument. Returns a copy of the string where ' + 'each\n' + ' replacement field is replaced with the string value ' + 'of the\n' + ' corresponding argument.\n' + '\n' + ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n' + " 'The sum of 1 + 2 is 3'\n" + '\n' + ' See *Format String Syntax* for a description of the ' + 'various\n' + ' formatting options that can be specified in format ' + 'strings.\n' + '\n' + 'str.format_map(mapping)\n' + '\n' + ' Similar to "str.format(**mapping)", except that ' + '"mapping" is used\n' + ' directly and not copied to a "dict". This is useful ' + 'if for example\n' + ' "mapping" is a dict subclass:\n' + '\n' + ' >>> class Default(dict):\n' + ' ... def __missing__(self, key):\n' + ' ... return key\n' + ' ...\n' + " >>> '{name} was born in " + "{country}'.format_map(Default(name='Guido'))\n" + " 'Guido was born in country'\n" + '\n' + ' New in version 3.2.\n' + '\n' + 'str.index(sub[, start[, end]])\n' + '\n' + ' Like "find()", but raise "ValueError" when the ' + 'substring is not\n' + ' found.\n' + '\n' + 'str.isalnum()\n' + '\n' + ' Return true if all characters in the string are ' + 'alphanumeric and\n' + ' there is at least one character, false otherwise. A ' + 'character "c"\n' + ' is alphanumeric if one of the following returns ' + '"True":\n' + ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or ' + '"c.isnumeric()".\n' + '\n' + 'str.isalpha()\n' + '\n' + ' Return true if all characters in the string are ' + 'alphabetic and\n' + ' there is at least one character, false otherwise. ' + 'Alphabetic\n' + ' characters are those characters defined in the ' + 'Unicode character\n' + ' database as "Letter", i.e., those with general ' + 'category property\n' + ' being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note ' + 'that this is\n' + ' different from the "Alphabetic" property defined in ' + 'the Unicode\n' + ' Standard.\n' + '\n' + 'str.isdecimal()\n' + '\n' + ' Return true if all characters in the string are ' + 'decimal characters\n' + ' and there is at least one character, false otherwise. ' + 'Decimal\n' + ' characters are those from general category "Nd". This ' + 'category\n' + ' includes digit characters, and all characters that ' + 'can be used to\n' + ' form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC ' + 'DIGIT ZERO.\n' + '\n' + 'str.isdigit()\n' + '\n' + ' Return true if all characters in the string are ' + 'digits and there is\n' + ' at least one character, false otherwise. Digits ' + 'include decimal\n' + ' characters and digits that need special handling, ' + 'such as the\n' + ' compatibility superscript digits. Formally, a digit ' + 'is a character\n' + ' that has the property value Numeric_Type=Digit or\n' + ' Numeric_Type=Decimal.\n' + '\n' + 'str.isidentifier()\n' + '\n' + ' Return true if the string is a valid identifier ' + 'according to the\n' + ' language definition, section *Identifiers and ' + 'keywords*.\n' + '\n' + ' Use "keyword.iskeyword()" to test for reserved ' + 'identifiers such as\n' + ' "def" and "class".\n' + '\n' + 'str.islower()\n' + '\n' + ' Return true if all cased characters [4] in the string ' + 'are lowercase\n' + ' and there is at least one cased character, false ' + 'otherwise.\n' + '\n' + 'str.isnumeric()\n' + '\n' + ' Return true if all characters in the string are ' + 'numeric characters,\n' + ' and there is at least one character, false otherwise. ' + 'Numeric\n' + ' characters include digit characters, and all ' + 'characters that have\n' + ' the Unicode numeric value property, e.g. U+2155, ' + 'VULGAR FRACTION\n' + ' ONE FIFTH. Formally, numeric characters are those ' + 'with the\n' + ' property value Numeric_Type=Digit, ' + 'Numeric_Type=Decimal or\n' + ' Numeric_Type=Numeric.\n' + '\n' + 'str.isprintable()\n' + '\n' + ' Return true if all characters in the string are ' + 'printable or the\n' + ' string is empty, false otherwise. Nonprintable ' + 'characters are\n' + ' those characters defined in the Unicode character ' + 'database as\n' + ' "Other" or "Separator", excepting the ASCII space ' + '(0x20) which is\n' + ' considered printable. (Note that printable ' + 'characters in this\n' + ' context are those which should not be escaped when ' + '"repr()" is\n' + ' invoked on a string. It has no bearing on the ' + 'handling of strings\n' + ' written to "sys.stdout" or "sys.stderr".)\n' + '\n' + 'str.isspace()\n' + '\n' + ' Return true if there are only whitespace characters ' + 'in the string\n' + ' and there is at least one character, false ' + 'otherwise. Whitespace\n' + ' characters are those characters defined in the ' + 'Unicode character\n' + ' database as "Other" or "Separator" and those with ' + 'bidirectional\n' + ' property being one of "WS", "B", or "S".\n' + '\n' + 'str.istitle()\n' + '\n' + ' Return true if the string is a titlecased string and ' + 'there is at\n' + ' least one character, for example uppercase characters ' + 'may only\n' + ' follow uncased characters and lowercase characters ' + 'only cased ones.\n' + ' Return false otherwise.\n' + '\n' + 'str.isupper()\n' + '\n' + ' Return true if all cased characters [4] in the string ' + 'are uppercase\n' + ' and there is at least one cased character, false ' + 'otherwise.\n' + '\n' + 'str.join(iterable)\n' + '\n' + ' Return a string which is the concatenation of the ' + 'strings in the\n' + ' *iterable* *iterable*. A "TypeError" will be raised ' + 'if there are\n' + ' any non-string values in *iterable*, including ' + '"bytes" objects.\n' + ' The separator between elements is the string ' + 'providing this method.\n' + '\n' + 'str.ljust(width[, fillchar])\n' + '\n' + ' Return the string left justified in a string of ' + 'length *width*.\n' + ' Padding is done using the specified *fillchar* ' + '(default is an ASCII\n' + ' space). The original string is returned if *width* is ' + 'less than or\n' + ' equal to "len(s)".\n' + '\n' + 'str.lower()\n' + '\n' + ' Return a copy of the string with all the cased ' + 'characters [4]\n' + ' converted to lowercase.\n' + '\n' + ' The lowercasing algorithm used is described in ' + 'section 3.13 of the\n' + ' Unicode Standard.\n' + '\n' + 'str.lstrip([chars])\n' + '\n' + ' Return a copy of the string with leading characters ' + 'removed. The\n' + ' *chars* argument is a string specifying the set of ' + 'characters to be\n' + ' removed. If omitted or "None", the *chars* argument ' + 'defaults to\n' + ' removing whitespace. The *chars* argument is not a ' + 'prefix; rather,\n' + ' all combinations of its values are stripped:\n' + '\n' + " >>> ' spacious '.lstrip()\n" + " 'spacious '\n" + " >>> 'www.example.com'.lstrip('cmowz.')\n" + " 'example.com'\n" + '\n' + 'static str.maketrans(x[, y[, z]])\n' + '\n' + ' This static method returns a translation table usable ' + 'for\n' + ' "str.translate()".\n' + '\n' + ' If there is only one argument, it must be a ' + 'dictionary mapping\n' + ' Unicode ordinals (integers) or characters (strings of ' + 'length 1) to\n' + ' Unicode ordinals, strings (of arbitrary lengths) or ' + 'None.\n' + ' Character keys will then be converted to ordinals.\n' + '\n' + ' If there are two arguments, they must be strings of ' + 'equal length,\n' + ' and in the resulting dictionary, each character in x ' + 'will be mapped\n' + ' to the character at the same position in y. If there ' + 'is a third\n' + ' argument, it must be a string, whose characters will ' + 'be mapped to\n' + ' None in the result.\n' + '\n' + 'str.partition(sep)\n' + '\n' + ' Split the string at the first occurrence of *sep*, ' + 'and return a\n' + ' 3-tuple containing the part before the separator, the ' + 'separator\n' + ' itself, and the part after the separator. If the ' + 'separator is not\n' + ' found, return a 3-tuple containing the string itself, ' + 'followed by\n' + ' two empty strings.\n' + '\n' + 'str.replace(old, new[, count])\n' + '\n' + ' Return a copy of the string with all occurrences of ' + 'substring *old*\n' + ' replaced by *new*. If the optional argument *count* ' + 'is given, only\n' + ' the first *count* occurrences are replaced.\n' + '\n' + 'str.rfind(sub[, start[, end]])\n' + '\n' + ' Return the highest index in the string where ' + 'substring *sub* is\n' + ' found, such that *sub* is contained within ' + '"s[start:end]".\n' + ' Optional arguments *start* and *end* are interpreted ' + 'as in slice\n' + ' notation. Return "-1" on failure.\n' + '\n' + 'str.rindex(sub[, start[, end]])\n' + '\n' + ' Like "rfind()" but raises "ValueError" when the ' + 'substring *sub* is\n' + ' not found.\n' + '\n' + 'str.rjust(width[, fillchar])\n' + '\n' + ' Return the string right justified in a string of ' + 'length *width*.\n' + ' Padding is done using the specified *fillchar* ' + '(default is an ASCII\n' + ' space). The original string is returned if *width* is ' + 'less than or\n' + ' equal to "len(s)".\n' + '\n' + 'str.rpartition(sep)\n' + '\n' + ' Split the string at the last occurrence of *sep*, and ' + 'return a\n' + ' 3-tuple containing the part before the separator, the ' + 'separator\n' + ' itself, and the part after the separator. If the ' + 'separator is not\n' + ' found, return a 3-tuple containing two empty strings, ' + 'followed by\n' + ' the string itself.\n' + '\n' + 'str.rsplit(sep=None, maxsplit=-1)\n' + '\n' + ' Return a list of the words in the string, using *sep* ' + 'as the\n' + ' delimiter string. If *maxsplit* is given, at most ' + '*maxsplit* splits\n' + ' are done, the *rightmost* ones. If *sep* is not ' + 'specified or\n' + ' "None", any whitespace string is a separator. Except ' + 'for splitting\n' + ' from the right, "rsplit()" behaves like "split()" ' + 'which is\n' + ' described in detail below.\n' + '\n' + 'str.rstrip([chars])\n' + '\n' + ' Return a copy of the string with trailing characters ' + 'removed. The\n' + ' *chars* argument is a string specifying the set of ' + 'characters to be\n' + ' removed. If omitted or "None", the *chars* argument ' + 'defaults to\n' + ' removing whitespace. The *chars* argument is not a ' + 'suffix; rather,\n' + ' all combinations of its values are stripped:\n' + '\n' + " >>> ' spacious '.rstrip()\n" + " ' spacious'\n" + " >>> 'mississippi'.rstrip('ipz')\n" + " 'mississ'\n" + '\n' + 'str.split(sep=None, maxsplit=-1)\n' + '\n' + ' Return a list of the words in the string, using *sep* ' + 'as the\n' + ' delimiter string. If *maxsplit* is given, at most ' + '*maxsplit*\n' + ' splits are done (thus, the list will have at most ' + '"maxsplit+1"\n' + ' elements). If *maxsplit* is not specified or "-1", ' + 'then there is\n' + ' no limit on the number of splits (all possible splits ' + 'are made).\n' + '\n' + ' If *sep* is given, consecutive delimiters are not ' + 'grouped together\n' + ' and are deemed to delimit empty strings (for ' + 'example,\n' + ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', ' + '\'2\']"). The *sep* argument\n' + ' may consist of multiple characters (for example,\n' + ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', ' + '\'3\']"). Splitting an\n' + ' empty string with a specified separator returns ' + '"[\'\']".\n' + '\n' + ' For example:\n' + '\n' + " >>> '1,2,3'.split(',')\n" + " ['1', '2', '3']\n" + " >>> '1,2,3'.split(',', maxsplit=1)\n" + " ['1', '2,3']\n" + " >>> '1,2,,3,'.split(',')\n" + " ['1', '2', '', '3', '']\n" + '\n' + ' If *sep* is not specified or is "None", a different ' + 'splitting\n' + ' algorithm is applied: runs of consecutive whitespace ' + 'are regarded\n' + ' as a single separator, and the result will contain no ' + 'empty strings\n' + ' at the start or end if the string has leading or ' + 'trailing\n' + ' whitespace. Consequently, splitting an empty string ' + 'or a string\n' + ' consisting of just whitespace with a "None" separator ' + 'returns "[]".\n' + '\n' + ' For example:\n' + '\n' + " >>> '1 2 3'.split()\n" + " ['1', '2', '3']\n" + " >>> '1 2 3'.split(maxsplit=1)\n" + " ['1', '2 3']\n" + " >>> ' 1 2 3 '.split()\n" + " ['1', '2', '3']\n" + '\n' + 'str.splitlines([keepends])\n' + '\n' + ' Return a list of the lines in the string, breaking at ' + 'line\n' + ' boundaries. Line breaks are not included in the ' + 'resulting list\n' + ' unless *keepends* is given and true.\n' + '\n' + ' This method splits on the following line boundaries. ' + 'In\n' + ' particular, the boundaries are a superset of ' + '*universal newlines*.\n' + '\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | Representation | ' + 'Description |\n' + ' ' + '+=========================+===============================+\n' + ' | "\\n" | Line ' + 'Feed |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\r" | Carriage ' + 'Return |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\r\\n" | Carriage Return + Line ' + 'Feed |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\v" or "\\x0b" | Line ' + 'Tabulation |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\f" or "\\x0c" | Form ' + 'Feed |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\x1c" | File ' + 'Separator |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\x1d" | Group ' + 'Separator |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\x1e" | Record ' + 'Separator |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\x85" | Next Line (C1 Control ' + 'Code) |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\u2028" | Line ' + 'Separator |\n' + ' ' + '+-------------------------+-------------------------------+\n' + ' | "\\u2029" | Paragraph ' + 'Separator |\n' + ' ' + '+-------------------------+-------------------------------+\n' + '\n' + ' Changed in version 3.2: "\\v" and "\\f" added to list ' + 'of line\n' + ' boundaries.\n' + '\n' + ' For example:\n' + '\n' + " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" + " ['ab c', '', 'de fg', 'kl']\n" + " >>> 'ab c\\n\\nde " + "fg\\rkl\\r\\n'.splitlines(keepends=True)\n" + " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" + '\n' + ' Unlike "split()" when a delimiter string *sep* is ' + 'given, this\n' + ' method returns an empty list for the empty string, ' + 'and a terminal\n' + ' line break does not result in an extra line:\n' + '\n' + ' >>> "".splitlines()\n' + ' []\n' + ' >>> "One line\\n".splitlines()\n' + " ['One line']\n" + '\n' + ' For comparison, "split(\'\\n\')" gives:\n' + '\n' + " >>> ''.split('\\n')\n" + " ['']\n" + " >>> 'Two lines\\n'.split('\\n')\n" + " ['Two lines', '']\n" + '\n' + 'str.startswith(prefix[, start[, end]])\n' + '\n' + ' Return "True" if string starts with the *prefix*, ' + 'otherwise return\n' + ' "False". *prefix* can also be a tuple of prefixes to ' + 'look for.\n' + ' With optional *start*, test string beginning at that ' + 'position.\n' + ' With optional *end*, stop comparing string at that ' + 'position.\n' + '\n' + 'str.strip([chars])\n' + '\n' + ' Return a copy of the string with the leading and ' + 'trailing\n' + ' characters removed. The *chars* argument is a string ' + 'specifying the\n' + ' set of characters to be removed. If omitted or ' + '"None", the *chars*\n' + ' argument defaults to removing whitespace. The *chars* ' + 'argument is\n' + ' not a prefix or suffix; rather, all combinations of ' + 'its values are\n' + ' stripped:\n' + '\n' + " >>> ' spacious '.strip()\n" + " 'spacious'\n" + " >>> 'www.example.com'.strip('cmowz.')\n" + " 'example'\n" + '\n' + 'str.swapcase()\n' + '\n' + ' Return a copy of the string with uppercase characters ' + 'converted to\n' + ' lowercase and vice versa. Note that it is not ' + 'necessarily true that\n' + ' "s.swapcase().swapcase() == s".\n' + '\n' + 'str.title()\n' + '\n' + ' Return a titlecased version of the string where words ' + 'start with an\n' + ' uppercase character and the remaining characters are ' + 'lowercase.\n' + '\n' + ' For example:\n' + '\n' + " >>> 'Hello world'.title()\n" + " 'Hello World'\n" + '\n' + ' The algorithm uses a simple language-independent ' + 'definition of a\n' + ' word as groups of consecutive letters. The ' + 'definition works in\n' + ' many contexts but it means that apostrophes in ' + 'contractions and\n' + ' possessives form word boundaries, which may not be ' + 'the desired\n' + ' result:\n' + '\n' + ' >>> "they\'re bill\'s friends from the ' + 'UK".title()\n' + ' "They\'Re Bill\'S Friends From The Uk"\n' + '\n' + ' A workaround for apostrophes can be constructed using ' + 'regular\n' + ' expressions:\n' + '\n' + ' >>> import re\n' + ' >>> def titlecase(s):\n' + ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' + ' ... lambda mo: ' + 'mo.group(0)[0].upper() +\n' + ' ... ' + 'mo.group(0)[1:].lower(),\n' + ' ... s)\n' + ' ...\n' + ' >>> titlecase("they\'re bill\'s friends.")\n' + ' "They\'re Bill\'s Friends."\n' + '\n' + 'str.translate(table)\n' + '\n' + ' Return a copy of the string in which each character ' + 'has been mapped\n' + ' through the given translation table. The table must ' + 'be an object\n' + ' that implements indexing via "__getitem__()", ' + 'typically a *mapping*\n' + ' or *sequence*. When indexed by a Unicode ordinal (an ' + 'integer), the\n' + ' table object can do any of the following: return a ' + 'Unicode ordinal\n' + ' or a string, to map the character to one or more ' + 'other characters;\n' + ' return "None", to delete the character from the ' + 'return string; or\n' + ' raise a "LookupError" exception, to map the character ' + 'to itself.\n' + '\n' + ' You can use "str.maketrans()" to create a translation ' + 'map from\n' + ' character-to-character mappings in different ' + 'formats.\n' + '\n' + ' See also the "codecs" module for a more flexible ' + 'approach to custom\n' + ' character mappings.\n' + '\n' + 'str.upper()\n' + '\n' + ' Return a copy of the string with all the cased ' + 'characters [4]\n' + ' converted to uppercase. Note that ' + '"str.upper().isupper()" might be\n' + ' "False" if "s" contains uncased characters or if the ' + 'Unicode\n' + ' category of the resulting character(s) is not "Lu" ' + '(Letter,\n' + ' uppercase), but e.g. "Lt" (Letter, titlecase).\n' + '\n' + ' The uppercasing algorithm used is described in ' + 'section 3.13 of the\n' + ' Unicode Standard.\n' + '\n' + 'str.zfill(width)\n' + '\n' + ' Return a copy of the string left filled with ASCII ' + '"\'0\'" digits to\n' + ' make a string of length *width*. A leading sign ' + 'prefix\n' + ' ("\'+\'"/"\'-\'") is handled by inserting the padding ' + '*after* the sign\n' + ' character rather than before. The original string is ' + 'returned if\n' + ' *width* is less than or equal to "len(s)".\n' + '\n' + ' For example:\n' + '\n' + ' >>> "42".zfill(5)\n' + " '00042'\n" + ' >>> "-42".zfill(5)\n' + " '-0042'\n", + 'strings': '\n' + 'String and Bytes literals\n' + '*************************\n' + '\n' + 'String literals are described by the following lexical ' + 'definitions:\n' + '\n' + ' stringliteral ::= [stringprefix](shortstring | ' + 'longstring)\n' + ' stringprefix ::= "r" | "u" | "R" | "U"\n' + ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' ' + 'shortstringitem* \'"\'\n' + ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | ' + '\'"""\' longstringitem* \'"""\'\n' + ' shortstringitem ::= shortstringchar | stringescapeseq\n' + ' longstringitem ::= longstringchar | stringescapeseq\n' + ' shortstringchar ::= \n' + ' longstringchar ::= \n' + ' stringescapeseq ::= "\\" \n' + '\n' + ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n' + ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | ' + '"rb" | "rB" | "Rb" | "RB"\n' + ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' ' + 'shortbytesitem* \'"\'\n' + ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | ' + '\'"""\' longbytesitem* \'"""\'\n' + ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n' + ' longbytesitem ::= longbyteschar | bytesescapeseq\n' + ' shortbyteschar ::= \n' + ' longbyteschar ::= \n' + ' bytesescapeseq ::= "\\" \n' + '\n' + 'One syntactic restriction not indicated by these productions is ' + 'that\n' + 'whitespace is not allowed between the "stringprefix" or ' + '"bytesprefix"\n' + 'and the rest of the literal. The source character set is ' + 'defined by\n' + 'the encoding declaration; it is UTF-8 if no encoding ' + 'declaration is\n' + 'given in the source file; see section *Encoding declarations*.\n' + '\n' + 'In plain English: Both types of literals can be enclosed in ' + 'matching\n' + 'single quotes ("\'") or double quotes ("""). They can also be ' + 'enclosed\n' + 'in matching groups of three single or double quotes (these are\n' + 'generally referred to as *triple-quoted strings*). The ' + 'backslash\n' + '("\\") character is used to escape characters that otherwise ' + 'have a\n' + 'special meaning, such as newline, backslash itself, or the ' + 'quote\n' + 'character.\n' + '\n' + 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; ' + 'they produce\n' + 'an instance of the "bytes" type instead of the "str" type. ' + 'They may\n' + 'only contain ASCII characters; bytes with a numeric value of ' + '128 or\n' + 'greater must be expressed with escapes.\n' + '\n' + 'As of Python 3.3 it is possible again to prefix string literals ' + 'with a\n' + '"u" prefix to simplify maintenance of dual 2.x and 3.x ' + 'codebases.\n' + '\n' + 'Both string and bytes literals may optionally be prefixed with ' + 'a\n' + 'letter "\'r\'" or "\'R\'"; such strings are called *raw ' + 'strings* and treat\n' + 'backslashes as literal characters. As a result, in string ' + 'literals,\n' + '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated ' + 'specially.\n' + "Given that Python 2.x's raw unicode literals behave differently " + 'than\n' + 'Python 3.x\'s the "\'ur\'" syntax is not supported.\n' + '\n' + 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals ' + 'has been\n' + 'added as a synonym of "\'br\'".\n' + '\n' + 'New in version 3.3: Support for the unicode legacy literal\n' + '("u\'value\'") was reintroduced to simplify the maintenance of ' + 'dual\n' + 'Python 2.x and 3.x codebases. See **PEP 414** for more ' + 'information.\n' + '\n' + 'In triple-quoted literals, unescaped newlines and quotes are ' + 'allowed\n' + '(and are retained), except that three unescaped quotes in a ' + 'row\n' + 'terminate the literal. (A "quote" is the character used to ' + 'open the\n' + 'literal, i.e. either "\'" or """.)\n' + '\n' + 'Unless an "\'r\'" or "\'R\'" prefix is present, escape ' + 'sequences in string\n' + 'and bytes literals are interpreted according to rules similar ' + 'to those\n' + 'used by Standard C. The recognized escape sequences are:\n' + '\n' + '+-------------------+-----------------------------------+---------+\n' + '| Escape Sequence | Meaning | ' + 'Notes |\n' + '+===================+===================================+=========+\n' + '| "\\newline" | Backslash and newline ignored ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\\\" | Backslash ("\\") ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\\'" | Single quote ("\'") ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\"" | Double quote (""") ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\a" | ASCII Bell (BEL) ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\b" | ASCII Backspace (BS) ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\f" | ASCII Formfeed (FF) ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\n" | ASCII Linefeed (LF) ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\r" | ASCII Carriage Return (CR) ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\t" | ASCII Horizontal Tab (TAB) ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\v" | ASCII Vertical Tab (VT) ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\ooo" | Character with octal value *ooo* | ' + '(1,3) |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\xhh" | Character with hex value *hh* | ' + '(2,3) |\n' + '+-------------------+-----------------------------------+---------+\n' + '\n' + 'Escape sequences only recognized in string literals are:\n' + '\n' + '+-------------------+-----------------------------------+---------+\n' + '| Escape Sequence | Meaning | ' + 'Notes |\n' + '+===================+===================================+=========+\n' + '| "\\N{name}" | Character named *name* in the | ' + '(4) |\n' + '| | Unicode database ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\uxxxx" | Character with 16-bit hex value | ' + '(5) |\n' + '| | *xxxx* ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' + '(6) |\n' + '| | *xxxxxxxx* ' + '| |\n' + '+-------------------+-----------------------------------+---------+\n' + '\n' + 'Notes:\n' + '\n' + '1. As in Standard C, up to three octal digits are accepted.\n' + '\n' + '2. Unlike in Standard C, exactly two hex digits are required.\n' + '\n' + '3. In a bytes literal, hexadecimal and octal escapes denote ' + 'the\n' + ' byte with the given value. In a string literal, these ' + 'escapes\n' + ' denote a Unicode character with the given value.\n' + '\n' + '4. Changed in version 3.3: Support for name aliases [1] has ' + 'been\n' + ' added.\n' + '\n' + '5. Individual code units which form parts of a surrogate pair ' + 'can\n' + ' be encoded using this escape sequence. Exactly four hex ' + 'digits are\n' + ' required.\n' + '\n' + '6. Any Unicode character can be encoded this way. Exactly ' + 'eight\n' + ' hex digits are required.\n' + '\n' + 'Unlike Standard C, all unrecognized escape sequences are left ' + 'in the\n' + 'string unchanged, i.e., *the backslash is left in the result*. ' + '(This\n' + 'behavior is useful when debugging: if an escape sequence is ' + 'mistyped,\n' + 'the resulting output is more easily recognized as broken.) It ' + 'is also\n' + 'important to note that the escape sequences only recognized in ' + 'string\n' + 'literals fall into the category of unrecognized escapes for ' + 'bytes\n' + 'literals.\n' + '\n' + 'Even in a raw literal, quotes can be escaped with a backslash, ' + 'but the\n' + 'backslash remains in the result; for example, "r"\\""" is a ' + 'valid\n' + 'string literal consisting of two characters: a backslash and a ' + 'double\n' + 'quote; "r"\\"" is not a valid string literal (even a raw string ' + 'cannot\n' + 'end in an odd number of backslashes). Specifically, *a raw ' + 'literal\n' + 'cannot end in a single backslash* (since the backslash would ' + 'escape\n' + 'the following quote character). Note also that a single ' + 'backslash\n' + 'followed by a newline is interpreted as those two characters as ' + 'part\n' + 'of the literal, *not* as a line continuation.\n', + 'subscriptions': '\n' + 'Subscriptions\n' + '*************\n' + '\n' + 'A subscription selects an item of a sequence (string, ' + 'tuple or list)\n' + 'or mapping (dictionary) object:\n' + '\n' + ' subscription ::= primary "[" expression_list "]"\n' + '\n' + 'The primary must evaluate to an object that supports ' + 'subscription\n' + '(lists or dictionaries for example). User-defined ' + 'objects can support\n' + 'subscription by defining a "__getitem__()" method.\n' + '\n' + 'For built-in objects, there are two types of objects that ' + 'support\n' + 'subscription:\n' + '\n' + 'If the primary is a mapping, the expression list must ' + 'evaluate to an\n' + 'object whose value is one of the keys of the mapping, and ' + 'the\n' + 'subscription selects the value in the mapping that ' + 'corresponds to that\n' + 'key. (The expression list is a tuple except if it has ' + 'exactly one\n' + 'item.)\n' + '\n' + 'If the primary is a sequence, the expression (list) must ' + 'evaluate to\n' + 'an integer or a slice (as discussed in the following ' + 'section).\n' + '\n' + 'The formal syntax makes no special provision for negative ' + 'indices in\n' + 'sequences; however, built-in sequences all provide a ' + '"__getitem__()"\n' + 'method that interprets negative indices by adding the ' + 'length of the\n' + 'sequence to the index (so that "x[-1]" selects the last ' + 'item of "x").\n' + 'The resulting value must be a nonnegative integer less ' + 'than the number\n' + 'of items in the sequence, and the subscription selects ' + 'the item whose\n' + 'index is that value (counting from zero). Since the ' + 'support for\n' + "negative indices and slicing occurs in the object's " + '"__getitem__()"\n' + 'method, subclasses overriding this method will need to ' + 'explicitly add\n' + 'that support.\n' + '\n' + "A string's items are characters. A character is not a " + 'separate data\n' + 'type but a string of exactly one character.\n', + 'truth': '\n' + 'Truth Value Testing\n' + '*******************\n' + '\n' + 'Any object can be tested for truth value, for use in an "if" or\n' + '"while" condition or as operand of the Boolean operations below. ' + 'The\n' + 'following values are considered false:\n' + '\n' + '* "None"\n' + '\n' + '* "False"\n' + '\n' + '* zero of any numeric type, for example, "0", "0.0", "0j".\n' + '\n' + '* any empty sequence, for example, "\'\'", "()", "[]".\n' + '\n' + '* any empty mapping, for example, "{}".\n' + '\n' + '* instances of user-defined classes, if the class defines a\n' + ' "__bool__()" or "__len__()" method, when that method returns ' + 'the\n' + ' integer zero or "bool" value "False". [1]\n' + '\n' + 'All other values are considered true --- so objects of many types ' + 'are\n' + 'always true.\n' + '\n' + 'Operations and built-in functions that have a Boolean result ' + 'always\n' + 'return "0" or "False" for false and "1" or "True" for true, ' + 'unless\n' + 'otherwise stated. (Important exception: the Boolean operations ' + '"or"\n' + 'and "and" always return one of their operands.)\n', + 'try': '\n' + 'The "try" statement\n' + '*******************\n' + '\n' + 'The "try" statement specifies exception handlers and/or cleanup ' + 'code\n' + 'for a group of statements:\n' + '\n' + ' try_stmt ::= try1_stmt | try2_stmt\n' + ' try1_stmt ::= "try" ":" suite\n' + ' ("except" [expression ["as" identifier]] ":" ' + 'suite)+\n' + ' ["else" ":" suite]\n' + ' ["finally" ":" suite]\n' + ' try2_stmt ::= "try" ":" suite\n' + ' "finally" ":" suite\n' + '\n' + 'The "except" clause(s) specify one or more exception handlers. When ' + 'no\n' + 'exception occurs in the "try" clause, no exception handler is\n' + 'executed. When an exception occurs in the "try" suite, a search for ' + 'an\n' + 'exception handler is started. This search inspects the except ' + 'clauses\n' + 'in turn until one is found that matches the exception. An ' + 'expression-\n' + 'less except clause, if present, must be last; it matches any\n' + 'exception. For an except clause with an expression, that ' + 'expression\n' + 'is evaluated, and the clause matches the exception if the ' + 'resulting\n' + 'object is "compatible" with the exception. An object is ' + 'compatible\n' + 'with an exception if it is the class or a base class of the ' + 'exception\n' + 'object or a tuple containing an item compatible with the ' + 'exception.\n' + '\n' + 'If no except clause matches the exception, the search for an ' + 'exception\n' + 'handler continues in the surrounding code and on the invocation ' + 'stack.\n' + '[1]\n' + '\n' + 'If the evaluation of an expression in the header of an except ' + 'clause\n' + 'raises an exception, the original search for a handler is canceled ' + 'and\n' + 'a search starts for the new exception in the surrounding code and ' + 'on\n' + 'the call stack (it is treated as if the entire "try" statement ' + 'raised\n' + 'the exception).\n' + '\n' + 'When a matching except clause is found, the exception is assigned ' + 'to\n' + 'the target specified after the "as" keyword in that except clause, ' + 'if\n' + "present, and the except clause's suite is executed. All except\n" + 'clauses must have an executable block. When the end of this block ' + 'is\n' + 'reached, execution continues normally after the entire try ' + 'statement.\n' + '(This means that if two nested handlers exist for the same ' + 'exception,\n' + 'and the exception occurs in the try clause of the inner handler, ' + 'the\n' + 'outer handler will not handle the exception.)\n' + '\n' + 'When an exception has been assigned using "as target", it is ' + 'cleared\n' + 'at the end of the except clause. This is as if\n' + '\n' + ' except E as N:\n' + ' foo\n' + '\n' + 'was translated to\n' + '\n' + ' except E as N:\n' + ' try:\n' + ' foo\n' + ' finally:\n' + ' del N\n' + '\n' + 'This means the exception must be assigned to a different name to ' + 'be\n' + 'able to refer to it after the except clause. Exceptions are ' + 'cleared\n' + 'because with the traceback attached to them, they form a reference\n' + 'cycle with the stack frame, keeping all locals in that frame alive\n' + 'until the next garbage collection occurs.\n' + '\n' + "Before an except clause's suite is executed, details about the\n" + 'exception are stored in the "sys" module and can be accessed via\n' + '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' + 'the\n' + 'exception class, the exception instance and a traceback object ' + '(see\n' + 'section *The standard type hierarchy*) identifying the point in ' + 'the\n' + 'program where the exception occurred. "sys.exc_info()" values are\n' + 'restored to their previous values (before the call) when returning\n' + 'from a function that handled an exception.\n' + '\n' + 'The optional "else" clause is executed if and when control flows ' + 'off\n' + 'the end of the "try" clause. [2] Exceptions in the "else" clause ' + 'are\n' + 'not handled by the preceding "except" clauses.\n' + '\n' + 'If "finally" is present, it specifies a \'cleanup\' handler. The ' + '"try"\n' + 'clause is executed, including any "except" and "else" clauses. If ' + 'an\n' + 'exception occurs in any of the clauses and is not handled, the\n' + 'exception is temporarily saved. The "finally" clause is executed. ' + 'If\n' + 'there is a saved exception it is re-raised at the end of the ' + '"finally"\n' + 'clause. If the "finally" clause raises another exception, the ' + 'saved\n' + 'exception is set as the context of the new exception. If the ' + '"finally"\n' + 'clause executes a "return" or "break" statement, the saved ' + 'exception\n' + 'is discarded:\n' + '\n' + ' >>> def f():\n' + ' ... try:\n' + ' ... 1/0\n' + ' ... finally:\n' + ' ... return 42\n' + ' ...\n' + ' >>> f()\n' + ' 42\n' + '\n' + 'The exception information is not available to the program during\n' + 'execution of the "finally" clause.\n' + '\n' + 'When a "return", "break" or "continue" statement is executed in ' + 'the\n' + '"try" suite of a "try"..."finally" statement, the "finally" clause ' + 'is\n' + 'also executed \'on the way out.\' A "continue" statement is illegal ' + 'in\n' + 'the "finally" clause. (The reason is a problem with the current\n' + 'implementation --- this restriction may be lifted in the future).\n' + '\n' + 'The return value of a function is determined by the last "return"\n' + 'statement executed. Since the "finally" clause always executes, a\n' + '"return" statement executed in the "finally" clause will always be ' + 'the\n' + 'last one executed:\n' + '\n' + ' >>> def foo():\n' + ' ... try:\n' + " ... return 'try'\n" + ' ... finally:\n' + " ... return 'finally'\n" + ' ...\n' + ' >>> foo()\n' + " 'finally'\n" + '\n' + 'Additional information on exceptions can be found in section\n' + '*Exceptions*, and information on using the "raise" statement to\n' + 'generate exceptions may be found in section *The raise statement*.\n', + 'types': '\n' + 'The standard type hierarchy\n' + '***************************\n' + '\n' + 'Below is a list of the types that are built into Python. ' + 'Extension\n' + 'modules (written in C, Java, or other languages, depending on ' + 'the\n' + 'implementation) can define additional types. Future versions of\n' + 'Python may add types to the type hierarchy (e.g., rational ' + 'numbers,\n' + 'efficiently stored arrays of integers, etc.), although such ' + 'additions\n' + 'will often be provided via the standard library instead.\n' + '\n' + 'Some of the type descriptions below contain a paragraph listing\n' + "'special attributes.' These are attributes that provide access " + 'to the\n' + 'implementation and are not intended for general use. Their ' + 'definition\n' + 'may change in the future.\n' + '\n' + 'None\n' + ' This type has a single value. There is a single object with ' + 'this\n' + ' value. This object is accessed through the built-in name ' + '"None". It\n' + ' is used to signify the absence of a value in many situations, ' + 'e.g.,\n' + " it is returned from functions that don't explicitly return\n" + ' anything. Its truth value is false.\n' + '\n' + 'NotImplemented\n' + ' This type has a single value. There is a single object with ' + 'this\n' + ' value. This object is accessed through the built-in name\n' + ' "NotImplemented". Numeric methods and rich comparison methods\n' + ' should return this value if they do not implement the ' + 'operation for\n' + ' the operands provided. (The interpreter will then try the\n' + ' reflected operation, or some other fallback, depending on the\n' + ' operator.) Its truth value is true.\n' + '\n' + ' See *Implementing the arithmetic operations* for more ' + 'details.\n' + '\n' + 'Ellipsis\n' + ' This type has a single value. There is a single object with ' + 'this\n' + ' value. This object is accessed through the literal "..." or ' + 'the\n' + ' built-in name "Ellipsis". Its truth value is true.\n' + '\n' + '"numbers.Number"\n' + ' These are created by numeric literals and returned as results ' + 'by\n' + ' arithmetic operators and arithmetic built-in functions. ' + 'Numeric\n' + ' objects are immutable; once created their value never ' + 'changes.\n' + ' Python numbers are of course strongly related to mathematical\n' + ' numbers, but subject to the limitations of numerical ' + 'representation\n' + ' in computers.\n' + '\n' + ' Python distinguishes between integers, floating point numbers, ' + 'and\n' + ' complex numbers:\n' + '\n' + ' "numbers.Integral"\n' + ' These represent elements from the mathematical set of ' + 'integers\n' + ' (positive and negative).\n' + '\n' + ' There are two types of integers:\n' + '\n' + ' Integers ("int")\n' + '\n' + ' These represent numbers in an unlimited range, subject ' + 'to\n' + ' available (virtual) memory only. For the purpose of ' + 'shift\n' + ' and mask operations, a binary representation is assumed, ' + 'and\n' + " negative numbers are represented in a variant of 2's\n" + ' complement which gives the illusion of an infinite ' + 'string of\n' + ' sign bits extending to the left.\n' + '\n' + ' Booleans ("bool")\n' + ' These represent the truth values False and True. The ' + 'two\n' + ' objects representing the values "False" and "True" are ' + 'the\n' + ' only Boolean objects. The Boolean type is a subtype of ' + 'the\n' + ' integer type, and Boolean values behave like the values ' + '0 and\n' + ' 1, respectively, in almost all contexts, the exception ' + 'being\n' + ' that when converted to a string, the strings ""False"" ' + 'or\n' + ' ""True"" are returned, respectively.\n' + '\n' + ' The rules for integer representation are intended to give ' + 'the\n' + ' most meaningful interpretation of shift and mask ' + 'operations\n' + ' involving negative integers.\n' + '\n' + ' "numbers.Real" ("float")\n' + ' These represent machine-level double precision floating ' + 'point\n' + ' numbers. You are at the mercy of the underlying machine\n' + ' architecture (and C or Java implementation) for the ' + 'accepted\n' + ' range and handling of overflow. Python does not support ' + 'single-\n' + ' precision floating point numbers; the savings in processor ' + 'and\n' + ' memory usage that are usually the reason for using these ' + 'are\n' + ' dwarfed by the overhead of using objects in Python, so ' + 'there is\n' + ' no reason to complicate the language with two kinds of ' + 'floating\n' + ' point numbers.\n' + '\n' + ' "numbers.Complex" ("complex")\n' + ' These represent complex numbers as a pair of machine-level\n' + ' double precision floating point numbers. The same caveats ' + 'apply\n' + ' as for floating point numbers. The real and imaginary parts ' + 'of a\n' + ' complex number "z" can be retrieved through the read-only\n' + ' attributes "z.real" and "z.imag".\n' + '\n' + 'Sequences\n' + ' These represent finite ordered sets indexed by non-negative\n' + ' numbers. The built-in function "len()" returns the number of ' + 'items\n' + ' of a sequence. When the length of a sequence is *n*, the index ' + 'set\n' + ' contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence ' + '*a* is\n' + ' selected by "a[i]".\n' + '\n' + ' Sequences also support slicing: "a[i:j]" selects all items ' + 'with\n' + ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n' + ' expression, a slice is a sequence of the same type. This ' + 'implies\n' + ' that the index set is renumbered so that it starts at 0.\n' + '\n' + ' Some sequences also support "extended slicing" with a third ' + '"step"\n' + ' parameter: "a[i:j:k]" selects all items of *a* with index *x* ' + 'where\n' + ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n' + '\n' + ' Sequences are distinguished according to their mutability:\n' + '\n' + ' Immutable sequences\n' + ' An object of an immutable sequence type cannot change once ' + 'it is\n' + ' created. (If the object contains references to other ' + 'objects,\n' + ' these other objects may be mutable and may be changed; ' + 'however,\n' + ' the collection of objects directly referenced by an ' + 'immutable\n' + ' object cannot change.)\n' + '\n' + ' The following types are immutable sequences:\n' + '\n' + ' Strings\n' + ' A string is a sequence of values that represent Unicode ' + 'code\n' + ' points. All the code points in the range "U+0000 - ' + 'U+10FFFF"\n' + " can be represented in a string. Python doesn't have a " + '"char"\n' + ' type; instead, every code point in the string is ' + 'represented\n' + ' as a string object with length "1". The built-in ' + 'function\n' + ' "ord()" converts a code point from its string form to ' + 'an\n' + ' integer in the range "0 - 10FFFF"; "chr()" converts an\n' + ' integer in the range "0 - 10FFFF" to the corresponding ' + 'length\n' + ' "1" string object. "str.encode()" can be used to convert ' + 'a\n' + ' "str" to "bytes" using the given text encoding, and\n' + ' "bytes.decode()" can be used to achieve the opposite.\n' + '\n' + ' Tuples\n' + ' The items of a tuple are arbitrary Python objects. ' + 'Tuples of\n' + ' two or more items are formed by comma-separated lists ' + 'of\n' + " expressions. A tuple of one item (a 'singleton') can " + 'be\n' + ' formed by affixing a comma to an expression (an ' + 'expression by\n' + ' itself does not create a tuple, since parentheses must ' + 'be\n' + ' usable for grouping of expressions). An empty tuple can ' + 'be\n' + ' formed by an empty pair of parentheses.\n' + '\n' + ' Bytes\n' + ' A bytes object is an immutable array. The items are ' + '8-bit\n' + ' bytes, represented by integers in the range 0 <= x < ' + '256.\n' + ' Bytes literals (like "b\'abc\'") and the built-in ' + 'function\n' + ' "bytes()" can be used to construct bytes objects. ' + 'Also,\n' + ' bytes objects can be decoded to strings via the ' + '"decode()"\n' + ' method.\n' + '\n' + ' Mutable sequences\n' + ' Mutable sequences can be changed after they are created. ' + 'The\n' + ' subscription and slicing notations can be used as the ' + 'target of\n' + ' assignment and "del" (delete) statements.\n' + '\n' + ' There are currently two intrinsic mutable sequence types:\n' + '\n' + ' Lists\n' + ' The items of a list are arbitrary Python objects. Lists ' + 'are\n' + ' formed by placing a comma-separated list of expressions ' + 'in\n' + ' square brackets. (Note that there are no special cases ' + 'needed\n' + ' to form lists of length 0 or 1.)\n' + '\n' + ' Byte Arrays\n' + ' A bytearray object is a mutable array. They are created ' + 'by\n' + ' the built-in "bytearray()" constructor. Aside from ' + 'being\n' + ' mutable (and hence unhashable), byte arrays otherwise ' + 'provide\n' + ' the same interface and functionality as immutable bytes\n' + ' objects.\n' + '\n' + ' The extension module "array" provides an additional example ' + 'of a\n' + ' mutable sequence type, as does the "collections" module.\n' + '\n' + 'Set types\n' + ' These represent unordered, finite sets of unique, immutable\n' + ' objects. As such, they cannot be indexed by any subscript. ' + 'However,\n' + ' they can be iterated over, and the built-in function "len()"\n' + ' returns the number of items in a set. Common uses for sets are ' + 'fast\n' + ' membership testing, removing duplicates from a sequence, and\n' + ' computing mathematical operations such as intersection, ' + 'union,\n' + ' difference, and symmetric difference.\n' + '\n' + ' For set elements, the same immutability rules apply as for\n' + ' dictionary keys. Note that numeric types obey the normal rules ' + 'for\n' + ' numeric comparison: if two numbers compare equal (e.g., "1" ' + 'and\n' + ' "1.0"), only one of them can be contained in a set.\n' + '\n' + ' There are currently two intrinsic set types:\n' + '\n' + ' Sets\n' + ' These represent a mutable set. They are created by the ' + 'built-in\n' + ' "set()" constructor and can be modified afterwards by ' + 'several\n' + ' methods, such as "add()".\n' + '\n' + ' Frozen sets\n' + ' These represent an immutable set. They are created by the\n' + ' built-in "frozenset()" constructor. As a frozenset is ' + 'immutable\n' + ' and *hashable*, it can be used again as an element of ' + 'another\n' + ' set, or as a dictionary key.\n' + '\n' + 'Mappings\n' + ' These represent finite sets of objects indexed by arbitrary ' + 'index\n' + ' sets. The subscript notation "a[k]" selects the item indexed ' + 'by "k"\n' + ' from the mapping "a"; this can be used in expressions and as ' + 'the\n' + ' target of assignments or "del" statements. The built-in ' + 'function\n' + ' "len()" returns the number of items in a mapping.\n' + '\n' + ' There is currently a single intrinsic mapping type:\n' + '\n' + ' Dictionaries\n' + ' These represent finite sets of objects indexed by nearly\n' + ' arbitrary values. The only types of values not acceptable ' + 'as\n' + ' keys are values containing lists or dictionaries or other\n' + ' mutable types that are compared by value rather than by ' + 'object\n' + ' identity, the reason being that the efficient ' + 'implementation of\n' + " dictionaries requires a key's hash value to remain " + 'constant.\n' + ' Numeric types used for keys obey the normal rules for ' + 'numeric\n' + ' comparison: if two numbers compare equal (e.g., "1" and ' + '"1.0")\n' + ' then they can be used interchangeably to index the same\n' + ' dictionary entry.\n' + '\n' + ' Dictionaries are mutable; they can be created by the ' + '"{...}"\n' + ' notation (see section *Dictionary displays*).\n' + '\n' + ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n' + ' additional examples of mapping types, as does the ' + '"collections"\n' + ' module.\n' + '\n' + 'Callable types\n' + ' These are the types to which the function call operation (see\n' + ' section *Calls*) can be applied:\n' + '\n' + ' User-defined functions\n' + ' A user-defined function object is created by a function\n' + ' definition (see section *Function definitions*). It should ' + 'be\n' + ' called with an argument list containing the same number of ' + 'items\n' + " as the function's formal parameter list.\n" + '\n' + ' Special attributes:\n' + '\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | Attribute | ' + 'Meaning | |\n' + ' ' + '+===========================+=================================+=============+\n' + ' | "__doc__" | The function\'s ' + 'documentation | Writable |\n' + ' | | string, or "None" ' + 'if | |\n' + ' | | unavailable; not inherited ' + 'by | |\n' + ' | | ' + 'subclasses | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__name__" | The function\'s ' + 'name | Writable |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__qualname__" | The function\'s *qualified ' + 'name* | Writable |\n' + ' | | New in version ' + '3.3. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__module__" | The name of the module ' + 'the | Writable |\n' + ' | | function was defined in, ' + 'or | |\n' + ' | | "None" if ' + 'unavailable. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__defaults__" | A tuple containing ' + 'default | Writable |\n' + ' | | argument values for ' + 'those | |\n' + ' | | arguments that have ' + 'defaults, | |\n' + ' | | or "None" if no arguments ' + 'have | |\n' + ' | | a default ' + 'value | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__code__" | The code object ' + 'representing | Writable |\n' + ' | | the compiled function ' + 'body. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__globals__" | A reference to the ' + 'dictionary | Read-only |\n' + ' | | that holds the ' + "function's | |\n" + ' | | global variables --- the ' + 'global | |\n' + ' | | namespace of the module ' + 'in | |\n' + ' | | which the function was ' + 'defined. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__dict__" | The namespace ' + 'supporting | Writable |\n' + ' | | arbitrary function ' + 'attributes. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__closure__" | "None" or a tuple of cells ' + 'that | Read-only |\n' + ' | | contain bindings for ' + 'the | |\n' + " | | function's free " + 'variables. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__annotations__" | A dict containing ' + 'annotations | Writable |\n' + ' | | of parameters. The keys of ' + 'the | |\n' + ' | | dict are the parameter ' + 'names, | |\n' + ' | | and "\'return\'" for the ' + 'return | |\n' + ' | | annotation, if ' + 'provided. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + ' | "__kwdefaults__" | A dict containing defaults ' + 'for | Writable |\n' + ' | | keyword-only ' + 'parameters. | |\n' + ' ' + '+---------------------------+---------------------------------+-------------+\n' + '\n' + ' Most of the attributes labelled "Writable" check the type ' + 'of the\n' + ' assigned value.\n' + '\n' + ' Function objects also support getting and setting ' + 'arbitrary\n' + ' attributes, which can be used, for example, to attach ' + 'metadata\n' + ' to functions. Regular attribute dot-notation is used to ' + 'get and\n' + ' set such attributes. *Note that the current implementation ' + 'only\n' + ' supports function attributes on user-defined functions. ' + 'Function\n' + ' attributes on built-in functions may be supported in the\n' + ' future.*\n' + '\n' + " Additional information about a function's definition can " + 'be\n' + ' retrieved from its code object; see the description of ' + 'internal\n' + ' types below.\n' + '\n' + ' Instance methods\n' + ' An instance method object combines a class, a class ' + 'instance and\n' + ' any callable object (normally a user-defined function).\n' + '\n' + ' Special read-only attributes: "__self__" is the class ' + 'instance\n' + ' object, "__func__" is the function object; "__doc__" is ' + 'the\n' + ' method\'s documentation (same as "__func__.__doc__"); ' + '"__name__"\n' + ' is the method name (same as "__func__.__name__"); ' + '"__module__"\n' + ' is the name of the module the method was defined in, or ' + '"None"\n' + ' if unavailable.\n' + '\n' + ' Methods also support accessing (but not setting) the ' + 'arbitrary\n' + ' function attributes on the underlying function object.\n' + '\n' + ' User-defined method objects may be created when getting an\n' + ' attribute of a class (perhaps via an instance of that ' + 'class), if\n' + ' that attribute is a user-defined function object or a ' + 'class\n' + ' method object.\n' + '\n' + ' When an instance method object is created by retrieving a ' + 'user-\n' + ' defined function object from a class via one of its ' + 'instances,\n' + ' its "__self__" attribute is the instance, and the method ' + 'object\n' + ' is said to be bound. The new method\'s "__func__" ' + 'attribute is\n' + ' the original function object.\n' + '\n' + ' When a user-defined method object is created by retrieving\n' + ' another method object from a class or instance, the ' + 'behaviour is\n' + ' the same as for a function object, except that the ' + '"__func__"\n' + ' attribute of the new instance is not the original method ' + 'object\n' + ' but its "__func__" attribute.\n' + '\n' + ' When an instance method object is created by retrieving a ' + 'class\n' + ' method object from a class or instance, its "__self__" ' + 'attribute\n' + ' is the class itself, and its "__func__" attribute is the\n' + ' function object underlying the class method.\n' + '\n' + ' When an instance method object is called, the underlying\n' + ' function ("__func__") is called, inserting the class ' + 'instance\n' + ' ("__self__") in front of the argument list. For instance, ' + 'when\n' + ' "C" is a class which contains a definition for a function ' + '"f()",\n' + ' and "x" is an instance of "C", calling "x.f(1)" is ' + 'equivalent to\n' + ' calling "C.f(x, 1)".\n' + '\n' + ' When an instance method object is derived from a class ' + 'method\n' + ' object, the "class instance" stored in "__self__" will ' + 'actually\n' + ' be the class itself, so that calling either "x.f(1)" or ' + '"C.f(1)"\n' + ' is equivalent to calling "f(C,1)" where "f" is the ' + 'underlying\n' + ' function.\n' + '\n' + ' Note that the transformation from function object to ' + 'instance\n' + ' method object happens each time the attribute is retrieved ' + 'from\n' + ' the instance. In some cases, a fruitful optimization is ' + 'to\n' + ' assign the attribute to a local variable and call that ' + 'local\n' + ' variable. Also notice that this transformation only happens ' + 'for\n' + ' user-defined functions; other callable objects (and all ' + 'non-\n' + ' callable objects) are retrieved without transformation. It ' + 'is\n' + ' also important to note that user-defined functions which ' + 'are\n' + ' attributes of a class instance are not converted to bound\n' + ' methods; this *only* happens when the function is an ' + 'attribute\n' + ' of the class.\n' + '\n' + ' Generator functions\n' + ' A function or method which uses the "yield" statement (see\n' + ' section *The yield statement*) is called a *generator ' + 'function*.\n' + ' Such a function, when called, always returns an iterator ' + 'object\n' + ' which can be used to execute the body of the function: ' + 'calling\n' + ' the iterator\'s "iterator.__next__()" method will cause ' + 'the\n' + ' function to execute until it provides a value using the ' + '"yield"\n' + ' statement. When the function executes a "return" statement ' + 'or\n' + ' falls off the end, a "StopIteration" exception is raised ' + 'and the\n' + ' iterator will have reached the end of the set of values to ' + 'be\n' + ' returned.\n' + '\n' + ' Built-in functions\n' + ' A built-in function object is a wrapper around a C ' + 'function.\n' + ' Examples of built-in functions are "len()" and ' + '"math.sin()"\n' + ' ("math" is a standard built-in module). The number and type ' + 'of\n' + ' the arguments are determined by the C function. Special ' + 'read-\n' + ' only attributes: "__doc__" is the function\'s ' + 'documentation\n' + ' string, or "None" if unavailable; "__name__" is the ' + "function's\n" + ' name; "__self__" is set to "None" (but see the next item);\n' + ' "__module__" is the name of the module the function was ' + 'defined\n' + ' in or "None" if unavailable.\n' + '\n' + ' Built-in methods\n' + ' This is really a different disguise of a built-in function, ' + 'this\n' + ' time containing an object passed to the C function as an\n' + ' implicit extra argument. An example of a built-in method ' + 'is\n' + ' "alist.append()", assuming *alist* is a list object. In ' + 'this\n' + ' case, the special read-only attribute "__self__" is set to ' + 'the\n' + ' object denoted by *alist*.\n' + '\n' + ' Classes\n' + ' Classes are callable. These objects normally act as ' + 'factories\n' + ' for new instances of themselves, but variations are ' + 'possible for\n' + ' class types that override "__new__()". The arguments of ' + 'the\n' + ' call are passed to "__new__()" and, in the typical case, ' + 'to\n' + ' "__init__()" to initialize the new instance.\n' + '\n' + ' Class Instances\n' + ' Instances of arbitrary classes can be made callable by ' + 'defining\n' + ' a "__call__()" method in their class.\n' + '\n' + 'Modules\n' + ' Modules are a basic organizational unit of Python code, and ' + 'are\n' + ' created by the *import system* as invoked either by the ' + '"import"\n' + ' statement (see "import"), or by calling functions such as\n' + ' "importlib.import_module()" and built-in "__import__()". A ' + 'module\n' + ' object has a namespace implemented by a dictionary object ' + '(this is\n' + ' the dictionary referenced by the "__globals__" attribute of\n' + ' functions defined in the module). Attribute references are\n' + ' translated to lookups in this dictionary, e.g., "m.x" is ' + 'equivalent\n' + ' to "m.__dict__["x"]". A module object does not contain the ' + 'code\n' + " object used to initialize the module (since it isn't needed " + 'once\n' + ' the initialization is done).\n' + '\n' + " Attribute assignment updates the module's namespace " + 'dictionary,\n' + ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n' + '\n' + ' Special read-only attribute: "__dict__" is the module\'s ' + 'namespace\n' + ' as a dictionary object.\n' + '\n' + ' **CPython implementation detail:** Because of the way CPython\n' + ' clears module dictionaries, the module dictionary will be ' + 'cleared\n' + ' when the module falls out of scope even if the dictionary ' + 'still has\n' + ' live references. To avoid this, copy the dictionary or keep ' + 'the\n' + ' module around while using its dictionary directly.\n' + '\n' + ' Predefined (writable) attributes: "__name__" is the module\'s ' + 'name;\n' + ' "__doc__" is the module\'s documentation string, or "None" if\n' + ' unavailable; "__file__" is the pathname of the file from which ' + 'the\n' + ' module was loaded, if it was loaded from a file. The ' + '"__file__"\n' + ' attribute may be missing for certain types of modules, such as ' + 'C\n' + ' modules that are statically linked into the interpreter; for\n' + ' extension modules loaded dynamically from a shared library, it ' + 'is\n' + ' the pathname of the shared library file.\n' + '\n' + 'Custom classes\n' + ' Custom class types are typically created by class definitions ' + '(see\n' + ' section *Class definitions*). A class has a namespace ' + 'implemented\n' + ' by a dictionary object. Class attribute references are ' + 'translated\n' + ' to lookups in this dictionary, e.g., "C.x" is translated to\n' + ' "C.__dict__["x"]" (although there are a number of hooks which ' + 'allow\n' + ' for other means of locating attributes). When the attribute ' + 'name is\n' + ' not found there, the attribute search continues in the base\n' + ' classes. This search of the base classes uses the C3 method\n' + ' resolution order which behaves correctly even in the presence ' + 'of\n' + " 'diamond' inheritance structures where there are multiple\n" + ' inheritance paths leading back to a common ancestor. ' + 'Additional\n' + ' details on the C3 MRO used by Python can be found in the\n' + ' documentation accompanying the 2.3 release at\n' + ' https://www.python.org/download/releases/2.3/mro/.\n' + '\n' + ' When a class attribute reference (for class "C", say) would ' + 'yield a\n' + ' class method object, it is transformed into an instance ' + 'method\n' + ' object whose "__self__" attributes is "C". When it would ' + 'yield a\n' + ' static method object, it is transformed into the object ' + 'wrapped by\n' + ' the static method object. See section *Implementing ' + 'Descriptors*\n' + ' for another way in which attributes retrieved from a class ' + 'may\n' + ' differ from those actually contained in its "__dict__".\n' + '\n' + " Class attribute assignments update the class's dictionary, " + 'never\n' + ' the dictionary of a base class.\n' + '\n' + ' A class object can be called (see above) to yield a class ' + 'instance\n' + ' (see below).\n' + '\n' + ' Special attributes: "__name__" is the class name; "__module__" ' + 'is\n' + ' the module name in which the class was defined; "__dict__" is ' + 'the\n' + ' dictionary containing the class\'s namespace; "__bases__" is a ' + 'tuple\n' + ' (possibly empty or a singleton) containing the base classes, ' + 'in the\n' + ' order of their occurrence in the base class list; "__doc__" is ' + 'the\n' + " class's documentation string, or None if undefined.\n" + '\n' + 'Class instances\n' + ' A class instance is created by calling a class object (see ' + 'above).\n' + ' A class instance has a namespace implemented as a dictionary ' + 'which\n' + ' is the first place in which attribute references are ' + 'searched.\n' + " When an attribute is not found there, and the instance's class " + 'has\n' + ' an attribute by that name, the search continues with the ' + 'class\n' + ' attributes. If a class attribute is found that is a ' + 'user-defined\n' + ' function object, it is transformed into an instance method ' + 'object\n' + ' whose "__self__" attribute is the instance. Static method ' + 'and\n' + ' class method objects are also transformed; see above under\n' + ' "Classes". See section *Implementing Descriptors* for another ' + 'way\n' + ' in which attributes of a class retrieved via its instances ' + 'may\n' + " differ from the objects actually stored in the class's " + '"__dict__".\n' + " If no class attribute is found, and the object's class has a\n" + ' "__getattr__()" method, that is called to satisfy the lookup.\n' + '\n' + " Attribute assignments and deletions update the instance's\n" + " dictionary, never a class's dictionary. If the class has a\n" + ' "__setattr__()" or "__delattr__()" method, this is called ' + 'instead\n' + ' of updating the instance dictionary directly.\n' + '\n' + ' Class instances can pretend to be numbers, sequences, or ' + 'mappings\n' + ' if they have methods with certain special names. See section\n' + ' *Special method names*.\n' + '\n' + ' Special attributes: "__dict__" is the attribute dictionary;\n' + ' "__class__" is the instance\'s class.\n' + '\n' + 'I/O objects (also known as file objects)\n' + ' A *file object* represents an open file. Various shortcuts ' + 'are\n' + ' available to create file objects: the "open()" built-in ' + 'function,\n' + ' and also "os.popen()", "os.fdopen()", and the "makefile()" ' + 'method\n' + ' of socket objects (and perhaps by other functions or methods\n' + ' provided by extension modules).\n' + '\n' + ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n' + ' initialized to file objects corresponding to the ' + "interpreter's\n" + ' standard input, output and error streams; they are all open in ' + 'text\n' + ' mode and therefore follow the interface defined by the\n' + ' "io.TextIOBase" abstract class.\n' + '\n' + 'Internal types\n' + ' A few types used internally by the interpreter are exposed to ' + 'the\n' + ' user. Their definitions may change with future versions of ' + 'the\n' + ' interpreter, but they are mentioned here for completeness.\n' + '\n' + ' Code objects\n' + ' Code objects represent *byte-compiled* executable Python ' + 'code,\n' + ' or *bytecode*. The difference between a code object and a\n' + ' function object is that the function object contains an ' + 'explicit\n' + " reference to the function's globals (the module in which it " + 'was\n' + ' defined), while a code object contains no context; also ' + 'the\n' + ' default argument values are stored in the function object, ' + 'not\n' + ' in the code object (because they represent values ' + 'calculated at\n' + ' run-time). Unlike function objects, code objects are ' + 'immutable\n' + ' and contain no references (directly or indirectly) to ' + 'mutable\n' + ' objects.\n' + '\n' + ' Special read-only attributes: "co_name" gives the function ' + 'name;\n' + ' "co_argcount" is the number of positional arguments ' + '(including\n' + ' arguments with default values); "co_nlocals" is the number ' + 'of\n' + ' local variables used by the function (including ' + 'arguments);\n' + ' "co_varnames" is a tuple containing the names of the local\n' + ' variables (starting with the argument names); "co_cellvars" ' + 'is a\n' + ' tuple containing the names of local variables that are\n' + ' referenced by nested functions; "co_freevars" is a tuple\n' + ' containing the names of free variables; "co_code" is a ' + 'string\n' + ' representing the sequence of bytecode instructions; ' + '"co_consts"\n' + ' is a tuple containing the literals used by the bytecode;\n' + ' "co_names" is a tuple containing the names used by the ' + 'bytecode;\n' + ' "co_filename" is the filename from which the code was ' + 'compiled;\n' + ' "co_firstlineno" is the first line number of the function;\n' + ' "co_lnotab" is a string encoding the mapping from bytecode\n' + ' offsets to line numbers (for details see the source code of ' + 'the\n' + ' interpreter); "co_stacksize" is the required stack size\n' + ' (including local variables); "co_flags" is an integer ' + 'encoding a\n' + ' number of flags for the interpreter.\n' + '\n' + ' The following flag bits are defined for "co_flags": bit ' + '"0x04"\n' + ' is set if the function uses the "*arguments" syntax to ' + 'accept an\n' + ' arbitrary number of positional arguments; bit "0x08" is set ' + 'if\n' + ' the function uses the "**keywords" syntax to accept ' + 'arbitrary\n' + ' keyword arguments; bit "0x20" is set if the function is a\n' + ' generator.\n' + '\n' + ' Future feature declarations ("from __future__ import ' + 'division")\n' + ' also use bits in "co_flags" to indicate whether a code ' + 'object\n' + ' was compiled with a particular feature enabled: bit ' + '"0x2000" is\n' + ' set if the function was compiled with future division ' + 'enabled;\n' + ' bits "0x10" and "0x1000" were used in earlier versions of\n' + ' Python.\n' + '\n' + ' Other bits in "co_flags" are reserved for internal use.\n' + '\n' + ' If a code object represents a function, the first item in\n' + ' "co_consts" is the documentation string of the function, ' + 'or\n' + ' "None" if undefined.\n' + '\n' + ' Frame objects\n' + ' Frame objects represent execution frames. They may occur ' + 'in\n' + ' traceback objects (see below).\n' + '\n' + ' Special read-only attributes: "f_back" is to the previous ' + 'stack\n' + ' frame (towards the caller), or "None" if this is the ' + 'bottom\n' + ' stack frame; "f_code" is the code object being executed in ' + 'this\n' + ' frame; "f_locals" is the dictionary used to look up local\n' + ' variables; "f_globals" is used for global variables;\n' + ' "f_builtins" is used for built-in (intrinsic) names; ' + '"f_lasti"\n' + ' gives the precise instruction (this is an index into the\n' + ' bytecode string of the code object).\n' + '\n' + ' Special writable attributes: "f_trace", if not "None", is ' + 'a\n' + ' function called at the start of each source code line (this ' + 'is\n' + ' used by the debugger); "f_lineno" is the current line ' + 'number of\n' + ' the frame --- writing to this from within a trace function ' + 'jumps\n' + ' to the given line (only for the bottom-most frame). A ' + 'debugger\n' + ' can implement a Jump command (aka Set Next Statement) by ' + 'writing\n' + ' to f_lineno.\n' + '\n' + ' Frame objects support one method:\n' + '\n' + ' frame.clear()\n' + '\n' + ' This method clears all references to local variables ' + 'held by\n' + ' the frame. Also, if the frame belonged to a generator, ' + 'the\n' + ' generator is finalized. This helps break reference ' + 'cycles\n' + ' involving frame objects (for example when catching an\n' + ' exception and storing its traceback for later use).\n' + '\n' + ' "RuntimeError" is raised if the frame is currently ' + 'executing.\n' + '\n' + ' New in version 3.4.\n' + '\n' + ' Traceback objects\n' + ' Traceback objects represent a stack trace of an exception. ' + 'A\n' + ' traceback object is created when an exception occurs. When ' + 'the\n' + ' search for an exception handler unwinds the execution ' + 'stack, at\n' + ' each unwound level a traceback object is inserted in front ' + 'of\n' + ' the current traceback. When an exception handler is ' + 'entered,\n' + ' the stack trace is made available to the program. (See ' + 'section\n' + ' *The try statement*.) It is accessible as the third item of ' + 'the\n' + ' tuple returned by "sys.exc_info()". When the program ' + 'contains no\n' + ' suitable handler, the stack trace is written (nicely ' + 'formatted)\n' + ' to the standard error stream; if the interpreter is ' + 'interactive,\n' + ' it is also made available to the user as ' + '"sys.last_traceback".\n' + '\n' + ' Special read-only attributes: "tb_next" is the next level ' + 'in the\n' + ' stack trace (towards the frame where the exception ' + 'occurred), or\n' + ' "None" if there is no next level; "tb_frame" points to the\n' + ' execution frame of the current level; "tb_lineno" gives the ' + 'line\n' + ' number where the exception occurred; "tb_lasti" indicates ' + 'the\n' + ' precise instruction. The line number and last instruction ' + 'in\n' + ' the traceback may differ from the line number of its frame\n' + ' object if the exception occurred in a "try" statement with ' + 'no\n' + ' matching except clause or with a finally clause.\n' + '\n' + ' Slice objects\n' + ' Slice objects are used to represent slices for ' + '"__getitem__()"\n' + ' methods. They are also created by the built-in "slice()"\n' + ' function.\n' + '\n' + ' Special read-only attributes: "start" is the lower bound; ' + '"stop"\n' + ' is the upper bound; "step" is the step value; each is ' + '"None" if\n' + ' omitted. These attributes can have any type.\n' + '\n' + ' Slice objects support one method:\n' + '\n' + ' slice.indices(self, length)\n' + '\n' + ' This method takes a single integer argument *length* ' + 'and\n' + ' computes information about the slice that the slice ' + 'object\n' + ' would describe if applied to a sequence of *length* ' + 'items.\n' + ' It returns a tuple of three integers; respectively these ' + 'are\n' + ' the *start* and *stop* indices and the *step* or stride\n' + ' length of the slice. Missing or out-of-bounds indices ' + 'are\n' + ' handled in a manner consistent with regular slices.\n' + '\n' + ' Static method objects\n' + ' Static method objects provide a way of defeating the\n' + ' transformation of function objects to method objects ' + 'described\n' + ' above. A static method object is a wrapper around any ' + 'other\n' + ' object, usually a user-defined method object. When a ' + 'static\n' + ' method object is retrieved from a class or a class ' + 'instance, the\n' + ' object actually returned is the wrapped object, which is ' + 'not\n' + ' subject to any further transformation. Static method ' + 'objects are\n' + ' not themselves callable, although the objects they wrap ' + 'usually\n' + ' are. Static method objects are created by the built-in\n' + ' "staticmethod()" constructor.\n' + '\n' + ' Class method objects\n' + ' A class method object, like a static method object, is a ' + 'wrapper\n' + ' around another object that alters the way in which that ' + 'object\n' + ' is retrieved from classes and class instances. The ' + 'behaviour of\n' + ' class method objects upon such retrieval is described ' + 'above,\n' + ' under "User-defined methods". Class method objects are ' + 'created\n' + ' by the built-in "classmethod()" constructor.\n', + 'typesfunctions': '\n' + 'Functions\n' + '*********\n' + '\n' + 'Function objects are created by function definitions. ' + 'The only\n' + 'operation on a function object is to call it: ' + '"func(argument-list)".\n' + '\n' + 'There are really two flavors of function objects: ' + 'built-in functions\n' + 'and user-defined functions. Both support the same ' + 'operation (to call\n' + 'the function), but the implementation is different, ' + 'hence the\n' + 'different object types.\n' + '\n' + 'See *Function definitions* for more information.\n', + 'typesmapping': '\n' + 'Mapping Types --- "dict"\n' + '************************\n' + '\n' + 'A *mapping* object maps *hashable* values to arbitrary ' + 'objects.\n' + 'Mappings are mutable objects. There is currently only one ' + 'standard\n' + 'mapping type, the *dictionary*. (For other containers see ' + 'the built-\n' + 'in "list", "set", and "tuple" classes, and the ' + '"collections" module.)\n' + '\n' + "A dictionary's keys are *almost* arbitrary values. Values " + 'that are\n' + 'not *hashable*, that is, values containing lists, ' + 'dictionaries or\n' + 'other mutable types (that are compared by value rather ' + 'than by object\n' + 'identity) may not be used as keys. Numeric types used for ' + 'keys obey\n' + 'the normal rules for numeric comparison: if two numbers ' + 'compare equal\n' + '(such as "1" and "1.0") then they can be used ' + 'interchangeably to index\n' + 'the same dictionary entry. (Note however, that since ' + 'computers store\n' + 'floating-point numbers as approximations it is usually ' + 'unwise to use\n' + 'them as dictionary keys.)\n' + '\n' + 'Dictionaries can be created by placing a comma-separated ' + 'list of "key:\n' + 'value" pairs within braces, for example: "{\'jack\': 4098, ' + "'sjoerd':\n" + '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the ' + '"dict"\n' + 'constructor.\n' + '\n' + 'class class dict(**kwarg)\n' + 'class class dict(mapping, **kwarg)\n' + 'class class dict(iterable, **kwarg)\n' + '\n' + ' Return a new dictionary initialized from an optional ' + 'positional\n' + ' argument and a possibly empty set of keyword ' + 'arguments.\n' + '\n' + ' If no positional argument is given, an empty dictionary ' + 'is created.\n' + ' If a positional argument is given and it is a mapping ' + 'object, a\n' + ' dictionary is created with the same key-value pairs as ' + 'the mapping\n' + ' object. Otherwise, the positional argument must be an ' + '*iterable*\n' + ' object. Each item in the iterable must itself be an ' + 'iterable with\n' + ' exactly two objects. The first object of each item ' + 'becomes a key\n' + ' in the new dictionary, and the second object the ' + 'corresponding\n' + ' value. If a key occurs more than once, the last value ' + 'for that key\n' + ' becomes the corresponding value in the new dictionary.\n' + '\n' + ' If keyword arguments are given, the keyword arguments ' + 'and their\n' + ' values are added to the dictionary created from the ' + 'positional\n' + ' argument. If a key being added is already present, the ' + 'value from\n' + ' the keyword argument replaces the value from the ' + 'positional\n' + ' argument.\n' + '\n' + ' To illustrate, the following examples all return a ' + 'dictionary equal\n' + ' to "{"one": 1, "two": 2, "three": 3}":\n' + '\n' + ' >>> a = dict(one=1, two=2, three=3)\n' + " >>> b = {'one': 1, 'two': 2, 'three': 3}\n" + " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, " + '3]))\n' + " >>> d = dict([('two', 2), ('one', 1), ('three', " + '3)])\n' + " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n" + ' >>> a == b == c == d == e\n' + ' True\n' + '\n' + ' Providing keyword arguments as in the first example ' + 'only works for\n' + ' keys that are valid Python identifiers. Otherwise, any ' + 'valid keys\n' + ' can be used.\n' + '\n' + ' These are the operations that dictionaries support (and ' + 'therefore,\n' + ' custom mapping types should support too):\n' + '\n' + ' len(d)\n' + '\n' + ' Return the number of items in the dictionary *d*.\n' + '\n' + ' d[key]\n' + '\n' + ' Return the item of *d* with key *key*. Raises a ' + '"KeyError" if\n' + ' *key* is not in the map.\n' + '\n' + ' If a subclass of dict defines a method ' + '"__missing__()" and *key*\n' + ' is not present, the "d[key]" operation calls that ' + 'method with\n' + ' the key *key* as argument. The "d[key]" operation ' + 'then returns\n' + ' or raises whatever is returned or raised by the\n' + ' "__missing__(key)" call. No other operations or ' + 'methods invoke\n' + ' "__missing__()". If "__missing__()" is not defined, ' + '"KeyError"\n' + ' is raised. "__missing__()" must be a method; it ' + 'cannot be an\n' + ' instance variable:\n' + '\n' + ' >>> class Counter(dict):\n' + ' ... def __missing__(self, key):\n' + ' ... return 0\n' + ' >>> c = Counter()\n' + " >>> c['red']\n" + ' 0\n' + " >>> c['red'] += 1\n" + " >>> c['red']\n" + ' 1\n' + '\n' + ' The example above shows part of the implementation ' + 'of\n' + ' "collections.Counter". A different "__missing__" ' + 'method is used\n' + ' by "collections.defaultdict".\n' + '\n' + ' d[key] = value\n' + '\n' + ' Set "d[key]" to *value*.\n' + '\n' + ' del d[key]\n' + '\n' + ' Remove "d[key]" from *d*. Raises a "KeyError" if ' + '*key* is not\n' + ' in the map.\n' + '\n' + ' key in d\n' + '\n' + ' Return "True" if *d* has a key *key*, else "False".\n' + '\n' + ' key not in d\n' + '\n' + ' Equivalent to "not key in d".\n' + '\n' + ' iter(d)\n' + '\n' + ' Return an iterator over the keys of the dictionary. ' + 'This is a\n' + ' shortcut for "iter(d.keys())".\n' + '\n' + ' clear()\n' + '\n' + ' Remove all items from the dictionary.\n' + '\n' + ' copy()\n' + '\n' + ' Return a shallow copy of the dictionary.\n' + '\n' + ' classmethod fromkeys(seq[, value])\n' + '\n' + ' Create a new dictionary with keys from *seq* and ' + 'values set to\n' + ' *value*.\n' + '\n' + ' "fromkeys()" is a class method that returns a new ' + 'dictionary.\n' + ' *value* defaults to "None".\n' + '\n' + ' get(key[, default])\n' + '\n' + ' Return the value for *key* if *key* is in the ' + 'dictionary, else\n' + ' *default*. If *default* is not given, it defaults to ' + '"None", so\n' + ' that this method never raises a "KeyError".\n' + '\n' + ' items()\n' + '\n' + ' Return a new view of the dictionary\'s items ("(key, ' + 'value)"\n' + ' pairs). See the *documentation of view objects*.\n' + '\n' + ' keys()\n' + '\n' + " Return a new view of the dictionary's keys. See " + 'the\n' + ' *documentation of view objects*.\n' + '\n' + ' pop(key[, default])\n' + '\n' + ' If *key* is in the dictionary, remove it and return ' + 'its value,\n' + ' else return *default*. If *default* is not given ' + 'and *key* is\n' + ' not in the dictionary, a "KeyError" is raised.\n' + '\n' + ' popitem()\n' + '\n' + ' Remove and return an arbitrary "(key, value)" pair ' + 'from the\n' + ' dictionary.\n' + '\n' + ' "popitem()" is useful to destructively iterate over ' + 'a\n' + ' dictionary, as often used in set algorithms. If the ' + 'dictionary\n' + ' is empty, calling "popitem()" raises a "KeyError".\n' + '\n' + ' setdefault(key[, default])\n' + '\n' + ' If *key* is in the dictionary, return its value. If ' + 'not, insert\n' + ' *key* with a value of *default* and return ' + '*default*. *default*\n' + ' defaults to "None".\n' + '\n' + ' update([other])\n' + '\n' + ' Update the dictionary with the key/value pairs from ' + '*other*,\n' + ' overwriting existing keys. Return "None".\n' + '\n' + ' "update()" accepts either another dictionary object ' + 'or an\n' + ' iterable of key/value pairs (as tuples or other ' + 'iterables of\n' + ' length two). If keyword arguments are specified, ' + 'the dictionary\n' + ' is then updated with those key/value pairs: ' + '"d.update(red=1,\n' + ' blue=2)".\n' + '\n' + ' values()\n' + '\n' + " Return a new view of the dictionary's values. See " + 'the\n' + ' *documentation of view objects*.\n' + '\n' + ' Dictionaries compare equal if and only if they have the ' + 'same "(key,\n' + ' value)" pairs. Order comparisons (\'<\', \'<=\', ' + "'>=', '>') raise\n" + ' "TypeError".\n' + '\n' + 'See also: "types.MappingProxyType" can be used to create a ' + 'read-only\n' + ' view of a "dict".\n' + '\n' + '\n' + 'Dictionary view objects\n' + '=======================\n' + '\n' + 'The objects returned by "dict.keys()", "dict.values()" ' + 'and\n' + '"dict.items()" are *view objects*. They provide a dynamic ' + 'view on the\n' + "dictionary's entries, which means that when the dictionary " + 'changes,\n' + 'the view reflects these changes.\n' + '\n' + 'Dictionary views can be iterated over to yield their ' + 'respective data,\n' + 'and support membership tests:\n' + '\n' + 'len(dictview)\n' + '\n' + ' Return the number of entries in the dictionary.\n' + '\n' + 'iter(dictview)\n' + '\n' + ' Return an iterator over the keys, values or items ' + '(represented as\n' + ' tuples of "(key, value)") in the dictionary.\n' + '\n' + ' Keys and values are iterated over in an arbitrary order ' + 'which is\n' + ' non-random, varies across Python implementations, and ' + 'depends on\n' + " the dictionary's history of insertions and deletions. " + 'If keys,\n' + ' values and items views are iterated over with no ' + 'intervening\n' + ' modifications to the dictionary, the order of items ' + 'will directly\n' + ' correspond. This allows the creation of "(value, key)" ' + 'pairs using\n' + ' "zip()": "pairs = zip(d.values(), d.keys())". Another ' + 'way to\n' + ' create the same list is "pairs = [(v, k) for (k, v) in ' + 'd.items()]".\n' + '\n' + ' Iterating views while adding or deleting entries in the ' + 'dictionary\n' + ' may raise a "RuntimeError" or fail to iterate over all ' + 'entries.\n' + '\n' + 'x in dictview\n' + '\n' + ' Return "True" if *x* is in the underlying dictionary\'s ' + 'keys, values\n' + ' or items (in the latter case, *x* should be a "(key, ' + 'value)"\n' + ' tuple).\n' + '\n' + 'Keys views are set-like since their entries are unique and ' + 'hashable.\n' + 'If all values are hashable, so that "(key, value)" pairs ' + 'are unique\n' + 'and hashable, then the items view is also set-like. ' + '(Values views are\n' + 'not treated as set-like since the entries are generally ' + 'not unique.)\n' + 'For set-like views, all of the operations defined for the ' + 'abstract\n' + 'base class "collections.abc.Set" are available (for ' + 'example, "==",\n' + '"<", or "^").\n' + '\n' + 'An example of dictionary view usage:\n' + '\n' + " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, " + "'spam': 500}\n" + ' >>> keys = dishes.keys()\n' + ' >>> values = dishes.values()\n' + '\n' + ' >>> # iteration\n' + ' >>> n = 0\n' + ' >>> for val in values:\n' + ' ... n += val\n' + ' >>> print(n)\n' + ' 504\n' + '\n' + ' >>> # keys and values are iterated over in the same ' + 'order\n' + ' >>> list(keys)\n' + " ['eggs', 'bacon', 'sausage', 'spam']\n" + ' >>> list(values)\n' + ' [2, 1, 1, 500]\n' + '\n' + ' >>> # view objects are dynamic and reflect dict ' + 'changes\n' + " >>> del dishes['eggs']\n" + " >>> del dishes['sausage']\n" + ' >>> list(keys)\n' + " ['spam', 'bacon']\n" + '\n' + ' >>> # set operations\n' + " >>> keys & {'eggs', 'bacon', 'salad'}\n" + " {'bacon'}\n" + " >>> keys ^ {'sausage', 'juice'}\n" + " {'juice', 'sausage', 'bacon', 'spam'}\n", + 'typesmethods': '\n' + 'Methods\n' + '*******\n' + '\n' + 'Methods are functions that are called using the attribute ' + 'notation.\n' + 'There are two flavors: built-in methods (such as ' + '"append()" on lists)\n' + 'and class instance methods. Built-in methods are ' + 'described with the\n' + 'types that support them.\n' + '\n' + 'If you access a method (a function defined in a class ' + 'namespace)\n' + 'through an instance, you get a special object: a *bound ' + 'method* (also\n' + 'called *instance method*) object. When called, it will add ' + 'the "self"\n' + 'argument to the argument list. Bound methods have two ' + 'special read-\n' + 'only attributes: "m.__self__" is the object on which the ' + 'method\n' + 'operates, and "m.__func__" is the function implementing ' + 'the method.\n' + 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely ' + 'equivalent to\n' + 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., ' + 'arg-n)".\n' + '\n' + 'Like function objects, bound method objects support ' + 'getting arbitrary\n' + 'attributes. However, since method attributes are actually ' + 'stored on\n' + 'the underlying function object ("meth.__func__"), setting ' + 'method\n' + 'attributes on bound methods is disallowed. Attempting to ' + 'set an\n' + 'attribute on a method results in an "AttributeError" being ' + 'raised. In\n' + 'order to set a method attribute, you need to explicitly ' + 'set it on the\n' + 'underlying function object:\n' + '\n' + ' >>> class C:\n' + ' ... def method(self):\n' + ' ... pass\n' + ' ...\n' + ' >>> c = C()\n' + " >>> c.method.whoami = 'my name is method' # can't set " + 'on the method\n' + ' Traceback (most recent call last):\n' + ' File "", line 1, in \n' + " AttributeError: 'method' object has no attribute " + "'whoami'\n" + " >>> c.method.__func__.whoami = 'my name is method'\n" + ' >>> c.method.whoami\n' + " 'my name is method'\n" + '\n' + 'See *The standard type hierarchy* for more information.\n', + 'typesmodules': '\n' + 'Modules\n' + '*******\n' + '\n' + 'The only special operation on a module is attribute ' + 'access: "m.name",\n' + 'where *m* is a module and *name* accesses a name defined ' + "in *m*'s\n" + 'symbol table. Module attributes can be assigned to. (Note ' + 'that the\n' + '"import" statement is not, strictly speaking, an operation ' + 'on a module\n' + 'object; "import foo" does not require a module object ' + 'named *foo* to\n' + 'exist, rather it requires an (external) *definition* for a ' + 'module\n' + 'named *foo* somewhere.)\n' + '\n' + 'A special attribute of every module is "__dict__". This is ' + 'the\n' + "dictionary containing the module's symbol table. Modifying " + 'this\n' + "dictionary will actually change the module's symbol table, " + 'but direct\n' + 'assignment to the "__dict__" attribute is not possible ' + '(you can write\n' + '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", ' + "but you can't\n" + 'write "m.__dict__ = {}"). Modifying "__dict__" directly ' + 'is not\n' + 'recommended.\n' + '\n' + 'Modules built into the interpreter are written like this: ' + '"". If loaded from a file, they are ' + 'written as\n' + '"".\n', + 'typesseq': '\n' + 'Sequence Types --- "list", "tuple", "range"\n' + '*******************************************\n' + '\n' + 'There are three basic sequence types: lists, tuples, and ' + 'range\n' + 'objects. Additional sequence types tailored for processing of ' + '*binary\n' + 'data* and *text strings* are described in dedicated sections.\n' + '\n' + '\n' + 'Common Sequence Operations\n' + '==========================\n' + '\n' + 'The operations in the following table are supported by most ' + 'sequence\n' + 'types, both mutable and immutable. The ' + '"collections.abc.Sequence" ABC\n' + 'is provided to make it easier to correctly implement these ' + 'operations\n' + 'on custom sequence types.\n' + '\n' + 'This table lists the sequence operations sorted in ascending ' + 'priority.\n' + 'In the table, *s* and *t* are sequences of the same type, *n*, ' + '*i*,\n' + '*j* and *k* are integers and *x* is an arbitrary object that ' + 'meets any\n' + 'type and value restrictions imposed by *s*.\n' + '\n' + 'The "in" and "not in" operations have the same priorities as ' + 'the\n' + 'comparison operations. The "+" (concatenation) and "*" ' + '(repetition)\n' + 'operations have the same priority as the corresponding ' + 'numeric\n' + 'operations.\n' + '\n' + '+----------------------------+----------------------------------+------------+\n' + '| Operation | ' + 'Result | Notes |\n' + '+============================+==================================+============+\n' + '| "x in s" | "True" if an item of *s* ' + 'is | (1) |\n' + '| | equal to *x*, else ' + '"False" | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "x not in s" | "False" if an item of *s* ' + 'is | (1) |\n' + '| | equal to *x*, else ' + '"True" | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "s + t" | the concatenation of *s* and ' + '*t* | (6)(7) |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "s * n" or "n * s" | equivalent to adding *s* ' + 'to | (2)(7) |\n' + '| | itself *n* ' + 'times | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "s[i]" | *i*th item of *s*, origin ' + '0 | (3) |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "s[i:j]" | slice of *s* from *i* to ' + '*j* | (3)(4) |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "s[i:j:k]" | slice of *s* from *i* to ' + '*j* | (3)(5) |\n' + '| | with step ' + '*k* | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "len(s)" | length of ' + '*s* | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "min(s)" | smallest item of ' + '*s* | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "max(s)" | largest item of ' + '*s* | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "s.index(x[, i[, j]])" | index of the first occurrence ' + 'of | (8) |\n' + '| | *x* in *s* (at or after ' + 'index | |\n' + '| | *i* and before index ' + '*j*) | |\n' + '+----------------------------+----------------------------------+------------+\n' + '| "s.count(x)" | total number of occurrences ' + 'of | |\n' + '| | *x* in ' + '*s* | |\n' + '+----------------------------+----------------------------------+------------+\n' + '\n' + 'Sequences of the same type also support comparisons. In ' + 'particular,\n' + 'tuples and lists are compared lexicographically by comparing\n' + 'corresponding elements. This means that to compare equal, ' + 'every\n' + 'element must compare equal and the two sequences must be of ' + 'the same\n' + 'type and have the same length. (For full details see ' + '*Comparisons* in\n' + 'the language reference.)\n' + '\n' + 'Notes:\n' + '\n' + '1. While the "in" and "not in" operations are used only for ' + 'simple\n' + ' containment testing in the general case, some specialised ' + 'sequences\n' + ' (such as "str", "bytes" and "bytearray") also use them for\n' + ' subsequence testing:\n' + '\n' + ' >>> "gg" in "eggs"\n' + ' True\n' + '\n' + '2. Values of *n* less than "0" are treated as "0" (which ' + 'yields an\n' + ' empty sequence of the same type as *s*). Note that items ' + 'in the\n' + ' sequence *s* are not copied; they are referenced multiple ' + 'times.\n' + ' This often haunts new Python programmers; consider:\n' + '\n' + ' >>> lists = [[]] * 3\n' + ' >>> lists\n' + ' [[], [], []]\n' + ' >>> lists[0].append(3)\n' + ' >>> lists\n' + ' [[3], [3], [3]]\n' + '\n' + ' What has happened is that "[[]]" is a one-element list ' + 'containing\n' + ' an empty list, so all three elements of "[[]] * 3" are ' + 'references\n' + ' to this single empty list. Modifying any of the elements ' + 'of\n' + ' "lists" modifies this single list. You can create a list ' + 'of\n' + ' different lists this way:\n' + '\n' + ' >>> lists = [[] for i in range(3)]\n' + ' >>> lists[0].append(3)\n' + ' >>> lists[1].append(5)\n' + ' >>> lists[2].append(7)\n' + ' >>> lists\n' + ' [[3], [5], [7]]\n' + '\n' + ' Further explanation is available in the FAQ entry *How do I ' + 'create\n' + ' a multidimensional list?*.\n' + '\n' + '3. If *i* or *j* is negative, the index is relative to the end ' + 'of\n' + ' the string: "len(s) + i" or "len(s) + j" is substituted. ' + 'But note\n' + ' that "-0" is still "0".\n' + '\n' + '4. The slice of *s* from *i* to *j* is defined as the sequence ' + 'of\n' + ' items with index *k* such that "i <= k < j". If *i* or *j* ' + 'is\n' + ' greater than "len(s)", use "len(s)". If *i* is omitted or ' + '"None",\n' + ' use "0". If *j* is omitted or "None", use "len(s)". If ' + '*i* is\n' + ' greater than or equal to *j*, the slice is empty.\n' + '\n' + '5. The slice of *s* from *i* to *j* with step *k* is defined ' + 'as the\n' + ' sequence of items with index "x = i + n*k" such that "0 <= ' + 'n <\n' + ' (j-i)/k". In other words, the indices are "i", "i+k", ' + '"i+2*k",\n' + ' "i+3*k" and so on, stopping when *j* is reached (but never\n' + ' including *j*). If *i* or *j* is greater than "len(s)", ' + 'use\n' + ' "len(s)". If *i* or *j* are omitted or "None", they become ' + '"end"\n' + ' values (which end depends on the sign of *k*). Note, *k* ' + 'cannot be\n' + ' zero. If *k* is "None", it is treated like "1".\n' + '\n' + '6. Concatenating immutable sequences always results in a new\n' + ' object. This means that building up a sequence by repeated\n' + ' concatenation will have a quadratic runtime cost in the ' + 'total\n' + ' sequence length. To get a linear runtime cost, you must ' + 'switch to\n' + ' one of the alternatives below:\n' + '\n' + ' * if concatenating "str" objects, you can build a list and ' + 'use\n' + ' "str.join()" at the end or else write to an ' + '"io.StringIO"\n' + ' instance and retrieve its value when complete\n' + '\n' + ' * if concatenating "bytes" objects, you can similarly use\n' + ' "bytes.join()" or "io.BytesIO", or you can do in-place\n' + ' concatenation with a "bytearray" object. "bytearray" ' + 'objects are\n' + ' mutable and have an efficient overallocation mechanism\n' + '\n' + ' * if concatenating "tuple" objects, extend a "list" ' + 'instead\n' + '\n' + ' * for other types, investigate the relevant class ' + 'documentation\n' + '\n' + '7. Some sequence types (such as "range") only support item\n' + " sequences that follow specific patterns, and hence don't " + 'support\n' + ' sequence concatenation or repetition.\n' + '\n' + '8. "index" raises "ValueError" when *x* is not found in *s*. ' + 'When\n' + ' supported, the additional arguments to the index method ' + 'allow\n' + ' efficient searching of subsections of the sequence. Passing ' + 'the\n' + ' extra arguments is roughly equivalent to using ' + '"s[i:j].index(x)",\n' + ' only without copying any data and with the returned index ' + 'being\n' + ' relative to the start of the sequence rather than the start ' + 'of the\n' + ' slice.\n' + '\n' + '\n' + 'Immutable Sequence Types\n' + '========================\n' + '\n' + 'The only operation that immutable sequence types generally ' + 'implement\n' + 'that is not also implemented by mutable sequence types is ' + 'support for\n' + 'the "hash()" built-in.\n' + '\n' + 'This support allows immutable sequences, such as "tuple" ' + 'instances, to\n' + 'be used as "dict" keys and stored in "set" and "frozenset" ' + 'instances.\n' + '\n' + 'Attempting to hash an immutable sequence that contains ' + 'unhashable\n' + 'values will result in "TypeError".\n' + '\n' + '\n' + 'Mutable Sequence Types\n' + '======================\n' + '\n' + 'The operations in the following table are defined on mutable ' + 'sequence\n' + 'types. The "collections.abc.MutableSequence" ABC is provided ' + 'to make\n' + 'it easier to correctly implement these operations on custom ' + 'sequence\n' + 'types.\n' + '\n' + 'In the table *s* is an instance of a mutable sequence type, ' + '*t* is any\n' + 'iterable object and *x* is an arbitrary object that meets any ' + 'type and\n' + 'value restrictions imposed by *s* (for example, "bytearray" ' + 'only\n' + 'accepts integers that meet the value restriction "0 <= x <= ' + '255").\n' + '\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| Operation | ' + 'Result | Notes |\n' + '+================================+==================================+=======================+\n' + '| "s[i] = x" | item *i* of *s* is replaced ' + 'by | |\n' + '| | ' + '*x* | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s[i:j] = t" | slice of *s* from *i* to ' + '*j* is | |\n' + '| | replaced by the contents of ' + 'the | |\n' + '| | iterable ' + '*t* | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "del s[i:j]" | same as "s[i:j] = ' + '[]" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s[i:j:k] = t" | the elements of "s[i:j:k]" ' + 'are | (1) |\n' + '| | replaced by those of ' + '*t* | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "del s[i:j:k]" | removes the elements ' + 'of | |\n' + '| | "s[i:j:k]" from the ' + 'list | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.append(x)" | appends *x* to the end of ' + 'the | |\n' + '| | sequence (same ' + 'as | |\n' + '| | "s[len(s):len(s)] = ' + '[x]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.clear()" | removes all items from "s" ' + '(same | (5) |\n' + '| | as "del ' + 's[:]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.copy()" | creates a shallow copy of ' + '"s" | (5) |\n' + '| | (same as ' + '"s[:]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.extend(t)" or "s += t" | extends *s* with the ' + 'contents of | |\n' + '| | *t* (for the most part the ' + 'same | |\n' + '| | as "s[len(s):len(s)] = ' + 't") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s *= n" | updates *s* with its ' + 'contents | (6) |\n' + '| | repeated *n* ' + 'times | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.insert(i, x)" | inserts *x* into *s* at ' + 'the | |\n' + '| | index given by *i* (same ' + 'as | |\n' + '| | "s[i:i] = ' + '[x]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.pop([i])" | retrieves the item at *i* ' + 'and | (2) |\n' + '| | also removes it from ' + '*s* | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.remove(x)" | remove the first item from ' + '*s* | (3) |\n' + '| | where "s[i] == ' + 'x" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.reverse()" | reverses the items of *s* ' + 'in | (4) |\n' + '| | ' + 'place | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '\n' + 'Notes:\n' + '\n' + '1. *t* must have the same length as the slice it is ' + 'replacing.\n' + '\n' + '2. The optional argument *i* defaults to "-1", so that by ' + 'default\n' + ' the last item is removed and returned.\n' + '\n' + '3. "remove" raises "ValueError" when *x* is not found in *s*.\n' + '\n' + '4. The "reverse()" method modifies the sequence in place for\n' + ' economy of space when reversing a large sequence. To ' + 'remind users\n' + ' that it operates by side effect, it does not return the ' + 'reversed\n' + ' sequence.\n' + '\n' + '5. "clear()" and "copy()" are included for consistency with ' + 'the\n' + " interfaces of mutable containers that don't support " + 'slicing\n' + ' operations (such as "dict" and "set")\n' + '\n' + ' New in version 3.3: "clear()" and "copy()" methods.\n' + '\n' + '6. The value *n* is an integer, or an object implementing\n' + ' "__index__()". Zero and negative values of *n* clear the ' + 'sequence.\n' + ' Items in the sequence are not copied; they are referenced ' + 'multiple\n' + ' times, as explained for "s * n" under *Common Sequence ' + 'Operations*.\n' + '\n' + '\n' + 'Lists\n' + '=====\n' + '\n' + 'Lists are mutable sequences, typically used to store ' + 'collections of\n' + 'homogeneous items (where the precise degree of similarity will ' + 'vary by\n' + 'application).\n' + '\n' + 'class class list([iterable])\n' + '\n' + ' Lists may be constructed in several ways:\n' + '\n' + ' * Using a pair of square brackets to denote the empty list: ' + '"[]"\n' + '\n' + ' * Using square brackets, separating items with commas: ' + '"[a]",\n' + ' "[a, b, c]"\n' + '\n' + ' * Using a list comprehension: "[x for x in iterable]"\n' + '\n' + ' * Using the type constructor: "list()" or "list(iterable)"\n' + '\n' + ' The constructor builds a list whose items are the same and ' + 'in the\n' + " same order as *iterable*'s items. *iterable* may be either " + 'a\n' + ' sequence, a container that supports iteration, or an ' + 'iterator\n' + ' object. If *iterable* is already a list, a copy is made ' + 'and\n' + ' returned, similar to "iterable[:]". For example, ' + '"list(\'abc\')"\n' + ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" ' + 'returns "[1, 2,\n' + ' 3]". If no argument is given, the constructor creates a new ' + 'empty\n' + ' list, "[]".\n' + '\n' + ' Many other operations also produce lists, including the ' + '"sorted()"\n' + ' built-in.\n' + '\n' + ' Lists implement all of the *common* and *mutable* sequence\n' + ' operations. Lists also provide the following additional ' + 'method:\n' + '\n' + ' sort(*, key=None, reverse=None)\n' + '\n' + ' This method sorts the list in place, using only "<" ' + 'comparisons\n' + ' between items. Exceptions are not suppressed - if any ' + 'comparison\n' + ' operations fail, the entire sort operation will fail ' + '(and the\n' + ' list will likely be left in a partially modified ' + 'state).\n' + '\n' + ' "sort()" accepts two arguments that can only be passed ' + 'by\n' + ' keyword (*keyword-only arguments*):\n' + '\n' + ' *key* specifies a function of one argument that is used ' + 'to\n' + ' extract a comparison key from each list element (for ' + 'example,\n' + ' "key=str.lower"). The key corresponding to each item in ' + 'the list\n' + ' is calculated once and then used for the entire sorting ' + 'process.\n' + ' The default value of "None" means that list items are ' + 'sorted\n' + ' directly without calculating a separate key value.\n' + '\n' + ' The "functools.cmp_to_key()" utility is available to ' + 'convert a\n' + ' 2.x style *cmp* function to a *key* function.\n' + '\n' + ' *reverse* is a boolean value. If set to "True", then ' + 'the list\n' + ' elements are sorted as if each comparison were ' + 'reversed.\n' + '\n' + ' This method modifies the sequence in place for economy ' + 'of space\n' + ' when sorting a large sequence. To remind users that it ' + 'operates\n' + ' by side effect, it does not return the sorted sequence ' + '(use\n' + ' "sorted()" to explicitly request a new sorted list ' + 'instance).\n' + '\n' + ' The "sort()" method is guaranteed to be stable. A sort ' + 'is\n' + ' stable if it guarantees not to change the relative order ' + 'of\n' + ' elements that compare equal --- this is helpful for ' + 'sorting in\n' + ' multiple passes (for example, sort by department, then ' + 'by salary\n' + ' grade).\n' + '\n' + ' **CPython implementation detail:** While a list is being ' + 'sorted,\n' + ' the effect of attempting to mutate, or even inspect, the ' + 'list is\n' + ' undefined. The C implementation of Python makes the ' + 'list appear\n' + ' empty for the duration, and raises "ValueError" if it ' + 'can detect\n' + ' that the list has been mutated during a sort.\n' + '\n' + '\n' + 'Tuples\n' + '======\n' + '\n' + 'Tuples are immutable sequences, typically used to store ' + 'collections of\n' + 'heterogeneous data (such as the 2-tuples produced by the ' + '"enumerate()"\n' + 'built-in). Tuples are also used for cases where an immutable ' + 'sequence\n' + 'of homogeneous data is needed (such as allowing storage in a ' + '"set" or\n' + '"dict" instance).\n' + '\n' + 'class class tuple([iterable])\n' + '\n' + ' Tuples may be constructed in a number of ways:\n' + '\n' + ' * Using a pair of parentheses to denote the empty tuple: ' + '"()"\n' + '\n' + ' * Using a trailing comma for a singleton tuple: "a," or ' + '"(a,)"\n' + '\n' + ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n' + '\n' + ' * Using the "tuple()" built-in: "tuple()" or ' + '"tuple(iterable)"\n' + '\n' + ' The constructor builds a tuple whose items are the same and ' + 'in the\n' + " same order as *iterable*'s items. *iterable* may be either " + 'a\n' + ' sequence, a container that supports iteration, or an ' + 'iterator\n' + ' object. If *iterable* is already a tuple, it is returned\n' + ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', ' + '\'b\', \'c\')"\n' + ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no ' + 'argument is\n' + ' given, the constructor creates a new empty tuple, "()".\n' + '\n' + ' Note that it is actually the comma which makes a tuple, not ' + 'the\n' + ' parentheses. The parentheses are optional, except in the ' + 'empty\n' + ' tuple case, or when they are needed to avoid syntactic ' + 'ambiguity.\n' + ' For example, "f(a, b, c)" is a function call with three ' + 'arguments,\n' + ' while "f((a, b, c))" is a function call with a 3-tuple as ' + 'the sole\n' + ' argument.\n' + '\n' + ' Tuples implement all of the *common* sequence operations.\n' + '\n' + 'For heterogeneous collections of data where access by name is ' + 'clearer\n' + 'than access by index, "collections.namedtuple()" may be a ' + 'more\n' + 'appropriate choice than a simple tuple object.\n' + '\n' + '\n' + 'Ranges\n' + '======\n' + '\n' + 'The "range" type represents an immutable sequence of numbers ' + 'and is\n' + 'commonly used for looping a specific number of times in "for" ' + 'loops.\n' + '\n' + 'class class range(stop)\n' + 'class class range(start, stop[, step])\n' + '\n' + ' The arguments to the range constructor must be integers ' + '(either\n' + ' built-in "int" or any object that implements the ' + '"__index__"\n' + ' special method). If the *step* argument is omitted, it ' + 'defaults to\n' + ' "1". If the *start* argument is omitted, it defaults to ' + '"0". If\n' + ' *step* is zero, "ValueError" is raised.\n' + '\n' + ' For a positive *step*, the contents of a range "r" are ' + 'determined\n' + ' by the formula "r[i] = start + step*i" where "i >= 0" and ' + '"r[i] <\n' + ' stop".\n' + '\n' + ' For a negative *step*, the contents of the range are still\n' + ' determined by the formula "r[i] = start + step*i", but the\n' + ' constraints are "i >= 0" and "r[i] > stop".\n' + '\n' + ' A range object will be empty if "r[0]" does not meet the ' + 'value\n' + ' constraint. Ranges do support negative indices, but these ' + 'are\n' + ' interpreted as indexing from the end of the sequence ' + 'determined by\n' + ' the positive indices.\n' + '\n' + ' Ranges containing absolute values larger than "sys.maxsize" ' + 'are\n' + ' permitted but some features (such as "len()") may raise\n' + ' "OverflowError".\n' + '\n' + ' Range examples:\n' + '\n' + ' >>> list(range(10))\n' + ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n' + ' >>> list(range(1, 11))\n' + ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n' + ' >>> list(range(0, 30, 5))\n' + ' [0, 5, 10, 15, 20, 25]\n' + ' >>> list(range(0, 10, 3))\n' + ' [0, 3, 6, 9]\n' + ' >>> list(range(0, -10, -1))\n' + ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n' + ' >>> list(range(0))\n' + ' []\n' + ' >>> list(range(1, 0))\n' + ' []\n' + '\n' + ' Ranges implement all of the *common* sequence operations ' + 'except\n' + ' concatenation and repetition (due to the fact that range ' + 'objects\n' + ' can only represent sequences that follow a strict pattern ' + 'and\n' + ' repetition and concatenation will usually violate that ' + 'pattern).\n' + '\n' + 'The advantage of the "range" type over a regular "list" or ' + '"tuple" is\n' + 'that a "range" object will always take the same (small) amount ' + 'of\n' + 'memory, no matter the size of the range it represents (as it ' + 'only\n' + 'stores the "start", "stop" and "step" values, calculating ' + 'individual\n' + 'items and subranges as needed).\n' + '\n' + 'Range objects implement the "collections.abc.Sequence" ABC, ' + 'and\n' + 'provide features such as containment tests, element index ' + 'lookup,\n' + 'slicing and support for negative indices (see *Sequence Types ' + '---\n' + 'list, tuple, range*):\n' + '\n' + '>>> r = range(0, 20, 2)\n' + '>>> r\n' + 'range(0, 20, 2)\n' + '>>> 11 in r\n' + 'False\n' + '>>> 10 in r\n' + 'True\n' + '>>> r.index(10)\n' + '5\n' + '>>> r[5]\n' + '10\n' + '>>> r[:5]\n' + 'range(0, 10, 2)\n' + '>>> r[-1]\n' + '18\n' + '\n' + 'Testing range objects for equality with "==" and "!=" compares ' + 'them as\n' + 'sequences. That is, two range objects are considered equal if ' + 'they\n' + 'represent the same sequence of values. (Note that two range ' + 'objects\n' + 'that compare equal might have different "start", "stop" and ' + '"step"\n' + 'attributes, for example "range(0) == range(2, 1, 3)" or ' + '"range(0, 3,\n' + '2) == range(0, 4, 2)".)\n' + '\n' + 'Changed in version 3.2: Implement the Sequence ABC. Support ' + 'slicing\n' + 'and negative indices. Test "int" objects for membership in ' + 'constant\n' + 'time instead of iterating through all items.\n' + '\n' + "Changed in version 3.3: Define '==' and '!=' to compare range " + 'objects\n' + 'based on the sequence of values they define (instead of ' + 'comparing\n' + 'based on object identity).\n' + '\n' + 'New in version 3.3: The "start", "stop" and "step" ' + 'attributes.\n', + 'typesseq-mutable': '\n' + 'Mutable Sequence Types\n' + '**********************\n' + '\n' + 'The operations in the following table are defined on ' + 'mutable sequence\n' + 'types. The "collections.abc.MutableSequence" ABC is ' + 'provided to make\n' + 'it easier to correctly implement these operations on ' + 'custom sequence\n' + 'types.\n' + '\n' + 'In the table *s* is an instance of a mutable sequence ' + 'type, *t* is any\n' + 'iterable object and *x* is an arbitrary object that ' + 'meets any type and\n' + 'value restrictions imposed by *s* (for example, ' + '"bytearray" only\n' + 'accepts integers that meet the value restriction "0 <= ' + 'x <= 255").\n' + '\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| Operation | ' + 'Result | ' + 'Notes |\n' + '+================================+==================================+=======================+\n' + '| "s[i] = x" | item *i* of *s* is ' + 'replaced by | |\n' + '| | ' + '*x* ' + '| |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s[i:j] = t" | slice of *s* from ' + '*i* to *j* is | |\n' + '| | replaced by the ' + 'contents of the | |\n' + '| | iterable ' + '*t* | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "del s[i:j]" | same as "s[i:j] = ' + '[]" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s[i:j:k] = t" | the elements of ' + '"s[i:j:k]" are | (1) |\n' + '| | replaced by those ' + 'of *t* | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "del s[i:j:k]" | removes the ' + 'elements of | |\n' + '| | "s[i:j:k]" from the ' + 'list | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.append(x)" | appends *x* to the ' + 'end of the | |\n' + '| | sequence (same ' + 'as | |\n' + '| | "s[len(s):len(s)] = ' + '[x]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.clear()" | removes all items ' + 'from "s" (same | (5) |\n' + '| | as "del ' + 's[:]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.copy()" | creates a shallow ' + 'copy of "s" | (5) |\n' + '| | (same as ' + '"s[:]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.extend(t)" or "s += t" | extends *s* with ' + 'the contents of | |\n' + '| | *t* (for the most ' + 'part the same | |\n' + '| | as ' + '"s[len(s):len(s)] = t") | ' + '|\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s *= n" | updates *s* with ' + 'its contents | (6) |\n' + '| | repeated *n* ' + 'times | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.insert(i, x)" | inserts *x* into ' + '*s* at the | |\n' + '| | index given by *i* ' + '(same as | |\n' + '| | "s[i:i] = ' + '[x]") | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.pop([i])" | retrieves the item ' + 'at *i* and | (2) |\n' + '| | also removes it ' + 'from *s* | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.remove(x)" | remove the first ' + 'item from *s* | (3) |\n' + '| | where "s[i] == ' + 'x" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.reverse()" | reverses the items ' + 'of *s* in | (4) |\n' + '| | ' + 'place ' + '| |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '\n' + 'Notes:\n' + '\n' + '1. *t* must have the same length as the slice it is ' + 'replacing.\n' + '\n' + '2. The optional argument *i* defaults to "-1", so that ' + 'by default\n' + ' the last item is removed and returned.\n' + '\n' + '3. "remove" raises "ValueError" when *x* is not found ' + 'in *s*.\n' + '\n' + '4. The "reverse()" method modifies the sequence in ' + 'place for\n' + ' economy of space when reversing a large sequence. ' + 'To remind users\n' + ' that it operates by side effect, it does not return ' + 'the reversed\n' + ' sequence.\n' + '\n' + '5. "clear()" and "copy()" are included for consistency ' + 'with the\n' + " interfaces of mutable containers that don't support " + 'slicing\n' + ' operations (such as "dict" and "set")\n' + '\n' + ' New in version 3.3: "clear()" and "copy()" ' + 'methods.\n' + '\n' + '6. The value *n* is an integer, or an object ' + 'implementing\n' + ' "__index__()". Zero and negative values of *n* ' + 'clear the sequence.\n' + ' Items in the sequence are not copied; they are ' + 'referenced multiple\n' + ' times, as explained for "s * n" under *Common ' + 'Sequence Operations*.\n', + 'unary': '\n' + 'Unary arithmetic and bitwise operations\n' + '***************************************\n' + '\n' + 'All unary arithmetic and bitwise operations have the same ' + 'priority:\n' + '\n' + ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n' + '\n' + 'The unary "-" (minus) operator yields the negation of its ' + 'numeric\n' + 'argument.\n' + '\n' + 'The unary "+" (plus) operator yields its numeric argument ' + 'unchanged.\n' + '\n' + 'The unary "~" (invert) operator yields the bitwise inversion of ' + 'its\n' + 'integer argument. The bitwise inversion of "x" is defined as\n' + '"-(x+1)". It only applies to integral numbers.\n' + '\n' + 'In all three cases, if the argument does not have the proper ' + 'type, a\n' + '"TypeError" exception is raised.\n', + 'while': '\n' + 'The "while" statement\n' + '*********************\n' + '\n' + 'The "while" statement is used for repeated execution as long as ' + 'an\n' + 'expression is true:\n' + '\n' + ' while_stmt ::= "while" expression ":" suite\n' + ' ["else" ":" suite]\n' + '\n' + 'This repeatedly tests the expression and, if it is true, executes ' + 'the\n' + 'first suite; if the expression is false (which may be the first ' + 'time\n' + 'it is tested) the suite of the "else" clause, if present, is ' + 'executed\n' + 'and the loop terminates.\n' + '\n' + 'A "break" statement executed in the first suite terminates the ' + 'loop\n' + 'without executing the "else" clause\'s suite. A "continue" ' + 'statement\n' + 'executed in the first suite skips the rest of the suite and goes ' + 'back\n' + 'to testing the expression.\n', + 'with': '\n' + 'The "with" statement\n' + '********************\n' + '\n' + 'The "with" statement is used to wrap the execution of a block ' + 'with\n' + 'methods defined by a context manager (see section *With Statement\n' + 'Context Managers*). This allows common ' + '"try"..."except"..."finally"\n' + 'usage patterns to be encapsulated for convenient reuse.\n' + '\n' + ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' + ' with_item ::= expression ["as" target]\n' + '\n' + 'The execution of the "with" statement with one "item" proceeds as\n' + 'follows:\n' + '\n' + '1. The context expression (the expression given in the ' + '"with_item")\n' + ' is evaluated to obtain a context manager.\n' + '\n' + '2. The context manager\'s "__exit__()" is loaded for later use.\n' + '\n' + '3. The context manager\'s "__enter__()" method is invoked.\n' + '\n' + '4. If a target was included in the "with" statement, the return\n' + ' value from "__enter__()" is assigned to it.\n' + '\n' + ' Note: The "with" statement guarantees that if the ' + '"__enter__()"\n' + ' method returns without an error, then "__exit__()" will ' + 'always be\n' + ' called. Thus, if an error occurs during the assignment to ' + 'the\n' + ' target list, it will be treated the same as an error ' + 'occurring\n' + ' within the suite would be. See step 6 below.\n' + '\n' + '5. The suite is executed.\n' + '\n' + '6. The context manager\'s "__exit__()" method is invoked. If an\n' + ' exception caused the suite to be exited, its type, value, and\n' + ' traceback are passed as arguments to "__exit__()". Otherwise, ' + 'three\n' + ' "None" arguments are supplied.\n' + '\n' + ' If the suite was exited due to an exception, and the return ' + 'value\n' + ' from the "__exit__()" method was false, the exception is ' + 'reraised.\n' + ' If the return value was true, the exception is suppressed, and\n' + ' execution continues with the statement following the "with"\n' + ' statement.\n' + '\n' + ' If the suite was exited for any reason other than an exception, ' + 'the\n' + ' return value from "__exit__()" is ignored, and execution ' + 'proceeds\n' + ' at the normal location for the kind of exit that was taken.\n' + '\n' + 'With more than one item, the context managers are processed as if\n' + 'multiple "with" statements were nested:\n' + '\n' + ' with A() as a, B() as b:\n' + ' suite\n' + '\n' + 'is equivalent to\n' + '\n' + ' with A() as a:\n' + ' with B() as b:\n' + ' suite\n' + '\n' + 'Changed in version 3.1: Support for multiple context expressions.\n' + '\n' + 'See also: **PEP 0343** - The "with" statement\n' + '\n' + ' The specification, background, and examples for the Python ' + '"with"\n' + ' statement.\n', + 'yield': '\n' + 'The "yield" statement\n' + '*********************\n' + '\n' + ' yield_stmt ::= yield_expression\n' + '\n' + 'A "yield" statement is semantically equivalent to a *yield\n' + 'expression*. The yield statement can be used to omit the ' + 'parentheses\n' + 'that would otherwise be required in the equivalent yield ' + 'expression\n' + 'statement. For example, the yield statements\n' + '\n' + ' yield \n' + ' yield from \n' + '\n' + 'are equivalent to the yield expression statements\n' + '\n' + ' (yield )\n' + ' (yield from )\n' + '\n' + 'Yield expressions and statements are only used when defining a\n' + '*generator* function, and are only used in the body of the ' + 'generator\n' + 'function. Using yield in a function definition is sufficient to ' + 'cause\n' + 'that definition to create a generator function instead of a ' + 'normal\n' + 'function.\n' + '\n' + 'For full details of "yield" semantics, refer to the *Yield\n' + 'expressions* section.\n'} From c912af833905c3bb172f268410d6bcc5865f488c Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Sun, 23 Jul 2017 18:16:33 -0700 Subject: [PATCH 15/24] Version bump and copyright year fixes for 3.4.7rc1. --- Doc/copyright.rst | 2 +- Doc/tools/extensions/pyspecific.py | 2 +- Include/patchlevel.h | 8 ++++---- README | 7 ++++--- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/Doc/copyright.rst b/Doc/copyright.rst index 22d7705846ea93..2b5400cd9fb036 100644 --- a/Doc/copyright.rst +++ b/Doc/copyright.rst @@ -4,7 +4,7 @@ Copyright Python and this documentation is: -Copyright © 2001-2016 Python Software Foundation. All rights reserved. +Copyright © 2001-2017 Python Software Foundation. All rights reserved. Copyright © 2000 BeOpen.com. All rights reserved. diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 169060c1cdcd93..f719ae112f660d 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -34,7 +34,7 @@ ISSUE_URI = 'https://bugs.python.org/issue%s' -SOURCE_URI = 'https://hg.python.org/cpython/file/3.4/%s' +SOURCE_URI = 'https://github.com/python/cpython/tree/3.4/%s' # monkey-patch reST parser to disable alphabetic and roman enumerated lists from docutils.parsers.rst.states import Body diff --git a/Include/patchlevel.h b/Include/patchlevel.h index 21a8701d6edcaa..38424ba4b47be6 100644 --- a/Include/patchlevel.h +++ b/Include/patchlevel.h @@ -18,12 +18,12 @@ /*--start constants--*/ #define PY_MAJOR_VERSION 3 #define PY_MINOR_VERSION 4 -#define PY_MICRO_VERSION 6 -#define PY_RELEASE_LEVEL PY_RELEASE_LEVEL_FINAL -#define PY_RELEASE_SERIAL 0 +#define PY_MICRO_VERSION 7 +#define PY_RELEASE_LEVEL PY_RELEASE_LEVEL_GAMMA +#define PY_RELEASE_SERIAL 1 /* Version as a string */ -#define PY_VERSION "3.4.6+" +#define PY_VERSION "3.4.7rc1" /*--end constants--*/ /* Version as a single 4-byte hex number, e.g. 0x010502B2 == 1.5.2b2. diff --git a/README b/README index 2ee032b9da91f1..cd9983422b427c 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ -This is Python version 3.4.6 -============================ +This is Python version 3.4.7 release candidate 1 +================================================ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017 Python Software Foundation. All rights @@ -176,7 +176,8 @@ Copyright and License Information --------------------------------- Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, -2012, 2013, 2014, 2015, 2016 Python Software Foundation. All rights reserved. +2012, 2013, 2014, 2015, 2016, 2017 Python Software Foundation. All rights +reserved. Copyright (c) 2000 BeOpen.com. All rights reserved. From 5c673dd27ee4db4d62da4d96a384c64e245e8b36 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Tue, 25 Jul 2017 01:58:59 -0700 Subject: [PATCH 16/24] Post-release bump for 3.4.7rc1. --- Include/patchlevel.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Include/patchlevel.h b/Include/patchlevel.h index 38424ba4b47be6..02c8f95cf47feb 100644 --- a/Include/patchlevel.h +++ b/Include/patchlevel.h @@ -23,7 +23,7 @@ #define PY_RELEASE_SERIAL 1 /* Version as a string */ -#define PY_VERSION "3.4.7rc1" +#define PY_VERSION "3.4.7rc1+" /*--end constants--*/ /* Version as a single 4-byte hex number, e.g. 0x010502B2 == 1.5.2b2. From 2a5a26c87e82c7d9a348792891feccd1b5e9a769 Mon Sep 17 00:00:00 2001 From: Dong-hee Na Date: Fri, 28 Jul 2017 04:47:46 +0900 Subject: [PATCH 17/24] [3.4] bpo-30119: fix ftplib.FTP.putline() to throw an error for a illegal command (#1214) (#2893) --- Lib/ftplib.py | 2 ++ Lib/test/test_ftplib.py | 6 +++++- .../next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst | 2 ++ 3 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst diff --git a/Lib/ftplib.py b/Lib/ftplib.py index 1d3bd9ef21da10..47f02f8b39bea8 100644 --- a/Lib/ftplib.py +++ b/Lib/ftplib.py @@ -187,6 +187,8 @@ def sanitize(self, s): # Internal: send one line to the server, appending CRLF def putline(self, line): + if '\r' in line or '\n' in line: + raise ValueError('an illegal newline character should not be contained') line = line + CRLF if self.debugging > 1: print('*put*', self.sanitize(line)) diff --git a/Lib/test/test_ftplib.py b/Lib/test/test_ftplib.py index d3be7d6d0079f2..1d448d5c6e288c 100644 --- a/Lib/test/test_ftplib.py +++ b/Lib/test/test_ftplib.py @@ -482,6 +482,9 @@ def test_sanitize(self): self.assertEqual(self.client.sanitize('PASS 12345'), repr('PASS *****')) def test_exceptions(self): + self.assertRaises(ValueError, self.client.sendcmd, 'echo 40\r\n0') + self.assertRaises(ValueError, self.client.sendcmd, 'echo 40\n0') + self.assertRaises(ValueError, self.client.sendcmd, 'echo 40\r0') self.assertRaises(ftplib.error_temp, self.client.sendcmd, 'echo 400') self.assertRaises(ftplib.error_temp, self.client.sendcmd, 'echo 499') self.assertRaises(ftplib.error_perm, self.client.sendcmd, 'echo 500') @@ -490,7 +493,8 @@ def test_exceptions(self): def test_all_errors(self): exceptions = (ftplib.error_reply, ftplib.error_temp, ftplib.error_perm, - ftplib.error_proto, ftplib.Error, OSError, EOFError) + ftplib.error_proto, ftplib.Error, OSError, + EOFError) for x in exceptions: try: raise x('exception not included in all_errors set') diff --git a/Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst b/Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst new file mode 100644 index 00000000000000..a37d37038424c6 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst @@ -0,0 +1,2 @@ +ftplib.FTP.putline() now throws ValueError on commands that contains CR or +LF. Patch by Dong-hee Na. From 362e9fb0de4321bf265dbca290f7dc1f383a4a47 Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Fri, 28 Jul 2017 01:02:05 -0400 Subject: [PATCH 18/24] [3.5] bpo-31036: use an existing Misc/NEWS rather than trying to use blurb (#2874) (#2926) (cherry picked from commit 3de144890ad3bc50694368a1b33be6d7f3a780b3) --- Doc/Makefile | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/Doc/Makefile b/Doc/Makefile index 49a6f0f808d867..8e70b21bec72e1 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -40,7 +40,19 @@ help: build: -mkdir -p build - $(BLURB) merge -f build/NEWS +# Look first for a Misc/NEWS file (building from a source release tarball +# or old repo) and use that, otherwise look for a Misc/NEWS.d directory +# (building from a newer repo) and use blurb to generate the NEWS file. + @if [ -f ../Misc/NEWS ] ; then \ + echo "Using existing Misc/NEWS file"; \ + cp ../Misc/NEWS build/NEWS; \ + elif [ -d ../Misc/NEWS.d ]; then \ + echo "Building NEWS from Misc/NEWS.d with blurb"; \ + $(BLURB) merge -f build/NEWS; \ + else \ + echo "Neither Misc/NEWS.d nor Misc/NEWS found; cannot build docs"; \ + exit 1; \ + fi $(SPHINXBUILD) $(ALLSPHINXOPTS) @echo From 67dc125d5e5db04a6e0c11f94cabcc48166d2e84 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Wed, 9 Aug 2017 00:06:48 -0700 Subject: [PATCH 19/24] Blurb release and pydoc topics for 3.4.7 final. --- Lib/pydoc_data/topics.py | 12941 +--------------- Misc/NEWS.d/3.4.7.rst | 8 + .../2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst | 2 - 3 files changed, 86 insertions(+), 12865 deletions(-) create mode 100644 Misc/NEWS.d/3.4.7.rst delete mode 100644 Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py index 81464b0832345a..740d787709499d 100644 --- a/Lib/pydoc_data/topics.py +++ b/Lib/pydoc_data/topics.py @@ -1,12864 +1,79 @@ # -*- coding: utf-8 -*- -# Autogenerated by Sphinx on Sun Jul 23 18:11:02 2017 -topics = {'assert': '\n' - 'The "assert" statement\n' - '**********************\n' - '\n' - 'Assert statements are a convenient way to insert debugging ' - 'assertions\n' - 'into a program:\n' - '\n' - ' assert_stmt ::= "assert" expression ["," expression]\n' - '\n' - 'The simple form, "assert expression", is equivalent to\n' - '\n' - ' if __debug__:\n' - ' if not expression: raise AssertionError\n' - '\n' - 'The extended form, "assert expression1, expression2", is ' - 'equivalent to\n' - '\n' - ' if __debug__:\n' - ' if not expression1: raise AssertionError(expression2)\n' - '\n' - 'These equivalences assume that "__debug__" and "AssertionError" ' - 'refer\n' - 'to the built-in variables with those names. In the current\n' - 'implementation, the built-in variable "__debug__" is "True" ' - 'under\n' - 'normal circumstances, "False" when optimization is requested ' - '(command\n' - 'line option -O). The current code generator emits no code for ' - 'an\n' - 'assert statement when optimization is requested at compile ' - 'time. Note\n' - 'that it is unnecessary to include the source code for the ' - 'expression\n' - 'that failed in the error message; it will be displayed as part ' - 'of the\n' - 'stack trace.\n' - '\n' - 'Assignments to "__debug__" are illegal. The value for the ' - 'built-in\n' - 'variable is determined when the interpreter starts.\n', - 'assignment': '\n' - 'Assignment statements\n' - '*********************\n' - '\n' - 'Assignment statements are used to (re)bind names to values ' - 'and to\n' - 'modify attributes or items of mutable objects:\n' - '\n' - ' assignment_stmt ::= (target_list "=")+ (expression_list | ' - 'yield_expression)\n' - ' target_list ::= target ("," target)* [","]\n' - ' target ::= identifier\n' - ' | "(" target_list ")"\n' - ' | "[" target_list "]"\n' - ' | attributeref\n' - ' | subscription\n' - ' | slicing\n' - ' | "*" target\n' - '\n' - '(See section *Primaries* for the syntax definitions for\n' - '*attributeref*, *subscription*, and *slicing*.)\n' - '\n' - 'An assignment statement evaluates the expression list ' - '(remember that\n' - 'this can be a single expression or a comma-separated list, ' - 'the latter\n' - 'yielding a tuple) and assigns the single resulting object to ' - 'each of\n' - 'the target lists, from left to right.\n' - '\n' - 'Assignment is defined recursively depending on the form of ' - 'the target\n' - '(list). When a target is part of a mutable object (an ' - 'attribute\n' - 'reference, subscription or slicing), the mutable object ' - 'must\n' - 'ultimately perform the assignment and decide about its ' - 'validity, and\n' - 'may raise an exception if the assignment is unacceptable. ' - 'The rules\n' - 'observed by various types and the exceptions raised are ' - 'given with the\n' - 'definition of the object types (see section *The standard ' - 'type\n' - 'hierarchy*).\n' - '\n' - 'Assignment of an object to a target list, optionally ' - 'enclosed in\n' - 'parentheses or square brackets, is recursively defined as ' - 'follows.\n' - '\n' - '* If the target list is a single target: The object is ' - 'assigned to\n' - ' that target.\n' - '\n' - '* If the target list is a comma-separated list of targets: ' - 'The\n' - ' object must be an iterable with the same number of items ' - 'as there\n' - ' are targets in the target list, and the items are ' - 'assigned, from\n' - ' left to right, to the corresponding targets.\n' - '\n' - ' * If the target list contains one target prefixed with an\n' - ' asterisk, called a "starred" target: The object must be ' - 'a sequence\n' - ' with at least as many items as there are targets in the ' - 'target\n' - ' list, minus one. The first items of the sequence are ' - 'assigned,\n' - ' from left to right, to the targets before the starred ' - 'target. The\n' - ' final items of the sequence are assigned to the targets ' - 'after the\n' - ' starred target. A list of the remaining items in the ' - 'sequence is\n' - ' then assigned to the starred target (the list can be ' - 'empty).\n' - '\n' - ' * Else: The object must be a sequence with the same number ' - 'of\n' - ' items as there are targets in the target list, and the ' - 'items are\n' - ' assigned, from left to right, to the corresponding ' - 'targets.\n' - '\n' - 'Assignment of an object to a single target is recursively ' - 'defined as\n' - 'follows.\n' - '\n' - '* If the target is an identifier (name):\n' - '\n' - ' * If the name does not occur in a "global" or "nonlocal" ' - 'statement\n' - ' in the current code block: the name is bound to the ' - 'object in the\n' - ' current local namespace.\n' - '\n' - ' * Otherwise: the name is bound to the object in the ' - 'global\n' - ' namespace or the outer namespace determined by ' - '"nonlocal",\n' - ' respectively.\n' - '\n' - ' The name is rebound if it was already bound. This may ' - 'cause the\n' - ' reference count for the object previously bound to the ' - 'name to reach\n' - ' zero, causing the object to be deallocated and its ' - 'destructor (if it\n' - ' has one) to be called.\n' - '\n' - '* If the target is a target list enclosed in parentheses or ' - 'in\n' - ' square brackets: The object must be an iterable with the ' - 'same number\n' - ' of items as there are targets in the target list, and its ' - 'items are\n' - ' assigned, from left to right, to the corresponding ' - 'targets.\n' - '\n' - '* If the target is an attribute reference: The primary ' - 'expression in\n' - ' the reference is evaluated. It should yield an object ' - 'with\n' - ' assignable attributes; if this is not the case, ' - '"TypeError" is\n' - ' raised. That object is then asked to assign the assigned ' - 'object to\n' - ' the given attribute; if it cannot perform the assignment, ' - 'it raises\n' - ' an exception (usually but not necessarily ' - '"AttributeError").\n' - '\n' - ' Note: If the object is a class instance and the attribute ' - 'reference\n' - ' occurs on both sides of the assignment operator, the RHS ' - 'expression,\n' - ' "a.x" can access either an instance attribute or (if no ' - 'instance\n' - ' attribute exists) a class attribute. The LHS target "a.x" ' - 'is always\n' - ' set as an instance attribute, creating it if necessary. ' - 'Thus, the\n' - ' two occurrences of "a.x" do not necessarily refer to the ' - 'same\n' - ' attribute: if the RHS expression refers to a class ' - 'attribute, the\n' - ' LHS creates a new instance attribute as the target of the\n' - ' assignment:\n' - '\n' - ' class Cls:\n' - ' x = 3 # class variable\n' - ' inst = Cls()\n' - ' inst.x = inst.x + 1 # writes inst.x as 4 leaving ' - 'Cls.x as 3\n' - '\n' - ' This description does not necessarily apply to descriptor\n' - ' attributes, such as properties created with "property()".\n' - '\n' - '* If the target is a subscription: The primary expression in ' - 'the\n' - ' reference is evaluated. It should yield either a mutable ' - 'sequence\n' - ' object (such as a list) or a mapping object (such as a ' - 'dictionary).\n' - ' Next, the subscript expression is evaluated.\n' - '\n' - ' If the primary is a mutable sequence object (such as a ' - 'list), the\n' - ' subscript must yield an integer. If it is negative, the ' - "sequence's\n" - ' length is added to it. The resulting value must be a ' - 'nonnegative\n' - " integer less than the sequence's length, and the sequence " - 'is asked\n' - ' to assign the assigned object to its item with that ' - 'index. If the\n' - ' index is out of range, "IndexError" is raised (assignment ' - 'to a\n' - ' subscripted sequence cannot add new items to a list).\n' - '\n' - ' If the primary is a mapping object (such as a dictionary), ' - 'the\n' - " subscript must have a type compatible with the mapping's " - 'key type,\n' - ' and the mapping is then asked to create a key/datum pair ' - 'which maps\n' - ' the subscript to the assigned object. This can either ' - 'replace an\n' - ' existing key/value pair with the same key value, or insert ' - 'a new\n' - ' key/value pair (if no key with the same value existed).\n' - '\n' - ' For user-defined objects, the "__setitem__()" method is ' - 'called with\n' - ' appropriate arguments.\n' - '\n' - '* If the target is a slicing: The primary expression in the\n' - ' reference is evaluated. It should yield a mutable ' - 'sequence object\n' - ' (such as a list). The assigned object should be a ' - 'sequence object\n' - ' of the same type. Next, the lower and upper bound ' - 'expressions are\n' - ' evaluated, insofar they are present; defaults are zero and ' - 'the\n' - " sequence's length. The bounds should evaluate to " - 'integers. If\n' - " either bound is negative, the sequence's length is added " - 'to it. The\n' - ' resulting bounds are clipped to lie between zero and the ' - "sequence's\n" - ' length, inclusive. Finally, the sequence object is asked ' - 'to replace\n' - ' the slice with the items of the assigned sequence. The ' - 'length of\n' - ' the slice may be different from the length of the assigned ' - 'sequence,\n' - ' thus changing the length of the target sequence, if the ' - 'target\n' - ' sequence allows it.\n' - '\n' - '**CPython implementation detail:** In the current ' - 'implementation, the\n' - 'syntax for targets is taken to be the same as for ' - 'expressions, and\n' - 'invalid syntax is rejected during the code generation phase, ' - 'causing\n' - 'less detailed error messages.\n' - '\n' - 'Although the definition of assignment implies that overlaps ' - 'between\n' - 'the left-hand side and the right-hand side are ' - "'simultanenous' (for\n" - 'example "a, b = b, a" swaps two variables), overlaps ' - '*within* the\n' - 'collection of assigned-to variables occur left-to-right, ' - 'sometimes\n' - 'resulting in confusion. For instance, the following program ' - 'prints\n' - '"[0, 2]":\n' - '\n' - ' x = [0, 1]\n' - ' i = 0\n' - ' i, x[i] = 1, 2 # i is updated, then x[i] is ' - 'updated\n' - ' print(x)\n' - '\n' - 'See also: **PEP 3132** - Extended Iterable Unpacking\n' - '\n' - ' The specification for the "*target" feature.\n' - '\n' - '\n' - 'Augmented assignment statements\n' - '===============================\n' - '\n' - 'Augmented assignment is the combination, in a single ' - 'statement, of a\n' - 'binary operation and an assignment statement:\n' - '\n' - ' augmented_assignment_stmt ::= augtarget augop ' - '(expression_list | yield_expression)\n' - ' augtarget ::= identifier | attributeref | ' - 'subscription | slicing\n' - ' augop ::= "+=" | "-=" | "*=" | "/=" | ' - '"//=" | "%=" | "**="\n' - ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' - '\n' - '(See section *Primaries* for the syntax definitions of the ' - 'last three\n' - 'symbols.)\n' - '\n' - 'An augmented assignment evaluates the target (which, unlike ' - 'normal\n' - 'assignment statements, cannot be an unpacking) and the ' - 'expression\n' - 'list, performs the binary operation specific to the type of ' - 'assignment\n' - 'on the two operands, and assigns the result to the original ' - 'target.\n' - 'The target is only evaluated once.\n' - '\n' - 'An augmented assignment expression like "x += 1" can be ' - 'rewritten as\n' - '"x = x + 1" to achieve a similar, but not exactly equal ' - 'effect. In the\n' - 'augmented version, "x" is only evaluated once. Also, when ' - 'possible,\n' - 'the actual operation is performed *in-place*, meaning that ' - 'rather than\n' - 'creating a new object and assigning that to the target, the ' - 'old object\n' - 'is modified instead.\n' - '\n' - 'Unlike normal assignments, augmented assignments evaluate ' - 'the left-\n' - 'hand side *before* evaluating the right-hand side. For ' - 'example, "a[i]\n' - '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' - 'performs\n' - 'the addition, and lastly, it writes the result back to ' - '"a[i]".\n' - '\n' - 'With the exception of assigning to tuples and multiple ' - 'targets in a\n' - 'single statement, the assignment done by augmented ' - 'assignment\n' - 'statements is handled the same way as normal assignments. ' - 'Similarly,\n' - 'with the exception of the possible *in-place* behavior, the ' - 'binary\n' - 'operation performed by augmented assignment is the same as ' - 'the normal\n' - 'binary operations.\n' - '\n' - 'For targets which are attribute references, the same *caveat ' - 'about\n' - 'class and instance attributes* applies as for regular ' - 'assignments.\n', - 'atom-identifiers': '\n' - 'Identifiers (Names)\n' - '*******************\n' - '\n' - 'An identifier occurring as an atom is a name. See ' - 'section\n' - '*Identifiers and keywords* for lexical definition and ' - 'section *Naming\n' - 'and binding* for documentation of naming and binding.\n' - '\n' - 'When the name is bound to an object, evaluation of the ' - 'atom yields\n' - 'that object. When a name is not bound, an attempt to ' - 'evaluate it\n' - 'raises a "NameError" exception.\n' - '\n' - '**Private name mangling:** When an identifier that ' - 'textually occurs in\n' - 'a class definition begins with two or more underscore ' - 'characters and\n' - 'does not end in two or more underscores, it is ' - 'considered a *private\n' - 'name* of that class. Private names are transformed to ' - 'a longer form\n' - 'before code is generated for them. The transformation ' - 'inserts the\n' - 'class name, with leading underscores removed and a ' - 'single underscore\n' - 'inserted, in front of the name. For example, the ' - 'identifier "__spam"\n' - 'occurring in a class named "Ham" will be transformed ' - 'to "_Ham__spam".\n' - 'This transformation is independent of the syntactical ' - 'context in which\n' - 'the identifier is used. If the transformed name is ' - 'extremely long\n' - '(longer than 255 characters), implementation defined ' - 'truncation may\n' - 'happen. If the class name consists only of ' - 'underscores, no\n' - 'transformation is done.\n', - 'atom-literals': '\n' - 'Literals\n' - '********\n' - '\n' - 'Python supports string and bytes literals and various ' - 'numeric\n' - 'literals:\n' - '\n' - ' literal ::= stringliteral | bytesliteral\n' - ' | integer | floatnumber | imagnumber\n' - '\n' - 'Evaluation of a literal yields an object of the given ' - 'type (string,\n' - 'bytes, integer, floating point number, complex number) ' - 'with the given\n' - 'value. The value may be approximated in the case of ' - 'floating point\n' - 'and imaginary (complex) literals. See section *Literals* ' - 'for details.\n' - '\n' - 'All literals correspond to immutable data types, and ' - 'hence the\n' - "object's identity is less important than its value. " - 'Multiple\n' - 'evaluations of literals with the same value (either the ' - 'same\n' - 'occurrence in the program text or a different occurrence) ' - 'may obtain\n' - 'the same object or a different object with the same ' - 'value.\n', - 'attribute-access': '\n' - 'Customizing attribute access\n' - '****************************\n' - '\n' - 'The following methods can be defined to customize the ' - 'meaning of\n' - 'attribute access (use of, assignment to, or deletion ' - 'of "x.name") for\n' - 'class instances.\n' - '\n' - 'object.__getattr__(self, name)\n' - '\n' - ' Called when an attribute lookup has not found the ' - 'attribute in the\n' - ' usual places (i.e. it is not an instance attribute ' - 'nor is it found\n' - ' in the class tree for "self"). "name" is the ' - 'attribute name. This\n' - ' method should return the (computed) attribute value ' - 'or raise an\n' - ' "AttributeError" exception.\n' - '\n' - ' Note that if the attribute is found through the ' - 'normal mechanism,\n' - ' "__getattr__()" is not called. (This is an ' - 'intentional asymmetry\n' - ' between "__getattr__()" and "__setattr__()".) This ' - 'is done both for\n' - ' efficiency reasons and because otherwise ' - '"__getattr__()" would have\n' - ' no way to access other attributes of the instance. ' - 'Note that at\n' - ' least for instance variables, you can fake total ' - 'control by not\n' - ' inserting any values in the instance attribute ' - 'dictionary (but\n' - ' instead inserting them in another object). See ' - 'the\n' - ' "__getattribute__()" method below for a way to ' - 'actually get total\n' - ' control over attribute access.\n' - '\n' - 'object.__getattribute__(self, name)\n' - '\n' - ' Called unconditionally to implement attribute ' - 'accesses for\n' - ' instances of the class. If the class also defines ' - '"__getattr__()",\n' - ' the latter will not be called unless ' - '"__getattribute__()" either\n' - ' calls it explicitly or raises an "AttributeError". ' - 'This method\n' - ' should return the (computed) attribute value or ' - 'raise an\n' - ' "AttributeError" exception. In order to avoid ' - 'infinite recursion in\n' - ' this method, its implementation should always call ' - 'the base class\n' - ' method with the same name to access any attributes ' - 'it needs, for\n' - ' example, "object.__getattribute__(self, name)".\n' - '\n' - ' Note: This method may still be bypassed when ' - 'looking up special\n' - ' methods as the result of implicit invocation via ' - 'language syntax\n' - ' or built-in functions. See *Special method ' - 'lookup*.\n' - '\n' - 'object.__setattr__(self, name, value)\n' - '\n' - ' Called when an attribute assignment is attempted. ' - 'This is called\n' - ' instead of the normal mechanism (i.e. store the ' - 'value in the\n' - ' instance dictionary). *name* is the attribute name, ' - '*value* is the\n' - ' value to be assigned to it.\n' - '\n' - ' If "__setattr__()" wants to assign to an instance ' - 'attribute, it\n' - ' should call the base class method with the same ' - 'name, for example,\n' - ' "object.__setattr__(self, name, value)".\n' - '\n' - 'object.__delattr__(self, name)\n' - '\n' - ' Like "__setattr__()" but for attribute deletion ' - 'instead of\n' - ' assignment. This should only be implemented if ' - '"del obj.name" is\n' - ' meaningful for the object.\n' - '\n' - 'object.__dir__(self)\n' - '\n' - ' Called when "dir()" is called on the object. A ' - 'sequence must be\n' - ' returned. "dir()" converts the returned sequence to ' - 'a list and\n' - ' sorts it.\n' - '\n' - '\n' - 'Implementing Descriptors\n' - '========================\n' - '\n' - 'The following methods only apply when an instance of ' - 'the class\n' - 'containing the method (a so-called *descriptor* class) ' - 'appears in an\n' - '*owner* class (the descriptor must be in either the ' - "owner's class\n" - 'dictionary or in the class dictionary for one of its ' - 'parents). In the\n' - 'examples below, "the attribute" refers to the ' - 'attribute whose name is\n' - "the key of the property in the owner class' " - '"__dict__".\n' - '\n' - 'object.__get__(self, instance, owner)\n' - '\n' - ' Called to get the attribute of the owner class ' - '(class attribute\n' - ' access) or of an instance of that class (instance ' - 'attribute\n' - ' access). *owner* is always the owner class, while ' - '*instance* is the\n' - ' instance that the attribute was accessed through, ' - 'or "None" when\n' - ' the attribute is accessed through the *owner*. ' - 'This method should\n' - ' return the (computed) attribute value or raise an ' - '"AttributeError"\n' - ' exception.\n' - '\n' - 'object.__set__(self, instance, value)\n' - '\n' - ' Called to set the attribute on an instance ' - '*instance* of the owner\n' - ' class to a new value, *value*.\n' - '\n' - 'object.__delete__(self, instance)\n' - '\n' - ' Called to delete the attribute on an instance ' - '*instance* of the\n' - ' owner class.\n' - '\n' - 'The attribute "__objclass__" is interpreted by the ' - '"inspect" module as\n' - 'specifying the class where this object was defined ' - '(setting this\n' - 'appropriately can assist in runtime introspection of ' - 'dynamic class\n' - 'attributes). For callables, it may indicate that an ' - 'instance of the\n' - 'given type (or a subclass) is expected or required as ' - 'the first\n' - 'positional argument (for example, CPython sets this ' - 'attribute for\n' - 'unbound methods that are implemented in C).\n' - '\n' - '\n' - 'Invoking Descriptors\n' - '====================\n' - '\n' - 'In general, a descriptor is an object attribute with ' - '"binding\n' - 'behavior", one whose attribute access has been ' - 'overridden by methods\n' - 'in the descriptor protocol: "__get__()", "__set__()", ' - 'and\n' - '"__delete__()". If any of those methods are defined ' - 'for an object, it\n' - 'is said to be a descriptor.\n' - '\n' - 'The default behavior for attribute access is to get, ' - 'set, or delete\n' - "the attribute from an object's dictionary. For " - 'instance, "a.x" has a\n' - 'lookup chain starting with "a.__dict__[\'x\']", then\n' - '"type(a).__dict__[\'x\']", and continuing through the ' - 'base classes of\n' - '"type(a)" excluding metaclasses.\n' - '\n' - 'However, if the looked-up value is an object defining ' - 'one of the\n' - 'descriptor methods, then Python may override the ' - 'default behavior and\n' - 'invoke the descriptor method instead. Where this ' - 'occurs in the\n' - 'precedence chain depends on which descriptor methods ' - 'were defined and\n' - 'how they were called.\n' - '\n' - 'The starting point for descriptor invocation is a ' - 'binding, "a.x". How\n' - 'the arguments are assembled depends on "a":\n' - '\n' - 'Direct Call\n' - ' The simplest and least common call is when user ' - 'code directly\n' - ' invokes a descriptor method: "x.__get__(a)".\n' - '\n' - 'Instance Binding\n' - ' If binding to an object instance, "a.x" is ' - 'transformed into the\n' - ' call: "type(a).__dict__[\'x\'].__get__(a, ' - 'type(a))".\n' - '\n' - 'Class Binding\n' - ' If binding to a class, "A.x" is transformed into ' - 'the call:\n' - ' "A.__dict__[\'x\'].__get__(None, A)".\n' - '\n' - 'Super Binding\n' - ' If "a" is an instance of "super", then the binding ' - '"super(B,\n' - ' obj).m()" searches "obj.__class__.__mro__" for the ' - 'base class "A"\n' - ' immediately preceding "B" and then invokes the ' - 'descriptor with the\n' - ' call: "A.__dict__[\'m\'].__get__(obj, ' - 'obj.__class__)".\n' - '\n' - 'For instance bindings, the precedence of descriptor ' - 'invocation depends\n' - 'on the which descriptor methods are defined. A ' - 'descriptor can define\n' - 'any combination of "__get__()", "__set__()" and ' - '"__delete__()". If it\n' - 'does not define "__get__()", then accessing the ' - 'attribute will return\n' - 'the descriptor object itself unless there is a value ' - "in the object's\n" - 'instance dictionary. If the descriptor defines ' - '"__set__()" and/or\n' - '"__delete__()", it is a data descriptor; if it defines ' - 'neither, it is\n' - 'a non-data descriptor. Normally, data descriptors ' - 'define both\n' - '"__get__()" and "__set__()", while non-data ' - 'descriptors have just the\n' - '"__get__()" method. Data descriptors with "__set__()" ' - 'and "__get__()"\n' - 'defined always override a redefinition in an instance ' - 'dictionary. In\n' - 'contrast, non-data descriptors can be overridden by ' - 'instances.\n' - '\n' - 'Python methods (including "staticmethod()" and ' - '"classmethod()") are\n' - 'implemented as non-data descriptors. Accordingly, ' - 'instances can\n' - 'redefine and override methods. This allows individual ' - 'instances to\n' - 'acquire behaviors that differ from other instances of ' - 'the same class.\n' - '\n' - 'The "property()" function is implemented as a data ' - 'descriptor.\n' - 'Accordingly, instances cannot override the behavior of ' - 'a property.\n' - '\n' - '\n' - '__slots__\n' - '=========\n' - '\n' - 'By default, instances of classes have a dictionary for ' - 'attribute\n' - 'storage. This wastes space for objects having very ' - 'few instance\n' - 'variables. The space consumption can become acute ' - 'when creating large\n' - 'numbers of instances.\n' - '\n' - 'The default can be overridden by defining *__slots__* ' - 'in a class\n' - 'definition. The *__slots__* declaration takes a ' - 'sequence of instance\n' - 'variables and reserves just enough space in each ' - 'instance to hold a\n' - 'value for each variable. Space is saved because ' - '*__dict__* is not\n' - 'created for each instance.\n' - '\n' - 'object.__slots__\n' - '\n' - ' This class variable can be assigned a string, ' - 'iterable, or sequence\n' - ' of strings with variable names used by instances. ' - '*__slots__*\n' - ' reserves space for the declared variables and ' - 'prevents the\n' - ' automatic creation of *__dict__* and *__weakref__* ' - 'for each\n' - ' instance.\n' - '\n' - '\n' - 'Notes on using *__slots__*\n' - '--------------------------\n' - '\n' - '* When inheriting from a class without *__slots__*, ' - 'the *__dict__*\n' - ' attribute of that class will always be accessible, ' - 'so a *__slots__*\n' - ' definition in the subclass is meaningless.\n' - '\n' - '* Without a *__dict__* variable, instances cannot be ' - 'assigned new\n' - ' variables not listed in the *__slots__* definition. ' - 'Attempts to\n' - ' assign to an unlisted variable name raises ' - '"AttributeError". If\n' - ' dynamic assignment of new variables is desired, then ' - 'add\n' - ' "\'__dict__\'" to the sequence of strings in the ' - '*__slots__*\n' - ' declaration.\n' - '\n' - '* Without a *__weakref__* variable for each instance, ' - 'classes\n' - ' defining *__slots__* do not support weak references ' - 'to its\n' - ' instances. If weak reference support is needed, then ' - 'add\n' - ' "\'__weakref__\'" to the sequence of strings in the ' - '*__slots__*\n' - ' declaration.\n' - '\n' - '* *__slots__* are implemented at the class level by ' - 'creating\n' - ' descriptors (*Implementing Descriptors*) for each ' - 'variable name. As\n' - ' a result, class attributes cannot be used to set ' - 'default values for\n' - ' instance variables defined by *__slots__*; ' - 'otherwise, the class\n' - ' attribute would overwrite the descriptor ' - 'assignment.\n' - '\n' - '* The action of a *__slots__* declaration is limited ' - 'to the class\n' - ' where it is defined. As a result, subclasses will ' - 'have a *__dict__*\n' - ' unless they also define *__slots__* (which must only ' - 'contain names\n' - ' of any *additional* slots).\n' - '\n' - '* If a class defines a slot also defined in a base ' - 'class, the\n' - ' instance variable defined by the base class slot is ' - 'inaccessible\n' - ' (except by retrieving its descriptor directly from ' - 'the base class).\n' - ' This renders the meaning of the program undefined. ' - 'In the future, a\n' - ' check may be added to prevent this.\n' - '\n' - '* Nonempty *__slots__* does not work for classes ' - 'derived from\n' - ' "variable-length" built-in types such as "int", ' - '"bytes" and "tuple".\n' - '\n' - '* Any non-string iterable may be assigned to ' - '*__slots__*. Mappings\n' - ' may also be used; however, in the future, special ' - 'meaning may be\n' - ' assigned to the values corresponding to each key.\n' - '\n' - '* *__class__* assignment works only if both classes ' - 'have the same\n' - ' *__slots__*.\n', - 'attribute-references': '\n' - 'Attribute references\n' - '********************\n' - '\n' - 'An attribute reference is a primary followed by a ' - 'period and a name:\n' - '\n' - ' attributeref ::= primary "." identifier\n' - '\n' - 'The primary must evaluate to an object of a type ' - 'that supports\n' - 'attribute references, which most objects do. This ' - 'object is then\n' - 'asked to produce the attribute whose name is the ' - 'identifier. This\n' - 'production can be customized by overriding the ' - '"__getattr__()" method.\n' - 'If this attribute is not available, the exception ' - '"AttributeError" is\n' - 'raised. Otherwise, the type and value of the ' - 'object produced is\n' - 'determined by the object. Multiple evaluations of ' - 'the same attribute\n' - 'reference may yield different objects.\n', - 'augassign': '\n' - 'Augmented assignment statements\n' - '*******************************\n' - '\n' - 'Augmented assignment is the combination, in a single ' - 'statement, of a\n' - 'binary operation and an assignment statement:\n' - '\n' - ' augmented_assignment_stmt ::= augtarget augop ' - '(expression_list | yield_expression)\n' - ' augtarget ::= identifier | attributeref | ' - 'subscription | slicing\n' - ' augop ::= "+=" | "-=" | "*=" | "/=" | ' - '"//=" | "%=" | "**="\n' - ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' - '\n' - '(See section *Primaries* for the syntax definitions of the ' - 'last three\n' - 'symbols.)\n' - '\n' - 'An augmented assignment evaluates the target (which, unlike ' - 'normal\n' - 'assignment statements, cannot be an unpacking) and the ' - 'expression\n' - 'list, performs the binary operation specific to the type of ' - 'assignment\n' - 'on the two operands, and assigns the result to the original ' - 'target.\n' - 'The target is only evaluated once.\n' - '\n' - 'An augmented assignment expression like "x += 1" can be ' - 'rewritten as\n' - '"x = x + 1" to achieve a similar, but not exactly equal ' - 'effect. In the\n' - 'augmented version, "x" is only evaluated once. Also, when ' - 'possible,\n' - 'the actual operation is performed *in-place*, meaning that ' - 'rather than\n' - 'creating a new object and assigning that to the target, the ' - 'old object\n' - 'is modified instead.\n' - '\n' - 'Unlike normal assignments, augmented assignments evaluate the ' - 'left-\n' - 'hand side *before* evaluating the right-hand side. For ' - 'example, "a[i]\n' - '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' - 'performs\n' - 'the addition, and lastly, it writes the result back to ' - '"a[i]".\n' - '\n' - 'With the exception of assigning to tuples and multiple ' - 'targets in a\n' - 'single statement, the assignment done by augmented ' - 'assignment\n' - 'statements is handled the same way as normal assignments. ' - 'Similarly,\n' - 'with the exception of the possible *in-place* behavior, the ' - 'binary\n' - 'operation performed by augmented assignment is the same as ' - 'the normal\n' - 'binary operations.\n' - '\n' - 'For targets which are attribute references, the same *caveat ' - 'about\n' - 'class and instance attributes* applies as for regular ' - 'assignments.\n', - 'binary': '\n' - 'Binary arithmetic operations\n' - '****************************\n' - '\n' - 'The binary arithmetic operations have the conventional priority\n' - 'levels. Note that some of these operations also apply to ' - 'certain non-\n' - 'numeric types. Apart from the power operator, there are only ' - 'two\n' - 'levels, one for multiplicative operators and one for additive\n' - 'operators:\n' - '\n' - ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "//" u_expr | ' - 'm_expr "/" u_expr\n' - ' | m_expr "%" u_expr\n' - ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' - '\n' - 'The "*" (multiplication) operator yields the product of its ' - 'arguments.\n' - 'The arguments must either both be numbers, or one argument must ' - 'be an\n' - 'integer and the other must be a sequence. In the former case, ' - 'the\n' - 'numbers are converted to a common type and then multiplied ' - 'together.\n' - 'In the latter case, sequence repetition is performed; a ' - 'negative\n' - 'repetition factor yields an empty sequence.\n' - '\n' - 'The "/" (division) and "//" (floor division) operators yield ' - 'the\n' - 'quotient of their arguments. The numeric arguments are first\n' - 'converted to a common type. Division of integers yields a float, ' - 'while\n' - 'floor division of integers results in an integer; the result is ' - 'that\n' - "of mathematical division with the 'floor' function applied to " - 'the\n' - 'result. Division by zero raises the "ZeroDivisionError" ' - 'exception.\n' - '\n' - 'The "%" (modulo) operator yields the remainder from the division ' - 'of\n' - 'the first argument by the second. The numeric arguments are ' - 'first\n' - 'converted to a common type. A zero right argument raises the\n' - '"ZeroDivisionError" exception. The arguments may be floating ' - 'point\n' - 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals ' - '"4*0.7 +\n' - '0.34".) The modulo operator always yields a result with the ' - 'same sign\n' - 'as its second operand (or zero); the absolute value of the ' - 'result is\n' - 'strictly smaller than the absolute value of the second operand ' - '[1].\n' - '\n' - 'The floor division and modulo operators are connected by the ' - 'following\n' - 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo ' - 'are also\n' - 'connected with the built-in function "divmod()": "divmod(x, y) ' - '==\n' - '(x//y, x%y)". [2].\n' - '\n' - 'In addition to performing the modulo operation on numbers, the ' - '"%"\n' - 'operator is also overloaded by string objects to perform ' - 'old-style\n' - 'string formatting (also known as interpolation). The syntax ' - 'for\n' - 'string formatting is described in the Python Library Reference,\n' - 'section *printf-style String Formatting*.\n' - '\n' - 'The floor division operator, the modulo operator, and the ' - '"divmod()"\n' - 'function are not defined for complex numbers. Instead, convert ' - 'to a\n' - 'floating point number using the "abs()" function if ' - 'appropriate.\n' - '\n' - 'The "+" (addition) operator yields the sum of its arguments. ' - 'The\n' - 'arguments must either both be numbers or both be sequences of ' - 'the same\n' - 'type. In the former case, the numbers are converted to a common ' - 'type\n' - 'and then added together. In the latter case, the sequences are\n' - 'concatenated.\n' - '\n' - 'The "-" (subtraction) operator yields the difference of its ' - 'arguments.\n' - 'The numeric arguments are first converted to a common type.\n', - 'bitwise': '\n' - 'Binary bitwise operations\n' - '*************************\n' - '\n' - 'Each of the three bitwise operations has a different priority ' - 'level:\n' - '\n' - ' and_expr ::= shift_expr | and_expr "&" shift_expr\n' - ' xor_expr ::= and_expr | xor_expr "^" and_expr\n' - ' or_expr ::= xor_expr | or_expr "|" xor_expr\n' - '\n' - 'The "&" operator yields the bitwise AND of its arguments, which ' - 'must\n' - 'be integers.\n' - '\n' - 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' - 'arguments, which must be integers.\n' - '\n' - 'The "|" operator yields the bitwise (inclusive) OR of its ' - 'arguments,\n' - 'which must be integers.\n', - 'bltin-code-objects': '\n' - 'Code Objects\n' - '************\n' - '\n' - 'Code objects are used by the implementation to ' - 'represent "pseudo-\n' - 'compiled" executable Python code such as a function ' - 'body. They differ\n' - "from function objects because they don't contain a " - 'reference to their\n' - 'global execution environment. Code objects are ' - 'returned by the built-\n' - 'in "compile()" function and can be extracted from ' - 'function objects\n' - 'through their "__code__" attribute. See also the ' - '"code" module.\n' - '\n' - 'A code object can be executed or evaluated by ' - 'passing it (instead of a\n' - 'source string) to the "exec()" or "eval()" built-in ' - 'functions.\n' - '\n' - 'See *The standard type hierarchy* for more ' - 'information.\n', - 'bltin-ellipsis-object': '\n' - 'The Ellipsis Object\n' - '*******************\n' - '\n' - 'This object is commonly used by slicing (see ' - '*Slicings*). It supports\n' - 'no special operations. There is exactly one ' - 'ellipsis object, named\n' - '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' - 'produces the\n' - '"Ellipsis" singleton.\n' - '\n' - 'It is written as "Ellipsis" or "...".\n', - 'bltin-null-object': '\n' - 'The Null Object\n' - '***************\n' - '\n' - "This object is returned by functions that don't " - 'explicitly return a\n' - 'value. It supports no special operations. There is ' - 'exactly one null\n' - 'object, named "None" (a built-in name). ' - '"type(None)()" produces the\n' - 'same singleton.\n' - '\n' - 'It is written as "None".\n', - 'bltin-type-objects': '\n' - 'Type Objects\n' - '************\n' - '\n' - 'Type objects represent the various object types. An ' - "object's type is\n" - 'accessed by the built-in function "type()". There ' - 'are no special\n' - 'operations on types. The standard module "types" ' - 'defines names for\n' - 'all standard built-in types.\n' - '\n' - 'Types are written like this: "".\n', - 'booleans': '\n' - 'Boolean operations\n' - '******************\n' - '\n' - ' or_test ::= and_test | or_test "or" and_test\n' - ' and_test ::= not_test | and_test "and" not_test\n' - ' not_test ::= comparison | "not" not_test\n' - '\n' - 'In the context of Boolean operations, and also when ' - 'expressions are\n' - 'used by control flow statements, the following values are ' - 'interpreted\n' - 'as false: "False", "None", numeric zero of all types, and ' - 'empty\n' - 'strings and containers (including strings, tuples, lists,\n' - 'dictionaries, sets and frozensets). All other values are ' - 'interpreted\n' - 'as true. User-defined objects can customize their truth value ' - 'by\n' - 'providing a "__bool__()" method.\n' - '\n' - 'The operator "not" yields "True" if its argument is false, ' - '"False"\n' - 'otherwise.\n' - '\n' - 'The expression "x and y" first evaluates *x*; if *x* is false, ' - 'its\n' - 'value is returned; otherwise, *y* is evaluated and the ' - 'resulting value\n' - 'is returned.\n' - '\n' - 'The expression "x or y" first evaluates *x*; if *x* is true, ' - 'its value\n' - 'is returned; otherwise, *y* is evaluated and the resulting ' - 'value is\n' - 'returned.\n' - '\n' - '(Note that neither "and" nor "or" restrict the value and type ' - 'they\n' - 'return to "False" and "True", but rather return the last ' - 'evaluated\n' - 'argument. This is sometimes useful, e.g., if "s" is a string ' - 'that\n' - 'should be replaced by a default value if it is empty, the ' - 'expression\n' - '"s or \'foo\'" yields the desired value. Because "not" has to ' - 'create a\n' - 'new value, it returns a boolean value regardless of the type ' - 'of its\n' - 'argument (for example, "not \'foo\'" produces "False" rather ' - 'than "\'\'".)\n', - 'break': '\n' - 'The "break" statement\n' - '*********************\n' - '\n' - ' break_stmt ::= "break"\n' - '\n' - '"break" may only occur syntactically nested in a "for" or ' - '"while"\n' - 'loop, but not nested in a function or class definition within ' - 'that\n' - 'loop.\n' - '\n' - 'It terminates the nearest enclosing loop, skipping the optional ' - '"else"\n' - 'clause if the loop has one.\n' - '\n' - 'If a "for" loop is terminated by "break", the loop control ' - 'target\n' - 'keeps its current value.\n' - '\n' - 'When "break" passes control out of a "try" statement with a ' - '"finally"\n' - 'clause, that "finally" clause is executed before really leaving ' - 'the\n' - 'loop.\n', - 'callable-types': '\n' - 'Emulating callable objects\n' - '**************************\n' - '\n' - 'object.__call__(self[, args...])\n' - '\n' - ' Called when the instance is "called" as a function; ' - 'if this method\n' - ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' - ' "x.__call__(arg1, arg2, ...)".\n', - 'calls': '\n' - 'Calls\n' - '*****\n' - '\n' - 'A call calls a callable object (e.g., a *function*) with a ' - 'possibly\n' - 'empty series of *arguments*:\n' - '\n' - ' call ::= primary "(" [argument_list [","] | ' - 'comprehension] ")"\n' - ' argument_list ::= positional_arguments ["," ' - 'keyword_arguments]\n' - ' ["," "*" expression] ["," ' - 'keyword_arguments]\n' - ' ["," "**" expression]\n' - ' | keyword_arguments ["," "*" expression]\n' - ' ["," keyword_arguments] ["," "**" ' - 'expression]\n' - ' | "*" expression ["," keyword_arguments] ' - '["," "**" expression]\n' - ' | "**" expression\n' - ' positional_arguments ::= expression ("," expression)*\n' - ' keyword_arguments ::= keyword_item ("," keyword_item)*\n' - ' keyword_item ::= identifier "=" expression\n' - '\n' - 'An optional trailing comma may be present after the positional ' - 'and\n' - 'keyword arguments but does not affect the semantics.\n' - '\n' - 'The primary must evaluate to a callable object (user-defined\n' - 'functions, built-in functions, methods of built-in objects, ' - 'class\n' - 'objects, methods of class instances, and all objects having a\n' - '"__call__()" method are callable). All argument expressions are\n' - 'evaluated before the call is attempted. Please refer to section\n' - '*Function definitions* for the syntax of formal *parameter* ' - 'lists.\n' - '\n' - 'If keyword arguments are present, they are first converted to\n' - 'positional arguments, as follows. First, a list of unfilled ' - 'slots is\n' - 'created for the formal parameters. If there are N positional\n' - 'arguments, they are placed in the first N slots. Next, for each\n' - 'keyword argument, the identifier is used to determine the\n' - 'corresponding slot (if the identifier is the same as the first ' - 'formal\n' - 'parameter name, the first slot is used, and so on). If the slot ' - 'is\n' - 'already filled, a "TypeError" exception is raised. Otherwise, ' - 'the\n' - 'value of the argument is placed in the slot, filling it (even if ' - 'the\n' - 'expression is "None", it fills the slot). When all arguments ' - 'have\n' - 'been processed, the slots that are still unfilled are filled with ' - 'the\n' - 'corresponding default value from the function definition. ' - '(Default\n' - 'values are calculated, once, when the function is defined; thus, ' - 'a\n' - 'mutable object such as a list or dictionary used as default value ' - 'will\n' - "be shared by all calls that don't specify an argument value for " - 'the\n' - 'corresponding slot; this should usually be avoided.) If there ' - 'are any\n' - 'unfilled slots for which no default value is specified, a ' - '"TypeError"\n' - 'exception is raised. Otherwise, the list of filled slots is used ' - 'as\n' - 'the argument list for the call.\n' - '\n' - '**CPython implementation detail:** An implementation may provide\n' - 'built-in functions whose positional parameters do not have names, ' - 'even\n' - "if they are 'named' for the purpose of documentation, and which\n" - 'therefore cannot be supplied by keyword. In CPython, this is the ' - 'case\n' - 'for functions implemented in C that use "PyArg_ParseTuple()" to ' - 'parse\n' - 'their arguments.\n' - '\n' - 'If there are more positional arguments than there are formal ' - 'parameter\n' - 'slots, a "TypeError" exception is raised, unless a formal ' - 'parameter\n' - 'using the syntax "*identifier" is present; in this case, that ' - 'formal\n' - 'parameter receives a tuple containing the excess positional ' - 'arguments\n' - '(or an empty tuple if there were no excess positional ' - 'arguments).\n' - '\n' - 'If any keyword argument does not correspond to a formal ' - 'parameter\n' - 'name, a "TypeError" exception is raised, unless a formal ' - 'parameter\n' - 'using the syntax "**identifier" is present; in this case, that ' - 'formal\n' - 'parameter receives a dictionary containing the excess keyword\n' - 'arguments (using the keywords as keys and the argument values as\n' - 'corresponding values), or a (new) empty dictionary if there were ' - 'no\n' - 'excess keyword arguments.\n' - '\n' - 'If the syntax "*expression" appears in the function call, ' - '"expression"\n' - 'must evaluate to an iterable. Elements from this iterable are ' - 'treated\n' - 'as if they were additional positional arguments; if there are\n' - 'positional arguments *x1*, ..., *xN*, and "expression" evaluates ' - 'to a\n' - 'sequence *y1*, ..., *yM*, this is equivalent to a call with M+N\n' - 'positional arguments *x1*, ..., *xN*, *y1*, ..., *yM*.\n' - '\n' - 'A consequence of this is that although the "*expression" syntax ' - 'may\n' - 'appear *after* some keyword arguments, it is processed *before* ' - 'the\n' - 'keyword arguments (and the "**expression" argument, if any -- ' - 'see\n' - 'below). So:\n' - '\n' - ' >>> def f(a, b):\n' - ' ... print(a, b)\n' - ' ...\n' - ' >>> f(b=1, *(2,))\n' - ' 2 1\n' - ' >>> f(a=1, *(2,))\n' - ' Traceback (most recent call last):\n' - ' File "", line 1, in ?\n' - " TypeError: f() got multiple values for keyword argument 'a'\n" - ' >>> f(1, *(2,))\n' - ' 1 2\n' - '\n' - 'It is unusual for both keyword arguments and the "*expression" ' - 'syntax\n' - 'to be used in the same call, so in practice this confusion does ' - 'not\n' - 'arise.\n' - '\n' - 'If the syntax "**expression" appears in the function call,\n' - '"expression" must evaluate to a mapping, the contents of which ' - 'are\n' - 'treated as additional keyword arguments. In the case of a ' - 'keyword\n' - 'appearing in both "expression" and as an explicit keyword ' - 'argument, a\n' - '"TypeError" exception is raised.\n' - '\n' - 'Formal parameters using the syntax "*identifier" or ' - '"**identifier"\n' - 'cannot be used as positional argument slots or as keyword ' - 'argument\n' - 'names.\n' - '\n' - 'A call always returns some value, possibly "None", unless it ' - 'raises an\n' - 'exception. How this value is computed depends on the type of ' - 'the\n' - 'callable object.\n' - '\n' - 'If it is---\n' - '\n' - 'a user-defined function:\n' - ' The code block for the function is executed, passing it the\n' - ' argument list. The first thing the code block will do is bind ' - 'the\n' - ' formal parameters to the arguments; this is described in ' - 'section\n' - ' *Function definitions*. When the code block executes a ' - '"return"\n' - ' statement, this specifies the return value of the function ' - 'call.\n' - '\n' - 'a built-in function or method:\n' - ' The result is up to the interpreter; see *Built-in Functions* ' - 'for\n' - ' the descriptions of built-in functions and methods.\n' - '\n' - 'a class object:\n' - ' A new instance of that class is returned.\n' - '\n' - 'a class instance method:\n' - ' The corresponding user-defined function is called, with an ' - 'argument\n' - ' list that is one longer than the argument list of the call: ' - 'the\n' - ' instance becomes the first argument.\n' - '\n' - 'a class instance:\n' - ' The class must define a "__call__()" method; the effect is ' - 'then the\n' - ' same as if that method was called.\n', - 'class': '\n' - 'Class definitions\n' - '*****************\n' - '\n' - 'A class definition defines a class object (see section *The ' - 'standard\n' - 'type hierarchy*):\n' - '\n' - ' classdef ::= [decorators] "class" classname [inheritance] ' - '":" suite\n' - ' inheritance ::= "(" [parameter_list] ")"\n' - ' classname ::= identifier\n' - '\n' - 'A class definition is an executable statement. The inheritance ' - 'list\n' - 'usually gives a list of base classes (see *Customizing class ' - 'creation*\n' - 'for more advanced uses), so each item in the list should evaluate ' - 'to a\n' - 'class object which allows subclassing. Classes without an ' - 'inheritance\n' - 'list inherit, by default, from the base class "object"; hence,\n' - '\n' - ' class Foo:\n' - ' pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' class Foo(object):\n' - ' pass\n' - '\n' - "The class's suite is then executed in a new execution frame (see\n" - '*Naming and binding*), using a newly created local namespace and ' - 'the\n' - 'original global namespace. (Usually, the suite contains mostly\n' - "function definitions.) When the class's suite finishes " - 'execution, its\n' - 'execution frame is discarded but its local namespace is saved. ' - '[4] A\n' - 'class object is then created using the inheritance list for the ' - 'base\n' - 'classes and the saved local namespace for the attribute ' - 'dictionary.\n' - 'The class name is bound to this class object in the original ' - 'local\n' - 'namespace.\n' - '\n' - 'Class creation can be customized heavily using *metaclasses*.\n' - '\n' - 'Classes can also be decorated: just like when decorating ' - 'functions,\n' - '\n' - ' @f1(arg)\n' - ' @f2\n' - ' class Foo: pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' class Foo: pass\n' - ' Foo = f1(arg)(f2(Foo))\n' - '\n' - 'The evaluation rules for the decorator expressions are the same ' - 'as for\n' - 'function decorators. The result must be a class object, which is ' - 'then\n' - 'bound to the class name.\n' - '\n' - "**Programmer's note:** Variables defined in the class definition " - 'are\n' - 'class attributes; they are shared by instances. Instance ' - 'attributes\n' - 'can be set in a method with "self.name = value". Both class and\n' - 'instance attributes are accessible through the notation ' - '""self.name"",\n' - 'and an instance attribute hides a class attribute with the same ' - 'name\n' - 'when accessed in this way. Class attributes can be used as ' - 'defaults\n' - 'for instance attributes, but using mutable values there can lead ' - 'to\n' - 'unexpected results. *Descriptors* can be used to create ' - 'instance\n' - 'variables with different implementation details.\n' - '\n' - 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n' - ' Class Decorators\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] The exception is propagated to the invocation stack unless\n' - ' there is a "finally" clause which happens to raise another\n' - ' exception. That new exception causes the old one to be lost.\n' - '\n' - '[2] Currently, control "flows off the end" except in the case of\n' - ' an exception or the execution of a "return", "continue", or\n' - ' "break" statement.\n' - '\n' - '[3] A string literal appearing as the first statement in the\n' - ' function body is transformed into the function\'s "__doc__"\n' - " attribute and therefore the function's *docstring*.\n" - '\n' - '[4] A string literal appearing as the first statement in the ' - 'class\n' - ' body is transformed into the namespace\'s "__doc__" item and\n' - " therefore the class's *docstring*.\n", - 'comparisons': '\n' - 'Comparisons\n' - '***********\n' - '\n' - 'Unlike C, all comparison operations in Python have the same ' - 'priority,\n' - 'which is lower than that of any arithmetic, shifting or ' - 'bitwise\n' - 'operation. Also unlike C, expressions like "a < b < c" ' - 'have the\n' - 'interpretation that is conventional in mathematics:\n' - '\n' - ' comparison ::= or_expr ( comp_operator or_expr )*\n' - ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' - ' | "is" ["not"] | ["not"] "in"\n' - '\n' - 'Comparisons yield boolean values: "True" or "False".\n' - '\n' - 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" ' - 'is\n' - 'equivalent to "x < y and y <= z", except that "y" is ' - 'evaluated only\n' - 'once (but in both cases "z" is not evaluated at all when "x ' - '< y" is\n' - 'found to be false).\n' - '\n' - 'Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions ' - 'and *op1*,\n' - '*op2*, ..., *opN* are comparison operators, then "a op1 b ' - 'op2 c ... y\n' - 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' - 'z", except\n' - 'that each expression is evaluated at most once.\n' - '\n' - 'Note that "a op1 b op2 c" doesn\'t imply any kind of ' - 'comparison between\n' - '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' - '(though\n' - 'perhaps not pretty).\n' - '\n' - '\n' - 'Value comparisons\n' - '=================\n' - '\n' - 'The operators "<", ">", "==", ">=", "<=", and "!=" compare ' - 'the values\n' - 'of two objects. The objects do not need to have the same ' - 'type.\n' - '\n' - 'Chapter *Objects, values and types* states that objects ' - 'have a value\n' - '(in addition to type and identity). The value of an object ' - 'is a\n' - 'rather abstract notion in Python: For example, there is no ' - 'canonical\n' - "access method for an object's value. Also, there is no " - 'requirement\n' - 'that the value of an object should be constructed in a ' - 'particular way,\n' - 'e.g. comprised of all its data attributes. Comparison ' - 'operators\n' - 'implement a particular notion of what the value of an ' - 'object is. One\n' - 'can think of them as defining the value of an object ' - 'indirectly, by\n' - 'means of their comparison implementation.\n' - '\n' - 'Because all types are (direct or indirect) subtypes of ' - '"object", they\n' - 'inherit the default comparison behavior from "object". ' - 'Types can\n' - 'customize their comparison behavior by implementing *rich ' - 'comparison\n' - 'methods* like "__lt__()", described in *Basic ' - 'customization*.\n' - '\n' - 'The default behavior for equality comparison ("==" and ' - '"!=") is based\n' - 'on the identity of the objects. Hence, equality comparison ' - 'of\n' - 'instances with the same identity results in equality, and ' - 'equality\n' - 'comparison of instances with different identities results ' - 'in\n' - 'inequality. A motivation for this default behavior is the ' - 'desire that\n' - 'all objects should be reflexive (i.e. "x is y" implies "x ' - '== y").\n' - '\n' - 'A default order comparison ("<", ">", "<=", and ">=") is ' - 'not provided;\n' - 'an attempt raises "TypeError". A motivation for this ' - 'default behavior\n' - 'is the lack of a similar invariant as for equality.\n' - '\n' - 'The behavior of the default equality comparison, that ' - 'instances with\n' - 'different identities are always unequal, may be in contrast ' - 'to what\n' - 'types will need that have a sensible definition of object ' - 'value and\n' - 'value-based equality. Such types will need to customize ' - 'their\n' - 'comparison behavior, and in fact, a number of built-in ' - 'types have done\n' - 'that.\n' - '\n' - 'The following list describes the comparison behavior of the ' - 'most\n' - 'important built-in types.\n' - '\n' - '* Numbers of built-in numeric types (*Numeric Types --- ' - 'int, float,\n' - ' complex*) and of the standard library types ' - '"fractions.Fraction" and\n' - ' "decimal.Decimal" can be compared within and across their ' - 'types,\n' - ' with the restriction that complex numbers do not support ' - 'order\n' - ' comparison. Within the limits of the types involved, ' - 'they compare\n' - ' mathematically (algorithmically) correct without loss of ' - 'precision.\n' - '\n' - ' The not-a-number values "float(\'NaN\')" and ' - '"Decimal(\'NaN\')" are\n' - ' special. They are identical to themselves ("x is x" is ' - 'true) but\n' - ' are not equal to themselves ("x == x" is false). ' - 'Additionally,\n' - ' comparing any number to a not-a-number value will return ' - '"False".\n' - ' For example, both "3 < float(\'NaN\')" and ' - '"float(\'NaN\') < 3" will\n' - ' return "False".\n' - '\n' - '* Binary sequences (instances of "bytes" or "bytearray") ' - 'can be\n' - ' compared within and across their types. They compare\n' - ' lexicographically using the numeric values of their ' - 'elements.\n' - '\n' - '* Strings (instances of "str") compare lexicographically ' - 'using the\n' - ' numerical Unicode code points (the result of the built-in ' - 'function\n' - ' "ord()") of their characters. [3]\n' - '\n' - ' Strings and binary sequences cannot be directly ' - 'compared.\n' - '\n' - '* Sequences (instances of "tuple", "list", or "range") can ' - 'be\n' - ' compared only within each of their types, with the ' - 'restriction that\n' - ' ranges do not support order comparison. Equality ' - 'comparison across\n' - ' these types results in unequality, and ordering ' - 'comparison across\n' - ' these types raises "TypeError".\n' - '\n' - ' Sequences compare lexicographically using comparison of\n' - ' corresponding elements, whereby reflexivity of the ' - 'elements is\n' - ' enforced.\n' - '\n' - ' In enforcing reflexivity of elements, the comparison of ' - 'collections\n' - ' assumes that for a collection element "x", "x == x" is ' - 'always true.\n' - ' Based on that assumption, element identity is compared ' - 'first, and\n' - ' element comparison is performed only for distinct ' - 'elements. This\n' - ' approach yields the same result as a strict element ' - 'comparison\n' - ' would, if the compared elements are reflexive. For ' - 'non-reflexive\n' - ' elements, the result is different than for strict ' - 'element\n' - ' comparison, and may be surprising: The non-reflexive ' - 'not-a-number\n' - ' values for example result in the following comparison ' - 'behavior when\n' - ' used in a list:\n' - '\n' - " >>> nan = float('NaN')\n" - ' >>> nan is nan\n' - ' True\n' - ' >>> nan == nan\n' - ' False <-- the defined non-reflexive ' - 'behavior of NaN\n' - ' >>> [nan] == [nan]\n' - ' True <-- list enforces reflexivity ' - 'and tests identity first\n' - '\n' - ' Lexicographical comparison between built-in collections ' - 'works as\n' - ' follows:\n' - '\n' - ' * For two collections to compare equal, they must be of ' - 'the same\n' - ' type, have the same length, and each pair of ' - 'corresponding\n' - ' elements must compare equal (for example, "[1,2] == ' - '(1,2)" is\n' - ' false because the type is not the same).\n' - '\n' - ' * Collections that support order comparison are ordered ' - 'the same\n' - ' as their first unequal elements (for example, "[1,2,x] ' - '<= [1,2,y]"\n' - ' has the same value as "x <= y"). If a corresponding ' - 'element does\n' - ' not exist, the shorter collection is ordered first (for ' - 'example,\n' - ' "[1,2] < [1,2,3]" is true).\n' - '\n' - '* Mappings (instances of "dict") compare equal if and only ' - 'if they\n' - ' have equal *(key, value)* pairs. Equality comparison of ' - 'the keys and\n' - ' elements enforces reflexivity.\n' - '\n' - ' Order comparisons ("<", ">", "<=", and ">=") raise ' - '"TypeError".\n' - '\n' - '* Sets (instances of "set" or "frozenset") can be compared ' - 'within\n' - ' and across their types.\n' - '\n' - ' They define order comparison operators to mean subset and ' - 'superset\n' - ' tests. Those relations do not define total orderings ' - '(for example,\n' - ' the two sets "{1,2}" and "{2,3}" are not equal, nor ' - 'subsets of one\n' - ' another, nor supersets of one another). Accordingly, ' - 'sets are not\n' - ' appropriate arguments for functions which depend on total ' - 'ordering\n' - ' (for example, "min()", "max()", and "sorted()" produce ' - 'undefined\n' - ' results given a list of sets as inputs).\n' - '\n' - ' Comparison of sets enforces reflexivity of its elements.\n' - '\n' - '* Most other built-in types have no comparison methods ' - 'implemented,\n' - ' so they inherit the default comparison behavior.\n' - '\n' - 'User-defined classes that customize their comparison ' - 'behavior should\n' - 'follow some consistency rules, if possible:\n' - '\n' - '* Equality comparison should be reflexive. In other words, ' - 'identical\n' - ' objects should compare equal:\n' - '\n' - ' "x is y" implies "x == y"\n' - '\n' - '* Comparison should be symmetric. In other words, the ' - 'following\n' - ' expressions should have the same result:\n' - '\n' - ' "x == y" and "y == x"\n' - '\n' - ' "x != y" and "y != x"\n' - '\n' - ' "x < y" and "y > x"\n' - '\n' - ' "x <= y" and "y >= x"\n' - '\n' - '* Comparison should be transitive. The following ' - '(non-exhaustive)\n' - ' examples illustrate that:\n' - '\n' - ' "x > y and y > z" implies "x > z"\n' - '\n' - ' "x < y and y <= z" implies "x < z"\n' - '\n' - '* Inverse comparison should result in the boolean negation. ' - 'In other\n' - ' words, the following expressions should have the same ' - 'result:\n' - '\n' - ' "x == y" and "not x != y"\n' - '\n' - ' "x < y" and "not x >= y" (for total ordering)\n' - '\n' - ' "x > y" and "not x <= y" (for total ordering)\n' - '\n' - ' The last two expressions apply to totally ordered ' - 'collections (e.g.\n' - ' to sequences, but not to sets or mappings). See also the\n' - ' "total_ordering()" decorator.\n' - '\n' - 'Python does not enforce these consistency rules. In fact, ' - 'the\n' - 'not-a-number values are an example for not following these ' - 'rules.\n' - '\n' - '\n' - 'Membership test operations\n' - '==========================\n' - '\n' - 'The operators "in" and "not in" test for membership. "x in ' - 's"\n' - 'evaluates to true if *x* is a member of *s*, and false ' - 'otherwise. "x\n' - 'not in s" returns the negation of "x in s". All built-in ' - 'sequences\n' - 'and set types support this as well as dictionary, for which ' - '"in" tests\n' - 'whether the dictionary has a given key. For container types ' - 'such as\n' - 'list, tuple, set, frozenset, dict, or collections.deque, ' - 'the\n' - 'expression "x in y" is equivalent to "any(x is e or x == e ' - 'for e in\n' - 'y)".\n' - '\n' - 'For the string and bytes types, "x in y" is true if and ' - 'only if *x* is\n' - 'a substring of *y*. An equivalent test is "y.find(x) != ' - '-1". Empty\n' - 'strings are always considered to be a substring of any ' - 'other string,\n' - 'so """ in "abc"" will return "True".\n' - '\n' - 'For user-defined classes which define the "__contains__()" ' - 'method, "x\n' - 'in y" is true if and only if "y.__contains__(x)" is true.\n' - '\n' - 'For user-defined classes which do not define ' - '"__contains__()" but do\n' - 'define "__iter__()", "x in y" is true if some value "z" ' - 'with "x == z"\n' - 'is produced while iterating over "y". If an exception is ' - 'raised\n' - 'during the iteration, it is as if "in" raised that ' - 'exception.\n' - '\n' - 'Lastly, the old-style iteration protocol is tried: if a ' - 'class defines\n' - '"__getitem__()", "x in y" is true if and only if there is a ' - 'non-\n' - 'negative integer index *i* such that "x == y[i]", and all ' - 'lower\n' - 'integer indices do not raise "IndexError" exception. (If ' - 'any other\n' - 'exception is raised, it is as if "in" raised that ' - 'exception).\n' - '\n' - 'The operator "not in" is defined to have the inverse true ' - 'value of\n' - '"in".\n' - '\n' - '\n' - 'Identity comparisons\n' - '====================\n' - '\n' - 'The operators "is" and "is not" test for object identity: ' - '"x is y" is\n' - 'true if and only if *x* and *y* are the same object. "x is ' - 'not y"\n' - 'yields the inverse truth value. [4]\n', - 'compound': '\n' - 'Compound statements\n' - '*******************\n' - '\n' - 'Compound statements contain (groups of) other statements; they ' - 'affect\n' - 'or control the execution of those other statements in some ' - 'way. In\n' - 'general, compound statements span multiple lines, although in ' - 'simple\n' - 'incarnations a whole compound statement may be contained in ' - 'one line.\n' - '\n' - 'The "if", "while" and "for" statements implement traditional ' - 'control\n' - 'flow constructs. "try" specifies exception handlers and/or ' - 'cleanup\n' - 'code for a group of statements, while the "with" statement ' - 'allows the\n' - 'execution of initialization and finalization code around a ' - 'block of\n' - 'code. Function and class definitions are also syntactically ' - 'compound\n' - 'statements.\n' - '\n' - "A compound statement consists of one or more 'clauses.' A " - 'clause\n' - "consists of a header and a 'suite.' The clause headers of a\n" - 'particular compound statement are all at the same indentation ' - 'level.\n' - 'Each clause header begins with a uniquely identifying keyword ' - 'and ends\n' - 'with a colon. A suite is a group of statements controlled by ' - 'a\n' - 'clause. A suite can be one or more semicolon-separated ' - 'simple\n' - 'statements on the same line as the header, following the ' - "header's\n" - 'colon, or it can be one or more indented statements on ' - 'subsequent\n' - 'lines. Only the latter form of a suite can contain nested ' - 'compound\n' - 'statements; the following is illegal, mostly because it ' - "wouldn't be\n" - 'clear to which "if" clause a following "else" clause would ' - 'belong:\n' - '\n' - ' if test1: if test2: print(x)\n' - '\n' - 'Also note that the semicolon binds tighter than the colon in ' - 'this\n' - 'context, so that in the following example, either all or none ' - 'of the\n' - '"print()" calls are executed:\n' - '\n' - ' if x < y < z: print(x); print(y); print(z)\n' - '\n' - 'Summarizing:\n' - '\n' - ' compound_stmt ::= if_stmt\n' - ' | while_stmt\n' - ' | for_stmt\n' - ' | try_stmt\n' - ' | with_stmt\n' - ' | funcdef\n' - ' | classdef\n' - ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' - 'statement+ DEDENT\n' - ' statement ::= stmt_list NEWLINE | compound_stmt\n' - ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n' - '\n' - 'Note that statements always end in a "NEWLINE" possibly ' - 'followed by a\n' - '"DEDENT". Also note that optional continuation clauses always ' - 'begin\n' - 'with a keyword that cannot start a statement, thus there are ' - 'no\n' - 'ambiguities (the \'dangling "else"\' problem is solved in ' - 'Python by\n' - 'requiring nested "if" statements to be indented).\n' - '\n' - 'The formatting of the grammar rules in the following sections ' - 'places\n' - 'each clause on a separate line for clarity.\n' - '\n' - '\n' - 'The "if" statement\n' - '==================\n' - '\n' - 'The "if" statement is used for conditional execution:\n' - '\n' - ' if_stmt ::= "if" expression ":" suite\n' - ' ( "elif" expression ":" suite )*\n' - ' ["else" ":" suite]\n' - '\n' - 'It selects exactly one of the suites by evaluating the ' - 'expressions one\n' - 'by one until one is found to be true (see section *Boolean ' - 'operations*\n' - 'for the definition of true and false); then that suite is ' - 'executed\n' - '(and no other part of the "if" statement is executed or ' - 'evaluated).\n' - 'If all expressions are false, the suite of the "else" clause, ' - 'if\n' - 'present, is executed.\n' - '\n' - '\n' - 'The "while" statement\n' - '=====================\n' - '\n' - 'The "while" statement is used for repeated execution as long ' - 'as an\n' - 'expression is true:\n' - '\n' - ' while_stmt ::= "while" expression ":" suite\n' - ' ["else" ":" suite]\n' - '\n' - 'This repeatedly tests the expression and, if it is true, ' - 'executes the\n' - 'first suite; if the expression is false (which may be the ' - 'first time\n' - 'it is tested) the suite of the "else" clause, if present, is ' - 'executed\n' - 'and the loop terminates.\n' - '\n' - 'A "break" statement executed in the first suite terminates the ' - 'loop\n' - 'without executing the "else" clause\'s suite. A "continue" ' - 'statement\n' - 'executed in the first suite skips the rest of the suite and ' - 'goes back\n' - 'to testing the expression.\n' - '\n' - '\n' - 'The "for" statement\n' - '===================\n' - '\n' - 'The "for" statement is used to iterate over the elements of a ' - 'sequence\n' - '(such as a string, tuple or list) or other iterable object:\n' - '\n' - ' for_stmt ::= "for" target_list "in" expression_list ":" ' - 'suite\n' - ' ["else" ":" suite]\n' - '\n' - 'The expression list is evaluated once; it should yield an ' - 'iterable\n' - 'object. An iterator is created for the result of the\n' - '"expression_list". The suite is then executed once for each ' - 'item\n' - 'provided by the iterator, in the order returned by the ' - 'iterator. Each\n' - 'item in turn is assigned to the target list using the standard ' - 'rules\n' - 'for assignments (see *Assignment statements*), and then the ' - 'suite is\n' - 'executed. When the items are exhausted (which is immediately ' - 'when the\n' - 'sequence is empty or an iterator raises a "StopIteration" ' - 'exception),\n' - 'the suite in the "else" clause, if present, is executed, and ' - 'the loop\n' - 'terminates.\n' - '\n' - 'A "break" statement executed in the first suite terminates the ' - 'loop\n' - 'without executing the "else" clause\'s suite. A "continue" ' - 'statement\n' - 'executed in the first suite skips the rest of the suite and ' - 'continues\n' - 'with the next item, or with the "else" clause if there is no ' - 'next\n' - 'item.\n' - '\n' - 'The for-loop makes assignments to the variables(s) in the ' - 'target list.\n' - 'This overwrites all previous assignments to those variables ' - 'including\n' - 'those made in the suite of the for-loop:\n' - '\n' - ' for i in range(10):\n' - ' print(i)\n' - ' i = 5 # this will not affect the for-loop\n' - ' # because i will be overwritten with ' - 'the next\n' - ' # index in the range\n' - '\n' - 'Names in the target list are not deleted when the loop is ' - 'finished,\n' - 'but if the sequence is empty, they will not have been assigned ' - 'to at\n' - 'all by the loop. Hint: the built-in function "range()" ' - 'returns an\n' - 'iterator of integers suitable to emulate the effect of ' - 'Pascal\'s "for i\n' - ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' - '2]".\n' - '\n' - 'Note: There is a subtlety when the sequence is being modified ' - 'by the\n' - ' loop (this can only occur for mutable sequences, i.e. ' - 'lists). An\n' - ' internal counter is used to keep track of which item is used ' - 'next,\n' - ' and this is incremented on each iteration. When this ' - 'counter has\n' - ' reached the length of the sequence the loop terminates. ' - 'This means\n' - ' that if the suite deletes the current (or a previous) item ' - 'from the\n' - ' sequence, the next item will be skipped (since it gets the ' - 'index of\n' - ' the current item which has already been treated). Likewise, ' - 'if the\n' - ' suite inserts an item in the sequence before the current ' - 'item, the\n' - ' current item will be treated again the next time through the ' - 'loop.\n' - ' This can lead to nasty bugs that can be avoided by making a\n' - ' temporary copy using a slice of the whole sequence, e.g.,\n' - '\n' - ' for x in a[:]:\n' - ' if x < 0: a.remove(x)\n' - '\n' - '\n' - 'The "try" statement\n' - '===================\n' - '\n' - 'The "try" statement specifies exception handlers and/or ' - 'cleanup code\n' - 'for a group of statements:\n' - '\n' - ' try_stmt ::= try1_stmt | try2_stmt\n' - ' try1_stmt ::= "try" ":" suite\n' - ' ("except" [expression ["as" identifier]] ":" ' - 'suite)+\n' - ' ["else" ":" suite]\n' - ' ["finally" ":" suite]\n' - ' try2_stmt ::= "try" ":" suite\n' - ' "finally" ":" suite\n' - '\n' - 'The "except" clause(s) specify one or more exception handlers. ' - 'When no\n' - 'exception occurs in the "try" clause, no exception handler is\n' - 'executed. When an exception occurs in the "try" suite, a ' - 'search for an\n' - 'exception handler is started. This search inspects the except ' - 'clauses\n' - 'in turn until one is found that matches the exception. An ' - 'expression-\n' - 'less except clause, if present, must be last; it matches any\n' - 'exception. For an except clause with an expression, that ' - 'expression\n' - 'is evaluated, and the clause matches the exception if the ' - 'resulting\n' - 'object is "compatible" with the exception. An object is ' - 'compatible\n' - 'with an exception if it is the class or a base class of the ' - 'exception\n' - 'object or a tuple containing an item compatible with the ' - 'exception.\n' - '\n' - 'If no except clause matches the exception, the search for an ' - 'exception\n' - 'handler continues in the surrounding code and on the ' - 'invocation stack.\n' - '[1]\n' - '\n' - 'If the evaluation of an expression in the header of an except ' - 'clause\n' - 'raises an exception, the original search for a handler is ' - 'canceled and\n' - 'a search starts for the new exception in the surrounding code ' - 'and on\n' - 'the call stack (it is treated as if the entire "try" statement ' - 'raised\n' - 'the exception).\n' - '\n' - 'When a matching except clause is found, the exception is ' - 'assigned to\n' - 'the target specified after the "as" keyword in that except ' - 'clause, if\n' - "present, and the except clause's suite is executed. All " - 'except\n' - 'clauses must have an executable block. When the end of this ' - 'block is\n' - 'reached, execution continues normally after the entire try ' - 'statement.\n' - '(This means that if two nested handlers exist for the same ' - 'exception,\n' - 'and the exception occurs in the try clause of the inner ' - 'handler, the\n' - 'outer handler will not handle the exception.)\n' - '\n' - 'When an exception has been assigned using "as target", it is ' - 'cleared\n' - 'at the end of the except clause. This is as if\n' - '\n' - ' except E as N:\n' - ' foo\n' - '\n' - 'was translated to\n' - '\n' - ' except E as N:\n' - ' try:\n' - ' foo\n' - ' finally:\n' - ' del N\n' - '\n' - 'This means the exception must be assigned to a different name ' - 'to be\n' - 'able to refer to it after the except clause. Exceptions are ' - 'cleared\n' - 'because with the traceback attached to them, they form a ' - 'reference\n' - 'cycle with the stack frame, keeping all locals in that frame ' - 'alive\n' - 'until the next garbage collection occurs.\n' - '\n' - "Before an except clause's suite is executed, details about " - 'the\n' - 'exception are stored in the "sys" module and can be accessed ' - 'via\n' - '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple ' - 'consisting of the\n' - 'exception class, the exception instance and a traceback object ' - '(see\n' - 'section *The standard type hierarchy*) identifying the point ' - 'in the\n' - 'program where the exception occurred. "sys.exc_info()" values ' - 'are\n' - 'restored to their previous values (before the call) when ' - 'returning\n' - 'from a function that handled an exception.\n' - '\n' - 'The optional "else" clause is executed if and when control ' - 'flows off\n' - 'the end of the "try" clause. [2] Exceptions in the "else" ' - 'clause are\n' - 'not handled by the preceding "except" clauses.\n' - '\n' - 'If "finally" is present, it specifies a \'cleanup\' handler. ' - 'The "try"\n' - 'clause is executed, including any "except" and "else" ' - 'clauses. If an\n' - 'exception occurs in any of the clauses and is not handled, ' - 'the\n' - 'exception is temporarily saved. The "finally" clause is ' - 'executed. If\n' - 'there is a saved exception it is re-raised at the end of the ' - '"finally"\n' - 'clause. If the "finally" clause raises another exception, the ' - 'saved\n' - 'exception is set as the context of the new exception. If the ' - '"finally"\n' - 'clause executes a "return" or "break" statement, the saved ' - 'exception\n' - 'is discarded:\n' - '\n' - ' >>> def f():\n' - ' ... try:\n' - ' ... 1/0\n' - ' ... finally:\n' - ' ... return 42\n' - ' ...\n' - ' >>> f()\n' - ' 42\n' - '\n' - 'The exception information is not available to the program ' - 'during\n' - 'execution of the "finally" clause.\n' - '\n' - 'When a "return", "break" or "continue" statement is executed ' - 'in the\n' - '"try" suite of a "try"..."finally" statement, the "finally" ' - 'clause is\n' - 'also executed \'on the way out.\' A "continue" statement is ' - 'illegal in\n' - 'the "finally" clause. (The reason is a problem with the ' - 'current\n' - 'implementation --- this restriction may be lifted in the ' - 'future).\n' - '\n' - 'The return value of a function is determined by the last ' - '"return"\n' - 'statement executed. Since the "finally" clause always ' - 'executes, a\n' - '"return" statement executed in the "finally" clause will ' - 'always be the\n' - 'last one executed:\n' - '\n' - ' >>> def foo():\n' - ' ... try:\n' - " ... return 'try'\n" - ' ... finally:\n' - " ... return 'finally'\n" - ' ...\n' - ' >>> foo()\n' - " 'finally'\n" - '\n' - 'Additional information on exceptions can be found in section\n' - '*Exceptions*, and information on using the "raise" statement ' - 'to\n' - 'generate exceptions may be found in section *The raise ' - 'statement*.\n' - '\n' - '\n' - 'The "with" statement\n' - '====================\n' - '\n' - 'The "with" statement is used to wrap the execution of a block ' - 'with\n' - 'methods defined by a context manager (see section *With ' - 'Statement\n' - 'Context Managers*). This allows common ' - '"try"..."except"..."finally"\n' - 'usage patterns to be encapsulated for convenient reuse.\n' - '\n' - ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' - ' with_item ::= expression ["as" target]\n' - '\n' - 'The execution of the "with" statement with one "item" proceeds ' - 'as\n' - 'follows:\n' - '\n' - '1. The context expression (the expression given in the ' - '"with_item")\n' - ' is evaluated to obtain a context manager.\n' - '\n' - '2. The context manager\'s "__exit__()" is loaded for later ' - 'use.\n' - '\n' - '3. The context manager\'s "__enter__()" method is invoked.\n' - '\n' - '4. If a target was included in the "with" statement, the ' - 'return\n' - ' value from "__enter__()" is assigned to it.\n' - '\n' - ' Note: The "with" statement guarantees that if the ' - '"__enter__()"\n' - ' method returns without an error, then "__exit__()" will ' - 'always be\n' - ' called. Thus, if an error occurs during the assignment to ' - 'the\n' - ' target list, it will be treated the same as an error ' - 'occurring\n' - ' within the suite would be. See step 6 below.\n' - '\n' - '5. The suite is executed.\n' - '\n' - '6. The context manager\'s "__exit__()" method is invoked. If ' - 'an\n' - ' exception caused the suite to be exited, its type, value, ' - 'and\n' - ' traceback are passed as arguments to "__exit__()". ' - 'Otherwise, three\n' - ' "None" arguments are supplied.\n' - '\n' - ' If the suite was exited due to an exception, and the return ' - 'value\n' - ' from the "__exit__()" method was false, the exception is ' - 'reraised.\n' - ' If the return value was true, the exception is suppressed, ' - 'and\n' - ' execution continues with the statement following the ' - '"with"\n' - ' statement.\n' - '\n' - ' If the suite was exited for any reason other than an ' - 'exception, the\n' - ' return value from "__exit__()" is ignored, and execution ' - 'proceeds\n' - ' at the normal location for the kind of exit that was ' - 'taken.\n' - '\n' - 'With more than one item, the context managers are processed as ' - 'if\n' - 'multiple "with" statements were nested:\n' - '\n' - ' with A() as a, B() as b:\n' - ' suite\n' - '\n' - 'is equivalent to\n' - '\n' - ' with A() as a:\n' - ' with B() as b:\n' - ' suite\n' - '\n' - 'Changed in version 3.1: Support for multiple context ' - 'expressions.\n' - '\n' - 'See also: **PEP 0343** - The "with" statement\n' - '\n' - ' The specification, background, and examples for the ' - 'Python "with"\n' - ' statement.\n' - '\n' - '\n' - 'Function definitions\n' - '====================\n' - '\n' - 'A function definition defines a user-defined function object ' - '(see\n' - 'section *The standard type hierarchy*):\n' - '\n' - ' funcdef ::= [decorators] "def" funcname "(" ' - '[parameter_list] ")" ["->" expression] ":" suite\n' - ' decorators ::= decorator+\n' - ' decorator ::= "@" dotted_name ["(" [parameter_list ' - '[","]] ")"] NEWLINE\n' - ' dotted_name ::= identifier ("." identifier)*\n' - ' parameter_list ::= (defparameter ",")*\n' - ' | "*" [parameter] ("," defparameter)* ' - '["," "**" parameter]\n' - ' | "**" parameter\n' - ' | defparameter [","] )\n' - ' parameter ::= identifier [":" expression]\n' - ' defparameter ::= parameter ["=" expression]\n' - ' funcname ::= identifier\n' - '\n' - 'A function definition is an executable statement. Its ' - 'execution binds\n' - 'the function name in the current local namespace to a function ' - 'object\n' - '(a wrapper around the executable code for the function). ' - 'This\n' - 'function object contains a reference to the current global ' - 'namespace\n' - 'as the global namespace to be used when the function is ' - 'called.\n' - '\n' - 'The function definition does not execute the function body; ' - 'this gets\n' - 'executed only when the function is called. [3]\n' - '\n' - 'A function definition may be wrapped by one or more ' - '*decorator*\n' - 'expressions. Decorator expressions are evaluated when the ' - 'function is\n' - 'defined, in the scope that contains the function definition. ' - 'The\n' - 'result must be a callable, which is invoked with the function ' - 'object\n' - 'as the only argument. The returned value is bound to the ' - 'function name\n' - 'instead of the function object. Multiple decorators are ' - 'applied in\n' - 'nested fashion. For example, the following code\n' - '\n' - ' @f1(arg)\n' - ' @f2\n' - ' def func(): pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' def func(): pass\n' - ' func = f1(arg)(f2(func))\n' - '\n' - 'When one or more *parameters* have the form *parameter* "="\n' - '*expression*, the function is said to have "default parameter ' - 'values."\n' - 'For a parameter with a default value, the corresponding ' - '*argument* may\n' - "be omitted from a call, in which case the parameter's default " - 'value is\n' - 'substituted. If a parameter has a default value, all ' - 'following\n' - 'parameters up until the ""*"" must also have a default value ' - '--- this\n' - 'is a syntactic restriction that is not expressed by the ' - 'grammar.\n' - '\n' - '**Default parameter values are evaluated from left to right ' - 'when the\n' - 'function definition is executed.** This means that the ' - 'expression is\n' - 'evaluated once, when the function is defined, and that the ' - 'same "pre-\n' - 'computed" value is used for each call. This is especially ' - 'important\n' - 'to understand when a default parameter is a mutable object, ' - 'such as a\n' - 'list or a dictionary: if the function modifies the object ' - '(e.g. by\n' - 'appending an item to a list), the default value is in effect ' - 'modified.\n' - 'This is generally not what was intended. A way around this is ' - 'to use\n' - '"None" as the default, and explicitly test for it in the body ' - 'of the\n' - 'function, e.g.:\n' - '\n' - ' def whats_on_the_telly(penguin=None):\n' - ' if penguin is None:\n' - ' penguin = []\n' - ' penguin.append("property of the zoo")\n' - ' return penguin\n' - '\n' - 'Function call semantics are described in more detail in ' - 'section\n' - '*Calls*. A function call always assigns values to all ' - 'parameters\n' - 'mentioned in the parameter list, either from position ' - 'arguments, from\n' - 'keyword arguments, or from default values. If the form\n' - '""*identifier"" is present, it is initialized to a tuple ' - 'receiving any\n' - 'excess positional parameters, defaulting to the empty tuple. ' - 'If the\n' - 'form ""**identifier"" is present, it is initialized to a new\n' - 'dictionary receiving any excess keyword arguments, defaulting ' - 'to a new\n' - 'empty dictionary. Parameters after ""*"" or ""*identifier"" ' - 'are\n' - 'keyword-only parameters and may only be passed used keyword ' - 'arguments.\n' - '\n' - 'Parameters may have annotations of the form "": expression"" ' - 'following\n' - 'the parameter name. Any parameter may have an annotation even ' - 'those\n' - 'of the form "*identifier" or "**identifier". Functions may ' - 'have\n' - '"return" annotation of the form ""-> expression"" after the ' - 'parameter\n' - 'list. These annotations can be any valid Python expression ' - 'and are\n' - 'evaluated when the function definition is executed. ' - 'Annotations may\n' - 'be evaluated in a different order than they appear in the ' - 'source code.\n' - 'The presence of annotations does not change the semantics of ' - 'a\n' - 'function. The annotation values are available as values of a\n' - "dictionary keyed by the parameters' names in the " - '"__annotations__"\n' - 'attribute of the function object.\n' - '\n' - 'It is also possible to create anonymous functions (functions ' - 'not bound\n' - 'to a name), for immediate use in expressions. This uses ' - 'lambda\n' - 'expressions, described in section *Lambdas*. Note that the ' - 'lambda\n' - 'expression is merely a shorthand for a simplified function ' - 'definition;\n' - 'a function defined in a ""def"" statement can be passed around ' - 'or\n' - 'assigned to another name just like a function defined by a ' - 'lambda\n' - 'expression. The ""def"" form is actually more powerful since ' - 'it\n' - 'allows the execution of multiple statements and annotations.\n' - '\n' - "**Programmer's note:** Functions are first-class objects. A " - '""def""\n' - 'statement executed inside a function definition defines a ' - 'local\n' - 'function that can be returned or passed around. Free ' - 'variables used\n' - 'in the nested function can access the local variables of the ' - 'function\n' - 'containing the def. See section *Naming and binding* for ' - 'details.\n' - '\n' - 'See also: **PEP 3107** - Function Annotations\n' - '\n' - ' The original specification for function annotations.\n' - '\n' - '\n' - 'Class definitions\n' - '=================\n' - '\n' - 'A class definition defines a class object (see section *The ' - 'standard\n' - 'type hierarchy*):\n' - '\n' - ' classdef ::= [decorators] "class" classname ' - '[inheritance] ":" suite\n' - ' inheritance ::= "(" [parameter_list] ")"\n' - ' classname ::= identifier\n' - '\n' - 'A class definition is an executable statement. The ' - 'inheritance list\n' - 'usually gives a list of base classes (see *Customizing class ' - 'creation*\n' - 'for more advanced uses), so each item in the list should ' - 'evaluate to a\n' - 'class object which allows subclassing. Classes without an ' - 'inheritance\n' - 'list inherit, by default, from the base class "object"; ' - 'hence,\n' - '\n' - ' class Foo:\n' - ' pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' class Foo(object):\n' - ' pass\n' - '\n' - "The class's suite is then executed in a new execution frame " - '(see\n' - '*Naming and binding*), using a newly created local namespace ' - 'and the\n' - 'original global namespace. (Usually, the suite contains ' - 'mostly\n' - "function definitions.) When the class's suite finishes " - 'execution, its\n' - 'execution frame is discarded but its local namespace is saved. ' - '[4] A\n' - 'class object is then created using the inheritance list for ' - 'the base\n' - 'classes and the saved local namespace for the attribute ' - 'dictionary.\n' - 'The class name is bound to this class object in the original ' - 'local\n' - 'namespace.\n' - '\n' - 'Class creation can be customized heavily using *metaclasses*.\n' - '\n' - 'Classes can also be decorated: just like when decorating ' - 'functions,\n' - '\n' - ' @f1(arg)\n' - ' @f2\n' - ' class Foo: pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' class Foo: pass\n' - ' Foo = f1(arg)(f2(Foo))\n' - '\n' - 'The evaluation rules for the decorator expressions are the ' - 'same as for\n' - 'function decorators. The result must be a class object, which ' - 'is then\n' - 'bound to the class name.\n' - '\n' - "**Programmer's note:** Variables defined in the class " - 'definition are\n' - 'class attributes; they are shared by instances. Instance ' - 'attributes\n' - 'can be set in a method with "self.name = value". Both class ' - 'and\n' - 'instance attributes are accessible through the notation ' - '""self.name"",\n' - 'and an instance attribute hides a class attribute with the ' - 'same name\n' - 'when accessed in this way. Class attributes can be used as ' - 'defaults\n' - 'for instance attributes, but using mutable values there can ' - 'lead to\n' - 'unexpected results. *Descriptors* can be used to create ' - 'instance\n' - 'variables with different implementation details.\n' - '\n' - 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** ' - '-\n' - ' Class Decorators\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] The exception is propagated to the invocation stack ' - 'unless\n' - ' there is a "finally" clause which happens to raise ' - 'another\n' - ' exception. That new exception causes the old one to be ' - 'lost.\n' - '\n' - '[2] Currently, control "flows off the end" except in the case ' - 'of\n' - ' an exception or the execution of a "return", "continue", ' - 'or\n' - ' "break" statement.\n' - '\n' - '[3] A string literal appearing as the first statement in the\n' - " function body is transformed into the function's " - '"__doc__"\n' - " attribute and therefore the function's *docstring*.\n" - '\n' - '[4] A string literal appearing as the first statement in the ' - 'class\n' - ' body is transformed into the namespace\'s "__doc__" item ' - 'and\n' - " therefore the class's *docstring*.\n", - 'context-managers': '\n' - 'With Statement Context Managers\n' - '*******************************\n' - '\n' - 'A *context manager* is an object that defines the ' - 'runtime context to\n' - 'be established when executing a "with" statement. The ' - 'context manager\n' - 'handles the entry into, and the exit from, the desired ' - 'runtime context\n' - 'for the execution of the block of code. Context ' - 'managers are normally\n' - 'invoked using the "with" statement (described in ' - 'section *The with\n' - 'statement*), but can also be used by directly invoking ' - 'their methods.\n' - '\n' - 'Typical uses of context managers include saving and ' - 'restoring various\n' - 'kinds of global state, locking and unlocking ' - 'resources, closing opened\n' - 'files, etc.\n' - '\n' - 'For more information on context managers, see *Context ' - 'Manager Types*.\n' - '\n' - 'object.__enter__(self)\n' - '\n' - ' Enter the runtime context related to this object. ' - 'The "with"\n' - " statement will bind this method's return value to " - 'the target(s)\n' - ' specified in the "as" clause of the statement, if ' - 'any.\n' - '\n' - 'object.__exit__(self, exc_type, exc_value, traceback)\n' - '\n' - ' Exit the runtime context related to this object. ' - 'The parameters\n' - ' describe the exception that caused the context to ' - 'be exited. If the\n' - ' context was exited without an exception, all three ' - 'arguments will\n' - ' be "None".\n' - '\n' - ' If an exception is supplied, and the method wishes ' - 'to suppress the\n' - ' exception (i.e., prevent it from being propagated), ' - 'it should\n' - ' return a true value. Otherwise, the exception will ' - 'be processed\n' - ' normally upon exit from this method.\n' - '\n' - ' Note that "__exit__()" methods should not reraise ' - 'the passed-in\n' - " exception; this is the caller's responsibility.\n" - '\n' - 'See also: **PEP 0343** - The "with" statement\n' - '\n' - ' The specification, background, and examples for ' - 'the Python "with"\n' - ' statement.\n', - 'continue': '\n' - 'The "continue" statement\n' - '************************\n' - '\n' - ' continue_stmt ::= "continue"\n' - '\n' - '"continue" may only occur syntactically nested in a "for" or ' - '"while"\n' - 'loop, but not nested in a function or class definition or ' - '"finally"\n' - 'clause within that loop. It continues with the next cycle of ' - 'the\n' - 'nearest enclosing loop.\n' - '\n' - 'When "continue" passes control out of a "try" statement with ' - 'a\n' - '"finally" clause, that "finally" clause is executed before ' - 'really\n' - 'starting the next loop cycle.\n', - 'conversions': '\n' - 'Arithmetic conversions\n' - '**********************\n' - '\n' - 'When a description of an arithmetic operator below uses the ' - 'phrase\n' - '"the numeric arguments are converted to a common type," ' - 'this means\n' - 'that the operator implementation for built-in types works ' - 'as follows:\n' - '\n' - '* If either argument is a complex number, the other is ' - 'converted to\n' - ' complex;\n' - '\n' - '* otherwise, if either argument is a floating point number, ' - 'the\n' - ' other is converted to floating point;\n' - '\n' - '* otherwise, both must be integers and no conversion is ' - 'necessary.\n' - '\n' - 'Some additional rules apply for certain operators (e.g., a ' - 'string as a\n' - "left argument to the '%' operator). Extensions must define " - 'their own\n' - 'conversion behavior.\n', - 'customization': '\n' - 'Basic customization\n' - '*******************\n' - '\n' - 'object.__new__(cls[, ...])\n' - '\n' - ' Called to create a new instance of class *cls*. ' - '"__new__()" is a\n' - ' static method (special-cased so you need not declare ' - 'it as such)\n' - ' that takes the class of which an instance was ' - 'requested as its\n' - ' first argument. The remaining arguments are those ' - 'passed to the\n' - ' object constructor expression (the call to the ' - 'class). The return\n' - ' value of "__new__()" should be the new object instance ' - '(usually an\n' - ' instance of *cls*).\n' - '\n' - ' Typical implementations create a new instance of the ' - 'class by\n' - ' invoking the superclass\'s "__new__()" method using\n' - ' "super(currentclass, cls).__new__(cls[, ...])" with ' - 'appropriate\n' - ' arguments and then modifying the newly-created ' - 'instance as\n' - ' necessary before returning it.\n' - '\n' - ' If "__new__()" returns an instance of *cls*, then the ' - 'new\n' - ' instance\'s "__init__()" method will be invoked like\n' - ' "__init__(self[, ...])", where *self* is the new ' - 'instance and the\n' - ' remaining arguments are the same as were passed to ' - '"__new__()".\n' - '\n' - ' If "__new__()" does not return an instance of *cls*, ' - 'then the new\n' - ' instance\'s "__init__()" method will not be invoked.\n' - '\n' - ' "__new__()" is intended mainly to allow subclasses of ' - 'immutable\n' - ' types (like int, str, or tuple) to customize instance ' - 'creation. It\n' - ' is also commonly overridden in custom metaclasses in ' - 'order to\n' - ' customize class creation.\n' - '\n' - 'object.__init__(self[, ...])\n' - '\n' - ' Called after the instance has been created (by ' - '"__new__()"), but\n' - ' before it is returned to the caller. The arguments ' - 'are those\n' - ' passed to the class constructor expression. If a base ' - 'class has an\n' - ' "__init__()" method, the derived class\'s "__init__()" ' - 'method, if\n' - ' any, must explicitly call it to ensure proper ' - 'initialization of the\n' - ' base class part of the instance; for example:\n' - ' "BaseClass.__init__(self, [args...])".\n' - '\n' - ' Because "__new__()" and "__init__()" work together in ' - 'constructing\n' - ' objects ("__new__()" to create it, and "__init__()" to ' - 'customise\n' - ' it), no non-"None" value may be returned by ' - '"__init__()"; doing so\n' - ' will cause a "TypeError" to be raised at runtime.\n' - '\n' - 'object.__del__(self)\n' - '\n' - ' Called when the instance is about to be destroyed. ' - 'This is also\n' - ' called a destructor. If a base class has a ' - '"__del__()" method, the\n' - ' derived class\'s "__del__()" method, if any, must ' - 'explicitly call it\n' - ' to ensure proper deletion of the base class part of ' - 'the instance.\n' - ' Note that it is possible (though not recommended!) for ' - 'the\n' - ' "__del__()" method to postpone destruction of the ' - 'instance by\n' - ' creating a new reference to it. It may then be called ' - 'at a later\n' - ' time when this new reference is deleted. It is not ' - 'guaranteed that\n' - ' "__del__()" methods are called for objects that still ' - 'exist when\n' - ' the interpreter exits.\n' - '\n' - ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' - 'the former\n' - ' decrements the reference count for "x" by one, and ' - 'the latter is\n' - ' only called when "x"\'s reference count reaches ' - 'zero. Some common\n' - ' situations that may prevent the reference count of ' - 'an object from\n' - ' going to zero include: circular references between ' - 'objects (e.g.,\n' - ' a doubly-linked list or a tree data structure with ' - 'parent and\n' - ' child pointers); a reference to the object on the ' - 'stack frame of\n' - ' a function that caught an exception (the traceback ' - 'stored in\n' - ' "sys.exc_info()[2]" keeps the stack frame alive); or ' - 'a reference\n' - ' to the object on the stack frame that raised an ' - 'unhandled\n' - ' exception in interactive mode (the traceback stored ' - 'in\n' - ' "sys.last_traceback" keeps the stack frame alive). ' - 'The first\n' - ' situation can only be remedied by explicitly ' - 'breaking the cycles;\n' - ' the second can be resolved by freeing the reference ' - 'to the\n' - ' traceback object when it is no longer useful, and ' - 'the third can\n' - ' be resolved by storing "None" in ' - '"sys.last_traceback". Circular\n' - ' references which are garbage are detected and ' - 'cleaned up when the\n' - " cyclic garbage collector is enabled (it's on by " - 'default). Refer\n' - ' to the documentation for the "gc" module for more ' - 'information\n' - ' about this topic.\n' - '\n' - ' Warning: Due to the precarious circumstances under ' - 'which\n' - ' "__del__()" methods are invoked, exceptions that ' - 'occur during\n' - ' their execution are ignored, and a warning is ' - 'printed to\n' - ' "sys.stderr" instead. Also, when "__del__()" is ' - 'invoked in\n' - ' response to a module being deleted (e.g., when ' - 'execution of the\n' - ' program is done), other globals referenced by the ' - '"__del__()"\n' - ' method may already have been deleted or in the ' - 'process of being\n' - ' torn down (e.g. the import machinery shutting ' - 'down). For this\n' - ' reason, "__del__()" methods should do the absolute ' - 'minimum needed\n' - ' to maintain external invariants. Starting with ' - 'version 1.5,\n' - ' Python guarantees that globals whose name begins ' - 'with a single\n' - ' underscore are deleted from their module before ' - 'other globals are\n' - ' deleted; if no other references to such globals ' - 'exist, this may\n' - ' help in assuring that imported modules are still ' - 'available at the\n' - ' time when the "__del__()" method is called.\n' - '\n' - 'object.__repr__(self)\n' - '\n' - ' Called by the "repr()" built-in function to compute ' - 'the "official"\n' - ' string representation of an object. If at all ' - 'possible, this\n' - ' should look like a valid Python expression that could ' - 'be used to\n' - ' recreate an object with the same value (given an ' - 'appropriate\n' - ' environment). If this is not possible, a string of ' - 'the form\n' - ' "<...some useful description...>" should be returned. ' - 'The return\n' - ' value must be a string object. If a class defines ' - '"__repr__()" but\n' - ' not "__str__()", then "__repr__()" is also used when ' - 'an "informal"\n' - ' string representation of instances of that class is ' - 'required.\n' - '\n' - ' This is typically used for debugging, so it is ' - 'important that the\n' - ' representation is information-rich and unambiguous.\n' - '\n' - 'object.__str__(self)\n' - '\n' - ' Called by "str(object)" and the built-in functions ' - '"format()" and\n' - ' "print()" to compute the "informal" or nicely ' - 'printable string\n' - ' representation of an object. The return value must be ' - 'a *string*\n' - ' object.\n' - '\n' - ' This method differs from "object.__repr__()" in that ' - 'there is no\n' - ' expectation that "__str__()" return a valid Python ' - 'expression: a\n' - ' more convenient or concise representation can be ' - 'used.\n' - '\n' - ' The default implementation defined by the built-in ' - 'type "object"\n' - ' calls "object.__repr__()".\n' - '\n' - 'object.__bytes__(self)\n' - '\n' - ' Called by "bytes()" to compute a byte-string ' - 'representation of an\n' - ' object. This should return a "bytes" object.\n' - '\n' - 'object.__format__(self, format_spec)\n' - '\n' - ' Called by the "format()" built-in function (and by ' - 'extension, the\n' - ' "str.format()" method of class "str") to produce a ' - '"formatted"\n' - ' string representation of an object. The "format_spec" ' - 'argument is a\n' - ' string that contains a description of the formatting ' - 'options\n' - ' desired. The interpretation of the "format_spec" ' - 'argument is up to\n' - ' the type implementing "__format__()", however most ' - 'classes will\n' - ' either delegate formatting to one of the built-in ' - 'types, or use a\n' - ' similar formatting option syntax.\n' - '\n' - ' See *Format Specification Mini-Language* for a ' - 'description of the\n' - ' standard formatting syntax.\n' - '\n' - ' The return value must be a string object.\n' - '\n' - ' Changed in version 3.4: The __format__ method of ' - '"object" itself\n' - ' raises a "TypeError" if passed any non-empty string.\n' - '\n' - 'object.__lt__(self, other)\n' - 'object.__le__(self, other)\n' - 'object.__eq__(self, other)\n' - 'object.__ne__(self, other)\n' - 'object.__gt__(self, other)\n' - 'object.__ge__(self, other)\n' - '\n' - ' These are the so-called "rich comparison" methods. ' - 'The\n' - ' correspondence between operator symbols and method ' - 'names is as\n' - ' follows: "xy" calls\n' - ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' - '\n' - ' A rich comparison method may return the singleton ' - '"NotImplemented"\n' - ' if it does not implement the operation for a given ' - 'pair of\n' - ' arguments. By convention, "False" and "True" are ' - 'returned for a\n' - ' successful comparison. However, these methods can ' - 'return any value,\n' - ' so if the comparison operator is used in a Boolean ' - 'context (e.g.,\n' - ' in the condition of an "if" statement), Python will ' - 'call "bool()"\n' - ' on the value to determine if the result is true or ' - 'false.\n' - '\n' - ' By default, "__ne__()" delegates to "__eq__()" and ' - 'inverts the\n' - ' result unless it is "NotImplemented". There are no ' - 'other implied\n' - ' relationships among the comparison operators, for ' - 'example, the\n' - ' truth of "(x.__hash__".\n' - '\n' - ' If a class that does not override "__eq__()" wishes to ' - 'suppress\n' - ' hash support, it should include "__hash__ = None" in ' - 'the class\n' - ' definition. A class which defines its own "__hash__()" ' - 'that\n' - ' explicitly raises a "TypeError" would be incorrectly ' - 'identified as\n' - ' hashable by an "isinstance(obj, collections.Hashable)" ' - 'call.\n' - '\n' - ' Note: By default, the "__hash__()" values of str, ' - 'bytes and\n' - ' datetime objects are "salted" with an unpredictable ' - 'random value.\n' - ' Although they remain constant within an individual ' - 'Python\n' - ' process, they are not predictable between repeated ' - 'invocations of\n' - ' Python.This is intended to provide protection ' - 'against a denial-\n' - ' of-service caused by carefully-chosen inputs that ' - 'exploit the\n' - ' worst case performance of a dict insertion, O(n^2) ' - 'complexity.\n' - ' See ' - 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' - ' details.Changing hash values affects the iteration ' - 'order of\n' - ' dicts, sets and other mappings. Python has never ' - 'made guarantees\n' - ' about this ordering (and it typically varies between ' - '32-bit and\n' - ' 64-bit builds).See also "PYTHONHASHSEED".\n' - '\n' - ' Changed in version 3.3: Hash randomization is enabled ' - 'by default.\n' - '\n' - 'object.__bool__(self)\n' - '\n' - ' Called to implement truth value testing and the ' - 'built-in operation\n' - ' "bool()"; should return "False" or "True". When this ' - 'method is not\n' - ' defined, "__len__()" is called, if it is defined, and ' - 'the object is\n' - ' considered true if its result is nonzero. If a class ' - 'defines\n' - ' neither "__len__()" nor "__bool__()", all its ' - 'instances are\n' - ' considered true.\n', - 'debugger': '\n' - '"pdb" --- The Python Debugger\n' - '*****************************\n' - '\n' - '**Source code:** Lib/pdb.py\n' - '\n' - '======================================================================\n' - '\n' - 'The module "pdb" defines an interactive source code debugger ' - 'for\n' - 'Python programs. It supports setting (conditional) ' - 'breakpoints and\n' - 'single stepping at the source line level, inspection of stack ' - 'frames,\n' - 'source code listing, and evaluation of arbitrary Python code ' - 'in the\n' - 'context of any stack frame. It also supports post-mortem ' - 'debugging\n' - 'and can be called under program control.\n' - '\n' - 'The debugger is extensible -- it is actually defined as the ' - 'class\n' - '"Pdb". This is currently undocumented but easily understood by ' - 'reading\n' - 'the source. The extension interface uses the modules "bdb" ' - 'and "cmd".\n' - '\n' - 'The debugger\'s prompt is "(Pdb)". Typical usage to run a ' - 'program under\n' - 'control of the debugger is:\n' - '\n' - ' >>> import pdb\n' - ' >>> import mymodule\n' - " >>> pdb.run('mymodule.test()')\n" - ' > (0)?()\n' - ' (Pdb) continue\n' - ' > (1)?()\n' - ' (Pdb) continue\n' - " NameError: 'spam'\n" - ' > (1)?()\n' - ' (Pdb)\n' - '\n' - 'Changed in version 3.3: Tab-completion via the "readline" ' - 'module is\n' - 'available for commands and command arguments, e.g. the current ' - 'global\n' - 'and local names are offered as arguments of the "p" command.\n' - '\n' - '"pdb.py" can also be invoked as a script to debug other ' - 'scripts. For\n' - 'example:\n' - '\n' - ' python3 -m pdb myscript.py\n' - '\n' - 'When invoked as a script, pdb will automatically enter ' - 'post-mortem\n' - 'debugging if the program being debugged exits abnormally. ' - 'After post-\n' - 'mortem debugging (or after normal exit of the program), pdb ' - 'will\n' - "restart the program. Automatic restarting preserves pdb's " - 'state (such\n' - 'as breakpoints) and in most cases is more useful than quitting ' - 'the\n' - "debugger upon program's exit.\n" - '\n' - 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' - 'executes\n' - 'commands as if given in a ".pdbrc" file, see *Debugger ' - 'Commands*.\n' - '\n' - 'The typical usage to break into the debugger from a running ' - 'program is\n' - 'to insert\n' - '\n' - ' import pdb; pdb.set_trace()\n' - '\n' - 'at the location you want to break into the debugger. You can ' - 'then\n' - 'step through the code following this statement, and continue ' - 'running\n' - 'without the debugger using the "continue" command.\n' - '\n' - 'The typical usage to inspect a crashed program is:\n' - '\n' - ' >>> import pdb\n' - ' >>> import mymodule\n' - ' >>> mymodule.test()\n' - ' Traceback (most recent call last):\n' - ' File "", line 1, in ?\n' - ' File "./mymodule.py", line 4, in test\n' - ' test2()\n' - ' File "./mymodule.py", line 3, in test2\n' - ' print(spam)\n' - ' NameError: spam\n' - ' >>> pdb.pm()\n' - ' > ./mymodule.py(3)test2()\n' - ' -> print(spam)\n' - ' (Pdb)\n' - '\n' - 'The module defines the following functions; each enters the ' - 'debugger\n' - 'in a slightly different way:\n' - '\n' - 'pdb.run(statement, globals=None, locals=None)\n' - '\n' - ' Execute the *statement* (given as a string or a code ' - 'object) under\n' - ' debugger control. The debugger prompt appears before any ' - 'code is\n' - ' executed; you can set breakpoints and type "continue", or ' - 'you can\n' - ' step through the statement using "step" or "next" (all ' - 'these\n' - ' commands are explained below). The optional *globals* and ' - '*locals*\n' - ' arguments specify the environment in which the code is ' - 'executed; by\n' - ' default the dictionary of the module "__main__" is used. ' - '(See the\n' - ' explanation of the built-in "exec()" or "eval()" ' - 'functions.)\n' - '\n' - 'pdb.runeval(expression, globals=None, locals=None)\n' - '\n' - ' Evaluate the *expression* (given as a string or a code ' - 'object)\n' - ' under debugger control. When "runeval()" returns, it ' - 'returns the\n' - ' value of the expression. Otherwise this function is ' - 'similar to\n' - ' "run()".\n' - '\n' - 'pdb.runcall(function, *args, **kwds)\n' - '\n' - ' Call the *function* (a function or method object, not a ' - 'string)\n' - ' with the given arguments. When "runcall()" returns, it ' - 'returns\n' - ' whatever the function call returned. The debugger prompt ' - 'appears\n' - ' as soon as the function is entered.\n' - '\n' - 'pdb.set_trace()\n' - '\n' - ' Enter the debugger at the calling stack frame. This is ' - 'useful to\n' - ' hard-code a breakpoint at a given point in a program, even ' - 'if the\n' - ' code is not otherwise being debugged (e.g. when an ' - 'assertion\n' - ' fails).\n' - '\n' - 'pdb.post_mortem(traceback=None)\n' - '\n' - ' Enter post-mortem debugging of the given *traceback* ' - 'object. If no\n' - ' *traceback* is given, it uses the one of the exception that ' - 'is\n' - ' currently being handled (an exception must be being handled ' - 'if the\n' - ' default is to be used).\n' - '\n' - 'pdb.pm()\n' - '\n' - ' Enter post-mortem debugging of the traceback found in\n' - ' "sys.last_traceback".\n' - '\n' - 'The "run*" functions and "set_trace()" are aliases for ' - 'instantiating\n' - 'the "Pdb" class and calling the method of the same name. If ' - 'you want\n' - 'to access further features, you have to do this yourself:\n' - '\n' - "class class pdb.Pdb(completekey='tab', stdin=None, " - 'stdout=None, skip=None, nosigint=False)\n' - '\n' - ' "Pdb" is the debugger class.\n' - '\n' - ' The *completekey*, *stdin* and *stdout* arguments are ' - 'passed to the\n' - ' underlying "cmd.Cmd" class; see the description there.\n' - '\n' - ' The *skip* argument, if given, must be an iterable of ' - 'glob-style\n' - ' module name patterns. The debugger will not step into ' - 'frames that\n' - ' originate in a module that matches one of these patterns. ' - '[1]\n' - '\n' - ' By default, Pdb sets a handler for the SIGINT signal (which ' - 'is sent\n' - ' when the user presses "Ctrl-C" on the console) when you ' - 'give a\n' - ' "continue" command. This allows you to break into the ' - 'debugger\n' - ' again by pressing "Ctrl-C". If you want Pdb not to touch ' - 'the\n' - ' SIGINT handler, set *nosigint* tot true.\n' - '\n' - ' Example call to enable tracing with *skip*:\n' - '\n' - " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" - '\n' - ' New in version 3.1: The *skip* argument.\n' - '\n' - ' New in version 3.2: The *nosigint* argument. Previously, a ' - 'SIGINT\n' - ' handler was never set by Pdb.\n' - '\n' - ' run(statement, globals=None, locals=None)\n' - ' runeval(expression, globals=None, locals=None)\n' - ' runcall(function, *args, **kwds)\n' - ' set_trace()\n' - '\n' - ' See the documentation for the functions explained ' - 'above.\n' - '\n' - '\n' - 'Debugger Commands\n' - '=================\n' - '\n' - 'The commands recognized by the debugger are listed below. ' - 'Most\n' - 'commands can be abbreviated to one or two letters as ' - 'indicated; e.g.\n' - '"h(elp)" means that either "h" or "help" can be used to enter ' - 'the help\n' - 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' - 'Arguments to commands must be separated by whitespace (spaces ' - 'or\n' - 'tabs). Optional arguments are enclosed in square brackets ' - '("[]") in\n' - 'the command syntax; the square brackets must not be typed.\n' - 'Alternatives in the command syntax are separated by a vertical ' - 'bar\n' - '("|").\n' - '\n' - 'Entering a blank line repeats the last command entered. ' - 'Exception: if\n' - 'the last command was a "list" command, the next 11 lines are ' - 'listed.\n' - '\n' - "Commands that the debugger doesn't recognize are assumed to be " - 'Python\n' - 'statements and are executed in the context of the program ' - 'being\n' - 'debugged. Python statements can also be prefixed with an ' - 'exclamation\n' - 'point ("!"). This is a powerful way to inspect the program ' - 'being\n' - 'debugged; it is even possible to change a variable or call a ' - 'function.\n' - 'When an exception occurs in such a statement, the exception ' - 'name is\n' - "printed but the debugger's state is not changed.\n" - '\n' - 'The debugger supports *aliases*. Aliases can have parameters ' - 'which\n' - 'allows one a certain level of adaptability to the context ' - 'under\n' - 'examination.\n' - '\n' - 'Multiple commands may be entered on a single line, separated ' - 'by ";;".\n' - '(A single ";" is not used as it is the separator for multiple ' - 'commands\n' - 'in a line that is passed to the Python parser.) No ' - 'intelligence is\n' - 'applied to separating the commands; the input is split at the ' - 'first\n' - '";;" pair, even if it is in the middle of a quoted string.\n' - '\n' - 'If a file ".pdbrc" exists in the user\'s home directory or in ' - 'the\n' - 'current directory, it is read in and executed as if it had ' - 'been typed\n' - 'at the debugger prompt. This is particularly useful for ' - 'aliases. If\n' - 'both files exist, the one in the home directory is read first ' - 'and\n' - 'aliases defined there can be overridden by the local file.\n' - '\n' - 'Changed in version 3.2: ".pdbrc" can now contain commands ' - 'that\n' - 'continue debugging, such as "continue" or "next". Previously, ' - 'these\n' - 'commands had no effect.\n' - '\n' - 'h(elp) [command]\n' - '\n' - ' Without argument, print the list of available commands. ' - 'With a\n' - ' *command* as argument, print help about that command. ' - '"help pdb"\n' - ' displays the full documentation (the docstring of the ' - '"pdb"\n' - ' module). Since the *command* argument must be an ' - 'identifier, "help\n' - ' exec" must be entered to get help on the "!" command.\n' - '\n' - 'w(here)\n' - '\n' - ' Print a stack trace, with the most recent frame at the ' - 'bottom. An\n' - ' arrow indicates the current frame, which determines the ' - 'context of\n' - ' most commands.\n' - '\n' - 'd(own) [count]\n' - '\n' - ' Move the current frame *count* (default one) levels down in ' - 'the\n' - ' stack trace (to a newer frame).\n' - '\n' - 'u(p) [count]\n' - '\n' - ' Move the current frame *count* (default one) levels up in ' - 'the stack\n' - ' trace (to an older frame).\n' - '\n' - 'b(reak) [([filename:]lineno | function) [, condition]]\n' - '\n' - ' With a *lineno* argument, set a break there in the current ' - 'file.\n' - ' With a *function* argument, set a break at the first ' - 'executable\n' - ' statement within that function. The line number may be ' - 'prefixed\n' - ' with a filename and a colon, to specify a breakpoint in ' - 'another\n' - " file (probably one that hasn't been loaded yet). The file " - 'is\n' - ' searched on "sys.path". Note that each breakpoint is ' - 'assigned a\n' - ' number to which all the other breakpoint commands refer.\n' - '\n' - ' If a second argument is present, it is an expression which ' - 'must\n' - ' evaluate to true before the breakpoint is honored.\n' - '\n' - ' Without argument, list all breaks, including for each ' - 'breakpoint,\n' - ' the number of times that breakpoint has been hit, the ' - 'current\n' - ' ignore count, and the associated condition if any.\n' - '\n' - 'tbreak [([filename:]lineno | function) [, condition]]\n' - '\n' - ' Temporary breakpoint, which is removed automatically when ' - 'it is\n' - ' first hit. The arguments are the same as for "break".\n' - '\n' - 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n' - '\n' - ' With a *filename:lineno* argument, clear all the ' - 'breakpoints at\n' - ' this line. With a space separated list of breakpoint ' - 'numbers, clear\n' - ' those breakpoints. Without argument, clear all breaks (but ' - 'first\n' - ' ask confirmation).\n' - '\n' - 'disable [bpnumber [bpnumber ...]]\n' - '\n' - ' Disable the breakpoints given as a space separated list of\n' - ' breakpoint numbers. Disabling a breakpoint means it cannot ' - 'cause\n' - ' the program to stop execution, but unlike clearing a ' - 'breakpoint, it\n' - ' remains in the list of breakpoints and can be ' - '(re-)enabled.\n' - '\n' - 'enable [bpnumber [bpnumber ...]]\n' - '\n' - ' Enable the breakpoints specified.\n' - '\n' - 'ignore bpnumber [count]\n' - '\n' - ' Set the ignore count for the given breakpoint number. If ' - 'count is\n' - ' omitted, the ignore count is set to 0. A breakpoint ' - 'becomes active\n' - ' when the ignore count is zero. When non-zero, the count ' - 'is\n' - ' decremented each time the breakpoint is reached and the ' - 'breakpoint\n' - ' is not disabled and any associated condition evaluates to ' - 'true.\n' - '\n' - 'condition bpnumber [condition]\n' - '\n' - ' Set a new *condition* for the breakpoint, an expression ' - 'which must\n' - ' evaluate to true before the breakpoint is honored. If ' - '*condition*\n' - ' is absent, any existing condition is removed; i.e., the ' - 'breakpoint\n' - ' is made unconditional.\n' - '\n' - 'commands [bpnumber]\n' - '\n' - ' Specify a list of commands for breakpoint number ' - '*bpnumber*. The\n' - ' commands themselves appear on the following lines. Type a ' - 'line\n' - ' containing just "end" to terminate the commands. An ' - 'example:\n' - '\n' - ' (Pdb) commands 1\n' - ' (com) p some_variable\n' - ' (com) end\n' - ' (Pdb)\n' - '\n' - ' To remove all commands from a breakpoint, type commands and ' - 'follow\n' - ' it immediately with "end"; that is, give no commands.\n' - '\n' - ' With no *bpnumber* argument, commands refers to the last ' - 'breakpoint\n' - ' set.\n' - '\n' - ' You can use breakpoint commands to start your program up ' - 'again.\n' - ' Simply use the continue command, or step, or any other ' - 'command that\n' - ' resumes execution.\n' - '\n' - ' Specifying any command resuming execution (currently ' - 'continue,\n' - ' step, next, return, jump, quit and their abbreviations) ' - 'terminates\n' - ' the command list (as if that command was immediately ' - 'followed by\n' - ' end). This is because any time you resume execution (even ' - 'with a\n' - ' simple next or step), you may encounter another ' - 'breakpoint--which\n' - ' could have its own command list, leading to ambiguities ' - 'about which\n' - ' list to execute.\n' - '\n' - " If you use the 'silent' command in the command list, the " - 'usual\n' - ' message about stopping at a breakpoint is not printed. ' - 'This may be\n' - ' desirable for breakpoints that are to print a specific ' - 'message and\n' - ' then continue. If none of the other commands print ' - 'anything, you\n' - ' see no sign that the breakpoint was reached.\n' - '\n' - 's(tep)\n' - '\n' - ' Execute the current line, stop at the first possible ' - 'occasion\n' - ' (either in a function that is called or on the next line in ' - 'the\n' - ' current function).\n' - '\n' - 'n(ext)\n' - '\n' - ' Continue execution until the next line in the current ' - 'function is\n' - ' reached or it returns. (The difference between "next" and ' - '"step"\n' - ' is that "step" stops inside a called function, while ' - '"next"\n' - ' executes called functions at (nearly) full speed, only ' - 'stopping at\n' - ' the next line in the current function.)\n' - '\n' - 'unt(il) [lineno]\n' - '\n' - ' Without argument, continue execution until the line with a ' - 'number\n' - ' greater than the current one is reached.\n' - '\n' - ' With a line number, continue execution until a line with a ' - 'number\n' - ' greater or equal to that is reached. In both cases, also ' - 'stop when\n' - ' the current frame returns.\n' - '\n' - ' Changed in version 3.2: Allow giving an explicit line ' - 'number.\n' - '\n' - 'r(eturn)\n' - '\n' - ' Continue execution until the current function returns.\n' - '\n' - 'c(ont(inue))\n' - '\n' - ' Continue execution, only stop when a breakpoint is ' - 'encountered.\n' - '\n' - 'j(ump) lineno\n' - '\n' - ' Set the next line that will be executed. Only available in ' - 'the\n' - ' bottom-most frame. This lets you jump back and execute ' - 'code again,\n' - " or jump forward to skip code that you don't want to run.\n" - '\n' - ' It should be noted that not all jumps are allowed -- for ' - 'instance\n' - ' it is not possible to jump into the middle of a "for" loop ' - 'or out\n' - ' of a "finally" clause.\n' - '\n' - 'l(ist) [first[, last]]\n' - '\n' - ' List source code for the current file. Without arguments, ' - 'list 11\n' - ' lines around the current line or continue the previous ' - 'listing.\n' - ' With "." as argument, list 11 lines around the current ' - 'line. With\n' - ' one argument, list 11 lines around at that line. With two\n' - ' arguments, list the given range; if the second argument is ' - 'less\n' - ' than the first, it is interpreted as a count.\n' - '\n' - ' The current line in the current frame is indicated by ' - '"->". If an\n' - ' exception is being debugged, the line where the exception ' - 'was\n' - ' originally raised or propagated is indicated by ">>", if it ' - 'differs\n' - ' from the current line.\n' - '\n' - ' New in version 3.2: The ">>" marker.\n' - '\n' - 'll | longlist\n' - '\n' - ' List all source code for the current function or frame.\n' - ' Interesting lines are marked as for "list".\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'a(rgs)\n' - '\n' - ' Print the argument list of the current function.\n' - '\n' - 'p expression\n' - '\n' - ' Evaluate the *expression* in the current context and print ' - 'its\n' - ' value.\n' - '\n' - ' Note: "print()" can also be used, but is not a debugger ' - 'command\n' - ' --- this executes the Python "print()" function.\n' - '\n' - 'pp expression\n' - '\n' - ' Like the "p" command, except the value of the expression is ' - 'pretty-\n' - ' printed using the "pprint" module.\n' - '\n' - 'whatis expression\n' - '\n' - ' Print the type of the *expression*.\n' - '\n' - 'source expression\n' - '\n' - ' Try to get source code for the given object and display ' - 'it.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'display [expression]\n' - '\n' - ' Display the value of the expression if it changed, each ' - 'time\n' - ' execution stops in the current frame.\n' - '\n' - ' Without expression, list all display expressions for the ' - 'current\n' - ' frame.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'undisplay [expression]\n' - '\n' - ' Do not display the expression any more in the current ' - 'frame.\n' - ' Without expression, clear all display expressions for the ' - 'current\n' - ' frame.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'interact\n' - '\n' - ' Start an interative interpreter (using the "code" module) ' - 'whose\n' - ' global namespace contains all the (global and local) names ' - 'found in\n' - ' the current scope.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'alias [name [command]]\n' - '\n' - ' Create an alias called *name* that executes *command*. The ' - 'command\n' - ' must *not* be enclosed in quotes. Replaceable parameters ' - 'can be\n' - ' indicated by "%1", "%2", and so on, while "%*" is replaced ' - 'by all\n' - ' the parameters. If no command is given, the current alias ' - 'for\n' - ' *name* is shown. If no arguments are given, all aliases are ' - 'listed.\n' - '\n' - ' Aliases may be nested and can contain anything that can be ' - 'legally\n' - ' typed at the pdb prompt. Note that internal pdb commands ' - '*can* be\n' - ' overridden by aliases. Such a command is then hidden until ' - 'the\n' - ' alias is removed. Aliasing is recursively applied to the ' - 'first\n' - ' word of the command line; all other words in the line are ' - 'left\n' - ' alone.\n' - '\n' - ' As an example, here are two useful aliases (especially when ' - 'placed\n' - ' in the ".pdbrc" file):\n' - '\n' - ' # Print instance variables (usage "pi classInst")\n' - ' alias pi for k in %1.__dict__.keys(): ' - 'print("%1.",k,"=",%1.__dict__[k])\n' - ' # Print instance variables in self\n' - ' alias ps pi self\n' - '\n' - 'unalias name\n' - '\n' - ' Delete the specified alias.\n' - '\n' - '! statement\n' - '\n' - ' Execute the (one-line) *statement* in the context of the ' - 'current\n' - ' stack frame. The exclamation point can be omitted unless ' - 'the first\n' - ' word of the statement resembles a debugger command. To set ' - 'a\n' - ' global variable, you can prefix the assignment command with ' - 'a\n' - ' "global" statement on the same line, e.g.:\n' - '\n' - " (Pdb) global list_options; list_options = ['-l']\n" - ' (Pdb)\n' - '\n' - 'run [args ...]\n' - 'restart [args ...]\n' - '\n' - ' Restart the debugged Python program. If an argument is ' - 'supplied,\n' - ' it is split with "shlex" and the result is used as the new\n' - ' "sys.argv". History, breakpoints, actions and debugger ' - 'options are\n' - ' preserved. "restart" is an alias for "run".\n' - '\n' - 'q(uit)\n' - '\n' - ' Quit from the debugger. The program being executed is ' - 'aborted.\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] Whether a frame is considered to originate in a certain ' - 'module\n' - ' is determined by the "__name__" in the frame globals.\n', - 'del': '\n' - 'The "del" statement\n' - '*******************\n' - '\n' - ' del_stmt ::= "del" target_list\n' - '\n' - 'Deletion is recursively defined very similar to the way assignment ' - 'is\n' - 'defined. Rather than spelling it out in full details, here are ' - 'some\n' - 'hints.\n' - '\n' - 'Deletion of a target list recursively deletes each target, from ' - 'left\n' - 'to right.\n' - '\n' - 'Deletion of a name removes the binding of that name from the local ' - 'or\n' - 'global namespace, depending on whether the name occurs in a ' - '"global"\n' - 'statement in the same code block. If the name is unbound, a\n' - '"NameError" exception will be raised.\n' - '\n' - 'Deletion of attribute references, subscriptions and slicings is ' - 'passed\n' - 'to the primary object involved; deletion of a slicing is in ' - 'general\n' - 'equivalent to assignment of an empty slice of the right type (but ' - 'even\n' - 'this is determined by the sliced object).\n' - '\n' - 'Changed in version 3.2: Previously it was illegal to delete a name\n' - 'from the local namespace if it occurs as a free variable in a ' - 'nested\n' - 'block.\n', - 'dict': '\n' - 'Dictionary displays\n' - '*******************\n' - '\n' - 'A dictionary display is a possibly empty series of key/datum ' - 'pairs\n' - 'enclosed in curly braces:\n' - '\n' - ' dict_display ::= "{" [key_datum_list | ' - 'dict_comprehension] "}"\n' - ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' - ' key_datum ::= expression ":" expression\n' - ' dict_comprehension ::= expression ":" expression comp_for\n' - '\n' - 'A dictionary display yields a new dictionary object.\n' - '\n' - 'If a comma-separated sequence of key/datum pairs is given, they ' - 'are\n' - 'evaluated from left to right to define the entries of the ' - 'dictionary:\n' - 'each key object is used as a key into the dictionary to store the\n' - 'corresponding datum. This means that you can specify the same ' - 'key\n' - "multiple times in the key/datum list, and the final dictionary's " - 'value\n' - 'for that key will be the last one given.\n' - '\n' - 'A dict comprehension, in contrast to list and set comprehensions,\n' - 'needs two expressions separated with a colon followed by the ' - 'usual\n' - '"for" and "if" clauses. When the comprehension is run, the ' - 'resulting\n' - 'key and value elements are inserted in the new dictionary in the ' - 'order\n' - 'they are produced.\n' - '\n' - 'Restrictions on the types of the key values are listed earlier in\n' - 'section *The standard type hierarchy*. (To summarize, the key ' - 'type\n' - 'should be *hashable*, which excludes all mutable objects.) ' - 'Clashes\n' - 'between duplicate keys are not detected; the last datum ' - '(textually\n' - 'rightmost in the display) stored for a given key value prevails.\n', - 'dynamic-features': '\n' - 'Interaction with dynamic features\n' - '*********************************\n' - '\n' - 'Name resolution of free variables occurs at runtime, ' - 'not at compile\n' - 'time. This means that the following code will print ' - '42:\n' - '\n' - ' i = 10\n' - ' def f():\n' - ' print(i)\n' - ' i = 42\n' - ' f()\n' - '\n' - 'There are several cases where Python statements are ' - 'illegal when used\n' - 'in conjunction with nested scopes that contain free ' - 'variables.\n' - '\n' - 'If a variable is referenced in an enclosing scope, it ' - 'is illegal to\n' - 'delete the name. An error will be reported at compile ' - 'time.\n' - '\n' - 'The "eval()" and "exec()" functions do not have access ' - 'to the full\n' - 'environment for resolving names. Names may be ' - 'resolved in the local\n' - 'and global namespaces of the caller. Free variables ' - 'are not resolved\n' - 'in the nearest enclosing namespace, but in the global ' - 'namespace. [1]\n' - 'The "exec()" and "eval()" functions have optional ' - 'arguments to\n' - 'override the global and local namespace. If only one ' - 'namespace is\n' - 'specified, it is used for both.\n', - 'else': '\n' - 'The "if" statement\n' - '******************\n' - '\n' - 'The "if" statement is used for conditional execution:\n' - '\n' - ' if_stmt ::= "if" expression ":" suite\n' - ' ( "elif" expression ":" suite )*\n' - ' ["else" ":" suite]\n' - '\n' - 'It selects exactly one of the suites by evaluating the expressions ' - 'one\n' - 'by one until one is found to be true (see section *Boolean ' - 'operations*\n' - 'for the definition of true and false); then that suite is ' - 'executed\n' - '(and no other part of the "if" statement is executed or ' - 'evaluated).\n' - 'If all expressions are false, the suite of the "else" clause, if\n' - 'present, is executed.\n', - 'exceptions': '\n' - 'Exceptions\n' - '**********\n' - '\n' - 'Exceptions are a means of breaking out of the normal flow of ' - 'control\n' - 'of a code block in order to handle errors or other ' - 'exceptional\n' - 'conditions. An exception is *raised* at the point where the ' - 'error is\n' - 'detected; it may be *handled* by the surrounding code block ' - 'or by any\n' - 'code block that directly or indirectly invoked the code ' - 'block where\n' - 'the error occurred.\n' - '\n' - 'The Python interpreter raises an exception when it detects a ' - 'run-time\n' - 'error (such as division by zero). A Python program can ' - 'also\n' - 'explicitly raise an exception with the "raise" statement. ' - 'Exception\n' - 'handlers are specified with the "try" ... "except" ' - 'statement. The\n' - '"finally" clause of such a statement can be used to specify ' - 'cleanup\n' - 'code which does not handle the exception, but is executed ' - 'whether an\n' - 'exception occurred or not in the preceding code.\n' - '\n' - 'Python uses the "termination" model of error handling: an ' - 'exception\n' - 'handler can find out what happened and continue execution at ' - 'an outer\n' - 'level, but it cannot repair the cause of the error and retry ' - 'the\n' - 'failing operation (except by re-entering the offending piece ' - 'of code\n' - 'from the top).\n' - '\n' - 'When an exception is not handled at all, the interpreter ' - 'terminates\n' - 'execution of the program, or returns to its interactive main ' - 'loop. In\n' - 'either case, it prints a stack backtrace, except when the ' - 'exception is\n' - '"SystemExit".\n' - '\n' - 'Exceptions are identified by class instances. The "except" ' - 'clause is\n' - 'selected depending on the class of the instance: it must ' - 'reference the\n' - 'class of the instance or a base class thereof. The instance ' - 'can be\n' - 'received by the handler and can carry additional information ' - 'about the\n' - 'exceptional condition.\n' - '\n' - 'Note: Exception messages are not part of the Python API. ' - 'Their\n' - ' contents may change from one version of Python to the next ' - 'without\n' - ' warning and should not be relied on by code which will run ' - 'under\n' - ' multiple versions of the interpreter.\n' - '\n' - 'See also the description of the "try" statement in section ' - '*The try\n' - 'statement* and "raise" statement in section *The raise ' - 'statement*.\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] This limitation occurs because the code that is executed ' - 'by\n' - ' these operations is not available at the time the module ' - 'is\n' - ' compiled.\n', - 'execmodel': '\n' - 'Execution model\n' - '***************\n' - '\n' - '\n' - 'Structure of a program\n' - '======================\n' - '\n' - 'A Python program is constructed from code blocks. A *block* ' - 'is a piece\n' - 'of Python program text that is executed as a unit. The ' - 'following are\n' - 'blocks: a module, a function body, and a class definition. ' - 'Each\n' - 'command typed interactively is a block. A script file (a ' - 'file given\n' - 'as standard input to the interpreter or specified as a ' - 'command line\n' - 'argument to the interpreter) is a code block. A script ' - 'command (a\n' - 'command specified on the interpreter command line with the ' - "'**-c**'\n" - 'option) is a code block. The string argument passed to the ' - 'built-in\n' - 'functions "eval()" and "exec()" is a code block.\n' - '\n' - 'A code block is executed in an *execution frame*. A frame ' - 'contains\n' - 'some administrative information (used for debugging) and ' - 'determines\n' - "where and how execution continues after the code block's " - 'execution has\n' - 'completed.\n' - '\n' - '\n' - 'Naming and binding\n' - '==================\n' - '\n' - '\n' - 'Binding of names\n' - '----------------\n' - '\n' - '*Names* refer to objects. Names are introduced by name ' - 'binding\n' - 'operations.\n' - '\n' - 'The following constructs bind names: formal parameters to ' - 'functions,\n' - '"import" statements, class and function definitions (these ' - 'bind the\n' - 'class or function name in the defining block), and targets ' - 'that are\n' - 'identifiers if occurring in an assignment, "for" loop header, ' - 'or after\n' - '"as" in a "with" statement or "except" clause. The "import" ' - 'statement\n' - 'of the form "from ... import *" binds all names defined in ' - 'the\n' - 'imported module, except those beginning with an underscore. ' - 'This form\n' - 'may only be used at the module level.\n' - '\n' - 'A target occurring in a "del" statement is also considered ' - 'bound for\n' - 'this purpose (though the actual semantics are to unbind the ' - 'name).\n' - '\n' - 'Each assignment or import statement occurs within a block ' - 'defined by a\n' - 'class or function definition or at the module level (the ' - 'top-level\n' - 'code block).\n' - '\n' - 'If a name is bound in a block, it is a local variable of that ' - 'block,\n' - 'unless declared as "nonlocal" or "global". If a name is ' - 'bound at the\n' - 'module level, it is a global variable. (The variables of the ' - 'module\n' - 'code block are local and global.) If a variable is used in a ' - 'code\n' - 'block but not defined there, it is a *free variable*.\n' - '\n' - 'Each occurrence of a name in the program text refers to the ' - '*binding*\n' - 'of that name established by the following name resolution ' - 'rules.\n' - '\n' - '\n' - 'Resolution of names\n' - '-------------------\n' - '\n' - 'A *scope* defines the visibility of a name within a block. ' - 'If a local\n' - 'variable is defined in a block, its scope includes that ' - 'block. If the\n' - 'definition occurs in a function block, the scope extends to ' - 'any blocks\n' - 'contained within the defining one, unless a contained block ' - 'introduces\n' - 'a different binding for the name.\n' - '\n' - 'When a name is used in a code block, it is resolved using the ' - 'nearest\n' - 'enclosing scope. The set of all such scopes visible to a ' - 'code block\n' - "is called the block's *environment*.\n" - '\n' - 'When a name is not found at all, a "NameError" exception is ' - 'raised. If\n' - 'the current scope is a function scope, and the name refers to ' - 'a local\n' - 'variable that has not yet been bound to a value at the point ' - 'where the\n' - 'name is used, an "UnboundLocalError" exception is raised.\n' - '"UnboundLocalError" is a subclass of "NameError".\n' - '\n' - 'If a name binding operation occurs anywhere within a code ' - 'block, all\n' - 'uses of the name within the block are treated as references ' - 'to the\n' - 'current block. This can lead to errors when a name is used ' - 'within a\n' - 'block before it is bound. This rule is subtle. Python ' - 'lacks\n' - 'declarations and allows name binding operations to occur ' - 'anywhere\n' - 'within a code block. The local variables of a code block can ' - 'be\n' - 'determined by scanning the entire text of the block for name ' - 'binding\n' - 'operations.\n' - '\n' - 'If the "global" statement occurs within a block, all uses of ' - 'the name\n' - 'specified in the statement refer to the binding of that name ' - 'in the\n' - 'top-level namespace. Names are resolved in the top-level ' - 'namespace by\n' - 'searching the global namespace, i.e. the namespace of the ' - 'module\n' - 'containing the code block, and the builtins namespace, the ' - 'namespace\n' - 'of the module "builtins". The global namespace is searched ' - 'first. If\n' - 'the name is not found there, the builtins namespace is ' - 'searched. The\n' - '"global" statement must precede all uses of the name.\n' - '\n' - 'The "global" statement has the same scope as a name binding ' - 'operation\n' - 'in the same block. If the nearest enclosing scope for a free ' - 'variable\n' - 'contains a global statement, the free variable is treated as ' - 'a global.\n' - '\n' - 'The "nonlocal" statement causes corresponding names to refer ' - 'to\n' - 'previously bound variables in the nearest enclosing function ' - 'scope.\n' - '"SyntaxError" is raised at compile time if the given name ' - 'does not\n' - 'exist in any enclosing function scope.\n' - '\n' - 'The namespace for a module is automatically created the first ' - 'time a\n' - 'module is imported. The main module for a script is always ' - 'called\n' - '"__main__".\n' - '\n' - 'Class definition blocks and arguments to "exec()" and ' - '"eval()" are\n' - 'special in the context of name resolution. A class definition ' - 'is an\n' - 'executable statement that may use and define names. These ' - 'references\n' - 'follow the normal rules for name resolution with an exception ' - 'that\n' - 'unbound local variables are looked up in the global ' - 'namespace. The\n' - 'namespace of the class definition becomes the attribute ' - 'dictionary of\n' - 'the class. The scope of names defined in a class block is ' - 'limited to\n' - 'the class block; it does not extend to the code blocks of ' - 'methods --\n' - 'this includes comprehensions and generator expressions since ' - 'they are\n' - 'implemented using a function scope. This means that the ' - 'following\n' - 'will fail:\n' - '\n' - ' class A:\n' - ' a = 42\n' - ' b = list(a + i for i in range(10))\n' - '\n' - '\n' - 'Builtins and restricted execution\n' - '---------------------------------\n' - '\n' - 'The builtins namespace associated with the execution of a ' - 'code block\n' - 'is actually found by looking up the name "__builtins__" in ' - 'its global\n' - 'namespace; this should be a dictionary or a module (in the ' - 'latter case\n' - "the module's dictionary is used). By default, when in the " - '"__main__"\n' - 'module, "__builtins__" is the built-in module "builtins"; ' - 'when in any\n' - 'other module, "__builtins__" is an alias for the dictionary ' - 'of the\n' - '"builtins" module itself. "__builtins__" can be set to a ' - 'user-created\n' - 'dictionary to create a weak form of restricted execution.\n' - '\n' - '**CPython implementation detail:** Users should not touch\n' - '"__builtins__"; it is strictly an implementation detail. ' - 'Users\n' - 'wanting to override values in the builtins namespace should ' - '"import"\n' - 'the "builtins" module and modify its attributes ' - 'appropriately.\n' - '\n' - '\n' - 'Interaction with dynamic features\n' - '---------------------------------\n' - '\n' - 'Name resolution of free variables occurs at runtime, not at ' - 'compile\n' - 'time. This means that the following code will print 42:\n' - '\n' - ' i = 10\n' - ' def f():\n' - ' print(i)\n' - ' i = 42\n' - ' f()\n' - '\n' - 'There are several cases where Python statements are illegal ' - 'when used\n' - 'in conjunction with nested scopes that contain free ' - 'variables.\n' - '\n' - 'If a variable is referenced in an enclosing scope, it is ' - 'illegal to\n' - 'delete the name. An error will be reported at compile time.\n' - '\n' - 'The "eval()" and "exec()" functions do not have access to the ' - 'full\n' - 'environment for resolving names. Names may be resolved in ' - 'the local\n' - 'and global namespaces of the caller. Free variables are not ' - 'resolved\n' - 'in the nearest enclosing namespace, but in the global ' - 'namespace. [1]\n' - 'The "exec()" and "eval()" functions have optional arguments ' - 'to\n' - 'override the global and local namespace. If only one ' - 'namespace is\n' - 'specified, it is used for both.\n' - '\n' - '\n' - 'Exceptions\n' - '==========\n' - '\n' - 'Exceptions are a means of breaking out of the normal flow of ' - 'control\n' - 'of a code block in order to handle errors or other ' - 'exceptional\n' - 'conditions. An exception is *raised* at the point where the ' - 'error is\n' - 'detected; it may be *handled* by the surrounding code block ' - 'or by any\n' - 'code block that directly or indirectly invoked the code block ' - 'where\n' - 'the error occurred.\n' - '\n' - 'The Python interpreter raises an exception when it detects a ' - 'run-time\n' - 'error (such as division by zero). A Python program can also\n' - 'explicitly raise an exception with the "raise" statement. ' - 'Exception\n' - 'handlers are specified with the "try" ... "except" ' - 'statement. The\n' - '"finally" clause of such a statement can be used to specify ' - 'cleanup\n' - 'code which does not handle the exception, but is executed ' - 'whether an\n' - 'exception occurred or not in the preceding code.\n' - '\n' - 'Python uses the "termination" model of error handling: an ' - 'exception\n' - 'handler can find out what happened and continue execution at ' - 'an outer\n' - 'level, but it cannot repair the cause of the error and retry ' - 'the\n' - 'failing operation (except by re-entering the offending piece ' - 'of code\n' - 'from the top).\n' - '\n' - 'When an exception is not handled at all, the interpreter ' - 'terminates\n' - 'execution of the program, or returns to its interactive main ' - 'loop. In\n' - 'either case, it prints a stack backtrace, except when the ' - 'exception is\n' - '"SystemExit".\n' - '\n' - 'Exceptions are identified by class instances. The "except" ' - 'clause is\n' - 'selected depending on the class of the instance: it must ' - 'reference the\n' - 'class of the instance or a base class thereof. The instance ' - 'can be\n' - 'received by the handler and can carry additional information ' - 'about the\n' - 'exceptional condition.\n' - '\n' - 'Note: Exception messages are not part of the Python API. ' - 'Their\n' - ' contents may change from one version of Python to the next ' - 'without\n' - ' warning and should not be relied on by code which will run ' - 'under\n' - ' multiple versions of the interpreter.\n' - '\n' - 'See also the description of the "try" statement in section ' - '*The try\n' - 'statement* and "raise" statement in section *The raise ' - 'statement*.\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] This limitation occurs because the code that is executed ' - 'by\n' - ' these operations is not available at the time the module ' - 'is\n' - ' compiled.\n', - 'exprlists': '\n' - 'Expression lists\n' - '****************\n' - '\n' - ' expression_list ::= expression ( "," expression )* [","]\n' - '\n' - 'An expression list containing at least one comma yields a ' - 'tuple. The\n' - 'length of the tuple is the number of expressions in the ' - 'list. The\n' - 'expressions are evaluated from left to right.\n' - '\n' - 'The trailing comma is required only to create a single tuple ' - '(a.k.a. a\n' - '*singleton*); it is optional in all other cases. A single ' - 'expression\n' - "without a trailing comma doesn't create a tuple, but rather " - 'yields the\n' - 'value of that expression. (To create an empty tuple, use an ' - 'empty pair\n' - 'of parentheses: "()".)\n', - 'floating': '\n' - 'Floating point literals\n' - '***********************\n' - '\n' - 'Floating point literals are described by the following ' - 'lexical\n' - 'definitions:\n' - '\n' - ' floatnumber ::= pointfloat | exponentfloat\n' - ' pointfloat ::= [intpart] fraction | intpart "."\n' - ' exponentfloat ::= (intpart | pointfloat) exponent\n' - ' intpart ::= digit+\n' - ' fraction ::= "." digit+\n' - ' exponent ::= ("e" | "E") ["+" | "-"] digit+\n' - '\n' - 'Note that the integer and exponent parts are always ' - 'interpreted using\n' - 'radix 10. For example, "077e010" is legal, and denotes the ' - 'same number\n' - 'as "77e10". The allowed range of floating point literals is\n' - 'implementation-dependent. Some examples of floating point ' - 'literals:\n' - '\n' - ' 3.14 10. .001 1e100 3.14e-10 0e0\n' - '\n' - 'Note that numeric literals do not include a sign; a phrase ' - 'like "-1"\n' - 'is actually an expression composed of the unary operator "-" ' - 'and the\n' - 'literal "1".\n', - 'for': '\n' - 'The "for" statement\n' - '*******************\n' - '\n' - 'The "for" statement is used to iterate over the elements of a ' - 'sequence\n' - '(such as a string, tuple or list) or other iterable object:\n' - '\n' - ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n' - ' ["else" ":" suite]\n' - '\n' - 'The expression list is evaluated once; it should yield an iterable\n' - 'object. An iterator is created for the result of the\n' - '"expression_list". The suite is then executed once for each item\n' - 'provided by the iterator, in the order returned by the iterator. ' - 'Each\n' - 'item in turn is assigned to the target list using the standard ' - 'rules\n' - 'for assignments (see *Assignment statements*), and then the suite ' - 'is\n' - 'executed. When the items are exhausted (which is immediately when ' - 'the\n' - 'sequence is empty or an iterator raises a "StopIteration" ' - 'exception),\n' - 'the suite in the "else" clause, if present, is executed, and the ' - 'loop\n' - 'terminates.\n' - '\n' - 'A "break" statement executed in the first suite terminates the ' - 'loop\n' - 'without executing the "else" clause\'s suite. A "continue" ' - 'statement\n' - 'executed in the first suite skips the rest of the suite and ' - 'continues\n' - 'with the next item, or with the "else" clause if there is no next\n' - 'item.\n' - '\n' - 'The for-loop makes assignments to the variables(s) in the target ' - 'list.\n' - 'This overwrites all previous assignments to those variables ' - 'including\n' - 'those made in the suite of the for-loop:\n' - '\n' - ' for i in range(10):\n' - ' print(i)\n' - ' i = 5 # this will not affect the for-loop\n' - ' # because i will be overwritten with the ' - 'next\n' - ' # index in the range\n' - '\n' - 'Names in the target list are not deleted when the loop is ' - 'finished,\n' - 'but if the sequence is empty, they will not have been assigned to ' - 'at\n' - 'all by the loop. Hint: the built-in function "range()" returns an\n' - "iterator of integers suitable to emulate the effect of Pascal's " - '"for i\n' - ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' - '2]".\n' - '\n' - 'Note: There is a subtlety when the sequence is being modified by ' - 'the\n' - ' loop (this can only occur for mutable sequences, i.e. lists). ' - 'An\n' - ' internal counter is used to keep track of which item is used ' - 'next,\n' - ' and this is incremented on each iteration. When this counter ' - 'has\n' - ' reached the length of the sequence the loop terminates. This ' - 'means\n' - ' that if the suite deletes the current (or a previous) item from ' - 'the\n' - ' sequence, the next item will be skipped (since it gets the index ' - 'of\n' - ' the current item which has already been treated). Likewise, if ' - 'the\n' - ' suite inserts an item in the sequence before the current item, ' - 'the\n' - ' current item will be treated again the next time through the ' - 'loop.\n' - ' This can lead to nasty bugs that can be avoided by making a\n' - ' temporary copy using a slice of the whole sequence, e.g.,\n' - '\n' - ' for x in a[:]:\n' - ' if x < 0: a.remove(x)\n', - 'formatstrings': '\n' - 'Format String Syntax\n' - '********************\n' - '\n' - 'The "str.format()" method and the "Formatter" class share ' - 'the same\n' - 'syntax for format strings (although in the case of ' - '"Formatter",\n' - 'subclasses can define their own format string syntax).\n' - '\n' - 'Format strings contain "replacement fields" surrounded by ' - 'curly braces\n' - '"{}". Anything that is not contained in braces is ' - 'considered literal\n' - 'text, which is copied unchanged to the output. If you ' - 'need to include\n' - 'a brace character in the literal text, it can be escaped ' - 'by doubling:\n' - '"{{" and "}}".\n' - '\n' - 'The grammar for a replacement field is as follows:\n' - '\n' - ' replacement_field ::= "{" [field_name] ["!" ' - 'conversion] [":" format_spec] "}"\n' - ' field_name ::= arg_name ("." attribute_name ' - '| "[" element_index "]")*\n' - ' arg_name ::= [identifier | integer]\n' - ' attribute_name ::= identifier\n' - ' element_index ::= integer | index_string\n' - ' index_string ::= +\n' - ' conversion ::= "r" | "s" | "a"\n' - ' format_spec ::= \n' - '\n' - 'In less formal terms, the replacement field can start ' - 'with a\n' - '*field_name* that specifies the object whose value is to ' - 'be formatted\n' - 'and inserted into the output instead of the replacement ' - 'field. The\n' - '*field_name* is optionally followed by a *conversion* ' - 'field, which is\n' - 'preceded by an exclamation point "\'!\'", and a ' - '*format_spec*, which is\n' - 'preceded by a colon "\':\'". These specify a non-default ' - 'format for the\n' - 'replacement value.\n' - '\n' - 'See also the *Format Specification Mini-Language* ' - 'section.\n' - '\n' - 'The *field_name* itself begins with an *arg_name* that is ' - 'either a\n' - "number or a keyword. If it's a number, it refers to a " - 'positional\n' - "argument, and if it's a keyword, it refers to a named " - 'keyword\n' - 'argument. If the numerical arg_names in a format string ' - 'are 0, 1, 2,\n' - '... in sequence, they can all be omitted (not just some) ' - 'and the\n' - 'numbers 0, 1, 2, ... will be automatically inserted in ' - 'that order.\n' - 'Because *arg_name* is not quote-delimited, it is not ' - 'possible to\n' - 'specify arbitrary dictionary keys (e.g., the strings ' - '"\'10\'" or\n' - '"\':-]\'") within a format string. The *arg_name* can be ' - 'followed by any\n' - 'number of index or attribute expressions. An expression ' - 'of the form\n' - '"\'.name\'" selects the named attribute using ' - '"getattr()", while an\n' - 'expression of the form "\'[index]\'" does an index lookup ' - 'using\n' - '"__getitem__()".\n' - '\n' - 'Changed in version 3.1: The positional argument ' - 'specifiers can be\n' - 'omitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n' - '\n' - 'Some simple format string examples:\n' - '\n' - ' "First, thou shalt count to {0}" # References first ' - 'positional argument\n' - ' "Bring me a {}" # Implicitly ' - 'references the first positional argument\n' - ' "From {} to {}" # Same as "From {0} ' - 'to {1}"\n' - ' "My quest is {name}" # References keyword ' - "argument 'name'\n" - ' "Weight in tons {0.weight}" # \'weight\' ' - 'attribute of first positional arg\n' - ' "Units destroyed: {players[0]}" # First element of ' - "keyword argument 'players'.\n" - '\n' - 'The *conversion* field causes a type coercion before ' - 'formatting.\n' - 'Normally, the job of formatting a value is done by the ' - '"__format__()"\n' - 'method of the value itself. However, in some cases it is ' - 'desirable to\n' - 'force a type to be formatted as a string, overriding its ' - 'own\n' - 'definition of formatting. By converting the value to a ' - 'string before\n' - 'calling "__format__()", the normal formatting logic is ' - 'bypassed.\n' - '\n' - 'Three conversion flags are currently supported: "\'!s\'" ' - 'which calls\n' - '"str()" on the value, "\'!r\'" which calls "repr()" and ' - '"\'!a\'" which\n' - 'calls "ascii()".\n' - '\n' - 'Some examples:\n' - '\n' - ' "Harold\'s a clever {0!s}" # Calls str() on the ' - 'argument first\n' - ' "Bring out the holy {name!r}" # Calls repr() on the ' - 'argument first\n' - ' "More {!a}" # Calls ascii() on ' - 'the argument first\n' - '\n' - 'The *format_spec* field contains a specification of how ' - 'the value\n' - 'should be presented, including such details as field ' - 'width, alignment,\n' - 'padding, decimal precision and so on. Each value type ' - 'can define its\n' - 'own "formatting mini-language" or interpretation of the ' - '*format_spec*.\n' - '\n' - 'Most built-in types support a common formatting ' - 'mini-language, which\n' - 'is described in the next section.\n' - '\n' - 'A *format_spec* field can also include nested replacement ' - 'fields\n' - 'within it. These nested replacement fields can contain ' - 'only a field\n' - 'name; conversion flags and format specifications are not ' - 'allowed. The\n' - 'replacement fields within the format_spec are substituted ' - 'before the\n' - '*format_spec* string is interpreted. This allows the ' - 'formatting of a\n' - 'value to be dynamically specified.\n' - '\n' - 'See the *Format examples* section for some examples.\n' - '\n' - '\n' - 'Format Specification Mini-Language\n' - '==================================\n' - '\n' - '"Format specifications" are used within replacement ' - 'fields contained\n' - 'within a format string to define how individual values ' - 'are presented\n' - '(see *Format String Syntax*). They can also be passed ' - 'directly to the\n' - 'built-in "format()" function. Each formattable type may ' - 'define how\n' - 'the format specification is to be interpreted.\n' - '\n' - 'Most built-in types implement the following options for ' - 'format\n' - 'specifications, although some of the formatting options ' - 'are only\n' - 'supported by the numeric types.\n' - '\n' - 'A general convention is that an empty format string ' - '("""") produces\n' - 'the same result as if you had called "str()" on the ' - 'value. A non-empty\n' - 'format string typically modifies the result.\n' - '\n' - 'The general form of a *standard format specifier* is:\n' - '\n' - ' format_spec ::= ' - '[[fill]align][sign][#][0][width][,][.precision][type]\n' - ' fill ::= \n' - ' align ::= "<" | ">" | "=" | "^"\n' - ' sign ::= "+" | "-" | " "\n' - ' width ::= integer\n' - ' precision ::= integer\n' - ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' - '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' - '\n' - 'If a valid *align* value is specified, it can be preceded ' - 'by a *fill*\n' - 'character that can be any character and defaults to a ' - 'space if\n' - 'omitted. Note that it is not possible to use "{" and "}" ' - 'as *fill*\n' - 'char while using the "str.format()" method; this ' - 'limitation however\n' - 'doesn\'t affect the "format()" function.\n' - '\n' - 'The meaning of the various alignment options is as ' - 'follows:\n' - '\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | Option | ' - 'Meaning ' - '|\n' - ' ' - '+===========+============================================================+\n' - ' | "\'<\'" | Forces the field to be left-aligned ' - 'within the available |\n' - ' | | space (this is the default for most ' - 'objects). |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'>\'" | Forces the field to be right-aligned ' - 'within the available |\n' - ' | | space (this is the default for ' - 'numbers). |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'=\'" | Forces the padding to be placed after ' - 'the sign (if any) |\n' - ' | | but before the digits. This is used for ' - 'printing fields |\n' - " | | in the form '+000000120'. This alignment " - 'option is only |\n' - ' | | valid for numeric ' - 'types. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'^\'" | Forces the field to be centered within ' - 'the available |\n' - ' | | ' - 'space. ' - '|\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - '\n' - 'Note that unless a minimum field width is defined, the ' - 'field width\n' - 'will always be the same size as the data to fill it, so ' - 'that the\n' - 'alignment option has no meaning in this case.\n' - '\n' - 'The *sign* option is only valid for number types, and can ' - 'be one of\n' - 'the following:\n' - '\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | Option | ' - 'Meaning ' - '|\n' - ' ' - '+===========+============================================================+\n' - ' | "\'+\'" | indicates that a sign should be used ' - 'for both positive as |\n' - ' | | well as negative ' - 'numbers. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'-\'" | indicates that a sign should be used ' - 'only for negative |\n' - ' | | numbers (this is the default ' - 'behavior). |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | space | indicates that a leading space should be ' - 'used on positive |\n' - ' | | numbers, and a minus sign on negative ' - 'numbers. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - '\n' - 'The "\'#\'" option causes the "alternate form" to be used ' - 'for the\n' - 'conversion. The alternate form is defined differently ' - 'for different\n' - 'types. This option is only valid for integer, float, ' - 'complex and\n' - 'Decimal types. For integers, when binary, octal, or ' - 'hexadecimal output\n' - 'is used, this option adds the prefix respective "\'0b\'", ' - '"\'0o\'", or\n' - '"\'0x\'" to the output value. For floats, complex and ' - 'Decimal the\n' - 'alternate form causes the result of the conversion to ' - 'always contain a\n' - 'decimal-point character, even if no digits follow it. ' - 'Normally, a\n' - 'decimal-point character appears in the result of these ' - 'conversions\n' - 'only if a digit follows it. In addition, for "\'g\'" and ' - '"\'G\'"\n' - 'conversions, trailing zeros are not removed from the ' - 'result.\n' - '\n' - 'The "\',\'" option signals the use of a comma for a ' - 'thousands separator.\n' - 'For a locale aware separator, use the "\'n\'" integer ' - 'presentation type\n' - 'instead.\n' - '\n' - 'Changed in version 3.1: Added the "\',\'" option (see ' - 'also **PEP 378**).\n' - '\n' - '*width* is a decimal integer defining the minimum field ' - 'width. If not\n' - 'specified, then the field width will be determined by the ' - 'content.\n' - '\n' - 'Preceding the *width* field by a zero ("\'0\'") character ' - 'enables sign-\n' - 'aware zero-padding for numeric types. This is equivalent ' - 'to a *fill*\n' - 'character of "\'0\'" with an *alignment* type of ' - '"\'=\'".\n' - '\n' - 'The *precision* is a decimal number indicating how many ' - 'digits should\n' - 'be displayed after the decimal point for a floating point ' - 'value\n' - 'formatted with "\'f\'" and "\'F\'", or before and after ' - 'the decimal point\n' - 'for a floating point value formatted with "\'g\'" or ' - '"\'G\'". For non-\n' - 'number types the field indicates the maximum field size - ' - 'in other\n' - 'words, how many characters will be used from the field ' - 'content. The\n' - '*precision* is not allowed for integer values.\n' - '\n' - 'Finally, the *type* determines how the data should be ' - 'presented.\n' - '\n' - 'The available string presentation types are:\n' - '\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | Type | ' - 'Meaning ' - '|\n' - ' ' - '+===========+============================================================+\n' - ' | "\'s\'" | String format. This is the default ' - 'type for strings and |\n' - ' | | may be ' - 'omitted. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | None | The same as ' - '"\'s\'". |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - '\n' - 'The available integer presentation types are:\n' - '\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | Type | ' - 'Meaning ' - '|\n' - ' ' - '+===========+============================================================+\n' - ' | "\'b\'" | Binary format. Outputs the number in ' - 'base 2. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'c\'" | Character. Converts the integer to the ' - 'corresponding |\n' - ' | | unicode character before ' - 'printing. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'d\'" | Decimal Integer. Outputs the number in ' - 'base 10. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'o\'" | Octal format. Outputs the number in ' - 'base 8. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'x\'" | Hex format. Outputs the number in base ' - '16, using lower- |\n' - ' | | case letters for the digits above ' - '9. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'X\'" | Hex format. Outputs the number in base ' - '16, using upper- |\n' - ' | | case letters for the digits above ' - '9. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'n\'" | Number. This is the same as "\'d\'", ' - 'except that it uses the |\n' - ' | | current locale setting to insert the ' - 'appropriate number |\n' - ' | | separator ' - 'characters. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | None | The same as ' - '"\'d\'". |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - '\n' - 'In addition to the above presentation types, integers can ' - 'be formatted\n' - 'with the floating point presentation types listed below ' - '(except "\'n\'"\n' - 'and None). When doing so, "float()" is used to convert ' - 'the integer to\n' - 'a floating point number before formatting.\n' - '\n' - 'The available presentation types for floating point and ' - 'decimal values\n' - 'are:\n' - '\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | Type | ' - 'Meaning ' - '|\n' - ' ' - '+===========+============================================================+\n' - ' | "\'e\'" | Exponent notation. Prints the number ' - 'in scientific |\n' - " | | notation using the letter 'e' to " - 'indicate the exponent. |\n' - ' | | The default precision is ' - '"6". |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' - 'except it uses an upper |\n' - " | | case 'E' as the separator " - 'character. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'f\'" | Fixed point. Displays the number as a ' - 'fixed-point number. |\n' - ' | | The default precision is ' - '"6". |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'F\'" | Fixed point. Same as "\'f\'", but ' - 'converts "nan" to "NAN" |\n' - ' | | and "inf" to ' - '"INF". |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'g\'" | General format. For a given precision ' - '"p >= 1", this |\n' - ' | | rounds the number to "p" significant ' - 'digits and then |\n' - ' | | formats the result in either fixed-point ' - 'format or in |\n' - ' | | scientific notation, depending on its ' - 'magnitude. The |\n' - ' | | precise rules are as follows: suppose ' - 'that the result |\n' - ' | | formatted with presentation type "\'e\'" ' - 'and precision "p-1" |\n' - ' | | would have exponent "exp". Then if "-4 ' - '<= exp < p", the |\n' - ' | | number is formatted with presentation ' - 'type "\'f\'" and |\n' - ' | | precision "p-1-exp". Otherwise, the ' - 'number is formatted |\n' - ' | | with presentation type "\'e\'" and ' - 'precision "p-1". In both |\n' - ' | | cases insignificant trailing zeros are ' - 'removed from the |\n' - ' | | significand, and the decimal point is ' - 'also removed if |\n' - ' | | there are no remaining digits following ' - 'it. Positive and |\n' - ' | | negative infinity, positive and negative ' - 'zero, and nans, |\n' - ' | | are formatted as "inf", "-inf", "0", ' - '"-0" and "nan" |\n' - ' | | respectively, regardless of the ' - 'precision. A precision of |\n' - ' | | "0" is treated as equivalent to a ' - 'precision of "1". The |\n' - ' | | default precision is ' - '"6". |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'G\'" | General format. Same as "\'g\'" except ' - 'switches to "\'E\'" if |\n' - ' | | the number gets too large. The ' - 'representations of infinity |\n' - ' | | and NaN are uppercased, ' - 'too. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'n\'" | Number. This is the same as "\'g\'", ' - 'except that it uses the |\n' - ' | | current locale setting to insert the ' - 'appropriate number |\n' - ' | | separator ' - 'characters. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | "\'%\'" | Percentage. Multiplies the number by ' - '100 and displays in |\n' - ' | | fixed ("\'f\'") format, followed by a ' - 'percent sign. |\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - ' | None | Similar to "\'g\'", except that ' - 'fixed-point notation, when |\n' - ' | | used, has at least one digit past the ' - 'decimal point. The |\n' - ' | | default precision is as high as needed ' - 'to represent the |\n' - ' | | particular value. The overall effect is ' - 'to match the |\n' - ' | | output of "str()" as altered by the ' - 'other format |\n' - ' | | ' - 'modifiers. ' - '|\n' - ' ' - '+-----------+------------------------------------------------------------+\n' - '\n' - '\n' - 'Format examples\n' - '===============\n' - '\n' - 'This section contains examples of the new format syntax ' - 'and comparison\n' - 'with the old "%"-formatting.\n' - '\n' - 'In most of the cases the syntax is similar to the old ' - '"%"-formatting,\n' - 'with the addition of the "{}" and with ":" used instead ' - 'of "%". For\n' - 'example, "\'%03.2f\'" can be translated to ' - '"\'{:03.2f}\'".\n' - '\n' - 'The new format syntax also supports new and different ' - 'options, shown\n' - 'in the follow examples.\n' - '\n' - 'Accessing arguments by position:\n' - '\n' - " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" - " 'a, b, c'\n" - " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" - " 'a, b, c'\n" - " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" - " 'c, b, a'\n" - " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking " - 'argument sequence\n' - " 'c, b, a'\n" - " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' " - 'indices can be repeated\n' - " 'abracadabra'\n" - '\n' - 'Accessing arguments by name:\n' - '\n' - " >>> 'Coordinates: {latitude}, " - "{longitude}'.format(latitude='37.24N', " - "longitude='-115.81W')\n" - " 'Coordinates: 37.24N, -115.81W'\n" - " >>> coord = {'latitude': '37.24N', 'longitude': " - "'-115.81W'}\n" - " >>> 'Coordinates: {latitude}, " - "{longitude}'.format(**coord)\n" - " 'Coordinates: 37.24N, -115.81W'\n" - '\n' - "Accessing arguments' attributes:\n" - '\n' - ' >>> c = 3-5j\n' - " >>> ('The complex number {0} is formed from the real " - "part {0.real} '\n" - " ... 'and the imaginary part {0.imag}.').format(c)\n" - " 'The complex number (3-5j) is formed from the real " - "part 3.0 and the imaginary part -5.0.'\n" - ' >>> class Point:\n' - ' ... def __init__(self, x, y):\n' - ' ... self.x, self.y = x, y\n' - ' ... def __str__(self):\n' - " ... return 'Point({self.x}, " - "{self.y})'.format(self=self)\n" - ' ...\n' - ' >>> str(Point(4, 2))\n' - " 'Point(4, 2)'\n" - '\n' - "Accessing arguments' items:\n" - '\n' - ' >>> coord = (3, 5)\n' - " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" - " 'X: 3; Y: 5'\n" - '\n' - 'Replacing "%s" and "%r":\n' - '\n' - ' >>> "repr() shows quotes: {!r}; str() doesn\'t: ' - '{!s}".format(\'test1\', \'test2\')\n' - ' "repr() shows quotes: \'test1\'; str() doesn\'t: ' - 'test2"\n' - '\n' - 'Aligning the text and specifying a width:\n' - '\n' - " >>> '{:<30}'.format('left aligned')\n" - " 'left aligned '\n" - " >>> '{:>30}'.format('right aligned')\n" - " ' right aligned'\n" - " >>> '{:^30}'.format('centered')\n" - " ' centered '\n" - " >>> '{:*^30}'.format('centered') # use '*' as a fill " - 'char\n' - " '***********centered***********'\n" - '\n' - 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n' - '\n' - " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it " - 'always\n' - " '+3.140000; -3.140000'\n" - " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space " - 'for positive numbers\n' - " ' 3.140000; -3.140000'\n" - " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only " - "the minus -- same as '{:f}; {:f}'\n" - " '3.140000; -3.140000'\n" - '\n' - 'Replacing "%x" and "%o" and converting the value to ' - 'different bases:\n' - '\n' - ' >>> # format also supports binary numbers\n' - ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: ' - '{0:b}".format(42)\n' - " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n" - ' >>> # with 0x, 0o, or 0b as prefix:\n' - ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: ' - '{0:#b}".format(42)\n' - " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n" - '\n' - 'Using the comma as a thousands separator:\n' - '\n' - " >>> '{:,}'.format(1234567890)\n" - " '1,234,567,890'\n" - '\n' - 'Expressing a percentage:\n' - '\n' - ' >>> points = 19\n' - ' >>> total = 22\n' - " >>> 'Correct answers: {:.2%}'.format(points/total)\n" - " 'Correct answers: 86.36%'\n" - '\n' - 'Using type-specific formatting:\n' - '\n' - ' >>> import datetime\n' - ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n' - " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n" - " '2010-07-04 12:15:58'\n" - '\n' - 'Nesting arguments and more complex examples:\n' - '\n' - " >>> for align, text in zip('<^>', ['left', 'center', " - "'right']):\n" - " ... '{0:{fill}{align}16}'.format(text, fill=align, " - 'align=align)\n' - ' ...\n' - " 'left<<<<<<<<<<<<'\n" - " '^^^^^center^^^^^'\n" - " '>>>>>>>>>>>right'\n" - ' >>>\n' - ' >>> octets = [192, 168, 0, 1]\n' - " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n" - " 'C0A80001'\n" - ' >>> int(_, 16)\n' - ' 3232235521\n' - ' >>>\n' - ' >>> width = 5\n' - ' >>> for num in range(5,12): #doctest: ' - '+NORMALIZE_WHITESPACE\n' - " ... for base in 'dXob':\n" - " ... print('{0:{width}{base}}'.format(num, " - "base=base, width=width), end=' ')\n" - ' ... print()\n' - ' ...\n' - ' 5 5 5 101\n' - ' 6 6 6 110\n' - ' 7 7 7 111\n' - ' 8 8 10 1000\n' - ' 9 9 11 1001\n' - ' 10 A 12 1010\n' - ' 11 B 13 1011\n', - 'function': '\n' - 'Function definitions\n' - '********************\n' - '\n' - 'A function definition defines a user-defined function object ' - '(see\n' - 'section *The standard type hierarchy*):\n' - '\n' - ' funcdef ::= [decorators] "def" funcname "(" ' - '[parameter_list] ")" ["->" expression] ":" suite\n' - ' decorators ::= decorator+\n' - ' decorator ::= "@" dotted_name ["(" [parameter_list ' - '[","]] ")"] NEWLINE\n' - ' dotted_name ::= identifier ("." identifier)*\n' - ' parameter_list ::= (defparameter ",")*\n' - ' | "*" [parameter] ("," defparameter)* ' - '["," "**" parameter]\n' - ' | "**" parameter\n' - ' | defparameter [","] )\n' - ' parameter ::= identifier [":" expression]\n' - ' defparameter ::= parameter ["=" expression]\n' - ' funcname ::= identifier\n' - '\n' - 'A function definition is an executable statement. Its ' - 'execution binds\n' - 'the function name in the current local namespace to a function ' - 'object\n' - '(a wrapper around the executable code for the function). ' - 'This\n' - 'function object contains a reference to the current global ' - 'namespace\n' - 'as the global namespace to be used when the function is ' - 'called.\n' - '\n' - 'The function definition does not execute the function body; ' - 'this gets\n' - 'executed only when the function is called. [3]\n' - '\n' - 'A function definition may be wrapped by one or more ' - '*decorator*\n' - 'expressions. Decorator expressions are evaluated when the ' - 'function is\n' - 'defined, in the scope that contains the function definition. ' - 'The\n' - 'result must be a callable, which is invoked with the function ' - 'object\n' - 'as the only argument. The returned value is bound to the ' - 'function name\n' - 'instead of the function object. Multiple decorators are ' - 'applied in\n' - 'nested fashion. For example, the following code\n' - '\n' - ' @f1(arg)\n' - ' @f2\n' - ' def func(): pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' def func(): pass\n' - ' func = f1(arg)(f2(func))\n' - '\n' - 'When one or more *parameters* have the form *parameter* "="\n' - '*expression*, the function is said to have "default parameter ' - 'values."\n' - 'For a parameter with a default value, the corresponding ' - '*argument* may\n' - "be omitted from a call, in which case the parameter's default " - 'value is\n' - 'substituted. If a parameter has a default value, all ' - 'following\n' - 'parameters up until the ""*"" must also have a default value ' - '--- this\n' - 'is a syntactic restriction that is not expressed by the ' - 'grammar.\n' - '\n' - '**Default parameter values are evaluated from left to right ' - 'when the\n' - 'function definition is executed.** This means that the ' - 'expression is\n' - 'evaluated once, when the function is defined, and that the ' - 'same "pre-\n' - 'computed" value is used for each call. This is especially ' - 'important\n' - 'to understand when a default parameter is a mutable object, ' - 'such as a\n' - 'list or a dictionary: if the function modifies the object ' - '(e.g. by\n' - 'appending an item to a list), the default value is in effect ' - 'modified.\n' - 'This is generally not what was intended. A way around this is ' - 'to use\n' - '"None" as the default, and explicitly test for it in the body ' - 'of the\n' - 'function, e.g.:\n' - '\n' - ' def whats_on_the_telly(penguin=None):\n' - ' if penguin is None:\n' - ' penguin = []\n' - ' penguin.append("property of the zoo")\n' - ' return penguin\n' - '\n' - 'Function call semantics are described in more detail in ' - 'section\n' - '*Calls*. A function call always assigns values to all ' - 'parameters\n' - 'mentioned in the parameter list, either from position ' - 'arguments, from\n' - 'keyword arguments, or from default values. If the form\n' - '""*identifier"" is present, it is initialized to a tuple ' - 'receiving any\n' - 'excess positional parameters, defaulting to the empty tuple. ' - 'If the\n' - 'form ""**identifier"" is present, it is initialized to a new\n' - 'dictionary receiving any excess keyword arguments, defaulting ' - 'to a new\n' - 'empty dictionary. Parameters after ""*"" or ""*identifier"" ' - 'are\n' - 'keyword-only parameters and may only be passed used keyword ' - 'arguments.\n' - '\n' - 'Parameters may have annotations of the form "": expression"" ' - 'following\n' - 'the parameter name. Any parameter may have an annotation even ' - 'those\n' - 'of the form "*identifier" or "**identifier". Functions may ' - 'have\n' - '"return" annotation of the form ""-> expression"" after the ' - 'parameter\n' - 'list. These annotations can be any valid Python expression ' - 'and are\n' - 'evaluated when the function definition is executed. ' - 'Annotations may\n' - 'be evaluated in a different order than they appear in the ' - 'source code.\n' - 'The presence of annotations does not change the semantics of ' - 'a\n' - 'function. The annotation values are available as values of a\n' - "dictionary keyed by the parameters' names in the " - '"__annotations__"\n' - 'attribute of the function object.\n' - '\n' - 'It is also possible to create anonymous functions (functions ' - 'not bound\n' - 'to a name), for immediate use in expressions. This uses ' - 'lambda\n' - 'expressions, described in section *Lambdas*. Note that the ' - 'lambda\n' - 'expression is merely a shorthand for a simplified function ' - 'definition;\n' - 'a function defined in a ""def"" statement can be passed around ' - 'or\n' - 'assigned to another name just like a function defined by a ' - 'lambda\n' - 'expression. The ""def"" form is actually more powerful since ' - 'it\n' - 'allows the execution of multiple statements and annotations.\n' - '\n' - "**Programmer's note:** Functions are first-class objects. A " - '""def""\n' - 'statement executed inside a function definition defines a ' - 'local\n' - 'function that can be returned or passed around. Free ' - 'variables used\n' - 'in the nested function can access the local variables of the ' - 'function\n' - 'containing the def. See section *Naming and binding* for ' - 'details.\n' - '\n' - 'See also: **PEP 3107** - Function Annotations\n' - '\n' - ' The original specification for function annotations.\n', - 'global': '\n' - 'The "global" statement\n' - '**********************\n' - '\n' - ' global_stmt ::= "global" identifier ("," identifier)*\n' - '\n' - 'The "global" statement is a declaration which holds for the ' - 'entire\n' - 'current code block. It means that the listed identifiers are to ' - 'be\n' - 'interpreted as globals. It would be impossible to assign to a ' - 'global\n' - 'variable without "global", although free variables may refer to\n' - 'globals without being declared global.\n' - '\n' - 'Names listed in a "global" statement must not be used in the ' - 'same code\n' - 'block textually preceding that "global" statement.\n' - '\n' - 'Names listed in a "global" statement must not be defined as ' - 'formal\n' - 'parameters or in a "for" loop control target, "class" ' - 'definition,\n' - 'function definition, or "import" statement.\n' - '\n' - '**CPython implementation detail:** The current implementation ' - 'does not\n' - 'enforce the two restrictions, but programs should not abuse ' - 'this\n' - 'freedom, as future implementations may enforce them or silently ' - 'change\n' - 'the meaning of the program.\n' - '\n' - '**Programmer\'s note:** the "global" is a directive to the ' - 'parser. It\n' - 'applies only to code parsed at the same time as the "global"\n' - 'statement. In particular, a "global" statement contained in a ' - 'string\n' - 'or code object supplied to the built-in "exec()" function does ' - 'not\n' - 'affect the code block *containing* the function call, and code\n' - 'contained in such a string is unaffected by "global" statements ' - 'in the\n' - 'code containing the function call. The same applies to the ' - '"eval()"\n' - 'and "compile()" functions.\n', - 'id-classes': '\n' - 'Reserved classes of identifiers\n' - '*******************************\n' - '\n' - 'Certain classes of identifiers (besides keywords) have ' - 'special\n' - 'meanings. These classes are identified by the patterns of ' - 'leading and\n' - 'trailing underscore characters:\n' - '\n' - '"_*"\n' - ' Not imported by "from module import *". The special ' - 'identifier "_"\n' - ' is used in the interactive interpreter to store the ' - 'result of the\n' - ' last evaluation; it is stored in the "builtins" module. ' - 'When not\n' - ' in interactive mode, "_" has no special meaning and is ' - 'not defined.\n' - ' See section *The import statement*.\n' - '\n' - ' Note: The name "_" is often used in conjunction with\n' - ' internationalization; refer to the documentation for ' - 'the\n' - ' "gettext" module for more information on this ' - 'convention.\n' - '\n' - '"__*__"\n' - ' System-defined names. These names are defined by the ' - 'interpreter\n' - ' and its implementation (including the standard library). ' - 'Current\n' - ' system names are discussed in the *Special method names* ' - 'section\n' - ' and elsewhere. More will likely be defined in future ' - 'versions of\n' - ' Python. *Any* use of "__*__" names, in any context, that ' - 'does not\n' - ' follow explicitly documented use, is subject to breakage ' - 'without\n' - ' warning.\n' - '\n' - '"__*"\n' - ' Class-private names. Names in this category, when used ' - 'within the\n' - ' context of a class definition, are re-written to use a ' - 'mangled form\n' - ' to help avoid name clashes between "private" attributes ' - 'of base and\n' - ' derived classes. See section *Identifiers (Names)*.\n', - 'identifiers': '\n' - 'Identifiers and keywords\n' - '************************\n' - '\n' - 'Identifiers (also referred to as *names*) are described by ' - 'the\n' - 'following lexical definitions.\n' - '\n' - 'The syntax of identifiers in Python is based on the Unicode ' - 'standard\n' - 'annex UAX-31, with elaboration and changes as defined ' - 'below; see also\n' - '**PEP 3131** for further details.\n' - '\n' - 'Within the ASCII range (U+0001..U+007F), the valid ' - 'characters for\n' - 'identifiers are the same as in Python 2.x: the uppercase ' - 'and lowercase\n' - 'letters "A" through "Z", the underscore "_" and, except for ' - 'the first\n' - 'character, the digits "0" through "9".\n' - '\n' - 'Python 3.0 introduces additional characters from outside ' - 'the ASCII\n' - 'range (see **PEP 3131**). For these characters, the ' - 'classification\n' - 'uses the version of the Unicode Character Database as ' - 'included in the\n' - '"unicodedata" module.\n' - '\n' - 'Identifiers are unlimited in length. Case is significant.\n' - '\n' - ' identifier ::= xid_start xid_continue*\n' - ' id_start ::= \n' - ' id_continue ::= \n' - ' xid_start ::= \n' - ' xid_continue ::= \n' - '\n' - 'The Unicode category codes mentioned above stand for:\n' - '\n' - '* *Lu* - uppercase letters\n' - '\n' - '* *Ll* - lowercase letters\n' - '\n' - '* *Lt* - titlecase letters\n' - '\n' - '* *Lm* - modifier letters\n' - '\n' - '* *Lo* - other letters\n' - '\n' - '* *Nl* - letter numbers\n' - '\n' - '* *Mn* - nonspacing marks\n' - '\n' - '* *Mc* - spacing combining marks\n' - '\n' - '* *Nd* - decimal numbers\n' - '\n' - '* *Pc* - connector punctuations\n' - '\n' - '* *Other_ID_Start* - explicit list of characters in ' - 'PropList.txt to\n' - ' support backwards compatibility\n' - '\n' - '* *Other_ID_Continue* - likewise\n' - '\n' - 'All identifiers are converted into the normal form NFKC ' - 'while parsing;\n' - 'comparison of identifiers is based on NFKC.\n' - '\n' - 'A non-normative HTML file listing all valid identifier ' - 'characters for\n' - 'Unicode 4.1 can be found at http://www.dcl.hpi.uni-\n' - 'potsdam.de/home/loewis/table-3131.html.\n' - '\n' - '\n' - 'Keywords\n' - '========\n' - '\n' - 'The following identifiers are used as reserved words, or ' - '*keywords* of\n' - 'the language, and cannot be used as ordinary identifiers. ' - 'They must\n' - 'be spelled exactly as written here:\n' - '\n' - ' False class finally is return\n' - ' None continue for lambda try\n' - ' True def from nonlocal while\n' - ' and del global not with\n' - ' as elif if or yield\n' - ' assert else import pass\n' - ' break except in raise\n' - '\n' - '\n' - 'Reserved classes of identifiers\n' - '===============================\n' - '\n' - 'Certain classes of identifiers (besides keywords) have ' - 'special\n' - 'meanings. These classes are identified by the patterns of ' - 'leading and\n' - 'trailing underscore characters:\n' - '\n' - '"_*"\n' - ' Not imported by "from module import *". The special ' - 'identifier "_"\n' - ' is used in the interactive interpreter to store the ' - 'result of the\n' - ' last evaluation; it is stored in the "builtins" module. ' - 'When not\n' - ' in interactive mode, "_" has no special meaning and is ' - 'not defined.\n' - ' See section *The import statement*.\n' - '\n' - ' Note: The name "_" is often used in conjunction with\n' - ' internationalization; refer to the documentation for ' - 'the\n' - ' "gettext" module for more information on this ' - 'convention.\n' - '\n' - '"__*__"\n' - ' System-defined names. These names are defined by the ' - 'interpreter\n' - ' and its implementation (including the standard ' - 'library). Current\n' - ' system names are discussed in the *Special method names* ' - 'section\n' - ' and elsewhere. More will likely be defined in future ' - 'versions of\n' - ' Python. *Any* use of "__*__" names, in any context, ' - 'that does not\n' - ' follow explicitly documented use, is subject to breakage ' - 'without\n' - ' warning.\n' - '\n' - '"__*"\n' - ' Class-private names. Names in this category, when used ' - 'within the\n' - ' context of a class definition, are re-written to use a ' - 'mangled form\n' - ' to help avoid name clashes between "private" attributes ' - 'of base and\n' - ' derived classes. See section *Identifiers (Names)*.\n', - 'if': '\n' - 'The "if" statement\n' - '******************\n' - '\n' - 'The "if" statement is used for conditional execution:\n' - '\n' - ' if_stmt ::= "if" expression ":" suite\n' - ' ( "elif" expression ":" suite )*\n' - ' ["else" ":" suite]\n' - '\n' - 'It selects exactly one of the suites by evaluating the expressions ' - 'one\n' - 'by one until one is found to be true (see section *Boolean ' - 'operations*\n' - 'for the definition of true and false); then that suite is executed\n' - '(and no other part of the "if" statement is executed or evaluated).\n' - 'If all expressions are false, the suite of the "else" clause, if\n' - 'present, is executed.\n', - 'imaginary': '\n' - 'Imaginary literals\n' - '******************\n' - '\n' - 'Imaginary literals are described by the following lexical ' - 'definitions:\n' - '\n' - ' imagnumber ::= (floatnumber | intpart) ("j" | "J")\n' - '\n' - 'An imaginary literal yields a complex number with a real part ' - 'of 0.0.\n' - 'Complex numbers are represented as a pair of floating point ' - 'numbers\n' - 'and have the same restrictions on their range. To create a ' - 'complex\n' - 'number with a nonzero real part, add a floating point number ' - 'to it,\n' - 'e.g., "(3+4j)". Some examples of imaginary literals:\n' - '\n' - ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j\n', - 'import': '\n' - 'The "import" statement\n' - '**********************\n' - '\n' - ' import_stmt ::= "import" module ["as" name] ( "," module ' - '["as" name] )*\n' - ' | "from" relative_module "import" identifier ' - '["as" name]\n' - ' ( "," identifier ["as" name] )*\n' - ' | "from" relative_module "import" "(" ' - 'identifier ["as" name]\n' - ' ( "," identifier ["as" name] )* [","] ")"\n' - ' | "from" module "import" "*"\n' - ' module ::= (identifier ".")* identifier\n' - ' relative_module ::= "."* module | "."+\n' - ' name ::= identifier\n' - '\n' - 'The basic import statement (no "from" clause) is executed in ' - 'two\n' - 'steps:\n' - '\n' - '1. find a module, loading and initializing it if necessary\n' - '\n' - '2. define a name or names in the local namespace for the scope\n' - ' where the "import" statement occurs.\n' - '\n' - 'When the statement contains multiple clauses (separated by ' - 'commas) the\n' - 'two steps are carried out separately for each clause, just as ' - 'though\n' - 'the clauses had been separated out into individiual import ' - 'statements.\n' - '\n' - 'The details of the first step, finding and loading modules are\n' - 'described in greater detail in the section on the *import ' - 'system*,\n' - 'which also describes the various types of packages and modules ' - 'that\n' - 'can be imported, as well as all the hooks that can be used to\n' - 'customize the import system. Note that failures in this step ' - 'may\n' - 'indicate either that the module could not be located, *or* that ' - 'an\n' - 'error occurred while initializing the module, which includes ' - 'execution\n' - "of the module's code.\n" - '\n' - 'If the requested module is retrieved successfully, it will be ' - 'made\n' - 'available in the local namespace in one of three ways:\n' - '\n' - '* If the module name is followed by "as", then the name ' - 'following\n' - ' "as" is bound directly to the imported module.\n' - '\n' - '* If no other name is specified, and the module being imported ' - 'is a\n' - " top level module, the module's name is bound in the local " - 'namespace\n' - ' as a reference to the imported module\n' - '\n' - '* If the module being imported is *not* a top level module, then ' - 'the\n' - ' name of the top level package that contains the module is ' - 'bound in\n' - ' the local namespace as a reference to the top level package. ' - 'The\n' - ' imported module must be accessed using its full qualified ' - 'name\n' - ' rather than directly\n' - '\n' - 'The "from" form uses a slightly more complex process:\n' - '\n' - '1. find the module specified in the "from" clause, loading and\n' - ' initializing it if necessary;\n' - '\n' - '2. for each of the identifiers specified in the "import" ' - 'clauses:\n' - '\n' - ' 1. check if the imported module has an attribute by that ' - 'name\n' - '\n' - ' 2. if not, attempt to import a submodule with that name and ' - 'then\n' - ' check the imported module again for that attribute\n' - '\n' - ' 3. if the attribute is not found, "ImportError" is raised.\n' - '\n' - ' 4. otherwise, a reference to that value is stored in the ' - 'local\n' - ' namespace, using the name in the "as" clause if it is ' - 'present,\n' - ' otherwise using the attribute name\n' - '\n' - 'Examples:\n' - '\n' - ' import foo # foo imported and bound locally\n' - ' import foo.bar.baz # foo.bar.baz imported, foo bound ' - 'locally\n' - ' import foo.bar.baz as fbb # foo.bar.baz imported and bound ' - 'as fbb\n' - ' from foo.bar import baz # foo.bar.baz imported and bound ' - 'as baz\n' - ' from foo import attr # foo imported and foo.attr bound ' - 'as attr\n' - '\n' - 'If the list of identifiers is replaced by a star ("\'*\'"), all ' - 'public\n' - 'names defined in the module are bound in the local namespace for ' - 'the\n' - 'scope where the "import" statement occurs.\n' - '\n' - 'The *public names* defined by a module are determined by ' - 'checking the\n' - 'module\'s namespace for a variable named "__all__"; if defined, ' - 'it must\n' - 'be a sequence of strings which are names defined or imported by ' - 'that\n' - 'module. The names given in "__all__" are all considered public ' - 'and\n' - 'are required to exist. If "__all__" is not defined, the set of ' - 'public\n' - "names includes all names found in the module's namespace which " - 'do not\n' - 'begin with an underscore character ("\'_\'"). "__all__" should ' - 'contain\n' - 'the entire public API. It is intended to avoid accidentally ' - 'exporting\n' - 'items that are not part of the API (such as library modules ' - 'which were\n' - 'imported and used within the module).\n' - '\n' - 'The wild card form of import --- "from module import *" --- is ' - 'only\n' - 'allowed at the module level. Attempting to use it in class or\n' - 'function definitions will raise a "SyntaxError".\n' - '\n' - 'When specifying what module to import you do not have to specify ' - 'the\n' - 'absolute name of the module. When a module or package is ' - 'contained\n' - 'within another package it is possible to make a relative import ' - 'within\n' - 'the same top package without having to mention the package name. ' - 'By\n' - 'using leading dots in the specified module or package after ' - '"from" you\n' - 'can specify how high to traverse up the current package ' - 'hierarchy\n' - 'without specifying exact names. One leading dot means the ' - 'current\n' - 'package where the module making the import exists. Two dots ' - 'means up\n' - 'one package level. Three dots is up two levels, etc. So if you ' - 'execute\n' - '"from . import mod" from a module in the "pkg" package then you ' - 'will\n' - 'end up importing "pkg.mod". If you execute "from ..subpkg2 ' - 'import mod"\n' - 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". ' - 'The\n' - 'specification for relative imports is contained within **PEP ' - '328**.\n' - '\n' - '"importlib.import_module()" is provided to support applications ' - 'that\n' - 'determine dynamically the modules to be loaded.\n' - '\n' - '\n' - 'Future statements\n' - '=================\n' - '\n' - 'A *future statement* is a directive to the compiler that a ' - 'particular\n' - 'module should be compiled using syntax or semantics that will ' - 'be\n' - 'available in a specified future release of Python where the ' - 'feature\n' - 'becomes standard.\n' - '\n' - 'The future statement is intended to ease migration to future ' - 'versions\n' - 'of Python that introduce incompatible changes to the language. ' - 'It\n' - 'allows use of the new features on a per-module basis before the\n' - 'release in which the feature becomes standard.\n' - '\n' - ' future_statement ::= "from" "__future__" "import" feature ' - '["as" name]\n' - ' ("," feature ["as" name])*\n' - ' | "from" "__future__" "import" "(" ' - 'feature ["as" name]\n' - ' ("," feature ["as" name])* [","] ")"\n' - ' feature ::= identifier\n' - ' name ::= identifier\n' - '\n' - 'A future statement must appear near the top of the module. The ' - 'only\n' - 'lines that can appear before a future statement are:\n' - '\n' - '* the module docstring (if any),\n' - '\n' - '* comments,\n' - '\n' - '* blank lines, and\n' - '\n' - '* other future statements.\n' - '\n' - 'The features recognized by Python 3.0 are "absolute_import",\n' - '"division", "generators", "unicode_literals", "print_function",\n' - '"nested_scopes" and "with_statement". They are all redundant ' - 'because\n' - 'they are always enabled, and only kept for backwards ' - 'compatibility.\n' - '\n' - 'A future statement is recognized and treated specially at ' - 'compile\n' - 'time: Changes to the semantics of core constructs are often\n' - 'implemented by generating different code. It may even be the ' - 'case\n' - 'that a new feature introduces new incompatible syntax (such as a ' - 'new\n' - 'reserved word), in which case the compiler may need to parse ' - 'the\n' - 'module differently. Such decisions cannot be pushed off until\n' - 'runtime.\n' - '\n' - 'For any given release, the compiler knows which feature names ' - 'have\n' - 'been defined, and raises a compile-time error if a future ' - 'statement\n' - 'contains a feature not known to it.\n' - '\n' - 'The direct runtime semantics are the same as for any import ' - 'statement:\n' - 'there is a standard module "__future__", described later, and it ' - 'will\n' - 'be imported in the usual way at the time the future statement ' - 'is\n' - 'executed.\n' - '\n' - 'The interesting runtime semantics depend on the specific ' - 'feature\n' - 'enabled by the future statement.\n' - '\n' - 'Note that there is nothing special about the statement:\n' - '\n' - ' import __future__ [as name]\n' - '\n' - "That is not a future statement; it's an ordinary import " - 'statement with\n' - 'no special semantics or syntax restrictions.\n' - '\n' - 'Code compiled by calls to the built-in functions "exec()" and\n' - '"compile()" that occur in a module "M" containing a future ' - 'statement\n' - 'will, by default, use the new syntax or semantics associated ' - 'with the\n' - 'future statement. This can be controlled by optional arguments ' - 'to\n' - '"compile()" --- see the documentation of that function for ' - 'details.\n' - '\n' - 'A future statement typed at an interactive interpreter prompt ' - 'will\n' - 'take effect for the rest of the interpreter session. If an\n' - 'interpreter is started with the *-i* option, is passed a script ' - 'name\n' - 'to execute, and the script includes a future statement, it will ' - 'be in\n' - 'effect in the interactive session started after the script is\n' - 'executed.\n' - '\n' - 'See also: **PEP 236** - Back to the __future__\n' - '\n' - ' The original proposal for the __future__ mechanism.\n', - 'in': '\n' - 'Membership test operations\n' - '**************************\n' - '\n' - 'The operators "in" and "not in" test for membership. "x in s"\n' - 'evaluates to true if *x* is a member of *s*, and false otherwise. ' - '"x\n' - 'not in s" returns the negation of "x in s". All built-in sequences\n' - 'and set types support this as well as dictionary, for which "in" ' - 'tests\n' - 'whether the dictionary has a given key. For container types such as\n' - 'list, tuple, set, frozenset, dict, or collections.deque, the\n' - 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n' - 'y)".\n' - '\n' - 'For the string and bytes types, "x in y" is true if and only if *x* ' - 'is\n' - 'a substring of *y*. An equivalent test is "y.find(x) != -1". ' - 'Empty\n' - 'strings are always considered to be a substring of any other ' - 'string,\n' - 'so """ in "abc"" will return "True".\n' - '\n' - 'For user-defined classes which define the "__contains__()" method, ' - '"x\n' - 'in y" is true if and only if "y.__contains__(x)" is true.\n' - '\n' - 'For user-defined classes which do not define "__contains__()" but ' - 'do\n' - 'define "__iter__()", "x in y" is true if some value "z" with "x == ' - 'z"\n' - 'is produced while iterating over "y". If an exception is raised\n' - 'during the iteration, it is as if "in" raised that exception.\n' - '\n' - 'Lastly, the old-style iteration protocol is tried: if a class ' - 'defines\n' - '"__getitem__()", "x in y" is true if and only if there is a non-\n' - 'negative integer index *i* such that "x == y[i]", and all lower\n' - 'integer indices do not raise "IndexError" exception. (If any other\n' - 'exception is raised, it is as if "in" raised that exception).\n' - '\n' - 'The operator "not in" is defined to have the inverse true value of\n' - '"in".\n', - 'integers': '\n' - 'Integer literals\n' - '****************\n' - '\n' - 'Integer literals are described by the following lexical ' - 'definitions:\n' - '\n' - ' integer ::= decimalinteger | octinteger | hexinteger ' - '| bininteger\n' - ' decimalinteger ::= nonzerodigit digit* | "0"+\n' - ' nonzerodigit ::= "1"..."9"\n' - ' digit ::= "0"..."9"\n' - ' octinteger ::= "0" ("o" | "O") octdigit+\n' - ' hexinteger ::= "0" ("x" | "X") hexdigit+\n' - ' bininteger ::= "0" ("b" | "B") bindigit+\n' - ' octdigit ::= "0"..."7"\n' - ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' - ' bindigit ::= "0" | "1"\n' - '\n' - 'There is no limit for the length of integer literals apart ' - 'from what\n' - 'can be stored in available memory.\n' - '\n' - 'Note that leading zeros in a non-zero decimal number are not ' - 'allowed.\n' - 'This is for disambiguation with C-style octal literals, which ' - 'Python\n' - 'used before version 3.0.\n' - '\n' - 'Some examples of integer literals:\n' - '\n' - ' 7 2147483647 0o177 ' - '0b100110111\n' - ' 3 79228162514264337593543950336 0o377 ' - '0xdeadbeef\n', - 'lambda': '\n' - 'Lambdas\n' - '*******\n' - '\n' - ' lambda_expr ::= "lambda" [parameter_list]: expression\n' - ' lambda_expr_nocond ::= "lambda" [parameter_list]: ' - 'expression_nocond\n' - '\n' - 'Lambda expressions (sometimes called lambda forms) are used to ' - 'create\n' - 'anonymous functions. The expression "lambda arguments: ' - 'expression"\n' - 'yields a function object. The unnamed object behaves like a ' - 'function\n' - 'object defined with\n' - '\n' - ' def (arguments):\n' - ' return expression\n' - '\n' - 'See section *Function definitions* for the syntax of parameter ' - 'lists.\n' - 'Note that functions created with lambda expressions cannot ' - 'contain\n' - 'statements or annotations.\n', - 'lists': '\n' - 'List displays\n' - '*************\n' - '\n' - 'A list display is a possibly empty series of expressions enclosed ' - 'in\n' - 'square brackets:\n' - '\n' - ' list_display ::= "[" [expression_list | comprehension] "]"\n' - '\n' - 'A list display yields a new list object, the contents being ' - 'specified\n' - 'by either a list of expressions or a comprehension. When a ' - 'comma-\n' - 'separated list of expressions is supplied, its elements are ' - 'evaluated\n' - 'from left to right and placed into the list object in that ' - 'order.\n' - 'When a comprehension is supplied, the list is constructed from ' - 'the\n' - 'elements resulting from the comprehension.\n', - 'naming': '\n' - 'Naming and binding\n' - '******************\n' - '\n' - '\n' - 'Binding of names\n' - '================\n' - '\n' - '*Names* refer to objects. Names are introduced by name binding\n' - 'operations.\n' - '\n' - 'The following constructs bind names: formal parameters to ' - 'functions,\n' - '"import" statements, class and function definitions (these bind ' - 'the\n' - 'class or function name in the defining block), and targets that ' - 'are\n' - 'identifiers if occurring in an assignment, "for" loop header, or ' - 'after\n' - '"as" in a "with" statement or "except" clause. The "import" ' - 'statement\n' - 'of the form "from ... import *" binds all names defined in the\n' - 'imported module, except those beginning with an underscore. ' - 'This form\n' - 'may only be used at the module level.\n' - '\n' - 'A target occurring in a "del" statement is also considered bound ' - 'for\n' - 'this purpose (though the actual semantics are to unbind the ' - 'name).\n' - '\n' - 'Each assignment or import statement occurs within a block ' - 'defined by a\n' - 'class or function definition or at the module level (the ' - 'top-level\n' - 'code block).\n' - '\n' - 'If a name is bound in a block, it is a local variable of that ' - 'block,\n' - 'unless declared as "nonlocal" or "global". If a name is bound ' - 'at the\n' - 'module level, it is a global variable. (The variables of the ' - 'module\n' - 'code block are local and global.) If a variable is used in a ' - 'code\n' - 'block but not defined there, it is a *free variable*.\n' - '\n' - 'Each occurrence of a name in the program text refers to the ' - '*binding*\n' - 'of that name established by the following name resolution ' - 'rules.\n' - '\n' - '\n' - 'Resolution of names\n' - '===================\n' - '\n' - 'A *scope* defines the visibility of a name within a block. If a ' - 'local\n' - 'variable is defined in a block, its scope includes that block. ' - 'If the\n' - 'definition occurs in a function block, the scope extends to any ' - 'blocks\n' - 'contained within the defining one, unless a contained block ' - 'introduces\n' - 'a different binding for the name.\n' - '\n' - 'When a name is used in a code block, it is resolved using the ' - 'nearest\n' - 'enclosing scope. The set of all such scopes visible to a code ' - 'block\n' - "is called the block's *environment*.\n" - '\n' - 'When a name is not found at all, a "NameError" exception is ' - 'raised. If\n' - 'the current scope is a function scope, and the name refers to a ' - 'local\n' - 'variable that has not yet been bound to a value at the point ' - 'where the\n' - 'name is used, an "UnboundLocalError" exception is raised.\n' - '"UnboundLocalError" is a subclass of "NameError".\n' - '\n' - 'If a name binding operation occurs anywhere within a code block, ' - 'all\n' - 'uses of the name within the block are treated as references to ' - 'the\n' - 'current block. This can lead to errors when a name is used ' - 'within a\n' - 'block before it is bound. This rule is subtle. Python lacks\n' - 'declarations and allows name binding operations to occur ' - 'anywhere\n' - 'within a code block. The local variables of a code block can ' - 'be\n' - 'determined by scanning the entire text of the block for name ' - 'binding\n' - 'operations.\n' - '\n' - 'If the "global" statement occurs within a block, all uses of the ' - 'name\n' - 'specified in the statement refer to the binding of that name in ' - 'the\n' - 'top-level namespace. Names are resolved in the top-level ' - 'namespace by\n' - 'searching the global namespace, i.e. the namespace of the ' - 'module\n' - 'containing the code block, and the builtins namespace, the ' - 'namespace\n' - 'of the module "builtins". The global namespace is searched ' - 'first. If\n' - 'the name is not found there, the builtins namespace is ' - 'searched. The\n' - '"global" statement must precede all uses of the name.\n' - '\n' - 'The "global" statement has the same scope as a name binding ' - 'operation\n' - 'in the same block. If the nearest enclosing scope for a free ' - 'variable\n' - 'contains a global statement, the free variable is treated as a ' - 'global.\n' - '\n' - 'The "nonlocal" statement causes corresponding names to refer to\n' - 'previously bound variables in the nearest enclosing function ' - 'scope.\n' - '"SyntaxError" is raised at compile time if the given name does ' - 'not\n' - 'exist in any enclosing function scope.\n' - '\n' - 'The namespace for a module is automatically created the first ' - 'time a\n' - 'module is imported. The main module for a script is always ' - 'called\n' - '"__main__".\n' - '\n' - 'Class definition blocks and arguments to "exec()" and "eval()" ' - 'are\n' - 'special in the context of name resolution. A class definition is ' - 'an\n' - 'executable statement that may use and define names. These ' - 'references\n' - 'follow the normal rules for name resolution with an exception ' - 'that\n' - 'unbound local variables are looked up in the global namespace. ' - 'The\n' - 'namespace of the class definition becomes the attribute ' - 'dictionary of\n' - 'the class. The scope of names defined in a class block is ' - 'limited to\n' - 'the class block; it does not extend to the code blocks of ' - 'methods --\n' - 'this includes comprehensions and generator expressions since ' - 'they are\n' - 'implemented using a function scope. This means that the ' - 'following\n' - 'will fail:\n' - '\n' - ' class A:\n' - ' a = 42\n' - ' b = list(a + i for i in range(10))\n' - '\n' - '\n' - 'Builtins and restricted execution\n' - '=================================\n' - '\n' - 'The builtins namespace associated with the execution of a code ' - 'block\n' - 'is actually found by looking up the name "__builtins__" in its ' - 'global\n' - 'namespace; this should be a dictionary or a module (in the ' - 'latter case\n' - "the module's dictionary is used). By default, when in the " - '"__main__"\n' - 'module, "__builtins__" is the built-in module "builtins"; when ' - 'in any\n' - 'other module, "__builtins__" is an alias for the dictionary of ' - 'the\n' - '"builtins" module itself. "__builtins__" can be set to a ' - 'user-created\n' - 'dictionary to create a weak form of restricted execution.\n' - '\n' - '**CPython implementation detail:** Users should not touch\n' - '"__builtins__"; it is strictly an implementation detail. Users\n' - 'wanting to override values in the builtins namespace should ' - '"import"\n' - 'the "builtins" module and modify its attributes appropriately.\n' - '\n' - '\n' - 'Interaction with dynamic features\n' - '=================================\n' - '\n' - 'Name resolution of free variables occurs at runtime, not at ' - 'compile\n' - 'time. This means that the following code will print 42:\n' - '\n' - ' i = 10\n' - ' def f():\n' - ' print(i)\n' - ' i = 42\n' - ' f()\n' - '\n' - 'There are several cases where Python statements are illegal when ' - 'used\n' - 'in conjunction with nested scopes that contain free variables.\n' - '\n' - 'If a variable is referenced in an enclosing scope, it is illegal ' - 'to\n' - 'delete the name. An error will be reported at compile time.\n' - '\n' - 'The "eval()" and "exec()" functions do not have access to the ' - 'full\n' - 'environment for resolving names. Names may be resolved in the ' - 'local\n' - 'and global namespaces of the caller. Free variables are not ' - 'resolved\n' - 'in the nearest enclosing namespace, but in the global ' - 'namespace. [1]\n' - 'The "exec()" and "eval()" functions have optional arguments to\n' - 'override the global and local namespace. If only one namespace ' - 'is\n' - 'specified, it is used for both.\n', - 'nonlocal': '\n' - 'The "nonlocal" statement\n' - '************************\n' - '\n' - ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' - '\n' - 'The "nonlocal" statement causes the listed identifiers to ' - 'refer to\n' - 'previously bound variables in the nearest enclosing scope ' - 'excluding\n' - 'globals. This is important because the default behavior for ' - 'binding is\n' - 'to search the local namespace first. The statement allows\n' - 'encapsulated code to rebind variables outside of the local ' - 'scope\n' - 'besides the global (module) scope.\n' - '\n' - 'Names listed in a "nonlocal" statement, unlike those listed in ' - 'a\n' - '"global" statement, must refer to pre-existing bindings in an\n' - 'enclosing scope (the scope in which a new binding should be ' - 'created\n' - 'cannot be determined unambiguously).\n' - '\n' - 'Names listed in a "nonlocal" statement must not collide with ' - 'pre-\n' - 'existing bindings in the local scope.\n' - '\n' - 'See also: **PEP 3104** - Access to Names in Outer Scopes\n' - '\n' - ' The specification for the "nonlocal" statement.\n', - 'numbers': '\n' - 'Numeric literals\n' - '****************\n' - '\n' - 'There are three types of numeric literals: integers, floating ' - 'point\n' - 'numbers, and imaginary numbers. There are no complex literals\n' - '(complex numbers can be formed by adding a real number and an\n' - 'imaginary number).\n' - '\n' - 'Note that numeric literals do not include a sign; a phrase like ' - '"-1"\n' - 'is actually an expression composed of the unary operator ' - '\'"-"\' and the\n' - 'literal "1".\n', - 'numeric-types': '\n' - 'Emulating numeric types\n' - '***********************\n' - '\n' - 'The following methods can be defined to emulate numeric ' - 'objects.\n' - 'Methods corresponding to operations that are not ' - 'supported by the\n' - 'particular kind of number implemented (e.g., bitwise ' - 'operations for\n' - 'non-integral numbers) should be left undefined.\n' - '\n' - 'object.__add__(self, other)\n' - 'object.__sub__(self, other)\n' - 'object.__mul__(self, other)\n' - 'object.__truediv__(self, other)\n' - 'object.__floordiv__(self, other)\n' - 'object.__mod__(self, other)\n' - 'object.__divmod__(self, other)\n' - 'object.__pow__(self, other[, modulo])\n' - 'object.__lshift__(self, other)\n' - 'object.__rshift__(self, other)\n' - 'object.__and__(self, other)\n' - 'object.__xor__(self, other)\n' - 'object.__or__(self, other)\n' - '\n' - ' These methods are called to implement the binary ' - 'arithmetic\n' - ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' - '"pow()",\n' - ' "**", "<<", ">>", "&", "^", "|"). For instance, to ' - 'evaluate the\n' - ' expression "x + y", where *x* is an instance of a ' - 'class that has an\n' - ' "__add__()" method, "x.__add__(y)" is called. The ' - '"__divmod__()"\n' - ' method should be the equivalent to using ' - '"__floordiv__()" and\n' - ' "__mod__()"; it should not be related to ' - '"__truediv__()". Note\n' - ' that "__pow__()" should be defined to accept an ' - 'optional third\n' - ' argument if the ternary version of the built-in ' - '"pow()" function is\n' - ' to be supported.\n' - '\n' - ' If one of those methods does not support the operation ' - 'with the\n' - ' supplied arguments, it should return ' - '"NotImplemented".\n' - '\n' - 'object.__radd__(self, other)\n' - 'object.__rsub__(self, other)\n' - 'object.__rmul__(self, other)\n' - 'object.__rtruediv__(self, other)\n' - 'object.__rfloordiv__(self, other)\n' - 'object.__rmod__(self, other)\n' - 'object.__rdivmod__(self, other)\n' - 'object.__rpow__(self, other)\n' - 'object.__rlshift__(self, other)\n' - 'object.__rrshift__(self, other)\n' - 'object.__rand__(self, other)\n' - 'object.__rxor__(self, other)\n' - 'object.__ror__(self, other)\n' - '\n' - ' These methods are called to implement the binary ' - 'arithmetic\n' - ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' - '"pow()",\n' - ' "**", "<<", ">>", "&", "^", "|") with reflected ' - '(swapped) operands.\n' - ' These functions are only called if the left operand ' - 'does not\n' - ' support the corresponding operation and the operands ' - 'are of\n' - ' different types. [2] For instance, to evaluate the ' - 'expression "x -\n' - ' y", where *y* is an instance of a class that has an ' - '"__rsub__()"\n' - ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' - 'returns\n' - ' *NotImplemented*.\n' - '\n' - ' Note that ternary "pow()" will not try calling ' - '"__rpow__()" (the\n' - ' coercion rules would become too complicated).\n' - '\n' - " Note: If the right operand's type is a subclass of the " - 'left\n' - " operand's type and that subclass provides the " - 'reflected method\n' - ' for the operation, this method will be called before ' - 'the left\n' - " operand's non-reflected method. This behavior " - 'allows subclasses\n' - " to override their ancestors' operations.\n" - '\n' - 'object.__iadd__(self, other)\n' - 'object.__isub__(self, other)\n' - 'object.__imul__(self, other)\n' - 'object.__itruediv__(self, other)\n' - 'object.__ifloordiv__(self, other)\n' - 'object.__imod__(self, other)\n' - 'object.__ipow__(self, other[, modulo])\n' - 'object.__ilshift__(self, other)\n' - 'object.__irshift__(self, other)\n' - 'object.__iand__(self, other)\n' - 'object.__ixor__(self, other)\n' - 'object.__ior__(self, other)\n' - '\n' - ' These methods are called to implement the augmented ' - 'arithmetic\n' - ' assignments ("+=", "-=", "*=", "/=", "//=", "%=", ' - '"**=", "<<=",\n' - ' ">>=", "&=", "^=", "|="). These methods should ' - 'attempt to do the\n' - ' operation in-place (modifying *self*) and return the ' - 'result (which\n' - ' could be, but does not have to be, *self*). If a ' - 'specific method\n' - ' is not defined, the augmented assignment falls back to ' - 'the normal\n' - ' methods. For instance, if *x* is an instance of a ' - 'class with an\n' - ' "__iadd__()" method, "x += y" is equivalent to "x = ' - 'x.__iadd__(y)"\n' - ' . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are ' - 'considered, as\n' - ' with the evaluation of "x + y". In certain situations, ' - 'augmented\n' - ' assignment can result in unexpected errors (see *Why ' - 'does\n' - " a_tuple[i] += ['item'] raise an exception when the " - 'addition\n' - ' works?*), but this behavior is in fact part of the ' - 'data model.\n' - '\n' - 'object.__neg__(self)\n' - 'object.__pos__(self)\n' - 'object.__abs__(self)\n' - 'object.__invert__(self)\n' - '\n' - ' Called to implement the unary arithmetic operations ' - '("-", "+",\n' - ' "abs()" and "~").\n' - '\n' - 'object.__complex__(self)\n' - 'object.__int__(self)\n' - 'object.__float__(self)\n' - 'object.__round__(self[, n])\n' - '\n' - ' Called to implement the built-in functions ' - '"complex()", "int()",\n' - ' "float()" and "round()". Should return a value of the ' - 'appropriate\n' - ' type.\n' - '\n' - 'object.__index__(self)\n' - '\n' - ' Called to implement "operator.index()", and whenever ' - 'Python needs\n' - ' to losslessly convert the numeric object to an integer ' - 'object (such\n' - ' as in slicing, or in the built-in "bin()", "hex()" and ' - '"oct()"\n' - ' functions). Presence of this method indicates that the ' - 'numeric\n' - ' object is an integer type. Must return an integer.\n' - '\n' - ' Note: In order to have a coherent integer type class, ' - 'when\n' - ' "__index__()" is defined "__int__()" should also be ' - 'defined, and\n' - ' both should return the same value.\n', - 'objects': '\n' - 'Objects, values and types\n' - '*************************\n' - '\n' - "*Objects* are Python's abstraction for data. All data in a " - 'Python\n' - 'program is represented by objects or by relations between ' - 'objects. (In\n' - "a sense, and in conformance to Von Neumann's model of a " - '"stored\n' - 'program computer," code is also represented by objects.)\n' - '\n' - "Every object has an identity, a type and a value. An object's\n" - '*identity* never changes once it has been created; you may ' - 'think of it\n' - 'as the object\'s address in memory. The \'"is"\' operator ' - 'compares the\n' - 'identity of two objects; the "id()" function returns an ' - 'integer\n' - 'representing its identity.\n' - '\n' - '**CPython implementation detail:** For CPython, "id(x)" is the ' - 'memory\n' - 'address where "x" is stored.\n' - '\n' - "An object's type determines the operations that the object " - 'supports\n' - '(e.g., "does it have a length?") and also defines the possible ' - 'values\n' - 'for objects of that type. The "type()" function returns an ' - "object's\n" - 'type (which is an object itself). Like its identity, an ' - "object's\n" - '*type* is also unchangeable. [1]\n' - '\n' - 'The *value* of some objects can change. Objects whose value ' - 'can\n' - 'change are said to be *mutable*; objects whose value is ' - 'unchangeable\n' - 'once they are created are called *immutable*. (The value of an\n' - 'immutable container object that contains a reference to a ' - 'mutable\n' - "object can change when the latter's value is changed; however " - 'the\n' - 'container is still considered immutable, because the collection ' - 'of\n' - 'objects it contains cannot be changed. So, immutability is ' - 'not\n' - 'strictly the same as having an unchangeable value, it is more ' - 'subtle.)\n' - "An object's mutability is determined by its type; for " - 'instance,\n' - 'numbers, strings and tuples are immutable, while dictionaries ' - 'and\n' - 'lists are mutable.\n' - '\n' - 'Objects are never explicitly destroyed; however, when they ' - 'become\n' - 'unreachable they may be garbage-collected. An implementation ' - 'is\n' - 'allowed to postpone garbage collection or omit it altogether ' - '--- it is\n' - 'a matter of implementation quality how garbage collection is\n' - 'implemented, as long as no objects are collected that are ' - 'still\n' - 'reachable.\n' - '\n' - '**CPython implementation detail:** CPython currently uses a ' - 'reference-\n' - 'counting scheme with (optional) delayed detection of cyclically ' - 'linked\n' - 'garbage, which collects most objects as soon as they become\n' - 'unreachable, but is not guaranteed to collect garbage ' - 'containing\n' - 'circular references. See the documentation of the "gc" module ' - 'for\n' - 'information on controlling the collection of cyclic garbage. ' - 'Other\n' - 'implementations act differently and CPython may change. Do not ' - 'depend\n' - 'on immediate finalization of objects when they become ' - 'unreachable (so\n' - 'you should always close files explicitly).\n' - '\n' - "Note that the use of the implementation's tracing or debugging\n" - 'facilities may keep objects alive that would normally be ' - 'collectable.\n' - 'Also note that catching an exception with a ' - '\'"try"..."except"\'\n' - 'statement may keep objects alive.\n' - '\n' - 'Some objects contain references to "external" resources such as ' - 'open\n' - 'files or windows. It is understood that these resources are ' - 'freed\n' - 'when the object is garbage-collected, but since garbage ' - 'collection is\n' - 'not guaranteed to happen, such objects also provide an explicit ' - 'way to\n' - 'release the external resource, usually a "close()" method. ' - 'Programs\n' - 'are strongly recommended to explicitly close such objects. ' - 'The\n' - '\'"try"..."finally"\' statement and the \'"with"\' statement ' - 'provide\n' - 'convenient ways to do this.\n' - '\n' - 'Some objects contain references to other objects; these are ' - 'called\n' - '*containers*. Examples of containers are tuples, lists and\n' - "dictionaries. The references are part of a container's value. " - 'In\n' - 'most cases, when we talk about the value of a container, we ' - 'imply the\n' - 'values, not the identities of the contained objects; however, ' - 'when we\n' - 'talk about the mutability of a container, only the identities ' - 'of the\n' - 'immediately contained objects are implied. So, if an ' - 'immutable\n' - 'container (like a tuple) contains a reference to a mutable ' - 'object, its\n' - 'value changes if that mutable object is changed.\n' - '\n' - 'Types affect almost all aspects of object behavior. Even the\n' - 'importance of object identity is affected in some sense: for ' - 'immutable\n' - 'types, operations that compute new values may actually return ' - 'a\n' - 'reference to any existing object with the same type and value, ' - 'while\n' - 'for mutable objects this is not allowed. E.g., after "a = 1; b ' - '= 1",\n' - '"a" and "b" may or may not refer to the same object with the ' - 'value\n' - 'one, depending on the implementation, but after "c = []; d = ' - '[]", "c"\n' - 'and "d" are guaranteed to refer to two different, unique, ' - 'newly\n' - 'created empty lists. (Note that "c = d = []" assigns the same ' - 'object\n' - 'to both "c" and "d".)\n', - 'operator-summary': '\n' - 'Operator precedence\n' - '*******************\n' - '\n' - 'The following table summarizes the operator precedence ' - 'in Python, from\n' - 'lowest precedence (least binding) to highest ' - 'precedence (most\n' - 'binding). Operators in the same box have the same ' - 'precedence. Unless\n' - 'the syntax is explicitly given, operators are binary. ' - 'Operators in\n' - 'the same box group left to right (except for ' - 'exponentiation, which\n' - 'groups from right to left).\n' - '\n' - 'Note that comparisons, membership tests, and identity ' - 'tests, all have\n' - 'the same precedence and have a left-to-right chaining ' - 'feature as\n' - 'described in the *Comparisons* section.\n' - '\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| Operator | ' - 'Description |\n' - '+=================================================+=======================================+\n' - '| "lambda" | ' - 'Lambda expression |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "if" -- "else" | ' - 'Conditional expression |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "or" | ' - 'Boolean OR |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "and" | ' - 'Boolean AND |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "not" "x" | ' - 'Boolean NOT |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "in", "not in", "is", "is not", "<", "<=", ">", | ' - 'Comparisons, including membership |\n' - '| ">=", "!=", "==" | ' - 'tests and identity tests |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "|" | ' - 'Bitwise OR |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "^" | ' - 'Bitwise XOR |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "&" | ' - 'Bitwise AND |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "<<", ">>" | ' - 'Shifts |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "+", "-" | ' - 'Addition and subtraction |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "*", "/", "//", "%" | ' - 'Multiplication, division, remainder |\n' - '| | ' - '[5] |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "+x", "-x", "~x" | ' - 'Positive, negative, bitwise NOT |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "**" | ' - 'Exponentiation [6] |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "x[index]", "x[index:index]", | ' - 'Subscription, slicing, call, |\n' - '| "x(arguments...)", "x.attribute" | ' - 'attribute reference |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "(expressions...)", "[expressions...]", "{key: | ' - 'Binding or tuple display, list |\n' - '| value...}", "{expressions...}" | ' - 'display, dictionary display, set |\n' - '| | ' - 'display |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] While "abs(x%y) < abs(y)" is true mathematically, ' - 'for floats\n' - ' it may not be true numerically due to roundoff. ' - 'For example, and\n' - ' assuming a platform on which a Python float is an ' - 'IEEE 754 double-\n' - ' precision number, in order that "-1e-100 % 1e100" ' - 'have the same\n' - ' sign as "1e100", the computed result is "-1e-100 + ' - '1e100", which\n' - ' is numerically exactly equal to "1e100". The ' - 'function\n' - ' "math.fmod()" returns a result whose sign matches ' - 'the sign of the\n' - ' first argument instead, and so returns "-1e-100" ' - 'in this case.\n' - ' Which approach is more appropriate depends on the ' - 'application.\n' - '\n' - '[2] If x is very close to an exact integer multiple of ' - "y, it's\n" - ' possible for "x//y" to be one larger than ' - '"(x-x%y)//y" due to\n' - ' rounding. In such cases, Python returns the ' - 'latter result, in\n' - ' order to preserve that "divmod(x,y)[0] * y + x % ' - 'y" be very close\n' - ' to "x".\n' - '\n' - '[3] The Unicode standard distinguishes between *code ' - 'points* (e.g.\n' - ' U+0041) and *abstract characters* (e.g. "LATIN ' - 'CAPITAL LETTER A").\n' - ' While most abstract characters in Unicode are only ' - 'represented\n' - ' using one code point, there is a number of ' - 'abstract characters\n' - ' that can in addition be represented using a ' - 'sequence of more than\n' - ' one code point. For example, the abstract ' - 'character "LATIN\n' - ' CAPITAL LETTER C WITH CEDILLA" can be represented ' - 'as a single\n' - ' *precomposed character* at code position U+00C7, ' - 'or as a sequence\n' - ' of a *base character* at code position U+0043 ' - '(LATIN CAPITAL\n' - ' LETTER C), followed by a *combining character* at ' - 'code position\n' - ' U+0327 (COMBINING CEDILLA).\n' - '\n' - ' The comparison operators on strings compare at the ' - 'level of\n' - ' Unicode code points. This may be counter-intuitive ' - 'to humans. For\n' - ' example, ""\\u00C7" == "\\u0043\\u0327"" is ' - '"False", even though both\n' - ' strings represent the same abstract character ' - '"LATIN CAPITAL\n' - ' LETTER C WITH CEDILLA".\n' - '\n' - ' To compare strings at the level of abstract ' - 'characters (that is,\n' - ' in a way intuitive to humans), use ' - '"unicodedata.normalize()".\n' - '\n' - '[4] Due to automatic garbage-collection, free lists, ' - 'and the\n' - ' dynamic nature of descriptors, you may notice ' - 'seemingly unusual\n' - ' behaviour in certain uses of the "is" operator, ' - 'like those\n' - ' involving comparisons between instance methods, or ' - 'constants.\n' - ' Check their documentation for more info.\n' - '\n' - '[5] The "%" operator is also used for string ' - 'formatting; the same\n' - ' precedence applies.\n' - '\n' - '[6] The power operator "**" binds less tightly than an ' - 'arithmetic\n' - ' or bitwise unary operator on its right, that is, ' - '"2**-1" is "0.5".\n', - 'pass': '\n' - 'The "pass" statement\n' - '********************\n' - '\n' - ' pass_stmt ::= "pass"\n' - '\n' - '"pass" is a null operation --- when it is executed, nothing ' - 'happens.\n' - 'It is useful as a placeholder when a statement is required\n' - 'syntactically, but no code needs to be executed, for example:\n' - '\n' - ' def f(arg): pass # a function that does nothing (yet)\n' - '\n' - ' class C: pass # a class with no methods (yet)\n', - 'power': '\n' - 'The power operator\n' - '******************\n' - '\n' - 'The power operator binds more tightly than unary operators on ' - 'its\n' - 'left; it binds less tightly than unary operators on its right. ' - 'The\n' - 'syntax is:\n' - '\n' - ' power ::= primary ["**" u_expr]\n' - '\n' - 'Thus, in an unparenthesized sequence of power and unary ' - 'operators, the\n' - 'operators are evaluated from right to left (this does not ' - 'constrain\n' - 'the evaluation order for the operands): "-1**2" results in "-1".\n' - '\n' - 'The power operator has the same semantics as the built-in ' - '"pow()"\n' - 'function, when called with two arguments: it yields its left ' - 'argument\n' - 'raised to the power of its right argument. The numeric arguments ' - 'are\n' - 'first converted to a common type, and the result is of that ' - 'type.\n' - '\n' - 'For int operands, the result has the same type as the operands ' - 'unless\n' - 'the second argument is negative; in that case, all arguments are\n' - 'converted to float and a float result is delivered. For example,\n' - '"10**2" returns "100", but "10**-2" returns "0.01".\n' - '\n' - 'Raising "0.0" to a negative power results in a ' - '"ZeroDivisionError".\n' - 'Raising a negative number to a fractional power results in a ' - '"complex"\n' - 'number. (In earlier versions it raised a "ValueError".)\n', - 'raise': '\n' - 'The "raise" statement\n' - '*********************\n' - '\n' - ' raise_stmt ::= "raise" [expression ["from" expression]]\n' - '\n' - 'If no expressions are present, "raise" re-raises the last ' - 'exception\n' - 'that was active in the current scope. If no exception is active ' - 'in\n' - 'the current scope, a "RuntimeError" exception is raised ' - 'indicating\n' - 'that this is an error.\n' - '\n' - 'Otherwise, "raise" evaluates the first expression as the ' - 'exception\n' - 'object. It must be either a subclass or an instance of\n' - '"BaseException". If it is a class, the exception instance will ' - 'be\n' - 'obtained when needed by instantiating the class with no ' - 'arguments.\n' - '\n' - "The *type* of the exception is the exception instance's class, " - 'the\n' - '*value* is the instance itself.\n' - '\n' - 'A traceback object is normally created automatically when an ' - 'exception\n' - 'is raised and attached to it as the "__traceback__" attribute, ' - 'which\n' - 'is writable. You can create an exception and set your own ' - 'traceback in\n' - 'one step using the "with_traceback()" exception method (which ' - 'returns\n' - 'the same exception instance, with its traceback set to its ' - 'argument),\n' - 'like so:\n' - '\n' - ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' - '\n' - 'The "from" clause is used for exception chaining: if given, the ' - 'second\n' - '*expression* must be another exception class or instance, which ' - 'will\n' - 'then be attached to the raised exception as the "__cause__" ' - 'attribute\n' - '(which is writable). If the raised exception is not handled, ' - 'both\n' - 'exceptions will be printed:\n' - '\n' - ' >>> try:\n' - ' ... print(1 / 0)\n' - ' ... except Exception as exc:\n' - ' ... raise RuntimeError("Something bad happened") from exc\n' - ' ...\n' - ' Traceback (most recent call last):\n' - ' File "", line 2, in \n' - ' ZeroDivisionError: int division or modulo by zero\n' - '\n' - ' The above exception was the direct cause of the following ' - 'exception:\n' - '\n' - ' Traceback (most recent call last):\n' - ' File "", line 4, in \n' - ' RuntimeError: Something bad happened\n' - '\n' - 'A similar mechanism works implicitly if an exception is raised ' - 'inside\n' - 'an exception handler or a "finally" clause: the previous ' - 'exception is\n' - 'then attached as the new exception\'s "__context__" attribute:\n' - '\n' - ' >>> try:\n' - ' ... print(1 / 0)\n' - ' ... except:\n' - ' ... raise RuntimeError("Something bad happened")\n' - ' ...\n' - ' Traceback (most recent call last):\n' - ' File "", line 2, in \n' - ' ZeroDivisionError: int division or modulo by zero\n' - '\n' - ' During handling of the above exception, another exception ' - 'occurred:\n' - '\n' - ' Traceback (most recent call last):\n' - ' File "", line 4, in \n' - ' RuntimeError: Something bad happened\n' - '\n' - 'Additional information on exceptions can be found in section\n' - '*Exceptions*, and information about handling exceptions is in ' - 'section\n' - '*The try statement*.\n', - 'return': '\n' - 'The "return" statement\n' - '**********************\n' - '\n' - ' return_stmt ::= "return" [expression_list]\n' - '\n' - '"return" may only occur syntactically nested in a function ' - 'definition,\n' - 'not within a nested class definition.\n' - '\n' - 'If an expression list is present, it is evaluated, else "None" ' - 'is\n' - 'substituted.\n' - '\n' - '"return" leaves the current function call with the expression ' - 'list (or\n' - '"None") as return value.\n' - '\n' - 'When "return" passes control out of a "try" statement with a ' - '"finally"\n' - 'clause, that "finally" clause is executed before really leaving ' - 'the\n' - 'function.\n' - '\n' - 'In a generator function, the "return" statement indicates that ' - 'the\n' - 'generator is done and will cause "StopIteration" to be raised. ' - 'The\n' - 'returned value (if any) is used as an argument to construct\n' - '"StopIteration" and becomes the "StopIteration.value" ' - 'attribute.\n', - 'sequence-types': '\n' - 'Emulating container types\n' - '*************************\n' - '\n' - 'The following methods can be defined to implement ' - 'container objects.\n' - 'Containers usually are sequences (such as lists or ' - 'tuples) or mappings\n' - '(like dictionaries), but can represent other containers ' - 'as well. The\n' - 'first set of methods is used either to emulate a ' - 'sequence or to\n' - 'emulate a mapping; the difference is that for a ' - 'sequence, the\n' - 'allowable keys should be the integers *k* for which "0 ' - '<= k < N" where\n' - '*N* is the length of the sequence, or slice objects, ' - 'which define a\n' - 'range of items. It is also recommended that mappings ' - 'provide the\n' - 'methods "keys()", "values()", "items()", "get()", ' - '"clear()",\n' - '"setdefault()", "pop()", "popitem()", "copy()", and ' - '"update()"\n' - "behaving similar to those for Python's standard " - 'dictionary objects.\n' - 'The "collections" module provides a "MutableMapping" ' - 'abstract base\n' - 'class to help create those methods from a base set of ' - '"__getitem__()",\n' - '"__setitem__()", "__delitem__()", and "keys()". Mutable ' - 'sequences\n' - 'should provide methods "append()", "count()", "index()", ' - '"extend()",\n' - '"insert()", "pop()", "remove()", "reverse()" and ' - '"sort()", like Python\n' - 'standard list objects. Finally, sequence types should ' - 'implement\n' - 'addition (meaning concatenation) and multiplication ' - '(meaning\n' - 'repetition) by defining the methods "__add__()", ' - '"__radd__()",\n' - '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' - 'described\n' - 'below; they should not define other numerical ' - 'operators. It is\n' - 'recommended that both mappings and sequences implement ' - 'the\n' - '"__contains__()" method to allow efficient use of the ' - '"in" operator;\n' - 'for mappings, "in" should search the mapping\'s keys; ' - 'for sequences, it\n' - 'should search through the values. It is further ' - 'recommended that both\n' - 'mappings and sequences implement the "__iter__()" method ' - 'to allow\n' - 'efficient iteration through the container; for mappings, ' - '"__iter__()"\n' - 'should be the same as "keys()"; for sequences, it should ' - 'iterate\n' - 'through the values.\n' - '\n' - 'object.__len__(self)\n' - '\n' - ' Called to implement the built-in function "len()". ' - 'Should return\n' - ' the length of the object, an integer ">=" 0. Also, ' - 'an object that\n' - ' doesn\'t define a "__bool__()" method and whose ' - '"__len__()" method\n' - ' returns zero is considered to be false in a Boolean ' - 'context.\n' - '\n' - 'object.__length_hint__(self)\n' - '\n' - ' Called to implement "operator.length_hint()". Should ' - 'return an\n' - ' estimated length for the object (which may be greater ' - 'or less than\n' - ' the actual length). The length must be an integer ' - '">=" 0. This\n' - ' method is purely an optimization and is never ' - 'required for\n' - ' correctness.\n' - '\n' - ' New in version 3.4.\n' - '\n' - 'Note: Slicing is done exclusively with the following ' - 'three methods.\n' - ' A call like\n' - '\n' - ' a[1:2] = b\n' - '\n' - ' is translated to\n' - '\n' - ' a[slice(1, 2, None)] = b\n' - '\n' - ' and so forth. Missing slice items are always filled ' - 'in with "None".\n' - '\n' - 'object.__getitem__(self, key)\n' - '\n' - ' Called to implement evaluation of "self[key]". For ' - 'sequence types,\n' - ' the accepted keys should be integers and slice ' - 'objects. Note that\n' - ' the special interpretation of negative indexes (if ' - 'the class wishes\n' - ' to emulate a sequence type) is up to the ' - '"__getitem__()" method. If\n' - ' *key* is of an inappropriate type, "TypeError" may be ' - 'raised; if of\n' - ' a value outside the set of indexes for the sequence ' - '(after any\n' - ' special interpretation of negative values), ' - '"IndexError" should be\n' - ' raised. For mapping types, if *key* is missing (not ' - 'in the\n' - ' container), "KeyError" should be raised.\n' - '\n' - ' Note: "for" loops expect that an "IndexError" will be ' - 'raised for\n' - ' illegal indexes to allow proper detection of the ' - 'end of the\n' - ' sequence.\n' - '\n' - 'object.__missing__(self, key)\n' - '\n' - ' Called by "dict"."__getitem__()" to implement ' - '"self[key]" for dict\n' - ' subclasses when key is not in the dictionary.\n' - '\n' - 'object.__setitem__(self, key, value)\n' - '\n' - ' Called to implement assignment to "self[key]". Same ' - 'note as for\n' - ' "__getitem__()". This should only be implemented for ' - 'mappings if\n' - ' the objects support changes to the values for keys, ' - 'or if new keys\n' - ' can be added, or for sequences if elements can be ' - 'replaced. The\n' - ' same exceptions should be raised for improper *key* ' - 'values as for\n' - ' the "__getitem__()" method.\n' - '\n' - 'object.__delitem__(self, key)\n' - '\n' - ' Called to implement deletion of "self[key]". Same ' - 'note as for\n' - ' "__getitem__()". This should only be implemented for ' - 'mappings if\n' - ' the objects support removal of keys, or for sequences ' - 'if elements\n' - ' can be removed from the sequence. The same ' - 'exceptions should be\n' - ' raised for improper *key* values as for the ' - '"__getitem__()" method.\n' - '\n' - 'object.__iter__(self)\n' - '\n' - ' This method is called when an iterator is required ' - 'for a container.\n' - ' This method should return a new iterator object that ' - 'can iterate\n' - ' over all the objects in the container. For mappings, ' - 'it should\n' - ' iterate over the keys of the container.\n' - '\n' - ' Iterator objects also need to implement this method; ' - 'they are\n' - ' required to return themselves. For more information ' - 'on iterator\n' - ' objects, see *Iterator Types*.\n' - '\n' - 'object.__reversed__(self)\n' - '\n' - ' Called (if present) by the "reversed()" built-in to ' - 'implement\n' - ' reverse iteration. It should return a new iterator ' - 'object that\n' - ' iterates over all the objects in the container in ' - 'reverse order.\n' - '\n' - ' If the "__reversed__()" method is not provided, the ' - '"reversed()"\n' - ' built-in will fall back to using the sequence ' - 'protocol ("__len__()"\n' - ' and "__getitem__()"). Objects that support the ' - 'sequence protocol\n' - ' should only provide "__reversed__()" if they can ' - 'provide an\n' - ' implementation that is more efficient than the one ' - 'provided by\n' - ' "reversed()".\n' - '\n' - 'The membership test operators ("in" and "not in") are ' - 'normally\n' - 'implemented as an iteration through a sequence. ' - 'However, container\n' - 'objects can supply the following special method with a ' - 'more efficient\n' - 'implementation, which also does not require the object ' - 'be a sequence.\n' - '\n' - 'object.__contains__(self, item)\n' - '\n' - ' Called to implement membership test operators. ' - 'Should return true\n' - ' if *item* is in *self*, false otherwise. For mapping ' - 'objects, this\n' - ' should consider the keys of the mapping rather than ' - 'the values or\n' - ' the key-item pairs.\n' - '\n' - ' For objects that don\'t define "__contains__()", the ' - 'membership test\n' - ' first tries iteration via "__iter__()", then the old ' - 'sequence\n' - ' iteration protocol via "__getitem__()", see *this ' - 'section in the\n' - ' language reference*.\n', - 'shifting': '\n' - 'Shifting operations\n' - '*******************\n' - '\n' - 'The shifting operations have lower priority than the ' - 'arithmetic\n' - 'operations:\n' - '\n' - ' shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n' - '\n' - 'These operators accept integers as arguments. They shift the ' - 'first\n' - 'argument to the left or right by the number of bits given by ' - 'the\n' - 'second argument.\n' - '\n' - 'A right shift by *n* bits is defined as floor division by ' - '"pow(2,n)".\n' - 'A left shift by *n* bits is defined as multiplication with ' - '"pow(2,n)".\n' - '\n' - 'Note: In the current implementation, the right-hand operand ' - 'is\n' - ' required to be at most "sys.maxsize". If the right-hand ' - 'operand is\n' - ' larger than "sys.maxsize" an "OverflowError" exception is ' - 'raised.\n', - 'slicings': '\n' - 'Slicings\n' - '********\n' - '\n' - 'A slicing selects a range of items in a sequence object (e.g., ' - 'a\n' - 'string, tuple or list). Slicings may be used as expressions ' - 'or as\n' - 'targets in assignment or "del" statements. The syntax for a ' - 'slicing:\n' - '\n' - ' slicing ::= primary "[" slice_list "]"\n' - ' slice_list ::= slice_item ("," slice_item)* [","]\n' - ' slice_item ::= expression | proper_slice\n' - ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" ' - '[stride] ]\n' - ' lower_bound ::= expression\n' - ' upper_bound ::= expression\n' - ' stride ::= expression\n' - '\n' - 'There is ambiguity in the formal syntax here: anything that ' - 'looks like\n' - 'an expression list also looks like a slice list, so any ' - 'subscription\n' - 'can be interpreted as a slicing. Rather than further ' - 'complicating the\n' - 'syntax, this is disambiguated by defining that in this case ' - 'the\n' - 'interpretation as a subscription takes priority over the\n' - 'interpretation as a slicing (this is the case if the slice ' - 'list\n' - 'contains no proper slice).\n' - '\n' - 'The semantics for a slicing are as follows. The primary is ' - 'indexed\n' - '(using the same "__getitem__()" method as normal subscription) ' - 'with a\n' - 'key that is constructed from the slice list, as follows. If ' - 'the slice\n' - 'list contains at least one comma, the key is a tuple ' - 'containing the\n' - 'conversion of the slice items; otherwise, the conversion of ' - 'the lone\n' - 'slice item is the key. The conversion of a slice item that is ' - 'an\n' - 'expression is that expression. The conversion of a proper ' - 'slice is a\n' - 'slice object (see section *The standard type hierarchy*) ' - 'whose\n' - '"start", "stop" and "step" attributes are the values of the\n' - 'expressions given as lower bound, upper bound and stride,\n' - 'respectively, substituting "None" for missing expressions.\n', - 'specialattrs': '\n' - 'Special Attributes\n' - '******************\n' - '\n' - 'The implementation adds a few special read-only attributes ' - 'to several\n' - 'object types, where they are relevant. Some of these are ' - 'not reported\n' - 'by the "dir()" built-in function.\n' - '\n' - 'object.__dict__\n' - '\n' - ' A dictionary or other mapping object used to store an ' - "object's\n" - ' (writable) attributes.\n' - '\n' - 'instance.__class__\n' - '\n' - ' The class to which a class instance belongs.\n' - '\n' - 'class.__bases__\n' - '\n' - ' The tuple of base classes of a class object.\n' - '\n' - 'class.__name__\n' - '\n' - ' The name of the class or type.\n' - '\n' - 'class.__qualname__\n' - '\n' - ' The *qualified name* of the class or type.\n' - '\n' - ' New in version 3.3.\n' - '\n' - 'class.__mro__\n' - '\n' - ' This attribute is a tuple of classes that are ' - 'considered when\n' - ' looking for base classes during method resolution.\n' - '\n' - 'class.mro()\n' - '\n' - ' This method can be overridden by a metaclass to ' - 'customize the\n' - ' method resolution order for its instances. It is ' - 'called at class\n' - ' instantiation, and its result is stored in "__mro__".\n' - '\n' - 'class.__subclasses__()\n' - '\n' - ' Each class keeps a list of weak references to its ' - 'immediate\n' - ' subclasses. This method returns a list of all those ' - 'references\n' - ' still alive. Example:\n' - '\n' - ' >>> int.__subclasses__()\n' - " []\n" - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] Additional information on these special methods may be ' - 'found\n' - ' in the Python Reference Manual (*Basic ' - 'customization*).\n' - '\n' - '[2] As a consequence, the list "[1, 2]" is considered ' - 'equal to\n' - ' "[1.0, 2.0]", and similarly for tuples.\n' - '\n' - "[3] They must have since the parser can't tell the type of " - 'the\n' - ' operands.\n' - '\n' - '[4] Cased characters are those with general category ' - 'property\n' - ' being one of "Lu" (Letter, uppercase), "Ll" (Letter, ' - 'lowercase),\n' - ' or "Lt" (Letter, titlecase).\n' - '\n' - '[5] To format only a tuple you should therefore provide a\n' - ' singleton tuple whose only element is the tuple to be ' - 'formatted.\n', - 'specialnames': '\n' - 'Special method names\n' - '********************\n' - '\n' - 'A class can implement certain operations that are invoked ' - 'by special\n' - 'syntax (such as arithmetic operations or subscripting and ' - 'slicing) by\n' - "defining methods with special names. This is Python's " - 'approach to\n' - '*operator overloading*, allowing classes to define their ' - 'own behavior\n' - 'with respect to language operators. For instance, if a ' - 'class defines\n' - 'a method named "__getitem__()", and "x" is an instance of ' - 'this class,\n' - 'then "x[i]" is roughly equivalent to ' - '"type(x).__getitem__(x, i)".\n' - 'Except where mentioned, attempts to execute an operation ' - 'raise an\n' - 'exception when no appropriate method is defined ' - '(typically\n' - '"AttributeError" or "TypeError").\n' - '\n' - 'When implementing a class that emulates any built-in type, ' - 'it is\n' - 'important that the emulation only be implemented to the ' - 'degree that it\n' - 'makes sense for the object being modelled. For example, ' - 'some\n' - 'sequences may work well with retrieval of individual ' - 'elements, but\n' - 'extracting a slice may not make sense. (One example of ' - 'this is the\n' - '"NodeList" interface in the W3C\'s Document Object ' - 'Model.)\n' - '\n' - '\n' - 'Basic customization\n' - '===================\n' - '\n' - 'object.__new__(cls[, ...])\n' - '\n' - ' Called to create a new instance of class *cls*. ' - '"__new__()" is a\n' - ' static method (special-cased so you need not declare it ' - 'as such)\n' - ' that takes the class of which an instance was requested ' - 'as its\n' - ' first argument. The remaining arguments are those ' - 'passed to the\n' - ' object constructor expression (the call to the class). ' - 'The return\n' - ' value of "__new__()" should be the new object instance ' - '(usually an\n' - ' instance of *cls*).\n' - '\n' - ' Typical implementations create a new instance of the ' - 'class by\n' - ' invoking the superclass\'s "__new__()" method using\n' - ' "super(currentclass, cls).__new__(cls[, ...])" with ' - 'appropriate\n' - ' arguments and then modifying the newly-created instance ' - 'as\n' - ' necessary before returning it.\n' - '\n' - ' If "__new__()" returns an instance of *cls*, then the ' - 'new\n' - ' instance\'s "__init__()" method will be invoked like\n' - ' "__init__(self[, ...])", where *self* is the new ' - 'instance and the\n' - ' remaining arguments are the same as were passed to ' - '"__new__()".\n' - '\n' - ' If "__new__()" does not return an instance of *cls*, ' - 'then the new\n' - ' instance\'s "__init__()" method will not be invoked.\n' - '\n' - ' "__new__()" is intended mainly to allow subclasses of ' - 'immutable\n' - ' types (like int, str, or tuple) to customize instance ' - 'creation. It\n' - ' is also commonly overridden in custom metaclasses in ' - 'order to\n' - ' customize class creation.\n' - '\n' - 'object.__init__(self[, ...])\n' - '\n' - ' Called after the instance has been created (by ' - '"__new__()"), but\n' - ' before it is returned to the caller. The arguments are ' - 'those\n' - ' passed to the class constructor expression. If a base ' - 'class has an\n' - ' "__init__()" method, the derived class\'s "__init__()" ' - 'method, if\n' - ' any, must explicitly call it to ensure proper ' - 'initialization of the\n' - ' base class part of the instance; for example:\n' - ' "BaseClass.__init__(self, [args...])".\n' - '\n' - ' Because "__new__()" and "__init__()" work together in ' - 'constructing\n' - ' objects ("__new__()" to create it, and "__init__()" to ' - 'customise\n' - ' it), no non-"None" value may be returned by ' - '"__init__()"; doing so\n' - ' will cause a "TypeError" to be raised at runtime.\n' - '\n' - 'object.__del__(self)\n' - '\n' - ' Called when the instance is about to be destroyed. ' - 'This is also\n' - ' called a destructor. If a base class has a "__del__()" ' - 'method, the\n' - ' derived class\'s "__del__()" method, if any, must ' - 'explicitly call it\n' - ' to ensure proper deletion of the base class part of the ' - 'instance.\n' - ' Note that it is possible (though not recommended!) for ' - 'the\n' - ' "__del__()" method to postpone destruction of the ' - 'instance by\n' - ' creating a new reference to it. It may then be called ' - 'at a later\n' - ' time when this new reference is deleted. It is not ' - 'guaranteed that\n' - ' "__del__()" methods are called for objects that still ' - 'exist when\n' - ' the interpreter exits.\n' - '\n' - ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' - 'the former\n' - ' decrements the reference count for "x" by one, and ' - 'the latter is\n' - ' only called when "x"\'s reference count reaches ' - 'zero. Some common\n' - ' situations that may prevent the reference count of an ' - 'object from\n' - ' going to zero include: circular references between ' - 'objects (e.g.,\n' - ' a doubly-linked list or a tree data structure with ' - 'parent and\n' - ' child pointers); a reference to the object on the ' - 'stack frame of\n' - ' a function that caught an exception (the traceback ' - 'stored in\n' - ' "sys.exc_info()[2]" keeps the stack frame alive); or ' - 'a reference\n' - ' to the object on the stack frame that raised an ' - 'unhandled\n' - ' exception in interactive mode (the traceback stored ' - 'in\n' - ' "sys.last_traceback" keeps the stack frame alive). ' - 'The first\n' - ' situation can only be remedied by explicitly breaking ' - 'the cycles;\n' - ' the second can be resolved by freeing the reference ' - 'to the\n' - ' traceback object when it is no longer useful, and the ' - 'third can\n' - ' be resolved by storing "None" in ' - '"sys.last_traceback". Circular\n' - ' references which are garbage are detected and cleaned ' - 'up when the\n' - " cyclic garbage collector is enabled (it's on by " - 'default). Refer\n' - ' to the documentation for the "gc" module for more ' - 'information\n' - ' about this topic.\n' - '\n' - ' Warning: Due to the precarious circumstances under ' - 'which\n' - ' "__del__()" methods are invoked, exceptions that ' - 'occur during\n' - ' their execution are ignored, and a warning is printed ' - 'to\n' - ' "sys.stderr" instead. Also, when "__del__()" is ' - 'invoked in\n' - ' response to a module being deleted (e.g., when ' - 'execution of the\n' - ' program is done), other globals referenced by the ' - '"__del__()"\n' - ' method may already have been deleted or in the ' - 'process of being\n' - ' torn down (e.g. the import machinery shutting down). ' - 'For this\n' - ' reason, "__del__()" methods should do the absolute ' - 'minimum needed\n' - ' to maintain external invariants. Starting with ' - 'version 1.5,\n' - ' Python guarantees that globals whose name begins with ' - 'a single\n' - ' underscore are deleted from their module before other ' - 'globals are\n' - ' deleted; if no other references to such globals ' - 'exist, this may\n' - ' help in assuring that imported modules are still ' - 'available at the\n' - ' time when the "__del__()" method is called.\n' - '\n' - 'object.__repr__(self)\n' - '\n' - ' Called by the "repr()" built-in function to compute the ' - '"official"\n' - ' string representation of an object. If at all ' - 'possible, this\n' - ' should look like a valid Python expression that could ' - 'be used to\n' - ' recreate an object with the same value (given an ' - 'appropriate\n' - ' environment). If this is not possible, a string of the ' - 'form\n' - ' "<...some useful description...>" should be returned. ' - 'The return\n' - ' value must be a string object. If a class defines ' - '"__repr__()" but\n' - ' not "__str__()", then "__repr__()" is also used when an ' - '"informal"\n' - ' string representation of instances of that class is ' - 'required.\n' - '\n' - ' This is typically used for debugging, so it is ' - 'important that the\n' - ' representation is information-rich and unambiguous.\n' - '\n' - 'object.__str__(self)\n' - '\n' - ' Called by "str(object)" and the built-in functions ' - '"format()" and\n' - ' "print()" to compute the "informal" or nicely printable ' - 'string\n' - ' representation of an object. The return value must be ' - 'a *string*\n' - ' object.\n' - '\n' - ' This method differs from "object.__repr__()" in that ' - 'there is no\n' - ' expectation that "__str__()" return a valid Python ' - 'expression: a\n' - ' more convenient or concise representation can be used.\n' - '\n' - ' The default implementation defined by the built-in type ' - '"object"\n' - ' calls "object.__repr__()".\n' - '\n' - 'object.__bytes__(self)\n' - '\n' - ' Called by "bytes()" to compute a byte-string ' - 'representation of an\n' - ' object. This should return a "bytes" object.\n' - '\n' - 'object.__format__(self, format_spec)\n' - '\n' - ' Called by the "format()" built-in function (and by ' - 'extension, the\n' - ' "str.format()" method of class "str") to produce a ' - '"formatted"\n' - ' string representation of an object. The "format_spec" ' - 'argument is a\n' - ' string that contains a description of the formatting ' - 'options\n' - ' desired. The interpretation of the "format_spec" ' - 'argument is up to\n' - ' the type implementing "__format__()", however most ' - 'classes will\n' - ' either delegate formatting to one of the built-in ' - 'types, or use a\n' - ' similar formatting option syntax.\n' - '\n' - ' See *Format Specification Mini-Language* for a ' - 'description of the\n' - ' standard formatting syntax.\n' - '\n' - ' The return value must be a string object.\n' - '\n' - ' Changed in version 3.4: The __format__ method of ' - '"object" itself\n' - ' raises a "TypeError" if passed any non-empty string.\n' - '\n' - 'object.__lt__(self, other)\n' - 'object.__le__(self, other)\n' - 'object.__eq__(self, other)\n' - 'object.__ne__(self, other)\n' - 'object.__gt__(self, other)\n' - 'object.__ge__(self, other)\n' - '\n' - ' These are the so-called "rich comparison" methods. The\n' - ' correspondence between operator symbols and method ' - 'names is as\n' - ' follows: "xy" calls\n' - ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' - '\n' - ' A rich comparison method may return the singleton ' - '"NotImplemented"\n' - ' if it does not implement the operation for a given pair ' - 'of\n' - ' arguments. By convention, "False" and "True" are ' - 'returned for a\n' - ' successful comparison. However, these methods can ' - 'return any value,\n' - ' so if the comparison operator is used in a Boolean ' - 'context (e.g.,\n' - ' in the condition of an "if" statement), Python will ' - 'call "bool()"\n' - ' on the value to determine if the result is true or ' - 'false.\n' - '\n' - ' By default, "__ne__()" delegates to "__eq__()" and ' - 'inverts the\n' - ' result unless it is "NotImplemented". There are no ' - 'other implied\n' - ' relationships among the comparison operators, for ' - 'example, the\n' - ' truth of "(x.__hash__".\n' - '\n' - ' If a class that does not override "__eq__()" wishes to ' - 'suppress\n' - ' hash support, it should include "__hash__ = None" in ' - 'the class\n' - ' definition. A class which defines its own "__hash__()" ' - 'that\n' - ' explicitly raises a "TypeError" would be incorrectly ' - 'identified as\n' - ' hashable by an "isinstance(obj, collections.Hashable)" ' - 'call.\n' - '\n' - ' Note: By default, the "__hash__()" values of str, bytes ' - 'and\n' - ' datetime objects are "salted" with an unpredictable ' - 'random value.\n' - ' Although they remain constant within an individual ' - 'Python\n' - ' process, they are not predictable between repeated ' - 'invocations of\n' - ' Python.This is intended to provide protection against ' - 'a denial-\n' - ' of-service caused by carefully-chosen inputs that ' - 'exploit the\n' - ' worst case performance of a dict insertion, O(n^2) ' - 'complexity.\n' - ' See ' - 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' - ' details.Changing hash values affects the iteration ' - 'order of\n' - ' dicts, sets and other mappings. Python has never ' - 'made guarantees\n' - ' about this ordering (and it typically varies between ' - '32-bit and\n' - ' 64-bit builds).See also "PYTHONHASHSEED".\n' - '\n' - ' Changed in version 3.3: Hash randomization is enabled ' - 'by default.\n' - '\n' - 'object.__bool__(self)\n' - '\n' - ' Called to implement truth value testing and the ' - 'built-in operation\n' - ' "bool()"; should return "False" or "True". When this ' - 'method is not\n' - ' defined, "__len__()" is called, if it is defined, and ' - 'the object is\n' - ' considered true if its result is nonzero. If a class ' - 'defines\n' - ' neither "__len__()" nor "__bool__()", all its instances ' - 'are\n' - ' considered true.\n' - '\n' - '\n' - 'Customizing attribute access\n' - '============================\n' - '\n' - 'The following methods can be defined to customize the ' - 'meaning of\n' - 'attribute access (use of, assignment to, or deletion of ' - '"x.name") for\n' - 'class instances.\n' - '\n' - 'object.__getattr__(self, name)\n' - '\n' - ' Called when an attribute lookup has not found the ' - 'attribute in the\n' - ' usual places (i.e. it is not an instance attribute nor ' - 'is it found\n' - ' in the class tree for "self"). "name" is the attribute ' - 'name. This\n' - ' method should return the (computed) attribute value or ' - 'raise an\n' - ' "AttributeError" exception.\n' - '\n' - ' Note that if the attribute is found through the normal ' - 'mechanism,\n' - ' "__getattr__()" is not called. (This is an intentional ' - 'asymmetry\n' - ' between "__getattr__()" and "__setattr__()".) This is ' - 'done both for\n' - ' efficiency reasons and because otherwise ' - '"__getattr__()" would have\n' - ' no way to access other attributes of the instance. ' - 'Note that at\n' - ' least for instance variables, you can fake total ' - 'control by not\n' - ' inserting any values in the instance attribute ' - 'dictionary (but\n' - ' instead inserting them in another object). See the\n' - ' "__getattribute__()" method below for a way to actually ' - 'get total\n' - ' control over attribute access.\n' - '\n' - 'object.__getattribute__(self, name)\n' - '\n' - ' Called unconditionally to implement attribute accesses ' - 'for\n' - ' instances of the class. If the class also defines ' - '"__getattr__()",\n' - ' the latter will not be called unless ' - '"__getattribute__()" either\n' - ' calls it explicitly or raises an "AttributeError". This ' - 'method\n' - ' should return the (computed) attribute value or raise ' - 'an\n' - ' "AttributeError" exception. In order to avoid infinite ' - 'recursion in\n' - ' this method, its implementation should always call the ' - 'base class\n' - ' method with the same name to access any attributes it ' - 'needs, for\n' - ' example, "object.__getattribute__(self, name)".\n' - '\n' - ' Note: This method may still be bypassed when looking up ' - 'special\n' - ' methods as the result of implicit invocation via ' - 'language syntax\n' - ' or built-in functions. See *Special method lookup*.\n' - '\n' - 'object.__setattr__(self, name, value)\n' - '\n' - ' Called when an attribute assignment is attempted. This ' - 'is called\n' - ' instead of the normal mechanism (i.e. store the value ' - 'in the\n' - ' instance dictionary). *name* is the attribute name, ' - '*value* is the\n' - ' value to be assigned to it.\n' - '\n' - ' If "__setattr__()" wants to assign to an instance ' - 'attribute, it\n' - ' should call the base class method with the same name, ' - 'for example,\n' - ' "object.__setattr__(self, name, value)".\n' - '\n' - 'object.__delattr__(self, name)\n' - '\n' - ' Like "__setattr__()" but for attribute deletion instead ' - 'of\n' - ' assignment. This should only be implemented if "del ' - 'obj.name" is\n' - ' meaningful for the object.\n' - '\n' - 'object.__dir__(self)\n' - '\n' - ' Called when "dir()" is called on the object. A sequence ' - 'must be\n' - ' returned. "dir()" converts the returned sequence to a ' - 'list and\n' - ' sorts it.\n' - '\n' - '\n' - 'Implementing Descriptors\n' - '------------------------\n' - '\n' - 'The following methods only apply when an instance of the ' - 'class\n' - 'containing the method (a so-called *descriptor* class) ' - 'appears in an\n' - '*owner* class (the descriptor must be in either the ' - "owner's class\n" - 'dictionary or in the class dictionary for one of its ' - 'parents). In the\n' - 'examples below, "the attribute" refers to the attribute ' - 'whose name is\n' - 'the key of the property in the owner class\' "__dict__".\n' - '\n' - 'object.__get__(self, instance, owner)\n' - '\n' - ' Called to get the attribute of the owner class (class ' - 'attribute\n' - ' access) or of an instance of that class (instance ' - 'attribute\n' - ' access). *owner* is always the owner class, while ' - '*instance* is the\n' - ' instance that the attribute was accessed through, or ' - '"None" when\n' - ' the attribute is accessed through the *owner*. This ' - 'method should\n' - ' return the (computed) attribute value or raise an ' - '"AttributeError"\n' - ' exception.\n' - '\n' - 'object.__set__(self, instance, value)\n' - '\n' - ' Called to set the attribute on an instance *instance* ' - 'of the owner\n' - ' class to a new value, *value*.\n' - '\n' - 'object.__delete__(self, instance)\n' - '\n' - ' Called to delete the attribute on an instance ' - '*instance* of the\n' - ' owner class.\n' - '\n' - 'The attribute "__objclass__" is interpreted by the ' - '"inspect" module as\n' - 'specifying the class where this object was defined ' - '(setting this\n' - 'appropriately can assist in runtime introspection of ' - 'dynamic class\n' - 'attributes). For callables, it may indicate that an ' - 'instance of the\n' - 'given type (or a subclass) is expected or required as the ' - 'first\n' - 'positional argument (for example, CPython sets this ' - 'attribute for\n' - 'unbound methods that are implemented in C).\n' - '\n' - '\n' - 'Invoking Descriptors\n' - '--------------------\n' - '\n' - 'In general, a descriptor is an object attribute with ' - '"binding\n' - 'behavior", one whose attribute access has been overridden ' - 'by methods\n' - 'in the descriptor protocol: "__get__()", "__set__()", ' - 'and\n' - '"__delete__()". If any of those methods are defined for an ' - 'object, it\n' - 'is said to be a descriptor.\n' - '\n' - 'The default behavior for attribute access is to get, set, ' - 'or delete\n' - "the attribute from an object's dictionary. For instance, " - '"a.x" has a\n' - 'lookup chain starting with "a.__dict__[\'x\']", then\n' - '"type(a).__dict__[\'x\']", and continuing through the base ' - 'classes of\n' - '"type(a)" excluding metaclasses.\n' - '\n' - 'However, if the looked-up value is an object defining one ' - 'of the\n' - 'descriptor methods, then Python may override the default ' - 'behavior and\n' - 'invoke the descriptor method instead. Where this occurs ' - 'in the\n' - 'precedence chain depends on which descriptor methods were ' - 'defined and\n' - 'how they were called.\n' - '\n' - 'The starting point for descriptor invocation is a binding, ' - '"a.x". How\n' - 'the arguments are assembled depends on "a":\n' - '\n' - 'Direct Call\n' - ' The simplest and least common call is when user code ' - 'directly\n' - ' invokes a descriptor method: "x.__get__(a)".\n' - '\n' - 'Instance Binding\n' - ' If binding to an object instance, "a.x" is transformed ' - 'into the\n' - ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' - '\n' - 'Class Binding\n' - ' If binding to a class, "A.x" is transformed into the ' - 'call:\n' - ' "A.__dict__[\'x\'].__get__(None, A)".\n' - '\n' - 'Super Binding\n' - ' If "a" is an instance of "super", then the binding ' - '"super(B,\n' - ' obj).m()" searches "obj.__class__.__mro__" for the base ' - 'class "A"\n' - ' immediately preceding "B" and then invokes the ' - 'descriptor with the\n' - ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n' - '\n' - 'For instance bindings, the precedence of descriptor ' - 'invocation depends\n' - 'on the which descriptor methods are defined. A descriptor ' - 'can define\n' - 'any combination of "__get__()", "__set__()" and ' - '"__delete__()". If it\n' - 'does not define "__get__()", then accessing the attribute ' - 'will return\n' - 'the descriptor object itself unless there is a value in ' - "the object's\n" - 'instance dictionary. If the descriptor defines ' - '"__set__()" and/or\n' - '"__delete__()", it is a data descriptor; if it defines ' - 'neither, it is\n' - 'a non-data descriptor. Normally, data descriptors define ' - 'both\n' - '"__get__()" and "__set__()", while non-data descriptors ' - 'have just the\n' - '"__get__()" method. Data descriptors with "__set__()" and ' - '"__get__()"\n' - 'defined always override a redefinition in an instance ' - 'dictionary. In\n' - 'contrast, non-data descriptors can be overridden by ' - 'instances.\n' - '\n' - 'Python methods (including "staticmethod()" and ' - '"classmethod()") are\n' - 'implemented as non-data descriptors. Accordingly, ' - 'instances can\n' - 'redefine and override methods. This allows individual ' - 'instances to\n' - 'acquire behaviors that differ from other instances of the ' - 'same class.\n' - '\n' - 'The "property()" function is implemented as a data ' - 'descriptor.\n' - 'Accordingly, instances cannot override the behavior of a ' - 'property.\n' - '\n' - '\n' - '__slots__\n' - '---------\n' - '\n' - 'By default, instances of classes have a dictionary for ' - 'attribute\n' - 'storage. This wastes space for objects having very few ' - 'instance\n' - 'variables. The space consumption can become acute when ' - 'creating large\n' - 'numbers of instances.\n' - '\n' - 'The default can be overridden by defining *__slots__* in a ' - 'class\n' - 'definition. The *__slots__* declaration takes a sequence ' - 'of instance\n' - 'variables and reserves just enough space in each instance ' - 'to hold a\n' - 'value for each variable. Space is saved because ' - '*__dict__* is not\n' - 'created for each instance.\n' - '\n' - 'object.__slots__\n' - '\n' - ' This class variable can be assigned a string, iterable, ' - 'or sequence\n' - ' of strings with variable names used by instances. ' - '*__slots__*\n' - ' reserves space for the declared variables and prevents ' - 'the\n' - ' automatic creation of *__dict__* and *__weakref__* for ' - 'each\n' - ' instance.\n' - '\n' - '\n' - 'Notes on using *__slots__*\n' - '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' - '\n' - '* When inheriting from a class without *__slots__*, the ' - '*__dict__*\n' - ' attribute of that class will always be accessible, so a ' - '*__slots__*\n' - ' definition in the subclass is meaningless.\n' - '\n' - '* Without a *__dict__* variable, instances cannot be ' - 'assigned new\n' - ' variables not listed in the *__slots__* definition. ' - 'Attempts to\n' - ' assign to an unlisted variable name raises ' - '"AttributeError". If\n' - ' dynamic assignment of new variables is desired, then ' - 'add\n' - ' "\'__dict__\'" to the sequence of strings in the ' - '*__slots__*\n' - ' declaration.\n' - '\n' - '* Without a *__weakref__* variable for each instance, ' - 'classes\n' - ' defining *__slots__* do not support weak references to ' - 'its\n' - ' instances. If weak reference support is needed, then ' - 'add\n' - ' "\'__weakref__\'" to the sequence of strings in the ' - '*__slots__*\n' - ' declaration.\n' - '\n' - '* *__slots__* are implemented at the class level by ' - 'creating\n' - ' descriptors (*Implementing Descriptors*) for each ' - 'variable name. As\n' - ' a result, class attributes cannot be used to set default ' - 'values for\n' - ' instance variables defined by *__slots__*; otherwise, ' - 'the class\n' - ' attribute would overwrite the descriptor assignment.\n' - '\n' - '* The action of a *__slots__* declaration is limited to ' - 'the class\n' - ' where it is defined. As a result, subclasses will have ' - 'a *__dict__*\n' - ' unless they also define *__slots__* (which must only ' - 'contain names\n' - ' of any *additional* slots).\n' - '\n' - '* If a class defines a slot also defined in a base class, ' - 'the\n' - ' instance variable defined by the base class slot is ' - 'inaccessible\n' - ' (except by retrieving its descriptor directly from the ' - 'base class).\n' - ' This renders the meaning of the program undefined. In ' - 'the future, a\n' - ' check may be added to prevent this.\n' - '\n' - '* Nonempty *__slots__* does not work for classes derived ' - 'from\n' - ' "variable-length" built-in types such as "int", "bytes" ' - 'and "tuple".\n' - '\n' - '* Any non-string iterable may be assigned to *__slots__*. ' - 'Mappings\n' - ' may also be used; however, in the future, special ' - 'meaning may be\n' - ' assigned to the values corresponding to each key.\n' - '\n' - '* *__class__* assignment works only if both classes have ' - 'the same\n' - ' *__slots__*.\n' - '\n' - '\n' - 'Customizing class creation\n' - '==========================\n' - '\n' - 'By default, classes are constructed using "type()". The ' - 'class body is\n' - 'executed in a new namespace and the class name is bound ' - 'locally to the\n' - 'result of "type(name, bases, namespace)".\n' - '\n' - 'The class creation process can be customised by passing ' - 'the\n' - '"metaclass" keyword argument in the class definition line, ' - 'or by\n' - 'inheriting from an existing class that included such an ' - 'argument. In\n' - 'the following example, both "MyClass" and "MySubclass" are ' - 'instances\n' - 'of "Meta":\n' - '\n' - ' class Meta(type):\n' - ' pass\n' - '\n' - ' class MyClass(metaclass=Meta):\n' - ' pass\n' - '\n' - ' class MySubclass(MyClass):\n' - ' pass\n' - '\n' - 'Any other keyword arguments that are specified in the ' - 'class definition\n' - 'are passed through to all metaclass operations described ' - 'below.\n' - '\n' - 'When a class definition is executed, the following steps ' - 'occur:\n' - '\n' - '* the appropriate metaclass is determined\n' - '\n' - '* the class namespace is prepared\n' - '\n' - '* the class body is executed\n' - '\n' - '* the class object is created\n' - '\n' - '\n' - 'Determining the appropriate metaclass\n' - '-------------------------------------\n' - '\n' - 'The appropriate metaclass for a class definition is ' - 'determined as\n' - 'follows:\n' - '\n' - '* if no bases and no explicit metaclass are given, then ' - '"type()" is\n' - ' used\n' - '\n' - '* if an explicit metaclass is given and it is *not* an ' - 'instance of\n' - ' "type()", then it is used directly as the metaclass\n' - '\n' - '* if an instance of "type()" is given as the explicit ' - 'metaclass, or\n' - ' bases are defined, then the most derived metaclass is ' - 'used\n' - '\n' - 'The most derived metaclass is selected from the explicitly ' - 'specified\n' - 'metaclass (if any) and the metaclasses (i.e. "type(cls)") ' - 'of all\n' - 'specified base classes. The most derived metaclass is one ' - 'which is a\n' - 'subtype of *all* of these candidate metaclasses. If none ' - 'of the\n' - 'candidate metaclasses meets that criterion, then the class ' - 'definition\n' - 'will fail with "TypeError".\n' - '\n' - '\n' - 'Preparing the class namespace\n' - '-----------------------------\n' - '\n' - 'Once the appropriate metaclass has been identified, then ' - 'the class\n' - 'namespace is prepared. If the metaclass has a ' - '"__prepare__" attribute,\n' - 'it is called as "namespace = metaclass.__prepare__(name, ' - 'bases,\n' - '**kwds)" (where the additional keyword arguments, if any, ' - 'come from\n' - 'the class definition).\n' - '\n' - 'If the metaclass has no "__prepare__" attribute, then the ' - 'class\n' - 'namespace is initialised as an empty "dict()" instance.\n' - '\n' - 'See also: **PEP 3115** - Metaclasses in Python 3000\n' - '\n' - ' Introduced the "__prepare__" namespace hook\n' - '\n' - '\n' - 'Executing the class body\n' - '------------------------\n' - '\n' - 'The class body is executed (approximately) as "exec(body, ' - 'globals(),\n' - 'namespace)". The key difference from a normal call to ' - '"exec()" is that\n' - 'lexical scoping allows the class body (including any ' - 'methods) to\n' - 'reference names from the current and outer scopes when the ' - 'class\n' - 'definition occurs inside a function.\n' - '\n' - 'However, even when the class definition occurs inside the ' - 'function,\n' - 'methods defined inside the class still cannot see names ' - 'defined at the\n' - 'class scope. Class variables must be accessed through the ' - 'first\n' - 'parameter of instance or class methods, and cannot be ' - 'accessed at all\n' - 'from static methods.\n' - '\n' - '\n' - 'Creating the class object\n' - '-------------------------\n' - '\n' - 'Once the class namespace has been populated by executing ' - 'the class\n' - 'body, the class object is created by calling ' - '"metaclass(name, bases,\n' - 'namespace, **kwds)" (the additional keywords passed here ' - 'are the same\n' - 'as those passed to "__prepare__").\n' - '\n' - 'This class object is the one that will be referenced by ' - 'the zero-\n' - 'argument form of "super()". "__class__" is an implicit ' - 'closure\n' - 'reference created by the compiler if any methods in a ' - 'class body refer\n' - 'to either "__class__" or "super". This allows the zero ' - 'argument form\n' - 'of "super()" to correctly identify the class being defined ' - 'based on\n' - 'lexical scoping, while the class or instance that was used ' - 'to make the\n' - 'current call is identified based on the first argument ' - 'passed to the\n' - 'method.\n' - '\n' - 'After the class object is created, it is passed to the ' - 'class\n' - 'decorators included in the class definition (if any) and ' - 'the resulting\n' - 'object is bound in the local namespace as the defined ' - 'class.\n' - '\n' - 'See also: **PEP 3135** - New super\n' - '\n' - ' Describes the implicit "__class__" closure reference\n' - '\n' - '\n' - 'Metaclass example\n' - '-----------------\n' - '\n' - 'The potential uses for metaclasses are boundless. Some ' - 'ideas that have\n' - 'been explored include logging, interface checking, ' - 'automatic\n' - 'delegation, automatic property creation, proxies, ' - 'frameworks, and\n' - 'automatic resource locking/synchronization.\n' - '\n' - 'Here is an example of a metaclass that uses an\n' - '"collections.OrderedDict" to remember the order that class ' - 'variables\n' - 'are defined:\n' - '\n' - ' class OrderedClass(type):\n' - '\n' - ' @classmethod\n' - ' def __prepare__(metacls, name, bases, **kwds):\n' - ' return collections.OrderedDict()\n' - '\n' - ' def __new__(cls, name, bases, namespace, **kwds):\n' - ' result = type.__new__(cls, name, bases, ' - 'dict(namespace))\n' - ' result.members = tuple(namespace)\n' - ' return result\n' - '\n' - ' class A(metaclass=OrderedClass):\n' - ' def one(self): pass\n' - ' def two(self): pass\n' - ' def three(self): pass\n' - ' def four(self): pass\n' - '\n' - ' >>> A.members\n' - " ('__module__', 'one', 'two', 'three', 'four')\n" - '\n' - 'When the class definition for *A* gets executed, the ' - 'process begins\n' - 'with calling the metaclass\'s "__prepare__()" method which ' - 'returns an\n' - 'empty "collections.OrderedDict". That mapping records the ' - 'methods and\n' - 'attributes of *A* as they are defined within the body of ' - 'the class\n' - 'statement. Once those definitions are executed, the ' - 'ordered dictionary\n' - 'is fully populated and the metaclass\'s "__new__()" method ' - 'gets\n' - 'invoked. That method builds the new type and it saves the ' - 'ordered\n' - 'dictionary keys in an attribute called "members".\n' - '\n' - '\n' - 'Customizing instance and subclass checks\n' - '========================================\n' - '\n' - 'The following methods are used to override the default ' - 'behavior of the\n' - '"isinstance()" and "issubclass()" built-in functions.\n' - '\n' - 'In particular, the metaclass "abc.ABCMeta" implements ' - 'these methods in\n' - 'order to allow the addition of Abstract Base Classes ' - '(ABCs) as\n' - '"virtual base classes" to any class or type (including ' - 'built-in\n' - 'types), including other ABCs.\n' - '\n' - 'class.__instancecheck__(self, instance)\n' - '\n' - ' Return true if *instance* should be considered a ' - '(direct or\n' - ' indirect) instance of *class*. If defined, called to ' - 'implement\n' - ' "isinstance(instance, class)".\n' - '\n' - 'class.__subclasscheck__(self, subclass)\n' - '\n' - ' Return true if *subclass* should be considered a ' - '(direct or\n' - ' indirect) subclass of *class*. If defined, called to ' - 'implement\n' - ' "issubclass(subclass, class)".\n' - '\n' - 'Note that these methods are looked up on the type ' - '(metaclass) of a\n' - 'class. They cannot be defined as class methods in the ' - 'actual class.\n' - 'This is consistent with the lookup of special methods that ' - 'are called\n' - 'on instances, only in this case the instance is itself a ' - 'class.\n' - '\n' - 'See also: **PEP 3119** - Introducing Abstract Base ' - 'Classes\n' - '\n' - ' Includes the specification for customizing ' - '"isinstance()" and\n' - ' "issubclass()" behavior through "__instancecheck__()" ' - 'and\n' - ' "__subclasscheck__()", with motivation for this ' - 'functionality in\n' - ' the context of adding Abstract Base Classes (see the ' - '"abc"\n' - ' module) to the language.\n' - '\n' - '\n' - 'Emulating callable objects\n' - '==========================\n' - '\n' - 'object.__call__(self[, args...])\n' - '\n' - ' Called when the instance is "called" as a function; if ' - 'this method\n' - ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' - ' "x.__call__(arg1, arg2, ...)".\n' - '\n' - '\n' - 'Emulating container types\n' - '=========================\n' - '\n' - 'The following methods can be defined to implement ' - 'container objects.\n' - 'Containers usually are sequences (such as lists or tuples) ' - 'or mappings\n' - '(like dictionaries), but can represent other containers as ' - 'well. The\n' - 'first set of methods is used either to emulate a sequence ' - 'or to\n' - 'emulate a mapping; the difference is that for a sequence, ' - 'the\n' - 'allowable keys should be the integers *k* for which "0 <= ' - 'k < N" where\n' - '*N* is the length of the sequence, or slice objects, which ' - 'define a\n' - 'range of items. It is also recommended that mappings ' - 'provide the\n' - 'methods "keys()", "values()", "items()", "get()", ' - '"clear()",\n' - '"setdefault()", "pop()", "popitem()", "copy()", and ' - '"update()"\n' - "behaving similar to those for Python's standard dictionary " - 'objects.\n' - 'The "collections" module provides a "MutableMapping" ' - 'abstract base\n' - 'class to help create those methods from a base set of ' - '"__getitem__()",\n' - '"__setitem__()", "__delitem__()", and "keys()". Mutable ' - 'sequences\n' - 'should provide methods "append()", "count()", "index()", ' - '"extend()",\n' - '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' - 'like Python\n' - 'standard list objects. Finally, sequence types should ' - 'implement\n' - 'addition (meaning concatenation) and multiplication ' - '(meaning\n' - 'repetition) by defining the methods "__add__()", ' - '"__radd__()",\n' - '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' - 'described\n' - 'below; they should not define other numerical operators. ' - 'It is\n' - 'recommended that both mappings and sequences implement ' - 'the\n' - '"__contains__()" method to allow efficient use of the "in" ' - 'operator;\n' - 'for mappings, "in" should search the mapping\'s keys; for ' - 'sequences, it\n' - 'should search through the values. It is further ' - 'recommended that both\n' - 'mappings and sequences implement the "__iter__()" method ' - 'to allow\n' - 'efficient iteration through the container; for mappings, ' - '"__iter__()"\n' - 'should be the same as "keys()"; for sequences, it should ' - 'iterate\n' - 'through the values.\n' - '\n' - 'object.__len__(self)\n' - '\n' - ' Called to implement the built-in function "len()". ' - 'Should return\n' - ' the length of the object, an integer ">=" 0. Also, an ' - 'object that\n' - ' doesn\'t define a "__bool__()" method and whose ' - '"__len__()" method\n' - ' returns zero is considered to be false in a Boolean ' - 'context.\n' - '\n' - 'object.__length_hint__(self)\n' - '\n' - ' Called to implement "operator.length_hint()". Should ' - 'return an\n' - ' estimated length for the object (which may be greater ' - 'or less than\n' - ' the actual length). The length must be an integer ">=" ' - '0. This\n' - ' method is purely an optimization and is never required ' - 'for\n' - ' correctness.\n' - '\n' - ' New in version 3.4.\n' - '\n' - 'Note: Slicing is done exclusively with the following three ' - 'methods.\n' - ' A call like\n' - '\n' - ' a[1:2] = b\n' - '\n' - ' is translated to\n' - '\n' - ' a[slice(1, 2, None)] = b\n' - '\n' - ' and so forth. Missing slice items are always filled in ' - 'with "None".\n' - '\n' - 'object.__getitem__(self, key)\n' - '\n' - ' Called to implement evaluation of "self[key]". For ' - 'sequence types,\n' - ' the accepted keys should be integers and slice ' - 'objects. Note that\n' - ' the special interpretation of negative indexes (if the ' - 'class wishes\n' - ' to emulate a sequence type) is up to the ' - '"__getitem__()" method. If\n' - ' *key* is of an inappropriate type, "TypeError" may be ' - 'raised; if of\n' - ' a value outside the set of indexes for the sequence ' - '(after any\n' - ' special interpretation of negative values), ' - '"IndexError" should be\n' - ' raised. For mapping types, if *key* is missing (not in ' - 'the\n' - ' container), "KeyError" should be raised.\n' - '\n' - ' Note: "for" loops expect that an "IndexError" will be ' - 'raised for\n' - ' illegal indexes to allow proper detection of the end ' - 'of the\n' - ' sequence.\n' - '\n' - 'object.__missing__(self, key)\n' - '\n' - ' Called by "dict"."__getitem__()" to implement ' - '"self[key]" for dict\n' - ' subclasses when key is not in the dictionary.\n' - '\n' - 'object.__setitem__(self, key, value)\n' - '\n' - ' Called to implement assignment to "self[key]". Same ' - 'note as for\n' - ' "__getitem__()". This should only be implemented for ' - 'mappings if\n' - ' the objects support changes to the values for keys, or ' - 'if new keys\n' - ' can be added, or for sequences if elements can be ' - 'replaced. The\n' - ' same exceptions should be raised for improper *key* ' - 'values as for\n' - ' the "__getitem__()" method.\n' - '\n' - 'object.__delitem__(self, key)\n' - '\n' - ' Called to implement deletion of "self[key]". Same note ' - 'as for\n' - ' "__getitem__()". This should only be implemented for ' - 'mappings if\n' - ' the objects support removal of keys, or for sequences ' - 'if elements\n' - ' can be removed from the sequence. The same exceptions ' - 'should be\n' - ' raised for improper *key* values as for the ' - '"__getitem__()" method.\n' - '\n' - 'object.__iter__(self)\n' - '\n' - ' This method is called when an iterator is required for ' - 'a container.\n' - ' This method should return a new iterator object that ' - 'can iterate\n' - ' over all the objects in the container. For mappings, ' - 'it should\n' - ' iterate over the keys of the container.\n' - '\n' - ' Iterator objects also need to implement this method; ' - 'they are\n' - ' required to return themselves. For more information on ' - 'iterator\n' - ' objects, see *Iterator Types*.\n' - '\n' - 'object.__reversed__(self)\n' - '\n' - ' Called (if present) by the "reversed()" built-in to ' - 'implement\n' - ' reverse iteration. It should return a new iterator ' - 'object that\n' - ' iterates over all the objects in the container in ' - 'reverse order.\n' - '\n' - ' If the "__reversed__()" method is not provided, the ' - '"reversed()"\n' - ' built-in will fall back to using the sequence protocol ' - '("__len__()"\n' - ' and "__getitem__()"). Objects that support the ' - 'sequence protocol\n' - ' should only provide "__reversed__()" if they can ' - 'provide an\n' - ' implementation that is more efficient than the one ' - 'provided by\n' - ' "reversed()".\n' - '\n' - 'The membership test operators ("in" and "not in") are ' - 'normally\n' - 'implemented as an iteration through a sequence. However, ' - 'container\n' - 'objects can supply the following special method with a ' - 'more efficient\n' - 'implementation, which also does not require the object be ' - 'a sequence.\n' - '\n' - 'object.__contains__(self, item)\n' - '\n' - ' Called to implement membership test operators. Should ' - 'return true\n' - ' if *item* is in *self*, false otherwise. For mapping ' - 'objects, this\n' - ' should consider the keys of the mapping rather than the ' - 'values or\n' - ' the key-item pairs.\n' - '\n' - ' For objects that don\'t define "__contains__()", the ' - 'membership test\n' - ' first tries iteration via "__iter__()", then the old ' - 'sequence\n' - ' iteration protocol via "__getitem__()", see *this ' - 'section in the\n' - ' language reference*.\n' - '\n' - '\n' - 'Emulating numeric types\n' - '=======================\n' - '\n' - 'The following methods can be defined to emulate numeric ' - 'objects.\n' - 'Methods corresponding to operations that are not supported ' - 'by the\n' - 'particular kind of number implemented (e.g., bitwise ' - 'operations for\n' - 'non-integral numbers) should be left undefined.\n' - '\n' - 'object.__add__(self, other)\n' - 'object.__sub__(self, other)\n' - 'object.__mul__(self, other)\n' - 'object.__truediv__(self, other)\n' - 'object.__floordiv__(self, other)\n' - 'object.__mod__(self, other)\n' - 'object.__divmod__(self, other)\n' - 'object.__pow__(self, other[, modulo])\n' - 'object.__lshift__(self, other)\n' - 'object.__rshift__(self, other)\n' - 'object.__and__(self, other)\n' - 'object.__xor__(self, other)\n' - 'object.__or__(self, other)\n' - '\n' - ' These methods are called to implement the binary ' - 'arithmetic\n' - ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' - '"pow()",\n' - ' "**", "<<", ">>", "&", "^", "|"). For instance, to ' - 'evaluate the\n' - ' expression "x + y", where *x* is an instance of a class ' - 'that has an\n' - ' "__add__()" method, "x.__add__(y)" is called. The ' - '"__divmod__()"\n' - ' method should be the equivalent to using ' - '"__floordiv__()" and\n' - ' "__mod__()"; it should not be related to ' - '"__truediv__()". Note\n' - ' that "__pow__()" should be defined to accept an ' - 'optional third\n' - ' argument if the ternary version of the built-in "pow()" ' - 'function is\n' - ' to be supported.\n' - '\n' - ' If one of those methods does not support the operation ' - 'with the\n' - ' supplied arguments, it should return "NotImplemented".\n' - '\n' - 'object.__radd__(self, other)\n' - 'object.__rsub__(self, other)\n' - 'object.__rmul__(self, other)\n' - 'object.__rtruediv__(self, other)\n' - 'object.__rfloordiv__(self, other)\n' - 'object.__rmod__(self, other)\n' - 'object.__rdivmod__(self, other)\n' - 'object.__rpow__(self, other)\n' - 'object.__rlshift__(self, other)\n' - 'object.__rrshift__(self, other)\n' - 'object.__rand__(self, other)\n' - 'object.__rxor__(self, other)\n' - 'object.__ror__(self, other)\n' - '\n' - ' These methods are called to implement the binary ' - 'arithmetic\n' - ' operations ("+", "-", "*", "/", "//", "%", "divmod()", ' - '"pow()",\n' - ' "**", "<<", ">>", "&", "^", "|") with reflected ' - '(swapped) operands.\n' - ' These functions are only called if the left operand ' - 'does not\n' - ' support the corresponding operation and the operands ' - 'are of\n' - ' different types. [2] For instance, to evaluate the ' - 'expression "x -\n' - ' y", where *y* is an instance of a class that has an ' - '"__rsub__()"\n' - ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' - 'returns\n' - ' *NotImplemented*.\n' - '\n' - ' Note that ternary "pow()" will not try calling ' - '"__rpow__()" (the\n' - ' coercion rules would become too complicated).\n' - '\n' - " Note: If the right operand's type is a subclass of the " - 'left\n' - " operand's type and that subclass provides the " - 'reflected method\n' - ' for the operation, this method will be called before ' - 'the left\n' - " operand's non-reflected method. This behavior allows " - 'subclasses\n' - " to override their ancestors' operations.\n" - '\n' - 'object.__iadd__(self, other)\n' - 'object.__isub__(self, other)\n' - 'object.__imul__(self, other)\n' - 'object.__itruediv__(self, other)\n' - 'object.__ifloordiv__(self, other)\n' - 'object.__imod__(self, other)\n' - 'object.__ipow__(self, other[, modulo])\n' - 'object.__ilshift__(self, other)\n' - 'object.__irshift__(self, other)\n' - 'object.__iand__(self, other)\n' - 'object.__ixor__(self, other)\n' - 'object.__ior__(self, other)\n' - '\n' - ' These methods are called to implement the augmented ' - 'arithmetic\n' - ' assignments ("+=", "-=", "*=", "/=", "//=", "%=", ' - '"**=", "<<=",\n' - ' ">>=", "&=", "^=", "|="). These methods should attempt ' - 'to do the\n' - ' operation in-place (modifying *self*) and return the ' - 'result (which\n' - ' could be, but does not have to be, *self*). If a ' - 'specific method\n' - ' is not defined, the augmented assignment falls back to ' - 'the normal\n' - ' methods. For instance, if *x* is an instance of a ' - 'class with an\n' - ' "__iadd__()" method, "x += y" is equivalent to "x = ' - 'x.__iadd__(y)"\n' - ' . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are ' - 'considered, as\n' - ' with the evaluation of "x + y". In certain situations, ' - 'augmented\n' - ' assignment can result in unexpected errors (see *Why ' - 'does\n' - " a_tuple[i] += ['item'] raise an exception when the " - 'addition\n' - ' works?*), but this behavior is in fact part of the data ' - 'model.\n' - '\n' - 'object.__neg__(self)\n' - 'object.__pos__(self)\n' - 'object.__abs__(self)\n' - 'object.__invert__(self)\n' - '\n' - ' Called to implement the unary arithmetic operations ' - '("-", "+",\n' - ' "abs()" and "~").\n' - '\n' - 'object.__complex__(self)\n' - 'object.__int__(self)\n' - 'object.__float__(self)\n' - 'object.__round__(self[, n])\n' - '\n' - ' Called to implement the built-in functions "complex()", ' - '"int()",\n' - ' "float()" and "round()". Should return a value of the ' - 'appropriate\n' - ' type.\n' - '\n' - 'object.__index__(self)\n' - '\n' - ' Called to implement "operator.index()", and whenever ' - 'Python needs\n' - ' to losslessly convert the numeric object to an integer ' - 'object (such\n' - ' as in slicing, or in the built-in "bin()", "hex()" and ' - '"oct()"\n' - ' functions). Presence of this method indicates that the ' - 'numeric\n' - ' object is an integer type. Must return an integer.\n' - '\n' - ' Note: In order to have a coherent integer type class, ' - 'when\n' - ' "__index__()" is defined "__int__()" should also be ' - 'defined, and\n' - ' both should return the same value.\n' - '\n' - '\n' - 'With Statement Context Managers\n' - '===============================\n' - '\n' - 'A *context manager* is an object that defines the runtime ' - 'context to\n' - 'be established when executing a "with" statement. The ' - 'context manager\n' - 'handles the entry into, and the exit from, the desired ' - 'runtime context\n' - 'for the execution of the block of code. Context managers ' - 'are normally\n' - 'invoked using the "with" statement (described in section ' - '*The with\n' - 'statement*), but can also be used by directly invoking ' - 'their methods.\n' - '\n' - 'Typical uses of context managers include saving and ' - 'restoring various\n' - 'kinds of global state, locking and unlocking resources, ' - 'closing opened\n' - 'files, etc.\n' - '\n' - 'For more information on context managers, see *Context ' - 'Manager Types*.\n' - '\n' - 'object.__enter__(self)\n' - '\n' - ' Enter the runtime context related to this object. The ' - '"with"\n' - " statement will bind this method's return value to the " - 'target(s)\n' - ' specified in the "as" clause of the statement, if any.\n' - '\n' - 'object.__exit__(self, exc_type, exc_value, traceback)\n' - '\n' - ' Exit the runtime context related to this object. The ' - 'parameters\n' - ' describe the exception that caused the context to be ' - 'exited. If the\n' - ' context was exited without an exception, all three ' - 'arguments will\n' - ' be "None".\n' - '\n' - ' If an exception is supplied, and the method wishes to ' - 'suppress the\n' - ' exception (i.e., prevent it from being propagated), it ' - 'should\n' - ' return a true value. Otherwise, the exception will be ' - 'processed\n' - ' normally upon exit from this method.\n' - '\n' - ' Note that "__exit__()" methods should not reraise the ' - 'passed-in\n' - " exception; this is the caller's responsibility.\n" - '\n' - 'See also: **PEP 0343** - The "with" statement\n' - '\n' - ' The specification, background, and examples for the ' - 'Python "with"\n' - ' statement.\n' - '\n' - '\n' - 'Special method lookup\n' - '=====================\n' - '\n' - 'For custom classes, implicit invocations of special ' - 'methods are only\n' - "guaranteed to work correctly if defined on an object's " - 'type, not in\n' - "the object's instance dictionary. That behaviour is the " - 'reason why\n' - 'the following code raises an exception:\n' - '\n' - ' >>> class C:\n' - ' ... pass\n' - ' ...\n' - ' >>> c = C()\n' - ' >>> c.__len__ = lambda: 5\n' - ' >>> len(c)\n' - ' Traceback (most recent call last):\n' - ' File "", line 1, in \n' - " TypeError: object of type 'C' has no len()\n" - '\n' - 'The rationale behind this behaviour lies with a number of ' - 'special\n' - 'methods such as "__hash__()" and "__repr__()" that are ' - 'implemented by\n' - 'all objects, including type objects. If the implicit ' - 'lookup of these\n' - 'methods used the conventional lookup process, they would ' - 'fail when\n' - 'invoked on the type object itself:\n' - '\n' - ' >>> 1 .__hash__() == hash(1)\n' - ' True\n' - ' >>> int.__hash__() == hash(int)\n' - ' Traceback (most recent call last):\n' - ' File "", line 1, in \n' - " TypeError: descriptor '__hash__' of 'int' object needs " - 'an argument\n' - '\n' - 'Incorrectly attempting to invoke an unbound method of a ' - 'class in this\n' - "way is sometimes referred to as 'metaclass confusion', and " - 'is avoided\n' - 'by bypassing the instance when looking up special ' - 'methods:\n' - '\n' - ' >>> type(1).__hash__(1) == hash(1)\n' - ' True\n' - ' >>> type(int).__hash__(int) == hash(int)\n' - ' True\n' - '\n' - 'In addition to bypassing any instance attributes in the ' - 'interest of\n' - 'correctness, implicit special method lookup generally also ' - 'bypasses\n' - 'the "__getattribute__()" method even of the object\'s ' - 'metaclass:\n' - '\n' - ' >>> class Meta(type):\n' - ' ... def __getattribute__(*args):\n' - ' ... print("Metaclass getattribute invoked")\n' - ' ... return type.__getattribute__(*args)\n' - ' ...\n' - ' >>> class C(object, metaclass=Meta):\n' - ' ... def __len__(self):\n' - ' ... return 10\n' - ' ... def __getattribute__(*args):\n' - ' ... print("Class getattribute invoked")\n' - ' ... return object.__getattribute__(*args)\n' - ' ...\n' - ' >>> c = C()\n' - ' >>> c.__len__() # Explicit lookup via ' - 'instance\n' - ' Class getattribute invoked\n' - ' 10\n' - ' >>> type(c).__len__(c) # Explicit lookup via ' - 'type\n' - ' Metaclass getattribute invoked\n' - ' 10\n' - ' >>> len(c) # Implicit lookup\n' - ' 10\n' - '\n' - 'Bypassing the "__getattribute__()" machinery in this ' - 'fashion provides\n' - 'significant scope for speed optimisations within the ' - 'interpreter, at\n' - 'the cost of some flexibility in the handling of special ' - 'methods (the\n' - 'special method *must* be set on the class object itself in ' - 'order to be\n' - 'consistently invoked by the interpreter).\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - "[1] It *is* possible in some cases to change an object's " - 'type,\n' - ' under certain controlled conditions. It generally ' - "isn't a good\n" - ' idea though, since it can lead to some very strange ' - 'behaviour if\n' - ' it is handled incorrectly.\n' - '\n' - '[2] For operands of the same type, it is assumed that if ' - 'the non-\n' - ' reflected method (such as "__add__()") fails the ' - 'operation is not\n' - ' supported, which is why the reflected method is not ' - 'called.\n', - 'string-methods': '\n' - 'String Methods\n' - '**************\n' - '\n' - 'Strings implement all of the *common* sequence ' - 'operations, along with\n' - 'the additional methods described below.\n' - '\n' - 'Strings also support two styles of string formatting, ' - 'one providing a\n' - 'large degree of flexibility and customization (see ' - '"str.format()",\n' - '*Format String Syntax* and *String Formatting*) and the ' - 'other based on\n' - 'C "printf" style formatting that handles a narrower ' - 'range of types and\n' - 'is slightly harder to use correctly, but is often faster ' - 'for the cases\n' - 'it can handle (*printf-style String Formatting*).\n' - '\n' - 'The *Text Processing Services* section of the standard ' - 'library covers\n' - 'a number of other modules that provide various text ' - 'related utilities\n' - '(including regular expression support in the "re" ' - 'module).\n' - '\n' - 'str.capitalize()\n' - '\n' - ' Return a copy of the string with its first character ' - 'capitalized\n' - ' and the rest lowercased.\n' - '\n' - 'str.casefold()\n' - '\n' - ' Return a casefolded copy of the string. Casefolded ' - 'strings may be\n' - ' used for caseless matching.\n' - '\n' - ' Casefolding is similar to lowercasing but more ' - 'aggressive because\n' - ' it is intended to remove all case distinctions in a ' - 'string. For\n' - ' example, the German lowercase letter "\'ß\'" is ' - 'equivalent to ""ss"".\n' - ' Since it is already lowercase, "lower()" would do ' - 'nothing to "\'ß\'";\n' - ' "casefold()" converts it to ""ss"".\n' - '\n' - ' The casefolding algorithm is described in section ' - '3.13 of the\n' - ' Unicode Standard.\n' - '\n' - ' New in version 3.3.\n' - '\n' - 'str.center(width[, fillchar])\n' - '\n' - ' Return centered in a string of length *width*. ' - 'Padding is done\n' - ' using the specified *fillchar* (default is an ASCII ' - 'space). The\n' - ' original string is returned if *width* is less than ' - 'or equal to\n' - ' "len(s)".\n' - '\n' - 'str.count(sub[, start[, end]])\n' - '\n' - ' Return the number of non-overlapping occurrences of ' - 'substring *sub*\n' - ' in the range [*start*, *end*]. Optional arguments ' - '*start* and\n' - ' *end* are interpreted as in slice notation.\n' - '\n' - 'str.encode(encoding="utf-8", errors="strict")\n' - '\n' - ' Return an encoded version of the string as a bytes ' - 'object. Default\n' - ' encoding is "\'utf-8\'". *errors* may be given to set ' - 'a different\n' - ' error handling scheme. The default for *errors* is ' - '"\'strict\'",\n' - ' meaning that encoding errors raise a "UnicodeError". ' - 'Other possible\n' - ' values are "\'ignore\'", "\'replace\'", ' - '"\'xmlcharrefreplace\'",\n' - ' "\'backslashreplace\'" and any other name registered ' - 'via\n' - ' "codecs.register_error()", see section *Error ' - 'Handlers*. For a list\n' - ' of possible encodings, see section *Standard ' - 'Encodings*.\n' - '\n' - ' Changed in version 3.1: Support for keyword arguments ' - 'added.\n' - '\n' - 'str.endswith(suffix[, start[, end]])\n' - '\n' - ' Return "True" if the string ends with the specified ' - '*suffix*,\n' - ' otherwise return "False". *suffix* can also be a ' - 'tuple of suffixes\n' - ' to look for. With optional *start*, test beginning ' - 'at that\n' - ' position. With optional *end*, stop comparing at ' - 'that position.\n' - '\n' - 'str.expandtabs(tabsize=8)\n' - '\n' - ' Return a copy of the string where all tab characters ' - 'are replaced\n' - ' by one or more spaces, depending on the current ' - 'column and the\n' - ' given tab size. Tab positions occur every *tabsize* ' - 'characters\n' - ' (default is 8, giving tab positions at columns 0, 8, ' - '16 and so on).\n' - ' To expand the string, the current column is set to ' - 'zero and the\n' - ' string is examined character by character. If the ' - 'character is a\n' - ' tab ("\\t"), one or more space characters are ' - 'inserted in the result\n' - ' until the current column is equal to the next tab ' - 'position. (The\n' - ' tab character itself is not copied.) If the ' - 'character is a newline\n' - ' ("\\n") or return ("\\r"), it is copied and the ' - 'current column is\n' - ' reset to zero. Any other character is copied ' - 'unchanged and the\n' - ' current column is incremented by one regardless of ' - 'how the\n' - ' character is represented when printed.\n' - '\n' - " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n" - " '01 012 0123 01234'\n" - " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n" - " '01 012 0123 01234'\n" - '\n' - 'str.find(sub[, start[, end]])\n' - '\n' - ' Return the lowest index in the string where substring ' - '*sub* is\n' - ' found within the slice "s[start:end]". Optional ' - 'arguments *start*\n' - ' and *end* are interpreted as in slice notation. ' - 'Return "-1" if\n' - ' *sub* is not found.\n' - '\n' - ' Note: The "find()" method should be used only if you ' - 'need to know\n' - ' the position of *sub*. To check if *sub* is a ' - 'substring or not,\n' - ' use the "in" operator:\n' - '\n' - " >>> 'Py' in 'Python'\n" - ' True\n' - '\n' - 'str.format(*args, **kwargs)\n' - '\n' - ' Perform a string formatting operation. The string on ' - 'which this\n' - ' method is called can contain literal text or ' - 'replacement fields\n' - ' delimited by braces "{}". Each replacement field ' - 'contains either\n' - ' the numeric index of a positional argument, or the ' - 'name of a\n' - ' keyword argument. Returns a copy of the string where ' - 'each\n' - ' replacement field is replaced with the string value ' - 'of the\n' - ' corresponding argument.\n' - '\n' - ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n' - " 'The sum of 1 + 2 is 3'\n" - '\n' - ' See *Format String Syntax* for a description of the ' - 'various\n' - ' formatting options that can be specified in format ' - 'strings.\n' - '\n' - 'str.format_map(mapping)\n' - '\n' - ' Similar to "str.format(**mapping)", except that ' - '"mapping" is used\n' - ' directly and not copied to a "dict". This is useful ' - 'if for example\n' - ' "mapping" is a dict subclass:\n' - '\n' - ' >>> class Default(dict):\n' - ' ... def __missing__(self, key):\n' - ' ... return key\n' - ' ...\n' - " >>> '{name} was born in " - "{country}'.format_map(Default(name='Guido'))\n" - " 'Guido was born in country'\n" - '\n' - ' New in version 3.2.\n' - '\n' - 'str.index(sub[, start[, end]])\n' - '\n' - ' Like "find()", but raise "ValueError" when the ' - 'substring is not\n' - ' found.\n' - '\n' - 'str.isalnum()\n' - '\n' - ' Return true if all characters in the string are ' - 'alphanumeric and\n' - ' there is at least one character, false otherwise. A ' - 'character "c"\n' - ' is alphanumeric if one of the following returns ' - '"True":\n' - ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or ' - '"c.isnumeric()".\n' - '\n' - 'str.isalpha()\n' - '\n' - ' Return true if all characters in the string are ' - 'alphabetic and\n' - ' there is at least one character, false otherwise. ' - 'Alphabetic\n' - ' characters are those characters defined in the ' - 'Unicode character\n' - ' database as "Letter", i.e., those with general ' - 'category property\n' - ' being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note ' - 'that this is\n' - ' different from the "Alphabetic" property defined in ' - 'the Unicode\n' - ' Standard.\n' - '\n' - 'str.isdecimal()\n' - '\n' - ' Return true if all characters in the string are ' - 'decimal characters\n' - ' and there is at least one character, false otherwise. ' - 'Decimal\n' - ' characters are those from general category "Nd". This ' - 'category\n' - ' includes digit characters, and all characters that ' - 'can be used to\n' - ' form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC ' - 'DIGIT ZERO.\n' - '\n' - 'str.isdigit()\n' - '\n' - ' Return true if all characters in the string are ' - 'digits and there is\n' - ' at least one character, false otherwise. Digits ' - 'include decimal\n' - ' characters and digits that need special handling, ' - 'such as the\n' - ' compatibility superscript digits. Formally, a digit ' - 'is a character\n' - ' that has the property value Numeric_Type=Digit or\n' - ' Numeric_Type=Decimal.\n' - '\n' - 'str.isidentifier()\n' - '\n' - ' Return true if the string is a valid identifier ' - 'according to the\n' - ' language definition, section *Identifiers and ' - 'keywords*.\n' - '\n' - ' Use "keyword.iskeyword()" to test for reserved ' - 'identifiers such as\n' - ' "def" and "class".\n' - '\n' - 'str.islower()\n' - '\n' - ' Return true if all cased characters [4] in the string ' - 'are lowercase\n' - ' and there is at least one cased character, false ' - 'otherwise.\n' - '\n' - 'str.isnumeric()\n' - '\n' - ' Return true if all characters in the string are ' - 'numeric characters,\n' - ' and there is at least one character, false otherwise. ' - 'Numeric\n' - ' characters include digit characters, and all ' - 'characters that have\n' - ' the Unicode numeric value property, e.g. U+2155, ' - 'VULGAR FRACTION\n' - ' ONE FIFTH. Formally, numeric characters are those ' - 'with the\n' - ' property value Numeric_Type=Digit, ' - 'Numeric_Type=Decimal or\n' - ' Numeric_Type=Numeric.\n' - '\n' - 'str.isprintable()\n' - '\n' - ' Return true if all characters in the string are ' - 'printable or the\n' - ' string is empty, false otherwise. Nonprintable ' - 'characters are\n' - ' those characters defined in the Unicode character ' - 'database as\n' - ' "Other" or "Separator", excepting the ASCII space ' - '(0x20) which is\n' - ' considered printable. (Note that printable ' - 'characters in this\n' - ' context are those which should not be escaped when ' - '"repr()" is\n' - ' invoked on a string. It has no bearing on the ' - 'handling of strings\n' - ' written to "sys.stdout" or "sys.stderr".)\n' - '\n' - 'str.isspace()\n' - '\n' - ' Return true if there are only whitespace characters ' - 'in the string\n' - ' and there is at least one character, false ' - 'otherwise. Whitespace\n' - ' characters are those characters defined in the ' - 'Unicode character\n' - ' database as "Other" or "Separator" and those with ' - 'bidirectional\n' - ' property being one of "WS", "B", or "S".\n' - '\n' - 'str.istitle()\n' - '\n' - ' Return true if the string is a titlecased string and ' - 'there is at\n' - ' least one character, for example uppercase characters ' - 'may only\n' - ' follow uncased characters and lowercase characters ' - 'only cased ones.\n' - ' Return false otherwise.\n' - '\n' - 'str.isupper()\n' - '\n' - ' Return true if all cased characters [4] in the string ' - 'are uppercase\n' - ' and there is at least one cased character, false ' - 'otherwise.\n' - '\n' - 'str.join(iterable)\n' - '\n' - ' Return a string which is the concatenation of the ' - 'strings in the\n' - ' *iterable* *iterable*. A "TypeError" will be raised ' - 'if there are\n' - ' any non-string values in *iterable*, including ' - '"bytes" objects.\n' - ' The separator between elements is the string ' - 'providing this method.\n' - '\n' - 'str.ljust(width[, fillchar])\n' - '\n' - ' Return the string left justified in a string of ' - 'length *width*.\n' - ' Padding is done using the specified *fillchar* ' - '(default is an ASCII\n' - ' space). The original string is returned if *width* is ' - 'less than or\n' - ' equal to "len(s)".\n' - '\n' - 'str.lower()\n' - '\n' - ' Return a copy of the string with all the cased ' - 'characters [4]\n' - ' converted to lowercase.\n' - '\n' - ' The lowercasing algorithm used is described in ' - 'section 3.13 of the\n' - ' Unicode Standard.\n' - '\n' - 'str.lstrip([chars])\n' - '\n' - ' Return a copy of the string with leading characters ' - 'removed. The\n' - ' *chars* argument is a string specifying the set of ' - 'characters to be\n' - ' removed. If omitted or "None", the *chars* argument ' - 'defaults to\n' - ' removing whitespace. The *chars* argument is not a ' - 'prefix; rather,\n' - ' all combinations of its values are stripped:\n' - '\n' - " >>> ' spacious '.lstrip()\n" - " 'spacious '\n" - " >>> 'www.example.com'.lstrip('cmowz.')\n" - " 'example.com'\n" - '\n' - 'static str.maketrans(x[, y[, z]])\n' - '\n' - ' This static method returns a translation table usable ' - 'for\n' - ' "str.translate()".\n' - '\n' - ' If there is only one argument, it must be a ' - 'dictionary mapping\n' - ' Unicode ordinals (integers) or characters (strings of ' - 'length 1) to\n' - ' Unicode ordinals, strings (of arbitrary lengths) or ' - 'None.\n' - ' Character keys will then be converted to ordinals.\n' - '\n' - ' If there are two arguments, they must be strings of ' - 'equal length,\n' - ' and in the resulting dictionary, each character in x ' - 'will be mapped\n' - ' to the character at the same position in y. If there ' - 'is a third\n' - ' argument, it must be a string, whose characters will ' - 'be mapped to\n' - ' None in the result.\n' - '\n' - 'str.partition(sep)\n' - '\n' - ' Split the string at the first occurrence of *sep*, ' - 'and return a\n' - ' 3-tuple containing the part before the separator, the ' - 'separator\n' - ' itself, and the part after the separator. If the ' - 'separator is not\n' - ' found, return a 3-tuple containing the string itself, ' - 'followed by\n' - ' two empty strings.\n' - '\n' - 'str.replace(old, new[, count])\n' - '\n' - ' Return a copy of the string with all occurrences of ' - 'substring *old*\n' - ' replaced by *new*. If the optional argument *count* ' - 'is given, only\n' - ' the first *count* occurrences are replaced.\n' - '\n' - 'str.rfind(sub[, start[, end]])\n' - '\n' - ' Return the highest index in the string where ' - 'substring *sub* is\n' - ' found, such that *sub* is contained within ' - '"s[start:end]".\n' - ' Optional arguments *start* and *end* are interpreted ' - 'as in slice\n' - ' notation. Return "-1" on failure.\n' - '\n' - 'str.rindex(sub[, start[, end]])\n' - '\n' - ' Like "rfind()" but raises "ValueError" when the ' - 'substring *sub* is\n' - ' not found.\n' - '\n' - 'str.rjust(width[, fillchar])\n' - '\n' - ' Return the string right justified in a string of ' - 'length *width*.\n' - ' Padding is done using the specified *fillchar* ' - '(default is an ASCII\n' - ' space). The original string is returned if *width* is ' - 'less than or\n' - ' equal to "len(s)".\n' - '\n' - 'str.rpartition(sep)\n' - '\n' - ' Split the string at the last occurrence of *sep*, and ' - 'return a\n' - ' 3-tuple containing the part before the separator, the ' - 'separator\n' - ' itself, and the part after the separator. If the ' - 'separator is not\n' - ' found, return a 3-tuple containing two empty strings, ' - 'followed by\n' - ' the string itself.\n' - '\n' - 'str.rsplit(sep=None, maxsplit=-1)\n' - '\n' - ' Return a list of the words in the string, using *sep* ' - 'as the\n' - ' delimiter string. If *maxsplit* is given, at most ' - '*maxsplit* splits\n' - ' are done, the *rightmost* ones. If *sep* is not ' - 'specified or\n' - ' "None", any whitespace string is a separator. Except ' - 'for splitting\n' - ' from the right, "rsplit()" behaves like "split()" ' - 'which is\n' - ' described in detail below.\n' - '\n' - 'str.rstrip([chars])\n' - '\n' - ' Return a copy of the string with trailing characters ' - 'removed. The\n' - ' *chars* argument is a string specifying the set of ' - 'characters to be\n' - ' removed. If omitted or "None", the *chars* argument ' - 'defaults to\n' - ' removing whitespace. The *chars* argument is not a ' - 'suffix; rather,\n' - ' all combinations of its values are stripped:\n' - '\n' - " >>> ' spacious '.rstrip()\n" - " ' spacious'\n" - " >>> 'mississippi'.rstrip('ipz')\n" - " 'mississ'\n" - '\n' - 'str.split(sep=None, maxsplit=-1)\n' - '\n' - ' Return a list of the words in the string, using *sep* ' - 'as the\n' - ' delimiter string. If *maxsplit* is given, at most ' - '*maxsplit*\n' - ' splits are done (thus, the list will have at most ' - '"maxsplit+1"\n' - ' elements). If *maxsplit* is not specified or "-1", ' - 'then there is\n' - ' no limit on the number of splits (all possible splits ' - 'are made).\n' - '\n' - ' If *sep* is given, consecutive delimiters are not ' - 'grouped together\n' - ' and are deemed to delimit empty strings (for ' - 'example,\n' - ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', ' - '\'2\']"). The *sep* argument\n' - ' may consist of multiple characters (for example,\n' - ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', ' - '\'3\']"). Splitting an\n' - ' empty string with a specified separator returns ' - '"[\'\']".\n' - '\n' - ' For example:\n' - '\n' - " >>> '1,2,3'.split(',')\n" - " ['1', '2', '3']\n" - " >>> '1,2,3'.split(',', maxsplit=1)\n" - " ['1', '2,3']\n" - " >>> '1,2,,3,'.split(',')\n" - " ['1', '2', '', '3', '']\n" - '\n' - ' If *sep* is not specified or is "None", a different ' - 'splitting\n' - ' algorithm is applied: runs of consecutive whitespace ' - 'are regarded\n' - ' as a single separator, and the result will contain no ' - 'empty strings\n' - ' at the start or end if the string has leading or ' - 'trailing\n' - ' whitespace. Consequently, splitting an empty string ' - 'or a string\n' - ' consisting of just whitespace with a "None" separator ' - 'returns "[]".\n' - '\n' - ' For example:\n' - '\n' - " >>> '1 2 3'.split()\n" - " ['1', '2', '3']\n" - " >>> '1 2 3'.split(maxsplit=1)\n" - " ['1', '2 3']\n" - " >>> ' 1 2 3 '.split()\n" - " ['1', '2', '3']\n" - '\n' - 'str.splitlines([keepends])\n' - '\n' - ' Return a list of the lines in the string, breaking at ' - 'line\n' - ' boundaries. Line breaks are not included in the ' - 'resulting list\n' - ' unless *keepends* is given and true.\n' - '\n' - ' This method splits on the following line boundaries. ' - 'In\n' - ' particular, the boundaries are a superset of ' - '*universal newlines*.\n' - '\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | Representation | ' - 'Description |\n' - ' ' - '+=========================+===============================+\n' - ' | "\\n" | Line ' - 'Feed |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\r" | Carriage ' - 'Return |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\r\\n" | Carriage Return + Line ' - 'Feed |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\v" or "\\x0b" | Line ' - 'Tabulation |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\f" or "\\x0c" | Form ' - 'Feed |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\x1c" | File ' - 'Separator |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\x1d" | Group ' - 'Separator |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\x1e" | Record ' - 'Separator |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\x85" | Next Line (C1 Control ' - 'Code) |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\u2028" | Line ' - 'Separator |\n' - ' ' - '+-------------------------+-------------------------------+\n' - ' | "\\u2029" | Paragraph ' - 'Separator |\n' - ' ' - '+-------------------------+-------------------------------+\n' - '\n' - ' Changed in version 3.2: "\\v" and "\\f" added to list ' - 'of line\n' - ' boundaries.\n' - '\n' - ' For example:\n' - '\n' - " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" - " ['ab c', '', 'de fg', 'kl']\n" - " >>> 'ab c\\n\\nde " - "fg\\rkl\\r\\n'.splitlines(keepends=True)\n" - " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" - '\n' - ' Unlike "split()" when a delimiter string *sep* is ' - 'given, this\n' - ' method returns an empty list for the empty string, ' - 'and a terminal\n' - ' line break does not result in an extra line:\n' - '\n' - ' >>> "".splitlines()\n' - ' []\n' - ' >>> "One line\\n".splitlines()\n' - " ['One line']\n" - '\n' - ' For comparison, "split(\'\\n\')" gives:\n' - '\n' - " >>> ''.split('\\n')\n" - " ['']\n" - " >>> 'Two lines\\n'.split('\\n')\n" - " ['Two lines', '']\n" - '\n' - 'str.startswith(prefix[, start[, end]])\n' - '\n' - ' Return "True" if string starts with the *prefix*, ' - 'otherwise return\n' - ' "False". *prefix* can also be a tuple of prefixes to ' - 'look for.\n' - ' With optional *start*, test string beginning at that ' - 'position.\n' - ' With optional *end*, stop comparing string at that ' - 'position.\n' - '\n' - 'str.strip([chars])\n' - '\n' - ' Return a copy of the string with the leading and ' - 'trailing\n' - ' characters removed. The *chars* argument is a string ' - 'specifying the\n' - ' set of characters to be removed. If omitted or ' - '"None", the *chars*\n' - ' argument defaults to removing whitespace. The *chars* ' - 'argument is\n' - ' not a prefix or suffix; rather, all combinations of ' - 'its values are\n' - ' stripped:\n' - '\n' - " >>> ' spacious '.strip()\n" - " 'spacious'\n" - " >>> 'www.example.com'.strip('cmowz.')\n" - " 'example'\n" - '\n' - 'str.swapcase()\n' - '\n' - ' Return a copy of the string with uppercase characters ' - 'converted to\n' - ' lowercase and vice versa. Note that it is not ' - 'necessarily true that\n' - ' "s.swapcase().swapcase() == s".\n' - '\n' - 'str.title()\n' - '\n' - ' Return a titlecased version of the string where words ' - 'start with an\n' - ' uppercase character and the remaining characters are ' - 'lowercase.\n' - '\n' - ' For example:\n' - '\n' - " >>> 'Hello world'.title()\n" - " 'Hello World'\n" - '\n' - ' The algorithm uses a simple language-independent ' - 'definition of a\n' - ' word as groups of consecutive letters. The ' - 'definition works in\n' - ' many contexts but it means that apostrophes in ' - 'contractions and\n' - ' possessives form word boundaries, which may not be ' - 'the desired\n' - ' result:\n' - '\n' - ' >>> "they\'re bill\'s friends from the ' - 'UK".title()\n' - ' "They\'Re Bill\'S Friends From The Uk"\n' - '\n' - ' A workaround for apostrophes can be constructed using ' - 'regular\n' - ' expressions:\n' - '\n' - ' >>> import re\n' - ' >>> def titlecase(s):\n' - ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' - ' ... lambda mo: ' - 'mo.group(0)[0].upper() +\n' - ' ... ' - 'mo.group(0)[1:].lower(),\n' - ' ... s)\n' - ' ...\n' - ' >>> titlecase("they\'re bill\'s friends.")\n' - ' "They\'re Bill\'s Friends."\n' - '\n' - 'str.translate(table)\n' - '\n' - ' Return a copy of the string in which each character ' - 'has been mapped\n' - ' through the given translation table. The table must ' - 'be an object\n' - ' that implements indexing via "__getitem__()", ' - 'typically a *mapping*\n' - ' or *sequence*. When indexed by a Unicode ordinal (an ' - 'integer), the\n' - ' table object can do any of the following: return a ' - 'Unicode ordinal\n' - ' or a string, to map the character to one or more ' - 'other characters;\n' - ' return "None", to delete the character from the ' - 'return string; or\n' - ' raise a "LookupError" exception, to map the character ' - 'to itself.\n' - '\n' - ' You can use "str.maketrans()" to create a translation ' - 'map from\n' - ' character-to-character mappings in different ' - 'formats.\n' - '\n' - ' See also the "codecs" module for a more flexible ' - 'approach to custom\n' - ' character mappings.\n' - '\n' - 'str.upper()\n' - '\n' - ' Return a copy of the string with all the cased ' - 'characters [4]\n' - ' converted to uppercase. Note that ' - '"str.upper().isupper()" might be\n' - ' "False" if "s" contains uncased characters or if the ' - 'Unicode\n' - ' category of the resulting character(s) is not "Lu" ' - '(Letter,\n' - ' uppercase), but e.g. "Lt" (Letter, titlecase).\n' - '\n' - ' The uppercasing algorithm used is described in ' - 'section 3.13 of the\n' - ' Unicode Standard.\n' - '\n' - 'str.zfill(width)\n' - '\n' - ' Return a copy of the string left filled with ASCII ' - '"\'0\'" digits to\n' - ' make a string of length *width*. A leading sign ' - 'prefix\n' - ' ("\'+\'"/"\'-\'") is handled by inserting the padding ' - '*after* the sign\n' - ' character rather than before. The original string is ' - 'returned if\n' - ' *width* is less than or equal to "len(s)".\n' - '\n' - ' For example:\n' - '\n' - ' >>> "42".zfill(5)\n' - " '00042'\n" - ' >>> "-42".zfill(5)\n' - " '-0042'\n", - 'strings': '\n' - 'String and Bytes literals\n' - '*************************\n' - '\n' - 'String literals are described by the following lexical ' - 'definitions:\n' - '\n' - ' stringliteral ::= [stringprefix](shortstring | ' - 'longstring)\n' - ' stringprefix ::= "r" | "u" | "R" | "U"\n' - ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' ' - 'shortstringitem* \'"\'\n' - ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | ' - '\'"""\' longstringitem* \'"""\'\n' - ' shortstringitem ::= shortstringchar | stringescapeseq\n' - ' longstringitem ::= longstringchar | stringescapeseq\n' - ' shortstringchar ::= \n' - ' longstringchar ::= \n' - ' stringescapeseq ::= "\\" \n' - '\n' - ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n' - ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | ' - '"rb" | "rB" | "Rb" | "RB"\n' - ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' ' - 'shortbytesitem* \'"\'\n' - ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | ' - '\'"""\' longbytesitem* \'"""\'\n' - ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n' - ' longbytesitem ::= longbyteschar | bytesescapeseq\n' - ' shortbyteschar ::= \n' - ' longbyteschar ::= \n' - ' bytesescapeseq ::= "\\" \n' - '\n' - 'One syntactic restriction not indicated by these productions is ' - 'that\n' - 'whitespace is not allowed between the "stringprefix" or ' - '"bytesprefix"\n' - 'and the rest of the literal. The source character set is ' - 'defined by\n' - 'the encoding declaration; it is UTF-8 if no encoding ' - 'declaration is\n' - 'given in the source file; see section *Encoding declarations*.\n' - '\n' - 'In plain English: Both types of literals can be enclosed in ' - 'matching\n' - 'single quotes ("\'") or double quotes ("""). They can also be ' - 'enclosed\n' - 'in matching groups of three single or double quotes (these are\n' - 'generally referred to as *triple-quoted strings*). The ' - 'backslash\n' - '("\\") character is used to escape characters that otherwise ' - 'have a\n' - 'special meaning, such as newline, backslash itself, or the ' - 'quote\n' - 'character.\n' - '\n' - 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; ' - 'they produce\n' - 'an instance of the "bytes" type instead of the "str" type. ' - 'They may\n' - 'only contain ASCII characters; bytes with a numeric value of ' - '128 or\n' - 'greater must be expressed with escapes.\n' - '\n' - 'As of Python 3.3 it is possible again to prefix string literals ' - 'with a\n' - '"u" prefix to simplify maintenance of dual 2.x and 3.x ' - 'codebases.\n' - '\n' - 'Both string and bytes literals may optionally be prefixed with ' - 'a\n' - 'letter "\'r\'" or "\'R\'"; such strings are called *raw ' - 'strings* and treat\n' - 'backslashes as literal characters. As a result, in string ' - 'literals,\n' - '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated ' - 'specially.\n' - "Given that Python 2.x's raw unicode literals behave differently " - 'than\n' - 'Python 3.x\'s the "\'ur\'" syntax is not supported.\n' - '\n' - 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals ' - 'has been\n' - 'added as a synonym of "\'br\'".\n' - '\n' - 'New in version 3.3: Support for the unicode legacy literal\n' - '("u\'value\'") was reintroduced to simplify the maintenance of ' - 'dual\n' - 'Python 2.x and 3.x codebases. See **PEP 414** for more ' - 'information.\n' - '\n' - 'In triple-quoted literals, unescaped newlines and quotes are ' - 'allowed\n' - '(and are retained), except that three unescaped quotes in a ' - 'row\n' - 'terminate the literal. (A "quote" is the character used to ' - 'open the\n' - 'literal, i.e. either "\'" or """.)\n' - '\n' - 'Unless an "\'r\'" or "\'R\'" prefix is present, escape ' - 'sequences in string\n' - 'and bytes literals are interpreted according to rules similar ' - 'to those\n' - 'used by Standard C. The recognized escape sequences are:\n' - '\n' - '+-------------------+-----------------------------------+---------+\n' - '| Escape Sequence | Meaning | ' - 'Notes |\n' - '+===================+===================================+=========+\n' - '| "\\newline" | Backslash and newline ignored ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\\\" | Backslash ("\\") ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\\'" | Single quote ("\'") ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\"" | Double quote (""") ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\a" | ASCII Bell (BEL) ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\b" | ASCII Backspace (BS) ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\f" | ASCII Formfeed (FF) ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\n" | ASCII Linefeed (LF) ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\r" | ASCII Carriage Return (CR) ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\t" | ASCII Horizontal Tab (TAB) ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\v" | ASCII Vertical Tab (VT) ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\ooo" | Character with octal value *ooo* | ' - '(1,3) |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\xhh" | Character with hex value *hh* | ' - '(2,3) |\n' - '+-------------------+-----------------------------------+---------+\n' - '\n' - 'Escape sequences only recognized in string literals are:\n' - '\n' - '+-------------------+-----------------------------------+---------+\n' - '| Escape Sequence | Meaning | ' - 'Notes |\n' - '+===================+===================================+=========+\n' - '| "\\N{name}" | Character named *name* in the | ' - '(4) |\n' - '| | Unicode database ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\uxxxx" | Character with 16-bit hex value | ' - '(5) |\n' - '| | *xxxx* ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' - '(6) |\n' - '| | *xxxxxxxx* ' - '| |\n' - '+-------------------+-----------------------------------+---------+\n' - '\n' - 'Notes:\n' - '\n' - '1. As in Standard C, up to three octal digits are accepted.\n' - '\n' - '2. Unlike in Standard C, exactly two hex digits are required.\n' - '\n' - '3. In a bytes literal, hexadecimal and octal escapes denote ' - 'the\n' - ' byte with the given value. In a string literal, these ' - 'escapes\n' - ' denote a Unicode character with the given value.\n' - '\n' - '4. Changed in version 3.3: Support for name aliases [1] has ' - 'been\n' - ' added.\n' - '\n' - '5. Individual code units which form parts of a surrogate pair ' - 'can\n' - ' be encoded using this escape sequence. Exactly four hex ' - 'digits are\n' - ' required.\n' - '\n' - '6. Any Unicode character can be encoded this way. Exactly ' - 'eight\n' - ' hex digits are required.\n' - '\n' - 'Unlike Standard C, all unrecognized escape sequences are left ' - 'in the\n' - 'string unchanged, i.e., *the backslash is left in the result*. ' - '(This\n' - 'behavior is useful when debugging: if an escape sequence is ' - 'mistyped,\n' - 'the resulting output is more easily recognized as broken.) It ' - 'is also\n' - 'important to note that the escape sequences only recognized in ' - 'string\n' - 'literals fall into the category of unrecognized escapes for ' - 'bytes\n' - 'literals.\n' - '\n' - 'Even in a raw literal, quotes can be escaped with a backslash, ' - 'but the\n' - 'backslash remains in the result; for example, "r"\\""" is a ' - 'valid\n' - 'string literal consisting of two characters: a backslash and a ' - 'double\n' - 'quote; "r"\\"" is not a valid string literal (even a raw string ' - 'cannot\n' - 'end in an odd number of backslashes). Specifically, *a raw ' - 'literal\n' - 'cannot end in a single backslash* (since the backslash would ' - 'escape\n' - 'the following quote character). Note also that a single ' - 'backslash\n' - 'followed by a newline is interpreted as those two characters as ' - 'part\n' - 'of the literal, *not* as a line continuation.\n', - 'subscriptions': '\n' - 'Subscriptions\n' - '*************\n' - '\n' - 'A subscription selects an item of a sequence (string, ' - 'tuple or list)\n' - 'or mapping (dictionary) object:\n' - '\n' - ' subscription ::= primary "[" expression_list "]"\n' - '\n' - 'The primary must evaluate to an object that supports ' - 'subscription\n' - '(lists or dictionaries for example). User-defined ' - 'objects can support\n' - 'subscription by defining a "__getitem__()" method.\n' - '\n' - 'For built-in objects, there are two types of objects that ' - 'support\n' - 'subscription:\n' - '\n' - 'If the primary is a mapping, the expression list must ' - 'evaluate to an\n' - 'object whose value is one of the keys of the mapping, and ' - 'the\n' - 'subscription selects the value in the mapping that ' - 'corresponds to that\n' - 'key. (The expression list is a tuple except if it has ' - 'exactly one\n' - 'item.)\n' - '\n' - 'If the primary is a sequence, the expression (list) must ' - 'evaluate to\n' - 'an integer or a slice (as discussed in the following ' - 'section).\n' - '\n' - 'The formal syntax makes no special provision for negative ' - 'indices in\n' - 'sequences; however, built-in sequences all provide a ' - '"__getitem__()"\n' - 'method that interprets negative indices by adding the ' - 'length of the\n' - 'sequence to the index (so that "x[-1]" selects the last ' - 'item of "x").\n' - 'The resulting value must be a nonnegative integer less ' - 'than the number\n' - 'of items in the sequence, and the subscription selects ' - 'the item whose\n' - 'index is that value (counting from zero). Since the ' - 'support for\n' - "negative indices and slicing occurs in the object's " - '"__getitem__()"\n' - 'method, subclasses overriding this method will need to ' - 'explicitly add\n' - 'that support.\n' - '\n' - "A string's items are characters. A character is not a " - 'separate data\n' - 'type but a string of exactly one character.\n', - 'truth': '\n' - 'Truth Value Testing\n' - '*******************\n' - '\n' - 'Any object can be tested for truth value, for use in an "if" or\n' - '"while" condition or as operand of the Boolean operations below. ' - 'The\n' - 'following values are considered false:\n' - '\n' - '* "None"\n' - '\n' - '* "False"\n' - '\n' - '* zero of any numeric type, for example, "0", "0.0", "0j".\n' - '\n' - '* any empty sequence, for example, "\'\'", "()", "[]".\n' - '\n' - '* any empty mapping, for example, "{}".\n' - '\n' - '* instances of user-defined classes, if the class defines a\n' - ' "__bool__()" or "__len__()" method, when that method returns ' - 'the\n' - ' integer zero or "bool" value "False". [1]\n' - '\n' - 'All other values are considered true --- so objects of many types ' - 'are\n' - 'always true.\n' - '\n' - 'Operations and built-in functions that have a Boolean result ' - 'always\n' - 'return "0" or "False" for false and "1" or "True" for true, ' - 'unless\n' - 'otherwise stated. (Important exception: the Boolean operations ' - '"or"\n' - 'and "and" always return one of their operands.)\n', - 'try': '\n' - 'The "try" statement\n' - '*******************\n' - '\n' - 'The "try" statement specifies exception handlers and/or cleanup ' - 'code\n' - 'for a group of statements:\n' - '\n' - ' try_stmt ::= try1_stmt | try2_stmt\n' - ' try1_stmt ::= "try" ":" suite\n' - ' ("except" [expression ["as" identifier]] ":" ' - 'suite)+\n' - ' ["else" ":" suite]\n' - ' ["finally" ":" suite]\n' - ' try2_stmt ::= "try" ":" suite\n' - ' "finally" ":" suite\n' - '\n' - 'The "except" clause(s) specify one or more exception handlers. When ' - 'no\n' - 'exception occurs in the "try" clause, no exception handler is\n' - 'executed. When an exception occurs in the "try" suite, a search for ' - 'an\n' - 'exception handler is started. This search inspects the except ' - 'clauses\n' - 'in turn until one is found that matches the exception. An ' - 'expression-\n' - 'less except clause, if present, must be last; it matches any\n' - 'exception. For an except clause with an expression, that ' - 'expression\n' - 'is evaluated, and the clause matches the exception if the ' - 'resulting\n' - 'object is "compatible" with the exception. An object is ' - 'compatible\n' - 'with an exception if it is the class or a base class of the ' - 'exception\n' - 'object or a tuple containing an item compatible with the ' - 'exception.\n' - '\n' - 'If no except clause matches the exception, the search for an ' - 'exception\n' - 'handler continues in the surrounding code and on the invocation ' - 'stack.\n' - '[1]\n' - '\n' - 'If the evaluation of an expression in the header of an except ' - 'clause\n' - 'raises an exception, the original search for a handler is canceled ' - 'and\n' - 'a search starts for the new exception in the surrounding code and ' - 'on\n' - 'the call stack (it is treated as if the entire "try" statement ' - 'raised\n' - 'the exception).\n' - '\n' - 'When a matching except clause is found, the exception is assigned ' - 'to\n' - 'the target specified after the "as" keyword in that except clause, ' - 'if\n' - "present, and the except clause's suite is executed. All except\n" - 'clauses must have an executable block. When the end of this block ' - 'is\n' - 'reached, execution continues normally after the entire try ' - 'statement.\n' - '(This means that if two nested handlers exist for the same ' - 'exception,\n' - 'and the exception occurs in the try clause of the inner handler, ' - 'the\n' - 'outer handler will not handle the exception.)\n' - '\n' - 'When an exception has been assigned using "as target", it is ' - 'cleared\n' - 'at the end of the except clause. This is as if\n' - '\n' - ' except E as N:\n' - ' foo\n' - '\n' - 'was translated to\n' - '\n' - ' except E as N:\n' - ' try:\n' - ' foo\n' - ' finally:\n' - ' del N\n' - '\n' - 'This means the exception must be assigned to a different name to ' - 'be\n' - 'able to refer to it after the except clause. Exceptions are ' - 'cleared\n' - 'because with the traceback attached to them, they form a reference\n' - 'cycle with the stack frame, keeping all locals in that frame alive\n' - 'until the next garbage collection occurs.\n' - '\n' - "Before an except clause's suite is executed, details about the\n" - 'exception are stored in the "sys" module and can be accessed via\n' - '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' - 'the\n' - 'exception class, the exception instance and a traceback object ' - '(see\n' - 'section *The standard type hierarchy*) identifying the point in ' - 'the\n' - 'program where the exception occurred. "sys.exc_info()" values are\n' - 'restored to their previous values (before the call) when returning\n' - 'from a function that handled an exception.\n' - '\n' - 'The optional "else" clause is executed if and when control flows ' - 'off\n' - 'the end of the "try" clause. [2] Exceptions in the "else" clause ' - 'are\n' - 'not handled by the preceding "except" clauses.\n' - '\n' - 'If "finally" is present, it specifies a \'cleanup\' handler. The ' - '"try"\n' - 'clause is executed, including any "except" and "else" clauses. If ' - 'an\n' - 'exception occurs in any of the clauses and is not handled, the\n' - 'exception is temporarily saved. The "finally" clause is executed. ' - 'If\n' - 'there is a saved exception it is re-raised at the end of the ' - '"finally"\n' - 'clause. If the "finally" clause raises another exception, the ' - 'saved\n' - 'exception is set as the context of the new exception. If the ' - '"finally"\n' - 'clause executes a "return" or "break" statement, the saved ' - 'exception\n' - 'is discarded:\n' - '\n' - ' >>> def f():\n' - ' ... try:\n' - ' ... 1/0\n' - ' ... finally:\n' - ' ... return 42\n' - ' ...\n' - ' >>> f()\n' - ' 42\n' - '\n' - 'The exception information is not available to the program during\n' - 'execution of the "finally" clause.\n' - '\n' - 'When a "return", "break" or "continue" statement is executed in ' - 'the\n' - '"try" suite of a "try"..."finally" statement, the "finally" clause ' - 'is\n' - 'also executed \'on the way out.\' A "continue" statement is illegal ' - 'in\n' - 'the "finally" clause. (The reason is a problem with the current\n' - 'implementation --- this restriction may be lifted in the future).\n' - '\n' - 'The return value of a function is determined by the last "return"\n' - 'statement executed. Since the "finally" clause always executes, a\n' - '"return" statement executed in the "finally" clause will always be ' - 'the\n' - 'last one executed:\n' - '\n' - ' >>> def foo():\n' - ' ... try:\n' - " ... return 'try'\n" - ' ... finally:\n' - " ... return 'finally'\n" - ' ...\n' - ' >>> foo()\n' - " 'finally'\n" - '\n' - 'Additional information on exceptions can be found in section\n' - '*Exceptions*, and information on using the "raise" statement to\n' - 'generate exceptions may be found in section *The raise statement*.\n', - 'types': '\n' - 'The standard type hierarchy\n' - '***************************\n' - '\n' - 'Below is a list of the types that are built into Python. ' - 'Extension\n' - 'modules (written in C, Java, or other languages, depending on ' - 'the\n' - 'implementation) can define additional types. Future versions of\n' - 'Python may add types to the type hierarchy (e.g., rational ' - 'numbers,\n' - 'efficiently stored arrays of integers, etc.), although such ' - 'additions\n' - 'will often be provided via the standard library instead.\n' - '\n' - 'Some of the type descriptions below contain a paragraph listing\n' - "'special attributes.' These are attributes that provide access " - 'to the\n' - 'implementation and are not intended for general use. Their ' - 'definition\n' - 'may change in the future.\n' - '\n' - 'None\n' - ' This type has a single value. There is a single object with ' - 'this\n' - ' value. This object is accessed through the built-in name ' - '"None". It\n' - ' is used to signify the absence of a value in many situations, ' - 'e.g.,\n' - " it is returned from functions that don't explicitly return\n" - ' anything. Its truth value is false.\n' - '\n' - 'NotImplemented\n' - ' This type has a single value. There is a single object with ' - 'this\n' - ' value. This object is accessed through the built-in name\n' - ' "NotImplemented". Numeric methods and rich comparison methods\n' - ' should return this value if they do not implement the ' - 'operation for\n' - ' the operands provided. (The interpreter will then try the\n' - ' reflected operation, or some other fallback, depending on the\n' - ' operator.) Its truth value is true.\n' - '\n' - ' See *Implementing the arithmetic operations* for more ' - 'details.\n' - '\n' - 'Ellipsis\n' - ' This type has a single value. There is a single object with ' - 'this\n' - ' value. This object is accessed through the literal "..." or ' - 'the\n' - ' built-in name "Ellipsis". Its truth value is true.\n' - '\n' - '"numbers.Number"\n' - ' These are created by numeric literals and returned as results ' - 'by\n' - ' arithmetic operators and arithmetic built-in functions. ' - 'Numeric\n' - ' objects are immutable; once created their value never ' - 'changes.\n' - ' Python numbers are of course strongly related to mathematical\n' - ' numbers, but subject to the limitations of numerical ' - 'representation\n' - ' in computers.\n' - '\n' - ' Python distinguishes between integers, floating point numbers, ' - 'and\n' - ' complex numbers:\n' - '\n' - ' "numbers.Integral"\n' - ' These represent elements from the mathematical set of ' - 'integers\n' - ' (positive and negative).\n' - '\n' - ' There are two types of integers:\n' - '\n' - ' Integers ("int")\n' - '\n' - ' These represent numbers in an unlimited range, subject ' - 'to\n' - ' available (virtual) memory only. For the purpose of ' - 'shift\n' - ' and mask operations, a binary representation is assumed, ' - 'and\n' - " negative numbers are represented in a variant of 2's\n" - ' complement which gives the illusion of an infinite ' - 'string of\n' - ' sign bits extending to the left.\n' - '\n' - ' Booleans ("bool")\n' - ' These represent the truth values False and True. The ' - 'two\n' - ' objects representing the values "False" and "True" are ' - 'the\n' - ' only Boolean objects. The Boolean type is a subtype of ' - 'the\n' - ' integer type, and Boolean values behave like the values ' - '0 and\n' - ' 1, respectively, in almost all contexts, the exception ' - 'being\n' - ' that when converted to a string, the strings ""False"" ' - 'or\n' - ' ""True"" are returned, respectively.\n' - '\n' - ' The rules for integer representation are intended to give ' - 'the\n' - ' most meaningful interpretation of shift and mask ' - 'operations\n' - ' involving negative integers.\n' - '\n' - ' "numbers.Real" ("float")\n' - ' These represent machine-level double precision floating ' - 'point\n' - ' numbers. You are at the mercy of the underlying machine\n' - ' architecture (and C or Java implementation) for the ' - 'accepted\n' - ' range and handling of overflow. Python does not support ' - 'single-\n' - ' precision floating point numbers; the savings in processor ' - 'and\n' - ' memory usage that are usually the reason for using these ' - 'are\n' - ' dwarfed by the overhead of using objects in Python, so ' - 'there is\n' - ' no reason to complicate the language with two kinds of ' - 'floating\n' - ' point numbers.\n' - '\n' - ' "numbers.Complex" ("complex")\n' - ' These represent complex numbers as a pair of machine-level\n' - ' double precision floating point numbers. The same caveats ' - 'apply\n' - ' as for floating point numbers. The real and imaginary parts ' - 'of a\n' - ' complex number "z" can be retrieved through the read-only\n' - ' attributes "z.real" and "z.imag".\n' - '\n' - 'Sequences\n' - ' These represent finite ordered sets indexed by non-negative\n' - ' numbers. The built-in function "len()" returns the number of ' - 'items\n' - ' of a sequence. When the length of a sequence is *n*, the index ' - 'set\n' - ' contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence ' - '*a* is\n' - ' selected by "a[i]".\n' - '\n' - ' Sequences also support slicing: "a[i:j]" selects all items ' - 'with\n' - ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n' - ' expression, a slice is a sequence of the same type. This ' - 'implies\n' - ' that the index set is renumbered so that it starts at 0.\n' - '\n' - ' Some sequences also support "extended slicing" with a third ' - '"step"\n' - ' parameter: "a[i:j:k]" selects all items of *a* with index *x* ' - 'where\n' - ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n' - '\n' - ' Sequences are distinguished according to their mutability:\n' - '\n' - ' Immutable sequences\n' - ' An object of an immutable sequence type cannot change once ' - 'it is\n' - ' created. (If the object contains references to other ' - 'objects,\n' - ' these other objects may be mutable and may be changed; ' - 'however,\n' - ' the collection of objects directly referenced by an ' - 'immutable\n' - ' object cannot change.)\n' - '\n' - ' The following types are immutable sequences:\n' - '\n' - ' Strings\n' - ' A string is a sequence of values that represent Unicode ' - 'code\n' - ' points. All the code points in the range "U+0000 - ' - 'U+10FFFF"\n' - " can be represented in a string. Python doesn't have a " - '"char"\n' - ' type; instead, every code point in the string is ' - 'represented\n' - ' as a string object with length "1". The built-in ' - 'function\n' - ' "ord()" converts a code point from its string form to ' - 'an\n' - ' integer in the range "0 - 10FFFF"; "chr()" converts an\n' - ' integer in the range "0 - 10FFFF" to the corresponding ' - 'length\n' - ' "1" string object. "str.encode()" can be used to convert ' - 'a\n' - ' "str" to "bytes" using the given text encoding, and\n' - ' "bytes.decode()" can be used to achieve the opposite.\n' - '\n' - ' Tuples\n' - ' The items of a tuple are arbitrary Python objects. ' - 'Tuples of\n' - ' two or more items are formed by comma-separated lists ' - 'of\n' - " expressions. A tuple of one item (a 'singleton') can " - 'be\n' - ' formed by affixing a comma to an expression (an ' - 'expression by\n' - ' itself does not create a tuple, since parentheses must ' - 'be\n' - ' usable for grouping of expressions). An empty tuple can ' - 'be\n' - ' formed by an empty pair of parentheses.\n' - '\n' - ' Bytes\n' - ' A bytes object is an immutable array. The items are ' - '8-bit\n' - ' bytes, represented by integers in the range 0 <= x < ' - '256.\n' - ' Bytes literals (like "b\'abc\'") and the built-in ' - 'function\n' - ' "bytes()" can be used to construct bytes objects. ' - 'Also,\n' - ' bytes objects can be decoded to strings via the ' - '"decode()"\n' - ' method.\n' - '\n' - ' Mutable sequences\n' - ' Mutable sequences can be changed after they are created. ' - 'The\n' - ' subscription and slicing notations can be used as the ' - 'target of\n' - ' assignment and "del" (delete) statements.\n' - '\n' - ' There are currently two intrinsic mutable sequence types:\n' - '\n' - ' Lists\n' - ' The items of a list are arbitrary Python objects. Lists ' - 'are\n' - ' formed by placing a comma-separated list of expressions ' - 'in\n' - ' square brackets. (Note that there are no special cases ' - 'needed\n' - ' to form lists of length 0 or 1.)\n' - '\n' - ' Byte Arrays\n' - ' A bytearray object is a mutable array. They are created ' - 'by\n' - ' the built-in "bytearray()" constructor. Aside from ' - 'being\n' - ' mutable (and hence unhashable), byte arrays otherwise ' - 'provide\n' - ' the same interface and functionality as immutable bytes\n' - ' objects.\n' - '\n' - ' The extension module "array" provides an additional example ' - 'of a\n' - ' mutable sequence type, as does the "collections" module.\n' - '\n' - 'Set types\n' - ' These represent unordered, finite sets of unique, immutable\n' - ' objects. As such, they cannot be indexed by any subscript. ' - 'However,\n' - ' they can be iterated over, and the built-in function "len()"\n' - ' returns the number of items in a set. Common uses for sets are ' - 'fast\n' - ' membership testing, removing duplicates from a sequence, and\n' - ' computing mathematical operations such as intersection, ' - 'union,\n' - ' difference, and symmetric difference.\n' - '\n' - ' For set elements, the same immutability rules apply as for\n' - ' dictionary keys. Note that numeric types obey the normal rules ' - 'for\n' - ' numeric comparison: if two numbers compare equal (e.g., "1" ' - 'and\n' - ' "1.0"), only one of them can be contained in a set.\n' - '\n' - ' There are currently two intrinsic set types:\n' - '\n' - ' Sets\n' - ' These represent a mutable set. They are created by the ' - 'built-in\n' - ' "set()" constructor and can be modified afterwards by ' - 'several\n' - ' methods, such as "add()".\n' - '\n' - ' Frozen sets\n' - ' These represent an immutable set. They are created by the\n' - ' built-in "frozenset()" constructor. As a frozenset is ' - 'immutable\n' - ' and *hashable*, it can be used again as an element of ' - 'another\n' - ' set, or as a dictionary key.\n' - '\n' - 'Mappings\n' - ' These represent finite sets of objects indexed by arbitrary ' - 'index\n' - ' sets. The subscript notation "a[k]" selects the item indexed ' - 'by "k"\n' - ' from the mapping "a"; this can be used in expressions and as ' - 'the\n' - ' target of assignments or "del" statements. The built-in ' - 'function\n' - ' "len()" returns the number of items in a mapping.\n' - '\n' - ' There is currently a single intrinsic mapping type:\n' - '\n' - ' Dictionaries\n' - ' These represent finite sets of objects indexed by nearly\n' - ' arbitrary values. The only types of values not acceptable ' - 'as\n' - ' keys are values containing lists or dictionaries or other\n' - ' mutable types that are compared by value rather than by ' - 'object\n' - ' identity, the reason being that the efficient ' - 'implementation of\n' - " dictionaries requires a key's hash value to remain " - 'constant.\n' - ' Numeric types used for keys obey the normal rules for ' - 'numeric\n' - ' comparison: if two numbers compare equal (e.g., "1" and ' - '"1.0")\n' - ' then they can be used interchangeably to index the same\n' - ' dictionary entry.\n' - '\n' - ' Dictionaries are mutable; they can be created by the ' - '"{...}"\n' - ' notation (see section *Dictionary displays*).\n' - '\n' - ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n' - ' additional examples of mapping types, as does the ' - '"collections"\n' - ' module.\n' - '\n' - 'Callable types\n' - ' These are the types to which the function call operation (see\n' - ' section *Calls*) can be applied:\n' - '\n' - ' User-defined functions\n' - ' A user-defined function object is created by a function\n' - ' definition (see section *Function definitions*). It should ' - 'be\n' - ' called with an argument list containing the same number of ' - 'items\n' - " as the function's formal parameter list.\n" - '\n' - ' Special attributes:\n' - '\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | Attribute | ' - 'Meaning | |\n' - ' ' - '+===========================+=================================+=============+\n' - ' | "__doc__" | The function\'s ' - 'documentation | Writable |\n' - ' | | string, or "None" ' - 'if | |\n' - ' | | unavailable; not inherited ' - 'by | |\n' - ' | | ' - 'subclasses | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__name__" | The function\'s ' - 'name | Writable |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__qualname__" | The function\'s *qualified ' - 'name* | Writable |\n' - ' | | New in version ' - '3.3. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__module__" | The name of the module ' - 'the | Writable |\n' - ' | | function was defined in, ' - 'or | |\n' - ' | | "None" if ' - 'unavailable. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__defaults__" | A tuple containing ' - 'default | Writable |\n' - ' | | argument values for ' - 'those | |\n' - ' | | arguments that have ' - 'defaults, | |\n' - ' | | or "None" if no arguments ' - 'have | |\n' - ' | | a default ' - 'value | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__code__" | The code object ' - 'representing | Writable |\n' - ' | | the compiled function ' - 'body. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__globals__" | A reference to the ' - 'dictionary | Read-only |\n' - ' | | that holds the ' - "function's | |\n" - ' | | global variables --- the ' - 'global | |\n' - ' | | namespace of the module ' - 'in | |\n' - ' | | which the function was ' - 'defined. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__dict__" | The namespace ' - 'supporting | Writable |\n' - ' | | arbitrary function ' - 'attributes. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__closure__" | "None" or a tuple of cells ' - 'that | Read-only |\n' - ' | | contain bindings for ' - 'the | |\n' - " | | function's free " - 'variables. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__annotations__" | A dict containing ' - 'annotations | Writable |\n' - ' | | of parameters. The keys of ' - 'the | |\n' - ' | | dict are the parameter ' - 'names, | |\n' - ' | | and "\'return\'" for the ' - 'return | |\n' - ' | | annotation, if ' - 'provided. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__kwdefaults__" | A dict containing defaults ' - 'for | Writable |\n' - ' | | keyword-only ' - 'parameters. | |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - '\n' - ' Most of the attributes labelled "Writable" check the type ' - 'of the\n' - ' assigned value.\n' - '\n' - ' Function objects also support getting and setting ' - 'arbitrary\n' - ' attributes, which can be used, for example, to attach ' - 'metadata\n' - ' to functions. Regular attribute dot-notation is used to ' - 'get and\n' - ' set such attributes. *Note that the current implementation ' - 'only\n' - ' supports function attributes on user-defined functions. ' - 'Function\n' - ' attributes on built-in functions may be supported in the\n' - ' future.*\n' - '\n' - " Additional information about a function's definition can " - 'be\n' - ' retrieved from its code object; see the description of ' - 'internal\n' - ' types below.\n' - '\n' - ' Instance methods\n' - ' An instance method object combines a class, a class ' - 'instance and\n' - ' any callable object (normally a user-defined function).\n' - '\n' - ' Special read-only attributes: "__self__" is the class ' - 'instance\n' - ' object, "__func__" is the function object; "__doc__" is ' - 'the\n' - ' method\'s documentation (same as "__func__.__doc__"); ' - '"__name__"\n' - ' is the method name (same as "__func__.__name__"); ' - '"__module__"\n' - ' is the name of the module the method was defined in, or ' - '"None"\n' - ' if unavailable.\n' - '\n' - ' Methods also support accessing (but not setting) the ' - 'arbitrary\n' - ' function attributes on the underlying function object.\n' - '\n' - ' User-defined method objects may be created when getting an\n' - ' attribute of a class (perhaps via an instance of that ' - 'class), if\n' - ' that attribute is a user-defined function object or a ' - 'class\n' - ' method object.\n' - '\n' - ' When an instance method object is created by retrieving a ' - 'user-\n' - ' defined function object from a class via one of its ' - 'instances,\n' - ' its "__self__" attribute is the instance, and the method ' - 'object\n' - ' is said to be bound. The new method\'s "__func__" ' - 'attribute is\n' - ' the original function object.\n' - '\n' - ' When a user-defined method object is created by retrieving\n' - ' another method object from a class or instance, the ' - 'behaviour is\n' - ' the same as for a function object, except that the ' - '"__func__"\n' - ' attribute of the new instance is not the original method ' - 'object\n' - ' but its "__func__" attribute.\n' - '\n' - ' When an instance method object is created by retrieving a ' - 'class\n' - ' method object from a class or instance, its "__self__" ' - 'attribute\n' - ' is the class itself, and its "__func__" attribute is the\n' - ' function object underlying the class method.\n' - '\n' - ' When an instance method object is called, the underlying\n' - ' function ("__func__") is called, inserting the class ' - 'instance\n' - ' ("__self__") in front of the argument list. For instance, ' - 'when\n' - ' "C" is a class which contains a definition for a function ' - '"f()",\n' - ' and "x" is an instance of "C", calling "x.f(1)" is ' - 'equivalent to\n' - ' calling "C.f(x, 1)".\n' - '\n' - ' When an instance method object is derived from a class ' - 'method\n' - ' object, the "class instance" stored in "__self__" will ' - 'actually\n' - ' be the class itself, so that calling either "x.f(1)" or ' - '"C.f(1)"\n' - ' is equivalent to calling "f(C,1)" where "f" is the ' - 'underlying\n' - ' function.\n' - '\n' - ' Note that the transformation from function object to ' - 'instance\n' - ' method object happens each time the attribute is retrieved ' - 'from\n' - ' the instance. In some cases, a fruitful optimization is ' - 'to\n' - ' assign the attribute to a local variable and call that ' - 'local\n' - ' variable. Also notice that this transformation only happens ' - 'for\n' - ' user-defined functions; other callable objects (and all ' - 'non-\n' - ' callable objects) are retrieved without transformation. It ' - 'is\n' - ' also important to note that user-defined functions which ' - 'are\n' - ' attributes of a class instance are not converted to bound\n' - ' methods; this *only* happens when the function is an ' - 'attribute\n' - ' of the class.\n' - '\n' - ' Generator functions\n' - ' A function or method which uses the "yield" statement (see\n' - ' section *The yield statement*) is called a *generator ' - 'function*.\n' - ' Such a function, when called, always returns an iterator ' - 'object\n' - ' which can be used to execute the body of the function: ' - 'calling\n' - ' the iterator\'s "iterator.__next__()" method will cause ' - 'the\n' - ' function to execute until it provides a value using the ' - '"yield"\n' - ' statement. When the function executes a "return" statement ' - 'or\n' - ' falls off the end, a "StopIteration" exception is raised ' - 'and the\n' - ' iterator will have reached the end of the set of values to ' - 'be\n' - ' returned.\n' - '\n' - ' Built-in functions\n' - ' A built-in function object is a wrapper around a C ' - 'function.\n' - ' Examples of built-in functions are "len()" and ' - '"math.sin()"\n' - ' ("math" is a standard built-in module). The number and type ' - 'of\n' - ' the arguments are determined by the C function. Special ' - 'read-\n' - ' only attributes: "__doc__" is the function\'s ' - 'documentation\n' - ' string, or "None" if unavailable; "__name__" is the ' - "function's\n" - ' name; "__self__" is set to "None" (but see the next item);\n' - ' "__module__" is the name of the module the function was ' - 'defined\n' - ' in or "None" if unavailable.\n' - '\n' - ' Built-in methods\n' - ' This is really a different disguise of a built-in function, ' - 'this\n' - ' time containing an object passed to the C function as an\n' - ' implicit extra argument. An example of a built-in method ' - 'is\n' - ' "alist.append()", assuming *alist* is a list object. In ' - 'this\n' - ' case, the special read-only attribute "__self__" is set to ' - 'the\n' - ' object denoted by *alist*.\n' - '\n' - ' Classes\n' - ' Classes are callable. These objects normally act as ' - 'factories\n' - ' for new instances of themselves, but variations are ' - 'possible for\n' - ' class types that override "__new__()". The arguments of ' - 'the\n' - ' call are passed to "__new__()" and, in the typical case, ' - 'to\n' - ' "__init__()" to initialize the new instance.\n' - '\n' - ' Class Instances\n' - ' Instances of arbitrary classes can be made callable by ' - 'defining\n' - ' a "__call__()" method in their class.\n' - '\n' - 'Modules\n' - ' Modules are a basic organizational unit of Python code, and ' - 'are\n' - ' created by the *import system* as invoked either by the ' - '"import"\n' - ' statement (see "import"), or by calling functions such as\n' - ' "importlib.import_module()" and built-in "__import__()". A ' - 'module\n' - ' object has a namespace implemented by a dictionary object ' - '(this is\n' - ' the dictionary referenced by the "__globals__" attribute of\n' - ' functions defined in the module). Attribute references are\n' - ' translated to lookups in this dictionary, e.g., "m.x" is ' - 'equivalent\n' - ' to "m.__dict__["x"]". A module object does not contain the ' - 'code\n' - " object used to initialize the module (since it isn't needed " - 'once\n' - ' the initialization is done).\n' - '\n' - " Attribute assignment updates the module's namespace " - 'dictionary,\n' - ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n' - '\n' - ' Special read-only attribute: "__dict__" is the module\'s ' - 'namespace\n' - ' as a dictionary object.\n' - '\n' - ' **CPython implementation detail:** Because of the way CPython\n' - ' clears module dictionaries, the module dictionary will be ' - 'cleared\n' - ' when the module falls out of scope even if the dictionary ' - 'still has\n' - ' live references. To avoid this, copy the dictionary or keep ' - 'the\n' - ' module around while using its dictionary directly.\n' - '\n' - ' Predefined (writable) attributes: "__name__" is the module\'s ' - 'name;\n' - ' "__doc__" is the module\'s documentation string, or "None" if\n' - ' unavailable; "__file__" is the pathname of the file from which ' - 'the\n' - ' module was loaded, if it was loaded from a file. The ' - '"__file__"\n' - ' attribute may be missing for certain types of modules, such as ' - 'C\n' - ' modules that are statically linked into the interpreter; for\n' - ' extension modules loaded dynamically from a shared library, it ' - 'is\n' - ' the pathname of the shared library file.\n' - '\n' - 'Custom classes\n' - ' Custom class types are typically created by class definitions ' - '(see\n' - ' section *Class definitions*). A class has a namespace ' - 'implemented\n' - ' by a dictionary object. Class attribute references are ' - 'translated\n' - ' to lookups in this dictionary, e.g., "C.x" is translated to\n' - ' "C.__dict__["x"]" (although there are a number of hooks which ' - 'allow\n' - ' for other means of locating attributes). When the attribute ' - 'name is\n' - ' not found there, the attribute search continues in the base\n' - ' classes. This search of the base classes uses the C3 method\n' - ' resolution order which behaves correctly even in the presence ' - 'of\n' - " 'diamond' inheritance structures where there are multiple\n" - ' inheritance paths leading back to a common ancestor. ' - 'Additional\n' - ' details on the C3 MRO used by Python can be found in the\n' - ' documentation accompanying the 2.3 release at\n' - ' https://www.python.org/download/releases/2.3/mro/.\n' - '\n' - ' When a class attribute reference (for class "C", say) would ' - 'yield a\n' - ' class method object, it is transformed into an instance ' - 'method\n' - ' object whose "__self__" attributes is "C". When it would ' - 'yield a\n' - ' static method object, it is transformed into the object ' - 'wrapped by\n' - ' the static method object. See section *Implementing ' - 'Descriptors*\n' - ' for another way in which attributes retrieved from a class ' - 'may\n' - ' differ from those actually contained in its "__dict__".\n' - '\n' - " Class attribute assignments update the class's dictionary, " - 'never\n' - ' the dictionary of a base class.\n' - '\n' - ' A class object can be called (see above) to yield a class ' - 'instance\n' - ' (see below).\n' - '\n' - ' Special attributes: "__name__" is the class name; "__module__" ' - 'is\n' - ' the module name in which the class was defined; "__dict__" is ' - 'the\n' - ' dictionary containing the class\'s namespace; "__bases__" is a ' - 'tuple\n' - ' (possibly empty or a singleton) containing the base classes, ' - 'in the\n' - ' order of their occurrence in the base class list; "__doc__" is ' - 'the\n' - " class's documentation string, or None if undefined.\n" - '\n' - 'Class instances\n' - ' A class instance is created by calling a class object (see ' - 'above).\n' - ' A class instance has a namespace implemented as a dictionary ' - 'which\n' - ' is the first place in which attribute references are ' - 'searched.\n' - " When an attribute is not found there, and the instance's class " - 'has\n' - ' an attribute by that name, the search continues with the ' - 'class\n' - ' attributes. If a class attribute is found that is a ' - 'user-defined\n' - ' function object, it is transformed into an instance method ' - 'object\n' - ' whose "__self__" attribute is the instance. Static method ' - 'and\n' - ' class method objects are also transformed; see above under\n' - ' "Classes". See section *Implementing Descriptors* for another ' - 'way\n' - ' in which attributes of a class retrieved via its instances ' - 'may\n' - " differ from the objects actually stored in the class's " - '"__dict__".\n' - " If no class attribute is found, and the object's class has a\n" - ' "__getattr__()" method, that is called to satisfy the lookup.\n' - '\n' - " Attribute assignments and deletions update the instance's\n" - " dictionary, never a class's dictionary. If the class has a\n" - ' "__setattr__()" or "__delattr__()" method, this is called ' - 'instead\n' - ' of updating the instance dictionary directly.\n' - '\n' - ' Class instances can pretend to be numbers, sequences, or ' - 'mappings\n' - ' if they have methods with certain special names. See section\n' - ' *Special method names*.\n' - '\n' - ' Special attributes: "__dict__" is the attribute dictionary;\n' - ' "__class__" is the instance\'s class.\n' - '\n' - 'I/O objects (also known as file objects)\n' - ' A *file object* represents an open file. Various shortcuts ' - 'are\n' - ' available to create file objects: the "open()" built-in ' - 'function,\n' - ' and also "os.popen()", "os.fdopen()", and the "makefile()" ' - 'method\n' - ' of socket objects (and perhaps by other functions or methods\n' - ' provided by extension modules).\n' - '\n' - ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n' - ' initialized to file objects corresponding to the ' - "interpreter's\n" - ' standard input, output and error streams; they are all open in ' - 'text\n' - ' mode and therefore follow the interface defined by the\n' - ' "io.TextIOBase" abstract class.\n' - '\n' - 'Internal types\n' - ' A few types used internally by the interpreter are exposed to ' - 'the\n' - ' user. Their definitions may change with future versions of ' - 'the\n' - ' interpreter, but they are mentioned here for completeness.\n' - '\n' - ' Code objects\n' - ' Code objects represent *byte-compiled* executable Python ' - 'code,\n' - ' or *bytecode*. The difference between a code object and a\n' - ' function object is that the function object contains an ' - 'explicit\n' - " reference to the function's globals (the module in which it " - 'was\n' - ' defined), while a code object contains no context; also ' - 'the\n' - ' default argument values are stored in the function object, ' - 'not\n' - ' in the code object (because they represent values ' - 'calculated at\n' - ' run-time). Unlike function objects, code objects are ' - 'immutable\n' - ' and contain no references (directly or indirectly) to ' - 'mutable\n' - ' objects.\n' - '\n' - ' Special read-only attributes: "co_name" gives the function ' - 'name;\n' - ' "co_argcount" is the number of positional arguments ' - '(including\n' - ' arguments with default values); "co_nlocals" is the number ' - 'of\n' - ' local variables used by the function (including ' - 'arguments);\n' - ' "co_varnames" is a tuple containing the names of the local\n' - ' variables (starting with the argument names); "co_cellvars" ' - 'is a\n' - ' tuple containing the names of local variables that are\n' - ' referenced by nested functions; "co_freevars" is a tuple\n' - ' containing the names of free variables; "co_code" is a ' - 'string\n' - ' representing the sequence of bytecode instructions; ' - '"co_consts"\n' - ' is a tuple containing the literals used by the bytecode;\n' - ' "co_names" is a tuple containing the names used by the ' - 'bytecode;\n' - ' "co_filename" is the filename from which the code was ' - 'compiled;\n' - ' "co_firstlineno" is the first line number of the function;\n' - ' "co_lnotab" is a string encoding the mapping from bytecode\n' - ' offsets to line numbers (for details see the source code of ' - 'the\n' - ' interpreter); "co_stacksize" is the required stack size\n' - ' (including local variables); "co_flags" is an integer ' - 'encoding a\n' - ' number of flags for the interpreter.\n' - '\n' - ' The following flag bits are defined for "co_flags": bit ' - '"0x04"\n' - ' is set if the function uses the "*arguments" syntax to ' - 'accept an\n' - ' arbitrary number of positional arguments; bit "0x08" is set ' - 'if\n' - ' the function uses the "**keywords" syntax to accept ' - 'arbitrary\n' - ' keyword arguments; bit "0x20" is set if the function is a\n' - ' generator.\n' - '\n' - ' Future feature declarations ("from __future__ import ' - 'division")\n' - ' also use bits in "co_flags" to indicate whether a code ' - 'object\n' - ' was compiled with a particular feature enabled: bit ' - '"0x2000" is\n' - ' set if the function was compiled with future division ' - 'enabled;\n' - ' bits "0x10" and "0x1000" were used in earlier versions of\n' - ' Python.\n' - '\n' - ' Other bits in "co_flags" are reserved for internal use.\n' - '\n' - ' If a code object represents a function, the first item in\n' - ' "co_consts" is the documentation string of the function, ' - 'or\n' - ' "None" if undefined.\n' - '\n' - ' Frame objects\n' - ' Frame objects represent execution frames. They may occur ' - 'in\n' - ' traceback objects (see below).\n' - '\n' - ' Special read-only attributes: "f_back" is to the previous ' - 'stack\n' - ' frame (towards the caller), or "None" if this is the ' - 'bottom\n' - ' stack frame; "f_code" is the code object being executed in ' - 'this\n' - ' frame; "f_locals" is the dictionary used to look up local\n' - ' variables; "f_globals" is used for global variables;\n' - ' "f_builtins" is used for built-in (intrinsic) names; ' - '"f_lasti"\n' - ' gives the precise instruction (this is an index into the\n' - ' bytecode string of the code object).\n' - '\n' - ' Special writable attributes: "f_trace", if not "None", is ' - 'a\n' - ' function called at the start of each source code line (this ' - 'is\n' - ' used by the debugger); "f_lineno" is the current line ' - 'number of\n' - ' the frame --- writing to this from within a trace function ' - 'jumps\n' - ' to the given line (only for the bottom-most frame). A ' - 'debugger\n' - ' can implement a Jump command (aka Set Next Statement) by ' - 'writing\n' - ' to f_lineno.\n' - '\n' - ' Frame objects support one method:\n' - '\n' - ' frame.clear()\n' - '\n' - ' This method clears all references to local variables ' - 'held by\n' - ' the frame. Also, if the frame belonged to a generator, ' - 'the\n' - ' generator is finalized. This helps break reference ' - 'cycles\n' - ' involving frame objects (for example when catching an\n' - ' exception and storing its traceback for later use).\n' - '\n' - ' "RuntimeError" is raised if the frame is currently ' - 'executing.\n' - '\n' - ' New in version 3.4.\n' - '\n' - ' Traceback objects\n' - ' Traceback objects represent a stack trace of an exception. ' - 'A\n' - ' traceback object is created when an exception occurs. When ' - 'the\n' - ' search for an exception handler unwinds the execution ' - 'stack, at\n' - ' each unwound level a traceback object is inserted in front ' - 'of\n' - ' the current traceback. When an exception handler is ' - 'entered,\n' - ' the stack trace is made available to the program. (See ' - 'section\n' - ' *The try statement*.) It is accessible as the third item of ' - 'the\n' - ' tuple returned by "sys.exc_info()". When the program ' - 'contains no\n' - ' suitable handler, the stack trace is written (nicely ' - 'formatted)\n' - ' to the standard error stream; if the interpreter is ' - 'interactive,\n' - ' it is also made available to the user as ' - '"sys.last_traceback".\n' - '\n' - ' Special read-only attributes: "tb_next" is the next level ' - 'in the\n' - ' stack trace (towards the frame where the exception ' - 'occurred), or\n' - ' "None" if there is no next level; "tb_frame" points to the\n' - ' execution frame of the current level; "tb_lineno" gives the ' - 'line\n' - ' number where the exception occurred; "tb_lasti" indicates ' - 'the\n' - ' precise instruction. The line number and last instruction ' - 'in\n' - ' the traceback may differ from the line number of its frame\n' - ' object if the exception occurred in a "try" statement with ' - 'no\n' - ' matching except clause or with a finally clause.\n' - '\n' - ' Slice objects\n' - ' Slice objects are used to represent slices for ' - '"__getitem__()"\n' - ' methods. They are also created by the built-in "slice()"\n' - ' function.\n' - '\n' - ' Special read-only attributes: "start" is the lower bound; ' - '"stop"\n' - ' is the upper bound; "step" is the step value; each is ' - '"None" if\n' - ' omitted. These attributes can have any type.\n' - '\n' - ' Slice objects support one method:\n' - '\n' - ' slice.indices(self, length)\n' - '\n' - ' This method takes a single integer argument *length* ' - 'and\n' - ' computes information about the slice that the slice ' - 'object\n' - ' would describe if applied to a sequence of *length* ' - 'items.\n' - ' It returns a tuple of three integers; respectively these ' - 'are\n' - ' the *start* and *stop* indices and the *step* or stride\n' - ' length of the slice. Missing or out-of-bounds indices ' - 'are\n' - ' handled in a manner consistent with regular slices.\n' - '\n' - ' Static method objects\n' - ' Static method objects provide a way of defeating the\n' - ' transformation of function objects to method objects ' - 'described\n' - ' above. A static method object is a wrapper around any ' - 'other\n' - ' object, usually a user-defined method object. When a ' - 'static\n' - ' method object is retrieved from a class or a class ' - 'instance, the\n' - ' object actually returned is the wrapped object, which is ' - 'not\n' - ' subject to any further transformation. Static method ' - 'objects are\n' - ' not themselves callable, although the objects they wrap ' - 'usually\n' - ' are. Static method objects are created by the built-in\n' - ' "staticmethod()" constructor.\n' - '\n' - ' Class method objects\n' - ' A class method object, like a static method object, is a ' - 'wrapper\n' - ' around another object that alters the way in which that ' - 'object\n' - ' is retrieved from classes and class instances. The ' - 'behaviour of\n' - ' class method objects upon such retrieval is described ' - 'above,\n' - ' under "User-defined methods". Class method objects are ' - 'created\n' - ' by the built-in "classmethod()" constructor.\n', - 'typesfunctions': '\n' - 'Functions\n' - '*********\n' - '\n' - 'Function objects are created by function definitions. ' - 'The only\n' - 'operation on a function object is to call it: ' - '"func(argument-list)".\n' - '\n' - 'There are really two flavors of function objects: ' - 'built-in functions\n' - 'and user-defined functions. Both support the same ' - 'operation (to call\n' - 'the function), but the implementation is different, ' - 'hence the\n' - 'different object types.\n' - '\n' - 'See *Function definitions* for more information.\n', - 'typesmapping': '\n' - 'Mapping Types --- "dict"\n' - '************************\n' - '\n' - 'A *mapping* object maps *hashable* values to arbitrary ' - 'objects.\n' - 'Mappings are mutable objects. There is currently only one ' - 'standard\n' - 'mapping type, the *dictionary*. (For other containers see ' - 'the built-\n' - 'in "list", "set", and "tuple" classes, and the ' - '"collections" module.)\n' - '\n' - "A dictionary's keys are *almost* arbitrary values. Values " - 'that are\n' - 'not *hashable*, that is, values containing lists, ' - 'dictionaries or\n' - 'other mutable types (that are compared by value rather ' - 'than by object\n' - 'identity) may not be used as keys. Numeric types used for ' - 'keys obey\n' - 'the normal rules for numeric comparison: if two numbers ' - 'compare equal\n' - '(such as "1" and "1.0") then they can be used ' - 'interchangeably to index\n' - 'the same dictionary entry. (Note however, that since ' - 'computers store\n' - 'floating-point numbers as approximations it is usually ' - 'unwise to use\n' - 'them as dictionary keys.)\n' - '\n' - 'Dictionaries can be created by placing a comma-separated ' - 'list of "key:\n' - 'value" pairs within braces, for example: "{\'jack\': 4098, ' - "'sjoerd':\n" - '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the ' - '"dict"\n' - 'constructor.\n' - '\n' - 'class class dict(**kwarg)\n' - 'class class dict(mapping, **kwarg)\n' - 'class class dict(iterable, **kwarg)\n' - '\n' - ' Return a new dictionary initialized from an optional ' - 'positional\n' - ' argument and a possibly empty set of keyword ' - 'arguments.\n' - '\n' - ' If no positional argument is given, an empty dictionary ' - 'is created.\n' - ' If a positional argument is given and it is a mapping ' - 'object, a\n' - ' dictionary is created with the same key-value pairs as ' - 'the mapping\n' - ' object. Otherwise, the positional argument must be an ' - '*iterable*\n' - ' object. Each item in the iterable must itself be an ' - 'iterable with\n' - ' exactly two objects. The first object of each item ' - 'becomes a key\n' - ' in the new dictionary, and the second object the ' - 'corresponding\n' - ' value. If a key occurs more than once, the last value ' - 'for that key\n' - ' becomes the corresponding value in the new dictionary.\n' - '\n' - ' If keyword arguments are given, the keyword arguments ' - 'and their\n' - ' values are added to the dictionary created from the ' - 'positional\n' - ' argument. If a key being added is already present, the ' - 'value from\n' - ' the keyword argument replaces the value from the ' - 'positional\n' - ' argument.\n' - '\n' - ' To illustrate, the following examples all return a ' - 'dictionary equal\n' - ' to "{"one": 1, "two": 2, "three": 3}":\n' - '\n' - ' >>> a = dict(one=1, two=2, three=3)\n' - " >>> b = {'one': 1, 'two': 2, 'three': 3}\n" - " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, " - '3]))\n' - " >>> d = dict([('two', 2), ('one', 1), ('three', " - '3)])\n' - " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n" - ' >>> a == b == c == d == e\n' - ' True\n' - '\n' - ' Providing keyword arguments as in the first example ' - 'only works for\n' - ' keys that are valid Python identifiers. Otherwise, any ' - 'valid keys\n' - ' can be used.\n' - '\n' - ' These are the operations that dictionaries support (and ' - 'therefore,\n' - ' custom mapping types should support too):\n' - '\n' - ' len(d)\n' - '\n' - ' Return the number of items in the dictionary *d*.\n' - '\n' - ' d[key]\n' - '\n' - ' Return the item of *d* with key *key*. Raises a ' - '"KeyError" if\n' - ' *key* is not in the map.\n' - '\n' - ' If a subclass of dict defines a method ' - '"__missing__()" and *key*\n' - ' is not present, the "d[key]" operation calls that ' - 'method with\n' - ' the key *key* as argument. The "d[key]" operation ' - 'then returns\n' - ' or raises whatever is returned or raised by the\n' - ' "__missing__(key)" call. No other operations or ' - 'methods invoke\n' - ' "__missing__()". If "__missing__()" is not defined, ' - '"KeyError"\n' - ' is raised. "__missing__()" must be a method; it ' - 'cannot be an\n' - ' instance variable:\n' - '\n' - ' >>> class Counter(dict):\n' - ' ... def __missing__(self, key):\n' - ' ... return 0\n' - ' >>> c = Counter()\n' - " >>> c['red']\n" - ' 0\n' - " >>> c['red'] += 1\n" - " >>> c['red']\n" - ' 1\n' - '\n' - ' The example above shows part of the implementation ' - 'of\n' - ' "collections.Counter". A different "__missing__" ' - 'method is used\n' - ' by "collections.defaultdict".\n' - '\n' - ' d[key] = value\n' - '\n' - ' Set "d[key]" to *value*.\n' - '\n' - ' del d[key]\n' - '\n' - ' Remove "d[key]" from *d*. Raises a "KeyError" if ' - '*key* is not\n' - ' in the map.\n' - '\n' - ' key in d\n' - '\n' - ' Return "True" if *d* has a key *key*, else "False".\n' - '\n' - ' key not in d\n' - '\n' - ' Equivalent to "not key in d".\n' - '\n' - ' iter(d)\n' - '\n' - ' Return an iterator over the keys of the dictionary. ' - 'This is a\n' - ' shortcut for "iter(d.keys())".\n' - '\n' - ' clear()\n' - '\n' - ' Remove all items from the dictionary.\n' - '\n' - ' copy()\n' - '\n' - ' Return a shallow copy of the dictionary.\n' - '\n' - ' classmethod fromkeys(seq[, value])\n' - '\n' - ' Create a new dictionary with keys from *seq* and ' - 'values set to\n' - ' *value*.\n' - '\n' - ' "fromkeys()" is a class method that returns a new ' - 'dictionary.\n' - ' *value* defaults to "None".\n' - '\n' - ' get(key[, default])\n' - '\n' - ' Return the value for *key* if *key* is in the ' - 'dictionary, else\n' - ' *default*. If *default* is not given, it defaults to ' - '"None", so\n' - ' that this method never raises a "KeyError".\n' - '\n' - ' items()\n' - '\n' - ' Return a new view of the dictionary\'s items ("(key, ' - 'value)"\n' - ' pairs). See the *documentation of view objects*.\n' - '\n' - ' keys()\n' - '\n' - " Return a new view of the dictionary's keys. See " - 'the\n' - ' *documentation of view objects*.\n' - '\n' - ' pop(key[, default])\n' - '\n' - ' If *key* is in the dictionary, remove it and return ' - 'its value,\n' - ' else return *default*. If *default* is not given ' - 'and *key* is\n' - ' not in the dictionary, a "KeyError" is raised.\n' - '\n' - ' popitem()\n' - '\n' - ' Remove and return an arbitrary "(key, value)" pair ' - 'from the\n' - ' dictionary.\n' - '\n' - ' "popitem()" is useful to destructively iterate over ' - 'a\n' - ' dictionary, as often used in set algorithms. If the ' - 'dictionary\n' - ' is empty, calling "popitem()" raises a "KeyError".\n' - '\n' - ' setdefault(key[, default])\n' - '\n' - ' If *key* is in the dictionary, return its value. If ' - 'not, insert\n' - ' *key* with a value of *default* and return ' - '*default*. *default*\n' - ' defaults to "None".\n' - '\n' - ' update([other])\n' - '\n' - ' Update the dictionary with the key/value pairs from ' - '*other*,\n' - ' overwriting existing keys. Return "None".\n' - '\n' - ' "update()" accepts either another dictionary object ' - 'or an\n' - ' iterable of key/value pairs (as tuples or other ' - 'iterables of\n' - ' length two). If keyword arguments are specified, ' - 'the dictionary\n' - ' is then updated with those key/value pairs: ' - '"d.update(red=1,\n' - ' blue=2)".\n' - '\n' - ' values()\n' - '\n' - " Return a new view of the dictionary's values. See " - 'the\n' - ' *documentation of view objects*.\n' - '\n' - ' Dictionaries compare equal if and only if they have the ' - 'same "(key,\n' - ' value)" pairs. Order comparisons (\'<\', \'<=\', ' - "'>=', '>') raise\n" - ' "TypeError".\n' - '\n' - 'See also: "types.MappingProxyType" can be used to create a ' - 'read-only\n' - ' view of a "dict".\n' - '\n' - '\n' - 'Dictionary view objects\n' - '=======================\n' - '\n' - 'The objects returned by "dict.keys()", "dict.values()" ' - 'and\n' - '"dict.items()" are *view objects*. They provide a dynamic ' - 'view on the\n' - "dictionary's entries, which means that when the dictionary " - 'changes,\n' - 'the view reflects these changes.\n' - '\n' - 'Dictionary views can be iterated over to yield their ' - 'respective data,\n' - 'and support membership tests:\n' - '\n' - 'len(dictview)\n' - '\n' - ' Return the number of entries in the dictionary.\n' - '\n' - 'iter(dictview)\n' - '\n' - ' Return an iterator over the keys, values or items ' - '(represented as\n' - ' tuples of "(key, value)") in the dictionary.\n' - '\n' - ' Keys and values are iterated over in an arbitrary order ' - 'which is\n' - ' non-random, varies across Python implementations, and ' - 'depends on\n' - " the dictionary's history of insertions and deletions. " - 'If keys,\n' - ' values and items views are iterated over with no ' - 'intervening\n' - ' modifications to the dictionary, the order of items ' - 'will directly\n' - ' correspond. This allows the creation of "(value, key)" ' - 'pairs using\n' - ' "zip()": "pairs = zip(d.values(), d.keys())". Another ' - 'way to\n' - ' create the same list is "pairs = [(v, k) for (k, v) in ' - 'd.items()]".\n' - '\n' - ' Iterating views while adding or deleting entries in the ' - 'dictionary\n' - ' may raise a "RuntimeError" or fail to iterate over all ' - 'entries.\n' - '\n' - 'x in dictview\n' - '\n' - ' Return "True" if *x* is in the underlying dictionary\'s ' - 'keys, values\n' - ' or items (in the latter case, *x* should be a "(key, ' - 'value)"\n' - ' tuple).\n' - '\n' - 'Keys views are set-like since their entries are unique and ' - 'hashable.\n' - 'If all values are hashable, so that "(key, value)" pairs ' - 'are unique\n' - 'and hashable, then the items view is also set-like. ' - '(Values views are\n' - 'not treated as set-like since the entries are generally ' - 'not unique.)\n' - 'For set-like views, all of the operations defined for the ' - 'abstract\n' - 'base class "collections.abc.Set" are available (for ' - 'example, "==",\n' - '"<", or "^").\n' - '\n' - 'An example of dictionary view usage:\n' - '\n' - " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, " - "'spam': 500}\n" - ' >>> keys = dishes.keys()\n' - ' >>> values = dishes.values()\n' - '\n' - ' >>> # iteration\n' - ' >>> n = 0\n' - ' >>> for val in values:\n' - ' ... n += val\n' - ' >>> print(n)\n' - ' 504\n' - '\n' - ' >>> # keys and values are iterated over in the same ' - 'order\n' - ' >>> list(keys)\n' - " ['eggs', 'bacon', 'sausage', 'spam']\n" - ' >>> list(values)\n' - ' [2, 1, 1, 500]\n' - '\n' - ' >>> # view objects are dynamic and reflect dict ' - 'changes\n' - " >>> del dishes['eggs']\n" - " >>> del dishes['sausage']\n" - ' >>> list(keys)\n' - " ['spam', 'bacon']\n" - '\n' - ' >>> # set operations\n' - " >>> keys & {'eggs', 'bacon', 'salad'}\n" - " {'bacon'}\n" - " >>> keys ^ {'sausage', 'juice'}\n" - " {'juice', 'sausage', 'bacon', 'spam'}\n", - 'typesmethods': '\n' - 'Methods\n' - '*******\n' - '\n' - 'Methods are functions that are called using the attribute ' - 'notation.\n' - 'There are two flavors: built-in methods (such as ' - '"append()" on lists)\n' - 'and class instance methods. Built-in methods are ' - 'described with the\n' - 'types that support them.\n' - '\n' - 'If you access a method (a function defined in a class ' - 'namespace)\n' - 'through an instance, you get a special object: a *bound ' - 'method* (also\n' - 'called *instance method*) object. When called, it will add ' - 'the "self"\n' - 'argument to the argument list. Bound methods have two ' - 'special read-\n' - 'only attributes: "m.__self__" is the object on which the ' - 'method\n' - 'operates, and "m.__func__" is the function implementing ' - 'the method.\n' - 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely ' - 'equivalent to\n' - 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., ' - 'arg-n)".\n' - '\n' - 'Like function objects, bound method objects support ' - 'getting arbitrary\n' - 'attributes. However, since method attributes are actually ' - 'stored on\n' - 'the underlying function object ("meth.__func__"), setting ' - 'method\n' - 'attributes on bound methods is disallowed. Attempting to ' - 'set an\n' - 'attribute on a method results in an "AttributeError" being ' - 'raised. In\n' - 'order to set a method attribute, you need to explicitly ' - 'set it on the\n' - 'underlying function object:\n' - '\n' - ' >>> class C:\n' - ' ... def method(self):\n' - ' ... pass\n' - ' ...\n' - ' >>> c = C()\n' - " >>> c.method.whoami = 'my name is method' # can't set " - 'on the method\n' - ' Traceback (most recent call last):\n' - ' File "", line 1, in \n' - " AttributeError: 'method' object has no attribute " - "'whoami'\n" - " >>> c.method.__func__.whoami = 'my name is method'\n" - ' >>> c.method.whoami\n' - " 'my name is method'\n" - '\n' - 'See *The standard type hierarchy* for more information.\n', - 'typesmodules': '\n' - 'Modules\n' - '*******\n' - '\n' - 'The only special operation on a module is attribute ' - 'access: "m.name",\n' - 'where *m* is a module and *name* accesses a name defined ' - "in *m*'s\n" - 'symbol table. Module attributes can be assigned to. (Note ' - 'that the\n' - '"import" statement is not, strictly speaking, an operation ' - 'on a module\n' - 'object; "import foo" does not require a module object ' - 'named *foo* to\n' - 'exist, rather it requires an (external) *definition* for a ' - 'module\n' - 'named *foo* somewhere.)\n' - '\n' - 'A special attribute of every module is "__dict__". This is ' - 'the\n' - "dictionary containing the module's symbol table. Modifying " - 'this\n' - "dictionary will actually change the module's symbol table, " - 'but direct\n' - 'assignment to the "__dict__" attribute is not possible ' - '(you can write\n' - '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", ' - "but you can't\n" - 'write "m.__dict__ = {}"). Modifying "__dict__" directly ' - 'is not\n' - 'recommended.\n' - '\n' - 'Modules built into the interpreter are written like this: ' - '"". If loaded from a file, they are ' - 'written as\n' - '"".\n', - 'typesseq': '\n' - 'Sequence Types --- "list", "tuple", "range"\n' - '*******************************************\n' - '\n' - 'There are three basic sequence types: lists, tuples, and ' - 'range\n' - 'objects. Additional sequence types tailored for processing of ' - '*binary\n' - 'data* and *text strings* are described in dedicated sections.\n' - '\n' - '\n' - 'Common Sequence Operations\n' - '==========================\n' - '\n' - 'The operations in the following table are supported by most ' - 'sequence\n' - 'types, both mutable and immutable. The ' - '"collections.abc.Sequence" ABC\n' - 'is provided to make it easier to correctly implement these ' - 'operations\n' - 'on custom sequence types.\n' - '\n' - 'This table lists the sequence operations sorted in ascending ' - 'priority.\n' - 'In the table, *s* and *t* are sequences of the same type, *n*, ' - '*i*,\n' - '*j* and *k* are integers and *x* is an arbitrary object that ' - 'meets any\n' - 'type and value restrictions imposed by *s*.\n' - '\n' - 'The "in" and "not in" operations have the same priorities as ' - 'the\n' - 'comparison operations. The "+" (concatenation) and "*" ' - '(repetition)\n' - 'operations have the same priority as the corresponding ' - 'numeric\n' - 'operations.\n' - '\n' - '+----------------------------+----------------------------------+------------+\n' - '| Operation | ' - 'Result | Notes |\n' - '+============================+==================================+============+\n' - '| "x in s" | "True" if an item of *s* ' - 'is | (1) |\n' - '| | equal to *x*, else ' - '"False" | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "x not in s" | "False" if an item of *s* ' - 'is | (1) |\n' - '| | equal to *x*, else ' - '"True" | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s + t" | the concatenation of *s* and ' - '*t* | (6)(7) |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s * n" or "n * s" | equivalent to adding *s* ' - 'to | (2)(7) |\n' - '| | itself *n* ' - 'times | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s[i]" | *i*th item of *s*, origin ' - '0 | (3) |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s[i:j]" | slice of *s* from *i* to ' - '*j* | (3)(4) |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s[i:j:k]" | slice of *s* from *i* to ' - '*j* | (3)(5) |\n' - '| | with step ' - '*k* | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "len(s)" | length of ' - '*s* | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "min(s)" | smallest item of ' - '*s* | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "max(s)" | largest item of ' - '*s* | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s.index(x[, i[, j]])" | index of the first occurrence ' - 'of | (8) |\n' - '| | *x* in *s* (at or after ' - 'index | |\n' - '| | *i* and before index ' - '*j*) | |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s.count(x)" | total number of occurrences ' - 'of | |\n' - '| | *x* in ' - '*s* | |\n' - '+----------------------------+----------------------------------+------------+\n' - '\n' - 'Sequences of the same type also support comparisons. In ' - 'particular,\n' - 'tuples and lists are compared lexicographically by comparing\n' - 'corresponding elements. This means that to compare equal, ' - 'every\n' - 'element must compare equal and the two sequences must be of ' - 'the same\n' - 'type and have the same length. (For full details see ' - '*Comparisons* in\n' - 'the language reference.)\n' - '\n' - 'Notes:\n' - '\n' - '1. While the "in" and "not in" operations are used only for ' - 'simple\n' - ' containment testing in the general case, some specialised ' - 'sequences\n' - ' (such as "str", "bytes" and "bytearray") also use them for\n' - ' subsequence testing:\n' - '\n' - ' >>> "gg" in "eggs"\n' - ' True\n' - '\n' - '2. Values of *n* less than "0" are treated as "0" (which ' - 'yields an\n' - ' empty sequence of the same type as *s*). Note that items ' - 'in the\n' - ' sequence *s* are not copied; they are referenced multiple ' - 'times.\n' - ' This often haunts new Python programmers; consider:\n' - '\n' - ' >>> lists = [[]] * 3\n' - ' >>> lists\n' - ' [[], [], []]\n' - ' >>> lists[0].append(3)\n' - ' >>> lists\n' - ' [[3], [3], [3]]\n' - '\n' - ' What has happened is that "[[]]" is a one-element list ' - 'containing\n' - ' an empty list, so all three elements of "[[]] * 3" are ' - 'references\n' - ' to this single empty list. Modifying any of the elements ' - 'of\n' - ' "lists" modifies this single list. You can create a list ' - 'of\n' - ' different lists this way:\n' - '\n' - ' >>> lists = [[] for i in range(3)]\n' - ' >>> lists[0].append(3)\n' - ' >>> lists[1].append(5)\n' - ' >>> lists[2].append(7)\n' - ' >>> lists\n' - ' [[3], [5], [7]]\n' - '\n' - ' Further explanation is available in the FAQ entry *How do I ' - 'create\n' - ' a multidimensional list?*.\n' - '\n' - '3. If *i* or *j* is negative, the index is relative to the end ' - 'of\n' - ' the string: "len(s) + i" or "len(s) + j" is substituted. ' - 'But note\n' - ' that "-0" is still "0".\n' - '\n' - '4. The slice of *s* from *i* to *j* is defined as the sequence ' - 'of\n' - ' items with index *k* such that "i <= k < j". If *i* or *j* ' - 'is\n' - ' greater than "len(s)", use "len(s)". If *i* is omitted or ' - '"None",\n' - ' use "0". If *j* is omitted or "None", use "len(s)". If ' - '*i* is\n' - ' greater than or equal to *j*, the slice is empty.\n' - '\n' - '5. The slice of *s* from *i* to *j* with step *k* is defined ' - 'as the\n' - ' sequence of items with index "x = i + n*k" such that "0 <= ' - 'n <\n' - ' (j-i)/k". In other words, the indices are "i", "i+k", ' - '"i+2*k",\n' - ' "i+3*k" and so on, stopping when *j* is reached (but never\n' - ' including *j*). If *i* or *j* is greater than "len(s)", ' - 'use\n' - ' "len(s)". If *i* or *j* are omitted or "None", they become ' - '"end"\n' - ' values (which end depends on the sign of *k*). Note, *k* ' - 'cannot be\n' - ' zero. If *k* is "None", it is treated like "1".\n' - '\n' - '6. Concatenating immutable sequences always results in a new\n' - ' object. This means that building up a sequence by repeated\n' - ' concatenation will have a quadratic runtime cost in the ' - 'total\n' - ' sequence length. To get a linear runtime cost, you must ' - 'switch to\n' - ' one of the alternatives below:\n' - '\n' - ' * if concatenating "str" objects, you can build a list and ' - 'use\n' - ' "str.join()" at the end or else write to an ' - '"io.StringIO"\n' - ' instance and retrieve its value when complete\n' - '\n' - ' * if concatenating "bytes" objects, you can similarly use\n' - ' "bytes.join()" or "io.BytesIO", or you can do in-place\n' - ' concatenation with a "bytearray" object. "bytearray" ' - 'objects are\n' - ' mutable and have an efficient overallocation mechanism\n' - '\n' - ' * if concatenating "tuple" objects, extend a "list" ' - 'instead\n' - '\n' - ' * for other types, investigate the relevant class ' - 'documentation\n' - '\n' - '7. Some sequence types (such as "range") only support item\n' - " sequences that follow specific patterns, and hence don't " - 'support\n' - ' sequence concatenation or repetition.\n' - '\n' - '8. "index" raises "ValueError" when *x* is not found in *s*. ' - 'When\n' - ' supported, the additional arguments to the index method ' - 'allow\n' - ' efficient searching of subsections of the sequence. Passing ' - 'the\n' - ' extra arguments is roughly equivalent to using ' - '"s[i:j].index(x)",\n' - ' only without copying any data and with the returned index ' - 'being\n' - ' relative to the start of the sequence rather than the start ' - 'of the\n' - ' slice.\n' - '\n' - '\n' - 'Immutable Sequence Types\n' - '========================\n' - '\n' - 'The only operation that immutable sequence types generally ' - 'implement\n' - 'that is not also implemented by mutable sequence types is ' - 'support for\n' - 'the "hash()" built-in.\n' - '\n' - 'This support allows immutable sequences, such as "tuple" ' - 'instances, to\n' - 'be used as "dict" keys and stored in "set" and "frozenset" ' - 'instances.\n' - '\n' - 'Attempting to hash an immutable sequence that contains ' - 'unhashable\n' - 'values will result in "TypeError".\n' - '\n' - '\n' - 'Mutable Sequence Types\n' - '======================\n' - '\n' - 'The operations in the following table are defined on mutable ' - 'sequence\n' - 'types. The "collections.abc.MutableSequence" ABC is provided ' - 'to make\n' - 'it easier to correctly implement these operations on custom ' - 'sequence\n' - 'types.\n' - '\n' - 'In the table *s* is an instance of a mutable sequence type, ' - '*t* is any\n' - 'iterable object and *x* is an arbitrary object that meets any ' - 'type and\n' - 'value restrictions imposed by *s* (for example, "bytearray" ' - 'only\n' - 'accepts integers that meet the value restriction "0 <= x <= ' - '255").\n' - '\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| Operation | ' - 'Result | Notes |\n' - '+================================+==================================+=======================+\n' - '| "s[i] = x" | item *i* of *s* is replaced ' - 'by | |\n' - '| | ' - '*x* | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s[i:j] = t" | slice of *s* from *i* to ' - '*j* is | |\n' - '| | replaced by the contents of ' - 'the | |\n' - '| | iterable ' - '*t* | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "del s[i:j]" | same as "s[i:j] = ' - '[]" | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s[i:j:k] = t" | the elements of "s[i:j:k]" ' - 'are | (1) |\n' - '| | replaced by those of ' - '*t* | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "del s[i:j:k]" | removes the elements ' - 'of | |\n' - '| | "s[i:j:k]" from the ' - 'list | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.append(x)" | appends *x* to the end of ' - 'the | |\n' - '| | sequence (same ' - 'as | |\n' - '| | "s[len(s):len(s)] = ' - '[x]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.clear()" | removes all items from "s" ' - '(same | (5) |\n' - '| | as "del ' - 's[:]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.copy()" | creates a shallow copy of ' - '"s" | (5) |\n' - '| | (same as ' - '"s[:]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.extend(t)" or "s += t" | extends *s* with the ' - 'contents of | |\n' - '| | *t* (for the most part the ' - 'same | |\n' - '| | as "s[len(s):len(s)] = ' - 't") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s *= n" | updates *s* with its ' - 'contents | (6) |\n' - '| | repeated *n* ' - 'times | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.insert(i, x)" | inserts *x* into *s* at ' - 'the | |\n' - '| | index given by *i* (same ' - 'as | |\n' - '| | "s[i:i] = ' - '[x]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.pop([i])" | retrieves the item at *i* ' - 'and | (2) |\n' - '| | also removes it from ' - '*s* | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.remove(x)" | remove the first item from ' - '*s* | (3) |\n' - '| | where "s[i] == ' - 'x" | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.reverse()" | reverses the items of *s* ' - 'in | (4) |\n' - '| | ' - 'place | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '\n' - 'Notes:\n' - '\n' - '1. *t* must have the same length as the slice it is ' - 'replacing.\n' - '\n' - '2. The optional argument *i* defaults to "-1", so that by ' - 'default\n' - ' the last item is removed and returned.\n' - '\n' - '3. "remove" raises "ValueError" when *x* is not found in *s*.\n' - '\n' - '4. The "reverse()" method modifies the sequence in place for\n' - ' economy of space when reversing a large sequence. To ' - 'remind users\n' - ' that it operates by side effect, it does not return the ' - 'reversed\n' - ' sequence.\n' - '\n' - '5. "clear()" and "copy()" are included for consistency with ' - 'the\n' - " interfaces of mutable containers that don't support " - 'slicing\n' - ' operations (such as "dict" and "set")\n' - '\n' - ' New in version 3.3: "clear()" and "copy()" methods.\n' - '\n' - '6. The value *n* is an integer, or an object implementing\n' - ' "__index__()". Zero and negative values of *n* clear the ' - 'sequence.\n' - ' Items in the sequence are not copied; they are referenced ' - 'multiple\n' - ' times, as explained for "s * n" under *Common Sequence ' - 'Operations*.\n' - '\n' - '\n' - 'Lists\n' - '=====\n' - '\n' - 'Lists are mutable sequences, typically used to store ' - 'collections of\n' - 'homogeneous items (where the precise degree of similarity will ' - 'vary by\n' - 'application).\n' - '\n' - 'class class list([iterable])\n' - '\n' - ' Lists may be constructed in several ways:\n' - '\n' - ' * Using a pair of square brackets to denote the empty list: ' - '"[]"\n' - '\n' - ' * Using square brackets, separating items with commas: ' - '"[a]",\n' - ' "[a, b, c]"\n' - '\n' - ' * Using a list comprehension: "[x for x in iterable]"\n' - '\n' - ' * Using the type constructor: "list()" or "list(iterable)"\n' - '\n' - ' The constructor builds a list whose items are the same and ' - 'in the\n' - " same order as *iterable*'s items. *iterable* may be either " - 'a\n' - ' sequence, a container that supports iteration, or an ' - 'iterator\n' - ' object. If *iterable* is already a list, a copy is made ' - 'and\n' - ' returned, similar to "iterable[:]". For example, ' - '"list(\'abc\')"\n' - ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" ' - 'returns "[1, 2,\n' - ' 3]". If no argument is given, the constructor creates a new ' - 'empty\n' - ' list, "[]".\n' - '\n' - ' Many other operations also produce lists, including the ' - '"sorted()"\n' - ' built-in.\n' - '\n' - ' Lists implement all of the *common* and *mutable* sequence\n' - ' operations. Lists also provide the following additional ' - 'method:\n' - '\n' - ' sort(*, key=None, reverse=None)\n' - '\n' - ' This method sorts the list in place, using only "<" ' - 'comparisons\n' - ' between items. Exceptions are not suppressed - if any ' - 'comparison\n' - ' operations fail, the entire sort operation will fail ' - '(and the\n' - ' list will likely be left in a partially modified ' - 'state).\n' - '\n' - ' "sort()" accepts two arguments that can only be passed ' - 'by\n' - ' keyword (*keyword-only arguments*):\n' - '\n' - ' *key* specifies a function of one argument that is used ' - 'to\n' - ' extract a comparison key from each list element (for ' - 'example,\n' - ' "key=str.lower"). The key corresponding to each item in ' - 'the list\n' - ' is calculated once and then used for the entire sorting ' - 'process.\n' - ' The default value of "None" means that list items are ' - 'sorted\n' - ' directly without calculating a separate key value.\n' - '\n' - ' The "functools.cmp_to_key()" utility is available to ' - 'convert a\n' - ' 2.x style *cmp* function to a *key* function.\n' - '\n' - ' *reverse* is a boolean value. If set to "True", then ' - 'the list\n' - ' elements are sorted as if each comparison were ' - 'reversed.\n' - '\n' - ' This method modifies the sequence in place for economy ' - 'of space\n' - ' when sorting a large sequence. To remind users that it ' - 'operates\n' - ' by side effect, it does not return the sorted sequence ' - '(use\n' - ' "sorted()" to explicitly request a new sorted list ' - 'instance).\n' - '\n' - ' The "sort()" method is guaranteed to be stable. A sort ' - 'is\n' - ' stable if it guarantees not to change the relative order ' - 'of\n' - ' elements that compare equal --- this is helpful for ' - 'sorting in\n' - ' multiple passes (for example, sort by department, then ' - 'by salary\n' - ' grade).\n' - '\n' - ' **CPython implementation detail:** While a list is being ' - 'sorted,\n' - ' the effect of attempting to mutate, or even inspect, the ' - 'list is\n' - ' undefined. The C implementation of Python makes the ' - 'list appear\n' - ' empty for the duration, and raises "ValueError" if it ' - 'can detect\n' - ' that the list has been mutated during a sort.\n' - '\n' - '\n' - 'Tuples\n' - '======\n' - '\n' - 'Tuples are immutable sequences, typically used to store ' - 'collections of\n' - 'heterogeneous data (such as the 2-tuples produced by the ' - '"enumerate()"\n' - 'built-in). Tuples are also used for cases where an immutable ' - 'sequence\n' - 'of homogeneous data is needed (such as allowing storage in a ' - '"set" or\n' - '"dict" instance).\n' - '\n' - 'class class tuple([iterable])\n' - '\n' - ' Tuples may be constructed in a number of ways:\n' - '\n' - ' * Using a pair of parentheses to denote the empty tuple: ' - '"()"\n' - '\n' - ' * Using a trailing comma for a singleton tuple: "a," or ' - '"(a,)"\n' - '\n' - ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n' - '\n' - ' * Using the "tuple()" built-in: "tuple()" or ' - '"tuple(iterable)"\n' - '\n' - ' The constructor builds a tuple whose items are the same and ' - 'in the\n' - " same order as *iterable*'s items. *iterable* may be either " - 'a\n' - ' sequence, a container that supports iteration, or an ' - 'iterator\n' - ' object. If *iterable* is already a tuple, it is returned\n' - ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', ' - '\'b\', \'c\')"\n' - ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no ' - 'argument is\n' - ' given, the constructor creates a new empty tuple, "()".\n' - '\n' - ' Note that it is actually the comma which makes a tuple, not ' - 'the\n' - ' parentheses. The parentheses are optional, except in the ' - 'empty\n' - ' tuple case, or when they are needed to avoid syntactic ' - 'ambiguity.\n' - ' For example, "f(a, b, c)" is a function call with three ' - 'arguments,\n' - ' while "f((a, b, c))" is a function call with a 3-tuple as ' - 'the sole\n' - ' argument.\n' - '\n' - ' Tuples implement all of the *common* sequence operations.\n' - '\n' - 'For heterogeneous collections of data where access by name is ' - 'clearer\n' - 'than access by index, "collections.namedtuple()" may be a ' - 'more\n' - 'appropriate choice than a simple tuple object.\n' - '\n' - '\n' - 'Ranges\n' - '======\n' - '\n' - 'The "range" type represents an immutable sequence of numbers ' - 'and is\n' - 'commonly used for looping a specific number of times in "for" ' - 'loops.\n' - '\n' - 'class class range(stop)\n' - 'class class range(start, stop[, step])\n' - '\n' - ' The arguments to the range constructor must be integers ' - '(either\n' - ' built-in "int" or any object that implements the ' - '"__index__"\n' - ' special method). If the *step* argument is omitted, it ' - 'defaults to\n' - ' "1". If the *start* argument is omitted, it defaults to ' - '"0". If\n' - ' *step* is zero, "ValueError" is raised.\n' - '\n' - ' For a positive *step*, the contents of a range "r" are ' - 'determined\n' - ' by the formula "r[i] = start + step*i" where "i >= 0" and ' - '"r[i] <\n' - ' stop".\n' - '\n' - ' For a negative *step*, the contents of the range are still\n' - ' determined by the formula "r[i] = start + step*i", but the\n' - ' constraints are "i >= 0" and "r[i] > stop".\n' - '\n' - ' A range object will be empty if "r[0]" does not meet the ' - 'value\n' - ' constraint. Ranges do support negative indices, but these ' - 'are\n' - ' interpreted as indexing from the end of the sequence ' - 'determined by\n' - ' the positive indices.\n' - '\n' - ' Ranges containing absolute values larger than "sys.maxsize" ' - 'are\n' - ' permitted but some features (such as "len()") may raise\n' - ' "OverflowError".\n' - '\n' - ' Range examples:\n' - '\n' - ' >>> list(range(10))\n' - ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n' - ' >>> list(range(1, 11))\n' - ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n' - ' >>> list(range(0, 30, 5))\n' - ' [0, 5, 10, 15, 20, 25]\n' - ' >>> list(range(0, 10, 3))\n' - ' [0, 3, 6, 9]\n' - ' >>> list(range(0, -10, -1))\n' - ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n' - ' >>> list(range(0))\n' - ' []\n' - ' >>> list(range(1, 0))\n' - ' []\n' - '\n' - ' Ranges implement all of the *common* sequence operations ' - 'except\n' - ' concatenation and repetition (due to the fact that range ' - 'objects\n' - ' can only represent sequences that follow a strict pattern ' - 'and\n' - ' repetition and concatenation will usually violate that ' - 'pattern).\n' - '\n' - 'The advantage of the "range" type over a regular "list" or ' - '"tuple" is\n' - 'that a "range" object will always take the same (small) amount ' - 'of\n' - 'memory, no matter the size of the range it represents (as it ' - 'only\n' - 'stores the "start", "stop" and "step" values, calculating ' - 'individual\n' - 'items and subranges as needed).\n' - '\n' - 'Range objects implement the "collections.abc.Sequence" ABC, ' - 'and\n' - 'provide features such as containment tests, element index ' - 'lookup,\n' - 'slicing and support for negative indices (see *Sequence Types ' - '---\n' - 'list, tuple, range*):\n' - '\n' - '>>> r = range(0, 20, 2)\n' - '>>> r\n' - 'range(0, 20, 2)\n' - '>>> 11 in r\n' - 'False\n' - '>>> 10 in r\n' - 'True\n' - '>>> r.index(10)\n' - '5\n' - '>>> r[5]\n' - '10\n' - '>>> r[:5]\n' - 'range(0, 10, 2)\n' - '>>> r[-1]\n' - '18\n' - '\n' - 'Testing range objects for equality with "==" and "!=" compares ' - 'them as\n' - 'sequences. That is, two range objects are considered equal if ' - 'they\n' - 'represent the same sequence of values. (Note that two range ' - 'objects\n' - 'that compare equal might have different "start", "stop" and ' - '"step"\n' - 'attributes, for example "range(0) == range(2, 1, 3)" or ' - '"range(0, 3,\n' - '2) == range(0, 4, 2)".)\n' - '\n' - 'Changed in version 3.2: Implement the Sequence ABC. Support ' - 'slicing\n' - 'and negative indices. Test "int" objects for membership in ' - 'constant\n' - 'time instead of iterating through all items.\n' - '\n' - "Changed in version 3.3: Define '==' and '!=' to compare range " - 'objects\n' - 'based on the sequence of values they define (instead of ' - 'comparing\n' - 'based on object identity).\n' - '\n' - 'New in version 3.3: The "start", "stop" and "step" ' - 'attributes.\n', - 'typesseq-mutable': '\n' - 'Mutable Sequence Types\n' - '**********************\n' - '\n' - 'The operations in the following table are defined on ' - 'mutable sequence\n' - 'types. The "collections.abc.MutableSequence" ABC is ' - 'provided to make\n' - 'it easier to correctly implement these operations on ' - 'custom sequence\n' - 'types.\n' - '\n' - 'In the table *s* is an instance of a mutable sequence ' - 'type, *t* is any\n' - 'iterable object and *x* is an arbitrary object that ' - 'meets any type and\n' - 'value restrictions imposed by *s* (for example, ' - '"bytearray" only\n' - 'accepts integers that meet the value restriction "0 <= ' - 'x <= 255").\n' - '\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| Operation | ' - 'Result | ' - 'Notes |\n' - '+================================+==================================+=======================+\n' - '| "s[i] = x" | item *i* of *s* is ' - 'replaced by | |\n' - '| | ' - '*x* ' - '| |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s[i:j] = t" | slice of *s* from ' - '*i* to *j* is | |\n' - '| | replaced by the ' - 'contents of the | |\n' - '| | iterable ' - '*t* | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "del s[i:j]" | same as "s[i:j] = ' - '[]" | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s[i:j:k] = t" | the elements of ' - '"s[i:j:k]" are | (1) |\n' - '| | replaced by those ' - 'of *t* | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "del s[i:j:k]" | removes the ' - 'elements of | |\n' - '| | "s[i:j:k]" from the ' - 'list | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.append(x)" | appends *x* to the ' - 'end of the | |\n' - '| | sequence (same ' - 'as | |\n' - '| | "s[len(s):len(s)] = ' - '[x]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.clear()" | removes all items ' - 'from "s" (same | (5) |\n' - '| | as "del ' - 's[:]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.copy()" | creates a shallow ' - 'copy of "s" | (5) |\n' - '| | (same as ' - '"s[:]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.extend(t)" or "s += t" | extends *s* with ' - 'the contents of | |\n' - '| | *t* (for the most ' - 'part the same | |\n' - '| | as ' - '"s[len(s):len(s)] = t") | ' - '|\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s *= n" | updates *s* with ' - 'its contents | (6) |\n' - '| | repeated *n* ' - 'times | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.insert(i, x)" | inserts *x* into ' - '*s* at the | |\n' - '| | index given by *i* ' - '(same as | |\n' - '| | "s[i:i] = ' - '[x]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.pop([i])" | retrieves the item ' - 'at *i* and | (2) |\n' - '| | also removes it ' - 'from *s* | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.remove(x)" | remove the first ' - 'item from *s* | (3) |\n' - '| | where "s[i] == ' - 'x" | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.reverse()" | reverses the items ' - 'of *s* in | (4) |\n' - '| | ' - 'place ' - '| |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '\n' - 'Notes:\n' - '\n' - '1. *t* must have the same length as the slice it is ' - 'replacing.\n' - '\n' - '2. The optional argument *i* defaults to "-1", so that ' - 'by default\n' - ' the last item is removed and returned.\n' - '\n' - '3. "remove" raises "ValueError" when *x* is not found ' - 'in *s*.\n' - '\n' - '4. The "reverse()" method modifies the sequence in ' - 'place for\n' - ' economy of space when reversing a large sequence. ' - 'To remind users\n' - ' that it operates by side effect, it does not return ' - 'the reversed\n' - ' sequence.\n' - '\n' - '5. "clear()" and "copy()" are included for consistency ' - 'with the\n' - " interfaces of mutable containers that don't support " - 'slicing\n' - ' operations (such as "dict" and "set")\n' - '\n' - ' New in version 3.3: "clear()" and "copy()" ' - 'methods.\n' - '\n' - '6. The value *n* is an integer, or an object ' - 'implementing\n' - ' "__index__()". Zero and negative values of *n* ' - 'clear the sequence.\n' - ' Items in the sequence are not copied; they are ' - 'referenced multiple\n' - ' times, as explained for "s * n" under *Common ' - 'Sequence Operations*.\n', - 'unary': '\n' - 'Unary arithmetic and bitwise operations\n' - '***************************************\n' - '\n' - 'All unary arithmetic and bitwise operations have the same ' - 'priority:\n' - '\n' - ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n' - '\n' - 'The unary "-" (minus) operator yields the negation of its ' - 'numeric\n' - 'argument.\n' - '\n' - 'The unary "+" (plus) operator yields its numeric argument ' - 'unchanged.\n' - '\n' - 'The unary "~" (invert) operator yields the bitwise inversion of ' - 'its\n' - 'integer argument. The bitwise inversion of "x" is defined as\n' - '"-(x+1)". It only applies to integral numbers.\n' - '\n' - 'In all three cases, if the argument does not have the proper ' - 'type, a\n' - '"TypeError" exception is raised.\n', - 'while': '\n' - 'The "while" statement\n' - '*********************\n' - '\n' - 'The "while" statement is used for repeated execution as long as ' - 'an\n' - 'expression is true:\n' - '\n' - ' while_stmt ::= "while" expression ":" suite\n' - ' ["else" ":" suite]\n' - '\n' - 'This repeatedly tests the expression and, if it is true, executes ' - 'the\n' - 'first suite; if the expression is false (which may be the first ' - 'time\n' - 'it is tested) the suite of the "else" clause, if present, is ' - 'executed\n' - 'and the loop terminates.\n' - '\n' - 'A "break" statement executed in the first suite terminates the ' - 'loop\n' - 'without executing the "else" clause\'s suite. A "continue" ' - 'statement\n' - 'executed in the first suite skips the rest of the suite and goes ' - 'back\n' - 'to testing the expression.\n', - 'with': '\n' - 'The "with" statement\n' - '********************\n' - '\n' - 'The "with" statement is used to wrap the execution of a block ' - 'with\n' - 'methods defined by a context manager (see section *With Statement\n' - 'Context Managers*). This allows common ' - '"try"..."except"..."finally"\n' - 'usage patterns to be encapsulated for convenient reuse.\n' - '\n' - ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' - ' with_item ::= expression ["as" target]\n' - '\n' - 'The execution of the "with" statement with one "item" proceeds as\n' - 'follows:\n' - '\n' - '1. The context expression (the expression given in the ' - '"with_item")\n' - ' is evaluated to obtain a context manager.\n' - '\n' - '2. The context manager\'s "__exit__()" is loaded for later use.\n' - '\n' - '3. The context manager\'s "__enter__()" method is invoked.\n' - '\n' - '4. If a target was included in the "with" statement, the return\n' - ' value from "__enter__()" is assigned to it.\n' - '\n' - ' Note: The "with" statement guarantees that if the ' - '"__enter__()"\n' - ' method returns without an error, then "__exit__()" will ' - 'always be\n' - ' called. Thus, if an error occurs during the assignment to ' - 'the\n' - ' target list, it will be treated the same as an error ' - 'occurring\n' - ' within the suite would be. See step 6 below.\n' - '\n' - '5. The suite is executed.\n' - '\n' - '6. The context manager\'s "__exit__()" method is invoked. If an\n' - ' exception caused the suite to be exited, its type, value, and\n' - ' traceback are passed as arguments to "__exit__()". Otherwise, ' - 'three\n' - ' "None" arguments are supplied.\n' - '\n' - ' If the suite was exited due to an exception, and the return ' - 'value\n' - ' from the "__exit__()" method was false, the exception is ' - 'reraised.\n' - ' If the return value was true, the exception is suppressed, and\n' - ' execution continues with the statement following the "with"\n' - ' statement.\n' - '\n' - ' If the suite was exited for any reason other than an exception, ' - 'the\n' - ' return value from "__exit__()" is ignored, and execution ' - 'proceeds\n' - ' at the normal location for the kind of exit that was taken.\n' - '\n' - 'With more than one item, the context managers are processed as if\n' - 'multiple "with" statements were nested:\n' - '\n' - ' with A() as a, B() as b:\n' - ' suite\n' - '\n' - 'is equivalent to\n' - '\n' - ' with A() as a:\n' - ' with B() as b:\n' - ' suite\n' - '\n' - 'Changed in version 3.1: Support for multiple context expressions.\n' - '\n' - 'See also: **PEP 0343** - The "with" statement\n' - '\n' - ' The specification, background, and examples for the Python ' - '"with"\n' - ' statement.\n', - 'yield': '\n' - 'The "yield" statement\n' - '*********************\n' - '\n' - ' yield_stmt ::= yield_expression\n' - '\n' - 'A "yield" statement is semantically equivalent to a *yield\n' - 'expression*. The yield statement can be used to omit the ' - 'parentheses\n' - 'that would otherwise be required in the equivalent yield ' - 'expression\n' - 'statement. For example, the yield statements\n' - '\n' - ' yield \n' - ' yield from \n' - '\n' - 'are equivalent to the yield expression statements\n' - '\n' - ' (yield )\n' - ' (yield from )\n' - '\n' - 'Yield expressions and statements are only used when defining a\n' - '*generator* function, and are only used in the body of the ' - 'generator\n' - 'function. Using yield in a function definition is sufficient to ' - 'cause\n' - 'that definition to create a generator function instead of a ' - 'normal\n' - 'function.\n' - '\n' - 'For full details of "yield" semantics, refer to the *Yield\n' - 'expressions* section.\n'} +# Autogenerated by Sphinx on Wed Aug 9 00:06:25 2017 +topics = {'assert': u'\nThe "assert" statement\n**********************\n\nAssert statements are a convenient way to insert debugging assertions\ninto a program:\n\n assert_stmt ::= "assert" expression ["," expression]\n\nThe simple form, "assert expression", is equivalent to\n\n if __debug__:\n if not expression: raise AssertionError\n\nThe extended form, "assert expression1, expression2", is equivalent to\n\n if __debug__:\n if not expression1: raise AssertionError(expression2)\n\nThese equivalences assume that "__debug__" and "AssertionError" refer\nto the built-in variables with those names. In the current\nimplementation, the built-in variable "__debug__" is "True" under\nnormal circumstances, "False" when optimization is requested (command\nline option -O). The current code generator emits no code for an\nassert statement when optimization is requested at compile time. Note\nthat it is unnecessary to include the source code for the expression\nthat failed in the error message; it will be displayed as part of the\nstack trace.\n\nAssignments to "__debug__" are illegal. The value for the built-in\nvariable is determined when the interpreter starts.\n', + 'assignment': u'\nAssignment statements\n*********************\n\nAssignment statements are used to (re)bind names to values and to\nmodify attributes or items of mutable objects:\n\n assignment_stmt ::= (target_list "=")+ (expression_list | yield_expression)\n target_list ::= target ("," target)* [","]\n target ::= identifier\n | "(" target_list ")"\n | "[" target_list "]"\n | attributeref\n | subscription\n | slicing\n | "*" target\n\n(See section *Primaries* for the syntax definitions for\n*attributeref*, *subscription*, and *slicing*.)\n\nAn assignment statement evaluates the expression list (remember that\nthis can be a single expression or a comma-separated list, the latter\nyielding a tuple) and assigns the single resulting object to each of\nthe target lists, from left to right.\n\nAssignment is defined recursively depending on the form of the target\n(list). When a target is part of a mutable object (an attribute\nreference, subscription or slicing), the mutable object must\nultimately perform the assignment and decide about its validity, and\nmay raise an exception if the assignment is unacceptable. The rules\nobserved by various types and the exceptions raised are given with the\ndefinition of the object types (see section *The standard type\nhierarchy*).\n\nAssignment of an object to a target list, optionally enclosed in\nparentheses or square brackets, is recursively defined as follows.\n\n* If the target list is a single target: The object is assigned to\n that target.\n\n* If the target list is a comma-separated list of targets: The\n object must be an iterable with the same number of items as there\n are targets in the target list, and the items are assigned, from\n left to right, to the corresponding targets.\n\n * If the target list contains one target prefixed with an\n asterisk, called a "starred" target: The object must be a sequence\n with at least as many items as there are targets in the target\n list, minus one. The first items of the sequence are assigned,\n from left to right, to the targets before the starred target. The\n final items of the sequence are assigned to the targets after the\n starred target. A list of the remaining items in the sequence is\n then assigned to the starred target (the list can be empty).\n\n * Else: The object must be a sequence with the same number of\n items as there are targets in the target list, and the items are\n assigned, from left to right, to the corresponding targets.\n\nAssignment of an object to a single target is recursively defined as\nfollows.\n\n* If the target is an identifier (name):\n\n * If the name does not occur in a "global" or "nonlocal" statement\n in the current code block: the name is bound to the object in the\n current local namespace.\n\n * Otherwise: the name is bound to the object in the global\n namespace or the outer namespace determined by "nonlocal",\n respectively.\n\n The name is rebound if it was already bound. This may cause the\n reference count for the object previously bound to the name to reach\n zero, causing the object to be deallocated and its destructor (if it\n has one) to be called.\n\n* If the target is a target list enclosed in parentheses or in\n square brackets: The object must be an iterable with the same number\n of items as there are targets in the target list, and its items are\n assigned, from left to right, to the corresponding targets.\n\n* If the target is an attribute reference: The primary expression in\n the reference is evaluated. It should yield an object with\n assignable attributes; if this is not the case, "TypeError" is\n raised. That object is then asked to assign the assigned object to\n the given attribute; if it cannot perform the assignment, it raises\n an exception (usually but not necessarily "AttributeError").\n\n Note: If the object is a class instance and the attribute reference\n occurs on both sides of the assignment operator, the RHS expression,\n "a.x" can access either an instance attribute or (if no instance\n attribute exists) a class attribute. The LHS target "a.x" is always\n set as an instance attribute, creating it if necessary. Thus, the\n two occurrences of "a.x" do not necessarily refer to the same\n attribute: if the RHS expression refers to a class attribute, the\n LHS creates a new instance attribute as the target of the\n assignment:\n\n class Cls:\n x = 3 # class variable\n inst = Cls()\n inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x as 3\n\n This description does not necessarily apply to descriptor\n attributes, such as properties created with "property()".\n\n* If the target is a subscription: The primary expression in the\n reference is evaluated. It should yield either a mutable sequence\n object (such as a list) or a mapping object (such as a dictionary).\n Next, the subscript expression is evaluated.\n\n If the primary is a mutable sequence object (such as a list), the\n subscript must yield an integer. If it is negative, the sequence\'s\n length is added to it. The resulting value must be a nonnegative\n integer less than the sequence\'s length, and the sequence is asked\n to assign the assigned object to its item with that index. If the\n index is out of range, "IndexError" is raised (assignment to a\n subscripted sequence cannot add new items to a list).\n\n If the primary is a mapping object (such as a dictionary), the\n subscript must have a type compatible with the mapping\'s key type,\n and the mapping is then asked to create a key/datum pair which maps\n the subscript to the assigned object. This can either replace an\n existing key/value pair with the same key value, or insert a new\n key/value pair (if no key with the same value existed).\n\n For user-defined objects, the "__setitem__()" method is called with\n appropriate arguments.\n\n* If the target is a slicing: The primary expression in the\n reference is evaluated. It should yield a mutable sequence object\n (such as a list). The assigned object should be a sequence object\n of the same type. Next, the lower and upper bound expressions are\n evaluated, insofar they are present; defaults are zero and the\n sequence\'s length. The bounds should evaluate to integers. If\n either bound is negative, the sequence\'s length is added to it. The\n resulting bounds are clipped to lie between zero and the sequence\'s\n length, inclusive. Finally, the sequence object is asked to replace\n the slice with the items of the assigned sequence. The length of\n the slice may be different from the length of the assigned sequence,\n thus changing the length of the target sequence, if the target\n sequence allows it.\n\n**CPython implementation detail:** In the current implementation, the\nsyntax for targets is taken to be the same as for expressions, and\ninvalid syntax is rejected during the code generation phase, causing\nless detailed error messages.\n\nAlthough the definition of assignment implies that overlaps between\nthe left-hand side and the right-hand side are \'simultanenous\' (for\nexample "a, b = b, a" swaps two variables), overlaps *within* the\ncollection of assigned-to variables occur left-to-right, sometimes\nresulting in confusion. For instance, the following program prints\n"[0, 2]":\n\n x = [0, 1]\n i = 0\n i, x[i] = 1, 2 # i is updated, then x[i] is updated\n print(x)\n\nSee also: **PEP 3132** - Extended Iterable Unpacking\n\n The specification for the "*target" feature.\n\n\nAugmented assignment statements\n===============================\n\nAugmented assignment is the combination, in a single statement, of a\nbinary operation and an assignment statement:\n\n augmented_assignment_stmt ::= augtarget augop (expression_list | yield_expression)\n augtarget ::= identifier | attributeref | subscription | slicing\n augop ::= "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="\n | ">>=" | "<<=" | "&=" | "^=" | "|="\n\n(See section *Primaries* for the syntax definitions of the last three\nsymbols.)\n\nAn augmented assignment evaluates the target (which, unlike normal\nassignment statements, cannot be an unpacking) and the expression\nlist, performs the binary operation specific to the type of assignment\non the two operands, and assigns the result to the original target.\nThe target is only evaluated once.\n\nAn augmented assignment expression like "x += 1" can be rewritten as\n"x = x + 1" to achieve a similar, but not exactly equal effect. In the\naugmented version, "x" is only evaluated once. Also, when possible,\nthe actual operation is performed *in-place*, meaning that rather than\ncreating a new object and assigning that to the target, the old object\nis modified instead.\n\nUnlike normal assignments, augmented assignments evaluate the left-\nhand side *before* evaluating the right-hand side. For example, "a[i]\n+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and performs\nthe addition, and lastly, it writes the result back to "a[i]".\n\nWith the exception of assigning to tuples and multiple targets in a\nsingle statement, the assignment done by augmented assignment\nstatements is handled the same way as normal assignments. Similarly,\nwith the exception of the possible *in-place* behavior, the binary\noperation performed by augmented assignment is the same as the normal\nbinary operations.\n\nFor targets which are attribute references, the same *caveat about\nclass and instance attributes* applies as for regular assignments.\n', + 'atom-identifiers': u'\nIdentifiers (Names)\n*******************\n\nAn identifier occurring as an atom is a name. See section\n*Identifiers and keywords* for lexical definition and section *Naming\nand binding* for documentation of naming and binding.\n\nWhen the name is bound to an object, evaluation of the atom yields\nthat object. When a name is not bound, an attempt to evaluate it\nraises a "NameError" exception.\n\n**Private name mangling:** When an identifier that textually occurs in\na class definition begins with two or more underscore characters and\ndoes not end in two or more underscores, it is considered a *private\nname* of that class. Private names are transformed to a longer form\nbefore code is generated for them. The transformation inserts the\nclass name, with leading underscores removed and a single underscore\ninserted, in front of the name. For example, the identifier "__spam"\noccurring in a class named "Ham" will be transformed to "_Ham__spam".\nThis transformation is independent of the syntactical context in which\nthe identifier is used. If the transformed name is extremely long\n(longer than 255 characters), implementation defined truncation may\nhappen. If the class name consists only of underscores, no\ntransformation is done.\n', + 'atom-literals': u"\nLiterals\n********\n\nPython supports string and bytes literals and various numeric\nliterals:\n\n literal ::= stringliteral | bytesliteral\n | integer | floatnumber | imagnumber\n\nEvaluation of a literal yields an object of the given type (string,\nbytes, integer, floating point number, complex number) with the given\nvalue. The value may be approximated in the case of floating point\nand imaginary (complex) literals. See section *Literals* for details.\n\nAll literals correspond to immutable data types, and hence the\nobject's identity is less important than its value. Multiple\nevaluations of literals with the same value (either the same\noccurrence in the program text or a different occurrence) may obtain\nthe same object or a different object with the same value.\n", + 'attribute-access': u'\nCustomizing attribute access\n****************************\n\nThe following methods can be defined to customize the meaning of\nattribute access (use of, assignment to, or deletion of "x.name") for\nclass instances.\n\nobject.__getattr__(self, name)\n\n Called when an attribute lookup has not found the attribute in the\n usual places (i.e. it is not an instance attribute nor is it found\n in the class tree for "self"). "name" is the attribute name. This\n method should return the (computed) attribute value or raise an\n "AttributeError" exception.\n\n Note that if the attribute is found through the normal mechanism,\n "__getattr__()" is not called. (This is an intentional asymmetry\n between "__getattr__()" and "__setattr__()".) This is done both for\n efficiency reasons and because otherwise "__getattr__()" would have\n no way to access other attributes of the instance. Note that at\n least for instance variables, you can fake total control by not\n inserting any values in the instance attribute dictionary (but\n instead inserting them in another object). See the\n "__getattribute__()" method below for a way to actually get total\n control over attribute access.\n\nobject.__getattribute__(self, name)\n\n Called unconditionally to implement attribute accesses for\n instances of the class. If the class also defines "__getattr__()",\n the latter will not be called unless "__getattribute__()" either\n calls it explicitly or raises an "AttributeError". This method\n should return the (computed) attribute value or raise an\n "AttributeError" exception. In order to avoid infinite recursion in\n this method, its implementation should always call the base class\n method with the same name to access any attributes it needs, for\n example, "object.__getattribute__(self, name)".\n\n Note: This method may still be bypassed when looking up special\n methods as the result of implicit invocation via language syntax\n or built-in functions. See *Special method lookup*.\n\nobject.__setattr__(self, name, value)\n\n Called when an attribute assignment is attempted. This is called\n instead of the normal mechanism (i.e. store the value in the\n instance dictionary). *name* is the attribute name, *value* is the\n value to be assigned to it.\n\n If "__setattr__()" wants to assign to an instance attribute, it\n should call the base class method with the same name, for example,\n "object.__setattr__(self, name, value)".\n\nobject.__delattr__(self, name)\n\n Like "__setattr__()" but for attribute deletion instead of\n assignment. This should only be implemented if "del obj.name" is\n meaningful for the object.\n\nobject.__dir__(self)\n\n Called when "dir()" is called on the object. A sequence must be\n returned. "dir()" converts the returned sequence to a list and\n sorts it.\n\n\nImplementing Descriptors\n========================\n\nThe following methods only apply when an instance of the class\ncontaining the method (a so-called *descriptor* class) appears in an\n*owner* class (the descriptor must be in either the owner\'s class\ndictionary or in the class dictionary for one of its parents). In the\nexamples below, "the attribute" refers to the attribute whose name is\nthe key of the property in the owner class\' "__dict__".\n\nobject.__get__(self, instance, owner)\n\n Called to get the attribute of the owner class (class attribute\n access) or of an instance of that class (instance attribute\n access). *owner* is always the owner class, while *instance* is the\n instance that the attribute was accessed through, or "None" when\n the attribute is accessed through the *owner*. This method should\n return the (computed) attribute value or raise an "AttributeError"\n exception.\n\nobject.__set__(self, instance, value)\n\n Called to set the attribute on an instance *instance* of the owner\n class to a new value, *value*.\n\nobject.__delete__(self, instance)\n\n Called to delete the attribute on an instance *instance* of the\n owner class.\n\nThe attribute "__objclass__" is interpreted by the "inspect" module as\nspecifying the class where this object was defined (setting this\nappropriately can assist in runtime introspection of dynamic class\nattributes). For callables, it may indicate that an instance of the\ngiven type (or a subclass) is expected or required as the first\npositional argument (for example, CPython sets this attribute for\nunbound methods that are implemented in C).\n\n\nInvoking Descriptors\n====================\n\nIn general, a descriptor is an object attribute with "binding\nbehavior", one whose attribute access has been overridden by methods\nin the descriptor protocol: "__get__()", "__set__()", and\n"__delete__()". If any of those methods are defined for an object, it\nis said to be a descriptor.\n\nThe default behavior for attribute access is to get, set, or delete\nthe attribute from an object\'s dictionary. For instance, "a.x" has a\nlookup chain starting with "a.__dict__[\'x\']", then\n"type(a).__dict__[\'x\']", and continuing through the base classes of\n"type(a)" excluding metaclasses.\n\nHowever, if the looked-up value is an object defining one of the\ndescriptor methods, then Python may override the default behavior and\ninvoke the descriptor method instead. Where this occurs in the\nprecedence chain depends on which descriptor methods were defined and\nhow they were called.\n\nThe starting point for descriptor invocation is a binding, "a.x". How\nthe arguments are assembled depends on "a":\n\nDirect Call\n The simplest and least common call is when user code directly\n invokes a descriptor method: "x.__get__(a)".\n\nInstance Binding\n If binding to an object instance, "a.x" is transformed into the\n call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n\nClass Binding\n If binding to a class, "A.x" is transformed into the call:\n "A.__dict__[\'x\'].__get__(None, A)".\n\nSuper Binding\n If "a" is an instance of "super", then the binding "super(B,\n obj).m()" searches "obj.__class__.__mro__" for the base class "A"\n immediately preceding "B" and then invokes the descriptor with the\n call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n\nFor instance bindings, the precedence of descriptor invocation depends\non the which descriptor methods are defined. A descriptor can define\nany combination of "__get__()", "__set__()" and "__delete__()". If it\ndoes not define "__get__()", then accessing the attribute will return\nthe descriptor object itself unless there is a value in the object\'s\ninstance dictionary. If the descriptor defines "__set__()" and/or\n"__delete__()", it is a data descriptor; if it defines neither, it is\na non-data descriptor. Normally, data descriptors define both\n"__get__()" and "__set__()", while non-data descriptors have just the\n"__get__()" method. Data descriptors with "__set__()" and "__get__()"\ndefined always override a redefinition in an instance dictionary. In\ncontrast, non-data descriptors can be overridden by instances.\n\nPython methods (including "staticmethod()" and "classmethod()") are\nimplemented as non-data descriptors. Accordingly, instances can\nredefine and override methods. This allows individual instances to\nacquire behaviors that differ from other instances of the same class.\n\nThe "property()" function is implemented as a data descriptor.\nAccordingly, instances cannot override the behavior of a property.\n\n\n__slots__\n=========\n\nBy default, instances of classes have a dictionary for attribute\nstorage. This wastes space for objects having very few instance\nvariables. The space consumption can become acute when creating large\nnumbers of instances.\n\nThe default can be overridden by defining *__slots__* in a class\ndefinition. The *__slots__* declaration takes a sequence of instance\nvariables and reserves just enough space in each instance to hold a\nvalue for each variable. Space is saved because *__dict__* is not\ncreated for each instance.\n\nobject.__slots__\n\n This class variable can be assigned a string, iterable, or sequence\n of strings with variable names used by instances. *__slots__*\n reserves space for the declared variables and prevents the\n automatic creation of *__dict__* and *__weakref__* for each\n instance.\n\n\nNotes on using *__slots__*\n--------------------------\n\n* When inheriting from a class without *__slots__*, the *__dict__*\n attribute of that class will always be accessible, so a *__slots__*\n definition in the subclass is meaningless.\n\n* Without a *__dict__* variable, instances cannot be assigned new\n variables not listed in the *__slots__* definition. Attempts to\n assign to an unlisted variable name raises "AttributeError". If\n dynamic assignment of new variables is desired, then add\n "\'__dict__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* Without a *__weakref__* variable for each instance, classes\n defining *__slots__* do not support weak references to its\n instances. If weak reference support is needed, then add\n "\'__weakref__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* *__slots__* are implemented at the class level by creating\n descriptors (*Implementing Descriptors*) for each variable name. As\n a result, class attributes cannot be used to set default values for\n instance variables defined by *__slots__*; otherwise, the class\n attribute would overwrite the descriptor assignment.\n\n* The action of a *__slots__* declaration is limited to the class\n where it is defined. As a result, subclasses will have a *__dict__*\n unless they also define *__slots__* (which must only contain names\n of any *additional* slots).\n\n* If a class defines a slot also defined in a base class, the\n instance variable defined by the base class slot is inaccessible\n (except by retrieving its descriptor directly from the base class).\n This renders the meaning of the program undefined. In the future, a\n check may be added to prevent this.\n\n* Nonempty *__slots__* does not work for classes derived from\n "variable-length" built-in types such as "int", "bytes" and "tuple".\n\n* Any non-string iterable may be assigned to *__slots__*. Mappings\n may also be used; however, in the future, special meaning may be\n assigned to the values corresponding to each key.\n\n* *__class__* assignment works only if both classes have the same\n *__slots__*.\n', + 'attribute-references': u'\nAttribute references\n********************\n\nAn attribute reference is a primary followed by a period and a name:\n\n attributeref ::= primary "." identifier\n\nThe primary must evaluate to an object of a type that supports\nattribute references, which most objects do. This object is then\nasked to produce the attribute whose name is the identifier. This\nproduction can be customized by overriding the "__getattr__()" method.\nIf this attribute is not available, the exception "AttributeError" is\nraised. Otherwise, the type and value of the object produced is\ndetermined by the object. Multiple evaluations of the same attribute\nreference may yield different objects.\n', + 'augassign': u'\nAugmented assignment statements\n*******************************\n\nAugmented assignment is the combination, in a single statement, of a\nbinary operation and an assignment statement:\n\n augmented_assignment_stmt ::= augtarget augop (expression_list | yield_expression)\n augtarget ::= identifier | attributeref | subscription | slicing\n augop ::= "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="\n | ">>=" | "<<=" | "&=" | "^=" | "|="\n\n(See section *Primaries* for the syntax definitions of the last three\nsymbols.)\n\nAn augmented assignment evaluates the target (which, unlike normal\nassignment statements, cannot be an unpacking) and the expression\nlist, performs the binary operation specific to the type of assignment\non the two operands, and assigns the result to the original target.\nThe target is only evaluated once.\n\nAn augmented assignment expression like "x += 1" can be rewritten as\n"x = x + 1" to achieve a similar, but not exactly equal effect. In the\naugmented version, "x" is only evaluated once. Also, when possible,\nthe actual operation is performed *in-place*, meaning that rather than\ncreating a new object and assigning that to the target, the old object\nis modified instead.\n\nUnlike normal assignments, augmented assignments evaluate the left-\nhand side *before* evaluating the right-hand side. For example, "a[i]\n+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and performs\nthe addition, and lastly, it writes the result back to "a[i]".\n\nWith the exception of assigning to tuples and multiple targets in a\nsingle statement, the assignment done by augmented assignment\nstatements is handled the same way as normal assignments. Similarly,\nwith the exception of the possible *in-place* behavior, the binary\noperation performed by augmented assignment is the same as the normal\nbinary operations.\n\nFor targets which are attribute references, the same *caveat about\nclass and instance attributes* applies as for regular assignments.\n', + 'binary': u'\nBinary arithmetic operations\n****************************\n\nThe binary arithmetic operations have the conventional priority\nlevels. Note that some of these operations also apply to certain non-\nnumeric types. Apart from the power operator, there are only two\nlevels, one for multiplicative operators and one for additive\noperators:\n\n m_expr ::= u_expr | m_expr "*" u_expr | m_expr "//" u_expr | m_expr "/" u_expr\n | m_expr "%" u_expr\n a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n\nThe "*" (multiplication) operator yields the product of its arguments.\nThe arguments must either both be numbers, or one argument must be an\ninteger and the other must be a sequence. In the former case, the\nnumbers are converted to a common type and then multiplied together.\nIn the latter case, sequence repetition is performed; a negative\nrepetition factor yields an empty sequence.\n\nThe "/" (division) and "//" (floor division) operators yield the\nquotient of their arguments. The numeric arguments are first\nconverted to a common type. Division of integers yields a float, while\nfloor division of integers results in an integer; the result is that\nof mathematical division with the \'floor\' function applied to the\nresult. Division by zero raises the "ZeroDivisionError" exception.\n\nThe "%" (modulo) operator yields the remainder from the division of\nthe first argument by the second. The numeric arguments are first\nconverted to a common type. A zero right argument raises the\n"ZeroDivisionError" exception. The arguments may be floating point\nnumbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals "4*0.7 +\n0.34".) The modulo operator always yields a result with the same sign\nas its second operand (or zero); the absolute value of the result is\nstrictly smaller than the absolute value of the second operand [1].\n\nThe floor division and modulo operators are connected by the following\nidentity: "x == (x//y)*y + (x%y)". Floor division and modulo are also\nconnected with the built-in function "divmod()": "divmod(x, y) ==\n(x//y, x%y)". [2].\n\nIn addition to performing the modulo operation on numbers, the "%"\noperator is also overloaded by string objects to perform old-style\nstring formatting (also known as interpolation). The syntax for\nstring formatting is described in the Python Library Reference,\nsection *printf-style String Formatting*.\n\nThe floor division operator, the modulo operator, and the "divmod()"\nfunction are not defined for complex numbers. Instead, convert to a\nfloating point number using the "abs()" function if appropriate.\n\nThe "+" (addition) operator yields the sum of its arguments. The\narguments must either both be numbers or both be sequences of the same\ntype. In the former case, the numbers are converted to a common type\nand then added together. In the latter case, the sequences are\nconcatenated.\n\nThe "-" (subtraction) operator yields the difference of its arguments.\nThe numeric arguments are first converted to a common type.\n', + 'bitwise': u'\nBinary bitwise operations\n*************************\n\nEach of the three bitwise operations has a different priority level:\n\n and_expr ::= shift_expr | and_expr "&" shift_expr\n xor_expr ::= and_expr | xor_expr "^" and_expr\n or_expr ::= xor_expr | or_expr "|" xor_expr\n\nThe "&" operator yields the bitwise AND of its arguments, which must\nbe integers.\n\nThe "^" operator yields the bitwise XOR (exclusive OR) of its\narguments, which must be integers.\n\nThe "|" operator yields the bitwise (inclusive) OR of its arguments,\nwhich must be integers.\n', + 'bltin-code-objects': u'\nCode Objects\n************\n\nCode objects are used by the implementation to represent "pseudo-\ncompiled" executable Python code such as a function body. They differ\nfrom function objects because they don\'t contain a reference to their\nglobal execution environment. Code objects are returned by the built-\nin "compile()" function and can be extracted from function objects\nthrough their "__code__" attribute. See also the "code" module.\n\nA code object can be executed or evaluated by passing it (instead of a\nsource string) to the "exec()" or "eval()" built-in functions.\n\nSee *The standard type hierarchy* for more information.\n', + 'bltin-ellipsis-object': u'\nThe Ellipsis Object\n*******************\n\nThis object is commonly used by slicing (see *Slicings*). It supports\nno special operations. There is exactly one ellipsis object, named\n"Ellipsis" (a built-in name). "type(Ellipsis)()" produces the\n"Ellipsis" singleton.\n\nIt is written as "Ellipsis" or "...".\n', + 'bltin-null-object': u'\nThe Null Object\n***************\n\nThis object is returned by functions that don\'t explicitly return a\nvalue. It supports no special operations. There is exactly one null\nobject, named "None" (a built-in name). "type(None)()" produces the\nsame singleton.\n\nIt is written as "None".\n', + 'bltin-type-objects': u'\nType Objects\n************\n\nType objects represent the various object types. An object\'s type is\naccessed by the built-in function "type()". There are no special\noperations on types. The standard module "types" defines names for\nall standard built-in types.\n\nTypes are written like this: "".\n', + 'booleans': u'\nBoolean operations\n******************\n\n or_test ::= and_test | or_test "or" and_test\n and_test ::= not_test | and_test "and" not_test\n not_test ::= comparison | "not" not_test\n\nIn the context of Boolean operations, and also when expressions are\nused by control flow statements, the following values are interpreted\nas false: "False", "None", numeric zero of all types, and empty\nstrings and containers (including strings, tuples, lists,\ndictionaries, sets and frozensets). All other values are interpreted\nas true. User-defined objects can customize their truth value by\nproviding a "__bool__()" method.\n\nThe operator "not" yields "True" if its argument is false, "False"\notherwise.\n\nThe expression "x and y" first evaluates *x*; if *x* is false, its\nvalue is returned; otherwise, *y* is evaluated and the resulting value\nis returned.\n\nThe expression "x or y" first evaluates *x*; if *x* is true, its value\nis returned; otherwise, *y* is evaluated and the resulting value is\nreturned.\n\n(Note that neither "and" nor "or" restrict the value and type they\nreturn to "False" and "True", but rather return the last evaluated\nargument. This is sometimes useful, e.g., if "s" is a string that\nshould be replaced by a default value if it is empty, the expression\n"s or \'foo\'" yields the desired value. Because "not" has to create a\nnew value, it returns a boolean value regardless of the type of its\nargument (for example, "not \'foo\'" produces "False" rather than "\'\'".)\n', + 'break': u'\nThe "break" statement\n*********************\n\n break_stmt ::= "break"\n\n"break" may only occur syntactically nested in a "for" or "while"\nloop, but not nested in a function or class definition within that\nloop.\n\nIt terminates the nearest enclosing loop, skipping the optional "else"\nclause if the loop has one.\n\nIf a "for" loop is terminated by "break", the loop control target\nkeeps its current value.\n\nWhen "break" passes control out of a "try" statement with a "finally"\nclause, that "finally" clause is executed before really leaving the\nloop.\n', + 'callable-types': u'\nEmulating callable objects\n**************************\n\nobject.__call__(self[, args...])\n\n Called when the instance is "called" as a function; if this method\n is defined, "x(arg1, arg2, ...)" is a shorthand for\n "x.__call__(arg1, arg2, ...)".\n', + 'calls': u'\nCalls\n*****\n\nA call calls a callable object (e.g., a *function*) with a possibly\nempty series of *arguments*:\n\n call ::= primary "(" [argument_list [","] | comprehension] ")"\n argument_list ::= positional_arguments ["," keyword_arguments]\n ["," "*" expression] ["," keyword_arguments]\n ["," "**" expression]\n | keyword_arguments ["," "*" expression]\n ["," keyword_arguments] ["," "**" expression]\n | "*" expression ["," keyword_arguments] ["," "**" expression]\n | "**" expression\n positional_arguments ::= expression ("," expression)*\n keyword_arguments ::= keyword_item ("," keyword_item)*\n keyword_item ::= identifier "=" expression\n\nAn optional trailing comma may be present after the positional and\nkeyword arguments but does not affect the semantics.\n\nThe primary must evaluate to a callable object (user-defined\nfunctions, built-in functions, methods of built-in objects, class\nobjects, methods of class instances, and all objects having a\n"__call__()" method are callable). All argument expressions are\nevaluated before the call is attempted. Please refer to section\n*Function definitions* for the syntax of formal *parameter* lists.\n\nIf keyword arguments are present, they are first converted to\npositional arguments, as follows. First, a list of unfilled slots is\ncreated for the formal parameters. If there are N positional\narguments, they are placed in the first N slots. Next, for each\nkeyword argument, the identifier is used to determine the\ncorresponding slot (if the identifier is the same as the first formal\nparameter name, the first slot is used, and so on). If the slot is\nalready filled, a "TypeError" exception is raised. Otherwise, the\nvalue of the argument is placed in the slot, filling it (even if the\nexpression is "None", it fills the slot). When all arguments have\nbeen processed, the slots that are still unfilled are filled with the\ncorresponding default value from the function definition. (Default\nvalues are calculated, once, when the function is defined; thus, a\nmutable object such as a list or dictionary used as default value will\nbe shared by all calls that don\'t specify an argument value for the\ncorresponding slot; this should usually be avoided.) If there are any\nunfilled slots for which no default value is specified, a "TypeError"\nexception is raised. Otherwise, the list of filled slots is used as\nthe argument list for the call.\n\n**CPython implementation detail:** An implementation may provide\nbuilt-in functions whose positional parameters do not have names, even\nif they are \'named\' for the purpose of documentation, and which\ntherefore cannot be supplied by keyword. In CPython, this is the case\nfor functions implemented in C that use "PyArg_ParseTuple()" to parse\ntheir arguments.\n\nIf there are more positional arguments than there are formal parameter\nslots, a "TypeError" exception is raised, unless a formal parameter\nusing the syntax "*identifier" is present; in this case, that formal\nparameter receives a tuple containing the excess positional arguments\n(or an empty tuple if there were no excess positional arguments).\n\nIf any keyword argument does not correspond to a formal parameter\nname, a "TypeError" exception is raised, unless a formal parameter\nusing the syntax "**identifier" is present; in this case, that formal\nparameter receives a dictionary containing the excess keyword\narguments (using the keywords as keys and the argument values as\ncorresponding values), or a (new) empty dictionary if there were no\nexcess keyword arguments.\n\nIf the syntax "*expression" appears in the function call, "expression"\nmust evaluate to an iterable. Elements from this iterable are treated\nas if they were additional positional arguments; if there are\npositional arguments *x1*, ..., *xN*, and "expression" evaluates to a\nsequence *y1*, ..., *yM*, this is equivalent to a call with M+N\npositional arguments *x1*, ..., *xN*, *y1*, ..., *yM*.\n\nA consequence of this is that although the "*expression" syntax may\nappear *after* some keyword arguments, it is processed *before* the\nkeyword arguments (and the "**expression" argument, if any -- see\nbelow). So:\n\n >>> def f(a, b):\n ... print(a, b)\n ...\n >>> f(b=1, *(2,))\n 2 1\n >>> f(a=1, *(2,))\n Traceback (most recent call last):\n File "", line 1, in ?\n TypeError: f() got multiple values for keyword argument \'a\'\n >>> f(1, *(2,))\n 1 2\n\nIt is unusual for both keyword arguments and the "*expression" syntax\nto be used in the same call, so in practice this confusion does not\narise.\n\nIf the syntax "**expression" appears in the function call,\n"expression" must evaluate to a mapping, the contents of which are\ntreated as additional keyword arguments. In the case of a keyword\nappearing in both "expression" and as an explicit keyword argument, a\n"TypeError" exception is raised.\n\nFormal parameters using the syntax "*identifier" or "**identifier"\ncannot be used as positional argument slots or as keyword argument\nnames.\n\nA call always returns some value, possibly "None", unless it raises an\nexception. How this value is computed depends on the type of the\ncallable object.\n\nIf it is---\n\na user-defined function:\n The code block for the function is executed, passing it the\n argument list. The first thing the code block will do is bind the\n formal parameters to the arguments; this is described in section\n *Function definitions*. When the code block executes a "return"\n statement, this specifies the return value of the function call.\n\na built-in function or method:\n The result is up to the interpreter; see *Built-in Functions* for\n the descriptions of built-in functions and methods.\n\na class object:\n A new instance of that class is returned.\n\na class instance method:\n The corresponding user-defined function is called, with an argument\n list that is one longer than the argument list of the call: the\n instance becomes the first argument.\n\na class instance:\n The class must define a "__call__()" method; the effect is then the\n same as if that method was called.\n', + 'class': u'\nClass definitions\n*****************\n\nA class definition defines a class object (see section *The standard\ntype hierarchy*):\n\n classdef ::= [decorators] "class" classname [inheritance] ":" suite\n inheritance ::= "(" [parameter_list] ")"\n classname ::= identifier\n\nA class definition is an executable statement. The inheritance list\nusually gives a list of base classes (see *Customizing class creation*\nfor more advanced uses), so each item in the list should evaluate to a\nclass object which allows subclassing. Classes without an inheritance\nlist inherit, by default, from the base class "object"; hence,\n\n class Foo:\n pass\n\nis equivalent to\n\n class Foo(object):\n pass\n\nThe class\'s suite is then executed in a new execution frame (see\n*Naming and binding*), using a newly created local namespace and the\noriginal global namespace. (Usually, the suite contains mostly\nfunction definitions.) When the class\'s suite finishes execution, its\nexecution frame is discarded but its local namespace is saved. [4] A\nclass object is then created using the inheritance list for the base\nclasses and the saved local namespace for the attribute dictionary.\nThe class name is bound to this class object in the original local\nnamespace.\n\nClass creation can be customized heavily using *metaclasses*.\n\nClasses can also be decorated: just like when decorating functions,\n\n @f1(arg)\n @f2\n class Foo: pass\n\nis equivalent to\n\n class Foo: pass\n Foo = f1(arg)(f2(Foo))\n\nThe evaluation rules for the decorator expressions are the same as for\nfunction decorators. The result must be a class object, which is then\nbound to the class name.\n\n**Programmer\'s note:** Variables defined in the class definition are\nclass attributes; they are shared by instances. Instance attributes\ncan be set in a method with "self.name = value". Both class and\ninstance attributes are accessible through the notation ""self.name"",\nand an instance attribute hides a class attribute with the same name\nwhen accessed in this way. Class attributes can be used as defaults\nfor instance attributes, but using mutable values there can lead to\nunexpected results. *Descriptors* can be used to create instance\nvariables with different implementation details.\n\nSee also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n Class Decorators\n\n-[ Footnotes ]-\n\n[1] The exception is propagated to the invocation stack unless\n there is a "finally" clause which happens to raise another\n exception. That new exception causes the old one to be lost.\n\n[2] Currently, control "flows off the end" except in the case of\n an exception or the execution of a "return", "continue", or\n "break" statement.\n\n[3] A string literal appearing as the first statement in the\n function body is transformed into the function\'s "__doc__"\n attribute and therefore the function\'s *docstring*.\n\n[4] A string literal appearing as the first statement in the class\n body is transformed into the namespace\'s "__doc__" item and\n therefore the class\'s *docstring*.\n', + 'comparisons': u'\nComparisons\n***********\n\nUnlike C, all comparison operations in Python have the same priority,\nwhich is lower than that of any arithmetic, shifting or bitwise\noperation. Also unlike C, expressions like "a < b < c" have the\ninterpretation that is conventional in mathematics:\n\n comparison ::= or_expr ( comp_operator or_expr )*\n comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n | "is" ["not"] | ["not"] "in"\n\nComparisons yield boolean values: "True" or "False".\n\nComparisons can be chained arbitrarily, e.g., "x < y <= z" is\nequivalent to "x < y and y <= z", except that "y" is evaluated only\nonce (but in both cases "z" is not evaluated at all when "x < y" is\nfound to be false).\n\nFormally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*,\n*op2*, ..., *opN* are comparison operators, then "a op1 b op2 c ... y\nopN z" is equivalent to "a op1 b and b op2 c and ... y opN z", except\nthat each expression is evaluated at most once.\n\nNote that "a op1 b op2 c" doesn\'t imply any kind of comparison between\n*a* and *c*, so that, e.g., "x < y > z" is perfectly legal (though\nperhaps not pretty).\n\n\nValue comparisons\n=================\n\nThe operators "<", ">", "==", ">=", "<=", and "!=" compare the values\nof two objects. The objects do not need to have the same type.\n\nChapter *Objects, values and types* states that objects have a value\n(in addition to type and identity). The value of an object is a\nrather abstract notion in Python: For example, there is no canonical\naccess method for an object\'s value. Also, there is no requirement\nthat the value of an object should be constructed in a particular way,\ne.g. comprised of all its data attributes. Comparison operators\nimplement a particular notion of what the value of an object is. One\ncan think of them as defining the value of an object indirectly, by\nmeans of their comparison implementation.\n\nBecause all types are (direct or indirect) subtypes of "object", they\ninherit the default comparison behavior from "object". Types can\ncustomize their comparison behavior by implementing *rich comparison\nmethods* like "__lt__()", described in *Basic customization*.\n\nThe default behavior for equality comparison ("==" and "!=") is based\non the identity of the objects. Hence, equality comparison of\ninstances with the same identity results in equality, and equality\ncomparison of instances with different identities results in\ninequality. A motivation for this default behavior is the desire that\nall objects should be reflexive (i.e. "x is y" implies "x == y").\n\nA default order comparison ("<", ">", "<=", and ">=") is not provided;\nan attempt raises "TypeError". A motivation for this default behavior\nis the lack of a similar invariant as for equality.\n\nThe behavior of the default equality comparison, that instances with\ndifferent identities are always unequal, may be in contrast to what\ntypes will need that have a sensible definition of object value and\nvalue-based equality. Such types will need to customize their\ncomparison behavior, and in fact, a number of built-in types have done\nthat.\n\nThe following list describes the comparison behavior of the most\nimportant built-in types.\n\n* Numbers of built-in numeric types (*Numeric Types --- int, float,\n complex*) and of the standard library types "fractions.Fraction" and\n "decimal.Decimal" can be compared within and across their types,\n with the restriction that complex numbers do not support order\n comparison. Within the limits of the types involved, they compare\n mathematically (algorithmically) correct without loss of precision.\n\n The not-a-number values "float(\'NaN\')" and "Decimal(\'NaN\')" are\n special. They are identical to themselves ("x is x" is true) but\n are not equal to themselves ("x == x" is false). Additionally,\n comparing any number to a not-a-number value will return "False".\n For example, both "3 < float(\'NaN\')" and "float(\'NaN\') < 3" will\n return "False".\n\n* Binary sequences (instances of "bytes" or "bytearray") can be\n compared within and across their types. They compare\n lexicographically using the numeric values of their elements.\n\n* Strings (instances of "str") compare lexicographically using the\n numerical Unicode code points (the result of the built-in function\n "ord()") of their characters. [3]\n\n Strings and binary sequences cannot be directly compared.\n\n* Sequences (instances of "tuple", "list", or "range") can be\n compared only within each of their types, with the restriction that\n ranges do not support order comparison. Equality comparison across\n these types results in unequality, and ordering comparison across\n these types raises "TypeError".\n\n Sequences compare lexicographically using comparison of\n corresponding elements, whereby reflexivity of the elements is\n enforced.\n\n In enforcing reflexivity of elements, the comparison of collections\n assumes that for a collection element "x", "x == x" is always true.\n Based on that assumption, element identity is compared first, and\n element comparison is performed only for distinct elements. This\n approach yields the same result as a strict element comparison\n would, if the compared elements are reflexive. For non-reflexive\n elements, the result is different than for strict element\n comparison, and may be surprising: The non-reflexive not-a-number\n values for example result in the following comparison behavior when\n used in a list:\n\n >>> nan = float(\'NaN\')\n >>> nan is nan\n True\n >>> nan == nan\n False <-- the defined non-reflexive behavior of NaN\n >>> [nan] == [nan]\n True <-- list enforces reflexivity and tests identity first\n\n Lexicographical comparison between built-in collections works as\n follows:\n\n * For two collections to compare equal, they must be of the same\n type, have the same length, and each pair of corresponding\n elements must compare equal (for example, "[1,2] == (1,2)" is\n false because the type is not the same).\n\n * Collections that support order comparison are ordered the same\n as their first unequal elements (for example, "[1,2,x] <= [1,2,y]"\n has the same value as "x <= y"). If a corresponding element does\n not exist, the shorter collection is ordered first (for example,\n "[1,2] < [1,2,3]" is true).\n\n* Mappings (instances of "dict") compare equal if and only if they\n have equal *(key, value)* pairs. Equality comparison of the keys and\n elements enforces reflexivity.\n\n Order comparisons ("<", ">", "<=", and ">=") raise "TypeError".\n\n* Sets (instances of "set" or "frozenset") can be compared within\n and across their types.\n\n They define order comparison operators to mean subset and superset\n tests. Those relations do not define total orderings (for example,\n the two sets "{1,2}" and "{2,3}" are not equal, nor subsets of one\n another, nor supersets of one another). Accordingly, sets are not\n appropriate arguments for functions which depend on total ordering\n (for example, "min()", "max()", and "sorted()" produce undefined\n results given a list of sets as inputs).\n\n Comparison of sets enforces reflexivity of its elements.\n\n* Most other built-in types have no comparison methods implemented,\n so they inherit the default comparison behavior.\n\nUser-defined classes that customize their comparison behavior should\nfollow some consistency rules, if possible:\n\n* Equality comparison should be reflexive. In other words, identical\n objects should compare equal:\n\n "x is y" implies "x == y"\n\n* Comparison should be symmetric. In other words, the following\n expressions should have the same result:\n\n "x == y" and "y == x"\n\n "x != y" and "y != x"\n\n "x < y" and "y > x"\n\n "x <= y" and "y >= x"\n\n* Comparison should be transitive. The following (non-exhaustive)\n examples illustrate that:\n\n "x > y and y > z" implies "x > z"\n\n "x < y and y <= z" implies "x < z"\n\n* Inverse comparison should result in the boolean negation. In other\n words, the following expressions should have the same result:\n\n "x == y" and "not x != y"\n\n "x < y" and "not x >= y" (for total ordering)\n\n "x > y" and "not x <= y" (for total ordering)\n\n The last two expressions apply to totally ordered collections (e.g.\n to sequences, but not to sets or mappings). See also the\n "total_ordering()" decorator.\n\nPython does not enforce these consistency rules. In fact, the\nnot-a-number values are an example for not following these rules.\n\n\nMembership test operations\n==========================\n\nThe operators "in" and "not in" test for membership. "x in s"\nevaluates to true if *x* is a member of *s*, and false otherwise. "x\nnot in s" returns the negation of "x in s". All built-in sequences\nand set types support this as well as dictionary, for which "in" tests\nwhether the dictionary has a given key. For container types such as\nlist, tuple, set, frozenset, dict, or collections.deque, the\nexpression "x in y" is equivalent to "any(x is e or x == e for e in\ny)".\n\nFor the string and bytes types, "x in y" is true if and only if *x* is\na substring of *y*. An equivalent test is "y.find(x) != -1". Empty\nstrings are always considered to be a substring of any other string,\nso """ in "abc"" will return "True".\n\nFor user-defined classes which define the "__contains__()" method, "x\nin y" is true if and only if "y.__contains__(x)" is true.\n\nFor user-defined classes which do not define "__contains__()" but do\ndefine "__iter__()", "x in y" is true if some value "z" with "x == z"\nis produced while iterating over "y". If an exception is raised\nduring the iteration, it is as if "in" raised that exception.\n\nLastly, the old-style iteration protocol is tried: if a class defines\n"__getitem__()", "x in y" is true if and only if there is a non-\nnegative integer index *i* such that "x == y[i]", and all lower\ninteger indices do not raise "IndexError" exception. (If any other\nexception is raised, it is as if "in" raised that exception).\n\nThe operator "not in" is defined to have the inverse true value of\n"in".\n\n\nIdentity comparisons\n====================\n\nThe operators "is" and "is not" test for object identity: "x is y" is\ntrue if and only if *x* and *y* are the same object. "x is not y"\nyields the inverse truth value. [4]\n', + 'compound': u'\nCompound statements\n*******************\n\nCompound statements contain (groups of) other statements; they affect\nor control the execution of those other statements in some way. In\ngeneral, compound statements span multiple lines, although in simple\nincarnations a whole compound statement may be contained in one line.\n\nThe "if", "while" and "for" statements implement traditional control\nflow constructs. "try" specifies exception handlers and/or cleanup\ncode for a group of statements, while the "with" statement allows the\nexecution of initialization and finalization code around a block of\ncode. Function and class definitions are also syntactically compound\nstatements.\n\nA compound statement consists of one or more \'clauses.\' A clause\nconsists of a header and a \'suite.\' The clause headers of a\nparticular compound statement are all at the same indentation level.\nEach clause header begins with a uniquely identifying keyword and ends\nwith a colon. A suite is a group of statements controlled by a\nclause. A suite can be one or more semicolon-separated simple\nstatements on the same line as the header, following the header\'s\ncolon, or it can be one or more indented statements on subsequent\nlines. Only the latter form of a suite can contain nested compound\nstatements; the following is illegal, mostly because it wouldn\'t be\nclear to which "if" clause a following "else" clause would belong:\n\n if test1: if test2: print(x)\n\nAlso note that the semicolon binds tighter than the colon in this\ncontext, so that in the following example, either all or none of the\n"print()" calls are executed:\n\n if x < y < z: print(x); print(y); print(z)\n\nSummarizing:\n\n compound_stmt ::= if_stmt\n | while_stmt\n | for_stmt\n | try_stmt\n | with_stmt\n | funcdef\n | classdef\n suite ::= stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT\n statement ::= stmt_list NEWLINE | compound_stmt\n stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n\nNote that statements always end in a "NEWLINE" possibly followed by a\n"DEDENT". Also note that optional continuation clauses always begin\nwith a keyword that cannot start a statement, thus there are no\nambiguities (the \'dangling "else"\' problem is solved in Python by\nrequiring nested "if" statements to be indented).\n\nThe formatting of the grammar rules in the following sections places\neach clause on a separate line for clarity.\n\n\nThe "if" statement\n==================\n\nThe "if" statement is used for conditional execution:\n\n if_stmt ::= "if" expression ":" suite\n ( "elif" expression ":" suite )*\n ["else" ":" suite]\n\nIt selects exactly one of the suites by evaluating the expressions one\nby one until one is found to be true (see section *Boolean operations*\nfor the definition of true and false); then that suite is executed\n(and no other part of the "if" statement is executed or evaluated).\nIf all expressions are false, the suite of the "else" clause, if\npresent, is executed.\n\n\nThe "while" statement\n=====================\n\nThe "while" statement is used for repeated execution as long as an\nexpression is true:\n\n while_stmt ::= "while" expression ":" suite\n ["else" ":" suite]\n\nThis repeatedly tests the expression and, if it is true, executes the\nfirst suite; if the expression is false (which may be the first time\nit is tested) the suite of the "else" clause, if present, is executed\nand the loop terminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and goes back\nto testing the expression.\n\n\nThe "for" statement\n===================\n\nThe "for" statement is used to iterate over the elements of a sequence\n(such as a string, tuple or list) or other iterable object:\n\n for_stmt ::= "for" target_list "in" expression_list ":" suite\n ["else" ":" suite]\n\nThe expression list is evaluated once; it should yield an iterable\nobject. An iterator is created for the result of the\n"expression_list". The suite is then executed once for each item\nprovided by the iterator, in the order returned by the iterator. Each\nitem in turn is assigned to the target list using the standard rules\nfor assignments (see *Assignment statements*), and then the suite is\nexecuted. When the items are exhausted (which is immediately when the\nsequence is empty or an iterator raises a "StopIteration" exception),\nthe suite in the "else" clause, if present, is executed, and the loop\nterminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and continues\nwith the next item, or with the "else" clause if there is no next\nitem.\n\nThe for-loop makes assignments to the variables(s) in the target list.\nThis overwrites all previous assignments to those variables including\nthose made in the suite of the for-loop:\n\n for i in range(10):\n print(i)\n i = 5 # this will not affect the for-loop\n # because i will be overwritten with the next\n # index in the range\n\nNames in the target list are not deleted when the loop is finished,\nbut if the sequence is empty, they will not have been assigned to at\nall by the loop. Hint: the built-in function "range()" returns an\niterator of integers suitable to emulate the effect of Pascal\'s "for i\n:= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n\nNote: There is a subtlety when the sequence is being modified by the\n loop (this can only occur for mutable sequences, i.e. lists). An\n internal counter is used to keep track of which item is used next,\n and this is incremented on each iteration. When this counter has\n reached the length of the sequence the loop terminates. This means\n that if the suite deletes the current (or a previous) item from the\n sequence, the next item will be skipped (since it gets the index of\n the current item which has already been treated). Likewise, if the\n suite inserts an item in the sequence before the current item, the\n current item will be treated again the next time through the loop.\n This can lead to nasty bugs that can be avoided by making a\n temporary copy using a slice of the whole sequence, e.g.,\n\n for x in a[:]:\n if x < 0: a.remove(x)\n\n\nThe "try" statement\n===================\n\nThe "try" statement specifies exception handlers and/or cleanup code\nfor a group of statements:\n\n try_stmt ::= try1_stmt | try2_stmt\n try1_stmt ::= "try" ":" suite\n ("except" [expression ["as" identifier]] ":" suite)+\n ["else" ":" suite]\n ["finally" ":" suite]\n try2_stmt ::= "try" ":" suite\n "finally" ":" suite\n\nThe "except" clause(s) specify one or more exception handlers. When no\nexception occurs in the "try" clause, no exception handler is\nexecuted. When an exception occurs in the "try" suite, a search for an\nexception handler is started. This search inspects the except clauses\nin turn until one is found that matches the exception. An expression-\nless except clause, if present, must be last; it matches any\nexception. For an except clause with an expression, that expression\nis evaluated, and the clause matches the exception if the resulting\nobject is "compatible" with the exception. An object is compatible\nwith an exception if it is the class or a base class of the exception\nobject or a tuple containing an item compatible with the exception.\n\nIf no except clause matches the exception, the search for an exception\nhandler continues in the surrounding code and on the invocation stack.\n[1]\n\nIf the evaluation of an expression in the header of an except clause\nraises an exception, the original search for a handler is canceled and\na search starts for the new exception in the surrounding code and on\nthe call stack (it is treated as if the entire "try" statement raised\nthe exception).\n\nWhen a matching except clause is found, the exception is assigned to\nthe target specified after the "as" keyword in that except clause, if\npresent, and the except clause\'s suite is executed. All except\nclauses must have an executable block. When the end of this block is\nreached, execution continues normally after the entire try statement.\n(This means that if two nested handlers exist for the same exception,\nand the exception occurs in the try clause of the inner handler, the\nouter handler will not handle the exception.)\n\nWhen an exception has been assigned using "as target", it is cleared\nat the end of the except clause. This is as if\n\n except E as N:\n foo\n\nwas translated to\n\n except E as N:\n try:\n foo\n finally:\n del N\n\nThis means the exception must be assigned to a different name to be\nable to refer to it after the except clause. Exceptions are cleared\nbecause with the traceback attached to them, they form a reference\ncycle with the stack frame, keeping all locals in that frame alive\nuntil the next garbage collection occurs.\n\nBefore an except clause\'s suite is executed, details about the\nexception are stored in the "sys" module and can be accessed via\n"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of the\nexception class, the exception instance and a traceback object (see\nsection *The standard type hierarchy*) identifying the point in the\nprogram where the exception occurred. "sys.exc_info()" values are\nrestored to their previous values (before the call) when returning\nfrom a function that handled an exception.\n\nThe optional "else" clause is executed if and when control flows off\nthe end of the "try" clause. [2] Exceptions in the "else" clause are\nnot handled by the preceding "except" clauses.\n\nIf "finally" is present, it specifies a \'cleanup\' handler. The "try"\nclause is executed, including any "except" and "else" clauses. If an\nexception occurs in any of the clauses and is not handled, the\nexception is temporarily saved. The "finally" clause is executed. If\nthere is a saved exception it is re-raised at the end of the "finally"\nclause. If the "finally" clause raises another exception, the saved\nexception is set as the context of the new exception. If the "finally"\nclause executes a "return" or "break" statement, the saved exception\nis discarded:\n\n >>> def f():\n ... try:\n ... 1/0\n ... finally:\n ... return 42\n ...\n >>> f()\n 42\n\nThe exception information is not available to the program during\nexecution of the "finally" clause.\n\nWhen a "return", "break" or "continue" statement is executed in the\n"try" suite of a "try"..."finally" statement, the "finally" clause is\nalso executed \'on the way out.\' A "continue" statement is illegal in\nthe "finally" clause. (The reason is a problem with the current\nimplementation --- this restriction may be lifted in the future).\n\nThe return value of a function is determined by the last "return"\nstatement executed. Since the "finally" clause always executes, a\n"return" statement executed in the "finally" clause will always be the\nlast one executed:\n\n >>> def foo():\n ... try:\n ... return \'try\'\n ... finally:\n ... return \'finally\'\n ...\n >>> foo()\n \'finally\'\n\nAdditional information on exceptions can be found in section\n*Exceptions*, and information on using the "raise" statement to\ngenerate exceptions may be found in section *The raise statement*.\n\n\nThe "with" statement\n====================\n\nThe "with" statement is used to wrap the execution of a block with\nmethods defined by a context manager (see section *With Statement\nContext Managers*). This allows common "try"..."except"..."finally"\nusage patterns to be encapsulated for convenient reuse.\n\n with_stmt ::= "with" with_item ("," with_item)* ":" suite\n with_item ::= expression ["as" target]\n\nThe execution of the "with" statement with one "item" proceeds as\nfollows:\n\n1. The context expression (the expression given in the "with_item")\n is evaluated to obtain a context manager.\n\n2. The context manager\'s "__exit__()" is loaded for later use.\n\n3. The context manager\'s "__enter__()" method is invoked.\n\n4. If a target was included in the "with" statement, the return\n value from "__enter__()" is assigned to it.\n\n Note: The "with" statement guarantees that if the "__enter__()"\n method returns without an error, then "__exit__()" will always be\n called. Thus, if an error occurs during the assignment to the\n target list, it will be treated the same as an error occurring\n within the suite would be. See step 6 below.\n\n5. The suite is executed.\n\n6. The context manager\'s "__exit__()" method is invoked. If an\n exception caused the suite to be exited, its type, value, and\n traceback are passed as arguments to "__exit__()". Otherwise, three\n "None" arguments are supplied.\n\n If the suite was exited due to an exception, and the return value\n from the "__exit__()" method was false, the exception is reraised.\n If the return value was true, the exception is suppressed, and\n execution continues with the statement following the "with"\n statement.\n\n If the suite was exited for any reason other than an exception, the\n return value from "__exit__()" is ignored, and execution proceeds\n at the normal location for the kind of exit that was taken.\n\nWith more than one item, the context managers are processed as if\nmultiple "with" statements were nested:\n\n with A() as a, B() as b:\n suite\n\nis equivalent to\n\n with A() as a:\n with B() as b:\n suite\n\nChanged in version 3.1: Support for multiple context expressions.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n\n\nFunction definitions\n====================\n\nA function definition defines a user-defined function object (see\nsection *The standard type hierarchy*):\n\n funcdef ::= [decorators] "def" funcname "(" [parameter_list] ")" ["->" expression] ":" suite\n decorators ::= decorator+\n decorator ::= "@" dotted_name ["(" [parameter_list [","]] ")"] NEWLINE\n dotted_name ::= identifier ("." identifier)*\n parameter_list ::= (defparameter ",")*\n | "*" [parameter] ("," defparameter)* ["," "**" parameter]\n | "**" parameter\n | defparameter [","] )\n parameter ::= identifier [":" expression]\n defparameter ::= parameter ["=" expression]\n funcname ::= identifier\n\nA function definition is an executable statement. Its execution binds\nthe function name in the current local namespace to a function object\n(a wrapper around the executable code for the function). This\nfunction object contains a reference to the current global namespace\nas the global namespace to be used when the function is called.\n\nThe function definition does not execute the function body; this gets\nexecuted only when the function is called. [3]\n\nA function definition may be wrapped by one or more *decorator*\nexpressions. Decorator expressions are evaluated when the function is\ndefined, in the scope that contains the function definition. The\nresult must be a callable, which is invoked with the function object\nas the only argument. The returned value is bound to the function name\ninstead of the function object. Multiple decorators are applied in\nnested fashion. For example, the following code\n\n @f1(arg)\n @f2\n def func(): pass\n\nis equivalent to\n\n def func(): pass\n func = f1(arg)(f2(func))\n\nWhen one or more *parameters* have the form *parameter* "="\n*expression*, the function is said to have "default parameter values."\nFor a parameter with a default value, the corresponding *argument* may\nbe omitted from a call, in which case the parameter\'s default value is\nsubstituted. If a parameter has a default value, all following\nparameters up until the ""*"" must also have a default value --- this\nis a syntactic restriction that is not expressed by the grammar.\n\n**Default parameter values are evaluated from left to right when the\nfunction definition is executed.** This means that the expression is\nevaluated once, when the function is defined, and that the same "pre-\ncomputed" value is used for each call. This is especially important\nto understand when a default parameter is a mutable object, such as a\nlist or a dictionary: if the function modifies the object (e.g. by\nappending an item to a list), the default value is in effect modified.\nThis is generally not what was intended. A way around this is to use\n"None" as the default, and explicitly test for it in the body of the\nfunction, e.g.:\n\n def whats_on_the_telly(penguin=None):\n if penguin is None:\n penguin = []\n penguin.append("property of the zoo")\n return penguin\n\nFunction call semantics are described in more detail in section\n*Calls*. A function call always assigns values to all parameters\nmentioned in the parameter list, either from position arguments, from\nkeyword arguments, or from default values. If the form\n""*identifier"" is present, it is initialized to a tuple receiving any\nexcess positional parameters, defaulting to the empty tuple. If the\nform ""**identifier"" is present, it is initialized to a new\ndictionary receiving any excess keyword arguments, defaulting to a new\nempty dictionary. Parameters after ""*"" or ""*identifier"" are\nkeyword-only parameters and may only be passed used keyword arguments.\n\nParameters may have annotations of the form "": expression"" following\nthe parameter name. Any parameter may have an annotation even those\nof the form "*identifier" or "**identifier". Functions may have\n"return" annotation of the form ""-> expression"" after the parameter\nlist. These annotations can be any valid Python expression and are\nevaluated when the function definition is executed. Annotations may\nbe evaluated in a different order than they appear in the source code.\nThe presence of annotations does not change the semantics of a\nfunction. The annotation values are available as values of a\ndictionary keyed by the parameters\' names in the "__annotations__"\nattribute of the function object.\n\nIt is also possible to create anonymous functions (functions not bound\nto a name), for immediate use in expressions. This uses lambda\nexpressions, described in section *Lambdas*. Note that the lambda\nexpression is merely a shorthand for a simplified function definition;\na function defined in a ""def"" statement can be passed around or\nassigned to another name just like a function defined by a lambda\nexpression. The ""def"" form is actually more powerful since it\nallows the execution of multiple statements and annotations.\n\n**Programmer\'s note:** Functions are first-class objects. A ""def""\nstatement executed inside a function definition defines a local\nfunction that can be returned or passed around. Free variables used\nin the nested function can access the local variables of the function\ncontaining the def. See section *Naming and binding* for details.\n\nSee also: **PEP 3107** - Function Annotations\n\n The original specification for function annotations.\n\n\nClass definitions\n=================\n\nA class definition defines a class object (see section *The standard\ntype hierarchy*):\n\n classdef ::= [decorators] "class" classname [inheritance] ":" suite\n inheritance ::= "(" [parameter_list] ")"\n classname ::= identifier\n\nA class definition is an executable statement. The inheritance list\nusually gives a list of base classes (see *Customizing class creation*\nfor more advanced uses), so each item in the list should evaluate to a\nclass object which allows subclassing. Classes without an inheritance\nlist inherit, by default, from the base class "object"; hence,\n\n class Foo:\n pass\n\nis equivalent to\n\n class Foo(object):\n pass\n\nThe class\'s suite is then executed in a new execution frame (see\n*Naming and binding*), using a newly created local namespace and the\noriginal global namespace. (Usually, the suite contains mostly\nfunction definitions.) When the class\'s suite finishes execution, its\nexecution frame is discarded but its local namespace is saved. [4] A\nclass object is then created using the inheritance list for the base\nclasses and the saved local namespace for the attribute dictionary.\nThe class name is bound to this class object in the original local\nnamespace.\n\nClass creation can be customized heavily using *metaclasses*.\n\nClasses can also be decorated: just like when decorating functions,\n\n @f1(arg)\n @f2\n class Foo: pass\n\nis equivalent to\n\n class Foo: pass\n Foo = f1(arg)(f2(Foo))\n\nThe evaluation rules for the decorator expressions are the same as for\nfunction decorators. The result must be a class object, which is then\nbound to the class name.\n\n**Programmer\'s note:** Variables defined in the class definition are\nclass attributes; they are shared by instances. Instance attributes\ncan be set in a method with "self.name = value". Both class and\ninstance attributes are accessible through the notation ""self.name"",\nand an instance attribute hides a class attribute with the same name\nwhen accessed in this way. Class attributes can be used as defaults\nfor instance attributes, but using mutable values there can lead to\nunexpected results. *Descriptors* can be used to create instance\nvariables with different implementation details.\n\nSee also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n Class Decorators\n\n-[ Footnotes ]-\n\n[1] The exception is propagated to the invocation stack unless\n there is a "finally" clause which happens to raise another\n exception. That new exception causes the old one to be lost.\n\n[2] Currently, control "flows off the end" except in the case of\n an exception or the execution of a "return", "continue", or\n "break" statement.\n\n[3] A string literal appearing as the first statement in the\n function body is transformed into the function\'s "__doc__"\n attribute and therefore the function\'s *docstring*.\n\n[4] A string literal appearing as the first statement in the class\n body is transformed into the namespace\'s "__doc__" item and\n therefore the class\'s *docstring*.\n', + 'context-managers': u'\nWith Statement Context Managers\n*******************************\n\nA *context manager* is an object that defines the runtime context to\nbe established when executing a "with" statement. The context manager\nhandles the entry into, and the exit from, the desired runtime context\nfor the execution of the block of code. Context managers are normally\ninvoked using the "with" statement (described in section *The with\nstatement*), but can also be used by directly invoking their methods.\n\nTypical uses of context managers include saving and restoring various\nkinds of global state, locking and unlocking resources, closing opened\nfiles, etc.\n\nFor more information on context managers, see *Context Manager Types*.\n\nobject.__enter__(self)\n\n Enter the runtime context related to this object. The "with"\n statement will bind this method\'s return value to the target(s)\n specified in the "as" clause of the statement, if any.\n\nobject.__exit__(self, exc_type, exc_value, traceback)\n\n Exit the runtime context related to this object. The parameters\n describe the exception that caused the context to be exited. If the\n context was exited without an exception, all three arguments will\n be "None".\n\n If an exception is supplied, and the method wishes to suppress the\n exception (i.e., prevent it from being propagated), it should\n return a true value. Otherwise, the exception will be processed\n normally upon exit from this method.\n\n Note that "__exit__()" methods should not reraise the passed-in\n exception; this is the caller\'s responsibility.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n', + 'continue': u'\nThe "continue" statement\n************************\n\n continue_stmt ::= "continue"\n\n"continue" may only occur syntactically nested in a "for" or "while"\nloop, but not nested in a function or class definition or "finally"\nclause within that loop. It continues with the next cycle of the\nnearest enclosing loop.\n\nWhen "continue" passes control out of a "try" statement with a\n"finally" clause, that "finally" clause is executed before really\nstarting the next loop cycle.\n', + 'conversions': u'\nArithmetic conversions\n**********************\n\nWhen a description of an arithmetic operator below uses the phrase\n"the numeric arguments are converted to a common type," this means\nthat the operator implementation for built-in types works as follows:\n\n* If either argument is a complex number, the other is converted to\n complex;\n\n* otherwise, if either argument is a floating point number, the\n other is converted to floating point;\n\n* otherwise, both must be integers and no conversion is necessary.\n\nSome additional rules apply for certain operators (e.g., a string as a\nleft argument to the \'%\' operator). Extensions must define their own\nconversion behavior.\n', + 'customization': u'\nBasic customization\n*******************\n\nobject.__new__(cls[, ...])\n\n Called to create a new instance of class *cls*. "__new__()" is a\n static method (special-cased so you need not declare it as such)\n that takes the class of which an instance was requested as its\n first argument. The remaining arguments are those passed to the\n object constructor expression (the call to the class). The return\n value of "__new__()" should be the new object instance (usually an\n instance of *cls*).\n\n Typical implementations create a new instance of the class by\n invoking the superclass\'s "__new__()" method using\n "super(currentclass, cls).__new__(cls[, ...])" with appropriate\n arguments and then modifying the newly-created instance as\n necessary before returning it.\n\n If "__new__()" returns an instance of *cls*, then the new\n instance\'s "__init__()" method will be invoked like\n "__init__(self[, ...])", where *self* is the new instance and the\n remaining arguments are the same as were passed to "__new__()".\n\n If "__new__()" does not return an instance of *cls*, then the new\n instance\'s "__init__()" method will not be invoked.\n\n "__new__()" is intended mainly to allow subclasses of immutable\n types (like int, str, or tuple) to customize instance creation. It\n is also commonly overridden in custom metaclasses in order to\n customize class creation.\n\nobject.__init__(self[, ...])\n\n Called after the instance has been created (by "__new__()"), but\n before it is returned to the caller. The arguments are those\n passed to the class constructor expression. If a base class has an\n "__init__()" method, the derived class\'s "__init__()" method, if\n any, must explicitly call it to ensure proper initialization of the\n base class part of the instance; for example:\n "BaseClass.__init__(self, [args...])".\n\n Because "__new__()" and "__init__()" work together in constructing\n objects ("__new__()" to create it, and "__init__()" to customise\n it), no non-"None" value may be returned by "__init__()"; doing so\n will cause a "TypeError" to be raised at runtime.\n\nobject.__del__(self)\n\n Called when the instance is about to be destroyed. This is also\n called a destructor. If a base class has a "__del__()" method, the\n derived class\'s "__del__()" method, if any, must explicitly call it\n to ensure proper deletion of the base class part of the instance.\n Note that it is possible (though not recommended!) for the\n "__del__()" method to postpone destruction of the instance by\n creating a new reference to it. It may then be called at a later\n time when this new reference is deleted. It is not guaranteed that\n "__del__()" methods are called for objects that still exist when\n the interpreter exits.\n\n Note: "del x" doesn\'t directly call "x.__del__()" --- the former\n decrements the reference count for "x" by one, and the latter is\n only called when "x"\'s reference count reaches zero. Some common\n situations that may prevent the reference count of an object from\n going to zero include: circular references between objects (e.g.,\n a doubly-linked list or a tree data structure with parent and\n child pointers); a reference to the object on the stack frame of\n a function that caught an exception (the traceback stored in\n "sys.exc_info()[2]" keeps the stack frame alive); or a reference\n to the object on the stack frame that raised an unhandled\n exception in interactive mode (the traceback stored in\n "sys.last_traceback" keeps the stack frame alive). The first\n situation can only be remedied by explicitly breaking the cycles;\n the second can be resolved by freeing the reference to the\n traceback object when it is no longer useful, and the third can\n be resolved by storing "None" in "sys.last_traceback". Circular\n references which are garbage are detected and cleaned up when the\n cyclic garbage collector is enabled (it\'s on by default). Refer\n to the documentation for the "gc" module for more information\n about this topic.\n\n Warning: Due to the precarious circumstances under which\n "__del__()" methods are invoked, exceptions that occur during\n their execution are ignored, and a warning is printed to\n "sys.stderr" instead. Also, when "__del__()" is invoked in\n response to a module being deleted (e.g., when execution of the\n program is done), other globals referenced by the "__del__()"\n method may already have been deleted or in the process of being\n torn down (e.g. the import machinery shutting down). For this\n reason, "__del__()" methods should do the absolute minimum needed\n to maintain external invariants. Starting with version 1.5,\n Python guarantees that globals whose name begins with a single\n underscore are deleted from their module before other globals are\n deleted; if no other references to such globals exist, this may\n help in assuring that imported modules are still available at the\n time when the "__del__()" method is called.\n\nobject.__repr__(self)\n\n Called by the "repr()" built-in function to compute the "official"\n string representation of an object. If at all possible, this\n should look like a valid Python expression that could be used to\n recreate an object with the same value (given an appropriate\n environment). If this is not possible, a string of the form\n "<...some useful description...>" should be returned. The return\n value must be a string object. If a class defines "__repr__()" but\n not "__str__()", then "__repr__()" is also used when an "informal"\n string representation of instances of that class is required.\n\n This is typically used for debugging, so it is important that the\n representation is information-rich and unambiguous.\n\nobject.__str__(self)\n\n Called by "str(object)" and the built-in functions "format()" and\n "print()" to compute the "informal" or nicely printable string\n representation of an object. The return value must be a *string*\n object.\n\n This method differs from "object.__repr__()" in that there is no\n expectation that "__str__()" return a valid Python expression: a\n more convenient or concise representation can be used.\n\n The default implementation defined by the built-in type "object"\n calls "object.__repr__()".\n\nobject.__bytes__(self)\n\n Called by "bytes()" to compute a byte-string representation of an\n object. This should return a "bytes" object.\n\nobject.__format__(self, format_spec)\n\n Called by the "format()" built-in function (and by extension, the\n "str.format()" method of class "str") to produce a "formatted"\n string representation of an object. The "format_spec" argument is a\n string that contains a description of the formatting options\n desired. The interpretation of the "format_spec" argument is up to\n the type implementing "__format__()", however most classes will\n either delegate formatting to one of the built-in types, or use a\n similar formatting option syntax.\n\n See *Format Specification Mini-Language* for a description of the\n standard formatting syntax.\n\n The return value must be a string object.\n\n Changed in version 3.4: The __format__ method of "object" itself\n raises a "TypeError" if passed any non-empty string.\n\nobject.__lt__(self, other)\nobject.__le__(self, other)\nobject.__eq__(self, other)\nobject.__ne__(self, other)\nobject.__gt__(self, other)\nobject.__ge__(self, other)\n\n These are the so-called "rich comparison" methods. The\n correspondence between operator symbols and method names is as\n follows: "xy" calls\n "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n\n A rich comparison method may return the singleton "NotImplemented"\n if it does not implement the operation for a given pair of\n arguments. By convention, "False" and "True" are returned for a\n successful comparison. However, these methods can return any value,\n so if the comparison operator is used in a Boolean context (e.g.,\n in the condition of an "if" statement), Python will call "bool()"\n on the value to determine if the result is true or false.\n\n By default, "__ne__()" delegates to "__eq__()" and inverts the\n result unless it is "NotImplemented". There are no other implied\n relationships among the comparison operators, for example, the\n truth of "(x.__hash__".\n\n If a class that does not override "__eq__()" wishes to suppress\n hash support, it should include "__hash__ = None" in the class\n definition. A class which defines its own "__hash__()" that\n explicitly raises a "TypeError" would be incorrectly identified as\n hashable by an "isinstance(obj, collections.Hashable)" call.\n\n Note: By default, the "__hash__()" values of str, bytes and\n datetime objects are "salted" with an unpredictable random value.\n Although they remain constant within an individual Python\n process, they are not predictable between repeated invocations of\n Python.This is intended to provide protection against a denial-\n of-service caused by carefully-chosen inputs that exploit the\n worst case performance of a dict insertion, O(n^2) complexity.\n See http://www.ocert.org/advisories/ocert-2011-003.html for\n details.Changing hash values affects the iteration order of\n dicts, sets and other mappings. Python has never made guarantees\n about this ordering (and it typically varies between 32-bit and\n 64-bit builds).See also "PYTHONHASHSEED".\n\n Changed in version 3.3: Hash randomization is enabled by default.\n\nobject.__bool__(self)\n\n Called to implement truth value testing and the built-in operation\n "bool()"; should return "False" or "True". When this method is not\n defined, "__len__()" is called, if it is defined, and the object is\n considered true if its result is nonzero. If a class defines\n neither "__len__()" nor "__bool__()", all its instances are\n considered true.\n', + 'debugger': u'\n"pdb" --- The Python Debugger\n*****************************\n\n**Source code:** Lib/pdb.py\n\n======================================================================\n\nThe module "pdb" defines an interactive source code debugger for\nPython programs. It supports setting (conditional) breakpoints and\nsingle stepping at the source line level, inspection of stack frames,\nsource code listing, and evaluation of arbitrary Python code in the\ncontext of any stack frame. It also supports post-mortem debugging\nand can be called under program control.\n\nThe debugger is extensible -- it is actually defined as the class\n"Pdb". This is currently undocumented but easily understood by reading\nthe source. The extension interface uses the modules "bdb" and "cmd".\n\nThe debugger\'s prompt is "(Pdb)". Typical usage to run a program under\ncontrol of the debugger is:\n\n >>> import pdb\n >>> import mymodule\n >>> pdb.run(\'mymodule.test()\')\n > (0)?()\n (Pdb) continue\n > (1)?()\n (Pdb) continue\n NameError: \'spam\'\n > (1)?()\n (Pdb)\n\nChanged in version 3.3: Tab-completion via the "readline" module is\navailable for commands and command arguments, e.g. the current global\nand local names are offered as arguments of the "p" command.\n\n"pdb.py" can also be invoked as a script to debug other scripts. For\nexample:\n\n python3 -m pdb myscript.py\n\nWhen invoked as a script, pdb will automatically enter post-mortem\ndebugging if the program being debugged exits abnormally. After post-\nmortem debugging (or after normal exit of the program), pdb will\nrestart the program. Automatic restarting preserves pdb\'s state (such\nas breakpoints) and in most cases is more useful than quitting the\ndebugger upon program\'s exit.\n\nNew in version 3.2: "pdb.py" now accepts a "-c" option that executes\ncommands as if given in a ".pdbrc" file, see *Debugger Commands*.\n\nThe typical usage to break into the debugger from a running program is\nto insert\n\n import pdb; pdb.set_trace()\n\nat the location you want to break into the debugger. You can then\nstep through the code following this statement, and continue running\nwithout the debugger using the "continue" command.\n\nThe typical usage to inspect a crashed program is:\n\n >>> import pdb\n >>> import mymodule\n >>> mymodule.test()\n Traceback (most recent call last):\n File "", line 1, in ?\n File "./mymodule.py", line 4, in test\n test2()\n File "./mymodule.py", line 3, in test2\n print(spam)\n NameError: spam\n >>> pdb.pm()\n > ./mymodule.py(3)test2()\n -> print(spam)\n (Pdb)\n\nThe module defines the following functions; each enters the debugger\nin a slightly different way:\n\npdb.run(statement, globals=None, locals=None)\n\n Execute the *statement* (given as a string or a code object) under\n debugger control. The debugger prompt appears before any code is\n executed; you can set breakpoints and type "continue", or you can\n step through the statement using "step" or "next" (all these\n commands are explained below). The optional *globals* and *locals*\n arguments specify the environment in which the code is executed; by\n default the dictionary of the module "__main__" is used. (See the\n explanation of the built-in "exec()" or "eval()" functions.)\n\npdb.runeval(expression, globals=None, locals=None)\n\n Evaluate the *expression* (given as a string or a code object)\n under debugger control. When "runeval()" returns, it returns the\n value of the expression. Otherwise this function is similar to\n "run()".\n\npdb.runcall(function, *args, **kwds)\n\n Call the *function* (a function or method object, not a string)\n with the given arguments. When "runcall()" returns, it returns\n whatever the function call returned. The debugger prompt appears\n as soon as the function is entered.\n\npdb.set_trace()\n\n Enter the debugger at the calling stack frame. This is useful to\n hard-code a breakpoint at a given point in a program, even if the\n code is not otherwise being debugged (e.g. when an assertion\n fails).\n\npdb.post_mortem(traceback=None)\n\n Enter post-mortem debugging of the given *traceback* object. If no\n *traceback* is given, it uses the one of the exception that is\n currently being handled (an exception must be being handled if the\n default is to be used).\n\npdb.pm()\n\n Enter post-mortem debugging of the traceback found in\n "sys.last_traceback".\n\nThe "run*" functions and "set_trace()" are aliases for instantiating\nthe "Pdb" class and calling the method of the same name. If you want\nto access further features, you have to do this yourself:\n\nclass class pdb.Pdb(completekey=\'tab\', stdin=None, stdout=None, skip=None, nosigint=False)\n\n "Pdb" is the debugger class.\n\n The *completekey*, *stdin* and *stdout* arguments are passed to the\n underlying "cmd.Cmd" class; see the description there.\n\n The *skip* argument, if given, must be an iterable of glob-style\n module name patterns. The debugger will not step into frames that\n originate in a module that matches one of these patterns. [1]\n\n By default, Pdb sets a handler for the SIGINT signal (which is sent\n when the user presses "Ctrl-C" on the console) when you give a\n "continue" command. This allows you to break into the debugger\n again by pressing "Ctrl-C". If you want Pdb not to touch the\n SIGINT handler, set *nosigint* tot true.\n\n Example call to enable tracing with *skip*:\n\n import pdb; pdb.Pdb(skip=[\'django.*\']).set_trace()\n\n New in version 3.1: The *skip* argument.\n\n New in version 3.2: The *nosigint* argument. Previously, a SIGINT\n handler was never set by Pdb.\n\n run(statement, globals=None, locals=None)\n runeval(expression, globals=None, locals=None)\n runcall(function, *args, **kwds)\n set_trace()\n\n See the documentation for the functions explained above.\n\n\nDebugger Commands\n=================\n\nThe commands recognized by the debugger are listed below. Most\ncommands can be abbreviated to one or two letters as indicated; e.g.\n"h(elp)" means that either "h" or "help" can be used to enter the help\ncommand (but not "he" or "hel", nor "H" or "Help" or "HELP").\nArguments to commands must be separated by whitespace (spaces or\ntabs). Optional arguments are enclosed in square brackets ("[]") in\nthe command syntax; the square brackets must not be typed.\nAlternatives in the command syntax are separated by a vertical bar\n("|").\n\nEntering a blank line repeats the last command entered. Exception: if\nthe last command was a "list" command, the next 11 lines are listed.\n\nCommands that the debugger doesn\'t recognize are assumed to be Python\nstatements and are executed in the context of the program being\ndebugged. Python statements can also be prefixed with an exclamation\npoint ("!"). This is a powerful way to inspect the program being\ndebugged; it is even possible to change a variable or call a function.\nWhen an exception occurs in such a statement, the exception name is\nprinted but the debugger\'s state is not changed.\n\nThe debugger supports *aliases*. Aliases can have parameters which\nallows one a certain level of adaptability to the context under\nexamination.\n\nMultiple commands may be entered on a single line, separated by ";;".\n(A single ";" is not used as it is the separator for multiple commands\nin a line that is passed to the Python parser.) No intelligence is\napplied to separating the commands; the input is split at the first\n";;" pair, even if it is in the middle of a quoted string.\n\nIf a file ".pdbrc" exists in the user\'s home directory or in the\ncurrent directory, it is read in and executed as if it had been typed\nat the debugger prompt. This is particularly useful for aliases. If\nboth files exist, the one in the home directory is read first and\naliases defined there can be overridden by the local file.\n\nChanged in version 3.2: ".pdbrc" can now contain commands that\ncontinue debugging, such as "continue" or "next". Previously, these\ncommands had no effect.\n\nh(elp) [command]\n\n Without argument, print the list of available commands. With a\n *command* as argument, print help about that command. "help pdb"\n displays the full documentation (the docstring of the "pdb"\n module). Since the *command* argument must be an identifier, "help\n exec" must be entered to get help on the "!" command.\n\nw(here)\n\n Print a stack trace, with the most recent frame at the bottom. An\n arrow indicates the current frame, which determines the context of\n most commands.\n\nd(own) [count]\n\n Move the current frame *count* (default one) levels down in the\n stack trace (to a newer frame).\n\nu(p) [count]\n\n Move the current frame *count* (default one) levels up in the stack\n trace (to an older frame).\n\nb(reak) [([filename:]lineno | function) [, condition]]\n\n With a *lineno* argument, set a break there in the current file.\n With a *function* argument, set a break at the first executable\n statement within that function. The line number may be prefixed\n with a filename and a colon, to specify a breakpoint in another\n file (probably one that hasn\'t been loaded yet). The file is\n searched on "sys.path". Note that each breakpoint is assigned a\n number to which all the other breakpoint commands refer.\n\n If a second argument is present, it is an expression which must\n evaluate to true before the breakpoint is honored.\n\n Without argument, list all breaks, including for each breakpoint,\n the number of times that breakpoint has been hit, the current\n ignore count, and the associated condition if any.\n\ntbreak [([filename:]lineno | function) [, condition]]\n\n Temporary breakpoint, which is removed automatically when it is\n first hit. The arguments are the same as for "break".\n\ncl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n\n With a *filename:lineno* argument, clear all the breakpoints at\n this line. With a space separated list of breakpoint numbers, clear\n those breakpoints. Without argument, clear all breaks (but first\n ask confirmation).\n\ndisable [bpnumber [bpnumber ...]]\n\n Disable the breakpoints given as a space separated list of\n breakpoint numbers. Disabling a breakpoint means it cannot cause\n the program to stop execution, but unlike clearing a breakpoint, it\n remains in the list of breakpoints and can be (re-)enabled.\n\nenable [bpnumber [bpnumber ...]]\n\n Enable the breakpoints specified.\n\nignore bpnumber [count]\n\n Set the ignore count for the given breakpoint number. If count is\n omitted, the ignore count is set to 0. A breakpoint becomes active\n when the ignore count is zero. When non-zero, the count is\n decremented each time the breakpoint is reached and the breakpoint\n is not disabled and any associated condition evaluates to true.\n\ncondition bpnumber [condition]\n\n Set a new *condition* for the breakpoint, an expression which must\n evaluate to true before the breakpoint is honored. If *condition*\n is absent, any existing condition is removed; i.e., the breakpoint\n is made unconditional.\n\ncommands [bpnumber]\n\n Specify a list of commands for breakpoint number *bpnumber*. The\n commands themselves appear on the following lines. Type a line\n containing just "end" to terminate the commands. An example:\n\n (Pdb) commands 1\n (com) p some_variable\n (com) end\n (Pdb)\n\n To remove all commands from a breakpoint, type commands and follow\n it immediately with "end"; that is, give no commands.\n\n With no *bpnumber* argument, commands refers to the last breakpoint\n set.\n\n You can use breakpoint commands to start your program up again.\n Simply use the continue command, or step, or any other command that\n resumes execution.\n\n Specifying any command resuming execution (currently continue,\n step, next, return, jump, quit and their abbreviations) terminates\n the command list (as if that command was immediately followed by\n end). This is because any time you resume execution (even with a\n simple next or step), you may encounter another breakpoint--which\n could have its own command list, leading to ambiguities about which\n list to execute.\n\n If you use the \'silent\' command in the command list, the usual\n message about stopping at a breakpoint is not printed. This may be\n desirable for breakpoints that are to print a specific message and\n then continue. If none of the other commands print anything, you\n see no sign that the breakpoint was reached.\n\ns(tep)\n\n Execute the current line, stop at the first possible occasion\n (either in a function that is called or on the next line in the\n current function).\n\nn(ext)\n\n Continue execution until the next line in the current function is\n reached or it returns. (The difference between "next" and "step"\n is that "step" stops inside a called function, while "next"\n executes called functions at (nearly) full speed, only stopping at\n the next line in the current function.)\n\nunt(il) [lineno]\n\n Without argument, continue execution until the line with a number\n greater than the current one is reached.\n\n With a line number, continue execution until a line with a number\n greater or equal to that is reached. In both cases, also stop when\n the current frame returns.\n\n Changed in version 3.2: Allow giving an explicit line number.\n\nr(eturn)\n\n Continue execution until the current function returns.\n\nc(ont(inue))\n\n Continue execution, only stop when a breakpoint is encountered.\n\nj(ump) lineno\n\n Set the next line that will be executed. Only available in the\n bottom-most frame. This lets you jump back and execute code again,\n or jump forward to skip code that you don\'t want to run.\n\n It should be noted that not all jumps are allowed -- for instance\n it is not possible to jump into the middle of a "for" loop or out\n of a "finally" clause.\n\nl(ist) [first[, last]]\n\n List source code for the current file. Without arguments, list 11\n lines around the current line or continue the previous listing.\n With "." as argument, list 11 lines around the current line. With\n one argument, list 11 lines around at that line. With two\n arguments, list the given range; if the second argument is less\n than the first, it is interpreted as a count.\n\n The current line in the current frame is indicated by "->". If an\n exception is being debugged, the line where the exception was\n originally raised or propagated is indicated by ">>", if it differs\n from the current line.\n\n New in version 3.2: The ">>" marker.\n\nll | longlist\n\n List all source code for the current function or frame.\n Interesting lines are marked as for "list".\n\n New in version 3.2.\n\na(rgs)\n\n Print the argument list of the current function.\n\np expression\n\n Evaluate the *expression* in the current context and print its\n value.\n\n Note: "print()" can also be used, but is not a debugger command\n --- this executes the Python "print()" function.\n\npp expression\n\n Like the "p" command, except the value of the expression is pretty-\n printed using the "pprint" module.\n\nwhatis expression\n\n Print the type of the *expression*.\n\nsource expression\n\n Try to get source code for the given object and display it.\n\n New in version 3.2.\n\ndisplay [expression]\n\n Display the value of the expression if it changed, each time\n execution stops in the current frame.\n\n Without expression, list all display expressions for the current\n frame.\n\n New in version 3.2.\n\nundisplay [expression]\n\n Do not display the expression any more in the current frame.\n Without expression, clear all display expressions for the current\n frame.\n\n New in version 3.2.\n\ninteract\n\n Start an interative interpreter (using the "code" module) whose\n global namespace contains all the (global and local) names found in\n the current scope.\n\n New in version 3.2.\n\nalias [name [command]]\n\n Create an alias called *name* that executes *command*. The command\n must *not* be enclosed in quotes. Replaceable parameters can be\n indicated by "%1", "%2", and so on, while "%*" is replaced by all\n the parameters. If no command is given, the current alias for\n *name* is shown. If no arguments are given, all aliases are listed.\n\n Aliases may be nested and can contain anything that can be legally\n typed at the pdb prompt. Note that internal pdb commands *can* be\n overridden by aliases. Such a command is then hidden until the\n alias is removed. Aliasing is recursively applied to the first\n word of the command line; all other words in the line are left\n alone.\n\n As an example, here are two useful aliases (especially when placed\n in the ".pdbrc" file):\n\n # Print instance variables (usage "pi classInst")\n alias pi for k in %1.__dict__.keys(): print("%1.",k,"=",%1.__dict__[k])\n # Print instance variables in self\n alias ps pi self\n\nunalias name\n\n Delete the specified alias.\n\n! statement\n\n Execute the (one-line) *statement* in the context of the current\n stack frame. The exclamation point can be omitted unless the first\n word of the statement resembles a debugger command. To set a\n global variable, you can prefix the assignment command with a\n "global" statement on the same line, e.g.:\n\n (Pdb) global list_options; list_options = [\'-l\']\n (Pdb)\n\nrun [args ...]\nrestart [args ...]\n\n Restart the debugged Python program. If an argument is supplied,\n it is split with "shlex" and the result is used as the new\n "sys.argv". History, breakpoints, actions and debugger options are\n preserved. "restart" is an alias for "run".\n\nq(uit)\n\n Quit from the debugger. The program being executed is aborted.\n\n-[ Footnotes ]-\n\n[1] Whether a frame is considered to originate in a certain module\n is determined by the "__name__" in the frame globals.\n', + 'del': u'\nThe "del" statement\n*******************\n\n del_stmt ::= "del" target_list\n\nDeletion is recursively defined very similar to the way assignment is\ndefined. Rather than spelling it out in full details, here are some\nhints.\n\nDeletion of a target list recursively deletes each target, from left\nto right.\n\nDeletion of a name removes the binding of that name from the local or\nglobal namespace, depending on whether the name occurs in a "global"\nstatement in the same code block. If the name is unbound, a\n"NameError" exception will be raised.\n\nDeletion of attribute references, subscriptions and slicings is passed\nto the primary object involved; deletion of a slicing is in general\nequivalent to assignment of an empty slice of the right type (but even\nthis is determined by the sliced object).\n\nChanged in version 3.2: Previously it was illegal to delete a name\nfrom the local namespace if it occurs as a free variable in a nested\nblock.\n', + 'dict': u'\nDictionary displays\n*******************\n\nA dictionary display is a possibly empty series of key/datum pairs\nenclosed in curly braces:\n\n dict_display ::= "{" [key_datum_list | dict_comprehension] "}"\n key_datum_list ::= key_datum ("," key_datum)* [","]\n key_datum ::= expression ":" expression\n dict_comprehension ::= expression ":" expression comp_for\n\nA dictionary display yields a new dictionary object.\n\nIf a comma-separated sequence of key/datum pairs is given, they are\nevaluated from left to right to define the entries of the dictionary:\neach key object is used as a key into the dictionary to store the\ncorresponding datum. This means that you can specify the same key\nmultiple times in the key/datum list, and the final dictionary\'s value\nfor that key will be the last one given.\n\nA dict comprehension, in contrast to list and set comprehensions,\nneeds two expressions separated with a colon followed by the usual\n"for" and "if" clauses. When the comprehension is run, the resulting\nkey and value elements are inserted in the new dictionary in the order\nthey are produced.\n\nRestrictions on the types of the key values are listed earlier in\nsection *The standard type hierarchy*. (To summarize, the key type\nshould be *hashable*, which excludes all mutable objects.) Clashes\nbetween duplicate keys are not detected; the last datum (textually\nrightmost in the display) stored for a given key value prevails.\n', + 'dynamic-features': u'\nInteraction with dynamic features\n*********************************\n\nName resolution of free variables occurs at runtime, not at compile\ntime. This means that the following code will print 42:\n\n i = 10\n def f():\n print(i)\n i = 42\n f()\n\nThere are several cases where Python statements are illegal when used\nin conjunction with nested scopes that contain free variables.\n\nIf a variable is referenced in an enclosing scope, it is illegal to\ndelete the name. An error will be reported at compile time.\n\nThe "eval()" and "exec()" functions do not have access to the full\nenvironment for resolving names. Names may be resolved in the local\nand global namespaces of the caller. Free variables are not resolved\nin the nearest enclosing namespace, but in the global namespace. [1]\nThe "exec()" and "eval()" functions have optional arguments to\noverride the global and local namespace. If only one namespace is\nspecified, it is used for both.\n', + 'else': u'\nThe "if" statement\n******************\n\nThe "if" statement is used for conditional execution:\n\n if_stmt ::= "if" expression ":" suite\n ( "elif" expression ":" suite )*\n ["else" ":" suite]\n\nIt selects exactly one of the suites by evaluating the expressions one\nby one until one is found to be true (see section *Boolean operations*\nfor the definition of true and false); then that suite is executed\n(and no other part of the "if" statement is executed or evaluated).\nIf all expressions are false, the suite of the "else" clause, if\npresent, is executed.\n', + 'exceptions': u'\nExceptions\n**********\n\nExceptions are a means of breaking out of the normal flow of control\nof a code block in order to handle errors or other exceptional\nconditions. An exception is *raised* at the point where the error is\ndetected; it may be *handled* by the surrounding code block or by any\ncode block that directly or indirectly invoked the code block where\nthe error occurred.\n\nThe Python interpreter raises an exception when it detects a run-time\nerror (such as division by zero). A Python program can also\nexplicitly raise an exception with the "raise" statement. Exception\nhandlers are specified with the "try" ... "except" statement. The\n"finally" clause of such a statement can be used to specify cleanup\ncode which does not handle the exception, but is executed whether an\nexception occurred or not in the preceding code.\n\nPython uses the "termination" model of error handling: an exception\nhandler can find out what happened and continue execution at an outer\nlevel, but it cannot repair the cause of the error and retry the\nfailing operation (except by re-entering the offending piece of code\nfrom the top).\n\nWhen an exception is not handled at all, the interpreter terminates\nexecution of the program, or returns to its interactive main loop. In\neither case, it prints a stack backtrace, except when the exception is\n"SystemExit".\n\nExceptions are identified by class instances. The "except" clause is\nselected depending on the class of the instance: it must reference the\nclass of the instance or a base class thereof. The instance can be\nreceived by the handler and can carry additional information about the\nexceptional condition.\n\nNote: Exception messages are not part of the Python API. Their\n contents may change from one version of Python to the next without\n warning and should not be relied on by code which will run under\n multiple versions of the interpreter.\n\nSee also the description of the "try" statement in section *The try\nstatement* and "raise" statement in section *The raise statement*.\n\n-[ Footnotes ]-\n\n[1] This limitation occurs because the code that is executed by\n these operations is not available at the time the module is\n compiled.\n', + 'execmodel': u'\nExecution model\n***************\n\n\nStructure of a program\n======================\n\nA Python program is constructed from code blocks. A *block* is a piece\nof Python program text that is executed as a unit. The following are\nblocks: a module, a function body, and a class definition. Each\ncommand typed interactively is a block. A script file (a file given\nas standard input to the interpreter or specified as a command line\nargument to the interpreter) is a code block. A script command (a\ncommand specified on the interpreter command line with the \'**-c**\'\noption) is a code block. The string argument passed to the built-in\nfunctions "eval()" and "exec()" is a code block.\n\nA code block is executed in an *execution frame*. A frame contains\nsome administrative information (used for debugging) and determines\nwhere and how execution continues after the code block\'s execution has\ncompleted.\n\n\nNaming and binding\n==================\n\n\nBinding of names\n----------------\n\n*Names* refer to objects. Names are introduced by name binding\noperations.\n\nThe following constructs bind names: formal parameters to functions,\n"import" statements, class and function definitions (these bind the\nclass or function name in the defining block), and targets that are\nidentifiers if occurring in an assignment, "for" loop header, or after\n"as" in a "with" statement or "except" clause. The "import" statement\nof the form "from ... import *" binds all names defined in the\nimported module, except those beginning with an underscore. This form\nmay only be used at the module level.\n\nA target occurring in a "del" statement is also considered bound for\nthis purpose (though the actual semantics are to unbind the name).\n\nEach assignment or import statement occurs within a block defined by a\nclass or function definition or at the module level (the top-level\ncode block).\n\nIf a name is bound in a block, it is a local variable of that block,\nunless declared as "nonlocal" or "global". If a name is bound at the\nmodule level, it is a global variable. (The variables of the module\ncode block are local and global.) If a variable is used in a code\nblock but not defined there, it is a *free variable*.\n\nEach occurrence of a name in the program text refers to the *binding*\nof that name established by the following name resolution rules.\n\n\nResolution of names\n-------------------\n\nA *scope* defines the visibility of a name within a block. If a local\nvariable is defined in a block, its scope includes that block. If the\ndefinition occurs in a function block, the scope extends to any blocks\ncontained within the defining one, unless a contained block introduces\na different binding for the name.\n\nWhen a name is used in a code block, it is resolved using the nearest\nenclosing scope. The set of all such scopes visible to a code block\nis called the block\'s *environment*.\n\nWhen a name is not found at all, a "NameError" exception is raised. If\nthe current scope is a function scope, and the name refers to a local\nvariable that has not yet been bound to a value at the point where the\nname is used, an "UnboundLocalError" exception is raised.\n"UnboundLocalError" is a subclass of "NameError".\n\nIf a name binding operation occurs anywhere within a code block, all\nuses of the name within the block are treated as references to the\ncurrent block. This can lead to errors when a name is used within a\nblock before it is bound. This rule is subtle. Python lacks\ndeclarations and allows name binding operations to occur anywhere\nwithin a code block. The local variables of a code block can be\ndetermined by scanning the entire text of the block for name binding\noperations.\n\nIf the "global" statement occurs within a block, all uses of the name\nspecified in the statement refer to the binding of that name in the\ntop-level namespace. Names are resolved in the top-level namespace by\nsearching the global namespace, i.e. the namespace of the module\ncontaining the code block, and the builtins namespace, the namespace\nof the module "builtins". The global namespace is searched first. If\nthe name is not found there, the builtins namespace is searched. The\n"global" statement must precede all uses of the name.\n\nThe "global" statement has the same scope as a name binding operation\nin the same block. If the nearest enclosing scope for a free variable\ncontains a global statement, the free variable is treated as a global.\n\nThe "nonlocal" statement causes corresponding names to refer to\npreviously bound variables in the nearest enclosing function scope.\n"SyntaxError" is raised at compile time if the given name does not\nexist in any enclosing function scope.\n\nThe namespace for a module is automatically created the first time a\nmodule is imported. The main module for a script is always called\n"__main__".\n\nClass definition blocks and arguments to "exec()" and "eval()" are\nspecial in the context of name resolution. A class definition is an\nexecutable statement that may use and define names. These references\nfollow the normal rules for name resolution with an exception that\nunbound local variables are looked up in the global namespace. The\nnamespace of the class definition becomes the attribute dictionary of\nthe class. The scope of names defined in a class block is limited to\nthe class block; it does not extend to the code blocks of methods --\nthis includes comprehensions and generator expressions since they are\nimplemented using a function scope. This means that the following\nwill fail:\n\n class A:\n a = 42\n b = list(a + i for i in range(10))\n\n\nBuiltins and restricted execution\n---------------------------------\n\nThe builtins namespace associated with the execution of a code block\nis actually found by looking up the name "__builtins__" in its global\nnamespace; this should be a dictionary or a module (in the latter case\nthe module\'s dictionary is used). By default, when in the "__main__"\nmodule, "__builtins__" is the built-in module "builtins"; when in any\nother module, "__builtins__" is an alias for the dictionary of the\n"builtins" module itself. "__builtins__" can be set to a user-created\ndictionary to create a weak form of restricted execution.\n\n**CPython implementation detail:** Users should not touch\n"__builtins__"; it is strictly an implementation detail. Users\nwanting to override values in the builtins namespace should "import"\nthe "builtins" module and modify its attributes appropriately.\n\n\nInteraction with dynamic features\n---------------------------------\n\nName resolution of free variables occurs at runtime, not at compile\ntime. This means that the following code will print 42:\n\n i = 10\n def f():\n print(i)\n i = 42\n f()\n\nThere are several cases where Python statements are illegal when used\nin conjunction with nested scopes that contain free variables.\n\nIf a variable is referenced in an enclosing scope, it is illegal to\ndelete the name. An error will be reported at compile time.\n\nThe "eval()" and "exec()" functions do not have access to the full\nenvironment for resolving names. Names may be resolved in the local\nand global namespaces of the caller. Free variables are not resolved\nin the nearest enclosing namespace, but in the global namespace. [1]\nThe "exec()" and "eval()" functions have optional arguments to\noverride the global and local namespace. If only one namespace is\nspecified, it is used for both.\n\n\nExceptions\n==========\n\nExceptions are a means of breaking out of the normal flow of control\nof a code block in order to handle errors or other exceptional\nconditions. An exception is *raised* at the point where the error is\ndetected; it may be *handled* by the surrounding code block or by any\ncode block that directly or indirectly invoked the code block where\nthe error occurred.\n\nThe Python interpreter raises an exception when it detects a run-time\nerror (such as division by zero). A Python program can also\nexplicitly raise an exception with the "raise" statement. Exception\nhandlers are specified with the "try" ... "except" statement. The\n"finally" clause of such a statement can be used to specify cleanup\ncode which does not handle the exception, but is executed whether an\nexception occurred or not in the preceding code.\n\nPython uses the "termination" model of error handling: an exception\nhandler can find out what happened and continue execution at an outer\nlevel, but it cannot repair the cause of the error and retry the\nfailing operation (except by re-entering the offending piece of code\nfrom the top).\n\nWhen an exception is not handled at all, the interpreter terminates\nexecution of the program, or returns to its interactive main loop. In\neither case, it prints a stack backtrace, except when the exception is\n"SystemExit".\n\nExceptions are identified by class instances. The "except" clause is\nselected depending on the class of the instance: it must reference the\nclass of the instance or a base class thereof. The instance can be\nreceived by the handler and can carry additional information about the\nexceptional condition.\n\nNote: Exception messages are not part of the Python API. Their\n contents may change from one version of Python to the next without\n warning and should not be relied on by code which will run under\n multiple versions of the interpreter.\n\nSee also the description of the "try" statement in section *The try\nstatement* and "raise" statement in section *The raise statement*.\n\n-[ Footnotes ]-\n\n[1] This limitation occurs because the code that is executed by\n these operations is not available at the time the module is\n compiled.\n', + 'exprlists': u'\nExpression lists\n****************\n\n expression_list ::= expression ( "," expression )* [","]\n\nAn expression list containing at least one comma yields a tuple. The\nlength of the tuple is the number of expressions in the list. The\nexpressions are evaluated from left to right.\n\nThe trailing comma is required only to create a single tuple (a.k.a. a\n*singleton*); it is optional in all other cases. A single expression\nwithout a trailing comma doesn\'t create a tuple, but rather yields the\nvalue of that expression. (To create an empty tuple, use an empty pair\nof parentheses: "()".)\n', + 'floating': u'\nFloating point literals\n***********************\n\nFloating point literals are described by the following lexical\ndefinitions:\n\n floatnumber ::= pointfloat | exponentfloat\n pointfloat ::= [intpart] fraction | intpart "."\n exponentfloat ::= (intpart | pointfloat) exponent\n intpart ::= digit+\n fraction ::= "." digit+\n exponent ::= ("e" | "E") ["+" | "-"] digit+\n\nNote that the integer and exponent parts are always interpreted using\nradix 10. For example, "077e010" is legal, and denotes the same number\nas "77e10". The allowed range of floating point literals is\nimplementation-dependent. Some examples of floating point literals:\n\n 3.14 10. .001 1e100 3.14e-10 0e0\n\nNote that numeric literals do not include a sign; a phrase like "-1"\nis actually an expression composed of the unary operator "-" and the\nliteral "1".\n', + 'for': u'\nThe "for" statement\n*******************\n\nThe "for" statement is used to iterate over the elements of a sequence\n(such as a string, tuple or list) or other iterable object:\n\n for_stmt ::= "for" target_list "in" expression_list ":" suite\n ["else" ":" suite]\n\nThe expression list is evaluated once; it should yield an iterable\nobject. An iterator is created for the result of the\n"expression_list". The suite is then executed once for each item\nprovided by the iterator, in the order returned by the iterator. Each\nitem in turn is assigned to the target list using the standard rules\nfor assignments (see *Assignment statements*), and then the suite is\nexecuted. When the items are exhausted (which is immediately when the\nsequence is empty or an iterator raises a "StopIteration" exception),\nthe suite in the "else" clause, if present, is executed, and the loop\nterminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and continues\nwith the next item, or with the "else" clause if there is no next\nitem.\n\nThe for-loop makes assignments to the variables(s) in the target list.\nThis overwrites all previous assignments to those variables including\nthose made in the suite of the for-loop:\n\n for i in range(10):\n print(i)\n i = 5 # this will not affect the for-loop\n # because i will be overwritten with the next\n # index in the range\n\nNames in the target list are not deleted when the loop is finished,\nbut if the sequence is empty, they will not have been assigned to at\nall by the loop. Hint: the built-in function "range()" returns an\niterator of integers suitable to emulate the effect of Pascal\'s "for i\n:= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n\nNote: There is a subtlety when the sequence is being modified by the\n loop (this can only occur for mutable sequences, i.e. lists). An\n internal counter is used to keep track of which item is used next,\n and this is incremented on each iteration. When this counter has\n reached the length of the sequence the loop terminates. This means\n that if the suite deletes the current (or a previous) item from the\n sequence, the next item will be skipped (since it gets the index of\n the current item which has already been treated). Likewise, if the\n suite inserts an item in the sequence before the current item, the\n current item will be treated again the next time through the loop.\n This can lead to nasty bugs that can be avoided by making a\n temporary copy using a slice of the whole sequence, e.g.,\n\n for x in a[:]:\n if x < 0: a.remove(x)\n', + 'formatstrings': u'\nFormat String Syntax\n********************\n\nThe "str.format()" method and the "Formatter" class share the same\nsyntax for format strings (although in the case of "Formatter",\nsubclasses can define their own format string syntax).\n\nFormat strings contain "replacement fields" surrounded by curly braces\n"{}". Anything that is not contained in braces is considered literal\ntext, which is copied unchanged to the output. If you need to include\na brace character in the literal text, it can be escaped by doubling:\n"{{" and "}}".\n\nThe grammar for a replacement field is as follows:\n\n replacement_field ::= "{" [field_name] ["!" conversion] [":" format_spec] "}"\n field_name ::= arg_name ("." attribute_name | "[" element_index "]")*\n arg_name ::= [identifier | integer]\n attribute_name ::= identifier\n element_index ::= integer | index_string\n index_string ::= +\n conversion ::= "r" | "s" | "a"\n format_spec ::= \n\nIn less formal terms, the replacement field can start with a\n*field_name* that specifies the object whose value is to be formatted\nand inserted into the output instead of the replacement field. The\n*field_name* is optionally followed by a *conversion* field, which is\npreceded by an exclamation point "\'!\'", and a *format_spec*, which is\npreceded by a colon "\':\'". These specify a non-default format for the\nreplacement value.\n\nSee also the *Format Specification Mini-Language* section.\n\nThe *field_name* itself begins with an *arg_name* that is either a\nnumber or a keyword. If it\'s a number, it refers to a positional\nargument, and if it\'s a keyword, it refers to a named keyword\nargument. If the numerical arg_names in a format string are 0, 1, 2,\n... in sequence, they can all be omitted (not just some) and the\nnumbers 0, 1, 2, ... will be automatically inserted in that order.\nBecause *arg_name* is not quote-delimited, it is not possible to\nspecify arbitrary dictionary keys (e.g., the strings "\'10\'" or\n"\':-]\'") within a format string. The *arg_name* can be followed by any\nnumber of index or attribute expressions. An expression of the form\n"\'.name\'" selects the named attribute using "getattr()", while an\nexpression of the form "\'[index]\'" does an index lookup using\n"__getitem__()".\n\nChanged in version 3.1: The positional argument specifiers can be\nomitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n\nSome simple format string examples:\n\n "First, thou shalt count to {0}" # References first positional argument\n "Bring me a {}" # Implicitly references the first positional argument\n "From {} to {}" # Same as "From {0} to {1}"\n "My quest is {name}" # References keyword argument \'name\'\n "Weight in tons {0.weight}" # \'weight\' attribute of first positional arg\n "Units destroyed: {players[0]}" # First element of keyword argument \'players\'.\n\nThe *conversion* field causes a type coercion before formatting.\nNormally, the job of formatting a value is done by the "__format__()"\nmethod of the value itself. However, in some cases it is desirable to\nforce a type to be formatted as a string, overriding its own\ndefinition of formatting. By converting the value to a string before\ncalling "__format__()", the normal formatting logic is bypassed.\n\nThree conversion flags are currently supported: "\'!s\'" which calls\n"str()" on the value, "\'!r\'" which calls "repr()" and "\'!a\'" which\ncalls "ascii()".\n\nSome examples:\n\n "Harold\'s a clever {0!s}" # Calls str() on the argument first\n "Bring out the holy {name!r}" # Calls repr() on the argument first\n "More {!a}" # Calls ascii() on the argument first\n\nThe *format_spec* field contains a specification of how the value\nshould be presented, including such details as field width, alignment,\npadding, decimal precision and so on. Each value type can define its\nown "formatting mini-language" or interpretation of the *format_spec*.\n\nMost built-in types support a common formatting mini-language, which\nis described in the next section.\n\nA *format_spec* field can also include nested replacement fields\nwithin it. These nested replacement fields can contain only a field\nname; conversion flags and format specifications are not allowed. The\nreplacement fields within the format_spec are substituted before the\n*format_spec* string is interpreted. This allows the formatting of a\nvalue to be dynamically specified.\n\nSee the *Format examples* section for some examples.\n\n\nFormat Specification Mini-Language\n==================================\n\n"Format specifications" are used within replacement fields contained\nwithin a format string to define how individual values are presented\n(see *Format String Syntax*). They can also be passed directly to the\nbuilt-in "format()" function. Each formattable type may define how\nthe format specification is to be interpreted.\n\nMost built-in types implement the following options for format\nspecifications, although some of the formatting options are only\nsupported by the numeric types.\n\nA general convention is that an empty format string ("""") produces\nthe same result as if you had called "str()" on the value. A non-empty\nformat string typically modifies the result.\n\nThe general form of a *standard format specifier* is:\n\n format_spec ::= [[fill]align][sign][#][0][width][,][.precision][type]\n fill ::= \n align ::= "<" | ">" | "=" | "^"\n sign ::= "+" | "-" | " "\n width ::= integer\n precision ::= integer\n type ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n\nIf a valid *align* value is specified, it can be preceded by a *fill*\ncharacter that can be any character and defaults to a space if\nomitted. Note that it is not possible to use "{" and "}" as *fill*\nchar while using the "str.format()" method; this limitation however\ndoesn\'t affect the "format()" function.\n\nThe meaning of the various alignment options is as follows:\n\n +-----------+------------------------------------------------------------+\n | Option | Meaning |\n +===========+============================================================+\n | "\'<\'" | Forces the field to be left-aligned within the available |\n | | space (this is the default for most objects). |\n +-----------+------------------------------------------------------------+\n | "\'>\'" | Forces the field to be right-aligned within the available |\n | | space (this is the default for numbers). |\n +-----------+------------------------------------------------------------+\n | "\'=\'" | Forces the padding to be placed after the sign (if any) |\n | | but before the digits. This is used for printing fields |\n | | in the form \'+000000120\'. This alignment option is only |\n | | valid for numeric types. |\n +-----------+------------------------------------------------------------+\n | "\'^\'" | Forces the field to be centered within the available |\n | | space. |\n +-----------+------------------------------------------------------------+\n\nNote that unless a minimum field width is defined, the field width\nwill always be the same size as the data to fill it, so that the\nalignment option has no meaning in this case.\n\nThe *sign* option is only valid for number types, and can be one of\nthe following:\n\n +-----------+------------------------------------------------------------+\n | Option | Meaning |\n +===========+============================================================+\n | "\'+\'" | indicates that a sign should be used for both positive as |\n | | well as negative numbers. |\n +-----------+------------------------------------------------------------+\n | "\'-\'" | indicates that a sign should be used only for negative |\n | | numbers (this is the default behavior). |\n +-----------+------------------------------------------------------------+\n | space | indicates that a leading space should be used on positive |\n | | numbers, and a minus sign on negative numbers. |\n +-----------+------------------------------------------------------------+\n\nThe "\'#\'" option causes the "alternate form" to be used for the\nconversion. The alternate form is defined differently for different\ntypes. This option is only valid for integer, float, complex and\nDecimal types. For integers, when binary, octal, or hexadecimal output\nis used, this option adds the prefix respective "\'0b\'", "\'0o\'", or\n"\'0x\'" to the output value. For floats, complex and Decimal the\nalternate form causes the result of the conversion to always contain a\ndecimal-point character, even if no digits follow it. Normally, a\ndecimal-point character appears in the result of these conversions\nonly if a digit follows it. In addition, for "\'g\'" and "\'G\'"\nconversions, trailing zeros are not removed from the result.\n\nThe "\',\'" option signals the use of a comma for a thousands separator.\nFor a locale aware separator, use the "\'n\'" integer presentation type\ninstead.\n\nChanged in version 3.1: Added the "\',\'" option (see also **PEP 378**).\n\n*width* is a decimal integer defining the minimum field width. If not\nspecified, then the field width will be determined by the content.\n\nPreceding the *width* field by a zero ("\'0\'") character enables sign-\naware zero-padding for numeric types. This is equivalent to a *fill*\ncharacter of "\'0\'" with an *alignment* type of "\'=\'".\n\nThe *precision* is a decimal number indicating how many digits should\nbe displayed after the decimal point for a floating point value\nformatted with "\'f\'" and "\'F\'", or before and after the decimal point\nfor a floating point value formatted with "\'g\'" or "\'G\'". For non-\nnumber types the field indicates the maximum field size - in other\nwords, how many characters will be used from the field content. The\n*precision* is not allowed for integer values.\n\nFinally, the *type* determines how the data should be presented.\n\nThe available string presentation types are:\n\n +-----------+------------------------------------------------------------+\n | Type | Meaning |\n +===========+============================================================+\n | "\'s\'" | String format. This is the default type for strings and |\n | | may be omitted. |\n +-----------+------------------------------------------------------------+\n | None | The same as "\'s\'". |\n +-----------+------------------------------------------------------------+\n\nThe available integer presentation types are:\n\n +-----------+------------------------------------------------------------+\n | Type | Meaning |\n +===========+============================================================+\n | "\'b\'" | Binary format. Outputs the number in base 2. |\n +-----------+------------------------------------------------------------+\n | "\'c\'" | Character. Converts the integer to the corresponding |\n | | unicode character before printing. |\n +-----------+------------------------------------------------------------+\n | "\'d\'" | Decimal Integer. Outputs the number in base 10. |\n +-----------+------------------------------------------------------------+\n | "\'o\'" | Octal format. Outputs the number in base 8. |\n +-----------+------------------------------------------------------------+\n | "\'x\'" | Hex format. Outputs the number in base 16, using lower- |\n | | case letters for the digits above 9. |\n +-----------+------------------------------------------------------------+\n | "\'X\'" | Hex format. Outputs the number in base 16, using upper- |\n | | case letters for the digits above 9. |\n +-----------+------------------------------------------------------------+\n | "\'n\'" | Number. This is the same as "\'d\'", except that it uses the |\n | | current locale setting to insert the appropriate number |\n | | separator characters. |\n +-----------+------------------------------------------------------------+\n | None | The same as "\'d\'". |\n +-----------+------------------------------------------------------------+\n\nIn addition to the above presentation types, integers can be formatted\nwith the floating point presentation types listed below (except "\'n\'"\nand None). When doing so, "float()" is used to convert the integer to\na floating point number before formatting.\n\nThe available presentation types for floating point and decimal values\nare:\n\n +-----------+------------------------------------------------------------+\n | Type | Meaning |\n +===========+============================================================+\n | "\'e\'" | Exponent notation. Prints the number in scientific |\n | | notation using the letter \'e\' to indicate the exponent. |\n | | The default precision is "6". |\n +-----------+------------------------------------------------------------+\n | "\'E\'" | Exponent notation. Same as "\'e\'" except it uses an upper |\n | | case \'E\' as the separator character. |\n +-----------+------------------------------------------------------------+\n | "\'f\'" | Fixed point. Displays the number as a fixed-point number. |\n | | The default precision is "6". |\n +-----------+------------------------------------------------------------+\n | "\'F\'" | Fixed point. Same as "\'f\'", but converts "nan" to "NAN" |\n | | and "inf" to "INF". |\n +-----------+------------------------------------------------------------+\n | "\'g\'" | General format. For a given precision "p >= 1", this |\n | | rounds the number to "p" significant digits and then |\n | | formats the result in either fixed-point format or in |\n | | scientific notation, depending on its magnitude. The |\n | | precise rules are as follows: suppose that the result |\n | | formatted with presentation type "\'e\'" and precision "p-1" |\n | | would have exponent "exp". Then if "-4 <= exp < p", the |\n | | number is formatted with presentation type "\'f\'" and |\n | | precision "p-1-exp". Otherwise, the number is formatted |\n | | with presentation type "\'e\'" and precision "p-1". In both |\n | | cases insignificant trailing zeros are removed from the |\n | | significand, and the decimal point is also removed if |\n | | there are no remaining digits following it. Positive and |\n | | negative infinity, positive and negative zero, and nans, |\n | | are formatted as "inf", "-inf", "0", "-0" and "nan" |\n | | respectively, regardless of the precision. A precision of |\n | | "0" is treated as equivalent to a precision of "1". The |\n | | default precision is "6". |\n +-----------+------------------------------------------------------------+\n | "\'G\'" | General format. Same as "\'g\'" except switches to "\'E\'" if |\n | | the number gets too large. The representations of infinity |\n | | and NaN are uppercased, too. |\n +-----------+------------------------------------------------------------+\n | "\'n\'" | Number. This is the same as "\'g\'", except that it uses the |\n | | current locale setting to insert the appropriate number |\n | | separator characters. |\n +-----------+------------------------------------------------------------+\n | "\'%\'" | Percentage. Multiplies the number by 100 and displays in |\n | | fixed ("\'f\'") format, followed by a percent sign. |\n +-----------+------------------------------------------------------------+\n | None | Similar to "\'g\'", except that fixed-point notation, when |\n | | used, has at least one digit past the decimal point. The |\n | | default precision is as high as needed to represent the |\n | | particular value. The overall effect is to match the |\n | | output of "str()" as altered by the other format |\n | | modifiers. |\n +-----------+------------------------------------------------------------+\n\n\nFormat examples\n===============\n\nThis section contains examples of the new format syntax and comparison\nwith the old "%"-formatting.\n\nIn most of the cases the syntax is similar to the old "%"-formatting,\nwith the addition of the "{}" and with ":" used instead of "%". For\nexample, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n\nThe new format syntax also supports new and different options, shown\nin the follow examples.\n\nAccessing arguments by position:\n\n >>> \'{0}, {1}, {2}\'.format(\'a\', \'b\', \'c\')\n \'a, b, c\'\n >>> \'{}, {}, {}\'.format(\'a\', \'b\', \'c\') # 3.1+ only\n \'a, b, c\'\n >>> \'{2}, {1}, {0}\'.format(\'a\', \'b\', \'c\')\n \'c, b, a\'\n >>> \'{2}, {1}, {0}\'.format(*\'abc\') # unpacking argument sequence\n \'c, b, a\'\n >>> \'{0}{1}{0}\'.format(\'abra\', \'cad\') # arguments\' indices can be repeated\n \'abracadabra\'\n\nAccessing arguments by name:\n\n >>> \'Coordinates: {latitude}, {longitude}\'.format(latitude=\'37.24N\', longitude=\'-115.81W\')\n \'Coordinates: 37.24N, -115.81W\'\n >>> coord = {\'latitude\': \'37.24N\', \'longitude\': \'-115.81W\'}\n >>> \'Coordinates: {latitude}, {longitude}\'.format(**coord)\n \'Coordinates: 37.24N, -115.81W\'\n\nAccessing arguments\' attributes:\n\n >>> c = 3-5j\n >>> (\'The complex number {0} is formed from the real part {0.real} \'\n ... \'and the imaginary part {0.imag}.\').format(c)\n \'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.\'\n >>> class Point:\n ... def __init__(self, x, y):\n ... self.x, self.y = x, y\n ... def __str__(self):\n ... return \'Point({self.x}, {self.y})\'.format(self=self)\n ...\n >>> str(Point(4, 2))\n \'Point(4, 2)\'\n\nAccessing arguments\' items:\n\n >>> coord = (3, 5)\n >>> \'X: {0[0]}; Y: {0[1]}\'.format(coord)\n \'X: 3; Y: 5\'\n\nReplacing "%s" and "%r":\n\n >>> "repr() shows quotes: {!r}; str() doesn\'t: {!s}".format(\'test1\', \'test2\')\n "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n\nAligning the text and specifying a width:\n\n >>> \'{:<30}\'.format(\'left aligned\')\n \'left aligned \'\n >>> \'{:>30}\'.format(\'right aligned\')\n \' right aligned\'\n >>> \'{:^30}\'.format(\'centered\')\n \' centered \'\n >>> \'{:*^30}\'.format(\'centered\') # use \'*\' as a fill char\n \'***********centered***********\'\n\nReplacing "%+f", "%-f", and "% f" and specifying a sign:\n\n >>> \'{:+f}; {:+f}\'.format(3.14, -3.14) # show it always\n \'+3.140000; -3.140000\'\n >>> \'{: f}; {: f}\'.format(3.14, -3.14) # show a space for positive numbers\n \' 3.140000; -3.140000\'\n >>> \'{:-f}; {:-f}\'.format(3.14, -3.14) # show only the minus -- same as \'{:f}; {:f}\'\n \'3.140000; -3.140000\'\n\nReplacing "%x" and "%o" and converting the value to different bases:\n\n >>> # format also supports binary numbers\n >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)\n \'int: 42; hex: 2a; oct: 52; bin: 101010\'\n >>> # with 0x, 0o, or 0b as prefix:\n >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)\n \'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010\'\n\nUsing the comma as a thousands separator:\n\n >>> \'{:,}\'.format(1234567890)\n \'1,234,567,890\'\n\nExpressing a percentage:\n\n >>> points = 19\n >>> total = 22\n >>> \'Correct answers: {:.2%}\'.format(points/total)\n \'Correct answers: 86.36%\'\n\nUsing type-specific formatting:\n\n >>> import datetime\n >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n >>> \'{:%Y-%m-%d %H:%M:%S}\'.format(d)\n \'2010-07-04 12:15:58\'\n\nNesting arguments and more complex examples:\n\n >>> for align, text in zip(\'<^>\', [\'left\', \'center\', \'right\']):\n ... \'{0:{fill}{align}16}\'.format(text, fill=align, align=align)\n ...\n \'left<<<<<<<<<<<<\'\n \'^^^^^center^^^^^\'\n \'>>>>>>>>>>>right\'\n >>>\n >>> octets = [192, 168, 0, 1]\n >>> \'{:02X}{:02X}{:02X}{:02X}\'.format(*octets)\n \'C0A80001\'\n >>> int(_, 16)\n 3232235521\n >>>\n >>> width = 5\n >>> for num in range(5,12): #doctest: +NORMALIZE_WHITESPACE\n ... for base in \'dXob\':\n ... print(\'{0:{width}{base}}\'.format(num, base=base, width=width), end=\' \')\n ... print()\n ...\n 5 5 5 101\n 6 6 6 110\n 7 7 7 111\n 8 8 10 1000\n 9 9 11 1001\n 10 A 12 1010\n 11 B 13 1011\n', + 'function': u'\nFunction definitions\n********************\n\nA function definition defines a user-defined function object (see\nsection *The standard type hierarchy*):\n\n funcdef ::= [decorators] "def" funcname "(" [parameter_list] ")" ["->" expression] ":" suite\n decorators ::= decorator+\n decorator ::= "@" dotted_name ["(" [parameter_list [","]] ")"] NEWLINE\n dotted_name ::= identifier ("." identifier)*\n parameter_list ::= (defparameter ",")*\n | "*" [parameter] ("," defparameter)* ["," "**" parameter]\n | "**" parameter\n | defparameter [","] )\n parameter ::= identifier [":" expression]\n defparameter ::= parameter ["=" expression]\n funcname ::= identifier\n\nA function definition is an executable statement. Its execution binds\nthe function name in the current local namespace to a function object\n(a wrapper around the executable code for the function). This\nfunction object contains a reference to the current global namespace\nas the global namespace to be used when the function is called.\n\nThe function definition does not execute the function body; this gets\nexecuted only when the function is called. [3]\n\nA function definition may be wrapped by one or more *decorator*\nexpressions. Decorator expressions are evaluated when the function is\ndefined, in the scope that contains the function definition. The\nresult must be a callable, which is invoked with the function object\nas the only argument. The returned value is bound to the function name\ninstead of the function object. Multiple decorators are applied in\nnested fashion. For example, the following code\n\n @f1(arg)\n @f2\n def func(): pass\n\nis equivalent to\n\n def func(): pass\n func = f1(arg)(f2(func))\n\nWhen one or more *parameters* have the form *parameter* "="\n*expression*, the function is said to have "default parameter values."\nFor a parameter with a default value, the corresponding *argument* may\nbe omitted from a call, in which case the parameter\'s default value is\nsubstituted. If a parameter has a default value, all following\nparameters up until the ""*"" must also have a default value --- this\nis a syntactic restriction that is not expressed by the grammar.\n\n**Default parameter values are evaluated from left to right when the\nfunction definition is executed.** This means that the expression is\nevaluated once, when the function is defined, and that the same "pre-\ncomputed" value is used for each call. This is especially important\nto understand when a default parameter is a mutable object, such as a\nlist or a dictionary: if the function modifies the object (e.g. by\nappending an item to a list), the default value is in effect modified.\nThis is generally not what was intended. A way around this is to use\n"None" as the default, and explicitly test for it in the body of the\nfunction, e.g.:\n\n def whats_on_the_telly(penguin=None):\n if penguin is None:\n penguin = []\n penguin.append("property of the zoo")\n return penguin\n\nFunction call semantics are described in more detail in section\n*Calls*. A function call always assigns values to all parameters\nmentioned in the parameter list, either from position arguments, from\nkeyword arguments, or from default values. If the form\n""*identifier"" is present, it is initialized to a tuple receiving any\nexcess positional parameters, defaulting to the empty tuple. If the\nform ""**identifier"" is present, it is initialized to a new\ndictionary receiving any excess keyword arguments, defaulting to a new\nempty dictionary. Parameters after ""*"" or ""*identifier"" are\nkeyword-only parameters and may only be passed used keyword arguments.\n\nParameters may have annotations of the form "": expression"" following\nthe parameter name. Any parameter may have an annotation even those\nof the form "*identifier" or "**identifier". Functions may have\n"return" annotation of the form ""-> expression"" after the parameter\nlist. These annotations can be any valid Python expression and are\nevaluated when the function definition is executed. Annotations may\nbe evaluated in a different order than they appear in the source code.\nThe presence of annotations does not change the semantics of a\nfunction. The annotation values are available as values of a\ndictionary keyed by the parameters\' names in the "__annotations__"\nattribute of the function object.\n\nIt is also possible to create anonymous functions (functions not bound\nto a name), for immediate use in expressions. This uses lambda\nexpressions, described in section *Lambdas*. Note that the lambda\nexpression is merely a shorthand for a simplified function definition;\na function defined in a ""def"" statement can be passed around or\nassigned to another name just like a function defined by a lambda\nexpression. The ""def"" form is actually more powerful since it\nallows the execution of multiple statements and annotations.\n\n**Programmer\'s note:** Functions are first-class objects. A ""def""\nstatement executed inside a function definition defines a local\nfunction that can be returned or passed around. Free variables used\nin the nested function can access the local variables of the function\ncontaining the def. See section *Naming and binding* for details.\n\nSee also: **PEP 3107** - Function Annotations\n\n The original specification for function annotations.\n', + 'global': u'\nThe "global" statement\n**********************\n\n global_stmt ::= "global" identifier ("," identifier)*\n\nThe "global" statement is a declaration which holds for the entire\ncurrent code block. It means that the listed identifiers are to be\ninterpreted as globals. It would be impossible to assign to a global\nvariable without "global", although free variables may refer to\nglobals without being declared global.\n\nNames listed in a "global" statement must not be used in the same code\nblock textually preceding that "global" statement.\n\nNames listed in a "global" statement must not be defined as formal\nparameters or in a "for" loop control target, "class" definition,\nfunction definition, or "import" statement.\n\n**CPython implementation detail:** The current implementation does not\nenforce the two restrictions, but programs should not abuse this\nfreedom, as future implementations may enforce them or silently change\nthe meaning of the program.\n\n**Programmer\'s note:** the "global" is a directive to the parser. It\napplies only to code parsed at the same time as the "global"\nstatement. In particular, a "global" statement contained in a string\nor code object supplied to the built-in "exec()" function does not\naffect the code block *containing* the function call, and code\ncontained in such a string is unaffected by "global" statements in the\ncode containing the function call. The same applies to the "eval()"\nand "compile()" functions.\n', + 'id-classes': u'\nReserved classes of identifiers\n*******************************\n\nCertain classes of identifiers (besides keywords) have special\nmeanings. These classes are identified by the patterns of leading and\ntrailing underscore characters:\n\n"_*"\n Not imported by "from module import *". The special identifier "_"\n is used in the interactive interpreter to store the result of the\n last evaluation; it is stored in the "builtins" module. When not\n in interactive mode, "_" has no special meaning and is not defined.\n See section *The import statement*.\n\n Note: The name "_" is often used in conjunction with\n internationalization; refer to the documentation for the\n "gettext" module for more information on this convention.\n\n"__*__"\n System-defined names. These names are defined by the interpreter\n and its implementation (including the standard library). Current\n system names are discussed in the *Special method names* section\n and elsewhere. More will likely be defined in future versions of\n Python. *Any* use of "__*__" names, in any context, that does not\n follow explicitly documented use, is subject to breakage without\n warning.\n\n"__*"\n Class-private names. Names in this category, when used within the\n context of a class definition, are re-written to use a mangled form\n to help avoid name clashes between "private" attributes of base and\n derived classes. See section *Identifiers (Names)*.\n', + 'identifiers': u'\nIdentifiers and keywords\n************************\n\nIdentifiers (also referred to as *names*) are described by the\nfollowing lexical definitions.\n\nThe syntax of identifiers in Python is based on the Unicode standard\nannex UAX-31, with elaboration and changes as defined below; see also\n**PEP 3131** for further details.\n\nWithin the ASCII range (U+0001..U+007F), the valid characters for\nidentifiers are the same as in Python 2.x: the uppercase and lowercase\nletters "A" through "Z", the underscore "_" and, except for the first\ncharacter, the digits "0" through "9".\n\nPython 3.0 introduces additional characters from outside the ASCII\nrange (see **PEP 3131**). For these characters, the classification\nuses the version of the Unicode Character Database as included in the\n"unicodedata" module.\n\nIdentifiers are unlimited in length. Case is significant.\n\n identifier ::= xid_start xid_continue*\n id_start ::= \n id_continue ::= \n xid_start ::= \n xid_continue ::= \n\nThe Unicode category codes mentioned above stand for:\n\n* *Lu* - uppercase letters\n\n* *Ll* - lowercase letters\n\n* *Lt* - titlecase letters\n\n* *Lm* - modifier letters\n\n* *Lo* - other letters\n\n* *Nl* - letter numbers\n\n* *Mn* - nonspacing marks\n\n* *Mc* - spacing combining marks\n\n* *Nd* - decimal numbers\n\n* *Pc* - connector punctuations\n\n* *Other_ID_Start* - explicit list of characters in PropList.txt to\n support backwards compatibility\n\n* *Other_ID_Continue* - likewise\n\nAll identifiers are converted into the normal form NFKC while parsing;\ncomparison of identifiers is based on NFKC.\n\nA non-normative HTML file listing all valid identifier characters for\nUnicode 4.1 can be found at http://www.dcl.hpi.uni-\npotsdam.de/home/loewis/table-3131.html.\n\n\nKeywords\n========\n\nThe following identifiers are used as reserved words, or *keywords* of\nthe language, and cannot be used as ordinary identifiers. They must\nbe spelled exactly as written here:\n\n False class finally is return\n None continue for lambda try\n True def from nonlocal while\n and del global not with\n as elif if or yield\n assert else import pass\n break except in raise\n\n\nReserved classes of identifiers\n===============================\n\nCertain classes of identifiers (besides keywords) have special\nmeanings. These classes are identified by the patterns of leading and\ntrailing underscore characters:\n\n"_*"\n Not imported by "from module import *". The special identifier "_"\n is used in the interactive interpreter to store the result of the\n last evaluation; it is stored in the "builtins" module. When not\n in interactive mode, "_" has no special meaning and is not defined.\n See section *The import statement*.\n\n Note: The name "_" is often used in conjunction with\n internationalization; refer to the documentation for the\n "gettext" module for more information on this convention.\n\n"__*__"\n System-defined names. These names are defined by the interpreter\n and its implementation (including the standard library). Current\n system names are discussed in the *Special method names* section\n and elsewhere. More will likely be defined in future versions of\n Python. *Any* use of "__*__" names, in any context, that does not\n follow explicitly documented use, is subject to breakage without\n warning.\n\n"__*"\n Class-private names. Names in this category, when used within the\n context of a class definition, are re-written to use a mangled form\n to help avoid name clashes between "private" attributes of base and\n derived classes. See section *Identifiers (Names)*.\n', + 'if': u'\nThe "if" statement\n******************\n\nThe "if" statement is used for conditional execution:\n\n if_stmt ::= "if" expression ":" suite\n ( "elif" expression ":" suite )*\n ["else" ":" suite]\n\nIt selects exactly one of the suites by evaluating the expressions one\nby one until one is found to be true (see section *Boolean operations*\nfor the definition of true and false); then that suite is executed\n(and no other part of the "if" statement is executed or evaluated).\nIf all expressions are false, the suite of the "else" clause, if\npresent, is executed.\n', + 'imaginary': u'\nImaginary literals\n******************\n\nImaginary literals are described by the following lexical definitions:\n\n imagnumber ::= (floatnumber | intpart) ("j" | "J")\n\nAn imaginary literal yields a complex number with a real part of 0.0.\nComplex numbers are represented as a pair of floating point numbers\nand have the same restrictions on their range. To create a complex\nnumber with a nonzero real part, add a floating point number to it,\ne.g., "(3+4j)". Some examples of imaginary literals:\n\n 3.14j 10.j 10j .001j 1e100j 3.14e-10j\n', + 'import': u'\nThe "import" statement\n**********************\n\n import_stmt ::= "import" module ["as" name] ( "," module ["as" name] )*\n | "from" relative_module "import" identifier ["as" name]\n ( "," identifier ["as" name] )*\n | "from" relative_module "import" "(" identifier ["as" name]\n ( "," identifier ["as" name] )* [","] ")"\n | "from" module "import" "*"\n module ::= (identifier ".")* identifier\n relative_module ::= "."* module | "."+\n name ::= identifier\n\nThe basic import statement (no "from" clause) is executed in two\nsteps:\n\n1. find a module, loading and initializing it if necessary\n\n2. define a name or names in the local namespace for the scope\n where the "import" statement occurs.\n\nWhen the statement contains multiple clauses (separated by commas) the\ntwo steps are carried out separately for each clause, just as though\nthe clauses had been separated out into individiual import statements.\n\nThe details of the first step, finding and loading modules are\ndescribed in greater detail in the section on the *import system*,\nwhich also describes the various types of packages and modules that\ncan be imported, as well as all the hooks that can be used to\ncustomize the import system. Note that failures in this step may\nindicate either that the module could not be located, *or* that an\nerror occurred while initializing the module, which includes execution\nof the module\'s code.\n\nIf the requested module is retrieved successfully, it will be made\navailable in the local namespace in one of three ways:\n\n* If the module name is followed by "as", then the name following\n "as" is bound directly to the imported module.\n\n* If no other name is specified, and the module being imported is a\n top level module, the module\'s name is bound in the local namespace\n as a reference to the imported module\n\n* If the module being imported is *not* a top level module, then the\n name of the top level package that contains the module is bound in\n the local namespace as a reference to the top level package. The\n imported module must be accessed using its full qualified name\n rather than directly\n\nThe "from" form uses a slightly more complex process:\n\n1. find the module specified in the "from" clause, loading and\n initializing it if necessary;\n\n2. for each of the identifiers specified in the "import" clauses:\n\n 1. check if the imported module has an attribute by that name\n\n 2. if not, attempt to import a submodule with that name and then\n check the imported module again for that attribute\n\n 3. if the attribute is not found, "ImportError" is raised.\n\n 4. otherwise, a reference to that value is stored in the local\n namespace, using the name in the "as" clause if it is present,\n otherwise using the attribute name\n\nExamples:\n\n import foo # foo imported and bound locally\n import foo.bar.baz # foo.bar.baz imported, foo bound locally\n import foo.bar.baz as fbb # foo.bar.baz imported and bound as fbb\n from foo.bar import baz # foo.bar.baz imported and bound as baz\n from foo import attr # foo imported and foo.attr bound as attr\n\nIf the list of identifiers is replaced by a star ("\'*\'"), all public\nnames defined in the module are bound in the local namespace for the\nscope where the "import" statement occurs.\n\nThe *public names* defined by a module are determined by checking the\nmodule\'s namespace for a variable named "__all__"; if defined, it must\nbe a sequence of strings which are names defined or imported by that\nmodule. The names given in "__all__" are all considered public and\nare required to exist. If "__all__" is not defined, the set of public\nnames includes all names found in the module\'s namespace which do not\nbegin with an underscore character ("\'_\'"). "__all__" should contain\nthe entire public API. It is intended to avoid accidentally exporting\nitems that are not part of the API (such as library modules which were\nimported and used within the module).\n\nThe wild card form of import --- "from module import *" --- is only\nallowed at the module level. Attempting to use it in class or\nfunction definitions will raise a "SyntaxError".\n\nWhen specifying what module to import you do not have to specify the\nabsolute name of the module. When a module or package is contained\nwithin another package it is possible to make a relative import within\nthe same top package without having to mention the package name. By\nusing leading dots in the specified module or package after "from" you\ncan specify how high to traverse up the current package hierarchy\nwithout specifying exact names. One leading dot means the current\npackage where the module making the import exists. Two dots means up\none package level. Three dots is up two levels, etc. So if you execute\n"from . import mod" from a module in the "pkg" package then you will\nend up importing "pkg.mod". If you execute "from ..subpkg2 import mod"\nfrom within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\nspecification for relative imports is contained within **PEP 328**.\n\n"importlib.import_module()" is provided to support applications that\ndetermine dynamically the modules to be loaded.\n\n\nFuture statements\n=================\n\nA *future statement* is a directive to the compiler that a particular\nmodule should be compiled using syntax or semantics that will be\navailable in a specified future release of Python where the feature\nbecomes standard.\n\nThe future statement is intended to ease migration to future versions\nof Python that introduce incompatible changes to the language. It\nallows use of the new features on a per-module basis before the\nrelease in which the feature becomes standard.\n\n future_statement ::= "from" "__future__" "import" feature ["as" name]\n ("," feature ["as" name])*\n | "from" "__future__" "import" "(" feature ["as" name]\n ("," feature ["as" name])* [","] ")"\n feature ::= identifier\n name ::= identifier\n\nA future statement must appear near the top of the module. The only\nlines that can appear before a future statement are:\n\n* the module docstring (if any),\n\n* comments,\n\n* blank lines, and\n\n* other future statements.\n\nThe features recognized by Python 3.0 are "absolute_import",\n"division", "generators", "unicode_literals", "print_function",\n"nested_scopes" and "with_statement". They are all redundant because\nthey are always enabled, and only kept for backwards compatibility.\n\nA future statement is recognized and treated specially at compile\ntime: Changes to the semantics of core constructs are often\nimplemented by generating different code. It may even be the case\nthat a new feature introduces new incompatible syntax (such as a new\nreserved word), in which case the compiler may need to parse the\nmodule differently. Such decisions cannot be pushed off until\nruntime.\n\nFor any given release, the compiler knows which feature names have\nbeen defined, and raises a compile-time error if a future statement\ncontains a feature not known to it.\n\nThe direct runtime semantics are the same as for any import statement:\nthere is a standard module "__future__", described later, and it will\nbe imported in the usual way at the time the future statement is\nexecuted.\n\nThe interesting runtime semantics depend on the specific feature\nenabled by the future statement.\n\nNote that there is nothing special about the statement:\n\n import __future__ [as name]\n\nThat is not a future statement; it\'s an ordinary import statement with\nno special semantics or syntax restrictions.\n\nCode compiled by calls to the built-in functions "exec()" and\n"compile()" that occur in a module "M" containing a future statement\nwill, by default, use the new syntax or semantics associated with the\nfuture statement. This can be controlled by optional arguments to\n"compile()" --- see the documentation of that function for details.\n\nA future statement typed at an interactive interpreter prompt will\ntake effect for the rest of the interpreter session. If an\ninterpreter is started with the *-i* option, is passed a script name\nto execute, and the script includes a future statement, it will be in\neffect in the interactive session started after the script is\nexecuted.\n\nSee also: **PEP 236** - Back to the __future__\n\n The original proposal for the __future__ mechanism.\n', + 'in': u'\nMembership test operations\n**************************\n\nThe operators "in" and "not in" test for membership. "x in s"\nevaluates to true if *x* is a member of *s*, and false otherwise. "x\nnot in s" returns the negation of "x in s". All built-in sequences\nand set types support this as well as dictionary, for which "in" tests\nwhether the dictionary has a given key. For container types such as\nlist, tuple, set, frozenset, dict, or collections.deque, the\nexpression "x in y" is equivalent to "any(x is e or x == e for e in\ny)".\n\nFor the string and bytes types, "x in y" is true if and only if *x* is\na substring of *y*. An equivalent test is "y.find(x) != -1". Empty\nstrings are always considered to be a substring of any other string,\nso """ in "abc"" will return "True".\n\nFor user-defined classes which define the "__contains__()" method, "x\nin y" is true if and only if "y.__contains__(x)" is true.\n\nFor user-defined classes which do not define "__contains__()" but do\ndefine "__iter__()", "x in y" is true if some value "z" with "x == z"\nis produced while iterating over "y". If an exception is raised\nduring the iteration, it is as if "in" raised that exception.\n\nLastly, the old-style iteration protocol is tried: if a class defines\n"__getitem__()", "x in y" is true if and only if there is a non-\nnegative integer index *i* such that "x == y[i]", and all lower\ninteger indices do not raise "IndexError" exception. (If any other\nexception is raised, it is as if "in" raised that exception).\n\nThe operator "not in" is defined to have the inverse true value of\n"in".\n', + 'integers': u'\nInteger literals\n****************\n\nInteger literals are described by the following lexical definitions:\n\n integer ::= decimalinteger | octinteger | hexinteger | bininteger\n decimalinteger ::= nonzerodigit digit* | "0"+\n nonzerodigit ::= "1"..."9"\n digit ::= "0"..."9"\n octinteger ::= "0" ("o" | "O") octdigit+\n hexinteger ::= "0" ("x" | "X") hexdigit+\n bininteger ::= "0" ("b" | "B") bindigit+\n octdigit ::= "0"..."7"\n hexdigit ::= digit | "a"..."f" | "A"..."F"\n bindigit ::= "0" | "1"\n\nThere is no limit for the length of integer literals apart from what\ncan be stored in available memory.\n\nNote that leading zeros in a non-zero decimal number are not allowed.\nThis is for disambiguation with C-style octal literals, which Python\nused before version 3.0.\n\nSome examples of integer literals:\n\n 7 2147483647 0o177 0b100110111\n 3 79228162514264337593543950336 0o377 0xdeadbeef\n', + 'lambda': u'\nLambdas\n*******\n\n lambda_expr ::= "lambda" [parameter_list]: expression\n lambda_expr_nocond ::= "lambda" [parameter_list]: expression_nocond\n\nLambda expressions (sometimes called lambda forms) are used to create\nanonymous functions. The expression "lambda arguments: expression"\nyields a function object. The unnamed object behaves like a function\nobject defined with\n\n def (arguments):\n return expression\n\nSee section *Function definitions* for the syntax of parameter lists.\nNote that functions created with lambda expressions cannot contain\nstatements or annotations.\n', + 'lists': u'\nList displays\n*************\n\nA list display is a possibly empty series of expressions enclosed in\nsquare brackets:\n\n list_display ::= "[" [expression_list | comprehension] "]"\n\nA list display yields a new list object, the contents being specified\nby either a list of expressions or a comprehension. When a comma-\nseparated list of expressions is supplied, its elements are evaluated\nfrom left to right and placed into the list object in that order.\nWhen a comprehension is supplied, the list is constructed from the\nelements resulting from the comprehension.\n', + 'naming': u'\nNaming and binding\n******************\n\n\nBinding of names\n================\n\n*Names* refer to objects. Names are introduced by name binding\noperations.\n\nThe following constructs bind names: formal parameters to functions,\n"import" statements, class and function definitions (these bind the\nclass or function name in the defining block), and targets that are\nidentifiers if occurring in an assignment, "for" loop header, or after\n"as" in a "with" statement or "except" clause. The "import" statement\nof the form "from ... import *" binds all names defined in the\nimported module, except those beginning with an underscore. This form\nmay only be used at the module level.\n\nA target occurring in a "del" statement is also considered bound for\nthis purpose (though the actual semantics are to unbind the name).\n\nEach assignment or import statement occurs within a block defined by a\nclass or function definition or at the module level (the top-level\ncode block).\n\nIf a name is bound in a block, it is a local variable of that block,\nunless declared as "nonlocal" or "global". If a name is bound at the\nmodule level, it is a global variable. (The variables of the module\ncode block are local and global.) If a variable is used in a code\nblock but not defined there, it is a *free variable*.\n\nEach occurrence of a name in the program text refers to the *binding*\nof that name established by the following name resolution rules.\n\n\nResolution of names\n===================\n\nA *scope* defines the visibility of a name within a block. If a local\nvariable is defined in a block, its scope includes that block. If the\ndefinition occurs in a function block, the scope extends to any blocks\ncontained within the defining one, unless a contained block introduces\na different binding for the name.\n\nWhen a name is used in a code block, it is resolved using the nearest\nenclosing scope. The set of all such scopes visible to a code block\nis called the block\'s *environment*.\n\nWhen a name is not found at all, a "NameError" exception is raised. If\nthe current scope is a function scope, and the name refers to a local\nvariable that has not yet been bound to a value at the point where the\nname is used, an "UnboundLocalError" exception is raised.\n"UnboundLocalError" is a subclass of "NameError".\n\nIf a name binding operation occurs anywhere within a code block, all\nuses of the name within the block are treated as references to the\ncurrent block. This can lead to errors when a name is used within a\nblock before it is bound. This rule is subtle. Python lacks\ndeclarations and allows name binding operations to occur anywhere\nwithin a code block. The local variables of a code block can be\ndetermined by scanning the entire text of the block for name binding\noperations.\n\nIf the "global" statement occurs within a block, all uses of the name\nspecified in the statement refer to the binding of that name in the\ntop-level namespace. Names are resolved in the top-level namespace by\nsearching the global namespace, i.e. the namespace of the module\ncontaining the code block, and the builtins namespace, the namespace\nof the module "builtins". The global namespace is searched first. If\nthe name is not found there, the builtins namespace is searched. The\n"global" statement must precede all uses of the name.\n\nThe "global" statement has the same scope as a name binding operation\nin the same block. If the nearest enclosing scope for a free variable\ncontains a global statement, the free variable is treated as a global.\n\nThe "nonlocal" statement causes corresponding names to refer to\npreviously bound variables in the nearest enclosing function scope.\n"SyntaxError" is raised at compile time if the given name does not\nexist in any enclosing function scope.\n\nThe namespace for a module is automatically created the first time a\nmodule is imported. The main module for a script is always called\n"__main__".\n\nClass definition blocks and arguments to "exec()" and "eval()" are\nspecial in the context of name resolution. A class definition is an\nexecutable statement that may use and define names. These references\nfollow the normal rules for name resolution with an exception that\nunbound local variables are looked up in the global namespace. The\nnamespace of the class definition becomes the attribute dictionary of\nthe class. The scope of names defined in a class block is limited to\nthe class block; it does not extend to the code blocks of methods --\nthis includes comprehensions and generator expressions since they are\nimplemented using a function scope. This means that the following\nwill fail:\n\n class A:\n a = 42\n b = list(a + i for i in range(10))\n\n\nBuiltins and restricted execution\n=================================\n\nThe builtins namespace associated with the execution of a code block\nis actually found by looking up the name "__builtins__" in its global\nnamespace; this should be a dictionary or a module (in the latter case\nthe module\'s dictionary is used). By default, when in the "__main__"\nmodule, "__builtins__" is the built-in module "builtins"; when in any\nother module, "__builtins__" is an alias for the dictionary of the\n"builtins" module itself. "__builtins__" can be set to a user-created\ndictionary to create a weak form of restricted execution.\n\n**CPython implementation detail:** Users should not touch\n"__builtins__"; it is strictly an implementation detail. Users\nwanting to override values in the builtins namespace should "import"\nthe "builtins" module and modify its attributes appropriately.\n\n\nInteraction with dynamic features\n=================================\n\nName resolution of free variables occurs at runtime, not at compile\ntime. This means that the following code will print 42:\n\n i = 10\n def f():\n print(i)\n i = 42\n f()\n\nThere are several cases where Python statements are illegal when used\nin conjunction with nested scopes that contain free variables.\n\nIf a variable is referenced in an enclosing scope, it is illegal to\ndelete the name. An error will be reported at compile time.\n\nThe "eval()" and "exec()" functions do not have access to the full\nenvironment for resolving names. Names may be resolved in the local\nand global namespaces of the caller. Free variables are not resolved\nin the nearest enclosing namespace, but in the global namespace. [1]\nThe "exec()" and "eval()" functions have optional arguments to\noverride the global and local namespace. If only one namespace is\nspecified, it is used for both.\n', + 'nonlocal': u'\nThe "nonlocal" statement\n************************\n\n nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n\nThe "nonlocal" statement causes the listed identifiers to refer to\npreviously bound variables in the nearest enclosing scope excluding\nglobals. This is important because the default behavior for binding is\nto search the local namespace first. The statement allows\nencapsulated code to rebind variables outside of the local scope\nbesides the global (module) scope.\n\nNames listed in a "nonlocal" statement, unlike those listed in a\n"global" statement, must refer to pre-existing bindings in an\nenclosing scope (the scope in which a new binding should be created\ncannot be determined unambiguously).\n\nNames listed in a "nonlocal" statement must not collide with pre-\nexisting bindings in the local scope.\n\nSee also: **PEP 3104** - Access to Names in Outer Scopes\n\n The specification for the "nonlocal" statement.\n', + 'numbers': u'\nNumeric literals\n****************\n\nThere are three types of numeric literals: integers, floating point\nnumbers, and imaginary numbers. There are no complex literals\n(complex numbers can be formed by adding a real number and an\nimaginary number).\n\nNote that numeric literals do not include a sign; a phrase like "-1"\nis actually an expression composed of the unary operator \'"-"\' and the\nliteral "1".\n', + 'numeric-types': u'\nEmulating numeric types\n***********************\n\nThe following methods can be defined to emulate numeric objects.\nMethods corresponding to operations that are not supported by the\nparticular kind of number implemented (e.g., bitwise operations for\nnon-integral numbers) should be left undefined.\n\nobject.__add__(self, other)\nobject.__sub__(self, other)\nobject.__mul__(self, other)\nobject.__truediv__(self, other)\nobject.__floordiv__(self, other)\nobject.__mod__(self, other)\nobject.__divmod__(self, other)\nobject.__pow__(self, other[, modulo])\nobject.__lshift__(self, other)\nobject.__rshift__(self, other)\nobject.__and__(self, other)\nobject.__xor__(self, other)\nobject.__or__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|"). For instance, to evaluate the\n expression "x + y", where *x* is an instance of a class that has an\n "__add__()" method, "x.__add__(y)" is called. The "__divmod__()"\n method should be the equivalent to using "__floordiv__()" and\n "__mod__()"; it should not be related to "__truediv__()". Note\n that "__pow__()" should be defined to accept an optional third\n argument if the ternary version of the built-in "pow()" function is\n to be supported.\n\n If one of those methods does not support the operation with the\n supplied arguments, it should return "NotImplemented".\n\nobject.__radd__(self, other)\nobject.__rsub__(self, other)\nobject.__rmul__(self, other)\nobject.__rtruediv__(self, other)\nobject.__rfloordiv__(self, other)\nobject.__rmod__(self, other)\nobject.__rdivmod__(self, other)\nobject.__rpow__(self, other)\nobject.__rlshift__(self, other)\nobject.__rrshift__(self, other)\nobject.__rand__(self, other)\nobject.__rxor__(self, other)\nobject.__ror__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|") with reflected (swapped) operands.\n These functions are only called if the left operand does not\n support the corresponding operation and the operands are of\n different types. [2] For instance, to evaluate the expression "x -\n y", where *y* is an instance of a class that has an "__rsub__()"\n method, "y.__rsub__(x)" is called if "x.__sub__(y)" returns\n *NotImplemented*.\n\n Note that ternary "pow()" will not try calling "__rpow__()" (the\n coercion rules would become too complicated).\n\n Note: If the right operand\'s type is a subclass of the left\n operand\'s type and that subclass provides the reflected method\n for the operation, this method will be called before the left\n operand\'s non-reflected method. This behavior allows subclasses\n to override their ancestors\' operations.\n\nobject.__iadd__(self, other)\nobject.__isub__(self, other)\nobject.__imul__(self, other)\nobject.__itruediv__(self, other)\nobject.__ifloordiv__(self, other)\nobject.__imod__(self, other)\nobject.__ipow__(self, other[, modulo])\nobject.__ilshift__(self, other)\nobject.__irshift__(self, other)\nobject.__iand__(self, other)\nobject.__ixor__(self, other)\nobject.__ior__(self, other)\n\n These methods are called to implement the augmented arithmetic\n assignments ("+=", "-=", "*=", "/=", "//=", "%=", "**=", "<<=",\n ">>=", "&=", "^=", "|="). These methods should attempt to do the\n operation in-place (modifying *self*) and return the result (which\n could be, but does not have to be, *self*). If a specific method\n is not defined, the augmented assignment falls back to the normal\n methods. For instance, if *x* is an instance of a class with an\n "__iadd__()" method, "x += y" is equivalent to "x = x.__iadd__(y)"\n . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are considered, as\n with the evaluation of "x + y". In certain situations, augmented\n assignment can result in unexpected errors (see *Why does\n a_tuple[i] += [\'item\'] raise an exception when the addition\n works?*), but this behavior is in fact part of the data model.\n\nobject.__neg__(self)\nobject.__pos__(self)\nobject.__abs__(self)\nobject.__invert__(self)\n\n Called to implement the unary arithmetic operations ("-", "+",\n "abs()" and "~").\n\nobject.__complex__(self)\nobject.__int__(self)\nobject.__float__(self)\nobject.__round__(self[, n])\n\n Called to implement the built-in functions "complex()", "int()",\n "float()" and "round()". Should return a value of the appropriate\n type.\n\nobject.__index__(self)\n\n Called to implement "operator.index()", and whenever Python needs\n to losslessly convert the numeric object to an integer object (such\n as in slicing, or in the built-in "bin()", "hex()" and "oct()"\n functions). Presence of this method indicates that the numeric\n object is an integer type. Must return an integer.\n\n Note: In order to have a coherent integer type class, when\n "__index__()" is defined "__int__()" should also be defined, and\n both should return the same value.\n', + 'objects': u'\nObjects, values and types\n*************************\n\n*Objects* are Python\'s abstraction for data. All data in a Python\nprogram is represented by objects or by relations between objects. (In\na sense, and in conformance to Von Neumann\'s model of a "stored\nprogram computer," code is also represented by objects.)\n\nEvery object has an identity, a type and a value. An object\'s\n*identity* never changes once it has been created; you may think of it\nas the object\'s address in memory. The \'"is"\' operator compares the\nidentity of two objects; the "id()" function returns an integer\nrepresenting its identity.\n\n**CPython implementation detail:** For CPython, "id(x)" is the memory\naddress where "x" is stored.\n\nAn object\'s type determines the operations that the object supports\n(e.g., "does it have a length?") and also defines the possible values\nfor objects of that type. The "type()" function returns an object\'s\ntype (which is an object itself). Like its identity, an object\'s\n*type* is also unchangeable. [1]\n\nThe *value* of some objects can change. Objects whose value can\nchange are said to be *mutable*; objects whose value is unchangeable\nonce they are created are called *immutable*. (The value of an\nimmutable container object that contains a reference to a mutable\nobject can change when the latter\'s value is changed; however the\ncontainer is still considered immutable, because the collection of\nobjects it contains cannot be changed. So, immutability is not\nstrictly the same as having an unchangeable value, it is more subtle.)\nAn object\'s mutability is determined by its type; for instance,\nnumbers, strings and tuples are immutable, while dictionaries and\nlists are mutable.\n\nObjects are never explicitly destroyed; however, when they become\nunreachable they may be garbage-collected. An implementation is\nallowed to postpone garbage collection or omit it altogether --- it is\na matter of implementation quality how garbage collection is\nimplemented, as long as no objects are collected that are still\nreachable.\n\n**CPython implementation detail:** CPython currently uses a reference-\ncounting scheme with (optional) delayed detection of cyclically linked\ngarbage, which collects most objects as soon as they become\nunreachable, but is not guaranteed to collect garbage containing\ncircular references. See the documentation of the "gc" module for\ninformation on controlling the collection of cyclic garbage. Other\nimplementations act differently and CPython may change. Do not depend\non immediate finalization of objects when they become unreachable (so\nyou should always close files explicitly).\n\nNote that the use of the implementation\'s tracing or debugging\nfacilities may keep objects alive that would normally be collectable.\nAlso note that catching an exception with a \'"try"..."except"\'\nstatement may keep objects alive.\n\nSome objects contain references to "external" resources such as open\nfiles or windows. It is understood that these resources are freed\nwhen the object is garbage-collected, but since garbage collection is\nnot guaranteed to happen, such objects also provide an explicit way to\nrelease the external resource, usually a "close()" method. Programs\nare strongly recommended to explicitly close such objects. The\n\'"try"..."finally"\' statement and the \'"with"\' statement provide\nconvenient ways to do this.\n\nSome objects contain references to other objects; these are called\n*containers*. Examples of containers are tuples, lists and\ndictionaries. The references are part of a container\'s value. In\nmost cases, when we talk about the value of a container, we imply the\nvalues, not the identities of the contained objects; however, when we\ntalk about the mutability of a container, only the identities of the\nimmediately contained objects are implied. So, if an immutable\ncontainer (like a tuple) contains a reference to a mutable object, its\nvalue changes if that mutable object is changed.\n\nTypes affect almost all aspects of object behavior. Even the\nimportance of object identity is affected in some sense: for immutable\ntypes, operations that compute new values may actually return a\nreference to any existing object with the same type and value, while\nfor mutable objects this is not allowed. E.g., after "a = 1; b = 1",\n"a" and "b" may or may not refer to the same object with the value\none, depending on the implementation, but after "c = []; d = []", "c"\nand "d" are guaranteed to refer to two different, unique, newly\ncreated empty lists. (Note that "c = d = []" assigns the same object\nto both "c" and "d".)\n', + 'operator-summary': u'\nOperator precedence\n*******************\n\nThe following table summarizes the operator precedence in Python, from\nlowest precedence (least binding) to highest precedence (most\nbinding). Operators in the same box have the same precedence. Unless\nthe syntax is explicitly given, operators are binary. Operators in\nthe same box group left to right (except for exponentiation, which\ngroups from right to left).\n\nNote that comparisons, membership tests, and identity tests, all have\nthe same precedence and have a left-to-right chaining feature as\ndescribed in the *Comparisons* section.\n\n+-------------------------------------------------+---------------------------------------+\n| Operator | Description |\n+=================================================+=======================================+\n| "lambda" | Lambda expression |\n+-------------------------------------------------+---------------------------------------+\n| "if" -- "else" | Conditional expression |\n+-------------------------------------------------+---------------------------------------+\n| "or" | Boolean OR |\n+-------------------------------------------------+---------------------------------------+\n| "and" | Boolean AND |\n+-------------------------------------------------+---------------------------------------+\n| "not" "x" | Boolean NOT |\n+-------------------------------------------------+---------------------------------------+\n| "in", "not in", "is", "is not", "<", "<=", ">", | Comparisons, including membership |\n| ">=", "!=", "==" | tests and identity tests |\n+-------------------------------------------------+---------------------------------------+\n| "|" | Bitwise OR |\n+-------------------------------------------------+---------------------------------------+\n| "^" | Bitwise XOR |\n+-------------------------------------------------+---------------------------------------+\n| "&" | Bitwise AND |\n+-------------------------------------------------+---------------------------------------+\n| "<<", ">>" | Shifts |\n+-------------------------------------------------+---------------------------------------+\n| "+", "-" | Addition and subtraction |\n+-------------------------------------------------+---------------------------------------+\n| "*", "/", "//", "%" | Multiplication, division, remainder |\n| | [5] |\n+-------------------------------------------------+---------------------------------------+\n| "+x", "-x", "~x" | Positive, negative, bitwise NOT |\n+-------------------------------------------------+---------------------------------------+\n| "**" | Exponentiation [6] |\n+-------------------------------------------------+---------------------------------------+\n| "x[index]", "x[index:index]", | Subscription, slicing, call, |\n| "x(arguments...)", "x.attribute" | attribute reference |\n+-------------------------------------------------+---------------------------------------+\n| "(expressions...)", "[expressions...]", "{key: | Binding or tuple display, list |\n| value...}", "{expressions...}" | display, dictionary display, set |\n| | display |\n+-------------------------------------------------+---------------------------------------+\n\n-[ Footnotes ]-\n\n[1] While "abs(x%y) < abs(y)" is true mathematically, for floats\n it may not be true numerically due to roundoff. For example, and\n assuming a platform on which a Python float is an IEEE 754 double-\n precision number, in order that "-1e-100 % 1e100" have the same\n sign as "1e100", the computed result is "-1e-100 + 1e100", which\n is numerically exactly equal to "1e100". The function\n "math.fmod()" returns a result whose sign matches the sign of the\n first argument instead, and so returns "-1e-100" in this case.\n Which approach is more appropriate depends on the application.\n\n[2] If x is very close to an exact integer multiple of y, it\'s\n possible for "x//y" to be one larger than "(x-x%y)//y" due to\n rounding. In such cases, Python returns the latter result, in\n order to preserve that "divmod(x,y)[0] * y + x % y" be very close\n to "x".\n\n[3] The Unicode standard distinguishes between *code points* (e.g.\n U+0041) and *abstract characters* (e.g. "LATIN CAPITAL LETTER A").\n While most abstract characters in Unicode are only represented\n using one code point, there is a number of abstract characters\n that can in addition be represented using a sequence of more than\n one code point. For example, the abstract character "LATIN\n CAPITAL LETTER C WITH CEDILLA" can be represented as a single\n *precomposed character* at code position U+00C7, or as a sequence\n of a *base character* at code position U+0043 (LATIN CAPITAL\n LETTER C), followed by a *combining character* at code position\n U+0327 (COMBINING CEDILLA).\n\n The comparison operators on strings compare at the level of\n Unicode code points. This may be counter-intuitive to humans. For\n example, ""\\u00C7" == "\\u0043\\u0327"" is "False", even though both\n strings represent the same abstract character "LATIN CAPITAL\n LETTER C WITH CEDILLA".\n\n To compare strings at the level of abstract characters (that is,\n in a way intuitive to humans), use "unicodedata.normalize()".\n\n[4] Due to automatic garbage-collection, free lists, and the\n dynamic nature of descriptors, you may notice seemingly unusual\n behaviour in certain uses of the "is" operator, like those\n involving comparisons between instance methods, or constants.\n Check their documentation for more info.\n\n[5] The "%" operator is also used for string formatting; the same\n precedence applies.\n\n[6] The power operator "**" binds less tightly than an arithmetic\n or bitwise unary operator on its right, that is, "2**-1" is "0.5".\n', + 'pass': u'\nThe "pass" statement\n********************\n\n pass_stmt ::= "pass"\n\n"pass" is a null operation --- when it is executed, nothing happens.\nIt is useful as a placeholder when a statement is required\nsyntactically, but no code needs to be executed, for example:\n\n def f(arg): pass # a function that does nothing (yet)\n\n class C: pass # a class with no methods (yet)\n', + 'power': u'\nThe power operator\n******************\n\nThe power operator binds more tightly than unary operators on its\nleft; it binds less tightly than unary operators on its right. The\nsyntax is:\n\n power ::= primary ["**" u_expr]\n\nThus, in an unparenthesized sequence of power and unary operators, the\noperators are evaluated from right to left (this does not constrain\nthe evaluation order for the operands): "-1**2" results in "-1".\n\nThe power operator has the same semantics as the built-in "pow()"\nfunction, when called with two arguments: it yields its left argument\nraised to the power of its right argument. The numeric arguments are\nfirst converted to a common type, and the result is of that type.\n\nFor int operands, the result has the same type as the operands unless\nthe second argument is negative; in that case, all arguments are\nconverted to float and a float result is delivered. For example,\n"10**2" returns "100", but "10**-2" returns "0.01".\n\nRaising "0.0" to a negative power results in a "ZeroDivisionError".\nRaising a negative number to a fractional power results in a "complex"\nnumber. (In earlier versions it raised a "ValueError".)\n', + 'raise': u'\nThe "raise" statement\n*********************\n\n raise_stmt ::= "raise" [expression ["from" expression]]\n\nIf no expressions are present, "raise" re-raises the last exception\nthat was active in the current scope. If no exception is active in\nthe current scope, a "RuntimeError" exception is raised indicating\nthat this is an error.\n\nOtherwise, "raise" evaluates the first expression as the exception\nobject. It must be either a subclass or an instance of\n"BaseException". If it is a class, the exception instance will be\nobtained when needed by instantiating the class with no arguments.\n\nThe *type* of the exception is the exception instance\'s class, the\n*value* is the instance itself.\n\nA traceback object is normally created automatically when an exception\nis raised and attached to it as the "__traceback__" attribute, which\nis writable. You can create an exception and set your own traceback in\none step using the "with_traceback()" exception method (which returns\nthe same exception instance, with its traceback set to its argument),\nlike so:\n\n raise Exception("foo occurred").with_traceback(tracebackobj)\n\nThe "from" clause is used for exception chaining: if given, the second\n*expression* must be another exception class or instance, which will\nthen be attached to the raised exception as the "__cause__" attribute\n(which is writable). If the raised exception is not handled, both\nexceptions will be printed:\n\n >>> try:\n ... print(1 / 0)\n ... except Exception as exc:\n ... raise RuntimeError("Something bad happened") from exc\n ...\n Traceback (most recent call last):\n File "", line 2, in \n ZeroDivisionError: int division or modulo by zero\n\n The above exception was the direct cause of the following exception:\n\n Traceback (most recent call last):\n File "", line 4, in \n RuntimeError: Something bad happened\n\nA similar mechanism works implicitly if an exception is raised inside\nan exception handler or a "finally" clause: the previous exception is\nthen attached as the new exception\'s "__context__" attribute:\n\n >>> try:\n ... print(1 / 0)\n ... except:\n ... raise RuntimeError("Something bad happened")\n ...\n Traceback (most recent call last):\n File "", line 2, in \n ZeroDivisionError: int division or modulo by zero\n\n During handling of the above exception, another exception occurred:\n\n Traceback (most recent call last):\n File "", line 4, in \n RuntimeError: Something bad happened\n\nAdditional information on exceptions can be found in section\n*Exceptions*, and information about handling exceptions is in section\n*The try statement*.\n', + 'return': u'\nThe "return" statement\n**********************\n\n return_stmt ::= "return" [expression_list]\n\n"return" may only occur syntactically nested in a function definition,\nnot within a nested class definition.\n\nIf an expression list is present, it is evaluated, else "None" is\nsubstituted.\n\n"return" leaves the current function call with the expression list (or\n"None") as return value.\n\nWhen "return" passes control out of a "try" statement with a "finally"\nclause, that "finally" clause is executed before really leaving the\nfunction.\n\nIn a generator function, the "return" statement indicates that the\ngenerator is done and will cause "StopIteration" to be raised. The\nreturned value (if any) is used as an argument to construct\n"StopIteration" and becomes the "StopIteration.value" attribute.\n', + 'sequence-types': u'\nEmulating container types\n*************************\n\nThe following methods can be defined to implement container objects.\nContainers usually are sequences (such as lists or tuples) or mappings\n(like dictionaries), but can represent other containers as well. The\nfirst set of methods is used either to emulate a sequence or to\nemulate a mapping; the difference is that for a sequence, the\nallowable keys should be the integers *k* for which "0 <= k < N" where\n*N* is the length of the sequence, or slice objects, which define a\nrange of items. It is also recommended that mappings provide the\nmethods "keys()", "values()", "items()", "get()", "clear()",\n"setdefault()", "pop()", "popitem()", "copy()", and "update()"\nbehaving similar to those for Python\'s standard dictionary objects.\nThe "collections" module provides a "MutableMapping" abstract base\nclass to help create those methods from a base set of "__getitem__()",\n"__setitem__()", "__delitem__()", and "keys()". Mutable sequences\nshould provide methods "append()", "count()", "index()", "extend()",\n"insert()", "pop()", "remove()", "reverse()" and "sort()", like Python\nstandard list objects. Finally, sequence types should implement\naddition (meaning concatenation) and multiplication (meaning\nrepetition) by defining the methods "__add__()", "__radd__()",\n"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" described\nbelow; they should not define other numerical operators. It is\nrecommended that both mappings and sequences implement the\n"__contains__()" method to allow efficient use of the "in" operator;\nfor mappings, "in" should search the mapping\'s keys; for sequences, it\nshould search through the values. It is further recommended that both\nmappings and sequences implement the "__iter__()" method to allow\nefficient iteration through the container; for mappings, "__iter__()"\nshould be the same as "keys()"; for sequences, it should iterate\nthrough the values.\n\nobject.__len__(self)\n\n Called to implement the built-in function "len()". Should return\n the length of the object, an integer ">=" 0. Also, an object that\n doesn\'t define a "__bool__()" method and whose "__len__()" method\n returns zero is considered to be false in a Boolean context.\n\nobject.__length_hint__(self)\n\n Called to implement "operator.length_hint()". Should return an\n estimated length for the object (which may be greater or less than\n the actual length). The length must be an integer ">=" 0. This\n method is purely an optimization and is never required for\n correctness.\n\n New in version 3.4.\n\nNote: Slicing is done exclusively with the following three methods.\n A call like\n\n a[1:2] = b\n\n is translated to\n\n a[slice(1, 2, None)] = b\n\n and so forth. Missing slice items are always filled in with "None".\n\nobject.__getitem__(self, key)\n\n Called to implement evaluation of "self[key]". For sequence types,\n the accepted keys should be integers and slice objects. Note that\n the special interpretation of negative indexes (if the class wishes\n to emulate a sequence type) is up to the "__getitem__()" method. If\n *key* is of an inappropriate type, "TypeError" may be raised; if of\n a value outside the set of indexes for the sequence (after any\n special interpretation of negative values), "IndexError" should be\n raised. For mapping types, if *key* is missing (not in the\n container), "KeyError" should be raised.\n\n Note: "for" loops expect that an "IndexError" will be raised for\n illegal indexes to allow proper detection of the end of the\n sequence.\n\nobject.__missing__(self, key)\n\n Called by "dict"."__getitem__()" to implement "self[key]" for dict\n subclasses when key is not in the dictionary.\n\nobject.__setitem__(self, key, value)\n\n Called to implement assignment to "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support changes to the values for keys, or if new keys\n can be added, or for sequences if elements can be replaced. The\n same exceptions should be raised for improper *key* values as for\n the "__getitem__()" method.\n\nobject.__delitem__(self, key)\n\n Called to implement deletion of "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support removal of keys, or for sequences if elements\n can be removed from the sequence. The same exceptions should be\n raised for improper *key* values as for the "__getitem__()" method.\n\nobject.__iter__(self)\n\n This method is called when an iterator is required for a container.\n This method should return a new iterator object that can iterate\n over all the objects in the container. For mappings, it should\n iterate over the keys of the container.\n\n Iterator objects also need to implement this method; they are\n required to return themselves. For more information on iterator\n objects, see *Iterator Types*.\n\nobject.__reversed__(self)\n\n Called (if present) by the "reversed()" built-in to implement\n reverse iteration. It should return a new iterator object that\n iterates over all the objects in the container in reverse order.\n\n If the "__reversed__()" method is not provided, the "reversed()"\n built-in will fall back to using the sequence protocol ("__len__()"\n and "__getitem__()"). Objects that support the sequence protocol\n should only provide "__reversed__()" if they can provide an\n implementation that is more efficient than the one provided by\n "reversed()".\n\nThe membership test operators ("in" and "not in") are normally\nimplemented as an iteration through a sequence. However, container\nobjects can supply the following special method with a more efficient\nimplementation, which also does not require the object be a sequence.\n\nobject.__contains__(self, item)\n\n Called to implement membership test operators. Should return true\n if *item* is in *self*, false otherwise. For mapping objects, this\n should consider the keys of the mapping rather than the values or\n the key-item pairs.\n\n For objects that don\'t define "__contains__()", the membership test\n first tries iteration via "__iter__()", then the old sequence\n iteration protocol via "__getitem__()", see *this section in the\n language reference*.\n', + 'shifting': u'\nShifting operations\n*******************\n\nThe shifting operations have lower priority than the arithmetic\noperations:\n\n shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n\nThese operators accept integers as arguments. They shift the first\nargument to the left or right by the number of bits given by the\nsecond argument.\n\nA right shift by *n* bits is defined as floor division by "pow(2,n)".\nA left shift by *n* bits is defined as multiplication with "pow(2,n)".\n\nNote: In the current implementation, the right-hand operand is\n required to be at most "sys.maxsize". If the right-hand operand is\n larger than "sys.maxsize" an "OverflowError" exception is raised.\n', + 'slicings': u'\nSlicings\n********\n\nA slicing selects a range of items in a sequence object (e.g., a\nstring, tuple or list). Slicings may be used as expressions or as\ntargets in assignment or "del" statements. The syntax for a slicing:\n\n slicing ::= primary "[" slice_list "]"\n slice_list ::= slice_item ("," slice_item)* [","]\n slice_item ::= expression | proper_slice\n proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" [stride] ]\n lower_bound ::= expression\n upper_bound ::= expression\n stride ::= expression\n\nThere is ambiguity in the formal syntax here: anything that looks like\nan expression list also looks like a slice list, so any subscription\ncan be interpreted as a slicing. Rather than further complicating the\nsyntax, this is disambiguated by defining that in this case the\ninterpretation as a subscription takes priority over the\ninterpretation as a slicing (this is the case if the slice list\ncontains no proper slice).\n\nThe semantics for a slicing are as follows. The primary is indexed\n(using the same "__getitem__()" method as normal subscription) with a\nkey that is constructed from the slice list, as follows. If the slice\nlist contains at least one comma, the key is a tuple containing the\nconversion of the slice items; otherwise, the conversion of the lone\nslice item is the key. The conversion of a slice item that is an\nexpression is that expression. The conversion of a proper slice is a\nslice object (see section *The standard type hierarchy*) whose\n"start", "stop" and "step" attributes are the values of the\nexpressions given as lower bound, upper bound and stride,\nrespectively, substituting "None" for missing expressions.\n', + 'specialattrs': u'\nSpecial Attributes\n******************\n\nThe implementation adds a few special read-only attributes to several\nobject types, where they are relevant. Some of these are not reported\nby the "dir()" built-in function.\n\nobject.__dict__\n\n A dictionary or other mapping object used to store an object\'s\n (writable) attributes.\n\ninstance.__class__\n\n The class to which a class instance belongs.\n\nclass.__bases__\n\n The tuple of base classes of a class object.\n\nclass.__name__\n\n The name of the class or type.\n\nclass.__qualname__\n\n The *qualified name* of the class or type.\n\n New in version 3.3.\n\nclass.__mro__\n\n This attribute is a tuple of classes that are considered when\n looking for base classes during method resolution.\n\nclass.mro()\n\n This method can be overridden by a metaclass to customize the\n method resolution order for its instances. It is called at class\n instantiation, and its result is stored in "__mro__".\n\nclass.__subclasses__()\n\n Each class keeps a list of weak references to its immediate\n subclasses. This method returns a list of all those references\n still alive. Example:\n\n >>> int.__subclasses__()\n []\n\n-[ Footnotes ]-\n\n[1] Additional information on these special methods may be found\n in the Python Reference Manual (*Basic customization*).\n\n[2] As a consequence, the list "[1, 2]" is considered equal to\n "[1.0, 2.0]", and similarly for tuples.\n\n[3] They must have since the parser can\'t tell the type of the\n operands.\n\n[4] Cased characters are those with general category property\n being one of "Lu" (Letter, uppercase), "Ll" (Letter, lowercase),\n or "Lt" (Letter, titlecase).\n\n[5] To format only a tuple you should therefore provide a\n singleton tuple whose only element is the tuple to be formatted.\n', + 'specialnames': u'\nSpecial method names\n********************\n\nA class can implement certain operations that are invoked by special\nsyntax (such as arithmetic operations or subscripting and slicing) by\ndefining methods with special names. This is Python\'s approach to\n*operator overloading*, allowing classes to define their own behavior\nwith respect to language operators. For instance, if a class defines\na method named "__getitem__()", and "x" is an instance of this class,\nthen "x[i]" is roughly equivalent to "type(x).__getitem__(x, i)".\nExcept where mentioned, attempts to execute an operation raise an\nexception when no appropriate method is defined (typically\n"AttributeError" or "TypeError").\n\nWhen implementing a class that emulates any built-in type, it is\nimportant that the emulation only be implemented to the degree that it\nmakes sense for the object being modelled. For example, some\nsequences may work well with retrieval of individual elements, but\nextracting a slice may not make sense. (One example of this is the\n"NodeList" interface in the W3C\'s Document Object Model.)\n\n\nBasic customization\n===================\n\nobject.__new__(cls[, ...])\n\n Called to create a new instance of class *cls*. "__new__()" is a\n static method (special-cased so you need not declare it as such)\n that takes the class of which an instance was requested as its\n first argument. The remaining arguments are those passed to the\n object constructor expression (the call to the class). The return\n value of "__new__()" should be the new object instance (usually an\n instance of *cls*).\n\n Typical implementations create a new instance of the class by\n invoking the superclass\'s "__new__()" method using\n "super(currentclass, cls).__new__(cls[, ...])" with appropriate\n arguments and then modifying the newly-created instance as\n necessary before returning it.\n\n If "__new__()" returns an instance of *cls*, then the new\n instance\'s "__init__()" method will be invoked like\n "__init__(self[, ...])", where *self* is the new instance and the\n remaining arguments are the same as were passed to "__new__()".\n\n If "__new__()" does not return an instance of *cls*, then the new\n instance\'s "__init__()" method will not be invoked.\n\n "__new__()" is intended mainly to allow subclasses of immutable\n types (like int, str, or tuple) to customize instance creation. It\n is also commonly overridden in custom metaclasses in order to\n customize class creation.\n\nobject.__init__(self[, ...])\n\n Called after the instance has been created (by "__new__()"), but\n before it is returned to the caller. The arguments are those\n passed to the class constructor expression. If a base class has an\n "__init__()" method, the derived class\'s "__init__()" method, if\n any, must explicitly call it to ensure proper initialization of the\n base class part of the instance; for example:\n "BaseClass.__init__(self, [args...])".\n\n Because "__new__()" and "__init__()" work together in constructing\n objects ("__new__()" to create it, and "__init__()" to customise\n it), no non-"None" value may be returned by "__init__()"; doing so\n will cause a "TypeError" to be raised at runtime.\n\nobject.__del__(self)\n\n Called when the instance is about to be destroyed. This is also\n called a destructor. If a base class has a "__del__()" method, the\n derived class\'s "__del__()" method, if any, must explicitly call it\n to ensure proper deletion of the base class part of the instance.\n Note that it is possible (though not recommended!) for the\n "__del__()" method to postpone destruction of the instance by\n creating a new reference to it. It may then be called at a later\n time when this new reference is deleted. It is not guaranteed that\n "__del__()" methods are called for objects that still exist when\n the interpreter exits.\n\n Note: "del x" doesn\'t directly call "x.__del__()" --- the former\n decrements the reference count for "x" by one, and the latter is\n only called when "x"\'s reference count reaches zero. Some common\n situations that may prevent the reference count of an object from\n going to zero include: circular references between objects (e.g.,\n a doubly-linked list or a tree data structure with parent and\n child pointers); a reference to the object on the stack frame of\n a function that caught an exception (the traceback stored in\n "sys.exc_info()[2]" keeps the stack frame alive); or a reference\n to the object on the stack frame that raised an unhandled\n exception in interactive mode (the traceback stored in\n "sys.last_traceback" keeps the stack frame alive). The first\n situation can only be remedied by explicitly breaking the cycles;\n the second can be resolved by freeing the reference to the\n traceback object when it is no longer useful, and the third can\n be resolved by storing "None" in "sys.last_traceback". Circular\n references which are garbage are detected and cleaned up when the\n cyclic garbage collector is enabled (it\'s on by default). Refer\n to the documentation for the "gc" module for more information\n about this topic.\n\n Warning: Due to the precarious circumstances under which\n "__del__()" methods are invoked, exceptions that occur during\n their execution are ignored, and a warning is printed to\n "sys.stderr" instead. Also, when "__del__()" is invoked in\n response to a module being deleted (e.g., when execution of the\n program is done), other globals referenced by the "__del__()"\n method may already have been deleted or in the process of being\n torn down (e.g. the import machinery shutting down). For this\n reason, "__del__()" methods should do the absolute minimum needed\n to maintain external invariants. Starting with version 1.5,\n Python guarantees that globals whose name begins with a single\n underscore are deleted from their module before other globals are\n deleted; if no other references to such globals exist, this may\n help in assuring that imported modules are still available at the\n time when the "__del__()" method is called.\n\nobject.__repr__(self)\n\n Called by the "repr()" built-in function to compute the "official"\n string representation of an object. If at all possible, this\n should look like a valid Python expression that could be used to\n recreate an object with the same value (given an appropriate\n environment). If this is not possible, a string of the form\n "<...some useful description...>" should be returned. The return\n value must be a string object. If a class defines "__repr__()" but\n not "__str__()", then "__repr__()" is also used when an "informal"\n string representation of instances of that class is required.\n\n This is typically used for debugging, so it is important that the\n representation is information-rich and unambiguous.\n\nobject.__str__(self)\n\n Called by "str(object)" and the built-in functions "format()" and\n "print()" to compute the "informal" or nicely printable string\n representation of an object. The return value must be a *string*\n object.\n\n This method differs from "object.__repr__()" in that there is no\n expectation that "__str__()" return a valid Python expression: a\n more convenient or concise representation can be used.\n\n The default implementation defined by the built-in type "object"\n calls "object.__repr__()".\n\nobject.__bytes__(self)\n\n Called by "bytes()" to compute a byte-string representation of an\n object. This should return a "bytes" object.\n\nobject.__format__(self, format_spec)\n\n Called by the "format()" built-in function (and by extension, the\n "str.format()" method of class "str") to produce a "formatted"\n string representation of an object. The "format_spec" argument is a\n string that contains a description of the formatting options\n desired. The interpretation of the "format_spec" argument is up to\n the type implementing "__format__()", however most classes will\n either delegate formatting to one of the built-in types, or use a\n similar formatting option syntax.\n\n See *Format Specification Mini-Language* for a description of the\n standard formatting syntax.\n\n The return value must be a string object.\n\n Changed in version 3.4: The __format__ method of "object" itself\n raises a "TypeError" if passed any non-empty string.\n\nobject.__lt__(self, other)\nobject.__le__(self, other)\nobject.__eq__(self, other)\nobject.__ne__(self, other)\nobject.__gt__(self, other)\nobject.__ge__(self, other)\n\n These are the so-called "rich comparison" methods. The\n correspondence between operator symbols and method names is as\n follows: "xy" calls\n "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n\n A rich comparison method may return the singleton "NotImplemented"\n if it does not implement the operation for a given pair of\n arguments. By convention, "False" and "True" are returned for a\n successful comparison. However, these methods can return any value,\n so if the comparison operator is used in a Boolean context (e.g.,\n in the condition of an "if" statement), Python will call "bool()"\n on the value to determine if the result is true or false.\n\n By default, "__ne__()" delegates to "__eq__()" and inverts the\n result unless it is "NotImplemented". There are no other implied\n relationships among the comparison operators, for example, the\n truth of "(x.__hash__".\n\n If a class that does not override "__eq__()" wishes to suppress\n hash support, it should include "__hash__ = None" in the class\n definition. A class which defines its own "__hash__()" that\n explicitly raises a "TypeError" would be incorrectly identified as\n hashable by an "isinstance(obj, collections.Hashable)" call.\n\n Note: By default, the "__hash__()" values of str, bytes and\n datetime objects are "salted" with an unpredictable random value.\n Although they remain constant within an individual Python\n process, they are not predictable between repeated invocations of\n Python.This is intended to provide protection against a denial-\n of-service caused by carefully-chosen inputs that exploit the\n worst case performance of a dict insertion, O(n^2) complexity.\n See http://www.ocert.org/advisories/ocert-2011-003.html for\n details.Changing hash values affects the iteration order of\n dicts, sets and other mappings. Python has never made guarantees\n about this ordering (and it typically varies between 32-bit and\n 64-bit builds).See also "PYTHONHASHSEED".\n\n Changed in version 3.3: Hash randomization is enabled by default.\n\nobject.__bool__(self)\n\n Called to implement truth value testing and the built-in operation\n "bool()"; should return "False" or "True". When this method is not\n defined, "__len__()" is called, if it is defined, and the object is\n considered true if its result is nonzero. If a class defines\n neither "__len__()" nor "__bool__()", all its instances are\n considered true.\n\n\nCustomizing attribute access\n============================\n\nThe following methods can be defined to customize the meaning of\nattribute access (use of, assignment to, or deletion of "x.name") for\nclass instances.\n\nobject.__getattr__(self, name)\n\n Called when an attribute lookup has not found the attribute in the\n usual places (i.e. it is not an instance attribute nor is it found\n in the class tree for "self"). "name" is the attribute name. This\n method should return the (computed) attribute value or raise an\n "AttributeError" exception.\n\n Note that if the attribute is found through the normal mechanism,\n "__getattr__()" is not called. (This is an intentional asymmetry\n between "__getattr__()" and "__setattr__()".) This is done both for\n efficiency reasons and because otherwise "__getattr__()" would have\n no way to access other attributes of the instance. Note that at\n least for instance variables, you can fake total control by not\n inserting any values in the instance attribute dictionary (but\n instead inserting them in another object). See the\n "__getattribute__()" method below for a way to actually get total\n control over attribute access.\n\nobject.__getattribute__(self, name)\n\n Called unconditionally to implement attribute accesses for\n instances of the class. If the class also defines "__getattr__()",\n the latter will not be called unless "__getattribute__()" either\n calls it explicitly or raises an "AttributeError". This method\n should return the (computed) attribute value or raise an\n "AttributeError" exception. In order to avoid infinite recursion in\n this method, its implementation should always call the base class\n method with the same name to access any attributes it needs, for\n example, "object.__getattribute__(self, name)".\n\n Note: This method may still be bypassed when looking up special\n methods as the result of implicit invocation via language syntax\n or built-in functions. See *Special method lookup*.\n\nobject.__setattr__(self, name, value)\n\n Called when an attribute assignment is attempted. This is called\n instead of the normal mechanism (i.e. store the value in the\n instance dictionary). *name* is the attribute name, *value* is the\n value to be assigned to it.\n\n If "__setattr__()" wants to assign to an instance attribute, it\n should call the base class method with the same name, for example,\n "object.__setattr__(self, name, value)".\n\nobject.__delattr__(self, name)\n\n Like "__setattr__()" but for attribute deletion instead of\n assignment. This should only be implemented if "del obj.name" is\n meaningful for the object.\n\nobject.__dir__(self)\n\n Called when "dir()" is called on the object. A sequence must be\n returned. "dir()" converts the returned sequence to a list and\n sorts it.\n\n\nImplementing Descriptors\n------------------------\n\nThe following methods only apply when an instance of the class\ncontaining the method (a so-called *descriptor* class) appears in an\n*owner* class (the descriptor must be in either the owner\'s class\ndictionary or in the class dictionary for one of its parents). In the\nexamples below, "the attribute" refers to the attribute whose name is\nthe key of the property in the owner class\' "__dict__".\n\nobject.__get__(self, instance, owner)\n\n Called to get the attribute of the owner class (class attribute\n access) or of an instance of that class (instance attribute\n access). *owner* is always the owner class, while *instance* is the\n instance that the attribute was accessed through, or "None" when\n the attribute is accessed through the *owner*. This method should\n return the (computed) attribute value or raise an "AttributeError"\n exception.\n\nobject.__set__(self, instance, value)\n\n Called to set the attribute on an instance *instance* of the owner\n class to a new value, *value*.\n\nobject.__delete__(self, instance)\n\n Called to delete the attribute on an instance *instance* of the\n owner class.\n\nThe attribute "__objclass__" is interpreted by the "inspect" module as\nspecifying the class where this object was defined (setting this\nappropriately can assist in runtime introspection of dynamic class\nattributes). For callables, it may indicate that an instance of the\ngiven type (or a subclass) is expected or required as the first\npositional argument (for example, CPython sets this attribute for\nunbound methods that are implemented in C).\n\n\nInvoking Descriptors\n--------------------\n\nIn general, a descriptor is an object attribute with "binding\nbehavior", one whose attribute access has been overridden by methods\nin the descriptor protocol: "__get__()", "__set__()", and\n"__delete__()". If any of those methods are defined for an object, it\nis said to be a descriptor.\n\nThe default behavior for attribute access is to get, set, or delete\nthe attribute from an object\'s dictionary. For instance, "a.x" has a\nlookup chain starting with "a.__dict__[\'x\']", then\n"type(a).__dict__[\'x\']", and continuing through the base classes of\n"type(a)" excluding metaclasses.\n\nHowever, if the looked-up value is an object defining one of the\ndescriptor methods, then Python may override the default behavior and\ninvoke the descriptor method instead. Where this occurs in the\nprecedence chain depends on which descriptor methods were defined and\nhow they were called.\n\nThe starting point for descriptor invocation is a binding, "a.x". How\nthe arguments are assembled depends on "a":\n\nDirect Call\n The simplest and least common call is when user code directly\n invokes a descriptor method: "x.__get__(a)".\n\nInstance Binding\n If binding to an object instance, "a.x" is transformed into the\n call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n\nClass Binding\n If binding to a class, "A.x" is transformed into the call:\n "A.__dict__[\'x\'].__get__(None, A)".\n\nSuper Binding\n If "a" is an instance of "super", then the binding "super(B,\n obj).m()" searches "obj.__class__.__mro__" for the base class "A"\n immediately preceding "B" and then invokes the descriptor with the\n call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n\nFor instance bindings, the precedence of descriptor invocation depends\non the which descriptor methods are defined. A descriptor can define\nany combination of "__get__()", "__set__()" and "__delete__()". If it\ndoes not define "__get__()", then accessing the attribute will return\nthe descriptor object itself unless there is a value in the object\'s\ninstance dictionary. If the descriptor defines "__set__()" and/or\n"__delete__()", it is a data descriptor; if it defines neither, it is\na non-data descriptor. Normally, data descriptors define both\n"__get__()" and "__set__()", while non-data descriptors have just the\n"__get__()" method. Data descriptors with "__set__()" and "__get__()"\ndefined always override a redefinition in an instance dictionary. In\ncontrast, non-data descriptors can be overridden by instances.\n\nPython methods (including "staticmethod()" and "classmethod()") are\nimplemented as non-data descriptors. Accordingly, instances can\nredefine and override methods. This allows individual instances to\nacquire behaviors that differ from other instances of the same class.\n\nThe "property()" function is implemented as a data descriptor.\nAccordingly, instances cannot override the behavior of a property.\n\n\n__slots__\n---------\n\nBy default, instances of classes have a dictionary for attribute\nstorage. This wastes space for objects having very few instance\nvariables. The space consumption can become acute when creating large\nnumbers of instances.\n\nThe default can be overridden by defining *__slots__* in a class\ndefinition. The *__slots__* declaration takes a sequence of instance\nvariables and reserves just enough space in each instance to hold a\nvalue for each variable. Space is saved because *__dict__* is not\ncreated for each instance.\n\nobject.__slots__\n\n This class variable can be assigned a string, iterable, or sequence\n of strings with variable names used by instances. *__slots__*\n reserves space for the declared variables and prevents the\n automatic creation of *__dict__* and *__weakref__* for each\n instance.\n\n\nNotes on using *__slots__*\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* When inheriting from a class without *__slots__*, the *__dict__*\n attribute of that class will always be accessible, so a *__slots__*\n definition in the subclass is meaningless.\n\n* Without a *__dict__* variable, instances cannot be assigned new\n variables not listed in the *__slots__* definition. Attempts to\n assign to an unlisted variable name raises "AttributeError". If\n dynamic assignment of new variables is desired, then add\n "\'__dict__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* Without a *__weakref__* variable for each instance, classes\n defining *__slots__* do not support weak references to its\n instances. If weak reference support is needed, then add\n "\'__weakref__\'" to the sequence of strings in the *__slots__*\n declaration.\n\n* *__slots__* are implemented at the class level by creating\n descriptors (*Implementing Descriptors*) for each variable name. As\n a result, class attributes cannot be used to set default values for\n instance variables defined by *__slots__*; otherwise, the class\n attribute would overwrite the descriptor assignment.\n\n* The action of a *__slots__* declaration is limited to the class\n where it is defined. As a result, subclasses will have a *__dict__*\n unless they also define *__slots__* (which must only contain names\n of any *additional* slots).\n\n* If a class defines a slot also defined in a base class, the\n instance variable defined by the base class slot is inaccessible\n (except by retrieving its descriptor directly from the base class).\n This renders the meaning of the program undefined. In the future, a\n check may be added to prevent this.\n\n* Nonempty *__slots__* does not work for classes derived from\n "variable-length" built-in types such as "int", "bytes" and "tuple".\n\n* Any non-string iterable may be assigned to *__slots__*. Mappings\n may also be used; however, in the future, special meaning may be\n assigned to the values corresponding to each key.\n\n* *__class__* assignment works only if both classes have the same\n *__slots__*.\n\n\nCustomizing class creation\n==========================\n\nBy default, classes are constructed using "type()". The class body is\nexecuted in a new namespace and the class name is bound locally to the\nresult of "type(name, bases, namespace)".\n\nThe class creation process can be customised by passing the\n"metaclass" keyword argument in the class definition line, or by\ninheriting from an existing class that included such an argument. In\nthe following example, both "MyClass" and "MySubclass" are instances\nof "Meta":\n\n class Meta(type):\n pass\n\n class MyClass(metaclass=Meta):\n pass\n\n class MySubclass(MyClass):\n pass\n\nAny other keyword arguments that are specified in the class definition\nare passed through to all metaclass operations described below.\n\nWhen a class definition is executed, the following steps occur:\n\n* the appropriate metaclass is determined\n\n* the class namespace is prepared\n\n* the class body is executed\n\n* the class object is created\n\n\nDetermining the appropriate metaclass\n-------------------------------------\n\nThe appropriate metaclass for a class definition is determined as\nfollows:\n\n* if no bases and no explicit metaclass are given, then "type()" is\n used\n\n* if an explicit metaclass is given and it is *not* an instance of\n "type()", then it is used directly as the metaclass\n\n* if an instance of "type()" is given as the explicit metaclass, or\n bases are defined, then the most derived metaclass is used\n\nThe most derived metaclass is selected from the explicitly specified\nmetaclass (if any) and the metaclasses (i.e. "type(cls)") of all\nspecified base classes. The most derived metaclass is one which is a\nsubtype of *all* of these candidate metaclasses. If none of the\ncandidate metaclasses meets that criterion, then the class definition\nwill fail with "TypeError".\n\n\nPreparing the class namespace\n-----------------------------\n\nOnce the appropriate metaclass has been identified, then the class\nnamespace is prepared. If the metaclass has a "__prepare__" attribute,\nit is called as "namespace = metaclass.__prepare__(name, bases,\n**kwds)" (where the additional keyword arguments, if any, come from\nthe class definition).\n\nIf the metaclass has no "__prepare__" attribute, then the class\nnamespace is initialised as an empty "dict()" instance.\n\nSee also: **PEP 3115** - Metaclasses in Python 3000\n\n Introduced the "__prepare__" namespace hook\n\n\nExecuting the class body\n------------------------\n\nThe class body is executed (approximately) as "exec(body, globals(),\nnamespace)". The key difference from a normal call to "exec()" is that\nlexical scoping allows the class body (including any methods) to\nreference names from the current and outer scopes when the class\ndefinition occurs inside a function.\n\nHowever, even when the class definition occurs inside the function,\nmethods defined inside the class still cannot see names defined at the\nclass scope. Class variables must be accessed through the first\nparameter of instance or class methods, and cannot be accessed at all\nfrom static methods.\n\n\nCreating the class object\n-------------------------\n\nOnce the class namespace has been populated by executing the class\nbody, the class object is created by calling "metaclass(name, bases,\nnamespace, **kwds)" (the additional keywords passed here are the same\nas those passed to "__prepare__").\n\nThis class object is the one that will be referenced by the zero-\nargument form of "super()". "__class__" is an implicit closure\nreference created by the compiler if any methods in a class body refer\nto either "__class__" or "super". This allows the zero argument form\nof "super()" to correctly identify the class being defined based on\nlexical scoping, while the class or instance that was used to make the\ncurrent call is identified based on the first argument passed to the\nmethod.\n\nAfter the class object is created, it is passed to the class\ndecorators included in the class definition (if any) and the resulting\nobject is bound in the local namespace as the defined class.\n\nSee also: **PEP 3135** - New super\n\n Describes the implicit "__class__" closure reference\n\n\nMetaclass example\n-----------------\n\nThe potential uses for metaclasses are boundless. Some ideas that have\nbeen explored include logging, interface checking, automatic\ndelegation, automatic property creation, proxies, frameworks, and\nautomatic resource locking/synchronization.\n\nHere is an example of a metaclass that uses an\n"collections.OrderedDict" to remember the order that class variables\nare defined:\n\n class OrderedClass(type):\n\n @classmethod\n def __prepare__(metacls, name, bases, **kwds):\n return collections.OrderedDict()\n\n def __new__(cls, name, bases, namespace, **kwds):\n result = type.__new__(cls, name, bases, dict(namespace))\n result.members = tuple(namespace)\n return result\n\n class A(metaclass=OrderedClass):\n def one(self): pass\n def two(self): pass\n def three(self): pass\n def four(self): pass\n\n >>> A.members\n (\'__module__\', \'one\', \'two\', \'three\', \'four\')\n\nWhen the class definition for *A* gets executed, the process begins\nwith calling the metaclass\'s "__prepare__()" method which returns an\nempty "collections.OrderedDict". That mapping records the methods and\nattributes of *A* as they are defined within the body of the class\nstatement. Once those definitions are executed, the ordered dictionary\nis fully populated and the metaclass\'s "__new__()" method gets\ninvoked. That method builds the new type and it saves the ordered\ndictionary keys in an attribute called "members".\n\n\nCustomizing instance and subclass checks\n========================================\n\nThe following methods are used to override the default behavior of the\n"isinstance()" and "issubclass()" built-in functions.\n\nIn particular, the metaclass "abc.ABCMeta" implements these methods in\norder to allow the addition of Abstract Base Classes (ABCs) as\n"virtual base classes" to any class or type (including built-in\ntypes), including other ABCs.\n\nclass.__instancecheck__(self, instance)\n\n Return true if *instance* should be considered a (direct or\n indirect) instance of *class*. If defined, called to implement\n "isinstance(instance, class)".\n\nclass.__subclasscheck__(self, subclass)\n\n Return true if *subclass* should be considered a (direct or\n indirect) subclass of *class*. If defined, called to implement\n "issubclass(subclass, class)".\n\nNote that these methods are looked up on the type (metaclass) of a\nclass. They cannot be defined as class methods in the actual class.\nThis is consistent with the lookup of special methods that are called\non instances, only in this case the instance is itself a class.\n\nSee also: **PEP 3119** - Introducing Abstract Base Classes\n\n Includes the specification for customizing "isinstance()" and\n "issubclass()" behavior through "__instancecheck__()" and\n "__subclasscheck__()", with motivation for this functionality in\n the context of adding Abstract Base Classes (see the "abc"\n module) to the language.\n\n\nEmulating callable objects\n==========================\n\nobject.__call__(self[, args...])\n\n Called when the instance is "called" as a function; if this method\n is defined, "x(arg1, arg2, ...)" is a shorthand for\n "x.__call__(arg1, arg2, ...)".\n\n\nEmulating container types\n=========================\n\nThe following methods can be defined to implement container objects.\nContainers usually are sequences (such as lists or tuples) or mappings\n(like dictionaries), but can represent other containers as well. The\nfirst set of methods is used either to emulate a sequence or to\nemulate a mapping; the difference is that for a sequence, the\nallowable keys should be the integers *k* for which "0 <= k < N" where\n*N* is the length of the sequence, or slice objects, which define a\nrange of items. It is also recommended that mappings provide the\nmethods "keys()", "values()", "items()", "get()", "clear()",\n"setdefault()", "pop()", "popitem()", "copy()", and "update()"\nbehaving similar to those for Python\'s standard dictionary objects.\nThe "collections" module provides a "MutableMapping" abstract base\nclass to help create those methods from a base set of "__getitem__()",\n"__setitem__()", "__delitem__()", and "keys()". Mutable sequences\nshould provide methods "append()", "count()", "index()", "extend()",\n"insert()", "pop()", "remove()", "reverse()" and "sort()", like Python\nstandard list objects. Finally, sequence types should implement\naddition (meaning concatenation) and multiplication (meaning\nrepetition) by defining the methods "__add__()", "__radd__()",\n"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" described\nbelow; they should not define other numerical operators. It is\nrecommended that both mappings and sequences implement the\n"__contains__()" method to allow efficient use of the "in" operator;\nfor mappings, "in" should search the mapping\'s keys; for sequences, it\nshould search through the values. It is further recommended that both\nmappings and sequences implement the "__iter__()" method to allow\nefficient iteration through the container; for mappings, "__iter__()"\nshould be the same as "keys()"; for sequences, it should iterate\nthrough the values.\n\nobject.__len__(self)\n\n Called to implement the built-in function "len()". Should return\n the length of the object, an integer ">=" 0. Also, an object that\n doesn\'t define a "__bool__()" method and whose "__len__()" method\n returns zero is considered to be false in a Boolean context.\n\nobject.__length_hint__(self)\n\n Called to implement "operator.length_hint()". Should return an\n estimated length for the object (which may be greater or less than\n the actual length). The length must be an integer ">=" 0. This\n method is purely an optimization and is never required for\n correctness.\n\n New in version 3.4.\n\nNote: Slicing is done exclusively with the following three methods.\n A call like\n\n a[1:2] = b\n\n is translated to\n\n a[slice(1, 2, None)] = b\n\n and so forth. Missing slice items are always filled in with "None".\n\nobject.__getitem__(self, key)\n\n Called to implement evaluation of "self[key]". For sequence types,\n the accepted keys should be integers and slice objects. Note that\n the special interpretation of negative indexes (if the class wishes\n to emulate a sequence type) is up to the "__getitem__()" method. If\n *key* is of an inappropriate type, "TypeError" may be raised; if of\n a value outside the set of indexes for the sequence (after any\n special interpretation of negative values), "IndexError" should be\n raised. For mapping types, if *key* is missing (not in the\n container), "KeyError" should be raised.\n\n Note: "for" loops expect that an "IndexError" will be raised for\n illegal indexes to allow proper detection of the end of the\n sequence.\n\nobject.__missing__(self, key)\n\n Called by "dict"."__getitem__()" to implement "self[key]" for dict\n subclasses when key is not in the dictionary.\n\nobject.__setitem__(self, key, value)\n\n Called to implement assignment to "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support changes to the values for keys, or if new keys\n can be added, or for sequences if elements can be replaced. The\n same exceptions should be raised for improper *key* values as for\n the "__getitem__()" method.\n\nobject.__delitem__(self, key)\n\n Called to implement deletion of "self[key]". Same note as for\n "__getitem__()". This should only be implemented for mappings if\n the objects support removal of keys, or for sequences if elements\n can be removed from the sequence. The same exceptions should be\n raised for improper *key* values as for the "__getitem__()" method.\n\nobject.__iter__(self)\n\n This method is called when an iterator is required for a container.\n This method should return a new iterator object that can iterate\n over all the objects in the container. For mappings, it should\n iterate over the keys of the container.\n\n Iterator objects also need to implement this method; they are\n required to return themselves. For more information on iterator\n objects, see *Iterator Types*.\n\nobject.__reversed__(self)\n\n Called (if present) by the "reversed()" built-in to implement\n reverse iteration. It should return a new iterator object that\n iterates over all the objects in the container in reverse order.\n\n If the "__reversed__()" method is not provided, the "reversed()"\n built-in will fall back to using the sequence protocol ("__len__()"\n and "__getitem__()"). Objects that support the sequence protocol\n should only provide "__reversed__()" if they can provide an\n implementation that is more efficient than the one provided by\n "reversed()".\n\nThe membership test operators ("in" and "not in") are normally\nimplemented as an iteration through a sequence. However, container\nobjects can supply the following special method with a more efficient\nimplementation, which also does not require the object be a sequence.\n\nobject.__contains__(self, item)\n\n Called to implement membership test operators. Should return true\n if *item* is in *self*, false otherwise. For mapping objects, this\n should consider the keys of the mapping rather than the values or\n the key-item pairs.\n\n For objects that don\'t define "__contains__()", the membership test\n first tries iteration via "__iter__()", then the old sequence\n iteration protocol via "__getitem__()", see *this section in the\n language reference*.\n\n\nEmulating numeric types\n=======================\n\nThe following methods can be defined to emulate numeric objects.\nMethods corresponding to operations that are not supported by the\nparticular kind of number implemented (e.g., bitwise operations for\nnon-integral numbers) should be left undefined.\n\nobject.__add__(self, other)\nobject.__sub__(self, other)\nobject.__mul__(self, other)\nobject.__truediv__(self, other)\nobject.__floordiv__(self, other)\nobject.__mod__(self, other)\nobject.__divmod__(self, other)\nobject.__pow__(self, other[, modulo])\nobject.__lshift__(self, other)\nobject.__rshift__(self, other)\nobject.__and__(self, other)\nobject.__xor__(self, other)\nobject.__or__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|"). For instance, to evaluate the\n expression "x + y", where *x* is an instance of a class that has an\n "__add__()" method, "x.__add__(y)" is called. The "__divmod__()"\n method should be the equivalent to using "__floordiv__()" and\n "__mod__()"; it should not be related to "__truediv__()". Note\n that "__pow__()" should be defined to accept an optional third\n argument if the ternary version of the built-in "pow()" function is\n to be supported.\n\n If one of those methods does not support the operation with the\n supplied arguments, it should return "NotImplemented".\n\nobject.__radd__(self, other)\nobject.__rsub__(self, other)\nobject.__rmul__(self, other)\nobject.__rtruediv__(self, other)\nobject.__rfloordiv__(self, other)\nobject.__rmod__(self, other)\nobject.__rdivmod__(self, other)\nobject.__rpow__(self, other)\nobject.__rlshift__(self, other)\nobject.__rrshift__(self, other)\nobject.__rand__(self, other)\nobject.__rxor__(self, other)\nobject.__ror__(self, other)\n\n These methods are called to implement the binary arithmetic\n operations ("+", "-", "*", "/", "//", "%", "divmod()", "pow()",\n "**", "<<", ">>", "&", "^", "|") with reflected (swapped) operands.\n These functions are only called if the left operand does not\n support the corresponding operation and the operands are of\n different types. [2] For instance, to evaluate the expression "x -\n y", where *y* is an instance of a class that has an "__rsub__()"\n method, "y.__rsub__(x)" is called if "x.__sub__(y)" returns\n *NotImplemented*.\n\n Note that ternary "pow()" will not try calling "__rpow__()" (the\n coercion rules would become too complicated).\n\n Note: If the right operand\'s type is a subclass of the left\n operand\'s type and that subclass provides the reflected method\n for the operation, this method will be called before the left\n operand\'s non-reflected method. This behavior allows subclasses\n to override their ancestors\' operations.\n\nobject.__iadd__(self, other)\nobject.__isub__(self, other)\nobject.__imul__(self, other)\nobject.__itruediv__(self, other)\nobject.__ifloordiv__(self, other)\nobject.__imod__(self, other)\nobject.__ipow__(self, other[, modulo])\nobject.__ilshift__(self, other)\nobject.__irshift__(self, other)\nobject.__iand__(self, other)\nobject.__ixor__(self, other)\nobject.__ior__(self, other)\n\n These methods are called to implement the augmented arithmetic\n assignments ("+=", "-=", "*=", "/=", "//=", "%=", "**=", "<<=",\n ">>=", "&=", "^=", "|="). These methods should attempt to do the\n operation in-place (modifying *self*) and return the result (which\n could be, but does not have to be, *self*). If a specific method\n is not defined, the augmented assignment falls back to the normal\n methods. For instance, if *x* is an instance of a class with an\n "__iadd__()" method, "x += y" is equivalent to "x = x.__iadd__(y)"\n . Otherwise, "x.__add__(y)" and "y.__radd__(x)" are considered, as\n with the evaluation of "x + y". In certain situations, augmented\n assignment can result in unexpected errors (see *Why does\n a_tuple[i] += [\'item\'] raise an exception when the addition\n works?*), but this behavior is in fact part of the data model.\n\nobject.__neg__(self)\nobject.__pos__(self)\nobject.__abs__(self)\nobject.__invert__(self)\n\n Called to implement the unary arithmetic operations ("-", "+",\n "abs()" and "~").\n\nobject.__complex__(self)\nobject.__int__(self)\nobject.__float__(self)\nobject.__round__(self[, n])\n\n Called to implement the built-in functions "complex()", "int()",\n "float()" and "round()". Should return a value of the appropriate\n type.\n\nobject.__index__(self)\n\n Called to implement "operator.index()", and whenever Python needs\n to losslessly convert the numeric object to an integer object (such\n as in slicing, or in the built-in "bin()", "hex()" and "oct()"\n functions). Presence of this method indicates that the numeric\n object is an integer type. Must return an integer.\n\n Note: In order to have a coherent integer type class, when\n "__index__()" is defined "__int__()" should also be defined, and\n both should return the same value.\n\n\nWith Statement Context Managers\n===============================\n\nA *context manager* is an object that defines the runtime context to\nbe established when executing a "with" statement. The context manager\nhandles the entry into, and the exit from, the desired runtime context\nfor the execution of the block of code. Context managers are normally\ninvoked using the "with" statement (described in section *The with\nstatement*), but can also be used by directly invoking their methods.\n\nTypical uses of context managers include saving and restoring various\nkinds of global state, locking and unlocking resources, closing opened\nfiles, etc.\n\nFor more information on context managers, see *Context Manager Types*.\n\nobject.__enter__(self)\n\n Enter the runtime context related to this object. The "with"\n statement will bind this method\'s return value to the target(s)\n specified in the "as" clause of the statement, if any.\n\nobject.__exit__(self, exc_type, exc_value, traceback)\n\n Exit the runtime context related to this object. The parameters\n describe the exception that caused the context to be exited. If the\n context was exited without an exception, all three arguments will\n be "None".\n\n If an exception is supplied, and the method wishes to suppress the\n exception (i.e., prevent it from being propagated), it should\n return a true value. Otherwise, the exception will be processed\n normally upon exit from this method.\n\n Note that "__exit__()" methods should not reraise the passed-in\n exception; this is the caller\'s responsibility.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n\n\nSpecial method lookup\n=====================\n\nFor custom classes, implicit invocations of special methods are only\nguaranteed to work correctly if defined on an object\'s type, not in\nthe object\'s instance dictionary. That behaviour is the reason why\nthe following code raises an exception:\n\n >>> class C:\n ... pass\n ...\n >>> c = C()\n >>> c.__len__ = lambda: 5\n >>> len(c)\n Traceback (most recent call last):\n File "", line 1, in \n TypeError: object of type \'C\' has no len()\n\nThe rationale behind this behaviour lies with a number of special\nmethods such as "__hash__()" and "__repr__()" that are implemented by\nall objects, including type objects. If the implicit lookup of these\nmethods used the conventional lookup process, they would fail when\ninvoked on the type object itself:\n\n >>> 1 .__hash__() == hash(1)\n True\n >>> int.__hash__() == hash(int)\n Traceback (most recent call last):\n File "", line 1, in \n TypeError: descriptor \'__hash__\' of \'int\' object needs an argument\n\nIncorrectly attempting to invoke an unbound method of a class in this\nway is sometimes referred to as \'metaclass confusion\', and is avoided\nby bypassing the instance when looking up special methods:\n\n >>> type(1).__hash__(1) == hash(1)\n True\n >>> type(int).__hash__(int) == hash(int)\n True\n\nIn addition to bypassing any instance attributes in the interest of\ncorrectness, implicit special method lookup generally also bypasses\nthe "__getattribute__()" method even of the object\'s metaclass:\n\n >>> class Meta(type):\n ... def __getattribute__(*args):\n ... print("Metaclass getattribute invoked")\n ... return type.__getattribute__(*args)\n ...\n >>> class C(object, metaclass=Meta):\n ... def __len__(self):\n ... return 10\n ... def __getattribute__(*args):\n ... print("Class getattribute invoked")\n ... return object.__getattribute__(*args)\n ...\n >>> c = C()\n >>> c.__len__() # Explicit lookup via instance\n Class getattribute invoked\n 10\n >>> type(c).__len__(c) # Explicit lookup via type\n Metaclass getattribute invoked\n 10\n >>> len(c) # Implicit lookup\n 10\n\nBypassing the "__getattribute__()" machinery in this fashion provides\nsignificant scope for speed optimisations within the interpreter, at\nthe cost of some flexibility in the handling of special methods (the\nspecial method *must* be set on the class object itself in order to be\nconsistently invoked by the interpreter).\n\n-[ Footnotes ]-\n\n[1] It *is* possible in some cases to change an object\'s type,\n under certain controlled conditions. It generally isn\'t a good\n idea though, since it can lead to some very strange behaviour if\n it is handled incorrectly.\n\n[2] For operands of the same type, it is assumed that if the non-\n reflected method (such as "__add__()") fails the operation is not\n supported, which is why the reflected method is not called.\n', + 'string-methods': u'\nString Methods\n**************\n\nStrings implement all of the *common* sequence operations, along with\nthe additional methods described below.\n\nStrings also support two styles of string formatting, one providing a\nlarge degree of flexibility and customization (see "str.format()",\n*Format String Syntax* and *String Formatting*) and the other based on\nC "printf" style formatting that handles a narrower range of types and\nis slightly harder to use correctly, but is often faster for the cases\nit can handle (*printf-style String Formatting*).\n\nThe *Text Processing Services* section of the standard library covers\na number of other modules that provide various text related utilities\n(including regular expression support in the "re" module).\n\nstr.capitalize()\n\n Return a copy of the string with its first character capitalized\n and the rest lowercased.\n\nstr.casefold()\n\n Return a casefolded copy of the string. Casefolded strings may be\n used for caseless matching.\n\n Casefolding is similar to lowercasing but more aggressive because\n it is intended to remove all case distinctions in a string. For\n example, the German lowercase letter "\'\xdf\'" is equivalent to ""ss"".\n Since it is already lowercase, "lower()" would do nothing to "\'\xdf\'";\n "casefold()" converts it to ""ss"".\n\n The casefolding algorithm is described in section 3.13 of the\n Unicode Standard.\n\n New in version 3.3.\n\nstr.center(width[, fillchar])\n\n Return centered in a string of length *width*. Padding is done\n using the specified *fillchar* (default is an ASCII space). The\n original string is returned if *width* is less than or equal to\n "len(s)".\n\nstr.count(sub[, start[, end]])\n\n Return the number of non-overlapping occurrences of substring *sub*\n in the range [*start*, *end*]. Optional arguments *start* and\n *end* are interpreted as in slice notation.\n\nstr.encode(encoding="utf-8", errors="strict")\n\n Return an encoded version of the string as a bytes object. Default\n encoding is "\'utf-8\'". *errors* may be given to set a different\n error handling scheme. The default for *errors* is "\'strict\'",\n meaning that encoding errors raise a "UnicodeError". Other possible\n values are "\'ignore\'", "\'replace\'", "\'xmlcharrefreplace\'",\n "\'backslashreplace\'" and any other name registered via\n "codecs.register_error()", see section *Error Handlers*. For a list\n of possible encodings, see section *Standard Encodings*.\n\n Changed in version 3.1: Support for keyword arguments added.\n\nstr.endswith(suffix[, start[, end]])\n\n Return "True" if the string ends with the specified *suffix*,\n otherwise return "False". *suffix* can also be a tuple of suffixes\n to look for. With optional *start*, test beginning at that\n position. With optional *end*, stop comparing at that position.\n\nstr.expandtabs(tabsize=8)\n\n Return a copy of the string where all tab characters are replaced\n by one or more spaces, depending on the current column and the\n given tab size. Tab positions occur every *tabsize* characters\n (default is 8, giving tab positions at columns 0, 8, 16 and so on).\n To expand the string, the current column is set to zero and the\n string is examined character by character. If the character is a\n tab ("\\t"), one or more space characters are inserted in the result\n until the current column is equal to the next tab position. (The\n tab character itself is not copied.) If the character is a newline\n ("\\n") or return ("\\r"), it is copied and the current column is\n reset to zero. Any other character is copied unchanged and the\n current column is incremented by one regardless of how the\n character is represented when printed.\n\n >>> \'01\\t012\\t0123\\t01234\'.expandtabs()\n \'01 012 0123 01234\'\n >>> \'01\\t012\\t0123\\t01234\'.expandtabs(4)\n \'01 012 0123 01234\'\n\nstr.find(sub[, start[, end]])\n\n Return the lowest index in the string where substring *sub* is\n found within the slice "s[start:end]". Optional arguments *start*\n and *end* are interpreted as in slice notation. Return "-1" if\n *sub* is not found.\n\n Note: The "find()" method should be used only if you need to know\n the position of *sub*. To check if *sub* is a substring or not,\n use the "in" operator:\n\n >>> \'Py\' in \'Python\'\n True\n\nstr.format(*args, **kwargs)\n\n Perform a string formatting operation. The string on which this\n method is called can contain literal text or replacement fields\n delimited by braces "{}". Each replacement field contains either\n the numeric index of a positional argument, or the name of a\n keyword argument. Returns a copy of the string where each\n replacement field is replaced with the string value of the\n corresponding argument.\n\n >>> "The sum of 1 + 2 is {0}".format(1+2)\n \'The sum of 1 + 2 is 3\'\n\n See *Format String Syntax* for a description of the various\n formatting options that can be specified in format strings.\n\nstr.format_map(mapping)\n\n Similar to "str.format(**mapping)", except that "mapping" is used\n directly and not copied to a "dict". This is useful if for example\n "mapping" is a dict subclass:\n\n >>> class Default(dict):\n ... def __missing__(self, key):\n ... return key\n ...\n >>> \'{name} was born in {country}\'.format_map(Default(name=\'Guido\'))\n \'Guido was born in country\'\n\n New in version 3.2.\n\nstr.index(sub[, start[, end]])\n\n Like "find()", but raise "ValueError" when the substring is not\n found.\n\nstr.isalnum()\n\n Return true if all characters in the string are alphanumeric and\n there is at least one character, false otherwise. A character "c"\n is alphanumeric if one of the following returns "True":\n "c.isalpha()", "c.isdecimal()", "c.isdigit()", or "c.isnumeric()".\n\nstr.isalpha()\n\n Return true if all characters in the string are alphabetic and\n there is at least one character, false otherwise. Alphabetic\n characters are those characters defined in the Unicode character\n database as "Letter", i.e., those with general category property\n being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is\n different from the "Alphabetic" property defined in the Unicode\n Standard.\n\nstr.isdecimal()\n\n Return true if all characters in the string are decimal characters\n and there is at least one character, false otherwise. Decimal\n characters are those from general category "Nd". This category\n includes digit characters, and all characters that can be used to\n form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC DIGIT ZERO.\n\nstr.isdigit()\n\n Return true if all characters in the string are digits and there is\n at least one character, false otherwise. Digits include decimal\n characters and digits that need special handling, such as the\n compatibility superscript digits. Formally, a digit is a character\n that has the property value Numeric_Type=Digit or\n Numeric_Type=Decimal.\n\nstr.isidentifier()\n\n Return true if the string is a valid identifier according to the\n language definition, section *Identifiers and keywords*.\n\n Use "keyword.iskeyword()" to test for reserved identifiers such as\n "def" and "class".\n\nstr.islower()\n\n Return true if all cased characters [4] in the string are lowercase\n and there is at least one cased character, false otherwise.\n\nstr.isnumeric()\n\n Return true if all characters in the string are numeric characters,\n and there is at least one character, false otherwise. Numeric\n characters include digit characters, and all characters that have\n the Unicode numeric value property, e.g. U+2155, VULGAR FRACTION\n ONE FIFTH. Formally, numeric characters are those with the\n property value Numeric_Type=Digit, Numeric_Type=Decimal or\n Numeric_Type=Numeric.\n\nstr.isprintable()\n\n Return true if all characters in the string are printable or the\n string is empty, false otherwise. Nonprintable characters are\n those characters defined in the Unicode character database as\n "Other" or "Separator", excepting the ASCII space (0x20) which is\n considered printable. (Note that printable characters in this\n context are those which should not be escaped when "repr()" is\n invoked on a string. It has no bearing on the handling of strings\n written to "sys.stdout" or "sys.stderr".)\n\nstr.isspace()\n\n Return true if there are only whitespace characters in the string\n and there is at least one character, false otherwise. Whitespace\n characters are those characters defined in the Unicode character\n database as "Other" or "Separator" and those with bidirectional\n property being one of "WS", "B", or "S".\n\nstr.istitle()\n\n Return true if the string is a titlecased string and there is at\n least one character, for example uppercase characters may only\n follow uncased characters and lowercase characters only cased ones.\n Return false otherwise.\n\nstr.isupper()\n\n Return true if all cased characters [4] in the string are uppercase\n and there is at least one cased character, false otherwise.\n\nstr.join(iterable)\n\n Return a string which is the concatenation of the strings in the\n *iterable* *iterable*. A "TypeError" will be raised if there are\n any non-string values in *iterable*, including "bytes" objects.\n The separator between elements is the string providing this method.\n\nstr.ljust(width[, fillchar])\n\n Return the string left justified in a string of length *width*.\n Padding is done using the specified *fillchar* (default is an ASCII\n space). The original string is returned if *width* is less than or\n equal to "len(s)".\n\nstr.lower()\n\n Return a copy of the string with all the cased characters [4]\n converted to lowercase.\n\n The lowercasing algorithm used is described in section 3.13 of the\n Unicode Standard.\n\nstr.lstrip([chars])\n\n Return a copy of the string with leading characters removed. The\n *chars* argument is a string specifying the set of characters to be\n removed. If omitted or "None", the *chars* argument defaults to\n removing whitespace. The *chars* argument is not a prefix; rather,\n all combinations of its values are stripped:\n\n >>> \' spacious \'.lstrip()\n \'spacious \'\n >>> \'www.example.com\'.lstrip(\'cmowz.\')\n \'example.com\'\n\nstatic str.maketrans(x[, y[, z]])\n\n This static method returns a translation table usable for\n "str.translate()".\n\n If there is only one argument, it must be a dictionary mapping\n Unicode ordinals (integers) or characters (strings of length 1) to\n Unicode ordinals, strings (of arbitrary lengths) or None.\n Character keys will then be converted to ordinals.\n\n If there are two arguments, they must be strings of equal length,\n and in the resulting dictionary, each character in x will be mapped\n to the character at the same position in y. If there is a third\n argument, it must be a string, whose characters will be mapped to\n None in the result.\n\nstr.partition(sep)\n\n Split the string at the first occurrence of *sep*, and return a\n 3-tuple containing the part before the separator, the separator\n itself, and the part after the separator. If the separator is not\n found, return a 3-tuple containing the string itself, followed by\n two empty strings.\n\nstr.replace(old, new[, count])\n\n Return a copy of the string with all occurrences of substring *old*\n replaced by *new*. If the optional argument *count* is given, only\n the first *count* occurrences are replaced.\n\nstr.rfind(sub[, start[, end]])\n\n Return the highest index in the string where substring *sub* is\n found, such that *sub* is contained within "s[start:end]".\n Optional arguments *start* and *end* are interpreted as in slice\n notation. Return "-1" on failure.\n\nstr.rindex(sub[, start[, end]])\n\n Like "rfind()" but raises "ValueError" when the substring *sub* is\n not found.\n\nstr.rjust(width[, fillchar])\n\n Return the string right justified in a string of length *width*.\n Padding is done using the specified *fillchar* (default is an ASCII\n space). The original string is returned if *width* is less than or\n equal to "len(s)".\n\nstr.rpartition(sep)\n\n Split the string at the last occurrence of *sep*, and return a\n 3-tuple containing the part before the separator, the separator\n itself, and the part after the separator. If the separator is not\n found, return a 3-tuple containing two empty strings, followed by\n the string itself.\n\nstr.rsplit(sep=None, maxsplit=-1)\n\n Return a list of the words in the string, using *sep* as the\n delimiter string. If *maxsplit* is given, at most *maxsplit* splits\n are done, the *rightmost* ones. If *sep* is not specified or\n "None", any whitespace string is a separator. Except for splitting\n from the right, "rsplit()" behaves like "split()" which is\n described in detail below.\n\nstr.rstrip([chars])\n\n Return a copy of the string with trailing characters removed. The\n *chars* argument is a string specifying the set of characters to be\n removed. If omitted or "None", the *chars* argument defaults to\n removing whitespace. The *chars* argument is not a suffix; rather,\n all combinations of its values are stripped:\n\n >>> \' spacious \'.rstrip()\n \' spacious\'\n >>> \'mississippi\'.rstrip(\'ipz\')\n \'mississ\'\n\nstr.split(sep=None, maxsplit=-1)\n\n Return a list of the words in the string, using *sep* as the\n delimiter string. If *maxsplit* is given, at most *maxsplit*\n splits are done (thus, the list will have at most "maxsplit+1"\n elements). If *maxsplit* is not specified or "-1", then there is\n no limit on the number of splits (all possible splits are made).\n\n If *sep* is given, consecutive delimiters are not grouped together\n and are deemed to delimit empty strings (for example,\n "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', \'2\']"). The *sep* argument\n may consist of multiple characters (for example,\n "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', \'3\']"). Splitting an\n empty string with a specified separator returns "[\'\']".\n\n For example:\n\n >>> \'1,2,3\'.split(\',\')\n [\'1\', \'2\', \'3\']\n >>> \'1,2,3\'.split(\',\', maxsplit=1)\n [\'1\', \'2,3\']\n >>> \'1,2,,3,\'.split(\',\')\n [\'1\', \'2\', \'\', \'3\', \'\']\n\n If *sep* is not specified or is "None", a different splitting\n algorithm is applied: runs of consecutive whitespace are regarded\n as a single separator, and the result will contain no empty strings\n at the start or end if the string has leading or trailing\n whitespace. Consequently, splitting an empty string or a string\n consisting of just whitespace with a "None" separator returns "[]".\n\n For example:\n\n >>> \'1 2 3\'.split()\n [\'1\', \'2\', \'3\']\n >>> \'1 2 3\'.split(maxsplit=1)\n [\'1\', \'2 3\']\n >>> \' 1 2 3 \'.split()\n [\'1\', \'2\', \'3\']\n\nstr.splitlines([keepends])\n\n Return a list of the lines in the string, breaking at line\n boundaries. Line breaks are not included in the resulting list\n unless *keepends* is given and true.\n\n This method splits on the following line boundaries. In\n particular, the boundaries are a superset of *universal newlines*.\n\n +-------------------------+-------------------------------+\n | Representation | Description |\n +=========================+===============================+\n | "\\n" | Line Feed |\n +-------------------------+-------------------------------+\n | "\\r" | Carriage Return |\n +-------------------------+-------------------------------+\n | "\\r\\n" | Carriage Return + Line Feed |\n +-------------------------+-------------------------------+\n | "\\v" or "\\x0b" | Line Tabulation |\n +-------------------------+-------------------------------+\n | "\\f" or "\\x0c" | Form Feed |\n +-------------------------+-------------------------------+\n | "\\x1c" | File Separator |\n +-------------------------+-------------------------------+\n | "\\x1d" | Group Separator |\n +-------------------------+-------------------------------+\n | "\\x1e" | Record Separator |\n +-------------------------+-------------------------------+\n | "\\x85" | Next Line (C1 Control Code) |\n +-------------------------+-------------------------------+\n | "\\u2028" | Line Separator |\n +-------------------------+-------------------------------+\n | "\\u2029" | Paragraph Separator |\n +-------------------------+-------------------------------+\n\n Changed in version 3.2: "\\v" and "\\f" added to list of line\n boundaries.\n\n For example:\n\n >>> \'ab c\\n\\nde fg\\rkl\\r\\n\'.splitlines()\n [\'ab c\', \'\', \'de fg\', \'kl\']\n >>> \'ab c\\n\\nde fg\\rkl\\r\\n\'.splitlines(keepends=True)\n [\'ab c\\n\', \'\\n\', \'de fg\\r\', \'kl\\r\\n\']\n\n Unlike "split()" when a delimiter string *sep* is given, this\n method returns an empty list for the empty string, and a terminal\n line break does not result in an extra line:\n\n >>> "".splitlines()\n []\n >>> "One line\\n".splitlines()\n [\'One line\']\n\n For comparison, "split(\'\\n\')" gives:\n\n >>> \'\'.split(\'\\n\')\n [\'\']\n >>> \'Two lines\\n\'.split(\'\\n\')\n [\'Two lines\', \'\']\n\nstr.startswith(prefix[, start[, end]])\n\n Return "True" if string starts with the *prefix*, otherwise return\n "False". *prefix* can also be a tuple of prefixes to look for.\n With optional *start*, test string beginning at that position.\n With optional *end*, stop comparing string at that position.\n\nstr.strip([chars])\n\n Return a copy of the string with the leading and trailing\n characters removed. The *chars* argument is a string specifying the\n set of characters to be removed. If omitted or "None", the *chars*\n argument defaults to removing whitespace. The *chars* argument is\n not a prefix or suffix; rather, all combinations of its values are\n stripped:\n\n >>> \' spacious \'.strip()\n \'spacious\'\n >>> \'www.example.com\'.strip(\'cmowz.\')\n \'example\'\n\nstr.swapcase()\n\n Return a copy of the string with uppercase characters converted to\n lowercase and vice versa. Note that it is not necessarily true that\n "s.swapcase().swapcase() == s".\n\nstr.title()\n\n Return a titlecased version of the string where words start with an\n uppercase character and the remaining characters are lowercase.\n\n For example:\n\n >>> \'Hello world\'.title()\n \'Hello World\'\n\n The algorithm uses a simple language-independent definition of a\n word as groups of consecutive letters. The definition works in\n many contexts but it means that apostrophes in contractions and\n possessives form word boundaries, which may not be the desired\n result:\n\n >>> "they\'re bill\'s friends from the UK".title()\n "They\'Re Bill\'S Friends From The Uk"\n\n A workaround for apostrophes can be constructed using regular\n expressions:\n\n >>> import re\n >>> def titlecase(s):\n ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n ... lambda mo: mo.group(0)[0].upper() +\n ... mo.group(0)[1:].lower(),\n ... s)\n ...\n >>> titlecase("they\'re bill\'s friends.")\n "They\'re Bill\'s Friends."\n\nstr.translate(table)\n\n Return a copy of the string in which each character has been mapped\n through the given translation table. The table must be an object\n that implements indexing via "__getitem__()", typically a *mapping*\n or *sequence*. When indexed by a Unicode ordinal (an integer), the\n table object can do any of the following: return a Unicode ordinal\n or a string, to map the character to one or more other characters;\n return "None", to delete the character from the return string; or\n raise a "LookupError" exception, to map the character to itself.\n\n You can use "str.maketrans()" to create a translation map from\n character-to-character mappings in different formats.\n\n See also the "codecs" module for a more flexible approach to custom\n character mappings.\n\nstr.upper()\n\n Return a copy of the string with all the cased characters [4]\n converted to uppercase. Note that "str.upper().isupper()" might be\n "False" if "s" contains uncased characters or if the Unicode\n category of the resulting character(s) is not "Lu" (Letter,\n uppercase), but e.g. "Lt" (Letter, titlecase).\n\n The uppercasing algorithm used is described in section 3.13 of the\n Unicode Standard.\n\nstr.zfill(width)\n\n Return a copy of the string left filled with ASCII "\'0\'" digits to\n make a string of length *width*. A leading sign prefix\n ("\'+\'"/"\'-\'") is handled by inserting the padding *after* the sign\n character rather than before. The original string is returned if\n *width* is less than or equal to "len(s)".\n\n For example:\n\n >>> "42".zfill(5)\n \'00042\'\n >>> "-42".zfill(5)\n \'-0042\'\n', + 'strings': u'\nString and Bytes literals\n*************************\n\nString literals are described by the following lexical definitions:\n\n stringliteral ::= [stringprefix](shortstring | longstring)\n stringprefix ::= "r" | "u" | "R" | "U"\n shortstring ::= "\'" shortstringitem* "\'" | \'"\' shortstringitem* \'"\'\n longstring ::= "\'\'\'" longstringitem* "\'\'\'" | \'"""\' longstringitem* \'"""\'\n shortstringitem ::= shortstringchar | stringescapeseq\n longstringitem ::= longstringchar | stringescapeseq\n shortstringchar ::= \n longstringchar ::= \n stringescapeseq ::= "\\" \n\n bytesliteral ::= bytesprefix(shortbytes | longbytes)\n bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"\n shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' shortbytesitem* \'"\'\n longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' longbytesitem* \'"""\'\n shortbytesitem ::= shortbyteschar | bytesescapeseq\n longbytesitem ::= longbyteschar | bytesescapeseq\n shortbyteschar ::= \n longbyteschar ::= \n bytesescapeseq ::= "\\" \n\nOne syntactic restriction not indicated by these productions is that\nwhitespace is not allowed between the "stringprefix" or "bytesprefix"\nand the rest of the literal. The source character set is defined by\nthe encoding declaration; it is UTF-8 if no encoding declaration is\ngiven in the source file; see section *Encoding declarations*.\n\nIn plain English: Both types of literals can be enclosed in matching\nsingle quotes ("\'") or double quotes ("""). They can also be enclosed\nin matching groups of three single or double quotes (these are\ngenerally referred to as *triple-quoted strings*). The backslash\n("\\") character is used to escape characters that otherwise have a\nspecial meaning, such as newline, backslash itself, or the quote\ncharacter.\n\nBytes literals are always prefixed with "\'b\'" or "\'B\'"; they produce\nan instance of the "bytes" type instead of the "str" type. They may\nonly contain ASCII characters; bytes with a numeric value of 128 or\ngreater must be expressed with escapes.\n\nAs of Python 3.3 it is possible again to prefix string literals with a\n"u" prefix to simplify maintenance of dual 2.x and 3.x codebases.\n\nBoth string and bytes literals may optionally be prefixed with a\nletter "\'r\'" or "\'R\'"; such strings are called *raw strings* and treat\nbackslashes as literal characters. As a result, in string literals,\n"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated specially.\nGiven that Python 2.x\'s raw unicode literals behave differently than\nPython 3.x\'s the "\'ur\'" syntax is not supported.\n\nNew in version 3.3: The "\'rb\'" prefix of raw bytes literals has been\nadded as a synonym of "\'br\'".\n\nNew in version 3.3: Support for the unicode legacy literal\n("u\'value\'") was reintroduced to simplify the maintenance of dual\nPython 2.x and 3.x codebases. See **PEP 414** for more information.\n\nIn triple-quoted literals, unescaped newlines and quotes are allowed\n(and are retained), except that three unescaped quotes in a row\nterminate the literal. (A "quote" is the character used to open the\nliteral, i.e. either "\'" or """.)\n\nUnless an "\'r\'" or "\'R\'" prefix is present, escape sequences in string\nand bytes literals are interpreted according to rules similar to those\nused by Standard C. The recognized escape sequences are:\n\n+-------------------+-----------------------------------+---------+\n| Escape Sequence | Meaning | Notes |\n+===================+===================================+=========+\n| "\\newline" | Backslash and newline ignored | |\n+-------------------+-----------------------------------+---------+\n| "\\\\" | Backslash ("\\") | |\n+-------------------+-----------------------------------+---------+\n| "\\\'" | Single quote ("\'") | |\n+-------------------+-----------------------------------+---------+\n| "\\"" | Double quote (""") | |\n+-------------------+-----------------------------------+---------+\n| "\\a" | ASCII Bell (BEL) | |\n+-------------------+-----------------------------------+---------+\n| "\\b" | ASCII Backspace (BS) | |\n+-------------------+-----------------------------------+---------+\n| "\\f" | ASCII Formfeed (FF) | |\n+-------------------+-----------------------------------+---------+\n| "\\n" | ASCII Linefeed (LF) | |\n+-------------------+-----------------------------------+---------+\n| "\\r" | ASCII Carriage Return (CR) | |\n+-------------------+-----------------------------------+---------+\n| "\\t" | ASCII Horizontal Tab (TAB) | |\n+-------------------+-----------------------------------+---------+\n| "\\v" | ASCII Vertical Tab (VT) | |\n+-------------------+-----------------------------------+---------+\n| "\\ooo" | Character with octal value *ooo* | (1,3) |\n+-------------------+-----------------------------------+---------+\n| "\\xhh" | Character with hex value *hh* | (2,3) |\n+-------------------+-----------------------------------+---------+\n\nEscape sequences only recognized in string literals are:\n\n+-------------------+-----------------------------------+---------+\n| Escape Sequence | Meaning | Notes |\n+===================+===================================+=========+\n| "\\N{name}" | Character named *name* in the | (4) |\n| | Unicode database | |\n+-------------------+-----------------------------------+---------+\n| "\\uxxxx" | Character with 16-bit hex value | (5) |\n| | *xxxx* | |\n+-------------------+-----------------------------------+---------+\n| "\\Uxxxxxxxx" | Character with 32-bit hex value | (6) |\n| | *xxxxxxxx* | |\n+-------------------+-----------------------------------+---------+\n\nNotes:\n\n1. As in Standard C, up to three octal digits are accepted.\n\n2. Unlike in Standard C, exactly two hex digits are required.\n\n3. In a bytes literal, hexadecimal and octal escapes denote the\n byte with the given value. In a string literal, these escapes\n denote a Unicode character with the given value.\n\n4. Changed in version 3.3: Support for name aliases [1] has been\n added.\n\n5. Individual code units which form parts of a surrogate pair can\n be encoded using this escape sequence. Exactly four hex digits are\n required.\n\n6. Any Unicode character can be encoded this way. Exactly eight\n hex digits are required.\n\nUnlike Standard C, all unrecognized escape sequences are left in the\nstring unchanged, i.e., *the backslash is left in the result*. (This\nbehavior is useful when debugging: if an escape sequence is mistyped,\nthe resulting output is more easily recognized as broken.) It is also\nimportant to note that the escape sequences only recognized in string\nliterals fall into the category of unrecognized escapes for bytes\nliterals.\n\nEven in a raw literal, quotes can be escaped with a backslash, but the\nbackslash remains in the result; for example, "r"\\""" is a valid\nstring literal consisting of two characters: a backslash and a double\nquote; "r"\\"" is not a valid string literal (even a raw string cannot\nend in an odd number of backslashes). Specifically, *a raw literal\ncannot end in a single backslash* (since the backslash would escape\nthe following quote character). Note also that a single backslash\nfollowed by a newline is interpreted as those two characters as part\nof the literal, *not* as a line continuation.\n', + 'subscriptions': u'\nSubscriptions\n*************\n\nA subscription selects an item of a sequence (string, tuple or list)\nor mapping (dictionary) object:\n\n subscription ::= primary "[" expression_list "]"\n\nThe primary must evaluate to an object that supports subscription\n(lists or dictionaries for example). User-defined objects can support\nsubscription by defining a "__getitem__()" method.\n\nFor built-in objects, there are two types of objects that support\nsubscription:\n\nIf the primary is a mapping, the expression list must evaluate to an\nobject whose value is one of the keys of the mapping, and the\nsubscription selects the value in the mapping that corresponds to that\nkey. (The expression list is a tuple except if it has exactly one\nitem.)\n\nIf the primary is a sequence, the expression (list) must evaluate to\nan integer or a slice (as discussed in the following section).\n\nThe formal syntax makes no special provision for negative indices in\nsequences; however, built-in sequences all provide a "__getitem__()"\nmethod that interprets negative indices by adding the length of the\nsequence to the index (so that "x[-1]" selects the last item of "x").\nThe resulting value must be a nonnegative integer less than the number\nof items in the sequence, and the subscription selects the item whose\nindex is that value (counting from zero). Since the support for\nnegative indices and slicing occurs in the object\'s "__getitem__()"\nmethod, subclasses overriding this method will need to explicitly add\nthat support.\n\nA string\'s items are characters. A character is not a separate data\ntype but a string of exactly one character.\n', + 'truth': u'\nTruth Value Testing\n*******************\n\nAny object can be tested for truth value, for use in an "if" or\n"while" condition or as operand of the Boolean operations below. The\nfollowing values are considered false:\n\n* "None"\n\n* "False"\n\n* zero of any numeric type, for example, "0", "0.0", "0j".\n\n* any empty sequence, for example, "\'\'", "()", "[]".\n\n* any empty mapping, for example, "{}".\n\n* instances of user-defined classes, if the class defines a\n "__bool__()" or "__len__()" method, when that method returns the\n integer zero or "bool" value "False". [1]\n\nAll other values are considered true --- so objects of many types are\nalways true.\n\nOperations and built-in functions that have a Boolean result always\nreturn "0" or "False" for false and "1" or "True" for true, unless\notherwise stated. (Important exception: the Boolean operations "or"\nand "and" always return one of their operands.)\n', + 'try': u'\nThe "try" statement\n*******************\n\nThe "try" statement specifies exception handlers and/or cleanup code\nfor a group of statements:\n\n try_stmt ::= try1_stmt | try2_stmt\n try1_stmt ::= "try" ":" suite\n ("except" [expression ["as" identifier]] ":" suite)+\n ["else" ":" suite]\n ["finally" ":" suite]\n try2_stmt ::= "try" ":" suite\n "finally" ":" suite\n\nThe "except" clause(s) specify one or more exception handlers. When no\nexception occurs in the "try" clause, no exception handler is\nexecuted. When an exception occurs in the "try" suite, a search for an\nexception handler is started. This search inspects the except clauses\nin turn until one is found that matches the exception. An expression-\nless except clause, if present, must be last; it matches any\nexception. For an except clause with an expression, that expression\nis evaluated, and the clause matches the exception if the resulting\nobject is "compatible" with the exception. An object is compatible\nwith an exception if it is the class or a base class of the exception\nobject or a tuple containing an item compatible with the exception.\n\nIf no except clause matches the exception, the search for an exception\nhandler continues in the surrounding code and on the invocation stack.\n[1]\n\nIf the evaluation of an expression in the header of an except clause\nraises an exception, the original search for a handler is canceled and\na search starts for the new exception in the surrounding code and on\nthe call stack (it is treated as if the entire "try" statement raised\nthe exception).\n\nWhen a matching except clause is found, the exception is assigned to\nthe target specified after the "as" keyword in that except clause, if\npresent, and the except clause\'s suite is executed. All except\nclauses must have an executable block. When the end of this block is\nreached, execution continues normally after the entire try statement.\n(This means that if two nested handlers exist for the same exception,\nand the exception occurs in the try clause of the inner handler, the\nouter handler will not handle the exception.)\n\nWhen an exception has been assigned using "as target", it is cleared\nat the end of the except clause. This is as if\n\n except E as N:\n foo\n\nwas translated to\n\n except E as N:\n try:\n foo\n finally:\n del N\n\nThis means the exception must be assigned to a different name to be\nable to refer to it after the except clause. Exceptions are cleared\nbecause with the traceback attached to them, they form a reference\ncycle with the stack frame, keeping all locals in that frame alive\nuntil the next garbage collection occurs.\n\nBefore an except clause\'s suite is executed, details about the\nexception are stored in the "sys" module and can be accessed via\n"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of the\nexception class, the exception instance and a traceback object (see\nsection *The standard type hierarchy*) identifying the point in the\nprogram where the exception occurred. "sys.exc_info()" values are\nrestored to their previous values (before the call) when returning\nfrom a function that handled an exception.\n\nThe optional "else" clause is executed if and when control flows off\nthe end of the "try" clause. [2] Exceptions in the "else" clause are\nnot handled by the preceding "except" clauses.\n\nIf "finally" is present, it specifies a \'cleanup\' handler. The "try"\nclause is executed, including any "except" and "else" clauses. If an\nexception occurs in any of the clauses and is not handled, the\nexception is temporarily saved. The "finally" clause is executed. If\nthere is a saved exception it is re-raised at the end of the "finally"\nclause. If the "finally" clause raises another exception, the saved\nexception is set as the context of the new exception. If the "finally"\nclause executes a "return" or "break" statement, the saved exception\nis discarded:\n\n >>> def f():\n ... try:\n ... 1/0\n ... finally:\n ... return 42\n ...\n >>> f()\n 42\n\nThe exception information is not available to the program during\nexecution of the "finally" clause.\n\nWhen a "return", "break" or "continue" statement is executed in the\n"try" suite of a "try"..."finally" statement, the "finally" clause is\nalso executed \'on the way out.\' A "continue" statement is illegal in\nthe "finally" clause. (The reason is a problem with the current\nimplementation --- this restriction may be lifted in the future).\n\nThe return value of a function is determined by the last "return"\nstatement executed. Since the "finally" clause always executes, a\n"return" statement executed in the "finally" clause will always be the\nlast one executed:\n\n >>> def foo():\n ... try:\n ... return \'try\'\n ... finally:\n ... return \'finally\'\n ...\n >>> foo()\n \'finally\'\n\nAdditional information on exceptions can be found in section\n*Exceptions*, and information on using the "raise" statement to\ngenerate exceptions may be found in section *The raise statement*.\n', + 'types': u'\nThe standard type hierarchy\n***************************\n\nBelow is a list of the types that are built into Python. Extension\nmodules (written in C, Java, or other languages, depending on the\nimplementation) can define additional types. Future versions of\nPython may add types to the type hierarchy (e.g., rational numbers,\nefficiently stored arrays of integers, etc.), although such additions\nwill often be provided via the standard library instead.\n\nSome of the type descriptions below contain a paragraph listing\n\'special attributes.\' These are attributes that provide access to the\nimplementation and are not intended for general use. Their definition\nmay change in the future.\n\nNone\n This type has a single value. There is a single object with this\n value. This object is accessed through the built-in name "None". It\n is used to signify the absence of a value in many situations, e.g.,\n it is returned from functions that don\'t explicitly return\n anything. Its truth value is false.\n\nNotImplemented\n This type has a single value. There is a single object with this\n value. This object is accessed through the built-in name\n "NotImplemented". Numeric methods and rich comparison methods\n should return this value if they do not implement the operation for\n the operands provided. (The interpreter will then try the\n reflected operation, or some other fallback, depending on the\n operator.) Its truth value is true.\n\n See *Implementing the arithmetic operations* for more details.\n\nEllipsis\n This type has a single value. There is a single object with this\n value. This object is accessed through the literal "..." or the\n built-in name "Ellipsis". Its truth value is true.\n\n"numbers.Number"\n These are created by numeric literals and returned as results by\n arithmetic operators and arithmetic built-in functions. Numeric\n objects are immutable; once created their value never changes.\n Python numbers are of course strongly related to mathematical\n numbers, but subject to the limitations of numerical representation\n in computers.\n\n Python distinguishes between integers, floating point numbers, and\n complex numbers:\n\n "numbers.Integral"\n These represent elements from the mathematical set of integers\n (positive and negative).\n\n There are two types of integers:\n\n Integers ("int")\n\n These represent numbers in an unlimited range, subject to\n available (virtual) memory only. For the purpose of shift\n and mask operations, a binary representation is assumed, and\n negative numbers are represented in a variant of 2\'s\n complement which gives the illusion of an infinite string of\n sign bits extending to the left.\n\n Booleans ("bool")\n These represent the truth values False and True. The two\n objects representing the values "False" and "True" are the\n only Boolean objects. The Boolean type is a subtype of the\n integer type, and Boolean values behave like the values 0 and\n 1, respectively, in almost all contexts, the exception being\n that when converted to a string, the strings ""False"" or\n ""True"" are returned, respectively.\n\n The rules for integer representation are intended to give the\n most meaningful interpretation of shift and mask operations\n involving negative integers.\n\n "numbers.Real" ("float")\n These represent machine-level double precision floating point\n numbers. You are at the mercy of the underlying machine\n architecture (and C or Java implementation) for the accepted\n range and handling of overflow. Python does not support single-\n precision floating point numbers; the savings in processor and\n memory usage that are usually the reason for using these are\n dwarfed by the overhead of using objects in Python, so there is\n no reason to complicate the language with two kinds of floating\n point numbers.\n\n "numbers.Complex" ("complex")\n These represent complex numbers as a pair of machine-level\n double precision floating point numbers. The same caveats apply\n as for floating point numbers. The real and imaginary parts of a\n complex number "z" can be retrieved through the read-only\n attributes "z.real" and "z.imag".\n\nSequences\n These represent finite ordered sets indexed by non-negative\n numbers. The built-in function "len()" returns the number of items\n of a sequence. When the length of a sequence is *n*, the index set\n contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence *a* is\n selected by "a[i]".\n\n Sequences also support slicing: "a[i:j]" selects all items with\n index *k* such that *i* "<=" *k* "<" *j*. When used as an\n expression, a slice is a sequence of the same type. This implies\n that the index set is renumbered so that it starts at 0.\n\n Some sequences also support "extended slicing" with a third "step"\n parameter: "a[i:j:k]" selects all items of *a* with index *x* where\n "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n\n Sequences are distinguished according to their mutability:\n\n Immutable sequences\n An object of an immutable sequence type cannot change once it is\n created. (If the object contains references to other objects,\n these other objects may be mutable and may be changed; however,\n the collection of objects directly referenced by an immutable\n object cannot change.)\n\n The following types are immutable sequences:\n\n Strings\n A string is a sequence of values that represent Unicode code\n points. All the code points in the range "U+0000 - U+10FFFF"\n can be represented in a string. Python doesn\'t have a "char"\n type; instead, every code point in the string is represented\n as a string object with length "1". The built-in function\n "ord()" converts a code point from its string form to an\n integer in the range "0 - 10FFFF"; "chr()" converts an\n integer in the range "0 - 10FFFF" to the corresponding length\n "1" string object. "str.encode()" can be used to convert a\n "str" to "bytes" using the given text encoding, and\n "bytes.decode()" can be used to achieve the opposite.\n\n Tuples\n The items of a tuple are arbitrary Python objects. Tuples of\n two or more items are formed by comma-separated lists of\n expressions. A tuple of one item (a \'singleton\') can be\n formed by affixing a comma to an expression (an expression by\n itself does not create a tuple, since parentheses must be\n usable for grouping of expressions). An empty tuple can be\n formed by an empty pair of parentheses.\n\n Bytes\n A bytes object is an immutable array. The items are 8-bit\n bytes, represented by integers in the range 0 <= x < 256.\n Bytes literals (like "b\'abc\'") and the built-in function\n "bytes()" can be used to construct bytes objects. Also,\n bytes objects can be decoded to strings via the "decode()"\n method.\n\n Mutable sequences\n Mutable sequences can be changed after they are created. The\n subscription and slicing notations can be used as the target of\n assignment and "del" (delete) statements.\n\n There are currently two intrinsic mutable sequence types:\n\n Lists\n The items of a list are arbitrary Python objects. Lists are\n formed by placing a comma-separated list of expressions in\n square brackets. (Note that there are no special cases needed\n to form lists of length 0 or 1.)\n\n Byte Arrays\n A bytearray object is a mutable array. They are created by\n the built-in "bytearray()" constructor. Aside from being\n mutable (and hence unhashable), byte arrays otherwise provide\n the same interface and functionality as immutable bytes\n objects.\n\n The extension module "array" provides an additional example of a\n mutable sequence type, as does the "collections" module.\n\nSet types\n These represent unordered, finite sets of unique, immutable\n objects. As such, they cannot be indexed by any subscript. However,\n they can be iterated over, and the built-in function "len()"\n returns the number of items in a set. Common uses for sets are fast\n membership testing, removing duplicates from a sequence, and\n computing mathematical operations such as intersection, union,\n difference, and symmetric difference.\n\n For set elements, the same immutability rules apply as for\n dictionary keys. Note that numeric types obey the normal rules for\n numeric comparison: if two numbers compare equal (e.g., "1" and\n "1.0"), only one of them can be contained in a set.\n\n There are currently two intrinsic set types:\n\n Sets\n These represent a mutable set. They are created by the built-in\n "set()" constructor and can be modified afterwards by several\n methods, such as "add()".\n\n Frozen sets\n These represent an immutable set. They are created by the\n built-in "frozenset()" constructor. As a frozenset is immutable\n and *hashable*, it can be used again as an element of another\n set, or as a dictionary key.\n\nMappings\n These represent finite sets of objects indexed by arbitrary index\n sets. The subscript notation "a[k]" selects the item indexed by "k"\n from the mapping "a"; this can be used in expressions and as the\n target of assignments or "del" statements. The built-in function\n "len()" returns the number of items in a mapping.\n\n There is currently a single intrinsic mapping type:\n\n Dictionaries\n These represent finite sets of objects indexed by nearly\n arbitrary values. The only types of values not acceptable as\n keys are values containing lists or dictionaries or other\n mutable types that are compared by value rather than by object\n identity, the reason being that the efficient implementation of\n dictionaries requires a key\'s hash value to remain constant.\n Numeric types used for keys obey the normal rules for numeric\n comparison: if two numbers compare equal (e.g., "1" and "1.0")\n then they can be used interchangeably to index the same\n dictionary entry.\n\n Dictionaries are mutable; they can be created by the "{...}"\n notation (see section *Dictionary displays*).\n\n The extension modules "dbm.ndbm" and "dbm.gnu" provide\n additional examples of mapping types, as does the "collections"\n module.\n\nCallable types\n These are the types to which the function call operation (see\n section *Calls*) can be applied:\n\n User-defined functions\n A user-defined function object is created by a function\n definition (see section *Function definitions*). It should be\n called with an argument list containing the same number of items\n as the function\'s formal parameter list.\n\n Special attributes:\n\n +---------------------------+---------------------------------+-------------+\n | Attribute | Meaning | |\n +===========================+=================================+=============+\n | "__doc__" | The function\'s documentation | Writable |\n | | string, or "None" if | |\n | | unavailable; not inherited by | |\n | | subclasses | |\n +---------------------------+---------------------------------+-------------+\n | "__name__" | The function\'s name | Writable |\n +---------------------------+---------------------------------+-------------+\n | "__qualname__" | The function\'s *qualified name* | Writable |\n | | New in version 3.3. | |\n +---------------------------+---------------------------------+-------------+\n | "__module__" | The name of the module the | Writable |\n | | function was defined in, or | |\n | | "None" if unavailable. | |\n +---------------------------+---------------------------------+-------------+\n | "__defaults__" | A tuple containing default | Writable |\n | | argument values for those | |\n | | arguments that have defaults, | |\n | | or "None" if no arguments have | |\n | | a default value | |\n +---------------------------+---------------------------------+-------------+\n | "__code__" | The code object representing | Writable |\n | | the compiled function body. | |\n +---------------------------+---------------------------------+-------------+\n | "__globals__" | A reference to the dictionary | Read-only |\n | | that holds the function\'s | |\n | | global variables --- the global | |\n | | namespace of the module in | |\n | | which the function was defined. | |\n +---------------------------+---------------------------------+-------------+\n | "__dict__" | The namespace supporting | Writable |\n | | arbitrary function attributes. | |\n +---------------------------+---------------------------------+-------------+\n | "__closure__" | "None" or a tuple of cells that | Read-only |\n | | contain bindings for the | |\n | | function\'s free variables. | |\n +---------------------------+---------------------------------+-------------+\n | "__annotations__" | A dict containing annotations | Writable |\n | | of parameters. The keys of the | |\n | | dict are the parameter names, | |\n | | and "\'return\'" for the return | |\n | | annotation, if provided. | |\n +---------------------------+---------------------------------+-------------+\n | "__kwdefaults__" | A dict containing defaults for | Writable |\n | | keyword-only parameters. | |\n +---------------------------+---------------------------------+-------------+\n\n Most of the attributes labelled "Writable" check the type of the\n assigned value.\n\n Function objects also support getting and setting arbitrary\n attributes, which can be used, for example, to attach metadata\n to functions. Regular attribute dot-notation is used to get and\n set such attributes. *Note that the current implementation only\n supports function attributes on user-defined functions. Function\n attributes on built-in functions may be supported in the\n future.*\n\n Additional information about a function\'s definition can be\n retrieved from its code object; see the description of internal\n types below.\n\n Instance methods\n An instance method object combines a class, a class instance and\n any callable object (normally a user-defined function).\n\n Special read-only attributes: "__self__" is the class instance\n object, "__func__" is the function object; "__doc__" is the\n method\'s documentation (same as "__func__.__doc__"); "__name__"\n is the method name (same as "__func__.__name__"); "__module__"\n is the name of the module the method was defined in, or "None"\n if unavailable.\n\n Methods also support accessing (but not setting) the arbitrary\n function attributes on the underlying function object.\n\n User-defined method objects may be created when getting an\n attribute of a class (perhaps via an instance of that class), if\n that attribute is a user-defined function object or a class\n method object.\n\n When an instance method object is created by retrieving a user-\n defined function object from a class via one of its instances,\n its "__self__" attribute is the instance, and the method object\n is said to be bound. The new method\'s "__func__" attribute is\n the original function object.\n\n When a user-defined method object is created by retrieving\n another method object from a class or instance, the behaviour is\n the same as for a function object, except that the "__func__"\n attribute of the new instance is not the original method object\n but its "__func__" attribute.\n\n When an instance method object is created by retrieving a class\n method object from a class or instance, its "__self__" attribute\n is the class itself, and its "__func__" attribute is the\n function object underlying the class method.\n\n When an instance method object is called, the underlying\n function ("__func__") is called, inserting the class instance\n ("__self__") in front of the argument list. For instance, when\n "C" is a class which contains a definition for a function "f()",\n and "x" is an instance of "C", calling "x.f(1)" is equivalent to\n calling "C.f(x, 1)".\n\n When an instance method object is derived from a class method\n object, the "class instance" stored in "__self__" will actually\n be the class itself, so that calling either "x.f(1)" or "C.f(1)"\n is equivalent to calling "f(C,1)" where "f" is the underlying\n function.\n\n Note that the transformation from function object to instance\n method object happens each time the attribute is retrieved from\n the instance. In some cases, a fruitful optimization is to\n assign the attribute to a local variable and call that local\n variable. Also notice that this transformation only happens for\n user-defined functions; other callable objects (and all non-\n callable objects) are retrieved without transformation. It is\n also important to note that user-defined functions which are\n attributes of a class instance are not converted to bound\n methods; this *only* happens when the function is an attribute\n of the class.\n\n Generator functions\n A function or method which uses the "yield" statement (see\n section *The yield statement*) is called a *generator function*.\n Such a function, when called, always returns an iterator object\n which can be used to execute the body of the function: calling\n the iterator\'s "iterator.__next__()" method will cause the\n function to execute until it provides a value using the "yield"\n statement. When the function executes a "return" statement or\n falls off the end, a "StopIteration" exception is raised and the\n iterator will have reached the end of the set of values to be\n returned.\n\n Built-in functions\n A built-in function object is a wrapper around a C function.\n Examples of built-in functions are "len()" and "math.sin()"\n ("math" is a standard built-in module). The number and type of\n the arguments are determined by the C function. Special read-\n only attributes: "__doc__" is the function\'s documentation\n string, or "None" if unavailable; "__name__" is the function\'s\n name; "__self__" is set to "None" (but see the next item);\n "__module__" is the name of the module the function was defined\n in or "None" if unavailable.\n\n Built-in methods\n This is really a different disguise of a built-in function, this\n time containing an object passed to the C function as an\n implicit extra argument. An example of a built-in method is\n "alist.append()", assuming *alist* is a list object. In this\n case, the special read-only attribute "__self__" is set to the\n object denoted by *alist*.\n\n Classes\n Classes are callable. These objects normally act as factories\n for new instances of themselves, but variations are possible for\n class types that override "__new__()". The arguments of the\n call are passed to "__new__()" and, in the typical case, to\n "__init__()" to initialize the new instance.\n\n Class Instances\n Instances of arbitrary classes can be made callable by defining\n a "__call__()" method in their class.\n\nModules\n Modules are a basic organizational unit of Python code, and are\n created by the *import system* as invoked either by the "import"\n statement (see "import"), or by calling functions such as\n "importlib.import_module()" and built-in "__import__()". A module\n object has a namespace implemented by a dictionary object (this is\n the dictionary referenced by the "__globals__" attribute of\n functions defined in the module). Attribute references are\n translated to lookups in this dictionary, e.g., "m.x" is equivalent\n to "m.__dict__["x"]". A module object does not contain the code\n object used to initialize the module (since it isn\'t needed once\n the initialization is done).\n\n Attribute assignment updates the module\'s namespace dictionary,\n e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n\n Special read-only attribute: "__dict__" is the module\'s namespace\n as a dictionary object.\n\n **CPython implementation detail:** Because of the way CPython\n clears module dictionaries, the module dictionary will be cleared\n when the module falls out of scope even if the dictionary still has\n live references. To avoid this, copy the dictionary or keep the\n module around while using its dictionary directly.\n\n Predefined (writable) attributes: "__name__" is the module\'s name;\n "__doc__" is the module\'s documentation string, or "None" if\n unavailable; "__file__" is the pathname of the file from which the\n module was loaded, if it was loaded from a file. The "__file__"\n attribute may be missing for certain types of modules, such as C\n modules that are statically linked into the interpreter; for\n extension modules loaded dynamically from a shared library, it is\n the pathname of the shared library file.\n\nCustom classes\n Custom class types are typically created by class definitions (see\n section *Class definitions*). A class has a namespace implemented\n by a dictionary object. Class attribute references are translated\n to lookups in this dictionary, e.g., "C.x" is translated to\n "C.__dict__["x"]" (although there are a number of hooks which allow\n for other means of locating attributes). When the attribute name is\n not found there, the attribute search continues in the base\n classes. This search of the base classes uses the C3 method\n resolution order which behaves correctly even in the presence of\n \'diamond\' inheritance structures where there are multiple\n inheritance paths leading back to a common ancestor. Additional\n details on the C3 MRO used by Python can be found in the\n documentation accompanying the 2.3 release at\n https://www.python.org/download/releases/2.3/mro/.\n\n When a class attribute reference (for class "C", say) would yield a\n class method object, it is transformed into an instance method\n object whose "__self__" attributes is "C". When it would yield a\n static method object, it is transformed into the object wrapped by\n the static method object. See section *Implementing Descriptors*\n for another way in which attributes retrieved from a class may\n differ from those actually contained in its "__dict__".\n\n Class attribute assignments update the class\'s dictionary, never\n the dictionary of a base class.\n\n A class object can be called (see above) to yield a class instance\n (see below).\n\n Special attributes: "__name__" is the class name; "__module__" is\n the module name in which the class was defined; "__dict__" is the\n dictionary containing the class\'s namespace; "__bases__" is a tuple\n (possibly empty or a singleton) containing the base classes, in the\n order of their occurrence in the base class list; "__doc__" is the\n class\'s documentation string, or None if undefined.\n\nClass instances\n A class instance is created by calling a class object (see above).\n A class instance has a namespace implemented as a dictionary which\n is the first place in which attribute references are searched.\n When an attribute is not found there, and the instance\'s class has\n an attribute by that name, the search continues with the class\n attributes. If a class attribute is found that is a user-defined\n function object, it is transformed into an instance method object\n whose "__self__" attribute is the instance. Static method and\n class method objects are also transformed; see above under\n "Classes". See section *Implementing Descriptors* for another way\n in which attributes of a class retrieved via its instances may\n differ from the objects actually stored in the class\'s "__dict__".\n If no class attribute is found, and the object\'s class has a\n "__getattr__()" method, that is called to satisfy the lookup.\n\n Attribute assignments and deletions update the instance\'s\n dictionary, never a class\'s dictionary. If the class has a\n "__setattr__()" or "__delattr__()" method, this is called instead\n of updating the instance dictionary directly.\n\n Class instances can pretend to be numbers, sequences, or mappings\n if they have methods with certain special names. See section\n *Special method names*.\n\n Special attributes: "__dict__" is the attribute dictionary;\n "__class__" is the instance\'s class.\n\nI/O objects (also known as file objects)\n A *file object* represents an open file. Various shortcuts are\n available to create file objects: the "open()" built-in function,\n and also "os.popen()", "os.fdopen()", and the "makefile()" method\n of socket objects (and perhaps by other functions or methods\n provided by extension modules).\n\n The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n initialized to file objects corresponding to the interpreter\'s\n standard input, output and error streams; they are all open in text\n mode and therefore follow the interface defined by the\n "io.TextIOBase" abstract class.\n\nInternal types\n A few types used internally by the interpreter are exposed to the\n user. Their definitions may change with future versions of the\n interpreter, but they are mentioned here for completeness.\n\n Code objects\n Code objects represent *byte-compiled* executable Python code,\n or *bytecode*. The difference between a code object and a\n function object is that the function object contains an explicit\n reference to the function\'s globals (the module in which it was\n defined), while a code object contains no context; also the\n default argument values are stored in the function object, not\n in the code object (because they represent values calculated at\n run-time). Unlike function objects, code objects are immutable\n and contain no references (directly or indirectly) to mutable\n objects.\n\n Special read-only attributes: "co_name" gives the function name;\n "co_argcount" is the number of positional arguments (including\n arguments with default values); "co_nlocals" is the number of\n local variables used by the function (including arguments);\n "co_varnames" is a tuple containing the names of the local\n variables (starting with the argument names); "co_cellvars" is a\n tuple containing the names of local variables that are\n referenced by nested functions; "co_freevars" is a tuple\n containing the names of free variables; "co_code" is a string\n representing the sequence of bytecode instructions; "co_consts"\n is a tuple containing the literals used by the bytecode;\n "co_names" is a tuple containing the names used by the bytecode;\n "co_filename" is the filename from which the code was compiled;\n "co_firstlineno" is the first line number of the function;\n "co_lnotab" is a string encoding the mapping from bytecode\n offsets to line numbers (for details see the source code of the\n interpreter); "co_stacksize" is the required stack size\n (including local variables); "co_flags" is an integer encoding a\n number of flags for the interpreter.\n\n The following flag bits are defined for "co_flags": bit "0x04"\n is set if the function uses the "*arguments" syntax to accept an\n arbitrary number of positional arguments; bit "0x08" is set if\n the function uses the "**keywords" syntax to accept arbitrary\n keyword arguments; bit "0x20" is set if the function is a\n generator.\n\n Future feature declarations ("from __future__ import division")\n also use bits in "co_flags" to indicate whether a code object\n was compiled with a particular feature enabled: bit "0x2000" is\n set if the function was compiled with future division enabled;\n bits "0x10" and "0x1000" were used in earlier versions of\n Python.\n\n Other bits in "co_flags" are reserved for internal use.\n\n If a code object represents a function, the first item in\n "co_consts" is the documentation string of the function, or\n "None" if undefined.\n\n Frame objects\n Frame objects represent execution frames. They may occur in\n traceback objects (see below).\n\n Special read-only attributes: "f_back" is to the previous stack\n frame (towards the caller), or "None" if this is the bottom\n stack frame; "f_code" is the code object being executed in this\n frame; "f_locals" is the dictionary used to look up local\n variables; "f_globals" is used for global variables;\n "f_builtins" is used for built-in (intrinsic) names; "f_lasti"\n gives the precise instruction (this is an index into the\n bytecode string of the code object).\n\n Special writable attributes: "f_trace", if not "None", is a\n function called at the start of each source code line (this is\n used by the debugger); "f_lineno" is the current line number of\n the frame --- writing to this from within a trace function jumps\n to the given line (only for the bottom-most frame). A debugger\n can implement a Jump command (aka Set Next Statement) by writing\n to f_lineno.\n\n Frame objects support one method:\n\n frame.clear()\n\n This method clears all references to local variables held by\n the frame. Also, if the frame belonged to a generator, the\n generator is finalized. This helps break reference cycles\n involving frame objects (for example when catching an\n exception and storing its traceback for later use).\n\n "RuntimeError" is raised if the frame is currently executing.\n\n New in version 3.4.\n\n Traceback objects\n Traceback objects represent a stack trace of an exception. A\n traceback object is created when an exception occurs. When the\n search for an exception handler unwinds the execution stack, at\n each unwound level a traceback object is inserted in front of\n the current traceback. When an exception handler is entered,\n the stack trace is made available to the program. (See section\n *The try statement*.) It is accessible as the third item of the\n tuple returned by "sys.exc_info()". When the program contains no\n suitable handler, the stack trace is written (nicely formatted)\n to the standard error stream; if the interpreter is interactive,\n it is also made available to the user as "sys.last_traceback".\n\n Special read-only attributes: "tb_next" is the next level in the\n stack trace (towards the frame where the exception occurred), or\n "None" if there is no next level; "tb_frame" points to the\n execution frame of the current level; "tb_lineno" gives the line\n number where the exception occurred; "tb_lasti" indicates the\n precise instruction. The line number and last instruction in\n the traceback may differ from the line number of its frame\n object if the exception occurred in a "try" statement with no\n matching except clause or with a finally clause.\n\n Slice objects\n Slice objects are used to represent slices for "__getitem__()"\n methods. They are also created by the built-in "slice()"\n function.\n\n Special read-only attributes: "start" is the lower bound; "stop"\n is the upper bound; "step" is the step value; each is "None" if\n omitted. These attributes can have any type.\n\n Slice objects support one method:\n\n slice.indices(self, length)\n\n This method takes a single integer argument *length* and\n computes information about the slice that the slice object\n would describe if applied to a sequence of *length* items.\n It returns a tuple of three integers; respectively these are\n the *start* and *stop* indices and the *step* or stride\n length of the slice. Missing or out-of-bounds indices are\n handled in a manner consistent with regular slices.\n\n Static method objects\n Static method objects provide a way of defeating the\n transformation of function objects to method objects described\n above. A static method object is a wrapper around any other\n object, usually a user-defined method object. When a static\n method object is retrieved from a class or a class instance, the\n object actually returned is the wrapped object, which is not\n subject to any further transformation. Static method objects are\n not themselves callable, although the objects they wrap usually\n are. Static method objects are created by the built-in\n "staticmethod()" constructor.\n\n Class method objects\n A class method object, like a static method object, is a wrapper\n around another object that alters the way in which that object\n is retrieved from classes and class instances. The behaviour of\n class method objects upon such retrieval is described above,\n under "User-defined methods". Class method objects are created\n by the built-in "classmethod()" constructor.\n', + 'typesfunctions': u'\nFunctions\n*********\n\nFunction objects are created by function definitions. The only\noperation on a function object is to call it: "func(argument-list)".\n\nThere are really two flavors of function objects: built-in functions\nand user-defined functions. Both support the same operation (to call\nthe function), but the implementation is different, hence the\ndifferent object types.\n\nSee *Function definitions* for more information.\n', + 'typesmapping': u'\nMapping Types --- "dict"\n************************\n\nA *mapping* object maps *hashable* values to arbitrary objects.\nMappings are mutable objects. There is currently only one standard\nmapping type, the *dictionary*. (For other containers see the built-\nin "list", "set", and "tuple" classes, and the "collections" module.)\n\nA dictionary\'s keys are *almost* arbitrary values. Values that are\nnot *hashable*, that is, values containing lists, dictionaries or\nother mutable types (that are compared by value rather than by object\nidentity) may not be used as keys. Numeric types used for keys obey\nthe normal rules for numeric comparison: if two numbers compare equal\n(such as "1" and "1.0") then they can be used interchangeably to index\nthe same dictionary entry. (Note however, that since computers store\nfloating-point numbers as approximations it is usually unwise to use\nthem as dictionary keys.)\n\nDictionaries can be created by placing a comma-separated list of "key:\nvalue" pairs within braces, for example: "{\'jack\': 4098, \'sjoerd\':\n4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the "dict"\nconstructor.\n\nclass class dict(**kwarg)\nclass class dict(mapping, **kwarg)\nclass class dict(iterable, **kwarg)\n\n Return a new dictionary initialized from an optional positional\n argument and a possibly empty set of keyword arguments.\n\n If no positional argument is given, an empty dictionary is created.\n If a positional argument is given and it is a mapping object, a\n dictionary is created with the same key-value pairs as the mapping\n object. Otherwise, the positional argument must be an *iterable*\n object. Each item in the iterable must itself be an iterable with\n exactly two objects. The first object of each item becomes a key\n in the new dictionary, and the second object the corresponding\n value. If a key occurs more than once, the last value for that key\n becomes the corresponding value in the new dictionary.\n\n If keyword arguments are given, the keyword arguments and their\n values are added to the dictionary created from the positional\n argument. If a key being added is already present, the value from\n the keyword argument replaces the value from the positional\n argument.\n\n To illustrate, the following examples all return a dictionary equal\n to "{"one": 1, "two": 2, "three": 3}":\n\n >>> a = dict(one=1, two=2, three=3)\n >>> b = {\'one\': 1, \'two\': 2, \'three\': 3}\n >>> c = dict(zip([\'one\', \'two\', \'three\'], [1, 2, 3]))\n >>> d = dict([(\'two\', 2), (\'one\', 1), (\'three\', 3)])\n >>> e = dict({\'three\': 3, \'one\': 1, \'two\': 2})\n >>> a == b == c == d == e\n True\n\n Providing keyword arguments as in the first example only works for\n keys that are valid Python identifiers. Otherwise, any valid keys\n can be used.\n\n These are the operations that dictionaries support (and therefore,\n custom mapping types should support too):\n\n len(d)\n\n Return the number of items in the dictionary *d*.\n\n d[key]\n\n Return the item of *d* with key *key*. Raises a "KeyError" if\n *key* is not in the map.\n\n If a subclass of dict defines a method "__missing__()" and *key*\n is not present, the "d[key]" operation calls that method with\n the key *key* as argument. The "d[key]" operation then returns\n or raises whatever is returned or raised by the\n "__missing__(key)" call. No other operations or methods invoke\n "__missing__()". If "__missing__()" is not defined, "KeyError"\n is raised. "__missing__()" must be a method; it cannot be an\n instance variable:\n\n >>> class Counter(dict):\n ... def __missing__(self, key):\n ... return 0\n >>> c = Counter()\n >>> c[\'red\']\n 0\n >>> c[\'red\'] += 1\n >>> c[\'red\']\n 1\n\n The example above shows part of the implementation of\n "collections.Counter". A different "__missing__" method is used\n by "collections.defaultdict".\n\n d[key] = value\n\n Set "d[key]" to *value*.\n\n del d[key]\n\n Remove "d[key]" from *d*. Raises a "KeyError" if *key* is not\n in the map.\n\n key in d\n\n Return "True" if *d* has a key *key*, else "False".\n\n key not in d\n\n Equivalent to "not key in d".\n\n iter(d)\n\n Return an iterator over the keys of the dictionary. This is a\n shortcut for "iter(d.keys())".\n\n clear()\n\n Remove all items from the dictionary.\n\n copy()\n\n Return a shallow copy of the dictionary.\n\n classmethod fromkeys(seq[, value])\n\n Create a new dictionary with keys from *seq* and values set to\n *value*.\n\n "fromkeys()" is a class method that returns a new dictionary.\n *value* defaults to "None".\n\n get(key[, default])\n\n Return the value for *key* if *key* is in the dictionary, else\n *default*. If *default* is not given, it defaults to "None", so\n that this method never raises a "KeyError".\n\n items()\n\n Return a new view of the dictionary\'s items ("(key, value)"\n pairs). See the *documentation of view objects*.\n\n keys()\n\n Return a new view of the dictionary\'s keys. See the\n *documentation of view objects*.\n\n pop(key[, default])\n\n If *key* is in the dictionary, remove it and return its value,\n else return *default*. If *default* is not given and *key* is\n not in the dictionary, a "KeyError" is raised.\n\n popitem()\n\n Remove and return an arbitrary "(key, value)" pair from the\n dictionary.\n\n "popitem()" is useful to destructively iterate over a\n dictionary, as often used in set algorithms. If the dictionary\n is empty, calling "popitem()" raises a "KeyError".\n\n setdefault(key[, default])\n\n If *key* is in the dictionary, return its value. If not, insert\n *key* with a value of *default* and return *default*. *default*\n defaults to "None".\n\n update([other])\n\n Update the dictionary with the key/value pairs from *other*,\n overwriting existing keys. Return "None".\n\n "update()" accepts either another dictionary object or an\n iterable of key/value pairs (as tuples or other iterables of\n length two). If keyword arguments are specified, the dictionary\n is then updated with those key/value pairs: "d.update(red=1,\n blue=2)".\n\n values()\n\n Return a new view of the dictionary\'s values. See the\n *documentation of view objects*.\n\n Dictionaries compare equal if and only if they have the same "(key,\n value)" pairs. Order comparisons (\'<\', \'<=\', \'>=\', \'>\') raise\n "TypeError".\n\nSee also: "types.MappingProxyType" can be used to create a read-only\n view of a "dict".\n\n\nDictionary view objects\n=======================\n\nThe objects returned by "dict.keys()", "dict.values()" and\n"dict.items()" are *view objects*. They provide a dynamic view on the\ndictionary\'s entries, which means that when the dictionary changes,\nthe view reflects these changes.\n\nDictionary views can be iterated over to yield their respective data,\nand support membership tests:\n\nlen(dictview)\n\n Return the number of entries in the dictionary.\n\niter(dictview)\n\n Return an iterator over the keys, values or items (represented as\n tuples of "(key, value)") in the dictionary.\n\n Keys and values are iterated over in an arbitrary order which is\n non-random, varies across Python implementations, and depends on\n the dictionary\'s history of insertions and deletions. If keys,\n values and items views are iterated over with no intervening\n modifications to the dictionary, the order of items will directly\n correspond. This allows the creation of "(value, key)" pairs using\n "zip()": "pairs = zip(d.values(), d.keys())". Another way to\n create the same list is "pairs = [(v, k) for (k, v) in d.items()]".\n\n Iterating views while adding or deleting entries in the dictionary\n may raise a "RuntimeError" or fail to iterate over all entries.\n\nx in dictview\n\n Return "True" if *x* is in the underlying dictionary\'s keys, values\n or items (in the latter case, *x* should be a "(key, value)"\n tuple).\n\nKeys views are set-like since their entries are unique and hashable.\nIf all values are hashable, so that "(key, value)" pairs are unique\nand hashable, then the items view is also set-like. (Values views are\nnot treated as set-like since the entries are generally not unique.)\nFor set-like views, all of the operations defined for the abstract\nbase class "collections.abc.Set" are available (for example, "==",\n"<", or "^").\n\nAn example of dictionary view usage:\n\n >>> dishes = {\'eggs\': 2, \'sausage\': 1, \'bacon\': 1, \'spam\': 500}\n >>> keys = dishes.keys()\n >>> values = dishes.values()\n\n >>> # iteration\n >>> n = 0\n >>> for val in values:\n ... n += val\n >>> print(n)\n 504\n\n >>> # keys and values are iterated over in the same order\n >>> list(keys)\n [\'eggs\', \'bacon\', \'sausage\', \'spam\']\n >>> list(values)\n [2, 1, 1, 500]\n\n >>> # view objects are dynamic and reflect dict changes\n >>> del dishes[\'eggs\']\n >>> del dishes[\'sausage\']\n >>> list(keys)\n [\'spam\', \'bacon\']\n\n >>> # set operations\n >>> keys & {\'eggs\', \'bacon\', \'salad\'}\n {\'bacon\'}\n >>> keys ^ {\'sausage\', \'juice\'}\n {\'juice\', \'sausage\', \'bacon\', \'spam\'}\n', + 'typesmethods': u'\nMethods\n*******\n\nMethods are functions that are called using the attribute notation.\nThere are two flavors: built-in methods (such as "append()" on lists)\nand class instance methods. Built-in methods are described with the\ntypes that support them.\n\nIf you access a method (a function defined in a class namespace)\nthrough an instance, you get a special object: a *bound method* (also\ncalled *instance method*) object. When called, it will add the "self"\nargument to the argument list. Bound methods have two special read-\nonly attributes: "m.__self__" is the object on which the method\noperates, and "m.__func__" is the function implementing the method.\nCalling "m(arg-1, arg-2, ..., arg-n)" is completely equivalent to\ncalling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n\nLike function objects, bound method objects support getting arbitrary\nattributes. However, since method attributes are actually stored on\nthe underlying function object ("meth.__func__"), setting method\nattributes on bound methods is disallowed. Attempting to set an\nattribute on a method results in an "AttributeError" being raised. In\norder to set a method attribute, you need to explicitly set it on the\nunderlying function object:\n\n >>> class C:\n ... def method(self):\n ... pass\n ...\n >>> c = C()\n >>> c.method.whoami = \'my name is method\' # can\'t set on the method\n Traceback (most recent call last):\n File "", line 1, in \n AttributeError: \'method\' object has no attribute \'whoami\'\n >>> c.method.__func__.whoami = \'my name is method\'\n >>> c.method.whoami\n \'my name is method\'\n\nSee *The standard type hierarchy* for more information.\n', + 'typesmodules': u'\nModules\n*******\n\nThe only special operation on a module is attribute access: "m.name",\nwhere *m* is a module and *name* accesses a name defined in *m*\'s\nsymbol table. Module attributes can be assigned to. (Note that the\n"import" statement is not, strictly speaking, an operation on a module\nobject; "import foo" does not require a module object named *foo* to\nexist, rather it requires an (external) *definition* for a module\nnamed *foo* somewhere.)\n\nA special attribute of every module is "__dict__". This is the\ndictionary containing the module\'s symbol table. Modifying this\ndictionary will actually change the module\'s symbol table, but direct\nassignment to the "__dict__" attribute is not possible (you can write\n"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but you can\'t\nwrite "m.__dict__ = {}"). Modifying "__dict__" directly is not\nrecommended.\n\nModules built into the interpreter are written like this: "". If loaded from a file, they are written as\n"".\n', + 'typesseq': u'\nSequence Types --- "list", "tuple", "range"\n*******************************************\n\nThere are three basic sequence types: lists, tuples, and range\nobjects. Additional sequence types tailored for processing of *binary\ndata* and *text strings* are described in dedicated sections.\n\n\nCommon Sequence Operations\n==========================\n\nThe operations in the following table are supported by most sequence\ntypes, both mutable and immutable. The "collections.abc.Sequence" ABC\nis provided to make it easier to correctly implement these operations\non custom sequence types.\n\nThis table lists the sequence operations sorted in ascending priority.\nIn the table, *s* and *t* are sequences of the same type, *n*, *i*,\n*j* and *k* are integers and *x* is an arbitrary object that meets any\ntype and value restrictions imposed by *s*.\n\nThe "in" and "not in" operations have the same priorities as the\ncomparison operations. The "+" (concatenation) and "*" (repetition)\noperations have the same priority as the corresponding numeric\noperations.\n\n+----------------------------+----------------------------------+------------+\n| Operation | Result | Notes |\n+============================+==================================+============+\n| "x in s" | "True" if an item of *s* is | (1) |\n| | equal to *x*, else "False" | |\n+----------------------------+----------------------------------+------------+\n| "x not in s" | "False" if an item of *s* is | (1) |\n| | equal to *x*, else "True" | |\n+----------------------------+----------------------------------+------------+\n| "s + t" | the concatenation of *s* and *t* | (6)(7) |\n+----------------------------+----------------------------------+------------+\n| "s * n" or "n * s" | equivalent to adding *s* to | (2)(7) |\n| | itself *n* times | |\n+----------------------------+----------------------------------+------------+\n| "s[i]" | *i*th item of *s*, origin 0 | (3) |\n+----------------------------+----------------------------------+------------+\n| "s[i:j]" | slice of *s* from *i* to *j* | (3)(4) |\n+----------------------------+----------------------------------+------------+\n| "s[i:j:k]" | slice of *s* from *i* to *j* | (3)(5) |\n| | with step *k* | |\n+----------------------------+----------------------------------+------------+\n| "len(s)" | length of *s* | |\n+----------------------------+----------------------------------+------------+\n| "min(s)" | smallest item of *s* | |\n+----------------------------+----------------------------------+------------+\n| "max(s)" | largest item of *s* | |\n+----------------------------+----------------------------------+------------+\n| "s.index(x[, i[, j]])" | index of the first occurrence of | (8) |\n| | *x* in *s* (at or after index | |\n| | *i* and before index *j*) | |\n+----------------------------+----------------------------------+------------+\n| "s.count(x)" | total number of occurrences of | |\n| | *x* in *s* | |\n+----------------------------+----------------------------------+------------+\n\nSequences of the same type also support comparisons. In particular,\ntuples and lists are compared lexicographically by comparing\ncorresponding elements. This means that to compare equal, every\nelement must compare equal and the two sequences must be of the same\ntype and have the same length. (For full details see *Comparisons* in\nthe language reference.)\n\nNotes:\n\n1. While the "in" and "not in" operations are used only for simple\n containment testing in the general case, some specialised sequences\n (such as "str", "bytes" and "bytearray") also use them for\n subsequence testing:\n\n >>> "gg" in "eggs"\n True\n\n2. Values of *n* less than "0" are treated as "0" (which yields an\n empty sequence of the same type as *s*). Note that items in the\n sequence *s* are not copied; they are referenced multiple times.\n This often haunts new Python programmers; consider:\n\n >>> lists = [[]] * 3\n >>> lists\n [[], [], []]\n >>> lists[0].append(3)\n >>> lists\n [[3], [3], [3]]\n\n What has happened is that "[[]]" is a one-element list containing\n an empty list, so all three elements of "[[]] * 3" are references\n to this single empty list. Modifying any of the elements of\n "lists" modifies this single list. You can create a list of\n different lists this way:\n\n >>> lists = [[] for i in range(3)]\n >>> lists[0].append(3)\n >>> lists[1].append(5)\n >>> lists[2].append(7)\n >>> lists\n [[3], [5], [7]]\n\n Further explanation is available in the FAQ entry *How do I create\n a multidimensional list?*.\n\n3. If *i* or *j* is negative, the index is relative to the end of\n the string: "len(s) + i" or "len(s) + j" is substituted. But note\n that "-0" is still "0".\n\n4. The slice of *s* from *i* to *j* is defined as the sequence of\n items with index *k* such that "i <= k < j". If *i* or *j* is\n greater than "len(s)", use "len(s)". If *i* is omitted or "None",\n use "0". If *j* is omitted or "None", use "len(s)". If *i* is\n greater than or equal to *j*, the slice is empty.\n\n5. The slice of *s* from *i* to *j* with step *k* is defined as the\n sequence of items with index "x = i + n*k" such that "0 <= n <\n (j-i)/k". In other words, the indices are "i", "i+k", "i+2*k",\n "i+3*k" and so on, stopping when *j* is reached (but never\n including *j*). If *i* or *j* is greater than "len(s)", use\n "len(s)". If *i* or *j* are omitted or "None", they become "end"\n values (which end depends on the sign of *k*). Note, *k* cannot be\n zero. If *k* is "None", it is treated like "1".\n\n6. Concatenating immutable sequences always results in a new\n object. This means that building up a sequence by repeated\n concatenation will have a quadratic runtime cost in the total\n sequence length. To get a linear runtime cost, you must switch to\n one of the alternatives below:\n\n * if concatenating "str" objects, you can build a list and use\n "str.join()" at the end or else write to an "io.StringIO"\n instance and retrieve its value when complete\n\n * if concatenating "bytes" objects, you can similarly use\n "bytes.join()" or "io.BytesIO", or you can do in-place\n concatenation with a "bytearray" object. "bytearray" objects are\n mutable and have an efficient overallocation mechanism\n\n * if concatenating "tuple" objects, extend a "list" instead\n\n * for other types, investigate the relevant class documentation\n\n7. Some sequence types (such as "range") only support item\n sequences that follow specific patterns, and hence don\'t support\n sequence concatenation or repetition.\n\n8. "index" raises "ValueError" when *x* is not found in *s*. When\n supported, the additional arguments to the index method allow\n efficient searching of subsections of the sequence. Passing the\n extra arguments is roughly equivalent to using "s[i:j].index(x)",\n only without copying any data and with the returned index being\n relative to the start of the sequence rather than the start of the\n slice.\n\n\nImmutable Sequence Types\n========================\n\nThe only operation that immutable sequence types generally implement\nthat is not also implemented by mutable sequence types is support for\nthe "hash()" built-in.\n\nThis support allows immutable sequences, such as "tuple" instances, to\nbe used as "dict" keys and stored in "set" and "frozenset" instances.\n\nAttempting to hash an immutable sequence that contains unhashable\nvalues will result in "TypeError".\n\n\nMutable Sequence Types\n======================\n\nThe operations in the following table are defined on mutable sequence\ntypes. The "collections.abc.MutableSequence" ABC is provided to make\nit easier to correctly implement these operations on custom sequence\ntypes.\n\nIn the table *s* is an instance of a mutable sequence type, *t* is any\niterable object and *x* is an arbitrary object that meets any type and\nvalue restrictions imposed by *s* (for example, "bytearray" only\naccepts integers that meet the value restriction "0 <= x <= 255").\n\n+--------------------------------+----------------------------------+-----------------------+\n| Operation | Result | Notes |\n+================================+==================================+=======================+\n| "s[i] = x" | item *i* of *s* is replaced by | |\n| | *x* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j] = t" | slice of *s* from *i* to *j* is | |\n| | replaced by the contents of the | |\n| | iterable *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j]" | same as "s[i:j] = []" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j:k] = t" | the elements of "s[i:j:k]" are | (1) |\n| | replaced by those of *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j:k]" | removes the elements of | |\n| | "s[i:j:k]" from the list | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.append(x)" | appends *x* to the end of the | |\n| | sequence (same as | |\n| | "s[len(s):len(s)] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.clear()" | removes all items from "s" (same | (5) |\n| | as "del s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.copy()" | creates a shallow copy of "s" | (5) |\n| | (same as "s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.extend(t)" or "s += t" | extends *s* with the contents of | |\n| | *t* (for the most part the same | |\n| | as "s[len(s):len(s)] = t") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s *= n" | updates *s* with its contents | (6) |\n| | repeated *n* times | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.insert(i, x)" | inserts *x* into *s* at the | |\n| | index given by *i* (same as | |\n| | "s[i:i] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.pop([i])" | retrieves the item at *i* and | (2) |\n| | also removes it from *s* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.remove(x)" | remove the first item from *s* | (3) |\n| | where "s[i] == x" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.reverse()" | reverses the items of *s* in | (4) |\n| | place | |\n+--------------------------------+----------------------------------+-----------------------+\n\nNotes:\n\n1. *t* must have the same length as the slice it is replacing.\n\n2. The optional argument *i* defaults to "-1", so that by default\n the last item is removed and returned.\n\n3. "remove" raises "ValueError" when *x* is not found in *s*.\n\n4. The "reverse()" method modifies the sequence in place for\n economy of space when reversing a large sequence. To remind users\n that it operates by side effect, it does not return the reversed\n sequence.\n\n5. "clear()" and "copy()" are included for consistency with the\n interfaces of mutable containers that don\'t support slicing\n operations (such as "dict" and "set")\n\n New in version 3.3: "clear()" and "copy()" methods.\n\n6. The value *n* is an integer, or an object implementing\n "__index__()". Zero and negative values of *n* clear the sequence.\n Items in the sequence are not copied; they are referenced multiple\n times, as explained for "s * n" under *Common Sequence Operations*.\n\n\nLists\n=====\n\nLists are mutable sequences, typically used to store collections of\nhomogeneous items (where the precise degree of similarity will vary by\napplication).\n\nclass class list([iterable])\n\n Lists may be constructed in several ways:\n\n * Using a pair of square brackets to denote the empty list: "[]"\n\n * Using square brackets, separating items with commas: "[a]",\n "[a, b, c]"\n\n * Using a list comprehension: "[x for x in iterable]"\n\n * Using the type constructor: "list()" or "list(iterable)"\n\n The constructor builds a list whose items are the same and in the\n same order as *iterable*\'s items. *iterable* may be either a\n sequence, a container that supports iteration, or an iterator\n object. If *iterable* is already a list, a copy is made and\n returned, similar to "iterable[:]". For example, "list(\'abc\')"\n returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" returns "[1, 2,\n 3]". If no argument is given, the constructor creates a new empty\n list, "[]".\n\n Many other operations also produce lists, including the "sorted()"\n built-in.\n\n Lists implement all of the *common* and *mutable* sequence\n operations. Lists also provide the following additional method:\n\n sort(*, key=None, reverse=None)\n\n This method sorts the list in place, using only "<" comparisons\n between items. Exceptions are not suppressed - if any comparison\n operations fail, the entire sort operation will fail (and the\n list will likely be left in a partially modified state).\n\n "sort()" accepts two arguments that can only be passed by\n keyword (*keyword-only arguments*):\n\n *key* specifies a function of one argument that is used to\n extract a comparison key from each list element (for example,\n "key=str.lower"). The key corresponding to each item in the list\n is calculated once and then used for the entire sorting process.\n The default value of "None" means that list items are sorted\n directly without calculating a separate key value.\n\n The "functools.cmp_to_key()" utility is available to convert a\n 2.x style *cmp* function to a *key* function.\n\n *reverse* is a boolean value. If set to "True", then the list\n elements are sorted as if each comparison were reversed.\n\n This method modifies the sequence in place for economy of space\n when sorting a large sequence. To remind users that it operates\n by side effect, it does not return the sorted sequence (use\n "sorted()" to explicitly request a new sorted list instance).\n\n The "sort()" method is guaranteed to be stable. A sort is\n stable if it guarantees not to change the relative order of\n elements that compare equal --- this is helpful for sorting in\n multiple passes (for example, sort by department, then by salary\n grade).\n\n **CPython implementation detail:** While a list is being sorted,\n the effect of attempting to mutate, or even inspect, the list is\n undefined. The C implementation of Python makes the list appear\n empty for the duration, and raises "ValueError" if it can detect\n that the list has been mutated during a sort.\n\n\nTuples\n======\n\nTuples are immutable sequences, typically used to store collections of\nheterogeneous data (such as the 2-tuples produced by the "enumerate()"\nbuilt-in). Tuples are also used for cases where an immutable sequence\nof homogeneous data is needed (such as allowing storage in a "set" or\n"dict" instance).\n\nclass class tuple([iterable])\n\n Tuples may be constructed in a number of ways:\n\n * Using a pair of parentheses to denote the empty tuple: "()"\n\n * Using a trailing comma for a singleton tuple: "a," or "(a,)"\n\n * Separating items with commas: "a, b, c" or "(a, b, c)"\n\n * Using the "tuple()" built-in: "tuple()" or "tuple(iterable)"\n\n The constructor builds a tuple whose items are the same and in the\n same order as *iterable*\'s items. *iterable* may be either a\n sequence, a container that supports iteration, or an iterator\n object. If *iterable* is already a tuple, it is returned\n unchanged. For example, "tuple(\'abc\')" returns "(\'a\', \'b\', \'c\')"\n and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument is\n given, the constructor creates a new empty tuple, "()".\n\n Note that it is actually the comma which makes a tuple, not the\n parentheses. The parentheses are optional, except in the empty\n tuple case, or when they are needed to avoid syntactic ambiguity.\n For example, "f(a, b, c)" is a function call with three arguments,\n while "f((a, b, c))" is a function call with a 3-tuple as the sole\n argument.\n\n Tuples implement all of the *common* sequence operations.\n\nFor heterogeneous collections of data where access by name is clearer\nthan access by index, "collections.namedtuple()" may be a more\nappropriate choice than a simple tuple object.\n\n\nRanges\n======\n\nThe "range" type represents an immutable sequence of numbers and is\ncommonly used for looping a specific number of times in "for" loops.\n\nclass class range(stop)\nclass class range(start, stop[, step])\n\n The arguments to the range constructor must be integers (either\n built-in "int" or any object that implements the "__index__"\n special method). If the *step* argument is omitted, it defaults to\n "1". If the *start* argument is omitted, it defaults to "0". If\n *step* is zero, "ValueError" is raised.\n\n For a positive *step*, the contents of a range "r" are determined\n by the formula "r[i] = start + step*i" where "i >= 0" and "r[i] <\n stop".\n\n For a negative *step*, the contents of the range are still\n determined by the formula "r[i] = start + step*i", but the\n constraints are "i >= 0" and "r[i] > stop".\n\n A range object will be empty if "r[0]" does not meet the value\n constraint. Ranges do support negative indices, but these are\n interpreted as indexing from the end of the sequence determined by\n the positive indices.\n\n Ranges containing absolute values larger than "sys.maxsize" are\n permitted but some features (such as "len()") may raise\n "OverflowError".\n\n Range examples:\n\n >>> list(range(10))\n [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n >>> list(range(1, 11))\n [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n >>> list(range(0, 30, 5))\n [0, 5, 10, 15, 20, 25]\n >>> list(range(0, 10, 3))\n [0, 3, 6, 9]\n >>> list(range(0, -10, -1))\n [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n >>> list(range(0))\n []\n >>> list(range(1, 0))\n []\n\n Ranges implement all of the *common* sequence operations except\n concatenation and repetition (due to the fact that range objects\n can only represent sequences that follow a strict pattern and\n repetition and concatenation will usually violate that pattern).\n\nThe advantage of the "range" type over a regular "list" or "tuple" is\nthat a "range" object will always take the same (small) amount of\nmemory, no matter the size of the range it represents (as it only\nstores the "start", "stop" and "step" values, calculating individual\nitems and subranges as needed).\n\nRange objects implement the "collections.abc.Sequence" ABC, and\nprovide features such as containment tests, element index lookup,\nslicing and support for negative indices (see *Sequence Types ---\nlist, tuple, range*):\n\n>>> r = range(0, 20, 2)\n>>> r\nrange(0, 20, 2)\n>>> 11 in r\nFalse\n>>> 10 in r\nTrue\n>>> r.index(10)\n5\n>>> r[5]\n10\n>>> r[:5]\nrange(0, 10, 2)\n>>> r[-1]\n18\n\nTesting range objects for equality with "==" and "!=" compares them as\nsequences. That is, two range objects are considered equal if they\nrepresent the same sequence of values. (Note that two range objects\nthat compare equal might have different "start", "stop" and "step"\nattributes, for example "range(0) == range(2, 1, 3)" or "range(0, 3,\n2) == range(0, 4, 2)".)\n\nChanged in version 3.2: Implement the Sequence ABC. Support slicing\nand negative indices. Test "int" objects for membership in constant\ntime instead of iterating through all items.\n\nChanged in version 3.3: Define \'==\' and \'!=\' to compare range objects\nbased on the sequence of values they define (instead of comparing\nbased on object identity).\n\nNew in version 3.3: The "start", "stop" and "step" attributes.\n', + 'typesseq-mutable': u'\nMutable Sequence Types\n**********************\n\nThe operations in the following table are defined on mutable sequence\ntypes. The "collections.abc.MutableSequence" ABC is provided to make\nit easier to correctly implement these operations on custom sequence\ntypes.\n\nIn the table *s* is an instance of a mutable sequence type, *t* is any\niterable object and *x* is an arbitrary object that meets any type and\nvalue restrictions imposed by *s* (for example, "bytearray" only\naccepts integers that meet the value restriction "0 <= x <= 255").\n\n+--------------------------------+----------------------------------+-----------------------+\n| Operation | Result | Notes |\n+================================+==================================+=======================+\n| "s[i] = x" | item *i* of *s* is replaced by | |\n| | *x* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j] = t" | slice of *s* from *i* to *j* is | |\n| | replaced by the contents of the | |\n| | iterable *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j]" | same as "s[i:j] = []" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s[i:j:k] = t" | the elements of "s[i:j:k]" are | (1) |\n| | replaced by those of *t* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "del s[i:j:k]" | removes the elements of | |\n| | "s[i:j:k]" from the list | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.append(x)" | appends *x* to the end of the | |\n| | sequence (same as | |\n| | "s[len(s):len(s)] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.clear()" | removes all items from "s" (same | (5) |\n| | as "del s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.copy()" | creates a shallow copy of "s" | (5) |\n| | (same as "s[:]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.extend(t)" or "s += t" | extends *s* with the contents of | |\n| | *t* (for the most part the same | |\n| | as "s[len(s):len(s)] = t") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s *= n" | updates *s* with its contents | (6) |\n| | repeated *n* times | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.insert(i, x)" | inserts *x* into *s* at the | |\n| | index given by *i* (same as | |\n| | "s[i:i] = [x]") | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.pop([i])" | retrieves the item at *i* and | (2) |\n| | also removes it from *s* | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.remove(x)" | remove the first item from *s* | (3) |\n| | where "s[i] == x" | |\n+--------------------------------+----------------------------------+-----------------------+\n| "s.reverse()" | reverses the items of *s* in | (4) |\n| | place | |\n+--------------------------------+----------------------------------+-----------------------+\n\nNotes:\n\n1. *t* must have the same length as the slice it is replacing.\n\n2. The optional argument *i* defaults to "-1", so that by default\n the last item is removed and returned.\n\n3. "remove" raises "ValueError" when *x* is not found in *s*.\n\n4. The "reverse()" method modifies the sequence in place for\n economy of space when reversing a large sequence. To remind users\n that it operates by side effect, it does not return the reversed\n sequence.\n\n5. "clear()" and "copy()" are included for consistency with the\n interfaces of mutable containers that don\'t support slicing\n operations (such as "dict" and "set")\n\n New in version 3.3: "clear()" and "copy()" methods.\n\n6. The value *n* is an integer, or an object implementing\n "__index__()". Zero and negative values of *n* clear the sequence.\n Items in the sequence are not copied; they are referenced multiple\n times, as explained for "s * n" under *Common Sequence Operations*.\n', + 'unary': u'\nUnary arithmetic and bitwise operations\n***************************************\n\nAll unary arithmetic and bitwise operations have the same priority:\n\n u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n\nThe unary "-" (minus) operator yields the negation of its numeric\nargument.\n\nThe unary "+" (plus) operator yields its numeric argument unchanged.\n\nThe unary "~" (invert) operator yields the bitwise inversion of its\ninteger argument. The bitwise inversion of "x" is defined as\n"-(x+1)". It only applies to integral numbers.\n\nIn all three cases, if the argument does not have the proper type, a\n"TypeError" exception is raised.\n', + 'while': u'\nThe "while" statement\n*********************\n\nThe "while" statement is used for repeated execution as long as an\nexpression is true:\n\n while_stmt ::= "while" expression ":" suite\n ["else" ":" suite]\n\nThis repeatedly tests the expression and, if it is true, executes the\nfirst suite; if the expression is false (which may be the first time\nit is tested) the suite of the "else" clause, if present, is executed\nand the loop terminates.\n\nA "break" statement executed in the first suite terminates the loop\nwithout executing the "else" clause\'s suite. A "continue" statement\nexecuted in the first suite skips the rest of the suite and goes back\nto testing the expression.\n', + 'with': u'\nThe "with" statement\n********************\n\nThe "with" statement is used to wrap the execution of a block with\nmethods defined by a context manager (see section *With Statement\nContext Managers*). This allows common "try"..."except"..."finally"\nusage patterns to be encapsulated for convenient reuse.\n\n with_stmt ::= "with" with_item ("," with_item)* ":" suite\n with_item ::= expression ["as" target]\n\nThe execution of the "with" statement with one "item" proceeds as\nfollows:\n\n1. The context expression (the expression given in the "with_item")\n is evaluated to obtain a context manager.\n\n2. The context manager\'s "__exit__()" is loaded for later use.\n\n3. The context manager\'s "__enter__()" method is invoked.\n\n4. If a target was included in the "with" statement, the return\n value from "__enter__()" is assigned to it.\n\n Note: The "with" statement guarantees that if the "__enter__()"\n method returns without an error, then "__exit__()" will always be\n called. Thus, if an error occurs during the assignment to the\n target list, it will be treated the same as an error occurring\n within the suite would be. See step 6 below.\n\n5. The suite is executed.\n\n6. The context manager\'s "__exit__()" method is invoked. If an\n exception caused the suite to be exited, its type, value, and\n traceback are passed as arguments to "__exit__()". Otherwise, three\n "None" arguments are supplied.\n\n If the suite was exited due to an exception, and the return value\n from the "__exit__()" method was false, the exception is reraised.\n If the return value was true, the exception is suppressed, and\n execution continues with the statement following the "with"\n statement.\n\n If the suite was exited for any reason other than an exception, the\n return value from "__exit__()" is ignored, and execution proceeds\n at the normal location for the kind of exit that was taken.\n\nWith more than one item, the context managers are processed as if\nmultiple "with" statements were nested:\n\n with A() as a, B() as b:\n suite\n\nis equivalent to\n\n with A() as a:\n with B() as b:\n suite\n\nChanged in version 3.1: Support for multiple context expressions.\n\nSee also: **PEP 0343** - The "with" statement\n\n The specification, background, and examples for the Python "with"\n statement.\n', + 'yield': u'\nThe "yield" statement\n*********************\n\n yield_stmt ::= yield_expression\n\nA "yield" statement is semantically equivalent to a *yield\nexpression*. The yield statement can be used to omit the parentheses\nthat would otherwise be required in the equivalent yield expression\nstatement. For example, the yield statements\n\n yield \n yield from \n\nare equivalent to the yield expression statements\n\n (yield )\n (yield from )\n\nYield expressions and statements are only used when defining a\n*generator* function, and are only used in the body of the generator\nfunction. Using yield in a function definition is sufficient to cause\nthat definition to create a generator function instead of a normal\nfunction.\n\nFor full details of "yield" semantics, refer to the *Yield\nexpressions* section.\n'} diff --git a/Misc/NEWS.d/3.4.7.rst b/Misc/NEWS.d/3.4.7.rst new file mode 100644 index 00000000000000..f84ac7d5cd95ff --- /dev/null +++ b/Misc/NEWS.d/3.4.7.rst @@ -0,0 +1,8 @@ +.. bpo: 30119 +.. date: 2017-07-26-21-50-13 +.. nonce: DZ6C_S +.. release date: 2017-08-09 +.. section: Library + +ftplib.FTP.putline() now throws ValueError on commands that contains CR or +LF. Patch by Dong-hee Na. diff --git a/Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst b/Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst deleted file mode 100644 index a37d37038424c6..00000000000000 --- a/Misc/NEWS.d/next/Library/2017-07-26-21-50-13.bpo-30119.DZ6C_S.rst +++ /dev/null @@ -1,2 +0,0 @@ -ftplib.FTP.putline() now throws ValueError on commands that contains CR or -LF. Patch by Dong-hee Na. From 7dc38385ce78c5c04637531c4325a83b57fbeb3a Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Wed, 9 Aug 2017 00:08:33 -0700 Subject: [PATCH 20/24] Version bump for 3.4.7 final. --- Include/patchlevel.h | 6 +++--- README | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Include/patchlevel.h b/Include/patchlevel.h index 02c8f95cf47feb..44a6c71d07f32c 100644 --- a/Include/patchlevel.h +++ b/Include/patchlevel.h @@ -19,11 +19,11 @@ #define PY_MAJOR_VERSION 3 #define PY_MINOR_VERSION 4 #define PY_MICRO_VERSION 7 -#define PY_RELEASE_LEVEL PY_RELEASE_LEVEL_GAMMA -#define PY_RELEASE_SERIAL 1 +#define PY_RELEASE_LEVEL PY_RELEASE_LEVEL_FINAL +#define PY_RELEASE_SERIAL 0 /* Version as a string */ -#define PY_VERSION "3.4.7rc1+" +#define PY_VERSION "3.4.7" /*--end constants--*/ /* Version as a single 4-byte hex number, e.g. 0x010502B2 == 1.5.2b2. diff --git a/README b/README index cd9983422b427c..d1f6a4d16033ed 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ -This is Python version 3.4.7 release candidate 1 -================================================ +This is Python version 3.4.7 +============================ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017 Python Software Foundation. All rights From ed51967c7352c0cfca08d2efb4c6e7c54d147374 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Wed, 9 Aug 2017 00:36:14 -0700 Subject: [PATCH 21/24] Post-release bump for 3.4.7 final. --- Include/patchlevel.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Include/patchlevel.h b/Include/patchlevel.h index 44a6c71d07f32c..24a50fb25767ac 100644 --- a/Include/patchlevel.h +++ b/Include/patchlevel.h @@ -23,7 +23,7 @@ #define PY_RELEASE_SERIAL 0 /* Version as a string */ -#define PY_VERSION "3.4.7" +#define PY_VERSION "3.4.7+" /*--end constants--*/ /* Version as a single 4-byte hex number, e.g. 0x010502B2 == 1.5.2b2. From d0e61bded5256e775e470e2c0da22367a1a81970 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 16 Aug 2017 18:05:57 +0200 Subject: [PATCH 22/24] bpo-29169: Update zlib to 1.2.11 (#3107) Python 3.4 backport: convert the Misc/NEWS entry using blurb. (cherry picked from commit 34e7e2ecb1741850190e78f42875480693d3537b) --- .../2017-08-16-17-34-02.bpo-29169.GRXsSt.rst | 1 + Modules/zlib/ChangeLog | 55 +- Modules/zlib/Makefile.in | 232 +++-- Modules/zlib/README | 6 +- Modules/zlib/adler32.c | 21 +- Modules/zlib/compress.c | 42 +- Modules/zlib/configure | 134 ++- Modules/zlib/crc32.c | 41 +- Modules/zlib/deflate.c | 802 +++++++++++------- Modules/zlib/deflate.h | 35 +- Modules/zlib/gzguts.h | 23 +- Modules/zlib/gzlib.c | 31 +- Modules/zlib/gzread.c | 156 ++-- Modules/zlib/gzwrite.c | 332 +++++--- Modules/zlib/infback.c | 4 +- Modules/zlib/inffast.c | 85 +- Modules/zlib/inflate.c | 123 ++- Modules/zlib/inflate.h | 11 +- Modules/zlib/inftrees.c | 26 +- Modules/zlib/trees.c | 99 +-- Modules/zlib/uncompr.c | 98 ++- Modules/zlib/zconf.h | 41 +- Modules/zlib/zconf.h.cmakein | 41 +- Modules/zlib/zconf.h.in | 41 +- Modules/zlib/zlib.3 | 72 +- Modules/zlib/zlib.h | 452 ++++++---- Modules/zlib/zlib.map | 177 ++-- Modules/zlib/zutil.c | 49 +- Modules/zlib/zutil.h | 52 +- 29 files changed, 2106 insertions(+), 1176 deletions(-) create mode 100644 Misc/NEWS.d/next/Security/2017-08-16-17-34-02.bpo-29169.GRXsSt.rst diff --git a/Misc/NEWS.d/next/Security/2017-08-16-17-34-02.bpo-29169.GRXsSt.rst b/Misc/NEWS.d/next/Security/2017-08-16-17-34-02.bpo-29169.GRXsSt.rst new file mode 100644 index 00000000000000..dab5963a09791a --- /dev/null +++ b/Misc/NEWS.d/next/Security/2017-08-16-17-34-02.bpo-29169.GRXsSt.rst @@ -0,0 +1 @@ +Update zlib from 1.2.8 to 1.2.11 to get security fixes. diff --git a/Modules/zlib/ChangeLog b/Modules/zlib/ChangeLog index f22aabaef53422..30199a65a03daa 100644 --- a/Modules/zlib/ChangeLog +++ b/Modules/zlib/ChangeLog @@ -1,10 +1,53 @@ ChangeLog file for zlib +Changes in 1.2.11 (15 Jan 2017) +- Fix deflate stored bug when pulling last block from window +- Permit immediate deflateParams changes before any deflate input + +Changes in 1.2.10 (2 Jan 2017) +- Avoid warnings on snprintf() return value +- Fix bug in deflate_stored() for zero-length input +- Fix bug in gzwrite.c that produced corrupt gzip files +- Remove files to be installed before copying them in Makefile.in +- Add warnings when compiling with assembler code + +Changes in 1.2.9 (31 Dec 2016) +- Fix contrib/minizip to permit unzipping with desktop API [Zouzou] +- Improve contrib/blast to return unused bytes +- Assure that gzoffset() is correct when appending +- Improve compress() and uncompress() to support large lengths +- Fix bug in test/example.c where error code not saved +- Remedy Coverity warning [Randers-Pehrson] +- Improve speed of gzprintf() in transparent mode +- Fix inflateInit2() bug when windowBits is 16 or 32 +- Change DEBUG macro to ZLIB_DEBUG +- Avoid uninitialized access by gzclose_w() +- Allow building zlib outside of the source directory +- Fix bug that accepted invalid zlib header when windowBits is zero +- Fix gzseek() problem on MinGW due to buggy _lseeki64 there +- Loop on write() calls in gzwrite.c in case of non-blocking I/O +- Add --warn (-w) option to ./configure for more compiler warnings +- Reject a window size of 256 bytes if not using the zlib wrapper +- Fix bug when level 0 used with Z_HUFFMAN or Z_RLE +- Add --debug (-d) option to ./configure to define ZLIB_DEBUG +- Fix bugs in creating a very large gzip header +- Add uncompress2() function, which returns the input size used +- Assure that deflateParams() will not switch functions mid-block +- Dramatically speed up deflation for level 0 (storing) +- Add gzfread(), duplicating the interface of fread() +- Add gzfwrite(), duplicating the interface of fwrite() +- Add deflateGetDictionary() function +- Use snprintf() for later versions of Microsoft C +- Fix *Init macros to use z_ prefix when requested +- Replace as400 with os400 for OS/400 support [Monnerat] +- Add crc32_z() and adler32_z() functions with size_t lengths +- Update Visual Studio project files [AraHaan] + Changes in 1.2.8 (28 Apr 2013) - Update contrib/minizip/iowin32.c for Windows RT [Vollant] - Do not force Z_CONST for C++ -- Clean up contrib/vstudio [Ro] +- Clean up contrib/vstudio [Roß] - Correct spelling error in zlib.h - Fix mixed line endings in contrib/vstudio @@ -34,7 +77,7 @@ Changes in 1.2.7.1 (24 Mar 2013) - Clean up the usage of z_const and respect const usage within zlib - Clean up examples/gzlog.[ch] comparisons of different types - Avoid shift equal to bits in type (caused endless loop) -- Fix unintialized value bug in gzputc() introduced by const patches +- Fix uninitialized value bug in gzputc() introduced by const patches - Fix memory allocation error in examples/zran.c [Nor] - Fix bug where gzopen(), gzclose() would write an empty file - Fix bug in gzclose() when gzwrite() runs out of memory @@ -194,7 +237,7 @@ Changes in 1.2.5.2 (17 Dec 2011) - Add a transparent write mode to gzopen() when 'T' is in the mode - Update python link in zlib man page - Get inffixed.h and MAKEFIXED result to match -- Add a ./config --solo option to make zlib subset with no libary use +- Add a ./config --solo option to make zlib subset with no library use - Add undocumented inflateResetKeep() function for CAB file decoding - Add --cover option to ./configure for gcc coverage testing - Add #define ZLIB_CONST option to use const in the z_stream interface @@ -564,7 +607,7 @@ Changes in 1.2.3.1 (16 August 2006) - Update make_vms.com [Zinser] - Use -fPIC for shared build in configure [Teredesai, Nicholson] - Use only major version number for libz.so on IRIX and OSF1 [Reinholdtsen] -- Use fdopen() (not _fdopen()) for Interix in zutil.h [Bck] +- Use fdopen() (not _fdopen()) for Interix in zutil.h [Bäck] - Add some FAQ entries about the contrib directory - Update the MVS question in the FAQ - Avoid extraneous reads after EOF in gzio.c [Brown] @@ -1178,7 +1221,7 @@ Changes in 1.0.6 (19 Jan 1998) 386 asm code replacing longest_match(). contrib/iostream/ by Kevin Ruland A C++ I/O streams interface to the zlib gz* functions - contrib/iostream2/ by Tyge Lvset + contrib/iostream2/ by Tyge Løvset Another C++ I/O streams interface contrib/untgz/ by "Pedro A. Aranda Guti\irrez" A very simple tar.gz file extractor using zlib @@ -1267,7 +1310,7 @@ Changes in 1.0.1 (20 May 96) [1.0 skipped to avoid confusion] - fix array overlay in deflate.c which sometimes caused bad compressed data - fix inflate bug with empty stored block - fix MSDOS medium model which was broken in 0.99 -- fix deflateParams() which could generated bad compressed data. +- fix deflateParams() which could generate bad compressed data. - Bytef is define'd instead of typedef'ed (work around Borland bug) - added an INDEX file - new makefiles for DJGPP (Makefile.dj2), 32-bit Borland (Makefile.b32), diff --git a/Modules/zlib/Makefile.in b/Modules/zlib/Makefile.in index c61aa3008d441f..1852192546a1ca 100644 --- a/Modules/zlib/Makefile.in +++ b/Modules/zlib/Makefile.in @@ -1,5 +1,5 @@ # Makefile for zlib -# Copyright (C) 1995-2013 Jean-loup Gailly, Mark Adler +# Copyright (C) 1995-2016 Jean-loup Gailly, Mark Adler # For conditions of distribution and use, see copyright notice in zlib.h # To compile and test, type: @@ -20,7 +20,7 @@ CC=cc CFLAGS=-O #CFLAGS=-O -DMAX_WBITS=14 -DMAX_MEM_LEVEL=7 -#CFLAGS=-g -DDEBUG +#CFLAGS=-g -DZLIB_DEBUG #CFLAGS=-O3 -Wall -Wwrite-strings -Wpointer-arith -Wconversion \ # -Wstrict-prototypes -Wmissing-prototypes @@ -32,7 +32,7 @@ CPP=$(CC) -E STATICLIB=libz.a SHAREDLIB=libz.so -SHAREDLIBV=libz.so.1.2.8 +SHAREDLIBV=libz.so.1.2.10 SHAREDLIBM=libz.so.1 LIBS=$(STATICLIB) $(SHAREDLIBV) @@ -53,6 +53,9 @@ includedir = ${prefix}/include mandir = ${prefix}/share/man man3dir = ${mandir}/man3 pkgconfigdir = ${libdir}/pkgconfig +SRCDIR= +ZINC= +ZINCOUT=-I. OBJZ = adler32.o crc32.o deflate.o infback.o inffast.o inflate.o inftrees.o trees.o zutil.o OBJG = compress.o uncompr.o gzclose.o gzlib.o gzread.o gzwrite.o @@ -113,8 +116,8 @@ test64: all64 fi; \ rm -f $$TMP64 -infcover.o: test/infcover.c zlib.h zconf.h - $(CC) $(CFLAGS) -I. -c -o $@ test/infcover.c +infcover.o: $(SRCDIR)test/infcover.c $(SRCDIR)zlib.h zconf.h + $(CC) $(CFLAGS) $(ZINCOUT) -c -o $@ $(SRCDIR)test/infcover.c infcover: infcover.o libz.a $(CC) $(CFLAGS) -o $@ infcover.o libz.a @@ -140,24 +143,140 @@ match.lo: match.S mv _match.o match.lo rm -f _match.s -example.o: test/example.c zlib.h zconf.h - $(CC) $(CFLAGS) -I. -c -o $@ test/example.c +example.o: $(SRCDIR)test/example.c $(SRCDIR)zlib.h zconf.h + $(CC) $(CFLAGS) $(ZINCOUT) -c -o $@ $(SRCDIR)test/example.c -minigzip.o: test/minigzip.c zlib.h zconf.h - $(CC) $(CFLAGS) -I. -c -o $@ test/minigzip.c +minigzip.o: $(SRCDIR)test/minigzip.c $(SRCDIR)zlib.h zconf.h + $(CC) $(CFLAGS) $(ZINCOUT) -c -o $@ $(SRCDIR)test/minigzip.c -example64.o: test/example.c zlib.h zconf.h - $(CC) $(CFLAGS) -I. -D_FILE_OFFSET_BITS=64 -c -o $@ test/example.c +example64.o: $(SRCDIR)test/example.c $(SRCDIR)zlib.h zconf.h + $(CC) $(CFLAGS) $(ZINCOUT) -D_FILE_OFFSET_BITS=64 -c -o $@ $(SRCDIR)test/example.c -minigzip64.o: test/minigzip.c zlib.h zconf.h - $(CC) $(CFLAGS) -I. -D_FILE_OFFSET_BITS=64 -c -o $@ test/minigzip.c +minigzip64.o: $(SRCDIR)test/minigzip.c $(SRCDIR)zlib.h zconf.h + $(CC) $(CFLAGS) $(ZINCOUT) -D_FILE_OFFSET_BITS=64 -c -o $@ $(SRCDIR)test/minigzip.c -.SUFFIXES: .lo -.c.lo: +adler32.o: $(SRCDIR)adler32.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)adler32.c + +crc32.o: $(SRCDIR)crc32.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)crc32.c + +deflate.o: $(SRCDIR)deflate.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)deflate.c + +infback.o: $(SRCDIR)infback.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)infback.c + +inffast.o: $(SRCDIR)inffast.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)inffast.c + +inflate.o: $(SRCDIR)inflate.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)inflate.c + +inftrees.o: $(SRCDIR)inftrees.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)inftrees.c + +trees.o: $(SRCDIR)trees.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)trees.c + +zutil.o: $(SRCDIR)zutil.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)zutil.c + +compress.o: $(SRCDIR)compress.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)compress.c + +uncompr.o: $(SRCDIR)uncompr.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)uncompr.c + +gzclose.o: $(SRCDIR)gzclose.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)gzclose.c + +gzlib.o: $(SRCDIR)gzlib.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)gzlib.c + +gzread.o: $(SRCDIR)gzread.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)gzread.c + +gzwrite.o: $(SRCDIR)gzwrite.c + $(CC) $(CFLAGS) $(ZINC) -c -o $@ $(SRCDIR)gzwrite.c + + +adler32.lo: $(SRCDIR)adler32.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/adler32.o $(SRCDIR)adler32.c + -@mv objs/adler32.o $@ + +crc32.lo: $(SRCDIR)crc32.c -@mkdir objs 2>/dev/null || test -d objs - $(CC) $(SFLAGS) -DPIC -c -o objs/$*.o $< - -@mv objs/$*.o $@ + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/crc32.o $(SRCDIR)crc32.c + -@mv objs/crc32.o $@ + +deflate.lo: $(SRCDIR)deflate.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/deflate.o $(SRCDIR)deflate.c + -@mv objs/deflate.o $@ + +infback.lo: $(SRCDIR)infback.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/infback.o $(SRCDIR)infback.c + -@mv objs/infback.o $@ + +inffast.lo: $(SRCDIR)inffast.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/inffast.o $(SRCDIR)inffast.c + -@mv objs/inffast.o $@ + +inflate.lo: $(SRCDIR)inflate.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/inflate.o $(SRCDIR)inflate.c + -@mv objs/inflate.o $@ + +inftrees.lo: $(SRCDIR)inftrees.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/inftrees.o $(SRCDIR)inftrees.c + -@mv objs/inftrees.o $@ + +trees.lo: $(SRCDIR)trees.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/trees.o $(SRCDIR)trees.c + -@mv objs/trees.o $@ + +zutil.lo: $(SRCDIR)zutil.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/zutil.o $(SRCDIR)zutil.c + -@mv objs/zutil.o $@ + +compress.lo: $(SRCDIR)compress.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/compress.o $(SRCDIR)compress.c + -@mv objs/compress.o $@ + +uncompr.lo: $(SRCDIR)uncompr.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/uncompr.o $(SRCDIR)uncompr.c + -@mv objs/uncompr.o $@ + +gzclose.lo: $(SRCDIR)gzclose.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/gzclose.o $(SRCDIR)gzclose.c + -@mv objs/gzclose.o $@ + +gzlib.lo: $(SRCDIR)gzlib.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/gzlib.o $(SRCDIR)gzlib.c + -@mv objs/gzlib.o $@ + +gzread.lo: $(SRCDIR)gzread.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/gzread.o $(SRCDIR)gzread.c + -@mv objs/gzread.o $@ + +gzwrite.lo: $(SRCDIR)gzwrite.c + -@mkdir objs 2>/dev/null || test -d objs + $(CC) $(SFLAGS) $(ZINC) -DPIC -c -o objs/gzwrite.o $(SRCDIR)gzwrite.c + -@mv objs/gzwrite.o $@ + placebo $(SHAREDLIBV): $(PIC_OBJS) libz.a $(LDSHARED) $(SFLAGS) -o $@ $(PIC_OBJS) $(LDSHAREDLIBC) $(LDFLAGS) @@ -190,10 +309,12 @@ install-libs: $(LIBS) -@if [ ! -d $(DESTDIR)$(sharedlibdir) ]; then mkdir -p $(DESTDIR)$(sharedlibdir); fi -@if [ ! -d $(DESTDIR)$(man3dir) ]; then mkdir -p $(DESTDIR)$(man3dir); fi -@if [ ! -d $(DESTDIR)$(pkgconfigdir) ]; then mkdir -p $(DESTDIR)$(pkgconfigdir); fi + rm -f $(DESTDIR)$(libdir)/$(STATICLIB) cp $(STATICLIB) $(DESTDIR)$(libdir) chmod 644 $(DESTDIR)$(libdir)/$(STATICLIB) -@($(RANLIB) $(DESTDIR)$(libdir)/libz.a || true) >/dev/null 2>&1 -@if test -n "$(SHAREDLIBV)"; then \ + rm -f $(DESTDIR)$(sharedlibdir)/$(SHAREDLIBV); \ cp $(SHAREDLIBV) $(DESTDIR)$(sharedlibdir); \ echo "cp $(SHAREDLIBV) $(DESTDIR)$(sharedlibdir)"; \ chmod 755 $(DESTDIR)$(sharedlibdir)/$(SHAREDLIBV); \ @@ -203,8 +324,10 @@ install-libs: $(LIBS) ln -s $(SHAREDLIBV) $(DESTDIR)$(sharedlibdir)/$(SHAREDLIBM); \ ($(LDCONFIG) || true) >/dev/null 2>&1; \ fi - cp zlib.3 $(DESTDIR)$(man3dir) + rm -f $(DESTDIR)$(man3dir)/zlib.3 + cp $(SRCDIR)zlib.3 $(DESTDIR)$(man3dir) chmod 644 $(DESTDIR)$(man3dir)/zlib.3 + rm -f $(DESTDIR)$(pkgconfigdir)/zlib.pc cp zlib.pc $(DESTDIR)$(pkgconfigdir) chmod 644 $(DESTDIR)$(pkgconfigdir)/zlib.pc # The ranlib in install is needed on NeXTSTEP which checks file times @@ -212,7 +335,8 @@ install-libs: $(LIBS) install: install-libs -@if [ ! -d $(DESTDIR)$(includedir) ]; then mkdir -p $(DESTDIR)$(includedir); fi - cp zlib.h zconf.h $(DESTDIR)$(includedir) + rm -f $(DESTDIR)$(includedir)/zlib.h $(DESTDIR)$(includedir)/zconf.h + cp $(SRCDIR)zlib.h zconf.h $(DESTDIR)$(includedir) chmod 644 $(DESTDIR)$(includedir)/zlib.h $(DESTDIR)$(includedir)/zconf.h uninstall: @@ -226,18 +350,18 @@ uninstall: docs: zlib.3.pdf -zlib.3.pdf: zlib.3 - groff -mandoc -f H -T ps zlib.3 | ps2pdf - zlib.3.pdf +zlib.3.pdf: $(SRCDIR)zlib.3 + groff -mandoc -f H -T ps $(SRCDIR)zlib.3 | ps2pdf - $@ -zconf.h.cmakein: zconf.h.in +zconf.h.cmakein: $(SRCDIR)zconf.h.in -@ TEMPFILE=zconfh_$$; \ echo "/#define ZCONF_H/ a\\\\\n#cmakedefine Z_PREFIX\\\\\n#cmakedefine Z_HAVE_UNISTD_H\n" >> $$TEMPFILE &&\ - sed -f $$TEMPFILE zconf.h.in > zconf.h.cmakein &&\ - touch -r zconf.h.in zconf.h.cmakein &&\ + sed -f $$TEMPFILE $(SRCDIR)zconf.h.in > $@ &&\ + touch -r $(SRCDIR)zconf.h.in $@ &&\ rm $$TEMPFILE -zconf: zconf.h.in - cp -p zconf.h.in zconf.h +zconf: $(SRCDIR)zconf.h.in + cp -p $(SRCDIR)zconf.h.in zconf.h mostlyclean: clean clean: @@ -255,34 +379,32 @@ maintainer-clean: distclean distclean: clean zconf zconf.h.cmakein docs rm -f Makefile zlib.pc configure.log -@rm -f .DS_Store - -@printf 'all:\n\t-@echo "Please use ./configure first. Thank you."\n' > Makefile - -@printf '\ndistclean:\n\tmake -f Makefile.in distclean\n' >> Makefile - -@touch -r Makefile.in Makefile + @if [ -f Makefile.in ]; then \ + printf 'all:\n\t-@echo "Please use ./configure first. Thank you."\n' > Makefile ; \ + printf '\ndistclean:\n\tmake -f Makefile.in distclean\n' >> Makefile ; \ + touch -r $(SRCDIR)Makefile.in Makefile ; fi + @if [ ! -f zconf.h.in ]; then rm -f zconf.h zconf.h.cmakein ; fi + @if [ ! -f zlib.3 ]; then rm -f zlib.3.pdf ; fi tags: - etags *.[ch] - -depend: - makedepend -- $(CFLAGS) -- *.[ch] - -# DO NOT DELETE THIS LINE -- make depend depends on it. - -adler32.o zutil.o: zutil.h zlib.h zconf.h -gzclose.o gzlib.o gzread.o gzwrite.o: zlib.h zconf.h gzguts.h -compress.o example.o minigzip.o uncompr.o: zlib.h zconf.h -crc32.o: zutil.h zlib.h zconf.h crc32.h -deflate.o: deflate.h zutil.h zlib.h zconf.h -infback.o inflate.o: zutil.h zlib.h zconf.h inftrees.h inflate.h inffast.h inffixed.h -inffast.o: zutil.h zlib.h zconf.h inftrees.h inflate.h inffast.h -inftrees.o: zutil.h zlib.h zconf.h inftrees.h -trees.o: deflate.h zutil.h zlib.h zconf.h trees.h - -adler32.lo zutil.lo: zutil.h zlib.h zconf.h -gzclose.lo gzlib.lo gzread.lo gzwrite.lo: zlib.h zconf.h gzguts.h -compress.lo example.lo minigzip.lo uncompr.lo: zlib.h zconf.h -crc32.lo: zutil.h zlib.h zconf.h crc32.h -deflate.lo: deflate.h zutil.h zlib.h zconf.h -infback.lo inflate.lo: zutil.h zlib.h zconf.h inftrees.h inflate.h inffast.h inffixed.h -inffast.lo: zutil.h zlib.h zconf.h inftrees.h inflate.h inffast.h -inftrees.lo: zutil.h zlib.h zconf.h inftrees.h -trees.lo: deflate.h zutil.h zlib.h zconf.h trees.h + etags $(SRCDIR)*.[ch] + +adler32.o zutil.o: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h +gzclose.o gzlib.o gzread.o gzwrite.o: $(SRCDIR)zlib.h zconf.h $(SRCDIR)gzguts.h +compress.o example.o minigzip.o uncompr.o: $(SRCDIR)zlib.h zconf.h +crc32.o: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)crc32.h +deflate.o: $(SRCDIR)deflate.h $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h +infback.o inflate.o: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)inftrees.h $(SRCDIR)inflate.h $(SRCDIR)inffast.h $(SRCDIR)inffixed.h +inffast.o: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)inftrees.h $(SRCDIR)inflate.h $(SRCDIR)inffast.h +inftrees.o: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)inftrees.h +trees.o: $(SRCDIR)deflate.h $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)trees.h + +adler32.lo zutil.lo: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h +gzclose.lo gzlib.lo gzread.lo gzwrite.lo: $(SRCDIR)zlib.h zconf.h $(SRCDIR)gzguts.h +compress.lo example.lo minigzip.lo uncompr.lo: $(SRCDIR)zlib.h zconf.h +crc32.lo: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)crc32.h +deflate.lo: $(SRCDIR)deflate.h $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h +infback.lo inflate.lo: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)inftrees.h $(SRCDIR)inflate.h $(SRCDIR)inffast.h $(SRCDIR)inffixed.h +inffast.lo: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)inftrees.h $(SRCDIR)inflate.h $(SRCDIR)inffast.h +inftrees.lo: $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)inftrees.h +trees.lo: $(SRCDIR)deflate.h $(SRCDIR)zutil.h $(SRCDIR)zlib.h zconf.h $(SRCDIR)trees.h diff --git a/Modules/zlib/README b/Modules/zlib/README index 5ca9d127edaf7a..51106de4753292 100644 --- a/Modules/zlib/README +++ b/Modules/zlib/README @@ -1,6 +1,6 @@ ZLIB DATA COMPRESSION LIBRARY -zlib 1.2.8 is a general purpose data compression library. All the code is +zlib 1.2.11 is a general purpose data compression library. All the code is thread safe. The data format used by the zlib library is described by RFCs (Request for Comments) 1950 to 1952 in the files http://tools.ietf.org/html/rfc1950 (zlib format), rfc1951 (deflate format) and @@ -31,7 +31,7 @@ Mark Nelson wrote an article about zlib for the Jan. 1997 issue of Dr. Dobb's Journal; a copy of the article is available at http://marknelson.us/1997/01/01/zlib-engine/ . -The changes made in version 1.2.8 are documented in the file ChangeLog. +The changes made in version 1.2.11 are documented in the file ChangeLog. Unsupported third party contributions are provided in directory contrib/ . @@ -84,7 +84,7 @@ Acknowledgments: Copyright notice: - (C) 1995-2013 Jean-loup Gailly and Mark Adler + (C) 1995-2017 Jean-loup Gailly and Mark Adler This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Modules/zlib/adler32.c b/Modules/zlib/adler32.c index a868f073d8a0e3..d0be4380a39c9c 100644 --- a/Modules/zlib/adler32.c +++ b/Modules/zlib/adler32.c @@ -1,5 +1,5 @@ /* adler32.c -- compute the Adler-32 checksum of a data stream - * Copyright (C) 1995-2011 Mark Adler + * Copyright (C) 1995-2011, 2016 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -7,11 +7,9 @@ #include "zutil.h" -#define local static - local uLong adler32_combine_ OF((uLong adler1, uLong adler2, z_off64_t len2)); -#define BASE 65521 /* largest prime smaller than 65536 */ +#define BASE 65521U /* largest prime smaller than 65536 */ #define NMAX 5552 /* NMAX is the largest n such that 255n(n+1)/2 + (n+1)(BASE-1) <= 2^32-1 */ @@ -62,10 +60,10 @@ local uLong adler32_combine_ OF((uLong adler1, uLong adler2, z_off64_t len2)); #endif /* ========================================================================= */ -uLong ZEXPORT adler32(adler, buf, len) +uLong ZEXPORT adler32_z(adler, buf, len) uLong adler; const Bytef *buf; - uInt len; + z_size_t len; { unsigned long sum2; unsigned n; @@ -132,6 +130,15 @@ uLong ZEXPORT adler32(adler, buf, len) return adler | (sum2 << 16); } +/* ========================================================================= */ +uLong ZEXPORT adler32(adler, buf, len) + uLong adler; + const Bytef *buf; + uInt len; +{ + return adler32_z(adler, buf, len); +} + /* ========================================================================= */ local uLong adler32_combine_(adler1, adler2, len2) uLong adler1; @@ -156,7 +163,7 @@ local uLong adler32_combine_(adler1, adler2, len2) sum2 += ((adler1 >> 16) & 0xffff) + ((adler2 >> 16) & 0xffff) + BASE - rem; if (sum1 >= BASE) sum1 -= BASE; if (sum1 >= BASE) sum1 -= BASE; - if (sum2 >= (BASE << 1)) sum2 -= (BASE << 1); + if (sum2 >= ((unsigned long)BASE << 1)) sum2 -= ((unsigned long)BASE << 1); if (sum2 >= BASE) sum2 -= BASE; return sum1 | (sum2 << 16); } diff --git a/Modules/zlib/compress.c b/Modules/zlib/compress.c index 6e9762676a0d05..e2db404abf888b 100644 --- a/Modules/zlib/compress.c +++ b/Modules/zlib/compress.c @@ -1,5 +1,5 @@ /* compress.c -- compress a memory buffer - * Copyright (C) 1995-2005 Jean-loup Gailly. + * Copyright (C) 1995-2005, 2014, 2016 Jean-loup Gailly, Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -28,16 +28,11 @@ int ZEXPORT compress2 (dest, destLen, source, sourceLen, level) { z_stream stream; int err; + const uInt max = (uInt)-1; + uLong left; - stream.next_in = (z_const Bytef *)source; - stream.avail_in = (uInt)sourceLen; -#ifdef MAXSEG_64K - /* Check for source > 64K on 16-bit machine: */ - if ((uLong)stream.avail_in != sourceLen) return Z_BUF_ERROR; -#endif - stream.next_out = dest; - stream.avail_out = (uInt)*destLen; - if ((uLong)stream.avail_out != *destLen) return Z_BUF_ERROR; + left = *destLen; + *destLen = 0; stream.zalloc = (alloc_func)0; stream.zfree = (free_func)0; @@ -46,15 +41,26 @@ int ZEXPORT compress2 (dest, destLen, source, sourceLen, level) err = deflateInit(&stream, level); if (err != Z_OK) return err; - err = deflate(&stream, Z_FINISH); - if (err != Z_STREAM_END) { - deflateEnd(&stream); - return err == Z_OK ? Z_BUF_ERROR : err; - } - *destLen = stream.total_out; + stream.next_out = dest; + stream.avail_out = 0; + stream.next_in = (z_const Bytef *)source; + stream.avail_in = 0; + + do { + if (stream.avail_out == 0) { + stream.avail_out = left > (uLong)max ? max : (uInt)left; + left -= stream.avail_out; + } + if (stream.avail_in == 0) { + stream.avail_in = sourceLen > (uLong)max ? max : (uInt)sourceLen; + sourceLen -= stream.avail_in; + } + err = deflate(&stream, sourceLen ? Z_NO_FLUSH : Z_FINISH); + } while (err == Z_OK); - err = deflateEnd(&stream); - return err; + *destLen = stream.total_out; + deflateEnd(&stream); + return err == Z_STREAM_END ? Z_OK : err; } /* =========================================================================== diff --git a/Modules/zlib/configure b/Modules/zlib/configure index b77a8a8cf95f75..e974d1fd799fbc 100755 --- a/Modules/zlib/configure +++ b/Modules/zlib/configure @@ -18,6 +18,18 @@ echo -------------------- >> configure.log echo $0 $* >> configure.log date >> configure.log +# get source directory +SRCDIR=`dirname $0` +if test $SRCDIR = "."; then + ZINC="" + ZINCOUT="-I." + SRCDIR="" +else + ZINC='-include zconf.h' + ZINCOUT='-I. -I$(SRCDIR)' + SRCDIR="$SRCDIR/" +fi + # set command prefix for cross-compilation if [ -n "${CHOST}" ]; then uname="`echo "${CHOST}" | sed -e 's/^[^-]*-\([^-]*\)$/\1/' -e 's/^[^-]*-[^-]*-\([^-]*\)$/\1/' -e 's/^[^-]*-[^-]*-\([^-]*\)-.*$/\1/'`" @@ -28,10 +40,10 @@ fi STATICLIB=libz.a # extract zlib version numbers from zlib.h -VER=`sed -n -e '/VERSION "/s/.*"\(.*\)".*/\1/p' < zlib.h` -VER3=`sed -n -e '/VERSION "/s/.*"\([0-9]*\\.[0-9]*\\.[0-9]*\).*/\1/p' < zlib.h` -VER2=`sed -n -e '/VERSION "/s/.*"\([0-9]*\\.[0-9]*\)\\..*/\1/p' < zlib.h` -VER1=`sed -n -e '/VERSION "/s/.*"\([0-9]*\)\\..*/\1/p' < zlib.h` +VER=`sed -n -e '/VERSION "/s/.*"\(.*\)".*/\1/p' < ${SRCDIR}zlib.h` +VER3=`sed -n -e '/VERSION "/s/.*"\([0-9]*\\.[0-9]*\\.[0-9]*\).*/\1/p' < ${SRCDIR}zlib.h` +VER2=`sed -n -e '/VERSION "/s/.*"\([0-9]*\\.[0-9]*\)\\..*/\1/p' < ${SRCDIR}zlib.h` +VER1=`sed -n -e '/VERSION "/s/.*"\([0-9]*\)\\..*/\1/p' < ${SRCDIR}zlib.h` # establish commands for library building if "${CROSS_PREFIX}ar" --version >/dev/null 2>/dev/null || test $? -lt 126; then @@ -73,6 +85,8 @@ zprefix=0 zconst=0 build64=0 gcc=0 +warn=0 +debug=0 old_cc="$CC" old_cflags="$CFLAGS" OBJC='$(OBJZ) $(OBJG)' @@ -121,6 +135,8 @@ case "$1" in --sysconfdir=*) echo "ignored option: --sysconfdir" | tee -a configure.log; shift ;; --localstatedir=*) echo "ignored option: --localstatedir" | tee -a configure.log; shift ;; -c* | --const) zconst=1; shift ;; + -w* | --warn) warn=1; shift ;; + -d* | --debug) debug=1; shift ;; *) echo "unknown option: $1" | tee -a configure.log echo "$0 --help for help" | tee -a configure.log @@ -159,34 +175,42 @@ case "$cc" in esac case `$cc -v 2>&1` in *gcc*) gcc=1 ;; + *clang*) gcc=1 ;; esac show $cc -c $test.c if test "$gcc" -eq 1 && ($cc -c $test.c) >> configure.log 2>&1; then echo ... using gcc >> configure.log CC="$cc" - CFLAGS="${CFLAGS--O3} ${ARCHS}" + CFLAGS="${CFLAGS--O3}" SFLAGS="${CFLAGS--O3} -fPIC" - LDFLAGS="${LDFLAGS} ${ARCHS}" + if test "$ARCHS"; then + CFLAGS="${CFLAGS} ${ARCHS}" + LDFLAGS="${LDFLAGS} ${ARCHS}" + fi if test $build64 -eq 1; then CFLAGS="${CFLAGS} -m64" SFLAGS="${SFLAGS} -m64" fi - if test "${ZLIBGCCWARN}" = "YES"; then + if test "$warn" -eq 1; then if test "$zconst" -eq 1; then CFLAGS="${CFLAGS} -Wall -Wextra -Wcast-qual -pedantic -DZLIB_CONST" else CFLAGS="${CFLAGS} -Wall -Wextra -pedantic" fi fi + if test $debug -eq 1; then + CFLAGS="${CFLAGS} -DZLIB_DEBUG" + SFLAGS="${SFLAGS} -DZLIB_DEBUG" + fi if test -z "$uname"; then uname=`(uname -s || echo unknown) 2>/dev/null` fi case "$uname" in Linux* | linux* | GNU | GNU/* | solaris*) - LDSHARED=${LDSHARED-"$cc -shared -Wl,-soname,libz.so.1,--version-script,zlib.map"} ;; + LDSHARED=${LDSHARED-"$cc -shared -Wl,-soname,libz.so.1,--version-script,${SRCDIR}zlib.map"} ;; *BSD | *bsd* | DragonFly) - LDSHARED=${LDSHARED-"$cc -shared -Wl,-soname,libz.so.1,--version-script,zlib.map"} + LDSHARED=${LDSHARED-"$cc -shared -Wl,-soname,libz.so.1,--version-script,${SRCDIR}zlib.map"} LDCONFIG="ldconfig -m" ;; CYGWIN* | Cygwin* | cygwin* | OS/2*) EXE='.exe' ;; @@ -287,6 +311,9 @@ else esac fi fi + if test -n "$ZINC"; then + ZINC='-I- -I. -I$(SRCDIR)' + fi ;; SunOS\ 4*) SFLAGS=${CFLAGS-"-O2 -PIC"} CFLAGS=${CFLAGS-"-O2"} @@ -337,16 +364,16 @@ if ($CC -c $CFLAGS $test.c) 2>/dev/null; then } echo - using any output from compiler to indicate an error >> configure.log else -try() -{ - show $* - ( $* ) >> configure.log 2>&1 - ret=$? - if test $ret -ne 0; then - echo "(exit code "$ret")" >> configure.log - fi - return $ret -} + try() + { + show $* + ( $* ) >> configure.log 2>&1 + ret=$? + if test $ret -ne 0; then + echo "(exit code "$ret")" >> configure.log + fi + return $ret + } fi tryboth() @@ -422,6 +449,65 @@ esac echo >> configure.log +# check for size_t +cat > $test.c < +#include +size_t dummy = 0; +EOF +if try $CC -c $CFLAGS $test.c; then + echo "Checking for size_t... Yes." | tee -a configure.log + need_sizet=0 +else + echo "Checking for size_t... No." | tee -a configure.log + need_sizet=1 +fi + +echo >> configure.log + +# find the size_t integer type, if needed +if test $need_sizet -eq 1; then + cat > $test.c < $test.c < +int main(void) { + if (sizeof(void *) <= sizeof(int)) puts("int"); + else if (sizeof(void *) <= sizeof(long)) puts("long"); + else puts("z_longlong"); + return 0; +} +EOF + else + echo "Checking for long long... No." | tee -a configure.log + cat > $test.c < +int main(void) { + if (sizeof(void *) <= sizeof(int)) puts("int"); + else puts("long"); + return 0; +} +EOF + fi + if try $CC $CFLAGS -o $test $test.c; then + sizet=`./$test` + echo "Checking for a pointer-size integer type..." $sizet"." | tee -a configure.log + else + echo "Failed to find a pointer-size integer type." | tee -a configure.log + leave 1 + fi +fi + +if test $need_sizet -eq 1; then + CFLAGS="${CFLAGS} -DNO_SIZE_T=${sizet}" + SFLAGS="${SFLAGS} -DNO_SIZE_T=${sizet}" +fi + +echo >> configure.log + # check for large file support, and if none, check for fseeko() cat > $test.c < @@ -470,7 +556,7 @@ else fi # copy clean zconf.h for subsequent edits -cp -p zconf.h.in zconf.h +cp -p ${SRCDIR}zconf.h.in zconf.h echo >> configure.log @@ -764,6 +850,7 @@ echo STATICLIB = $STATICLIB >> configure.log echo TEST = $TEST >> configure.log echo VER = $VER >> configure.log echo Z_U4 = $Z_U4 >> configure.log +echo SRCDIR = $SRCDIR >> configure.log echo exec_prefix = $exec_prefix >> configure.log echo includedir = $includedir >> configure.log echo libdir = $libdir >> configure.log @@ -773,7 +860,7 @@ echo sharedlibdir = $sharedlibdir >> configure.log echo uname = $uname >> configure.log # udpate Makefile with the configure results -sed < Makefile.in " +sed < ${SRCDIR}Makefile.in " /^CC *=/s#=.*#=$CC# /^CFLAGS *=/s#=.*#=$CFLAGS# /^SFLAGS *=/s#=.*#=$SFLAGS# @@ -790,6 +877,9 @@ sed < Makefile.in " /^LDCONFIG *=/s#=.*#=$LDCONFIG# /^LDSHAREDLIBC *=/s#=.*#=$LDSHAREDLIBC# /^EXE *=/s#=.*#=$EXE# +/^SRCDIR *=/s#=.*#=$SRCDIR# +/^ZINC *=/s#=.*#=$ZINC# +/^ZINCOUT *=/s#=.*#=$ZINCOUT# /^prefix *=/s#=.*#=$prefix# /^exec_prefix *=/s#=.*#=$exec_prefix# /^libdir *=/s#=.*#=$libdir# @@ -803,7 +893,7 @@ sed < Makefile.in " " > Makefile # create zlib.pc with the configure results -sed < zlib.pc.in " +sed < ${SRCDIR}zlib.pc.in " /^CC *=/s#=.*#=$CC# /^CFLAGS *=/s#=.*#=$CFLAGS# /^CPP *=/s#=.*#=$CPP# diff --git a/Modules/zlib/crc32.c b/Modules/zlib/crc32.c index 979a7190a3ca44..9580440c0e6b67 100644 --- a/Modules/zlib/crc32.c +++ b/Modules/zlib/crc32.c @@ -1,5 +1,5 @@ /* crc32.c -- compute the CRC-32 of a data stream - * Copyright (C) 1995-2006, 2010, 2011, 2012 Mark Adler + * Copyright (C) 1995-2006, 2010, 2011, 2012, 2016 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h * * Thanks to Rodney Brown for his contribution of faster @@ -30,17 +30,15 @@ #include "zutil.h" /* for STDC and FAR definitions */ -#define local static - /* Definitions for doing the crc four data bytes at a time. */ #if !defined(NOBYFOUR) && defined(Z_U4) # define BYFOUR #endif #ifdef BYFOUR local unsigned long crc32_little OF((unsigned long, - const unsigned char FAR *, unsigned)); + const unsigned char FAR *, z_size_t)); local unsigned long crc32_big OF((unsigned long, - const unsigned char FAR *, unsigned)); + const unsigned char FAR *, z_size_t)); # define TBLS 8 #else # define TBLS 1 @@ -201,10 +199,10 @@ const z_crc_t FAR * ZEXPORT get_crc_table() #define DO8 DO1; DO1; DO1; DO1; DO1; DO1; DO1; DO1 /* ========================================================================= */ -unsigned long ZEXPORT crc32(crc, buf, len) +unsigned long ZEXPORT crc32_z(crc, buf, len) unsigned long crc; const unsigned char FAR *buf; - uInt len; + z_size_t len; { if (buf == Z_NULL) return 0UL; @@ -235,8 +233,29 @@ unsigned long ZEXPORT crc32(crc, buf, len) return crc ^ 0xffffffffUL; } +/* ========================================================================= */ +unsigned long ZEXPORT crc32(crc, buf, len) + unsigned long crc; + const unsigned char FAR *buf; + uInt len; +{ + return crc32_z(crc, buf, len); +} + #ifdef BYFOUR +/* + This BYFOUR code accesses the passed unsigned char * buffer with a 32-bit + integer pointer type. This violates the strict aliasing rule, where a + compiler can assume, for optimization purposes, that two pointers to + fundamentally different types won't ever point to the same memory. This can + manifest as a problem only if one of the pointers is written to. This code + only reads from those pointers. So long as this code remains isolated in + this compilation unit, there won't be a problem. For this reason, this code + should not be copied and pasted into a compilation unit in which other code + writes to the buffer that is passed to these routines. + */ + /* ========================================================================= */ #define DOLIT4 c ^= *buf4++; \ c = crc_table[3][c & 0xff] ^ crc_table[2][(c >> 8) & 0xff] ^ \ @@ -247,7 +266,7 @@ unsigned long ZEXPORT crc32(crc, buf, len) local unsigned long crc32_little(crc, buf, len) unsigned long crc; const unsigned char FAR *buf; - unsigned len; + z_size_t len; { register z_crc_t c; register const z_crc_t FAR *buf4; @@ -278,7 +297,7 @@ local unsigned long crc32_little(crc, buf, len) } /* ========================================================================= */ -#define DOBIG4 c ^= *++buf4; \ +#define DOBIG4 c ^= *buf4++; \ c = crc_table[4][c & 0xff] ^ crc_table[5][(c >> 8) & 0xff] ^ \ crc_table[6][(c >> 16) & 0xff] ^ crc_table[7][c >> 24] #define DOBIG32 DOBIG4; DOBIG4; DOBIG4; DOBIG4; DOBIG4; DOBIG4; DOBIG4; DOBIG4 @@ -287,7 +306,7 @@ local unsigned long crc32_little(crc, buf, len) local unsigned long crc32_big(crc, buf, len) unsigned long crc; const unsigned char FAR *buf; - unsigned len; + z_size_t len; { register z_crc_t c; register const z_crc_t FAR *buf4; @@ -300,7 +319,6 @@ local unsigned long crc32_big(crc, buf, len) } buf4 = (const z_crc_t FAR *)(const void FAR *)buf; - buf4--; while (len >= 32) { DOBIG32; len -= 32; @@ -309,7 +327,6 @@ local unsigned long crc32_big(crc, buf, len) DOBIG4; len -= 4; } - buf4++; buf = (const unsigned char FAR *)buf4; if (len) do { diff --git a/Modules/zlib/deflate.c b/Modules/zlib/deflate.c index 696957705b756b..1ec761448de926 100644 --- a/Modules/zlib/deflate.c +++ b/Modules/zlib/deflate.c @@ -1,5 +1,5 @@ /* deflate.c -- compress data using the deflation algorithm - * Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler + * Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -52,7 +52,7 @@ #include "deflate.h" const char deflate_copyright[] = - " deflate 1.2.8 Copyright 1995-2013 Jean-loup Gailly and Mark Adler "; + " deflate 1.2.11 Copyright 1995-2017 Jean-loup Gailly and Mark Adler "; /* If you use the zlib library in a product, an acknowledgment is welcome in the documentation of your product. If for some reason you cannot @@ -73,6 +73,8 @@ typedef enum { typedef block_state (*compress_func) OF((deflate_state *s, int flush)); /* Compression function. Returns the block state after the call. */ +local int deflateStateCheck OF((z_streamp strm)); +local void slide_hash OF((deflate_state *s)); local void fill_window OF((deflate_state *s)); local block_state deflate_stored OF((deflate_state *s, int flush)); local block_state deflate_fast OF((deflate_state *s, int flush)); @@ -84,15 +86,16 @@ local block_state deflate_huff OF((deflate_state *s, int flush)); local void lm_init OF((deflate_state *s)); local void putShortMSB OF((deflate_state *s, uInt b)); local void flush_pending OF((z_streamp strm)); -local int read_buf OF((z_streamp strm, Bytef *buf, unsigned size)); +local unsigned read_buf OF((z_streamp strm, Bytef *buf, unsigned size)); #ifdef ASMV +# pragma message("Assembler code may have bugs -- use at your own risk") void match_init OF((void)); /* asm code initialization */ uInt longest_match OF((deflate_state *s, IPos cur_match)); #else local uInt longest_match OF((deflate_state *s, IPos cur_match)); #endif -#ifdef DEBUG +#ifdef ZLIB_DEBUG local void check_match OF((deflate_state *s, IPos start, IPos match, int length)); #endif @@ -148,21 +151,14 @@ local const config configuration_table[10] = { * meaning. */ -#define EQUAL 0 -/* result of memcmp for equal strings */ - -#ifndef NO_DUMMY_DECL -struct static_tree_desc_s {int dummy;}; /* for buggy compilers */ -#endif - /* rank Z_BLOCK between Z_NO_FLUSH and Z_PARTIAL_FLUSH */ -#define RANK(f) (((f) << 1) - ((f) > 4 ? 9 : 0)) +#define RANK(f) (((f) * 2) - ((f) > 4 ? 9 : 0)) /* =========================================================================== * Update a hash value with the given input byte - * IN assertion: all calls to to UPDATE_HASH are made with consecutive - * input characters, so that a running hash key can be computed from the - * previous key instead of complete recalculation each time. + * IN assertion: all calls to UPDATE_HASH are made with consecutive input + * characters, so that a running hash key can be computed from the previous + * key instead of complete recalculation each time. */ #define UPDATE_HASH(s,h,c) (h = (((h)<hash_shift) ^ (c)) & s->hash_mask) @@ -173,9 +169,9 @@ struct static_tree_desc_s {int dummy;}; /* for buggy compilers */ * the previous length of the hash chain. * If this file is compiled with -DFASTEST, the compression level is forced * to 1, and no hash chains are maintained. - * IN assertion: all calls to to INSERT_STRING are made with consecutive - * input characters and the first MIN_MATCH bytes of str are valid - * (except for the last MIN_MATCH-1 bytes of the input file). + * IN assertion: all calls to INSERT_STRING are made with consecutive input + * characters and the first MIN_MATCH bytes of str are valid (except for + * the last MIN_MATCH-1 bytes of the input file). */ #ifdef FASTEST #define INSERT_STRING(s, str, match_head) \ @@ -197,6 +193,37 @@ struct static_tree_desc_s {int dummy;}; /* for buggy compilers */ s->head[s->hash_size-1] = NIL; \ zmemzero((Bytef *)s->head, (unsigned)(s->hash_size-1)*sizeof(*s->head)); +/* =========================================================================== + * Slide the hash table when sliding the window down (could be avoided with 32 + * bit values at the expense of memory usage). We slide even when level == 0 to + * keep the hash table consistent if we switch back to level > 0 later. + */ +local void slide_hash(s) + deflate_state *s; +{ + unsigned n, m; + Posf *p; + uInt wsize = s->w_size; + + n = s->hash_size; + p = &s->head[n]; + do { + m = *--p; + *p = (Pos)(m >= wsize ? m - wsize : NIL); + } while (--n); + n = wsize; +#ifndef FASTEST + p = &s->prev[n]; + do { + m = *--p; + *p = (Pos)(m >= wsize ? m - wsize : NIL); + /* If n is not on any hash chain, prev[n] is garbage but + * its value will never be used. + */ + } while (--n); +#endif +} + /* ========================================================================= */ int ZEXPORT deflateInit_(strm, level, version, stream_size) z_streamp strm; @@ -270,7 +297,7 @@ int ZEXPORT deflateInit2_(strm, level, method, windowBits, memLevel, strategy, #endif if (memLevel < 1 || memLevel > MAX_MEM_LEVEL || method != Z_DEFLATED || windowBits < 8 || windowBits > 15 || level < 0 || level > 9 || - strategy < 0 || strategy > Z_FIXED) { + strategy < 0 || strategy > Z_FIXED || (windowBits == 8 && wrap != 1)) { return Z_STREAM_ERROR; } if (windowBits == 8) windowBits = 9; /* until 256-byte window bug fixed */ @@ -278,14 +305,15 @@ int ZEXPORT deflateInit2_(strm, level, method, windowBits, memLevel, strategy, if (s == Z_NULL) return Z_MEM_ERROR; strm->state = (struct internal_state FAR *)s; s->strm = strm; + s->status = INIT_STATE; /* to pass state test in deflateReset() */ s->wrap = wrap; s->gzhead = Z_NULL; - s->w_bits = windowBits; + s->w_bits = (uInt)windowBits; s->w_size = 1 << s->w_bits; s->w_mask = s->w_size - 1; - s->hash_bits = memLevel + 7; + s->hash_bits = (uInt)memLevel + 7; s->hash_size = 1 << s->hash_bits; s->hash_mask = s->hash_size - 1; s->hash_shift = ((s->hash_bits+MIN_MATCH-1)/MIN_MATCH); @@ -319,6 +347,31 @@ int ZEXPORT deflateInit2_(strm, level, method, windowBits, memLevel, strategy, return deflateReset(strm); } +/* ========================================================================= + * Check for a valid deflate stream state. Return 0 if ok, 1 if not. + */ +local int deflateStateCheck (strm) + z_streamp strm; +{ + deflate_state *s; + if (strm == Z_NULL || + strm->zalloc == (alloc_func)0 || strm->zfree == (free_func)0) + return 1; + s = strm->state; + if (s == Z_NULL || s->strm != strm || (s->status != INIT_STATE && +#ifdef GZIP + s->status != GZIP_STATE && +#endif + s->status != EXTRA_STATE && + s->status != NAME_STATE && + s->status != COMMENT_STATE && + s->status != HCRC_STATE && + s->status != BUSY_STATE && + s->status != FINISH_STATE)) + return 1; + return 0; +} + /* ========================================================================= */ int ZEXPORT deflateSetDictionary (strm, dictionary, dictLength) z_streamp strm; @@ -331,7 +384,7 @@ int ZEXPORT deflateSetDictionary (strm, dictionary, dictLength) unsigned avail; z_const unsigned char *next; - if (strm == Z_NULL || strm->state == Z_NULL || dictionary == Z_NULL) + if (deflateStateCheck(strm) || dictionary == Z_NULL) return Z_STREAM_ERROR; s = strm->state; wrap = s->wrap; @@ -388,14 +441,35 @@ int ZEXPORT deflateSetDictionary (strm, dictionary, dictLength) return Z_OK; } +/* ========================================================================= */ +int ZEXPORT deflateGetDictionary (strm, dictionary, dictLength) + z_streamp strm; + Bytef *dictionary; + uInt *dictLength; +{ + deflate_state *s; + uInt len; + + if (deflateStateCheck(strm)) + return Z_STREAM_ERROR; + s = strm->state; + len = s->strstart + s->lookahead; + if (len > s->w_size) + len = s->w_size; + if (dictionary != Z_NULL && len) + zmemcpy(dictionary, s->window + s->strstart + s->lookahead - len, len); + if (dictLength != Z_NULL) + *dictLength = len; + return Z_OK; +} + /* ========================================================================= */ int ZEXPORT deflateResetKeep (strm) z_streamp strm; { deflate_state *s; - if (strm == Z_NULL || strm->state == Z_NULL || - strm->zalloc == (alloc_func)0 || strm->zfree == (free_func)0) { + if (deflateStateCheck(strm)) { return Z_STREAM_ERROR; } @@ -410,7 +484,11 @@ int ZEXPORT deflateResetKeep (strm) if (s->wrap < 0) { s->wrap = -s->wrap; /* was made negative by deflate(..., Z_FINISH); */ } - s->status = s->wrap ? INIT_STATE : BUSY_STATE; + s->status = +#ifdef GZIP + s->wrap == 2 ? GZIP_STATE : +#endif + s->wrap ? INIT_STATE : BUSY_STATE; strm->adler = #ifdef GZIP s->wrap == 2 ? crc32(0L, Z_NULL, 0) : @@ -440,8 +518,8 @@ int ZEXPORT deflateSetHeader (strm, head) z_streamp strm; gz_headerp head; { - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; - if (strm->state->wrap != 2) return Z_STREAM_ERROR; + if (deflateStateCheck(strm) || strm->state->wrap != 2) + return Z_STREAM_ERROR; strm->state->gzhead = head; return Z_OK; } @@ -452,7 +530,7 @@ int ZEXPORT deflatePending (strm, pending, bits) int *bits; z_streamp strm; { - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (deflateStateCheck(strm)) return Z_STREAM_ERROR; if (pending != Z_NULL) *pending = strm->state->pending; if (bits != Z_NULL) @@ -469,7 +547,7 @@ int ZEXPORT deflatePrime (strm, bits, value) deflate_state *s; int put; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (deflateStateCheck(strm)) return Z_STREAM_ERROR; s = strm->state; if ((Bytef *)(s->d_buf) < s->pending_out + ((Buf_size + 7) >> 3)) return Z_BUF_ERROR; @@ -494,9 +572,8 @@ int ZEXPORT deflateParams(strm, level, strategy) { deflate_state *s; compress_func func; - int err = Z_OK; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (deflateStateCheck(strm)) return Z_STREAM_ERROR; s = strm->state; #ifdef FASTEST @@ -510,13 +587,22 @@ int ZEXPORT deflateParams(strm, level, strategy) func = configuration_table[s->level].func; if ((strategy != s->strategy || func != configuration_table[level].func) && - strm->total_in != 0) { + s->high_water) { /* Flush the last buffer: */ - err = deflate(strm, Z_BLOCK); - if (err == Z_BUF_ERROR && s->pending == 0) - err = Z_OK; + int err = deflate(strm, Z_BLOCK); + if (err == Z_STREAM_ERROR) + return err; + if (strm->avail_out == 0) + return Z_BUF_ERROR; } if (s->level != level) { + if (s->level == 0 && s->matches != 0) { + if (s->matches == 1) + slide_hash(s); + else + CLEAR_HASH(s); + s->matches = 0; + } s->level = level; s->max_lazy_match = configuration_table[level].max_lazy; s->good_match = configuration_table[level].good_length; @@ -524,7 +610,7 @@ int ZEXPORT deflateParams(strm, level, strategy) s->max_chain_length = configuration_table[level].max_chain; } s->strategy = strategy; - return err; + return Z_OK; } /* ========================================================================= */ @@ -537,12 +623,12 @@ int ZEXPORT deflateTune(strm, good_length, max_lazy, nice_length, max_chain) { deflate_state *s; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (deflateStateCheck(strm)) return Z_STREAM_ERROR; s = strm->state; - s->good_match = good_length; - s->max_lazy_match = max_lazy; + s->good_match = (uInt)good_length; + s->max_lazy_match = (uInt)max_lazy; s->nice_match = nice_length; - s->max_chain_length = max_chain; + s->max_chain_length = (uInt)max_chain; return Z_OK; } @@ -569,14 +655,13 @@ uLong ZEXPORT deflateBound(strm, sourceLen) { deflate_state *s; uLong complen, wraplen; - Bytef *str; /* conservative upper bound for compressed data */ complen = sourceLen + ((sourceLen + 7) >> 3) + ((sourceLen + 63) >> 6) + 5; /* if can't get parameters, return conservative bound plus zlib wrapper */ - if (strm == Z_NULL || strm->state == Z_NULL) + if (deflateStateCheck(strm)) return complen + 6; /* compute wrapper length */ @@ -588,9 +673,11 @@ uLong ZEXPORT deflateBound(strm, sourceLen) case 1: /* zlib wrapper */ wraplen = 6 + (s->strstart ? 4 : 0); break; +#ifdef GZIP case 2: /* gzip wrapper */ wraplen = 18; if (s->gzhead != Z_NULL) { /* user-supplied gzip header */ + Bytef *str; if (s->gzhead->extra != Z_NULL) wraplen += 2 + s->gzhead->extra_len; str = s->gzhead->name; @@ -607,6 +694,7 @@ uLong ZEXPORT deflateBound(strm, sourceLen) wraplen += 2; } break; +#endif default: /* for compiler happiness */ wraplen = 6; } @@ -634,10 +722,10 @@ local void putShortMSB (s, b) } /* ========================================================================= - * Flush as much pending output as possible. All deflate() output goes - * through this function so some applications may wish to modify it - * to avoid allocating a large strm->next_out buffer and copying into it. - * (See also read_buf()). + * Flush as much pending output as possible. All deflate() output, except for + * some deflate_stored() output, goes through this function so some + * applications may wish to modify it to avoid allocating a large + * strm->next_out buffer and copying into it. (See also read_buf()). */ local void flush_pending(strm) z_streamp strm; @@ -654,13 +742,23 @@ local void flush_pending(strm) strm->next_out += len; s->pending_out += len; strm->total_out += len; - strm->avail_out -= len; - s->pending -= len; + strm->avail_out -= len; + s->pending -= len; if (s->pending == 0) { s->pending_out = s->pending_buf; } } +/* =========================================================================== + * Update the header CRC with the bytes s->pending_buf[beg..s->pending - 1]. + */ +#define HCRC_UPDATE(beg) \ + do { \ + if (s->gzhead->hcrc && s->pending > (beg)) \ + strm->adler = crc32(strm->adler, s->pending_buf + (beg), \ + s->pending - (beg)); \ + } while (0) + /* ========================================================================= */ int ZEXPORT deflate (strm, flush) z_streamp strm; @@ -669,230 +767,229 @@ int ZEXPORT deflate (strm, flush) int old_flush; /* value of flush param for previous deflate call */ deflate_state *s; - if (strm == Z_NULL || strm->state == Z_NULL || - flush > Z_BLOCK || flush < 0) { + if (deflateStateCheck(strm) || flush > Z_BLOCK || flush < 0) { return Z_STREAM_ERROR; } s = strm->state; if (strm->next_out == Z_NULL || - (strm->next_in == Z_NULL && strm->avail_in != 0) || + (strm->avail_in != 0 && strm->next_in == Z_NULL) || (s->status == FINISH_STATE && flush != Z_FINISH)) { ERR_RETURN(strm, Z_STREAM_ERROR); } if (strm->avail_out == 0) ERR_RETURN(strm, Z_BUF_ERROR); - s->strm = strm; /* just in case */ old_flush = s->last_flush; s->last_flush = flush; + /* Flush as much pending output as possible */ + if (s->pending != 0) { + flush_pending(strm); + if (strm->avail_out == 0) { + /* Since avail_out is 0, deflate will be called again with + * more output space, but possibly with both pending and + * avail_in equal to zero. There won't be anything to do, + * but this is not an error situation so make sure we + * return OK instead of BUF_ERROR at next call of deflate: + */ + s->last_flush = -1; + return Z_OK; + } + + /* Make sure there is something to do and avoid duplicate consecutive + * flushes. For repeated and useless calls with Z_FINISH, we keep + * returning Z_STREAM_END instead of Z_BUF_ERROR. + */ + } else if (strm->avail_in == 0 && RANK(flush) <= RANK(old_flush) && + flush != Z_FINISH) { + ERR_RETURN(strm, Z_BUF_ERROR); + } + + /* User must not provide more input after the first FINISH: */ + if (s->status == FINISH_STATE && strm->avail_in != 0) { + ERR_RETURN(strm, Z_BUF_ERROR); + } + /* Write the header */ if (s->status == INIT_STATE) { -#ifdef GZIP - if (s->wrap == 2) { - strm->adler = crc32(0L, Z_NULL, 0); - put_byte(s, 31); - put_byte(s, 139); - put_byte(s, 8); - if (s->gzhead == Z_NULL) { - put_byte(s, 0); - put_byte(s, 0); - put_byte(s, 0); - put_byte(s, 0); - put_byte(s, 0); - put_byte(s, s->level == 9 ? 2 : - (s->strategy >= Z_HUFFMAN_ONLY || s->level < 2 ? - 4 : 0)); - put_byte(s, OS_CODE); - s->status = BUSY_STATE; - } - else { - put_byte(s, (s->gzhead->text ? 1 : 0) + - (s->gzhead->hcrc ? 2 : 0) + - (s->gzhead->extra == Z_NULL ? 0 : 4) + - (s->gzhead->name == Z_NULL ? 0 : 8) + - (s->gzhead->comment == Z_NULL ? 0 : 16) - ); - put_byte(s, (Byte)(s->gzhead->time & 0xff)); - put_byte(s, (Byte)((s->gzhead->time >> 8) & 0xff)); - put_byte(s, (Byte)((s->gzhead->time >> 16) & 0xff)); - put_byte(s, (Byte)((s->gzhead->time >> 24) & 0xff)); - put_byte(s, s->level == 9 ? 2 : - (s->strategy >= Z_HUFFMAN_ONLY || s->level < 2 ? - 4 : 0)); - put_byte(s, s->gzhead->os & 0xff); - if (s->gzhead->extra != Z_NULL) { - put_byte(s, s->gzhead->extra_len & 0xff); - put_byte(s, (s->gzhead->extra_len >> 8) & 0xff); - } - if (s->gzhead->hcrc) - strm->adler = crc32(strm->adler, s->pending_buf, - s->pending); - s->gzindex = 0; - s->status = EXTRA_STATE; - } - } + /* zlib header */ + uInt header = (Z_DEFLATED + ((s->w_bits-8)<<4)) << 8; + uInt level_flags; + + if (s->strategy >= Z_HUFFMAN_ONLY || s->level < 2) + level_flags = 0; + else if (s->level < 6) + level_flags = 1; + else if (s->level == 6) + level_flags = 2; else -#endif - { - uInt header = (Z_DEFLATED + ((s->w_bits-8)<<4)) << 8; - uInt level_flags; - - if (s->strategy >= Z_HUFFMAN_ONLY || s->level < 2) - level_flags = 0; - else if (s->level < 6) - level_flags = 1; - else if (s->level == 6) - level_flags = 2; - else - level_flags = 3; - header |= (level_flags << 6); - if (s->strstart != 0) header |= PRESET_DICT; - header += 31 - (header % 31); + level_flags = 3; + header |= (level_flags << 6); + if (s->strstart != 0) header |= PRESET_DICT; + header += 31 - (header % 31); + + putShortMSB(s, header); + /* Save the adler32 of the preset dictionary: */ + if (s->strstart != 0) { + putShortMSB(s, (uInt)(strm->adler >> 16)); + putShortMSB(s, (uInt)(strm->adler & 0xffff)); + } + strm->adler = adler32(0L, Z_NULL, 0); + s->status = BUSY_STATE; + + /* Compression must start with an empty pending buffer */ + flush_pending(strm); + if (s->pending != 0) { + s->last_flush = -1; + return Z_OK; + } + } +#ifdef GZIP + if (s->status == GZIP_STATE) { + /* gzip header */ + strm->adler = crc32(0L, Z_NULL, 0); + put_byte(s, 31); + put_byte(s, 139); + put_byte(s, 8); + if (s->gzhead == Z_NULL) { + put_byte(s, 0); + put_byte(s, 0); + put_byte(s, 0); + put_byte(s, 0); + put_byte(s, 0); + put_byte(s, s->level == 9 ? 2 : + (s->strategy >= Z_HUFFMAN_ONLY || s->level < 2 ? + 4 : 0)); + put_byte(s, OS_CODE); s->status = BUSY_STATE; - putShortMSB(s, header); - /* Save the adler32 of the preset dictionary: */ - if (s->strstart != 0) { - putShortMSB(s, (uInt)(strm->adler >> 16)); - putShortMSB(s, (uInt)(strm->adler & 0xffff)); + /* Compression must start with an empty pending buffer */ + flush_pending(strm); + if (s->pending != 0) { + s->last_flush = -1; + return Z_OK; + } + } + else { + put_byte(s, (s->gzhead->text ? 1 : 0) + + (s->gzhead->hcrc ? 2 : 0) + + (s->gzhead->extra == Z_NULL ? 0 : 4) + + (s->gzhead->name == Z_NULL ? 0 : 8) + + (s->gzhead->comment == Z_NULL ? 0 : 16) + ); + put_byte(s, (Byte)(s->gzhead->time & 0xff)); + put_byte(s, (Byte)((s->gzhead->time >> 8) & 0xff)); + put_byte(s, (Byte)((s->gzhead->time >> 16) & 0xff)); + put_byte(s, (Byte)((s->gzhead->time >> 24) & 0xff)); + put_byte(s, s->level == 9 ? 2 : + (s->strategy >= Z_HUFFMAN_ONLY || s->level < 2 ? + 4 : 0)); + put_byte(s, s->gzhead->os & 0xff); + if (s->gzhead->extra != Z_NULL) { + put_byte(s, s->gzhead->extra_len & 0xff); + put_byte(s, (s->gzhead->extra_len >> 8) & 0xff); } - strm->adler = adler32(0L, Z_NULL, 0); + if (s->gzhead->hcrc) + strm->adler = crc32(strm->adler, s->pending_buf, + s->pending); + s->gzindex = 0; + s->status = EXTRA_STATE; } } -#ifdef GZIP if (s->status == EXTRA_STATE) { if (s->gzhead->extra != Z_NULL) { - uInt beg = s->pending; /* start of bytes to update crc */ - - while (s->gzindex < (s->gzhead->extra_len & 0xffff)) { - if (s->pending == s->pending_buf_size) { - if (s->gzhead->hcrc && s->pending > beg) - strm->adler = crc32(strm->adler, s->pending_buf + beg, - s->pending - beg); - flush_pending(strm); - beg = s->pending; - if (s->pending == s->pending_buf_size) - break; + ulg beg = s->pending; /* start of bytes to update crc */ + uInt left = (s->gzhead->extra_len & 0xffff) - s->gzindex; + while (s->pending + left > s->pending_buf_size) { + uInt copy = s->pending_buf_size - s->pending; + zmemcpy(s->pending_buf + s->pending, + s->gzhead->extra + s->gzindex, copy); + s->pending = s->pending_buf_size; + HCRC_UPDATE(beg); + s->gzindex += copy; + flush_pending(strm); + if (s->pending != 0) { + s->last_flush = -1; + return Z_OK; } - put_byte(s, s->gzhead->extra[s->gzindex]); - s->gzindex++; - } - if (s->gzhead->hcrc && s->pending > beg) - strm->adler = crc32(strm->adler, s->pending_buf + beg, - s->pending - beg); - if (s->gzindex == s->gzhead->extra_len) { - s->gzindex = 0; - s->status = NAME_STATE; + beg = 0; + left -= copy; } + zmemcpy(s->pending_buf + s->pending, + s->gzhead->extra + s->gzindex, left); + s->pending += left; + HCRC_UPDATE(beg); + s->gzindex = 0; } - else - s->status = NAME_STATE; + s->status = NAME_STATE; } if (s->status == NAME_STATE) { if (s->gzhead->name != Z_NULL) { - uInt beg = s->pending; /* start of bytes to update crc */ + ulg beg = s->pending; /* start of bytes to update crc */ int val; - do { if (s->pending == s->pending_buf_size) { - if (s->gzhead->hcrc && s->pending > beg) - strm->adler = crc32(strm->adler, s->pending_buf + beg, - s->pending - beg); + HCRC_UPDATE(beg); flush_pending(strm); - beg = s->pending; - if (s->pending == s->pending_buf_size) { - val = 1; - break; + if (s->pending != 0) { + s->last_flush = -1; + return Z_OK; } + beg = 0; } val = s->gzhead->name[s->gzindex++]; put_byte(s, val); } while (val != 0); - if (s->gzhead->hcrc && s->pending > beg) - strm->adler = crc32(strm->adler, s->pending_buf + beg, - s->pending - beg); - if (val == 0) { - s->gzindex = 0; - s->status = COMMENT_STATE; - } + HCRC_UPDATE(beg); + s->gzindex = 0; } - else - s->status = COMMENT_STATE; + s->status = COMMENT_STATE; } if (s->status == COMMENT_STATE) { if (s->gzhead->comment != Z_NULL) { - uInt beg = s->pending; /* start of bytes to update crc */ + ulg beg = s->pending; /* start of bytes to update crc */ int val; - do { if (s->pending == s->pending_buf_size) { - if (s->gzhead->hcrc && s->pending > beg) - strm->adler = crc32(strm->adler, s->pending_buf + beg, - s->pending - beg); + HCRC_UPDATE(beg); flush_pending(strm); - beg = s->pending; - if (s->pending == s->pending_buf_size) { - val = 1; - break; + if (s->pending != 0) { + s->last_flush = -1; + return Z_OK; } + beg = 0; } val = s->gzhead->comment[s->gzindex++]; put_byte(s, val); } while (val != 0); - if (s->gzhead->hcrc && s->pending > beg) - strm->adler = crc32(strm->adler, s->pending_buf + beg, - s->pending - beg); - if (val == 0) - s->status = HCRC_STATE; + HCRC_UPDATE(beg); } - else - s->status = HCRC_STATE; + s->status = HCRC_STATE; } if (s->status == HCRC_STATE) { if (s->gzhead->hcrc) { - if (s->pending + 2 > s->pending_buf_size) + if (s->pending + 2 > s->pending_buf_size) { flush_pending(strm); - if (s->pending + 2 <= s->pending_buf_size) { - put_byte(s, (Byte)(strm->adler & 0xff)); - put_byte(s, (Byte)((strm->adler >> 8) & 0xff)); - strm->adler = crc32(0L, Z_NULL, 0); - s->status = BUSY_STATE; + if (s->pending != 0) { + s->last_flush = -1; + return Z_OK; + } } + put_byte(s, (Byte)(strm->adler & 0xff)); + put_byte(s, (Byte)((strm->adler >> 8) & 0xff)); + strm->adler = crc32(0L, Z_NULL, 0); } - else - s->status = BUSY_STATE; - } -#endif + s->status = BUSY_STATE; - /* Flush as much pending output as possible */ - if (s->pending != 0) { + /* Compression must start with an empty pending buffer */ flush_pending(strm); - if (strm->avail_out == 0) { - /* Since avail_out is 0, deflate will be called again with - * more output space, but possibly with both pending and - * avail_in equal to zero. There won't be anything to do, - * but this is not an error situation so make sure we - * return OK instead of BUF_ERROR at next call of deflate: - */ + if (s->pending != 0) { s->last_flush = -1; return Z_OK; } - - /* Make sure there is something to do and avoid duplicate consecutive - * flushes. For repeated and useless calls with Z_FINISH, we keep - * returning Z_STREAM_END instead of Z_BUF_ERROR. - */ - } else if (strm->avail_in == 0 && RANK(flush) <= RANK(old_flush) && - flush != Z_FINISH) { - ERR_RETURN(strm, Z_BUF_ERROR); - } - - /* User must not provide more input after the first FINISH: */ - if (s->status == FINISH_STATE && strm->avail_in != 0) { - ERR_RETURN(strm, Z_BUF_ERROR); } +#endif /* Start a new block or continue the current one. */ @@ -900,9 +997,10 @@ int ZEXPORT deflate (strm, flush) (flush != Z_NO_FLUSH && s->status != FINISH_STATE)) { block_state bstate; - bstate = s->strategy == Z_HUFFMAN_ONLY ? deflate_huff(s, flush) : - (s->strategy == Z_RLE ? deflate_rle(s, flush) : - (*(configuration_table[s->level].func))(s, flush)); + bstate = s->level == 0 ? deflate_stored(s, flush) : + s->strategy == Z_HUFFMAN_ONLY ? deflate_huff(s, flush) : + s->strategy == Z_RLE ? deflate_rle(s, flush) : + (*(configuration_table[s->level].func))(s, flush); if (bstate == finish_started || bstate == finish_done) { s->status = FINISH_STATE; @@ -944,7 +1042,6 @@ int ZEXPORT deflate (strm, flush) } } } - Assert(strm->avail_out > 0, "bug2"); if (flush != Z_FINISH) return Z_OK; if (s->wrap <= 0) return Z_STREAM_END; @@ -981,18 +1078,9 @@ int ZEXPORT deflateEnd (strm) { int status; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (deflateStateCheck(strm)) return Z_STREAM_ERROR; status = strm->state->status; - if (status != INIT_STATE && - status != EXTRA_STATE && - status != NAME_STATE && - status != COMMENT_STATE && - status != HCRC_STATE && - status != BUSY_STATE && - status != FINISH_STATE) { - return Z_STREAM_ERROR; - } /* Deallocate in reverse order of allocations: */ TRY_FREE(strm, strm->state->pending_buf); @@ -1023,7 +1111,7 @@ int ZEXPORT deflateCopy (dest, source) ushf *overlay; - if (source == Z_NULL || dest == Z_NULL || source->state == Z_NULL) { + if (deflateStateCheck(source) || dest == Z_NULL) { return Z_STREAM_ERROR; } @@ -1073,7 +1161,7 @@ int ZEXPORT deflateCopy (dest, source) * allocating a large strm->next_in buffer and copying from it. * (See also flush_pending()). */ -local int read_buf(strm, buf, size) +local unsigned read_buf(strm, buf, size) z_streamp strm; Bytef *buf; unsigned size; @@ -1097,7 +1185,7 @@ local int read_buf(strm, buf, size) strm->next_in += len; strm->total_in += len; - return (int)len; + return len; } /* =========================================================================== @@ -1151,9 +1239,9 @@ local uInt longest_match(s, cur_match) { unsigned chain_length = s->max_chain_length;/* max hash chain length */ register Bytef *scan = s->window + s->strstart; /* current string */ - register Bytef *match; /* matched string */ + register Bytef *match; /* matched string */ register int len; /* length of current match */ - int best_len = s->prev_length; /* best match length so far */ + int best_len = (int)s->prev_length; /* best match length so far */ int nice_match = s->nice_match; /* stop if match long enough */ IPos limit = s->strstart > (IPos)MAX_DIST(s) ? s->strstart - (IPos)MAX_DIST(s) : NIL; @@ -1188,7 +1276,7 @@ local uInt longest_match(s, cur_match) /* Do not look for matches beyond the end of the input. This is necessary * to make deflate deterministic. */ - if ((uInt)nice_match > s->lookahead) nice_match = s->lookahead; + if ((uInt)nice_match > s->lookahead) nice_match = (int)s->lookahead; Assert((ulg)s->strstart <= s->window_size-MIN_LOOKAHEAD, "need lookahead"); @@ -1349,7 +1437,11 @@ local uInt longest_match(s, cur_match) #endif /* FASTEST */ -#ifdef DEBUG +#ifdef ZLIB_DEBUG + +#define EQUAL 0 +/* result of memcmp for equal strings */ + /* =========================================================================== * Check that the match at match_start is indeed a match. */ @@ -1375,7 +1467,7 @@ local void check_match(s, start, match, length) } #else # define check_match(s, start, match, length) -#endif /* DEBUG */ +#endif /* ZLIB_DEBUG */ /* =========================================================================== * Fill the window when the lookahead becomes insufficient. @@ -1390,8 +1482,7 @@ local void check_match(s, start, match, length) local void fill_window(s) deflate_state *s; { - register unsigned n, m; - register Posf *p; + unsigned n; unsigned more; /* Amount of free space at the end of the window. */ uInt wsize = s->w_size; @@ -1418,35 +1509,11 @@ local void fill_window(s) */ if (s->strstart >= wsize+MAX_DIST(s)) { - zmemcpy(s->window, s->window+wsize, (unsigned)wsize); + zmemcpy(s->window, s->window+wsize, (unsigned)wsize - more); s->match_start -= wsize; s->strstart -= wsize; /* we now have strstart >= MAX_DIST */ s->block_start -= (long) wsize; - - /* Slide the hash table (could be avoided with 32 bit values - at the expense of memory usage). We slide even when level == 0 - to keep the hash table consistent if we switch back to level > 0 - later. (Using level 0 permanently is not an optimal usage of - zlib, so we don't care about this pathological case.) - */ - n = s->hash_size; - p = &s->head[n]; - do { - m = *--p; - *p = (Pos)(m >= wsize ? m-wsize : NIL); - } while (--n); - - n = wsize; -#ifndef FASTEST - p = &s->prev[n]; - do { - m = *--p; - *p = (Pos)(m >= wsize ? m-wsize : NIL); - /* If n is not on any hash chain, prev[n] is garbage but - * its value will never be used. - */ - } while (--n); -#endif + slide_hash(s); more += wsize; } if (s->strm->avail_in == 0) break; @@ -1552,70 +1619,199 @@ local void fill_window(s) if (s->strm->avail_out == 0) return (last) ? finish_started : need_more; \ } +/* Maximum stored block length in deflate format (not including header). */ +#define MAX_STORED 65535 + +/* Minimum of a and b. */ +#define MIN(a, b) ((a) > (b) ? (b) : (a)) + /* =========================================================================== * Copy without compression as much as possible from the input stream, return * the current block state. - * This function does not insert new strings in the dictionary since - * uncompressible data is probably not useful. This function is used - * only for the level=0 compression option. - * NOTE: this function should be optimized to avoid extra copying from - * window to pending_buf. + * + * In case deflateParams() is used to later switch to a non-zero compression + * level, s->matches (otherwise unused when storing) keeps track of the number + * of hash table slides to perform. If s->matches is 1, then one hash table + * slide will be done when switching. If s->matches is 2, the maximum value + * allowed here, then the hash table will be cleared, since two or more slides + * is the same as a clear. + * + * deflate_stored() is written to minimize the number of times an input byte is + * copied. It is most efficient with large input and output buffers, which + * maximizes the opportunites to have a single copy from next_in to next_out. */ local block_state deflate_stored(s, flush) deflate_state *s; int flush; { - /* Stored blocks are limited to 0xffff bytes, pending_buf is limited - * to pending_buf_size, and each stored block has a 5 byte header: + /* Smallest worthy block size when not flushing or finishing. By default + * this is 32K. This can be as small as 507 bytes for memLevel == 1. For + * large input and output buffers, the stored block size will be larger. */ - ulg max_block_size = 0xffff; - ulg max_start; - - if (max_block_size > s->pending_buf_size - 5) { - max_block_size = s->pending_buf_size - 5; - } + unsigned min_block = MIN(s->pending_buf_size - 5, s->w_size); - /* Copy as much as possible from input to output: */ - for (;;) { - /* Fill the window as much as possible: */ - if (s->lookahead <= 1) { - - Assert(s->strstart < s->w_size+MAX_DIST(s) || - s->block_start >= (long)s->w_size, "slide too late"); + /* Copy as many min_block or larger stored blocks directly to next_out as + * possible. If flushing, copy the remaining available input to next_out as + * stored blocks, if there is enough space. + */ + unsigned len, left, have, last = 0; + unsigned used = s->strm->avail_in; + do { + /* Set len to the maximum size block that we can copy directly with the + * available input data and output space. Set left to how much of that + * would be copied from what's left in the window. + */ + len = MAX_STORED; /* maximum deflate stored block length */ + have = (s->bi_valid + 42) >> 3; /* number of header bytes */ + if (s->strm->avail_out < have) /* need room for header */ + break; + /* maximum stored block length that will fit in avail_out: */ + have = s->strm->avail_out - have; + left = s->strstart - s->block_start; /* bytes left in window */ + if (len > (ulg)left + s->strm->avail_in) + len = left + s->strm->avail_in; /* limit len to the input */ + if (len > have) + len = have; /* limit len to the output */ + + /* If the stored block would be less than min_block in length, or if + * unable to copy all of the available input when flushing, then try + * copying to the window and the pending buffer instead. Also don't + * write an empty block when flushing -- deflate() does that. + */ + if (len < min_block && ((len == 0 && flush != Z_FINISH) || + flush == Z_NO_FLUSH || + len != left + s->strm->avail_in)) + break; - fill_window(s); - if (s->lookahead == 0 && flush == Z_NO_FLUSH) return need_more; + /* Make a dummy stored block in pending to get the header bytes, + * including any pending bits. This also updates the debugging counts. + */ + last = flush == Z_FINISH && len == left + s->strm->avail_in ? 1 : 0; + _tr_stored_block(s, (char *)0, 0L, last); + + /* Replace the lengths in the dummy stored block with len. */ + s->pending_buf[s->pending - 4] = len; + s->pending_buf[s->pending - 3] = len >> 8; + s->pending_buf[s->pending - 2] = ~len; + s->pending_buf[s->pending - 1] = ~len >> 8; + + /* Write the stored block header bytes. */ + flush_pending(s->strm); + +#ifdef ZLIB_DEBUG + /* Update debugging counts for the data about to be copied. */ + s->compressed_len += len << 3; + s->bits_sent += len << 3; +#endif - if (s->lookahead == 0) break; /* flush the current block */ + /* Copy uncompressed bytes from the window to next_out. */ + if (left) { + if (left > len) + left = len; + zmemcpy(s->strm->next_out, s->window + s->block_start, left); + s->strm->next_out += left; + s->strm->avail_out -= left; + s->strm->total_out += left; + s->block_start += left; + len -= left; } - Assert(s->block_start >= 0L, "block gone"); - - s->strstart += s->lookahead; - s->lookahead = 0; - - /* Emit a stored block if pending_buf will be full: */ - max_start = s->block_start + max_block_size; - if (s->strstart == 0 || (ulg)s->strstart >= max_start) { - /* strstart == 0 is possible when wraparound on 16-bit machine */ - s->lookahead = (uInt)(s->strstart - max_start); - s->strstart = (uInt)max_start; - FLUSH_BLOCK(s, 0); + + /* Copy uncompressed bytes directly from next_in to next_out, updating + * the check value. + */ + if (len) { + read_buf(s->strm, s->strm->next_out, len); + s->strm->next_out += len; + s->strm->avail_out -= len; + s->strm->total_out += len; } - /* Flush if we may have to slide, otherwise block_start may become - * negative and the data will be gone: + } while (last == 0); + + /* Update the sliding window with the last s->w_size bytes of the copied + * data, or append all of the copied data to the existing window if less + * than s->w_size bytes were copied. Also update the number of bytes to + * insert in the hash tables, in the event that deflateParams() switches to + * a non-zero compression level. + */ + used -= s->strm->avail_in; /* number of input bytes directly copied */ + if (used) { + /* If any input was used, then no unused input remains in the window, + * therefore s->block_start == s->strstart. */ - if (s->strstart - (uInt)s->block_start >= MAX_DIST(s)) { - FLUSH_BLOCK(s, 0); + if (used >= s->w_size) { /* supplant the previous history */ + s->matches = 2; /* clear hash */ + zmemcpy(s->window, s->strm->next_in - s->w_size, s->w_size); + s->strstart = s->w_size; } + else { + if (s->window_size - s->strstart <= used) { + /* Slide the window down. */ + s->strstart -= s->w_size; + zmemcpy(s->window, s->window + s->w_size, s->strstart); + if (s->matches < 2) + s->matches++; /* add a pending slide_hash() */ + } + zmemcpy(s->window + s->strstart, s->strm->next_in - used, used); + s->strstart += used; + } + s->block_start = s->strstart; + s->insert += MIN(used, s->w_size - s->insert); } - s->insert = 0; - if (flush == Z_FINISH) { - FLUSH_BLOCK(s, 1); + if (s->high_water < s->strstart) + s->high_water = s->strstart; + + /* If the last block was written to next_out, then done. */ + if (last) return finish_done; + + /* If flushing and all input has been consumed, then done. */ + if (flush != Z_NO_FLUSH && flush != Z_FINISH && + s->strm->avail_in == 0 && (long)s->strstart == s->block_start) + return block_done; + + /* Fill the window with any remaining input. */ + have = s->window_size - s->strstart - 1; + if (s->strm->avail_in > have && s->block_start >= (long)s->w_size) { + /* Slide the window down. */ + s->block_start -= s->w_size; + s->strstart -= s->w_size; + zmemcpy(s->window, s->window + s->w_size, s->strstart); + if (s->matches < 2) + s->matches++; /* add a pending slide_hash() */ + have += s->w_size; /* more space now */ } - if ((long)s->strstart > s->block_start) - FLUSH_BLOCK(s, 0); - return block_done; + if (have > s->strm->avail_in) + have = s->strm->avail_in; + if (have) { + read_buf(s->strm, s->window + s->strstart, have); + s->strstart += have; + } + if (s->high_water < s->strstart) + s->high_water = s->strstart; + + /* There was not enough avail_out to write a complete worthy or flushed + * stored block to next_out. Write a stored block to pending instead, if we + * have enough input for a worthy block, or if flushing and there is enough + * room for the remaining input as a stored block in the pending buffer. + */ + have = (s->bi_valid + 42) >> 3; /* number of header bytes */ + /* maximum stored block length that will fit in pending: */ + have = MIN(s->pending_buf_size - have, MAX_STORED); + min_block = MIN(have, s->w_size); + left = s->strstart - s->block_start; + if (left >= min_block || + ((left || flush == Z_FINISH) && flush != Z_NO_FLUSH && + s->strm->avail_in == 0 && left <= have)) { + len = MIN(left, have); + last = flush == Z_FINISH && s->strm->avail_in == 0 && + len == left ? 1 : 0; + _tr_stored_block(s, (charf *)s->window + s->block_start, len, last); + s->block_start += len; + flush_pending(s->strm); + } + + /* We've done all we can with the available input and output. */ + return last ? finish_started : need_more; } /* =========================================================================== @@ -1892,7 +2088,7 @@ local block_state deflate_rle(s, flush) prev == *++scan && prev == *++scan && prev == *++scan && prev == *++scan && scan < strend); - s->match_length = MAX_MATCH - (int)(strend - scan); + s->match_length = MAX_MATCH - (uInt)(strend - scan); if (s->match_length > s->lookahead) s->match_length = s->lookahead; } diff --git a/Modules/zlib/deflate.h b/Modules/zlib/deflate.h index ce0299edd19168..23ecdd312bc06e 100644 --- a/Modules/zlib/deflate.h +++ b/Modules/zlib/deflate.h @@ -1,5 +1,5 @@ /* deflate.h -- internal compression state - * Copyright (C) 1995-2012 Jean-loup Gailly + * Copyright (C) 1995-2016 Jean-loup Gailly * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -51,13 +51,16 @@ #define Buf_size 16 /* size of bit buffer in bi_buf */ -#define INIT_STATE 42 -#define EXTRA_STATE 69 -#define NAME_STATE 73 -#define COMMENT_STATE 91 -#define HCRC_STATE 103 -#define BUSY_STATE 113 -#define FINISH_STATE 666 +#define INIT_STATE 42 /* zlib header -> BUSY_STATE */ +#ifdef GZIP +# define GZIP_STATE 57 /* gzip header -> BUSY_STATE | EXTRA_STATE */ +#endif +#define EXTRA_STATE 69 /* gzip extra block -> NAME_STATE */ +#define NAME_STATE 73 /* gzip file name -> COMMENT_STATE */ +#define COMMENT_STATE 91 /* gzip comment -> HCRC_STATE */ +#define HCRC_STATE 103 /* gzip header CRC -> BUSY_STATE */ +#define BUSY_STATE 113 /* deflate -> FINISH_STATE */ +#define FINISH_STATE 666 /* stream complete */ /* Stream status */ @@ -83,7 +86,7 @@ typedef struct static_tree_desc_s static_tree_desc; typedef struct tree_desc_s { ct_data *dyn_tree; /* the dynamic tree */ int max_code; /* largest code with non zero frequency */ - static_tree_desc *stat_desc; /* the corresponding static tree */ + const static_tree_desc *stat_desc; /* the corresponding static tree */ } FAR tree_desc; typedef ush Pos; @@ -100,10 +103,10 @@ typedef struct internal_state { Bytef *pending_buf; /* output still pending */ ulg pending_buf_size; /* size of pending_buf */ Bytef *pending_out; /* next pending byte to output to the stream */ - uInt pending; /* nb of bytes in the pending buffer */ + ulg pending; /* nb of bytes in the pending buffer */ int wrap; /* bit 0 true for zlib, bit 1 true for gzip */ gz_headerp gzhead; /* gzip header information to write */ - uInt gzindex; /* where in extra, name, or comment */ + ulg gzindex; /* where in extra, name, or comment */ Byte method; /* can only be DEFLATED */ int last_flush; /* value of flush param for previous deflate call */ @@ -249,7 +252,7 @@ typedef struct internal_state { uInt matches; /* number of string matches in current block */ uInt insert; /* bytes at end of window left to insert */ -#ifdef DEBUG +#ifdef ZLIB_DEBUG ulg compressed_len; /* total bit length of compressed file mod 2^32 */ ulg bits_sent; /* bit length of compressed data sent mod 2^32 */ #endif @@ -275,7 +278,7 @@ typedef struct internal_state { /* Output a byte on the stream. * IN assertion: there is enough room in pending_buf. */ -#define put_byte(s, c) {s->pending_buf[s->pending++] = (c);} +#define put_byte(s, c) {s->pending_buf[s->pending++] = (Bytef)(c);} #define MIN_LOOKAHEAD (MAX_MATCH+MIN_MATCH+1) @@ -309,7 +312,7 @@ void ZLIB_INTERNAL _tr_stored_block OF((deflate_state *s, charf *buf, * used. */ -#ifndef DEBUG +#ifndef ZLIB_DEBUG /* Inline versions of _tr_tally for speed: */ #if defined(GEN_TREES_H) || !defined(STDC) @@ -328,8 +331,8 @@ void ZLIB_INTERNAL _tr_stored_block OF((deflate_state *s, charf *buf, flush = (s->last_lit == s->lit_bufsize-1); \ } # define _tr_tally_dist(s, distance, length, flush) \ - { uch len = (length); \ - ush dist = (distance); \ + { uch len = (uch)(length); \ + ush dist = (ush)(distance); \ s->d_buf[s->last_lit] = dist; \ s->l_buf[s->last_lit++] = len; \ dist--; \ diff --git a/Modules/zlib/gzguts.h b/Modules/zlib/gzguts.h index d87659d0319fa3..990a4d25149337 100644 --- a/Modules/zlib/gzguts.h +++ b/Modules/zlib/gzguts.h @@ -1,5 +1,5 @@ /* gzguts.h -- zlib internal header definitions for gz* operations - * Copyright (C) 2004, 2005, 2010, 2011, 2012, 2013 Mark Adler + * Copyright (C) 2004, 2005, 2010, 2011, 2012, 2013, 2016 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -25,6 +25,10 @@ # include # include #endif + +#ifndef _POSIX_SOURCE +# define _POSIX_SOURCE +#endif #include #ifdef _WIN32 @@ -35,6 +39,10 @@ # include #endif +#if defined(_WIN32) || defined(__CYGWIN__) +# define WIDECHAR +#endif + #ifdef WINAPI_FAMILY # define open _open # define read _read @@ -95,18 +103,19 @@ # endif #endif -/* unlike snprintf (which is required in C99, yet still not supported by - Microsoft more than a decade later!), _snprintf does not guarantee null - termination of the result -- however this is only used in gzlib.c where +/* unlike snprintf (which is required in C99), _snprintf does not guarantee + null termination of the result -- however this is only used in gzlib.c where the result is assured to fit in the space provided */ -#ifdef _MSC_VER +#if defined(_MSC_VER) && _MSC_VER < 1900 # define snprintf _snprintf #endif #ifndef local # define local static #endif -/* compile with -Dlocal if your debugger can't find static symbols */ +/* since "static" is used to mean two completely different things in C, we + define "local" for the non-static meaning of "static", for readability + (compile with -Dlocal if your debugger can't find static symbols) */ /* gz* functions always use library allocation functions */ #ifndef STDC @@ -170,7 +179,7 @@ typedef struct { char *path; /* path or fd for error messages */ unsigned size; /* buffer size, zero if not allocated yet */ unsigned want; /* requested buffer size, default is GZBUFSIZE */ - unsigned char *in; /* input buffer */ + unsigned char *in; /* input buffer (double-sized when writing) */ unsigned char *out; /* output buffer (double-sized when reading) */ int direct; /* 0 if processing gzip, 1 if transparent */ /* just for reading */ diff --git a/Modules/zlib/gzlib.c b/Modules/zlib/gzlib.c index fae202ef8905a3..4105e6aff92594 100644 --- a/Modules/zlib/gzlib.c +++ b/Modules/zlib/gzlib.c @@ -1,11 +1,11 @@ /* gzlib.c -- zlib functions common to reading and writing gzip files - * Copyright (C) 2004, 2010, 2011, 2012, 2013 Mark Adler + * Copyright (C) 2004-2017 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ #include "gzguts.h" -#if defined(_WIN32) && !defined(__BORLANDC__) +#if defined(_WIN32) && !defined(__BORLANDC__) && !defined(__MINGW32__) # define LSEEK _lseeki64 #else #if defined(_LARGEFILE64_SOURCE) && _LFS64_LARGEFILE-0 @@ -94,7 +94,7 @@ local gzFile gz_open(path, fd, mode) const char *mode; { gz_statep state; - size_t len; + z_size_t len; int oflag; #ifdef O_CLOEXEC int cloexec = 0; @@ -188,10 +188,10 @@ local gzFile gz_open(path, fd, mode) } /* save the path name for error messages */ -#ifdef _WIN32 +#ifdef WIDECHAR if (fd == -2) { len = wcstombs(NULL, path, 0); - if (len == (size_t)-1) + if (len == (z_size_t)-1) len = 0; } else @@ -202,7 +202,7 @@ local gzFile gz_open(path, fd, mode) free(state); return NULL; } -#ifdef _WIN32 +#ifdef WIDECHAR if (fd == -2) if (len) wcstombs(state->path, path, len + 1); @@ -211,7 +211,7 @@ local gzFile gz_open(path, fd, mode) else #endif #if !defined(NO_snprintf) && !defined(NO_vsnprintf) - snprintf(state->path, len + 1, "%s", (const char *)path); + (void)snprintf(state->path, len + 1, "%s", (const char *)path); #else strcpy(state->path, path); #endif @@ -239,7 +239,7 @@ local gzFile gz_open(path, fd, mode) /* open the file with the appropriate flags (or just use fd) */ state->fd = fd > -1 ? fd : ( -#ifdef _WIN32 +#ifdef WIDECHAR fd == -2 ? _wopen(path, oflag, 0666) : #endif open((const char *)path, oflag, 0666)); @@ -248,8 +248,10 @@ local gzFile gz_open(path, fd, mode) free(state); return NULL; } - if (state->mode == GZ_APPEND) + if (state->mode == GZ_APPEND) { + LSEEK(state->fd, 0, SEEK_END); /* so gzoffset() is correct */ state->mode = GZ_WRITE; /* simplify later checks */ + } /* save the current position for rewinding (only if reading) */ if (state->mode == GZ_READ) { @@ -291,7 +293,7 @@ gzFile ZEXPORT gzdopen(fd, mode) if (fd == -1 || (path = (char *)malloc(7 + 3 * sizeof(int))) == NULL) return NULL; #if !defined(NO_snprintf) && !defined(NO_vsnprintf) - snprintf(path, 7 + 3 * sizeof(int), "", fd); /* for debugging */ + (void)snprintf(path, 7 + 3 * sizeof(int), "", fd); #else sprintf(path, "", fd); /* for debugging */ #endif @@ -301,7 +303,7 @@ gzFile ZEXPORT gzdopen(fd, mode) } /* -- see zlib.h -- */ -#ifdef _WIN32 +#ifdef WIDECHAR gzFile ZEXPORT gzopen_w(path, mode) const wchar_t *path; const char *mode; @@ -329,6 +331,8 @@ int ZEXPORT gzbuffer(file, size) return -1; /* check and set requested size */ + if ((size << 1) < size) + return -1; /* need to be able to double it */ if (size < 2) size = 2; /* need two bytes to check magic header */ state->want = size; @@ -604,14 +608,13 @@ void ZLIB_INTERNAL gz_error(state, err, msg) return; } #if !defined(NO_snprintf) && !defined(NO_vsnprintf) - snprintf(state->msg, strlen(state->path) + strlen(msg) + 3, - "%s%s%s", state->path, ": ", msg); + (void)snprintf(state->msg, strlen(state->path) + strlen(msg) + 3, + "%s%s%s", state->path, ": ", msg); #else strcpy(state->msg, state->path); strcat(state->msg, ": "); strcat(state->msg, msg); #endif - return; } #ifndef INT_MAX diff --git a/Modules/zlib/gzread.c b/Modules/zlib/gzread.c index bf4538eb274245..956b91ea7d9e2a 100644 --- a/Modules/zlib/gzread.c +++ b/Modules/zlib/gzread.c @@ -1,5 +1,5 @@ /* gzread.c -- zlib functions for reading gzip files - * Copyright (C) 2004, 2005, 2010, 2011, 2012, 2013 Mark Adler + * Copyright (C) 2004, 2005, 2010, 2011, 2012, 2013, 2016 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -12,6 +12,7 @@ local int gz_look OF((gz_statep)); local int gz_decomp OF((gz_statep)); local int gz_fetch OF((gz_statep)); local int gz_skip OF((gz_statep, z_off64_t)); +local z_size_t gz_read OF((gz_statep, voidp, z_size_t)); /* Use read() to load a buffer -- return -1 on error, otherwise 0. Read from state->fd, and update state->eof, state->err, and state->msg as appropriate. @@ -24,13 +25,17 @@ local int gz_load(state, buf, len, have) unsigned *have; { int ret; + unsigned get, max = ((unsigned)-1 >> 2) + 1; *have = 0; do { - ret = read(state->fd, buf + *have, len - *have); + get = len - *have; + if (get > max) + get = max; + ret = read(state->fd, buf + *have, get); if (ret <= 0) break; - *have += ret; + *have += (unsigned)ret; } while (*have < len); if (ret < 0) { gz_error(state, Z_ERRNO, zstrerror()); @@ -94,10 +99,8 @@ local int gz_look(state) state->in = (unsigned char *)malloc(state->want); state->out = (unsigned char *)malloc(state->want << 1); if (state->in == NULL || state->out == NULL) { - if (state->out != NULL) - free(state->out); - if (state->in != NULL) - free(state->in); + free(state->out); + free(state->in); gz_error(state, Z_MEM_ERROR, "out of memory"); return -1; } @@ -284,33 +287,17 @@ local int gz_skip(state, len) return 0; } -/* -- see zlib.h -- */ -int ZEXPORT gzread(file, buf, len) - gzFile file; +/* Read len bytes into buf from file, or less than len up to the end of the + input. Return the number of bytes read. If zero is returned, either the + end of file was reached, or there was an error. state->err must be + consulted in that case to determine which. */ +local z_size_t gz_read(state, buf, len) + gz_statep state; voidp buf; - unsigned len; + z_size_t len; { - unsigned got, n; - gz_statep state; - z_streamp strm; - - /* get internal structure */ - if (file == NULL) - return -1; - state = (gz_statep)file; - strm = &(state->strm); - - /* check that we're reading and that there's no (serious) error */ - if (state->mode != GZ_READ || - (state->err != Z_OK && state->err != Z_BUF_ERROR)) - return -1; - - /* since an int is returned, make sure len fits in one, otherwise return - with an error (this avoids the flaw in the interface) */ - if ((int)len < 0) { - gz_error(state, Z_DATA_ERROR, "requested length does not fit in int"); - return -1; - } + z_size_t got; + unsigned n; /* if len is zero, avoid unnecessary operations */ if (len == 0) @@ -320,32 +307,38 @@ int ZEXPORT gzread(file, buf, len) if (state->seek) { state->seek = 0; if (gz_skip(state, state->skip) == -1) - return -1; + return 0; } /* get len bytes to buf, or less than len if at the end */ got = 0; do { + /* set n to the maximum amount of len that fits in an unsigned int */ + n = -1; + if (n > len) + n = len; + /* first just try copying data from the output buffer */ if (state->x.have) { - n = state->x.have > len ? len : state->x.have; + if (state->x.have < n) + n = state->x.have; memcpy(buf, state->x.next, n); state->x.next += n; state->x.have -= n; } /* output buffer empty -- return if we're at the end of the input */ - else if (state->eof && strm->avail_in == 0) { + else if (state->eof && state->strm.avail_in == 0) { state->past = 1; /* tried to read past end */ break; } /* need output data -- for small len or new stream load up our output buffer */ - else if (state->how == LOOK || len < (state->size << 1)) { + else if (state->how == LOOK || n < (state->size << 1)) { /* get more output, looking for header if required */ if (gz_fetch(state) == -1) - return -1; + return 0; continue; /* no progress yet -- go back to copy above */ /* the copy above assures that we will leave with space in the output buffer, allowing at least one gzungetc() to succeed */ @@ -353,16 +346,16 @@ int ZEXPORT gzread(file, buf, len) /* large len -- read directly into user buffer */ else if (state->how == COPY) { /* read directly */ - if (gz_load(state, (unsigned char *)buf, len, &n) == -1) - return -1; + if (gz_load(state, (unsigned char *)buf, n, &n) == -1) + return 0; } /* large len -- decompress directly into user buffer */ else { /* state->how == GZIP */ - strm->avail_out = len; - strm->next_out = (unsigned char *)buf; + state->strm.avail_out = n; + state->strm.next_out = (unsigned char *)buf; if (gz_decomp(state) == -1) - return -1; + return 0; n = state->x.have; state->x.have = 0; } @@ -374,8 +367,75 @@ int ZEXPORT gzread(file, buf, len) state->x.pos += n; } while (len); - /* return number of bytes read into user buffer (will fit in int) */ - return (int)got; + /* return number of bytes read into user buffer */ + return got; +} + +/* -- see zlib.h -- */ +int ZEXPORT gzread(file, buf, len) + gzFile file; + voidp buf; + unsigned len; +{ + gz_statep state; + + /* get internal structure */ + if (file == NULL) + return -1; + state = (gz_statep)file; + + /* check that we're reading and that there's no (serious) error */ + if (state->mode != GZ_READ || + (state->err != Z_OK && state->err != Z_BUF_ERROR)) + return -1; + + /* since an int is returned, make sure len fits in one, otherwise return + with an error (this avoids a flaw in the interface) */ + if ((int)len < 0) { + gz_error(state, Z_STREAM_ERROR, "request does not fit in an int"); + return -1; + } + + /* read len or fewer bytes to buf */ + len = gz_read(state, buf, len); + + /* check for an error */ + if (len == 0 && state->err != Z_OK && state->err != Z_BUF_ERROR) + return -1; + + /* return the number of bytes read (this is assured to fit in an int) */ + return (int)len; +} + +/* -- see zlib.h -- */ +z_size_t ZEXPORT gzfread(buf, size, nitems, file) + voidp buf; + z_size_t size; + z_size_t nitems; + gzFile file; +{ + z_size_t len; + gz_statep state; + + /* get internal structure */ + if (file == NULL) + return 0; + state = (gz_statep)file; + + /* check that we're reading and that there's no (serious) error */ + if (state->mode != GZ_READ || + (state->err != Z_OK && state->err != Z_BUF_ERROR)) + return 0; + + /* compute bytes to read -- error on overflow */ + len = nitems * size; + if (size && len / size != nitems) { + gz_error(state, Z_STREAM_ERROR, "request does not fit in a size_t"); + return 0; + } + + /* read len or fewer bytes to buf, return the number of full items read */ + return len ? gz_read(state, buf, len) / size : 0; } /* -- see zlib.h -- */ @@ -408,8 +468,8 @@ int ZEXPORT gzgetc(file) return *(state->x.next)++; } - /* nothing there -- try gzread() */ - ret = gzread(file, buf, 1); + /* nothing there -- try gz_read() */ + ret = gz_read(state, buf, 1); return ret < 1 ? -1 : buf[0]; } @@ -451,7 +511,7 @@ int ZEXPORT gzungetc(c, file) if (state->x.have == 0) { state->x.have = 1; state->x.next = state->out + (state->size << 1) - 1; - state->x.next[0] = c; + state->x.next[0] = (unsigned char)c; state->x.pos--; state->past = 0; return c; @@ -473,7 +533,7 @@ int ZEXPORT gzungetc(c, file) } state->x.have++; state->x.next--; - state->x.next[0] = c; + state->x.next[0] = (unsigned char)c; state->x.pos--; state->past = 0; return c; diff --git a/Modules/zlib/gzwrite.c b/Modules/zlib/gzwrite.c index aa767fbf63ec7d..c7b5651d70b994 100644 --- a/Modules/zlib/gzwrite.c +++ b/Modules/zlib/gzwrite.c @@ -1,5 +1,5 @@ /* gzwrite.c -- zlib functions for writing gzip files - * Copyright (C) 2004, 2005, 2010, 2011, 2012, 2013 Mark Adler + * Copyright (C) 2004-2017 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -9,17 +9,19 @@ local int gz_init OF((gz_statep)); local int gz_comp OF((gz_statep, int)); local int gz_zero OF((gz_statep, z_off64_t)); +local z_size_t gz_write OF((gz_statep, voidpc, z_size_t)); /* Initialize state for writing a gzip file. Mark initialization by setting - state->size to non-zero. Return -1 on failure or 0 on success. */ + state->size to non-zero. Return -1 on a memory allocation failure, or 0 on + success. */ local int gz_init(state) gz_statep state; { int ret; z_streamp strm = &(state->strm); - /* allocate input buffer */ - state->in = (unsigned char *)malloc(state->want); + /* allocate input buffer (double size for gzprintf) */ + state->in = (unsigned char *)malloc(state->want << 1); if (state->in == NULL) { gz_error(state, Z_MEM_ERROR, "out of memory"); return -1; @@ -47,6 +49,7 @@ local int gz_init(state) gz_error(state, Z_MEM_ERROR, "out of memory"); return -1; } + strm->next_in = NULL; } /* mark state as initialized */ @@ -62,17 +65,17 @@ local int gz_init(state) } /* Compress whatever is at avail_in and next_in and write to the output file. - Return -1 if there is an error writing to the output file, otherwise 0. - flush is assumed to be a valid deflate() flush value. If flush is Z_FINISH, - then the deflate() state is reset to start a new gzip stream. If gz->direct - is true, then simply write to the output file without compressing, and - ignore flush. */ + Return -1 if there is an error writing to the output file or if gz_init() + fails to allocate memory, otherwise 0. flush is assumed to be a valid + deflate() flush value. If flush is Z_FINISH, then the deflate() state is + reset to start a new gzip stream. If gz->direct is true, then simply write + to the output file without compressing, and ignore flush. */ local int gz_comp(state, flush) gz_statep state; int flush; { - int ret, got; - unsigned have; + int ret, writ; + unsigned have, put, max = ((unsigned)-1 >> 2) + 1; z_streamp strm = &(state->strm); /* allocate memory if this is the first time through */ @@ -81,12 +84,16 @@ local int gz_comp(state, flush) /* write directly if requested */ if (state->direct) { - got = write(state->fd, strm->next_in, strm->avail_in); - if (got < 0 || (unsigned)got != strm->avail_in) { - gz_error(state, Z_ERRNO, zstrerror()); - return -1; + while (strm->avail_in) { + put = strm->avail_in > max ? max : strm->avail_in; + writ = write(state->fd, strm->next_in, put); + if (writ < 0) { + gz_error(state, Z_ERRNO, zstrerror()); + return -1; + } + strm->avail_in -= (unsigned)writ; + strm->next_in += writ; } - strm->avail_in = 0; return 0; } @@ -97,17 +104,21 @@ local int gz_comp(state, flush) doing Z_FINISH then don't write until we get to Z_STREAM_END */ if (strm->avail_out == 0 || (flush != Z_NO_FLUSH && (flush != Z_FINISH || ret == Z_STREAM_END))) { - have = (unsigned)(strm->next_out - state->x.next); - if (have && ((got = write(state->fd, state->x.next, have)) < 0 || - (unsigned)got != have)) { - gz_error(state, Z_ERRNO, zstrerror()); - return -1; + while (strm->next_out > state->x.next) { + put = strm->next_out - state->x.next > (int)max ? max : + (unsigned)(strm->next_out - state->x.next); + writ = write(state->fd, state->x.next, put); + if (writ < 0) { + gz_error(state, Z_ERRNO, zstrerror()); + return -1; + } + state->x.next += writ; } if (strm->avail_out == 0) { strm->avail_out = state->size; strm->next_out = state->out; + state->x.next = state->out; } - state->x.next = strm->next_out; } /* compress */ @@ -129,7 +140,8 @@ local int gz_comp(state, flush) return 0; } -/* Compress len zeros to output. Return -1 on error, 0 on success. */ +/* Compress len zeros to output. Return -1 on a write error or memory + allocation failure by gz_comp(), or 0 on success. */ local int gz_zero(state, len) gz_statep state; z_off64_t len; @@ -161,32 +173,14 @@ local int gz_zero(state, len) return 0; } -/* -- see zlib.h -- */ -int ZEXPORT gzwrite(file, buf, len) - gzFile file; +/* Write len bytes from buf to file. Return the number of bytes written. If + the returned value is less than len, then there was an error. */ +local z_size_t gz_write(state, buf, len) + gz_statep state; voidpc buf; - unsigned len; + z_size_t len; { - unsigned put = len; - gz_statep state; - z_streamp strm; - - /* get internal structure */ - if (file == NULL) - return 0; - state = (gz_statep)file; - strm = &(state->strm); - - /* check that we're writing and that there's no error */ - if (state->mode != GZ_WRITE || state->err != Z_OK) - return 0; - - /* since an int is returned, make sure len fits in one, otherwise return - with an error (this avoids the flaw in the interface) */ - if ((int)len < 0) { - gz_error(state, Z_DATA_ERROR, "requested length does not fit in int"); - return 0; - } + z_size_t put = len; /* if len is zero, avoid unnecessary operations */ if (len == 0) @@ -209,14 +203,15 @@ int ZEXPORT gzwrite(file, buf, len) do { unsigned have, copy; - if (strm->avail_in == 0) - strm->next_in = state->in; - have = (unsigned)((strm->next_in + strm->avail_in) - state->in); + if (state->strm.avail_in == 0) + state->strm.next_in = state->in; + have = (unsigned)((state->strm.next_in + state->strm.avail_in) - + state->in); copy = state->size - have; if (copy > len) copy = len; memcpy(state->in + have, buf, copy); - strm->avail_in += copy; + state->strm.avail_in += copy; state->x.pos += copy; buf = (const char *)buf + copy; len -= copy; @@ -226,19 +221,83 @@ int ZEXPORT gzwrite(file, buf, len) } else { /* consume whatever's left in the input buffer */ - if (strm->avail_in && gz_comp(state, Z_NO_FLUSH) == -1) + if (state->strm.avail_in && gz_comp(state, Z_NO_FLUSH) == -1) return 0; /* directly compress user buffer to file */ - strm->avail_in = len; - strm->next_in = (z_const Bytef *)buf; - state->x.pos += len; - if (gz_comp(state, Z_NO_FLUSH) == -1) - return 0; + state->strm.next_in = (z_const Bytef *)buf; + do { + unsigned n = (unsigned)-1; + if (n > len) + n = len; + state->strm.avail_in = n; + state->x.pos += n; + if (gz_comp(state, Z_NO_FLUSH) == -1) + return 0; + len -= n; + } while (len); + } + + /* input was all buffered or compressed */ + return put; +} + +/* -- see zlib.h -- */ +int ZEXPORT gzwrite(file, buf, len) + gzFile file; + voidpc buf; + unsigned len; +{ + gz_statep state; + + /* get internal structure */ + if (file == NULL) + return 0; + state = (gz_statep)file; + + /* check that we're writing and that there's no error */ + if (state->mode != GZ_WRITE || state->err != Z_OK) + return 0; + + /* since an int is returned, make sure len fits in one, otherwise return + with an error (this avoids a flaw in the interface) */ + if ((int)len < 0) { + gz_error(state, Z_DATA_ERROR, "requested length does not fit in int"); + return 0; + } + + /* write len bytes from buf (the return value will fit in an int) */ + return (int)gz_write(state, buf, len); +} + +/* -- see zlib.h -- */ +z_size_t ZEXPORT gzfwrite(buf, size, nitems, file) + voidpc buf; + z_size_t size; + z_size_t nitems; + gzFile file; +{ + z_size_t len; + gz_statep state; + + /* get internal structure */ + if (file == NULL) + return 0; + state = (gz_statep)file; + + /* check that we're writing and that there's no error */ + if (state->mode != GZ_WRITE || state->err != Z_OK) + return 0; + + /* compute bytes to read -- error on overflow */ + len = nitems * size; + if (size && len / size != nitems) { + gz_error(state, Z_STREAM_ERROR, "request does not fit in a size_t"); + return 0; } - /* input was all buffered or compressed (put will fit in int) */ - return (int)put; + /* write len bytes to buf, return the number of full items written */ + return len ? gz_write(state, buf, len) / size : 0; } /* -- see zlib.h -- */ @@ -275,7 +334,7 @@ int ZEXPORT gzputc(file, c) strm->next_in = state->in; have = (unsigned)((strm->next_in + strm->avail_in) - state->in); if (have < state->size) { - state->in[have] = c; + state->in[have] = (unsigned char)c; strm->avail_in++; state->x.pos++; return c & 0xff; @@ -283,8 +342,8 @@ int ZEXPORT gzputc(file, c) } /* no room in buffer or not initialized, use gz_write() */ - buf[0] = c; - if (gzwrite(file, buf, 1) != 1) + buf[0] = (unsigned char)c; + if (gz_write(state, buf, 1) != 1) return -1; return c & 0xff; } @@ -295,11 +354,21 @@ int ZEXPORT gzputs(file, str) const char *str; { int ret; - unsigned len; + z_size_t len; + gz_statep state; + + /* get internal structure */ + if (file == NULL) + return -1; + state = (gz_statep)file; + + /* check that we're writing and that there's no error */ + if (state->mode != GZ_WRITE || state->err != Z_OK) + return -1; /* write string */ - len = (unsigned)strlen(str); - ret = gzwrite(file, str, len); + len = strlen(str); + ret = gz_write(state, str, len); return ret == 0 && len != 0 ? -1 : ret; } @@ -309,63 +378,73 @@ int ZEXPORT gzputs(file, str) /* -- see zlib.h -- */ int ZEXPORTVA gzvprintf(gzFile file, const char *format, va_list va) { - int size, len; + int len; + unsigned left; + char *next; gz_statep state; z_streamp strm; /* get internal structure */ if (file == NULL) - return -1; + return Z_STREAM_ERROR; state = (gz_statep)file; strm = &(state->strm); /* check that we're writing and that there's no error */ if (state->mode != GZ_WRITE || state->err != Z_OK) - return 0; + return Z_STREAM_ERROR; /* make sure we have some buffer space */ if (state->size == 0 && gz_init(state) == -1) - return 0; + return state->err; /* check for seek request */ if (state->seek) { state->seek = 0; if (gz_zero(state, state->skip) == -1) - return 0; + return state->err; } - /* consume whatever's left in the input buffer */ - if (strm->avail_in && gz_comp(state, Z_NO_FLUSH) == -1) - return 0; - - /* do the printf() into the input buffer, put length in len */ - size = (int)(state->size); - state->in[size - 1] = 0; + /* do the printf() into the input buffer, put length in len -- the input + buffer is double-sized just for this function, so there is guaranteed to + be state->size bytes available after the current contents */ + if (strm->avail_in == 0) + strm->next_in = state->in; + next = (char *)(state->in + (strm->next_in - state->in) + strm->avail_in); + next[state->size - 1] = 0; #ifdef NO_vsnprintf # ifdef HAS_vsprintf_void - (void)vsprintf((char *)(state->in), format, va); - for (len = 0; len < size; len++) - if (state->in[len] == 0) break; + (void)vsprintf(next, format, va); + for (len = 0; len < state->size; len++) + if (next[len] == 0) break; # else - len = vsprintf((char *)(state->in), format, va); + len = vsprintf(next, format, va); # endif #else # ifdef HAS_vsnprintf_void - (void)vsnprintf((char *)(state->in), size, format, va); - len = strlen((char *)(state->in)); + (void)vsnprintf(next, state->size, format, va); + len = strlen(next); # else - len = vsnprintf((char *)(state->in), size, format, va); + len = vsnprintf(next, state->size, format, va); # endif #endif /* check that printf() results fit in buffer */ - if (len <= 0 || len >= (int)size || state->in[size - 1] != 0) + if (len == 0 || (unsigned)len >= state->size || next[state->size - 1] != 0) return 0; - /* update buffer and position, defer compression until needed */ - strm->avail_in = (unsigned)len; - strm->next_in = state->in; + /* update buffer and position, compress first half if past that */ + strm->avail_in += (unsigned)len; state->x.pos += len; + if (strm->avail_in >= state->size) { + left = strm->avail_in - state->size; + strm->avail_in = state->size; + if (gz_comp(state, Z_NO_FLUSH) == -1) + return state->err; + memcpy(state->in, state->in + state->size, left); + strm->next_in = state->in; + strm->avail_in = left; + } return len; } @@ -390,73 +469,82 @@ int ZEXPORTVA gzprintf (file, format, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, int a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20; { - int size, len; + unsigned len, left; + char *next; gz_statep state; z_streamp strm; /* get internal structure */ if (file == NULL) - return -1; + return Z_STREAM_ERROR; state = (gz_statep)file; strm = &(state->strm); /* check that can really pass pointer in ints */ if (sizeof(int) != sizeof(void *)) - return 0; + return Z_STREAM_ERROR; /* check that we're writing and that there's no error */ if (state->mode != GZ_WRITE || state->err != Z_OK) - return 0; + return Z_STREAM_ERROR; /* make sure we have some buffer space */ if (state->size == 0 && gz_init(state) == -1) - return 0; + return state->error; /* check for seek request */ if (state->seek) { state->seek = 0; if (gz_zero(state, state->skip) == -1) - return 0; + return state->error; } - /* consume whatever's left in the input buffer */ - if (strm->avail_in && gz_comp(state, Z_NO_FLUSH) == -1) - return 0; - - /* do the printf() into the input buffer, put length in len */ - size = (int)(state->size); - state->in[size - 1] = 0; + /* do the printf() into the input buffer, put length in len -- the input + buffer is double-sized just for this function, so there is guaranteed to + be state->size bytes available after the current contents */ + if (strm->avail_in == 0) + strm->next_in = state->in; + next = (char *)(strm->next_in + strm->avail_in); + next[state->size - 1] = 0; #ifdef NO_snprintf # ifdef HAS_sprintf_void - sprintf((char *)(state->in), format, a1, a2, a3, a4, a5, a6, a7, a8, - a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20); + sprintf(next, format, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, + a13, a14, a15, a16, a17, a18, a19, a20); for (len = 0; len < size; len++) - if (state->in[len] == 0) break; + if (next[len] == 0) + break; # else - len = sprintf((char *)(state->in), format, a1, a2, a3, a4, a5, a6, a7, a8, - a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20); + len = sprintf(next, format, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, + a12, a13, a14, a15, a16, a17, a18, a19, a20); # endif #else # ifdef HAS_snprintf_void - snprintf((char *)(state->in), size, format, a1, a2, a3, a4, a5, a6, a7, a8, - a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20); - len = strlen((char *)(state->in)); + snprintf(next, state->size, format, a1, a2, a3, a4, a5, a6, a7, a8, a9, + a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20); + len = strlen(next); # else - len = snprintf((char *)(state->in), size, format, a1, a2, a3, a4, a5, a6, - a7, a8, a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, - a19, a20); + len = snprintf(next, state->size, format, a1, a2, a3, a4, a5, a6, a7, a8, + a9, a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20); # endif #endif /* check that printf() results fit in buffer */ - if (len <= 0 || len >= (int)size || state->in[size - 1] != 0) + if (len == 0 || len >= state->size || next[state->size - 1] != 0) return 0; - /* update buffer and position, defer compression until needed */ - strm->avail_in = (unsigned)len; - strm->next_in = state->in; + /* update buffer and position, compress first half if past that */ + strm->avail_in += len; state->x.pos += len; - return len; + if (strm->avail_in >= state->size) { + left = strm->avail_in - state->size; + strm->avail_in = state->size; + if (gz_comp(state, Z_NO_FLUSH) == -1) + return state->err; + memcpy(state->in, state->in + state->size, left); + strm->next_in = state->in; + strm->avail_in = left; + } + return (int)len; } #endif @@ -470,7 +558,7 @@ int ZEXPORT gzflush(file, flush) /* get internal structure */ if (file == NULL) - return -1; + return Z_STREAM_ERROR; state = (gz_statep)file; /* check that we're writing and that there's no error */ @@ -485,11 +573,11 @@ int ZEXPORT gzflush(file, flush) if (state->seek) { state->seek = 0; if (gz_zero(state, state->skip) == -1) - return -1; + return state->err; } /* compress remaining data with requested flush */ - gz_comp(state, flush); + (void)gz_comp(state, flush); return state->err; } @@ -520,13 +608,13 @@ int ZEXPORT gzsetparams(file, level, strategy) if (state->seek) { state->seek = 0; if (gz_zero(state, state->skip) == -1) - return -1; + return state->err; } /* change compression parameters for subsequent input */ if (state->size) { /* flush previous input with previous parameters before changing */ - if (strm->avail_in && gz_comp(state, Z_PARTIAL_FLUSH) == -1) + if (strm->avail_in && gz_comp(state, Z_BLOCK) == -1) return state->err; deflateParams(strm, level, strategy); } diff --git a/Modules/zlib/infback.c b/Modules/zlib/infback.c index f3833c2e434a56..59679ecbfc5d77 100644 --- a/Modules/zlib/infback.c +++ b/Modules/zlib/infback.c @@ -1,5 +1,5 @@ /* infback.c -- inflate using a call-back interface - * Copyright (C) 1995-2011 Mark Adler + * Copyright (C) 1995-2016 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -61,7 +61,7 @@ int stream_size; Tracev((stderr, "inflate: allocated\n")); strm->state = (struct internal_state FAR *)state; state->dmax = 32768U; - state->wbits = windowBits; + state->wbits = (uInt)windowBits; state->wsize = 1U << windowBits; state->window = window; state->wnext = 0; diff --git a/Modules/zlib/inffast.c b/Modules/zlib/inffast.c index bda59ceb6a12b2..0dbd1dbc09f2f6 100644 --- a/Modules/zlib/inffast.c +++ b/Modules/zlib/inffast.c @@ -1,5 +1,5 @@ /* inffast.c -- fast decoding - * Copyright (C) 1995-2008, 2010, 2013 Mark Adler + * Copyright (C) 1995-2017 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -8,26 +8,9 @@ #include "inflate.h" #include "inffast.h" -#ifndef ASMINF - -/* Allow machine dependent optimization for post-increment or pre-increment. - Based on testing to date, - Pre-increment preferred for: - - PowerPC G3 (Adler) - - MIPS R5000 (Randers-Pehrson) - Post-increment preferred for: - - none - No measurable difference: - - Pentium III (Anderson) - - M68060 (Nikl) - */ -#ifdef POSTINC -# define OFF 0 -# define PUP(a) *(a)++ +#ifdef ASMINF +# pragma message("Assembler code may have bugs -- use at your own risk") #else -# define OFF 1 -# define PUP(a) *++(a) -#endif /* Decode literal, length, and distance codes and write out the resulting @@ -96,9 +79,9 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ /* copy state to local variables */ state = (struct inflate_state FAR *)strm->state; - in = strm->next_in - OFF; + in = strm->next_in; last = in + (strm->avail_in - 5); - out = strm->next_out - OFF; + out = strm->next_out; beg = out - (start - strm->avail_out); end = out + (strm->avail_out - 257); #ifdef INFLATE_STRICT @@ -119,9 +102,9 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ input data or output space */ do { if (bits < 15) { - hold += (unsigned long)(PUP(in)) << bits; + hold += (unsigned long)(*in++) << bits; bits += 8; - hold += (unsigned long)(PUP(in)) << bits; + hold += (unsigned long)(*in++) << bits; bits += 8; } here = lcode[hold & lmask]; @@ -134,14 +117,14 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ Tracevv((stderr, here.val >= 0x20 && here.val < 0x7f ? "inflate: literal '%c'\n" : "inflate: literal 0x%02x\n", here.val)); - PUP(out) = (unsigned char)(here.val); + *out++ = (unsigned char)(here.val); } else if (op & 16) { /* length base */ len = (unsigned)(here.val); op &= 15; /* number of extra bits */ if (op) { if (bits < op) { - hold += (unsigned long)(PUP(in)) << bits; + hold += (unsigned long)(*in++) << bits; bits += 8; } len += (unsigned)hold & ((1U << op) - 1); @@ -150,9 +133,9 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ } Tracevv((stderr, "inflate: length %u\n", len)); if (bits < 15) { - hold += (unsigned long)(PUP(in)) << bits; + hold += (unsigned long)(*in++) << bits; bits += 8; - hold += (unsigned long)(PUP(in)) << bits; + hold += (unsigned long)(*in++) << bits; bits += 8; } here = dcode[hold & dmask]; @@ -165,10 +148,10 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ dist = (unsigned)(here.val); op &= 15; /* number of extra bits */ if (bits < op) { - hold += (unsigned long)(PUP(in)) << bits; + hold += (unsigned long)(*in++) << bits; bits += 8; if (bits < op) { - hold += (unsigned long)(PUP(in)) << bits; + hold += (unsigned long)(*in++) << bits; bits += 8; } } @@ -196,30 +179,30 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ #ifdef INFLATE_ALLOW_INVALID_DISTANCE_TOOFAR_ARRR if (len <= op - whave) { do { - PUP(out) = 0; + *out++ = 0; } while (--len); continue; } len -= op - whave; do { - PUP(out) = 0; + *out++ = 0; } while (--op > whave); if (op == 0) { from = out - dist; do { - PUP(out) = PUP(from); + *out++ = *from++; } while (--len); continue; } #endif } - from = window - OFF; + from = window; if (wnext == 0) { /* very common case */ from += wsize - op; if (op < len) { /* some from window */ len -= op; do { - PUP(out) = PUP(from); + *out++ = *from++; } while (--op); from = out - dist; /* rest from output */ } @@ -230,14 +213,14 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ if (op < len) { /* some from end of window */ len -= op; do { - PUP(out) = PUP(from); + *out++ = *from++; } while (--op); - from = window - OFF; + from = window; if (wnext < len) { /* some from start of window */ op = wnext; len -= op; do { - PUP(out) = PUP(from); + *out++ = *from++; } while (--op); from = out - dist; /* rest from output */ } @@ -248,35 +231,35 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ if (op < len) { /* some from window */ len -= op; do { - PUP(out) = PUP(from); + *out++ = *from++; } while (--op); from = out - dist; /* rest from output */ } } while (len > 2) { - PUP(out) = PUP(from); - PUP(out) = PUP(from); - PUP(out) = PUP(from); + *out++ = *from++; + *out++ = *from++; + *out++ = *from++; len -= 3; } if (len) { - PUP(out) = PUP(from); + *out++ = *from++; if (len > 1) - PUP(out) = PUP(from); + *out++ = *from++; } } else { from = out - dist; /* copy direct from output */ do { /* minimum length is three */ - PUP(out) = PUP(from); - PUP(out) = PUP(from); - PUP(out) = PUP(from); + *out++ = *from++; + *out++ = *from++; + *out++ = *from++; len -= 3; } while (len > 2); if (len) { - PUP(out) = PUP(from); + *out++ = *from++; if (len > 1) - PUP(out) = PUP(from); + *out++ = *from++; } } } @@ -313,8 +296,8 @@ unsigned start; /* inflate()'s starting value for strm->avail_out */ hold &= (1U << bits) - 1; /* update state and return */ - strm->next_in = in + OFF; - strm->next_out = out + OFF; + strm->next_in = in; + strm->next_out = out; strm->avail_in = (unsigned)(in < last ? 5 + (last - in) : 5 - (in - last)); strm->avail_out = (unsigned)(out < end ? 257 + (end - out) : 257 - (out - end)); diff --git a/Modules/zlib/inflate.c b/Modules/zlib/inflate.c index 870f89bb4d3646..ac333e8c2edae9 100644 --- a/Modules/zlib/inflate.c +++ b/Modules/zlib/inflate.c @@ -1,5 +1,5 @@ /* inflate.c -- zlib decompression - * Copyright (C) 1995-2012 Mark Adler + * Copyright (C) 1995-2016 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -92,6 +92,7 @@ #endif /* function prototypes */ +local int inflateStateCheck OF((z_streamp strm)); local void fixedtables OF((struct inflate_state FAR *state)); local int updatewindow OF((z_streamp strm, const unsigned char FAR *end, unsigned copy)); @@ -101,12 +102,26 @@ local int updatewindow OF((z_streamp strm, const unsigned char FAR *end, local unsigned syncsearch OF((unsigned FAR *have, const unsigned char FAR *buf, unsigned len)); +local int inflateStateCheck(strm) +z_streamp strm; +{ + struct inflate_state FAR *state; + if (strm == Z_NULL || + strm->zalloc == (alloc_func)0 || strm->zfree == (free_func)0) + return 1; + state = (struct inflate_state FAR *)strm->state; + if (state == Z_NULL || state->strm != strm || + state->mode < HEAD || state->mode > SYNC) + return 1; + return 0; +} + int ZEXPORT inflateResetKeep(strm) z_streamp strm; { struct inflate_state FAR *state; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; strm->total_in = strm->total_out = state->total = 0; strm->msg = Z_NULL; @@ -131,7 +146,7 @@ z_streamp strm; { struct inflate_state FAR *state; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; state->wsize = 0; state->whave = 0; @@ -147,7 +162,7 @@ int windowBits; struct inflate_state FAR *state; /* get the state */ - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; /* extract wrap request from windowBits parameter */ @@ -156,7 +171,7 @@ int windowBits; windowBits = -windowBits; } else { - wrap = (windowBits >> 4) + 1; + wrap = (windowBits >> 4) + 5; #ifdef GUNZIP if (windowBits < 48) windowBits &= 15; @@ -210,7 +225,9 @@ int stream_size; if (state == Z_NULL) return Z_MEM_ERROR; Tracev((stderr, "inflate: allocated\n")); strm->state = (struct internal_state FAR *)state; + state->strm = strm; state->window = Z_NULL; + state->mode = HEAD; /* to pass state test in inflateReset2() */ ret = inflateReset2(strm, windowBits); if (ret != Z_OK) { ZFREE(strm, state); @@ -234,17 +251,17 @@ int value; { struct inflate_state FAR *state; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; if (bits < 0) { state->hold = 0; state->bits = 0; return Z_OK; } - if (bits > 16 || state->bits + bits > 32) return Z_STREAM_ERROR; + if (bits > 16 || state->bits + (uInt)bits > 32) return Z_STREAM_ERROR; value &= (1L << bits) - 1; - state->hold += value << state->bits; - state->bits += bits; + state->hold += (unsigned)value << state->bits; + state->bits += (uInt)bits; return Z_OK; } @@ -625,7 +642,7 @@ int flush; static const unsigned short order[19] = /* permutation of code lengths */ {16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15}; - if (strm == Z_NULL || strm->state == Z_NULL || strm->next_out == Z_NULL || + if (inflateStateCheck(strm) || strm->next_out == Z_NULL || (strm->next_in == Z_NULL && strm->avail_in != 0)) return Z_STREAM_ERROR; @@ -645,6 +662,8 @@ int flush; NEEDBITS(16); #ifdef GUNZIP if ((state->wrap & 2) && hold == 0x8b1f) { /* gzip header */ + if (state->wbits == 0) + state->wbits = 15; state->check = crc32(0L, Z_NULL, 0); CRC2(state->check, hold); INITBITS(); @@ -672,7 +691,7 @@ int flush; len = BITS(4) + 8; if (state->wbits == 0) state->wbits = len; - else if (len > state->wbits) { + if (len > 15 || len > state->wbits) { strm->msg = (char *)"invalid window size"; state->mode = BAD; break; @@ -699,14 +718,16 @@ int flush; } if (state->head != Z_NULL) state->head->text = (int)((hold >> 8) & 1); - if (state->flags & 0x0200) CRC2(state->check, hold); + if ((state->flags & 0x0200) && (state->wrap & 4)) + CRC2(state->check, hold); INITBITS(); state->mode = TIME; case TIME: NEEDBITS(32); if (state->head != Z_NULL) state->head->time = hold; - if (state->flags & 0x0200) CRC4(state->check, hold); + if ((state->flags & 0x0200) && (state->wrap & 4)) + CRC4(state->check, hold); INITBITS(); state->mode = OS; case OS: @@ -715,7 +736,8 @@ int flush; state->head->xflags = (int)(hold & 0xff); state->head->os = (int)(hold >> 8); } - if (state->flags & 0x0200) CRC2(state->check, hold); + if ((state->flags & 0x0200) && (state->wrap & 4)) + CRC2(state->check, hold); INITBITS(); state->mode = EXLEN; case EXLEN: @@ -724,7 +746,8 @@ int flush; state->length = (unsigned)(hold); if (state->head != Z_NULL) state->head->extra_len = (unsigned)hold; - if (state->flags & 0x0200) CRC2(state->check, hold); + if ((state->flags & 0x0200) && (state->wrap & 4)) + CRC2(state->check, hold); INITBITS(); } else if (state->head != Z_NULL) @@ -742,7 +765,7 @@ int flush; len + copy > state->head->extra_max ? state->head->extra_max - len : copy); } - if (state->flags & 0x0200) + if ((state->flags & 0x0200) && (state->wrap & 4)) state->check = crc32(state->check, next, copy); have -= copy; next += copy; @@ -761,9 +784,9 @@ int flush; if (state->head != Z_NULL && state->head->name != Z_NULL && state->length < state->head->name_max) - state->head->name[state->length++] = len; + state->head->name[state->length++] = (Bytef)len; } while (len && copy < have); - if (state->flags & 0x0200) + if ((state->flags & 0x0200) && (state->wrap & 4)) state->check = crc32(state->check, next, copy); have -= copy; next += copy; @@ -782,9 +805,9 @@ int flush; if (state->head != Z_NULL && state->head->comment != Z_NULL && state->length < state->head->comm_max) - state->head->comment[state->length++] = len; + state->head->comment[state->length++] = (Bytef)len; } while (len && copy < have); - if (state->flags & 0x0200) + if ((state->flags & 0x0200) && (state->wrap & 4)) state->check = crc32(state->check, next, copy); have -= copy; next += copy; @@ -796,7 +819,7 @@ int flush; case HCRC: if (state->flags & 0x0200) { NEEDBITS(16); - if (hold != (state->check & 0xffff)) { + if ((state->wrap & 4) && hold != (state->check & 0xffff)) { strm->msg = (char *)"header crc mismatch"; state->mode = BAD; break; @@ -1177,11 +1200,11 @@ int flush; out -= left; strm->total_out += out; state->total += out; - if (out) + if ((state->wrap & 4) && out) strm->adler = state->check = UPDATE(state->check, put - out, out); out = left; - if (( + if ((state->wrap & 4) && ( #ifdef GUNZIP state->flags ? hold : #endif @@ -1240,10 +1263,10 @@ int flush; strm->total_in += in; strm->total_out += out; state->total += out; - if (state->wrap && out) + if ((state->wrap & 4) && out) strm->adler = state->check = UPDATE(state->check, strm->next_out - out, out); - strm->data_type = state->bits + (state->last ? 64 : 0) + + strm->data_type = (int)state->bits + (state->last ? 64 : 0) + (state->mode == TYPE ? 128 : 0) + (state->mode == LEN_ || state->mode == COPY_ ? 256 : 0); if (((in == 0 && out == 0) || flush == Z_FINISH) && ret == Z_OK) @@ -1255,7 +1278,7 @@ int ZEXPORT inflateEnd(strm) z_streamp strm; { struct inflate_state FAR *state; - if (strm == Z_NULL || strm->state == Z_NULL || strm->zfree == (free_func)0) + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; if (state->window != Z_NULL) ZFREE(strm, state->window); @@ -1273,7 +1296,7 @@ uInt *dictLength; struct inflate_state FAR *state; /* check state */ - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; /* copy dictionary */ @@ -1298,7 +1321,7 @@ uInt dictLength; int ret; /* check state */ - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; if (state->wrap != 0 && state->mode != DICT) return Z_STREAM_ERROR; @@ -1330,7 +1353,7 @@ gz_headerp head; struct inflate_state FAR *state; /* check state */ - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; if ((state->wrap & 2) == 0) return Z_STREAM_ERROR; @@ -1383,7 +1406,7 @@ z_streamp strm; struct inflate_state FAR *state; /* check parameters */ - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; if (strm->avail_in == 0 && state->bits < 8) return Z_BUF_ERROR; @@ -1430,7 +1453,7 @@ z_streamp strm; { struct inflate_state FAR *state; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; return state->mode == STORED && state->bits == 0; } @@ -1445,8 +1468,7 @@ z_streamp source; unsigned wsize; /* check input */ - if (dest == Z_NULL || source == Z_NULL || source->state == Z_NULL || - source->zalloc == (alloc_func)0 || source->zfree == (free_func)0) + if (inflateStateCheck(source) || dest == Z_NULL) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)source->state; @@ -1467,6 +1489,7 @@ z_streamp source; /* copy state */ zmemcpy((voidpf)dest, (voidpf)source, sizeof(z_stream)); zmemcpy((voidpf)copy, (voidpf)state, sizeof(struct inflate_state)); + copy->strm = dest; if (state->lencode >= state->codes && state->lencode <= state->codes + ENOUGH - 1) { copy->lencode = copy->codes + (state->lencode - state->codes); @@ -1488,25 +1511,51 @@ int subvert; { struct inflate_state FAR *state; - if (strm == Z_NULL || strm->state == Z_NULL) return Z_STREAM_ERROR; + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; state = (struct inflate_state FAR *)strm->state; - state->sane = !subvert; #ifdef INFLATE_ALLOW_INVALID_DISTANCE_TOOFAR_ARRR + state->sane = !subvert; return Z_OK; #else + (void)subvert; state->sane = 1; return Z_DATA_ERROR; #endif } +int ZEXPORT inflateValidate(strm, check) +z_streamp strm; +int check; +{ + struct inflate_state FAR *state; + + if (inflateStateCheck(strm)) return Z_STREAM_ERROR; + state = (struct inflate_state FAR *)strm->state; + if (check) + state->wrap |= 4; + else + state->wrap &= ~4; + return Z_OK; +} + long ZEXPORT inflateMark(strm) z_streamp strm; { struct inflate_state FAR *state; - if (strm == Z_NULL || strm->state == Z_NULL) return -1L << 16; + if (inflateStateCheck(strm)) + return -(1L << 16); state = (struct inflate_state FAR *)strm->state; - return ((long)(state->back) << 16) + + return (long)(((unsigned long)((long)state->back)) << 16) + (state->mode == COPY ? state->length : (state->mode == MATCH ? state->was - state->length : 0)); } + +unsigned long ZEXPORT inflateCodesUsed(strm) +z_streamp strm; +{ + struct inflate_state FAR *state; + if (inflateStateCheck(strm)) return (unsigned long)-1; + state = (struct inflate_state FAR *)strm->state; + return (unsigned long)(state->next - state->codes); +} diff --git a/Modules/zlib/inflate.h b/Modules/zlib/inflate.h index 95f4986d400223..a46cce6b6d05ef 100644 --- a/Modules/zlib/inflate.h +++ b/Modules/zlib/inflate.h @@ -1,5 +1,5 @@ /* inflate.h -- internal inflate state definition - * Copyright (C) 1995-2009 Mark Adler + * Copyright (C) 1995-2016 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -18,7 +18,7 @@ /* Possible inflate modes between inflate() calls */ typedef enum { - HEAD, /* i: waiting for magic header */ + HEAD = 16180, /* i: waiting for magic header */ FLAGS, /* i: waiting for method and flags (gzip) */ TIME, /* i: waiting for modification time (gzip) */ OS, /* i: waiting for extra flags and operating system (gzip) */ @@ -77,11 +77,14 @@ typedef enum { CHECK -> LENGTH -> DONE */ -/* state maintained between inflate() calls. Approximately 10K bytes. */ +/* State maintained between inflate() calls -- approximately 7K bytes, not + including the allocated sliding window, which is up to 32K bytes. */ struct inflate_state { + z_streamp strm; /* pointer back to this zlib stream */ inflate_mode mode; /* current inflate mode */ int last; /* true if processing last block */ - int wrap; /* bit 0 true for zlib, bit 1 true for gzip */ + int wrap; /* bit 0 true for zlib, bit 1 true for gzip, + bit 2 true to validate check value */ int havedict; /* true if dictionary provided */ int flags; /* gzip header method and flags (0 if zlib) */ unsigned dmax; /* zlib header max distance (INFLATE_STRICT) */ diff --git a/Modules/zlib/inftrees.c b/Modules/zlib/inftrees.c index 44d89cf24e1c2a..2ea08fc13ea8ec 100644 --- a/Modules/zlib/inftrees.c +++ b/Modules/zlib/inftrees.c @@ -1,5 +1,5 @@ /* inftrees.c -- generate Huffman trees for efficient decoding - * Copyright (C) 1995-2013 Mark Adler + * Copyright (C) 1995-2017 Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -9,7 +9,7 @@ #define MAXBITS 15 const char inflate_copyright[] = - " inflate 1.2.8 Copyright 1995-2013 Mark Adler "; + " inflate 1.2.11 Copyright 1995-2017 Mark Adler "; /* If you use the zlib library in a product, an acknowledgment is welcome in the documentation of your product. If for some reason you cannot @@ -54,7 +54,7 @@ unsigned short FAR *work; code FAR *next; /* next available space in table */ const unsigned short FAR *base; /* base value table to use */ const unsigned short FAR *extra; /* extra bits table to use */ - int end; /* use base and extra for symbol > end */ + unsigned match; /* use base and extra for symbol >= match */ unsigned short count[MAXBITS+1]; /* number of codes of each length */ unsigned short offs[MAXBITS+1]; /* offsets in table for each length */ static const unsigned short lbase[31] = { /* Length codes 257..285 base */ @@ -62,7 +62,7 @@ unsigned short FAR *work; 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258, 0, 0}; static const unsigned short lext[31] = { /* Length codes 257..285 extra */ 16, 16, 16, 16, 16, 16, 16, 16, 17, 17, 17, 17, 18, 18, 18, 18, - 19, 19, 19, 19, 20, 20, 20, 20, 21, 21, 21, 21, 16, 72, 78}; + 19, 19, 19, 19, 20, 20, 20, 20, 21, 21, 21, 21, 16, 77, 202}; static const unsigned short dbase[32] = { /* Distance codes 0..29 base */ 1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, @@ -181,19 +181,17 @@ unsigned short FAR *work; switch (type) { case CODES: base = extra = work; /* dummy value--not used */ - end = 19; + match = 20; break; case LENS: base = lbase; - base -= 257; extra = lext; - extra -= 257; - end = 256; + match = 257; break; - default: /* DISTS */ + default: /* DISTS */ base = dbase; extra = dext; - end = -1; + match = 0; } /* initialize state for loop */ @@ -216,13 +214,13 @@ unsigned short FAR *work; for (;;) { /* create table entry */ here.bits = (unsigned char)(len - drop); - if ((int)(work[sym]) < end) { + if (work[sym] + 1U < match) { here.op = (unsigned char)0; here.val = work[sym]; } - else if ((int)(work[sym]) > end) { - here.op = (unsigned char)(extra[work[sym]]); - here.val = base[work[sym]]; + else if (work[sym] >= match) { + here.op = (unsigned char)(extra[work[sym] - match]); + here.val = base[work[sym] - match]; } else { here.op = (unsigned char)(32 + 64); /* end of block */ diff --git a/Modules/zlib/trees.c b/Modules/zlib/trees.c index 1fd7759ef004c6..50cf4b4571cfec 100644 --- a/Modules/zlib/trees.c +++ b/Modules/zlib/trees.c @@ -1,5 +1,5 @@ /* trees.c -- output deflated data using Huffman coding - * Copyright (C) 1995-2012 Jean-loup Gailly + * Copyright (C) 1995-2017 Jean-loup Gailly * detect_data_type() function provided freely by Cosmin Truta, 2006 * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -36,7 +36,7 @@ #include "deflate.h" -#ifdef DEBUG +#ifdef ZLIB_DEBUG # include #endif @@ -122,13 +122,13 @@ struct static_tree_desc_s { int max_length; /* max bit length for the codes */ }; -local static_tree_desc static_l_desc = +local const static_tree_desc static_l_desc = {static_ltree, extra_lbits, LITERALS+1, L_CODES, MAX_BITS}; -local static_tree_desc static_d_desc = +local const static_tree_desc static_d_desc = {static_dtree, extra_dbits, 0, D_CODES, MAX_BITS}; -local static_tree_desc static_bl_desc = +local const static_tree_desc static_bl_desc = {(const ct_data *)0, extra_blbits, 0, BL_CODES, MAX_BL_BITS}; /* =========================================================================== @@ -152,18 +152,16 @@ local int detect_data_type OF((deflate_state *s)); local unsigned bi_reverse OF((unsigned value, int length)); local void bi_windup OF((deflate_state *s)); local void bi_flush OF((deflate_state *s)); -local void copy_block OF((deflate_state *s, charf *buf, unsigned len, - int header)); #ifdef GEN_TREES_H local void gen_trees_header OF((void)); #endif -#ifndef DEBUG +#ifndef ZLIB_DEBUG # define send_code(s, c, tree) send_bits(s, tree[c].Code, tree[c].Len) /* Send a code of the given tree. c and tree must not have side effects */ -#else /* DEBUG */ +#else /* !ZLIB_DEBUG */ # define send_code(s, c, tree) \ { if (z_verbose>2) fprintf(stderr,"\ncd %3d ",(c)); \ send_bits(s, tree[c].Code, tree[c].Len); } @@ -182,7 +180,7 @@ local void gen_trees_header OF((void)); * Send a value on a given number of bits. * IN assertion: length <= 16 and value fits in length bits. */ -#ifdef DEBUG +#ifdef ZLIB_DEBUG local void send_bits OF((deflate_state *s, int value, int length)); local void send_bits(s, value, length) @@ -208,12 +206,12 @@ local void send_bits(s, value, length) s->bi_valid += length; } } -#else /* !DEBUG */ +#else /* !ZLIB_DEBUG */ #define send_bits(s, value, length) \ { int len = length;\ if (s->bi_valid > (int)Buf_size - len) {\ - int val = value;\ + int val = (int)value;\ s->bi_buf |= (ush)val << s->bi_valid;\ put_short(s, s->bi_buf);\ s->bi_buf = (ush)val >> (Buf_size - s->bi_valid);\ @@ -223,7 +221,7 @@ local void send_bits(s, value, length) s->bi_valid += len;\ }\ } -#endif /* DEBUG */ +#endif /* ZLIB_DEBUG */ /* the arguments must not have side effects */ @@ -317,7 +315,7 @@ local void tr_static_init() * Genererate the file trees.h describing the static trees. */ #ifdef GEN_TREES_H -# ifndef DEBUG +# ifndef ZLIB_DEBUG # include # endif @@ -394,7 +392,7 @@ void ZLIB_INTERNAL _tr_init(s) s->bi_buf = 0; s->bi_valid = 0; -#ifdef DEBUG +#ifdef ZLIB_DEBUG s->compressed_len = 0L; s->bits_sent = 0L; #endif @@ -522,12 +520,12 @@ local void gen_bitlen(s, desc) xbits = 0; if (n >= base) xbits = extra[n-base]; f = tree[n].Freq; - s->opt_len += (ulg)f * (bits + xbits); - if (stree) s->static_len += (ulg)f * (stree[n].Len + xbits); + s->opt_len += (ulg)f * (unsigned)(bits + xbits); + if (stree) s->static_len += (ulg)f * (unsigned)(stree[n].Len + xbits); } if (overflow == 0) return; - Trace((stderr,"\nbit length overflow\n")); + Tracev((stderr,"\nbit length overflow\n")); /* This happens for example on obj2 and pic of the Calgary corpus */ /* Find the first bit length which could increase: */ @@ -554,9 +552,8 @@ local void gen_bitlen(s, desc) m = s->heap[--h]; if (m > max_code) continue; if ((unsigned) tree[m].Len != (unsigned) bits) { - Trace((stderr,"code %d bits %d->%d\n", m, tree[m].Len, bits)); - s->opt_len += ((long)bits - (long)tree[m].Len) - *(long)tree[m].Freq; + Tracev((stderr,"code %d bits %d->%d\n", m, tree[m].Len, bits)); + s->opt_len += ((ulg)bits - tree[m].Len) * tree[m].Freq; tree[m].Len = (ush)bits; } n--; @@ -578,7 +575,7 @@ local void gen_codes (tree, max_code, bl_count) ushf *bl_count; /* number of codes at each bit length */ { ush next_code[MAX_BITS+1]; /* next code value for each bit length */ - ush code = 0; /* running code value */ + unsigned code = 0; /* running code value */ int bits; /* bit index */ int n; /* code index */ @@ -586,7 +583,8 @@ local void gen_codes (tree, max_code, bl_count) * without bit reversal. */ for (bits = 1; bits <= MAX_BITS; bits++) { - next_code[bits] = code = (code + bl_count[bits-1]) << 1; + code = (code + bl_count[bits-1]) << 1; + next_code[bits] = (ush)code; } /* Check that the bit counts in bl_count are consistent. The last code * must be all ones. @@ -599,7 +597,7 @@ local void gen_codes (tree, max_code, bl_count) int len = tree[n].Len; if (len == 0) continue; /* Now reverse the bits */ - tree[n].Code = bi_reverse(next_code[len]++, len); + tree[n].Code = (ush)bi_reverse(next_code[len]++, len); Tracecv(tree != static_ltree, (stderr,"\nn %3d %c l %2d c %4x (%x) ", n, (isgraph(n) ? n : ' '), len, tree[n].Code, next_code[len]-1)); @@ -821,7 +819,7 @@ local int build_bl_tree(s) if (s->bl_tree[bl_order[max_blindex]].Len != 0) break; } /* Update opt_len to include the bit length tree and counts */ - s->opt_len += 3*(max_blindex+1) + 5+5+4; + s->opt_len += 3*((ulg)max_blindex+1) + 5+5+4; Tracev((stderr, "\ndyn trees: dyn %ld, stat %ld", s->opt_len, s->static_len)); @@ -869,11 +867,17 @@ void ZLIB_INTERNAL _tr_stored_block(s, buf, stored_len, last) int last; /* one if this is the last block for a file */ { send_bits(s, (STORED_BLOCK<<1)+last, 3); /* send block type */ -#ifdef DEBUG + bi_windup(s); /* align on byte boundary */ + put_short(s, (ush)stored_len); + put_short(s, (ush)~stored_len); + zmemcpy(s->pending_buf + s->pending, (Bytef *)buf, stored_len); + s->pending += stored_len; +#ifdef ZLIB_DEBUG s->compressed_len = (s->compressed_len + 3 + 7) & (ulg)~7L; s->compressed_len += (stored_len + 4) << 3; + s->bits_sent += 2*16; + s->bits_sent += stored_len<<3; #endif - copy_block(s, buf, (unsigned)stored_len, 1); /* with header */ } /* =========================================================================== @@ -894,7 +898,7 @@ void ZLIB_INTERNAL _tr_align(s) { send_bits(s, STATIC_TREES<<1, 3); send_code(s, END_BLOCK, static_ltree); -#ifdef DEBUG +#ifdef ZLIB_DEBUG s->compressed_len += 10L; /* 3 for block type, 7 for EOB */ #endif bi_flush(s); @@ -902,7 +906,7 @@ void ZLIB_INTERNAL _tr_align(s) /* =========================================================================== * Determine the best encoding for the current block: dynamic trees, static - * trees or store, and output the encoded block to the zip file. + * trees or store, and write out the encoded block. */ void ZLIB_INTERNAL _tr_flush_block(s, buf, stored_len, last) deflate_state *s; @@ -974,7 +978,7 @@ void ZLIB_INTERNAL _tr_flush_block(s, buf, stored_len, last) send_bits(s, (STATIC_TREES<<1)+last, 3); compress_block(s, (const ct_data *)static_ltree, (const ct_data *)static_dtree); -#ifdef DEBUG +#ifdef ZLIB_DEBUG s->compressed_len += 3 + s->static_len; #endif } else { @@ -983,7 +987,7 @@ void ZLIB_INTERNAL _tr_flush_block(s, buf, stored_len, last) max_blindex+1); compress_block(s, (const ct_data *)s->dyn_ltree, (const ct_data *)s->dyn_dtree); -#ifdef DEBUG +#ifdef ZLIB_DEBUG s->compressed_len += 3 + s->opt_len; #endif } @@ -995,7 +999,7 @@ void ZLIB_INTERNAL _tr_flush_block(s, buf, stored_len, last) if (last) { bi_windup(s); -#ifdef DEBUG +#ifdef ZLIB_DEBUG s->compressed_len += 7; /* align on byte boundary */ #endif } @@ -1090,7 +1094,7 @@ local void compress_block(s, ltree, dtree) send_code(s, code, dtree); /* send the distance code */ extra = extra_dbits[code]; if (extra != 0) { - dist -= base_dist[code]; + dist -= (unsigned)base_dist[code]; send_bits(s, dist, extra); /* send the extra distance bits */ } } /* literal or match pair ? */ @@ -1193,34 +1197,7 @@ local void bi_windup(s) } s->bi_buf = 0; s->bi_valid = 0; -#ifdef DEBUG +#ifdef ZLIB_DEBUG s->bits_sent = (s->bits_sent+7) & ~7; #endif } - -/* =========================================================================== - * Copy a stored block, storing first the length and its - * one's complement if requested. - */ -local void copy_block(s, buf, len, header) - deflate_state *s; - charf *buf; /* the input data */ - unsigned len; /* its length */ - int header; /* true if block header must be written */ -{ - bi_windup(s); /* align on byte boundary */ - - if (header) { - put_short(s, (ush)len); - put_short(s, (ush)~len); -#ifdef DEBUG - s->bits_sent += 2*16; -#endif - } -#ifdef DEBUG - s->bits_sent += (ulg)len<<3; -#endif - while (len--) { - put_byte(s, *buf++); - } -} diff --git a/Modules/zlib/uncompr.c b/Modules/zlib/uncompr.c index 242e9493dff5c2..f03a1a865e347d 100644 --- a/Modules/zlib/uncompr.c +++ b/Modules/zlib/uncompr.c @@ -1,5 +1,5 @@ /* uncompr.c -- decompress a memory buffer - * Copyright (C) 1995-2003, 2010 Jean-loup Gailly. + * Copyright (C) 1995-2003, 2010, 2014, 2016 Jean-loup Gailly, Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -9,51 +9,85 @@ #include "zlib.h" /* =========================================================================== - Decompresses the source buffer into the destination buffer. sourceLen is - the byte length of the source buffer. Upon entry, destLen is the total - size of the destination buffer, which must be large enough to hold the - entire uncompressed data. (The size of the uncompressed data must have - been saved previously by the compressor and transmitted to the decompressor - by some mechanism outside the scope of this compression library.) - Upon exit, destLen is the actual size of the compressed buffer. - - uncompress returns Z_OK if success, Z_MEM_ERROR if there was not - enough memory, Z_BUF_ERROR if there was not enough room in the output - buffer, or Z_DATA_ERROR if the input data was corrupted. + Decompresses the source buffer into the destination buffer. *sourceLen is + the byte length of the source buffer. Upon entry, *destLen is the total size + of the destination buffer, which must be large enough to hold the entire + uncompressed data. (The size of the uncompressed data must have been saved + previously by the compressor and transmitted to the decompressor by some + mechanism outside the scope of this compression library.) Upon exit, + *destLen is the size of the decompressed data and *sourceLen is the number + of source bytes consumed. Upon return, source + *sourceLen points to the + first unused input byte. + + uncompress returns Z_OK if success, Z_MEM_ERROR if there was not enough + memory, Z_BUF_ERROR if there was not enough room in the output buffer, or + Z_DATA_ERROR if the input data was corrupted, including if the input data is + an incomplete zlib stream. */ -int ZEXPORT uncompress (dest, destLen, source, sourceLen) +int ZEXPORT uncompress2 (dest, destLen, source, sourceLen) Bytef *dest; uLongf *destLen; const Bytef *source; - uLong sourceLen; + uLong *sourceLen; { z_stream stream; int err; + const uInt max = (uInt)-1; + uLong len, left; + Byte buf[1]; /* for detection of incomplete stream when *destLen == 0 */ - stream.next_in = (z_const Bytef *)source; - stream.avail_in = (uInt)sourceLen; - /* Check for source > 64K on 16-bit machine: */ - if ((uLong)stream.avail_in != sourceLen) return Z_BUF_ERROR; - - stream.next_out = dest; - stream.avail_out = (uInt)*destLen; - if ((uLong)stream.avail_out != *destLen) return Z_BUF_ERROR; + len = *sourceLen; + if (*destLen) { + left = *destLen; + *destLen = 0; + } + else { + left = 1; + dest = buf; + } + stream.next_in = (z_const Bytef *)source; + stream.avail_in = 0; stream.zalloc = (alloc_func)0; stream.zfree = (free_func)0; + stream.opaque = (voidpf)0; err = inflateInit(&stream); if (err != Z_OK) return err; - err = inflate(&stream, Z_FINISH); - if (err != Z_STREAM_END) { - inflateEnd(&stream); - if (err == Z_NEED_DICT || (err == Z_BUF_ERROR && stream.avail_in == 0)) - return Z_DATA_ERROR; - return err; - } - *destLen = stream.total_out; + stream.next_out = dest; + stream.avail_out = 0; - err = inflateEnd(&stream); - return err; + do { + if (stream.avail_out == 0) { + stream.avail_out = left > (uLong)max ? max : (uInt)left; + left -= stream.avail_out; + } + if (stream.avail_in == 0) { + stream.avail_in = len > (uLong)max ? max : (uInt)len; + len -= stream.avail_in; + } + err = inflate(&stream, Z_NO_FLUSH); + } while (err == Z_OK); + + *sourceLen -= len + stream.avail_in; + if (dest != buf) + *destLen = stream.total_out; + else if (stream.total_out && err == Z_BUF_ERROR) + left = 1; + + inflateEnd(&stream); + return err == Z_STREAM_END ? Z_OK : + err == Z_NEED_DICT ? Z_DATA_ERROR : + err == Z_BUF_ERROR && left + stream.avail_out ? Z_DATA_ERROR : + err; +} + +int ZEXPORT uncompress (dest, destLen, source, sourceLen) + Bytef *dest; + uLongf *destLen; + const Bytef *source; + uLong sourceLen; +{ + return uncompress2(dest, destLen, source, &sourceLen); } diff --git a/Modules/zlib/zconf.h b/Modules/zlib/zconf.h index 9987a775530c03..5e1d68a004e974 100644 --- a/Modules/zlib/zconf.h +++ b/Modules/zlib/zconf.h @@ -1,5 +1,5 @@ /* zconf.h -- configuration of the zlib compression library - * Copyright (C) 1995-2013 Jean-loup Gailly. + * Copyright (C) 1995-2016 Jean-loup Gailly, Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -17,7 +17,7 @@ #ifdef Z_PREFIX /* may be set to #if 1 by ./configure */ # define Z_PREFIX_SET -/* all linked symbols */ +/* all linked symbols and init macros */ # define _dist_code z__dist_code # define _length_code z__length_code # define _tr_align z__tr_align @@ -29,6 +29,7 @@ # define adler32 z_adler32 # define adler32_combine z_adler32_combine # define adler32_combine64 z_adler32_combine64 +# define adler32_z z_adler32_z # ifndef Z_SOLO # define compress z_compress # define compress2 z_compress2 @@ -37,10 +38,14 @@ # define crc32 z_crc32 # define crc32_combine z_crc32_combine # define crc32_combine64 z_crc32_combine64 +# define crc32_z z_crc32_z # define deflate z_deflate # define deflateBound z_deflateBound # define deflateCopy z_deflateCopy # define deflateEnd z_deflateEnd +# define deflateGetDictionary z_deflateGetDictionary +# define deflateInit z_deflateInit +# define deflateInit2 z_deflateInit2 # define deflateInit2_ z_deflateInit2_ # define deflateInit_ z_deflateInit_ # define deflateParams z_deflateParams @@ -67,6 +72,8 @@ # define gzeof z_gzeof # define gzerror z_gzerror # define gzflush z_gzflush +# define gzfread z_gzfread +# define gzfwrite z_gzfwrite # define gzgetc z_gzgetc # define gzgetc_ z_gzgetc_ # define gzgets z_gzgets @@ -78,7 +85,6 @@ # define gzopen_w z_gzopen_w # endif # define gzprintf z_gzprintf -# define gzvprintf z_gzvprintf # define gzputc z_gzputc # define gzputs z_gzputs # define gzread z_gzread @@ -89,32 +95,39 @@ # define gztell z_gztell # define gztell64 z_gztell64 # define gzungetc z_gzungetc +# define gzvprintf z_gzvprintf # define gzwrite z_gzwrite # endif # define inflate z_inflate # define inflateBack z_inflateBack # define inflateBackEnd z_inflateBackEnd +# define inflateBackInit z_inflateBackInit # define inflateBackInit_ z_inflateBackInit_ +# define inflateCodesUsed z_inflateCodesUsed # define inflateCopy z_inflateCopy # define inflateEnd z_inflateEnd +# define inflateGetDictionary z_inflateGetDictionary # define inflateGetHeader z_inflateGetHeader +# define inflateInit z_inflateInit +# define inflateInit2 z_inflateInit2 # define inflateInit2_ z_inflateInit2_ # define inflateInit_ z_inflateInit_ # define inflateMark z_inflateMark # define inflatePrime z_inflatePrime # define inflateReset z_inflateReset # define inflateReset2 z_inflateReset2 +# define inflateResetKeep z_inflateResetKeep # define inflateSetDictionary z_inflateSetDictionary -# define inflateGetDictionary z_inflateGetDictionary # define inflateSync z_inflateSync # define inflateSyncPoint z_inflateSyncPoint # define inflateUndermine z_inflateUndermine -# define inflateResetKeep z_inflateResetKeep +# define inflateValidate z_inflateValidate # define inflate_copyright z_inflate_copyright # define inflate_fast z_inflate_fast # define inflate_table z_inflate_table # ifndef Z_SOLO # define uncompress z_uncompress +# define uncompress2 z_uncompress2 # endif # define zError z_zError # ifndef Z_SOLO @@ -224,9 +237,19 @@ # define z_const #endif -/* Some Mac compilers merge all .h files incorrectly: */ -#if defined(__MWERKS__)||defined(applec)||defined(THINK_C)||defined(__SC__) -# define NO_DUMMY_DECL +#ifdef Z_SOLO + typedef unsigned long z_size_t; +#else +# define z_longlong long long +# if defined(NO_SIZE_T) + typedef unsigned NO_SIZE_T z_size_t; +# elif defined(STDC) +# include + typedef size_t z_size_t; +# else + typedef unsigned long z_size_t; +# endif +# undef z_longlong #endif /* Maximum value for memLevel in deflateInit2 */ @@ -256,7 +279,7 @@ Of course this will generally degrade compression (there's no free lunch). The memory requirements for inflate are (in bytes) 1 << windowBits - that is, 32K for windowBits=15 (default value) plus a few kilobytes + that is, 32K for windowBits=15 (default value) plus about 7 kilobytes for small objects. */ diff --git a/Modules/zlib/zconf.h.cmakein b/Modules/zlib/zconf.h.cmakein index 043019cda1db5e..a7f24cce60ff7a 100644 --- a/Modules/zlib/zconf.h.cmakein +++ b/Modules/zlib/zconf.h.cmakein @@ -1,5 +1,5 @@ /* zconf.h -- configuration of the zlib compression library - * Copyright (C) 1995-2013 Jean-loup Gailly. + * Copyright (C) 1995-2016 Jean-loup Gailly, Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -19,7 +19,7 @@ #ifdef Z_PREFIX /* may be set to #if 1 by ./configure */ # define Z_PREFIX_SET -/* all linked symbols */ +/* all linked symbols and init macros */ # define _dist_code z__dist_code # define _length_code z__length_code # define _tr_align z__tr_align @@ -31,6 +31,7 @@ # define adler32 z_adler32 # define adler32_combine z_adler32_combine # define adler32_combine64 z_adler32_combine64 +# define adler32_z z_adler32_z # ifndef Z_SOLO # define compress z_compress # define compress2 z_compress2 @@ -39,10 +40,14 @@ # define crc32 z_crc32 # define crc32_combine z_crc32_combine # define crc32_combine64 z_crc32_combine64 +# define crc32_z z_crc32_z # define deflate z_deflate # define deflateBound z_deflateBound # define deflateCopy z_deflateCopy # define deflateEnd z_deflateEnd +# define deflateGetDictionary z_deflateGetDictionary +# define deflateInit z_deflateInit +# define deflateInit2 z_deflateInit2 # define deflateInit2_ z_deflateInit2_ # define deflateInit_ z_deflateInit_ # define deflateParams z_deflateParams @@ -69,6 +74,8 @@ # define gzeof z_gzeof # define gzerror z_gzerror # define gzflush z_gzflush +# define gzfread z_gzfread +# define gzfwrite z_gzfwrite # define gzgetc z_gzgetc # define gzgetc_ z_gzgetc_ # define gzgets z_gzgets @@ -80,7 +87,6 @@ # define gzopen_w z_gzopen_w # endif # define gzprintf z_gzprintf -# define gzvprintf z_gzvprintf # define gzputc z_gzputc # define gzputs z_gzputs # define gzread z_gzread @@ -91,32 +97,39 @@ # define gztell z_gztell # define gztell64 z_gztell64 # define gzungetc z_gzungetc +# define gzvprintf z_gzvprintf # define gzwrite z_gzwrite # endif # define inflate z_inflate # define inflateBack z_inflateBack # define inflateBackEnd z_inflateBackEnd +# define inflateBackInit z_inflateBackInit # define inflateBackInit_ z_inflateBackInit_ +# define inflateCodesUsed z_inflateCodesUsed # define inflateCopy z_inflateCopy # define inflateEnd z_inflateEnd +# define inflateGetDictionary z_inflateGetDictionary # define inflateGetHeader z_inflateGetHeader +# define inflateInit z_inflateInit +# define inflateInit2 z_inflateInit2 # define inflateInit2_ z_inflateInit2_ # define inflateInit_ z_inflateInit_ # define inflateMark z_inflateMark # define inflatePrime z_inflatePrime # define inflateReset z_inflateReset # define inflateReset2 z_inflateReset2 +# define inflateResetKeep z_inflateResetKeep # define inflateSetDictionary z_inflateSetDictionary -# define inflateGetDictionary z_inflateGetDictionary # define inflateSync z_inflateSync # define inflateSyncPoint z_inflateSyncPoint # define inflateUndermine z_inflateUndermine -# define inflateResetKeep z_inflateResetKeep +# define inflateValidate z_inflateValidate # define inflate_copyright z_inflate_copyright # define inflate_fast z_inflate_fast # define inflate_table z_inflate_table # ifndef Z_SOLO # define uncompress z_uncompress +# define uncompress2 z_uncompress2 # endif # define zError z_zError # ifndef Z_SOLO @@ -226,9 +239,19 @@ # define z_const #endif -/* Some Mac compilers merge all .h files incorrectly: */ -#if defined(__MWERKS__)||defined(applec)||defined(THINK_C)||defined(__SC__) -# define NO_DUMMY_DECL +#ifdef Z_SOLO + typedef unsigned long z_size_t; +#else +# define z_longlong long long +# if defined(NO_SIZE_T) + typedef unsigned NO_SIZE_T z_size_t; +# elif defined(STDC) +# include + typedef size_t z_size_t; +# else + typedef unsigned long z_size_t; +# endif +# undef z_longlong #endif /* Maximum value for memLevel in deflateInit2 */ @@ -258,7 +281,7 @@ Of course this will generally degrade compression (there's no free lunch). The memory requirements for inflate are (in bytes) 1 << windowBits - that is, 32K for windowBits=15 (default value) plus a few kilobytes + that is, 32K for windowBits=15 (default value) plus about 7 kilobytes for small objects. */ diff --git a/Modules/zlib/zconf.h.in b/Modules/zlib/zconf.h.in index 9987a775530c03..5e1d68a004e974 100644 --- a/Modules/zlib/zconf.h.in +++ b/Modules/zlib/zconf.h.in @@ -1,5 +1,5 @@ /* zconf.h -- configuration of the zlib compression library - * Copyright (C) 1995-2013 Jean-loup Gailly. + * Copyright (C) 1995-2016 Jean-loup Gailly, Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -17,7 +17,7 @@ #ifdef Z_PREFIX /* may be set to #if 1 by ./configure */ # define Z_PREFIX_SET -/* all linked symbols */ +/* all linked symbols and init macros */ # define _dist_code z__dist_code # define _length_code z__length_code # define _tr_align z__tr_align @@ -29,6 +29,7 @@ # define adler32 z_adler32 # define adler32_combine z_adler32_combine # define adler32_combine64 z_adler32_combine64 +# define adler32_z z_adler32_z # ifndef Z_SOLO # define compress z_compress # define compress2 z_compress2 @@ -37,10 +38,14 @@ # define crc32 z_crc32 # define crc32_combine z_crc32_combine # define crc32_combine64 z_crc32_combine64 +# define crc32_z z_crc32_z # define deflate z_deflate # define deflateBound z_deflateBound # define deflateCopy z_deflateCopy # define deflateEnd z_deflateEnd +# define deflateGetDictionary z_deflateGetDictionary +# define deflateInit z_deflateInit +# define deflateInit2 z_deflateInit2 # define deflateInit2_ z_deflateInit2_ # define deflateInit_ z_deflateInit_ # define deflateParams z_deflateParams @@ -67,6 +72,8 @@ # define gzeof z_gzeof # define gzerror z_gzerror # define gzflush z_gzflush +# define gzfread z_gzfread +# define gzfwrite z_gzfwrite # define gzgetc z_gzgetc # define gzgetc_ z_gzgetc_ # define gzgets z_gzgets @@ -78,7 +85,6 @@ # define gzopen_w z_gzopen_w # endif # define gzprintf z_gzprintf -# define gzvprintf z_gzvprintf # define gzputc z_gzputc # define gzputs z_gzputs # define gzread z_gzread @@ -89,32 +95,39 @@ # define gztell z_gztell # define gztell64 z_gztell64 # define gzungetc z_gzungetc +# define gzvprintf z_gzvprintf # define gzwrite z_gzwrite # endif # define inflate z_inflate # define inflateBack z_inflateBack # define inflateBackEnd z_inflateBackEnd +# define inflateBackInit z_inflateBackInit # define inflateBackInit_ z_inflateBackInit_ +# define inflateCodesUsed z_inflateCodesUsed # define inflateCopy z_inflateCopy # define inflateEnd z_inflateEnd +# define inflateGetDictionary z_inflateGetDictionary # define inflateGetHeader z_inflateGetHeader +# define inflateInit z_inflateInit +# define inflateInit2 z_inflateInit2 # define inflateInit2_ z_inflateInit2_ # define inflateInit_ z_inflateInit_ # define inflateMark z_inflateMark # define inflatePrime z_inflatePrime # define inflateReset z_inflateReset # define inflateReset2 z_inflateReset2 +# define inflateResetKeep z_inflateResetKeep # define inflateSetDictionary z_inflateSetDictionary -# define inflateGetDictionary z_inflateGetDictionary # define inflateSync z_inflateSync # define inflateSyncPoint z_inflateSyncPoint # define inflateUndermine z_inflateUndermine -# define inflateResetKeep z_inflateResetKeep +# define inflateValidate z_inflateValidate # define inflate_copyright z_inflate_copyright # define inflate_fast z_inflate_fast # define inflate_table z_inflate_table # ifndef Z_SOLO # define uncompress z_uncompress +# define uncompress2 z_uncompress2 # endif # define zError z_zError # ifndef Z_SOLO @@ -224,9 +237,19 @@ # define z_const #endif -/* Some Mac compilers merge all .h files incorrectly: */ -#if defined(__MWERKS__)||defined(applec)||defined(THINK_C)||defined(__SC__) -# define NO_DUMMY_DECL +#ifdef Z_SOLO + typedef unsigned long z_size_t; +#else +# define z_longlong long long +# if defined(NO_SIZE_T) + typedef unsigned NO_SIZE_T z_size_t; +# elif defined(STDC) +# include + typedef size_t z_size_t; +# else + typedef unsigned long z_size_t; +# endif +# undef z_longlong #endif /* Maximum value for memLevel in deflateInit2 */ @@ -256,7 +279,7 @@ Of course this will generally degrade compression (there's no free lunch). The memory requirements for inflate are (in bytes) 1 << windowBits - that is, 32K for windowBits=15 (default value) plus a few kilobytes + that is, 32K for windowBits=15 (default value) plus about 7 kilobytes for small objects. */ diff --git a/Modules/zlib/zlib.3 b/Modules/zlib/zlib.3 index 0160e62b69f419..bda4eb0737090c 100644 --- a/Modules/zlib/zlib.3 +++ b/Modules/zlib/zlib.3 @@ -1,4 +1,4 @@ -.TH ZLIB 3 "28 Apr 2013" +.TH ZLIB 3 "15 Jan 2017" .SH NAME zlib \- compression/decompression library .SH SYNOPSIS @@ -48,32 +48,10 @@ Changes to this version are documented in the file that accompanies the source. .LP .I zlib -is available in Java using the java.util.zip package: -.IP -http://java.sun.com/developer/technicalArticles/Programming/compression/ -.LP -A Perl interface to -.IR zlib , -written by Paul Marquess (pmqs@cpan.org), -is available at CPAN (Comprehensive Perl Archive Network) sites, -including: -.IP -http://search.cpan.org/~pmqs/IO-Compress-Zlib/ -.LP -A Python interface to -.IR zlib , -written by A.M. Kuchling (amk@magnet.com), -is available in Python 1.5 and later versions: -.IP -http://docs.python.org/library/zlib.html -.LP -.I zlib -is built into -.IR tcl: -.IP -http://wiki.tcl.tk/4610 +is built in to many languages and operating systems, including but not limited to +Java, Python, .NET, PHP, Perl, Ruby, Swift, and Go. .LP -An experimental package to read and write files in .zip format, +An experimental package to read and write files in the .zip format, written on top of .I zlib by Gilles Vollant (info@winimage.com), @@ -92,7 +70,9 @@ web site can be found at: .IP http://zlib.net/ .LP -The data format used by the zlib library is described by RFC +The data format used by the +.I zlib +library is described by RFC (Request for Comments) 1950 to 1952 in the files: .IP http://tools.ietf.org/html/rfc1950 (for the zlib header and trailer format) @@ -124,17 +104,35 @@ http://zlib.net/zlib_faq.html before asking for help. Send questions and/or comments to zlib@gzip.org, or (for the Windows DLL version) to Gilles Vollant (info@winimage.com). -.SH AUTHORS -Version 1.2.8 -Copyright (C) 1995-2013 Jean-loup Gailly (jloup@gzip.org) -and Mark Adler (madler@alumni.caltech.edu). -.LP -This software is provided "as-is," -without any express or implied warranty. -In no event will the authors be held liable for any damages +.SH AUTHORS AND LICENSE +Version 1.2.11 +.LP +Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler +.LP +This software is provided 'as-is', without any express or implied +warranty. In no event will the authors be held liable for any damages arising from the use of this software. -See the distribution directory with respect to requirements -governing redistribution. +.LP +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: +.LP +.nr step 1 1 +.IP \n[step]. 3 +The origin of this software must not be misrepresented; you must not +claim that you wrote the original software. If you use this software +in a product, an acknowledgment in the product documentation would be +appreciated but is not required. +.IP \n+[step]. +Altered source versions must be plainly marked as such, and must not be +misrepresented as being the original software. +.IP \n+[step]. +This notice may not be removed or altered from any source distribution. +.LP +Jean-loup Gailly Mark Adler +.br +jloup@gzip.org madler@alumni.caltech.edu +.LP The deflate format used by .I zlib was defined by Phil Katz. diff --git a/Modules/zlib/zlib.h b/Modules/zlib/zlib.h index 3e0c7672ac51d9..f09cdaf1e0543d 100644 --- a/Modules/zlib/zlib.h +++ b/Modules/zlib/zlib.h @@ -1,7 +1,7 @@ /* zlib.h -- interface of the 'zlib' general purpose compression library - version 1.2.8, April 28th, 2013 + version 1.2.11, January 15th, 2017 - Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler + Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -37,11 +37,11 @@ extern "C" { #endif -#define ZLIB_VERSION "1.2.8" -#define ZLIB_VERNUM 0x1280 +#define ZLIB_VERSION "1.2.11" +#define ZLIB_VERNUM 0x12b0 #define ZLIB_VER_MAJOR 1 #define ZLIB_VER_MINOR 2 -#define ZLIB_VER_REVISION 8 +#define ZLIB_VER_REVISION 11 #define ZLIB_VER_SUBREVISION 0 /* @@ -65,7 +65,8 @@ extern "C" { with "gz". The gzip format is different from the zlib format. gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. - This library can optionally read and write gzip streams in memory as well. + This library can optionally read and write gzip and raw deflate streams in + memory as well. The zlib format was designed to be compact and fast for use in memory and on communications channels. The gzip format was designed for single- @@ -74,7 +75,7 @@ extern "C" { The library does not install any signal handler. The decoder checks the consistency of the compressed data, so the library should never crash - even in case of corrupted input. + even in the case of corrupted input. */ typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); @@ -87,7 +88,7 @@ typedef struct z_stream_s { uInt avail_in; /* number of bytes available at next_in */ uLong total_in; /* total number of input bytes read so far */ - Bytef *next_out; /* next output byte should be put there */ + Bytef *next_out; /* next output byte will go here */ uInt avail_out; /* remaining free space at next_out */ uLong total_out; /* total number of bytes output so far */ @@ -98,8 +99,9 @@ typedef struct z_stream_s { free_func zfree; /* used to free the internal state */ voidpf opaque; /* private data object passed to zalloc and zfree */ - int data_type; /* best guess about the data type: binary or text */ - uLong adler; /* adler32 value of the uncompressed data */ + int data_type; /* best guess about the data type: binary or text + for deflate, or the decoding state for inflate */ + uLong adler; /* Adler-32 or CRC-32 value of the uncompressed data */ uLong reserved; /* reserved for future use */ } z_stream; @@ -142,7 +144,9 @@ typedef gz_header FAR *gz_headerp; zalloc must return Z_NULL if there is not enough memory for the object. If zlib is used in a multi-threaded application, zalloc and zfree must be - thread safe. + thread safe. In that case, zlib is thread-safe. When zalloc and zfree are + Z_NULL on entry to the initialization function, they are set to internal + routines that use the standard library functions malloc() and free(). On 16-bit systems, the functions zalloc and zfree must be able to allocate exactly 65536 bytes, but will not be required to allocate more than this if @@ -155,7 +159,7 @@ typedef gz_header FAR *gz_headerp; The fields total_in and total_out can be used for statistics or progress reports. After compression, total_in holds the total size of the - uncompressed data and may be saved for use in the decompressor (particularly + uncompressed data and may be saved for use by the decompressor (particularly if the decompressor wants to decompress everything in a single step). */ @@ -200,7 +204,7 @@ typedef gz_header FAR *gz_headerp; #define Z_TEXT 1 #define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ #define Z_UNKNOWN 2 -/* Possible values of the data_type field (though see inflate()) */ +/* Possible values of the data_type field for deflate() */ #define Z_DEFLATED 8 /* The deflate compression method (the only one supported in this version) */ @@ -258,11 +262,11 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); enough room in the output buffer), next_in and avail_in are updated and processing will resume at this point for the next call of deflate(). - - Provide more output starting at next_out and update next_out and avail_out + - Generate more output starting at next_out and update next_out and avail_out accordingly. This action is forced if the parameter flush is non zero. Forcing flush frequently degrades the compression ratio, so this parameter - should be set only when necessary (in interactive applications). Some - output may be provided even if flush is not set. + should be set only when necessary. Some output may be provided even if + flush is zero. Before the call of deflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more @@ -271,7 +275,9 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); output when it wants, for example when the output buffer is full (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK and with zero avail_out, it must be called again after making room in the output - buffer because there might be more output pending. + buffer because there might be more output pending. See deflatePending(), + which can be used if desired to determine whether or not there is more ouput + in that case. Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to decide how much data to accumulate before producing output, in order to @@ -292,8 +298,8 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); input data so far will be available to the decompressor, as for Z_SYNC_FLUSH. This completes the current deflate block and follows it with an empty fixed codes block that is 10 bits long. This assures that enough bytes are output - in order for the decompressor to finish the block before the empty fixed code - block. + in order for the decompressor to finish the block before the empty fixed + codes block. If flush is set to Z_BLOCK, a deflate block is completed and emitted, as for Z_SYNC_FLUSH, but the output is not aligned on a byte boundary, and up to @@ -319,34 +325,38 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); If the parameter flush is set to Z_FINISH, pending input is processed, pending output is flushed and deflate returns with Z_STREAM_END if there was - enough output space; if deflate returns with Z_OK, this function must be - called again with Z_FINISH and more output space (updated avail_out) but no - more input data, until it returns with Z_STREAM_END or an error. After - deflate has returned Z_STREAM_END, the only possible operations on the stream - are deflateReset or deflateEnd. - - Z_FINISH can be used immediately after deflateInit if all the compression - is to be done in a single step. In this case, avail_out must be at least the - value returned by deflateBound (see below). Then deflate is guaranteed to - return Z_STREAM_END. If not enough output space is provided, deflate will - not return Z_STREAM_END, and it must be called again as described above. - - deflate() sets strm->adler to the adler32 checksum of all input read - so far (that is, total_in bytes). + enough output space. If deflate returns with Z_OK or Z_BUF_ERROR, this + function must be called again with Z_FINISH and more output space (updated + avail_out) but no more input data, until it returns with Z_STREAM_END or an + error. After deflate has returned Z_STREAM_END, the only possible operations + on the stream are deflateReset or deflateEnd. + + Z_FINISH can be used in the first deflate call after deflateInit if all the + compression is to be done in a single step. In order to complete in one + call, avail_out must be at least the value returned by deflateBound (see + below). Then deflate is guaranteed to return Z_STREAM_END. If not enough + output space is provided, deflate will not return Z_STREAM_END, and it must + be called again as described above. + + deflate() sets strm->adler to the Adler-32 checksum of all input read + so far (that is, total_in bytes). If a gzip stream is being generated, then + strm->adler will be the CRC-32 checksum of the input read so far. (See + deflateInit2 below.) deflate() may update strm->data_type if it can make a good guess about - the input data type (Z_BINARY or Z_TEXT). In doubt, the data is considered - binary. This field is only for information purposes and does not affect the - compression algorithm in any manner. + the input data type (Z_BINARY or Z_TEXT). If in doubt, the data is + considered binary. This field is only for information purposes and does not + affect the compression algorithm in any manner. deflate() returns Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if all input has been consumed and all output has been produced (only when flush is set to Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example - if next_in or next_out was Z_NULL), Z_BUF_ERROR if no progress is possible - (for example avail_in or avail_out was zero). Note that Z_BUF_ERROR is not - fatal, and deflate() can be called again with more input and more output - space to continue compressing. + if next_in or next_out was Z_NULL or the state was inadvertently written over + by the application), or Z_BUF_ERROR if no progress is possible (for example + avail_in or avail_out was zero). Note that Z_BUF_ERROR is not fatal, and + deflate() can be called again with more input and more output space to + continue compressing. */ @@ -369,23 +379,21 @@ ZEXTERN int ZEXPORT inflateInit OF((z_streamp strm)); Initializes the internal stream state for decompression. The fields next_in, avail_in, zalloc, zfree and opaque must be initialized before by - the caller. If next_in is not Z_NULL and avail_in is large enough (the - exact value depends on the compression method), inflateInit determines the - compression method from the zlib header and allocates all data structures - accordingly; otherwise the allocation will be deferred to the first call of - inflate. If zalloc and zfree are set to Z_NULL, inflateInit updates them to - use default allocation functions. + the caller. In the current version of inflate, the provided input is not + read or consumed. The allocation of a sliding window will be deferred to + the first call of inflate (if the decompression does not complete on the + first call). If zalloc and zfree are set to Z_NULL, inflateInit updates + them to use default allocation functions. inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_VERSION_ERROR if the zlib library version is incompatible with the version assumed by the caller, or Z_STREAM_ERROR if the parameters are invalid, such as a null pointer to the structure. msg is set to null if - there is no error message. inflateInit does not perform any decompression - apart from possibly reading the zlib header if present: actual decompression - will be done by inflate(). (So next_in and avail_in may be modified, but - next_out and avail_out are unused and unchanged.) The current implementation - of inflateInit() does not process any header information -- that is deferred - until inflate() is called. + there is no error message. inflateInit does not perform any decompression. + Actual decompression will be done by inflate(). So next_in, and avail_in, + next_out, and avail_out are unused and unchanged. The current + implementation of inflateInit() does not process any header information -- + that is deferred until inflate() is called. */ @@ -401,17 +409,20 @@ ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); - Decompress more input starting at next_in and update next_in and avail_in accordingly. If not all input can be processed (because there is not - enough room in the output buffer), next_in is updated and processing will - resume at this point for the next call of inflate(). + enough room in the output buffer), then next_in and avail_in are updated + accordingly, and processing will resume at this point for the next call of + inflate(). - - Provide more output starting at next_out and update next_out and avail_out + - Generate more output starting at next_out and update next_out and avail_out accordingly. inflate() provides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter). Before the call of inflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more - output, and updating the next_* and avail_* values accordingly. The + output, and updating the next_* and avail_* values accordingly. If the + caller of inflate() does not provide both available input and available + output space, it is possible that there will be no progress made. The application can consume the uncompressed output when it wants, for example when the output buffer is full (avail_out == 0), or after each call of inflate(). If inflate returns Z_OK and with zero avail_out, it must be @@ -428,7 +439,7 @@ ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); gets to the end of that block, or when it runs out of data. The Z_BLOCK option assists in appending to or combining deflate streams. - Also to assist in this, on return inflate() will set strm->data_type to the + To assist in this, on return inflate() always sets strm->data_type to the number of unused bits in the last byte taken from strm->next_in, plus 64 if inflate() is currently decoding the last block in the deflate stream, plus 128 if inflate() returned immediately after decoding an end-of-block code or @@ -454,7 +465,7 @@ ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); this case all pending input is processed and all pending output is flushed; avail_out must be large enough to hold all of the uncompressed data for the operation to complete. (The size of the uncompressed data may have been - saved by the compressor for this purpose.) The use of Z_FINISH is not + saved by the compressor for this purpose.) The use of Z_FINISH is not required to perform an inflation in one step. However it may be used to inform inflate that a faster approach can be used for the single inflate() call. Z_FINISH also informs inflate to not maintain a sliding window if the @@ -476,32 +487,33 @@ ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); chosen by the compressor and returns Z_NEED_DICT; otherwise it sets strm->adler to the Adler-32 checksum of all output produced so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described - below. At the end of the stream, inflate() checks that its computed adler32 + below. At the end of the stream, inflate() checks that its computed Adler-32 checksum is equal to that saved by the compressor and returns Z_STREAM_END only if the checksum is correct. inflate() can decompress and check either zlib-wrapped or gzip-wrapped deflate data. The header type is detected automatically, if requested when initializing with inflateInit2(). Any information contained in the gzip - header is not retained, so applications that need that information should - instead use raw inflate, see inflateInit2() below, or inflateBack() and - perform their own processing of the gzip header and trailer. When processing + header is not retained unless inflateGetHeader() is used. When processing gzip-wrapped deflate data, strm->adler32 is set to the CRC-32 of the output - producted so far. The CRC-32 is checked against the gzip trailer. + produced so far. The CRC-32 is checked against the gzip trailer, as is the + uncompressed length, modulo 2^32. inflate() returns Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if the end of the compressed data has been reached and all uncompressed output has been produced, Z_NEED_DICT if a preset dictionary is needed at this point, Z_DATA_ERROR if the input data was corrupted (input stream not conforming to the zlib format or incorrect check - value), Z_STREAM_ERROR if the stream structure was inconsistent (for example - next_in or next_out was Z_NULL), Z_MEM_ERROR if there was not enough memory, - Z_BUF_ERROR if no progress is possible or if there was not enough room in the - output buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and + value, in which case strm->msg points to a string with a more specific + error), Z_STREAM_ERROR if the stream structure was inconsistent (for example + next_in or next_out was Z_NULL, or the state was inadvertently written over + by the application), Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR + if no progress was possible or if there was not enough room in the output + buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and inflate() can be called again with more input and more output space to continue decompressing. If Z_DATA_ERROR is returned, the application may then call inflateSync() to look for a good compression block if a partial - recovery of the data is desired. + recovery of the data is to be attempted. */ @@ -511,9 +523,8 @@ ZEXTERN int ZEXPORT inflateEnd OF((z_streamp strm)); This function discards any unprocessed input and does not flush any pending output. - inflateEnd returns Z_OK if success, Z_STREAM_ERROR if the stream state - was inconsistent. In the error case, msg may be set but then points to a - static string (which must not be deallocated). + inflateEnd returns Z_OK if success, or Z_STREAM_ERROR if the stream state + was inconsistent. */ @@ -544,16 +555,29 @@ ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm, compression at the expense of memory usage. The default value is 15 if deflateInit is used instead. + For the current implementation of deflate(), a windowBits value of 8 (a + window size of 256 bytes) is not supported. As a result, a request for 8 + will result in 9 (a 512-byte window). In that case, providing 8 to + inflateInit2() will result in an error when the zlib header with 9 is + checked against the initialization of inflate(). The remedy is to not use 8 + with deflateInit2() with this initialization, or at least in that case use 9 + with inflateInit2(). + windowBits can also be -8..-15 for raw deflate. In this case, -windowBits determines the window size. deflate() will then generate raw deflate data - with no zlib header or trailer, and will not compute an adler32 check value. + with no zlib header or trailer, and will not compute a check value. windowBits can also be greater than 15 for optional gzip encoding. Add 16 to windowBits to write a simple gzip header and trailer around the compressed data instead of a zlib wrapper. The gzip header will have no file name, no extra data, no comment, no modification time (set to zero), no - header crc, and the operating system will be set to 255 (unknown). If a - gzip stream is being written, strm->adler is a crc32 instead of an adler32. + header crc, and the operating system will be set to the appropriate value, + if the operating system was determined at compile time. If a gzip stream is + being written, strm->adler is a CRC-32 instead of an Adler-32. + + For raw deflate or gzip encoding, a request for a 256-byte window is + rejected as invalid, since only the zlib header provides a means of + transmitting the window size to the decompressor. The memLevel parameter specifies how much memory should be allocated for the internal compression state. memLevel=1 uses minimum memory but is @@ -614,12 +638,12 @@ ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, addition, the current implementation of deflate will use at most the window size minus 262 bytes of the provided dictionary. - Upon return of this function, strm->adler is set to the adler32 value + Upon return of this function, strm->adler is set to the Adler-32 value of the dictionary; the decompressor may later use this value to determine - which dictionary has been used by the compressor. (The adler32 value + which dictionary has been used by the compressor. (The Adler-32 value applies to the whole dictionary even if only a subset of the dictionary is actually used by the compressor.) If a raw deflate was requested, then the - adler32 value is not computed and strm->adler is not set. + Adler-32 value is not computed and strm->adler is not set. deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is @@ -628,6 +652,28 @@ ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, not perform any compression: this will be done by deflate(). */ +ZEXTERN int ZEXPORT deflateGetDictionary OF((z_streamp strm, + Bytef *dictionary, + uInt *dictLength)); +/* + Returns the sliding dictionary being maintained by deflate. dictLength is + set to the number of bytes in the dictionary, and that many bytes are copied + to dictionary. dictionary must have enough space, where 32768 bytes is + always enough. If deflateGetDictionary() is called with dictionary equal to + Z_NULL, then only the dictionary length is returned, and nothing is copied. + Similary, if dictLength is Z_NULL, then it is not set. + + deflateGetDictionary() may return a length less than the window size, even + when more than the window size in input has been provided. It may return up + to 258 bytes less in that case, due to how zlib's implementation of deflate + manages the sliding window and lookahead for matches, where matches can be + up to 258 bytes long. If the application needs the last window-size bytes of + input, then that would need to be saved by the application outside of zlib. + + deflateGetDictionary returns Z_OK on success, or Z_STREAM_ERROR if the + stream state is inconsistent. +*/ + ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, z_streamp source)); /* @@ -648,10 +694,10 @@ ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, ZEXTERN int ZEXPORT deflateReset OF((z_streamp strm)); /* - This function is equivalent to deflateEnd followed by deflateInit, - but does not free and reallocate all the internal compression state. The - stream will keep the same compression level and any other attributes that - may have been set by deflateInit2. + This function is equivalent to deflateEnd followed by deflateInit, but + does not free and reallocate the internal compression state. The stream + will leave the compression level and any other attributes that may have been + set unchanged. deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL). @@ -662,20 +708,36 @@ ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm, int strategy)); /* Dynamically update the compression level and compression strategy. The - interpretation of level and strategy is as in deflateInit2. This can be + interpretation of level and strategy is as in deflateInit2(). This can be used to switch between compression and straight copy of the input data, or to switch to a different kind of input data requiring a different strategy. - If the compression level is changed, the input available so far is - compressed with the old level (and may be flushed); the new level will take - effect only at the next call of deflate(). - - Before the call of deflateParams, the stream state must be set as for - a call of deflate(), since the currently available input may have to be - compressed and flushed. In particular, strm->avail_out must be non-zero. - - deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source - stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR if - strm->avail_out was zero. + If the compression approach (which is a function of the level) or the + strategy is changed, and if any input has been consumed in a previous + deflate() call, then the input available so far is compressed with the old + level and strategy using deflate(strm, Z_BLOCK). There are three approaches + for the compression levels 0, 1..3, and 4..9 respectively. The new level + and strategy will take effect at the next call of deflate(). + + If a deflate(strm, Z_BLOCK) is performed by deflateParams(), and it does + not have enough output space to complete, then the parameter change will not + take effect. In this case, deflateParams() can be called again with the + same parameters and more output space to try again. + + In order to assure a change in the parameters on the first try, the + deflate stream should be flushed using deflate() with Z_BLOCK or other flush + request until strm.avail_out is not zero, before calling deflateParams(). + Then no more input data should be provided before the deflateParams() call. + If this is done, the old level and strategy will be applied to the data + compressed before deflateParams(), and the new level and strategy will be + applied to the the data compressed after deflateParams(). + + deflateParams returns Z_OK on success, Z_STREAM_ERROR if the source stream + state was inconsistent or if a parameter was invalid, or Z_BUF_ERROR if + there was not enough output space to complete the compression of the + available input data before a change in the strategy or approach. Note that + in the case of a Z_BUF_ERROR, the parameters are not changed. A return + value of Z_BUF_ERROR is not fatal, in which case deflateParams() can be + retried with more output space. */ ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm, @@ -793,7 +855,7 @@ ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, is for use with other formats that use the deflate compressed data format such as zip. Those formats provide their own check values. If a custom format is developed using the raw deflate format for compressed data, it is - recommended that a check value such as an adler32 or a crc32 be applied to + recommended that a check value such as an Adler-32 or a CRC-32 be applied to the uncompressed data as is done in the zlib, gzip, and zip formats. For most applications, the zlib format should be used as is. Note that comments above on the use in deflateInit2() applies to the magnitude of windowBits. @@ -802,7 +864,10 @@ ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, 32 to windowBits to enable zlib and gzip decoding with automatic header detection, or add 16 to decode only the gzip format (the zlib format will return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is a - crc32 instead of an adler32. + CRC-32 instead of an Adler-32. Unlike the gunzip utility and gzread() (see + below), inflate() will not automatically decode concatenated gzip streams. + inflate() will return Z_STREAM_END at the end of the gzip stream. The state + would need to be reset to continue decoding a subsequent gzip stream. inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_VERSION_ERROR if the zlib library version is incompatible with the @@ -823,7 +888,7 @@ ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm, Initializes the decompression dictionary from the given uncompressed byte sequence. This function must be called immediately after a call of inflate, if that call returned Z_NEED_DICT. The dictionary chosen by the compressor - can be determined from the adler32 value returned by that call of inflate. + can be determined from the Adler-32 value returned by that call of inflate. The compressor and decompressor must use exactly the same dictionary (see deflateSetDictionary). For raw inflate, this function can be called at any time to set the dictionary. If the provided dictionary is smaller than the @@ -834,7 +899,7 @@ ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm, inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the - expected one (incorrect adler32 value). inflateSetDictionary does not + expected one (incorrect Adler-32 value). inflateSetDictionary does not perform any decompression: this will be done by subsequent calls of inflate(). */ @@ -892,7 +957,7 @@ ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest, ZEXTERN int ZEXPORT inflateReset OF((z_streamp strm)); /* This function is equivalent to inflateEnd followed by inflateInit, - but does not free and reallocate all the internal decompression state. The + but does not free and reallocate the internal decompression state. The stream will keep attributes that may have been set by inflateInit2. inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source @@ -904,7 +969,9 @@ ZEXTERN int ZEXPORT inflateReset2 OF((z_streamp strm, /* This function is the same as inflateReset, but it also permits changing the wrap and window size requests. The windowBits parameter is interpreted - the same as it is for inflateInit2. + the same as it is for inflateInit2. If the window size is changed, then the + memory allocated for the window is freed, and the window will be reallocated + by inflate() if needed. inflateReset2 returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL), or if @@ -956,7 +1023,7 @@ ZEXTERN long ZEXPORT inflateMark OF((z_streamp strm)); location in the input stream can be determined from avail_in and data_type as noted in the description for the Z_BLOCK flush parameter for inflate. - inflateMark returns the value noted above or -1 << 16 if the provided + inflateMark returns the value noted above, or -65536 if the provided source stream state was inconsistent. */ @@ -1048,9 +1115,9 @@ ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, This routine would normally be used in a utility that reads zip or gzip files and writes out uncompressed files. The utility would decode the header and process the trailer on its own, hence this routine expects only - the raw deflate stream to decompress. This is different from the normal - behavior of inflate(), which expects either a zlib or gzip header and - trailer around the deflate stream. + the raw deflate stream to decompress. This is different from the default + behavior of inflate(), which expects a zlib header and trailer around the + deflate stream. inflateBack() uses two subroutines supplied by the caller that are then called by inflateBack() for input and output. inflateBack() calls those @@ -1059,12 +1126,12 @@ ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, parameters and return types are defined above in the in_func and out_func typedefs. inflateBack() will call in(in_desc, &buf) which should return the number of bytes of provided input, and a pointer to that input in buf. If - there is no input available, in() must return zero--buf is ignored in that - case--and inflateBack() will return a buffer error. inflateBack() will call - out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. out() - should return zero on success, or non-zero on failure. If out() returns - non-zero, inflateBack() will return with an error. Neither in() nor out() - are permitted to change the contents of the window provided to + there is no input available, in() must return zero -- buf is ignored in that + case -- and inflateBack() will return a buffer error. inflateBack() will + call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. + out() should return zero on success, or non-zero on failure. If out() + returns non-zero, inflateBack() will return with an error. Neither in() nor + out() are permitted to change the contents of the window provided to inflateBackInit(), which is also the buffer that out() uses to write from. The length written by out() will be at most the window size. Any non-zero amount of input may be provided by in(). @@ -1092,7 +1159,7 @@ ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, using strm->next_in which will be Z_NULL only if in() returned an error. If strm->next_in is not Z_NULL, then the Z_BUF_ERROR was due to out() returning non-zero. (in() will always be called before out(), so strm->next_in is - assured to be defined if out() returns non-zero.) Note that inflateBack() + assured to be defined if out() returns non-zero.) Note that inflateBack() cannot return Z_OK. */ @@ -1114,7 +1181,7 @@ ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void)); 7.6: size of z_off_t Compiler, assembler, and debug options: - 8: DEBUG + 8: ZLIB_DEBUG 9: ASMV or ASMINF -- use ASM code 10: ZLIB_WINAPI -- exported functions use the WINAPI calling convention 11: 0 (reserved) @@ -1164,7 +1231,8 @@ ZEXTERN int ZEXPORT compress OF((Bytef *dest, uLongf *destLen, the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least the value returned by compressBound(sourceLen). Upon exit, destLen is the actual size of the - compressed buffer. + compressed data. compress() is equivalent to compress2() with a level + parameter of Z_DEFAULT_COMPRESSION. compress returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output @@ -1180,7 +1248,7 @@ ZEXTERN int ZEXPORT compress2 OF((Bytef *dest, uLongf *destLen, length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least the value returned by compressBound(sourceLen). Upon exit, destLen is the actual size of the - compressed buffer. + compressed data. compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output buffer, @@ -1203,7 +1271,7 @@ ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, uncompressed data. (The size of the uncompressed data must have been saved previously by the compressor and transmitted to the decompressor by some mechanism outside the scope of this compression library.) Upon exit, destLen - is the actual size of the uncompressed buffer. + is the actual size of the uncompressed data. uncompress returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output @@ -1212,6 +1280,14 @@ ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, buffer with the uncompressed data up to that point. */ +ZEXTERN int ZEXPORT uncompress2 OF((Bytef *dest, uLongf *destLen, + const Bytef *source, uLong *sourceLen)); +/* + Same as uncompress, except that sourceLen is a pointer, where the + length of the source is *sourceLen. On return, *sourceLen is the number of + source bytes consumed. +*/ + /* gzip file access functions */ /* @@ -1290,10 +1366,9 @@ ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size)); default buffer size is 8192 bytes. This function must be called after gzopen() or gzdopen(), and before any other calls that read or write the file. The buffer memory allocation is always deferred to the first read or - write. Two buffers are allocated, either both of the specified size when - writing, or one of the specified size and the other twice that size when - reading. A larger buffer size of, for example, 64K or 128K bytes will - noticeably increase the speed of decompression (reading). + write. Three times that size in buffer space is allocated. A larger buffer + size of, for example, 64K or 128K bytes will noticeably increase the speed + of decompression (reading). The new buffer size also affects the maximum length for gzprintf(). @@ -1304,10 +1379,12 @@ ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size)); ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy)); /* Dynamically update the compression level or strategy. See the description - of deflateInit2 for the meaning of these parameters. + of deflateInit2 for the meaning of these parameters. Previously provided + data is flushed before the parameter change. - gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file was not - opened for writing. + gzsetparams returns Z_OK if success, Z_STREAM_ERROR if the file was not + opened for writing, Z_ERRNO if there is an error writing the flushed data, + or Z_MEM_ERROR if there is a memory allocation error. */ ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); @@ -1335,7 +1412,35 @@ ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); case. gzread returns the number of uncompressed bytes actually read, less than - len for end of file, or -1 for error. + len for end of file, or -1 for error. If len is too large to fit in an int, + then nothing is read, -1 is returned, and the error state is set to + Z_STREAM_ERROR. +*/ + +ZEXTERN z_size_t ZEXPORT gzfread OF((voidp buf, z_size_t size, z_size_t nitems, + gzFile file)); +/* + Read up to nitems items of size size from file to buf, otherwise operating + as gzread() does. This duplicates the interface of stdio's fread(), with + size_t request and return types. If the library defines size_t, then + z_size_t is identical to size_t. If not, then z_size_t is an unsigned + integer type that can contain a pointer. + + gzfread() returns the number of full items read of size size, or zero if + the end of the file was reached and a full item could not be read, or if + there was an error. gzerror() must be consulted if zero is returned in + order to determine if there was an error. If the multiplication of size and + nitems overflows, i.e. the product does not fit in a z_size_t, then nothing + is read, zero is returned, and the error state is set to Z_STREAM_ERROR. + + In the event that the end of file is reached and only a partial item is + available at the end, i.e. the remaining uncompressed data length is not a + multiple of size, then the final partial item is nevetheless read into buf + and the end-of-file flag is set. The length of the partial item read is not + provided, but could be inferred from the result of gztell(). This behavior + is the same as the behavior of fread() implementations in common libraries, + but it prevents the direct use of gzfread() to read a concurrently written + file, reseting and retrying on end-of-file, when size is not 1. */ ZEXTERN int ZEXPORT gzwrite OF((gzFile file, @@ -1346,19 +1451,33 @@ ZEXTERN int ZEXPORT gzwrite OF((gzFile file, error. */ +ZEXTERN z_size_t ZEXPORT gzfwrite OF((voidpc buf, z_size_t size, + z_size_t nitems, gzFile file)); +/* + gzfwrite() writes nitems items of size size from buf to file, duplicating + the interface of stdio's fwrite(), with size_t request and return types. If + the library defines size_t, then z_size_t is identical to size_t. If not, + then z_size_t is an unsigned integer type that can contain a pointer. + + gzfwrite() returns the number of full items written of size size, or zero + if there was an error. If the multiplication of size and nitems overflows, + i.e. the product does not fit in a z_size_t, then nothing is written, zero + is returned, and the error state is set to Z_STREAM_ERROR. +*/ + ZEXTERN int ZEXPORTVA gzprintf Z_ARG((gzFile file, const char *format, ...)); /* Converts, formats, and writes the arguments to the compressed file under control of the format string, as in fprintf. gzprintf returns the number of - uncompressed bytes actually written, or 0 in case of error. The number of - uncompressed bytes written is limited to 8191, or one less than the buffer - size given to gzbuffer(). The caller should assure that this limit is not - exceeded. If it is exceeded, then gzprintf() will return an error (0) with - nothing written. In this case, there may also be a buffer overflow with - unpredictable consequences, which is possible only if zlib was compiled with - the insecure functions sprintf() or vsprintf() because the secure snprintf() - or vsnprintf() functions were not available. This can be determined using - zlibCompileFlags(). + uncompressed bytes actually written, or a negative zlib error code in case + of error. The number of uncompressed bytes written is limited to 8191, or + one less than the buffer size given to gzbuffer(). The caller should assure + that this limit is not exceeded. If it is exceeded, then gzprintf() will + return an error (0) with nothing written. In this case, there may also be a + buffer overflow with unpredictable consequences, which is possible only if + zlib was compiled with the insecure functions sprintf() or vsprintf() + because the secure snprintf() or vsnprintf() functions were not available. + This can be determined using zlibCompileFlags(). */ ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); @@ -1418,7 +1537,7 @@ ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); If the flush parameter is Z_FINISH, the remaining data is written and the gzip stream is completed in the output. If gzwrite() is called again, a new gzip stream will be started in the output. gzread() is able to read such - concatented gzip streams. + concatenated gzip streams. gzflush should be called only when strictly necessary because it will degrade compression if called too often. @@ -1572,7 +1691,7 @@ ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); return the updated checksum. If buf is Z_NULL, this function returns the required initial value for the checksum. - An Adler-32 checksum is almost as reliable as a CRC32 but can be computed + An Adler-32 checksum is almost as reliable as a CRC-32 but can be computed much faster. Usage example: @@ -1585,6 +1704,12 @@ ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); if (adler != original_adler) error(); */ +ZEXTERN uLong ZEXPORT adler32_z OF((uLong adler, const Bytef *buf, + z_size_t len)); +/* + Same as adler32(), but with a size_t length. +*/ + /* ZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2, z_off_t len2)); @@ -1614,6 +1739,12 @@ ZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len)); if (crc != original_crc) error(); */ +ZEXTERN uLong ZEXPORT crc32_z OF((uLong adler, const Bytef *buf, + z_size_t len)); +/* + Same as crc32(), but with a size_t length. +*/ + /* ZEXTERN uLong ZEXPORT crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2)); @@ -1644,19 +1775,35 @@ ZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, unsigned char FAR *window, const char *version, int stream_size)); -#define deflateInit(strm, level) \ - deflateInit_((strm), (level), ZLIB_VERSION, (int)sizeof(z_stream)) -#define inflateInit(strm) \ - inflateInit_((strm), ZLIB_VERSION, (int)sizeof(z_stream)) -#define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ - deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ - (strategy), ZLIB_VERSION, (int)sizeof(z_stream)) -#define inflateInit2(strm, windowBits) \ - inflateInit2_((strm), (windowBits), ZLIB_VERSION, \ - (int)sizeof(z_stream)) -#define inflateBackInit(strm, windowBits, window) \ - inflateBackInit_((strm), (windowBits), (window), \ - ZLIB_VERSION, (int)sizeof(z_stream)) +#ifdef Z_PREFIX_SET +# define z_deflateInit(strm, level) \ + deflateInit_((strm), (level), ZLIB_VERSION, (int)sizeof(z_stream)) +# define z_inflateInit(strm) \ + inflateInit_((strm), ZLIB_VERSION, (int)sizeof(z_stream)) +# define z_deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ + deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ + (strategy), ZLIB_VERSION, (int)sizeof(z_stream)) +# define z_inflateInit2(strm, windowBits) \ + inflateInit2_((strm), (windowBits), ZLIB_VERSION, \ + (int)sizeof(z_stream)) +# define z_inflateBackInit(strm, windowBits, window) \ + inflateBackInit_((strm), (windowBits), (window), \ + ZLIB_VERSION, (int)sizeof(z_stream)) +#else +# define deflateInit(strm, level) \ + deflateInit_((strm), (level), ZLIB_VERSION, (int)sizeof(z_stream)) +# define inflateInit(strm) \ + inflateInit_((strm), ZLIB_VERSION, (int)sizeof(z_stream)) +# define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ + deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ + (strategy), ZLIB_VERSION, (int)sizeof(z_stream)) +# define inflateInit2(strm, windowBits) \ + inflateInit2_((strm), (windowBits), ZLIB_VERSION, \ + (int)sizeof(z_stream)) +# define inflateBackInit(strm, windowBits, window) \ + inflateBackInit_((strm), (windowBits), (window), \ + ZLIB_VERSION, (int)sizeof(z_stream)) +#endif #ifndef Z_SOLO @@ -1676,10 +1823,10 @@ ZEXTERN int ZEXPORT gzgetc_ OF((gzFile file)); /* backward compatibility */ #ifdef Z_PREFIX_SET # undef z_gzgetc # define z_gzgetc(g) \ - ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : gzgetc(g)) + ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : (gzgetc)(g)) #else # define gzgetc(g) \ - ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : gzgetc(g)) + ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : (gzgetc)(g)) #endif /* provide 64-bit offset functions if _LARGEFILE64_SOURCE defined, and/or @@ -1737,19 +1884,16 @@ ZEXTERN int ZEXPORT gzgetc_ OF((gzFile file)); /* backward compatibility */ #endif /* !Z_SOLO */ -/* hack for buggy compilers */ -#if !defined(ZUTIL_H) && !defined(NO_DUMMY_DECL) - struct internal_state {int dummy;}; -#endif - /* undocumented functions */ ZEXTERN const char * ZEXPORT zError OF((int)); ZEXTERN int ZEXPORT inflateSyncPoint OF((z_streamp)); ZEXTERN const z_crc_t FAR * ZEXPORT get_crc_table OF((void)); ZEXTERN int ZEXPORT inflateUndermine OF((z_streamp, int)); +ZEXTERN int ZEXPORT inflateValidate OF((z_streamp, int)); +ZEXTERN unsigned long ZEXPORT inflateCodesUsed OF ((z_streamp)); ZEXTERN int ZEXPORT inflateResetKeep OF((z_streamp)); ZEXTERN int ZEXPORT deflateResetKeep OF((z_streamp)); -#if defined(_WIN32) && !defined(Z_SOLO) +#if (defined(_WIN32) || defined(__CYGWIN__)) && !defined(Z_SOLO) ZEXTERN gzFile ZEXPORT gzopen_w OF((const wchar_t *path, const char *mode)); #endif diff --git a/Modules/zlib/zlib.map b/Modules/zlib/zlib.map index 55c6647eb46f95..40fa9db2bce351 100644 --- a/Modules/zlib/zlib.map +++ b/Modules/zlib/zlib.map @@ -1,83 +1,94 @@ -ZLIB_1.2.0 { - global: - compressBound; - deflateBound; - inflateBack; - inflateBackEnd; - inflateBackInit_; - inflateCopy; - local: - deflate_copyright; - inflate_copyright; - inflate_fast; - inflate_table; - zcalloc; - zcfree; - z_errmsg; - gz_error; - gz_intmax; - _*; -}; - -ZLIB_1.2.0.2 { - gzclearerr; - gzungetc; - zlibCompileFlags; -} ZLIB_1.2.0; - -ZLIB_1.2.0.8 { - deflatePrime; -} ZLIB_1.2.0.2; - -ZLIB_1.2.2 { - adler32_combine; - crc32_combine; - deflateSetHeader; - inflateGetHeader; -} ZLIB_1.2.0.8; - -ZLIB_1.2.2.3 { - deflateTune; - gzdirect; -} ZLIB_1.2.2; - -ZLIB_1.2.2.4 { - inflatePrime; -} ZLIB_1.2.2.3; - -ZLIB_1.2.3.3 { - adler32_combine64; - crc32_combine64; - gzopen64; - gzseek64; - gztell64; - inflateUndermine; -} ZLIB_1.2.2.4; - -ZLIB_1.2.3.4 { - inflateReset2; - inflateMark; -} ZLIB_1.2.3.3; - -ZLIB_1.2.3.5 { - gzbuffer; - gzoffset; - gzoffset64; - gzclose_r; - gzclose_w; -} ZLIB_1.2.3.4; - -ZLIB_1.2.5.1 { - deflatePending; -} ZLIB_1.2.3.5; - -ZLIB_1.2.5.2 { - deflateResetKeep; - gzgetc_; - inflateResetKeep; -} ZLIB_1.2.5.1; - -ZLIB_1.2.7.1 { - inflateGetDictionary; - gzvprintf; -} ZLIB_1.2.5.2; +ZLIB_1.2.0 { + global: + compressBound; + deflateBound; + inflateBack; + inflateBackEnd; + inflateBackInit_; + inflateCopy; + local: + deflate_copyright; + inflate_copyright; + inflate_fast; + inflate_table; + zcalloc; + zcfree; + z_errmsg; + gz_error; + gz_intmax; + _*; +}; + +ZLIB_1.2.0.2 { + gzclearerr; + gzungetc; + zlibCompileFlags; +} ZLIB_1.2.0; + +ZLIB_1.2.0.8 { + deflatePrime; +} ZLIB_1.2.0.2; + +ZLIB_1.2.2 { + adler32_combine; + crc32_combine; + deflateSetHeader; + inflateGetHeader; +} ZLIB_1.2.0.8; + +ZLIB_1.2.2.3 { + deflateTune; + gzdirect; +} ZLIB_1.2.2; + +ZLIB_1.2.2.4 { + inflatePrime; +} ZLIB_1.2.2.3; + +ZLIB_1.2.3.3 { + adler32_combine64; + crc32_combine64; + gzopen64; + gzseek64; + gztell64; + inflateUndermine; +} ZLIB_1.2.2.4; + +ZLIB_1.2.3.4 { + inflateReset2; + inflateMark; +} ZLIB_1.2.3.3; + +ZLIB_1.2.3.5 { + gzbuffer; + gzoffset; + gzoffset64; + gzclose_r; + gzclose_w; +} ZLIB_1.2.3.4; + +ZLIB_1.2.5.1 { + deflatePending; +} ZLIB_1.2.3.5; + +ZLIB_1.2.5.2 { + deflateResetKeep; + gzgetc_; + inflateResetKeep; +} ZLIB_1.2.5.1; + +ZLIB_1.2.7.1 { + inflateGetDictionary; + gzvprintf; +} ZLIB_1.2.5.2; + +ZLIB_1.2.9 { + inflateCodesUsed; + inflateValidate; + uncompress2; + gzfread; + gzfwrite; + deflateGetDictionary; + adler32_z; + crc32_z; +} ZLIB_1.2.7.1; diff --git a/Modules/zlib/zutil.c b/Modules/zlib/zutil.c index 23d2ebef008fdc..a76c6b0c7e557f 100644 --- a/Modules/zlib/zutil.c +++ b/Modules/zlib/zutil.c @@ -1,5 +1,5 @@ /* zutil.c -- target dependent utility functions for the compression library - * Copyright (C) 1995-2005, 2010, 2011, 2012 Jean-loup Gailly. + * Copyright (C) 1995-2017 Jean-loup Gailly * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -10,21 +10,18 @@ # include "gzguts.h" #endif -#ifndef NO_DUMMY_DECL -struct internal_state {int dummy;}; /* for buggy compilers */ -#endif - z_const char * const z_errmsg[10] = { -"need dictionary", /* Z_NEED_DICT 2 */ -"stream end", /* Z_STREAM_END 1 */ -"", /* Z_OK 0 */ -"file error", /* Z_ERRNO (-1) */ -"stream error", /* Z_STREAM_ERROR (-2) */ -"data error", /* Z_DATA_ERROR (-3) */ -"insufficient memory", /* Z_MEM_ERROR (-4) */ -"buffer error", /* Z_BUF_ERROR (-5) */ -"incompatible version",/* Z_VERSION_ERROR (-6) */ -""}; + (z_const char *)"need dictionary", /* Z_NEED_DICT 2 */ + (z_const char *)"stream end", /* Z_STREAM_END 1 */ + (z_const char *)"", /* Z_OK 0 */ + (z_const char *)"file error", /* Z_ERRNO (-1) */ + (z_const char *)"stream error", /* Z_STREAM_ERROR (-2) */ + (z_const char *)"data error", /* Z_DATA_ERROR (-3) */ + (z_const char *)"insufficient memory", /* Z_MEM_ERROR (-4) */ + (z_const char *)"buffer error", /* Z_BUF_ERROR (-5) */ + (z_const char *)"incompatible version",/* Z_VERSION_ERROR (-6) */ + (z_const char *)"" +}; const char * ZEXPORT zlibVersion() @@ -61,7 +58,7 @@ uLong ZEXPORT zlibCompileFlags() case 8: flags += 2 << 6; break; default: flags += 3 << 6; } -#ifdef DEBUG +#ifdef ZLIB_DEBUG flags += 1 << 8; #endif #if defined(ASMV) || defined(ASMINF) @@ -115,8 +112,8 @@ uLong ZEXPORT zlibCompileFlags() return flags; } -#ifdef DEBUG - +#ifdef ZLIB_DEBUG +#include # ifndef verbose # define verbose 0 # endif @@ -219,9 +216,11 @@ local ptr_table table[MAX_PTR]; voidpf ZLIB_INTERNAL zcalloc (voidpf opaque, unsigned items, unsigned size) { - voidpf buf = opaque; /* just to make some compilers happy */ + voidpf buf; ulg bsize = (ulg)items*size; + (void)opaque; + /* If we allocate less than 65520 bytes, we assume that farmalloc * will return a usable pointer which doesn't have to be normalized. */ @@ -244,6 +243,9 @@ voidpf ZLIB_INTERNAL zcalloc (voidpf opaque, unsigned items, unsigned size) void ZLIB_INTERNAL zcfree (voidpf opaque, voidpf ptr) { int n; + + (void)opaque; + if (*(ush*)&ptr != 0) { /* object < 64K */ farfree(ptr); return; @@ -259,7 +261,6 @@ void ZLIB_INTERNAL zcfree (voidpf opaque, voidpf ptr) next_ptr--; return; } - ptr = opaque; /* just to make some compilers happy */ Assert(0, "zcfree: ptr not found"); } @@ -278,13 +279,13 @@ void ZLIB_INTERNAL zcfree (voidpf opaque, voidpf ptr) voidpf ZLIB_INTERNAL zcalloc (voidpf opaque, uInt items, uInt size) { - if (opaque) opaque = 0; /* to make compiler happy */ + (void)opaque; return _halloc((long)items, size); } void ZLIB_INTERNAL zcfree (voidpf opaque, voidpf ptr) { - if (opaque) opaque = 0; /* to make compiler happy */ + (void)opaque; _hfree(ptr); } @@ -306,7 +307,7 @@ voidpf ZLIB_INTERNAL zcalloc (opaque, items, size) unsigned items; unsigned size; { - if (opaque) items += size - size; /* make compiler happy */ + (void)opaque; return sizeof(uInt) > 2 ? (voidpf)malloc(items * size) : (voidpf)calloc(items, size); } @@ -315,8 +316,8 @@ void ZLIB_INTERNAL zcfree (opaque, ptr) voidpf opaque; voidpf ptr; { + (void)opaque; free(ptr); - if (opaque) return; /* make compiler happy */ } #endif /* MY_ZCALLOC */ diff --git a/Modules/zlib/zutil.h b/Modules/zlib/zutil.h index 24ab06b1cf60ae..b079ea6a80f5ab 100644 --- a/Modules/zlib/zutil.h +++ b/Modules/zlib/zutil.h @@ -1,5 +1,5 @@ /* zutil.h -- internal interface and configuration of the compression library - * Copyright (C) 1995-2013 Jean-loup Gailly. + * Copyright (C) 1995-2016 Jean-loup Gailly, Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ @@ -36,7 +36,9 @@ #ifndef local # define local static #endif -/* compile with -Dlocal if your debugger can't find static symbols */ +/* since "static" is used to mean two completely different things in C, we + define "local" for the non-static meaning of "static", for readability + (compile with -Dlocal if your debugger can't find static symbols) */ typedef unsigned char uch; typedef uch FAR uchf; @@ -98,28 +100,38 @@ extern z_const char * const z_errmsg[10]; /* indexed by 2-zlib_error */ #endif #ifdef AMIGA -# define OS_CODE 0x01 +# define OS_CODE 1 #endif #if defined(VAXC) || defined(VMS) -# define OS_CODE 0x02 +# define OS_CODE 2 # define F_OPEN(name, mode) \ fopen((name), (mode), "mbc=60", "ctx=stm", "rfm=fix", "mrs=512") #endif +#ifdef __370__ +# if __TARGET_LIB__ < 0x20000000 +# define OS_CODE 4 +# elif __TARGET_LIB__ < 0x40000000 +# define OS_CODE 11 +# else +# define OS_CODE 8 +# endif +#endif + #if defined(ATARI) || defined(atarist) -# define OS_CODE 0x05 +# define OS_CODE 5 #endif #ifdef OS2 -# define OS_CODE 0x06 +# define OS_CODE 6 # if defined(M_I86) && !defined(Z_SOLO) # include # endif #endif #if defined(MACOS) || defined(TARGET_OS_MAC) -# define OS_CODE 0x07 +# define OS_CODE 7 # ifndef Z_SOLO # if defined(__MWERKS__) && __dest_os != __be_os && __dest_os != __win32_os # include /* for fdopen */ @@ -131,18 +143,24 @@ extern z_const char * const z_errmsg[10]; /* indexed by 2-zlib_error */ # endif #endif -#ifdef TOPS20 -# define OS_CODE 0x0a +#ifdef __acorn +# define OS_CODE 13 #endif -#ifdef WIN32 -# ifndef __CYGWIN__ /* Cygwin is Unix, not Win32 */ -# define OS_CODE 0x0b -# endif +#if defined(WIN32) && !defined(__CYGWIN__) +# define OS_CODE 10 +#endif + +#ifdef _BEOS_ +# define OS_CODE 16 +#endif + +#ifdef __TOS_OS400__ +# define OS_CODE 18 #endif -#ifdef __50SERIES /* Prime/PRIMOS */ -# define OS_CODE 0x0f +#ifdef __APPLE__ +# define OS_CODE 19 #endif #if defined(_BEOS_) || defined(RISCOS) @@ -177,7 +195,7 @@ extern z_const char * const z_errmsg[10]; /* indexed by 2-zlib_error */ /* common defaults */ #ifndef OS_CODE -# define OS_CODE 0x03 /* assume Unix */ +# define OS_CODE 3 /* assume Unix */ #endif #ifndef F_OPEN @@ -216,7 +234,7 @@ extern z_const char * const z_errmsg[10]; /* indexed by 2-zlib_error */ #endif /* Diagnostic functions */ -#ifdef DEBUG +#ifdef ZLIB_DEBUG # include extern int ZLIB_INTERNAL z_verbose; extern void ZLIB_INTERNAL z_error OF((char *m)); From 86a713cb0c110b6798ca7f9e630fc511ee0a4028 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Sun, 24 Sep 2017 01:04:53 -0700 Subject: [PATCH 23/24] [3.4][Security] bpo-30947, bpo-31170: Update expat from 2.2.1 to 2.2.4 (#3353) * bpo-30947, bpo-31170: Update expat from 2.2.1 to 2.2.4 * Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security fixes. * Update libexpat from 2.2.3 to 2.2.4. Fix copying of partial characters for UTF-8 input (libexpat bug 115): https://github.com/libexpat/libexpat/issues/115 * Define XML_POOR_ENTROPY when compiling expat --- .../2017-09-05-20-35-21.bpo-31170.QGmJ1t.rst | 3 + .../2017-09-05-20-34-44.bpo-30947.iNMmm4.rst | 2 + Modules/expat/ascii.h | 32 +- Modules/expat/asciitab.h | 32 +- Modules/expat/expat.h | 35 +- Modules/expat/expat_external.h | 32 +- Modules/expat/iasciitab.h | 32 +- Modules/expat/internal.h | 29 + Modules/expat/latin1tab.h | 32 +- Modules/expat/loadlibrary.c | 143 +++++ Modules/expat/nametab.h | 32 + Modules/expat/siphash.h | 64 +- Modules/expat/utf8tab.h | 33 +- Modules/expat/winconfig.h | 37 +- Modules/expat/xmlparse.c | 559 +++++++++++++++--- Modules/expat/xmlrole.c | 62 +- Modules/expat/xmlrole.h | 32 +- Modules/expat/xmltok.c | 80 ++- Modules/expat/xmltok.h | 32 +- Modules/expat/xmltok_impl.c | 72 ++- Modules/expat/xmltok_impl.h | 31 +- Modules/expat/xmltok_ns.c | 33 +- setup.py | 3 + 23 files changed, 1289 insertions(+), 153 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2017-09-05-20-35-21.bpo-31170.QGmJ1t.rst create mode 100644 Misc/NEWS.d/next/Security/2017-09-05-20-34-44.bpo-30947.iNMmm4.rst create mode 100644 Modules/expat/loadlibrary.c diff --git a/Misc/NEWS.d/next/Library/2017-09-05-20-35-21.bpo-31170.QGmJ1t.rst b/Misc/NEWS.d/next/Library/2017-09-05-20-35-21.bpo-31170.QGmJ1t.rst new file mode 100644 index 00000000000000..2505007dac0c12 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2017-09-05-20-35-21.bpo-31170.QGmJ1t.rst @@ -0,0 +1,3 @@ +expat: Update libexpat from 2.2.3 to 2.2.4. Fix copying of partial +characters for UTF-8 input (libexpat bug 115): +https://github.com/libexpat/libexpat/issues/115 diff --git a/Misc/NEWS.d/next/Security/2017-09-05-20-34-44.bpo-30947.iNMmm4.rst b/Misc/NEWS.d/next/Security/2017-09-05-20-34-44.bpo-30947.iNMmm4.rst new file mode 100644 index 00000000000000..3caca9a79b4ba6 --- /dev/null +++ b/Misc/NEWS.d/next/Security/2017-09-05-20-34-44.bpo-30947.iNMmm4.rst @@ -0,0 +1,2 @@ +Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security +fixes. diff --git a/Modules/expat/ascii.h b/Modules/expat/ascii.h index d10530b09bde69..c3587e57332bff 100644 --- a/Modules/expat/ascii.h +++ b/Modules/expat/ascii.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #define ASCII_A 0x41 diff --git a/Modules/expat/asciitab.h b/Modules/expat/asciitab.h index 79a15c28ca14f8..2f59fd92906537 100644 --- a/Modules/expat/asciitab.h +++ b/Modules/expat/asciitab.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ /* 0x00 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, diff --git a/Modules/expat/expat.h b/Modules/expat/expat.h index 28b0f954d41963..d0735bb5c61676 100644 --- a/Modules/expat/expat.h +++ b/Modules/expat/expat.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #ifndef Expat_INCLUDED @@ -24,7 +52,6 @@ extern "C" { struct XML_ParserStruct; typedef struct XML_ParserStruct *XML_Parser; -/* Should this be defined using stdbool.h when C99 is available? */ typedef unsigned char XML_Bool; #define XML_TRUE ((XML_Bool) 1) #define XML_FALSE ((XML_Bool) 0) @@ -1049,7 +1076,7 @@ XML_GetFeatureList(void); */ #define XML_MAJOR_VERSION 2 #define XML_MINOR_VERSION 2 -#define XML_MICRO_VERSION 1 +#define XML_MICRO_VERSION 4 #ifdef __cplusplus } diff --git a/Modules/expat/expat_external.h b/Modules/expat/expat_external.h index 4c9e5eabdee2ce..81102856496965 100644 --- a/Modules/expat/expat_external.h +++ b/Modules/expat/expat_external.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #ifndef Expat_External_INCLUDED diff --git a/Modules/expat/iasciitab.h b/Modules/expat/iasciitab.h index 24a1d5ccc9a59b..ce4a4bf7edef53 100644 --- a/Modules/expat/iasciitab.h +++ b/Modules/expat/iasciitab.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ /* Like asciitab.h, except that 0xD has code BT_S rather than BT_CR */ diff --git a/Modules/expat/internal.h b/Modules/expat/internal.h index 94cb98e15cae40..3c5d6e913d6db3 100644 --- a/Modules/expat/internal.h +++ b/Modules/expat/internal.h @@ -18,6 +18,35 @@ Note: Use of these macros is based on judgement, not hard rules, and therefore subject to change. + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #if defined(__GNUC__) && defined(__i386__) && !defined(__MINGW32__) diff --git a/Modules/expat/latin1tab.h b/Modules/expat/latin1tab.h index 53c25d76b26813..95dfa52b1fbebb 100644 --- a/Modules/expat/latin1tab.h +++ b/Modules/expat/latin1tab.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ /* 0x80 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, diff --git a/Modules/expat/loadlibrary.c b/Modules/expat/loadlibrary.c new file mode 100644 index 00000000000000..452ae92db2673c --- /dev/null +++ b/Modules/expat/loadlibrary.c @@ -0,0 +1,143 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 2016 - 2017, Steve Holme, . + * Copyright (C) 2017, Expat development team + * + * All rights reserved. + * Licensed under the MIT license: + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF + * THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH + * THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + * + * Except as contained in this notice, the name of a copyright holder shall + * not be used in advertising or otherwise to promote the sale, use or other + * dealings in this Software without prior written authorization of the + * copyright holder. + * + ***************************************************************************/ + +#if defined(_WIN32) + +#include +#include + + +HMODULE _Expat_LoadLibrary(LPCTSTR filename); + + +#if !defined(LOAD_WITH_ALTERED_SEARCH_PATH) +#define LOAD_WITH_ALTERED_SEARCH_PATH 0x00000008 +#endif + +#if !defined(LOAD_LIBRARY_SEARCH_SYSTEM32) +#define LOAD_LIBRARY_SEARCH_SYSTEM32 0x00000800 +#endif + +/* We use our own typedef here since some headers might lack these */ +typedef HMODULE (APIENTRY *LOADLIBRARYEX_FN)(LPCTSTR, HANDLE, DWORD); + +/* See function definitions in winbase.h */ +#ifdef UNICODE +# ifdef _WIN32_WCE +# define LOADLIBARYEX L"LoadLibraryExW" +# else +# define LOADLIBARYEX "LoadLibraryExW" +# endif +#else +# define LOADLIBARYEX "LoadLibraryExA" +#endif + + +/* + * _Expat_LoadLibrary() + * + * This is used to dynamically load DLLs using the most secure method available + * for the version of Windows that we are running on. + * + * Parameters: + * + * filename [in] - The filename or full path of the DLL to load. If only the + * filename is passed then the DLL will be loaded from the + * Windows system directory. + * + * Returns the handle of the module on success; otherwise NULL. + */ +HMODULE _Expat_LoadLibrary(LPCTSTR filename) +{ + HMODULE hModule = NULL; + LOADLIBRARYEX_FN pLoadLibraryEx = NULL; + + /* Get a handle to kernel32 so we can access it's functions at runtime */ + HMODULE hKernel32 = GetModuleHandle(TEXT("kernel32")); + if(!hKernel32) + return NULL; + + /* Attempt to find LoadLibraryEx() which is only available on Windows 2000 + and above */ + pLoadLibraryEx = (LOADLIBRARYEX_FN) GetProcAddress(hKernel32, LOADLIBARYEX); + + /* Detect if there's already a path in the filename and load the library if + there is. Note: Both back slashes and forward slashes have been supported + since the earlier days of DOS at an API level although they are not + supported by command prompt */ + if(_tcspbrk(filename, TEXT("\\/"))) { + /** !checksrc! disable BANNEDFUNC 1 **/ + hModule = pLoadLibraryEx ? + pLoadLibraryEx(filename, NULL, LOAD_WITH_ALTERED_SEARCH_PATH) : + LoadLibrary(filename); + } + /* Detect if KB2533623 is installed, as LOAD_LIBARY_SEARCH_SYSTEM32 is only + supported on Windows Vista, Windows Server 2008, Windows 7 and Windows + Server 2008 R2 with this patch or natively on Windows 8 and above */ + else if(pLoadLibraryEx && GetProcAddress(hKernel32, "AddDllDirectory")) { + /* Load the DLL from the Windows system directory */ + hModule = pLoadLibraryEx(filename, NULL, LOAD_LIBRARY_SEARCH_SYSTEM32); + } + else { + /* Attempt to get the Windows system path */ + UINT systemdirlen = GetSystemDirectory(NULL, 0); + if(systemdirlen) { + /* Allocate space for the full DLL path (Room for the null terminator + is included in systemdirlen) */ + size_t filenamelen = _tcslen(filename); + TCHAR *path = malloc(sizeof(TCHAR) * (systemdirlen + 1 + filenamelen)); + if(path && GetSystemDirectory(path, systemdirlen)) { + /* Calculate the full DLL path */ + _tcscpy(path + _tcslen(path), TEXT("\\")); + _tcscpy(path + _tcslen(path), filename); + + /* Load the DLL from the Windows system directory */ + /** !checksrc! disable BANNEDFUNC 1 **/ + hModule = pLoadLibraryEx ? + pLoadLibraryEx(path, NULL, LOAD_WITH_ALTERED_SEARCH_PATH) : + LoadLibrary(path); + + } + free(path); + } + } + + return hModule; +} + +#else /* defined(_WIN32) */ + +/* ISO C requires a translation unit to contain at least one declaration + [-Wempty-translation-unit] */ +typedef int _TRANSLATION_UNIT_LOAD_LIBRARY_C_NOT_EMTPY; + +#endif /* defined(_WIN32) */ diff --git a/Modules/expat/nametab.h b/Modules/expat/nametab.h index b05e62c77a6c62..bfa2bd38cd95cd 100644 --- a/Modules/expat/nametab.h +++ b/Modules/expat/nametab.h @@ -1,3 +1,35 @@ +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. +*/ + static const unsigned namingBitmap[] = { 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, diff --git a/Modules/expat/siphash.h b/Modules/expat/siphash.h index 23b56d2ae48754..581872df7b4992 100644 --- a/Modules/expat/siphash.h +++ b/Modules/expat/siphash.h @@ -2,9 +2,8 @@ * siphash.h - SipHash-2-4 in a single header file * -------------------------------------------------------------------------- * Derived by William Ahern from the reference implementation[1] published[2] - * by Jean-Philippe Aumasson and Daniel J. Berstein. Licensed in kind. * by Jean-Philippe Aumasson and Daniel J. Berstein. - * Minimal changes by Sebastian Pipping on top, details below. + * Minimal changes by Sebastian Pipping and Victor Stinner on top, see below. * Licensed under the CC0 Public Domain Dedication license. * * 1. https://www.131002.net/siphash/siphash24.c @@ -12,14 +11,25 @@ * -------------------------------------------------------------------------- * HISTORY: * - * 2017-06-10 (Sebastian Pipping) + * 2017-07-25 (Vadim Zeitlin) + * - Fix use of SIPHASH_MAIN macro + * + * 2017-07-05 (Sebastian Pipping) + * - Use _SIP_ULL macro to not require a C++11 compiler if compiled as C++ + * - Add const qualifiers at two places + * - Ensure <=80 characters line length (assuming tab width 4) + * + * 2017-06-23 (Victor Stinner) + * - Address Win64 compile warnings + * + * 2017-06-18 (Sebastian Pipping) * - Clarify license note in the header * - Address C89 issues: * - Stop using inline keyword (and let compiler decide) - * - Turn integer suffix ULL to UL * - Replace _Bool by int * - Turn macro siphash24 into a function * - Address invalid conversion (void pointer) by explicit cast + * - Address lack of stdint.h for Visual Studio 2003 to 2008 * - Always expose sip24_valid (for self-tests) * * 2012-11-04 - Born. (William Ahern) @@ -76,7 +86,23 @@ #define SIPHASH_H #include /* size_t */ -#include /* uint64_t uint32_t uint8_t */ + +#if defined(_WIN32) && defined(_MSC_VER) && (_MSC_VER < 1600) + /* For vs2003/7.1 up to vs2008/9.0; _MSC_VER 1600 is vs2010/10.0 */ + typedef unsigned __int8 uint8_t; + typedef unsigned __int32 uint32_t; + typedef unsigned __int64 uint64_t; +#else + #include /* uint64_t uint32_t uint8_t */ +#endif + + +/* + * Workaround to not require a C++11 compiler for using ULL suffix + * if this code is included and compiled as C++; related GCC warning is: + * warning: use of C++11 long long integer constant [-Wlong-long] + */ +#define _SIP_ULL(high, low) (((uint64_t)high << 32) | low) #define SIP_ROTL(x, b) (uint64_t)(((x) << (b)) | ( (x) >> (64 - (b)))) @@ -158,11 +184,12 @@ static void sip_round(struct siphash *H, const int rounds) { } /* sip_round() */ -static struct siphash *sip24_init(struct siphash *H, const struct sipkey *key) { - H->v0 = 0x736f6d6570736575UL ^ key->k[0]; - H->v1 = 0x646f72616e646f6dUL ^ key->k[1]; - H->v2 = 0x6c7967656e657261UL ^ key->k[0]; - H->v3 = 0x7465646279746573UL ^ key->k[1]; +static struct siphash *sip24_init(struct siphash *H, + const struct sipkey *key) { + H->v0 = _SIP_ULL(0x736f6d65U, 0x70736575U) ^ key->k[0]; + H->v1 = _SIP_ULL(0x646f7261U, 0x6e646f6dU) ^ key->k[1]; + H->v2 = _SIP_ULL(0x6c796765U, 0x6e657261U) ^ key->k[0]; + H->v3 = _SIP_ULL(0x74656462U, 0x79746573U) ^ key->k[1]; H->p = H->buf; H->c = 0; @@ -173,7 +200,8 @@ static struct siphash *sip24_init(struct siphash *H, const struct sipkey *key) { #define sip_endof(a) (&(a)[sizeof (a) / sizeof *(a)]) -static struct siphash *sip24_update(struct siphash *H, const void *src, size_t len) { +static struct siphash *sip24_update(struct siphash *H, const void *src, + size_t len) { const unsigned char *p = (const unsigned char *)src, *pe = p + len; uint64_t m; @@ -198,7 +226,7 @@ static struct siphash *sip24_update(struct siphash *H, const void *src, size_t l static uint64_t sip24_final(struct siphash *H) { - char left = H->p - H->buf; + const char left = (char)(H->p - H->buf); uint64_t b = (H->c + left) << 56; switch (left) { @@ -222,7 +250,8 @@ static uint64_t sip24_final(struct siphash *H) { } /* sip24_final() */ -static uint64_t siphash24(const void *src, size_t len, const struct sipkey *key) { +static uint64_t siphash24(const void *src, size_t len, + const struct sipkey *key) { struct siphash state = SIPHASH_INITIALIZER; return sip24_final(sip24_update(sip24_init(&state, key), src, len)); } /* siphash24() */ @@ -310,10 +339,11 @@ static int sip24_valid(void) { struct sipkey k; size_t i; - sip_tokey(&k, "\000\001\002\003\004\005\006\007\010\011\012\013\014\015\016\017"); + sip_tokey(&k, "\000\001\002\003\004\005\006\007\010\011" + "\012\013\014\015\016\017"); for (i = 0; i < sizeof in; ++i) { - in[i] = i; + in[i] = (unsigned char)i; if (siphash24(in, i, &k) != SIP_U8TO64_LE(vectors[i])) return 0; @@ -323,12 +353,12 @@ static int sip24_valid(void) { } /* sip24_valid() */ -#if SIPHASH_MAIN +#ifdef SIPHASH_MAIN #include int main(void) { - int ok = sip24_valid(); + const int ok = sip24_valid(); if (ok) puts("OK"); diff --git a/Modules/expat/utf8tab.h b/Modules/expat/utf8tab.h index 7bb3e77603fa75..fa0bed6f5d751d 100644 --- a/Modules/expat/utf8tab.h +++ b/Modules/expat/utf8tab.h @@ -1,7 +1,34 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. -*/ +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. +*/ /* 0x80 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, /* 0x84 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, diff --git a/Modules/expat/winconfig.h b/Modules/expat/winconfig.h index 9bf014d7fbabd6..17fea4689001f4 100644 --- a/Modules/expat/winconfig.h +++ b/Modules/expat/winconfig.h @@ -1,10 +1,33 @@ -/*================================================================ -** Copyright 2000, Clark Cooper -** All rights reserved. -** -** This is free software. You are permitted to copy, distribute, or modify -** it under the terms of the MIT/X license (contained in the COPYING file -** with this distribution.) +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #ifndef WINCONFIG_H diff --git a/Modules/expat/xmlparse.c b/Modules/expat/xmlparse.c index 76f078e2505f90..0df68830f05e3a 100644 --- a/Modules/expat/xmlparse.c +++ b/Modules/expat/xmlparse.c @@ -1,10 +1,38 @@ -/* Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. - - 77fea421d361dca90041d0040ecf1dca651167fadf2af79e990e35168d70d933 (2.2.1+) +/* 8c6b2be7c6281da65ce05218fc15c339f02a811706340824ab596aa86e1fd51a (2.2.4+) + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ -#define _GNU_SOURCE /* syscall prototype */ +#if !defined(_GNU_SOURCE) +# define _GNU_SOURCE 1 /* syscall prototype */ +#endif #include #include /* memset(), memcpy() */ @@ -19,6 +47,8 @@ #include /* gettimeofday() */ #include /* getpid() */ #include /* getpid() */ +#include /* O_RDONLY */ +#include #endif #define XML_BUILDING_EXPAT 1 @@ -33,6 +63,54 @@ #include "expat.h" #include "siphash.h" +#if defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) +# if defined(HAVE_GETRANDOM) +# include /* getrandom */ +# else +# include /* syscall */ +# include /* SYS_getrandom */ +# endif +# if ! defined(GRND_NONBLOCK) +# define GRND_NONBLOCK 0x0001 +# endif /* defined(GRND_NONBLOCK) */ +#endif /* defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) */ + +#if defined(HAVE_LIBBSD) \ + && (defined(HAVE_ARC4RANDOM_BUF) || defined(HAVE_ARC4RANDOM)) +# include +#endif + +#if defined(_WIN32) && !defined(LOAD_LIBRARY_SEARCH_SYSTEM32) +# define LOAD_LIBRARY_SEARCH_SYSTEM32 0x00000800 +#endif + +#if !defined(HAVE_GETRANDOM) && !defined(HAVE_SYSCALL_GETRANDOM) \ + && !defined(HAVE_ARC4RANDOM_BUF) && !defined(HAVE_ARC4RANDOM) \ + && !defined(XML_DEV_URANDOM) \ + && !defined(_WIN32) \ + && !defined(XML_POOR_ENTROPY) +# error \ + You do not have support for any sources of high quality entropy \ + enabled. For end user security, that is probably not what you want. \ + \ + Your options include: \ + * Linux + glibc >=2.25 (getrandom): HAVE_GETRANDOM, \ + * Linux + glibc <2.25 (syscall SYS_getrandom): HAVE_SYSCALL_GETRANDOM, \ + * BSD / macOS >=10.7 (arc4random_buf): HAVE_ARC4RANDOM_BUF, \ + * BSD / macOS <10.7 (arc4random): HAVE_ARC4RANDOM, \ + * libbsd (arc4random_buf): HAVE_ARC4RANDOM_BUF + HAVE_LIBBSD, \ + * libbsd (arc4random): HAVE_ARC4RANDOM + HAVE_LIBBSD, \ + * Linux / BSD / macOS (/dev/urandom): XML_DEV_URANDOM \ + * Windows (RtlGenRandom): _WIN32. \ + \ + If insist on not using any of these, bypass this error by defining \ + XML_POOR_ENTROPY; you have been warned. \ + \ + If you have reasons to patch this detection code away or need changes \ + to the build system, please open a bug. Thank you! +#endif + + #ifdef XML_UNICODE #define XML_ENCODE_MAX XML_UTF16_ENCODE_MAX #define XmlConvert XmlUtf16Convert @@ -436,6 +514,9 @@ static ELEMENT_TYPE * getElementType(XML_Parser parser, const ENCODING *enc, const char *ptr, const char *end); +static XML_Char *copyString(const XML_Char *s, + const XML_Memory_Handling_Suite *memsuite); + static unsigned long generate_hash_secret_salt(XML_Parser parser); static XML_Bool startParsing(XML_Parser parser); @@ -696,21 +777,13 @@ static const XML_Char implicitContext[] = { #if defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) -# include - -# if defined(HAVE_GETRANDOM) -# include /* getrandom */ -# else -# include /* syscall */ -# include /* SYS_getrandom */ -# endif /* Obtain entropy on Linux 3.17+ */ static int -writeRandomBytes_getrandom(void * target, size_t count) { +writeRandomBytes_getrandom_nonblock(void * target, size_t count) { int success = 0; /* full count bytes written? */ size_t bytesWrittenTotal = 0; - const unsigned int getrandomFlags = 0; + const unsigned int getrandomFlags = GRND_NONBLOCK; do { void * const currentTarget = (void*)((char*)target + bytesWrittenTotal); @@ -728,7 +801,7 @@ writeRandomBytes_getrandom(void * target, size_t count) { if (bytesWrittenTotal >= count) success = 1; } - } while (! success && (errno == EINTR || errno == EAGAIN)); + } while (! success && (errno == EINTR)); return success; } @@ -736,12 +809,67 @@ writeRandomBytes_getrandom(void * target, size_t count) { #endif /* defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) */ +#if ! defined(_WIN32) && defined(XML_DEV_URANDOM) + +/* Extract entropy from /dev/urandom */ +static int +writeRandomBytes_dev_urandom(void * target, size_t count) { + int success = 0; /* full count bytes written? */ + size_t bytesWrittenTotal = 0; + + const int fd = open("/dev/urandom", O_RDONLY); + if (fd < 0) { + return 0; + } + + do { + void * const currentTarget = (void*)((char*)target + bytesWrittenTotal); + const size_t bytesToWrite = count - bytesWrittenTotal; + + const ssize_t bytesWrittenMore = read(fd, currentTarget, bytesToWrite); + + if (bytesWrittenMore > 0) { + bytesWrittenTotal += bytesWrittenMore; + if (bytesWrittenTotal >= count) + success = 1; + } + } while (! success && (errno == EINTR)); + + close(fd); + return success; +} + +#endif /* ! defined(_WIN32) && defined(XML_DEV_URANDOM) */ + + +#if defined(HAVE_ARC4RANDOM) + +static void +writeRandomBytes_arc4random(void * target, size_t count) { + size_t bytesWrittenTotal = 0; + + while (bytesWrittenTotal < count) { + const uint32_t random32 = arc4random(); + size_t i = 0; + + for (; (i < sizeof(random32)) && (bytesWrittenTotal < count); + i++, bytesWrittenTotal++) { + const uint8_t random8 = (uint8_t)(random32 >> (i * 8)); + ((uint8_t *)target)[bytesWrittenTotal] = random8; + } + } +} + +#endif /* defined(HAVE_ARC4RANDOM) */ + + #ifdef _WIN32 typedef BOOLEAN (APIENTRY *RTLGENRANDOM_FUNC)(PVOID, ULONG); +HMODULE _Expat_LoadLibrary(LPCTSTR filename); /* see loadlibrary.c */ /* Obtain entropy on Windows XP / Windows Server 2003 and later. - * Hint on RtlGenRandom and the following article from libsodioum. + * Hint on RtlGenRandom and the following article from libsodium. * * Michael Howard: Cryptographically Secure Random number on Windows without using CryptoAPI * https://blogs.msdn.microsoft.com/michael_howard/2005/01/14/cryptographically-secure-random-number-on-windows-without-using-cryptoapi/ @@ -749,7 +877,7 @@ typedef BOOLEAN (APIENTRY *RTLGENRANDOM_FUNC)(PVOID, ULONG); static int writeRandomBytes_RtlGenRandom(void * target, size_t count) { int success = 0; /* full count bytes written? */ - const HMODULE advapi32 = LoadLibrary("ADVAPI32.DLL"); + const HMODULE advapi32 = _Expat_LoadLibrary(TEXT("ADVAPI32.DLL")); if (advapi32) { const RTLGENRANDOM_FUNC RtlGenRandom @@ -768,6 +896,8 @@ writeRandomBytes_RtlGenRandom(void * target, size_t count) { #endif /* _WIN32 */ +#if ! defined(HAVE_ARC4RANDOM_BUF) && ! defined(HAVE_ARC4RANDOM) + static unsigned long gather_time_entropy(void) { @@ -780,16 +910,20 @@ gather_time_entropy(void) int gettimeofday_res; gettimeofday_res = gettimeofday(&tv, NULL); + +#if defined(NDEBUG) + (void)gettimeofday_res; +#else assert (gettimeofday_res == 0); +#endif /* defined(NDEBUG) */ /* Microseconds time is <20 bits entropy */ return tv.tv_usec; #endif } -#if defined(HAVE_ARC4RANDOM_BUF) && defined(HAVE_LIBBSD) -# include -#endif +#endif /* ! defined(HAVE_ARC4RANDOM_BUF) && ! defined(HAVE_ARC4RANDOM) */ + static unsigned long ENTROPY_DEBUG(const char * label, unsigned long entropy) { @@ -808,10 +942,12 @@ generate_hash_secret_salt(XML_Parser parser) { unsigned long entropy; (void)parser; -#if defined(HAVE_ARC4RANDOM_BUF) || defined(__CloudABI__) - (void)gather_time_entropy; +#if defined(HAVE_ARC4RANDOM_BUF) arc4random_buf(&entropy, sizeof(entropy)); return ENTROPY_DEBUG("arc4random_buf", entropy); +#elif defined(HAVE_ARC4RANDOM) + writeRandomBytes_arc4random((void *)&entropy, sizeof(entropy)); + return ENTROPY_DEBUG("arc4random", entropy); #else /* Try high quality providers first .. */ #ifdef _WIN32 @@ -819,10 +955,15 @@ generate_hash_secret_salt(XML_Parser parser) return ENTROPY_DEBUG("RtlGenRandom", entropy); } #elif defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) - if (writeRandomBytes_getrandom((void *)&entropy, sizeof(entropy))) { + if (writeRandomBytes_getrandom_nonblock((void *)&entropy, sizeof(entropy))) { return ENTROPY_DEBUG("getrandom", entropy); } #endif +#if ! defined(_WIN32) && defined(XML_DEV_URANDOM) + if (writeRandomBytes_dev_urandom((void *)&entropy, sizeof(entropy))) { + return ENTROPY_DEBUG("/dev/urandom", entropy); + } +#endif /* ! defined(_WIN32) && defined(XML_DEV_URANDOM) */ /* .. and self-made low quality for backup: */ /* Process ID is 0 bits entropy if attacker has local access */ @@ -833,7 +974,7 @@ generate_hash_secret_salt(XML_Parser parser) return ENTROPY_DEBUG("fallback(4)", entropy * 2147483647); } else { return ENTROPY_DEBUG("fallback(8)", - entropy * (unsigned long)2305843009213693951); + entropy * (unsigned long)2305843009213693951ULL); } #endif } @@ -962,6 +1103,8 @@ parserCreate(const XML_Char *encodingName, nsAttsVersion = 0; nsAttsPower = 0; + protocolEncodingName = NULL; + poolInit(&tempPool, &(parser->m_mem)); poolInit(&temp2Pool, &(parser->m_mem)); parserInit(parser, encodingName); @@ -988,9 +1131,9 @@ parserInit(XML_Parser parser, const XML_Char *encodingName) { processor = prologInitProcessor; XmlPrologStateInit(&prologState); - protocolEncodingName = (encodingName != NULL - ? poolCopyString(&tempPool, encodingName) - : NULL); + if (encodingName != NULL) { + protocolEncodingName = copyString(encodingName, &(parser->m_mem)); + } curBase = NULL; XmlInitEncoding(&initEncoding, &encoding, 0); userData = NULL; @@ -1103,6 +1246,8 @@ XML_ParserReset(XML_Parser parser, const XML_Char *encodingName) unknownEncodingRelease(unknownEncodingData); poolClear(&tempPool); poolClear(&temp2Pool); + FREE((void *)protocolEncodingName); + protocolEncodingName = NULL; parserInit(parser, encodingName); dtdReset(_dtd, &parser->m_mem); return XML_TRUE; @@ -1119,10 +1264,16 @@ XML_SetEncoding(XML_Parser parser, const XML_Char *encodingName) */ if (ps_parsing == XML_PARSING || ps_parsing == XML_SUSPENDED) return XML_STATUS_ERROR; + + /* Get rid of any previous encoding name */ + FREE((void *)protocolEncodingName); + if (encodingName == NULL) + /* No new encoding name */ protocolEncodingName = NULL; else { - protocolEncodingName = poolCopyString(&tempPool, encodingName); + /* Copy the new encoding name into allocated memory */ + protocolEncodingName = copyString(encodingName, &(parser->m_mem)); if (!protocolEncodingName) return XML_STATUS_ERROR; } @@ -1357,6 +1508,7 @@ XML_ParserFree(XML_Parser parser) destroyBindings(inheritedBindings, parser); poolDestroy(&tempPool); poolDestroy(&temp2Pool); + FREE((void *)protocolEncodingName); #ifdef XML_DTD /* external parameter entity parsers share the DTD structure parser->m_dtd with the root parser, so we must not destroy it @@ -1748,7 +1900,8 @@ enum XML_Status XMLCALL XML_Parse(XML_Parser parser, const char *s, int len, int isFinal) { if ((parser == NULL) || (len < 0) || ((s == NULL) && (len != 0))) { - errorCode = XML_ERROR_INVALID_ARGUMENT; + if (parser != NULL) + parser->m_errorCode = XML_ERROR_INVALID_ARGUMENT; return XML_STATUS_ERROR; } switch (ps_parsing) { @@ -1783,9 +1936,22 @@ XML_Parse(XML_Parser parser, const char *s, int len, int isFinal) if (errorCode == XML_ERROR_NONE) { switch (ps_parsing) { case XML_SUSPENDED: + /* It is hard to be certain, but it seems that this case + * cannot occur. This code is cleaning up a previous parse + * with no new data (since len == 0). Changing the parsing + * state requires getting to execute a handler function, and + * there doesn't seem to be an opportunity for that while in + * this circumstance. + * + * Given the uncertainty, we retain the code but exclude it + * from coverage tests. + * + * LCOV_EXCL_START + */ XmlUpdatePosition(encoding, positionPtr, bufferPtr, &position); positionPtr = bufferPtr; return XML_STATUS_SUSPENDED; + /* LCOV_EXCL_STOP */ case XML_INITIALIZED: case XML_PARSING: ps_parsing = XML_FINISHED; @@ -2974,9 +3140,17 @@ doContent(XML_Parser parser, return XML_ERROR_NO_MEMORY; break; default: + /* All of the tokens produced by XmlContentTok() have their own + * explicit cases, so this default is not strictly necessary. + * However it is a useful safety net, so we retain the code and + * simply exclude it from the coverage tests. + * + * LCOV_EXCL_START + */ if (defaultHandler) reportDefault(parser, enc, s, next); break; + /* LCOV_EXCL_STOP */ } *eventPP = s = next; switch (ps_parsing) { @@ -3067,13 +3241,17 @@ storeAtts(XML_Parser parser, const ENCODING *enc, #endif attsSize = n + nDefaultAtts + INIT_ATTS_SIZE; temp = (ATTRIBUTE *)REALLOC((void *)atts, attsSize * sizeof(ATTRIBUTE)); - if (temp == NULL) + if (temp == NULL) { + attsSize = oldAttsSize; return XML_ERROR_NO_MEMORY; + } atts = temp; #ifdef XML_ATTR_INFO temp2 = (XML_AttrInfo *)REALLOC((void *)attInfo, attsSize * sizeof(XML_AttrInfo)); - if (temp2 == NULL) + if (temp2 == NULL) { + attsSize = oldAttsSize; return XML_ERROR_NO_MEMORY; + } attInfo = temp2; #endif if (n > oldAttsSize) @@ -3210,6 +3388,7 @@ storeAtts(XML_Parser parser, const ENCODING *enc, int j; /* hash table index */ unsigned long version = nsAttsVersion; int nsAttsSize = (int)1 << nsAttsPower; + unsigned char oldNsAttsPower = nsAttsPower; /* size of hash table must be at least 2 * (# of prefixed attributes) */ if ((nPrefixes << 1) >> nsAttsPower) { /* true for nsAttsPower = 0 */ NS_ATT *temp; @@ -3219,8 +3398,11 @@ storeAtts(XML_Parser parser, const ENCODING *enc, nsAttsPower = 3; nsAttsSize = (int)1 << nsAttsPower; temp = (NS_ATT *)REALLOC(nsAtts, nsAttsSize * sizeof(NS_ATT)); - if (!temp) + if (!temp) { + /* Restore actual size of memory in nsAtts */ + nsAttsPower = oldNsAttsPower; return XML_ERROR_NO_MEMORY; + } nsAtts = temp; version = 0; /* force re-initialization of nsAtts hash table */ } @@ -3247,8 +3429,23 @@ storeAtts(XML_Parser parser, const ENCODING *enc, ((XML_Char *)s)[-1] = 0; /* clear flag */ id = (ATTRIBUTE_ID *)lookup(parser, &dtd->attributeIds, s, 0); - if (!id || !id->prefix) - return XML_ERROR_NO_MEMORY; + if (!id || !id->prefix) { + /* This code is walking through the appAtts array, dealing + * with (in this case) a prefixed attribute name. To be in + * the array, the attribute must have already been bound, so + * has to have passed through the hash table lookup once + * already. That implies that an entry for it already + * exists, so the lookup above will return a pointer to + * already allocated memory. There is no opportunaity for + * the allocator to fail, so the condition above cannot be + * fulfilled. + * + * Since it is difficult to be certain that the above + * analysis is complete, we retain the test and merely + * remove the code from coverage tests. + */ + return XML_ERROR_NO_MEMORY; /* LCOV_EXCL_LINE */ + } b = id->prefix->binding; if (!b) return XML_ERROR_UNBOUND_PREFIX; @@ -3625,8 +3822,16 @@ doCdataSection(XML_Parser parser, } return XML_ERROR_UNCLOSED_CDATA_SECTION; default: + /* Every token returned by XmlCdataSectionTok() has its own + * explicit case, so this default case will never be executed. + * We retain it as a safety net and exclude it from the coverage + * statistics. + * + * LCOV_EXCL_START + */ *eventPP = next; return XML_ERROR_UNEXPECTED_STATE; + /* LCOV_EXCL_STOP */ } *eventPP = s = next; @@ -3686,8 +3891,20 @@ doIgnoreSection(XML_Parser parser, eventEndPP = &eventEndPtr; } else { + /* It's not entirely clear, but it seems the following two lines + * of code cannot be executed. The only occasions on which 'enc' + * is not 'parser->m_encoding' are when this function is called + * from the internal entity processing, and IGNORE sections are an + * error in internal entities. + * + * Since it really isn't clear that this is true, we keep the code + * and just remove it from our coverage tests. + * + * LCOV_EXCL_START + */ eventPP = &(openInternalEntities->internalEventPtr); eventEndPP = &(openInternalEntities->internalEventEndPtr); + /* LCOV_EXCL_STOP */ } *eventPP = s; *startPtr = NULL; @@ -3720,8 +3937,16 @@ doIgnoreSection(XML_Parser parser, } return XML_ERROR_SYNTAX; /* XML_ERROR_UNCLOSED_IGNORE_SECTION */ default: + /* All of the tokens that XmlIgnoreSectionTok() returns have + * explicit cases to handle them, so this default case is never + * executed. We keep it as a safety net anyway, and remove it + * from our test coverage statistics. + * + * LCOV_EXCL_START + */ *eventPP = next; return XML_ERROR_UNEXPECTED_STATE; + /* LCOV_EXCL_STOP */ } /* not reached */ } @@ -3734,6 +3959,7 @@ initializeEncoding(XML_Parser parser) const char *s; #ifdef XML_UNICODE char encodingBuf[128]; + /* See comments abount `protoclEncodingName` in parserInit() */ if (!protocolEncodingName) s = NULL; else { @@ -3817,7 +4043,14 @@ processXmlDecl(XML_Parser parser, int isGeneralTextEntity, reportDefault(parser, encoding, s, next); if (protocolEncodingName == NULL) { if (newEncoding) { - if (newEncoding->minBytesPerChar != encoding->minBytesPerChar) { + /* Check that the specified encoding does not conflict with what + * the parser has already deduced. Do we have the same number + * of bytes in the smallest representation of a character? If + * this is UTF-16, is it the same endianness? + */ + if (newEncoding->minBytesPerChar != encoding->minBytesPerChar + || (newEncoding->minBytesPerChar == 2 && + newEncoding != encoding)) { eventPtr = encodingName; return XML_ERROR_INCORRECT_ENCODING; } @@ -3962,15 +4195,14 @@ entityValueInitProcessor(XML_Parser parser, result = processXmlDecl(parser, 0, start, next); if (result != XML_ERROR_NONE) return result; - switch (ps_parsing) { - case XML_SUSPENDED: - *nextPtr = next; - return XML_ERROR_NONE; - case XML_FINISHED: + /* At this point, ps_parsing cannot be XML_SUSPENDED. For that + * to happen, a parameter entity parsing handler must have + * attempted to suspend the parser, which fails and raises an + * error. The parser can be aborted, but can't be suspended. + */ + if (ps_parsing == XML_FINISHED) return XML_ERROR_ABORTED; - default: - *nextPtr = next; - } + *nextPtr = next; /* stop scanning for text declaration - we found one */ processor = entityValueProcessor; return entityValueProcessor(parser, next, end, nextPtr); @@ -4293,8 +4525,14 @@ doProlog(XML_Parser parser, &dtd->paramEntities, externalSubsetName, sizeof(ENTITY)); - if (!entity) - return XML_ERROR_NO_MEMORY; + if (!entity) { + /* The external subset name "#" will have already been + * inserted into the hash table at the start of the + * external entity parsing, so no allocation will happen + * and lookup() cannot fail. + */ + return XML_ERROR_NO_MEMORY; /* LCOV_EXCL_LINE */ + } if (useForeignDTD) entity->base = curBase; dtd->paramEntityRead = XML_FALSE; @@ -4773,8 +5011,10 @@ doProlog(XML_Parser parser, if (prologState.level >= groupSize) { if (groupSize) { char *temp = (char *)REALLOC(groupConnector, groupSize *= 2); - if (temp == NULL) + if (temp == NULL) { + groupSize /= 2; return XML_ERROR_NO_MEMORY; + } groupConnector = temp; if (dtd->scaffIndex) { int *temp = (int *)REALLOC(dtd->scaffIndex, @@ -4786,8 +5026,10 @@ doProlog(XML_Parser parser, } else { groupConnector = (char *)MALLOC(groupSize = 32); - if (!groupConnector) + if (!groupConnector) { + groupSize = 0; return XML_ERROR_NO_MEMORY; + } } } groupConnector[prologState.level] = 0; @@ -4850,8 +5092,29 @@ doProlog(XML_Parser parser, : !dtd->hasParamEntityRefs)) { if (!entity) return XML_ERROR_UNDEFINED_ENTITY; - else if (!entity->is_internal) - return XML_ERROR_ENTITY_DECLARED_IN_PE; + else if (!entity->is_internal) { + /* It's hard to exhaustively search the code to be sure, + * but there doesn't seem to be a way of executing the + * following line. There are two cases: + * + * If 'standalone' is false, the DTD must have no + * parameter entities or we wouldn't have passed the outer + * 'if' statement. That measn the only entity in the hash + * table is the external subset name "#" which cannot be + * given as a parameter entity name in XML syntax, so the + * lookup must have returned NULL and we don't even reach + * the test for an internal entity. + * + * If 'standalone' is true, it does not seem to be + * possible to create entities taking this code path that + * are not internal entities, so fail the test above. + * + * Because this analysis is very uncertain, the code is + * being left in place and merely removed from the + * coverage test statistics. + */ + return XML_ERROR_ENTITY_DECLARED_IN_PE; /* LCOV_EXCL_LINE */ + } } else if (!entity) { dtd->keepProcessing = dtd->standalone; @@ -5323,11 +5586,15 @@ appendAttributeValue(XML_Parser parser, const ENCODING *enc, XML_Bool isCdata, && (poolLength(pool) == 0 || poolLastChar(pool) == 0x20)) break; n = XmlEncode(n, (ICHAR *)buf); - if (!n) { - if (enc == encoding) - eventPtr = ptr; - return XML_ERROR_BAD_CHAR_REF; - } + /* The XmlEncode() functions can never return 0 here. That + * error return happens if the code point passed in is either + * negative or greater than or equal to 0x110000. The + * XmlCharRefNumber() functions will all return a number + * strictly less than 0x110000 or a negative value if an error + * occurred. The negative value is intercepted above, so + * XmlEncode() is never passed a value it might return an + * error for. + */ for (i = 0; i < n; i++) { if (!poolAppendChar(pool, buf[i])) return XML_ERROR_NO_MEMORY; @@ -5401,8 +5668,26 @@ appendAttributeValue(XML_Parser parser, const ENCODING *enc, XML_Bool isCdata, break; } if (entity->open) { - if (enc == encoding) - eventPtr = ptr; + if (enc == encoding) { + /* It does not appear that this line can be executed. + * + * The "if (entity->open)" check catches recursive entity + * definitions. In order to be called with an open + * entity, it must have gone through this code before and + * been through the recursive call to + * appendAttributeValue() some lines below. That call + * sets the local encoding ("enc") to the parser's + * internal encoding (internal_utf8 or internal_utf16), + * which can never be the same as the principle encoding. + * It doesn't appear there is another code path that gets + * here with entity->open being TRUE. + * + * Since it is not certain that this logic is watertight, + * we keep the line and merely exclude it from coverage + * tests. + */ + eventPtr = ptr; /* LCOV_EXCL_LINE */ + } return XML_ERROR_RECURSIVE_ENTITY_REF; } if (entity->notation) { @@ -5429,9 +5714,21 @@ appendAttributeValue(XML_Parser parser, const ENCODING *enc, XML_Bool isCdata, } break; default: + /* The only token returned by XmlAttributeValueTok() that does + * not have an explicit case here is XML_TOK_PARTIAL_CHAR. + * Getting that would require an entity name to contain an + * incomplete XML character (e.g. \xE2\x82); however previous + * tokenisers will have already recognised and rejected such + * names before XmlAttributeValueTok() gets a look-in. This + * default case should be retained as a safety net, but the code + * excluded from coverage tests. + * + * LCOV_EXCL_START + */ if (enc == encoding) eventPtr = ptr; return XML_ERROR_UNEXPECTED_STATE; + /* LCOV_EXCL_STOP */ } ptr = next; } @@ -5564,12 +5861,15 @@ storeEntityValue(XML_Parser parser, goto endEntityValue; } n = XmlEncode(n, (ICHAR *)buf); - if (!n) { - if (enc == encoding) - eventPtr = entityTextPtr; - result = XML_ERROR_BAD_CHAR_REF; - goto endEntityValue; - } + /* The XmlEncode() functions can never return 0 here. That + * error return happens if the code point passed in is either + * negative or greater than or equal to 0x110000. The + * XmlCharRefNumber() functions will all return a number + * strictly less than 0x110000 or a negative value if an error + * occurred. The negative value is intercepted above, so + * XmlEncode() is never passed a value it might return an + * error for. + */ for (i = 0; i < n; i++) { if (pool->end == pool->ptr && !poolGrow(pool)) { result = XML_ERROR_NO_MEMORY; @@ -5590,10 +5890,18 @@ storeEntityValue(XML_Parser parser, result = XML_ERROR_INVALID_TOKEN; goto endEntityValue; default: + /* This default case should be unnecessary -- all the tokens + * that XmlEntityValueTok() can return have their own explicit + * cases -- but should be retained for safety. We do however + * exclude it from the coverage statistics. + * + * LCOV_EXCL_START + */ if (enc == encoding) eventPtr = entityTextPtr; result = XML_ERROR_UNEXPECTED_STATE; goto endEntityValue; + /* LCOV_EXCL_STOP */ } entityTextPtr = next; } @@ -5691,8 +5999,25 @@ reportDefault(XML_Parser parser, const ENCODING *enc, eventEndPP = &eventEndPtr; } else { + /* To get here, two things must be true; the parser must be + * using a character encoding that is not the same as the + * encoding passed in, and the encoding passed in must need + * conversion to the internal format (UTF-8 unless XML_UNICODE + * is defined). The only occasions on which the encoding passed + * in is not the same as the parser's encoding are when it is + * the internal encoding (e.g. a previously defined parameter + * entity, already converted to internal format). This by + * definition doesn't need conversion, so the whole branch never + * gets executed. + * + * For safety's sake we don't delete these lines and merely + * exclude them from coverage statistics. + * + * LCOV_EXCL_START + */ eventPP = &(openInternalEntities->internalEventPtr); eventEndPP = &(openInternalEntities->internalEventEndPtr); + /* LCOV_EXCL_STOP */ } do { ICHAR *dataPtr = (ICHAR *)dataBuf; @@ -5861,9 +6186,30 @@ getContext(XML_Parser parser) len = dtd->defaultPrefix.binding->uriLen; if (namespaceSeparator) len--; - for (i = 0; i < len; i++) - if (!poolAppendChar(&tempPool, dtd->defaultPrefix.binding->uri[i])) - return NULL; + for (i = 0; i < len; i++) { + if (!poolAppendChar(&tempPool, dtd->defaultPrefix.binding->uri[i])) { + /* Because of memory caching, I don't believe this line can be + * executed. + * + * This is part of a loop copying the default prefix binding + * URI into the parser's temporary string pool. Previously, + * that URI was copied into the same string pool, with a + * terminating NUL character, as part of setContext(). When + * the pool was cleared, that leaves a block definitely big + * enough to hold the URI on the free block list of the pool. + * The URI copy in getContext() therefore cannot run out of + * memory. + * + * If the pool is used between the setContext() and + * getContext() calls, the worst it can do is leave a bigger + * block on the front of the free list. Given that this is + * all somewhat inobvious and program logic can be changed, we + * don't delete the line but we do exclude it from the test + * coverage statistics. + */ + return NULL; /* LCOV_EXCL_LINE */ + } + } needSep = XML_TRUE; } @@ -5875,8 +6221,15 @@ getContext(XML_Parser parser) PREFIX *prefix = (PREFIX *)hashTableIterNext(&iter); if (!prefix) break; - if (!prefix->binding) - continue; + if (!prefix->binding) { + /* This test appears to be (justifiable) paranoia. There does + * not seem to be a way of injecting a prefix without a binding + * that doesn't get errored long before this function is called. + * The test should remain for safety's sake, so we instead + * exclude the following line from the coverage statistics. + */ + continue; /* LCOV_EXCL_LINE */ + } if (needSep && !poolAppendChar(&tempPool, CONTEXT_SEP)) return NULL; for (s = prefix->name; *s; s++) @@ -6547,8 +6900,20 @@ poolCopyString(STRING_POOL *pool, const XML_Char *s) static const XML_Char * poolCopyStringN(STRING_POOL *pool, const XML_Char *s, int n) { - if (!pool->ptr && !poolGrow(pool)) - return NULL; + if (!pool->ptr && !poolGrow(pool)) { + /* The following line is unreachable given the current usage of + * poolCopyStringN(). Currently it is called from exactly one + * place to copy the text of a simple general entity. By that + * point, the name of the entity is already stored in the pool, so + * pool->ptr cannot be NULL. + * + * If poolCopyStringN() is used elsewhere as it well might be, + * this line may well become executable again. Regardless, this + * sort of check shouldn't be removed lightly, so we just exclude + * it from the coverage statistics. + */ + return NULL; /* LCOV_EXCL_LINE */ + } for (; n > 0; --n, s++) { if (!poolAppendChar(pool, *s)) return NULL; @@ -6641,8 +7006,19 @@ poolGrow(STRING_POOL *pool) int blockSize = (int)((unsigned)(pool->end - pool->start)*2U); size_t bytesToAllocate; - if (blockSize < 0) - return XML_FALSE; + // NOTE: Needs to be calculated prior to calling `realloc` + // to avoid dangling pointers: + const ptrdiff_t offsetInsideBlock = pool->ptr - pool->start; + + if (blockSize < 0) { + /* This condition traps a situation where either more than + * INT_MAX/2 bytes have already been allocated. This isn't + * readily testable, since it is unlikely that an average + * machine will have that much memory, so we exclude it from the + * coverage statistics. + */ + return XML_FALSE; /* LCOV_EXCL_LINE */ + } bytesToAllocate = poolBytesToAllocateFor(blockSize); if (bytesToAllocate == 0) @@ -6654,7 +7030,7 @@ poolGrow(STRING_POOL *pool) return XML_FALSE; pool->blocks = temp; pool->blocks->size = blockSize; - pool->ptr = pool->blocks->s + (pool->ptr - pool->start); + pool->ptr = pool->blocks->s + offsetInsideBlock; pool->start = pool->blocks->s; pool->end = pool->start + blockSize; } @@ -6663,8 +7039,18 @@ poolGrow(STRING_POOL *pool) int blockSize = (int)(pool->end - pool->start); size_t bytesToAllocate; - if (blockSize < 0) - return XML_FALSE; + if (blockSize < 0) { + /* This condition traps a situation where either more than + * INT_MAX bytes have already been allocated (which is prevented + * by various pieces of program logic, not least this one, never + * mind the unlikelihood of actually having that much memory) or + * the pool control fields have been corrupted (which could + * conceivably happen in an extremely buggy user handler + * function). Either way it isn't readily testable, so we + * exclude it from the coverage statistics. + */ + return XML_FALSE; /* LCOV_EXCL_LINE */ + } if (blockSize < INIT_BLOCK_SIZE) blockSize = INIT_BLOCK_SIZE; @@ -6827,3 +7213,26 @@ getElementType(XML_Parser parser, } return ret; } + +static XML_Char * +copyString(const XML_Char *s, + const XML_Memory_Handling_Suite *memsuite) +{ + int charsRequired = 0; + XML_Char *result; + + /* First determine how long the string is */ + while (s[charsRequired] != 0) { + charsRequired++; + } + /* Include the terminator */ + charsRequired++; + + /* Now allocate space for the copy */ + result = memsuite->malloc_fcn(charsRequired * sizeof(XML_Char)); + if (result == NULL) + return NULL; + /* Copy the original into place */ + memcpy(result, s, charsRequired * sizeof(XML_Char)); + return result; +} diff --git a/Modules/expat/xmlrole.c b/Modules/expat/xmlrole.c index a7c56302796957..708507d575be84 100644 --- a/Modules/expat/xmlrole.c +++ b/Modules/expat/xmlrole.c @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #include @@ -170,7 +198,14 @@ prolog1(PROLOG_STATE *state, case XML_TOK_COMMENT: return XML_ROLE_COMMENT; case XML_TOK_BOM: - return XML_ROLE_NONE; + /* This case can never arise. To reach this role function, the + * parse must have passed through prolog0 and therefore have had + * some form of input, even if only a space. At that point, a + * byte order mark is no longer a valid character (though + * technically it should be interpreted as a non-breaking space), + * so will be rejected by the tokenizing stages. + */ + return XML_ROLE_NONE; /* LCOV_EXCL_LINE */ case XML_TOK_DECL_OPEN: if (!XmlNameMatchesAscii(enc, ptr + 2 * MIN_BYTES_PER_CHAR(enc), @@ -1285,6 +1320,26 @@ declClose(PROLOG_STATE *state, return common(state, tok); } +/* This function will only be invoked if the internal logic of the + * parser has broken down. It is used in two cases: + * + * 1: When the XML prolog has been finished. At this point the + * processor (the parser level above these role handlers) should + * switch from prologProcessor to contentProcessor and reinitialise + * the handler function. + * + * 2: When an error has been detected (via common() below). At this + * point again the processor should be switched to errorProcessor, + * which will never call a handler. + * + * The result of this is that error() can only be called if the + * processor switch failed to happen, which is an internal error and + * therefore we shouldn't be able to provoke it simply by using the + * library. It is a necessary backstop, however, so we merely exclude + * it from the coverage statistics. + * + * LCOV_EXCL_START + */ static int PTRCALL error(PROLOG_STATE *UNUSED_P(state), int UNUSED_P(tok), @@ -1294,6 +1349,7 @@ error(PROLOG_STATE *UNUSED_P(state), { return XML_ROLE_NONE; } +/* LCOV_EXCL_STOP */ static int FASTCALL common(PROLOG_STATE *state, int tok) diff --git a/Modules/expat/xmlrole.h b/Modules/expat/xmlrole.h index 4dd9f06f97679e..e5f048eab55c6e 100644 --- a/Modules/expat/xmlrole.h +++ b/Modules/expat/xmlrole.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #ifndef XmlRole_INCLUDED diff --git a/Modules/expat/xmltok.c b/Modules/expat/xmltok.c index cdf0720dd89689..007aed0640a2ef 100644 --- a/Modules/expat/xmltok.c +++ b/Modules/expat/xmltok.c @@ -1,8 +1,38 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #include +#include +#include // memcpy #ifdef _WIN32 #include "winconfig.h" @@ -363,22 +393,33 @@ utf8_toUtf8(const ENCODING *UNUSED_P(enc), const char **fromP, const char *fromLim, char **toP, const char *toLim) { - char *to; - const char *from; - const char *fromLimInitial = fromLim; + bool input_incomplete = false; + bool output_exhausted = false; + + /* Avoid copying partial characters (due to limited space). */ + const ptrdiff_t bytesAvailable = fromLim - *fromP; + const ptrdiff_t bytesStorable = toLim - *toP; + if (bytesAvailable > bytesStorable) { + fromLim = *fromP + bytesStorable; + output_exhausted = true; + } - /* Avoid copying partial characters. */ + /* Avoid copying partial characters (from incomplete input). */ + const char * const fromLimBefore = fromLim; align_limit_to_full_utf8_characters(*fromP, &fromLim); + if (fromLim < fromLimBefore) { + input_incomplete = true; + } - for (to = *toP, from = *fromP; (from < fromLim) && (to < toLim); from++, to++) - *to = *from; - *fromP = from; - *toP = to; + const ptrdiff_t bytesToCopy = fromLim - *fromP; + memcpy((void *)*toP, (const void *)*fromP, (size_t)bytesToCopy); + *fromP += bytesToCopy; + *toP += bytesToCopy; - if (fromLim < fromLimInitial) - return XML_CONVERT_INPUT_INCOMPLETE; - else if ((to == toLim) && (from < fromLim)) + if (output_exhausted) // needs to go first return XML_CONVERT_OUTPUT_EXHAUSTED; + else if (input_incomplete) + return XML_CONVERT_INPUT_INCOMPLETE; else return XML_CONVERT_COMPLETED; } @@ -1019,7 +1060,11 @@ streqci(const char *s1, const char *s2) if (ASCII_a <= c1 && c1 <= ASCII_z) c1 += ASCII_A - ASCII_a; if (ASCII_a <= c2 && c2 <= ASCII_z) - c2 += ASCII_A - ASCII_a; + /* The following line will never get executed. streqci() is + * only called from two places, both of which guarantee to put + * upper-case strings into s2. + */ + c2 += ASCII_A - ASCII_a; /* LCOV_EXCL_LINE */ if (c1 != c2) return 0; if (!c1) @@ -1291,7 +1336,7 @@ XmlUtf8Encode(int c, char *buf) }; if (c < 0) - return 0; + return 0; /* LCOV_EXCL_LINE: this case is always eliminated beforehand */ if (c < min2) { buf[0] = (char)(c | UTF8_cval1); return 1; @@ -1314,7 +1359,7 @@ XmlUtf8Encode(int c, char *buf) buf[3] = (char)((c & 0x3f) | 0x80); return 4; } - return 0; + return 0; /* LCOV_EXCL_LINE: this case too is eliminated before calling */ } int FASTCALL @@ -1465,6 +1510,9 @@ XmlInitUnknownEncoding(void *mem, else if (c < 0) { if (c < -4) return 0; + /* Multi-byte sequences need a converter function */ + if (!convert) + return 0; e->normal.type[i] = (unsigned char)(BT_LEAD2 - (c + 2)); e->utf8[i][0] = 0; e->utf16[i] = 0; diff --git a/Modules/expat/xmltok.h b/Modules/expat/xmltok.h index 752007e8b9e219..6d31879b331d83 100644 --- a/Modules/expat/xmltok.h +++ b/Modules/expat/xmltok.h @@ -1,5 +1,33 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ #ifndef XmlTok_INCLUDED diff --git a/Modules/expat/xmltok_impl.c b/Modules/expat/xmltok_impl.c index 5f779c0571b5b1..93328b841a168b 100644 --- a/Modules/expat/xmltok_impl.c +++ b/Modules/expat/xmltok_impl.c @@ -1,8 +1,35 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* This file is included! + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/* This file is included! */ #ifdef XML_TOK_IMPL_C #ifndef IS_INVALID_CHAR @@ -1198,8 +1225,14 @@ PREFIX(attributeValueTok)(const ENCODING *enc, const char *ptr, const char *start; if (ptr >= end) return XML_TOK_NONE; - else if (! HAS_CHAR(enc, ptr, end)) - return XML_TOK_PARTIAL; + else if (! HAS_CHAR(enc, ptr, end)) { + /* This line cannot be executed. The incoming data has already + * been tokenized once, so incomplete characters like this have + * already been eliminated from the input. Retaining the paranoia + * check is still valuable, however. + */ + return XML_TOK_PARTIAL; /* LCOV_EXCL_LINE */ + } start = ptr; while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { @@ -1258,8 +1291,14 @@ PREFIX(entityValueTok)(const ENCODING *enc, const char *ptr, const char *start; if (ptr >= end) return XML_TOK_NONE; - else if (! HAS_CHAR(enc, ptr, end)) - return XML_TOK_PARTIAL; + else if (! HAS_CHAR(enc, ptr, end)) { + /* This line cannot be executed. The incoming data has already + * been tokenized once, so incomplete characters like this have + * already been eliminated from the input. Retaining the paranoia + * check is still valuable, however. + */ + return XML_TOK_PARTIAL; /* LCOV_EXCL_LINE */ + } start = ptr; while (HAS_CHAR(enc, ptr, end)) { switch (BYTE_TYPE(enc, ptr)) { @@ -1614,6 +1653,14 @@ PREFIX(predefinedEntityName)(const ENCODING *UNUSED_P(enc), const char *ptr, return 0; } +/* This function does not appear to be called from anywhere within the + * library code. It is used via the macro XmlSameName(), which is + * defined but never used. Since it appears in the encoding function + * table, removing it is not a thing to be undertaken lightly. For + * the moment, we simply exclude it from coverage tests. + * + * LCOV_EXCL_START + */ static int PTRCALL PREFIX(sameName)(const ENCODING *enc, const char *ptr1, const char *ptr2) { @@ -1677,14 +1724,21 @@ PREFIX(sameName)(const ENCODING *enc, const char *ptr1, const char *ptr2) } /* not reached */ } +/* LCOV_EXCL_STOP */ static int PTRCALL PREFIX(nameMatchesAscii)(const ENCODING *UNUSED_P(enc), const char *ptr1, const char *end1, const char *ptr2) { for (; *ptr2; ptr1 += MINBPC(enc), ptr2++) { - if (end1 - ptr1 < MINBPC(enc)) - return 0; + if (end1 - ptr1 < MINBPC(enc)) { + /* This line cannot be executed. THe incoming data has already + * been tokenized once, so imcomplete characters like this have + * already been eliminated from the input. Retaining the + * paranoia check is still valuable, however. + */ + return 0; /* LCOV_EXCL_LINE */ + } if (!CHAR_MATCHES(enc, ptr1, *ptr2)) return 0; } diff --git a/Modules/expat/xmltok_impl.h b/Modules/expat/xmltok_impl.h index da0ea60a657d66..a6420f48eedc04 100644 --- a/Modules/expat/xmltok_impl.h +++ b/Modules/expat/xmltok_impl.h @@ -1,6 +1,33 @@ /* -Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd -See the file COPYING for copying permission. + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ enum { diff --git a/Modules/expat/xmltok_ns.c b/Modules/expat/xmltok_ns.c index c3b88fdf4e3eec..23d31e8e424916 100644 --- a/Modules/expat/xmltok_ns.c +++ b/Modules/expat/xmltok_ns.c @@ -1,8 +1,35 @@ -/* Copyright (c) 1998, 1999 Thai Open Source Software Center Ltd - See the file COPYING for copying permission. +/* This file is included! + __ __ _ + ___\ \/ /_ __ __ _| |_ + / _ \\ /| '_ \ / _` | __| + | __// \| |_) | (_| | |_ + \___/_/\_\ .__/ \__,_|\__| + |_| XML parser + + Copyright (c) 1997-2000 Thai Open Source Software Center Ltd + Copyright (c) 2000-2017 Expat development team + Licensed under the MIT license: + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit + persons to whom the Software is furnished to do so, subject to the + following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN + NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE + USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/* This file is included! */ #ifdef XML_TOK_NS_C const ENCODING * diff --git a/setup.py b/setup.py index 277965837c32e4..88c3759d09121b 100644 --- a/setup.py +++ b/setup.py @@ -1423,6 +1423,9 @@ class db_found(Exception): pass expat_inc = [os.path.join(os.getcwd(), srcdir, 'Modules', 'expat')] define_macros = [ ('HAVE_EXPAT_CONFIG_H', '1'), + # bpo-30947: Python uses best available entropy sources to + # call XML_SetHashSalt(), expat entropy sources are not needed + ('XML_POOR_ENTROPY', '1'), ] expat_lib = [] expat_sources = ['expat/xmlparse.c', From 727f419b1a2c32fcc7f86be4c63671740b1f7940 Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Tue, 3 Oct 2017 23:33:54 -0400 Subject: [PATCH 24/24] Remove retired and security branches from active docs (#3883) --- Doc/tools/static/version_switch.js | 8 +++----- Doc/tools/templates/indexsidebar.html | 4 ++-- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/Doc/tools/static/version_switch.js b/Doc/tools/static/version_switch.js index 7289a4d01ea2f6..ea08a960f9d824 100644 --- a/Doc/tools/static/version_switch.js +++ b/Doc/tools/static/version_switch.js @@ -2,13 +2,11 @@ 'use strict'; var all_versions = { - '3.6': 'dev (3.6)', + '3.7': 'dev (3.7)', + '3.6': '3.6', '3.5': '3.5', '3.4': '3.4', - '3.3': '3.3', - '3.2': '3.2', - '2.7': '2.7', - '2.6': '2.6' + '2.7': '2.7' }; function build_select(current_version, current_release) { diff --git a/Doc/tools/templates/indexsidebar.html b/Doc/tools/templates/indexsidebar.html index abdf070772c8f8..8b009418a4ab30 100644 --- a/Doc/tools/templates/indexsidebar.html +++ b/Doc/tools/templates/indexsidebar.html @@ -3,8 +3,8 @@

Download

Docs for other versions