[BUG] Documented signatures of `mx.add` and 27 other ops omit the keyword-only `*`, so `stream` (and `equal_nan`) cannot be passed positionally as documented

Open Beginner friendly
  • Is something wrong?
#4,814 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

@Redempt1onzzZZ is already working on this.

Since Nov 2, 2026.

  • #4816 by @Redempt1onzzZZ — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
cpp, python
Domain
developer-experience, machine-learning

Research direction

Read python/src/ops.cpp, focusing on the listed nb::sig("def ...") strings and the corresponding nb::kw_only() bindings. Update the signatures so the documentation includes * before stream for the affected operations and before equal_nan for array_equal. Verify with each operation's __doc__ and the positional-call examples; done means the displayed signatures match the accepted call forms.

Written by the indexing model from the issue text.

Description

☑️ I understand it is strictly prohibited to use AI to write issues.

Describe the bug
The signatures shown in the docs (and in __doc__) of several ops list stream as a regular positional parameter, e.g.
add(a: scalar | array, b: scalar | array, stream: StreamOrDevice = None) -> array.
The bindings declare nb::kw_only() before stream, so passing it positionally raises TypeError. The same signature string is printed in the TypeError message, so the error points to a call form that does not work. array_equal has the same problem for equal_nan.

To Reproduce

Include code snippet

import mlx.core as mx

a, b = mx.array([1, 2]), mx.array([3, 4])
print(mx.add.__doc__.splitlines()[0])

print(mx.add(a, b, stream=mx.cpu))   # works
mx.add(a, b, mx.cpu)                 # TypeError, although the signature above allows it

Output:

add(a: scalar | array, b: scalar | array, stream: StreamOrDevice = None) -> array
array([4, 6], dtype=int32)
TypeError: add(): incompatible function arguments. The following argument types are supported:
    1. add(a: scalar | array, b: scalar | array, stream: StreamOrDevice = None) -> array

Invoked with types: mlx.core.array, mlx.core.array, mlx.core.DeviceType

Same for equal_nan:

import mlx.core as mx
a, b = mx.array([1, 2]), mx.array([3, 4])
mx.array_equal(a, b, True)           # equal_nan passed positionally

Output:

TypeError: array_equal(): incompatible function arguments. The following argument types are supported:
    1. array_equal(a: scalar | array, b: scalar | array, equal_nan: bool = False, stream: StreamOrDevice = None) -> array

Invoked with types: mlx.core.array, mlx.core.array, bool

Expected behavior
The documented signature matches the binding, i.e. add(a, b, *, stream=None) (as already done for e.g. flatten, squeeze, expand_dims), or stream is accepted positionally.

Desktop (please complete the following information):

  • OS Version: macOS 26.6.2 (arm64)
  • Version: mlx 0.32.4

Additional context
The hand-written nb::sig("def ...") strings in python/src/ops.cpp lack the * for these 28 functions, while the bindings use nb::kw_only(): add, subtract, multiply, divide, divmod, floor_divide, remainder, equal, not_equal, less, less_equal, greater, greater_equal, array_equal, bitwise_and, bitwise_or, bitwise_xor, left_shift, right_shift, bitwise_invert, isnan, isinf, isfinite, isposinf, isneginf, round, view, hadamard_transform.

Each of them raises TypeError when stream (or equal_nan) is passed positionally. A similar mismatch between nb::sig and the binding was fixed in #3950 (cholesky_inv). Adding * before stream (before equal_nan for array_equal) in these strings should fix it; I can open a PR.

Dominant language
C++
Stars
29k
Forks
2.4k
Avg merge
3d 10h
Merged PRs (30d)
115

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ml-explore/mlx

All issues in ml-explore/mlx

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.