This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: set update method description is incorrect
Type: Stage:
Components: Documentation Versions: Python 2.4
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: Nosy List: rickbking, terry.reedy
Priority: normal Keywords:

Created on 2006-03-01 20:19 by rickbking, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (2)
msg27637 - (view) Author: Richard King (rickbking) Date: 2006-03-01 20:19
Update is described as returning the set with the new 
members, but it only updates the set and returns None.
msg27638 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2006-03-06 04:40
Logged In: YES 
user_id=593130

You are right.

It is standard in Python for mutating methods to return 
None.  

The doc strings for update are more or less OK.
>>> set.update.__doc__
'Update a set with the union of itself and another.'
>>> sets.Set.update.__doc__
'Add all values from an iterable (such as a list or file).'

But
http://docs.python.org/lib/types-set.html 
http://docs.python.org/lib/set-objects.html
both incorrectly describes the first four update methods 
as returning the set after the update

(In the furture, giving specific section references or url 
for questionable docs would help verify the report.)

Verifying the expected behavior for the module:
>>> from sets import Set as S
>>> c=S([1,2,3])
>>> d=S([2,3,4])
>>> c.update(d)
>>> c
Set([1, 2, 3, 4])
# etc

Suggested fixes for both files:  In "The following table 
lists operations available ..." add 'mutation' 
before 'operatons' and follow the sentence with "All 
return None."
Change "return set s with elements added from t"
to "add elements from t to s"
Change "return set s keeping only elements also found in t"
to "remove elements of s not found in t"
Change "return set s after removing elements found in t"
to "remove elements of s also found in t"
Change "return set s after removing elements found in t"
to "remove elements of s also in t and add elements of t 
not in s"

Verify with set/sets author (RH I believe).

Additional glitch: at the bottom of 
http://docs.python.org/lib/types-set.html
there is a link to 'sets'
http://docs.python.org/lib/module-comparison-to-builtin-
set.html
I currently get 'page not found' message.

While on the topic of doc glitches:
http://docs.python.org/lib/typesmapping.html
has title "2.3.8 Mapping Types -- classdict"
'classdict'? looks like a typo.
History
Date User Action Args
2022-04-11 14:56:15adminsetgithub: 42961
2006-03-01 20:19:39rickbkingcreate