From ba0965b1c41d184928526d9a050cd2beba189ea0 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Mon, 23 Sep 2024 02:08:03 -0700 Subject: [PATCH 1/2] [3.12] GH-79714: Add mention of stderr for clarity to ArgumentParser.exit() (GH-123932) (cherry picked from commit 5f5c0b9c23238dc0a1fdb764f625ae0cc5604519) Co-authored-by: Savannah Ostrowski --- Doc/library/argparse.rst | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index b7ed3f5e7cb5f2..495aa6c7c32d9e 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1439,6 +1439,34 @@ behavior:: >>> parser.parse_args('--foo XXX'.split()) Namespace(bar='XXX') + +.. _deprecated: + +deprecated +^^^^^^^^^^ + +During a project's lifetime, some arguments may need to be removed from the +command line. Before removing them, you should inform +your users that the arguments are deprecated and will be removed. +The ``deprecated`` keyword argument of +:meth:`~ArgumentParser.add_argument`, which defaults to ``False``, +specifies if the argument is deprecated and will be removed +in the future. +For arguments, if ``deprecated`` is ``True``, then a warning will be +printed to :data:`sys.stderr` when the argument is used:: + + >>> import argparse + >>> parser = argparse.ArgumentParser(prog='snake.py') + >>> parser.add_argument('--legs', default=0, type=int, deprecated=True) + >>> parser.parse_args([]) + Namespace(legs=0) + >>> parser.parse_args(['--legs', '4']) # doctest: +SKIP + snake.py: warning: option '--legs' is deprecated + Namespace(legs=4) + +.. versionadded:: 3.13 + + Action classes ^^^^^^^^^^^^^^ @@ -2190,8 +2218,8 @@ Exiting methods .. method:: ArgumentParser.exit(status=0, message=None) This method terminates the program, exiting with the specified *status* - and, if given, it prints a *message* before that. The user can override - this method to handle these steps differently:: + and, if given, it prints a *message* to :data:`sys.stderr` before that. + The user can override this method to handle these steps differently:: class ErrorCatchingArgumentParser(argparse.ArgumentParser): def exit(self, status=0, message=None): @@ -2201,8 +2229,8 @@ Exiting methods .. method:: ArgumentParser.error(message) - This method prints a usage message including the *message* to the - standard error and terminates the program with a status code of 2. + This method prints a usage message, including the *message*, to + :data:`sys.stderr` and terminates the program with a status code of 2. Intermixed parsing From e99cfc2374faf397baeda4ff8f32d3b63289754f Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Mon, 23 Sep 2024 11:24:09 -0700 Subject: [PATCH 2/2] remove deprecated --- Doc/library/argparse.rst | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 495aa6c7c32d9e..82f11e1b9aad6d 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1439,34 +1439,6 @@ behavior:: >>> parser.parse_args('--foo XXX'.split()) Namespace(bar='XXX') - -.. _deprecated: - -deprecated -^^^^^^^^^^ - -During a project's lifetime, some arguments may need to be removed from the -command line. Before removing them, you should inform -your users that the arguments are deprecated and will be removed. -The ``deprecated`` keyword argument of -:meth:`~ArgumentParser.add_argument`, which defaults to ``False``, -specifies if the argument is deprecated and will be removed -in the future. -For arguments, if ``deprecated`` is ``True``, then a warning will be -printed to :data:`sys.stderr` when the argument is used:: - - >>> import argparse - >>> parser = argparse.ArgumentParser(prog='snake.py') - >>> parser.add_argument('--legs', default=0, type=int, deprecated=True) - >>> parser.parse_args([]) - Namespace(legs=0) - >>> parser.parse_args(['--legs', '4']) # doctest: +SKIP - snake.py: warning: option '--legs' is deprecated - Namespace(legs=4) - -.. versionadded:: 3.13 - - Action classes ^^^^^^^^^^^^^^