Support for mapping frozen dataclasses

[CaselIT]

Discussed in #9192

Using frozen dataclasses may be useful in some cases, but implementing it will be non trivial. See mike reply in the discussion

[frederikaalund]

I found this issue because I searched for some way to freeze my data (make it immutable).

Basically, I'd like a way to do something like this:

class UserAccount(Base):  # MappedAsDataClass and DeclarativeBase
    full_name: Mapped[str]
    ...

with Session(...) as session:
    result = session.execute(select(UserAccount))
    mutable_users: Iterable[UserAccount] = result.scalars()
    # I want to cache a read-only version the result. E.g., to display it in a UI elsewhere.
    # The data type looks identical (`Iterable[UserAccount]`) but at runtime we raise if anyone
    # tries to mutate the data (like with `@dataclass(frozen=True)`).
    frozen_users: Iterable[UserAccount] = session.freeze(mutable_users)
    # Assert that we got some result just for the sake of this code example
    assert frozen_users, "There is at least one user"
    # The following raises `dataclasses.FrozenInstanceError` (or similar).
    # This is great because because I can give `frozen_users` to the UI and not worry about
    # accidental data mutations.
    frozen_users[0].full_name = "fred"  # Raises `dataclasses.FrozenInstanceError` (or similar)

The new API is Session.freeze. Basically, it's a combination of Session.expunge and a subsequent "freeze" on each instance.

I know that this is only faux-immutability but that is good enough for me.

Bonus points if Session.freeze returns something like Iterable[UserAccount.Frozen] or Iterable[Frozen[UserAccount]]. E.g., a read-only view of UserAccount but where the type system knows that each member/field is immutable (good for the static type checkers). I just don't know if kind of dynamic typing is currently feasible in python.

Just my two cents. Feel free to create a separate issue/discussion for this if my input is too far from the original issue.

[zzzeek]

"frozen" is a class level behavior, not an instance level behavior. if you want some kind of flag on your instances that makes individual instances raise when written, that's fine but that would be something on your end; it's actually mutating the instances to set them in this special "raise on any further changes" mode.

[frederikaalund]

Thanks for the prompt reply. :)

"frozen" is a class level behavior, not an instance level behavior.

We agree.

if you want some kind of flag on your instances that makes individual instances raise when written, that's fine but that would be something on your end; it's actually mutating the instances to set them in this special "raise on any further changes" mode.

What I'm thinking of is a read-only view. I.e., a wrapper around the mutable data that only exposes __getattr__ and hides __setattr__/__delattr__.

In any case, I can understand if this use case is too far away from what SQLAlchemy can/should support. After all, the original issue only has two upvotes so far (and one is mine). I guess that the majority likes their data mutable because it's convenient. :)

Thanks again for the quick and thoughtful response.

[zzzeek]

Hi I just deleted my previous comment, it was wrong.

What I'm thinking of is a read-only view. I.e., a wrapper around the mutable data that only exposes __getattr__ and hides __setattr__/__delattr__.

as I had in my deleted comment, this is easy to implement given a specific set of assumptions about classes and mostly something you can put in a mixin of your own, in like two lines:

class OptionallyImmutableMixin:
    immutable = False

    def __setattr__(self, key, value):
       if self.immutable:
          raise TypeError("we're immutable")
      super().__setattr__(key, value)

(for some reason I thought __setattr__ wasn't triggered for descriptors but it is, there's no problem).

The above is trivial and you can use that. If we put that in SQLAlchemy, people would complain like mad about all the things it doesnt do, like, prevent collections from being mutated, prevent JSON / ARRAY values from being mutated, how it prevents all attributes from being mutated, how Python typing wouldn't see the immutability, etc. It also is not a "wrapper" - a "wrapper" is enormously complicated compared to just having a custom __setattr__() on selected classes.

This falls into this very large category of "very easy to do with 5 lines of code for my immediate need, very enormous / complicated to do in a generic way in a library, saving individual programmers that 5 lines of code, yet keeps all parties happy for all possible use cases".

[frederikaalund]

[...] this is easy to implement given a specific set of assumptions about classes and mostly something you can put in a mixin of your own, in like two lines:

Fantastic! That'll do for my use case. Luckily, all my Base-derived classes are my own (no third party stuff) so the mixin-based approach works for me. I'll probably add this runtime immutable flag directly in my Base class so that it applies to everything. :)

[...] how Python typing wouldn't see the immutability, etc.

You're right. I have hopes for typing.dataclass_transform with frozen=True for a future version of this mixin. :)

---

I completely understand that this is out of scope for SQLAlchemy for all the reasons that you mention (and probably more). 👍

[troyswanson]

I came across this thread while searching for how to enforce immutability on attributes within a SQLAlchemy ORM object. I like the "mixin" pattern for this so I implemented my own. The main feature is the ability to define a list of attributes that can be changed, as opposed to enforcing immutability across the board. I would welcome comments or criticisms of this approach.

Disclaimer: This code was tested on a limited basis and I make no guarantees that it will work.

class ImmutableMixin:
    """
    SQLAlchemy mixin to make all attributes immutable after initialization, except
    those listed in `_immutable_exceptions`.

    An attribute can be changed if any of the following conditions are met:

    1. The object is still initializing (`_immutable_initialized` is False)
    2. The attribute name is present in the `_immutable_exceptions` frozenset defined
       by the inheriting class
    3. The attribute name starts with `_sa_` (used internally by SQLAlchemy)

    The inheriting class should define `_immutable_exceptions` as a frozenset of
    attribute names that are allowed to be changed after initialization.
    """

    _immutable_initialized: bool = False
    _immutable_exceptions: frozenset[str] = frozenset()

    def __setattr__(self, key: str, value):
        if not self._immutable_initialized or key in self._immutable_exceptions or key.startswith("_sa_"):
            super().__setattr__(key, value)
        else:
            raise AttributeError(f"'{key}' is immutable")

    def __post_init__(self):
        self._immutable_initialized = True

    @reconstructor
    def _orm_init(self):
        self._immutable_initialized = True