This is a draft because I am going to apply the error handling changes in a separate issue first.

We can also apply some optimizations -- cache the ignored chars and returning on fast path after ignored characters.

Well, the issue with error handling was just that the error message could be more specific in some cases. It is not a bug. It can be included in this PR.

No worries, that was the point I was just free on Sunday, so I push out a PR in case you haven't started on it. BTW your PR looks good, I am no maintainer but you just have to run ./python Tools/build/generate_global_objects.py to generate the updated header files. I hope it helps.

Taking a quick look: The docs in this PR changed the default for validate and strict_mode from False to True. But versionchanged does not mention that change and there was no deprecation period. Did this behavior change? The docs need fixing at a minimum but if the behavior changed we also need a deprecation cycle. What I understand @vstinner above to be saying is to change the default only in the case of the new parameter being supplied?

that may just be a simple doc fix. the declaration lines need to not state a value for the parameters who's default behavior varies based on context:

.. function:: b64decode(s, altchars=None, validate=False)
              b64decode(s, altchars=None, validate=True, *, ignorechars)

.. function:: a2b_base64(string, /, *, strict_mode=False)
              a2b_base64(string, /, *, strict_mode=True, ignorechars)

The text below describes a dynamic behavior on both, but people will absolutely misread the function signature and not read the text if we do not indicate it in the signature.

Sorry, I do not understand. How is it different from what is in the documentation now?

Deprecation period is needed if we want to change the existing behavior into error. But ignorechars is new, there was no existing behavior which was changed.

Taking a quick look: The docs in this PR changed the default for validate and strict_mode from False to True. But versionchanged does not mention that change and there was no deprecation period. Did this behavior change?

The default remains validate=False (no change). The behavior only changes if you start using the new ignorechars parameter.

.. function:: b64decode(s, altchars=None, validate=False)
              b64decode(s, altchars=None, validate=True, *, ignorechars)

I like that. It's quick to read.