From 49da2ce1ccfc496242dadf52336569317c2b221d Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Sun, 19 Jan 2025 19:46:36 +0000 Subject: [PATCH] DOC: contributor docs for delegation --- docs/contributing.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 221021d..474fdd4 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,11 +6,14 @@ converting code to consume the standard. Thanks to [all contributors](contributors.md) so far! -## How to contribute a function +## How to contribute a new function - [Open an issue](https://github.com/data-apis/array-api-extra/issues/new) to - propose the new function. -- Add the implementation of your function to `src/array_api_extra/_funcs.py`. + propose the new function. You may want to wait for initial feedback on the + issue before diving into an implementation. Feel free to skip this step if + there is already an open issue for the function. +- Add the implementation of your function to + `src/array_api_extra/_lib/_funcs.py`. - Ensure that your function includes type annotations and a [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html). - Add your function to `__all__` at the top of the file. @@ -20,6 +23,33 @@ Thanks to [all contributors](contributors.md) so far! - Add your function to `docs/api-reference.md`. - [Make a PR!](https://github.com/data-apis/array-api-extra/pulls) +## How to add delegation to a function + +See [the tracker for adding delegation][delegation-tracker]. + +[delegation-tracker]: https://github.com/data-apis/array-api-extra/issues/100 + +- If you would like to discuss the task before diving into the implementation, + click on the three dots next to the function on the tracker issue, and choose + "Convert to sub-issue". +- Create a function in `src/array_api_extra/_delegation.py` with a signature + matching the function in `src/array_api_extra/_lib/_funcs.py`, and move the + docstring to the new function. Leave a one-line docstring in `_funcs.py`, + pointing to `_delegation.py` to see the full docstring. +- Also move the initial `array_namespace` call and any input validation over to + the new function. +- Add delegation to backends using the `if _delegate` pattern. See + `src/array_api_extra/_lib/_backends.py` for the full list of backends we have + worked with so far. +- After all delegation layers, return the result from the implementation in + `_funcs`. +- Simplify the signature in `_funcs.py` to remove impossible arguments now that + it is only called internally via `_delegation`. For example, the `xp` + parameter can be changed from type `ModuleType | None` to `ModuleType`. +- Don't worry if you are not sure how to do some of the above steps or think you + might have done something wrong - + [make a PR!](https://github.com/data-apis/array-api-extra/pulls) + ## Development workflow If you are an experienced contributor to Python packages, feel free to develop