Set operations documentation error

[a582d404-9f5b-4bfc-9517-0a25fb4837e4]

BPO	31995
Nosy	@rhettinger, @serhiy-storchaka

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = 'https://github.com/rhettinger' closed_at = created_at = labels = ['3.7', 'docs'] title = 'Set operations documentation error' updated_at = user = 'https://bugs.python.org/AlexanderMentis' ``` bugs.python.org fields: ```python activity = actor = 'rhettinger' assignee = 'rhettinger' closed = True closed_date = closer = 'rhettinger' components = ['Documentation'] creation = creator = 'Alexander Mentis' dependencies = [] files = [] hgrepos = [] issue_num = 31995 keywords = [] message_count = 4.0 messages = ['305981', '306060', '306067', '306068'] nosy_count = 4.0 nosy_names = ['rhettinger', 'docs@python', 'serhiy.storchaka', 'Alexander Mentis'] pr_nums = [] priority = 'low' resolution = 'wont fix' stage = 'resolved' status = 'closed' superseder = None type = None url = 'https://bugs.python.org/issue31995' versions = ['Python 2.7', 'Python 3.6', 'Python 3.7'] ```

[a582d404-9f5b-4bfc-9517-0a25fb4837e4]

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.

[rhettinger]

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.

[a582d404-9f5b-4bfc-9517-0a25fb4837e4]

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.

[rhettinger]

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.