技术控

    今日:88| 主题:49270
收藏本版 (1)
最新软件应用技术尽在掌握

[其他] futurepast - Deprecation tools for Python

[复制链接]
得味女人 发表于 2016-10-6 03:23:52
134 2

立即注册CoLaBug.com会员,免费获得投稿人的专业资料,享用更多功能,玩转个人品牌!

您需要 登录 才可以下载或查看,没有帐号?立即注册

x
futurepast

  Deprecation tools for Python (and humans)
  What are deprecations?

  Past me is often sloppy and makes bad decisions. Like giving functions or classes bad names, putting them in the wrong module, or choosing bad default values.
  Present me likes to fix this. But if someone else is actually using my code, any change to the user-facing API will break their code, make them unhappy, and in the end maybe even make them stop using my code.
  Some API changes can be dealt with in a way that doesn't break user code, though, through deprecations. Here is what I want from a deprecations:
  
       
  • If the user is relying on the old API, warn them that this API will be changed / removed in the future, and tell them how to fix it.   
  • Allow the user to change the code so they can make use of the new API.   
  • Make sure the user never has to worry about this ever again.   
  • Drop the old behavior at some point in the future, when all users had a chance to change their code.  
  The key idea is to allow users to choose when to go from the old API to the new API. The user is bugged with warnings until they take action and change their code. After the user took action, they shouldn't be bugged any more, though. When the old API is finally removed, the user shouldn't need to take any further action.
  What does futurepast do?

  The futurepast library is meant to make deprecations as pain-free for developers as possible, and help you to make sure no API is broken accidentally.
  It provides helpers to
  
       
  • rename, move and remove functions, methods, attributes, classes, modules and constants   
  • rename and remove parameters   
  • change default values of parameters  
  How does it work?

  Let's say we are in version    old_versionand we want to remove the old API in    new_version.  
  1. # remove a class
  2. from futurepast import remove
  3. @remove(past=old_version, future=new_version)
  4. class MyClass(object):
  5.     pass
  6. # remove a method
  7. class MyClass(object):
  8.     @remove(past=old_version, future=new_version)
  9.     def my_method(self):
  10.         pass
  11. # renamed a class from OldClass to NewClass
  12. from futurepast import move
  13. @move(old="OldClass", past=old_version, future=new_version)
  14. class NewClass(object):
  15.     pass
  16. # renaming parameter old_parameter to new_parameter
  17. from futurepast import rename_parameter
  18. @rename_parameter(old="old_parameter", new="new_parameter", past=old_version, future=new_version)
  19. def myfunc(new_parameter=default_value):
  20.     pass
  21. # changing default value of parameter
  22. from futurepast import changed_default
  23. @change_default(old=old_default, past=old_version, future=new_version)
  24. def myfunc(parameter=new_default)
  25.     pass
复制代码
To make it easy for the developer, any deprecation from    futurepastwill raise an error once    future(that is    new_version) arrives, so you know when to get rid of the old code.  
  Once the future arrives, it is enough to simply remove the    futurepastdecorator.  
  Assumptions on deprecations

  There are some assumptions that are made here for this to work, in particular:
  
       
  • Your users update frequently enough (which is the same as you wait long enough between deprecation and removal) that they will at some point use the version with the deprecation warning.   
  • Someone looks at the output of the code and sees the warning.   
  • They will actually take action.  
  The first one is the most tricky one, because it's the one you have to worry about. The second and third are somewhat on the users of your code.
  So is all good?

  Given the requirements on deprecations given above, some things can not be handled nicely. For example changing the return value of a function is not possible in this way, which is something I want to do A LOT. The best work-around might be to rename the function and give the new function the new behavior. There also currently no way to move anything into a different module automatically (because I haven't figured out how).
  Patterns to avoid

  
       
  • Avoid deprecations at all cost! Even if they are safe, they are still a hassle for the user!   
  • Don't break API without letting the user adjust!   
  • Don't make the user change the code twice, once on deprecation and once on removal!   
  • Don't keep warning the user after they made the change!  
友荐云推荐




上一篇:A new decentralized microblogging platform
下一篇:How We Built Our Own BI: When Off-The-Shelf Apps Won't Do
酷辣虫提示酷辣虫禁止发表任何与中华人民共和国法律有抵触的内容!所有内容由用户发布,并不代表酷辣虫的观点,酷辣虫无法对用户发布内容真实性提供任何的保证,请自行验证并承担风险与后果。如您有版权、违规等问题,请通过"联系我们"或"违规举报"告知我们处理。

寄琴 发表于 2016-10-6 05:23:08
怎么破
回复 支持 反对

使用道具 举报

印象 发表于 2016-10-6 21:03:07
我也来顶一下..
回复 支持 反对

使用道具 举报

*滑动验证:
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

我要投稿

推荐阅读

扫码访问 @iTTTTT瑞翔 的微博
回页顶回复上一篇下一篇回列表手机版
手机版/CoLaBug.com ( 粤ICP备05003221号 | 文网文[2010]257号 )|网站地图 酷辣虫

© 2001-2016 Comsenz Inc. Design: Dean. DiscuzFans.

返回顶部 返回列表