Skip to content

Commit dd1ad48

Browse files
committed
Add a section explaining the scope of the library
1 parent 2783a15 commit dd1ad48

File tree

2 files changed

+60
-0
lines changed

2 files changed

+60
-0
lines changed

Diff for: docs/index.md

+55
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,61 @@ references the name "array_api_compat").
120120

121121
Alternatively, the library may be installed as dependency on PyPI.
122122

123+
(scope)=
124+
## Scope
125+
126+
At this time, the scope of array-api-compat is limited to wrapping array
127+
libraries so that they can comply with the [array API
128+
standard](https://data-apis.org/array-api/latest/API_specification/index.html).
129+
This includes a small set of [helper functions](helper-functions.md) which may
130+
be useful to most users of array-api-compat, for instance, functions that
131+
provide meta-functionality to aid in supporting the array API, or functions
132+
that are necessary to work around wrapping limitations for certain libraries.
133+
134+
Things that are out-of-scope include:
135+
136+
- functions that have not yet been
137+
standardized (although note that functions that are in a draft version of the
138+
standard are *in scope*),
139+
140+
- functions that are complicated to implement correctly/maintain,
141+
142+
- anything that requires the use of non-Python code.
143+
144+
If you want a function that is not in array-api-compat that isn't part of the
145+
standard, you should request it either for [inclusion in the
146+
standard](https://github.com/data-apis/array-api/issues) or in specific array
147+
libraries.
148+
149+
Why is the scope limited in this way? Firstly, we want to keep
150+
array-api-compat as primarily a
151+
[polyfill](https://en.wikipedia.org/wiki/Polyfill_(programming)) compatibility
152+
shim. The goal is to let consuming libraries use the array API today, even
153+
with array libraries that do not yet fully support it. In an ideal world---one that we hope to eventually see in the future---array-api-compat would be
154+
unnecessary, because every array library would fully support the standard.
155+
156+
The inclusion of non-standardized functions in array-api-compat would
157+
undermine this goal. But much more importantly, it would also undermine the
158+
goals of the [Data APIs Consortium](https://data-apis.org/). The Consortium
159+
creates the array API standard via the consensus of stakeholders from various
160+
array libraries and users. If a not-yet-standardized function were included in
161+
array-api-compat, it would become *de facto* standard, bypassing the decision
162+
making processes of the Consortium.
163+
164+
Secondly, we want to keep array-api-compat as minimal as possible, so that it
165+
is easy for libraries to add as a (possibly vendored) dependency.
166+
167+
Thirdly, array-api-compat has a relatively small development team. Pull
168+
requests to array-api-compat would not necessarily receive the same stringent
169+
level of scrutiny that changes to established array libraries like NumPy or
170+
PyTorch would. For wrapped standard functions, this is fine, since the
171+
wrappers typically just clean up a few small inconsistencies from the
172+
standard, leaving the complexity of the implementation to the base array
173+
library function. Furthermore, standard functions are tested by the rigorous
174+
[array-api-tests](https://github.com/data-apis/array-api-tests) test suite.
175+
For this reason, functions that require complex implementations are generally
176+
out-of-scope and should be preferred to be implemented in upstream array
177+
libraries.
123178

124179
```{toctree}
125180
:titlesonly:

Diff for: docs/supported-array-libraries.md

+5
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@ Note that the [`array_namespace()`](helper-functions.md) helper will also
88
support any array library that explicitly supports the array API by defining
99
[`__array_namespace__`](https://data-apis.org/array-api/latest/API_specification/generated/array_api.array.__array_namespace__.html).
1010

11+
Any reasonably popular array library is in-scope for array-api-compat,
12+
assuming it is possible to wrap it to support the array API without too much
13+
complexity. If your favorite library is not supported, feel free to open an
14+
[issue or pull request](https://github.com/data-apis/array-api-compat/issues).
15+
1116
## [NumPy](https://numpy.org/) and [CuPy](https://cupy.dev/)
1217

1318
NumPy 2.0 has full array API compatibility. This package is not strictly

0 commit comments

Comments
 (0)