The documentation for optparse states it has been deprecated in favor of argparse since 2.7. However, the library documentation for difflib still uses optparse in the example.

https://docs.python.org/2/library/difflib.html#a-command-line-interface-to-difflib

https://docs.python.org/3.5/library/difflib.html#a-command-line-interface-to-difflib

I am willing to update the documentation if there is agreement that it is needed.

It wouldn't be a bad idea.  Of course, you'd also need to update Tools/script/diff.py.  Tests should be added as well, since we have started adding tests for things in Tools.   The tests should be written first, to make sure that the behavior of 'diff' does not change, since I know there are people actively using it (on Windows).

I think it would also be a good idea to change the docs so that the actual diff script is embedded in the docs (sphinx has a directive for doing that), rather that duplicating the code.

I took a look at Tools/scripts/diff.py and it looks like it got converted to use argparse 9 months ago. I think I should be able to just include that in the difflib documentation directly.

My next question is which branches need to have this changed? Do I just make the documentation change to the default branch or do I need to change it in 2.7, 3.2, 3.3, and 3.4 as well?

Here is the patch. I have tested it against tip. Let me know if you need anything else.

Since the Tools script was only changed in 3.5 (I was looking at the wrong branch), I think the docs should only be changed for 3.5.

New changeset 8777e59a99bd by Berker Peksag in branch '3.5':
Issue #24109: Include Tools/scripts/diff.py instead of duplicating it in difflib documentation.
https://hg.python.org/cpython/rev/8777e59a99bd

New changeset aa2517e9f9ce by Berker Peksag in branch 'default':
Issue #24109: Include Tools/scripts/diff.py instead of duplicating it in difflib documentation.
https://hg.python.org/cpython/rev/aa2517e9f9ce

Thanks Keith.