diff options
Diffstat (limited to 'Doc')
31 files changed, 444 insertions, 174 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 2965bc931a..7d9eefb1ea 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1147,46 +1147,6 @@ Python-level trace functions in previous versions. :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number events. -.. c:function:: PyObject* PyEval_GetCallStats(PyObject *self) - - Return a tuple of function call counts. There are constants defined for the - positions within the tuple: - - +-------------------------------+-------+ - | Name | Value | - +===============================+=======+ - | :const:`PCALL_ALL` | 0 | - +-------------------------------+-------+ - | :const:`PCALL_FUNCTION` | 1 | - +-------------------------------+-------+ - | :const:`PCALL_FAST_FUNCTION` | 2 | - +-------------------------------+-------+ - | :const:`PCALL_FASTER_FUNCTION`| 3 | - +-------------------------------+-------+ - | :const:`PCALL_METHOD` | 4 | - +-------------------------------+-------+ - | :const:`PCALL_BOUND_METHOD` | 5 | - +-------------------------------+-------+ - | :const:`PCALL_CFUNCTION` | 6 | - +-------------------------------+-------+ - | :const:`PCALL_TYPE` | 7 | - +-------------------------------+-------+ - | :const:`PCALL_GENERATOR` | 8 | - +-------------------------------+-------+ - | :const:`PCALL_OTHER` | 9 | - +-------------------------------+-------+ - | :const:`PCALL_POP` | 10 | - +-------------------------------+-------+ - - :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created. - :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used. - - If there is a method call where the call can be optimized by changing - the argument tuple and calling the function directly, it gets recorded - twice. - - This function is only present if Python is compiled with :const:`CALL_PROFILE` - defined. .. _advanced-debugging: diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index b761c808fc..754dedc1c6 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -244,63 +244,82 @@ Object Protocol and ``0`` otherwise. This function always succeeds. -.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw) +.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs) - Call a callable Python object *callable_object*, with arguments given by the - tuple *args*, and named arguments given by the dictionary *kw*. If no named - arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an - empty tuple if no arguments are needed. Returns the result of the call on - success, or *NULL* on failure. This is the equivalent of the Python expression - ``callable_object(*args, **kw)``. + Call a callable Python object *callable*, with arguments given by the + tuple *args*, and named arguments given by the dictionary *kwargs*. + *args* must not be *NULL*, use an empty tuple if no arguments are needed. + If no named arguments are needed, *kwargs* can be *NULL*. -.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args) + Returns the result of the call on success, or *NULL* on failure. - Call a callable Python object *callable_object*, with arguments given by the - tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns - the result of the call on success, or *NULL* on failure. This is the equivalent - of the Python expression ``callable_object(*args)``. + This is the equivalent of the Python expression: + ``callable(*args, **kwargs)``. + + +.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args) + + Call a callable Python object *callable*, with arguments given by the + tuple *args*. If no arguments are needed, then *args* can be *NULL*. + + Returns the result of the call on success, or *NULL* on failure. + + This is the equivalent of the Python expression: ``callable(*args)``. .. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...) Call a callable Python object *callable*, with a variable number of C arguments. The C arguments are described using a :c:func:`Py_BuildValue` style format - string. The format may be *NULL*, indicating that no arguments are provided. - Returns the result of the call on success, or *NULL* on failure. This is the - equivalent of the Python expression ``callable(*args)``. Note that if you only - pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a - faster alternative. + string. The format can be *NULL*, indicating that no arguments are provided. + + Returns the result of the call on success, or *NULL* on failure. + + This is the equivalent of the Python expression: ``callable(*args)``. + + Note that if you only pass :c:type:`PyObject \*` args, + :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative. .. versionchanged:: 3.4 The type of *format* was changed from ``char *``. -.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...) +.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...) - Call the method named *method* of object *o* with a variable number of C + Call the method named *name* of object *obj* with a variable number of C arguments. The C arguments are described by a :c:func:`Py_BuildValue` format - string that should produce a tuple. The format may be *NULL*, indicating that - no arguments are provided. Returns the result of the call on success, or *NULL* - on failure. This is the equivalent of the Python expression ``o.method(args)``. + string that should produce a tuple. + + The format can be *NULL*, indicating that no arguments are provided. + + Returns the result of the call on success, or *NULL* on failure. + + This is the equivalent of the Python expression: + ``obj.name(arg1, arg2, ...)``. + Note that if you only pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallMethodObjArgs` is a faster alternative. .. versionchanged:: 3.4 - The types of *method* and *format* were changed from ``char *``. + The types of *name* and *format* were changed from ``char *``. .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL) Call a callable Python object *callable*, with a variable number of :c:type:`PyObject\*` arguments. The arguments are provided as a variable number - of parameters followed by *NULL*. Returns the result of the call on success, or - *NULL* on failure. + of parameters followed by *NULL*. + + Returns the result of the call on success, or *NULL* on failure. + + This is the equivalent of the Python expression: + ``callable(arg1, arg2, ...)``. -.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL) +.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL) - Calls a method of the object *o*, where the name of the method is given as a + Calls a method of the Python object *obj*, where the name of the method is given as a Python string object in *name*. It is called with a variable number of :c:type:`PyObject\*` arguments. The arguments are provided as a variable number of parameters followed by *NULL*. Returns the result of the call on success, or diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index a825164918..5606ae41a5 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -56,3 +56,40 @@ Slice Objects .. versionchanged:: 3.2 The parameter type for the *slice* parameter was ``PySliceObject*`` before. + + .. versionchanged:: 3.6.1 + If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400`` + and ``0x03060000`` (not including) or ``0x03060100`` or higher + :c:func:`!PySlice_GetIndicesEx` is implemented as a macro using + :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`. + Arguments *start*, *stop* and *step* are evaluated more than once. + + .. deprecated:: 3.6.1 + If ``Py_LIMITED_API`` is set to the value less than ``0x03050400`` or + between ``0x03060000`` and ``0x03060100`` (not including) + :c:func:`!PySlice_GetIndicesEx` is a deprecated function. + + +.. c:function:: int PySlice_Unpack(PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step) + + Extract the start, stop and step data members from a slice object as + C integers. Silently reduce values larger than ``PY_SSIZE_T_MAX`` to + ``PY_SSIZE_T_MAX``, silently boost the start and stop values less than + ``-PY_SSIZE_T_MAX-1`` to ``-PY_SSIZE_T_MAX-1``, and silently boost the step + values less than ``-PY_SSIZE_T_MAX`` to ``-PY_SSIZE_T_MAX``. + + Return ``-1`` on error, ``0`` on success. + + .. versionadded:: 3.6.1 + + +.. c:function:: Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step) + + Adjust start/end slice indices assuming a sequence of the specified length. + Out of bounds indices are clipped in a manner consistent with the handling + of normal slices. + + Return the length of the slice. Always successful. Doesn't call Python + code. + + .. versionadded:: 3.6.1 diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ac6fd0b53f..2f0081aa3d 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -727,11 +727,11 @@ type objects) *must* have the :attr:`ob_size` field. typedef int (*setter)(PyObject *, PyObject *, void *); typedef struct PyGetSetDef { - char *name; /* attribute name */ - getter get; /* C function to get the attribute */ - setter set; /* C function to set or delete the attribute */ - char *doc; /* optional doc string */ - void *closure; /* optional additional data for getter and setter */ + const char *name; /* attribute name */ + getter get; /* C function to get the attribute */ + setter set; /* C function to set or delete the attribute */ + const char *doc; /* optional doc string */ + void *closure; /* optional additional data for getter and setter */ } PyGetSetDef; diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 02f7ada7be..bcae44ef49 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1038,7 +1038,7 @@ These are the UTF-8 codec APIs: raised by the codec. -.. c:function:: char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size) +.. c:function:: const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size) Return a pointer to the UTF-8 encoding of the Unicode object, and store the size of the encoded representation (in bytes) in *size*. The @@ -1055,13 +1055,19 @@ These are the UTF-8 codec APIs: .. versionadded:: 3.3 + .. versionchanged:: 3.7 + The return type is now ``const char *`` rather of ``char *``. -.. c:function:: char* PyUnicode_AsUTF8(PyObject *unicode) + +.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode) As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size. .. versionadded:: 3.3 + .. versionchanged:: 3.7 + The return type is now ``const char *`` rather of ``char *``. + .. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors) @@ -1605,6 +1611,9 @@ They all return *NULL* or ``-1`` if an exception occurs. .. versionadded:: 3.3 + .. versionchanged:: 3.7 + *start* and *end* are now adjusted to behave like ``str[start:end]``. + .. c:function:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, \ Py_ssize_t start, Py_ssize_t end) diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index b8ce437787..118f336ae1 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -1138,11 +1138,11 @@ in the instance. A variety of primitive C types are supported, and access may be read-only or read-write. The structures in the table are defined as:: typedef struct PyMemberDef { - char *name; - int type; - int offset; - int flags; - char *doc; + const char *name; + int type; + int offset; + int flags; + const char *doc; } PyMemberDef; For each entry in the table, a :term:`descriptor` will be constructed and added to the diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index a15690ba48..694d5642fb 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -957,6 +957,28 @@ All of the following opcodes use their arguments. value. +.. opcode:: LOAD_METHOD (namei) + + Loads a method named ``co_names[namei]`` from TOS object. TOS is popped and + method and TOS are pushed when interpreter can call unbound method directly. + TOS will be uesd as the first argument (``self``) by :opcode:`CALL_METHOD`. + Otherwise, ``NULL`` and method is pushed (method is bound method or + something else). + + .. versionadded:: 3.7 + + +.. opcode:: CALL_METHOD (argc) + + Calls a method. *argc* is number of positional arguments. + Keyword arguments are not supported. This opcode is designed to be used + with :opcode:`LOAD_METHOD`. Positional arguments are on top of the stack. + Below them, two items described in :opcode:`LOAD_METHOD` on the stack. + All of them are popped and return value is pushed. + + .. versionadded:: 3.7 + + .. opcode:: MAKE_FUNCTION (argc) Pushes a new function object on the stack. From bottom to top, the consumed diff --git a/Doc/library/http.cookies.rst b/Doc/library/http.cookies.rst index 4b45d4bc38..fb8317ad59 100644 --- a/Doc/library/http.cookies.rst +++ b/Doc/library/http.cookies.rst @@ -148,39 +148,31 @@ Morsel Objects :meth:`~Morsel.__eq__` now takes :attr:`~Morsel.key` and :attr:`~Morsel.value` into account. + .. versionchanged:: 3.7 + Attributes :attr:`~Morsel.key`, :attr:`~Morsel.value` and + :attr:`~Morsel.coded_value` are read-only. Use :meth:`~Morsel.set` for + setting them. + .. attribute:: Morsel.value The value of the cookie. - .. deprecated:: 3.5 - assigning to ``value``; use :meth:`~Morsel.set` instead. - .. attribute:: Morsel.coded_value The encoded value of the cookie --- this is what should be sent. - .. deprecated:: 3.5 - assigning to ``coded_value``; use :meth:`~Morsel.set` instead. - .. attribute:: Morsel.key The name of the cookie. - .. deprecated:: 3.5 - assigning to ``key``; use :meth:`~Morsel.set` instead. - .. method:: Morsel.set(key, value, coded_value) Set the *key*, *value* and *coded_value* attributes. - .. deprecated:: 3.5 - The undocumented *LegalChars* parameter is ignored and will be removed in - a future version. - .. method:: Morsel.isReservedKey(K) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 4da6e095d1..c8ff5b826d 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -477,7 +477,7 @@ I/O Base Classes A :exc:`BlockingIOError` is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment. - .. method:: read1(size=-1) + .. method:: read1([size]) Read and return up to *size* bytes, with at most one call to the underlying raw stream's :meth:`~RawIOBase.read` (or @@ -485,6 +485,9 @@ I/O Base Classes implementing your own buffering on top of a :class:`BufferedIOBase` object. + If *size* is ``-1`` (the default), an arbitrary number of bytes are + returned (more than zero unless EOF is reached). + .. method:: readinto(b) Read bytes into a pre-allocated, writable @@ -628,13 +631,16 @@ than raw I/O does. Return :class:`bytes` containing the entire contents of the buffer. - .. method:: read1() + .. method:: read1([size]) + + In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.read`. - In :class:`BytesIO`, this is the same as :meth:`read`. + .. versionchanged:: 3.7 + The *size* argument is now optional. - .. method:: readinto1() + .. method:: readinto1(b) - In :class:`BytesIO`, this is the same as :meth:`readinto`. + In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.readinto`. .. versionadded:: 3.5 @@ -664,12 +670,15 @@ than raw I/O does. Read and return *size* bytes, or if *size* is not given or negative, until EOF or if the read call would block in non-blocking mode. - .. method:: read1(size) + .. method:: read1([size]) Read and return up to *size* bytes with only one call on the raw stream. If at least one byte is buffered, only buffered bytes are returned. Otherwise, one raw stream read call is made. + .. versionchanged:: 3.7 + The *size* argument is now optional. + .. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 6098878c1a..d03cc50d87 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1023,7 +1023,7 @@ functions. handlers being added multiple times to the root logger, which can in turn lead to multiple messages for the same event. -.. function:: disable(lvl) +.. function:: disable(lvl=CRITICAL) Provides an overriding level *lvl* for all loggers which takes precedence over the logger's own level. When the need arises to temporarily throttle logging @@ -1036,6 +1036,14 @@ functions. overriding level, so that logging output again depends on the effective levels of individual loggers. + Note that if you have defined any custom logging level higher than + ``CRITICAL`` (this is not recommended), you won't be able to rely on the + default value for the *lvl* parameter, but will have to explicitly supply a + suitable value. + + .. versionchanged:: 3.7 + The *lvl* parameter was defaulted to level ``CRITICAL``. See Issue + #28524 for more information about this change. .. function:: addLevelName(lvl, levelName) diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 406054e5d7..38a9331577 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -453,19 +453,6 @@ the :mod:`glob` module.) Accepts a :term:`path-like object`. -.. function:: splitunc(path) - - .. deprecated:: 3.1 - Use *splitdrive* instead. - - Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC - mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of - the path (such as ``r'\path\file.ext'``). For paths containing drive letters, - *unc* will always be the empty string. - - Availability: Windows. - - .. data:: supports_unicode_filenames ``True`` if arbitrary Unicode strings can be used as file names (within limitations diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 7ef4cbeee7..adf3ddde23 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -761,9 +761,9 @@ form. Unknown escapes in *pattern* consisting of ``'\'`` and an ASCII letter now are errors. - .. deprecated-removed:: 3.5 3.7 - Unknown escapes in *repl* consisting of ``'\'`` and an ASCII letter now raise - a deprecation warning and will be forbidden in Python 3.7. + .. versionchanged:: 3.7 + Unknown escapes in *repl* consisting of ``'\'`` and an ASCII letter + now are errors. .. function:: subn(pattern, repl, string, count=0, flags=0) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 678e32ce57..d56caf0a58 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -664,6 +664,12 @@ The :mod:`socket` module also offers various network-related services: where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 2-byte swap operation. + .. deprecated:: 3.7 + In case *x* does not fit in 16-bit unsigned integer, but does fit in a + positive C int, it is silently truncated to 16-bit unsigned integer. + This silent truncation feature is deprecated, and will raise an + exception in future versions of Python. + .. function:: htonl(x) @@ -678,6 +684,12 @@ The :mod:`socket` module also offers various network-related services: where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 2-byte swap operation. + .. deprecated:: 3.7 + In case *x* does not fit in 16-bit unsigned integer, but does fit in a + positive C int, it is silently truncated to 16-bit unsigned integer. + This silent truncation feature is deprecated, and will raise an + exception in future versions of Python. + .. function:: inet_aton(ip_string) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 9a4f42caa4..d13fc3d920 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2316,11 +2316,15 @@ the bytes type has an additional class method to read data in that format: This :class:`bytes` class method returns a bytes object, decoding the given string object. The string must contain two hexadecimal digits per - byte, with ASCII spaces being ignored. + byte, with ASCII whitespace being ignored. >>> bytes.fromhex('2Ef0 F1f2 ') b'.\xf0\xf1\xf2' + .. versionchanged:: 3.7 + :meth:`bytes.fromhex` now skips all ASCII whitespace in the string, + not just spaces. + A reverse conversion function exists to transform a bytes object into its hexadecimal representation. @@ -2384,11 +2388,15 @@ the bytearray type has an additional class method to read data in that format: This :class:`bytearray` class method returns bytearray object, decoding the given string object. The string must contain two hexadecimal digits - per byte, with ASCII spaces being ignored. + per byte, with ASCII whitespace being ignored. >>> bytearray.fromhex('2Ef0 F1f2 ') bytearray(b'.\xf0\xf1\xf2') + .. versionchanged:: 3.7 + :meth:`bytearray.fromhex` now skips all ASCII whitespace in the string, + not just spaces. + A reverse conversion function exists to transform a bytearray object into its hexadecimal representation. diff --git a/Doc/library/string.rst b/Doc/library/string.rst index a0977b6461..03eaf3b9cd 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -95,9 +95,9 @@ implementation as the built-in :meth:`~str.format` method. an arbitrary set of positional and keyword arguments. It is just a wrapper that calls :meth:`vformat`. - .. deprecated:: 3.5 - Passing a format string as keyword argument *format_string* has been - deprecated. + .. versionchanged:: 3.7 + A format string argument is now :ref:`positional-only + <positional-only_parameter>`. .. method:: vformat(format_string, args, kwargs) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index ad2abe8245..ea065b897e 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -608,12 +608,6 @@ Instances of the :class:`Popen` class have the following methods: .. versionchanged:: 3.3 *timeout* was added. - .. deprecated:: 3.4 - - Do not use the *endtime* parameter. It is was unintentionally - exposed in 3.3 but was left undocumented as it was intended to be - private for internal use. Use *timeout* instead. - .. method:: Popen.communicate(input=None, timeout=None) Interact with process: Send data to stdin. Read data from stdout and stderr, diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index dd51ffd56c..54b99e0fd9 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -404,6 +404,15 @@ always available. .. versionadded:: 3.4 +.. function:: getandroidapilevel() + + Return the build time API version of Android as an integer. + + Availability: Android. + + .. versionadded:: 3.7 + + .. function:: getcheckinterval() Return the interpreter's "check interval"; see :func:`setcheckinterval`. diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index d8f809753d..2167f32f6a 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -429,16 +429,13 @@ be finalized; only the internally used file object will be closed. See the Return an :class:`io.BufferedReader` object. -.. method:: TarFile.add(name, arcname=None, recursive=True, exclude=None, *, filter=None) +.. method:: TarFile.add(name, arcname=None, recursive=True, *, filter=None) Add the file *name* to the archive. *name* may be any type of file (directory, fifo, symbolic link, etc.). If given, *arcname* specifies an alternative name for the file in the archive. Directories are added recursively by default. This can be avoided by setting *recursive* to - :const:`False`. If *exclude* is given, it must be a function that takes one - filename argument and returns a boolean value. Depending on this value the - respective file is either excluded (:const:`True`) or added - (:const:`False`). If *filter* is specified it must be a keyword argument. It + :const:`False`. If *filter* is given, it should be a function that takes a :class:`TarInfo` object argument and returns the changed :class:`TarInfo` object. If it instead returns :const:`None` the :class:`TarInfo` object will be excluded from the @@ -447,10 +444,6 @@ be finalized; only the internally used file object will be closed. See the .. versionchanged:: 3.2 Added the *filter* parameter. - .. deprecated:: 3.2 - The *exclude* parameter is deprecated, please use the *filter* parameter - instead. - .. method:: TarFile.addfile(tarinfo, fileobj=None) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index ae17f6f4f0..6ef02b7403 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -594,8 +594,13 @@ The module defines the following functions and data items: .. function:: tzset() - Resets the time conversion rules used by the library routines. The environment - variable :envvar:`TZ` specifies how this is done. + Reset the time conversion rules used by the library routines. The environment + variable :envvar:`TZ` specifies how this is done. It will also set the variables + ``tzname`` (from the :envvar:`TZ` environment variable), ``timezone`` (non-DST + seconds West of UTC), ``altzone`` (DST seconds west of UTC) and ``daylight`` + (to 0 if this timezone does not have any daylight saving time rules, or to + nonzero if there is a time, past, present or future when daylight saving time + applies). Availability: Unix. diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index 3b772765ac..4065808854 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -28,11 +28,11 @@ can be used to compare three different expressions: .. code-block:: sh $ python3 -m timeit '"-".join(str(n) for n in range(100))' - 10000 loops, best of 3: 30.2 usec per loop + 10000 loops, best of 5: 30.2 usec per loop $ python3 -m timeit '"-".join([str(n) for n in range(100)])' - 10000 loops, best of 3: 27.5 usec per loop + 10000 loops, best of 5: 27.5 usec per loop $ python3 -m timeit '"-".join(map(str, range(100)))' - 10000 loops, best of 3: 23.2 usec per loop + 10000 loops, best of 5: 23.2 usec per loop This can be achieved from the :ref:`python-interface` with:: @@ -141,9 +141,8 @@ The module defines three convenience functions and a public class: This is a convenience function that calls :meth:`.timeit` repeatedly so that the total time >= 0.2 second, returning the eventual (number of loops, time taken for that number of loops). It calls - :meth:`.timeit` with *number* set to successive powers of ten (10, - 100, 1000, ...) up to a maximum of one billion, until the time taken - is at least 0.2 second, or the maximum is reached. + :meth:`.timeit` with increasing numbers from the sequence 1, 2, 5, + 10, 20, 50, ... until the time taken is at least 0.2 second. If *callback* is given and is not ``None``, it will be called after each trial with two arguments: ``callback(number, time_taken)``. @@ -197,7 +196,7 @@ Command-Line Interface When called as a program from the command line, the following form is used:: - python -m timeit [-n N] [-r N] [-u U] [-s S] [-t] [-c] [-h] [statement ...] + python -m timeit [-n N] [-r N] [-u U] [-s S] [-h] [statement ...] Where the following options are understood: @@ -222,20 +221,12 @@ Where the following options are understood: .. versionadded:: 3.3 -.. cmdoption:: -t, --time - - use :func:`time.time` (deprecated) - .. cmdoption:: -u, --unit=U - specify a time unit for timer output; can select usec, msec, or sec + specify a time unit for timer output; can select nsec, usec, msec, or sec .. versionadded:: 3.5 -.. cmdoption:: -c, --clock - - use :func:`time.clock` (deprecated) - .. cmdoption:: -v, --verbose print raw timing results; repeat for more digits precision @@ -276,9 +267,9 @@ It is possible to provide a setup statement that is executed only once at the be .. code-block:: sh $ python -m timeit -s 'text = "sample string"; char = "g"' 'char in text' - 10000000 loops, best of 3: 0.0877 usec per loop + 5000000 loops, best of 5: 0.0877 usec per loop $ python -m timeit -s 'text = "sample string"; char = "g"' 'text.find(char)' - 1000000 loops, best of 3: 0.342 usec per loop + 1000000 loops, best of 5: 0.342 usec per loop :: @@ -305,14 +296,14 @@ to test for missing and present object attributes: .. code-block:: sh $ python -m timeit 'try:' ' str.__bool__' 'except AttributeError:' ' pass' - 100000 loops, best of 3: 15.7 usec per loop + 20000 loops, best of 5: 15.7 usec per loop $ python -m timeit 'if hasattr(str, "__bool__"): pass' - 100000 loops, best of 3: 4.26 usec per loop + 50000 loops, best of 5: 4.26 usec per loop $ python -m timeit 'try:' ' int.__bool__' 'except AttributeError:' ' pass' - 1000000 loops, best of 3: 1.43 usec per loop + 200000 loops, best of 5: 1.43 usec per loop $ python -m timeit 'if hasattr(int, "__bool__"): pass' - 100000 loops, best of 3: 2.23 usec per loop + 100000 loops, best of 5: 2.23 usec per loop :: diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 0c5619c713..2602e3cf76 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -132,6 +132,29 @@ Standard names are defined for the following types: C".) +.. data:: SlotWrapperType + + The type of methods of some built-in data types and base classes such as + :meth:`object.__init__` or :meth:`object.__lt__`. + + .. versionadded:: 3.7 + + +.. data:: MethodWrapperType + + The type of *bound* methods of some built-in data types and base classes. + For example it is the type of :code:`object().__str__`. + + .. versionadded:: 3.7 + + +.. data:: MethodDescriptorType + + The type of methods of some built-in data types such as :meth:`str.join`. + + .. versionadded:: 3.7 + + .. class:: ModuleType(name, doc=None) The type of :term:`modules <module>`. Constructor takes the name of the diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index c6d0ec92b6..ca5c2bc787 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -1831,8 +1831,9 @@ sentinel the same attribute will always return the same object. The objects returned have a sensible repr so that test failure messages are readable. - The ``sentinel`` attributes don't preserve their identity when they are - :mod:`copied <copy>` or :mod:`pickled <pickle>`. + .. versionchanged:: 3.7 + The ``sentinel`` attributes now preserve their identity when they are + :mod:`copied <copy>` or :mod:`pickled <pickle>`. Sometimes when testing you need to test that a specific object is passed as an argument to another method, or returned. It can be common to create named diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 5eb6f10338..a0de10cae3 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -672,18 +672,22 @@ Command-line options ~~~~~~~~~~~~~~~~~~~~ .. cmdoption:: -l <zipfile> + --list <zipfile> List files in a zipfile. .. cmdoption:: -c <zipfile> <source1> ... <sourceN> + --create <zipfile> <source1> ... <sourceN> Create zipfile from source files. .. cmdoption:: -e <zipfile> <output_dir> + --extract <zipfile> <output_dir> Extract zipfile into target directory. .. cmdoption:: -t <zipfile> + --test <zipfile> Test whether the zipfile is valid or not. diff --git a/Doc/tools/extensions/patchlevel.py b/Doc/tools/extensions/patchlevel.py index 919ba4a12e..617f28c252 100644 --- a/Doc/tools/extensions/patchlevel.py +++ b/Doc/tools/extensions/patchlevel.py @@ -24,15 +24,12 @@ def get_header_version_info(srcdir): rx = re.compile(r'\s*#define\s+([a-zA-Z][a-zA-Z_0-9]*)\s+([a-zA-Z_0-9]+)') d = {} - f = open(patchlevel_h) - try: + with open(patchlevel_h) as f: for line in f: m = rx.match(line) if m is not None: name, value = m.group(1, 2) d[name] = value - finally: - f.close() release = version = '%s.%s' % (d['PY_MAJOR_VERSION'], d['PY_MINOR_VERSION']) micro = int(d['PY_MICRO_VERSION']) diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv index c6e03119ae..51edb66238 100644 --- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -324,6 +324,5 @@ whatsnew/3.5,,::,>>> addr6 = ipaddress.IPv6Address('::1') whatsnew/3.5,,:root,ERROR:root:exception whatsnew/3.5,,:exception,ERROR:root:exception whatsnew/changelog,,:version,import sys; I = version[:version.index(' ')] -whatsnew/changelog,,:gz,": TarFile opened with external fileobj and ""w:gz"" mode didn't" -whatsnew/changelog,,::,": Use ""127.0.0.1"" or ""::1"" instead of ""localhost"" as much as" whatsnew/changelog,,`,"for readability (was ""`"")." +whatsnew/changelog,,:end,str[start:end] diff --git a/Doc/tools/templates/indexsidebar.html b/Doc/tools/templates/indexsidebar.html index 413c0a7699..72a4d7ae99 100644 --- a/Doc/tools/templates/indexsidebar.html +++ b/Doc/tools/templates/indexsidebar.html @@ -4,7 +4,7 @@ <ul> <li><a href="https://docs.python.org/2.7/">{% trans %}Python 2.7 (stable){% endtrans %}</a></li> <li><a href="https://docs.python.org/3.5/">{% trans %}Python 3.5 (stable){% endtrans %}</a></li> - <li><a href="https://docs.python.org/3.7/">{% trans %}Python 3.7 (in development){% endtrans %}</a></li> + <li><a href="https://docs.python.org/3.6/">{% trans %}Python 3.6 (stable){% endtrans %}</a></li> <li><a href="https://www.python.org/doc/versions/">{% trans %}Old versions{% endtrans %}</a></li> </ul> diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index faf57a344c..c97f5d88c2 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.6` +The Python interpreter is usually installed as :file:`/usr/local/bin/python3.7` 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.6 + python3.7 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 @@ -98,8 +98,8 @@ before printing the first prompt: .. code-block:: shell-session - $ python3.6 - Python 3.6 (default, Sep 16 2015, 09:25:04) + $ python3.7 + Python 3.7 (default, Sep 16 2015, 09:25:04) [GCC 4.8.2] on linux Type "help", "copyright", "credits" or "license" for more information. >>> diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index 1dd06c2338..6ac29fc602 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:\\Python36' + 'C:\\Python37' >>> 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 bf02c71b6a..99472314ea 100644 --- a/Doc/tutorial/stdlib2.rst +++ b/Doc/tutorial/stdlib2.rst @@ -278,7 +278,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:/python36/lib/weakref.py", line 46, in __getitem__ + File "C:/python37/lib/weakref.py", line 46, in __getitem__ o = self.data[key]() KeyError: 'primary' diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst new file mode 100644 index 0000000000..81ad4f9245 --- /dev/null +++ b/Doc/whatsnew/3.7.rst @@ -0,0 +1,190 @@ +**************************** + What's New In Python 3.7 +**************************** + +:Release: |release| +:Date: |today| + +.. Rules for maintenance: + + * Anyone can add text to this document. Do not spend very much time + on the wording of your changes, because your text will probably + get rewritten to some degree. + + * The maintainer will go through Misc/NEWS periodically and add + changes; it's therefore more important to add your changes to + Misc/NEWS than to this file. + + * This is not a complete list of every single change; completeness + is the purpose of Misc/NEWS. Some changes I consider too small + or esoteric to include. If such a change is added to the text, + I'll just remove it. (This is another reason you shouldn't spend + too much time on writing your addition.) + + * 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 just add a fragmentary note about a change. For + example: "XXX Describe the transmogrify() function added to the + socket module." The maintainer will research the change and + write the necessary text. + + * 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: + + XXX Describe the transmogrify() function added to the 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. + +This article explains the new features in Python 3.7, compared to 3.6. + +For full details, see the :ref:`changelog <changelog>`. + +.. note:: + + Prerelease users should be aware that this document is currently in draft + form. It will be updated substantially as Python 3.7 moves towards release, + so it's worth checking back even after reading earlier versions. + + +Summary -- Release highlights +============================= + +.. This section singles out the most important changes in Python 3.7. + Brevity is key. + + +.. PEP-sized items next. + + + +New Features +============ + + + +Other Language Changes +====================== + +* More than 255 arguments can now be passed to a function, and a function can + now have more than 255 parameters. + (Contributed by Serhiy Storchaka in :issue:`12844` and :issue:`18896`.) + +* :meth:`bytes.fromhex` and :meth:`bytearray.fromhex` now ignore all ASCII + whitespace, not only spaces. + (Contributed by Robert Xiao in :issue:`28927`.) + + +New Modules +=========== + +* None yet. + + +Improved Modules +================ + +unittest.mock +------------- + +The :const:`~unittest.mock.sentinel` attributes now preserve their identity +when they are :mod:`copied <copy>` or :mod:`pickled <pickle>`. +(Contributed by Serhiy Storchaka in :issue:`20804`.) + + +Optimizations +============= + +* Added two new opcodes: ``LOAD_METHOD`` and ``CALL_METHOD`` to avoid + instantiation of bound method objects for method calls, which results + in method calls being faster up to 20%. + (Contributed by Yury Selivanov and INADA Naoki in :issue:`26110`.) + + +Build and C API Changes +======================= + +* A full copy of libffi is no longer bundled for use when building the + :mod:`_ctypes <ctypes>` module on non-OSX UNIX platforms. An installed copy + of libffi is now required when building ``_ctypes`` on such platforms. + Contributed by Zachary Ware in :issue:`27979`. + +* The fields :c:member:`name` and :c:member:`doc` of structures + :c:type:`PyMemberDef`, :c:type:`PyGetSetDef`, + :c:type:`PyStructSequence_Field`, :c:type:`PyStructSequence_Desc`, + and :c:type:`wrapperbase` are now of type ``const char *`` rather of + ``char *``. (Contributed by Serhiy Storchaka in :issue:`28761`.) + +* The result of :c:func:`PyUnicode_AsUTF8AndSize` and :c:func:`PyUnicode_AsUTF8` + is now of type ``const char *`` rather of ``char *``. + (Contributed by Serhiy Storchaka in :issue:`28769`.) + +* Added functions :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`. + (Contributed by Serhiy Storchaka in :issue:`27867`.) + + +Deprecated +========== + +- Function :c:func:`PySlice_GetIndicesEx` is deprecated and replaced with + a macro if ``Py_LIMITED_API`` is not set or set to the value between + ``0x03050400`` and ``0x03060000`` (not including) or ``0x03060100`` or + higher. (Contributed by Serhiy Storchaka in :issue:`27867`.) + + +Removed +======= + +API and Feature Removals +------------------------ + +* Unknown escapes consisting of ``'\'`` and an ASCII letter in replacement + templates for :func:`re.sub` were deprecated in Python 3.5, and will now + cause an error. + +* Removed support of the *exclude* argument in :meth:`tarfile.TarFile.add`. + It was deprecated in Python 2.7 and 3.2. Use the *filter* argument instead. + +* The ``splitunc()`` function in the :mod:`ntpath` module was deprecated in + Python 3.1, and has now been removed. Use the :func:`~os.path.splitdrive` + function instead. + + +Porting to Python 3.7 +===================== + +This section lists previously described changes and other bugfixes +that may require changes to your code. + + +Changes in the Python API +------------------------- + +* A format string argument for :meth:`string.Formatter.format` + is now :ref:`positional-only <positional-only_parameter>`. + Passing it as a keyword argument was deprecated in Python 3.5. + (Contributed by Serhiy Storchaka in :issue:`29193`.) + +* Attributes :attr:`~http.cookies.Morsel.key`, + :attr:`~http.cookies.Morsel.value` and + :attr:`~http.cookies.Morsel.coded_value` of class + :class:`http.cookies.Morsel` are now read-only. + Assigning to them was deprecated in Python 3.5. + Use the :meth:`~http.cookies.Morsel.set` method for setting them. + (Contributed by Serhiy Storchaka in :issue:`29192`.) + + +CPython bytecode changes +------------------------ + +* Added two new opcodes: :opcode:`LOAD_METHOD` and :opcode:`CALL_METHOD`. + (Contributed by Yury Selivanov and INADA Naoki in :issue:`26110`.) diff --git a/Doc/whatsnew/index.rst b/Doc/whatsnew/index.rst index 7c9252401e..160b364a4b 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.7.rst 3.6.rst 3.5.rst 3.4.rst |