Will leave this open for a while so that many people can comment on the proposal before we act on it.

My initial take is:

* Having a way to deprecate seems useful.

* In practice, I haven't seen this done very much (in big tooling such as GCC perhaps, but everyday command-line tools don't seem to do this AFAICT).

* The warnings module is likely not the right implementation tool.  The warnings module doesn't make as much sense for CLIs as it does for libraries.  In particular, the warnings module is all about the ability of consumer code to filter, ignore, or escalate warnings.  Also, we've so far been good about minimizing inter-module dependencies so that start-up time remains fast.

* The PR is aggressive in providing *deprecated*, *deprecated_reason*, and *deprecated_pending*.  Perhaps a simpler hook or flag would suffice.  The overall module API is already large enough to be a barrier to learning all the features.

* There is some question as to whether this belongs in argparse at all or whether it should be in downstream, post-parsing logic.  For example:

    parser.add_argument('--throw', action='store_true',
             help = '(deprecated use "toss" instead) causes ball to move')
    ...
    args = parser.parse_args()
    if args.throw:
         print('"throw" has been deprecated, use "toss" instead',
               file=sys.stderr)