[issue31995] Set operations documentation error
New submission from Alexander Mentis asmentis@gmail.com:
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.
---------- assignee: docs@python components: Documentation messages: 305981 nosy: Alexander Mentis, docs@python priority: normal severity: normal status: open title: Set operations documentation error versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue31995 _______________________________________
Change by Serhiy Storchaka storchaka+cpython@gmail.com:
---------- nosy: +rhettinger, serhiy.storchaka versions: -Python 3.4, Python 3.5
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue31995 _______________________________________
Raymond Hettinger raymond.hettinger@gmail.com added the comment:
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.
---------- assignee: docs@python -> rhettinger resolution: -> rejected stage: -> resolved status: open -> closed
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue31995 _______________________________________
Alexander Mentis asmentis@gmail.com added the comment:
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.
---------- resolution: rejected -> status: closed -> open
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue31995 _______________________________________
Raymond Hettinger raymond.hettinger@gmail.com added the comment:
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.
---------- assignee: rhettinger ->
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue31995 _______________________________________
Change by Raymond Hettinger raymond.hettinger@gmail.com:
---------- assignee: -> rhettinger priority: normal -> low resolution: -> wont fix
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue31995 _______________________________________
Change by Raymond Hettinger raymond.hettinger@gmail.com:
---------- status: open -> closed
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue31995 _______________________________________
participants (3)
-
Alexander Mentis -
Raymond Hettinger
-
Serhiy Storchaka