[Poll] What is your favorite name for the new Include/ subdirectory?

Committers
1

I plan to merge my following PR tomorrow. It adds a new Include/unstable/ subdirectory: move code surrounded by “#ifndef Py_LIMITED_API” to this directory, so Include/*.h would only contain the “limited API”. See the bpo for more details.

Note: I would prefer to post this message to a “python-dev” category. Committers is restricted to core devs (but everyone can read). IMHO my message doesn’t belong to “Users” or “Ideas”. But there is no “python-dev” category yet. If something creates it, I suggest to call it “Core Development” rather than “python-dev” since many newbies misunderstant the purpose of the python-dev mailing list :slight_smile:

2

What is your favorite name for the new Include/ subdirectory?

  • Include/impl/
  • Include/cpython/
  • Include/unstable/
  • Include/board/
  • Include/pycapi/
  • other (add comment)
0 voters

The new subdirectory will contain “#ifndef Py_LIMITED_API” code, not the “Stable ABI” of PEP 384, but more “implementation details” of CPython. The API is public. The existing Include/internal/ is the private API which should not used outside CPython.

The name will be “hidden”: including directly an header from Include// will raise a compilation error :slight_smile:

First I proposed “pycapi” name, but now I dislike it because it’s way too generic.

Brett dislikes “unstable” and proposed “broad”:

The “unstable” name bugs me as it suggests we might change it without notice which isn’t true at all. It’s more a limited versus broad API. So maybe rename the directory “broad”?

See https://bugs.python.org/issue35134 for previous discussion on the name.

3

Nick Coghlan, Steve Dower and Paul Moore and me prefer “cpython” name, so let’s go with that one!

4

I realize it’s too late. I would have preferred “unstable” myself :slight_smile:

5

Nick Coghlan, Brett Cannon and Jeremy Kloth don’t like this name: https://bugs.python.org/issue35134#msg330246

6

Ah, thanks for the pointer. I think they are right actually.

7

I think that we had the same rationale: the opposite of “stable ABI (API)” is “unstable”, but no, it’s not exactly like that :slight_smile: The most important part is the summary which explains what belongs to Include/cpython/

Include/.h should be the portable Python API, whereas Include/cpython/.h should be the CPython API: CPython implementation details.

1 Like
8

I think the “portable” API would have more luck being a separate API as others have explained on python-dev, but the rationale is reasonable anyway.

9

If the new include directory is just intended to facilitate a third party API, please ignore the rest of the comment.

But here’s why I think a third-party API is better for some:

  1. I’m going to use internals anyway, so I have to maintain two versions of a module.

  2. If I maintain two versions, the API for the second version should be endorsed by PyPy.

  3. I already could use CFFI for the second version (which may be more fun to begin with), so a new API should be really good and have the full support from PyPy (including benchmarks against CFFI).

2 Likes
10

See the first message of the issue for the rationale:
https://bugs.python.org/issue35134#msg329060

In short, it’s the prevent to add a new function by mistake to the “stable API” (stable ABI).

It seems like you are talking about my idea of new C API. Hum, this thread is about Include/cpython/ which is unrelated to the new C API idea. I suggest you to reply to python-dev threads instead.

Note: I would prefer to close this topic, since I merged my PR creating Include/cpython/ and I closed the poll about the new API. I dislike having discussions at multiple places :frowning:

11

Indeed, the comment says “It is also part of a larger project to cleanup the C API.” and leads to https://pythoncapi.readthedocs.io/ .

I don’t think you can ask people to discuss everything in the exact venue of your choice if things appear to be connected.

12

Closed at the request of @vstinner who is the OP.