hbutils.reflection.clazz

Class and type reflection utilities.

This module provides helper functions for working with Python classes and types. It includes utilities for creating class-wrapping decorators that preserve metadata (similar to functools.wraps()) and for determining the most specific common base class across multiple classes.

The module contains the following public components:

  • class_wraps() - Create a class wrapper decorator that preserves metadata

  • common_base() - Find the most specific common base class

Example:

>>> from hbutils.reflection.clazz import class_wraps, common_base
>>>
>>> def cls_dec(clazz):
...     @class_wraps(clazz)
...     class _NewClazz(clazz):
...         pass
...     return _NewClazz
...
>>> class Original:
...     '''Original class docstring'''
...     pass
...
>>> @cls_dec
... class Wrapped(Original):
...     pass
...
>>> Wrapped.__doc__
'Original class docstring'
>>> common_base(RuntimeError, ValueError, KeyError)
<class 'Exception'>

__all__

hbutils.reflection.clazz.__all__ = ['class_wraps', 'common_base']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

CLASS_WRAPPER_UPDATES

hbutils.reflection.clazz.CLASS_WRAPPER_UPDATES: Tuple[str, ...] = ()

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

class_wraps

hbutils.reflection.clazz.class_wraps(wrapped: type, assigned: Tuple[str, ...] = ('__module__', '__name__', '__qualname__', '__doc__', '__annotations__'), updated: Tuple[str, ...] = ()) → Callable[[type], type][source]

Create a wrapper decorator for classes.

This function creates a decorator that can be used to wrap a class while preserving its metadata (similar to functools.wraps() but for classes). It updates the wrapper class with attributes from the wrapped class.

Parameters:

  • wrapped (type) – The class to be wrapped.

  • assigned (Tuple[str, ...]) – Tuple of attribute names to be assigned from wrapped to wrapper. Defaults to functools.WRAPPER_ASSIGNMENTS.

  • updated (Tuple[str, ...]) – Tuple of attribute names to be updated from wrapped to wrapper. Defaults to an empty tuple (no updates).

Returns:

A callable decorator that updates a wrapper class with metadata.

Return type:

Callable[[type], type]

Note

The returned decorator is a functools.partial of functools.update_wrapper() and is intended to be used when defining a new class that wraps an existing class.

Example:

>>> def cls_dec(clazz):
...     @class_wraps(clazz)
...     class _NewClazz(clazz):
...         pass
...     return _NewClazz
>>>
>>> class Original:
...     '''Original class docstring'''
...     pass
>>>
>>> @cls_dec
... class Wrapped(Original):
...     pass
>>>
>>> Wrapped.__doc__
'Original class docstring'

common_base

hbutils.reflection.clazz.common_base(cls: type, *clss: type) → type[source]

Get the most specific common base class for the given classes.

This function finds the most specific common base class shared by all provided classes. Only the __base__ attribute is considered during the search, which means it follows the direct inheritance chain rather than the full Method Resolution Order (MRO).

Parameters:

  • cls (type) – The first class to find a common base for.

  • clss (type) – Additional classes to find a common base for.

Returns:

The most specific common base class shared by all input classes.

Return type:

type

Raises:

TypeError – If any provided argument is not a class.

Example:

>>> from hbutils.reflection import common_base
>>> common_base(object)
<class 'object'>
>>> common_base(object, int, str)
<class 'object'>
>>> common_base(RuntimeError, ValueError, KeyError)
<class 'Exception'>
>>> common_base(int, float)
<class 'object'>
>>>
>>> class A: pass
>>> class B(A): pass
>>> class C(A): pass
>>> common_base(B, C)
<class '__main__.A'>