[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[STINNER Victor]

STINNER Victor  added the comment:

Jeremy Kloth:
> First off, to me, 'unstable' comes off quite negative, i.e. risky or erratic.

Ok, the 3rd people who dislike my "unstable" name, so it sounds really bad :-)

Jeremy Kloth: 
> 'volatile'; synonym for 'unstable' but with the benefit of being a C concept.

I don't think that it's true that the "#ifndef Py_LIMITED_API" is unstable or 
volatile. Most of this API didn't change much in the last 10 years. So sorry, 
"unstable" was really a bad name.

Brett Cannon:
> It's more a limited versus broad API. So maybe rename the directory "broad"?

Jeremy Kloth: 
> - 'extended' or 'extra'; as opposed to limited (from the macro)

The name by itself doesn't explain why an API should be in Include/ or 
Include//. What is extra or not?


Jeremy Kloth: 
> - 'crunchy'; Monty Python reference, "If we took the bones out, it wouldn't 
> be crunchy, would it?"   https://en.wikipedia.org/wiki/Crunchy_Frog

Sorry, I dislike humor in an API. An API has to make sense :-(


--

Ok, after I read all proposition, I now prefer "cpython".

Extract of my updated PR which gives the rationale:

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

It now makes sense to me what should go to Include/ and what should go to 
Include/cpython/.

Obviously, Include/cpython/ is incomplete. It's only the public flavor of the 
"CPython API". There is also the private CPython internal API in 
Include/internal/.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[Jeremy Kloth]

Jeremy Kloth  added the comment:

As a heavy user of the non-limited Python C API, I would like to offer my 
suggestions for consideration.  (I'm not allowed to post in discourse)

First off, to me, 'unstable' comes off quite negative, i.e. risky or erratic.  
Brett's suggestion of 'broad' is, well, seemingly too "broad" :)

In no particular order, some ideas:

- 'extended' or 'extra'; as opposed to limited (from the macro)

- 'volatile'; synonym for 'unstable' but with the benefit of being a C concept. 
 I like this one as the APIs covered by this include would have access to the 
"volatile" object details.  Things like borrowed references, direct array 
access or even the structure fields of the objects themselves.

- 'crunchy'; Monty Python reference, "If we took the bones out, it wouldn't be 
crunchy, would it?"
  https://en.wikipedia.org/wiki/Crunchy_Frog

--
nosy: +jkloth

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[STINNER Victor]

STINNER Victor  added the comment:

I created a poll on discuss.python.org for the name of the new subdirectory :-)
https://discuss.python.org/t/poll-what-is-your-favorite-name-for-the-new-include-subdirectory/477

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[STINNER Victor]

STINNER Victor  added the comment:

Another proposal: Include\impl\ as in "implementation details".

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[STINNER Victor]

STINNER Victor  added the comment:

Brett:
> 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"?

Brett: Nick proposed "Include\cpython", do you prefer this name?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[Brett Cannon]

Brett Cannon  added the comment:

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"?

--
nosy: +brett.cannon

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[STINNER Victor]

STINNER Victor  added the comment:

> I think the rules for C includes are that `"path/header.h"` looks next to the 
> current file first, whereas `` looks only in include 
> directories.

Oh ok, thanks.


> However, given your technique of mostly hiding the new directory name from 
> API consumers, what do you think of calling the new directory "cpython" 
> rather than "unstable"?

I'm not comfortable with "CPython" name. For me, everything the "CPython C API" 
is the concatenation of all files in Include/ but also in subdirectories. Right 
now, it's unclear what is the "Python" API ("portable" API, without 
implemenetation details) vs the "CPython API" (implementation details).

"unstable" comes from the PEP 384: "Defining a Stable ABI". IMHO what is not in 
the "Stable ABI" is the "Unstable ABI". By extension, APIs excluded by 
Py_LIMITED_API make the "unstable API".

>From my point of view, "CPython API" would be more internal/ + unstable/ APIs.


> The idea there would be that the "unstable ABI" eventually become known as 
> "the CPython C API" (since it exposes a lot of CPython implementation 
> details", while the limited API could become known as "the portable 
> cross-implementation Python C API".

Everybody seems to be confused by what is the "Python C API"... I see even more 
confusion if we have a "CPython C API". Do you see? "CPython" vs "Python", 
"Python C" vs "CPython"...

IMHO "unstable" is more explicit :-) It means: "don't touch this" :-D

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[Nick Coghlan]

Nick Coghlan  added the comment:

I think the rules for C includes are that `"path/header.h"` looks next to the 
current file first, whereas `` looks only in include directories.

However, given your technique of mostly hiding the new directory name from API 
consumers, what do you think of calling the new directory "cpython" rather than 
"unstable"?

The idea there would be that the "unstable ABI" eventually become known as "the 
CPython C API" (since it exposes a lot of CPython implementation details", 
while the limited API could become known as "the portable cross-implementation 
Python C API".

(I know, I know, you were aiming to avoid further bikeshedding on the name, but 
"cpython" would namespace things nicely even if a compiler does something weird 
with header file lookups, and helps make it clearer to CPython contributors 
that we still need to care about public API stability in that directory, we 
just don't need to care about cross-implementation portability)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[STINNER Victor]

STINNER Victor  added the comment:

Just to avoid the risk of name conflict, would it make sense to rename 
"unstable" to "pyunstable" or something else with "py" inside? I'm not sure if 
#include "unstable/objimpl.h" first looks the same directory than the header 
file that does the include?

Note: I tested "make install" and I get a 
/opt/py38/include/python3.8dm/unstable/ directory which contains a single file 
(yet): objimpl.h.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue35134] Add a new Include/unstable/ subdirectory for the "unstable" API

[STINNER Victor]

Change by STINNER Victor :


--
title: Move !Py_LIMITED_API to Include/pycapi/ -> Add a new Include/unstable/ 
subdirectory for the "unstable" API

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com