This PR would be an easy merge if it didn't also make these changes to the signature. My objective in using *args and **kwargs was to avoid repetition of the signature of io.TextIOWrapper and make minimal assumptions about it. This new approach causes keyword-based arguments to be transformed to positional ones and will require maintenance if a future Python version adds a new argument.

It took me a moment to realize why this changed. It's basically inlining the logic of _extract_text_encoding into the signatures and parameter handling of the two affected methods. In my opinion, this logic should be encapsulated to capture its essential purpose (apply text_encoding to any encoding parameter).

If only we had something like Annotations as Transforms, we could write it as:

def open(self, mode='r', encoding:apply(text_encoding)=None, ...):

That would succinctly describe the intended effect and independent of the function logic.

Since we don't have parameter transforms, and because decorators are the current best art for implementing this kind of abstraction, I'd like to explore having a decorator to implement the "transform the encoding parameter" behavior.

I may end up deciding that this proposed approach is best.

I tried writing a decorator, but observed it's nearly impossible to reliably extract a possibly positional or possibly keyword argument from the middle of a signature like this one. So I've abandoned that concept.

In a3a66c5, I've restored the _extract_text_encoding function. This approach is a smaller diff and avoids changing assumptions about encoding parameters.

I'm not sure I love it. There was something elegant about being able to call text_encoding directly and without any stacklevel overrides.

I'm tempted to say let's go with the smaller change for now and we can revisit what to do about _extract_text_encoding later. Maybe we simply revert that commit. Or maybe we keep the "extract" logic and apply the text_encoding to the extracted encoding parameter.