Materials for Range tutorial

python-range/README.md

@@ -0,0 +1,48 @@
+# Python `range()`: Represent Numerical Ranges
+
+This repository holds the code for Real Python's [Python `range()`: Represent Numerical Ranges](https://realpython.com/python-range/) tutorial.
+
+## PiDigits
+
+The file [`pi_digits.py`](pi_digits.py) shows the implementation of `PiDigits` which is an integer-like type that can be used as arguments to `range()`:
+
+```python
+>>> from pi_digits import PiDigits
+
+>>> PiDigits(3)
+PiDigits(num_digits=3)
+
+>>> int(PiDigits(3))
+314
+
+>>> range(PiDigits(3))
+range(0, 314)
+```
+
+See [the tutorial](https://realpython.com/python-range/#create-a-range-using-integer-like-parameters) for more details.
+
+## FloatRange
+
+In [`float_range.py`](float_range.py), you'll find an implementation of a custom `FloatRange` class that behaves similarly to the built-in `range()` except that its arguments can be floating point numbers:
+
+```pycon
+>>> from float_range import FloatRange
+
+>>> FloatRange(1, 10, 1.2)
+FloatRange(start=1, stop=10, step=1.2)
+
+>>> list(FloatRange(1, 10, 1.2))
+[1.0, 2.2, 3.4, 4.6, 5.8, 7.0, 8.2, 9.4]
+```
+
+The built-in `range()` is implemented in C. However, you can look at the source code of `FloatRange` to get an idea of how `range()` works under the hood.
+
+If you need to work with floating-point ranges, you can use `FloatRange`. However, NumPy's [`arange()`](https://realpython.com/how-to-use-numpy-arange/) will give you better performance, and is probably a better option overall.
+
+## Author
+
+- **Geir Arne Hjelle**, E-mail: [[email protected]]([email protected])
+
+## License
+
+Distributed under the MIT license. See [`LICENSE`](../LICENSE) for more information.

python-range/float_range.py

@@ -0,0 +1,113 @@
+from dataclasses import dataclass, field
+from math import ceil, isclose
+
+
+@dataclass
+class FloatRange:
+    """Range of numbers that allows floating point numbers."""
+
+    start: float | int
+    stop: float | int | None = None
+    step: float | int = 1.0
+
+    def __post_init__(self):
+        """Validate parameters."""
+        # Only one argument is given
+        if self.stop is None:
+            self.stop = self.start
+            self.start = 0
+
+        # Validate that all arguments are ints or floats
+        if not isinstance(self.start, float | int):
+            raise ValueError("'start' must be a floating point number")
+        if not isinstance(self.stop, float | int):
+            raise ValueError("'stop' must be a floating point number")
+        if not isinstance(self.step, float | int) or isclose(self.step, 0):
+            raise ValueError("'step' must be a non-zero floating point number")
+
+    def __iter__(self):
+        """Create an iterator based on the range."""
+        return _FloatRangeIterator(self.start, self.stop, self.step)
+
+    def __contains__(self, element):
+        """Check if element is a member of the range.
+
+        Use isclose() to handle floats.
+        """
+        offset = (element - self.start) % self.step
+        if self.step > 0:
+            return self.start <= element < self.stop and (
+                isclose(offset, 0) or isclose(offset, self.step)
+            )
+        else:
+            return self.stop < element <= self.start and (
+                isclose(offset, 0) or isclose(offset, self.step)
+            )
+
+    def __len__(self):
+        """Calculate the number of elements in the range."""
+        if any(
+            [
+                self.step > 0 and self.stop <= self.start,
+                self.step < 0 and self.stop >= self.start,
+            ]
+        ):
+            return 0
+        return 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 __reversed__(self):
+        """Create a FloatRange with elements in the reverse order.
+
+        Any number 0 < x < self.step can be used as offset. Use 0.1 when
+        possible as an "esthetically nice" offset.
+        """
+        cls = type(self)
+        offset = (1 if self.step > 0 else -1) * min(0.1, abs(self.step) / 2)
+        return cls(
+            (self.stop - self.step) + (self.start - self.stop) % self.step,
+            self.start - offset,
+            -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} is not in range")
+        return round((element - self.start) / self.step)
+
+
+@dataclass
+class _FloatRangeIterator:
+    """Non-public iterator. Should only be initialized by FloatRange."""
+
+    start: float | int
+    stop: float | int
+    step: float | int
+    _num_steps: int = field(default=0, init=False)
+
+    def __iter__(self):
+        """Initialize the iterator."""
+        return self
+
+    def __next__(self):
+        """Calculate the next element in the iteration."""
+        element = self.start + self._num_steps * self.step
+        if any(
+            [
+                self.step > 0 and element >= self.stop,
+                self.step < 0 and element <= self.stop,
+            ]
+        ):
+            raise StopIteration
+        self._num_steps += 1
+        return element

python-range/pi_digits.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class PiDigits:
+    num_digits: int
+
+    def __index__(self):
+        return int("3141592653589793238462643383279"[: self.num_digits])