Class decorators in Python: practical use cases

Question

I am looking for practical and non-synthetic use cases of Python class decorators. So far, the only case which made sense to me is registering a class in a publisher-subscriber system, e.g. plugins or events, something like:

@register
class MyPlugin(Plugin):
    pass

or

@recieves_notifications
class Console:
    def print(self, text):
        ...

Any other sane cases I've been thinking of could have been built on top of inheritance, metaclasses or decorating methods. Could you please share any good (or bad!) examples of using class decorators?

Thank you!

Answer 1

When writing unit tests having the @unittest.skipIf and @unittest.skipUnless can be used on either individual methods or on an entire unittest.TestCase class definition. This makes for writing tests for platform specific problems so much easier.

Example from asyncio/test_selectors

# Some platforms don't define the select.kqueue object for these tests.
# On those platforms, this entire grouping of tests will be skipped.

@unittest.skipUnless(hasattr(selectors, 'KqueueSelector'),
                 "Test needs selectors.KqueueSelector)")
class KqueueSelectorTestCase(BaseSelectorTestCase, ScalableSelectorMixIn):
...

Answer 2

Class decorators were explicitly created to make some things that were already expressible via metaclasses more pleasant, from the PEP:

The motivating use-case was to make certain constructs more easily expressed and less reliant on implementation details of the CPython interpreter. While it is possible to express class decorator-like functionality using metaclasses, the results are generally unpleasant and the implementation highly fragile. In addition, metaclasses are inherited, whereas class decorators are not, making metaclasses unsuitable for some, single class-specific uses of class decorators. The fact that large-scale Python projects like Zope were going through these wild contortions to achieve something like class decorators won over the BDFL.

Answer 3

From this stack overflow question:

def singleton(class_):
  instances = {}
  def getinstance(*args, **kwargs):
    if class_ not in instances:
        instances[class_] = class_(*args, **kwargs)
    return instances[class_]
  return getinstance

@singleton
class MyClass(BaseClass):
  pass

Answer 4

Looking for use cases that can be done with decorators on classes is futile - anything that can be done with decorators on classes can be done with metaclasses. Even your example of registration. To prove it, here is a metaclass that applies a decorator:

Python 2:

def register(target):
    print 'Registring', target
    return target


class ApplyDecorator(type):
    def __new__(mcs, name, bases, attrs):
        decorator = attrs.pop('_decorator')
        cls = type(name, bases, attrs)
        return decorator(cls)

    def __init__(cls, name, bases, attrs, decorator=None):
        super().__init__(name, bases, attrs)


class Foo:
    __metaclass__ = ApplyDecorator
    _decorator = register

Python 3:

def register(target):
    print('Registring', target)
    return target


class ApplyDecorator(type):
    def __new__(mcs, name, bases, attrs, decorator):
        cls = type(name, bases, attrs)
        return decorator(cls)

    def __init__(cls, name, bases, attrs):
        super().__init__(name, bases, attrs)


class Foo(metaclass=ApplyDecorator, decorator=register):
    pass