From 6a95300a052b9f444c2c18b63527d8c3dbd0e12a Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 5 Jun 2025 09:33:12 +0300 Subject: [PATCH 1/9] gh-133438: Fix the use of the terms "argument" and "parameter" in the documentation --- Doc/c-api/arg.rst | 12 ++++++------ Doc/c-api/code.rst | 2 +- Doc/c-api/veryhigh.rst | 2 +- Doc/deprecations/pending-removal-in-3.19.rst | 2 +- Doc/faq/programming.rst | 4 ++-- Doc/howto/logging-cookbook.rst | 18 +++++++++--------- Doc/library/ast.rst | 13 +++++++------ Doc/library/asyncio-eventloop.rst | 10 +++++----- Doc/library/asyncio-future.rst | 2 +- Doc/library/asyncio-graph.rst | 6 +++--- Doc/library/asyncio-runner.rst | 2 +- Doc/library/asyncio-task.rst | 8 ++++---- Doc/library/collections.rst | 2 +- Doc/library/configparser.rst | 2 +- Doc/library/contextvars.rst | 2 +- Doc/library/curses.rst | 2 +- Doc/library/difflib.rst | 8 ++++---- Doc/library/exceptions.rst | 6 +++--- Doc/library/functions.rst | 6 +++--- Doc/library/hashlib.rst | 2 +- Doc/library/importlib.metadata.rst | 2 +- Doc/library/inspect.rst | 4 ++-- Doc/library/mmap.rst | 6 +++--- Doc/library/multiprocessing.rst | 8 ++++---- Doc/library/os.rst | 4 ++-- Doc/library/pathlib.rst | 4 ++-- Doc/library/pdb.rst | 6 +++--- Doc/library/pickle.rst | 2 +- Doc/library/random.rst | 2 +- Doc/library/security_warnings.rst | 2 +- Doc/library/shutil.rst | 2 +- Doc/library/stdtypes.rst | 2 +- Doc/library/subprocess.rst | 15 +++++++++++---- Doc/library/unittest.mock.rst | 2 +- Doc/library/unittest.rst | 2 +- Doc/tutorial/controlflow.rst | 18 +++++++++--------- Doc/whatsnew/2.5.rst | 4 ++-- Doc/whatsnew/2.6.rst | 8 ++++---- Doc/whatsnew/3.0.rst | 4 ++-- Doc/whatsnew/3.10.rst | 6 +++--- Doc/whatsnew/3.13.rst | 8 ++++---- Doc/whatsnew/3.14.rst | 4 ++-- Doc/whatsnew/3.4.rst | 12 ++++++------ Doc/whatsnew/3.5.rst | 4 ++-- Doc/whatsnew/3.6.rst | 6 +++--- Doc/whatsnew/3.7.rst | 4 ++-- Doc/whatsnew/3.8.rst | 6 +++--- Lib/_ast_unparse.py | 6 +++--- Lib/asyncio/graph.py | 4 ++-- Lib/copyreg.py | 2 +- Lib/dataclasses.py | 6 +++--- Lib/difflib.py | 4 ++-- Lib/inspect.py | 13 +++++++------ Misc/NEWS.d/3.10.0a3.rst | 2 +- Misc/NEWS.d/3.10.0b1.rst | 6 +++--- Misc/NEWS.d/3.11.0b1.rst | 2 +- Misc/NEWS.d/3.12.0a1.rst | 2 +- Misc/NEWS.d/3.12.0b1.rst | 2 +- Misc/NEWS.d/3.13.0a1.rst | 2 +- Misc/NEWS.d/3.13.0a3.rst | 2 +- Misc/NEWS.d/3.13.0a4.rst | 2 +- Misc/NEWS.d/3.13.0b1.rst | 2 +- Misc/NEWS.d/3.14.0a1.rst | 2 +- Misc/NEWS.d/3.14.0a2.rst | 2 +- Misc/NEWS.d/3.14.0a6.rst | 4 ++-- Misc/NEWS.d/3.14.0b1.rst | 2 +- Misc/NEWS.d/3.5.0a1.rst | 6 +++--- Misc/NEWS.d/3.5.0a3.rst | 2 +- Misc/NEWS.d/3.6.0b2.rst | 2 +- Misc/NEWS.d/3.7.0a1.rst | 2 +- Misc/NEWS.d/3.7.0a2.rst | 2 +- Misc/NEWS.d/3.8.0a1.rst | 2 +- Misc/NEWS.d/3.8.0b1.rst | 6 +++--- Misc/NEWS.d/3.9.0a1.rst | 4 ++-- ...5-05-31-15-49-46.gh-issue-134978.mXXuvW.rst | 2 +- Modules/socketmodule.c | 2 +- Objects/typevarobject.c | 2 +- Python/ast_unparse.c | 6 +++--- Python/bltinmodule.c | 4 ++-- Python/ceval.c | 2 +- 80 files changed, 189 insertions(+), 180 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 3bbc990b6329c0..7b38629f8cb632 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -410,8 +410,8 @@ inside nested parentheses. They are: ``$`` :c:func:`PyArg_ParseTupleAndKeywords` only: - Indicates that the remaining arguments in the Python argument list are - keyword-only. Currently, all keyword-only arguments must also be optional + Indicates that the remaining arguments in the Python argument list can be + supplied only by keyword. Currently, all such arguments must also be optional arguments, so ``|`` must always be specified before ``$`` in the format string. @@ -450,7 +450,7 @@ API Functions .. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...) - Parse the parameters of a function that takes only positional parameters into + Parse the arguments of a function that takes only positional arguments into local variables. Returns true on success; on failure, it returns false and raises the appropriate exception. @@ -463,8 +463,8 @@ API Functions .. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char * const *keywords, ...) - Parse the parameters of a function that takes both positional and keyword - parameters into local variables. + Parse the arguments of a function that takes both positional and keyword + arguments into local variables. The *keywords* argument is a ``NULL``-terminated array of keyword parameter names specified as null-terminated ASCII or UTF-8 encoded C strings. Empty names denote @@ -506,7 +506,7 @@ API Functions .. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...) - Parse the parameter of a function that takes a single positional parameter + Parse the argument of a function that takes a single positional parameter into a local variable. Returns true on success; on failure, it returns false and raises the appropriate exception. diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst index 42594f063b0709..36f01071582df7 100644 --- a/Doc/c-api/code.rst +++ b/Doc/c-api/code.rst @@ -71,7 +71,7 @@ bound into a function. .. c:function:: PyCodeObject* PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable) - Similar to :c:func:`PyUnstable_Code_New`, but with an extra "posonlyargcount" for positional-only arguments. + Similar to :c:func:`PyUnstable_Code_New`, but with an extra "posonlyargcount" for positional-only parameters. The same caveats that apply to ``PyUnstable_Code_New`` also apply to this function. .. index:: single: PyCode_NewWithPosOnlyArgs (C function) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 1ef4181d52eb10..445de33490b597 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -267,7 +267,7 @@ the same library that the Python runtime is using. evaluation. This environment consists of a dictionary of global variables, a mapping object of local variables, arrays of arguments, keywords and defaults, a dictionary of default values for :ref:`keyword-only - ` arguments and a closure tuple of cells. + ` parameters and a closure tuple of cells. .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) diff --git a/Doc/deprecations/pending-removal-in-3.19.rst b/Doc/deprecations/pending-removal-in-3.19.rst index 25f9cba390de68..757c1600ad46bf 100644 --- a/Doc/deprecations/pending-removal-in-3.19.rst +++ b/Doc/deprecations/pending-removal-in-3.19.rst @@ -18,7 +18,7 @@ Pending removal in Python 3.19 Support for the ``string`` keyword argument name is now deprecated and slated for removal in Python 3.19. - Before Python 3.13, the ``string`` keyword parameter was not correctly + Before Python 3.13, the ``string`` keyword argument was not correctly supported depending on the backend implementation of hash functions. Prefer passing the initial data as a positional argument for maximum backwards compatibility. diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 9f9e4fab685b19..c1436041c236cc 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -390,8 +390,8 @@ You could use a global variable containing a dictionary instead of the default value; it's a matter of taste. -How can I pass optional or keyword parameters from one function to another? ---------------------------------------------------------------------------- +How can I pass optional positional or keyword arguments from one function to another? +------------------------------------------------------------------------------------- Collect the arguments using the ``*`` and ``**`` specifiers in the function's parameter list; this gives you the positional arguments as a tuple and the diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 7d64a02358adb3..65844a797d5da1 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -1634,7 +1634,7 @@ method. Since then, Python has gained two new formatting approaches: Logging (as of 3.2) provides improved support for these two additional formatting styles. The :class:`Formatter` class been enhanced to take an -additional, optional keyword parameter named ``style``. This defaults to +additional, optional keyword argument named ``style``. This defaults to ``'%'``, but other possible values are ``'{'`` and ``'$'``, which correspond to the other two formatting styles. Backwards compatibility is maintained by default (as you would expect), but by explicitly specifying a style parameter, @@ -1675,10 +1675,10 @@ That can still use %-formatting, as shown here:: >>> Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take -positional parameters for the actual logging message itself, with keyword -parameters used only for determining options for how to handle the actual -logging call (e.g. the ``exc_info`` keyword parameter to indicate that -traceback information should be logged, or the ``extra`` keyword parameter +positional arguments for the actual logging message itself, with keyword +arguments used only for determining options for how to handle the actual +logging call (e.g. the ``exc_info`` keyword argument to indicate that +traceback information should be logged, or the ``extra`` keyword argument to indicate additional contextual information to be added to the log). So you cannot directly make logging calls using :meth:`str.format` or :class:`string.Template` syntax, because internally the logging package @@ -2732,10 +2732,10 @@ governs the formatting of logging messages for final output to logs, and is completely orthogonal to how an individual logging message is constructed. Logging calls (:meth:`~Logger.debug`, :meth:`~Logger.info` etc.) only take -positional parameters for the actual logging message itself, with keyword -parameters used only for determining options for how to handle the logging call -(e.g. the ``exc_info`` keyword parameter to indicate that traceback information -should be logged, or the ``extra`` keyword parameter to indicate additional +positional arguments for the actual logging message itself, with keyword +arguments used only for determining options for how to handle the logging call +(e.g. the ``exc_info`` keyword argument to indicate that traceback information +should be logged, or the ``extra`` keyword argument to indicate additional contextual information to be added to the log). So you cannot directly make logging calls using :meth:`str.format` or :class:`string.Template` syntax, because internally the logging package uses %-formatting to merge the format diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index ef6c62dca1e124..56fd6c257fc549 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1930,21 +1930,22 @@ Function and class definitions .. class:: arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults) - The arguments for a function. + The parameters for a function. * ``posonlyargs``, ``args`` and ``kwonlyargs`` are lists of :class:`arg` nodes. * ``vararg`` and ``kwarg`` are single :class:`arg` nodes, referring to the ``*args, **kwargs`` parameters. - * ``kw_defaults`` is a list of default values for keyword-only arguments. If + * ``kw_defaults`` is a list of default values for keyword-only parameters. If one is ``None``, the corresponding argument is required. - * ``defaults`` is a list of default values for arguments that can be passed - positionally. If there are fewer defaults, they correspond to the last n - arguments. + * ``defaults`` is a list of default values for positional-only and + keyword-or-positional parameter. + If there are fewer defaults, they correspond to the last n + parameters. .. class:: arg(arg, annotation, type_comment) - A single argument in a list. ``arg`` is a raw string of the argument + A single parameter in a list. ``arg`` is a raw string of the parameter name; ``annotation`` is its annotation, such as a :class:`Name` node. .. attribute:: type_comment diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 91970c282391f7..04c258963d4ce7 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -232,7 +232,7 @@ Scheduling callbacks Callbacks are called in the order in which they are registered. Each callback will be called exactly once. - The optional keyword-only *context* argument specifies a + The optional keyword argument *context* specifies a custom :class:`contextvars.Context` for the *callback* to run in. Callbacks use the current context when no *context* is provided. @@ -296,11 +296,11 @@ clocks to track time. scheduled for exactly the same time, the order in which they are called is undefined. - The optional positional *args* will be passed to the callback when + The optional positional arguments *args* will be passed to the callback when it is called. If you want the callback to be called with keyword arguments use :func:`functools.partial`. - An optional keyword-only *context* argument allows specifying a + An optional keyword argument *context* allows specifying a custom :class:`contextvars.Context` for the *callback* to run in. The current context is used when no *context* is provided. @@ -377,11 +377,11 @@ Creating Futures and Tasks If the *name* argument is provided and not ``None``, it is set as the name of the task using :meth:`Task.set_name`. - An optional keyword-only *context* argument allows specifying a + An optional keyword argument *context* allows specifying a custom :class:`contextvars.Context` for the *coro* to run in. The current context copy is created when no *context* is provided. - An optional keyword-only *eager_start* argument allows specifying + An optional keyword argument *eager_start* allows specifying if the task should execute eagerly during the call to create_task, or be scheduled later. If *eager_start* is not passed the mode set by :meth:`loop.set_task_factory` will be used. diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst index 32771ba72e0002..d0d096fa5fad23 100644 --- a/Doc/library/asyncio-future.rst +++ b/Doc/library/asyncio-future.rst @@ -165,7 +165,7 @@ Future Object If the Future is already *done* when this method is called, the callback is scheduled with :meth:`loop.call_soon`. - An optional keyword-only *context* argument allows specifying a + An optional keyword argument *context* allows specifying a custom :class:`contextvars.Context` for the *callback* to run in. The current context is used when no *context* is provided. diff --git a/Doc/library/asyncio-graph.rst b/Doc/library/asyncio-graph.rst index 5f642a32bf75c2..97c959375a27a2 100644 --- a/Doc/library/asyncio-graph.rst +++ b/Doc/library/asyncio-graph.rst @@ -32,10 +32,10 @@ and debuggers. If not passed, the current running task will be used. If the function is called on *the current task*, the optional - keyword-only *depth* argument can be used to skip the specified + keyword argument *depth* can be used to skip the specified number of frames from top of the stack. - If the optional keyword-only *limit* argument is provided, each call stack + If the optional keyword argument *limit* is provided, each call stack in the resulting graph is truncated to include at most ``abs(limit)`` entries. If *limit* is positive, the entries left are the closest to the invocation point. If *limit* is negative, the topmost entries are @@ -91,7 +91,7 @@ and debuggers. current task, the function returns ``None``. If the function is called on *the current task*, the optional - keyword-only *depth* argument can be used to skip the specified + keyword argument *depth* can be used to skip the specified number of frames from top of the stack. Returns a ``FutureCallGraph`` data class object: diff --git a/Doc/library/asyncio-runner.rst b/Doc/library/asyncio-runner.rst index 48d78099fd3ce7..49899e2a950c9a 100644 --- a/Doc/library/asyncio-runner.rst +++ b/Doc/library/asyncio-runner.rst @@ -122,7 +122,7 @@ Runner context manager If the argument is a coroutine, it is wrapped in a Task. - An optional keyword-only *context* argument allows specifying a + An optional keyword argument *context* allows specifying a custom :class:`contextvars.Context` for the code to run in. The runner's default context is used if context is ``None``. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index b19ffa8213a971..038769ac14bc2c 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -247,11 +247,11 @@ Creating Tasks :class:`Task` constructor (or factory) - all of the keyword arguments to this function are passed through to that interface. - An optional keyword-only *context* argument allows specifying a + An optional keyword argument *context* allows specifying a custom :class:`contextvars.Context` for the *coro* to run in. The current context copy is created when no *context* is provided. - An optional keyword-only *eager_start* argument allows specifying + An optional keyword argument *eager_start* allows specifying if the task should execute eagerly during the call to create_task, or be scheduled later. If *eager_start* is not passed the mode set by :meth:`loop.set_task_factory` will be used. @@ -1232,12 +1232,12 @@ Task Object APIs except :meth:`Future.set_result` and :meth:`Future.set_exception`. - An optional keyword-only *context* argument allows specifying a + An optional keyword argument *context* allows specifying a custom :class:`contextvars.Context` for the *coro* to run in. If no *context* is provided, the Task copies the current context and later runs its coroutine in the copied context. - An optional keyword-only *eager_start* argument allows eagerly starting + An optional keyword argument *eager_start* allows eagerly starting the execution of the :class:`asyncio.Task` at task creation time. If set to ``True`` and the event loop is running, the task will start executing the coroutine immediately, until the first time the coroutine diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 5fbdb12f40cafa..5ad842b3e46673 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -889,7 +889,7 @@ they add the ability to access fields by name instead of position index. .. versionchanged:: 3.6 The *verbose* and *rename* parameters became - :ref:`keyword-only arguments `. + :ref:`keyword-only parameters `. .. versionchanged:: 3.6 Added the *module* parameter. diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index bb109a9b742cb7..b9da8cf1a5799f 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -241,7 +241,7 @@ even if we specify a fallback: One more thing to be aware of is that the parser-level :meth:`~ConfigParser.get` method provides a custom, more complex interface, maintained for backwards compatibility. When using this method, a fallback value can be provided via -the ``fallback`` keyword-only argument: +the ``fallback`` keyword argument: .. doctest:: diff --git a/Doc/library/contextvars.rst b/Doc/library/contextvars.rst index 57580ce026e96a..d420e2249d91fa 100644 --- a/Doc/library/contextvars.rst +++ b/Doc/library/contextvars.rst @@ -35,7 +35,7 @@ Context Variables The required *name* parameter is used for introspection and debug purposes. - The optional keyword-only *default* parameter is returned by + If the optional keyword argument *default* is specified, it will be returned by :meth:`ContextVar.get` when no value for the variable is found in the current context. diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 0b13c559295f3c..b7cc9f19e90864 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -812,7 +812,7 @@ the following methods and attributes: .. note:: A ``0`` value for any parameter will cause the default character to be used for - that parameter. Keyword parameters can *not* be used. The defaults are listed + that parameter. Keyword arguments can *not* be used. The defaults are listed in this table: +-----------+---------------------+-----------------------+ diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index ce948a6860f02c..5a8ee9dd94f4ca 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -99,7 +99,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. *tabsize* is an optional keyword argument to specify tab stop spacing and defaults to ``8``. - *wrapcolumn* is an optional keyword to specify column number where lines are + *wrapcolumn* is an optional keyword argument to specify column number where lines are broken and wrapped, defaults to ``None`` where lines are not wrapped. *linejunk* and *charjunk* are optional keyword arguments passed into :func:`ndiff` @@ -133,7 +133,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. properly escaped while receiving input from untrusted sources. .. versionchanged:: 3.5 - *charset* keyword-only argument was added. The default charset of + *charset* keyword-only parameter was added. The default charset of HTML document changed from ``'ISO-8859-1'`` to ``'utf-8'``. .. method:: make_table(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5) @@ -225,7 +225,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style delta (a :term:`generator` generating the delta lines). - Optional keyword parameters *linejunk* and *charjunk* are filtering functions + Optional keyword arguments *linejunk* and *charjunk* are filtering functions (or ``None``): *linejunk*: A function that accepts a single string argument, and returns @@ -652,7 +652,7 @@ The :class:`Differ` class has this constructor: .. class:: Differ(linejunk=None, charjunk=None) :noindex: - Optional keyword parameters *linejunk* and *charjunk* are for filter functions + Optional keyword arguments *linejunk* and *charjunk* are for filter functions (or ``None``): *linejunk*: A function that accepts a single string argument, and returns true diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index bb72032891ea98..eda1e5cb26c4e5 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -204,7 +204,7 @@ The following exceptions are the exceptions that are usually raised. assignment fails. (When an object does not support attribute references or attribute assignments at all, :exc:`TypeError` is raised.) - The :attr:`name` and :attr:`obj` attributes can be set using keyword-only + The :attr:`name` and :attr:`obj` attributes can be set using keyword arguments to the constructor. When set they represent the name of the attribute that was attempted to be accessed and the object that was accessed for said attribute, respectively. @@ -238,7 +238,7 @@ The following exceptions are the exceptions that are usually raised. load a module. Also raised when the "from list" in ``from ... import`` has a name that cannot be found. - The optional *name* and *path* keyword-only arguments + The optional *name* and *path* keyword arguments set the corresponding attributes: .. attribute:: name @@ -312,7 +312,7 @@ The following exceptions are the exceptions that are usually raised. unqualified names. The associated value is an error message that includes the name that could not be found. - The :attr:`name` attribute can be set using a keyword-only argument to the + The :attr:`name` attribute can be set passing a keyword argument to the constructor. When set it represent the name of the variable that was attempted to be accessed. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 2ecce3dba5a0b9..9a41e26ca44e50 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1232,7 +1232,7 @@ are always available. They are listed here in alphabetical order. arguments are provided, the largest of the positional arguments is returned. - There are two optional keyword-only arguments. The *key* argument specifies + Two optional keyword arguments are supported. 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 @@ -1270,7 +1270,7 @@ are always available. They are listed here in alphabetical order. arguments are provided, the smallest of the positional arguments is returned. - There are two optional keyword-only arguments. The *key* argument specifies + Two optional keyword arguments are supported. 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 @@ -2221,7 +2221,7 @@ are always available. They are listed here in alphabetical order. True .. versionchanged:: 3.10 - Added the ``strict`` argument. + Added the ``strict`` parameter. .. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0) diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 8bba6700930bf4..69b589e7b0eb17 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -80,7 +80,7 @@ accessible by name via :func:`new`. See :data:`algorithms_available`. .. _hashlib-usedforsecurity: .. versionchanged:: 3.9 - All hashlib constructors take a keyword-only argument *usedforsecurity* + All hashlib constructors have a keyword-only parameter *usedforsecurity* with default value ``True``. A false value allows the use of insecure and blocked hashing algorithms in restricted environments. ``False`` indicates that the hashing algorithm is not used in a security context, e.g. as a diff --git a/Doc/library/importlib.metadata.rst b/Doc/library/importlib.metadata.rst index 12014309e26ec9..37999f7d948c30 100644 --- a/Doc/library/importlib.metadata.rst +++ b/Doc/library/importlib.metadata.rst @@ -121,7 +121,7 @@ Entry points .. function:: entry_points(**select_params) Returns a :class:`EntryPoints` instance describing entry points for the - current environment. Any given keyword parameters are passed to the + current environment. Any given keyword arguments are passed to the :meth:`!select` method for comparison to the attributes of the individual entry point definitions. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index e8d1176f477866..b74b686715b2e7 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -981,7 +981,7 @@ function. | | definition. | +------------------------+----------------------------------------------+ - Example: print all keyword-only arguments without default values: + Example: print all keyword-only parameters without default values: .. doctest:: @@ -1165,7 +1165,7 @@ Classes and functions Note that :func:`signature` and :ref:`Signature Object ` provide the recommended API for callable introspection, and support additional behaviours (like - positional-only arguments) that are sometimes encountered in extension module + positional-only parameters) that are sometimes encountered in extension module APIs. This function is retained primarily for use in code that needs to maintain compatibility with the Python 2 ``inspect`` module API. diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index 4e20c07331a220..13851f1d6ae985 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -31,7 +31,7 @@ still needs to be closed when done). mapping. For both the Unix and Windows versions of the constructor, *access* may be -specified as an optional keyword parameter. *access* accepts one of four +specified as an optional keyword argument. *access* accepts one of four values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to specify read-only, write-through or copy-on-write memory respectively, or :const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both Unix @@ -94,9 +94,9 @@ To map anonymous memory, -1 should be passed as the fileno along with the length :const:`PROT_READ \| PROT_WRITE`. *access* may be specified in lieu of *flags* and *prot* as an optional - keyword parameter. It is an error to specify both *flags*, *prot* and + keyword argument. It is an error to specify both *flags*, *prot* and *access*. See the description of *access* above for information on how to - use this parameter. + use this argument. *offset* may be specified as a non-negative integer offset. mmap references will be relative to the offset from the beginning of the file. *offset* diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index fc3c1134f97c85..4c240c4f86576a 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -529,7 +529,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the called. *name* is the process name (see :attr:`name` for more details). *args* is the argument tuple for the target invocation. *kwargs* is a dictionary of keyword arguments for the target invocation. If provided, - the keyword-only *daemon* argument sets the process :attr:`daemon` flag + the keyword argument *daemon* sets the process :attr:`daemon` flag to ``True`` or ``False``. If ``None`` (the default), this flag will be inherited from the creating process. @@ -1582,7 +1582,7 @@ inherited by child processes. with counter.get_lock(): counter.value += 1 - Note that *lock* is a keyword-only argument. + Note that *lock* is a keyword-only parameter. .. function:: Array(typecode_or_type, size_or_initializer, *, lock=True) @@ -1672,7 +1672,7 @@ processes. automatically protected by a lock, so it will not necessarily be "process-safe". - Note that *lock* is a keyword-only argument. + Note that *lock* is a keyword-only parameter. .. function:: Value(typecode_or_type, *args, lock=True) @@ -1687,7 +1687,7 @@ processes. automatically protected by a lock, so it will not necessarily be "process-safe". - Note that *lock* is a keyword-only argument. + Note that *lock* is a keyword-only parameter. .. function:: copy(obj) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 1e54cfec609bd2..fe2feb30ab0f13 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4712,7 +4712,7 @@ written in Python, such as a mail server's external command delivery program. write new code. The :mod:`subprocess` module is recommended instead. -.. function:: posix_spawn(path, argv, env, *, file_actions=None, \ +.. function:: posix_spawn(path, argv, env, /, *, file_actions=None, \ setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ setsigdef=(), scheduler=None) @@ -4720,7 +4720,7 @@ written in Python, such as a mail server's external command delivery program. Most users should use :func:`subprocess.run` instead of :func:`posix_spawn`. - The positional-only arguments *path*, *args*, and *env* are similar to + The positional-only parameters *path*, *args*, and *env* are similar to :func:`execve`. *env* is allowed to be ``None``, in which case current process' environment is used. diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 86351e65dc4ed6..89615083f5f086 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1348,12 +1348,12 @@ Reading directories .. seealso:: :ref:`pathlib-pattern-language` documentation. - By default, or when the *case_sensitive* keyword-only argument is set to + By default, or when the *case_sensitive* keyword argument is set to ``None``, this method matches paths using platform-specific casing rules: typically, case-sensitive on POSIX, and case-insensitive on Windows. Set *case_sensitive* to ``True`` or ``False`` to override this behaviour. - By default, or when the *recurse_symlinks* keyword-only argument is set to + By default, or when the *recurse_symlinks* keyword argument is set to ``False``, this method follows symlinks except when expanding "``**``" wildcards. Set *recurse_symlinks* to ``True`` to always follow symlinks. diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index f4b51664545be5..2f6d70dbc6118b 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -197,14 +197,14 @@ slightly different way: .. versionchanged:: 3.7 - The keyword-only argument *header*. + Added the keyword-only parameter *header*. .. versionchanged:: 3.13 :func:`set_trace` will enter the debugger immediately, rather than on the next line of code to be executed. - .. versionadded:: 3.14 - The *commands* argument. + .. versionchanged:: 3.14 + Added the *commands* parameter. .. awaitablefunction:: set_trace_async(*, header=None, commands=None) diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 007c9fe1b950cf..1df14a4be47237 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -610,7 +610,7 @@ methods: unpickling. You should implement this method if the :meth:`__new__` method of your - class requires keyword-only arguments. Otherwise, it is recommended for + class has keyword-only parameters. Otherwise, it is recommended for compatibility to implement :meth:`__getnewargs__`. .. versionchanged:: 3.6 diff --git a/Doc/library/random.rst b/Doc/library/random.rst index ef0cfb0e76cef6..5ef810119cd11a 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -243,7 +243,7 @@ Functions for sequences contains repeats, then each occurrence is a possible selection in the sample. Repeated elements can be specified one at a time or with the optional - keyword-only *counts* parameter. For example, ``sample(['red', 'blue'], + keyword argument *counts*. For example, ``sample(['red', 'blue'], counts=[4, 2], k=5)`` is equivalent to ``sample(['red', 'red', 'red', 'red', 'blue', 'blue'], k=5)``. diff --git a/Doc/library/security_warnings.rst b/Doc/library/security_warnings.rst index a573c98f73eb0a..17614e4c35ca37 100644 --- a/Doc/library/security_warnings.rst +++ b/Doc/library/security_warnings.rst @@ -9,7 +9,7 @@ The following modules have specific security considerations: * :mod:`base64`: :ref:`base64 security considerations ` in :rfc:`4648` -* :mod:`hashlib`: :ref:`all constructors take a "usedforsecurity" keyword-only +* :mod:`hashlib`: :ref:`all constructors take a "usedforsecurity" keyword argument disabling known insecure and blocked algorithms ` * :mod:`http.server` is not suitable for production use, only implementing diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index c78dfe1aafa0ed..4afa53d1dc97bd 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -712,7 +712,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. registered for that extension. In case none is found, a :exc:`ValueError` is raised. - The keyword-only *filter* argument is passed to the underlying unpacking + The keyword *filter* argument is passed to the underlying unpacking function. For zip files, *filter* is not accepted. For tar files, it is recommended to use ``'data'`` (default since Python 3.14), unless using features specific to tar and UNIX-like filesystems. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index f0b4b09ff10dce..fb904ce6b8813b 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1340,7 +1340,7 @@ application). in a partially modified state). :meth:`sort` accepts two arguments that can only be passed by keyword - (:ref:`keyword-only arguments `): + (:ref:`keyword-only parameters `): *key* specifies a function of one argument that is used to extract a comparison key from each list element (for example, ``key=str.lower``). diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 028a7861f36798..9ccd4ba18bfe67 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -958,10 +958,7 @@ on Windows. Partial support of the Windows `STARTUPINFO `__ structure is used for :class:`Popen` creation. The following attributes can - be set by passing them as keyword-only arguments. - - .. versionchanged:: 3.7 - Keyword-only argument support was added. + be set by passing them as keyword arguments. .. attribute:: dwFlags @@ -971,6 +968,8 @@ on Windows. si = subprocess.STARTUPINFO() si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW + .. versionadded:: 3.7 + .. attribute:: hStdInput If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute @@ -978,6 +977,8 @@ on Windows. :data:`STARTF_USESTDHANDLES` is not specified, the default for standard input is the keyboard buffer. + .. versionadded:: 3.7 + .. attribute:: hStdOutput If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute @@ -985,12 +986,16 @@ on Windows. is ignored and the default for standard output is the console window's buffer. + .. versionadded:: 3.7 + .. attribute:: hStdError If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute is the standard error handle for the process. Otherwise, this attribute is ignored and the default for standard error is the console window's buffer. + .. versionadded:: 3.7 + .. attribute:: wShowWindow If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this attribute @@ -1003,6 +1008,8 @@ on Windows. :data:`SW_HIDE` is provided for this attribute. It is used when :class:`Popen` is called with ``shell=True``. + .. versionadded:: 3.7 + .. attribute:: lpAttributeList A dictionary of additional attributes for process creation as given in diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 091562cc9aef98..716244db1bfbfc 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -445,7 +445,7 @@ the *new_callable* argument to :func:`patch`. Child mocks are reset as well. .. versionchanged:: 3.6 - Added two keyword-only arguments to the reset_mock function. + Added two keyword-only parameters to the reset_mock function. .. method:: mock_add_spec(spec, spec_set=False) diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index dcdda1719bf593..a9ca035f9e630e 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1879,7 +1879,7 @@ Loading and running tests Support for ``load_tests`` added. .. versionchanged:: 3.5 - Support for a keyword-only argument *pattern* has been added. + Keyword-only parameter *pattern* has been added. .. versionchanged:: 3.12 The undocumented and unofficial *use_load_tests* parameter has been diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 5c0e8f34bf82f4..ae2382d8266abf 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -764,9 +764,9 @@ parameter by how the arguments may be passed to the function: positional-only, positional-or-keyword, and keyword-only. Keyword parameters are also referred to as named parameters. -------------------------------- -Positional-or-Keyword Arguments -------------------------------- +-------------------------------- +Positional-or-Keyword Parameters +-------------------------------- If ``/`` and ``*`` are not present in the function definition, arguments may be passed to a function by position or by keyword. @@ -785,12 +785,12 @@ parameters. Parameters following the ``/`` may be *positional-or-keyword* or *keyword-only*. ----------------------- -Keyword-Only Arguments ----------------------- +----------------------- +Keyword-Only Parameters +----------------------- -To mark parameters as *keyword-only*, indicating the parameters must be passed -by keyword argument, place an ``*`` in the arguments list just before the first +To mark parameters as *keyword-only*, indicating the arguments must be passed +by keyword, place an ``*`` in the parameters list just before the first *keyword-only* parameter. ----------------- @@ -903,7 +903,7 @@ As guidance: * Use positional-only if you want the name of the parameters to not be available to the user. This is useful when parameter names have no real meaning, if you want to enforce the order of the arguments when the function - is called or if you need to take some positional parameters and arbitrary + is called or if you need to take some positional arguments and arbitrary keywords. * Use keyword-only when names have meaning and the function definition is more understandable by being explicit with names or you want to prevent diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 3430ac8668e280..639bf97be8b322 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1359,7 +1359,7 @@ complete list of changes, or look through the SVN logs for all the details. or 2 to specify which generation to collect. (Contributed by Barry Warsaw.) * The :func:`nsmallest` and :func:`nlargest` functions in the :mod:`heapq` - module now support a ``key`` keyword parameter similar to the one provided by + module now support a ``key`` keyword argument similar to the one provided by the :func:`min`/:func:`max` functions and the :meth:`sort` methods. For example:: @@ -2256,7 +2256,7 @@ code: * Library: The :mod:`pickle` and :mod:`!cPickle` modules no longer accept a return value of ``None`` from the :meth:`~object.__reduce__` method; the method must return a tuple of arguments instead. The modules also no longer accept the - deprecated *bin* keyword parameter. + deprecated *bin* keyword argument. * Library: The :mod:`SimpleXMLRPCServer ` and :mod:`DocXMLRPCServer ` classes now have a :attr:`rpc_paths` attribute that constrains XML-RPC operations to a diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 0803eba99e6d17..30016e93ec553a 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -1648,7 +1648,7 @@ Some smaller changes made to the core Python language are: (Contributed by Collin Winter; :issue:`1473257`.) * The :func:`compile` built-in function now accepts keyword arguments - as well as positional parameters. (Contributed by Thomas Wouters; + as well as positional arguments. (Contributed by Thomas Wouters; :issue:`1444529`.) * The :func:`complex` constructor now accepts strings containing @@ -2863,18 +2863,18 @@ Win32 LastError variables at the outset of each wrapped call. You can now retrieve the Unix ``errno`` variable after a function call. When creating a wrapped function, you can supply -``use_errno=True`` as a keyword parameter to the :func:`DLL` function +``use_errno=True`` as a keyword argument to the :func:`DLL` function and then call the module-level methods :meth:`set_errno` and :meth:`get_errno` to set and retrieve the error value. The Win32 LastError variable is similarly supported by the :func:`DLL`, :func:`OleDLL`, and :func:`WinDLL` functions. -You supply ``use_last_error=True`` as a keyword parameter +You supply ``use_last_error=True`` as a keyword argument and then call the module-level methods :meth:`set_last_error` and :meth:`get_last_error`. The :func:`byref` function, used to retrieve a pointer to a ctypes -instance, now has an optional *offset* parameter that is a byte +instance, now has an optional *offset* argument that is a byte count that will be added to the returned pointer. .. ====================================================================== diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst index d858586138e9ae..20a003053e6558 100644 --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -360,11 +360,11 @@ New Syntax the :attr:`~object.__annotations__` attribute. The intent is to encourage experimentation through metaclasses, decorators or frameworks. -* :pep:`3102`: Keyword-only arguments. Named parameters occurring +* :pep:`3102`: Keyword-only parameters. Named parameters occurring after ``*args`` in the parameter list *must* be specified using keyword syntax in the call. You can also use a bare ``*`` in the parameter list to indicate that you don't accept a variable-length - argument list, but you do have keyword-only arguments. + argument list, but you do have keyword-only parameters. * Keyword arguments are allowed after the list of base classes in a class definition. This is used by the new convention for specifying diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index 1067601c652300..ec6f37fbd9b1b1 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -1265,7 +1265,7 @@ and :const:`~os.O_NOFOLLOW_ANY` for macOS. os.path ------- -:func:`os.path.realpath` now accepts a *strict* keyword-only argument. When set +:func:`os.path.realpath` now accepts a *strict* keyword argument. When set to ``True``, :exc:`OSError` is raised if a path doesn't exist or a symlink loop is encountered. (Contributed by Barney Gale in :issue:`43757`.) @@ -1286,7 +1286,7 @@ order as :meth:`~pathlib.Path.symlink_to`. (Contributed by Barney Gale in :issue:`39950`.) :meth:`pathlib.Path.stat` and :meth:`~pathlib.Path.chmod` now accept a -*follow_symlinks* keyword-only argument for consistency with corresponding +*follow_symlinks* keyword argument for consistency with corresponding functions in the :mod:`os` module. (Contributed by Barney Gale in :issue:`39906`.) @@ -1440,7 +1440,7 @@ traceback The :func:`~traceback.format_exception`, :func:`~traceback.format_exception_only`, and :func:`~traceback.print_exception` functions can now take an exception object -as a positional-only argument. +as a positional argument. (Contributed by Zackery Spytz and Matthias Bussonnier in :issue:`26389`.) types diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index 580a3d8154dee1..7723f72b465a68 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -1121,7 +1121,7 @@ pathlib for low-level path parsing and joining. This will be either :mod:`!posixpath` or :mod:`!ntpath`. -* Add *recurse_symlinks* keyword-only argument to +* Add *recurse_symlinks* keyword-only parameter to :meth:`.Path.glob` and :meth:`~pathlib.Path.rglob`. (Contributed by Barney Gale in :gh:`77609`.) @@ -1130,7 +1130,7 @@ pathlib Previously, only directories were returned. (Contributed by Barney Gale in :gh:`70303`.) -* Add the *follow_symlinks* keyword-only argument to +* Add the *follow_symlinks* keyword-only parameter to :meth:`Path.is_file `, :meth:`Path.is_dir `, :meth:`.Path.owner`, and :meth:`.Path.group`. @@ -1324,11 +1324,11 @@ tkinter (Contributed by Serhiy Storchaka in :gh:`43457`.) * :meth:`!wm_attributes` can now return attributes as a :class:`dict`, - by using the new optional keyword-only parameter *return_python_dict*. + by using the new optional keyword argument *return_python_dict*. (Contributed by Serhiy Storchaka in :gh:`43457`.) * :meth:`!Text.count` can now return a simple :class:`int` - when the new optional keyword-only parameter *return_ints* is used. + when the new optional keyword argument *return_ints* is used. Otherwise, the single count is returned as a 1-tuple or ``None``. (Contributed by Serhiy Storchaka in :gh:`97928`.) diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 45e68aea5fb9a2..271b8d12f7bbb3 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -1322,8 +1322,8 @@ getopt getpass ------- -* Support keyboard feedback by :func:`getpass.getpass` via the keyword-only - optional argument ``echo_char``. Placeholder characters are rendered whenever +* Support keyboard feedback by :func:`getpass.getpass` via optional keyword + argument ``echo_char``. Placeholder characters are rendered whenever a character is entered, and removed when a character is deleted. (Contributed by Semyon Moroz in :gh:`77065`.) diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index e4f602a17ee968..c96db90b48c56f 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -403,7 +403,7 @@ Some smaller changes made to the core Python language are: * Unicode database updated to UCD version 6.3. -* :func:`min` and :func:`max` now accept a *default* keyword-only argument that +* :func:`min` and :func:`max` now accept a *default* keyword argument that can be used to specify the value they return if the iterable they are evaluating has no elements. (Contributed by Julian Berman in :issue:`18111`.) @@ -712,7 +712,7 @@ dis --- Functions :func:`~dis.show_code`, :func:`~dis.dis`, :func:`~dis.distb`, and -:func:`~dis.disassemble` now accept a keyword-only *file* argument that +:func:`~dis.disassemble` now accept a keyword argument *file* that controls where they write their output. The :mod:`dis` module is now built around an :class:`~dis.Instruction` class @@ -1221,8 +1221,8 @@ pickle :mod:`pickle` now supports (but does not use by default) a new pickle protocol, protocol 4. This new protocol addresses a number of issues that were present in previous protocols, such as the serialization of nested classes, very large -strings and containers, and classes whose :meth:`__new__` method takes -keyword-only arguments. It also provides some efficiency improvements. +strings and containers, and classes whose :meth:`__new__` method has +keyword-only parameters. It also provides some efficiency improvements. .. seealso:: @@ -2395,8 +2395,8 @@ Changes in the Python API values for the *base* parameter. It is unlikely anyone was doing this, but if so, it will now raise a :exc:`TypeError` (:issue:`16772`). -* Defaults for keyword-only arguments are now evaluated *after* defaults for - regular keyword arguments, instead of before. Hopefully no one wrote any +* Defaults for keyword-only parameters are now evaluated *after* defaults for + regular keyword-or-positional parameters, instead of before. Hopefully no one wrote any code that depends on the previous buggy behavior (:issue:`16967`). * Stale thread states are now cleared after :func:`~os.fork`. This may cause diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index db3f1db3bd74ad..52c9a426307f7e 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -1062,7 +1062,7 @@ difflib The charset of HTML documents generated by :meth:`HtmlDiff.make_file() ` -can now be customized by using a new *charset* keyword-only argument. +can now be customized by passing a *charset* keyword argument. The default charset of HTML document changed from ``"ISO-8859-1"`` to ``"utf-8"``. (Contributed by Berker Peksag in :issue:`2052`.) @@ -1985,7 +1985,7 @@ unittest -------- The :meth:`TestLoader.loadTestsFromModule() ` -method now accepts a keyword-only argument *pattern* which is passed to +method now accepts a keyword argument *pattern* which is passed to ``load_tests`` as the third argument. Found packages are now checked for ``load_tests`` regardless of whether their path matches *pattern*, because it is impossible for a package name to match the default pattern. diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index 050c9103b00c98..4a271f2d5a92d2 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -1664,7 +1664,7 @@ The :class:`~unittest.mock.Mock` class has the following improvements: (Contributed by Amit Saha in :issue:`26323`.) * The :meth:`Mock.reset_mock() ` method - now has two optional keyword only arguments: *return_value* and + now support two optional keyword arguments: *return_value* and *side_effect*. (Contributed by Kushal Das in :issue:`21271`.) @@ -2243,8 +2243,8 @@ Changes in the Python API * All optional arguments of the :func:`~json.dump`, :func:`~json.dumps`, :func:`~json.load` and :func:`~json.loads` functions and :class:`~json.JSONEncoder` and :class:`~json.JSONDecoder` class - constructors in the :mod:`json` module are now :ref:`keyword-only - `. + constructors in the :mod:`json` module can now be supplied + :ref:`only by keyword `. (Contributed by Serhiy Storchaka in :issue:`18726`.) * Subclasses of :class:`type` which don't override ``type.__new__`` may no diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index f420fa5c04479b..65d68c3b91ade5 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -1198,8 +1198,8 @@ on POSIX systems and can be used to determine whether a path is a mount point. pdb --- -:func:`pdb.set_trace` now takes an optional *header* keyword-only -argument. If given, it is printed to the console just before debugging +:func:`pdb.set_trace` now takes an optional keyword argument *header*. +If given, it is printed to the console just before debugging begins. (Contributed by Barry Warsaw in :issue:`31389`.) :mod:`pdb` command line now accepts ``-m module_name`` as an alternative to diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index bc2eb1d0e263f0..da782d4b702a6d 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -1625,7 +1625,7 @@ Build and C API Changes * The new function :c:func:`!PyCode_NewWithPosOnlyArgs` allows to create code objects like :c:func:`!PyCode_New`, but with an extra *posonlyargcount* - parameter for indicating the number of positional-only arguments. + parameter for indicating the number of positional-only parameters. (Contributed by Pablo Galindo in :issue:`37221`.) * :c:func:`!Py_SetPath` now sets :data:`sys.executable` to the program full @@ -2003,9 +2003,9 @@ Changes in the Python API in :issue:`36623`.) * :class:`types.CodeType` has a new parameter in the second position of the - constructor (*posonlyargcount*) to support positional-only arguments defined + constructor (*posonlyargcount*) to support positional-only parameters defined in :pep:`570`. The first argument (*argcount*) now represents the total - number of positional arguments (including positional-only arguments). The new + number of positional parameters (including positional-only parameters). The new ``replace()`` method of :class:`types.CodeType` can be used to make the code future-proof. diff --git a/Lib/_ast_unparse.py b/Lib/_ast_unparse.py index c25066eb107de1..56d6afb71dc4cd 100644 --- a/Lib/_ast_unparse.py +++ b/Lib/_ast_unparse.py @@ -1016,7 +1016,7 @@ def visit_arg(self, node): def visit_arguments(self, node): first = True - # normal arguments + # normal parameters all_args = node.posonlyargs + node.args defaults = [None] * (len(all_args) - len(node.defaults)) + node.defaults for index, elements in enumerate(zip(all_args, defaults), 1): @@ -1032,7 +1032,7 @@ def visit_arguments(self, node): if index == len(node.posonlyargs): self.write(", /") - # varargs, or bare '*' if no varargs but keyword-only arguments present + # varargs, or bare '*' if no varargs but keyword-only parameters present if node.vararg or node.kwonlyargs: if first: first = False @@ -1045,7 +1045,7 @@ def visit_arguments(self, node): self.write(": ") self.traverse(node.vararg.annotation) - # keyword-only arguments + # keyword-only parameters if node.kwonlyargs: for a, d in zip(node.kwonlyargs, node.kw_defaults): self.write(", ") diff --git a/Lib/asyncio/graph.py b/Lib/asyncio/graph.py index b5bfeb1630a159..1729d91a9bee1c 100644 --- a/Lib/asyncio/graph.py +++ b/Lib/asyncio/graph.py @@ -109,10 +109,10 @@ def capture_call_graph( returns None. If "capture_call_graph()" is introspecting *the current task*, the - optional keyword-only 'depth' argument can be used to skip the specified + optional keyword argument 'depth' can be used to skip the specified number of frames from top of the stack. - If the optional keyword-only 'limit' argument is provided, each call stack + If the optional keyword argument 'limit' is provided, each call stack in the resulting graph is truncated to include at most ``abs(limit)`` entries. If 'limit' is positive, the entries left are the closest to the invocation point. If 'limit' is negative, the topmost entries are diff --git a/Lib/copyreg.py b/Lib/copyreg.py index a5e8add4a554d7..8d306ee3b0e50b 100644 --- a/Lib/copyreg.py +++ b/Lib/copyreg.py @@ -105,7 +105,7 @@ def __newobj__(cls, *args): def __newobj_ex__(cls, args, kwargs): """Used by pickle protocol 4, instead of __newobj__ to allow classes with - keyword-only arguments to be pickled correctly. + keyword-only parameters to be pickled correctly. """ return cls.__new__(cls, *args, **kwargs) diff --git a/Lib/dataclasses.py b/Lib/dataclasses.py index 86d29df0639184..6cf7e5fe18248c 100644 --- a/Lib/dataclasses.py +++ b/Lib/dataclasses.py @@ -661,9 +661,9 @@ def _init_fn(fields, std_fields, kw_only_fields, frozen, has_post_init, _init_params = [_init_param(f) for f in std_fields] if kw_only_fields: - # Add the keyword-only args. Because the * can only be added if - # there's at least one keyword-only arg, there needs to be a test here - # (instead of just concatenating the lists together). + # Add the keyword-only parameters. Because the * can only be added if + # there's at least one keyword-only parameter, there needs to be a + # test here (instead of just concatenating the lists together). _init_params += ['*'] _init_params += [_init_param(f) for f in kw_only_fields] func_builder.add_fn('__init__', diff --git a/Lib/difflib.py b/Lib/difflib.py index 18801a9b19eb9d..98fea824e69f4a 100644 --- a/Lib/difflib.py +++ b/Lib/difflib.py @@ -811,7 +811,7 @@ def __init__(self, linejunk=None, charjunk=None): """ Construct a text differencer, with optional filters. - The two optional keyword parameters are for filter functions: + The two optional keyword arguments are for filter functions: - `linejunk`: A function that should accept a single string argument, and return true iff the string is junk. The module-level function @@ -1311,7 +1311,7 @@ def ndiff(a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK): r""" Compare `a` and `b` (lists of strings); return a `Differ`-style delta. - Optional keyword parameters `linejunk` and `charjunk` are for filter + Optional keyword arguments `linejunk` and `charjunk` are for filter functions, or can be None: - linejunk: A function that should accept a single string argument and diff --git a/Lib/inspect.py b/Lib/inspect.py index 183e67fabf966e..2b416793917b59 100644 --- a/Lib/inspect.py +++ b/Lib/inspect.py @@ -1199,9 +1199,10 @@ def getargs(co): """Get information about the arguments accepted by a code object. Three things are returned: (args, varargs, varkw), where - 'args' is the list of argument names. Keyword-only arguments are - appended. 'varargs' and 'varkw' are the names of the * and ** - arguments or None.""" + 'args' is the list of the names of positional-only, + positional-or-keyword and keyword-only parameters. 'varargs' and + 'varkw' are the names of the var-positional and var-keyword + parameters or None.""" if not iscode(co): raise TypeError('{!r} is not a code object'.format(co)) @@ -2248,7 +2249,7 @@ def p(name_node, default_node, default=empty): kind = Parameter.VAR_POSITIONAL p(f.args.vararg, empty) - # keyword-only arguments + # keyword-only parameters kind = Parameter.KEYWORD_ONLY for name, default in zip(f.args.kwonlyargs, f.args.kw_defaults): p(name, default) @@ -2938,7 +2939,7 @@ class Signature: * parameters : OrderedDict An ordered mapping of parameters' names to the corresponding - Parameter objects (keyword-only arguments are in the same order + Parameter objects (keyword-only parameters are in the same order as listed in `code.co_varnames`). * return_annotation : object The annotation for the return type of the function if specified. @@ -3276,7 +3277,7 @@ def format(self, *, max_width=None, quote_annotation_strings=True): if kind == _VAR_POSITIONAL: # OK, we have an '*args'-like parameter, so we won't need - # a '*' to separate keyword-only arguments + # a '*' to separate keyword-only parameters render_kw_only_separator = False elif kind == _KEYWORD_ONLY and render_kw_only_separator: # We have a keyword-only parameter to render and we haven't diff --git a/Misc/NEWS.d/3.10.0a3.rst b/Misc/NEWS.d/3.10.0a3.rst index 3f3fb7ec599e57..ea76e9280a444c 100644 --- a/Misc/NEWS.d/3.10.0a3.rst +++ b/Misc/NEWS.d/3.10.0a3.rst @@ -754,7 +754,7 @@ conformance with the other platforms. The :func:`traceback.format_exception`, :func:`traceback.format_exception_only`, and :func:`traceback.print_exception` functions can now take an exception object -as a positional-only argument. +as a positional argument. .. diff --git a/Misc/NEWS.d/3.10.0b1.rst b/Misc/NEWS.d/3.10.0b1.rst index 406a5d7853edc0..0546d85fd3037b 100644 --- a/Misc/NEWS.d/3.10.0b1.rst +++ b/Misc/NEWS.d/3.10.0b1.rst @@ -924,7 +924,7 @@ Implement :pep:`647` in the :mod:`typing` module by adding .. nonce: b33fa0 .. section: Library -:func:`os.path.realpath` now accepts a *strict* keyword-only argument. When +:func:`os.path.realpath` now accepts a *strict* keyword argument. When set to ``True``, :exc:`OSError` is raised if a path doesn't exist or a symlink loop is encountered. @@ -1069,7 +1069,7 @@ window working on behalf of the canvas window. .. section: Library Add the ability to specify keyword-only fields to dataclasses. These fields -will become keyword-only arguments to the generated __init__. +will become keyword-only parameters of the generated __init__. .. @@ -1300,7 +1300,7 @@ of ``1`` or ``0``. .. section: Library :meth:`pathlib.Path.stat` and :meth:`~pathlib.Path.chmod` now accept a -*follow_symlinks* keyword-only argument for consistency with corresponding +*follow_symlinks* keyword argument for consistency with corresponding functions in the :mod:`os` module. .. diff --git a/Misc/NEWS.d/3.11.0b1.rst b/Misc/NEWS.d/3.11.0b1.rst index c3a1942b881ad4..6d6616b6261bc3 100644 --- a/Misc/NEWS.d/3.11.0b1.rst +++ b/Misc/NEWS.d/3.11.0b1.rst @@ -970,7 +970,7 @@ raised. .. nonce: AWy4Cs .. section: Library -Add an optional keyword *shutdown_timeout* parameter to the +Add support for an optional keyword argument *shutdown_timeout* to the :class:`multiprocessing.BaseManager` constructor. Kill the process if terminate() takes longer than the timeout. Patch by Victor Stinner. diff --git a/Misc/NEWS.d/3.12.0a1.rst b/Misc/NEWS.d/3.12.0a1.rst index f2668e99a6299b..06b458f4958920 100644 --- a/Misc/NEWS.d/3.12.0a1.rst +++ b/Misc/NEWS.d/3.12.0a1.rst @@ -2620,7 +2620,7 @@ Faster ``json.dumps()`` when sorting of keys is not requested (default). .. section: Library Improve :meth:`Signature.bind ` error message for -missing keyword-only arguments. +missing arguments for keyword-only parameters. .. diff --git a/Misc/NEWS.d/3.12.0b1.rst b/Misc/NEWS.d/3.12.0b1.rst index 3a3870ac9fe621..af115ce47282a0 100644 --- a/Misc/NEWS.d/3.12.0b1.rst +++ b/Misc/NEWS.d/3.12.0b1.rst @@ -1594,7 +1594,7 @@ and returned. .. nonce: heTAod .. section: Library -Add *case_sensitive* keyword-only argument to :meth:`pathlib.Path.glob` and +Add *case_sensitive* keyword-only parameter to :meth:`pathlib.Path.glob` and :meth:`~pathlib.Path.rglob`. .. diff --git a/Misc/NEWS.d/3.13.0a1.rst b/Misc/NEWS.d/3.13.0a1.rst index 0a93cbcea0ffd2..c715f1feeb01fa 100644 --- a/Misc/NEWS.d/3.13.0a1.rst +++ b/Misc/NEWS.d/3.13.0a1.rst @@ -3591,7 +3591,7 @@ Zijlstra. .. nonce: YSoykM .. section: Library -Add *follow_symlinks* keyword-only argument to :meth:`pathlib.Path.is_dir` +Add *follow_symlinks* keyword-only parameter to :meth:`pathlib.Path.is_dir` and :meth:`~pathlib.Path.is_file`, defaulting to ``True``. .. diff --git a/Misc/NEWS.d/3.13.0a3.rst b/Misc/NEWS.d/3.13.0a3.rst index 0f8dee261c6589..a437f8c2b4fdc2 100644 --- a/Misc/NEWS.d/3.13.0a3.rst +++ b/Misc/NEWS.d/3.13.0a3.rst @@ -1625,7 +1625,7 @@ are many environment variables to go over. .. nonce: u64_QI .. section: Library -Add *follow_symlinks* keyword-only argument to :meth:`pathlib.Path.owner` +Add *follow_symlinks* keyword-only parameter to :meth:`pathlib.Path.owner` and :meth:`~pathlib.Path.group`, defaulting to ``True``. .. diff --git a/Misc/NEWS.d/3.13.0a4.rst b/Misc/NEWS.d/3.13.0a4.rst index 1b971113173e0a..4a1ab93f060094 100644 --- a/Misc/NEWS.d/3.13.0a4.rst +++ b/Misc/NEWS.d/3.13.0a4.rst @@ -1344,7 +1344,7 @@ Update GitHub CI workflows to use OpenSSL 3.0.13 and multissltests to use Fix a bug in Argument Clinic that generated incorrect code for methods with no parameters that use the :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS ` calling convention. Only the -positional parameter count was checked; any keyword argument passed would be +positional argument count was checked; any keyword argument passed would be silently accepted. .. diff --git a/Misc/NEWS.d/3.13.0b1.rst b/Misc/NEWS.d/3.13.0b1.rst index 97731276679ba6..26fc1b8556c240 100644 --- a/Misc/NEWS.d/3.13.0b1.rst +++ b/Misc/NEWS.d/3.13.0b1.rst @@ -406,7 +406,7 @@ calling convention: .. nonce: -_1YL0 .. section: Core and Builtins -Speed up calls to :func:`str` with positional-only argument, by using the +Speed up calls to :func:`str` with only positional argument, by using the :pep:`590` ``vectorcall`` calling convention. Patch by Erlend Aasland. .. diff --git a/Misc/NEWS.d/3.14.0a1.rst b/Misc/NEWS.d/3.14.0a1.rst index 67451a7e0087cb..f9371c70780e14 100644 --- a/Misc/NEWS.d/3.14.0a1.rst +++ b/Misc/NEWS.d/3.14.0a1.rst @@ -3697,7 +3697,7 @@ Prepare Tkinter for C API changes in Tcl 8.7/9.0 to avoid .. section: Library Fixed handling in :meth:`inspect.Signature.bind` of keyword arguments having -the same name as positional-only arguments when a variadic keyword argument +the same name as positional-only parameters when a variadic keyword parameter (e.g. ``**kwargs``) is present. .. diff --git a/Misc/NEWS.d/3.14.0a2.rst b/Misc/NEWS.d/3.14.0a2.rst index 7405a1344a9fa6..28a680dfdab6c1 100644 --- a/Misc/NEWS.d/3.14.0a2.rst +++ b/Misc/NEWS.d/3.14.0a2.rst @@ -870,7 +870,7 @@ Only show stale code warning in :mod:`pdb` when we display source code. .. nonce: vZJ-Ns .. section: Library -Deprecate passing keyword-only *prefix_chars* argument to +Deprecate passing keyword *prefix_chars* argument to :meth:`argparse.ArgumentParser.add_argument_group`. .. diff --git a/Misc/NEWS.d/3.14.0a6.rst b/Misc/NEWS.d/3.14.0a6.rst index bafd8845de6973..e7f491151b190f 100644 --- a/Misc/NEWS.d/3.14.0a6.rst +++ b/Misc/NEWS.d/3.14.0a6.rst @@ -493,8 +493,8 @@ or ``kill``, or ``send_signal``. .. section: Library Fixed failure to raise :exc:`TypeError` in :meth:`inspect.Signature.bind` -for positional-only arguments provided by keyword when a variadic keyword -argument (e.g. ``**kwargs``) is present. +for positional-only parameters provided by keyword when a variadic keyword +parameter (e.g. ``**kwargs``) is present. .. diff --git a/Misc/NEWS.d/3.14.0b1.rst b/Misc/NEWS.d/3.14.0b1.rst index 5847dea7d5e8ee..c1dcfaf94a2f3e 100644 --- a/Misc/NEWS.d/3.14.0b1.rst +++ b/Misc/NEWS.d/3.14.0b1.rst @@ -996,7 +996,7 @@ Add ability to specify name for :class:`!tkinter.OptionMenu` and .. nonce: 8uW0Wf .. section: Library -Add keyword-only optional argument *echo_char* for :meth:`getpass.getpass` +Add keyword-only parameter *echo_char* for :meth:`getpass.getpass` for optional visual keyboard feedback support. Patch by Semyon Moroz. .. diff --git a/Misc/NEWS.d/3.5.0a1.rst b/Misc/NEWS.d/3.5.0a1.rst index 8f9d8ce57caa05..65362b9f44a9a7 100644 --- a/Misc/NEWS.d/3.5.0a1.rst +++ b/Misc/NEWS.d/3.5.0a1.rst @@ -4390,8 +4390,8 @@ Popa. .. nonce: v0Vs9V .. section: Library -RE pattern methods now accept the string keyword parameters as documented. -The pattern and source keyword parameters are left as deprecated aliases. +RE pattern methods now accept the *string* keyword arguments as documented. +The *pattern* and *source* keyword parameters are left as deprecated aliases. .. @@ -4466,7 +4466,7 @@ Improve repr of inspect.Signature and inspect.Parameter. .. section: Library Fix inspect.getcallargs() to raise correct TypeError for missing -keyword-only arguments. Patch by Jeremiah Lowin. +arguments for keyword-only parameters. Patch by Jeremiah Lowin. .. diff --git a/Misc/NEWS.d/3.5.0a3.rst b/Misc/NEWS.d/3.5.0a3.rst index a81d67aea8663b..1579d0eacb8e6e 100644 --- a/Misc/NEWS.d/3.5.0a3.rst +++ b/Misc/NEWS.d/3.5.0a3.rst @@ -189,7 +189,7 @@ complexity in breaking long words. .. section: Library The copy module now uses pickle protocol 4 (PEP 3154) and supports copying -of instances of classes whose __new__ method takes keyword-only arguments. +of instances of classes whose __new__ method has keyword-only parameters. .. diff --git a/Misc/NEWS.d/3.6.0b2.rst b/Misc/NEWS.d/3.6.0b2.rst index 23dd69efb23b88..632733e0f88f9a 100644 --- a/Misc/NEWS.d/3.6.0b2.rst +++ b/Misc/NEWS.d/3.6.0b2.rst @@ -419,7 +419,7 @@ invalid string-like object as a name. Patch by Xiang Zhang. .. nonce: fQsEdn .. section: Library -random.choices() now has k as a keyword-only argument to improve the +:func:`random.choices` now has keyword-only parameter *k* to improve the readability of common cases and come into line with the signature used in other languages. diff --git a/Misc/NEWS.d/3.7.0a1.rst b/Misc/NEWS.d/3.7.0a1.rst index fd6ba07b53a617..4eefdf8c51dd51 100644 --- a/Misc/NEWS.d/3.7.0a1.rst +++ b/Misc/NEWS.d/3.7.0a1.rst @@ -4412,7 +4412,7 @@ invalid string-like object as a name. Patch by Xiang Zhang. .. nonce: fQsEdn .. section: Library -random.choices() now has k as a keyword-only argument to improve the +:func:`random.choices` now has keyword-only parameter *k* to improve the readability of common cases and come into line with the signature used in other languages. diff --git a/Misc/NEWS.d/3.7.0a2.rst b/Misc/NEWS.d/3.7.0a2.rst index 06ca32d37fa4fa..a1ff8b8354bd9a 100644 --- a/Misc/NEWS.d/3.7.0a2.rst +++ b/Misc/NEWS.d/3.7.0a2.rst @@ -507,7 +507,7 @@ has failed. .. nonce: jNFYqB .. section: Library -``pdb.set_trace()`` now takes an optional keyword-only argument ``header``. +``pdb.set_trace()`` now takes an optional keyword argument ``header``. If given, this is printed to the console just before debugging begins. .. diff --git a/Misc/NEWS.d/3.8.0a1.rst b/Misc/NEWS.d/3.8.0a1.rst index 93995bc8feaad7..638c71698bb29a 100644 --- a/Misc/NEWS.d/3.8.0a1.rst +++ b/Misc/NEWS.d/3.8.0a1.rst @@ -591,7 +591,7 @@ for invalid escape sequences in string and bytes literals. .. section: Core and Builtins Fixed a crash in compiling string annotations containing a lambda with a -keyword-only argument that doesn't have a default value. +keyword-only parameter that doesn't have a default value. .. diff --git a/Misc/NEWS.d/3.8.0b1.rst b/Misc/NEWS.d/3.8.0b1.rst index 5010473269d92f..f6ee2d6b667b7d 100644 --- a/Misc/NEWS.d/3.8.0b1.rst +++ b/Misc/NEWS.d/3.8.0b1.rst @@ -56,10 +56,10 @@ Pablo Galindo. .. section: Core and Builtins Make the *co_argcount* attribute of code objects represent the total number -of positional arguments (including positional-only arguments). The value of -*co_posonlyargcount* can be used to distinguish which arguments are +of positional parameters (including positional-only parameters). The value of +*co_posonlyargcount* can be used to distinguish which parameters are positional only, and the difference (*co_argcount* - *co_posonlyargcount*) -is the number of positional-or-keyword arguments. Patch by Pablo Galindo. +is the number of positional-or-keyword parameters. Patch by Pablo Galindo. .. diff --git a/Misc/NEWS.d/3.9.0a1.rst b/Misc/NEWS.d/3.9.0a1.rst index cc24bae5881df1..be337fb3e318d3 100644 --- a/Misc/NEWS.d/3.9.0a1.rst +++ b/Misc/NEWS.d/3.9.0a1.rst @@ -5431,8 +5431,8 @@ Remove ``Tools/scripts/h2py.py``: use cffi to access a C API in Python. .. nonce: zbTgy8 .. section: Tools/Demos -Argument Clinic now uses the argument name on errors with keyword-only -argument instead of their position. Patch contributed by Rémi Lapeyre. +Argument Clinic now uses the argument name on errors with arguments for keyword-only +parameter instead of their position. Patch contributed by Rémi Lapeyre. .. diff --git a/Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst b/Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst index e75ce1622d6396..fef55005f3414b 100644 --- a/Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst +++ b/Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst @@ -1,4 +1,4 @@ -:mod:`hashlib`: Supporting the ``string`` keyword parameter in hash function +:mod:`hashlib`: Supporting the ``string`` keyword argument in hash function constructors such as :func:`~hashlib.new` or the direct hash-named constructors such as :func:`~hashlib.md5` and :func:`~hashlib.sha256` is now deprecated and slated for removal in Python 3.19. diff --git a/Modules/socketmodule.c b/Modules/socketmodule.c index 92c9aa8b510dca..ca725b909e3809 100644 --- a/Modules/socketmodule.c +++ b/Modules/socketmodule.c @@ -5143,7 +5143,7 @@ sock_sendmsg_afalg(PyObject *s, PyObject *args, PyObject *kwds) memset(&msg, 0, sizeof(msg)); - /* op is a required, keyword-only argument >= 0 */ + /* op is a required keyword argument >= 0 */ if (opobj != NULL) { op = PyLong_AsInt(opobj); } diff --git a/Objects/typevarobject.c b/Objects/typevarobject.c index cead6e69af5451..1ad80ba49201d2 100644 --- a/Objects/typevarobject.c +++ b/Objects/typevarobject.c @@ -1443,7 +1443,7 @@ where the use of '**' creates a parameter specification::\n\ type IntFunc[**P] = Callable[P, int]\n\ \n\ The following syntax creates a parameter specification that defaults\n\ -to a callable accepting two positional-only arguments of types int\n\ +to a callable accepting two positional arguments of types int\n\ and str:\n\ \n\ type IntFuncDefault[**P = (int, str)] = Callable[P, int]\n\ diff --git a/Python/ast_unparse.c b/Python/ast_unparse.c index 557c12cfda61ff..f6e0e899ee800d 100644 --- a/Python/ast_unparse.c +++ b/Python/ast_unparse.c @@ -238,7 +238,7 @@ append_ast_args(PyUnicodeWriter *writer, arguments_ty args) first = true; - /* positional-only and positional arguments with defaults */ + /* positional-only and positional parameters with defaults */ posonlyarg_count = asdl_seq_LEN(args->posonlyargs); arg_count = asdl_seq_LEN(args->args); default_count = asdl_seq_LEN(args->defaults); @@ -260,7 +260,7 @@ append_ast_args(PyUnicodeWriter *writer, arguments_ty args) } } - /* vararg, or bare '*' if no varargs but keyword-only arguments present */ + /* vararg, or bare '*' if no varargs but keyword-only parameters present */ if (args->vararg || asdl_seq_LEN(args->kwonlyargs)) { APPEND_STR_IF_NOT_FIRST(", "); APPEND_STR("*"); @@ -269,7 +269,7 @@ append_ast_args(PyUnicodeWriter *writer, arguments_ty args) } } - /* keyword-only arguments */ + /* keyword-only parameters */ arg_count = asdl_seq_LEN(args->kwonlyargs); default_count = asdl_seq_LEN(args->kw_defaults); for (i = 0; i < arg_count; i++) { diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c index e08c63924ca16d..b1715637f0ebfc 100644 --- a/Python/bltinmodule.c +++ b/Python/bltinmodule.c @@ -2021,7 +2021,7 @@ PyDoc_STRVAR(min_doc, min(arg1, arg2, *args, *[, key=func]) -> value\n\ \n\ With a single iterable argument, return its smallest item. The\n\ -default keyword-only argument specifies an object to return if\n\ +default keyword argument specifies an object to return if\n\ the provided iterable is empty.\n\ With two or more positional arguments, return the smallest argument."); @@ -2038,7 +2038,7 @@ PyDoc_STRVAR(max_doc, max(arg1, arg2, *args, *[, key=func]) -> value\n\ \n\ With a single iterable argument, return its biggest item. The\n\ -default keyword-only argument specifies an object to return if\n\ +default keyword argument specifies an object to return if\n\ the provided iterable is empty.\n\ With two or more positional arguments, return the largest argument."); diff --git a/Python/ceval.c b/Python/ceval.c index 7aec196cb85704..af15114bbad560 100644 --- a/Python/ceval.c +++ b/Python/ceval.c @@ -1361,7 +1361,7 @@ too_many_positional(PyThreadState *tstate, PyCodeObject *co, Py_ssize_t co_argcount = co->co_argcount; assert((co->co_flags & CO_VARARGS) == 0); - /* Count missing keyword-only args. */ + /* Count missing arguments for keyword-only parameters. */ for (i = co_argcount; i < co_argcount + co->co_kwonlyargcount; i++) { if (PyStackRef_AsPyObjectBorrow(localsplus[i]) != NULL) { kwonly_given++; From 0f032ab55f9c854b686517cd83ec9e91d270d01a Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 5 Jun 2025 11:13:06 +0300 Subject: [PATCH 2/9] Fix more. --- Doc/library/configparser.rst | 6 +++--- Doc/library/inspect.rst | 21 ++++++++++----------- Doc/library/multiprocessing.rst | 2 +- Doc/tutorial/controlflow.rst | 2 +- Include/cpython/code.h | 8 ++++---- Lib/inspect.py | 9 +++++---- Misc/NEWS.d/3.10.0a4.rst | 2 +- Misc/NEWS.d/3.6.0a2.rst | 2 +- Misc/NEWS.d/3.6.4rc1.rst | 2 +- Misc/NEWS.d/3.7.0a2.rst | 2 +- Misc/NEWS.d/3.8.0b1.rst | 6 +++--- Misc/NEWS.d/3.9.0a1.rst | 4 ++-- Misc/NEWS.d/3.9.0a3.rst | 2 +- 13 files changed, 34 insertions(+), 34 deletions(-) diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index b9da8cf1a5799f..1b43adfd1f6b6e 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -1182,9 +1182,9 @@ ConfigParser Objects in the same manner as the option. .. versionchanged:: 3.2 - Arguments *raw*, *vars* and *fallback* are keyword only to protect - users from trying to use the third argument as the *fallback* fallback - (especially when using the mapping protocol). + Parameters *raw*, *vars* and *fallback* are keyword-only to protect + users from trying to use the third positional argument as the + *fallback* (especially when using the mapping protocol). .. method:: getint(section, option, *, raw=False, vars=None[, fallback]) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index b74b686715b2e7..b18a8d57aba2d5 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -172,10 +172,9 @@ attributes (see :ref:`import-mod-attrs` for module attributes): | | | references to local | | | | variables | +-----------------+-------------------+---------------------------+ -| code | co_argcount | number of arguments (not | -| | | including keyword only | -| | | arguments, \* or \*\* | -| | | args) | +| code | co_argcount | number of positional | +| | | parameters (not including | +| | | var-positional parameter) | +-----------------+-------------------+---------------------------+ | | co_code | string of raw compiled | | | | bytecode | @@ -206,12 +205,12 @@ attributes (see :ref:`import-mod-attrs` for module attributes): | | | variables (referenced via | | | | a function's closure) | +-----------------+-------------------+---------------------------+ -| | co_posonlyargcount| number of positional only | -| | | arguments | +| | co_posonlyargcount| number of positional-only | +| | | parameters | +-----------------+-------------------+---------------------------+ -| | co_kwonlyargcount | number of keyword only | -| | | arguments (not including | -| | | \*\* arg) | +| | co_kwonlyargcount | number of keyword-only | +| | | parameters (not including | +| | | var-positional parameter) | +-----------------+-------------------+---------------------------+ | | co_name | name with which this code | | | | object was defined | @@ -956,7 +955,7 @@ function. | Name | Meaning | +========================+==============================================+ | *POSITIONAL_ONLY* | Value must be supplied as a positional | - | | argument. Positional only parameters are | + | | argument. Positional-only parameters are | | | those which appear before a ``/`` entry (if | | | present) in a Python function definition. | +------------------------+----------------------------------------------+ @@ -971,7 +970,7 @@ function. | | Python function definition. | +------------------------+----------------------------------------------+ | *KEYWORD_ONLY* | Value must be supplied as a keyword argument.| - | | Keyword only parameters are those which | + | | Keyword-only parameters are those which | | | appear after a ``*`` or ``*args`` entry in a | | | Python function definition. | +------------------------+----------------------------------------------+ diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 4c240c4f86576a..6088ab88800368 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1603,7 +1603,7 @@ inherited by child processes. automatically protected by a lock, so it will not necessarily be "process-safe". - Note that *lock* is a keyword only argument. + Note that *lock* is a keyword-only parameter. Note that an array of :data:`ctypes.c_char` has *value* and *raw* attributes which allow one to use it to store and retrieve strings. diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index ae2382d8266abf..31572211792014 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -879,7 +879,7 @@ will always bind to the first parameter. For example:: TypeError: foo() got multiple values for argument 'name' >>> -But using ``/`` (positional only arguments), it is possible since it allows ``name`` as a positional argument and ``'name'`` as a key in the keyword arguments:: +But using ``/`` (positional-only parameters), it is possible since it allows ``name`` as a positional argument and ``'name'`` as a key in the keyword arguments:: >>> def foo(name, /, **kwds): ... return 'name' in kwds diff --git a/Include/cpython/code.h b/Include/cpython/code.h index 3f0dce03455526..0eef3de442353f 100644 --- a/Include/cpython/code.h +++ b/Include/cpython/code.h @@ -73,10 +73,10 @@ typedef struct { int co_flags; /* CO_..., see below */ \ \ /* The rest are not so impactful on performance. */ \ - int co_argcount; /* #arguments, except *args */ \ - int co_posonlyargcount; /* #positional only arguments */ \ - int co_kwonlyargcount; /* #keyword only arguments */ \ - int co_stacksize; /* #entries needed for evaluation stack */ \ + int co_argcount; /* # of positional parameters, except *args */ \ + int co_posonlyargcount; /* # of positional-only parameters */ \ + int co_kwonlyargcount; /* # of keyword-only parameters, except **kwargs */ \ + int co_stacksize; /* # of entries needed for evaluation stack */ \ int co_firstlineno; /* first source line number */ \ \ /* redundant values (derived from co_localsplusnames and \ diff --git a/Lib/inspect.py b/Lib/inspect.py index 2b416793917b59..8475b9f632bde1 100644 --- a/Lib/inspect.py +++ b/Lib/inspect.py @@ -401,8 +401,8 @@ def iscode(object): """Return true if the object is a code object. Code objects provide these attributes: - co_argcount number of arguments (not including *, ** args - or keyword only arguments) + co_argcount number of positional parameters (not including + var-positional parameter) co_code string of raw compiled bytecode co_cellvars tuple of names of cell variables co_consts tuple of constants used in the bytecode @@ -413,8 +413,9 @@ def iscode(object): | 256=iterable_coroutine | 512=async_generator | 0x4000000=has_docstring co_freevars tuple of names of free variables - co_posonlyargcount number of positional only arguments - co_kwonlyargcount number of keyword only arguments (not including ** arg) + co_posonlyargcount number of positional-only parameters + co_kwonlyargcount number of keyword-only parameters (not including + var-keyword parameter) co_lnotab encoded mapping of line numbers to bytecode indices co_name name with which this code object was defined co_names tuple of names other than arguments and function locals diff --git a/Misc/NEWS.d/3.10.0a4.rst b/Misc/NEWS.d/3.10.0a4.rst index 19f0db9a6be5e9..cc733118c81cf1 100644 --- a/Misc/NEWS.d/3.10.0a4.rst +++ b/Misc/NEWS.d/3.10.0a4.rst @@ -432,7 +432,7 @@ and the last exception was always silently ignored. .. nonce: qdEtZv .. section: Library -Fixed lib2to3.pgen2 to be able to parse PEP-570 positional only argument +Fixed lib2to3.pgen2 to be able to parse PEP-570 positional-only parameter syntax. .. diff --git a/Misc/NEWS.d/3.6.0a2.rst b/Misc/NEWS.d/3.6.0a2.rst index 89d68ab3f8078f..a29b37bdb6a752 100644 --- a/Misc/NEWS.d/3.6.0a2.rst +++ b/Misc/NEWS.d/3.6.0a2.rst @@ -484,7 +484,7 @@ lot of small objects. .. nonce: bHIfFA .. section: Library -New keyword only parameters in reset_mock call. +New keyword-only parameters in :meth:`!reset_mock` call. .. diff --git a/Misc/NEWS.d/3.6.4rc1.rst b/Misc/NEWS.d/3.6.4rc1.rst index afa5b8b0efb148..6dff17dd8a206a 100644 --- a/Misc/NEWS.d/3.6.4rc1.rst +++ b/Misc/NEWS.d/3.6.4rc1.rst @@ -1039,7 +1039,7 @@ of browsing python files that do not end in .py. .. nonce: LxN4Vb .. section: IDLE -IDLE - Make _htest, _utest parameters keyword only. +IDLE - Make _htest, _utest parameters keyword-only. .. diff --git a/Misc/NEWS.d/3.7.0a2.rst b/Misc/NEWS.d/3.7.0a2.rst index a1ff8b8354bd9a..28dd2675d860a7 100644 --- a/Misc/NEWS.d/3.7.0a2.rst +++ b/Misc/NEWS.d/3.7.0a2.rst @@ -606,7 +606,7 @@ of browsing python files that do not end in .py. .. nonce: LxN4Vb .. section: IDLE -IDLE - Make _htest, _utest parameters keyword only. +IDLE - Make _htest, _utest parameters keyword-only. .. diff --git a/Misc/NEWS.d/3.8.0b1.rst b/Misc/NEWS.d/3.8.0b1.rst index f6ee2d6b667b7d..b481bb381a032d 100644 --- a/Misc/NEWS.d/3.8.0b1.rst +++ b/Misc/NEWS.d/3.8.0b1.rst @@ -58,7 +58,7 @@ Pablo Galindo. Make the *co_argcount* attribute of code objects represent the total number of positional parameters (including positional-only parameters). The value of *co_posonlyargcount* can be used to distinguish which parameters are -positional only, and the difference (*co_argcount* - *co_posonlyargcount*) +positional-only, and the difference (*co_argcount* - *co_posonlyargcount*) is the number of positional-or-keyword parameters. Patch by Pablo Galindo. .. @@ -768,7 +768,7 @@ Taskaya .. nonce: u7cxu7 .. section: Library -PDB command ``args`` now display positional only arguments. Patch contributed +PDB command ``args`` now also displays values of positional-only parameters. Patch contributed by Rémi Lapeyre. .. @@ -778,7 +778,7 @@ by Rémi Lapeyre. .. nonce: JkZORP .. section: Library -PDB command ``args`` now display keyword only arguments. Patch contributed by +PDB command ``args`` now also displays values of keyword-only parameters. Patch contributed by Rémi Lapeyre. .. diff --git a/Misc/NEWS.d/3.9.0a1.rst b/Misc/NEWS.d/3.9.0a1.rst index be337fb3e318d3..45e1cf17e82608 100644 --- a/Misc/NEWS.d/3.9.0a1.rst +++ b/Misc/NEWS.d/3.9.0a1.rst @@ -2791,9 +2791,9 @@ Abhilash Raj. .. nonce: RUcxaK .. section: Library -The *dist* argument for statistics.quantiles() is now positional only. The +The *dist* parameter in :finc:`statistics.quantiles` is now positional-only. The current name doesn't reflect that the argument can be either a dataset or a -distribution. Marking the parameter as positional avoids confusion and +distribution. Marking the parameter as positional-only avoids confusion and makes it possible to change the name later. .. diff --git a/Misc/NEWS.d/3.9.0a3.rst b/Misc/NEWS.d/3.9.0a3.rst index 78194791ab5277..cd36c0810feb19 100644 --- a/Misc/NEWS.d/3.9.0a3.rst +++ b/Misc/NEWS.d/3.9.0a3.rst @@ -128,7 +128,7 @@ Port _json extension module to multiphase initialization (:pep:`489`). .. nonce: 74jLh9 .. section: Core and Builtins -Fix constant folding optimization for positional only arguments - by Anthony +Fix constant folding optimization for positional-only parameters - by Anthony Sottile. .. From 7246fcf3df0b306924e70193ed7e4a0d6b4f30f4 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 5 Jun 2025 13:00:14 +0300 Subject: [PATCH 3/9] Fix typo. --- Misc/NEWS.d/3.9.0a1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/3.9.0a1.rst b/Misc/NEWS.d/3.9.0a1.rst index 45e1cf17e82608..a47715d868f571 100644 --- a/Misc/NEWS.d/3.9.0a1.rst +++ b/Misc/NEWS.d/3.9.0a1.rst @@ -2791,7 +2791,7 @@ Abhilash Raj. .. nonce: RUcxaK .. section: Library -The *dist* parameter in :finc:`statistics.quantiles` is now positional-only. The +The *dist* parameter in :func:`statistics.quantiles` is now positional-only. The current name doesn't reflect that the argument can be either a dataset or a distribution. Marking the parameter as positional-only avoids confusion and makes it possible to change the name later. From 8516800d6cfe67dd88bd7fdecb50b6e2f26d2257 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 5 Jun 2025 18:02:45 +0300 Subject: [PATCH 4/9] Apply suggestions from code review Co-authored-by: Jelle Zijlstra Co-authored-by: Petr Viktorin --- Doc/c-api/arg.rst | 2 +- Doc/library/ast.rst | 4 ++-- Doc/library/shutil.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 7b38629f8cb632..209e6b471381a6 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -506,7 +506,7 @@ API Functions .. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...) - Parse the argument of a function that takes a single positional parameter + Parse the argument of a function that takes a single positional argument into a local variable. Returns true on success; on failure, it returns false and raises the appropriate exception. diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 56fd6c257fc549..2fc0125e0bfa68 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1938,8 +1938,8 @@ Function and class definitions * ``kw_defaults`` is a list of default values for keyword-only parameters. If one is ``None``, the corresponding argument is required. * ``defaults`` is a list of default values for positional-only and - keyword-or-positional parameter. - If there are fewer defaults, they correspond to the last n + keyword-or-positional parameters. + If there are fewer defaults, they correspond to the last *n* parameters. diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 4afa53d1dc97bd..f71957845133fa 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -712,7 +712,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. registered for that extension. In case none is found, a :exc:`ValueError` is raised. - The keyword *filter* argument is passed to the underlying unpacking + The keyword argument *filter* is passed to the underlying unpacking function. For zip files, *filter* is not accepted. For tar files, it is recommended to use ``'data'`` (default since Python 3.14), unless using features specific to tar and UNIX-like filesystems. From 4f33f9e944360f16df4a5ea032266ae9e38d2ca3 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 5 Jun 2025 18:03:43 +0300 Subject: [PATCH 5/9] Minor fixes. --- Doc/library/inspect.rst | 2 +- Doc/library/stdtypes.rst | 4 ++-- Doc/whatsnew/2.5.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index b18a8d57aba2d5..f075487892eee7 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -210,7 +210,7 @@ attributes (see :ref:`import-mod-attrs` for module attributes): +-----------------+-------------------+---------------------------+ | | co_kwonlyargcount | number of keyword-only | | | | parameters (not including | -| | | var-positional parameter) | +| | | var-keyword parameter) | +-----------------+-------------------+---------------------------+ | | co_name | name with which this code | | | | object was defined | diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index fb904ce6b8813b..64907415319c6b 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1339,8 +1339,8 @@ application). fail, the entire sort operation will fail (and the list will likely be left in a partially modified state). - :meth:`sort` accepts two arguments that can only be passed by keyword - (:ref:`keyword-only parameters `): + :meth:`sort` accepts two arguments that can + :ref:`only be passed by keyword `: *key* specifies a function of one argument that is used to extract a comparison key from each list element (for example, ``key=str.lower``). diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 639bf97be8b322..26198786762b91 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1358,7 +1358,7 @@ complete list of changes, or look through the SVN logs for all the details. :func:`gc.collect` function now takes an optional *generation* argument of 0, 1, or 2 to specify which generation to collect. (Contributed by Barry Warsaw.) -* The :func:`nsmallest` and :func:`nlargest` functions in the :mod:`heapq` +* The :func:`~heapq.nsmallest` and :func:`~heapq.nlargest` functions in the :mod:`heapq` module now support a ``key`` keyword argument similar to the one provided by the :func:`min`/:func:`max` functions and the :meth:`sort` methods. For example:: From e97232ac8343d7509443c9c2d31f5b727c808769 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 6 Jun 2025 00:36:42 +0300 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: Terry Jan Reedy --- Doc/c-api/veryhigh.rst | 2 +- Doc/library/ast.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 445de33490b597..63e5720ba16882 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -267,7 +267,7 @@ the same library that the Python runtime is using. evaluation. This environment consists of a dictionary of global variables, a mapping object of local variables, arrays of arguments, keywords and defaults, a dictionary of default values for :ref:`keyword-only - ` parameters and a closure tuple of cells. + ` parameters, and a closure tuple of cells. .. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 2fc0125e0bfa68..b4c20e9ce70187 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1930,16 +1930,16 @@ Function and class definitions .. class:: arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults) - The parameters for a function. + The parameters for the defined function. * ``posonlyargs``, ``args`` and ``kwonlyargs`` are lists of :class:`arg` nodes. * ``vararg`` and ``kwarg`` are single :class:`arg` nodes, referring to the ``*args, **kwargs`` parameters. - * ``kw_defaults`` is a list of default values for keyword-only parameters. If + * ``kw_defaults`` is the list of default values for keyword-only parameters. If one is ``None``, the corresponding argument is required. - * ``defaults`` is a list of default values for positional-only and + * ``defaults`` is the list of default values for positional-only and keyword-or-positional parameters. - If there are fewer defaults, they correspond to the last *n* + If there are fewer defaults than there are such parameters, the defaults correspond to the last *n* parameters. From 86550eb02700c26d6b39db5e9904fefc5e7ad653 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 6 Jun 2025 00:37:55 +0300 Subject: [PATCH 7/9] Apply suggestions from code review --- Doc/howto/logging-cookbook.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 65844a797d5da1..cc1e5239eb2a58 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -1675,7 +1675,7 @@ That can still use %-formatting, as shown here:: >>> Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take -positional arguments for the actual logging message itself, with keyword +positional arguments for the logging message itself, with keyword arguments used only for determining options for how to handle the actual logging call (e.g. the ``exc_info`` keyword argument to indicate that traceback information should be logged, or the ``extra`` keyword argument @@ -2732,7 +2732,7 @@ governs the formatting of logging messages for final output to logs, and is completely orthogonal to how an individual logging message is constructed. Logging calls (:meth:`~Logger.debug`, :meth:`~Logger.info` etc.) only take -positional arguments for the actual logging message itself, with keyword +positional arguments for the logging message itself, with keyword arguments used only for determining options for how to handle the logging call (e.g. the ``exc_info`` keyword argument to indicate that traceback information should be logged, or the ``extra`` keyword argument to indicate additional From b8c621c7455ec6ff0c72268dd09b726ef472a047 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 6 Jun 2025 11:05:33 +0300 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Terry Jan Reedy --- Doc/whatsnew/2.5.rst | 2 +- Doc/whatsnew/3.4.rst | 2 +- Doc/whatsnew/3.6.rst | 2 +- Doc/whatsnew/3.7.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 26198786762b91..8be6a76d827d26 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1359,7 +1359,7 @@ complete list of changes, or look through the SVN logs for all the details. or 2 to specify which generation to collect. (Contributed by Barry Warsaw.) * The :func:`~heapq.nsmallest` and :func:`~heapq.nlargest` functions in the :mod:`heapq` - module now support a ``key`` keyword argument similar to the one provided by + module now support a ``key`` keyword argument similar to the one provided by the :func:`min`/:func:`max` functions and the :meth:`sort` methods. For example:: diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index c96db90b48c56f..982d92609627a8 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -403,7 +403,7 @@ Some smaller changes made to the core Python language are: * Unicode database updated to UCD version 6.3. -* :func:`min` and :func:`max` now accept a *default* keyword argument that +* :func:`min` and :func:`max` now accept a keyword argument *default* that can be used to specify the value they return if the iterable they are evaluating has no elements. (Contributed by Julian Berman in :issue:`18111`.) diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index 4a271f2d5a92d2..28370ec0bcf778 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -1664,7 +1664,7 @@ The :class:`~unittest.mock.Mock` class has the following improvements: (Contributed by Amit Saha in :issue:`26323`.) * The :meth:`Mock.reset_mock() ` method - now support two optional keyword arguments: *return_value* and + now supports two optional keyword arguments: *return_value* and *side_effect*. (Contributed by Kushal Das in :issue:`21271`.) diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 65d68c3b91ade5..807d09b9495475 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -1198,7 +1198,7 @@ on POSIX systems and can be used to determine whether a path is a mount point. pdb --- -:func:`pdb.set_trace` now takes an optional keyword argument *header*. +:func:`pdb.set_trace` now takes optional keyword argument *header*. If given, it is printed to the console just before debugging begins. (Contributed by Barry Warsaw in :issue:`31389`.) From a6ac9e5a46ba1383feb23af1f09bf66bb997b1e9 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 8 Jun 2025 12:41:43 +0300 Subject: [PATCH 9/9] iFix some references. --- Doc/whatsnew/2.5.rst | 4 ++-- Doc/whatsnew/2.6.rst | 20 ++++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 8be6a76d827d26..302fe1d0bbe92c 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1685,9 +1685,9 @@ provides functions for loading shared libraries and calling functions in them. The :mod:`ctypes` package is much fancier. To load a shared library or DLL, you must create an instance of the -:class:`CDLL` class and provide the name or path of the shared library or DLL. +:class:`~ctypes.CDLL` class and provide the name or path of the shared library or DLL. Once that's done, you can call arbitrary functions by accessing them as -attributes of the :class:`CDLL` object. :: +attributes of the :class:`!CDLL` object. :: import ctypes diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 30016e93ec553a..397f1829fc077b 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -2851,11 +2851,11 @@ where various combinations of ``(start, stop, step)`` are supplied. .. Revision 57769 All :mod:`ctypes` data types now support -:meth:`from_buffer` and :meth:`from_buffer_copy` +:meth:`~ctypes._CData.from_buffer` and :meth:`~ctypes._CData.from_buffer_copy` methods that create a ctypes instance based on a -provided buffer object. :meth:`from_buffer_copy` copies +provided buffer object. :meth:`!from_buffer_copy` copies the contents of the object, -while :meth:`from_buffer` will share the same memory area. +while :meth:`!from_buffer` will share the same memory area. A new calling convention tells :mod:`ctypes` to clear the ``errno`` or Win32 LastError variables at the outset of each wrapped call. @@ -2863,17 +2863,17 @@ Win32 LastError variables at the outset of each wrapped call. You can now retrieve the Unix ``errno`` variable after a function call. When creating a wrapped function, you can supply -``use_errno=True`` as a keyword argument to the :func:`DLL` function -and then call the module-level methods :meth:`set_errno` and -:meth:`get_errno` to set and retrieve the error value. +``use_errno=True`` as a keyword argument to the :func:`~ctypes.DLL` function +and then call the module-level methods :func:`~ctypes.set_errno` and +:func:`~ctypes.get_errno` to set and retrieve the error value. The Win32 LastError variable is similarly supported by -the :func:`DLL`, :func:`OleDLL`, and :func:`WinDLL` functions. +the :func:`~ctypes.DLL`, :func:`~ctypes.OleDLL`, and :func:`~ctypes.WinDLL` functions. You supply ``use_last_error=True`` as a keyword argument -and then call the module-level methods :meth:`set_last_error` -and :meth:`get_last_error`. +and then call the module-level methods :func:`~ctypes.set_last_error` +and :func:`~ctypes.get_last_error`. -The :func:`byref` function, used to retrieve a pointer to a ctypes +The :func:`~ctypes.byref` function, used to retrieve a pointer to a ctypes instance, now has an optional *offset* argument that is a byte count that will be added to the returned pointer.