PR summary

closes #30547

This PR enhances the API of draw_path_collection() for long term maintainability.

Summary of Changes

1. Introduces the new VectorizedGraphicsContextBase class, which is similar to GraphicsContextBase, but each attribute is vectorized. This serves as the dataclass through which all parameters are passed to draw_path_collection().

2. Updated signature of draw_path_collection() by making the parameters optional in order to support both the following:

   • The previous call with gc and all parameters present
   • The new call with vgc and none of the optional parameters

3. Updated signature of _iter_collection() to take vgc instead of gc and added logic to cycle through all attributes.

4. Changed draw() in Collection to use the new draw_path_collection() API along with temporary fallback for third-party backends that use the old signature.

Why is this change required?

It would become much simpler to add / vectorize new attributes in collections, without completely breaking third party backends. For example, it would greatly simplify #27937, that aims to vectorize the hatch attribute.

To-do

• Docstrings
• What's new note
• Deprecation notice for the old API

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines