[Python-Dev] Policy on refactoring/clean up

[Nick Coghlan]

On 27 June 2018 at 15:27, Jeroen Demeyer <J.Demeyer at ugent.be> wrote:
> On 2018-06-27 00:02, Guido van Rossum wrote:
>>
>> And TBH a desire to refactor a lot of code is often a sign of a
>> relatively new contributor who hasn't learned their way around the code
>> yet, so they tend to want to make the code follow their understanding
>> rather than letting their understanding follow the code.
>
>
> ...or it could be that the code is written the way it is only for historical
> reasons, instead of being purposely written that way.

Even so, we're still wary of change-for-change's sake since it tends
to complicate maintenance of multiple concurrent release streams.

In this particular case though, since it's header file related, those
typically can't be backported for reasons of policy, so the risk of
interfering with an otherwise acceptable backport is likely to be low.

That leaves the "is there a clear motivation for API header
consolidation?" question, and I don't think the proposed consolidation
meets that bar, since it takes APIs from the abstract object API and
multiple concrete object APIs, as well as the legacy (no longer
documented) PyEval_* alternatives to the abstract object calling API,
and combines them into a single header based on a shared
categorisation of "calling things".

CPython's public API isn't structured that way, as we keep the
abstract object API and the concrete object API clearly distinct
(compare https://docs.python.org/3/c-api/abstract.html and
https://docs.python.org/3/c-api/concrete.html).

That said, the one part of the proposed change that I think could
definitely be reasonable is pulling the abstract call API (and
supporting definitions) out of "abstract.h" and into their own
"call.h" file (while leaving the concrete object API headers alone).
That gives a solid correlation between Include/call.h and
Objects/call.c, and I don't believe it's ever been the case that
abstract.h declared all the API functions that are part of the
PyObject_* namespace.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia