On Sat, 24 Dec 2022 at 15:00, Cameron Simpson <cs@cskk.id.au> wrote:
On 24Dec2022 14:35, Chris Angelico <rosuav@gmail.com> wrote:
On Sat, 24 Dec 2022 at 13:15, Cameron Simpson <cs@cskk.id.au> wrote: My question was more: do you know, or do you have to look? I'll take another example. Take the list.index() method, which returns the index where a thing can be found. *Without checking first*, answer these questions:
1) Will identical-but-not-equal values (eg the same instance of nan) be found?
I'd say no, because it should need to do an equality check to compare things.
Well, I'm wrong. Assuming it does a precheck with "is", I guess.
Indeed; even experts don't always know this. The check used is the "identity-or-equality" check common to a lot of containment checks in Python.
2) Do the docs and/or docstring tell you the answer to question 1?
[ To the docs!... How disappointing, the "Index" href at top right does not take me directly to list.index :-) ]
:)
help(list.index) seems empty.
Huh that's strange. I'm checking this in a few recent versions, and they all say "Return first index of value".
The best docs seem to be .index for sequences: https://docs.python.org/3/library/stdtypes.html#index-19 which only allude to the intended semantics:
index of the first occurrence of x in s (at or after index i and before index j)
I guess that though _could_ imply an object identify check, but if I read it that way I might really take it to mean identity ("occurrence of x in s"), rather than the more useful and expected "also equal".
The docs are a bit lax about mentioning the identity check (see further up in the same table, where containment is described in terms of equality; in actual fact, nan in [nan] will be True), but this seldom comes up in practice because most objects are equal to themselves.
The "nan" test says to me that there's an identity check, which is at least quite fast and maybe significantly useful for types which intern small values like int.
Right. I think that, originally, the identity check was considered to be merely an optimization, and values that compare unequal to themselves were considered weird outliers; it's only more recently that it was decided that the "identity-or-equality" semantic check was worth documenting. (No behavioural change, just a change in the attitude towards "weird values".)
And then a logical followup:
3) If your answer to question 1 was incorrect, {does it help, would it have helped} to have a note in the docs?
It would help to be able to understand the behaviour. I think with `list.index` I'd expect an equality test only (I was surprised by your "nan" example, even though "nan" is a pretty unusual value).
It might help in those rare instances where you think to go and read the docs, which basically means the times when something looks wrong to you. It almost certainly won't help for cases where someone doesn't recognize a problem. With string uppercasing, anyone who would think to look in the docs for how it handles locale-specific case conversions is already going to understand that it can't possibly do anything more than a generic translation table, so I don't think it'd buy anything to have a note in the docs. ChrisA