"""
An immutable set view.
"""
from __future__ import print_function, absolute_import
try:
from collections.abc import Set
except ImportError:
# Python 2
from collections import Set
__all__ = ['SetView']
[docs]class SetView(Set):
# pylint: disable=line-too-long
"""
An immutable set view.
Derived from :class:`~py3:collections.abc.Set`.
This class provides an immutable view on a possibly mutable set object.
The set object must be an instance of :class:`~py3:collections.abc.Set`.
This can be used for example when a class maintains a set that should be
made available to users of the class without allowing them to modify the
set.
In the description of this class, the term 'view' always refers to the
:class:`SetView` object, and the term 'set' or 'original set' refers to the
set object the view is based on.
The :class:`SetView` class supports the complete behavior of Python class
:class:`set`, except for any methods that would modify the set.
Note that the non-modifying methods of class :class:`set` are a superset of
the methods defined for the abstract class :class:`~py3:collections.abc.Set`
(the methods are listed in the table at the top of the linked page).
The view is "live": Since the view class delegates all operations to the
original set, any modification of the original set object will be visible
in the view object.
Note that only the view object is immutable, not necessarily its items.
So if the items in the original set are mutable objects, they can be
modified through the view.
Note that in Python, augmented assignment (e.g. `+=` is not guaranteed to
modify the left hand object in place, but can result in a new object.
For details, see
`object.__iadd__() <https://docs.python.org/3/reference/datamodel.html#object.__iadd__>`_.
The `+=` operator on a left hand object that is a SetView object results
in a new SetView object on a new set object.
""" # noqa: E501
# pylint: enable=line-too-long
def __init__(self, a_set):
"""
Parameters:
a_set (:class:`~py3:collections.abc.Set`):
The original set.
If this object is a SetView, its original set is used.
"""
if not isinstance(a_set, Set):
raise TypeError(
"The a_set parameter must be a Set, but is: {}".
format(type(a_set)))
if isinstance(a_set, SetView):
a_set = a_set._set
self._set = a_set
[docs] def __repr__(self):
"""
``repr(self)``:
Return a string representation of the view suitable for debugging.
The original set is represented using its ``repr()`` representation.
"""
return "{0.__class__.__name__}({1!r})".format(self, self._set)
[docs] def __len__(self):
"""
``len(self)``:
Return the number of items in the set.
The return value is the number of items in the original set.
"""
return len(self._set)
[docs] def __contains__(self, value):
"""
``value in self``:
Return a boolean indicating whether the set contains a value.
The return value indicates whether the original set contains an item
that is equal to the value.
"""
return value in self._set
[docs] def __iter__(self):
"""
``iter(self) ...``:
Return an iterator through the set.
The returned iterator yields the items in the original set in its
iteration order.
"""
return iter(self._set)
[docs] def __and__(self, other):
"""
``self & other``:
Return a new view on the intersection of the set and the other set.
The returned :class:`SetView` object is a view on a new set object of
the type of the left hand operand that contains the items that are in
the original set of the left hand operand and in the other set
(or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
new_set = self._set & other_set
return SetView(new_set)
[docs] def __rand__(self, other):
"""
``other & self``:
Return a new view on the intersection of the set and the other set.
This method is a fallback and is called only if the left operand does
not support the operation.
The returned :class:`SetView` object is a view on a new set object of
the type of the right hand operand that contains the items that are in
the original set of the right hand operand and in the other set
(or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
return self.__and__(other)
[docs] def intersection(self, *others):
"""
Return a new view on the intersection of the set and the other
iterables.
The returned :class:`SetView` object is a view on a new set object of
the type of the original set that contains the items that are in the
original set and in the other iterables (or in case of SetView objects,
their original sets).
The other objects must be :term:`iterables <py3:iterable>`.
The set and the other iterables are not changed.
Raises:
TypeError: The other objects are not all iterables.
"""
# pylint: disable=protected-access
other_sets = [other._set if isinstance(other, SetView) else other
for other in others]
new_set = self._set.intersection(*other_sets)
return SetView(new_set)
[docs] def __or__(self, other):
"""
``self | other``:
Return a new view on the union of the set and the other set.
The returned :class:`SetView` object is a view on a new set object of
the type of the left hand operand that contains all the (unique) items
from the original set of the left hand operand and the other set
(or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
new_set = self._set | other_set
return SetView(new_set)
[docs] def __ror__(self, other):
"""
``other | self``:
Return a new view on the union of the set and the other set.
This method is a fallback and is called only if the left operand does
not support the operation.
The returned :class:`SetView` object is a view on a new set object of
the type of the right hand operand that contains all the (unique) items
from the original set of the right hand operand and the other set
(or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
return self.__or__(other)
[docs] def union(self, *others):
"""
Return a new view on the union of the set and the other iterables.
The returned :class:`SetView` object is a view on a new set object of
the type of the original set that contains all the (unique) items from
the original set and the other iterables (or in case of SetView objects,
their original sets).
The other objects must be :term:`iterables <py3:iterable>`.
The set and the other iterables are not changed.
Raises:
TypeError: The other objects are not all iterables.
"""
# pylint: disable=protected-access
other_sets = [other._set if isinstance(other, SetView) else other
for other in others]
new_set = self._set.union(*other_sets)
return SetView(new_set)
[docs] def __sub__(self, other):
"""
``self - other``:
Return a new view on the difference of the set and the other set.
The returned :class:`SetView` object is a view on a new set object of
the type of the left hand operand that contains the items that are in
the original set of the left hand operand but not in the other set
(or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
new_set = self._set - other_set
return SetView(new_set)
[docs] def __rsub__(self, other):
"""
``other - self``:
Return a new view on the difference of the other set and the set.
This method is a fallback and is called only if the left operand does
not support the operation.
The returned :class:`SetView` object is a view on a new set object of
the type of the left hand operand that contains the items that are in
the other set (or in case of a SetView, its original set) but not in
the original set of the left hand operand.
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
new_set = set()
for item in other_set:
if item not in self._set:
new_set.add(item)
return SetView(new_set)
[docs] def difference(self, *others):
"""
Return a new view on the difference of the set and the other
iterables.
The returned :class:`SetView` object is a view on a new set object of
the type of the original set that contains the items that are in the
original set but not in any of the other iterables (or in case of
SetView objects, their original sets).
The other objects must be :term:`iterables <py3:iterable>`.
The set and the other iterables are not changed.
Raises:
TypeError: The other objects are not all iterables.
"""
# pylint: disable=protected-access
other_sets = [other._set if isinstance(other, SetView) else other
for other in others]
new_set = self._set.difference(*other_sets)
return SetView(new_set)
[docs] def __xor__(self, other):
"""
``self ^ other``:
Return a new view on the symmetric difference of the set and the other
set.
The returned :class:`SetView` object is a view on a new set object of
the type of the left hand operand that contains the items that are in
either the original set of the left hand operand or in the other set
(or in case of a SetView, its original set), but not in both.
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
new_set = self._set ^ other_set
return SetView(new_set)
[docs] def __rxor__(self, other):
"""
``other ^ self``:
Return a new view on the symmetric difference of the set and the other
set.
This method is a fallback and is called only if the left operand does
not support the operation.
The returned :class:`SetView` object is a view on a new set object of
the type of the right hand operand that contains the items that are in
either the original set of the right hand operand or in the other set
(or in case of a SetView, its original set), but not in both.
The other object must be a :class:`set` or :class:`SetView`.
The set and the other set are not changed.
Raises:
TypeError: The other object is not a set or SetView.
"""
return self.__xor__(other)
[docs] def symmetric_difference(self, other):
"""
Return a new view on the symmetric difference of the set and the other
iterable.
The returned :class:`SetView` object is a view on a new set object of
the type of the original set that contains the items that are in either
the original set or in the other iterable (or in case of a SetView, its
original set), but not in both.
The other object must be an :term:`py3:iterable`.
The set and the other iterable are not changed.
Raises:
TypeError: The other object is not an iterable.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
new_set = self._set.symmetric_difference(other_set)
return SetView(new_set)
[docs] def __eq__(self, other):
"""
``self == other``:
Return a boolean indicating whether the set is equal to the other set.
The return value indicates whether the items in the original set are
equal to the items in the other set (or in case of a SetView, its
original set).
The other object must be a :class:`set` or :class:`SetView`.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set == other_set
[docs] def __ne__(self, other):
"""
``self != other``:
Return a boolean indicating whether the set is not equal to the other
set.
The return value indicates whether the items in the original set are
not equal to the items in the other set (or in case of a SetView, its
original set).
The other object must be a :class:`set` or :class:`SetView`.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set != other_set
[docs] def __gt__(self, other):
"""
``self > other``:
Return a boolean indicating whether the set is a proper superset of the
other set.
The return value indicates whether the original set is a proper
superset of the other set (or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set > other_set
[docs] def __lt__(self, other):
"""
``self < other``:
Return a boolean indicating whether the set is a proper subset of the
other set.
The return value indicates whether the original set is a proper
subset of the other set (or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set < other_set
[docs] def __ge__(self, other):
"""
``self >= other``:
Return a boolean indicating whether the set is an inclusive superset
of the other set.
The return value indicates whether every item in the other set
(or in case of a SetView, its original set) is in the original set.
The other object must be a :class:`set` or :class:`SetView`.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set >= other_set
[docs] def issuperset(self, other):
"""
Return a boolean indicating whether the set is an inclusive superset
of the other iterable.
The return value indicates whether every item in the other iterable
(or in case of a SetView, its original set) is in the original set.
The other object must be an :term:`py3:iterable`.
Raises:
TypeError: The other object is not an iterable.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set.issuperset(other_set)
[docs] def __le__(self, other):
"""
``self <= other``:
Return a boolean indicating whether the set is an inclusive subset
of the other set.
The return value indicates whether every item in the original
set is in the other set (or in case of a SetView, its original set).
The other object must be a :class:`set` or :class:`SetView`.
Raises:
TypeError: The other object is not a set or SetView.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set <= other_set
[docs] def issubset(self, other):
"""
Return a boolean indicating whether the set is an inclusive subset
of the other iterable.
The return value indicates whether every item in the original set
is in the other iterable (or in case of a SetView, its original set).
The other object must be an :term:`py3:iterable`.
Raises:
TypeError: The other object is not an iterable.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set.issubset(other_set)
[docs] def isdisjoint(self, other):
"""
Return a boolean indicating whether the set does not intersect with
the other iterable.
The return value indicates whether the original set has no items in
common with the other iterable (or in case of a SetView, its original
set).
The other object must be an :term:`py3:iterable`.
Raises:
TypeError: The other object is not an iterable.
"""
# pylint: disable=protected-access
other_set = other._set if isinstance(other, SetView) else other
return self._set.isdisjoint(other_set)
[docs] def copy(self):
"""
Return a new view on a shallow copy of the set.
The returned :class:`SetView` object is a new view object on a set
object of the type of the original set.
If the set type is immutable, the returned set object may be the
original set object. If the set type is mutable, the returned set is
a new set object that is a shallow copy of the original set object.
"""
org_class = self._set.__class__
new_set = org_class(self._set) # May be same object if immutable
return SetView(new_set)