Skip to content

Commit ba1ffe7

Browse files
rgommerskgrytehonno
authored
Update the description of the entry point in purpose and scope (#327)
* Update the description of the entry point in purpose and scope Make it clearer this is optional, and why one would want to implement/use an entry point. * Update copy Co-authored-by: Matthew Barber <quitesimplymatt@gmail.com> Co-authored-by: Athan <kgryte@gmail.com> Co-authored-by: Matthew Barber <quitesimplymatt@gmail.com>
1 parent f8bbcd4 commit ba1ffe7

File tree

1 file changed

+33
-7
lines changed

1 file changed

+33
-7
lines changed

spec/purpose_and_scope.md

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -336,24 +336,50 @@ The `xp` namespace must contain all functionality specified in
336336
including additional functionality is not recommended as doing so may hinder
337337
portability and inter-operation of array libraries within user code.
338338

339-
### Checking for Compliance
339+
### Checking an array object for Compliance
340340

341-
Array-consuming libraries are likely to want a mechanism for determining whether a provided array is specification compliant. The recommended approach to check for compliance is by checking whether an array object has an `__array_namespace__` attribute, as this is the one distinguishing feature of an array-compliant object.
341+
Array-consuming libraries are likely to want a mechanism for determining
342+
whether a provided array is specification compliant. The recommended approach
343+
to check for compliance is by checking whether an array object has an
344+
`__array_namespace__` attribute, as this is the one distinguishing feature of
345+
an array-compliant object.
342346

343-
Checking for an `__array_namespace__` attribute can be implemented as a small utility function similar to the following.
347+
Checking for an `__array_namespace__` attribute can be implemented as a small
348+
utility function similar to the following.
344349

345350
```python
346351
def is_array_api_obj(x):
347352
return hasattr(x, '__array_namespace__')
348353
```
349354

350355
```{note}
351-
Providing a "reference library" on which people depend is out-of-scope; hence, the standard cannot, e.g., provide an array ABC from which libraries can inherit to enable an `isinstance` check.
356+
Providing a "reference library" on which people depend is out-of-scope for
357+
the standard. Hence the standard cannot, e.g., provide an array ABC from
358+
which libraries can inherit to enable an `isinstance` check. However, note
359+
that the `numpy.array_api` implementation aims to provide a reference
360+
implementation with only the behavior specified in this standard - it may
361+
prove useful for verifying one is writing portable code.
352362
```
353363

354-
### Discoverability
355-
356-
To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide an {pypa}`entry point <specifications/entry-points/>` in order to make an array API namespace discoverable. For example,
364+
### Discoverability of conforming implementations
365+
366+
It may be useful to have a way to discover all packages in a Python
367+
environment which provide a conforming array API implementation, and the
368+
namespace that that implementation resides in.
369+
To assist array-consuming libraries which need to create arrays originating
370+
from multiple conforming array implementations, or developers who want to perform
371+
for example cross-library testing, libraries may provide an
372+
{pypa}`entry point <specifications/entry-points/>` in order to make an array API
373+
namespace discoverable.
374+
375+
:::{admonition} Optional feature
376+
Given that entry points typically require build system & package installer
377+
specific implementation, this standard chooses to recommend rather than
378+
mandate providing an entry point.
379+
:::
380+
381+
The following code is an example for how one can discover installed
382+
conforming libraries:
357383

358384
```python
359385
from importlib.metadata import entry_points

0 commit comments

Comments
 (0)