introducing a more well-defined "legacy" API status

Hi all, We've got a number of (sets of) APIs that we keep around for backwards compatibility reasons, but that are not recommended to use in new code. The way we mark those APIs varies, and often it's not exactly clear that they shouldn't be used. Examples of legacy APIs: 1. `scipy.fftpack` 2. the functional interface to FITPACK (see, e.g., the Notes section of http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.splev.h... ) What do you think about adding a formal API status "legacy", and having a uniform way of marking such APIs? That could be for example a `.. legacy::` reST directive that gives a warning box near the top of the docs. The benefits would be (a) that it's clearer to end users that there is a better alternative, (b) it's clearer to other projects that they should not copy these APIs (thinking of CuPy, Dask, etc. here), and (c) there is a good intermediate state between "supported" and "deprecated" so that if we're not in agreement on the cost of a deprecation, we can move something to "legacy" instead rather than do nothing. Thoughts? Cheers, Ralf

Isn't that what PendingDeprecationWarning is for ?
Base class for warnings about features which are obsolete and expected to be deprecated in the future, but are not deprecated at the moment [1]
I think it's underused. The Main difference with DeprecationWarning being that DeprecationWarning is not ignored in __main__ but PendingDW is. -- M [1] : from https://docs.python.org/3/library/exceptions.html#PendingDeprecationWarning On Tue, 31 May 2022 at 14:28, Ralf Gommers <ralf.gommers@gmail.com> wrote:
Hi all,
We've got a number of (sets of) APIs that we keep around for backwards compatibility reasons, but that are not recommended to use in new code. The way we mark those APIs varies, and often it's not exactly clear that they shouldn't be used.
Examples of legacy APIs: 1. `scipy.fftpack` 2. the functional interface to FITPACK (see, e.g., the Notes section of http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.splev.h...)
What do you think about adding a formal API status "legacy", and having a uniform way of marking such APIs? That could be for example a `.. legacy::` reST directive that gives a warning box near the top of the docs.
The benefits would be (a) that it's clearer to end users that there is a better alternative, (b) it's clearer to other projects that they should not copy these APIs (thinking of CuPy, Dask, etc. here), and (c) there is a good intermediate state between "supported" and "deprecated" so that if we're not in agreement on the cost of a deprecation, we can move something to "legacy" instead rather than do nothing.
Thoughts?
Cheers, Ralf
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: bussonniermatthias@gmail.com

On Tue, May 31, 2022 at 2:35 PM Matthias Bussonnier < bussonniermatthias@gmail.com> wrote:
Isn't that what PendingDeprecationWarning is for ?
No it isn't, PendingDeprecationWarning means "we're planning to deprecate it", which is definitely not the same as "we're keeping it, but there's a better alternative now". Also, it emits a warning which means that other projects with policies like SciPy need to deal with it immediately, which is bad. Cheers, Ralf
Base class for warnings about features which are obsolete and expected to be deprecated in the future, but are not deprecated at the moment [1]
I think it's underused. The Main difference with DeprecationWarning being that DeprecationWarning is not ignored in __main__ but PendingDW is.
-- M
[1] : from https://docs.python.org/3/library/exceptions.html#PendingDeprecationWarning
On Tue, 31 May 2022 at 14:28, Ralf Gommers <ralf.gommers@gmail.com> wrote:
Hi all,
We've got a number of (sets of) APIs that we keep around for backwards
compatibility reasons, but that are not recommended to use in new code. The way we mark those APIs varies, and often it's not exactly clear that they shouldn't be used.
Examples of legacy APIs: 1. `scipy.fftpack` 2. the functional interface to FITPACK (see, e.g., the Notes section of
http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.splev.h... )
What do you think about adding a formal API status "legacy", and having
a uniform way of marking such APIs? That could be for example a `.. legacy::` reST directive that gives a warning box near the top of the docs.
The benefits would be (a) that it's clearer to end users that there is a
better alternative, (b) it's clearer to other projects that they should not copy these APIs (thinking of CuPy, Dask, etc. here), and (c) there is a good intermediate state between "supported" and "deprecated" so that if we're not in agreement on the cost of a deprecation, we can move something to "legacy" instead rather than do nothing.
Thoughts?
Cheers, Ralf
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: bussonniermatthias@gmail.com
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: ralf.gommers@gmail.com

Sounds like a great idea to me. I think we'd want to use it sparingly and deprecate the rest, but there are definitely situations in which a legacy status would be appropriate. My next thought is whether legacy functionality could *ever *be removed, but the timeline after declaring legacy status and eventual removal (or moving to a separate package?) is probably long enough that an endgame plan doesn't necessarily need to hold up this idea. Would we need to maintain legacy code? Maybe simple bug fixes would be considered, but no enhancements, and nothing backward-incompatible? On Tue, May 31, 2022 at 5:45 AM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Tue, May 31, 2022 at 2:35 PM Matthias Bussonnier < bussonniermatthias@gmail.com> wrote:
Isn't that what PendingDeprecationWarning is for ?
No it isn't, PendingDeprecationWarning means "we're planning to deprecate it", which is definitely not the same as "we're keeping it, but there's a better alternative now". Also, it emits a warning which means that other projects with policies like SciPy need to deal with it immediately, which is bad.
Cheers, Ralf
Base class for warnings about features which are obsolete and expected to be deprecated in the future, but are not deprecated at the moment [1]
I think it's underused. The Main difference with DeprecationWarning being that DeprecationWarning is not ignored in __main__ but PendingDW is.
-- M
[1] : from https://docs.python.org/3/library/exceptions.html#PendingDeprecationWarning
On Tue, 31 May 2022 at 14:28, Ralf Gommers <ralf.gommers@gmail.com> wrote:
Hi all,
We've got a number of (sets of) APIs that we keep around for backwards
compatibility reasons, but that are not recommended to use in new code. The way we mark those APIs varies, and often it's not exactly clear that they shouldn't be used.
Examples of legacy APIs: 1. `scipy.fftpack` 2. the functional interface to FITPACK (see, e.g., the Notes section of
http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.splev.h... )
What do you think about adding a formal API status "legacy", and having
a uniform way of marking such APIs? That could be for example a `.. legacy::` reST directive that gives a warning box near the top of the docs.
The benefits would be (a) that it's clearer to end users that there is
a better alternative, (b) it's clearer to other projects that they should not copy these APIs (thinking of CuPy, Dask, etc. here), and (c) there is a good intermediate state between "supported" and "deprecated" so that if we're not in agreement on the cost of a deprecation, we can move something to "legacy" instead rather than do nothing.
Thoughts?
Cheers, Ralf
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: bussonniermatthias@gmail.com
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: ralf.gommers@gmail.com
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: haberland@ucla.edu
-- Matt Haberland Assistant Professor BioResource and Agricultural Engineering 08A-3K, Cal Poly

+1 for a big fat note in the docs (via .. legacy:: directive), preferably with a link to a recommended replacement. -1 for emitting warnings from legacy APIs. This way, we cater to both legacy uses ("it does the job even though the author graduated a decade ago") and those who write new code. When an API is declared legacy, I guess, its development stops. All remaining bugs and warts are declared features, we promise to keep it in future versions (until further notice of course, legacy stuff can migrate to deprecated and removed if needs be), and we only promise to keep it working. I.e. if it does not compile on a new python version, we'll try to fix that, but no more. We now have a better way of doing whatever this thing was doing, come join us working on this new bright and shiny thing. Or, if you want things which used to work "forever", great, they keep working just like they did. Cheers, Evgeni P.S. For FITPACK specifically, I'd rather declare *UnivariateSplines legacy, not the spl* functional interface. But it's a separate, minor point. On Tue, May 31, 2022 at 7:06 PM Matt Haberland <mhaberla@calpoly.edu> wrote:
Sounds like a great idea to me. I think we'd want to use it sparingly and deprecate the rest, but there are definitely situations in which a legacy status would be appropriate.
My next thought is whether legacy functionality could ever be removed, but the timeline after declaring legacy status and eventual removal (or moving to a separate package?) is probably long enough that an endgame plan doesn't necessarily need to hold up this idea.
Would we need to maintain legacy code? Maybe simple bug fixes would be considered, but no enhancements, and nothing backward-incompatible?
On Tue, May 31, 2022 at 5:45 AM Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Tue, May 31, 2022 at 2:35 PM Matthias Bussonnier <bussonniermatthias@gmail.com> wrote:
Isn't that what PendingDeprecationWarning is for ?
No it isn't, PendingDeprecationWarning means "we're planning to deprecate it", which is definitely not the same as "we're keeping it, but there's a better alternative now". Also, it emits a warning which means that other projects with policies like SciPy need to deal with it immediately, which is bad.
Cheers, Ralf
Base class for warnings about features which are obsolete and expected to be deprecated in the future, but are not deprecated at the moment [1]
I think it's underused. The Main difference with DeprecationWarning being that DeprecationWarning is not ignored in __main__ but PendingDW is.
-- M
[1] : from https://docs.python.org/3/library/exceptions.html#PendingDeprecationWarning
On Tue, 31 May 2022 at 14:28, Ralf Gommers <ralf.gommers@gmail.com> wrote:
Hi all,
We've got a number of (sets of) APIs that we keep around for backwards compatibility reasons, but that are not recommended to use in new code. The way we mark those APIs varies, and often it's not exactly clear that they shouldn't be used.
Examples of legacy APIs: 1. `scipy.fftpack` 2. the functional interface to FITPACK (see, e.g., the Notes section of http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.splev.h...)
What do you think about adding a formal API status "legacy", and having a uniform way of marking such APIs? That could be for example a `.. legacy::` reST directive that gives a warning box near the top of the docs.
The benefits would be (a) that it's clearer to end users that there is a better alternative, (b) it's clearer to other projects that they should not copy these APIs (thinking of CuPy, Dask, etc. here), and (c) there is a good intermediate state between "supported" and "deprecated" so that if we're not in agreement on the cost of a deprecation, we can move something to "legacy" instead rather than do nothing.
Thoughts?
Cheers, Ralf
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: bussonniermatthias@gmail.com
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: ralf.gommers@gmail.com
_______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: haberland@ucla.edu
-- Matt Haberland Assistant Professor BioResource and Agricultural Engineering 08A-3K, Cal Poly _______________________________________________ SciPy-Dev mailing list -- scipy-dev@python.org To unsubscribe send an email to scipy-dev-leave@python.org https://mail.python.org/mailman3/lists/scipy-dev.python.org/ Member address: evgeny.burovskiy@gmail.com

On Tue, May 31, 2022 at 2:09 PM Evgeni Burovski <evgeny.burovskiy@gmail.com> wrote:
+1 for a big fat note in the docs (via .. legacy:: directive), preferably with a link to a recommended replacement. -1 for emitting warnings from legacy APIs.
This way, we cater to both legacy uses ("it does the job even though the author graduated a decade ago") and those who write new code.
When an API is declared legacy, I guess, its development stops. All remaining bugs and warts are declared features, we promise to keep it in future versions (until further notice of course, legacy stuff can migrate to deprecated and removed if needs be), and we only promise to keep it working. I.e. if it does not compile on a new python version, we'll try to fix that, but no more. We now have a better way of doing whatever this thing was doing, come join us working on this new bright and shiny thing. Or, if you want things which used to work "forever", great, they keep working just like they did.
I wouldn't necessarily *forbid* bug fixes to *all* things marked as legacy. For some things, like RandomState in numpy, it's warranted because very strict bug-for-bug backwards compatibility has some desirability. For most things that are legacy, the main point is just that bug fixes are at the bottom of our general priority queue. But sometimes a quick fix is simple enough that it rises up on *someone's* priority queue. So committers SHOULD <https://datatracker.ietf.org/doc/html/rfc2119> close bug *reports* on legacy components, and committers (and especially release managers) MAY veto legacy-bug-fixing PRs that are contributed, but could also accept them. -- Robert Kern
participants (5)
-
Evgeni Burovski
-
Matt Haberland
-
Matthias Bussonnier
-
Ralf Gommers
-
Robert Kern