From 6b85e14e93748eaafec6e312d4f5c99b688316b4 Mon Sep 17 00:00:00 2001 From: Matthew Date: Tue, 2 Nov 2021 16:40:13 +0000 Subject: [PATCH 1/5] Entry points as an optional feature when adoption --- spec/conf.py | 1 + spec/purpose_and_scope.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/spec/conf.py b/spec/conf.py index 308ba52d2..ffb1e94a2 100644 --- a/spec/conf.py +++ b/spec/conf.py @@ -143,4 +143,5 @@ ), "durole": ("http://docutils.sourceforge.net/docs/ref/rst/" "roles.html#%s", ""), "dudir": ("http://docutils.sourceforge.net/docs/ref/rst/" "directives.html#%s", ""), + "pypa": ("https://packaging.python.org/%s", ""), } diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index 56046a277..6af7db82d 100644 --- a/spec/purpose_and_scope.md +++ b/spec/purpose_and_scope.md @@ -369,6 +369,38 @@ recommended not to add other functions or objects, because that may make it harder for users to write code that will work with multiple array libraries. +### Discoverability + +Libraries that wish to [create arrays](../API_specification/creation_functions.md) +using multiple array libraries would still need to explicitly import each +library, as [`__array_namespace__()`](method-__array_namespace__) only makes an +API namespace accessible when consuming arrays. + +To address this issue, an {pypa}`entry point ` may +be provided by a conforming implementation to make its API namespace +discoverable: + +```python +from importlib.metadata import entry_points + +try: + eps = entry_points()['array_api'] + ep = next(ep for ep in eps if ep.name == 'package_name') +except TypeError: + # The dict interface for entry_points() is deprecated in py3.10, + # supplanted by a new select interface. + ep = entry_points(group='array_api', name='package_name') + +xp = ep.load() +``` + +The properties of an entry point should have: + +- `array_api` as the **group** +- The package name as the **name** +- The import path to the API namespace as the **object reference** + + * * * ## Conformance From 42b1bab26730ebb304250603e1b8c7e046fd7122 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 3 Nov 2021 22:51:24 -0700 Subject: [PATCH 2/5] Update copy --- spec/purpose_and_scope.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index 6af7db82d..b0cea0c89 100644 --- a/spec/purpose_and_scope.md +++ b/spec/purpose_and_scope.md @@ -371,14 +371,7 @@ harder for users to write code that will work with multiple array libraries. ### Discoverability -Libraries that wish to [create arrays](../API_specification/creation_functions.md) -using multiple array libraries would still need to explicitly import each -library, as [`__array_namespace__()`](method-__array_namespace__) only makes an -API namespace accessible when consuming arrays. - -To address this issue, an {pypa}`entry point ` may -be provided by a conforming implementation to make its API namespace -discoverable: +To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide an {pypa}`entry point ` in order to make an array API namespace discoverable: ```python from importlib.metadata import entry_points @@ -394,11 +387,11 @@ except TypeError: xp = ep.load() ``` -The properties of an entry point should have: +An entry point must have the following properties: -- `array_api` as the **group** -- The package name as the **name** -- The import path to the API namespace as the **object reference** +- **group**: equal to `array_api`. +- **name**: equal to the package name. +- **object reference**: equal to the array API namespace import path. * * * From 82f02a77defd20753f04fdb99393e3c6b94cc0e0 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 3 Nov 2021 22:52:29 -0700 Subject: [PATCH 3/5] Fix grammar --- spec/purpose_and_scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index b0cea0c89..2977d9651 100644 --- a/spec/purpose_and_scope.md +++ b/spec/purpose_and_scope.md @@ -371,7 +371,7 @@ harder for users to write code that will work with multiple array libraries. ### Discoverability -To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide an {pypa}`entry point ` in order to make an array API namespace discoverable: +To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide a {pypa}`entry point ` in order to make an array API namespace discoverable: ```python from importlib.metadata import entry_points From 1a922fec166cea7445b745dad2e8d907c9c98bab Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 3 Nov 2021 22:52:57 -0700 Subject: [PATCH 4/5] Revert change --- spec/purpose_and_scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index 2977d9651..b0cea0c89 100644 --- a/spec/purpose_and_scope.md +++ b/spec/purpose_and_scope.md @@ -371,7 +371,7 @@ harder for users to write code that will work with multiple array libraries. ### Discoverability -To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide a {pypa}`entry point ` in order to make an array API namespace discoverable: +To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide an {pypa}`entry point ` in order to make an array API namespace discoverable: ```python from importlib.metadata import entry_points From 275015dabe53c07eea0413f34f87af6c18861174 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 4 Nov 2021 01:10:45 -0700 Subject: [PATCH 5/5] Update copy --- spec/purpose_and_scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md index b0cea0c89..3ef3bc611 100644 --- a/spec/purpose_and_scope.md +++ b/spec/purpose_and_scope.md @@ -371,7 +371,7 @@ harder for users to write code that will work with multiple array libraries. ### Discoverability -To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide an {pypa}`entry point ` in order to make an array API namespace discoverable: +To assist array-consuming libraries which need to create arrays originating from multiple conforming array implementations, conforming implementations may provide an {pypa}`entry point ` in order to make an array API namespace discoverable. For example, ```python from importlib.metadata import entry_points