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.

Title: Set operations documentation error
Type: Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 2.7
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Alexander Mentis, docs@python, rhettinger, serhiy.storchaka
Priority: low Keywords:

Created on 2017-11-09 19:06 by Alexander Mentis, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Messages (4)
msg305981 - (view) Author: Alexander Mentis (Alexander Mentis) Date: 2017-11-09 19:06
Documentation for set/frozenset says |=, &=, -=, ^= operators do not apply to immutable instances of frozenset. This is incorrect. These operators can be used on frozenset; however, they behave differently on frozenset than on set. When used with set, they modify the target set in place. When used with frozenset, they return a new frozenset that replaces the target frozenset.
msg306060 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-11-10 23:31
This is an artifact of how in-place operators work (which is a topic covered in the Library Reference).  It doesn't really have anything to do with frozensets specifically.  For example, you see the same effect with tuples which like frozensets are immutable and do not implement any of the in-place dunder methods:

    >>> s = ('a', 'b', 'c')
    >>> s += ('d', 'e')
    >>> s
    ('a', 'b', 'c', 'd', 'e')

IIRC, this is the first time this has come-up in the 15 year history of sets, so I don't think there is a real problem to be solved.  At best, this should be a FAQ entry or relegated to StackOverflow.  I would prefer not to alter the set documentation because doing so would likely create confusion rather than solve it.
msg306067 - (view) Author: Alexander Mentis (Alexander Mentis) Date: 2017-11-10 23:56
I don't think you understood my bug.

That the augmented assignment operators work differently for set and frozenset is not the issue.

The issue is that the documentation says that the |=, &=, -=, ^= operators do not apply to immutable instances of frozenset. This is incorrect.
msg306068 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-11-11 00:06
I did understand your report.  IMO your "declaration of incorrectness" is due to an overly strict misreading of what the docs are trying to say and it does not reflect an understanding of what the in-place operators do in-general.   We could write an extra paragraph in the set documentation on this topic; however, I believe it would create confusion where none currently exists (i.e. no reported issues for 15+ years).   Also the discussion is somewhat generic to any type that doesn't specifically implement in-place operators.   In other words, I prefer to leave the doc as-is.
Date User Action Args
2022-04-11 14:58:54adminsetgithub: 76176
2017-11-11 00:06:48rhettingersetstatus: open -> closed
2017-11-11 00:06:21rhettingersetpriority: normal -> low
assignee: rhettinger
resolution: wont fix
2017-11-11 00:06:00rhettingersetassignee: rhettinger -> (no value)
messages: + msg306068
2017-11-10 23:56:52Alexander Mentissetstatus: closed -> open
resolution: rejected -> (no value)
messages: + msg306067
2017-11-10 23:31:04rhettingersetstatus: open -> closed
messages: + msg306060

assignee: docs@python -> rhettinger
resolution: rejected
stage: resolved
2017-11-09 19:08:35serhiy.storchakasetnosy: + rhettinger, serhiy.storchaka

versions: - Python 3.4, Python 3.5
2017-11-09 19:06:10Alexander Mentiscreate