Package: housekeeping
Housekeeping for PythonHousekeeping is a Python package designed to make it easy for projects to mark
consumed code as deprecated or pending deprecation, with helpful instructions
for consumers using deprecated functionality.It's built with the lessons we learned inReview Board,Djblets, andRBTools.With Housekeeping, you can easily manage deprecations in your code, helping you
and any consumers of your code transition to the latest and greatest.It offers decorators, mixins, and functions to help with deprecating functions,
methods, classes, modules, attributes, parameters, and dictionary keys.Housekeeping is licensed under the MIT license.Installing HousekeepingHousekeeping is built as a utility library for your project. It should be
added to your project's list of dependencies.To install it manually, run:$pipinstallhousekeepingHousekeeping followssemantic versioning, meaning no
surprises when you upgrade.Using Housekeeping In Your ProjectAdd Your Deprecation ClassesAdd base deprecation warning classes to your project.There are two categories of warnings:Deprecation warnings, which mark code as being deprecated and
scheduled for removal in a specific upcoming version.Pending deprecation warnings, which mark code as being available but
scheduled to be deprecated in an unknown future version. Projects should
later transition these to full deprecation warnings.You'll be creating classes for each type that identify your project and any
upcoming versions where deprecated code may be removed.We recommend adding these to the<project_name>.deprecationmodule.For example:fromhousekeepingimportBasePendingRemovalWarning,BaseRemovedInWarningclassPendingRemovalInMyProjectWarning(BasePendingRemovalWarning):project='My Project'classBaseRemovedInMyProjectWarning(BaseRemovedInWarning):project='My Project'classRemovedInMyProject20Warning(BaseRemovedInMyProjectWarning):version='2.0'classRemovedInMyProject30Warning(BaseRemovedInMyProjectWarning):version='3.0'...Begin Deprecating CodeHousekeeping offers several deprecation helpers to deprecate code.You can also call.warn()on your deprecation classes to warn about
deprecated code at any time.Deprecating Functions@deprecate_non_keyword_only_argsThis decorator can help convert positional arguments to keyword-only arguments:fromhousekeepingimportdeprecate_non_keyword_only_args@deprecate_non_keyword_only_args(RemovedInMyProject20Warning)defadd_abc(a,*,b,c=1):returna+b+cadd_abc(1,2,3)# This will emit a deprecation warning.add_abc(1,b=2,c=3)# This will not.@func_deprecatedThis decorator marks a function as deprecated, or pending deprecation:fromhousekeepingimportfunc_deprecated@func_deprecated(RemovedInMyProject20Warning)defmy_func():...my_func()# This will emit a deprecation warning.@func_movedThis decorator marks a function as having moved elsewhere.fromhousekeepingimportfunc_movedfrommyproject.new_moduleimportmy_funcasnew_my_func# This can be invoked with some special behavior:@func_moved(RemovedInMyProject20Warning,new_func=new_my_func)defmy_func(a,b):new_my_func(a,b,True)my_func()# This will emit a deprecation warning.deprecated_arg_valueThis wraps values that, when accessed, emit a deprecation or pending
deprecation warning. It's useful for passing legacy data to callback handlers.fromhousekeepingimportdeprecated_arg_valuedefcallback_handler(username=None,user=None):user=get_user(username)# This will emit a deprecation warning.user=get_user(user)# This would not.classUser:...defemit_did_thing(self):callback_handler(user=self,username=deprecated_arg_value(RemovedInMyProject20Warning,owner_name='User',value=self.username,old_name='username',new_name='user'))Deprecating ClassesClassDeprecatedMixinThis class mixin will emit warnings when you either instantiate or subclass
the class.fromhousekeepingimportClassDeprecatedMixinclassMyOldClass(ClassDeprecatedMixin,warning_cls=RemovedInMyProject20Warning):pass# This will emit a deprecation warning.MyOldClass()# So will this.classMyChildClass(OldBaseClass):pass# But this will not.MyChildClass()# Nor will this.classMyGrandChildClass(MyChildClass):passClassMovedMixinThis class mixin will emit warnings when you either instantiate or subclass
the class, pointing you to a replacement class or import.fromhousekeepingimportClassDeprecatedMixinclassMyOldClass(ClassMovedMixin,MyNewBaseClass,warning_cls=RemovedInMyProject20Warning):pass# This will emit a deprecation warning.MyOldClass()# So will this.classMyChildClass(MyOldClass):pass# But this will not.MyChildClass()# Nor will this.classMyGrandChildClass(MyChildClass):passDeprecating Modulesmodule_deprecatedThis function can be called within a module body to emit a warning when the
module is imported.fromhousekeepingimportmodule_deprecatedfrommyproject.deprecationimportRemovedInMyProject20Warningmodule_deprecated(RemovedInMyProject20Warning,__name__)module_movedThis function can be called within a module body to emit a warning when the
module is imported, pointing the consumer to a replacement module. This is
useful when reorganizing the codebase and moving modules around.fromhousekeepingimportmodule_movedfrommyproject.deprecationimportRemovedInMyProject20Warningfrommyprojectimportnewmodulemodule_moved(RemovedInMyProject20Warning,__name__,newmodule.__name__)Our Other ProjectsReview Board-
Our free, open source, extensible code and document review tool.Djblets-
Our pack of Django utilities for datagrids, API, extensions, and more. Used
by Review Board.Review Bot-
Automated code review for Review Board.You can see more ongithub.com/beanbagincandgithub.com/reviewboard.