Test

src/hiero_sdk_python/tokens/token_association.py

@@ -0,0 +1,93 @@
+"""
+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__()
+