[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-05-01 Thread Nick Coghlan 
On Sat, 30 Apr 2022, 3:02 am Guido van Rossum,  wrote:

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

While I've advocated for semi-stable in previous threads, I now agree the
pragmatic arguments for "unstable" hold up well enough to make the simpler
term the better choice:

* no question around using a hyphen or not
* "unstable public C API" is sufficient to distinguish the new tier from
Py_BUILD_CORE's completely unstable internal API

The risks of misinterpretation are also low:

* external users that need one of these APIs will presumably be invested
enough to actually check the stability expectations in the docs
* core devs will have regression tests to remind us that the published
unstable APIs aren't allowed to change after beta 1

Cheers,
Nick.




> --
> --Guido van Rossum (python.org/~guido)
> *Pronouns: he/him **(why is my pronoun here?)*
> 
>
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/6TVQ6MEVKNLYNQAHMQHCHDMJES7RIRXL/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread MRAB 

On 2022-04-30 03:17, Greg Ewing wrote:

On 30/04/22 5:25 am, MRAB wrote:

I was going to suggest "metastable". Too late? :-)


What, the API is balanced on a knife edge and likely to collapse
into something else if you sneeze too hard?

There's a possibility that the universe might be metastable, so a 
metastable API might not be that big a deal.

___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/57JT4SKQQGAN42Y2TFXCUCVAUYOQK3LV/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Greg Ewing 

On 30/04/22 5:25 am, MRAB wrote:

I was going to suggest "metastable". Too late? :-)


What, the API is balanced on a knife edge and likely to collapse
into something else if you sneeze too hard?

--
Greg
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/CUWORBXDLOK74M7H6HZSXSMC5ZKMCFFY/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Glenn Linderman 

On 4/29/2022 11:42 AM, Stephen J. Turnbull wrote:

MRAB writes:
  > On 2022-04-29 18:02, Guido van Rossum wrote:
  > > On Fri, Apr 29, 2022 at 10:15 AM Petr Viktorin  > > 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.
  > >  >
  > >  > Honestly, I would be more comfortable with the name: "unstable 
API".
  > >  > It would be clear that the API *can* change often. People who want 
to
  > >  > know exactly the backward compatibility warranties can dig into the
  > >  > API documentation to learn more about it.
  > >  >
  > >  > "Unstable API" is also the name the Guido proposed for
  > > PyCode_New() last year:
  > >  >
  > >  > * Proposal: declare "unstable APIs"
  > >  >
  > > 
https://mail.python.org/archives/list/[email protected]/thread/JM6SQ2YNMDAKXYD5O54QWMVR2X7QOXVL/
  > > 

  > >  > * Making code object APIs unstable
  > >  >
  > > 
https://mail.python.org/archives/list/[email protected]/thread/ZWTBR5ESYR26BUIVMXOKPFRLGGYDJSFC/
  > > 

  > >  >
  > >  > Victor
  > >
  > >
  > > Nick Coghlan argued against that term:
  > >
  > >  > "unstable" is the wrong term. We already have an unstable API
  > > tier: the
  > >  > internal API, which can change even in maintenance releases. The
  > > value of
  > >  > the new tier is that it is "semi stable": stable in maintenance
  > > releases,
  > >  > unstable in feature releases.
  > >
  > > —
  > > 
https://mail.python.org/archives/list/[email protected]/message/CTKKTHUV5R2A2RRN5DM32UQFNC42DDGJ/
  > > 

  > >
  > >
  > > 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".
  > >
  > I was going to suggest "metastable". Too late? :-)
A
Bikeshedding to a new level! --+


Metabikeshedding...


___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/CGNNVU7CUB4U6TK33FSYVIGP7OPPG4XJ/
Code of Conduct: http://python.org/psf/codeofconduct/


___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/GCS2AC32ODMY44PA6AS6JLLCJBP55BZV/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Stephen J. Turnbull 
MRAB writes:
 > On 2022-04-29 18:02, Guido van Rossum wrote:
 > > On Fri, Apr 29, 2022 at 10:15 AM Petr Viktorin  > > 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.
 > >  >
 > >  > Honestly, I would be more comfortable with the name: "unstable API".
 > >  > It would be clear that the API *can* change often. People who want 
 > > to
 > >  > know exactly the backward compatibility warranties can dig into the
 > >  > API documentation to learn more about it.
 > >  >
 > >  > "Unstable API" is also the name the Guido proposed for
 > > PyCode_New() last year:
 > >  >
 > >  > * Proposal: declare "unstable APIs"
 > >  >
 > > 
 > > https://mail.python.org/archives/list/[email protected]/thread/JM6SQ2YNMDAKXYD5O54QWMVR2X7QOXVL/
 > > 
 > > 
 > >  > * Making code object APIs unstable
 > >  >
 > > 
 > > https://mail.python.org/archives/list/[email protected]/thread/ZWTBR5ESYR26BUIVMXOKPFRLGGYDJSFC/
 > > 
 > > 
 > >  >
 > >  > Victor
 > > 
 > > 
 > > Nick Coghlan argued against that term:
 > > 
 > >  > "unstable" is the wrong term. We already have an unstable API
 > > tier: the
 > >  > internal API, which can change even in maintenance releases. The
 > > value of
 > >  > the new tier is that it is "semi stable": stable in maintenance
 > > releases,
 > >  > unstable in feature releases.
 > > 
 > > —
 > > 
 > > https://mail.python.org/archives/list/[email protected]/message/CTKKTHUV5R2A2RRN5DM32UQFNC42DDGJ/
 > > 
 > > 
 > > 
 > > 
 > > 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".
 > > 
 > I was going to suggest "metastable". Too late? :-)
   A
Bikeshedding to a new level! --+
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/CGNNVU7CUB4U6TK33FSYVIGP7OPPG4XJ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread MRAB 

On 2022-04-29 18:02, Guido van Rossum wrote:
On Fri, Apr 29, 2022 at 10:15 AM Petr Viktorin > 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.
 >
 > Honestly, I would be more comfortable with the name: "unstable API".
 > It would be clear that the API *can* change often. People who want to
 > know exactly the backward compatibility warranties can dig into the
 > API documentation to learn more about it.
 >
 > "Unstable API" is also the name the Guido proposed for
PyCode_New() last year:
 >
 > * Proposal: declare "unstable APIs"
 >

https://mail.python.org/archives/list/[email protected]/thread/JM6SQ2YNMDAKXYD5O54QWMVR2X7QOXVL/


 > * Making code object APIs unstable
 >

https://mail.python.org/archives/list/[email protected]/thread/ZWTBR5ESYR26BUIVMXOKPFRLGGYDJSFC/


 >
 > Victor


Nick Coghlan argued against that term:

 > "unstable" is the wrong term. We already have an unstable API
tier: the
 > internal API, which can change even in maintenance releases. The
value of
 > the new tier is that it is "semi stable": stable in maintenance
releases,
 > unstable in feature releases.

—

https://mail.python.org/archives/list/[email protected]/message/CTKKTHUV5R2A2RRN5DM32UQFNC42DDGJ/




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


I was going to suggest "metastable". Too late? :-)
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/5B7ES3BZJTKORNCT6LWLRHM7UNSFCKYU/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Victor Stinner 
I think that the main advantage of "unstable" over "semi-stable" is
that it's a single word :-D It avoids the really hard question (!)
about the separator between "semi" and "stable" ;-) (semistable?
semi-stable? semi_stable?).

Victor
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/V76VFFMUZFNGSQBOEYDKJH22D6NFZJZ2/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Guido van Rossum 
On Fri, Apr 29, 2022 at 10:15 AM Petr Viktorin  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.
> >
> > Honestly, I would be more comfortable with the name: "unstable API".
> > It would be clear that the API *can* change often. People who want to
> > know exactly the backward compatibility warranties can dig into the
> > API documentation to learn more about it.
> >
> > "Unstable API" is also the name the Guido proposed for PyCode_New() last
> year:
> >
> > * Proposal: declare "unstable APIs"
> >
> https://mail.python.org/archives/list/[email protected]/thread/JM6SQ2YNMDAKXYD5O54QWMVR2X7QOXVL/
> > * Making code object APIs unstable
> >
> https://mail.python.org/archives/list/[email protected]/thread/ZWTBR5ESYR26BUIVMXOKPFRLGGYDJSFC/
> >
> > Victor
>
>
> Nick Coghlan argued against that term:
>
> > "unstable" is the wrong term. We already have an unstable API tier: the
> > internal API, which can change even in maintenance releases. The value of
> > the new tier is that it is "semi stable": stable in maintenance releases,
> > unstable in feature releases.
>
> —
>
> https://mail.python.org/archives/list/[email protected]/message/CTKKTHUV5R2A2RRN5DM32UQFNC42DDGJ/
>
>
> 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".

-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/PVW7BB5MEHI7RPVIKN7JSMCSACVKKBI7/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Petr Viktorin 

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.

Honestly, I would be more comfortable with the name: "unstable API".
It would be clear that the API *can* change often. People who want to
know exactly the backward compatibility warranties can dig into the
API documentation to learn more about it.

"Unstable API" is also the name the Guido proposed for PyCode_New() last year:

* Proposal: declare "unstable APIs"

https://mail.python.org/archives/list/[email protected]/thread/JM6SQ2YNMDAKXYD5O54QWMVR2X7QOXVL/
* Making code object APIs unstable

https://mail.python.org/archives/list/[email protected]/thread/ZWTBR5ESYR26BUIVMXOKPFRLGGYDJSFC/

Victor



Nick Coghlan argued against that term:


"unstable" is the wrong term. We already have an unstable API tier: the
internal API, which can change even in maintenance releases. The value of
the new tier is that it is "semi stable": stable in maintenance releases,
unstable in feature releases.


— 
https://mail.python.org/archives/list/[email protected]/message/CTKKTHUV5R2A2RRN5DM32UQFNC42DDGJ/



But I also like “unstable” better than “semi-stable”. Splitting the 
internals into “private”/“internal” and “unstable” seems reasonable.

___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/MPOPMXJ7AZHE5MGSKCMJO4ZDJERMQNHE/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Victor Stinner 
> Rejected Ideas
> ==
>
> It might be good to add a similar tier in the Python (not C) API,
> e.g. for ``types.CodeType``.
> However, the opt-in mechanism would need to be different (if any).
> This is outside the scope of the PEP.

For types.CodeType constructor, would it be possible to just a mention
in the *documentation* that this API is "unstable"? It would come with
a link to definition of the "unstable" C API: explain that it can
change in 3.x.y bugfix releases, not not in 3.x.0 releases (major?
minor? I never recall how they should be called).

For now, I don't think that there is a need to actively remove this
API from the "default" Python API and add an opt-in option to get
access to these functions. But having a mention just in the
documentation would be better than nothing.

It seems to be popular complain and request. For example, most of the
ast module would fall into this "unstable API". Previous discussions:

* Proposal: declare "unstable APIs"
   
https://mail.python.org/archives/list/[email protected]/thread/JM6SQ2YNMDAKXYD5O54QWMVR2X7QOXVL/
* Making code object APIs unstable
   
https://mail.python.org/archives/list/[email protected]/thread/ZWTBR5ESYR26BUIVMXOKPFRLGGYDJSFC/

On one side, it's important to communicate that the API *can* change
in 3.x.0 releases, but also provide some warranties that the API *must
not change* in 3.x.y bugfix releases.

Victor
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/AS7KUFPSGNRNBUKMXPHHKHXAVDAZH2AT/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 689 – Semi-stable C API tier

2022-04-29 Thread Victor Stinner 
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.

Honestly, I would be more comfortable with the name: "unstable API".
It would be clear that the API *can* change often. People who want to
know exactly the backward compatibility warranties can dig into the
API documentation to learn more about it.

"Unstable API" is also the name the Guido proposed for PyCode_New() last year:

* Proposal: declare "unstable APIs"
   
https://mail.python.org/archives/list/[email protected]/thread/JM6SQ2YNMDAKXYD5O54QWMVR2X7QOXVL/
* Making code object APIs unstable
   
https://mail.python.org/archives/list/[email protected]/thread/ZWTBR5ESYR26BUIVMXOKPFRLGGYDJSFC/

Victor
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/UIUCHEVHLUJJFDZASBDTUDHLW4PIZWLP/
Code of Conduct: http://python.org/psf/codeofconduct/