From e6c53dd08535076fc60e9295bf46a2b7e615e2f3 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Wed, 11 Oct 2023 22:47:38 +0200
Subject: [PATCH] [3.12] gh-108826: Document `dis` module CLI and rename
 `_test` function to `main` (#108827) (#110681)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: Radislav Chugunov <52372310+chgnrdv@users.noreply.github.com>
---
 Doc/library/asyncio.rst                       |  2 +
 Doc/library/cmdline.rst                       | 57 +++++++++++++++++++
 Doc/library/compileall.rst                    |  2 +
 Doc/library/dis.rst                           | 22 +++++++
 Doc/library/gzip.rst                          |  2 +
 Doc/library/index.rst                         |  1 +
 Doc/library/pickletools.rst                   |  2 +
 Doc/library/profile.rst                       |  2 +
 Doc/library/py_compile.rst                    |  1 +
 Doc/library/sysconfig.rst                     |  1 +
 Lib/dis.py                                    |  5 +-
 ...-09-03-13-43-49.gh-issue-108826.KG7abS.rst |  1 +
 12 files changed, 95 insertions(+), 3 deletions(-)
 create mode 100644 Doc/library/cmdline.rst
 create mode 100644 Misc/NEWS.d/next/Documentation/2023-09-03-13-43-49.gh-issue-108826.KG7abS.rst

diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
index c6a046f534e9a1..c75ab47404c1e4 100644
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -56,6 +56,8 @@ Additionally, there are **low-level** APIs for
 * :ref:`bridge <asyncio-futures>` callback-based libraries and code
   with async/await syntax.
 
+.. _asyncio-cli:
+
 You can experiment with an ``asyncio`` concurrent context in the REPL:
 
 .. code-block:: pycon
diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
new file mode 100644
index 00000000000000..b2379befeffcba
--- /dev/null
+++ b/Doc/library/cmdline.rst
@@ -0,0 +1,57 @@
+++++++++++++++++++++++++++++++++++++
+Modules command-line interface (CLI)
+++++++++++++++++++++++++++++++++++++
+
+The following modules have a command-line interface.
+
+* :ref:`ast <ast-cli>`
+* :ref:`asyncio <asyncio-cli>`
+* :mod:`base64`
+* :ref:`calendar <calendar-cli>`
+* :mod:`code`
+* :ref:`compileall <compileall-cli>`
+* :mod:`cProfile`: see :ref:`profile <profile-cli>`
+* :ref:`difflib <difflib-interface>`
+* :ref:`dis <dis-cli>`
+* :mod:`doctest`
+* :mod:`!encodings.rot_13`
+* :mod:`ensurepip`
+* :mod:`filecmp`
+* :mod:`fileinput`
+* :mod:`ftplib`
+* :ref:`gzip <gzip-cli>`
+* :ref:`http.server <http-server-cli>`
+* :mod:`!idlelib`
+* :ref:`inspect <inspect-module-cli>`
+* :ref:`json.tool <json-commandline>`
+* :mod:`mimetypes`
+* :mod:`pdb`
+* :mod:`pickle`
+* :ref:`pickletools <pickletools-cli>`
+* :mod:`platform`
+* :mod:`poplib`
+* :ref:`profile <profile-cli>`
+* :mod:`pstats`
+* :ref:`py_compile <py_compile-cli>`
+* :mod:`pyclbr`
+* :mod:`pydoc`
+* :mod:`quopri`
+* :mod:`runpy`
+* :ref:`site <site-commandline>`
+* :ref:`sqlite3 <sqlite3-cli>`
+* :ref:`sysconfig <sysconfig-cli>`
+* :mod:`tabnanny`
+* :ref:`tarfile <tarfile-commandline>`
+* :mod:`!this`
+* :ref:`timeit <timeit-command-line-interface>`
+* :ref:`tokenize <tokenize-cli>`
+* :ref:`trace <trace-cli>`
+* :mod:`turtledemo`
+* :ref:`unittest <unittest-command-line-interface>`
+* :ref:`uuid <uuid-cli>`
+* :mod:`venv`
+* :mod:`webbrowser`
+* :ref:`zipapp <zipapp-command-line-interface>`
+* :ref:`zipfile <zipfile-commandline>`
+
+See also the :ref:`Python command-line interface <using-on-general>`.
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index a1482c9eb889e8..6d16734ddca21e 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -16,6 +16,8 @@ have write permission to the library directories.
 
 .. include:: ../includes/wasm-notavail.rst
 
+.. _compileall-cli:
+
 Command-line use
 ----------------
 
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index b559b085aa728b..ef016c1fc00a5d 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -63,6 +63,28 @@ the following command can be used to display the disassembly of
 
 (The "2" is a line number).
 
+.. _dis-cli:
+
+Command-line interface
+----------------------
+
+The :mod:`dis` module can be invoked as a script from the command line:
+
+.. code-block:: sh
+
+   python -m dis [-h] [infile]
+
+The following options are accepted:
+
+.. program:: dis
+
+.. cmdoption:: -h, --help
+
+   Display usage and exit.
+
+If :file:`infile` is specified, its disassembled code will be written to stdout.
+Otherwise, disassembly is performed on compiled source code recieved from stdin.
+
 Bytecode analysis
 -----------------
 
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 7c871048b43948..f931d0e399c9f2 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -250,6 +250,8 @@ Example of how to GZIP compress a binary string::
 
 .. program:: gzip
 
+.. _gzip-cli:
+
 Command Line Interface
 ----------------------
 
diff --git a/Doc/library/index.rst b/Doc/library/index.rst
index d064b680f9aaa4..0b348ae6f5c8c0 100644
--- a/Doc/library/index.rst
+++ b/Doc/library/index.rst
@@ -73,5 +73,6 @@ the `Python Package Index <https://pypi.org>`_.
    language.rst
    windows.rst
    unix.rst
+   cmdline.rst
    superseded.rst
    security_warnings.rst
diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst
index c6ff4e6ed3d3b5..41930f8cbe8412 100644
--- a/Doc/library/pickletools.rst
+++ b/Doc/library/pickletools.rst
@@ -17,6 +17,8 @@ are useful for Python core developers who are working on the :mod:`pickle`;
 ordinary users of the :mod:`pickle` module probably won't find the
 :mod:`pickletools` module relevant.
 
+.. _pickletools-cli:
+
 Command line usage
 ------------------
 
diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst
index 723f927135a0f4..69274b0c354a25 100644
--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
@@ -121,6 +121,8 @@ results to a file by specifying a filename to the :func:`run` function::
 The :class:`pstats.Stats` class reads profile results from a file and formats
 them in various ways.
 
+.. _profile-cli:
+
 The files :mod:`cProfile` and :mod:`profile` can also be invoked as a script to
 profile another script.  For example::
 
diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst
index 7272f36d9a5568..38c416f9ad0305 100644
--- a/Doc/library/py_compile.rst
+++ b/Doc/library/py_compile.rst
@@ -125,6 +125,7 @@ byte-code cache files in the directory containing the source code.
       This option is useful when the ``.pycs`` are kept up to date by some
       system external to Python like a build system.
 
+.. _py_compile-cli:
 
 Command-Line Interface
 ----------------------
diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst
index e5ed45b8529a57..905abc3a7c9f9b 100644
--- a/Doc/library/sysconfig.rst
+++ b/Doc/library/sysconfig.rst
@@ -427,6 +427,7 @@ Other functions
 
    Return the path of :file:`Makefile`.
 
+.. _sysconfig-cli:
 
 Using :mod:`sysconfig` as a script
 ----------------------------------
diff --git a/Lib/dis.py b/Lib/dis.py
index 3a8e6ac3bf5ace..320dec03d25b0c 100644
--- a/Lib/dis.py
+++ b/Lib/dis.py
@@ -790,8 +790,7 @@ def dis(self):
             return output.getvalue()
 
 
-def _test():
-    """Simple test program to disassemble a file."""
+def main():
     import argparse
 
     parser = argparse.ArgumentParser()
@@ -803,4 +802,4 @@ def _test():
     dis(code)
 
 if __name__ == "__main__":
-    _test()
+    main()
diff --git a/Misc/NEWS.d/next/Documentation/2023-09-03-13-43-49.gh-issue-108826.KG7abS.rst b/Misc/NEWS.d/next/Documentation/2023-09-03-13-43-49.gh-issue-108826.KG7abS.rst
new file mode 100644
index 00000000000000..139b8f3457930c
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2023-09-03-13-43-49.gh-issue-108826.KG7abS.rst
@@ -0,0 +1 @@
+:mod:`dis` module command-line interface is now mentioned in documentation.