Skip to content

Commit b0b26af

Browse files
[3.11] gh-86457: Add docs for Argument Clinic @text_signature directive (#107747) (#107799)
(cherry picked from commit a9aeb99) Co-authored-by: Alex Waygood <[email protected]>
1 parent 5b76eaf commit b0b26af

File tree

2 files changed

+34
-1
lines changed

2 files changed

+34
-1
lines changed

Doc/howto/clinic.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1893,3 +1893,36 @@ blocks embedded in Python files look slightly different. They look like this:
18931893
#[python start generated code]*/
18941894
def foo(): pass
18951895
#/*[python checksum:...]*/
1896+
1897+
1898+
.. _clinic-howto-override-signature:
1899+
1900+
How to override the generated signature
1901+
---------------------------------------
1902+
1903+
You can use the ``@text_signature`` directive to override the default generated
1904+
signature in the docstring.
1905+
This can be useful for complex signatures that Argument Clinic cannot handle.
1906+
The ``@text_signature`` directive takes one argument:
1907+
the custom signature as a string.
1908+
The provided signature is copied verbatim to the generated docstring.
1909+
1910+
Example from :source:`Objects/codeobject.c`::
1911+
1912+
/*[clinic input]
1913+
@text_signature "($self, /, **changes)"
1914+
code.replace
1915+
*
1916+
co_argcount: int(c_default="self->co_argcount") = unchanged
1917+
co_posonlyargcount: int(c_default="self->co_posonlyargcount") = unchanged
1918+
# etc ...
1919+
1920+
Return a copy of the code object with new values for the specified fields.
1921+
[clinic start generated output]*/
1922+
1923+
The generated docstring ends up looking like this::
1924+
1925+
replace($self, /, **changes)
1926+
--
1927+
1928+
Return a copy of the code object with new values for the specified fields.
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
Argument Clinic now supports overriding automatically generated signature by
2-
using directive ``@text_signature``.
2+
using directive ``@text_signature``. See :ref:`clinic-howto-override-signature`.

0 commit comments

Comments
 (0)