|
| 1 | +# Scouting Report: Priority 2 (Issue #10776) |
| 2 | + |
| 3 | +## Issue #10776: `Quantity.__array_ufunc__` should return `NotImplemented` for `Time` instances (and other unknown classes with units) |
| 4 | + |
| 5 | +This issue fits your profile very well as it touches the `astropy/units` subpackage, involves Numpy `ufunc` dispatching (`__array_ufunc__`), and relies on Python object model mechanics (like fallback to `__rmul__`). |
| 6 | + |
| 7 | +### What's broken |
| 8 | +When `astropy.units.Quantity.__array_ufunc__` encounters an object that defines a `unit` attribute (such as `astropy.time.Time` or `TimeDelta`), it assumes it can perform a unit conversion and proceeds to evaluate the Numpy ufunc. If the conversion or evaluation fails, it catches the error (e.g., `TypeError`, `ValueError`, `AttributeError`) and drops into a fallback `except` block. In this block, if the opposing object explicitly does not implement `__array_ufunc__` (or sets it to `None`), `Quantity.__array_ufunc__` incorrectly raises the exception rather than gracefully returning `NotImplemented`. Returning `NotImplemented` is required so that Numpy can fall back to the opposing object's arithmetic methods (such as `__rmul__`), which would otherwise correctly handle the operation. |
| 9 | + |
| 10 | +### Exact files to touch |
| 11 | +- **Source**: `astropy/units/quantity.py` |
| 12 | +- **Test**: `astropy/units/tests/test_quantity_ufuncs.py` |
| 13 | + |
| 14 | +### Step-by-step implementation approach |
| 15 | +1. Open `astropy/units/quantity.py` and locate the `def __array_ufunc__(self, function, method, *inputs, **kwargs):` method. |
| 16 | +2. Scroll to the bottom of the method to find the `except (TypeError, ValueError, AttributeError) as e:` block. |
| 17 | +3. Currently, the block computes an `ignored_ufunc` tuple: |
| 18 | + ```python |
| 19 | + ignored_ufunc = ( |
| 20 | + None, |
| 21 | + np.ndarray.__array_ufunc__, |
| 22 | + type(self).__array_ufunc__, |
| 23 | + ) |
| 24 | + ``` |
| 25 | + and checks if all inputs and outputs have their `__array_ufunc__` in this tuple. If they do, it raises `e` instead of returning `NotImplemented`. |
| 26 | +4. The fix involves realizing that if an unknown object (like `TimeDelta`) doesn't have an `__array_ufunc__` (meaning `getattr(..., "__array_ufunc__", None)` is `None`), we *must* still return `NotImplemented` so its `__rmul__` can take over. We should only raise the exception if *all* operands are known to be strictly `ndarray` or `Quantity` classes (which means no external object is present to handle the fallback). |
| 27 | +5. Modify the condition in the `except` block to check if there are any non-`ndarray` and non-`Quantity` objects present. If there are, return `NotImplemented`; otherwise, `raise e`. |
| 28 | +6. Open `astropy/units/tests/test_quantity_ufuncs.py`. |
| 29 | +7. Add a new test case (e.g., `test_array_ufunc_fallback_for_unknown_unit_class`). Create a mock class that defines `unit`, sets `__array_ufunc__ = None` (or leaves it undefined), and implements `__rmul__`. Verify that multiplying a `Quantity` by an instance of this mock class correctly invokes the mock class's `__rmul__` method and does not raise an exception. |
| 30 | + |
| 31 | +### Acceptance criteria |
| 32 | +- `Quantity.__array_ufunc__` correctly returns `NotImplemented` (rather than raising an exception) when encountering custom objects (like `Time` or custom mock classes) that define a `unit` but have `__array_ufunc__` set to `None`. |
| 33 | +- Numpy falls back to the object's reverse operations (e.g., `__rmul__`) successfully. |
| 34 | +- The Astropy test suite passes. |
| 35 | + |
| 36 | +### What NOT to change |
| 37 | +- Do not modify the core ufunc conversion logic or `quantity_helper` registration framework. |
| 38 | +- Do not change `__array_priority__` values on `Quantity` or `Time`. |
| 39 | +- Only modify the fallback logic inside the `except` block in `__array_ufunc__` to correctly delegate back to Numpy. |
| 40 | + |
| 41 | +### Difficulty (1-5) |
| 42 | +3 |
| 43 | + |
| 44 | +### Priority |
| 45 | +2 |
0 commit comments