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

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>

diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
index 4a295e069287d87cf910a1541144230d46dcb3e7..b2379befeffcbab2b09d50cc307ca28305fb1c3f 100644 (file)
--- 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
index b835f1ea2b0090aea526771a3980e846a9a7e8cc..1f773b7b337fa36e2326fdf8216a1b519fcc27e0 100644 (file)
--- 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
index 633c01b6fce56aea3017240b14db2194e0482a56..cad62b95990c3073c0b446af6755d6f636266efc 100644 (file)
--- a/Lib/dis.py
+++ b/Lib/dis.py
@@ -896,8 +896,7 @@ class Bytecode:
             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
new file mode 100644 (file)
index 0000000..139b8f3
--- /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.