# Examples

## Removing a class/classmethod/method/function

To signal to a user that a method (staticmethod, classmethod, or regular instance method) or a class or function is going to be removed at some point in the future the `remove()` function/decorator can be used to achieve this in a non-destructive manner.

A basic example to do just this (on a method/function):

    >>> from debtcollector import removals
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> class Car(object):
    ...   @removals.remove
    ...   def start(self):
    ...     pass
    ...
    >>> c = Car()
    >>> c.start()

Expected output:

    __main__:1: DeprecationWarning: Using function/method 'Car.start()' is deprecated

A basic example to do just this (on a class):

    >>> from debtcollector import removals
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> @removals.removed_class("Pinto")
    ... class Pinto(object):
    ...   pass
    ...
    >>> p = Pinto()

Expected output:

    __main__:1: DeprecationWarning: Using class 'Pinto' (either directly or via inheritance) is deprecated

A basic example to do just this (on a classmethod):

    >>> from debtcollector import removals
    >>> import warnings
    >>> warnings.simplefilter("once")
    >>> class OldAndBusted(object):
    ...     @removals.remove
    ...     @classmethod
    ...     def fix_things(cls):
    ...         pass
    ...
    >>> OldAndBusted.fix_things()

Expected output:

    __main__:1: DeprecationWarning: Using function/method 'OldAndBusted.fix_things()' is deprecated

## Removing a instance property

Use the `removed_property()` decorator to signal that an attribute of a class is deprecated.

A basic example to do just this:

    >>> import warnings
    >>> warnings.simplefilter("once")
    >>> from debtcollector import removals
    >>> class OldAndBusted(object):
    ...   @removals.removed_property
    ...   def thing(self):
    ...     return 'old-and-busted'
    ...   @thing.setter
    ...   def thing(self, value):
    ...     pass
    ...   @thing.deleter
    ...   def thing(self):
    ...     pass
    ...
    >>> o = OldAndBusted()
    >>> o.thing
    'old-and-busted'
    >>> o.thing = '2'
    >>> del o.thing

    __main__:1: DeprecationWarning: Reading the 'thing' property is deprecated
    __main__:1: DeprecationWarning: Setting the 'thing' property is deprecated
    __main__:1: DeprecationWarning: Deleting the 'thing' property is deprecated

## Removing a keyword argument

A basic example to do just this (on a classmethod):

    >>> import warnings
    >>> warnings.simplefilter("once")
    >>> from debtcollector import removals
    >>> class OldAndBusted(object):
    ...     @removals.removed_kwarg('resp', message="Please use 'response' instead")
    ...     @classmethod
    ...     def factory(cls, resp=None, response=None):
    ...         response = resp or response
    ...         return response
    ...
    >>> OldAndBusted.factory(resp='super-duper')
    'super-duper'

    __main__:1: DeprecationWarning: Using the 'resp' argument is deprecated: Please use 'response' instead

A basic example to do just this (on a `__init__` method):

    >>> import warnings
    >>> warnings.simplefilter("once")
    >>> from debtcollector import removals
    >>> class OldAndBusted(object):
    ...     @removals.removed_kwarg('bleep')
    ...     def __init__(self, bleep=None):
    ...         self.bloop = bleep
    ...
    >>> o = OldAndBusted(bleep=2)

    __main__:1: DeprecationWarning: Using the 'bleep' argument is deprecated

## Changing the default value of a keyword argument

A basic example to do just this:

    >>> import warnings
    >>> warnings.simplefilter("once")
    >>> from debtcollector import updating
    >>> class OldAndBusted(object):
    ...     ip = '127.0.0.1'
    ...     @updating.updated_kwarg_default_value('type', 'http', 'https')
    ...     def url(self, type='http'):
    ...         response = '%s://%s' % (type, self.ip)
    ...         return response
    ...
    >>> OldAndBusted().url()
    'http://127.0.0.1'

    __main__:1: FutureWarning: The http argument is changing its default value to https, please update the code to explicitly set http as the value

A basic classmethod example.

Note

the @classmethod decorator is before the debtcollector one

    >>> import warnings
    >>> warnings.simplefilter("once")
    >>> from debtcollector import updating
    >>> class OldAndBusted(object):
    ...     ip = '127.0.0.1'
    ...     @classmethod
    ...     @updating.updated_kwarg_default_value('type', 'http', 'https')
    ...     def url(cls, type='http'):
    ...         response = '%s://%s' % (type, cls.ip)
    ...         return response
    ...
    >>> OldAndBusted.url()
    'http://127.0.0.1'

    __main__:1: FutureWarning: The http argument is changing its default value to https, please update the code to explicitly set http as the value

## Moving a function

To change the name or location of a regular function use the `moved_function()` function:

    >>> from debtcollector import moves
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> def new_thing():
    ...   return "new thing"
    ...
    >>> old_thing = moves.moved_function(new_thing, 'old_thing', __name__)
    >>> new_thing()
    'new thing'
    >>> old_thing()
    'new thing'

Expected output:

    __main__:1: DeprecationWarning: Function '__main__.old_thing()' has moved to '__main__.new_thing()'

## Moving a method

To move a instance method from an existing one to a new one the `moved_method()` function/decorator can be used to achieve this in a non-destructive manner.

A basic example to do just this:

    >>> from debtcollector import moves
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> class Cat(object):
    ...   @moves.moved_method('meow')
    ...   def mewow(self):
    ...     return self.meow()
    ...   def meow(self):
    ...     return 'kitty'
    ...
    >>> c = Cat()
    >>> c.mewow()
    'kitty'
    >>> c.meow()
    'kitty'

Expected output:

    __main__:1: DeprecationWarning: Method 'Cat.mewow()' has moved to 'Cat.meow()'

## Moving a property

To move a instance property from an existing one to a new one the `moved_property()` function/decorator can be used to achieve this in a non-destructive manner.

A basic example to do just this:

    >>> from debtcollector import moves
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> class Dog(object):
    ...   @property
    ...   @moves.moved_property('bark')
    ...   def burk(self):
    ...     return self.bark
    ...   @property
    ...   def bark(self):
    ...     return 'woof'
    ...
    >>> d = Dog()
    >>> d.burk
    'woof'
    >>> d.bark
    'woof'

Expected output:

    __main__:1: DeprecationWarning: Property 'Dog.burk' has moved to 'Dog.bark'

## Moving a class

To move a class from an existing one to a new one the `moved_class()` type generator function can be used to achieve this in a non-destructive manner.

A basic example to do just this:

    >>> from debtcollector import moves
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> class WizBang(object):
    ...   pass
    ...
    >>> OldWizBang = moves.moved_class(WizBang, 'OldWizBang', __name__)
    >>> a = OldWizBang()
    >>> b = WizBang()

Expected output:

    __main__:1: DeprecationWarning: Class '__main__.OldWizBang' has moved to '__main__.WizBang'

## Renaming a keyword argument

To notify the user when a keyword argument has been replaced with a new and improved keyword argument and the user is still using the old keyword argument the `renamed_kwarg()` function/decorator can be used to achieve this in a non-destructive manner.

A basic example to do just this:

    >>> from debtcollector import renames
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> @renames.renamed_kwarg('snizzle', 'nizzle')
    ... def do_the_deed(snizzle=True, nizzle=True):
    ...   return (snizzle, nizzle)
    ...
    >>> do_the_deed()
    (True, True)
    >>> do_the_deed(snizzle=False)
    (False, True)
    >>> do_the_deed(nizzle=False)
    (True, False)

Expected output:

    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated, please use the 'nizzle' argument instead

## Further customizing the emitted messages

It is typically useful to tell the user when a deprecation has started and when the deprecated item will be officially removed (deleted or other). To enable this all the currently provided functions this library provides take a `message`, `version` and `removal_version` keyword arguments. These are used in forming the message that is shown to the user when they trigger the deprecated activity.

A basic example to do just this:

    >>> from debtcollector import renames
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> @renames.renamed_kwarg('snizzle', 'nizzle', version="0.5", removal_version="0.7")
    ... def do_the_deed(snizzle=True, nizzle=True):
    ...   pass
    ...
    >>> do_the_deed(snizzle=False)

Expected output:

    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated in version '0.5' and will be removed in version '0.7', please use the 'nizzle' argument instead

If the `removal_version` is unknown the special character `?` can be used instead (to denote that the deprecated activity will be removed sometime in the future).

A basic example to do just this:

    >>> from debtcollector import renames
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> @renames.renamed_kwarg('snizzle', 'nizzle', version="0.5", removal_version="?")
    ... def do_the_deed(snizzle=True, nizzle=True):
    ...   pass
    ...
    >>> do_the_deed(snizzle=False)

Expected output:

    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated in version '0.5' and will be removed in a future version, please use the 'nizzle' argument instead

To further customize the message (with a special postfix) the `message` keyword argument can be provided.

A basic example to do just this:

    >>> from debtcollector import renames
    >>> import warnings
    >>> warnings.simplefilter('always')
    >>> @renames.renamed_kwarg('snizzle', 'nizzle', message="Pretty please stop using it")
    ... def do_the_deed(snizzle=True, nizzle=True):
    ...   pass
    ...
    >>> do_the_deed(snizzle=False)

Expected output:

    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated, please use the 'nizzle' argument instead: Pretty please stop using it

## Deprecating anything else

For use-cases which do not fit the above decorators, properties other provided functionality the final option is to use debtcollectors the `deprecate()` function to make your own messages (using the message building logic that debtcollector uses itself).

A basic example to do just this:

    >>> import warnings
    >>> warnings.simplefilter("always")
    >>> import debtcollector
    >>> debtcollector.deprecate("This is no longer supported", version="1.0")

    __main__:1: DeprecationWarning: This is no longer supported in version '1.0'

this page last updated: 2026-02-09 12:50:12

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug