[Python-ideas] Deprecation utilities for the warnings module

[Ryan Gonzalez]

I have to say, this would be amazing! I've basically had to create many of
these by hand over time, and I doubt I'm the only person who's wondered how
this isn't in the stdlib!

On Thu, Sep 13, 2018, 7:18 PM Ilya Kulakov <kulakov.ilya at gmail.com> wrote:

> (Apologies if it's a duplicate. I originally posted to
> python-ideas at googlegroups.com)
>
> I've been recently working on an internal library written
> entirely in Python. The library while being under development
> was as actively used by other teams. The product was under
> pressure and hasty design decisions were made.
> Certain  interfaces were exposed before scope of the problem
> was entirely clear.
>
> Didn't take long before the code started to beg for refactoring.
> But compatibility needed to be preserved. As a result a set of utilities,
> which I'd like to share, came to life.
>
> ---
>
> The warnings module is a robust foundation. Authors can warn
> what should be avoided and users can choose how to act.
> However in its current form it still requires utilities
> to be useful. E.g. it's non-trivial to properly replace
> a deprecated class.
>
> I'd like to propose an extension for the warnings module
> to address this problem.
>
> The extensions consists of 4 decorators:
> - @deprecated
> - @obsolete
> - @deprecated_arg
> - @obsolete_arg
>
> The @deprecated decorator marks an object to issue a warning
> if it's used:
> - Callable objects issue a warning upon a call
> - Property attributes issue a warning upon an access
> - Classes issue a warning upon instantiation and subclassing
>   (directly or via a metaclass)
>
> The @obsolete decorator marks an object in the same way
> as @deprecated does but forwards usage to the replacement:
> - Callable object redirect the call
> - Property attribute redirect the access (get / set / del)
> - Class is replaced in a way that during both instantiation
>   and subclassing replacement is used
>
> In case of classes extra care is taken to preserve validity
> of existing isinstance and issubclass checks.
>
> The @deprecated_arg and @obsolete_arg work with signatures
> of callable objects. Upon a call either a warning is issued
> or an argument mapping is performed.
>
> Please take a look at the implementation and a few examples:
> https://gist.github.com/Kentzo/53df97c7a54609d3febf5f8eb6b67118
>
> Why I think it should be a part of stdlib:
> - Library authors are reluctant to add dependencies
>   especially when it's for internal usage
> - Ease of use will reduce compatibility problems
>   and ease migration burden since the soltion will be
>   readily available
> - IDEs and static analyzers are more likely
>   to support it
>
> ---
>
> Joshua Harlow shared a link to OpenStack's debtcollector:
> https://docs.openstack.org/debtcollector/latest/reference/index.html
> Certain aspects of my implementation are inspired by it.
>
> Please let me know what you think about the idea in general
> and implementation in particular. If that's something the community
> is interested in, I'm willing to work on it.
>
>
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>
-- 

Ryan (ライアン)
Yoko Shimomura, ryo (supercell/EGOIST), Hiroyuki Sawano >> everyone else
https://refi64.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20180913/642c376f/attachment-0001.html>