diff options
Diffstat (limited to 'Doc')
76 files changed, 1674 insertions, 638 deletions
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 6bacc32..1f599fe 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -110,6 +110,15 @@ Dictionary Objects :c:type:`char\*`, rather than a :c:type:`PyObject\*`. +.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default) + + This is the same as the Python-level :meth:`dict.setdefault`. If present, it + returns the value corresponding to *key* from the dictionary *p*. If the key + is not in the dict, it is inserted with value *defaultobj* and *defaultobj* + is returned. This function evaluates the hash function of *key* only once, + instead of evaluating it independently for the lookup and the insertion. + + .. c:function:: PyObject* PyDict_Items(PyObject *p) Return a :c:type:`PyListObject` containing all the items from the dictionary. diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 95ff4ee..6f847d9 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -654,6 +654,20 @@ with sub-interpreters: made on the main thread. This is mainly a helper/diagnostic function. +.. c:function:: int PyGILState_Check() + + Return 1 if the current thread is holding the GIL and 0 otherwise. + This function can be called from any thread at any time. + Only if it has had its Python thread state initialized and currently is + holding the GIL will it return 1. + This is mainly a helper/diagnostic function. It can be useful + for example in callback contexts or memory allocation functions when + knowing that the GIL is locked can allow the caller to perform sensitive + actions or otherwise behave differently. + + .. versionadded:: 3.4 + + The following macros are normally used without a trailing semicolon; look for example usage in the Python source distribution. diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index a47183c..02a0d36 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -342,6 +342,15 @@ is considered sufficient for this determination. returned. This is the equivalent to the Python expression ``len(o)``. +.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default) + + Return an estimated length for the object *o*. First trying to return its + actual length, then an estimate using ``__length_hint__``, and finally + returning the default value. On error ``-1`` is returned. This is the + equivalent to the Python expression ``operator.length_hint(o, default)``. + + .. versionadded:: 3.4 + .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key) Return element of *o* corresponding to the object *key* or *NULL* on failure. diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index fac89af..e299050 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -220,6 +220,11 @@ PyDict_GetItemString:PyObject*::0: PyDict_GetItemString:PyObject*:p:0: PyDict_GetItemString:char*:key:: +PyDict_SetDefault:PyObject*::0: +PyDict_SetDefault:PyObject*:p:0: +PyDict_SetDefault:PyObject*:key:0:conditionally +1 if inserted into the dict +PyDict_SetDefault:PyObject*:default:0:conditionally +1 if inserted into the dict + PyDict_Items:PyObject*::+1: PyDict_Items:PyObject*:p:0: diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index c8ef9e7..8bd774b 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -211,7 +211,7 @@ using curses, but curses is a fairly large module to learn. try: c = sys.stdin.read(1) print("Got character", repr(c)) - except IOError: + except OSError: pass finally: termios.tcsetattr(fd, termios.TCSAFLUSH, oldterm) @@ -224,7 +224,11 @@ using curses, but curses is a fairly large module to learn. :func:`termios.tcsetattr` turns off stdin's echoing and disables canonical mode. :func:`fcntl.fnctl` is used to obtain stdin's file descriptor flags and modify them for non-blocking mode. Since reading stdin when it is empty - results in an :exc:`IOError`, this error is caught and ignored. + results in an :exc:`OSError`, this error is caught and ignored. + + .. versionchanged:: 3.3 + *sys.stdin.read* used to raise :exc:`IOError`. Starting from Python 3.3 + :exc:`IOError` is alias for :exc:`OSError`. Threads diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index cdd4b66..6ea9a3f 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -741,9 +741,7 @@ the basis for code meeting your own specific requirements:: break logger = logging.getLogger(record.name) logger.handle(record) # No level or filter logic applied - just do it! - except (KeyboardInterrupt, SystemExit): - raise - except: + except Exception: import sys, traceback print('Whoops! Problem:', file=sys.stderr) traceback.print_exc(file=sys.stderr) diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 97e692f..158b3be 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -342,6 +342,10 @@ and off individually. They are described here in more detail. Handles the move of :func:`reduce` to :func:`functools.reduce`. +.. 2to3fixer:: reload + + Converts :func:`reload` to :func:`imp.reload`. + .. 2to3fixer:: renames Changes :data:`sys.maxint` to :data:`sys.maxsize`. diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 6f23596..27abb60 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -12,9 +12,9 @@ -------------- This module provides the infrastructure for defining :term:`abstract base -classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this -was added to Python. (See also :pep:`3141` and the :mod:`numbers` module -regarding a type hierarchy for numbers based on ABCs.) +classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; +see the PEP for why this was added to Python. (See also :pep:`3141` and the +:mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.) The :mod:`collections` module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition the @@ -23,7 +23,7 @@ a class or instance provides a particular interface, for example, is it hashable or a mapping. -This module provides the following class: +This module provides the following classes: .. class:: ABCMeta @@ -127,6 +127,19 @@ This module provides the following class: available as a method of ``Foo``, so it is provided separately. +.. class:: ABC + + A helper class that has :class:`ABCMeta` as its metaclass. With this class, + an abstract base class can be created by simply deriving from :class:`ABC`, + avoiding sometimes confusing metaclass usage. + + Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore + inheriting from :class:`ABC` requires the usual precautions regarding metaclass + usage, as multiple inheritance may lead to metaclass conflicts. + + .. versionadded:: 3.4 + + The :mod:`abc` module also provides the following decorators: .. decorator:: abstractmethod diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst index 999bad8..f8a6ab7 100644 --- a/Doc/library/aifc.rst +++ b/Doc/library/aifc.rst @@ -51,6 +51,10 @@ Module :mod:`aifc` defines the following function: used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use :meth:`writeframesraw` and :meth:`setnframes`. + Objects returned by :func:`.open` also supports the :keyword:`with` statement. + +.. versionchanged:: 3.4 + Support for the :keyword:`with` statement was added. Objects returned by :func:`.open` when a file is opened for reading have the following methods: diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 7267ae4..f3eb9dd 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -977,9 +977,9 @@ See the section on the default_ keyword argument for information on when the ``type`` argument is applied to default arguments. To ease the use of various types of files, the argparse module provides the -factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the -:func:`open` function. For example, ``FileType('w')`` can be used to create a -writable file:: +factory FileType which takes the ``mode=``, ``bufsize=``, ``encoding=`` and +``errors=`` arguments of the :func:`open` function. For example, +``FileType('w')`` can be used to create a writable file:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('bar', type=argparse.FileType('w')) @@ -1619,17 +1619,19 @@ Sub-commands FileType objects ^^^^^^^^^^^^^^^^ -.. class:: FileType(mode='r', bufsize=None) +.. class:: FileType(mode='r', bufsize=-1, encoding=None, errors=None) The :class:`FileType` factory creates objects that can be passed to the type argument of :meth:`ArgumentParser.add_argument`. Arguments that have - :class:`FileType` objects as their type will open command-line arguments as files - with the requested modes and buffer sizes:: + :class:`FileType` objects as their type will open command-line arguments as + files with the requested modes, buffer sizes, encodings and error handling + (see the :func:`open` function for more details):: >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--output', type=argparse.FileType('wb', 0)) - >>> parser.parse_args(['--output', 'out']) - Namespace(output=<_io.BufferedWriter name='out'>) + >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0)) + >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8')) + >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt']) + Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>) FileType objects understand the pseudo-argument ``'-'`` and automatically convert this into ``sys.stdin`` for readable :class:`FileType` objects and diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index a65fe5b..96c5aef 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -76,14 +76,19 @@ The class can be used to simulate nested scopes and is useful in templating. be modified to change which mappings are searched. The list should always contain at least one mapping. - .. method:: new_child() + .. method:: new_child(m=None) - Returns a new :class:`ChainMap` containing a new :class:`dict` followed by - all of the maps in the current instance. A call to ``d.new_child()`` is - equivalent to: ``ChainMap({}, *d.maps)``. This method is used for + Returns a new :class:`ChainMap` containing a new map followed by + all of the maps in the current instance. If ``m`` is specified, + it becomes the new map at the front of the list of mappings; if not + specified, an empty dict is used, so that a call to ``d.new_child()`` + is equivalent to: ``ChainMap({}, *d.maps)``. This method is used for creating subcontexts that can be updated without altering values in any of the parent mappings. + .. versionchanged:: 3.4 + The optional ``m`` parameter was added. + .. attribute:: parents Property returning a new :class:`ChainMap` containing all of the maps in diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index fee5067..86c3ab0 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -94,6 +94,26 @@ Functions and classes provided: without needing to explicitly close ``page``. Even if an error occurs, ``page.close()`` will be called when the :keyword:`with` block is exited. +.. function:: ignored(*exceptions) + + Return a context manager that ignores the specified exceptions if they + occur in the body of a with-statement. + + For example:: + + from contextlib import ignored + + with ignored(OSError): + os.remove('somefile.tmp') + + This code is equivalent to:: + + try: + os.remove('somefile.tmp') + except OSError: + pass + + .. versionadded:: 3.4 .. class:: ContextDecorator() diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 222c719..200de45 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -633,6 +633,16 @@ The second group of options controls how test failures are reported: the output is suppressed. +.. data:: FAIL_FAST + + When specified, exit after the first failing example and don't attempt to run + the remaining examples. Thus, the number of failures reported will be at most + 1. This flag may be useful during debugging, since examples after the first + failure won't even produce debugging output. + + .. versionadded:: 3.4 + + .. data:: REPORTING_FLAGS A bitmask or'ing together all the reporting flags above. diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 9595221..ece035d 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -260,6 +260,12 @@ The following exceptions are the exceptions that are usually raised. :exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and :exc:`mmap.error` have been merged into :exc:`OSError`. + .. versionchanged:: 3.4 + + The :attr:`filename` attribute is now the original file name passed to + the function, instead of the name encoded to or decoded from the + filesystem encoding. + .. exception:: OverflowError diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst index 8a88f8c..95c4ddf 100644 --- a/Doc/library/filecmp.rst +++ b/Doc/library/filecmp.rst @@ -55,28 +55,25 @@ The :class:`dircmp` class .. class:: dircmp(a, b, ignore=None, hide=None) - Construct a new directory comparison object, to compare the directories *a* and - *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS', - 'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir, - os.pardir]``. + Construct a new directory comparison object, to compare the directories *a* + and *b*. *ignore* is a list of names to ignore, and defaults to + :attr:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and + defaults to ``[os.curdir, os.pardir]``. The :class:`dircmp` class compares files by doing *shallow* comparisons as described for :func:`filecmp.cmp`. The :class:`dircmp` class provides the following methods: - .. method:: report() Print (to :data:`sys.stdout`) a comparison between *a* and *b*. - .. method:: report_partial_closure() Print a comparison between *a* and *b* and common immediate subdirectories. - .. method:: report_full_closure() Print a comparison between *a* and *b* and common subdirectories @@ -133,7 +130,7 @@ The :class:`dircmp` class .. attribute:: common_files - Files in both *a* and *b* + Files in both *a* and *b*. .. attribute:: common_funny @@ -164,6 +161,12 @@ The :class:`dircmp` class A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects. +.. attribute:: DEFAULT_IGNORES + + .. versionadded:: 3.4 + + List of directories ignored by :class:`dircmp` by default. + Here is a simplified example of using the ``subdirs`` attribute to search recursively through two directories to show common different files:: diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index c82e03f..0304431 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -543,6 +543,10 @@ are always available. They are listed here in alphabetical order. :exc:`TypeError` exception is raised if the method is not found or if either the *format_spec* or the return value are not strings. + .. versionadded:: 3.4 + ``object().__format__(format_spec)`` raises :exc:`TypeError` + if *format_spec* is not empty string. + .. _func-frozenset: .. function:: frozenset([iterable]) @@ -661,6 +665,12 @@ are always available. They are listed here in alphabetical order. The integer type is described in :ref:`typesnumeric`. + .. versionchanged:: 3.4 + If *base* is not an instance of :class:`int` and the *base* object has a + :meth:`base.__index__ <object.__index__>` method, that method is called + to obtain an integer for the base. Previous versions used + :meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__ + <object.__index__>`. .. function:: isinstance(object, classinfo) diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst index 41bda1e..95df2f8 100644 --- a/Doc/library/gc.rst +++ b/Doc/library/gc.rst @@ -67,6 +67,24 @@ The :mod:`gc` module provides the following functions: returned. +.. function:: get_stats() + + Return a list of 3 per-generation dictionaries containing collection + statistics since interpreter start. At this moment, each dictionary will + contain the following items: + + * ``collections`` is the number of times this generation was collected; + + * ``collected`` is the total number of objects collected inside this + generation; + + * ``uncollectable`` is the total number of objects which were found + to be uncollectable (and were therefore moved to the :data:`garbage` + list) inside this generation. + + .. versionadded:: 3.4 + + .. function:: set_threshold(threshold0[, threshold1[, threshold2]]) Set the garbage collection thresholds (the collection frequency). Setting diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 929d41b..f0fe915 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -51,9 +51,13 @@ concatenation of the data fed to it so far using the :meth:`digest` or .. index:: single: OpenSSL; (use in module hashlib) Constructors for hash algorithms that are always present in this module are -:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and -:func:`sha512`. Additional algorithms may also be available depending upon the -OpenSSL library that Python uses on your platform. +:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, +:func:`sha512`, :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, and +:func:`sha3_512`. Additional algorithms may also be available depending upon +the OpenSSL library that Python uses on your platform. + + .. versionchanged:: 3.4 + Add sha3 family of hash algorithms. For example, to obtain the digest of the byte string ``b'Nobody inspects the spammish repetition'``:: diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 8137573..0fad566 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -27,7 +27,7 @@ HTTPS protocols. It is normally not used directly --- the module The module provides the following classes: -.. class:: HTTPConnection(host, port=None[, strict][, timeout], \ +.. class:: HTTPConnection(host, port=None[, timeout], \ source_address=None) An :class:`HTTPConnection` instance represents one transaction with an HTTP @@ -51,13 +51,13 @@ The module provides the following classes: .. versionchanged:: 3.2 *source_address* was added. - .. deprecated-removed:: 3.2 3.4 - The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" - are not supported anymore. + .. versionchanged:: 3.4 + The *strict* parameter is removed. HTTP 0.9-style "Simple Responses" are + not supported. .. class:: HTTPSConnection(host, port=None, key_file=None, \ - cert_file=None[, strict][, timeout], \ + cert_file=None[, timeout], \ source_address=None, *, context=None, \ check_hostname=None) @@ -89,19 +89,19 @@ The module provides the following classes: This class now supports HTTPS virtual hosts if possible (that is, if :data:`ssl.HAS_SNI` is true). - .. deprecated-removed:: 3.2 3.4 - The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" - are not supported anymore. + .. versionchanged:: 3.4 + The *strict* parameter is removed. HTTP 0.9-style "Simple Responses" are + not supported anymore. -.. class:: HTTPResponse(sock, debuglevel=0[, strict], method=None, url=None) +.. class:: HTTPResponse(sock, debuglevel=0, method=None, url=None) Class whose instances are returned upon successful connection. Not instantiated directly by user. - .. deprecated-removed:: 3.2 3.4 - The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" - are not supported anymore. + .. versionchanged:: 3.4 + The *strict* parameter is removed. HTTP 0.9 style "Simple Responses" are + not supported anymore. The following exceptions are raised as appropriate: diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index cbad3ed..53139a2 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -170,12 +170,19 @@ of which this module provides three different variants: .. versionadded:: 3.2 - .. method:: send_error(code, message=None) + .. method:: send_error(code, message=None, explain=None) Sends and logs a complete error reply to the client. The numeric *code* - specifies the HTTP error code, with *message* as optional, more specific text. A - complete set of headers is sent, followed by text composed using the - :attr:`error_message_format` class variable. + specifies the HTTP error code, with *message* as optional, more specific + text, usually referring to short message response. The *explain* + argument can be used to send a detailed information about the error in + response content body. A complete set of headers is sent, followed by + text composed using the :attr:`error_message_format` class variable. + + .. versionchanged:: 3.4 + The error response includes a Content-Length header. + Added the *explain* argument. + .. method:: send_response(code, message=None) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index b40e470..c248956 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -16,70 +16,82 @@ IDLE has the following features: * coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit -* cross-platform: works on Windows and Unix +* cross-platform: works on Windows, Unix, and Mac OS X -* multi-window text editor with multiple undo, Python colorizing and many other - features, e.g. smart indent and call tips +* multi-window text editor with multiple undo, Python colorizing, + smart indent, call tips, and many other features * Python shell window (a.k.a. interactive interpreter) -* debugger (not complete, but you can set breakpoints, view and step) +* debugger (not complete, but you can set breakpoints, view and step) Menus ----- +IDLE has two window types, the Shell window and the Editor window. It is +possible to have multiple editor windows simultaneously. IDLE's +menus dynamically change based on which window is currently selected. Each menu +documented below indicates which window type it is associated with. Click on +the dotted line at the top of a menu to "tear it off": a separate window +containing the menu is created (for Unix and Windows only). -File menu -^^^^^^^^^ +File menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ New window - create a new editing window + Create a new editing window Open... - open an existing file + Open an existing file Open module... - open an existing module (searches sys.path) + Open an existing module (searches sys.path) + +Recent Files + Open a list of recent files Class browser - show classes and methods in current file + Show classes and methods in current file Path browser - show sys.path directories, modules, classes and methods + Show sys.path directories, modules, classes and methods .. index:: single: Class browser single: Path browser Save - save current window to the associated file (unsaved windows have a \* before and - after the window title) + Save current window to the associated file (unsaved windows have a + \* before and after the window title) Save As... - save current window to new file, which becomes the associated file + Save current window to new file, which becomes the associated file Save Copy As... - save current window to different file without changing the associated file + Save current window to different file without changing the associated file + +Print Window + Print the current window Close - close current window (asks to save if unsaved) + Close current window (asks to save if unsaved) Exit - close all windows and quit IDLE (asks to save if unsaved) + Close all windows and quit IDLE (asks to save if unsaved) -Edit menu -^^^^^^^^^ +Edit menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Undo - Undo last change to current window (max 1000 changes) + Undo last change to current window (a maximum of 1000 changes may be undone) Redo Redo last undone change to current window Cut - Copy selection into system-wide clipboard; then delete selection + Copy selection into system-wide clipboard; then delete the selection Copy Copy selection into system-wide clipboard @@ -108,11 +120,30 @@ Replace... Go to line Ask for a line number and show that line +Expand word + Expand the word you have typed to match another word in the same buffer; + repeat to get a different expansion + +Show call tip + After an unclosed parenthesis for a function, open a small window with + function parameter hints + +Show surrounding parens + Highlight the surrounding parenthesis + +Show Completions + Open a scroll window allowing selection keywords and attributes. See + Completions below. + + +Format menu (Editor window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Indent region - Shift selected lines right 4 spaces + Shift selected lines right by the indent width (default 4 spaces) Dedent region - Shift selected lines left 4 spaces + Shift selected lines left by the indent width (default 4 spaces) Comment out region Insert ## in front of selected lines @@ -121,67 +152,121 @@ Uncomment region Remove leading # or ## from selected lines Tabify region - Turns *leading* stretches of spaces into tabs + Turns *leading* stretches of spaces into tabs. (Note: We recommend using + 4 space blocks to indent Python code.) Untabify region - Turn *all* tabs into the right number of spaces + Turn *all* tabs into the correct number of spaces -Expand word - Expand the word you have typed to match another word in the same buffer; repeat - to get a different expansion +Toggle tabs + Open a dialog to switch between indenting with spaces and tabs. -Format Paragraph - Reformat the current blank-line-separated paragraph +New Indent Width + Open a dialog to change indent width. The accepted default by the Python + community is 4 spaces. -Import module - Import or reload the current module +Format Paragraph + Reformat the current blank-line-separated paragraph. All lines in the + paragraph will be formatted to less than 80 columns. -Run script - Execute the current file in the __main__ namespace +Strip trailing whitespace + Removes any space characters after the end of the last non-space character .. index:: single: Import module single: Run script -Windows menu -^^^^^^^^^^^^ +Run menu (Editor window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Zoom Height - toggles the window between normal size (24x80) and maximum height. +Python Shell + Open or wake up the Python Shell window -The rest of this menu lists the names of all open windows; select one to bring -it to the foreground (deiconifying it if necessary). +Check module + Check the syntax of the module currently open in the Editor window. If the + module has not been saved IDLE will prompt the user to save the code. + +Run module + Restart the shell to clean the environment, then execute the currently + open module. If the module has not been saved IDLE will prompt the user + to save the code. +Shell menu (Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Debug menu -^^^^^^^^^^ +View Last Restart + Scroll the shell window to the last Shell restart -* in the Python Shell window only +Restart Shell + Restart the shell to clean the environment + +Debug menu (Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Go to file/line Look around the insert point for a filename and line number, open the file, and show the line. Useful to view the source lines referenced in an - exception traceback. + exception traceback. Available in the context menu of the Shell window. -Debugger - Run commands in the shell under the debugger. +Debugger (toggle) + This feature is not complete and considered experimental. Run commands in + the shell under the debugger Stack viewer - Show the stack traceback of the last exception. + Show the stack traceback of the last exception Auto-open Stack Viewer - Open stack viewer on traceback. + Toggle automatically opening the stack viewer on unhandled exception .. index:: single: stack viewer single: debugger +Options menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configure IDLE + Open a configuration dialog. Fonts, indentation, keybindings, and color + themes may be altered. Startup Preferences may be set, and additional + help sources can be specified. + +Code Context (toggle)(Editor Window only) + Open a pane at the top of the edit window which shows the block context + of the section of code which is scrolling off the top of the window. + +Windows menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Zoom Height + Toggles the window between normal size (40x80 initial setting) and maximum + height. The initial size is in the Configure IDLE dialog under the general + tab. + +The rest of this menu lists the names of all open windows; select one to bring +it to the foreground (deiconifying it if necessary). + +Help menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +About IDLE + Version, copyright, license, credits + +IDLE Help + Display a help file for IDLE detailing the menu options, basic editing and + navigation, and other tips. + +Python Docs + Access local Python documentation, if installed. Or will start a web browser + and open docs.python.org showing the latest Python documentation. -Edit context menu -^^^^^^^^^^^^^^^^^ +Additional help sources may be added here with the Configure IDLE dialog under +the General tab. -* Right-click in Edit window (Control-click on OS X) +Editor Window context menu +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Right-click in Editor window (Control-click on OS X) Cut Copy selection into system-wide clipboard; then delete selection @@ -207,8 +292,8 @@ Clear Breakpoint single: breakpoints -Shell context menu -^^^^^^^^^^^^^^^^^^ +Shell Window context menu +^^^^^^^^^^^^^^^^^^^^^^^^^ * Right-click in Python Shell window (Control-click on OS X) @@ -225,19 +310,44 @@ Go to file/line Same as in Debug menu. -Basic editing and navigation ----------------------------- +Editing and navigation +---------------------- * :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right +* :kbd:`C-Backspace` delete word left; :kbd:`C-Del` delete word to the right + * Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around +* :kbd:`C-LeftArrow` and :kbd:`C-RightArrow` moves by words + * :kbd:`Home`/:kbd:`End` go to begin/end of line * :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file -* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, - :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` +* Some useful Emacs bindings are inherited from Tcl/Tk: + + * :kbd:`C-a` beginning of line + + * :kbd:`C-e` end of line + + * :kbd:`C-k` kill line (but doesn't put it in clipboard) + + * :kbd:`C-l` center window around the insertion point + + * :kbd:`C-b` go backwards one character without deleting (usually you can + also use the cursor key for this) + + * :kbd:`C-f` go forward one character without deleting (usually you can + also use the cursor key for this) + + * :kbd:`C-p` go up one line (usually you can also use the cursor key for + this) + + * :kbd:`C-d` delete next character + +Standard keybindings (like :kbd:`C-c` to copy and :kbd:`C-v` to paste) +may work. Keybindings are selected in the Configure IDLE dialog. Automatic indentation @@ -246,27 +356,76 @@ Automatic indentation After a block-opening statement, the next line is indented by 4 spaces (in the Python Shell window by one tab). After certain keywords (break, return etc.) the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up -to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python -Shell window one tab). See also the indent/dedent region commands in the edit -menu. - +to 4 spaces if they are there. :kbd:`Tab` inserts spaces (in the Python +Shell window one tab), number depends on Indent width. Currently tabs +are restricted to four spaces due to Tcl/Tk limitations. + +See also the indent/dedent region commands in the edit menu. + +Completions +^^^^^^^^^^^ + +Completions are supplied for functions, classes, and attributes of classes, +both built-in and user-defined. Completions are also provided for +filenames. + +The AutoCompleteWindow (ACW) will open after a predefined delay (default is +two seconds) after a '.' or (in a string) an os.sep is typed. If after one +of those characters (plus zero or more other characters) a tab is typed +the ACW will open immediately if a possible continuation is found. + +If there is only one possible completion for the characters entered, a +:kbd:`Tab` will supply that completion without opening the ACW. + +'Show Completions' will force open a completions window, by default the +:kbd:`C-space` will open a completions window. In an empty +string, this will contain the files in the current directory. On a +blank line, it will contain the built-in and user-defined functions and +classes in the current name spaces, plus any modules imported. If some +characters have been entered, the ACW will attempt to be more specific. + +If a string of characters is typed, the ACW selection will jump to the +entry most closely matching those characters. Entering a :kbd:`tab` will +cause the longest non-ambiguous match to be entered in the Editor window or +Shell. Two :kbd:`tab` in a row will supply the current ACW selection, as +will return or a double click. Cursor keys, Page Up/Down, mouse selection, +and the scroll wheel all operate on the ACW. + +"Hidden" attributes can be accessed by typing the beginning of hidden +name after a '.', e.g. '_'. This allows access to modules with +``__all__`` set, or to class-private attributes. + +Completions and the 'Expand Word' facility can save a lot of typing! + +Completions are currently limited to those in the namespaces. Names in +an Editor window which are not via ``__main__`` and :data:`sys.modules` will +not be found. Run the module once with your imports to correct this situation. +Note that IDLE itself places quite a few modules in sys.modules, so +much can be found by default, e.g. the re module. + +If you don't like the ACW popping up unbidden, simply make the delay +longer or disable the extension. Or another option is the delay could +be set to zero. Another alternative to preventing ACW popups is to +disable the call tips extension. Python Shell window ^^^^^^^^^^^^^^^^^^^ -* :kbd:`C-C` interrupts executing command +* :kbd:`C-c` interrupts executing command -* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt +* :kbd:`C-d` sends end-of-file; closes window if typed at a ``>>>`` prompt + (this is :kbd:`C-z` on Windows). -* :kbd:`Alt-p` retrieves previous command matching what you have typed +* :kbd:`Alt-/` (Expand word) is also useful to reduce typing -* :kbd:`Alt-n` retrieves next + Command history -* :kbd:`Return` while on any previous command retrieves that command + * :kbd:`Alt-p` retrieves previous command matching what you have typed. On + OS X use :kbd:`C-p`. -* :kbd:`Alt-/` (Expand word) is also useful here + * :kbd:`Alt-n` retrieves next. On OS X use :kbd:`C-n`. -.. index:: single: indentation + * :kbd:`Return` while on any previous command retrieves that command Syntax colors @@ -308,17 +467,17 @@ Startup Upon startup with the ``-s`` option, IDLE will execute the file referenced by the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`. -Idle first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file -referenced is run. If ``IDLESTARTUP`` is not present, Idle checks for +IDLE first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file +referenced is run. If ``IDLESTARTUP`` is not present, IDLE checks for ``PYTHONSTARTUP``. Files referenced by these environment variables are -convenient places to store functions that are used frequently from the Idle +convenient places to store functions that are used frequently from the IDLE shell, or for executing import statements to import common modules. In addition, ``Tk`` also loads a startup file if it is present. Note that the Tk file is loaded unconditionally. This additional file is ``.Idle.py`` and is looked for in the user's home directory. Statements in this file will be executed in the Tk namespace, so this file is not useful for importing functions -to be used from Idle's Python shell. +to be used from IDLE's Python shell. Command line usage @@ -349,3 +508,45 @@ If there are arguments: the arguments are still available in ``sys.argv``. +Additional help sources +----------------------- + +IDLE includes a help menu entry called "Python Docs" that will open the +extensive sources of help, including tutorials, available at docs.python.org. +Selected URLs can be added or removed from the help menu at any time using the +Configure IDLE dialog. See the IDLE help option in the help menu of IDLE for +more information. + + +Other preferences +----------------- + +The font preferences, highlighting, keys, and general preferences can be +changed via the Configure IDLE menu option. Be sure to note that +keys can be user defined, IDLE ships with four built in key sets. In +addition a user can create a custom key set in the Configure IDLE dialog +under the keys tab. + +Extensions +---------- + +IDLE contains an extension facility. See the beginning of +config-extensions.def in the idlelib directory for further information. The +default extensions are currently: + +* FormatParagraph + +* AutoExpand + +* ZoomHeight + +* ScriptBinding + +* CallTips + +* ParenMatch + +* AutoComplete + +* CodeContext + diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst index 7d4bf4f..e090e00 100644 --- a/Doc/library/imp.rst +++ b/Doc/library/imp.rst @@ -1,6 +1,9 @@ :mod:`imp` --- Access the :ref:`import <importsystem>` internals ================================================================ +.. deprecated:: 3.4 + The :mod:`imp` package has been deprecated in favor of :mod:`importlib`. + .. module:: imp :synopsis: Access the implementation of the import statement. @@ -11,10 +14,6 @@ This module provides an interface to the mechanisms used to implement the :keyword:`import` statement. It defines the following constants and functions: -.. note:: - New programs should use :mod:`importlib` rather than this module. - - .. function:: get_magic() .. index:: pair: file; byte-code diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 9120671..e78a2ed 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -90,7 +90,7 @@ Functions Find the loader for a module, optionally within the specified *path*. If the module is in :attr:`sys.modules`, then ``sys.modules[name].__loader__`` is - returned (unless the loader would be ``None``, in which case + returned (unless the loader would be ``None`` or is not set, in which case :exc:`ValueError` is raised). Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is returned if no loader is found. @@ -99,6 +99,12 @@ Functions will need to import all parent packages of the submodule and use the correct argument to *path*. + .. versionadded:: 3.3 + + .. versionchanged:: 3.4 + If ``__loader__`` is not set, raise :exc:`ValueError`, just like when the + attribute is set to ``None``. + .. function:: invalidate_caches() Invalidate the internal caches of finders stored at @@ -132,8 +138,6 @@ ABC hierarchy:: +-- ExecutionLoader --+ +-- FileLoader +-- SourceLoader - +-- PyLoader (deprecated) - +-- PyPycLoader (deprecated) .. class:: Finder @@ -149,6 +153,10 @@ ABC hierarchy:: module. Originally specified in :pep:`302`, this method was meant for use in :data:`sys.meta_path` and in the path-based import subsystem. + .. versionchanged:: 3.4 + Returns ``None`` when called instead of raising + :exc:`NotImplementedError`. + .. class:: MetaPathFinder @@ -165,12 +173,19 @@ ABC hierarchy:: will be the value of :attr:`__path__` from the parent package. If a loader cannot be found, ``None`` is returned. + .. versionchanged:: 3.4 + Returns ``None`` when called instead of raising + :exc:`NotImplementedError`. + .. method:: invalidate_caches() An optional method which, when called, should invalidate any internal cache used by the finder. Used by :func:`importlib.invalidate_caches` when invalidating the caches of all finders on :data:`sys.meta_path`. + .. versionchanged:: 3.4 + Returns ``None`` when called instead of ``NotImplemented``. + .. class:: PathEntryFinder @@ -178,7 +193,7 @@ ABC hierarchy:: it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder`` is meant for use only within the path-based import subsystem provided by :class:`PathFinder`. This ABC is a subclass of :class:`Finder` for - compatibility. + compatibility reasons only. .. versionadded:: 3.3 @@ -190,9 +205,12 @@ ABC hierarchy:: package. The loader may be ``None`` while specifying ``portion`` to signify the contribution of the file system locations to a namespace package. An empty list can be used for ``portion`` to signify the loader - is not part of a package. If ``loader`` is ``None`` and ``portion`` is - the empty list then no loader or location for a namespace package were - found (i.e. failure to find anything for the module). + is not part of a namespace package. If ``loader`` is ``None`` and + ``portion`` is the empty list then no loader or location for a namespace + package were found (i.e. failure to find anything for the module). + + .. versionchanged:: 3.4 + Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`. .. method:: find_module(fullname): @@ -245,20 +263,28 @@ ABC hierarchy:: - :attr:`__package__` The parent package for the module/package. If the module is top-level then it has a value of the empty string. The - :func:`importlib.util.set_package` decorator can handle the details - for :attr:`__package__`. + :func:`importlib.util.module_for_loader` decorator can handle the + details for :attr:`__package__`. - :attr:`__loader__` - The loader used to load the module. - (This is not set by the built-in import machinery, - but it should be set whenever a :term:`loader` is used.) + The loader used to load the module. The + :func:`importlib.util.module_for_loader` decorator can handle the + details for :attr:`__package__`. + + .. versionchanged:: 3.4 + Raise :exc:`ImportError` when called instead of + :exc:`NotImplementedError`. .. method:: module_repr(module) - An abstract method which when implemented calculates and returns the - given module's repr, as a string. + An optional method which when implemented calculates and returns the + given module's repr, as a string. The module type's default repr() will + use the result of this method as appropriate. - .. versionadded: 3.3 + .. versionadded:: 3.3 + + .. versionchanged:: 3.4 + Made optional instead of an abstractmethod. .. class:: ResourceLoader @@ -277,6 +303,9 @@ ABC hierarchy:: be found. The *path* is expected to be constructed using a module's :attr:`__file__` attribute or an item from a package's :attr:`__path__`. + .. versionchanged:: 3.4 + Raises :exc:`IOError` instead of :exc:`NotImplementedError`. + .. class:: InspectLoader @@ -293,6 +322,9 @@ ABC hierarchy:: .. index:: single: universal newlines; importlib.abc.InspectLoader.get_source method + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + .. method:: get_source(fullname) An abstract method to return the source of a module. It is returned as @@ -301,12 +333,18 @@ ABC hierarchy:: if no source is available (e.g. a built-in module). Raises :exc:`ImportError` if the loader cannot find the module specified. + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + .. method:: is_package(fullname) An abstract method to return a true value if the module is a package, a false value otherwise. :exc:`ImportError` is raised if the :term:`loader` cannot find the module. + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + .. class:: ExecutionLoader @@ -324,6 +362,9 @@ ABC hierarchy:: the source file, regardless of whether a bytecode was used to load the module. + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + .. class:: FileLoader(fullname, path) @@ -366,10 +407,12 @@ ABC hierarchy:: * :meth:`ResourceLoader.get_data` * :meth:`ExecutionLoader.get_filename` Should only return the path to the source file; sourceless - loading is not supported. + loading is not supported (see :class:`SourcelessLoader` if that + functionality is required) The abstract methods defined by this class are to add optional bytecode - file support. Not implementing these optional methods causes the loader to + file support. Not implementing these optional methods (or causing them to + raise :exc:`NotImplementedError`) causes the loader to only work with source code. Implementing the methods allows the loader to work with source *and* bytecode files; it does not allow for *sourceless* loading where only bytecode is provided. Bytecode files are an @@ -386,10 +429,13 @@ ABC hierarchy:: - ``'size'`` (optional): the size in bytes of the source code. Any other keys in the dictionary are ignored, to allow for future - extensions. + extensions. If the path cannot be handled, :exc:`IOError` is raised. .. versionadded:: 3.3 + .. versionchanged:: 3.4 + Raise :exc:`IOError` instead of :exc:`NotImplementedError`. + .. method:: path_mtime(path) Optional abstract method which returns the modification time for the @@ -398,7 +444,10 @@ ABC hierarchy:: .. deprecated:: 3.3 This method is deprecated in favour of :meth:`path_stats`. You don't have to implement it, but it is still available for compatibility - purposes. + purposes. Raise :exc:`IOError` if the path cannot be handled. + + .. versionchanged:: 3.4 + Raise :exc:`IOError` instead of :exc:`NotImplementedError`. .. method:: set_data(path, data) @@ -409,6 +458,20 @@ ABC hierarchy:: When writing to the path fails because the path is read-only (:attr:`errno.EACCES`), do not propagate the exception. + .. versionchanged:: 3.4 + No longer raises :exc:`NotImplementedError` when called. + + .. method:: source_to_code(data, path) + + Create a code object from Python source. + + The *data* argument can be whatever the :func:`compile` function + supports (i.e. string or bytes). The *path* argument should be + the "path" to where the source code originated from, which can be an + abstract concept (e.g. location in a zip file). + + .. versionadded:: 3.4 + .. method:: get_code(fullname) Concrete implementation of :meth:`InspectLoader.get_code`. @@ -430,142 +493,6 @@ ABC hierarchy:: itself does not end in ``__init__``. -.. class:: PyLoader - - An abstract base class inheriting from - :class:`ExecutionLoader` and - :class:`ResourceLoader` designed to ease the loading of - Python source modules (bytecode is not handled; see - :class:`SourceLoader` for a source/bytecode ABC). A subclass - implementing this ABC will only need to worry about exposing how the source - code is stored; all other details for loading Python source code will be - handled by the concrete implementations of key methods. - - .. deprecated:: 3.2 - This class has been deprecated in favor of :class:`SourceLoader` and is - slated for removal in Python 3.4. See below for how to create a - subclass that is compatible with Python 3.1 onwards. - - If compatibility with Python 3.1 is required, then use the following idiom - to implement a subclass that will work with Python 3.1 onwards (make sure - to implement :meth:`ExecutionLoader.get_filename`):: - - try: - from importlib.abc import SourceLoader - except ImportError: - from importlib.abc import PyLoader as SourceLoader - - - class CustomLoader(SourceLoader): - def get_filename(self, fullname): - """Return the path to the source file.""" - # Implement ... - - def source_path(self, fullname): - """Implement source_path in terms of get_filename.""" - try: - return self.get_filename(fullname) - except ImportError: - return None - - def is_package(self, fullname): - """Implement is_package by looking for an __init__ file - name as returned by get_filename.""" - filename = os.path.basename(self.get_filename(fullname)) - return os.path.splitext(filename)[0] == '__init__' - - - .. method:: source_path(fullname) - - An abstract method that returns the path to the source code for a - module. Should return ``None`` if there is no source code. - Raises :exc:`ImportError` if the loader knows it cannot handle the - module. - - .. method:: get_filename(fullname) - - A concrete implementation of - :meth:`importlib.abc.ExecutionLoader.get_filename` that - relies on :meth:`source_path`. If :meth:`source_path` returns - ``None``, then :exc:`ImportError` is raised. - - .. method:: load_module(fullname) - - A concrete implementation of :meth:`importlib.abc.Loader.load_module` - that loads Python source code. All needed information comes from the - abstract methods required by this ABC. The only pertinent assumption - made by this method is that when loading a package - :attr:`__path__` is set to ``[os.path.dirname(__file__)]``. - - .. method:: get_code(fullname) - - A concrete implementation of - :meth:`importlib.abc.InspectLoader.get_code` that creates code objects - from Python source code, by requesting the source code (using - :meth:`source_path` and :meth:`get_data`) and compiling it with the - built-in :func:`compile` function. - - .. method:: get_source(fullname) - - A concrete implementation of - :meth:`importlib.abc.InspectLoader.get_source`. Uses - :meth:`importlib.abc.ResourceLoader.get_data` and :meth:`source_path` - to get the source code. It tries to guess the source encoding using - :func:`tokenize.detect_encoding`. - - -.. class:: PyPycLoader - - An abstract base class inheriting from :class:`PyLoader`. - This ABC is meant to help in creating loaders that support both Python - source and bytecode. - - .. deprecated:: 3.2 - This class has been deprecated in favor of :class:`SourceLoader` and to - properly support :pep:`3147`. If compatibility is required with - Python 3.1, implement both :class:`SourceLoader` and :class:`PyLoader`; - instructions on how to do so are included in the documentation for - :class:`PyLoader`. Do note that this solution will not support - sourceless/bytecode-only loading; only source *and* bytecode loading. - - .. versionchanged:: 3.3 - Updated to parse (but not use) the new source size field in bytecode - files when reading and to write out the field properly when writing. - - .. method:: source_mtime(fullname) - - An abstract method which returns the modification time for the source - code of the specified module. The modification time should be an - integer. If there is no source code, return ``None``. If the - module cannot be found then :exc:`ImportError` is raised. - - .. method:: bytecode_path(fullname) - - An abstract method which returns the path to the bytecode for the - specified module, if it exists. It returns ``None`` - if no bytecode exists (yet). - Raises :exc:`ImportError` if the loader knows it cannot handle the - module. - - .. method:: get_filename(fullname) - - A concrete implementation of - :meth:`ExecutionLoader.get_filename` that relies on - :meth:`PyLoader.source_path` and :meth:`bytecode_path`. - If :meth:`source_path` returns a path, then that value is returned. - Else if :meth:`bytecode_path` returns a path, that path will be - returned. If a path is not available from both methods, - :exc:`ImportError` is raised. - - .. method:: write_bytecode(fullname, bytecode) - - An abstract method which has the loader write *bytecode* for future - use. If the bytecode is written, return ``True``. Return - ``False`` if the bytecode could not be written. This method - should not be called if :data:`sys.dont_write_bytecode` is true. - The *bytecode* argument should be a bytes string or bytes array. - - :mod:`importlib.machinery` -- Importers and path hooks ------------------------------------------------------ @@ -899,6 +826,10 @@ an :term:`importer`. It is recommended that :func:`module_for_loader` be used over this decorator as it subsumes this functionality. + .. versionchanged:: 3.4 + Set ``__loader__`` if set to ``None`` as well if the attribute does not + exist. + .. decorator:: set_package diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 433f948..faa7ac9 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -42,8 +42,7 @@ Compact encoding:: Pretty printing:: >>> import json - >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, - ... indent=4, separators=(',', ': '))) + >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)) { "4": 5, "6": 7 @@ -158,15 +157,13 @@ Basic Usage .. versionchanged:: 3.2 Allow strings for *indent* in addition to integers. - .. note:: - - Since the default item separator is ``', '``, the output might include - trailing whitespace when *indent* is specified. You can use - ``separators=(',', ': ')`` to avoid this. + If specified, *separators* should be an ``(item_separator, key_separator)`` + tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and + ``(',', ': ')`` otherwise. To get the most compact JSON representation, + you should specify ``(',', ':')`` to eliminate whitespace. - If *separators* is an ``(item_separator, dict_separator)`` tuple, then it - will be used instead of the default ``(', ', ': ')`` separators. ``(',', - ':')`` is the most compact JSON representation. + .. versionchanged:: 3.4 + Use ``(',', ': ')`` as default if *indent* is not ``None``. *default(obj)* is a function that should return a serializable version of *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. @@ -408,15 +405,13 @@ Encoders and Decoders .. versionchanged:: 3.2 Allow strings for *indent* in addition to integers. - .. note:: - - Since the default item separator is ``', '``, the output might include - trailing whitespace when *indent* is specified. You can use - ``separators=(',', ': ')`` to avoid this. - If specified, *separators* should be an ``(item_separator, key_separator)`` - tuple. The default is ``(', ', ': ')``. To get the most compact JSON - representation, you should specify ``(',', ':')`` to eliminate whitespace. + tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and + ``(',', ': ')`` otherwise. To get the most compact JSON representation, + you should specify ``(',', ':')`` to eliminate whitespace. + + .. versionchanged:: 3.4 + Use ``(',', ': ')`` as default if *indent* is not ``None``. If specified, *default* is a function that gets called for objects that can't otherwise be serialized. It should return a JSON encodable version of the diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index 1391ed2..16d3294 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -76,11 +76,23 @@ in :mod:`logging` itself) and defining handlers which are declared either in .. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True) - Reads the logging configuration from a :mod:`configparser`\-format file - named *fname*. This function can be called several times from an - application, allowing an end user to select from various pre-canned - configurations (if the developer provides a mechanism to present the choices - and load the chosen configuration). + Reads the logging configuration from a :mod:`configparser`\-format file. + This function can be called several times from an application, allowing an + end user to select from various pre-canned configurations (if the developer + provides a mechanism to present the choices and load the chosen + configuration). + + :param fname: A filename, or a file-like object, or an instance derived + from :class:`~configparser.RawConfigParser`. If a + ``RawConfigParser``-derived instance is passed, it is used as + is. Otherwise, a :class:`~configparser.Configparser` is + instantiated, and the configuration read by it from the + object passed in ``fname``. If that has a :meth:`readline` + method, it is assumed to be a file-like object and read using + :meth:`~configparser.ConfigParser.read_file`; otherwise, + it is assumed to be a filename and passed to + :meth:`~configparser.ConfigParser.read`. + :param defaults: Defaults to be passed to the ConfigParser can be specified in this argument. @@ -94,8 +106,17 @@ in :mod:`logging` itself) and defining handlers which are declared either in their ancestors are explicitly named in the logging configuration. + .. versionchanged:: 3.4 + An instance of a subclass of :class:`~configparser.RawConfigParser` is + now accepted as a value for ``fname``. This facilitates: + + * Use of a configuration file where logging configuration is just part + of the overall application configuration. + * Use of a configuration read from a file, and then modified by the using + application (e.g. based on command-line parameters or other aspects + of the runtime environment) before being passed to ``fileConfig``. -.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT) +.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None) Starts up a socket server on the specified port, and listens for new configurations. If no port is specified, the module's default @@ -105,6 +126,17 @@ in :mod:`logging` itself) and defining handlers which are declared either in server, and which you can :meth:`join` when appropriate. To stop the server, call :func:`stopListening`. + The ``verify`` argument, if specified, should be a callable which should + verify whether bytes received across the socket are valid and should be + processed. This could be done by encrypting and/or signing what is sent + across the socket, such that the ``verify`` callable can perform + signature verification and/or decryption. The ``verify`` callable is called + with a single argument - the bytes received across the socket - and should + return the bytes to be processed, or None to indicate that the bytes should + be discarded. The returned bytes could be the same as the passed in bytes + (e.g. when only verification is done), or they could be completely different + (perhaps if decryption were performed). + To send a configuration to the socket, read in the configuration file and send it to the socket as a string of bytes preceded by a four-byte length string packed in binary using ``struct.pack('>L', n)``. @@ -121,7 +153,12 @@ in :mod:`logging` itself) and defining handlers which are declared either in :func:`listen` socket and sending a configuration which runs whatever code the attacker wants to have executed in the victim's process. This is especially easy to do if the default port is used, but not hard even if a - different port is used). + different port is used). To avoid the risk of this happening, use the + ``verify`` argument to :func:`listen` to prevent unrecognised + configurations from being applied. + + .. versionchanged:: 3.4. + The ``verify`` argument was added. .. function:: stopListening() diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst index 30f9e03..909a678 100644 --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -296,7 +296,7 @@ The :class:`TimedRotatingFileHandler` class, located in the timed intervals. -.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False) +.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None) Returns a new instance of the :class:`TimedRotatingFileHandler` class. The specified file is opened and used as the stream for logging. On rotating it also @@ -346,6 +346,12 @@ timed intervals. If *delay* is true, then file opening is deferred until the first call to :meth:`emit`. + If *atTime* is not ``None``, it must be a ``datetime.time`` instance which + specifies the time of day when rollover occurs, for the cases where rollover + is set to happen "at midnight" or "on a particular weekday". + + .. versionchanged:: 3.4 + *atTime* parameter was added. .. method:: doRollover() diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst index 3b9e3d2..124eb61 100644 --- a/Doc/library/marshal.rst +++ b/Doc/library/marshal.rst @@ -40,10 +40,11 @@ this module. The following types are supported: booleans, integers, floating point numbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets, frozensets, dictionaries, and code objects, where it should be understood that tuples, lists, sets, frozensets and dictionaries are only supported as long as -the values contained therein are themselves supported; and recursive lists, sets -and dictionaries should not be written (they will cause infinite loops). The +the values contained therein are themselves supported. singletons :const:`None`, :const:`Ellipsis` and :exc:`StopIteration` can also be marshalled and unmarshalled. +For format *version* lower than 3, recursive lists, sets and dictionaries cannot +be written (see below). There are functions that read/write files as well as functions operating on strings. @@ -103,7 +104,9 @@ In addition, the following constants are defined: Indicates the format that the module uses. Version 0 is the historical format, version 1 shares interned strings and version 2 uses a binary format - for floating point numbers. The current version is 2. + for floating point numbers. + Version 3 adds support for object instancing and recursion. + The current version is 3. .. rubric:: Footnotes diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst index 1d1aa40..73b51c0 100644 --- a/Doc/library/nntplib.rst +++ b/Doc/library/nntplib.rst @@ -1,4 +1,3 @@ - :mod:`nntplib` --- NNTP protocol client ======================================= @@ -71,7 +70,7 @@ The module itself defines the following classes: reader-specific commands, such as ``group``. If you get unexpected :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. :class:`NNTP` class supports the :keyword:`with` statement to - unconditionally consume :exc:`socket.error` exceptions and to close the NNTP + unconditionally consume :exc:`OSError` exceptions and to close the NNTP connection when done. Here is a sample on how using it: >>> from nntplib import NNTP diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst index 3860880..877a790 100644 --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -235,6 +235,14 @@ their character equivalents. .. XXX: find a better, readable, example +.. function:: length_hint(obj, default=0) + + Return an estimated length for the object *o*. First trying to return its + actual length, then an estimate using :meth:`object.__length_hint__`, and + finally returning the default value. + + .. versionadded:: 3.4 + The :mod:`operator` module also defines tools for generalized attribute and item lookups. These are useful for making fast field extractors as arguments for :func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index dd3ac85..0d2ad04 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -42,7 +42,6 @@ the :mod:`glob` module.) * :mod:`posixpath` for UNIX-style paths * :mod:`ntpath` for Windows paths * :mod:`macpath` for old-style MacOS paths - * :mod:`os2emxpath` for OS/2 EMX paths .. function:: abspath(path) @@ -248,15 +247,14 @@ the :mod:`glob` module.) On Unix, this is determined by the device number and i-node number and raises an exception if a :func:`os.stat` call on either pathname fails. - On Windows, two files are the same if they resolve to the same final path - name using the Windows API call GetFinalPathNameByHandle. This function - raises an exception if handles cannot be obtained to either file. - Availability: Unix, Windows. .. versionchanged:: 3.2 Added Windows support. + .. versionchanged:: 3.4 + Windows now uses the same implementation as all other platforms. + .. function:: sameopenfile(fp1, fp2) @@ -275,7 +273,10 @@ the :mod:`glob` module.) :func:`stat`. This function implements the underlying comparison used by :func:`samefile` and :func:`sameopenfile`. - Availability: Unix. + Availability: Unix, Windows. + + .. versionchanged:: 3.4 + Added Windows support. .. function:: split(path) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index e70c886..344218c 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -54,7 +54,7 @@ Notes on the availability of these functions: The name of the operating system dependent module imported. The following names have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, - ``'os2'``, ``'ce'``, ``'java'``. + ``'ce'``, ``'java'``. .. seealso:: :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives @@ -1137,6 +1137,7 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window O_DIRECTORY O_NOFOLLOW O_NOATIME + O_PATH These constants are GNU extensions and not present if they are not defined by the C library. diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst index b4080d6..e248d6b 100644 --- a/Doc/library/poplib.rst +++ b/Doc/library/poplib.rst @@ -13,8 +13,11 @@ -------------- This module defines a class, :class:`POP3`, which encapsulates a connection to a -POP3 server and implements the protocol as defined in :rfc:`1725`. The -:class:`POP3` class supports both the minimal and optional command sets. +POP3 server and implements the protocol as defined in :rfc:`1939`. The +:class:`POP3` class supports both the minimal and optional command sets from +:rfc:`1939`. The :class:`POP3` class also supports the `STLS` command introduced +in :rfc:`2595` to enable encrypted communication on an already established connection. + Additionally, this module provides a class :class:`POP3_SSL`, which provides support for connecting to POP3 servers that use SSL as an underlying protocol layer. @@ -97,6 +100,14 @@ An :class:`POP3` instance has the following methods: Returns the greeting string sent by the POP3 server. +.. method:: POP3.capa() + + Query the server's capabilities as specified in :rfc:`2449`. + Returns a dictionary in the form ``{'name': ['param'...]}``. + + .. versionadded:: 3.4 + + .. method:: POP3.user(username) Send user command, response should indicate that a password is required. @@ -176,6 +187,18 @@ An :class:`POP3` instance has the following methods: the unique id for that message in the form ``'response mesgnum uid``, otherwise result is list ``(response, ['mesgnum uid', ...], octets)``. +.. method:: POP3.stls(context=None) + + Start a TLS session on the active connection as specified in :rfc:`2595`. + This is only allowed before user authentication + + *context* parameter is a :class:`ssl.SSLContext` object which allows + bundling SSL configuration options, certificates and private keys into + a single (potentially long-lived) structure. + + .. versionadded:: 3.4 + + Instances of :class:`POP3_SSL` have no additional methods. The interface of this subclass is identical to its parent. diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 3a86331..8d57c5d 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -14,8 +14,8 @@ The :mod:`pprint` module provides a capability to "pretty-print" arbitrary Python data structures in a form which can be used as input to the interpreter. If the formatted structures include objects which are not fundamental Python types, the representation may not be loadable. This may be the case if objects -such as files, sockets, classes, or instances are included, as well as many -other built-in objects which are not representable as Python constants. +such as files, sockets or classes are included, as well as many other +objects which are not representable as Python literals. The formatted representation keeps objects on a single line if it can, and breaks them onto multiple lines if they don't fit within the allowed width. @@ -65,7 +65,7 @@ The :mod:`pprint` module defines one class: ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...))))))) -The :class:`PrettyPrinter` class supports several derivative functions: +The :mod:`pprint` module also provides several shortcut functions: .. function:: pformat(object, indent=1, width=80, depth=None) @@ -193,101 +193,141 @@ Example ------- To demonstrate several uses of the :func:`pprint` function and its parameters, -let's fetch information about a project from PyPI:: +let's fetch information about a project from `PyPI <https://pypi.python.org>`_:: >>> import json >>> import pprint >>> from urllib.request import urlopen - >>> with urlopen('http://pypi.python.org/pypi/configparser/json') as url: + >>> with urlopen('http://pypi.python.org/pypi/Twisted/json') as url: ... http_info = url.info() ... raw_data = url.read().decode(http_info.get_content_charset()) >>> project_info = json.loads(raw_data) - >>> result = {'headers': http_info.items(), 'body': project_info} In its basic form, :func:`pprint` shows the whole object:: - >>> pprint.pprint(result) - {'body': {'info': {'_pypi_hidden': False, - '_pypi_ordering': 12, - 'classifiers': ['Development Status :: 4 - Beta', - 'Intended Audience :: Developers', - 'License :: OSI Approved :: MIT License', - 'Natural Language :: English', - 'Operating System :: OS Independent', - 'Programming Language :: Python', - 'Programming Language :: Python :: 2', - 'Programming Language :: Python :: 2.6', - 'Programming Language :: Python :: 2.7', - 'Topic :: Software Development :: Libraries', - 'Topic :: Software Development :: Libraries :: Python Modules'], - 'download_url': 'UNKNOWN', - 'home_page': 'http://docs.python.org/py3k/library/configparser.html', - 'keywords': 'configparser ini parsing conf cfg configuration file', - 'license': 'MIT', - 'name': 'configparser', - 'package_url': 'http://pypi.python.org/pypi/configparser', - 'platform': 'any', - 'release_url': 'http://pypi.python.org/pypi/configparser/3.2.0r3', - 'requires_python': None, - 'stable_version': None, - 'summary': 'This library brings the updated configparser from Python 3.2+ to Python 2.6-2.7.', - 'version': '3.2.0r3'}, - 'urls': [{'comment_text': '', - 'downloads': 47, - 'filename': 'configparser-3.2.0r3.tar.gz', - 'has_sig': False, - 'md5_digest': '8500fd87c61ac0de328fc996fce69b96', - 'packagetype': 'sdist', - 'python_version': 'source', - 'size': 32281, - 'upload_time': '2011-05-10T16:28:50', - 'url': 'http://pypi.python.org/packages/source/c/configparser/configparser-3.2.0r3.tar.gz'}]}, - 'headers': [('Date', 'Sat, 14 May 2011 12:48:52 GMT'), - ('Server', 'Apache/2.2.16 (Debian)'), - ('Content-Disposition', 'inline'), - ('Connection', 'close'), - ('Transfer-Encoding', 'chunked'), - ('Content-Type', 'application/json; charset="UTF-8"')]} + >>> pprint.pprint(project_info) + {'info': {'_pypi_hidden': False, + '_pypi_ordering': 125, + 'author': 'Glyph Lefkowitz', + 'author_email': 'glyph@twistedmatrix.com', + 'bugtrack_url': '', + 'cheesecake_code_kwalitee_id': None, + 'cheesecake_documentation_id': None, + 'cheesecake_installability_id': None, + 'classifiers': ['Programming Language :: Python :: 2.6', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 2 :: Only'], + 'description': 'An extensible framework for Python programming, ' + 'with special focus\r\n' + 'on event-based network programming and ' + 'multiprotocol integration.', + 'docs_url': '', + 'download_url': 'UNKNOWN', + 'home_page': 'http://twistedmatrix.com/', + 'keywords': '', + 'license': 'MIT', + 'maintainer': '', + 'maintainer_email': '', + 'name': 'Twisted', + 'package_url': 'http://pypi.python.org/pypi/Twisted', + 'platform': 'UNKNOWN', + 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', + 'requires_python': None, + 'stable_version': None, + 'summary': 'An asynchronous networking framework written in Python', + 'version': '12.3.0'}, + 'urls': [{'comment_text': '', + 'downloads': 71844, + 'filename': 'Twisted-12.3.0.tar.bz2', + 'has_sig': False, + 'md5_digest': '6e289825f3bf5591cfd670874cc0862d', + 'packagetype': 'sdist', + 'python_version': 'source', + 'size': 2615733, + 'upload_time': '2012-12-26T12:47:03', + 'url': 'https://pypi.python.org/packages/source/T/Twisted/Twisted-12.3.0.tar.bz2'}, + {'comment_text': '', + 'downloads': 5224, + 'filename': 'Twisted-12.3.0.win32-py2.7.msi', + 'has_sig': False, + 'md5_digest': '6b778f5201b622a5519a2aca1a2fe512', + 'packagetype': 'bdist_msi', + 'python_version': '2.7', + 'size': 2916352, + 'upload_time': '2012-12-26T12:48:15', + 'url': 'https://pypi.python.org/packages/2.7/T/Twisted/Twisted-12.3.0.win32-py2.7.msi'}]} The result can be limited to a certain *depth* (ellipsis is used for deeper contents):: - >>> pprint.pprint(result, depth=3) - {'body': {'info': {'_pypi_hidden': False, - '_pypi_ordering': 12, - 'classifiers': [...], - 'download_url': 'UNKNOWN', - 'home_page': 'http://docs.python.org/py3k/library/configparser.html', - 'keywords': 'configparser ini parsing conf cfg configuration file', - 'license': 'MIT', - 'name': 'configparser', - 'package_url': 'http://pypi.python.org/pypi/configparser', - 'platform': 'any', - 'release_url': 'http://pypi.python.org/pypi/configparser/3.2.0r3', - 'requires_python': None, - 'stable_version': None, - 'summary': 'This library brings the updated configparser from Python 3.2+ to Python 2.6-2.7.', - 'version': '3.2.0r3'}, - 'urls': [{...}]}, - 'headers': [('Date', 'Sat, 14 May 2011 12:48:52 GMT'), - ('Server', 'Apache/2.2.16 (Debian)'), - ('Content-Disposition', 'inline'), - ('Connection', 'close'), - ('Transfer-Encoding', 'chunked'), - ('Content-Type', 'application/json; charset="UTF-8"')]} - -Additionally, maximum *width* can be suggested. If a long object cannot be -split, the specified width will be exceeded:: - - >>> pprint.pprint(result['headers'], width=30) - [('Date', - 'Sat, 14 May 2011 12:48:52 GMT'), - ('Server', - 'Apache/2.2.16 (Debian)'), - ('Content-Disposition', - 'inline'), - ('Connection', 'close'), - ('Transfer-Encoding', - 'chunked'), - ('Content-Type', - 'application/json; charset="UTF-8"')] + >>> pprint.pprint(project_info, depth=2) + {'info': {'_pypi_hidden': False, + '_pypi_ordering': 125, + 'author': 'Glyph Lefkowitz', + 'author_email': 'glyph@twistedmatrix.com', + 'bugtrack_url': '', + 'cheesecake_code_kwalitee_id': None, + 'cheesecake_documentation_id': None, + 'cheesecake_installability_id': None, + 'classifiers': [...], + 'description': 'An extensible framework for Python programming, ' + 'with special focus\r\n' + 'on event-based network programming and ' + 'multiprotocol integration.', + 'docs_url': '', + 'download_url': 'UNKNOWN', + 'home_page': 'http://twistedmatrix.com/', + 'keywords': '', + 'license': 'MIT', + 'maintainer': '', + 'maintainer_email': '', + 'name': 'Twisted', + 'package_url': 'http://pypi.python.org/pypi/Twisted', + 'platform': 'UNKNOWN', + 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', + 'requires_python': None, + 'stable_version': None, + 'summary': 'An asynchronous networking framework written in Python', + 'version': '12.3.0'}, + 'urls': [{...}, {...}]} + +Additionally, maximum character *width* can be suggested. If a long object +cannot be split, the specified width will be exceeded:: + + >>> pprint.pprint(project_info, depth=2, width=50) + {'info': {'_pypi_hidden': False, + '_pypi_ordering': 125, + 'author': 'Glyph Lefkowitz', + 'author_email': 'glyph@twistedmatrix.com', + 'bugtrack_url': '', + 'cheesecake_code_kwalitee_id': None, + 'cheesecake_documentation_id': None, + 'cheesecake_installability_id': None, + 'classifiers': [...], + 'description': 'An extensible ' + 'framework for ' + 'Python programming, ' + 'with special ' + 'focus\r\n' + 'on event-based ' + 'network programming ' + 'and multiprotocol ' + 'integration.', + 'docs_url': '', + 'download_url': 'UNKNOWN', + 'home_page': 'http://twistedmatrix.com/', + 'keywords': '', + 'license': 'MIT', + 'maintainer': '', + 'maintainer_email': '', + 'name': 'Twisted', + 'package_url': 'http://pypi.python.org/pypi/Twisted', + 'platform': 'UNKNOWN', + 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', + 'requires_python': None, + 'stable_version': None, + 'summary': 'An asynchronous ' + 'networking framework ' + 'written in Python', + 'version': '12.3.0'}, + 'urls': [{...}, {...}]} diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index 2b9385b..90baec5 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -45,6 +45,9 @@ The :mod:`pty` module defines the following functions: a file descriptor. The defaults try to read 1024 bytes each time they are called. + .. versionchanged:: 3.4 + :func:`spawn` now returns the status value from :func:`os.waitpid` + on the child process. Example ------- diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst index 07ddc25..0c8c99d 100644 --- a/Doc/library/py_compile.rst +++ b/Doc/library/py_compile.rst @@ -28,7 +28,7 @@ byte-code cache files in the directory containing the source code. .. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1) - Compile a source file to byte-code and write out the byte-code cache file. + Compile a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file name *file*. The byte-code is written to *cfile*, which defaults to the :PEP:`3147` path, ending in ``.pyc`` (``.pyo`` if optimization is enabled in the current interpreter). @@ -50,6 +50,11 @@ byte-code cache files in the directory containing the source code. default was *file* + ``'c'`` (``'o'`` if optimization was enabled). Also added the *optimize* parameter. + .. versionchanged:: 3.4 + Changed code to use :mod:`importlib` for the byte-code cache file writing. + This means file creation/writing semantics now match what :mod:`importlib` + does, e.g. permissions, write-and-move semantics, etc. + .. function:: main(args=None) diff --git a/Doc/library/select.rst b/Doc/library/select.rst index 4e60f4a..b73f11e 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -47,11 +47,14 @@ The module defines the following: to :const:`EPOLL_CLOEXEC`, which causes the epoll descriptor to be closed automatically when :func:`os.execve` is called. See section :ref:`epoll-objects` below for the methods supported by epolling objects. - + They also support the :keyword:`with` statement. .. versionchanged:: 3.3 Added the *flags* parameter. + .. versionchanged:: 3.4 + Support for the :keyword:`with` statement was added. + .. function:: poll() diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst index 9d7d504..b60a548 100644 --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -44,8 +44,11 @@ lots of shared sub-objects. The keys are ordinary strings. .. note:: Do not rely on the shelf being closed automatically; always call - :meth:`close` explicitly when you don't need it any more, or use a - :keyword:`with` statement with :func:`contextlib.closing`. + :meth:`~Shelf.close` explicitly when you don't need it any more, or + use :func:`shelve.open` as a context manager:: + + with shelve.open('spam') as db: + db['eggs'] = 'eggs' .. warning:: @@ -118,10 +121,15 @@ Restrictions The *keyencoding* parameter is the encoding used to encode keys before they are used with the underlying dict. - .. versionadded:: 3.2 - The *keyencoding* parameter; previously, keys were always encoded in + :class:`Shelf` objects can also be used as context managers. + + .. versionchanged:: 3.2 + Added the *keyencoding* parameter; previously, keys were always encoded in UTF-8. + .. versionchanged:: 3.4 + Added context manager support. + .. class:: BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8') diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index a1457d0..e4f348c 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -53,7 +53,7 @@ Directory and files operations *dst* and return *dst*. *src* and *dst* are path names given as strings. *dst* must be the complete target file name; look at :func:`shutil.copy` for a copy that accepts a target directory path. If *src* and *dst* - specify the same file, :exc:`Error` is raised. + specify the same file, :exc:`SameFileError` is raised. The destination location must be writable; otherwise, an :exc:`OSError` exception will be raised. If *dst* already exists, it will be replaced. @@ -69,6 +69,19 @@ Directory and files operations Added *follow_symlinks* argument. Now returns *dst*. + .. versionchanged:: 3.4 + Raise :exc:`SameFileError` instead of :exc:`Error`. Since the former is + a subclass of the latter, this change is backward compatible. + + +.. exception:: SameFileError + + This exception is raised if source and destination in :func:`copyfile` + are the same file. + + .. versionadded:: 3.4 + + .. function:: copymode(src, dst, *, follow_symlinks=True) Copy the permission bits from *src* to *dst*. The file contents, owner, and @@ -380,11 +393,10 @@ provided by this module. :: errors.extend(err.args[0]) try: copystat(src, dst) - except WindowsError: - # can't copy file access times on Windows - pass except OSError as why: - errors.extend((src, dst, str(why))) + # can't copy file access times on Windows + if why.winerror is None: + errors.extend((src, dst, str(why))) if errors: raise Error(errors) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 9593dea..5762bb6 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -103,8 +103,8 @@ A nice selection of exceptions is defined as well: .. exception:: SMTPException - The base exception class for all the other excpetions provided by this - module. + Subclass of :exc:`OSError` that is the base exception class for all + the other excpetions provided by this module. .. exception:: SMTPServerDisconnected diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index b442b7c..aa59f7f 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -107,8 +107,8 @@ created. Socket addresses are represented as follows: .. versionadded:: 3.3 -- Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`) - support specific representations. +- Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`, + :const:`AF_CAN`) support specific representations. .. XXX document them! @@ -257,6 +257,16 @@ The module :mod:`socket` exports the following constants and functions: .. versionadded:: 3.3 +.. data:: CAN_BCM + CAN_BCM_* + + CAN_BCM, in the CAN protocol family, is the broadcast manager (BCM) protocol. + Broadcast manager constants, documented in the Linux documentation, are also + defined in the socket module. + + Availability: Linux >= 2.6.25. + + .. versionadded:: 3.4 .. data:: AF_RDS PF_RDS @@ -452,13 +462,16 @@ The module :mod:`socket` exports the following constants and functions: :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The socket type should be :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_`` - constants. The protocol number is usually zero and may be omitted in that - case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`. + constants. The protocol number is usually zero and may be omitted or in the + case where the address family is :const:`AF_CAN` the protocol should be one + of :const:`CAN_RAW` or :const:`CAN_BCM`. .. versionchanged:: 3.3 The AF_CAN family was added. The AF_RDS family was added. + .. versionchanged:: 3.4 + The CAN_BCM protocol was added. .. function:: socketpair([family[, type[, proto]]]) @@ -1331,7 +1344,16 @@ the interface:: s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF) The last example shows how to use the socket interface to communicate to a CAN -network. This example might require special priviledge:: +network using the raw socket protocol. To use CAN with the broadcast +manager protocol instead, open a socket with:: + + socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM) + +After binding (:const:`CAN_RAW`) or connecting (:const:`CAN_BCM`) the socket, you +can use the :meth:`socket.send`, and the :meth:`socket.recv` operations (and +their counterparts) on the socket object as usual. + +This example might require special priviledge:: import socket import struct diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 08e3a2e..529dc94 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -159,7 +159,7 @@ Module functions and constants first blank for the column name: the column name would simply be "x". -.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements]) +.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri]) Opens a connection to the SQLite database file *database*. You can use ``":memory:"`` to open a database connection to a database that resides in RAM @@ -195,6 +195,18 @@ Module functions and constants for the connection, you can set the *cached_statements* parameter. The currently implemented default is to cache 100 statements. + If *uri* is true, *database* is interpreted as a URI. This allows you + to specify options. For example, to open a database in read-only mode + you can use:: + + db = sqlite3.connect('file:path/to/database?mode=ro', uri=True) + + More information about this feature, including a list of recognized options, can + be found in the `SQLite URI documentation <http://www.sqlite.org/uri.html>`_. + + .. versionchanged:: 3.4 + Added the *uri* parameter. + .. function:: register_converter(typename, callable) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 1d4f9ca..2f8b9a2 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -26,7 +26,8 @@ probably additional platforms, as long as OpenSSL is installed on that platform. Some behavior may be platform dependent, since calls are made to the operating system socket APIs. The installed version of OpenSSL may also - cause variations in behavior. + cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with + openssl version 1.0.1. This section documents the objects and functions in the ``ssl`` module; for more general information about TLS, SSL, and certificates, the reader is referred to @@ -177,14 +178,16 @@ instead. .. table:: - ======================== ========= ========= ========== ========= - *client* / **server** **SSLv2** **SSLv3** **SSLv23** **TLSv1** - ------------------------ --------- --------- ---------- --------- - *SSLv2* yes no yes no - *SSLv3* no yes yes no - *SSLv23* yes no yes no - *TLSv1* no no yes yes - ======================== ========= ========= ========== ========= + ======================== ========= ========= ========== ========= =========== =========== + *client* / **server** **SSLv2** **SSLv3** **SSLv23** **TLSv1** **TLSv1.1** **TLSv1.2** + ------------------------ --------- --------- ---------- --------- ----------- ----------- + *SSLv2* yes no yes no no no + *SSLv3* no yes yes no no no + *SSLv23* yes no yes no no no + *TLSv1* no no yes yes no no + *TLSv1.1* no no yes no yes no + *TLSv1.2* no no yes no no yes + ======================== ========= ========= ========== ========= =========== =========== .. note:: @@ -401,9 +404,25 @@ Constants .. data:: PROTOCOL_TLSv1 - Selects TLS version 1 as the channel encryption protocol. This is the most + Selects TLS version 1.0 as the channel encryption protocol. + +.. data:: PROTOCOL_TLSv1_1 + + + Selects TLS version 1.1 as the channel encryption protocol. + Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 + +.. data:: PROTOCOL_TLSv1_2 + + + Selects TLS version 1.2 as the channel encryption protocol. This is the most modern version, and probably the best choice for maximum protection, if both sides can speak it. + Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 .. data:: OP_ALL @@ -437,6 +456,22 @@ Constants .. versionadded:: 3.2 +.. data:: OP_NO_TLSv1_1 + + Prevents a TLSv1.1 connection. This option is only applicable in conjunction + with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.1 as + the protocol version. Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 + +.. data:: OP_NO_TLSv1_2 + + Prevents a TLSv1.2 connection. This option is only applicable in conjunction + with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.2 as + the protocol version. Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 + .. data:: OP_CIPHER_SERVER_PREFERENCE Use the server's cipher ordering preference, rather than the client's. @@ -533,6 +568,19 @@ Constants .. versionadded:: 3.2 +.. data:: ALERT_DESCRIPTION_HANDSHAKE_FAILURE + ALERT_DESCRIPTION_INTERNAL_ERROR + ALERT_DESCRIPTION_* + + Alert Descriptions from :rfc:`5246` and others. The `IANA TLS Alert Registry + <http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_ + contains this list and references to the RFCs where their meaning is defined. + + Used as the return value of the callback function in + :meth:`SSLContext.set_servername_callback`. + + .. versionadded:: 3.4 + SSL Sockets ----------- @@ -786,6 +834,56 @@ to speed up repeated connections from the same clients. .. versionadded:: 3.3 +.. method:: SSLContext.set_servername_callback(server_name_callback) + + Register a callback function that will be called after the TLS Client Hello + handshake message has been received by the SSL/TLS server when the TLS client + specifies a server name indication. The server name indication mechanism + is specified in :rfc:`6066` section 3 - Server Name Indication. + + Only one callback can be set per ``SSLContext``. If *server_name_callback* + is ``None`` then the callback is disabled. Calling this function a + subsequent time will disable the previously registered callback. + + The callback function, *server_name_callback*, will be called with three + arguments; the first being the :class:`ssl.SSLSocket`, the second is a string + that represents the server name that the client is intending to communicate + (or :const:`None` if the TLS Client Hello does not contain a server name) + and the third argument is the original :class:`SSLContext`. The server name + argument is the IDNA decoded server name. + + A typical use of this callback is to change the :class:`ssl.SSLSocket`'s + :attr:`SSLSocket.context` attribute to a new object of type + :class:`SSLContext` representing a certificate chain that matches the server + name. + + Due to the early negotiation phase of the TLS connection, only limited + methods and attributes are usable like + :meth:`SSLSocket.selected_npn_protocol` and :attr:`SSLSocket.context`. + :meth:`SSLSocket.getpeercert`, :meth:`SSLSocket.getpeercert`, + :meth:`SSLSocket.cipher` and :meth:`SSLSocket.compress` methods require that + the TLS connection has progressed beyond the TLS Client Hello and therefore + will not contain return meaningful values nor can they be called safely. + + The *server_name_callback* function must return ``None`` to allow the + TLS negotiation to continue. If a TLS failure is required, a constant + :const:`ALERT_DESCRIPTION_* <ALERT_DESCRIPTION_INTERNAL_ERROR>` can be + returned. Other return values will result in a TLS fatal error with + :const:`ALERT_DESCRIPTION_INTERNAL_ERROR`. + + If there is a IDNA decoding error on the server name, the TLS connection + will terminate with an :const:`ALERT_DESCRIPTION_INTERNAL_ERROR` fatal TLS + alert message to the client. + + If an exception is raised from the *server_name_callback* function the TLS + connection will terminate with a fatal TLS alert message + :const:`ALERT_DESCRIPTION_HANDSHAKE_FAILURE`. + + This method will raise :exc:`NotImplementedError` if the OpenSSL library + had OPENSSL_NO_TLSEXT defined when it was built. + + .. versionadded:: 3.4 + .. method:: SSLContext.load_dh_params(dhfile) Load the key generation parameters for Diffie-Helman (DH) key exchange. @@ -1319,3 +1417,12 @@ use the ``openssl ciphers`` command on your system. `RFC 4366: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc/rfc4366>`_ Blake-Wilson et. al. + + `RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <http://www.ietf.org/rfc/rfc5246>`_ + T. Dierks et. al. + + `RFC 6066: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc/rfc6066>`_ + D. Eastlake + + `IANA TLS: Transport Layer Security (TLS) Parameters <http://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_ + IANA diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 4212e02..792a58f 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -829,8 +829,6 @@ The :mod:`subprocess` module exposes the following constants. The new process has a new console, instead of inheriting its parent's console (the default). - This flag is always set when :class:`Popen` is created with ``shell=True``. - .. data:: CREATE_NEW_PROCESS_GROUP A :class:`Popen` ``creationflags`` parameter to specify that a new process diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index e7e853d..5f8399f 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -380,6 +380,21 @@ always available. .. versionadded:: 3.1 +.. function:: getallocatedblocks() + + Return the number of memory blocks currently allocated by the interpreter, + regardless of their size. This function is mainly useful for tracking + and debugging memory leaks. Because of the interpreter's internal + caches, the result can vary from call to call; you may have to call + :func:`_clear_type_cache()` and :func:`gc.collect()` to get more + predictable results. + + If a Python build or implementation cannot reasonably compute this + information, :func:`getallocatedblocks()` is allowed to return 0 instead. + + .. versionadded:: 3.4 + + .. function:: getcheckinterval() Return the interpreter's "check interval"; see :func:`setcheckinterval`. @@ -809,8 +824,6 @@ always available. Windows ``'win32'`` Windows/Cygwin ``'cygwin'`` Mac OS X ``'darwin'`` - OS/2 ``'os2'`` - OS/2 EMX ``'os2emx'`` ================ =========================== .. versionchanged:: 3.3 @@ -1091,7 +1104,6 @@ always available. | :const:`name` | Name of the thread implementation: | | | | | | * ``'nt'``: Windows threads | - | | * ``'os2'``: OS/2 threads | | | * ``'pthread'``: POSIX threads | | | * ``'solaris'``: Solaris threads | +------------------+---------------------------------------------------------+ diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst index c47dcce..535ac54 100644 --- a/Doc/library/sysconfig.rst +++ b/Doc/library/sysconfig.rst @@ -83,8 +83,6 @@ Python currently supports seven schemes: located under the user home directory. - *nt*: scheme for NT platforms like Windows. - *nt_user*: scheme for NT platforms, when the *user* option is used. -- *os2*: scheme for OS/2 platforms. -- *os2_home*: scheme for OS/2 patforms, when the *user* option is used. Each scheme is itself composed of a series of paths and each path has a unique identifier. Python currently uses eight paths: diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index a487917..0cc1586 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -151,7 +151,7 @@ The module defines three convenience functions and a public class: t = Timer(...) # outside the try/except try: t.timeit(...) # or t.repeat(...) - except: + except Exception: t.print_exc() The advantage over the standard traceback is that source lines in the diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 83a5375..377694f 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -750,32 +750,6 @@ Entry widget indexes (index, view index, etc.) displayed. You can use these :mod:`tkinter` functions to access these special points in text widgets: -.. function:: AtEnd() - refers to the last position in the text - - .. deprecated:: 3.3 - -.. function:: AtInsert() - refers to the point where the text cursor is - - .. deprecated:: 3.3 - -.. function:: AtSelFirst() - indicates the beginning point of the selected text - - .. deprecated:: 3.3 - -.. function:: AtSelLast() - denotes the last point of the selected text and finally - - .. deprecated:: 3.3 - -.. function:: At(x[, y]) - refers to the character at pixel location *x*, *y* (with *y* not used in the - case of a text entry widget, which contains a single line of text). - - .. deprecated:: 3.3 - Text widget indexes The index notation for Text widgets is very rich and is best described in the Tk man pages. diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 32e5733..0533bea 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -146,7 +146,7 @@ module. :: source = input(">>> ") try: exec(source, envdir) - except: + except Exception: print("Exception in user code:") print("-"*60) traceback.print_exc(file=sys.stdout) diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 695480f..95132e8 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -212,6 +212,8 @@ Standard names are defined for the following types: keys = sorted(self.__dict__) items = ("{}={!r}".format(k, self.__dict__[k]) for k in keys) return "{}({})".format(type(self).__name__, ", ".join(items)) + def __eq__(self, other): + return self.__dict__ == other.__dict__ ``SimpleNamespace`` may be useful as a replacement for ``class NS: pass``. However, for a structured record type use :func:`~collections.namedtuple` diff --git a/Doc/library/unicodedata.rst b/Doc/library/unicodedata.rst index ad70dd9..26eced6 100644 --- a/Doc/library/unicodedata.rst +++ b/Doc/library/unicodedata.rst @@ -15,8 +15,8 @@ This module provides access to the Unicode Character Database (UCD) which defines character properties for all Unicode characters. The data contained in -this database is compiled from the `UCD version 6.1.0 -<http://www.unicode.org/Public/6.1.0/ucd>`_. +this database is compiled from the `UCD version 6.2.0 +<http://www.unicode.org/Public/6.2.0/ucd>`_. The module uses the same names and symbols as defined by Unicode Standard Annex #44, `"Unicode Character Database" @@ -166,6 +166,6 @@ Examples: .. rubric:: Footnotes -.. [#] http://www.unicode.org/Public/6.1.0/ucd/NameAliases.txt +.. [#] http://www.unicode.org/Public/6.2.0/ucd/NameAliases.txt -.. [#] http://www.unicode.org/Public/6.1.0/ucd/NamedSequences.txt +.. [#] http://www.unicode.org/Public/6.2.0/ucd/NamedSequences.txt diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst index d7d697d..444c208 100644 --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -277,6 +277,20 @@ instantiate the class in those tests. ... AttributeError: object has no attribute 'old_method' +Using a specification also enables a smarter matching of calls made to the +mock, regardless of whether some parameters were passed as positional or +named arguments:: + + >>> def f(a, b, c): pass + ... + >>> mock = Mock(spec=f) + >>> mock(1, 2, 3) + <Mock name='mock()' id='140161580456576'> + >>> mock.assert_called_with(a=1, b=2, c=3) + +If you want this smarter matching to also work with method calls on the mock, +you can use :ref:`auto-speccing <auto-speccing>`. + If you want a stronger form of specification that prevents the setting of arbitrary attributes as well as the getting of them then you can use `spec_set` instead of `spec`. diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 6d1a57e..be63728 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -264,7 +264,6 @@ the `new_callable` argument to `patch`. <Mock name='mock.method()' id='...'> >>> mock.method.assert_called_with(1, 2, 3, test='wow') - .. method:: assert_called_once_with(*args, **kwargs) Assert that the mock was called exactly once and with the specified @@ -685,6 +684,27 @@ have to create a dictionary and unpack it using `**`: ... KeyError +A callable mock which was created with a *spec* (or a *spec_set*) will +introspect the specification object's signature when matching calls to +the mock. Therefore, it can match the actual call's arguments regardless +of whether they were passed positionally or by name:: + + >>> def f(a, b, c): pass + ... + >>> mock = Mock(spec=f) + >>> mock(1, 2, c=3) + <Mock name='mock()' id='140161580456576'> + >>> mock.assert_called_with(1, 2, 3) + >>> mock.assert_called_with(a=1, b=2, c=3) + +This applies to :meth:`~Mock.assert_called_with`, +:meth:`~Mock.assert_called_once_with`, :meth:`~Mock.assert_has_calls` and +:meth:`~Mock.assert_any_call`. When :ref:`auto-speccing`, it will also +apply to method calls on the mock object. + + .. versionchanged:: 3.4 + Added signature introspection on specced and autospecced mock objects. + .. class:: PropertyMock(*args, **kwargs) @@ -1969,8 +1989,12 @@ mock_open default) then a `MagicMock` will be created for you, with the API limited to methods or attributes available on standard file handles. - `read_data` is a string for the `read` method of the file handle to return. - This is an empty string by default. + `read_data` is a string for the `read`, `readline`, and `readlines` methods + of the file handle to return. Calls to those methods will take data from + `read_data` until it is depleted. The mock of these methods is pretty + simplistic. If you need more control over the data that you are feeding to + the tested code you will need to customize this mock for yourself. + `read_data` is an empty string by default. Using `open` as a context manager is a great way to ensure your file handles are closed properly and is becoming common:: diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index c44ab23..766122b 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -563,6 +563,68 @@ Skipped tests will not have :meth:`setUp` or :meth:`tearDown` run around them. Skipped classes will not have :meth:`setUpClass` or :meth:`tearDownClass` run. +.. _subtests: + +Distinguishing test iterations using subtests +--------------------------------------------- + +.. versionadded:: 3.4 + +When some of your tests differ only by a some very small differences, for +instance some parameters, unittest allows you to distinguish them inside +the body of a test method using the :meth:`~TestCase.subTest` context manager. + +For example, the following test:: + + class NumbersTest(unittest.TestCase): + + def test_even(self): + """ + Test that numbers between 0 and 5 are all even. + """ + for i in range(0, 6): + with self.subTest(i=i): + self.assertEqual(i % 2, 0) + +will produce the following output:: + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) (i=1) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) (i=3) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) (i=5) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + +Without using a subtest, execution would stop after the first failure, +and the error would be less easy to diagnose because the value of ``i`` +wouldn't be displayed:: + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + + .. _unittest-contents: Classes and functions @@ -676,6 +738,21 @@ Test cases .. versionadded:: 3.1 + .. method:: subTest(msg=None, **params) + + Return a context manager which executes the enclosed code block as a + subtest. *msg* and *params* are optional, arbitrary values which are + displayed whenever a subtest fails, allowing you to identify them + clearly. + + A test case can contain any number of subtest declarations, and + they can be arbitrarily nested. + + See :ref:`subtests` for more information. + + .. versionadded:: 3.4 + + .. method:: debug() Run the test without collecting the result. This allows exceptions raised @@ -1500,7 +1577,9 @@ Loading and running tests directory must be specified separately. If importing a module fails, for example due to a syntax error, then this - will be recorded as a single error and discovery will continue. + will be recorded as a single error and discovery will continue. If the + import failure is due to :exc:`SkipTest` being raised, it will be recorded + as a skip instead of an error. If a test package name (directory with :file:`__init__.py`) matches the pattern then the package will be checked for a ``load_tests`` @@ -1519,6 +1598,15 @@ Loading and running tests .. versionadded:: 3.2 + .. versionchanged:: 3.4 + Modules that raise :exc:`SkipTest` on import are recorded as skips, + not errors. + + .. versionchanged:: 3.4 + Paths are sorted before being imported to ensure execution order for a + given test suite is the same even if the underlying file system's ordering + is not dependent on file name like in ext3/4. + The following attributes of a :class:`TestLoader` can be configured either by subclassing or assignment on an instance: @@ -1729,6 +1817,22 @@ Loading and running tests :attr:`unexpectedSuccesses` attribute. + .. method:: addSubTest(test, subtest, outcome) + + Called when a subtest finishes. *test* is the test case + corresponding to the test method. *subtest* is a custom + :class:`TestCase` instance describing the subtest. + + If *outcome* is :const:`None`, the subtest succeeded. Otherwise, + it failed with an exception where *outcome* is a tuple of the form + returned by :func:`sys.exc_info`: ``(type, value, traceback)``. + + The default implementation does nothing when the outcome is a + success, and records subtest failures as normal failures. + + .. versionadded:: 3.4 + + .. class:: TextTestResult(stream, descriptions, verbosity) A concrete implementation of :class:`TestResult` used by the @@ -1837,6 +1941,10 @@ Loading and running tests The *verbosity*, *failfast*, *catchbreak*, *buffer* and *warnings* parameters were added. + .. versionchanged:: 3.4 + The *defaultTest* parameter was changed to also accept an iterable of + test names. + load_tests Protocol ################### diff --git a/Doc/library/urllib.error.rst b/Doc/library/urllib.error.rst index 9c3fe91..7bd04b1 100644 --- a/Doc/library/urllib.error.rst +++ b/Doc/library/urllib.error.rst @@ -45,6 +45,13 @@ The following exceptions are raised by :mod:`urllib.error` as appropriate: This is usually a string explaining the reason for this error. + .. attribute:: headers + + The HTTP response headers for the HTTP request that cause the + :exc:`HTTPError`. + + .. versionadded:: 3.4 + .. exception:: ContentTooShortError(msg, content) This exception is raised when the :func:`urlretrieve` function detects that diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index c507084..ef80a92 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -129,7 +129,7 @@ The :mod:`urllib.request` module defines the following functions: instances of them or subclasses of them: :class:`ProxyHandler`, :class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`, :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`, - :class:`HTTPErrorProcessor`. + :class:`HTTPErrorProcessor`, :class:`DataHandler`. If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported), :class:`HTTPSHandler` will also be added. @@ -354,6 +354,11 @@ The following classes are provided: Open local files. +.. class:: DataHandler() + + Open data URLs. + + .. versionadded:: 3.4 .. class:: FTPHandler() @@ -411,6 +416,10 @@ request. The entity body for the request, or None if not specified. + .. versionchanged:: 3.4 + Changing value of :attr:`Request.data` now deletes "Content-Length" + header if it was previously set or calculated. + .. attribute:: Request.unverifiable boolean, indicates whether the request is unverifiable as defined @@ -459,6 +468,14 @@ request. unredirected). +.. method:: Request.remove_header(header) + + Remove named header from the request instance (both from regular and + unredirected headers). + + .. versionadded:: 3.4 + + .. method:: Request.get_full_url() Return the URL given in the constructor. @@ -471,54 +488,6 @@ request. URL given in the constructor. -.. method:: Request.add_data(data) - - Set the :class:`Request` data to *data*. This is ignored by all handlers except - HTTP handlers --- and there it should be a byte string, and will change the - request to be ``POST`` rather than ``GET``. Deprecated in 3.3, use - :attr:`Request.data`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.has_data() - - Return whether the instance has a non-\ ``None`` data. Deprecated in 3.3, - use :attr:`Request.data`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.get_data() - - Return the instance's data. Deprecated in 3.3, use :attr:`Request.data`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.get_type() - - Return the type of the URL --- also known as the scheme. Deprecated in 3.3, - use :attr:`Request.type`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.get_host() - - Return the host to which a connection will be made. Deprecated in 3.3, use - :attr:`Request.host`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.get_selector() - - Return the selector --- the part of the URL that is sent to the server. - Deprecated in 3.3, use :attr:`Request.selector`. - - .. deprecated-removed:: 3.3 3.4 - .. method:: Request.get_header(header_name, default=None) Return the value of the given header. If the header is not present, return @@ -529,26 +498,10 @@ request. Return a list of tuples (header_name, header_value) of the Request headers. - -.. method:: Request.set_proxy(host, type) - -.. method:: Request.get_origin_req_host() - - Return the request-host of the origin transaction, as defined by - :rfc:`2965`. See the documentation for the :class:`Request` constructor. - Deprecated in 3.3, use :attr:`Request.origin_req_host`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.is_unverifiable() - - Return whether the request is unverifiable, as defined by RFC 2965. See the - documentation for the :class:`Request` constructor. Deprecated in 3.3, use - :attr:`Request.unverifiable`. - - .. deprecated-removed:: 3.3 3.4 - +.. versionchanged:: 3.4 + Request methods add_data, has_data, get_data, get_type, get_host, + get_selector, get_origin_req_host and is_unverifiable deprecated since 3.3 + have been removed. .. _opener-director-objects: @@ -980,6 +933,21 @@ FileHandler Objects hostname is given, an :exc:`URLError` is raised. +.. _data-handler-objects: + +DataHandler Objects +------------------- + +.. method:: DataHandler.data_open(req) + + Read a data URL. This kind of URL contains the content encoded in the URL + itself. The data URL syntax is specified in :rfc:`2397`. This implementation + ignores white spaces in base64 encoded data URLs so the URL may be wrapped + in whatever source file it comes from. But even though some browsers don't + mind about a missing padding at the end of a base64 encoded data URL, this + implementation will raise an :exc:`ValueError` in that case. + + .. _ftp-handler-objects: FTPHandler Objects @@ -1395,7 +1363,9 @@ some point in the future. pair: FTP; protocol * Currently, only the following protocols are supported: HTTP (versions 0.9 and - 1.0), FTP, and local files. + 1.0), FTP, local files, and data URLs. + + .. versionchanged:: 3.4 Added support for data URLs. * The caching feature of :func:`urlretrieve` has been disabled until someone finds the time to hack proper processing of Expiration time headers. diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index cd04808..5cd209c 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -75,8 +75,8 @@ creation according to their needs, the :class:`EnvBuilder` class. * ``system_site_packages`` -- a Boolean value indicating that the system Python site-packages should be available to the environment (defaults to ``False``). - * ``clear`` -- a Boolean value which, if True, will delete any existing target - directory instead of raising an exception (defaults to ``False``). + * ``clear`` -- a Boolean value which, if True, will delete the contents of + any existing target directory, before creating the environment. * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the Python binary (and any necessary DLLs or other binaries, @@ -88,7 +88,6 @@ creation according to their needs, the :class:`EnvBuilder` class. upgraded in-place (defaults to ``False``). - Creators of third-party virtual environment tools will be free to use the provided ``EnvBuilder`` class as a base class. diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst index afafb45..2e64d00 100644 --- a/Doc/library/wave.rst +++ b/Doc/library/wave.rst @@ -98,8 +98,9 @@ Wave_read objects, as returned by :func:`.open`, have the following methods: .. method:: Wave_read.getparams() - Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype, - compname)``, equivalent to output of the :meth:`get\*` methods. + Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, + framerate, nframes, comptype, compname)``, equivalent to output of the + :meth:`get\*` methods. .. method:: Wave_read.readframes(n) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 224f442..ec50107 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -111,6 +111,15 @@ Extension types can easily be made to support weak references; see This is a subclassable type rather than a factory function. + .. attribute:: __callback__ + + This read-only attribute returns the callback currently associated to the + weakref. If there is no callback or if the referent of the weakref is + no longer alive then this attribute will have value ``None``. + + .. versionadded:: 3.4 + Added the :attr:`__callback__` attribute. + .. function:: proxy(object[, callback]) @@ -192,6 +201,35 @@ These method have the same issues as the and :meth:`keyrefs` method of discarded when no strong reference to it exists any more. +.. class:: WeakMethod(method) + + A custom :class:`ref` subclass which simulates a weak reference to a bound + method (i.e., a method defined on a class and looked up on an instance). + Since a bound method is ephemeral, a standard weak reference cannot keep + hold of it. :class:`WeakMethod` has special code to recreate the bound + method until either the object or the original function dies:: + + >>> class C: + ... def method(self): + ... print("method called!") + ... + >>> c = C() + >>> r = weakref.ref(c.method) + >>> r() + >>> r = weakref.WeakMethod(c.method) + >>> r() + <bound method C.method of <__main__.C object at 0x7fc859830220>> + >>> r()() + method called! + >>> del c + >>> gc.collect() + 0 + >>> r() + >>> + + .. versionadded:: 3.4 + + .. data:: ReferenceType The type object for weak references objects. @@ -232,8 +270,9 @@ These method have the same issues as the and :meth:`keyrefs` method of Weak Reference Objects ---------------------- -Weak reference objects have no attributes or methods, but do allow the referent -to be obtained, if it still exists, by calling it: +Weak reference objects have no methods and no attributes besides +:attr:`ref.__callback__`. A weak reference object allows the referent to be +obtained, if it still exists, by calling it: >>> import weakref >>> class Object: diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 45a0e7b..da03764 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -397,6 +397,9 @@ Functions If you need a fully populated element, look for "end" events instead. + .. note:: + For real event-driven parsing, see :class:`IncrementalParser`. + .. function:: parse(source, parser=None) @@ -437,29 +440,39 @@ Functions arguments. Returns an element instance. -.. function:: tostring(element, encoding="us-ascii", method="xml") +.. function:: tostring(element, encoding="us-ascii", method="xml", *, \ + short_empty_elements=True) Generates a string representation of an XML element, including all subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to generate a Unicode string (otherwise, a bytestring is generated). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + *short_empty_elements* has the same meaning as in :meth:`ElementTree.write`. Returns an (optionally) encoded string containing the XML data. + .. versionadded:: 3.4 + The *short_empty_elements* parameter. -.. function:: tostringlist(element, encoding="us-ascii", method="xml") + +.. function:: tostringlist(element, encoding="us-ascii", method="xml", *, \ + short_empty_elements=True) Generates a string representation of an XML element, including all subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to generate a Unicode string (otherwise, a bytestring is generated). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + *short_empty_elements* has the same meaning as in :meth:`ElementTree.write`. Returns a list of (optionally) encoded strings containing the XML data. It does not guarantee any specific sequence, except that ``"".join(tostringlist(element)) == tostring(element)``. .. versionadded:: 3.2 + .. versionadded:: 3.4 + The *short_empty_elements* parameter. + .. function:: XML(text, parser=None) @@ -751,7 +764,8 @@ ElementTree Objects .. method:: write(file, encoding="us-ascii", xml_declaration=None, \ - default_namespace=None, method="xml") + default_namespace=None, method="xml", *, \ + short_empty_elements=True) Writes the element tree to a file, as XML. *file* is a file name, or a :term:`file object` opened for writing. *encoding* [1]_ is the output @@ -762,6 +776,10 @@ ElementTree Objects *default_namespace* sets the default XML namespace (for "xmlns"). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + The keyword-only *short_empty_elements* parameter controls the formatting + of elements that contain no content. If *True* (the default), they are + emitted as a single self-closed tag, otherwise they are emitted as a pair + of start/end tags. The output is either a string (:class:`str`) or binary (:class:`bytes`). This is controlled by the *encoding* argument. If *encoding* is @@ -770,6 +788,9 @@ ElementTree Objects :term:`file object`; make sure you do not try to write a string to a binary stream and vice versa. + .. versionadded:: 3.4 + The *short_empty_elements* parameter. + This is the XML file that is going to be manipulated:: @@ -815,6 +836,48 @@ QName Objects :class:`QName` instances are opaque. +IncrementalParser Objects +^^^^^^^^^^^^^^^^^^^^^^^^^ + + +.. class:: IncrementalParser(events=None, parser=None) + + An incremental, event-driven parser suitable for non-blocking applications. + *events* is a list of events to report back. The supported events are the + strings ``"start"``, ``"end"``, ``"start-ns"`` and ``"end-ns"`` (the "ns" + events are used to get detailed namespace information). If *events* is + omitted, only ``"end"`` events are reported. *parser* is an optional + parser instance. If not given, the standard :class:`XMLParser` parser is + used. + + .. method:: data_received(data) + + Feed the given bytes data to the incremental parser. + + .. method:: eof_received() + + Signal the incremental parser that the data stream is terminated. + + .. method:: events() + + Iterate over the events which have been encountered in the data fed + to the parser. This method yields ``(event, elem)`` pairs, where + *event* is a string representing the type of event (e.g. ``"end"``) + and *elem* is the encountered :class:`Element` object. + + .. note:: + + :class:`IncrementalParser` only guarantees that it has seen the ">" + character of a starting tag when it emits a "start" event, so the + attributes are defined, but the contents of the text and tail attributes + are undefined at that point. The same applies to the element children; + they may or may not be present. + + If you need a fully populated element, look for "end" events instead. + + .. versionadded:: 3.4 + + .. _elementtree-treebuilder-objects: TreeBuilder Objects diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 75e8fd5..c45c070 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -265,10 +265,8 @@ ZipFile Objects Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of *path*, e.g. members that have absolute filenames starting with ``"/"`` or filenames with two - dots ``".."``. - - .. versionchanged:: 3.3.1 - The zipfile module attempts to prevent that. See :meth:`extract` note. + dots ``".."``. This module attempts to prevent that. + See :meth:`extract` note. .. method:: ZipFile.printdir() diff --git a/Doc/license.rst b/Doc/license.rst index aacfaa1..b09e9a8 100644 --- a/Doc/license.rst +++ b/Doc/license.rst @@ -126,6 +126,8 @@ been GPL-compatible; the table below summarizes the various releases. +----------------+--------------+------------+------------+-----------------+ | 3.3.1 | 3.3.0 | 2013 | PSF | yes | +----------------+--------------+------------+------------+-----------------+ +| 3.4.0 | 3.3.0 | 2014 | PSF | yes | ++----------------+--------------+------------+------------+-----------------+ .. note:: @@ -660,6 +662,25 @@ The :mod:`select` and contains the following notice for the kqueue interface:: SUCH DAMAGE. +SHA-3 +----- + +The module :mod:`_sha3` and :mod:`hashlib` are using the reference +implementation of Keccak. The files at :file:`Modules/_sha3/keccak/` contain +the following note:: + + The Keccak sponge function, designed by Guido Bertoni, Joan Daemen, + Michaël Peeters and Gilles Van Assche. For more information, feedback or + questions, please refer to our website: http://keccak.noekeon.org/ + + Implementation by the designers, + hereby denoted as "the implementer". + + To the extent possible under law, the implementer has waived all copyright + and related or neighboring rights to the source code in this file. + http://creativecommons.org/publicdomain/zero/1.0/ + + strtod and dtoa --------------- diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index d0d0646..c25c767 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -493,14 +493,15 @@ case the parameter's default value is substituted. If a parameter has a default value, all following parameters up until the "``*``" must also have a default value --- this is a syntactic restriction that is not expressed by the grammar. -**Default parameter values are evaluated when the function definition is -executed.** This means that the expression is evaluated once, when the function -is defined, and that the same "pre-computed" value is used for each call. This -is especially important to understand when a default parameter is a mutable -object, such as a list or a dictionary: if the function modifies the object -(e.g. by appending an item to a list), the default value is in effect modified. -This is generally not what was intended. A way around this is to use ``None`` -as the default, and explicitly test for it in the body of the function, e.g.:: +**Default parameter values are evaluated from left to right when the function +definition is executed.** This means that the expression is evaluated once, when +the function is defined, and that the same "pre-computed" value is used for each +call. This is especially important to understand when a default parameter is a +mutable object, such as a list or a dictionary: if the function modifies the +object (e.g. by appending an item to a list), the default value is in effect +modified. This is generally not what was intended. A way around this is to use +``None`` as the default, and explicitly test for it in the body of the function, +e.g.:: def whats_on_the_telly(penguin=None): if penguin is None: diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index e815690..4f9b8b0 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1817,6 +1817,15 @@ through the container; for mappings, :meth:`__iter__` should be the same as considered to be false in a Boolean context. +.. method:: object.__length_hint__(self) + + Called to implement :func:`operator.length_hint`. Should return an estimated + length for the object (which may be greater or less than the actual length). + The length must be an integer ``>=`` 0. This method is purely an + optimization and is never required for correctness. + + .. versionadded:: 3.4 + .. note:: Slicing is done exclusively with the following three methods. A call like :: diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 5874606..4ad4490 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -369,16 +369,18 @@ Loaders must satisfy the following requirements: * The ``__loader__`` attribute must be set to the loader object that loaded the module. This is mostly for introspection and reloading, but can be used for additional loader-specific functionality, for example getting - data associated with a loader. + data associated with a loader. If the attribute is missing or set to ``None`` + then the import machinery will automatically set it **after** the module has + been imported. - * The module's ``__package__`` attribute should be set. Its value must be a + * The module's ``__package__`` attribute must be set. Its value must be a string, but it can be the same value as its ``__name__``. If the attribute is set to ``None`` or is missing, the import system will fill it in with a - more appropriate value. When the module is a package, its ``__package__`` - value should be set to its ``__name__``. When the module is not a package, - ``__package__`` should be set to the empty string for top-level modules, or - for submodules, to the parent package's name. See :pep:`366` for further - details. + more appropriate value **after** the module has been imported. + When the module is a package, its ``__package__`` value should be set to its + ``__name__``. When the module is not a package, ``__package__`` should be + set to the empty string for top-level modules, or for submodules, to the + parent package's name. See :pep:`366` for further details. This attribute is used instead of ``__name__`` to calculate explicit relative imports for main modules, as defined in :pep:`366`. diff --git a/Doc/tools/sphinxext/indexsidebar.html b/Doc/tools/sphinxext/indexsidebar.html index a0ec32f..ed5da0c 100644 --- a/Doc/tools/sphinxext/indexsidebar.html +++ b/Doc/tools/sphinxext/indexsidebar.html @@ -3,7 +3,7 @@ <h3>Docs for other versions</h3> <ul> <li><a href="http://docs.python.org/2.7/">Python 2.7 (stable)</a></li> - <li><a href="http://docs.python.org/3.4/">Python 3.4 (in development)</a></li> + <li><a href="http://docs.python.org/3.3/">Python 3.3 (stable)</a></li> <li><a href="http://www.python.org/doc/versions/">Old versions</a></li> </ul> diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py index e8eb703..df6e48a 100644 --- a/Doc/tools/sphinxext/pyspecific.py +++ b/Doc/tools/sphinxext/pyspecific.py @@ -10,7 +10,7 @@ """ ISSUE_URI = 'http://bugs.python.org/issue%s' -SOURCE_URI = 'http://hg.python.org/cpython/file/3.3/%s' +SOURCE_URI = 'http://hg.python.org/cpython/file/default/%s' from docutils import nodes, utils from sphinx.util.nodes import split_explicit_title diff --git a/Doc/tools/sphinxext/susp-ignored.csv b/Doc/tools/sphinxext/susp-ignored.csv index 72c5255..d951dad 100644 --- a/Doc/tools/sphinxext/susp-ignored.csv +++ b/Doc/tools/sphinxext/susp-ignored.csv @@ -162,17 +162,9 @@ library/os.path,,:foo,c:foo library/pdb,,:lineno,filename:lineno library/pickle,,:memory,"conn = sqlite3.connect("":memory:"")" library/posix,,`,"CFLAGS=""`getconf LFS_CFLAGS`"" OPT=""-g -O2 $CFLAGS""" -library/pprint,209,::,"'classifiers': ['Development Status :: 4 - Beta'," -library/pprint,209,::,"'Intended Audience :: Developers'," -library/pprint,209,::,"'License :: OSI Approved :: MIT License'," -library/pprint,209,::,"'Natural Language :: English'," -library/pprint,209,::,"'Operating System :: OS Independent'," -library/pprint,209,::,"'Programming Language :: Python'," -library/pprint,209,::,"'Programming Language :: Python :: 2'," -library/pprint,209,::,"'Programming Language :: Python :: 2.6'," -library/pprint,209,::,"'Programming Language :: Python :: 2.7'," -library/pprint,209,::,"'Topic :: Software Development :: Libraries'," -library/pprint,209,::,"'Topic :: Software Development :: Libraries :: Python Modules']," +library/pprint,,::,"'Programming Language :: Python :: 2 :: Only']," +library/pprint,,::,"'Programming Language :: Python :: 2.6'," +library/pprint,,::,"'Programming Language :: Python :: 2.7'," library/profile,,:lineno,filename:lineno(function) library/pyexpat,,:elem1,<py:elem1 /> library/pyexpat,,:py,"xmlns:py = ""http://www.python.org/ns/"">" @@ -184,6 +176,7 @@ library/socket,,:len,fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) library/sqlite3,,:age,"cur.execute(""select * from people where name_last=:who and age=:age"", {""who"": who, ""age"": age})" library/sqlite3,,:memory, library/sqlite3,,:who,"cur.execute(""select * from people where name_last=:who and age=:age"", {""who"": who, ""age"": age})" +library/sqlite3,,:path,"db = sqlite3.connect('file:path/to/database?mode=ro', uri=True)" library/ssl,,:My,"Organizational Unit Name (eg, section) []:My Group" library/ssl,,:My,"Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc." library/ssl,,:myserver,"Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com" diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index cdc2bf2..c182511 100644 --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -10,13 +10,13 @@ Using the Python Interpreter Invoking the Interpreter ======================== -The Python interpreter is usually installed as :file:`/usr/local/bin/python3.3` +The Python interpreter is usually installed as :file:`/usr/local/bin/python3.4` on those machines where it is available; putting :file:`/usr/local/bin` in your Unix shell's search path makes it possible to start it by typing the command: .. code-block:: text - python3.3 + python3.4 to the shell. [#]_ Since the choice of the directory where the interpreter lives is an installation option, other places are possible; check with your local @@ -24,11 +24,11 @@ Python guru or system administrator. (E.g., :file:`/usr/local/python` is a popular alternative location.) On Windows machines, the Python installation is usually placed in -:file:`C:\\Python33`, though you can change this when you're running the +:file:`C:\\Python34`, though you can change this when you're running the installer. To add this directory to your path, you can type the following command into the command prompt in a DOS box:: - set path=%path%;C:\python33 + set path=%path%;C:\python34 Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on Windows) at the primary prompt causes the interpreter to exit with a zero exit @@ -95,8 +95,8 @@ with the *secondary prompt*, by default three dots (``...``). The interpreter prints a welcome message stating its version number and a copyright notice before printing the first prompt:: - $ python3.3 - Python 3.3 (default, Sep 24 2012, 09:25:04) + $ python3.4 + Python 3.4 (default, Sep 24 2012, 09:25:04) [GCC 4.6.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> @@ -149,7 +149,7 @@ Executable Python Scripts On BSD'ish Unix systems, Python scripts can be made directly executable, like shell scripts, by putting the line :: - #! /usr/bin/env python3.3 + #! /usr/bin/env python3.4 (assuming that the interpreter is on the user's :envvar:`PATH`) at the beginning of the script and giving the file an executable mode. The ``#!`` must be the diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst index 78fe511..fbcbe52 100644 --- a/Doc/tutorial/modules.rst +++ b/Doc/tutorial/modules.rst @@ -289,24 +289,23 @@ defines. It returns a sorted list of strings:: >>> dir(fibo) ['__name__', 'fib', 'fib2'] >>> dir(sys) # doctest: +NORMALIZE_WHITESPACE - ['__displayhook__', '__doc__', '__egginsert', '__excepthook__', - '__loader__', '__name__', '__package__', '__plen', '__stderr__', - '__stdin__', '__stdout__', '_clear_type_cache', '_current_frames', - '_debugmallocstats', '_getframe', '_home', '_mercurial', '_xoptions', - 'abiflags', 'api_version', 'argv', 'base_exec_prefix', 'base_prefix', - 'builtin_module_names', 'byteorder', 'call_tracing', 'callstats', - 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info', - 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info', - 'float_repr_style', 'getcheckinterval', 'getdefaultencoding', - 'getdlopenflags', 'getfilesystemencoding', 'getobjects', 'getprofile', - 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval', - 'gettotalrefcount', 'gettrace', 'hash_info', 'hexversion', - 'implementation', 'int_info', 'intern', 'maxsize', 'maxunicode', - 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache', - 'platform', 'prefix', 'ps1', 'setcheckinterval', 'setdlopenflags', - 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', - 'stderr', 'stdin', 'stdout', 'thread_info', 'version', 'version_info', - 'warnoptions'] + ['__displayhook__', '__doc__', '__excepthook__', '__loader__', '__name__', + '__package__', '__stderr__', '__stdin__', '__stdout__', + '_clear_type_cache', '_current_frames', '_debugmallocstats', '_getframe', + '_home', '_mercurial', '_xoptions', 'abiflags', 'api_version', 'argv', + 'base_exec_prefix', 'base_prefix', 'builtin_module_names', 'byteorder', + 'call_tracing', 'callstats', 'copyright', 'displayhook', + 'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix', + 'executable', 'exit', 'flags', 'float_info', 'float_repr_style', + 'getcheckinterval', 'getdefaultencoding', 'getdlopenflags', + 'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit', + 'getrefcount', 'getsizeof', 'getswitchinterval', 'gettotalrefcount', + 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info', + 'intern', 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', + 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1', + 'setcheckinterval', 'setdlopenflags', 'setprofile', 'setrecursionlimit', + 'setswitchinterval', 'settrace', 'stderr', 'stdin', 'stdout', + 'thread_info', 'version', 'version_info', 'warnoptions'] Without arguments, :func:`dir` lists the names you have defined currently:: diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index 7e7a154..2e3ed18 100644 --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -15,7 +15,7 @@ operating system:: >>> import os >>> os.getcwd() # Return the current working directory - 'C:\\Python33' + 'C:\\Python34' >>> os.chdir('/server/accesslogs') # Change current working directory >>> os.system('mkdir today') # Run the command mkdir in the system shell 0 diff --git a/Doc/tutorial/stdlib2.rst b/Doc/tutorial/stdlib2.rst index 4b6e036..3b9122f 100644 --- a/Doc/tutorial/stdlib2.rst +++ b/Doc/tutorial/stdlib2.rst @@ -275,7 +275,7 @@ applications include caching objects that are expensive to create:: Traceback (most recent call last): File "<stdin>", line 1, in <module> d['primary'] # entry was automatically removed - File "C:/python33/lib/weakref.py", line 46, in __getitem__ + File "C:/python34/lib/weakref.py", line 46, in __getitem__ o = self.data[key]() KeyError: 'primary' diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index e0c80f6..185852a 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -358,9 +358,14 @@ Miscellaneous options .. cmdoption:: -X Reserved for various implementation-specific options. CPython currently - defines just one, you can use ``-X faulthandler`` to enable - :mod:`faulthandler`. It also allows to pass arbitrary values and retrieve - them through the :data:`sys._xoptions` dictionary. + defines two possible values: + + * ``-X faulthandler`` to enable :mod:`faulthandler`; + * ``-X showrefcount`` to enable the output of the total reference count + and memory blocks (only works on debug builds); + + It also allows to pass arbitrary values and retrieve them through the + :data:`sys._xoptions` dictionary. .. versionchanged:: 3.2 It is now allowed to pass :option:`-X` with CPython. @@ -368,6 +373,9 @@ Miscellaneous options .. versionadded:: 3.3 The ``-X faulthandler`` option. + .. versionadded:: 3.4 + The ``-X showrefcount`` option. + Options you shouldn't use ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 3e1b74d..5be439f 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -25,7 +25,7 @@ there. What you get after installing is a number of things: -* A :file:`MacPython 3.3` folder in your :file:`Applications` folder. In here +* A :file:`MacPython 3.4` folder in your :file:`Applications` folder. In here you find IDLE, the development environment that is a standard part of official Python distributions; PythonLauncher, which handles double-clicking Python scripts from the Finder; and the "Build Applet" tool, which allows you to @@ -93,7 +93,7 @@ aware of: programs that talk to the Aqua window manager (in other words, anything that has a GUI) need to be run in a special way. Use :program:`pythonw` instead of :program:`python` to start such scripts. -With Python 3.3, you can use either :program:`python` or :program:`pythonw`. +With Python 3.4, you can use either :program:`python` or :program:`pythonw`. Configuration @@ -158,7 +158,7 @@ http://www.riverbankcomputing.co.uk/software/pyqt/intro. Distributing Python Applications on the Mac =========================================== -The "Build Applet" tool that is placed in the MacPython 3.3 folder is fine for +The "Build Applet" tool that is placed in the MacPython 3.4 folder is fine for packaging small Python scripts on your own machine to run as a standard Mac application. This tool, however, is not robust enough to distribute Python applications to other users. diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 5fdbc9b..706ac5d 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -56,20 +56,21 @@ virtualenv will be created, according to the given options, at each provided path. Once a venv has been created, it can be "activated" using a script in the -venv's binary directory. The invocation of the script is platform-specific: on -a Posix platform, you would typically do:: - - $ source <venv>/bin/activate - -whereas on Windows, you might do:: - - C:\> <venv>/Scripts/activate - -if you are using the ``cmd.exe`` shell, or perhaps:: - - PS C:\> <venv>/Scripts/Activate.ps1 - -if you use PowerShell. +venv's binary directory. The invocation of the script is platform-specific: + ++-------------+-----------------+-----------------------------------------+ +| Platform | Shell | Command to activate virtual environment | ++=============+=================+=========================================+ +| Posix | bash/zsh | $ source <venv>/bin/activate | ++-------------+-----------------+-----------------------------------------+ +| | fish | $ . <venv>/bin/activate.fish | ++-------------+-----------------+-----------------------------------------+ +| | csh/tcsh | $ source <venv>/bin/activate.csh | ++-------------+-----------------+-----------------------------------------+ +| Windows | cmd.exe | C:\> <venv>/Scripts/activate.bat | ++-------------+-----------------+-----------------------------------------+ +| | PowerShell | PS C:\> <venv>/Scripts/Activate.ps1 | ++-------------+-----------------+-----------------------------------------+ You don't specifically *need* to activate an environment; activation just prepends the venv's binary directory to your path, so that "python" invokes the diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst new file mode 100644 index 0000000..ca515f6 --- /dev/null +++ b/Doc/whatsnew/3.4.rst @@ -0,0 +1,233 @@ +**************************** + What's New In Python 3.4 +**************************** + +.. :Author: Someone <email> + (uncomment if there is a principal author) + +.. Rules for maintenance: + + * Anyone can add text to this document, but the maintainer reserves the + right to rewrite any additions. In particular, for obscure or esoteric + features, the maintainer may reduce any addition to a simple reference to + the new documentation rather than explaining the feature inline. + + * While the maintainer will periodically go through Misc/NEWS + and add changes, it's best not to rely on this. We know from experience + that any changes that aren't in the What's New documentation around the + time of the original release will remain largely unknown to the community + for years, even if they're added later. We also know from experience that + other priorities can arise, and the maintainer will run out of time to do + updates - in such cases, end users will be much better served by partial + notifications that at least give a hint about new features to + investigate. + + * This is not a complete list of every single change; completeness + is the purpose of Misc/NEWS. The What's New should focus on changes that + are visible to Python *users* and that *require* a feature release (i.e. + most bug fixes should only be recorded in Misc/NEWS) + + * PEPs should not be marked Final until they have an entry in What's New. + A placeholder entry that is just a section header and a link to the PEP + (e.g ":pep:`397` has been implemented") is acceptable. If a PEP has been + implemented and noted in What's New, don't forget to mark it as Final! + + * If you want to draw your new text to the attention of the + maintainer, add 'XXX' to the beginning of the paragraph or + section. + + * It's OK to add just a very brief note about a change. For + example: "The :ref:`~socket.transmogrify()` function was added to the + :mod:`socket` module." The maintainer will research the change and + write the necessary text (if appropriate). The advantage of doing this + is that even if no more descriptive text is ever added, readers will at + least have a notification that the new feature exists and a link to the + relevant documentation. + + * You can comment out your additions if you like, but it's not + necessary (especially when a final release is some months away). + + * Credit the author of a patch or bugfix. Just the name is + sufficient; the e-mail address isn't necessary. + + * It's helpful to add the bug/patch number as a comment: + + The :ref:`~socket.transmogrify()` function was added to the + :mod:`socket` module. (Contributed by P.Y. Developer in :issue:`12345`.) + + This saves the maintainer the effort of going through the Mercurial log + when researching a change. + + * Cross referencing tip: :ref:`mod.attr` will display as ``mod.attr``, + while :ref:`~mod.attr` will display as ``attr``. + +This article explains the new features in Python 3.4, compared to 3.3. + +.. Python 3.4 was released on TBD. + +For full details, see the +`changelog <http://docs.python.org/3.4/whatsnew/changelog.html>`_. + +.. note:: Prerelease users should be aware that this document is currently in + draft form. It will be updated substantially as Python 3.4 moves towards + release, so it's worth checking back even after reading earlier versions. + + +.. seealso:: + + .. :pep:`4XX` - Python 3.4 Release Schedule + + +Summary -- Release highlights +============================= + +.. This section singles out the most important changes in Python 3.4. + Brevity is key. + +New syntax features: + +* None yet. + +New library modules: + +* None yet. + +New built-in features: + +* None yet. + +Implementation improvements: + +* A more efficient :mod:`marshal` format <http://bugs.python.org/issue16475>. + +Significantly Improved Library Modules: + +* SHA-3 (Keccak) support for :mod:`hashlib`. +* TLSv1.1 and TLSv1.2 support for :mod:`ssl`. + +Security improvements: + +* None yet. + +Please read on for a comprehensive list of user-facing changes. + + +.. PEP-sized items next. + +.. _pep-4XX: + +.. PEP 4XX: Example PEP +.. ==================== + + +.. (Implemented by Foo Bar.) + +.. .. seealso:: + + :pep:`4XX` - Example PEP + PEP written by Example Author + + + + +Other Language Changes +====================== + +Some smaller changes made to the core Python language are: + +* Unicode database updated to UCD version 6.2. + + + +New Modules +=========== + +.. module name +.. ----------- + +* None yet. + + +Improved Modules +================ + + +doctest +------- + +Added ``FAIL_FAST`` flag to halt test running as soon as the first failure is +detected. (Contributed by R. David Murray and Daniel Urban in :issue:`16522`.) + + +smtplib +------- + +:exc:`~smtplib.SMTPException` is now a subclass of :exc:`OSError`, which allows +both socket level errors and SMTP protocol level errors to be caught in one +try/except statement by code that only cares whether or not an error occurred. +(:issue:`2118`). + + +wave +---- + +The :meth:`~wave.getparams` method now returns a namedtuple rather than a +plain tuple. (Contributed by Claudiu Popa in :issue:`17487`.) + + +Optimizations +============= + +Major performance enhancements have been added: + +* The UTF-32 decoder is now 3x to 4x faster. + + +Build and C API Changes +======================= + +Changes to Python's build process and to the C API include: + +* None yet. + + +Deprecated +========== + +Unsupported Operating Systems +----------------------------- + +* None yet. + + +Deprecated Python modules, functions and methods +------------------------------------------------ + +* :meth:`difflib.SequenceMatcher.isbjunk` and + :meth:`difflib.SequenceMatcher.isbpopulur`: use ``x in sm.bjunk`` and + ``x in sm.bpopular``, where sm is a :class:`~difflib.SequenceMatcher` object. + + +Deprecated functions and types of the C API +------------------------------------------- + +* None yet. + + +Deprecated features +------------------- + +* None yet. + + +Porting to Python 3.4 +===================== + +This section lists previously described changes and other bugfixes +that may require changes to your code. + +* The ABCs defined in :mod:`importlib.abc` now either raise the appropriate + exception or return a default value instead of raising + :exc:`NotImplementedError` blindly. This will only affect code calling + :func:`super` and falling through all the way to the ABCs. For compatibility, + catch both :exc:`NotImplementedError` or the appropriate exception as needed. diff --git a/Doc/whatsnew/index.rst b/Doc/whatsnew/index.rst index bc1206b..29902e4 100644 --- a/Doc/whatsnew/index.rst +++ b/Doc/whatsnew/index.rst @@ -11,6 +11,7 @@ anyone wishing to stay up-to-date after a new release. .. toctree:: :maxdepth: 2 + 3.4.rst 3.3.rst 3.2.rst 3.1.rst |