Add get_collision_info_with_list and sprite_push_out example

[pvcraven]

Summary

PR 2 of the push-out plan, following get_collision_info (#2910):

• arcade.get_collision_info_with_list(sprite, sprite_list, method=AUTO) returns a (colliding_sprite, CollisionInfo) pair for each sprite in the list that sprite collides with, deepest overlap first.
• A new example, sprite_push_out, with a docs page.

get_collision_info_with_list

for wall, info in arcade.get_collision_info_with_list(player, walls):
    ...

• It finds the same sprites as check_for_collision_with_list, using the same CollisionMethod choice (spatial hash, every sprite, or GPU), and never includes sprite itself.
• Each CollisionInfo is exactly what get_collision_info(sprite, that_sprite) returns.
• Results are sorted deepest first, which is usually the overlap to resolve first. The sort is stable, so equal depths keep the order found.
• The docstring says that each result is about one sprite. Resolving one overlap changes the others, so they don't add up to a single move.

get_collision_info is split into the public function (type checks) and an internal _get_collision_info, so the list version doesn't repeat the checks for every sprite. Its behavior is unchanged.

The example

The player moves freely with the arrow keys, with no physics engine. After each update, it's pushed out of the deepest overlapping wall, up to 4 times in case one push moves it into another wall. Pushing along the smallest overlap makes it slide along walls, including the three rotated ones, instead of stopping.

I checked it with a script driving the example without a visible window:

• Walking into the 45° wall deflects the player and it keeps going.
• Holding each direction and each diagonal into the corners: the player stays inside the room.
• A 6,000-frame random walk: the player never leaves the room. The worst overlap left after pushing was 3×10⁻¹⁴ px, which is the rounding get_collision_info's docs mention.

While testing, my first layout had a gap narrower than the player between a rotated wall and the top wall. The player could get wedged there, pushed back and forth between the two walls. I moved that wall to leave room, and the random walk above was run on the final layout.

Docs:

• doc/example_code/sprite_push_out.rst follows the same format as the other example pages.
• It's added to the example index under "Player Movement".
• The screenshot was rendered from the example. Its thumbnail is generated by the docs build, as for the other examples.

Tests

• test_get_collision_info_with_list: for every CollisionMethod, with and without a spatial hash, it checks:
  • deepest-first order and exact normals and depths,
  • that each result matches get_collision_info,
  • the same sprites as check_for_collision_with_list,
  • touching and far-away sprites, and the sprite itself, excluded,
  • an empty list.
• test_get_collision_info_with_list_equal_depths: stable order for ties.
• Type-error tests.
• With the sort removed, 6 of these fail.
• The example passes the docstring, line-length, and run-one-frame example tests.
• Full suite on pyglet 3.0.dev11: 1435 passed. The 3 failures are the render tests that only fail on my machine. Ruff is clean, and mypy reports no errors in collision.py.

🤖 Generated with Claude Code