diff options
Diffstat (limited to 'Doc')
37 files changed, 533 insertions, 259 deletions
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/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 92af0ec..b336a4a 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 d07aaa1..b324aa6 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -343,6 +343,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/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 4611689..0b59744 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -252,6 +252,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/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 bc8ab2c..4f5aac9 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.server.rst b/Doc/library/http.server.rst index cbad3ed..0577d5e 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -177,6 +177,9 @@ of which this module provides three different variants: 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. + .. method:: send_response(code, message=None) Adds a response header to the headers buffer and logs the accepted diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 083656e..ee9045b 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -132,8 +132,6 @@ ABC hierarchy:: +-- ExecutionLoader --+ +-- FileLoader +-- SourceLoader - +-- PyLoader (deprecated) - +-- PyPycLoader (deprecated) .. class:: Finder @@ -366,10 +364,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 @@ -409,6 +409,17 @@ ABC hierarchy:: When writing to the path fails because the path is read-only (:attr:`errno.EACCES`), do not propagate the exception. + .. 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 +441,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 ------------------------------------------------------ diff --git a/Doc/library/json.rst b/Doc/library/json.rst index bdb6436..25a3358 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 @@ -156,15 +155,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`. @@ -400,15 +397,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/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 aed9cf8..debfb10 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -37,7 +37,6 @@ applications should use string objects to access all files. * :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) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 722f7da..a82b401 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 diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst index 01f680e..1ac93c9 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/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/shutil.rst b/Doc/library/shutil.rst index 080c923..b2efcbd 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 diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 73914e3..5e2b371 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -839,8 +839,6 @@ always available. Windows ``'win32'`` Windows/Cygwin ``'cygwin'`` Mac OS X ``'darwin'`` - OS/2 ``'os2'`` - OS/2 EMX ``'os2emx'`` ================ =========================== .. versionchanged:: 3.3 @@ -1119,7 +1117,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/unicodedata.rst b/Doc/library/unicodedata.rst index 3787c36..d05142a 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" diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index 21255e5..65637fd 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -121,7 +121,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. @@ -346,6 +346,11 @@ The following classes are provided: Open local files. +.. class:: DataHandler() + + Open data URLs. + + .. versionadded:: 3.4 .. class:: FTPHandler() @@ -403,6 +408,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 @@ -451,6 +460,12 @@ request. unredirected). +.. method:: Request.remove_header(header) + + Remove named header from the request instance (both from regular and + unredirected headers). + + .. method:: Request.get_full_url() Return the URL given in the constructor. @@ -972,6 +987,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 @@ -1374,7 +1404,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 2499962..b2ecd93 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/weakref.rst b/Doc/library/weakref.rst index 224f442..1bf6b58 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -192,6 +192,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. diff --git a/Doc/license.rst b/Doc/license.rst index 6326ce4..e56ca5b 100644 --- a/Doc/license.rst +++ b/Doc/license.rst @@ -122,6 +122,8 @@ been GPL-compatible; the table below summarizes the various releases. +----------------+--------------+------------+------------+-----------------+ | 3.3.0 | 3.2 | 2012 | PSF | yes | +----------------+--------------+------------+------------+-----------------+ +| 3.4.0 | 3.3.0 | 2014 | PSF | yes | ++----------------+--------------+------------+------------+-----------------+ .. note:: @@ -656,6 +658,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/datamodel.rst b/Doc/reference/datamodel.rst index 7c51068..9a39eb4 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1815,6 +1815,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/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/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 c4d86ac..3a3283d 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 1ebf792..cb892fd 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/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..ab0b163 --- /dev/null +++ b/Doc/whatsnew/3.4.rst @@ -0,0 +1,209 @@ +**************************** + 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.3. + Brevity is key. + +New syntax features: + +* None yet. + +New library modules: + +* None yet. + +New built-in features: + +* None yet. + +Implementation improvements: + +* None yet. + +Significantly Improved Library Modules: + +* SHA-3 (Keccak) support for :mod:`hashlib`. + +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`.) + + +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 +------------------------------------------------ + +* None yet. + + +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. + +* Nothing yet. 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 |