Lint Doc/ with Ruff

.pre-commit-config.yaml

@@ -1,7 +1,11 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.0
+    rev: v0.1.1
     hooks:
+      - id: ruff
+        name: Run Ruff on Doc/
+        args: [--exit-non-zero-on-fix]
+        files: ^Doc/
       - id: ruff
         name: Run Ruff on Lib/test/
         args: [--exit-non-zero-on-fix]

Doc/.ruff.toml

@@ -0,0 +1,6 @@
+fix = true
+extend-exclude = [
+    # Incomplete/unparseable example files
+    "includes/email-mime.py",
+    "includes/email-simple.py",
+]

Doc/conf.py

@@ -6,7 +6,9 @@
 # The contents of this file are pickled, so don't put values in the namespace
 # that aren't pickleable (module imports are okay, they're removed automatically).
 
-import sys, os, time
+import os
+import sys
+import time
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
 
@@ -26,7 +28,7 @@
 
 # Skip if downstream redistributors haven't installed it
 try:
-    import sphinxext.opengraph
+    import sphinxext.opengraph  # noqa: F401
 except ImportError:
     pass
 else:
@@ -53,7 +55,7 @@
 
 # We look for the Include/patchlevel.h file in the current Python source tree
 # and replace the values accordingly.
-import patchlevel
+import patchlevel  # noqa: E402
 version, release = patchlevel.get_version_info()
 
 # There are two options for replacing |today|: either, you set today to some

Doc/includes/diff.py

@@ -7,7 +7,10 @@
 
 """
 
-import sys, os, difflib, argparse
+import argparse
+import difflib
+import os
+import sys
 from datetime import datetime, timezone
 
 def file_mtime(path):

Doc/includes/ndiff.py

@@ -35,7 +35,8 @@
 
 __version__ = 1, 7, 0
 
-import difflib, sys
+import difflib
+import sys
 
 def fail(msg):
     out = sys.stderr.write
@@ -58,8 +59,10 @@ def fcompare(f1name, f2name):
     if not f1 or not f2:
         return 0
 
-    a = f1.readlines(); f1.close()
-    b = f2.readlines(); f2.close()
+    a = f1.readlines()
+    b = f2.readlines()
+    f1.close()
+    f2.close()
     for line in difflib.ndiff(a, b):
         print(line, end=' ')
 

Doc/includes/newtypes/test.py

@@ -188,5 +188,6 @@
 """
 
 if __name__ == "__main__":
-    import doctest, __main__
+    import doctest
+    import __main__
     doctest.testmod(__main__)

Doc/includes/tzinfo_examples.py

@@ -1,15 +1,15 @@
 from datetime import tzinfo, timedelta, datetime
 
-ZERO = timedelta(0)
-HOUR = timedelta(hours=1)
-SECOND = timedelta(seconds=1)
-
 # A class capturing the platform's idea of local time.
 # (May result in wrong values on historical times in
 #  timezones where UTC offset and/or the DST rules had
 #  changed in the past.)
 import time as _time
 
+ZERO = timedelta(0)
+HOUR = timedelta(hours=1)
+SECOND = timedelta(seconds=1)
+
 STDOFFSET = timedelta(seconds = -_time.timezone)
 if _time.daylight:
     DSTOFFSET = timedelta(seconds = -_time.altzone)

Doc/tools/extensions/asdl_highlight.py

@@ -1,16 +1,17 @@
 import sys
 from pathlib import Path
 
-CPYTHON_ROOT = Path(__file__).resolve().parent.parent.parent.parent
-sys.path.append(str(CPYTHON_ROOT / "Parser"))
-
 from pygments.lexer import RegexLexer, bygroups, include, words
 from pygments.token import (Comment, Keyword, Name, Operator,
                             Punctuation, Text)
-
-from asdl import builtin_types
 from sphinx.highlighting import lexers
 
+CPYTHON_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+sys.path.append(str(CPYTHON_ROOT / "Parser"))
+
+from asdl import builtin_types  # noqa: E402
+
+
 class ASDLLexer(RegexLexer):
     name = "ASDL"
     aliases = ["asdl"]

Doc/tools/extensions/c_annotations.py

@@ -37,7 +37,6 @@
     'var': 'data',
     'type': 'type',
     'macro': 'macro',
-    'type': 'type',
     'member': 'member',
 }
 
@@ -93,7 +92,6 @@ def __init__(self, refcount_filename, stable_abi_file):
         self.stable_abi_data = {}
         with open(stable_abi_file, 'r') as fp:
             for record in csv.DictReader(fp):
-                role = record['role']
                 name = record['name']
                 self.stable_abi_data[name] = record
 

Doc/tools/extensions/pyspecific.py

@@ -18,6 +18,7 @@
 from docutils import nodes, utils
 from docutils.io import StringOutput
 from docutils.parsers.rst import Directive
+from docutils.parsers.rst.states import Body
 from docutils.utils import new_document
 from sphinx import addnodes
 from sphinx.builders import Builder
@@ -42,7 +43,6 @@
 SOURCE_URI = 'https://github.com/python/cpython/tree/main/%s'
 
 # monkey-patch reST parser to disable alphabetic and roman enumerated lists
-from docutils.parsers.rst.states import Body
 Body.enum.converters['loweralpha'] = \
     Body.enum.converters['upperalpha'] = \
     Body.enum.converters['lowerroman'] = \