gh-108826: Document dis module CLI and rename _test function to main (#108827)

chgnrdv · hugovk · blurb-it[bot] · web-flow · commit 0d805b998ded · 2023-10-10T16:31:28.000-06:00
Co-authored-by: Hugo van Kemenade &lt;hugovk@users.noreply.github.com&gt;
Co-authored-by: blurb-it[bot] &lt;43283697+blurb-it[bot]@users.noreply.github.com&gt;
diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
@@ -12,7 +12,7 @@ The following modules have a command-line interface.
 * :ref:`compileall <compileall-cli>`
 * :mod:`cProfile`: see :ref:`profile <profile-cli>`
 * :ref:`difflib <difflib-interface>`
-* :mod:`dis`
+* :ref:`dis <dis-cli>`
 * :mod:`doctest`
 * :mod:`!encodings.rot_13`
 * :mod:`ensurepip`
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
@@ -63,6 +63,32 @@ 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] [-C] [infile]
+
+The following options are accepted:
+
+.. program:: dis
+
+.. cmdoption:: -h, --help
+
+   Display usage and exit.
+
+.. cmdoption:: -C, --show-caches
+
+   Show inline caches.
+
+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/Lib/dis.py b/Lib/dis.py
@@ -896,8 +896,7 @@ def dis(self):
             return output.getvalue()
 
 
-def _test():
-    """Simple test program to disassemble a file."""
+def main():
     import argparse
 
     parser = argparse.ArgumentParser()
@@ -911,4 +910,4 @@ def _test():
     dis(code, show_caches=args.show_caches)
 
 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
@@ -0,0 +1 @@
+:mod:`dis` module command-line interface is now mentioned in documentation.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+:mod:`dis` module command-line interface is now mentioned in documentation.