As @AlexWaygood implied above, even builtin types can't provide the guarantee your current text for: if you call bool() or len() twice on a list, another thread might have run in between and mutated the list.

I think instead, we should say that in cases where the interpreter implicitly calls bool(), it is unspecified how often bool() is called, and it is unspecified what happens if multiple calls happen and they return different results. Not sure where to put that, though.

The language spec already says with regard to hashability:

The __hash__() method should return an integer. The only required property is that objects which compare equal have the same hash value

So some interesting questions that come to mind for me here are:

1. Does it ever make sense for objects that compare equal to have different boolean values?
2. Does it ever make sense for objects that have different boolean values to compare equal?
3. Does it ever make sense for x == y but len(x) != len(y)?

If we think that well-behaved code should never do those things, and that doing those things could violate some assumptions made by Python in some places, then we could consider adding a similar note to the language spec for __bool__, i.e.

A well-defined __bool__() method should never report different results for two objects that compare equal

But I'm not sure if it's worth doing so for __len__ as well/I'm not sure what a good phrasing might be there.

Additionally, this sort-of feels like an implicit requirement for an awful lot of dunders, really. I would find it pretty surprising if bytes(x) and bytes(y) produced different results for two objects x and y where x == y. Similarly for __int__, __index__, __neg__, etc... So that's an argument for not putting a special note in the entry for either __bool__ or __len__.

another thread might have run in between and mutated the list.

Then this example will not satisfy to added remark: calls to __bool__ weren't actually successive.

doing those things could violate some assumptions made by Python in some places

Do you have examples? While your points look reasonable, I'm not sure that such assumptions are actually used somewhere.

But I'm not sure if it's worth doing so for __len__

Well, in current version I have to add symmetric note for __len__ just because that helper might be used instead of __bool__ in some implicit call to bool().

So that's an argument for not putting a special note in the entry for either __bool__ or __len__.

There is a difference. The __bool__ method in general can return different values for same object; but the reference implementation does assume it can't be in certain conditions.

Maybe instead of saying something about __bool__(), we could instead say it about and/or. In a chain of logical ops, the interpreter is allowed to calculate the boolean value of any given term only once. Or more broadly, say in any given expression the boolean value of any given sub-expression may be reused if already calculated.

I think the docs can just say that __bool__ and __len__ should be idempotent.

I think the docs can just say that __bool__ and __len__ should be idempotent.

That's a more short version of the current statement, isn't? But I worry it might require explanation of the term. E.g. we don't expect that reader knows about complex numbers.

I think that I can't make progress on this.