Decorator for adding dispatch with the __array_function__ protocol. See NEP-18 for example usage. Parameters ---------- dispatcher : callable or None Function that when called like ``dispatcher(*args, **kwargs)`` with arguments from the NumPy function call returns a
(dispatcher=None, module=None, verify=True,
docs_from_dispatcher=False)
| 106 | |
| 107 | |
| 108 | def array_function_dispatch(dispatcher=None, module=None, verify=True, |
| 109 | docs_from_dispatcher=False): |
| 110 | """Decorator for adding dispatch with the __array_function__ protocol. |
| 111 | |
| 112 | See NEP-18 for example usage. |
| 113 | |
| 114 | Parameters |
| 115 | ---------- |
| 116 | dispatcher : callable or None |
| 117 | Function that when called like ``dispatcher(*args, **kwargs)`` with |
| 118 | arguments from the NumPy function call returns an iterable of |
| 119 | array-like arguments to check for ``__array_function__``. |
| 120 | |
| 121 | If `None`, the first argument is used as the single `like=` argument |
| 122 | and not passed on. A function implementing `like=` must call its |
| 123 | dispatcher with `like` as the first non-keyword argument. |
| 124 | module : str, optional |
| 125 | __module__ attribute to set on new function, e.g., ``module='numpy'``. |
| 126 | By default, module is copied from the decorated function. |
| 127 | verify : bool, optional |
| 128 | If True, verify the that the signature of the dispatcher and decorated |
| 129 | function signatures match exactly: all required and optional arguments |
| 130 | should appear in order with the same names, but the default values for |
| 131 | all optional arguments should be ``None``. Only disable verification |
| 132 | if the dispatcher's signature needs to deviate for some particular |
| 133 | reason, e.g., because the function has a signature like |
| 134 | ``func(*args, **kwargs)``. |
| 135 | docs_from_dispatcher : bool, optional |
| 136 | If True, copy docs from the dispatcher function onto the dispatched |
| 137 | function, rather than from the implementation. This is useful for |
| 138 | functions defined in C, which otherwise don't have docstrings. |
| 139 | |
| 140 | Returns |
| 141 | ------- |
| 142 | Function suitable for decorating the implementation of a NumPy function. |
| 143 | |
| 144 | """ |
| 145 | def decorator(implementation): |
| 146 | if verify: |
| 147 | if dispatcher is not None: |
| 148 | verify_matching_signatures(implementation, dispatcher) |
| 149 | else: |
| 150 | # Using __code__ directly similar to verify_matching_signature |
| 151 | co = implementation.__code__ |
| 152 | last_arg = co.co_argcount + co.co_kwonlyargcount - 1 |
| 153 | last_arg = co.co_varnames[last_arg] |
| 154 | if last_arg != "like" or co.co_kwonlyargcount == 0: |
| 155 | raise RuntimeError( |
| 156 | "__array_function__ expects `like=` to be the last " |
| 157 | "argument and a keyword-only argument. " |
| 158 | f"{implementation} does not seem to comply.") |
| 159 | |
| 160 | if docs_from_dispatcher and dispatcher.__doc__ is not None: |
| 161 | doc = inspect.cleandoc(dispatcher.__doc__) |
| 162 | add_docstring(implementation, doc) |
| 163 | |
| 164 | public_api = _ArrayFunctionDispatcher(dispatcher, implementation) |
| 165 | functools.update_wrapper(public_api, implementation) |
no outgoing calls
searching dependent graphs…