diff options
Diffstat (limited to 'Doc/library/functions.rst')
| -rw-r--r-- | Doc/library/functions.rst | 76 |
1 files changed, 54 insertions, 22 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 7ed25c1..2b37069 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -540,8 +540,13 @@ are always available. They are listed here in alphabetical order. A call to ``format(value, format_spec)`` is translated to ``type(value).__format__(format_spec)`` which bypasses the instance dictionary when searching for the value's :meth:`__format__` method. A - :exc:`TypeError` exception is raised if the method is not found or if either - the *format_spec* or the return value are not strings. + :exc:`TypeError` exception is raised if the method search reaches + :mod:`object` and the *format_spec* is non-empty, or if either the + *format_spec* or the return value are not strings. + + .. versionchanged:: 3.4 + ``object().__format__(format_spec)`` raises :exc:`TypeError` + if *format_spec* is not an empty string. .. _func-frozenset: @@ -605,6 +610,10 @@ are always available. They are listed here in alphabetical order. This function is added to the built-in namespace by the :mod:`site` module. + .. versionchanged:: 3.4 + Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported + signatures for callables are now more comprehensive and consistent. + .. function:: hex(x) @@ -676,6 +685,12 @@ are always available. They are listed here in alphabetical order. The integer type is described in :ref:`typesnumeric`. + .. versionchanged:: 3.4 + If *base* is not an instance of :class:`int` and the *base* object has a + :meth:`base.__index__ <object.__index__>` method, that method is called + to obtain an integer for the base. Previous versions used + :meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__ + <object.__index__>`. .. function:: isinstance(object, classinfo) @@ -758,25 +773,31 @@ are always available. They are listed here in alphabetical order. already arranged into argument tuples, see :func:`itertools.starmap`\. -.. function:: max(iterable, *[, key]) +.. function:: max(iterable, *[, default, key]) max(arg1, arg2, *args[, key]) Return the largest item in an iterable or the largest of two or more arguments. - If one positional argument is provided, *iterable* must be a non-empty - iterable (such as a non-empty string, tuple or list). The largest item - in the iterable is returned. If two or more positional arguments are - provided, the largest of the positional arguments is returned. + If one positional argument is provided, it should be an :term:`iterable`. + The largest item in the iterable is returned. If two or more positional + arguments are provided, the smallest of the positional arguments is + returned. - The optional keyword-only *key* argument specifies a one-argument ordering - function like that used for :meth:`list.sort`. + There are two optional keyword-only arguments. The *key* argument specifies + a one-argument ordering function like that used for :meth:`list.sort`. The + *default* argument specifies an object to return if the provided iterable is + empty. If the iterable is empty and *default* is not provided, a + :exc:`ValueError` is raised. If multiple items are maximal, the function returns the first one encountered. This is consistent with other sort-stability preserving tools such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and ``heapq.nlargest(1, iterable, key=keyfunc)``. + .. versionadded:: 3.4 + The *default* keyword-only argument. + .. _func-memoryview: .. function:: memoryview(obj) @@ -786,25 +807,31 @@ are always available. They are listed here in alphabetical order. :ref:`typememoryview` for more information. -.. function:: min(iterable, *[, key]) +.. function:: min(iterable, *[, default, key]) min(arg1, arg2, *args[, key]) Return the smallest item in an iterable or the smallest of two or more arguments. - If one positional argument is provided, *iterable* must be a non-empty - iterable (such as a non-empty string, tuple or list). The smallest item - in the iterable is returned. If two or more positional arguments are - provided, the smallest of the positional arguments is returned. + If one positional argument is provided, it should be an :term:`iterable`. + The smallest item in the iterable is returned. If two or more positional + arguments are provided, the smallest of the positional arguments is + returned. - The optional keyword-only *key* argument specifies a one-argument ordering - function like that used for :meth:`list.sort`. + There are two optional keyword-only arguments. The *key* argument specifies + a one-argument ordering function like that used for :meth:`list.sort`. The + *default* argument specifies an object to return if the provided iterable is + empty. If the iterable is empty and *default* is not provided, a + :exc:`ValueError` is raised. If multiple items are minimal, the function returns the first one encountered. This is consistent with other sort-stability preserving tools such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1, iterable, key=keyfunc)``. + .. versionadded:: 3.4 + The *default* keyword-only argument. + .. function:: next(iterator[, default]) Retrieve the next item from the *iterator* by calling its @@ -866,8 +893,7 @@ are always available. They are listed here in alphabetical order. ``'b'`` binary mode ``'t'`` text mode (default) ``'+'`` open a disk file for updating (reading and writing) - ``'U'`` universal newlines mode (for backwards compatibility; should - not be used in new code) + ``'U'`` :term:`universal newlines` mode (deprecated) ========= =============================================================== The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``). @@ -973,6 +999,8 @@ are always available. They are listed here in alphabetical order. :mod:`os.open` as *opener* results in functionality similar to passing ``None``). + The newly created file is :ref:`non-inheritable <fd_inheritance>`. + The following example uses the :ref:`dir_fd <dir_fd>` parameter of the :func:`os.open` function to open a file relative to a given directory:: @@ -986,10 +1014,6 @@ are always available. They are listed here in alphabetical order. ... >>> os.close(dir_fd) # don't leak a file descriptor - .. versionchanged:: 3.3 - The *opener* parameter was added. - The ``'x'`` mode was added. - The type of :term:`file object` returned by the :func:`open` function depends on the mode. When :func:`open` is used to open a file in a text mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of @@ -1016,10 +1040,18 @@ are always available. They are listed here in alphabetical order. and :mod:`shutil`. .. versionchanged:: 3.3 + The *opener* parameter was added. + The ``'x'`` mode was added. :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`. :exc:`FileExistsError` is now raised if the file opened in exclusive creation mode (``'x'``) already exists. + .. versionchanged:: 3.4 + The file is now non-inheritable. + + .. deprecated-removed:: 3.4 4.0 + The ``'U'`` mode. + .. XXX works for bytes too, but should it? .. function:: ord(c) |