hbutils.collection.recover

This module provides a flexible recovery system for Python objects, allowing objects to be restored to their original state after modifications.

The recovery system supports various built-in types (dict, list, tuple, etc.) and can be extended to support custom types through registration. It works by creating recovery objects that store the original state and can restore it when needed.

Key Features:

Recursive recovery of nested data structures
Support for built-in types (dict, list, tuple, primitives)
Extensible through custom recovery classes
Generic object recovery via __dict__ attribute

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()  # Restores original state

register_recovery

hbutils.collection.recover.register_recovery(cls: Type[BaseRecovery])[source]

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 customize 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][source]

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]

BaseRecovery

class hbutils.collection.recover.BaseRecovery(origin: _OriginType)[source]

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 should implement the _recover and from_origin methods to provide specific recovery 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)[source]

Constructor of BaseRecovery.

Parameters:: origin (_OriginType) – Origin object to be recovered.

classmethod _create_child(child, recursive: bool = True)[source]

Create child-level object for storage usage.

This method determines whether to create a recovery object for a child element or store it directly, based on the recursive flag.

Parameters:

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

Returns:

Object for storage (either a recovery object or the original child).

Return type:

Union[BaseRecovery, Any]

_recover()[source]

Implementation for recovery.

This method should be overridden by subclasses to provide the actual recovery logic for restoring the object to its original state.

Raises:: NotImplementedError – This method must be implemented by subclasses.

classmethod _recover_child(child)[source]

Get recovered child-level object.

This method handles the recovery of child objects, which may themselves be recovery objects or native Python objects.

Parameters:: child (Union[BaseRecovery, Any]) – Child object, should be a BaseRecovery or native object.
Returns:: Recovered child-level object.
Return type:: Any

classmethod from_origin(origin: _OriginType, recursive: bool = True) → BaseRecovery[source]

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[source]

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)[source]

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)[source]

Constructor of DictRecovery.

Parameters:

origin (_DictType) – Origin object to be recovered.
mp (Dict) – Dictionary mapping of keys to values or recovery objects.

classmethod _create_child(child, recursive: bool = True)

Create child-level object for storage usage.

This method determines whether to create a recovery object for a child element or store it directly, based on the recursive flag.

Parameters:

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

Returns:

Object for storage (either a recovery object or the original child).

Return type:

Union[BaseRecovery, Any]

_recover()[source]

Recover the dictionary to its original state.

This method restores all key-value pairs in the dictionary, removing any keys that were added and restoring original values.

classmethod _recover_child(child)

Get recovered child-level object.

This method handles the recovery of child objects, which may themselves be recovery objects or native Python objects.

Parameters:: child (Union[BaseRecovery, Any]) – Child object, should be a BaseRecovery or native object.
Returns:: Recovered child-level object.
Return type:: Any

classmethod from_origin(origin: _DictType, recursive: bool = True) → DictRecovery[source]

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

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

ListRecovery

class hbutils.collection.recover.ListRecovery(origin: _ListType, items: List)[source]

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)[source]

Constructor of ListRecovery.

Parameters:

origin (_ListType) – Origin object to be recovered.
items (List) – List of items or recovery objects from the original list.

classmethod _create_child(child, recursive: bool = True)

Create child-level object for storage usage.

This method determines whether to create a recovery object for a child element or store it directly, based on the recursive flag.

Parameters:

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

Returns:

Object for storage (either a recovery object or the original child).

Return type:

Union[BaseRecovery, Any]

_recover()[source]

Recover the list to its original state.

This method restores all elements in the list, replacing the current contents with the original elements.

classmethod _recover_child(child)

Get recovered child-level object.

This method handles the recovery of child objects, which may themselves be recovery objects or native Python objects.

Parameters:: child (Union[BaseRecovery, Any]) – Child object, should be a BaseRecovery or native object.
Returns:: Recovered child-level object.
Return type:: Any

classmethod from_origin(origin: _ListType, recursive: bool = True) → ListRecovery[source]

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

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

TupleRecovery

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

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])[source]

Constructor of TupleRecovery.

Parameters:

origin (_TupleType) – Origin object to be recovered.
items (List[Any]) – List of items or recovery objects from the tuple.

classmethod _create_child(child, recursive: bool = True)

Create child-level object for storage usage.

This method determines whether to create a recovery object for a child element or store it directly, based on the recursive flag.

Parameters:

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

Returns:

Object for storage (either a recovery object or the original child).

Return type:

Union[BaseRecovery, Any]

_recover()[source]

Recover the tuple’s contained objects.

Since tuples are immutable, this method only recovers the mutable objects contained within the tuple.

classmethod _recover_child(child)

Get recovered child-level object.

This method handles the recovery of child objects, which may themselves be recovery objects or native Python objects.

Parameters:: child (Union[BaseRecovery, Any]) – Child object, should be a BaseRecovery or native object.
Returns:: Recovered child-level object.
Return type:: Any

classmethod from_origin(origin: _TupleType, recursive: bool = True) → TupleRecovery[source]

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

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

NullRecovery

class hbutils.collection.recover.NullRecovery(origin: _OriginType)[source]

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.

__init__(origin: _OriginType)

Constructor of BaseRecovery.

Parameters:: origin (_OriginType) – Origin object to be recovered.

classmethod _create_child(child, recursive: bool = True)

Create child-level object for storage usage.

This method determines whether to create a recovery object for a child element or store it directly, based on the recursive flag.

Parameters:

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

Returns:

Object for storage (either a recovery object or the original child).

Return type:

Union[BaseRecovery, Any]

_recover()[source]

Just do nothing.

Immutable types do not need recovery as they cannot be modified.

classmethod _recover_child(child)

Get recovered child-level object.

This method handles the recovery of child objects, which may themselves be recovery objects or native Python objects.

Parameters:: child (Union[BaseRecovery, Any]) – Child object, should be a BaseRecovery or native object.
Returns:: Recovered child-level object.
Return type:: Any

classmethod from_origin(origin: _OriginType, recursive: bool = True) → NullRecovery[source]

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

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

GenericObjectRecovery

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

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__, may be you need to custom recovery class by inheriting BaseRecovery class, and register it by register_recovery() function.

__init__(origin: _OriginType, dict_: DictRecovery | None)[source]

Constructor of GenericObjectRecovery.

Parameters:

origin (_OriginType) – Original object to recover.
dict (Optional[DictRecovery]) – Recovery object of __dict__, None when origin do not have __dict__.

classmethod _create_child(child, recursive: bool = True)

Create child-level object for storage usage.

This method determines whether to create a recovery object for a child element or store it directly, based on the recursive flag.

Parameters:

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

Returns:

Object for storage (either a recovery object or the original child).

Return type:

Union[BaseRecovery, Any]

_recover()[source]

Recover the __dict__.

This method restores the object’s __dict__ attribute to its original state if it exists.

classmethod _recover_child(child)

Get recovered child-level object.

This method handles the recovery of child objects, which may themselves be recovery objects or native Python objects.

Parameters:: child (Union[BaseRecovery, Any]) – Child object, should be a BaseRecovery or native object.
Returns:: Recovered child-level object.
Return type:: Any

classmethod from_origin(origin: _OriginType, recursive: bool = True) → BaseRecovery[source]

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

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