What is the possible misuse?
If the name doesn’t act like the builtin, people reading your
implementation may be confused. If the function/method is long, you
yourself might forget the special meaning this name has within the
function at some point. And, of course, you’re temporarily prevented
from easy access to the builtin itself during the function.
I am not sure why I should make the API less intuitive when the risk is really low and when I am aware of it anyway - as far as I can see the risk is entirely on the side of the module implementer, not something that could affect the users of the module.
Correct.
So if my module uses the parameter topy
in the API, all I have to do is make sure that I do not use type(somevar)
anywhere which is easy.
Yes, it is all easily addressable. English is relatively rich in
synonyms, so choosing an alternative name is sometimes easy. But there’s
no need for you to adopt a different name.
Your difficulties seemed to stem largely from linters complaining.
There’s no need to accept all recommendations from linters. For example,
I run a few linters, and turn off various complaints, see this:
https://hg.sr.ht/~cameron-simpson/css/browse/bin-cs/lint
Note the pycodestyle_ignore and pylint_disable settings. You can also
filter lint output to discard things, and some (eg pylint) lets you
insert special comments into your code to indicate that you’re well
aware that you’re doing something it might complain about, and are
perfectly fine with it. Example from my own code:
from cs.upd import print # pylint: disable=redefined-builtin
You may well want to make your own “lint” script to run linters how you
want them; it saves much pain.
This is where I struggle because 1) there are simply no intuitive and good synonyms and 2) the trailing underscore is ugly as hell for users of the api, especially with keyword parameters, e.g findnext(a, type_="x")
is just not as nice as findnext(a, type="x")
I agree about the ugliness.
So I am trying to figure out what the balance between the cost and the
benefits of following PEP rules / recommendations is here.
Once the library gets used by too many people, there will be no chance to reconsider.
Aye.
I myself have a few places where I’ve got a parameter named “type”.
In a number of places I qualify a parameter, eg:
def _make_random_Block(self, block_type=None, leaf_only=False):
where I’ve used “block_type” instead of “type”. In code where I’ve got a
few different kinds of types floating around using qualified names like
“block_type” is well worth it.
Finally: I am a huge advocate of APIs being easy to use and easy to
remember. If “type” is the most ergonomic name for your parameter, just
do it!
Cheers,
Cameron Simpson cs@cskk.id.au