DEBTCOLLECTOR(1)

🎀 debtcollector(1) — debtcollector 3.1.0 🎀

okay bestie, welcome to the debtcollector manual page 💅 this is the whole vibe: it’s a collection of Python deprecation patterns and strategies that help you collect your technical debt in a non-destructive manner ✨

💖 Note: even though it’s designed with OpenStack integration in mind — and that’s where most of its current integration lives — it aims to be generally usable and useful in any project. no gatekeeping, periodt 🫶

---

🌸 NAME 🌸

debtcollector — debtcollector 3.1.0

A collection of Python deprecation patterns and strategies that help you collect your technical debt in a non-destructive manner.

💖 Note: even though it’s designed with OpenStack integration in mind, and that’s where most of its current integration is, it aims to be generally usable and useful in any project.

---

🎀 INSTALLATION 🎀

At the command line:

$ pip install debtcollector

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv debtcollector
$ pip install debtcollector

---

🦋 USING DEBTCOLLECTOR 🦋

💫 Examples 💫

✨ Removing a class/classmethod/method/function ✨

So you need to tell a user that a method — staticmethod, classmethod, or regular instance method — or a class or function is gonna be removed at some point in the future? iconic. use the remove() function/decorator and do it 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. yes, even properties get the little deprecation ribbon 🎀

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. slay, no breaking changes 💅

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. main character class migration energy 👑

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. very “we’ll deal with it later bestie” energy 😭

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)

What you should see pop out of that, bestie:

__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

And if you wanna glow up the message with your own little postfix, just hand over the message keyword argument. That's literally the whole trick 🎀

A tiny example of exactly that:

>>> 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 (yes, your custom bit gets stapled on the end 💅):

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

✨ Deprecating anything else ✨

So you've got a use-case that just does not fit the decorators above, or doesn't fit properties, or any of the other provided functionality? No stress, the final option is deprecate() — and it lets you build your own messages, using the very same message-building logic that debtcollector uses for itself. Iconic, honestly 🌈

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'

---

👑 API REFERENCE 👑

The currently documented publicly exposed API's for usage in your project are defined below.

Warning: external usage of internal utility functions and modules should be kept to a minimum 😭 because they may be altered, refactored or moved to other locations without notice — and without the typical deprecation cycle. So like… don't get attached, bestie.

Helpers

Moves

Renames

Removals

Fixtures

Those five are the whole menu, no cap 🫶

---

🦋 CONTRIBUTING 🦋

If you would like to contribute to the development of OpenStack, you must follow the steps in this page: <https://docs.openstack.org/infra/manual/developers.html>

Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following the workflow documented at: <https://docs.openstack.org/infra/manual/developers.html#development-workflow>

Pull requests submitted through GitHub will be ignored. 💀 Fr fr, don't do it.

Bugs should be filed on Launchpad, not GitHub: <https://bugs.launchpad.net/debtcollector>

Indices and tables

• Index <>
• Module Index <>
• Search Page <>

---

🎀 Author 🎀

Author name not set

🎀 Copyright 🎀

OpenStack Foundation

---

okay that's the whole page bestie, you made it 🫶 this one's 3.1.0 and it's dated Jan 02, 1980 (yes, really, that's the date on it 💀) — go forth and deprecate responsibly, mwah 💖