Skip to content

Deprecate AgentSet sequence behavior and add to_list() method#3208

Merged
quaquel merged 4 commits intomesa:mainfrom
codebyNJ:deprecate-agentset-sequence
Jan 26, 2026
Merged

Deprecate AgentSet sequence behavior and add to_list() method#3208
quaquel merged 4 commits intomesa:mainfrom
codebyNJ:deprecate-agentset-sequence

Conversation

@codebyNJ
Copy link
Copy Markdown
Contributor

@codebyNJ codebyNJ commented Jan 25, 2026

Summary

  • Add to_list() method to AgentSet for explicit list conversion
  • Add PendingDeprecationWarning to getitem directing users to use to_list()

This PR implements the deprecation path discussed in #3185, preparing users for the removal of sequence behavior in Mesa 4.0.

Motivation

As discussed in #3185, sequence support (indexing/slicing via getitem) on AgentSet will be removed in Mesa 4.0. This PR provides:

  1. A migration path for users via the new to_list() method
  2. Clear deprecation warnings guiding users to update their code

Changes

mesa/agent.py

  • Added to_list() method that returns a list of all agents in the AgentSet
  • Added PendingDeprecationWarning to getitem with guidance to use to_list()[index]

tests/test_agent.py

  • Added test_agentset_to_list() to test the new method
  • Updated test_agentset_get_item() to verify the deprecation warning is raised
  • Updated existing tests to use to_list() instead of direct indexing

@github-actions
Copy link
Copy Markdown

github-actions bot commented Jan 25, 2026

Performance benchmarks:

Model Size Init time [95% CI] Run time [95% CI]
BoltzmannWealth small 🟢 -4.2% [-4.7%, -3.8%] 🔵 -1.9% [-2.1%, -1.7%]
BoltzmannWealth large 🔵 +6.1% [-1.2%, +14.0%] 🔴 +7.8% [+5.8%, +9.9%]
Schelling small 🟢 -5.5% [-5.9%, -5.0%] 🔵 -1.1% [-1.2%, -1.0%]
Schelling large 🔵 +0.3% [-4.6%, +5.5%] 🔵 +1.9% [+0.7%, +3.2%]
WolfSheep small 🔵 +1.8% [+0.1%, +3.7%] 🔵 -1.3% [-1.6%, -1.0%]
WolfSheep large 🔴 +30.6% [+14.7%, +46.3%] 🔴 +5.6% [+4.2%, +7.1%]
BoidFlockers small 🟢 -3.6% [-4.0%, -3.2%] 🔵 -0.3% [-0.5%, -0.1%]
BoidFlockers large 🔵 +1.3% [-0.6%, +3.8%] 🔵 -0.2% [-0.4%, -0.0%]

quaquel
quaquel reviewed Jan 25, 2026
View reviewed changes
mesa/agent.py Outdated
Sequence behavior (indexing/slicing) is deprecated and will be removed in Mesa 4.0.
Use :meth:`to_list` instead: ``agentset.to_list()[index]`` or ``agentset.to_list()[start:stop]``.
"""
if not AgentSet._getitem_warning_emitted:
Copy link
Copy Markdown
Member

@quaquel quaquel Jan 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i dont;t think this is needed. warnings.warn should filter repeated warnings if I am not mistaken (but please test and check).

Copy link
Copy Markdown
Contributor Author

@codebyNJ codebyNJ Jan 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're partially correct! Python's warnings.warn with 'default' filter does suppress repeated warnings, but only per unique call site (due to stacklevel=2). Without the flag, if a user has agentset[0] in multiple locations, they'd see the warning once per location.

The class-level flag ensures the warning appears only once globally per session, which is less noisy but may hide additional call sites that need updating.

Options:

  1. Keep the flag - Shows warning exactly once globally (current implementation)
  2. Remove the flag - Shows warning once per call site (Python's default behavior, helps users find all locations to update)

Note: PendingDeprecationWarning is ignored by default in Python, so most users won't see this warning unless they enable it explicitly (e.g., running with -W default::PendingDeprecationWarning).

Which behavior do you prefer?

Copy link
Copy Markdown
Member

@quaquel quaquel Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest removing the if and relying on Python's warning behavior. Let's keep this as simple as possible.

Copy link
Copy Markdown
Contributor Author

@codebyNJ codebyNJ Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. I have updated the PR by relying on python's warning behavior.

@quaquel quaquel mentioned this pull request Jan 26, 2026
Merged
@quaquel quaquel added the deprecation When a new deprecation is introduced label Jan 26, 2026
@quaquel quaquel merged commit 6914176 into mesa:main Jan 26, 2026
12 of 13 checks passed
@EwoutH
Copy link
Copy Markdown
Member

EwoutH commented Jan 27, 2026

Thanks of the PR.

Can you add a small section to our migration guide?

@codebyNJ
Copy link
Copy Markdown
Contributor Author

codebyNJ commented Jan 27, 2026 •
edited
Loading

Thanks of the PR.

Can you add a small section to our migration guide?

Sure I will.

@codebyNJ
Copy link
Copy Markdown
Contributor Author

codebyNJ commented Jan 28, 2026

@EwoutH would you like to add this section under mesa 3.4.0 version or new mesa 3.5.0? And also could you verify the Content in it.

AgentSet Sequence Behavior Deprecation

The Sequence behavior (indexing and slicing) on AgentSet is deprecated and will be removed in Mesa 4.0. Use the new to_list() method instead.

# Old (deprecated)
first_agent = model.agents[0]
some_agents = model.agents[1:5]
last_agent = model.agents[-1]

# New
first_agent = model.agents.to_list()[0]
some_agents = model.agents.to_list()[1:5]
last_agent = model.agents.to_list()[-1]

For multiple list operations, convert once and reuse:

agent_list = model.agents.to_list()
first = agent_list[0]
last = agent_list[-1]
subset = agent_list[2:8]

Ref: PR #3208

@EwoutH
Copy link
Copy Markdown
Member

EwoutH commented Jan 28, 2026

On first glance the content looks good. I can add it, but if you like, you can also open a PR yourself. Our migration guide is available/editable here: https://github.com/mesa/mesa/blob/main/docs/migration_guide.md

@codebyNJ
Copy link
Copy Markdown
Contributor Author

codebyNJ commented Jan 28, 2026

@EwoutH I have created PR #3218 regarding the migration guide.

@souro26 souro26 mentioned this pull request Jan 31, 2026
Merged
@Jayantparashar10 Jayantparashar10 mentioned this pull request Feb 4, 2026
Closed
Jayantparashar10 added a commit to Jayantparashar10/mesa that referenced this pull request Feb 4, 2026
@Jayantparashar10
fix: update meta_agents extract_class to use to_list()
fdf4ea7 
Replace deprecated AgentSet[index] with AgentSet.to_list()[index]
in extract_class function per Mesa 4.0 migration guidelines.

Fixes mesa#3240
Related to mesa#3208 and mesa#3218
@Jayantparashar10 Jayantparashar10 mentioned this pull request Feb 4, 2026
Merged
quaquel pushed a commit that referenced this pull request Feb 4, 2026
@Jayantparashar10
fix: update meta_agents extract_class to use to_list() (#3241)
352c46c 
* fix: update meta_agents extract_class to use to_list()

Replace deprecated AgentSet[index] with AgentSet.to_list()[index]
in extract_class function per Mesa 4.0 migration guidelines.

Fixes #3240
Related to #3208 and #3218

* Use iterator protocol instead of to_list()

Per maintainer feedback, use next(iter()) which is more efficient
than converting to list first.
@codebreaker32 codebreaker32 mentioned this pull request Mar 19, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@quaquel quaquel quaquel approved these changes

Assignees

No one assigned

Labels

deprecation When a new deprecation is introduced

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@codebyNJ @EwoutH @quaquel