From 4506bbede1644e985991884964b43afa7ee6f609 Mon Sep 17 00:00:00 2001
From: Mark Shannon <mark@hotpy.org>
Date: Thu, 16 Dec 2021 13:40:54 +0000
Subject: bpo-46072: Document --enable-stats option. (GH-30139)

---
 Doc/using/configure.rst                         | 11 +++++
 Tools/scripts/summarize_specialization_stats.py | 53 -------------------------
 Tools/scripts/summarize_stats.py                | 53 +++++++++++++++++++++++++
 3 files changed, 64 insertions(+), 53 deletions(-)
 delete mode 100644 Tools/scripts/summarize_specialization_stats.py
 create mode 100644 Tools/scripts/summarize_stats.py

diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index b2a2936db7..771ad3cf18 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -131,6 +131,17 @@ General Options
 
    .. versionadded:: 3.11
 
+.. cmdoption:: --enable-pystats
+
+   Turn on internal statistics gathering.
+
+   The statistics will be dumped to a arbitrary (probably unique) file in
+   ``/tmp/py_stats/``, or ``C:\temp\py_stats\`` on Windows.
+
+   Use ``Tools//summarize_stats.py`` to read the stats.
+
+   .. versionadded:: 3.11
+
 
 Install Options
 ---------------
diff --git a/Tools/scripts/summarize_specialization_stats.py b/Tools/scripts/summarize_specialization_stats.py
deleted file mode 100644
index 15b1887415..0000000000
--- a/Tools/scripts/summarize_specialization_stats.py
+++ /dev/null
@@ -1,53 +0,0 @@
-"""Print a summary of specialization stats for all files in the
-default stats folders.
-"""
-
-import collections
-import os.path
-
-if os.name == "nt":
-    DEFAULT_DIR = "c:\\temp\\py_stats\\"
-else:
-    DEFAULT_DIR = "/tmp/py_stats/"
-
-
-TOTAL = "deferred", "hit", "miss", "unquickened"
-
-def print_stats(name, family_stats):
-    total = sum(family_stats[kind] for kind in TOTAL)
-    if total == 0:
-        return
-    print(name+":")
-    for key in sorted(family_stats):
-        if not key.startswith("specialization"):
-            print(f"{key:>12}:{family_stats[key]:>12} {100*family_stats[key]/total:0.1f}%")
-    for key in ("specialization_success",  "specialization_failure"):
-        print(f"  {key}:{family_stats[key]:>12}")
-    total_failures = family_stats["specialization_failure"]
-    failure_kinds = [ 0 ] * 30
-    for key in family_stats:
-        if not key.startswith("specialization_failure_kind"):
-            continue
-        _, index = key[:-1].split("[")
-        index =  int(index)
-        failure_kinds[index] = family_stats[key]
-    for index, value in enumerate(failure_kinds):
-        if not value:
-            continue
-        print(f"    kind {index:>2}: {value:>8} {100*value/total_failures:0.1f}%")
-
-def main():
-    stats = collections.defaultdict(collections.Counter)
-    for filename in os.listdir(DEFAULT_DIR):
-        for line in open(os.path.join(DEFAULT_DIR, filename)):
-            key, value = line.split(":")
-            key = key.strip()
-            family, stat = key.split(".")
-            value = int(value.strip())
-            stats[family][stat] += value
-
-    for name in sorted(stats):
-        print_stats(name, stats[name])
-
-if __name__ == "__main__":
-    main()
diff --git a/Tools/scripts/summarize_stats.py b/Tools/scripts/summarize_stats.py
new file mode 100644
index 0000000000..15b1887415
--- /dev/null
+++ b/Tools/scripts/summarize_stats.py
@@ -0,0 +1,53 @@
+"""Print a summary of specialization stats for all files in the
+default stats folders.
+"""
+
+import collections
+import os.path
+
+if os.name == "nt":
+    DEFAULT_DIR = "c:\\temp\\py_stats\\"
+else:
+    DEFAULT_DIR = "/tmp/py_stats/"
+
+
+TOTAL = "deferred", "hit", "miss", "unquickened"
+
+def print_stats(name, family_stats):
+    total = sum(family_stats[kind] for kind in TOTAL)
+    if total == 0:
+        return
+    print(name+":")
+    for key in sorted(family_stats):
+        if not key.startswith("specialization"):
+            print(f"{key:>12}:{family_stats[key]:>12} {100*family_stats[key]/total:0.1f}%")
+    for key in ("specialization_success",  "specialization_failure"):
+        print(f"  {key}:{family_stats[key]:>12}")
+    total_failures = family_stats["specialization_failure"]
+    failure_kinds = [ 0 ] * 30
+    for key in family_stats:
+        if not key.startswith("specialization_failure_kind"):
+            continue
+        _, index = key[:-1].split("[")
+        index =  int(index)
+        failure_kinds[index] = family_stats[key]
+    for index, value in enumerate(failure_kinds):
+        if not value:
+            continue
+        print(f"    kind {index:>2}: {value:>8} {100*value/total_failures:0.1f}%")
+
+def main():
+    stats = collections.defaultdict(collections.Counter)
+    for filename in os.listdir(DEFAULT_DIR):
+        for line in open(os.path.join(DEFAULT_DIR, filename)):
+            key, value = line.split(":")
+            key = key.strip()
+            family, stat = key.split(".")
+            value = int(value.strip())
+            stats[family][stat] += value
+
+    for name in sorted(stats):
+        print_stats(name, stats[name])
+
+if __name__ == "__main__":
+    main()
-- 
cgit v1.2.1