Mailing List Archive

I would love to see header files used for this -- while I know there is a
long tradition of feature-flags that must be #defined by the user before
#including a header in order to affect what the header exports (or not!),
30 years later I still find that approach pretty unintuitive.

But yes, it's going to be a complex transition.


On Mon, May 30, 2022 at 12:30 PM Brett Cannon <brett@python.org> wrote:

> We discussed having leading underscores for this API tier, and it was
> decided that a leading underscore was preferred.
>
> This did start a discussion, though, about whether we should control API
> access/opt-in via `#include` by having `.h` files that convey what API the
> user is opting into, or use `#define` to control what gets exposed via
> `Python.h`. The general feeling was that the header file idea is ideal, but
> it is a little extra work to transition to if you want to be compatible
> with older versions of Python that wouldn't have the header files (Victor's
> compatibility project could help here). The question for the team is
> whether separate header files makes sense to others, or would people prefer
> using `#define` and `Python.h` to control API access/opt-in?
> _______________________________________________
> 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/Q5JU5YKGX2U2UAAILDH45S5UGN6GLVXT/
> Code of Conduct: http://python.org/psf/codeofconduct/
>


--
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*
<http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-change-the-world/>

I prefer separate header files, provided people outside of core always
have one (presumably "Python.h") that should be included first and
includes enough info to check which headers will be available (i.e. the
version defs).

Modifying preprocessor definitions for different Python versions, or
having to set them before knowing what version is being used, seems more
complicated.

Cheers,
Steve

On 5/30/2022 8:26 PM, Brett Cannon wrote:
> We discussed having leading underscores for this API tier, and it was decided that a leading underscore was preferred.
>
> This did start a discussion, though, about whether we should control API access/opt-in via `#include` by having `.h` files that convey what API the user is opting into, or use `#define` to control what gets exposed via `Python.h`. The general feeling was that the header file idea is ideal, but it is a little extra work to transition to if you want to be compatible with older versions of Python that wouldn't have the header files (Victor's compatibility project could help here). The question for the team is whether separate header files makes sense to others, or would people prefer using `#define` and `Python.h` to control API access/opt-in?
_______________________________________________
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/NMIULT7IJA77KYNFQGNQYV5LOVLV3FSV/
Code of Conduct: http://python.org/psf/codeofconduct/

On Mon, May 30, 2022 at 12:54 PM Steve Dower <steve.dower@python.org> wrote:

> I prefer separate header files, provided people outside of core always
> have one (presumably "Python.h") that should be included first and
> includes enough info to check which headers will be available (i.e. the
> version defs).
>

The idea we were kicking around was e.g. `Python-unstable.h` would be all
of the limited API plus the unstable parts, `Python-unlimited.h` would be
**everything**, etc. I would expect `Python.h` would continue to be what it
is today for compatibility purposes. There wouldn't necessarily be an
"always have one" header since these header files would cascade into each
other as you opted into more and more unstable APIs (think about this as
layers of APIs ???? and representing each encompassing layer with a header
file). This would also let teams set policies of how much instability risk
they were willing to take by having CI have an allowlist/blocklist of
Python header files.

-Brett


>
> Modifying preprocessor definitions for different Python versions, or
> having to set them before knowing what version is being used, seems more
> complicated.
>

> Cheers,
> Steve
>
> On 5/30/2022 8:26 PM, Brett Cannon wrote:
> > We discussed having leading underscores for this API tier, and it was
> decided that a leading underscore was preferred.
> >
> > This did start a discussion, though, about whether we should control API
> access/opt-in via `#include` by having `.h` files that convey what API the
> user is opting into, or use `#define` to control what gets exposed via
> `Python.h`. The general feeling was that the header file idea is ideal, but
> it is a little extra work to transition to if you want to be compatible
> with older versions of Python that wouldn't have the header files (Victor's
> compatibility project could help here). The question for the team is
> whether separate header files makes sense to others, or would people prefer
> using `#define` and `Python.h` to control API access/opt-in?
>

On Mon, 30 May 2022 12:53:57 -0700
Guido van Rossum <guido@python.org> wrote:
> I would love to see header files used for this -- while I know there is a
> long tradition of feature-flags that must be #defined by the user before
> #including a header in order to affect what the header exports (or not!),
> 30 years later I still find that approach pretty unintuitive.

Agreed that #defining a flag before #including a header is a brittle
approach. If something else included the header before you set your
#define, then include guards can prevent you from seeing any effects.

This is a common issue in Windows land with the godawful Windows.h
header file.

Regards

Antoine.



>
> But yes, it's going to be a complex transition.
>
>
> On Mon, May 30, 2022 at 12:30 PM Brett Cannon <brett@python.org> wrote:
>
> > We discussed having leading underscores for this API tier, and it was
> > decided that a leading underscore was preferred.
> >
> > This did start a discussion, though, about whether we should control API
> > access/opt-in via `#include` by having `.h` files that convey what API the
> > user is opting into, or use `#define` to control what gets exposed via
> > `Python.h`. The general feeling was that the header file idea is ideal, but
> > it is a little extra work to transition to if you want to be compatible
> > with older versions of Python that wouldn't have the header files (Victor's
> > compatibility project could help here). The question for the team is
> > whether separate header files makes sense to others, or would people prefer
> > using `#define` and `Python.h` to control API access/opt-in?
> > _______________________________________________
> > 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/Q5JU5YKGX2U2UAAILDH45S5UGN6GLVXT/
> > Code of Conduct: http://python.org/psf/codeofconduct/
> >
>
>



_______________________________________________
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/5LUUISSYTQOFQQWUVOH2GUGQJLMYGFAT/
Code of Conduct: http://python.org/psf/codeofconduct/

Sasha Kacanski writes:

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

This is exactly what they're hammering out. It's not easy for several
reasons, chief of which is that in each case the boundary is a matter
of opinion as to the balance among what is most convenient for the
developers of Python itself, the developers of separately distributed
C/C++ modules, and for existing modules that were developed before the
divisions were set and would need to either be changed or to risk
API incompatibility with future versions of Python. The nomenclature
also matters, as individual programmers have various ideas about the
meaning of terms like "stable", and we want as much agreement as
possible that the "stable API" is "stable enough", and so on.

If you have specific ideas about which APIs belong where, feel free to
bring them forward. But this is not a process that should be rushed
nor would anyone benefit from pushing it forward more quickly.

_______________________________________________
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/3TDSVISHIV7PZPRDAI5ZRHNZYARH6J3O/
Code of Conduct: http://python.org/psf/codeofconduct/

I understand issues and welcome any discussions. For that matter I do not
rush to conclusions. I am not expert in C and Python as the rest of the
folks on this list
but I am pretty good with Python itself. I just suggested naming to be as
simple as possible for all relevant API's including full descriptions in
the code base regarding stable, semi-stable, unstable and so forth. I do
that in my projects with Python libraries I write ...
Sorry for intruding and possibly clouding the email thread...
Regards,




On Wed, Jun 1, 2022, 4:39 AM Stephen J. Turnbull <stephenjturnbull@gmail.com>
wrote:

> Sasha Kacanski writes:
>
> > Why you don't simplify with api A,B,C and forth and then follows
> > explanation ofr what is stable, unstable, semi... So forth....
>
> This is exactly what they're hammering out. It's not easy for several
> reasons, chief of which is that in each case the boundary is a matter
> of opinion as to the balance among what is most convenient for the
> developers of Python itself, the developers of separately distributed
> C/C++ modules, and for existing modules that were developed before the
> divisions were set and would need to either be changed or to risk
> API incompatibility with future versions of Python. The nomenclature
> also matters, as individual programmers have various ideas about the
> meaning of terms like "stable", and we want as much agreement as
> possible that the "stable API" is "stable enough", and so on.
>
> If you have specific ideas about which APIs belong where, feel free to
> bring them forward. But this is not a process that should be rushed
> nor would anyone benefit from pushing it forward more quickly.
>
>