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