From 3335042218bce35cc97c9205dd094601b19d2130 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Fri, 19 May 2023 14:09:02 -0500 Subject: [PATCH] ubuiltins: add set class Add type stubs and docs for builtin `set` type. Issue: https://github.com/pybricks/support/issues/402 --- CHANGELOG.md | 3 + doc/main/micropython/builtins.rst | 4 + src/ubuiltins/__init__.py | 205 ++++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 817139a5..906a3f83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ - Changed the beta feature for using the hub's gyro. Gyro control can now be toggled using `use_gyro` instead of using a separate `GyroDriveBase` class. +## Added +- Added `set` to `ubuiltins` module. + ## 3.3.0b5 - 2023-05-16 ### Added diff --git a/doc/main/micropython/builtins.rst b/doc/main/micropython/builtins.rst index 3ce655f4..8dd77104 100644 --- a/doc/main/micropython/builtins.rst +++ b/doc/main/micropython/builtins.rst @@ -72,6 +72,10 @@ Sequences .. pybricks-requirements:: stm32-extra +.. autoclass:: ubuiltins.set + +.. pybricks-requirements:: stm32-extra + .. autoclass:: ubuiltins.slice .. pybricks-requirements:: diff --git a/src/ubuiltins/__init__.py b/src/ubuiltins/__init__.py index f88c89ed..d2cd104d 100644 --- a/src/ubuiltins/__init__.py +++ b/src/ubuiltins/__init__.py @@ -23,6 +23,7 @@ Any, Callable, Dict, + Hashable, Iterable, Iterator, List, @@ -33,6 +34,7 @@ SupportsFloat, SupportsInt, Tuple, + TypeVar, Union, overload, ) @@ -55,6 +57,8 @@ _str = str _type = type +_Self = TypeVar("_Self") + # Functions and types @@ -1084,6 +1088,207 @@ def round(*args): """ +class set: + @overload + def __init__(self) -> None: + ... + + @overload + def __init__(self, iterable: Iterable[Hashable]) -> None: + ... + + def __init__(self, *args) -> None: + """ + set() + set(iterable) + + Creates a new set. + + With no arguments, creates a new empty set, otherwise creates a set + containing unique items of *iterable*. + + Sets can also be created using a set literal:: + + my_set = {1, 2, 3} + + Elements of a set must be hashable. There are only a few types, like + :class:`list` that aren't hashable. + + Args: + iterable: An iterable of hashable objects. + """ + + def copy(self: _Self) -> _Self: + """ + copy() -> set + + Returns a shallow copy of the set. + + Returns: + A new set. + """ + + def difference(self: _Self, *others: set) -> _Self: + """ + difference(other1, other2, ...) -> set + + Returns a new set with elements that are not in any of the other sets. + + The difference can also be computed using the ``-`` operator:: + + diff = s - other + + Args: + others: 1 or more other sets. + + Returns: + A new set. + """ + + def intersection(self: _Self, *others: set) -> _Self: + """ + intersection(other1, other2, ...) -> set + + Returns a new set with elements that are common between this set and + all other sets. + + The intersection can also be computed using the ``&`` operator:: + + intersect = s & other + + Args: + others: 1 or more other sets. + + Returns: + A new set. + """ + + def isdisjoint(self, other: set) -> bool: + """ + isdisjoint(other) -> bool + + Tests if a set and *other* have no elements in common. + + Args: + other: Another set. + + Returns: + ``True`` if this set has no elements in common with *other*, + otherwise ``False``. + """ + + def issubset(self, other: set) -> bool: + """ + issubset(other) -> bool + + Tests if a set is a subset of *other*. + + The test can also be performed using using the ``<=`` operator:: + + if s <= other: + # s is subset of other + ... + + Args: + other: Another set. + + Returns: + ``True`` if this set is a subset of *other*, otherwise ``False``. + """ + + def issuperset(self, other: set) -> bool: + """ + issuperset(other) -> bool + + Tests if a set is a superset of *other*. + + The test can also be performed using using the ``>=`` operator:: + + if s >= other: + # s is superset of other + ... + + Args: + other: Another set. + + Returns: + ``True`` if this set is a superset of *other*, otherwise ``False``. + """ + + def symmetric_difference(self: _Self, other: set) -> _Self: + """ + symmetric_difference(other) -> bool + + Returns a new set with elements in one set or the other but not in both. + + The symmetric difference can also be computed using the ``^`` operator:: + + diff = s ^ other + + Args: + other: Another set. + + Returns: + A new set. + """ + + def union(self: _Self, *others: set) -> _Self: + """ + union(other1, other2, ...) -> set + + Returns a new set with elements from this set and all other sets. + + The union can also be computed using the ``|`` operator:: + + u = s | other + + Args: + others: 1 or more other sets. + + Returns: + A new set. + """ + + def __contains__(self, item: Hashable) -> bool: + ... + + def __len__(self) -> int: + ... + + def __bool__(self) -> bool: + ... + + def __gt__(self, other: set) -> bool: + ... + + def __lt__(self, other: set) -> bool: + ... + + def __ge__(self, other: set) -> bool: + ... + + def __le__(self, other: set) -> bool: + ... + + def __eq__(self, other: set) -> bool: + ... + + def __ne__(self, other: set) -> bool: + ... + + def __sub__(self: _Self, other: set) -> _Self: + ... + + def __and__(self: _Self, other: set) -> _Self: + ... + + def __or__(self: _Self, other: set) -> _Self: + ... + + def __xor__(self: _Self, other: set) -> _Self: + ... + + def setattr(object: Any, name: _str, value: Any) -> None: """ setattr(object, name, value)