Underscored parameters of functions sometimes are used for different purposes. For example see random.Random.randrange(), subprocess.Popen.__del__() or codecs.CodecInfo.__new__(). These parameters are not a part of public API and should be excluded from help() or pydoc output.

This is not universally true.  Both namedtuple (for good reason) and email (for not-so-good reasons) have _ parameters that are part of the public API.

They can be explicitly mentioned in docstrings.

I'm -1 on this.

Yes, there is a convention in Python that _names are kind of private, but it's just a convention, and not everybody follow it. Making this change would just break too many things.

As for the code in question: Random.randrange -- why does it have this '_int' parameter, after all?

-1 as well.

Yury: it's a micro-optimization, the slow builtin lookup becomes a fast local lookup.

For context, codecs.CodecInfo now takes an undocumented "_is_text_encoding"
keyword-only argument to blacklist codecs from TextIOWrapper, str.encode,
bytes.decode etc. Serhiy expressed some concern that users would see that
via Pydoc, believe it was a public API, and then complain when it was
replaced by an official public API in 3.5. I suggested that hiding keyword
only underscore parameters in Pydoc might be an appropriate resolution of
that concern.

This was right around the time the Zope breakage due to relying on a
private parameter was discovered.

Some thoughts:

- you can never hide positional parameters, they affect the signature too
much
- hiding underscore prefixed keyword-only parameters *might* be reasonable
- Guido clarified the Zope breakage likely stemmed from the Python Labs
days when they occasionally blurred the lines between public API and
implementation detail a bit too much while working on both Zope *and* the
standard library
- users are generally aware that if they're relying on an undocumented
interface that starts with an underscore, it's up to them to adjust if it
changes behaviour in the next feature release
- I'm actually OK with the idea of advanced users deciding to blacklist
their own codecs if they so choose

So since making the suggestion originally, I have changed my view from +1
to -0 regarding making this change for keyword-only arguments. I was always
-1 for positional arguments.

> Yury: it's a micro-optimization, the slow builtin lookup becomes a fast local lookup.

That's what I thought, thank you.
I think we should discourage use of this pattern (at least in the stdlib). There is small to no performance benefit to do that.

And if it's absolutely required to optimize the hell out of function, it's much better to just create a protected module attribute:

_int = int

That way, there is almost no performance difference between _int in the signature, and _int as a module global.

We can *probably* make a convention, that "dunder" parameters are hidden from the pydoc.

like 'func(a, b, *, c, __hidden__=True, __int__=int)'

Or simply those that start with '__'. I'd be -0 on that ;)

Yes, this issue is based on Nick's intention in msg206515.

Since this issue was rejected, my objection against adding new underscored parameters in issue19619 remain in force.