token_association.py

"""
Module defining the TokenAssociation class.

This class provides a lightweight, immutable representation of a token ↔ account association
as reported by the Hedera network — specifically for associations that the network creates
**automatically** during transaction execution.

These appear in:
    TransactionRecord.automatic_token_associations
        (a list of TokenAssociation objects)

Common triggers include:
- Transfers to accounts with available auto-association slots
  (configured via max_automatic_token_associations on the account)
- Payer-sponsored transfers to non-existent aliases (HIP-542: auto-account creation + association)
- Frictionless token airdrops (HIP-904: automatic association on transfer when allowed)

**Important: Informational / read-only only**
Creating an instance of this object has no effect on ledger state.
Instances of TokenAssociation cannot be submitted in any transaction.

To create an association explicitly, submit a TokenAssociateTransaction.
"""

from dataclasses import dataclass
from typing import Optional

from hiero_sdk_python.account.account_id import AccountId
from hiero_sdk_python.tokens.token_id import TokenId
from hiero_sdk_python.hapi.services.basic_types_pb2 import TokenAssociation as TokenAssociationProto


@dataclass(frozen=True)
class TokenAssociation:
    """
    A lightweight immutable representation of a token ↔ account association.

    Used in:
    - TransactionRecord.automatic_token_associations (list of associations
      created automatically during transaction execution)

    Attributes:
        token_id: The identifier of the token being associated.
        account_id: The identifier of the account receiving the association.

    See usage examples in:
        examples/tokens/token_association.py
    """

    token_id: Optional[TokenId] = None
    """The identifier of the token being associated."""

    account_id: Optional[AccountId] = None
    """The identifier of the account receiving the association."""

    @classmethod
    def _from_proto(cls, proto: TokenAssociationProto) -> "TokenAssociation":
        """
        Construct a TokenAssociation object from the protobuf representation.
        """
        return cls(
            token_id=(
                TokenId._from_proto(proto.token_id)
                if proto.HasField("token_id")
                else None
            ),
            account_id=(
                AccountId._from_proto(proto.account_id)
                if proto.HasField("account_id")
                else None
            ),
        )

    def _to_proto(self) -> TokenAssociationProto:
        """
        Convert this TokenAssociation back into a protobuf message.
        """
        proto = TokenAssociationProto()

        if self.token_id is not None:
            proto.token_id.CopyFrom(self.token_id._to_proto())

        if self.account_id is not None:
            proto.account_id.CopyFrom(self.account_id._to_proto())

        return proto

    def __str__(self) -> str:
        return f"TokenAssociation(token_id={self.token_id}, account_id={self.account_id})"

    def __repr__(self) -> str:
        return self.__str__()