The attributes section should be removed.

Can you add , optional here.

Can you add , optional here.

Ship It!

When taking things in, we should ideally use Sequence instead of list (unless we're assigning directly to a list).

We should return a Mapping with a Sequence instead, so it's not mutable.

Same here: Sequence and Mapping.

I think Iterator is correct here, since the function yields items and is therefore an iterator, rather than returning something that can be iterated over.
Usually Iterator is taken in as something you want to iterate over, and Iterator (a subtype of Iterator) is returned as a thing from a function providing iteration.

We should maybe begin moving to keyword-only arguments.
Note that subclasses would need any deprecation decorators applied to their versions as well. Same with any other cases like this.

I feel like it'd be preferable to keep this up above where the other attributes are, and keep functions below any attributes, even if they're classmethods. These get heavily buried otherwise.

Summary must be on its own line.

Summary must be on its own line.

It'd be nice to move to keyword-only arguments here.

It'd be nice to move to keyword-only arguments here.
Same caveat as above.

Should be a django.utils.safestring.SafeString.

We should use Sequence or maybe Iterable here.

Can we type this?

Should maybe be Iterable.

Here, too.

Missing docs.

This needs to be Type, given Python 3.8 compatibility.

Should be Iterable.

Ship It!