Improve the readability and maintainability of test_capi using the AC

[corona10]

Currently, most of test_capi modules do not use the Argument Clinic tool.
As a result, we manually implement docstrings containing explanations for the test codes and handle parameter parsing manually: PyArg_ParseTuple .
To maintain code consistency in test_capi, I suggest using the Argument Clinic tool.

While some might criticize this as code churn, I believe it is necessary for maintaining consistent test code writing practices. I will attach a sample PR to illustrate how it can help improve the understanding of the test code. I hope this will help clarify the rationale behind it.

cc @erlend-aasland @sobolevn

Linked PRs

• gh-104469 Convert _testcapi/float.c to use AC #104470
• gh-104469 Convert _testcapi/exceptions to use AC #104502
• gh-104469: Convert _testcapi/watchers.c to use AC #104503
• gh-104469: Update README.txt for _testcapi #104529
• gh-104469: Convert _testcapi/long to use AC #104720
• gh-104469 Convert_testcapi/vectorcall.c to use AC #106557
• gh-104469 : Convert _testcapi/vectorcall_limited.c to use AC #107857
• gh-104469 : Convert _testcapi/dict.c to use AC #107859
• gh-104469 : Convert _testcapi/mem.c to use AC #107860
• Revert "gh-104469 : Convert _testcapi/vectorcall_limited.c to use AC … #107951
• gh-104469 Fix limited C API issue for WASI #107953
• gh-104469: Disallow using Py_LIMITED_API with Py_BUILD_CORE #109690
• gh-104469: Convert _testcapi/vectorcall_limited.c to use AC #109691

[sunmy2019]

LGTM

[corona10]

I am working on test_exceptions.

[sobolevn]

I am working on _testcapi/watchers.c 👍

[erlend-aasland]

Let's establish some guidelines:

• For the sake of readability (which is one of the goals here), please add a newline between the argument spec and the docstring
• If purpose is obvious given a function name, omit the docstring
• If a description is needed, make sure the added docstring clearly and succinctly describes purpose of the function
• DRY, use the clone feature of Argument Clinic
• Try to avoid adding new interned strings; reuse existing parameter names if possible and use the as feature to override the C name

cc. @sobolevn @corona10

[sobolevn]

Agreed, updated my PR.

[corona10]

Let's establish some guidelines:

+1, Super great
Update README.txt? (I prefer to update it to README.md either)
or publish it to https://devguide.python.org/developer-workflow/c-api/#c-api here?

[erlend-aasland]

Update README.txt?

Definitely! 🙂

(I prefer to update it to README.md either)

I'd just leave it as .txt unless there's a specific reason to reformat it.

or publish it to https://devguide.python.org/developer-workflow/c-api/#c-api here?

Yes, perhaps we should add some general AC advice to the devguide. Perhaps the first step is to link from the devguide to the AC How-to. We should also overhaul the latter considerably.

[sunmy2019]

there's a specific reason

README.md can be loaded by GitHub 🤣

[erlend-aasland]

there's a specific reason

README.md can be loaded by GitHub 🤣

So can .txt and .rst

[littlebutt]

Hi @corona10 , I worked on worked on vectorcall.c and PRed just now. But some test cases failed because of missing arguments. I'm not sure if AC introduced the problem. Thanks.

[serhiy-storchaka]

Could you please stop this?

It significantly reduces readability to me.

It significantly increases the number of lines in Modules/_testcapi/dict.c:

 Modules/_testcapi/dict.c | 412 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------------------------
 1 file changed, 291 insertions(+), 121 deletions(-)

And this is not counting the large amount of code added to another file.

I have a limited field of vision and can't see anything beyond a limited number of lines of code. Before that, test functions were compact. After these changes, they will exceed my limit. And if I need to understand what exactly the function does, I have to look for the corresponding code in the generated file and then go back to the previous file, but when I look from the file I lose the context and I have to reread each line on the screen again to find the right place.

These changes are not friendly to the visually impaired.

[corona10]

@serhiy-storchaka cc @erlend-aasland

These changes are not friendly to the visually impaired.

Okay, I should respect your physical situation.
Today was PyCon KR sprint day as I shared, and I tried to provide kinds of easy issues who want to write actual code works.

As you requested, I will close this issue and not progress this issue anymore.
I will drop the following PRs except

• gh-104469 : Convert _testcapi/dict.c to use AC #107859
• gh-104469 : Convert _testcapi/mem.c to use AC #107860

The following one will be merged #107857 this is not many changes.
I would like to request you to understand the special situation of today,

[serhiy-storchaka]

Thank you for respecting my physical situation @corona10.

These testing files are different from "normal" code using Argument Clinic, because they contain a large number of very short (in comparison to clinic decoration) and very similar functions. "Normal" code usually have larger functions, and the code is visually different. So I have less problems with other files.