1. Bags can be compared to sets, including other bags. Following, we see how bags are evaluated compared to sets:

      >>> from collections_extended import bag
      >>> bag() == set()
      True
      >>> bag('a') == set('a')
      True
      >>> bag('ab') == set('a')
      False
      >>> bag('a') == set('ab')
      False
      >>> bag('aa') == set('a')
      False
      >>> bag('aa') == set('ab')
      False
      >>> bag('ac') == set('ab')
      False
      >>> bag('ac') <= set('ab')
      False
      >>> bag('ac') >= set('ab')
      False
      >>> bag('a') <= bag('a') < bag('aa')
      True
      >>> bag('aa') <= bag('a')
      False

• • First, comparison shows that an empty bag is equal to an empty set.
  • Next, the same, single element in both shows that they are still comparatively equal.
  • Adding a new element to a bag upsets the balance with a single-element set, as expected. The same thing happens when an extra element is added to the set and compared to a single-element bag.
  • A bag with duplicate elements (multiplicity = 2) is not equal to a set with a single element, even if it is the same value.
  • Jumping ahead, a bag with two different elements cannot be adequately compared to a set with different elements. While testing for equality is expected to fail, both greater than and less than comparisons fail as well.
  • Testing bags against each other may prove successful, depending on the comparisons. A single-element bag is obviously equal to itself, and is less than a bag with the element multiplicity > 1.
  • Conversely, multiplicity > 1 will not be less than or equal to a multiplicity of 1.

2. Bags are roughly related to Counter collections, but provide different functionality. ext_collections_bag_compare.py shows how bags and Counters deal with adding and removing elements:

      >>> from collections import Counter
      >>> c = Counter()
      >>> c['a'] += 1
      >>> c['a'] -= 1
      >>> 'a' in c
      True
      >>> b = bag()
      >>> b.add('a')
      >>> 'a' in b
      True
      >>> b.remove('a')
      >>> 'a' in b
      False

• • A Counter instance is created and populated with an element.
  • When the element is removed via subtraction, it is still active in memory, as it hasn't actually been deleted from the Counter (to actually remove a Counter element, the del function must be used).
  • When a bag instance is created and an element added to it, the existence of the element is evident. However, when the remove() function is used on a bag element, that element is, in fact, removed.

3. The following example demonstrates how Counters and bags deal with object length as elements are added, removed, and duplicated:

      >>> c = Counter()
      >>> c['a'] += 1
      >>> len(c)
      1
      >>> c['a'] -= 1
      >>> len(c)
      1
      >>> c['a'] += 2
      >>> len(c)
      1
      >>> len(Counter('aaabbc'))
      3
      >>> b = bag()
      >>> b.add('a')
      >>> len(b)
      1
      >>> b.remove('a')
      >>> len(b)
      0
      >>> len(bag('aaabbc'))
      6

• • A Counter instance is created and populated.
  • With only one element added, the length of the instance is 1.
  • When the element is subtracted from the Counter, the length is still 1, as the element hasn't actually been removed from the Counter.
  • Adding multiple copies of an element to the Counter doesn't extend the length. The Counter simply tracks how many elements of the same value have been added, but doesn't append those values to its actual length.
  • Adding and removing elements to a bag, regardless of whether they are duplicates, actually affects the length of the bag object.

4. When iterating, bags again behave differently to Counters:

      >>> for item in Counter('aaa'): print(item)
      a
      >>> for item in bag('aaa'): print(item)
      a
      a

• • While a Counter prints only the element it contains (as the element is a key, with its value equal to the quantity of that key), a bag actually has all the elements contained in it, so it will print each and every element.

5. Several new methods are provided for bags:

• • num_unique_elements: It returns the number of unique elements in the bag.
  • unique_elements(): It returns a set of all the unique elements in the bag.
  • nlargest(n=None): It returns the n most common elements and their quantities, from most common to least common. If n is not provided, then all elements are returned.
  • copy(): It returns a shallow copy of the bag.
  • isdisjoint(other: Iterable): It tests whether the bag is disjoint with the provided Iterable.
  • from_mapping(map: Mapping): A class method to create a bag from the provided Mapping; maps the elements to counts.