Skip to content

gh-104683: Argument clinic: make format_docstring() a method on Function objects #107840

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
AlexWaygood wants to merge 3 commits into from
Closed

gh-104683: Argument clinic: make format_docstring() a method on Function objects #107840

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a26605
Argument clinic: make `format_docstring()` a method on `Function` obj…
AlexWaygood Aug 10, 2023
4edaf41
Also make `forced_text_signature` an attribute on `Function` objects
AlexWaygood Aug 10, 2023
421013d
Revert "Also make `forced_text_signature` an attribute on `Function` …
AlexWaygood Aug 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Also make forced_text_signature an attribute on Function objects
  • Loading branch information
@AlexWaygood
AlexWaygood committed Aug 10, 2023
commit 4edaf412028a7125d2e815139c181abb1d76d6e1
22 changes: 10 additions & 12 deletions Tools/clinic/clinic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2665,6 +2665,7 @@ class Function:
# functions with optional groups because we can't represent
# those accurately with inspect.Signature in 3.4.
docstring_only: bool = False
forced_text_signature: str | None = None

def __post_init__(self) -> None:
self.parent = self.cls or self.module
Expand Down Expand Up @@ -2724,12 +2725,12 @@ def copy(self, **overrides: Any) -> Function:
}
return f

def format_docstring_signature(self, *, forced_text_signature: str | None) -> str:
def format_docstring_signature(self) -> str:
parameters = self.render_parameters
text, add, output = _text_accumulator()
add(self.displayname)
if forced_text_signature:
add(forced_text_signature)
if self.forced_text_signature:
add(self.forced_text_signature)
else:
add('(')

Expand Down Expand Up @@ -2898,7 +2899,7 @@ def format_docstring_parameters(self) -> str:
add('\n')
return output()

def format_docstring(self, *, forced_text_signature: str | None) -> None:
def format_docstring(self) -> None:
if self.kind.new_or_init and not self.docstring:
# don't render a docstring at all, no signature, nothing.
return
Expand Down Expand Up @@ -2938,9 +2939,7 @@ def format_docstring(self, *, forced_text_signature: str | None) -> None:

# finalize docstring
parameters = self.format_docstring_parameters()
signature = self.format_docstring_signature(
forced_text_signature=forced_text_signature
)
signature = self.format_docstring_signature()
docstring = "\n".join(lines)
self.docstring = linear_format(docstring,
signature=signature,
Expand Down Expand Up @@ -4803,7 +4802,6 @@ class DSLParser:
indent: IndentStack
kind: FunctionKind
coexist: bool
forced_text_signature: str | None
parameter_continuation: str
preserve_output: bool
star_from_version_re = create_regex(
Expand Down Expand Up @@ -4840,7 +4838,6 @@ def reset(self) -> None:
self.indent = IndentStack()
self.kind = CALLABLE
self.coexist = False
self.forced_text_signature = None
self.parameter_continuation = ''
self.preserve_output = False

Expand Down Expand Up @@ -4982,9 +4979,10 @@ def at_coexist(self) -> None:
self.coexist = True

def at_text_signature(self, text_signature: str) -> None:
if self.forced_text_signature:
assert self.function
if self.function.forced_text_signature:
fail("Called @text_signature twice!")
self.forced_text_signature = text_signature
self.function.forced_text_signature = text_signature

def parse(self, block: Block) -> None:
self.reset()
Expand Down Expand Up @@ -5778,7 +5776,7 @@ def check_remaining(
if self.deprecated_positional:
check_remaining("* [from ...]", lambda p: not p.deprecated_positional)

self.function.format_docstring(forced_text_signature=self.forced_text_signature)
self.function.format_docstring()


# maps strings to callables.
Expand Down