`operator.rst` mentioning `or_` should also mention dict merge operators

[doronbehar]

I was designing the following:

from functools import reduce
from operator import or_

dicts = [
    {"a": 1, "b": 2},
    {"c": 99, "d": 3},
    {"e": 4}
]

merged = reduce(or_, dicts, {})
print(merged)

And from reading:

cpython/Doc/library/operator.rst

Line 414 in ed73c90

| Bitwise Or | ``a | b`` | ``or_(a, b)`` |

And:

cpython/Doc/library/operator.rst

Lines 174 to 177 in ed73c90

	.. function:: or_(a, b)
	__or__(a, b)
	Return the bitwise or of *a* and *b*.

I wasn't sure if or_ applies also to dictionaries, but according to the trivial implementation, of course it does :). Anyway, I thought it would be nice to rephrase the above 2 parts of the document somehow - not sure exactly how to do phrase it myself.

Linked PRs

• gh-141623: operator.rst: don't use bitwise keyword #141846

[skirpichev]

Good catch. This affects also e.g. and_ and xor. (Maybe more.) These operators are defined e.g. for sets.

not sure exactly how to do phrase it myself.

I think something like "Return a | b" is fine.

[picnixz]

Is the issue about "bitwise or" not being defined for dictionaries in this case? and that you want to have another word for this?

[Yashp002]

Hi, I'd be happy to work on this.

From what I understand, the issue is that the current documentation for or_, and_, and xor_ says "Return the bitwise or of a and b" without clarifying that these operations are not defined for dictionaries.

I think the clearest fix would be to add a note under each operator (or_, and_, xor_) explicitly stating:

"Note: This operation is not defined for dictionaries or other types that do not support bitwise operations."

Alternatively, we could rephrase it to say:

"Return the bitwise or of a and b. This operator is defined for sets, integers, and other types supporting bitwise operations, but not for dictionaries."

Does one of these approaches seem best, or would you prefer a different phrasing?

Happy to submit a PR once we agree on the wording.

[picnixz]

Your analysis is inccorrect. It is defined for dictionaries.

[Yashp002]

So is the main problem here that bitwise or isn't communicated in the docs/isn't immediately obvious to be functional for dictionary merging as well?

[skirpichev]

Is the issue about "bitwise or" not being defined for dictionaries in this case?

No. The issue is that sphinx docs for operator.or_ says:

Return the bitwise or of a and b.

It's not true. This might return a set union, or a logical or of symbolic expressions in some CAS, or something else. Docstring seems correct here:

>>> help(operator.or_)
Help on built-in function or_ in module _operator:

or_(a, b, /)
    Same as a | b.

It's just a function analog of the corresponding expression. Same for and_, xor_, invert, truediv. Even for mul.

We might note, that for integers that means the bitwise or, or that for numbers operator.mul means multiplication. But I'm not sure if this worth to mention.

[picnixz]

No. The problem is likely that "bitwise or" is usually used for integers, not for objects in general. Here, it would be better to talk about "binary or" in contrast to "logical or" (which we cannot override).

[skirpichev]

The problem is likely that "bitwise or" is usually used for integers, not for objects in general.

SymPy uses __or__() to represent logical or for expressions.

[picnixz]

Urgh, I would have preferred the logical or to reflect the "logical" or in the sense of Python (with the or keyword and truthiness) and binary or for whatever else (binary since there are 2 operands). But if SymPy uses __or__ for logical expressions as well, let's just stick to a | b.