hbutils.collection.recover

Recovery utilities for restoring Python objects to their original state.

This module implements a flexible recovery system that captures the state of objects and provides a callable to restore them later. It supports nested structures and common built-in containers, and it can be extended for custom classes via registration.

The module contains the following main components:

• BaseRecovery - Abstract base class for recovery implementations.

• DictRecovery - Recovery for dictionaries.

• ListRecovery - Recovery for lists.

• TupleRecovery - Recovery for tuples (recovers mutable children).

• NullRecovery - No-op recovery for immutable primitives.

• GenericObjectRecovery - Recovery for generic objects via __dict__.

• register_recovery() - Register custom recovery classes.

• get_recovery_func() - Create a recovery callable for an object.

Note

The recovery mechanism stores references to the original objects and restores them in-place. For mutable containers, this means the identity of the original object is preserved after recovery.

Example:

>>> from hbutils.collection import get_recovery_func
>>> l = [1, {'a': 1, 'b': 2}, 3, 4, 5]
>>> f = get_recovery_func(l)
>>> l[3] = 1
>>> l.pop()
>>> recovered = f()
>>> recovered is l
True
>>> l
[1, {'a': 1, 'b': 2}, 3, 4, 5]

__all__

hbutils.collection.recover.__all__ = ['BaseRecovery', 'DictRecovery', 'ListRecovery', 'TupleRecovery', 'NullRecovery', 'GenericObjectRecovery', 'register_recovery', 'get_recovery_func']

Built-in mutable sequence.

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

BaseRecovery

class hbutils.collection.recover.BaseRecovery(origin: _OriginType)

Base class for all recovery implementations.

This abstract class defines the interface for recovery objects that can restore Python objects to their original state. Subclasses implement the _recover() and from_origin() methods to provide specific logic for different types.

Variables:

• __rtype__ – The type(s) that this recovery class can handle.

• origin – The original object to be recovered.

__init__(origin: _OriginType)

Constructor of BaseRecovery.

Parameters:

origin (_OriginType) – Origin object to be recovered.

__rtype__

alias of object

classmethod from_origin(origin: _OriginType, recursive: bool = True) → BaseRecovery

Create a recovery object by the given original object.

This method should be overridden by subclasses to create an appropriate recovery object for the given original object.

Parameters:

• origin (_OriginType) – Original object to recover.

• recursive (bool) – Recursive or not. Default is True which means the child-level object contained in origin will be recovered as well.

Returns:

Recovery object.

Return type:

BaseRecovery

Raises:

NotImplementedError – This method must be implemented by subclasses.

recover() → _OriginType

Recover the given object.

This method calls the internal _recover() method to perform the actual recovery operation and then returns the recovered object.

Returns:

Recovered object.

Return type:

_OriginType

DictRecovery

class hbutils.collection.recover.DictRecovery(origin: _DictType, mp: Dict)

Recovery class for dictionary objects.

This class handles the recovery of dictionary objects by storing their key-value pairs and restoring them when recovery is triggered.

Variables:

mapping – Dictionary mapping of keys to values (or recovery objects).

__init__(origin: _DictType, mp: Dict)

Constructor of DictRecovery.

Parameters:

• origin (_DictType) – Origin object to be recovered.

• mp (Dict) – Dictionary mapping of keys to values or recovery objects.

__rtype__

alias of dict

classmethod from_origin(origin: _DictType, recursive: bool = True) → DictRecovery

Create a DictRecovery object from a dictionary.

Parameters:

• origin (_DictType) – Original dictionary to recover.

• recursive (bool) – Whether to recursively create recovery objects for values.

Returns:

DictRecovery object.

Return type:

DictRecovery

TupleRecovery

class hbutils.collection.recover.TupleRecovery(origin: _TupleType, items: List[Any])

Recovery class for tuple objects.

Since tuples are immutable, this class primarily handles recovery of mutable objects contained within the tuple.

Variables:

items – List of items (or recovery objects) in the tuple.

__init__(origin: _TupleType, items: List[Any])

Constructor of TupleRecovery.

Parameters:

• origin (_TupleType) – Origin object to be recovered.

• items (List[Any]) – List of items or recovery objects from the tuple.

__rtype__

alias of tuple

classmethod from_origin(origin: _TupleType, recursive: bool = True) → TupleRecovery

Create a TupleRecovery object from a tuple.

Parameters:

• origin (_TupleType) – Original tuple to recover.

• recursive (bool) – Whether to recursively create recovery objects for items.

Returns:

TupleRecovery object.

Return type:

TupleRecovery

ListRecovery

class hbutils.collection.recover.ListRecovery(origin: _ListType, items: List)

Recovery class for list objects.

This class handles the recovery of list objects by storing their elements and restoring them when recovery is triggered.

Variables:

items – List of items (or recovery objects) from the original list.

__init__(origin: _ListType, items: List)

Constructor of ListRecovery.

Parameters:

• origin (_ListType) – Origin object to be recovered.

• items (List) – List of items or recovery objects from the original list.

__rtype__

alias of list

classmethod from_origin(origin: _ListType, recursive: bool = True) → ListRecovery

Create a ListRecovery object from a list.

Parameters:

• origin (_ListType) – Original list to recover.

• recursive (bool) – Whether to recursively create recovery objects for items.

Returns:

ListRecovery object.

Return type:

ListRecovery

NullRecovery

class hbutils.collection.recover.NullRecovery(origin: _OriginType)

Empty recovery class for builtin immutable types.

This class is used for immutable types that cannot be modified and therefore do not need any recovery logic. It simply stores a reference to the original object.

classmethod from_origin(origin: _OriginType, recursive: bool = True) → NullRecovery

Just do nothing.

Create a NullRecovery object for an immutable type.

Parameters:

• origin (_OriginType) – Original immutable object.

• recursive (bool) – Ignored for immutable types.

Returns:

NullRecovery object.

Return type:

NullRecovery

GenericObjectRecovery

class hbutils.collection.recover.GenericObjectRecovery(origin: _OriginType, dict_: DictRecovery | None)

Recovery class for generic objects.

The __dict__ will be recovered.

This class provides recovery for arbitrary Python objects by storing and restoring their __dict__ attribute. This works for most custom classes but may not be sufficient for objects with special state storage.

Variables:

dict – Recovery object for the object’s __dict__, or None if no __dict__ exists.

Note

If what you need to recover is not only __dict__, you may need to create a custom recovery class by inheriting BaseRecovery, and register it by register_recovery().

__init__(origin: _OriginType, dict_: DictRecovery | None)

Constructor of GenericObjectRecovery.

Parameters:

• origin (_OriginType) – Original object to recover.

• dict (Optional[DictRecovery]) – Recovery object of __dict__, None when origin does not have __dict__.

__rtype__

alias of object

classmethod from_origin(origin: _OriginType, recursive: bool = True) → BaseRecovery

Create recovery object.

Creates a GenericObjectRecovery by storing the object’s __dict__ if it exists.

Parameters:

• origin (_OriginType) – Original object to recover.

• recursive (bool) – Whether to recursively create recovery objects for __dict__ values.

Returns:

GenericObjectRecovery object.

Return type:

GenericObjectRecovery

register_recovery

hbutils.collection.recover.register_recovery(cls: Type[BaseRecovery]) → None

Register recovery class.

This function registers a custom recovery class to the global registry, allowing it to be used for recovering objects of the types specified in the class’s __rtype__ attribute.

Parameters:

cls (Type[BaseRecovery]) – Recovery class to register.

Note

This API is used for custom recovery for other classes. For more details, you may take a look at the source code of BaseRecovery.

get_recovery_func

hbutils.collection.recover.get_recovery_func(origin: _OriginType, recursive: bool = True) → Callable[[], _OriginType]

Get recovery function for given object.

Dict, list and tuple object are natively supported.

This function creates a recovery object for the given object and returns a callable that will restore the object to its original state when invoked.

Parameters:

• origin (_OriginType) – Original object to recover.

• recursive (bool) – Recursive or not. Default is True which means the child-level object contained in origin will be recovered as well.

Returns:

Recovery function that restores the object when called.

Return type:

Callable[[], _OriginType]

Examples::

>>> from hbutils.collection import get_recovery_func
>>> l = [1, {'a': 1, 'b': 2}, 3, 4, 5]
>>> print(id(l), l)
140146367304720 [1, {'a': 1, 'b': 2}, 3, 4, 5]
>>> f = get_recovery_func(l)

>>> l[3] = 1
>>> l.pop()
>>> l.append('sdklfj')
>>> l.append('sdkfhjksd')
>>> l[1]['c'] = 2
>>> l[1]['a'] = 100
>>> print(id(l), l)
140146367304720 [1, {'a': 100, 'b': 2, 'c': 2}, 3, 1, 'sdklfj', 'sdkfhjksd']

>>> lx = f()
>>> print(id(lx), lx)  # lx is l
140146367304720 [1, {'a': 1, 'b': 2}, 3, 4, 5]
>>> print(id(l), l)  # the value is recovered
140146367304720 [1, {'a': 1, 'b': 2}, 3, 4, 5]