These functions can return str or bytes, and correspondingly accept a str or bytes file, depending on the formatter. Maybe we should make the formatters Generic, so that Formatter[str] would be a formatter that outputs strings, for example.

Yes, you're right. I was hoping to avoid needing to type the formatters as well.

I'm not sure how to actually type that. You'd want Formatter[str] if instantiated as Formatter(), and Formatter[bytes] if instantiated with Formatter(encoding="some_str") or Formatter(outencoding="some_str"). But, a Generic expects the type to be the same as a given parameter...

Maybe it's possible to cheat a little. Maybe something with overloads like this? I'm sure this is wrong though:

@overload
def __init__(self, encoding: None = ..., __type: _T = "str"): ...
@overload
def __init__(self, encoding: str, __type: _T = b"bytes"): ...

You are looking for self types:

@overload
def __init__(self: Formatter[str], encoding: None = ...) -> None: ...
@overload
def __init__(self: Formatter[bytes], encoding: str) -> None: ...

Yep, didn't think about doing that on the __init__.

OK, I think we're good now.