Metadata-Version: 1.0
Name: zope.deprecation
Version: 3.4.1
Summary: Zope Deprecation Infrastructure
Home-page: http://pypi.python.org/pypi/zope.deprecation
Author: Zope Corporation and Contributors
Author-email: zope-dev@zope.org
License: ZPL 2.1
Description: This package provides a simple function called ``deprecated(names, reason)`` to
        mark deprecated modules, classes, functions, methods and properties.
        
        
        .. contents::
        
        
        ===============
        Deprecation API
        ===============
        
        Deprecating objects inside a module
        -----------------------------------
        
        Let'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 deprecated
          demo1 = 1
          deprecated('demo1', 'demo1 is no more.')
        
          demo2 = 2
          deprecated('demo2', 'demo2 is no more.')
        
          demo3 = 3
          deprecated('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.
          ...
          2
        
        You 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.
          ...
          4
        
        Deprecating methods and properties
        ----------------------------------
        
        New 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 5
        
        And 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.
          ...
          5
        
        Deprecating modules
        -------------------
        
        It 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['zope.wanda'] = 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.modules['zope.wanda']
        
        Moving modules
        --------------
        
        When 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
          42
        
        Moving packages
        ---------------
        
        When 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 m3
        
        
        
        Temporarily turning off deprecation warnings
        --------------------------------------------
        
        In 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.
          ...
          1
        
        You can turn off the depraction warnings using
        
          >>> __show__.off()
          >>> __show__()
          False
        
          >>> foo.blah
          1
        
        Now, you can also nest several turn-offs, so that calling ``off()`` multiple
        times is meaningful:
        
          >>> __show__.stack
          [False]
        
          >>> __show__.off()
          >>> __show__.stack
          [False, False]
        
          >>> __show__.on()
          >>> __show__.stack
          [False]
          >>> __show__()
          False
        
          >>> __show__.on()
          >>> __show__.stack
          []
          >>> __show__()
          True
        
        You can also reset ``__show__`` to ``True``:
        
          >>> __show__.off()
          >>> __show__.off()
          >>> __show__()
          False
        
          >>> __show__.reset()
          >>> __show__()
          True
        
        Finally, you cannot call ``on()`` without having called ``off()`` before:
        
          >>> __show__.on()
          Traceback (most recent call last):
          ...
          IndexError: pop from empty list
        
        
        =======
        CHANGES
        =======
        
        3.4.1 (2011-06-07)
        ------------------
        
        - 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.
        
        
        3.4.0 (2007-07-19)
        ------------------
        
        - Release 3.4 final, corresponding to Zope 3.4.
        
        
        3.3.0 (2007-02-18)
        ------------------
        
        - Corresponds to the version of the ``zope.deprecation`` package shipped as
          part of the Zope 3.3.0 release.
        
Platform: UNKNOWN
