Skip to content

Supports Auto Freeze

Protocol for classes that support the auto-freeze mechanism.

supports_auto_freeze

Protocol for classes that support the auto-freeze mechanism.

SupportsAutoFreeze

Bases: Protocol

Contract for classes compatible with the @auto_freeze decorator.

Implementers must provide methods to transition between mutable and
immutable states. The @auto_freeze decorator calls these methods
based on class configuration.

Example 
@auto_freeze
class Email(ValueObject[str]):
    def freeze_instance(self) -> None:
        object.__setattr__(self, "_Email__is_frozen", True)

    def unfreeze_instance(self) -> None:
        object.__setattr__(self, "_Email__is_frozen", False)

    @classmethod
    def should_use_internal_freezing(cls) -> bool:
        return True
Source code in src/forging_blocks/foundation/autofreeze/supports_auto_freeze.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
class SupportsAutoFreeze(Protocol):  # pragma: no cover
    """Contract for classes compatible with the @auto_freeze decorator.

    Implementers must provide methods to transition between mutable and
    immutable states. The @auto_freeze decorator calls these methods
    based on class configuration.

    Example:
        ```python
        @auto_freeze
        class Email(ValueObject[str]):
            def freeze_instance(self) -> None:
                object.__setattr__(self, "_Email__is_frozen", True)

            def unfreeze_instance(self) -> None:
                object.__setattr__(self, "_Email__is_frozen", False)

            @classmethod
            def should_use_internal_freezing(cls) -> bool:
                return True
        ```
    """

    @classmethod
    def should_use_internal_freezing(cls) -> bool:
        """Determine whether the decorator should auto-freeze on init.

        Returns:
            True if instances should be automatically frozen after __init__
            completes, False to opt out of automatic freezing.

        Notes:
            - Override to return False to disable auto-freeze for a class tree.
            - Decorator checks this at runtime before calling freeze_instance().
        """
        ...

    def freeze_instance(self) -> None:
        """Transition the instance into an immutable state.

        Called automatically by @auto_freeze after __init__ completes
        (if should_use_internal_freezing() returns True).

        Responsibilities:
            - Mark the instance as frozen.
            - Prevent future attribute modifications.
            - Raise CantModifyImmutableAttributeError on __setattr__.

        Notes:
            - Implementation details are class-specific.
            - May use internal flags or other mechanisms.
        """
        ...

    def unfreeze_instance(self) -> None:
        """Transition the instance into a mutable state.

        Typically used only in testing or rollback scenarios.
        Normal application code should not call this directly.

        Responsibilities:
            - Remove the frozen marker.
            - Allow subsequent attribute modifications.

        Notes:
            - Use sparingly; violates immutability contract.
            - Intended for test setup/teardown and transaction rollback.
        """
        ...

    def freeze_attributes(self, attrs: Sequence[str]) -> None:
        """Selectively freeze specific attributes.

        Optional method for classes that support partial freezing.
        If not implemented, freeze_instance() is called instead.

        Args:
            attrs: Attribute names to freeze (e.g., ["_id"]).

        Notes:
            - Useful for Entities where only identity should be immutable.
            - Default behavior (if not overridden): freeze_instance().
        """
        ...

should_use_internal_freezing() -> bool classmethod

Determine whether the decorator should auto-freeze on init.

Returns:

Type Description
bool

True if instances should be automatically frozen after init
bool

completes, False to opt out of automatic freezing.
Notes
  • Override to return False to disable auto-freeze for a class tree.
  • Decorator checks this at runtime before calling freeze_instance().
Source code in src/forging_blocks/foundation/autofreeze/supports_auto_freeze.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
@classmethod
def should_use_internal_freezing(cls) -> bool:
    """Determine whether the decorator should auto-freeze on init.

    Returns:
        True if instances should be automatically frozen after __init__
        completes, False to opt out of automatic freezing.

    Notes:
        - Override to return False to disable auto-freeze for a class tree.
        - Decorator checks this at runtime before calling freeze_instance().
    """
    ...

freeze_instance() -> None

Transition the instance into an immutable state.

Called automatically by @auto_freeze after init completes
(if should_use_internal_freezing() returns True).

Responsibilities
  • Mark the instance as frozen.
  • Prevent future attribute modifications.
  • Raise CantModifyImmutableAttributeError on setattr.
Notes
  • Implementation details are class-specific.
  • May use internal flags or other mechanisms.
Source code in src/forging_blocks/foundation/autofreeze/supports_auto_freeze.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def freeze_instance(self) -> None:
    """Transition the instance into an immutable state.

    Called automatically by @auto_freeze after __init__ completes
    (if should_use_internal_freezing() returns True).

    Responsibilities:
        - Mark the instance as frozen.
        - Prevent future attribute modifications.
        - Raise CantModifyImmutableAttributeError on __setattr__.

    Notes:
        - Implementation details are class-specific.
        - May use internal flags or other mechanisms.
    """
    ...

unfreeze_instance() -> None

Transition the instance into a mutable state.

Typically used only in testing or rollback scenarios.
Normal application code should not call this directly.

Responsibilities
  • Remove the frozen marker.
  • Allow subsequent attribute modifications.
Notes
  • Use sparingly; violates immutability contract.
  • Intended for test setup/teardown and transaction rollback.
Source code in src/forging_blocks/foundation/autofreeze/supports_auto_freeze.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def unfreeze_instance(self) -> None:
    """Transition the instance into a mutable state.

    Typically used only in testing or rollback scenarios.
    Normal application code should not call this directly.

    Responsibilities:
        - Remove the frozen marker.
        - Allow subsequent attribute modifications.

    Notes:
        - Use sparingly; violates immutability contract.
        - Intended for test setup/teardown and transaction rollback.
    """
    ...

freeze_attributes(attrs: Sequence[str]) -> None

Selectively freeze specific attributes.

Optional method for classes that support partial freezing.
If not implemented, freeze_instance() is called instead.

Parameters:

Name Type Description Default
attrs Sequence[str]

Attribute names to freeze (e.g., ["_id"]).

 required
Notes
  • Useful for Entities where only identity should be immutable.
  • Default behavior (if not overridden): freeze_instance().
Source code in src/forging_blocks/foundation/autofreeze/supports_auto_freeze.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def freeze_attributes(self, attrs: Sequence[str]) -> None:
    """Selectively freeze specific attributes.

    Optional method for classes that support partial freezing.
    If not implemented, freeze_instance() is called instead.

    Args:
        attrs: Attribute names to freeze (e.g., ["_id"]).

    Notes:
        - Useful for Entities where only identity should be immutable.
        - Default behavior (if not overridden): freeze_instance().
    """
    ...