profile
viewpoint

Ask questionsHandle deprecation in a standard and consistent way?

We have a couple things deprecated and pending removal in the future.

Can we have a standard and consistent methodology to handle deprecation and removal?

What we have now:

  • BaseAssignment.accesses calls warnings.warn(..., DeprecationWarning) when it's been called.
  • BatchableMetadataProvider, MetadataWrapper, and other metadata related classes were moved to libcst.metadata but there were still available in libcst for backward compatibility.
  • ExtSlice is deprecated and we have inline comments in the code.
  • SyntacticPositionProvider and BasicPositionProvider are about to be deprecated in https://github.com/Instagram/LibCST/pull/114
  • TODO: move BaseMetadataProvider to libcst.metadata

The warnings.warn(..., DeprecationWarning) seems to be a widely adopted way to warn on deprecation. Can we try to use it on all cases? For class deprecation, we don't want to just subclass since that may require lots of other changes to make existing callsite/type-checking work. Can we somehow have a helper to wrap all all methods in a class to call warnings.warn(..., DeprecationWarning)?

There are more things we can do, e.g. add the deprecation warning to readthedoc docs, so reader see it. Or explicitly declare the target version that deprecated things will be removed. There are deprecation packages provides a @deprecation to make all those easier:

  • https://deprecation.readthedocs.io/en/latest/
  • https://pypi.org/project/Deprecated/

Some projects put all deprecated things together in a doc for tracking, e.g. https://django.readthedocs.io/en/1.5.x/internals/deprecation.html https://github.com/numpy/numpy/issues/11521 This is more like a nice to have to me.

Instagram/LibCST

Answer questions bgw

I've seen a lot of projects use their changelog (and by extension, the github releases page) for declaring deprecations.

useful!

Related questions

3.8 Support hot 1
Github User Rank List