From: DongHun Kwak Date: Mon, 16 Oct 2017 10:56:29 +0000 (+0900) Subject: Imported Upstream version 3.4.5 X-Git-Tag: upstream/3.6.3~11 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=36027d8ce51d3661430ae00b95ca56b10557dc78;p=platform%2Fupstream%2Fpython3.git Imported Upstream version 3.4.5 Change-Id: I31435ecc855874ee0c136dd39a0f6d7df18cc43f Signed-off-by: DongHun Kwak --- diff --git a/Doc/README.txt b/Doc/README.txt index 58bda626..f985e6e3 100644 --- a/Doc/README.txt +++ b/Doc/README.txt @@ -119,27 +119,3 @@ and we will process your request as soon as possible. If you want to help the Documentation Team, you are always welcome. Just send a mail to docs@python.org. - - -Copyright notice -================ - -The Python source is copyrighted, but you can freely use and copy it -as long as you don't change or remove the copyright notice: - ----------------------------------------------------------------------- -Copyright (c) 2000-2015 Python Software Foundation. -All rights reserved. - -Copyright (c) 2000 BeOpen.com. -All rights reserved. - -Copyright (c) 1995-2000 Corporation for National Research Initiatives. -All rights reserved. - -Copyright (c) 1991-1995 Stichting Mathematisch Centrum. -All rights reserved. - -See the file "license.rst" for information on usage and redistribution -of this file, and for a DISCLAIMER OF ALL WARRANTIES. ----------------------------------------------------------------------- diff --git a/Doc/copyright.rst b/Doc/copyright.rst index 2b2f8870..22d77058 100644 --- a/Doc/copyright.rst +++ b/Doc/copyright.rst @@ -4,7 +4,7 @@ Copyright Python and this documentation is: -Copyright © 2001-2015 Python Software Foundation. All rights reserved. +Copyright © 2001-2016 Python Software Foundation. All rights reserved. Copyright © 2000 BeOpen.com. All rights reserved. diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 295445ed..94b428d2 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -1010,8 +1010,7 @@ performance levels: may come up with. This is doubly true for primitives written in C, such as builtins and some extension types. For example, be sure to use either the :meth:`list.sort` built-in method or the related :func:`sorted` - function to do sorting (and see the - `sorting mini-HOWTO `_ for examples + function to do sorting (and see the :ref:`sortinghowto` for examples of moderately advanced usage). * Abstractions tend to create indirections and force the interpreter to work diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 5373acd5..8c3b7e4c 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -249,3 +249,8 @@ and classes for traversing abstract syntax trees: wanted *annotate_fields* must be set to ``False``. Attributes such as line numbers and column offsets are not dumped by default. If this is wanted, *include_attributes* can be set to ``True``. + +.. seealso:: + + `Green Tree Snakes `_, an external documentation resource, has good + details on working with Python ASTs. diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index 78faeaec..f9298b2d 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -1,8 +1,8 @@ .. currentmodule:: asyncio -+++++++++++++++++++++++++++++++++++++++++ -Transports and protocols (low-level API) -+++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++ +Transports and protocols (callback based API) +++++++++++++++++++++++++++++++++++++++++++++++ .. _asyncio-transport: diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 171fd862..52b93f9a 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -2,9 +2,9 @@ .. _asyncio-streams: -++++++++++++++++++++++++ -Streams (high-level API) -++++++++++++++++++++++++ ++++++++++++++++++++++++++++++ +Streams (coroutine based API) ++++++++++++++++++++++++++++++ Stream functions ================ diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index feea9d25..76f084a2 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -363,9 +363,10 @@ Task running in different threads. While a task waits for the completion of a future, the event loop executes a new task. - The cancellation of a task is different from the cancelation of a future. Calling - :meth:`cancel` will throw a :exc:`~concurrent.futures.CancelledError` to the - wrapped coroutine. :meth:`~Future.cancelled` only returns ``True`` if the + The cancellation of a task is different from the cancelation of a + future. Calling :meth:`cancel` will throw a + :exc:`~concurrent.futures.CancelledError` to the wrapped + coroutine. :meth:`~Future.cancelled` only returns ``True`` if the wrapped coroutine did not catch the :exc:`~concurrent.futures.CancelledError` exception, or raised a :exc:`~concurrent.futures.CancelledError` exception. @@ -417,10 +418,11 @@ Task Return the list of stack frames for this task's coroutine. - If the coroutine is not done, this returns the stack where it is suspended. - If the coroutine has completed successfully or was cancelled, this - returns an empty list. If the coroutine was terminated by an exception, - this returns the list of traceback frames. + If the coroutine is not done, this returns the stack where it is + suspended. If the coroutine has completed successfully or was + cancelled, this returns an empty list. If the coroutine was + terminated by an exception, this returns the list of traceback + frames. The frames are always ordered from oldest to newest. @@ -557,6 +559,45 @@ Task functions Return ``True`` if *func* is a decorated :ref:`coroutine function `. +.. function:: run_coroutine_threadsafe(coro, loop) + + Submit a :ref:`coroutine object ` to a given event loop. + + Return a :class:`concurrent.futures.Future` to access the result. + + This function is meant to be called from a different thread than the one + where the event loop is running. Usage:: + + # Create a coroutine + coro = asyncio.sleep(1, result=3) + # Submit the coroutine to a given loop + future = asyncio.run_coroutine_threadsafe(coro, loop) + # Wait for the result with an optional timeout argument + assert future.result(timeout) == 3 + + If an exception is raised in the coroutine, the returned future will be + notified. It can also be used to cancel the task in the event loop:: + + try: + result = future.result(timeout) + except asyncio.TimeoutError: + print('The coroutine took too long, cancelling the task...') + future.cancel() + except Exception as exc: + print('The coroutine raised an exception: {!r}'.format(exc)) + else: + print('The coroutine returned: {!r}'.format(result)) + + See the :ref:`concurrency and multithreading ` + section of the documentation. + + .. note:: + + Unlike the functions above, :func:`run_coroutine_threadsafe` requires the + *loop* argument to be passed explicitely. + + .. versionadded:: 3.4.4, 3.5.1 + .. coroutinefunction:: sleep(delay, result=None, \*, loop=None) Create a :ref:`coroutine ` that completes after a given @@ -595,7 +636,21 @@ Task functions except CancelledError: res = None -.. coroutinefunction:: wait(futures, \*, loop=None, timeout=None, return_when=ALL_COMPLETED) +.. function:: timeout(timeout, \*, loop=None) + + Return a context manager that cancels a block on *timeout* expiring:: + + with timeout(1.5): + yield from inner() + + 1. If ``inner()`` is executed faster than in ``1.5`` seconds + nothing happens. + 2. Otherwise ``inner()`` is cancelled internally but + :exc:`asyncio.TimeoutError` is raised outside of + context manager scope. + +.. coroutinefunction:: wait(futures, \*, loop=None, timeout=None,\ + return_when=ALL_COMPLETED) Wait for the Futures and coroutine objects given by the sequence *futures* to complete. Coroutines will be wrapped in Tasks. Returns two sets of @@ -662,41 +717,3 @@ Task functions If the wait is cancelled, the future *fut* is now also cancelled. -.. function:: run_coroutine_threadsafe(coro, loop) - - Submit a :ref:`coroutine object ` to a given event loop. - - Return a :class:`concurrent.futures.Future` to access the result. - - This function is meant to be called from a different thread than the one - where the event loop is running. Usage:: - - # Create a coroutine - coro = asyncio.sleep(1, result=3) - # Submit the coroutine to a given loop - future = asyncio.run_coroutine_threadsafe(coro, loop) - # Wait for the result with an optional timeout argument - assert future.result(timeout) == 3 - - If an exception is raised in the coroutine, the returned future will be - notified. It can also be used to cancel the task in the event loop:: - - try: - result = future.result(timeout) - except asyncio.TimeoutError: - print('The coroutine took too long, cancelling the task...') - future.cancel() - except Exception as exc: - print('The coroutine raised an exception: {!r}'.format(exc)) - else: - print('The coroutine returned: {!r}'.format(result)) - - See the :ref:`concurrency and multithreading ` - section of the documentation. - - .. note:: - - Unlike the functions above, :func:`run_coroutine_threadsafe` requires the - *loop* argument to be passed explicitely. - - .. versionadded:: 3.4.4, 3.5.1 diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst index e3f134b5..dbe535d9 100644 --- a/Doc/library/binascii.rst +++ b/Doc/library/binascii.rst @@ -55,8 +55,10 @@ The :mod:`binascii` module defines the following functions: .. function:: b2a_base64(data) Convert binary data to a line of ASCII characters in base64 coding. The return - value is the converted line, including a newline char. The length of *data* - should be at most 57 to adhere to the base64 standard. + value is the converted line, including a newline char. The newline is + added because the original use case for this function was to feed it a + series of 57 byte input lines to get output lines that conform to the + MIME-base64 standard. Otherwise the output conforms to :rfc:`3548`. .. function:: a2b_qp(data, header=False) @@ -168,7 +170,8 @@ The :mod:`binascii` module defines the following functions: .. seealso:: Module :mod:`base64` - Support for base64 encoding used in MIME email messages. + Support for RFC compliant base64-style encoding in base 16, 32, 64, + and 85. Module :mod:`binhex` Support for the binhex format used on the Macintosh. diff --git a/Doc/library/crypto.rst b/Doc/library/crypto.rst index 8ad24c8d..1eddfdc1 100644 --- a/Doc/library/crypto.rst +++ b/Doc/library/crypto.rst @@ -16,14 +16,3 @@ Here's an overview: hashlib.rst hmac.rst - -.. index:: - pair: AES; algorithm - single: cryptography - single: Kuchling, Andrew - -Hardcore cypherpunks will probably find the cryptographic modules written by -A.M. Kuchling of further interest; the package contains modules for various -encryption algorithms, most notably AES. These modules are not distributed with -Python but available separately. See the URL http://www.pycrypto.org/ for more -information. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 12610626..21aeaf9f 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1296,8 +1296,7 @@ are always available. They are listed here in alphabetical order. compare equal --- this is helpful for sorting in multiple passes (for example, sort by department, then by salary grade). - For sorting examples and a brief sorting tutorial, see `Sorting HowTo - `_\. + For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`. .. function:: staticmethod(function) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 4e75e1c7..8815d389 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1563,10 +1563,9 @@ expression support in the :mod:`re` module). .. method:: str.find(sub[, start[, end]]) - Return the lowest index in the string where substring *sub* is found, such - that *sub* is contained in the slice ``s[start:end]``. Optional arguments - *start* and *end* are interpreted as in slice notation. Return ``-1`` if - *sub* is not found. + Return the lowest index in the string where substring *sub* is found within + the slice ``s[start:end]``. Optional arguments *start* and *end* are + interpreted as in slice notation. Return ``-1`` if *sub* is not found. .. note:: diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 8d8b7d4c..0a3d9772 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -550,9 +550,11 @@ The module defines the following functions and data items: +-------+-------------------+---------------------------------+ Note that unlike the C structure, the month value is a range of [1, 12], not - [0, 11]. A ``-1`` argument as the daylight - savings flag, passed to :func:`mktime` will usually result in the correct - daylight savings state to be filled in. + [0, 11]. + + In calls to :func:`mktime`, :attr:`tm_isdst` may be set to 1 when daylight + savings time is in effect, and 0 when it is not. A value of -1 indicates that + this is not known, and will usually result in the correct state being filled in. When a tuple with an incorrect length is passed to a function expecting a :class:`struct_time`, or having elements of the wrong type, a diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index a8d9f53b..a896fc16 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -118,7 +118,7 @@ and produce a report. The :meth:`~TestCase.setUp` and :meth:`~TestCase.tearDown` methods allow you to define instructions that will be executed before and after each test method. -They are covered in more details in the section :ref:`organizing-tests`. +They are covered in more detail in the section :ref:`organizing-tests`. The final block shows a simple way to run the tests. :func:`unittest.main` provides a command-line interface to the test script. When run from the command diff --git a/Doc/license.rst b/Doc/license.rst index 53a1c4d5..8a613b21 100644 --- a/Doc/license.rst +++ b/Doc/license.rst @@ -84,9 +84,9 @@ Terms and conditions for accessing or otherwise using Python analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python |release| alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of - copyright, i.e., "Copyright © 2001-2015 Python Software Foundation; All - Rights Reserved" are retained in Python |release| alone or in any derivative - version prepared by Licensee. + copyright, i.e., "Copyright © 2001-2016 Python Software Foundation; All Rights + Reserved" are retained in Python |release| alone or in any derivative version + prepared by Licensee. #. In the event Licensee prepares a derivative work that is based on or incorporates Python |release| or any part thereof, and wants to make the diff --git a/Doc/tools/static/copybutton.js b/Doc/tools/static/copybutton.js index 5d82c672..716c9e47 100644 --- a/Doc/tools/static/copybutton.js +++ b/Doc/tools/static/copybutton.js @@ -28,6 +28,7 @@ $(document).ready(function() { var button = $('>>>'); button.css(button_styles) button.attr('title', hide_text); + button.data('hidden', 'false'); jthis.prepend(button); } // tracebacks (.gt) contain bare text elements that need to be @@ -38,20 +39,24 @@ $(document).ready(function() { }); // define the behavior of the button when it's clicked - $('.copybutton').toggle( - function() { - var button = $(this); + $('.copybutton').click(function(e){ + e.preventDefault(); + var button = $(this); + if (button.data('hidden') === 'false') { + // hide the code output button.parent().find('.go, .gp, .gt').hide(); button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden'); button.css('text-decoration', 'line-through'); button.attr('title', show_text); - }, - function() { - var button = $(this); + button.data('hidden', 'true'); + } else { + // show the code output button.parent().find('.go, .gp, .gt').show(); button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible'); button.css('text-decoration', 'none'); button.attr('title', hide_text); - }); + button.data('hidden', 'false'); + } + }); }); diff --git a/Doc/tools/templates/layout.html b/Doc/tools/templates/layout.html index 5abff1b3..8ae6e23f 100644 --- a/Doc/tools/templates/layout.html +++ b/Doc/tools/templates/layout.html @@ -18,7 +18,7 @@ {% if not embedded %}{% endif %} {% if versionswitcher is defined and not embedded %}{% endif %} - {% if pagename == 'whatsnew/changelog' %} + {% if pagename == 'whatsnew/changelog' and not embedded %}