Mailing List Archive

On Wed, May 4, 2022, 04:11 Petr Viktorin <encukou@gmail.com> wrote:

>
>
> On 29. 04. 22 19:02, Guido van Rossum wrote:
> > On Fri, Apr 29, 2022 at 10:15 AM Petr Viktorin <encukou@gmail.com
> > <mailto:encukou@gmail.com>> wrote:
> >
> > On 29. 04. 22 16:32, Victor Stinner wrote:
> > > Ok, let me start with the serious business: API name.
> > >
> > > I'm not comfortable with "semi-stable". Python already has a
> "limited
> > > API" and a "stable ABI". Just by its name, it's unclear what
> > > "semi-stable" means.
> [...]
> > Nick Coghlan argued against that term:
> [...]
> > But I also like “unstable” better than “semi-stable”. Splitting the
> > internals into “private”/“internal” and “unstable” seems reasonable.
> >
> >
> > I think picking "semi-stable" would be giving in to the OCD nerd in all
> > of us. :-) While perhaps technically less precise, "unstable" is the
> > catchy name with the right association. (And yes, we should keep it
> > stable within bugfix releases, but the name doesn't need to reflect that
> > detail.) The "internal API" isn't an API at all (except for CPython core
> > developers and contributors). The "unstable API" would definitely be an
> > *API* for users outside the core.
> >
> > So let's please go with "unstable".
>
>
> Thanks, you worded that perfectly!
>
> Alright, the PEP now uses “unstable” rather than “semi-stable”. And I
> don't see any issues with the technical details, so I'll see if it can
> still get into Python 3.11. Hopefully Pablo agrees as the Release Manager.
> Thanks for the discussion, everyone!
>

I've already brought this up to Petr directly, but I would greatly prefer
new unstable API functions have leading underscores, and that existing
functions being moved to the unstable API are _not_ renamed.

Renaming existing functions means a lot of unnecessary code churn. It looks
like we have more _-prefixed unstable functions than not, but I don't think
the churn is worth renaming the currently public ones.

Leading underscores for unstable API functions (that aren't currently
public) means we keep the widely assumed guarantee that Py*/PY* are part of
the public API. The Py_USING_UNSTABLE_API define is per-file, not per
symbol/use, so I would rather not open the door to unintended or unaware
use of unstable APIs. By giving the functions the leading underscore, we're
forcing people to think about -- or check the documentation -- whether the
specific function is okay to use.

The unstable API is intended for specific use-cases, and I think it's
preferable to put the burden of figuring out if a _Py/_PY* symbol is
acceptable for them to use, rather than putting the burden of figuring out
if a Py/PY* symbol is acceptable up use on _everyone else_.


_______________________________________________
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-leave@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/L6IGXJ5OM2GHAFTAEWWB35STT3MBQL2J/
> Code of Conduct: http://python.org/psf/codeofconduct/
>

On Thu, May 5, 2022 at 5:35 AM Thomas Wouters <thomaswout@gmail.com> wrote:
[...]
>
>
> I've already brought this up to Petr directly, but I would greatly prefer new unstable API functions have leading underscores, and that existing functions being moved to the unstable API are _not_ renamed.
>
> Renaming existing functions means a lot of unnecessary code churn. It looks like we have more _-prefixed unstable functions than not, but I don't think the churn is worth renaming the currently public ones.
>
> Leading underscores for unstable API functions (that aren't currently public) means we keep the widely assumed guarantee that Py*/PY* are part of the public API. The Py_USING_UNSTABLE_API define is per-file, not per symbol/use, so I would rather not open the door to unintended or unaware use of unstable APIs. By giving the functions the leading underscore, we're forcing people to think about -- or check the documentation -- whether the specific function is okay to use.
>
> The unstable API is intended for specific use-cases, and I think it's preferable to put the burden of figuring out if a _Py/_PY* symbol is acceptable for them to use, rather than putting the burden of figuring out if a Py/PY* symbol is acceptable up use on _everyone else_.
>

I don't think that's necessary. I still see the unstable API as
public: it needs more maintenance, but it's not particularly dangerous
to use it.
I think defining Py_USING_UNSTABLE_API once is quite enough.
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/RHQYGRQL6HWT6PC52BRKKVI6CUPHFT36/
Code of Conduct: http://python.org/psf/codeofconduct/

Hi,
Unfortunately my newborn child is taking up even more time than I
expected, so I won't be able to get the unstable API tier into Python
3.11 even if it's accepted today.
(If anyone else would like to try, feel free to add yourself as
Author, make any changes necessary and talk to Pablo (the RM) and the
SC.)

IMO it's fine to delay formalizing this until 3.12, so we can have a
proper discussion.
However, if someone has the time, it would be nice to ensure the use
cases from PEP 523 are possible with the 3.11 API.
Specifically, AFAIK, struct _PyInterpreterFrame needs to be exposed
(as an incomplete, opaque struct) to make _PyFrameEvalFunction usable,
_PyFrame_GetFrameObject needs to be exposed, and a
PyEval_EvalFrameDefault that takes PyFrameObject should be added.
Also, the What's New currently says “See PEP 523 for more details of
how to use [_PyFrameEvalFunction]”, which isn't very helpful.

On Thu, May 5, 2022 at 1:55 PM Petr Viktorin <encukou@gmail.com> wrote:
>
> On Thu, May 5, 2022 at 5:35 AM Thomas Wouters <thomaswout@gmail.com> wrote:
> [...]
> >
> >
> > I've already brought this up to Petr directly, but I would greatly prefer new unstable API functions have leading underscores, and that existing functions being moved to the unstable API are _not_ renamed.
> >
> > Renaming existing functions means a lot of unnecessary code churn. It looks like we have more _-prefixed unstable functions than not, but I don't think the churn is worth renaming the currently public ones.
> >
> > Leading underscores for unstable API functions (that aren't currently public) means we keep the widely assumed guarantee that Py*/PY* are part of the public API. The Py_USING_UNSTABLE_API define is per-file, not per symbol/use, so I would rather not open the door to unintended or unaware use of unstable APIs. By giving the functions the leading underscore, we're forcing people to think about -- or check the documentation -- whether the specific function is okay to use.
> >
> > The unstable API is intended for specific use-cases, and I think it's preferable to put the burden of figuring out if a _Py/_PY* symbol is acceptable for them to use, rather than putting the burden of figuring out if a Py/PY* symbol is acceptable up use on _everyone else_.
> >
>
> I don't think that's necessary. I still see the unstable API as
> public: it needs more maintenance, but it's not particularly dangerous
> to use it.
> I think defining Py_USING_UNSTABLE_API once is quite enough.
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/TKN73JBATGBJHP7THK5G3CPMJITG53T5/
Code of Conduct: http://python.org/psf/codeofconduct/

On Fri, 6 May 2022 at 22:50, Petr Viktorin <encukou@gmail.com> wrote:
> IMO it's fine to delay formalizing this until 3.12, so we can have a
> proper discussion.
> However, if someone has the time, it would be nice to ensure the use
> cases from PEP 523 are possible with the 3.11 API.
> Specifically, AFAIK, struct _PyInterpreterFrame needs to be exposed
> (as an incomplete, opaque struct) to make _PyFrameEvalFunction usable,
> _PyFrame_GetFrameObject needs to be exposed, and a
> PyEval_EvalFrameDefault that takes PyFrameObject should be added.
> Also, the What's New currently says “See PEP 523 for more details of
> how to use [_PyFrameEvalFunction]”, which isn't very helpful.

Given the proximity of beta1, I think affected projects are going to
need to define Py_BUILD_CORE for the Python 3.11 series - at least
some of them have already been updated to declare that during the
alpha cycle to handle the frame API changes.

PEP 689 can then be informed by feedback from those projects regarding
what breaks for them if they *don't* declare Py_BUILD_CORE.

That said, one slightly awkward consequence of this approach is
affected projects would end up needing to include CPython's
"patchlevel.h" [1] directly, so they can query PY_VERSION_HEX *before*
including "Python.h". Something like:

#include "patchlevel.h" # CPython's version declaration header
#if Py_VERSION_HEX+0 >= 0x030c0000 # CPython 3.12+
#define Py_USING_UNSTABLE_API
#elif Py_VERSION_HEX+0 >= 0x030b0000 # CPython 3.11.x
#define Py_BUILD_CORE
#endif
#include "Python.h"

So maybe it would be worth asking the SC for an exception to the beta
freeze, and allow the unstable API tier to land during the beta
period?

Cheers,
Nick.

[1] https://github.com/python/cpython/blob/main/Include/patchlevel.h

--
Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/KG56QXYVEPDUSPIGDDUDEDZLMYXOXPQG/
Code of Conduct: http://python.org/psf/codeofconduct/

Why you don't simplify with api A,B,C and forth and then follows
explanation ofr what is stable, unstable, semi... So forth....

On Wed, May 4, 2022, 6:10 AM Petr Viktorin <encukou@gmail.com> wrote:

>
>
> On 29. 04. 22 19:02, Guido van Rossum wrote:
> > On Fri, Apr 29, 2022 at 10:15 AM Petr Viktorin <encukou@gmail.com
> > <mailto:encukou@gmail.com>> wrote:
> >
> > On 29. 04. 22 16:32, Victor Stinner wrote:
> > > Ok, let me start with the serious business: API name.
> > >
> > > I'm not comfortable with "semi-stable". Python already has a
> "limited
> > > API" and a "stable ABI". Just by its name, it's unclear what
> > > "semi-stable" means.
> [...]
> > Nick Coghlan argued against that term:
> [...]
> > But I also like “unstable” better than “semi-stable”. Splitting the
> > internals into “private”/“internal” and “unstable” seems reasonable.
> >
> >
> > I think picking "semi-stable" would be giving in to the OCD nerd in all
> > of us. :-) While perhaps technically less precise, "unstable" is the
> > catchy name with the right association. (And yes, we should keep it
> > stable within bugfix releases, but the name doesn't need to reflect that
> > detail.) The "internal API" isn't an API at all (except for CPython core
> > developers and contributors). The "unstable API" would definitely be an
> > *API* for users outside the core.
> >
> > So let's please go with "unstable".
>
>
> Thanks, you worded that perfectly!
>
> Alright, the PEP now uses “unstable” rather than “semi-stable”. And I
> don't see any issues with the technical details, so I'll see if it can
> still get into Python 3.11. Hopefully Pablo agrees as the Release Manager.
> Thanks for the discussion, everyone!
> _______________________________________________
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-leave@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/L6IGXJ5OM2GHAFTAEWWB35STT3MBQL2J/
> Code of Conduct: http://python.org/psf/codeofconduct/
>