Python remove set from set

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])

set1-set2

set1={0,1,2,3}
set2={2,3,4,5}

set1-set2  # {0, 1}
set2-set1  # {4, 5}

However, note that for whatever reason you can't "+" sets in python...

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).

You can't have sets of sets in Python as a set is mutable. Instead, you can have sets of frozensets. On the other hand, you can call __contains__(), remove(), and discard() with a set. See this example:

a = set([frozenset([2])])
set([2]) in a       # you get True
a.remove(set([2]))  # a is now empty

So the answer to your question is that the documentation is referring to sets of frozensets.

I'm looking at the built-in help for various versions of python (for mac). Here are the results.

• python2.5

> remove(...)
Remove an element from a set; it must be a member.
If the element is not a member, raise a KeyError.

• python2.6

>remove(...)
Remove an element from a set; it must be a member. If the element is not a member, raise a KeyError.

• python2.7

>remove(...)
Remove an element from a set; it must be a member. If the element is not a member, raise a KeyError.

The documentation you refer to, in full, actually says:

> Note, the elem argument to the __contains__(), remove(), and discard() methods may be a set. To support searching for an equivalent frozenset, the elem set is temporarily mutated during the search and then restored.

This seems to be a footnote, that suggests the argument may be a set, but unless it finds a matching frozen set within the set, it will not be removed. The mention about the set being modified is so it can be hashed to look for a a matching frozen set.

I think the documentation is referring to sets of (frozen)sets, yes.