Question

According to my interpretation of Python 2.7.2 documentation for Built-In Types 5.7 Set Types, it should be possible to remove the elements of set A from set B by passing A to set.remove(elem) or set.discard(elem)

From the documentation for 2.7.2:

Note, the elem argument to the __contains__(), remove(), and discard()
methods may be a set.

I interpret this to mean that I can pass a set to remove(elem) or discard(elem) and all those elements will be removed from the target set. I would use this to do something weird like remove all vowels from a string or remove all common words from a word-frequency histogram. Here’s the test code:

Python 2.7.2 (default, Jun 12 2011, 14:24:46) [M...
Type "help", "copyright", "credits" or "license"
>>> a = set(range(10))
>>> b = set(range(5,10))
>>> a
set([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> b
set([8, 9, 5, 6, 7])
>>> a.remove(b)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: set([8, 9, 5, 6, 7])
>>> a.discard(b)
>>> a
set([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>>

Which I expect to return:

>>> a
set([0, 1, 2, 3, 4])

I know I can accomplish this with a.difference(b) which returns a new set; or with a set.difference_update(other); or with set operators a -= b, which modify the set in-place.

So is this a bug in the documentation? Can set.remove(elem) actually not take a set as an argument? Or does the documentation refer to sets of sets? Given that difference_update accomplishes my interpretation, I’m guess the case is the latter.

Is that unclear enough?

EDIT
After 3 years of additional (some professional) python work, and being recently drawn back to this question, I realize now what I was actually trying to do could be accomplished with:

>>> c = a.difference(b)
set([0,1,2,3,4])

which is what I was originally trying to get.

EDIT
After 4 more years of python development… I realize this operation can be expressed more cleanly using set literals and the - operator; and that it is more complete to show that set difference is non-commutative.

>>> a={0,1,2,3}
>>> b={2,3,4,5}
>>> a-b
set([0, 1])
>>> b-a
set([4, 5])

Answer 1

You already answered the question. It refers to sets of sets (actually sets containing frozensets).

The paragraph you are referring to begins with:

Note, the elem argument to the __contains__(), remove(), and discard() methods may be a set.

which means that b in a.remove(b) can be a set, and then continues with:

To support searching for an equivalent frozenset, the elem set is temporarily mutated during the search and then restored. During the search, the elem set should not be read or mutated since it does not have a meaningful value.

which means that if b is a set, a.remove(b) will scan a for a frozenset equivalent to b and remove it (or throw a KeyError if it doesn’t exist).