Proposal

This was recently proposed on discuss.python.org and was also proposed 15 years ago.

The old proposal did not move forward because:

• There were almost no known use cases.
• The Counter class was missing other multiset methods such as subset, superset, and equality tests.
• No other language implementation could be found that supported this operation.
• Math articles about multisets did not mention this operation.
• It was a one-off request that seemed unlikely to recur.

Since that time, some of those reasons have changed:

• We received a second request, so this is no longer a one-off.
• Since Python 3.10, Counter has full support for all the standard multiset methods.
• Maple subsequently added symdiff so now there is a precedent in another language.

Also looking at the discussions, the most obvious workaround (p | q) - (p & q) has the disadvantage of not working with signed inputs. A better workaround would be (p - q) | (q - p) which always gives the difference between the maximum count and the minimum count regardless of sign.

At this point, I'm inclined to complete the multiset API by adding symmetric_difference. With all the other multiset methods now being supported, there is a greater cognitive load for the method being missing than for it being present. It is easier to teach that all set operators are supported than teaching that all but one are supported.

The only downsides I can think of are:

1. It's possible (and perhaps likely) that this method will never get used.
2. Someone reading the code p ^ q would need to think carefully about what it does.

Linked PRs

• gh-138682: Add symmetric difference to Counter #138766