From 26b376742bdf85f9e568baf57bdce75cf05ec2e8 Mon Sep 17 00:00:00 2001
From: Radislav Chugunov <52372310+chgnrdv@users.noreply.github.com>
Date: Wed, 11 Oct 2023 01:31:28 +0300
Subject: [PATCH] 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>
---
 Doc/library/cmdline.rst                       |  2 +-
 Doc/library/dis.rst                           | 26 +++++++++++++++++++
 Lib/dis.py                                    |  5 ++--
 ...-09-03-13-43-49.gh-issue-108826.KG7abS.rst |  1 +
 4 files changed, 30 insertions(+), 4 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2023-09-03-13-43-49.gh-issue-108826.KG7abS.rst

diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
index 4a295e069287d87..b2379befeffcbab 100644
--- 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 b835f1ea2b0090a..1f773b7b337fa36 100644
--- 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 633c01b6fce56ae..cad62b95990c307 100644
--- 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
new file mode 100644
index 000000000000000..139b8f3457930c3
--- /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.