zope.deprecation Zope Deprecation Infrastructure
Download

zope.deprecation Ranking & Summary

zope.deprecation Tags

Zope infrastructure Zope deprecation deprecation infrastructure deprecated modules deprecation

zope.deprecation Description

Zope Deprecation Infrastructure zope.deprecation provides a simple function called deprecated(names, reason) to mark deprecated modules, classes, functions, methods and properties.Deprecation APIDeprecating objects inside a moduleLet's start with a demonstration of deprecating any name inside a module. To demonstrate the functionality, I have placed the following code inside the tests.py file of this package:from zope.deprecation import deprecateddemo1 = 1deprecated('demo1', 'demo1 is no more.')demo2 = 2deprecated('demo2', 'demo2 is no more.')demo3 = 3deprecated('demo3', 'demo3 is no more.')The first argument to the deprecated() function is a list of names that should be declared deprecated. If the first argument is a string, it is interpreted as one name. The second argument is the reason the particular name has been deprecated. It is good practice to also list the version in which the name will be removed completely.Let's now see how the deprecation warnings are displayed. >>> from zope.deprecation import tests >>> tests.demo1 From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: demo1: demo1 is no more. ... 1 >>> import zope.deprecation.tests >>> zope.deprecation.tests.demo2 From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: demo2: demo2 is no more. ... 2You can see that merely importing the affected module or one of its parents does not cause a deprecation warning. Only when we try to access the name in the module, we get a deprecation warning. On the other hand, if we import the name directly, the deprecation warning will be raised immediately. >>> from zope.deprecation.tests import demo3 From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: demo3: demo3 is no more. ...Deprecation can also happen inside a function. When we first access demo4, it can be accessed without problems, then we call a function that sets the deprecation message and we get the message upon the next access: >>> tests.demo4 4 >>> tests.deprecatedemo4() >>> tests.demo4 From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: demo4: demo4 is no more. ... 4Deprecating methods and propertiesNew let's see how properties and methods can be deprecated. We are going to use the same function as before, except that this time, we do not pass in names as first argument, but the method or attribute itself. The function then returns a wrapper that sends out a deprecation warning when the attribute or method is accessed. >>> from zope.deprecation import deprecation >>> class MyComponent(object): ... foo = property(lambda self: 1) ... foo = deprecation.deprecated(foo, 'foo is no more.') ... ... bar = 2 ... ... def blah(self): ... return 3 ... blah = deprecation.deprecated(blah, 'blah() is no more.') ... ... def splat(self): ... return 4 ... ... @deprecation.deprecate("clap() is no more.") ... def clap(self): ... return 5And here is the result: >>> my = MyComponent() >>> my.foo From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: foo is no more. ... 1 >>> my.bar 2 >>> my.blah() From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: blah() is no more. ... 3 >>> my.splat() 4 >>> my.clap() From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: clap() is no more. ... 5Deprecating modulesIt is also possible to deprecate whole modules. This is useful when creating module aliases for backward compatibility. Let's imagine, the zope.deprecation module used to be called zope.wanda and we'd like to retain backward compatibility: >>> import zope.deprecation >>> import sys >>> sys.modules = deprecation.deprecated( ... zope.deprecation, 'A module called Wanda is now zope.deprecation.')Now we can import wanda, but when accessing things from it, we get our deprecation message as expected: >>> from zope.wanda import deprecated From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: A module called Wanda is now zope.deprecation. ...Before we move on, we should clean up: >>> del deprecated >>> del sys.modulesMoving modulesWhen a module is moved, you often want to support importing from the old location for a while, generating a deprecation warning when someone uses the old location. This can be done using the moved function.To see how this works, we'll use a helper function to create two fake modules in the zope.deprecation package. First will create a module in the "old" location that used the moved function to indicate the a module on the new location should be used: >>> create_module(old_location= ... ''' ... import zope.deprecation ... zope.deprecation.moved('zope.deprecation.new_location', 'version 2') ... ''')and we define the module in the new location: >>> create_module(new_location= ... '''\ ... print "new module imported" ... x = 42 ... ''')Now, if we import the old location, we'll see the output of importing the old location: >>> import zope.deprecation.old_location ... # doctest: +NORMALIZE_WHITESPACE From tests.py's showwarning(): ...zope/deprecation/README.txt:1: DeprecationWarning: zope.deprecation.old_location has moved to zope.deprecation.new_location. Import of zope.deprecation.old_location will become unsupported in version 2 =============== new module imported >>> zope.deprecation.old_location.x 42Moving packagesWhen moving packages, you need to leave placeholders for each module. Let's look at an example: >>> create_module({ ... 'new_package.__init__': '''\ ... print __name__, 'imported' ... x=0 ... ''', ... 'new_package.m1': '''\ ... print __name__, 'imported' ... x=1 ... ''', ... 'new_package.m2': '''\ ... print __name__, 'imported' ... def x(): ... pass ... ''', ... 'new_package.m3': '''\ ... print __name__, 'imported' ... x=3 ... ''', ... 'old_package.__init__': '''\ ... import zope.deprecation ... zope.deprecation.moved('zope.deprecation.new_package', 'version 2') ... ''', ... 'old_package.m1': '''\ ... import zope.deprecation ... zope.deprecation.moved('zope.deprecation.new_package.m1', 'version 2') ... ''', ... 'old_package.m2': '''\ ... import zope.deprecation ... zope.deprecation.moved('zope.deprecation.new_package.m2', 'version 2') ... ''', ... })Now, if we import the old modules, we'll get warnings: >>> import zope.deprecation.old_package ... # doctest: +NORMALIZE_WHITESPACE From tests.py's showwarning(): ...zope/deprecation/README.txt:1: DeprecationWarning: zope.deprecation.old_package has moved to zope.deprecation.new_package. Import of zope.deprecation.old_package will become unsupported in version 2 =============== zope.deprecation.new_package imported >>> zope.deprecation.old_package.x 0 >>> import zope.deprecation.old_package.m1 ... # doctest: +NORMALIZE_WHITESPACE From tests.py's showwarning(): ...zope/deprecation/README.txt:1: DeprecationWarning: zope.deprecation.old_package.m1 has moved to zope.deprecation.new_package.m1. Import of zope.deprecation.old_package.m1 will become unsupported in version 2 =============== zope.deprecation.new_package.m1 imported >>> zope.deprecation.old_package.m1.x 1 >>> import zope.deprecation.old_package.m2 ... # doctest: +NORMALIZE_WHITESPACE From tests.py's showwarning(): ...zope/deprecation/README.txt:1: DeprecationWarning: zope.deprecation.old_package.m2 has moved to zope.deprecation.new_package.m2. Import of zope.deprecation.old_package.m2 will become unsupported in version 2 =============== zope.deprecation.new_package.m2 imported >>> zope.deprecation.old_package.m2.x is zope.deprecation.new_package.m2.x True >>> (zope.deprecation.old_package.m2.x.func_globals ... is zope.deprecation.new_package.m2.__dict__) True >>> zope.deprecation.old_package.m2.x.__module__ 'zope.deprecation.new_package.m2'We'll get an error if we try to import m3, because we didn't create a placeholder for it: >>> import zope.deprecation.old_package.m3 Traceback (most recent call last): ... ImportError: No module named m3Temporarily turning off deprecation warningsIn some cases it is desireable to turn off the deprecation warnings for a short time. To support such a feature, the zope.deprecation package provides an attribute called __show__. One can ask for its status by calling it: >>> from zope.deprecation import __show__ >>> __show__() True >>> class Foo(object): ... bar = property(lambda self: 1) ... bar = deprecation.deprecated(bar, 'bar is no more.') ... blah = property(lambda self: 1) ... blah = deprecation.deprecated(blah, 'blah is no more.') >>> foo = Foo() >>> foo.bar From tests.py's showwarning(): ...README.txt:1: DeprecationWarning: bar is no more. ... 1You can turn off the depraction warnings using >>> __show__.off() >>> __show__() False >>> foo.blah 1Now, you can also nest several turn-offs, so that calling off() multiple times is meaningful: >>> __show__.stack >>> __show__.off() >>> __show__.stack >>> __show__.on() >>> __show__.stack >>> __show__() False >>> __show__.on() >>> __show__.stack [] >>> __show__() TrueYou can also reset __show__ to True: >>> __show__.off() >>> __show__.off() >>> __show__() False >>> __show__.reset() >>> __show__() TrueFinally, you cannot call on() without having called off() before: >>> __show__.on() Traceback (most recent call last): ... IndexError: pop from empty list Requirements: · Python What's New in This Release: · Removed import cycle for __show__ by defining it in the zope.deprecation.deprecation module. · Added support to bootstrap on Jython. · Fix zope.deprecation.warn() to make the signature identical to warnings.warn() and to check for .pyc and .pyo files.

zope.deprecation Related Software