Begin enforcing docstring length in Argument Clinic

Author: AA-Turner

Tools/clinic/libclinic/_overlong_docstrings.py

@@ -0,0 +1,70 @@
+OVERLONG_DOCSTRINGS = frozenset((
+    '_abc._abc_instancecheck',
+    '_abc._abc_register',
+    '_abc._abc_subclasscheck',
+    '_codecs.lookup',
+    '_functools.reduce',
+    '_hashlib.pbkdf2_hmac',
+    '_io._BufferedIOBase.read1',
+    '_jit.is_active',
+    '_jit.is_available',
+    '_jit.is_enabled',
+    '_lzma._decode_filter_properties',
+    '_remote_debugging.RemoteUnwinder.get_async_stack_trace',
+    '_socket.inet_aton',
+    '_sre.SRE_Match.expand',
+    '_sre.SRE_Match.groupdict',
+    '_sre.SRE_Pattern.finditer',
+    '_sre.SRE_Pattern.search',
+    '_sre.SRE_Pattern.sub',
+    '_sre.SRE_Pattern.subn',
+    '_ssl._SSLContext.sni_callback',
+    '_ssl._SSLSocket.pending',
+    '_ssl.get_default_verify_paths',
+    '_ssl.RAND_status',
+    '_sysconfig.config_vars',
+    '_testcapi.make_exception_with_doc',
+    '_tkinter.getbusywaitinterval',
+    '_tkinter.setbusywaitinterval',
+    'array.array.buffer_info',
+    'array.array.frombytes',
+    'array.array.tobytes',
+    'bytearray.count',
+    'bytearray.find',
+    'bytearray.index',
+    'bytearray.rfind',
+    'bytearray.rindex',
+    'bytes.count',
+    'bytes.find',
+    'bytes.index',
+    'bytes.rfind',
+    'bytes.rindex',
+    'itertools.chain.from_iterable',
+    'itertools.combinations_with_replacement.__new__',
+    'itertools.cycle.__new__',
+    'itertools.starmap.__new__',
+    'itertools.takewhile.__new__',
+    'math.comb',
+    'msvcrt.kbhit',
+    'OrderedDict.pop',
+    'os.pwritev',
+    'os.sched_getaffinity',
+    'os.timerfd_gettime',
+    'os.timerfd_gettime_ns',
+    'pyexpat.xmlparser.ExternalEntityParserCreate',
+    'pyexpat.xmlparser.GetReparseDeferralEnabled',
+    'pyexpat.xmlparser.UseForeignDTD',
+    'str.count',
+    'str.find',
+    'str.index',
+    'str.rfind',
+    'str.rindex',
+    'str.rsplit',
+    'str.split',
+    'sys._setprofileallthreads',
+    'sys._settraceallthreads',
+    'unicodedata.UCD.decomposition',
+    'zoneinfo.ZoneInfo.dst',
+    'zoneinfo.ZoneInfo.tzname',
+    'zoneinfo.ZoneInfo.utcoffset',
+))

Tools/clinic/libclinic/dsl_parser.py

@@ -14,6 +14,7 @@
 from libclinic import (
     ClinicError, VersionTuple,
     fail, warn, unspecified, unknown, NULL)
+from libclinic._overlong_docstrings import OVERLONG_DOCSTRINGS
 from libclinic.function import (
     Module, Class, Function, Parameter,
     FunctionKind,
@@ -1509,6 +1510,9 @@ def format_docstring(self) -> str:
                 fail(f"Docstring for {f.full_name!r} does not have a summary line!\n"
                      "Every non-blank function docstring must start with "
                      "a single line summary followed by an empty line.")
+            if len(lines[0]) > 80 and f.full_name not in OVERLONG_DOCSTRINGS:
+                fail(f"Summary line {f.full_name!r} is too long!\n"
+                     "The summary line must be no longer than 80 characters.")
         elif len(lines) == 1:
             # the docstring is only one line right now--the summary line.
             # add an empty line after the summary line so we have space

Tools/clinic/libclinic/errors.py

@@ -15,7 +15,7 @@ def __post_init__(self) -> None:
     def report(self, *, warn_only: bool = False) -> str:
         msg = "Warning" if warn_only else "Error"
         if self.filename is not None:
-            msg += f" in file {self.filename!r}"
+            msg += f" in file '{self.filename}'"
         if self.lineno is not None:
             msg += f" on line {self.lineno}"
         msg += ":\n"