Multiset

Common errors

• TypeError: unhashable type: 'Multiset'

  cause Attempting to use a mutable `Multiset` object as a key in a dictionary or as an element in a set (or frozenset).
  fix Use `FrozenMultiset` for scenarios requiring hashability. For example: `my_dict = {FrozenMultiset([1, 2]): 'value'}`.

• AttributeError: 'Multiset' object has no attribute 'keys'

  cause Attempting to use a `dict`-specific method (`keys`, `values`, `items`, `popitem`, etc.) directly on a `Multiset` object after the API change in version 2.0.0.
  fix Use the `multiset` equivalent methods. For `keys`, use `multiset_instance.distinct_elements()`. For `items`, use `multiset_instance.items()`. Refer to the official API documentation for replacements.

• KeyError: 'element_name' (from get, setdefault, remove, or del)

  cause The `Multiset.get()` method requires a `default` argument (unlike `dict.get()`). `Multiset.setdefault()` also requires a `default` and will only add an element if the default is positive. Using `multiset_instance.remove(element)` or `del multiset_instance[element]` will raise a `KeyError` if the element is not present, unlike `multiset_instance.discard(element)` which will not.
  fix For `get`, always provide a `default` argument, e.g., `my_multiset.get(element, 0)`. For `setdefault`, ensure the `default` is positive if you expect a new element to be added. Use `discard()` if you want to remove an element without raising an error if it's missing.

Warnings

• breaking Python 3.7 is no longer supported starting from `multiset` version 3.1.0. Additionally, support for Python 2.7 and 3.6 was dropped in version 3.0.0.
  Fix: Ensure your Python environment is running Python 3.8 or higher.
• breaking In version 2.0.0, the `Multiset` class ceased direct inheritance from `dict`. Consequently, some `dict` methods (e.g., `keys()`, `values()`, `items()`, `fromkeys()`, `get()`, `setdefault()`, `pop()`, `popitem()`) were either removed, renamed, or had their signatures altered.
  Fix: Consult the official `multiset` API documentation for the correct method names and signatures. For example, use `multiset_instance.distinct_elements()` for distinct keys, or `multiset_instance.items()` for (element, multiplicity) pairs.
• gotcha The mutable `Multiset` object is not hashable and therefore cannot be used as a dictionary key or as an element in a `set`. The `FrozenMultiset` class, introduced in version 2.0.0, provides an immutable and hashable alternative.
  Fix: If a hashable multiset is required, use `FrozenMultiset`. For example, `my_dict = {FrozenMultiset([1, 2]): 'value'}`.
• gotcha Unlike `collections.Counter`, the `multiset` library automatically removes elements from the multiset whose multiplicity reaches zero. It also strictly only allows positive counts during initialization and other operations.
  Fix: Be aware that elements with zero (or negative) counts are not stored or represented. If you need to track zero or negative counts, `collections.Counter` from the standard library might be a more suitable data structure.

Install

• pip install multiset Install stable version

Imports

• Multiset

  from multiset import Multiset

• FrozenMultiset
  wrong:

  from multiset import Multiset; my_frozenset = Multiset([...]).freeze() # Old pattern or misunderstanding of API

  correct:

  from multiset import FrozenMultiset

  The `FrozenMultiset` class was introduced in version 2.0.0 to provide an immutable, hashable multiset, replacing the need for manual 'freezing' or reliance on the mutable `Multiset` for hashable contexts.

Quickstart

Demonstrates how to create mutable and immutable multisets, add elements, check multiplicities, and perform basic set operations.

from multiset import Multiset, FrozenMultiset

# Create a mutable multiset from an iterable
m1 = Multiset('banana')
print(f"Initial multiset: {m1}")
# Output: Initial multiset: {b, a, n, a, n, a}

# Add elements
m1.add('apple', multiplicity=2)
print(f"After adding apples: {m1}")
# Output: After adding apples: {b, a, n, a, n, a, apple, apple}

# Check multiplicity (count) of an element
print(f"Count of 'a': {m1.get('a')}")
# Output: Count of 'a': 3

# Perform set operations
m2 = Multiset(['a', 'p', 'p', 'l', 'e'])
intersection = m1 & m2
print(f"Intersection of m1 and m2: {intersection}")
# Output: Intersection of m1 and m2: {a, a, apple, p, l, e}

# Create an immutable, hashable multiset
f1 = FrozenMultiset([1, 1, 2, 3])
f2 = FrozenMultiset([1, 2, 2, 4])
print(f"Frozen multiset f1: {f1}")
# Output: Frozen multiset f1: {1, 1, 2, 3}

# Frozen multisets can be used in sets or as dict keys
my_set_of_multisets = {f1, f2}
print(f"Set of frozen multisets: {my_set_of_multisets}")
# Output: Set of frozen multisets: {{1, 1, 2, 3}, {1, 2, 2, 4}}