From 32020d719cd396e5c0c266a8438ee2b58dcd1a59 Mon Sep 17 00:00:00 2001 From: Yuki Kobayashi Date: Tue, 4 Mar 2025 05:04:02 +0000 Subject: [PATCH 1/2] gh-113746: Fix `set` and `frozenset` documents Divided the class description into a part about sets and a part about frozensets. Also, cleaned up the explanation of the comparison method. Fixed gh-113746. --- Doc/c-api/set.rst | 2 +- Doc/library/stdtypes.rst | 68 +++++++++++++++++++++++++++------------- Doc/whatsnew/2.3.rst | 8 ++--- 3 files changed, 52 insertions(+), 26 deletions(-) diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index cba823aa027bd6..09c0fb6b9c5f23 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -147,7 +147,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes. Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a - :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~frozenset.discard` + :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard` method, this function does not automatically convert unhashable sets into temporary frozensets. Raise :exc:`SystemError` if *set* is not an instance of :class:`set` or its subtype. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 0564981b52e4f0..ba6df0b26845c5 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -4451,9 +4451,8 @@ of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to t The constructors for both classes work the same: .. class:: set([iterable]) - frozenset([iterable]) - Return a new set or frozenset object whose elements are taken from + Return a new set object whose elements are taken from *iterable*. The elements of a set must be :term:`hashable`. To represent sets of sets, the inner sets must be :class:`frozenset` objects. If *iterable* is not specified, a new empty set is @@ -4465,8 +4464,7 @@ The constructors for both classes work the same: * Use a set comprehension: ``{c for c in 'abracadabra' if c not in 'abc'}`` * Use the type constructor: ``set()``, ``set('foobar')``, ``set(['a', 'b', 'foo'])`` - Instances of :class:`set` and :class:`frozenset` provide the following - operations: + Instances of :class:`set` provide the following operations: .. describe:: len(s) @@ -4485,6 +4483,11 @@ The constructors for both classes work the same: Return ``True`` if the set has no elements in common with *other*. Sets are disjoint if and only if their intersection is the empty set. + .. method:: set == other + + Test whether every element of each set is contained in the other, that is, + ``set <= other and set >= other``. + .. method:: issubset(other) set <= other @@ -4537,17 +4540,6 @@ The constructors for both classes work the same: sets. This precludes error-prone constructions like ``set('abc') & 'cbs'`` in favor of the more readable ``set('abc').intersection('cbs')``. - Both :class:`set` and :class:`frozenset` support set to set comparisons. Two - sets are equal if and only if every element of each set is contained in the - other (each is a subset of the other). A set is less than another set if and - only if the first set is a proper subset of the second set (is a subset, but - is not equal). A set is greater than another set if and only if the first set - is a proper superset of the second set (is a superset, but is not equal). - - Instances of :class:`set` are compared to instances of :class:`frozenset` - based on their members. For example, ``set('abc') == frozenset('abc')`` - returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``. - The subset and equality comparisons do not generalize to a total ordering function. For example, any two nonempty disjoint sets are not equal and are not subsets of each other, so *all* of the following return ``False``: ``a= other + set > other + union(*others) + set | other | ... + intersection(*others) + set & other & ... + new set with elements common to the set and all others. + difference(*others) + set - other - ... + symmetric_difference(other) + set ^ other + copy() + + The notes about these methods mentioned in :class:`set` also apply + to :class:`frozenset`. In addition, Note that: + + * Instances of :class:`set` are compared to instances of :class:`frozenset` + based on their members. For example, ``set('abc') == frozenset('abc')`` + returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``. + + * Binary operations that mix :class:`set` instances with :class:`frozenset` + return the type of the first operand. For example: ``frozenset('ab') | + set('bc')`` returns an instance of :class:`frozenset`. + .. _typesmapping: diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index b7e4e73f4ce4aa..caccfc030759c1 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -63,10 +63,10 @@ Here's a simple example:: Set([1, 2, 5]) >>> -The union and intersection of sets can be computed with the :meth:`~frozenset.union` and -:meth:`~frozenset.intersection` methods; an alternative notation uses the bitwise operators +The union and intersection of sets can be computed with the :meth:`~set.union` and +:meth:`~set.intersection` methods; an alternative notation uses the bitwise operators ``&`` and ``|``. Mutable sets also have in-place versions of these methods, -:meth:`!union_update` and :meth:`~frozenset.intersection_update`. :: +:meth:`!union_update` and :meth:`~set.intersection_update`. :: >>> S1 = sets.Set([1,2,3]) >>> S2 = sets.Set([4,5,6]) @@ -87,7 +87,7 @@ It's also possible to take the symmetric difference of two sets. This is the set of all elements in the union that aren't in the intersection. Another way of putting it is that the symmetric difference contains all elements that are in exactly one set. Again, there's an alternative notation (``^``), and an -in-place version with the ungainly name :meth:`~frozenset.symmetric_difference_update`. :: +in-place version with the ungainly name :meth:`~set.symmetric_difference_update`. :: >>> S1 = sets.Set([1,2,3,4]) >>> S2 = sets.Set([3,4,5,6]) From 832ea3cc8f9983b8b64136dcb74adeb7dc4ffc5a Mon Sep 17 00:00:00 2001 From: Yuki Kobayashi Date: Wed, 5 Mar 2025 05:21:37 +0000 Subject: [PATCH 2/2] Update `Doc/library/stdtypes.rst` --- Doc/library/stdtypes.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index ba6df0b26845c5..bf2031fb16f156 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -4483,11 +4483,6 @@ The constructors for both classes work the same: Return ``True`` if the set has no elements in common with *other*. Sets are disjoint if and only if their intersection is the empty set. - .. method:: set == other - - Test whether every element of each set is contained in the other, that is, - ``set <= other and set >= other``. - .. method:: issubset(other) set <= other @@ -4540,6 +4535,13 @@ The constructors for both classes work the same: sets. This precludes error-prone constructions like ``set('abc') & 'cbs'`` in favor of the more readable ``set('abc').intersection('cbs')``. + Both :class:`set` and :class:`frozenset` support set to set comparisons. Two + sets are equal if and only if every element of each set is contained in the + other (each is a subset of the other). A set is less than another set if and + only if the first set is a proper subset of the second set (is a subset, but + is not equal). A set is greater than another set if and only if the first set + is a proper superset of the second set (is a superset, but is not equal). + The subset and equality comparisons do not generalize to a total ordering function. For example, any two nonempty disjoint sets are not equal and are not subsets of each other, so *all* of the following return ``False``: ``a