Inconsistent behavior between `_io.text_encoding` and `_pyio.text_encoding`

[donBarbos]

Bug report

Bug description:

>>> import _io, _pyio
>>> _pyio.text_encoding(None, stacklevel=2)
'locale'
>>> _io.text_encoding(None, stacklevel=2)
Traceback (most recent call last):
  File "<python-input-54>", line 1, in <module>
    _io.text_encoding(None, stacklevel=2)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
TypeError: _io.text_encoding() takes no keyword arguments

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

[tomasr8]

Indeed, the C function signature is marked as positional-only:

cpython/Modules/_io/_iomodule.c

Lines 457 to 460 in e51da64

	_io.text_encoding
	encoding: object
	stacklevel: int = 2
	/

This was originally added when PEP 597 was implemented:
https://github.com/python/cpython/pull/19481/files#diff-0501b143a2f566e8a760abc20a88fd2533b1f230e5322831f400a0263b8c0253R511-R514

However, I didn't find any comments in the PR explaining why this is so. In addition, the example implementation in the PEP also allows keyword arguments.

cc @methane as the original author

[methane]

I just didn't care it well.

The doc uses positional only argument. It is official specification than the PEP.
https://docs.python.org/3.13/library/io.html#io.text_encoding

Unless clear use case for keyword argument here, how about just prohibit keyword argument on _pyio too?

[donBarbos]

Firstly, the documentation doesn't say anything about how to use the stacklevel argument. Yes, the positional argument is used in the example, but only the encoding argument is passed there.
Also, the C signature of the _io.open function is marked exactly the same like stacklevel argument (but these are keyword arguments).

cpython/Modules/_io/_iomodule.c

Lines 74 to 82 in e51da64

	_io.open
	file: object
	mode: str = "r"
	buffering: int = -1
	encoding: str(accept={str, NoneType}) = None
	errors: str(accept={str, NoneType}) = None
	newline: str(accept={str, NoneType}) = None
	closefd: bool = True
	opener: object = None

Secondly, if we remove stacklevel argument as keyword argumnet in _pyio implementation and leave it as positional argument, it will break backward compatibility.

I just suggest to consider stacklevel argument as a keyword argument.

cc @methane, @tomasr8

[methane]

Firstly, the documentation doesn't say anything about how to use the stacklevel argument. Yes, the positional argument is used in the example, but only the encoding argument is passed there.

The / means all arguments are positional-only.

[donBarbos]

@methane, oh sorry my bad.
so in the end we need to change the behavior of the python implementation?

[methane]

Secondly, if we remove stacklevel argument as keyword argumnet in _pyio implementation and leave it as positional argument, it will break backward compatibility.

_pyio is very minor module. Almost no one use it except testing purpose.

• Removing keyword support from _pyio needs only changelog.
• Adding keyword support to _io needs document update (e.g. versionchanged) and what's new etry.

This is why I am proposing just remove it unless there is clear benefits.

[donBarbos]

@methane, sounds good enough to me. I have no more objections to fixing the python implementation.
I'm ready to send PR.

[tomasr8]

Requiring positional-only arguments in pyio is definitely easier but I lean more towards allowing kw arguments in the C implementation.

For one, it's not a breaking change, unlike changing pyio even if very few people are using it. There's also no good reason for enforcing positional-only arguments and I'd even say it promotes bad habits because it forces you to write code like text_encoding(encoding, 2) with a magic constant, rather than text_encoding(encoding, stacklevel=2).

[methane]

FWIW, this function is not for regular users.
Good habit is do not use this function at all. Use encoding="utf-8" as default encoding instead.

This function is for almost only stdlib. 3rd party libraries may need it too, but it is rare.
Additionally, using stacklevel other than 2 is more rare. It is really rare.

That is why I am reluctant to make API improvements that would require a what's new entry and versionchanged note.
But If you still wish to make improvements, I am not opposed.

[picnixz]

Does PyPy uses the pure-python implementation io or not? if it does, we should not make a breaking change =/