[3.12] GH-79714: Add mention of stderr for clarity to ArgumentParser.…

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