[Python-checkins] gh-104683: Argument Clinic: Params now render their own docstrings (#107790)
erlend-aasland
webhook-mailer at python.org
Wed Aug 9 08:44:31 EDT 2023
https://github.com/python/cpython/commit/1b3f5f24af95c0476ba339ed786a8a4a2578362a
commit: 1b3f5f24af95c0476ba339ed786a8a4a2578362a
branch: main
author: Erlend E. Aasland <erlend at python.org>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-08-09T12:44:26Z
summary:
gh-104683: Argument Clinic: Params now render their own docstrings (#107790)
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>
files:
M Lib/test/test_clinic.py
M Tools/clinic/clinic.py
diff --git a/Lib/test/test_clinic.py b/Lib/test/test_clinic.py
index 026cd18d646ad..3921523af067f 100644
--- a/Lib/test/test_clinic.py
+++ b/Lib/test/test_clinic.py
@@ -833,8 +833,8 @@ def expect_failure(self, block, err, *, filename=None, lineno=None):
def checkDocstring(self, fn, expected):
self.assertTrue(hasattr(fn, "docstring"))
- self.assertEqual(fn.docstring.strip(),
- dedent(expected).strip())
+ self.assertEqual(dedent(expected).strip(),
+ fn.docstring.strip())
def test_trivial(self):
parser = DSLParser(_make_clinic())
@@ -997,8 +997,12 @@ def test_function_docstring(self):
path: str
Path to be examined
+ Ensure that multiple lines are indented correctly.
Perform a stat system call on the given path.
+
+ Ensure that multiple lines are indented correctly.
+ Ensure that multiple lines are indented correctly.
""")
self.checkDocstring(function, """
stat($module, /, path)
@@ -1008,6 +1012,10 @@ def test_function_docstring(self):
path
Path to be examined
+ Ensure that multiple lines are indented correctly.
+
+ Ensure that multiple lines are indented correctly.
+ Ensure that multiple lines are indented correctly.
""")
def test_docstring_trailing_whitespace(self):
diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index 059c2db27288d..3490d4871b891 100755
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -2775,6 +2775,13 @@ def get_displayname(self, i: int) -> str:
else:
return f'"argument {i}"'
+ def render_docstring(self) -> str:
+ add, out = text_accumulator()
+ add(f" {self.name}\n")
+ for line in self.docstring.split("\n"):
+ add(f" {line}\n")
+ return out().rstrip()
+
CConverterClassT = TypeVar("CConverterClassT", bound=type["CConverter"])
@@ -5686,23 +5693,11 @@ def add_parameter(text: str) -> None:
@staticmethod
def format_docstring_parameters(params: list[Parameter]) -> str:
"""Create substitution text for {parameters}"""
- text, add, output = _text_accumulator()
- spacer_line = False
- for param in params:
- docstring = param.docstring.strip()
- if not docstring:
- continue
- if spacer_line:
+ add, output = text_accumulator()
+ for p in params:
+ if p.docstring:
+ add(p.render_docstring())
add('\n')
- else:
- spacer_line = True
- add(" ")
- add(param.name)
- add('\n')
- stripped = rstrip_lines(docstring)
- add(textwrap.indent(stripped, " "))
- if text:
- add('\n')
return output()
def format_docstring(self) -> str:
More information about the Python-checkins
mailing list