kwargs in method signatures

[andrewgsavage]

Moving this to a new issue from a discussion in #9 (comment)

which functions should have **kwargs in their signatures

I think we should follow the array API standard's lead https://data-apis.org/array-api/draft/purpose_and_scope.html#conformance:

A conforming implementation of the array API standard may provide additional features (e.g., values, objects, properties, data types, functions, and function arguments) beyond those described in this specification.

thus **kwargs does not appear in the standard.

I have mixed feelings on their stance. It makes for easier-to-read docs, but it's actually less correct from a static typing perspective. The Array API doesn't actually have statically typed reference code, only the docs, so our situation is a bit different.

[nstarman]

Ok. This seems hard to get right. I whipped up two quick scenarios but I can't get either of them to pass statically

Common start

from typing import Protocol, runtime_checkable, Any, Self
from array import array

type VT = Any
type UT = dict[str, int]

class Quantity[V]:
    """Protocol for callable objects."""

    def __init__(self, value: V, unit: dict[str, int]) -> None:
        self._value = value
        self._unit = unit

    @property
    def value(self) -> V: return self._value
    def unit(self) -> dict[str, int]: return self._unit

asquantity without kwargs

@runtime_checkable
class AsQuantity[V](Protocol):
    """Protocol for callable objects."""

    def __call__(self, v: V, /, unit: dict[str, int]) -> Quantity[V]:
        """Return a quantity with value `v` and unit `unit`."""
        ...

def asquantity(value: list[int], unit: dict[str, int], *, dtype: type[int]) -> Quantity[list[int]]:
    return Quantity([dtype(v) for v in value], unit)

def call_func[V](func: AsQuantity[V], v: V, unit: dict[str, int], **kwargs: object) -> Quantity[V]:
    return func(v, unit, **kwargs)

_ = call_func(asquantity, [1, 2, 3], {"km": 1}, dtype=int)

asquantity with kwargs

@runtime_checkable
class AsQuantity[V](Protocol):
    """Protocol for callable objects."""

    def __call__(self, v: V, /, unit: dict[str, int], **kwargs: Any) -> Quantity[V]:
        """Return a quantity with value `v` and unit `unit`."""
        ...

def asquantity(value: list[int], /, unit: dict[str, int], *, dtype: object) -> Quantity[list[int]]:
    return Quantity(value, unit)

def call_func[V](func: AsQuantity[V], v: V, unit: dict[str, int], dtype: object) -> Quantity[V]:
    return func(v, unit, dtype=dtype)

_ = call_func(asquantity, [1, 2, 3], {"km": 1}, dtype=int)

The goal is to show that asquantity with kwargs can pass where asquantity without fails (which should be definitionally true).

[lucascolley]

let's see what array-api-typing conjures up before proceeding here