Materials for range membership Q&A (#402)

Author: gahjelle

python-range-membership-test/README.md

@@ -0,0 +1,25 @@
+# Why Are Membership Tests So Fast for `range()` in Python?
+
+This repository holds the code for Real Python's [Why Are Membership Tests So Fast for `range()` in Python?](https://realpython.com/python-range-membership-test/) tutorial.
+
+In [`range_tools.py`](range_tools.py), you'll find an implementation of a custom `Range` class that behaves similarly to the built-in `range()`:
+
+```pycon
+>>> from range_tools import Range
+
+>>> Range(start=1, stop=10, step=2)
+Range(start=1, stop=10, step=2)
+
+>>> list(Range(start=1, stop=10, step=2))
+[1, 3, 5, 7, 9]
+```
+
+While `range()` is implemented in C, you can look at the source code of `Range` to get an idea of how `range()` works under the hood.
+
+## Author
+
+- **Geir Arne Hjelle**, E-mail: [[email protected]]([email protected])
+
+## License
+
+Distributed under the MIT license. See [`LICENSE`](../LICENSE) for more information.

python-range-membership-test/range_tools.py

@@ -0,0 +1,69 @@
+import math
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Range:
+    start: int
+    stop: int
+    step: int = 1
+
+    def __post_init__(self):
+        """Validate parameters."""
+        if not isinstance(self.start, int):
+            raise ValueError("'start' must be an integer")
+        if not isinstance(self.stop, int):
+            raise ValueError("'stop' must be an integer")
+        if not isinstance(self.step, int) or self.step <= 0:
+            raise ValueError("'step' must be a positive integer")
+
+    def __iter__(self):
+        """Create an iterator based on the range."""
+        return _RangeIterator(self.start, self.stop, self.step)
+
+    def __contains__(self, element):
+        """Check if element is a member of the range."""
+        return (
+            self.start <= element < self.stop
+            and (element - self.start) % self.step == 0
+        )
+
+    def __len__(self):
+        """Calculate the number of elements in the range."""
+        if self.stop <= self.start:
+            return 0
+        return math.ceil((self.stop - self.start) / self.step)
+
+    def __getitem__(self, index):
+        """Get an element in the range based on its index."""
+        if index < 0 or index >= len(self):
+            raise IndexError(f"range index out of range: {index}")
+        return self.start + index * self.step
+
+    def count(self, element):
+        """Count number of occurences of element in range."""
+        return 1 if element in self else 0
+
+    def index(self, element):
+        """Calculate index of element in range."""
+        if element not in self:
+            raise ValueError(f"{element} not in range")
+        return (element - self.start) // self.step
+
+
+@dataclass
+class _RangeIterator:
+    start: int
+    stop: int
+    step: int
+    _state: int | None = field(default=None, init=False)
+
+    def __next__(self):
+        """Calculate the next element in the iteration."""
+        if self._state is None:
+            self._state = self.start
+        else:
+            self._state += self.step
+        if self._state >= self.stop:
+            raise StopIteration
+        return self._state