Rename 'agents' property to 'df' for AgentContainer for issue # 68

mesa_frames/abstract/agents.py

@@ -61,6 +61,8 @@
     Series,
 )
 
+import warnings
+
 if TYPE_CHECKING:
     from mesa_frames.abstract.space import SpaceDF
     from mesa_frames.concrete.agents import AgentSetDF
@@ -645,6 +647,26 @@
         """
         return self.model.space
 
+    @property
+    @abstractmethod
+    def df(self) -> DataFrame | dict[str, DataFrame]:
+        """The agents in the AgentContainer.
+
+        Returns
+        -------
+        DataFrame | dict[str, DataFrame]
+        """
+
+    @df.setter
+    @abstractmethod
+    def df(self, agents: DataFrame | list[AgentSetDF]) -> None:
+        """Set the agents in the AgentContainer.
+
+        Parameters
+        ----------
+        agents : DataFrame | list[AgentSetDF]
+        """
+
     @property
     @abstractmethod
     def agents(self) -> DataFrame | dict[str, DataFrame]:
@@ -664,6 +686,11 @@
         ----------
         agents : DataFrame | list[AgentSetDF]
         """
+        warnings.warn(
+            "Setting 'agents' is deprecated. Use 'df' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
     @property
     @abstractmethod
@@ -1038,8 +1065,28 @@
     def __reversed__(self) -> Iterator:
         return reversed(self._agents)
 
+    @property
+    def df(self) -> DataFrame:
+        return self._agents
+
+    @df.setter
+    def df(self, agents: DataFrame) -> None:
+        """Set the agents in the AgentSetDF.
+
+        Parameters
+        ----------
+        agents : DataFrame
+            The agents to set.
+        """
+        self._agents = agents
+
     @property
     def agents(self) -> DataFrame:
+        warnings.warn(
+            "'agents' is deprecated. Use 'df' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self._agents
 
     @agents.setter
@@ -1051,6 +1098,11 @@
         agents : DataFrame
             The agents to set.
         """
+        warnings.warn(
+            "Setting 'agents' is deprecated. Use 'df' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self._agents = agents
 
     @property

mesa_frames/concrete/agents.py

@@ -62,6 +62,8 @@
     Series,
 )
 
+import warnings
+
 if TYPE_CHECKING:
     from mesa_frames.concrete.model import ModelDF
 
@@ -553,12 +555,37 @@
 
     @property
     def agents(self) -> dict[AgentSetDF, DataFrame]:
+        warnings.warn(
+            "'agents' is deprecated. Use 'df' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return {agentset: agentset.agents for agentset in self._agentsets}
 
     @agents.setter
     def agents(self, other: Iterable[AgentSetDF]) -> None:
         """Set the agents in the AgentsDF.
 
+        Parameters
+        ----------
+        other : Iterable[AgentSetDF]
+            The AgentSetDFs to set.
+        """
+        warnings.warn(
+            "Setting 'agents' is deprecated. Use 'df' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self._agentsets = list(other)
+
+    @property
+    def df(self) -> dict[AgentSetDF, DataFrame]:
+        return {agentset: agentset.agents for agentset in self._agentsets}
+
+    @agents.setter
+    def df(self, other: Iterable[AgentSetDF]) -> None:
+        """Set the agents in the AgentsDF.
+
         Parameters
         ----------
         other : Iterable[AgentSetDF]

mesa_frames/concrete/agentset.py

@@ -73,6 +73,7 @@
     from mesa_frames.concrete.model import ModelDF
 
 import numpy as np
+import warnings
 
 
 @copydoc(AgentSetDF)
@@ -495,12 +496,32 @@
     def __reversed__(self) -> Iterator:
         return reversed(iter(self._agents.iter_rows(named=True)))
 
+    @property
+    def df(self) -> pl.DataFrame:
+        return self._agents
+
+    @df.setter
+    def df(self, agents: pl.DataFrame) -> None:
+        if "unique_id" not in agents.columns:
+            raise KeyError("DataFrame must have a unique_id column.")
+        self._agents = agents
+
     @property
     def agents(self) -> pl.DataFrame:
+        warnings.warn(
+            "'agents' is deprecated. Use 'df' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self._agents
 
     @agents.setter
     def agents(self, agents: pl.DataFrame) -> None:
+        warnings.warn(
+            "Setting 'agents' is deprecated. Use 'df' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if "unique_id" not in agents.columns:
             raise KeyError("DataFrame must have a unique_id column.")
         self._agents = agents