Re: Deprecating positional arguments for functions whose signatures are being already

I favor doing a wholesale change (option 1). I wouldn't put a ban on
incremental changes (option 2) that would take effect sooner, if motivated
by some other need.

I agree that the wholesale change sounds like a 2.0 thing. I'm happy with
the decorator being applied as soon as 2.0 discussion starts in earnest,
even without a firm date settled.

On Mon, Oct 23, 2023 at 5:05 AM Evgeni Burovski <[email protected]>
wrote:

> FWIW, I'd think
> - this is a good idea overall, and it's great to have momentum
> - this sounds to me like a SciPy 2.0 event. I know we don't have any
> specific plans for scipy 2.0; maybe this codebase-wide change could seed
> working out in more details of what is scipy 2.0 and when.
>
> My two cents,
>
> Evgeni
>
>
>
>
> On Mon, Oct 23, 2023 at 1:59 PM h.vetinari--- via SciPy-Dev <
> [email protected]> wrote:
>
>> Dear all,
>>
>> In the context of maintaining our APIs, previous discussions recognized
>> the advantages of using keyword-only arguments where appropriate, but it
>> was decided that a "big bang" change of all our APIs is not desired, and so
>> the current policy [1] states that this should only be done where APIs are
>> already being changed _anyway_, for example because a certain argument in
>> the signature is being removed (which would make positional-only use of all
>> following arguments invalid).
>>
>> In the context of the ongoing deprecation work, we (meaning mainly myself
>> and @j-bowhay) have taken this to mean "introduce the keyword-only cut-off
>> at the _natural_ point in the signature". Obviously there is some degree of
>> subjectivity in that, but I consider it strictly worse than doing nothing
>> to introduce the cut-off between positional-or-keyword and keyword-only at
>> exactly the point where a given deprecated argument gets removed. To me it
>> is a binary choice "whether to make a function keyword-only at its natural
>> point or not".
>>
>> To illustrate this distinction, let's imagine a function
>>
>> def func(x, y, z, option_A=..., option_B=..., option_C=...): ...
>>
>> Let's assume that option_B has become obsolete, or gets renamed, then -
>> strictly speaking - only option_C would need to become keyword-only, and
>> not option_A. However, I would argue that the only reasonable point to make
>> this function keyword only is as follows:
>>
>> def func(x, y, z, *, option_A=..., option_C=...): ...
>>
>> This results in a "net additional deprecation" of positional usage of
>> option_A vis-à-vis the most minimal deprecation to keep things working as
>> before that would look as follows:
>>
>> def func(x, y, z, option_A=..., *, option_C=...): ...
>>
>> This is worse IMO because it creates an inconsistency in how conceptually
>> equivalent arguments are treated in the API (one can be used positionally,
>> one cannot), and risks having to _again_ deprecate something in the
>> function if anything about option_A changes in the future.
>>
>> Obviously, not all examples are as clear-cut, and more than that,
>> sometimes a given deprecation only affects a subset of functions that
>> belong to an interrelated family, where the API should be consistent
>> overall. More context and discussion about this can be found in [2].
>>
>> For 1.12, we have taken all the functions being touched by deprecations
>> and handled them accordingly (in accordance with their respective owners,
>> in case the question about where to place the cut-off wasn't self-evident),
>> which happened early in 1.12 development. Currently, the affected functions
>> are (see also release notes):
>> * linalg.{eigh, eigvalsh, pinv}
>> * integrate.simpson
>> * signal.{firls, firwin, firwin2, remez}
>> * sparse.linalg.{bicg, bicgstab, cg, cgs, gcrotmk, gmres, lgmres, minres,
>> qmr, tfqmr}
>> * special.comb
>> * stats.kendalltau
>>
>> It's worth noting that in some cases we delayed signature changes already
>> announced for 1.12 or 1.13 to 1.14, in order to give people time to _also_
>> react to the fact that they now need to change away from positional usage
>> of some keyword arguments in those functions.
>>
>> There was some discussion in [2] about these additional deprecations
>> (e.g. the option_A case in the example above), resp. whether we should
>> revisit the choice about doing a wholesale change of our APIs like e.g.
>> scikit-learn did with SLEP009 [3].
>>
>> I agreed to bring up this topic on the mailing list - please let us know
>> your thoughts. The three broad choices (as far as I can tell) are:
>> 1. wholesale change à la SLEP009 (this will need more discussion and a
>> concrete plan of action IMO)
>> 2. keep doing incremental changes as currently present in main (but
>> changing over individual functions wholesale and not piecemeal w.r.t. their
>> signature)
>> 3. revert the change to keyword-only arguments for the above-mentioned
>> functions
>>
>> Option 2. represents the status quo of both the current documented policy
>> and the state of the repo on main.
>>
>> Best regards
>> H.
>>
>> [1]
>> https://docs.scipy.org/doc/scipy/dev/missing-bits.html#required-keyword-names
>> [2] https://github.com/scipy/scipy/issues/18703
>> [3] https://github.com/scikit-learn/scikit-learn/issues/15005
>> _______________________________________________
>> SciPy-Dev mailing list -- [email protected]
>> To unsubscribe send an email to [email protected]
>> https://mail.python.org/mailman3/lists/scipy-dev.python.org/
>> Member address: [email protected]
>>
> _______________________________________________
> SciPy-Dev mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://mail.python.org/mailman3/lists/scipy-dev.python.org/
> Member address: [email protected]
>

_______________________________________________
SciPy-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/scipy-dev.python.org/
Member address: [email protected]