Add dependency to array-api-compat

Author: crusaderky

.github/workflows/test-vendor.yml

@@ -0,0 +1,52 @@
+name: Test vendoring support
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
+  FORCE_COLOR: 3
+
+jobs:
+  pre-commit-and-lint:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout array-api-extra
+        uses: actions/checkout@v4
+        with:
+          path: array-api-extra
+
+      - name: Checkout array-api-compat
+        uses: actions/checkout@v4
+        with:
+          repository: data-apis/array-api-compat
+          path: array-api-compat
+
+      - name: Vendor array-api-extra into test package
+        run: |
+          cp -a array-api-compat/array_api_compat array-api-extra/vendor_tests/
+          cp -a array-api-extra/src/array_api_extra array-api-extra/vendor_tests/
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install Pixi
+        uses: prefix-dev/[email protected]
+        with:
+          pixi-version: v0.39.0
+          cache: true
+
+      - name: Test package
+        run: pixi run tests-vendor

.gitignore

@@ -162,3 +162,7 @@ Thumbs.db
 # pixi environments
 .pixi
 *.egg-info
+
+# Vendor tests
+vendor_tests/array_api_compat/
+vendor_tests/array_api_extra/

docs/index.md

@@ -51,16 +51,57 @@ If you require stability, it is recommended to pin `array-api-extra` to
 a specific version, or vendor the library inside your own.
 ```
 
+```{note}
+This library depends on array-api-compat. We aim for compatibility with
+the latest released version of array-api-compat, and your mileage may vary
+with older or dev versions.
+```
+
 (vendoring)=
 
 ## Vendoring
 
 To vendor the library, clone
-[the repository](https://github.com/data-apis/array-api-extra) and copy it into
-the appropriate place in your library, like:
+[the array-api-extra repository](https://github.com/data-apis/array-api-extra)
+and copy it into the appropriate place in your library, like:
 
 ```
-cp -R array-api-extra/ mylib/vendored/array_api_extra
+cp -a array-api-extra/src/array_api_extra mylib/vendored/
+```
+
+`array-api-extra` depends on `array-api-compat`. You may either add a dependency
+in your own project to `array-api-compat` or vendor it too:
+
+1. Clone
+   [the array-api-compat repository](https://github.com/data-apis/array-api-compat)
+   and copy it next to your vendored array-api-extra:
+
+   ```
+   cp -a array-api-compat/array_api_compat mylib/vendored/
+   ```
+
+2. Create a new hook file which array-api-extra will use instead of the
+   top-level `array-api-compat` if present:
+
+   ```
+   echo 'from mylib.vendored.array_api_compat import *' > mylib/vendored/_array_api_compat_vendor.py
+   ```
+
+This also allows overriding `array-api-compat` functions if you so wish. E.g.
+your `mylib/vendored/_array_api_compat_vendor.py` could look like this:
+
+```python
+from mylib.vendored.array_api_compat import *
+from mylib.vendored.array_api_compat import array_namespace as _array_namespace_orig
+
+
+def array_namespace(*xs, **kwargs):
+    import mylib
+
+    if any(isinstance(x, mylib.MyArray) for x in xs):
+        return mylib
+    else:
+        return _array_namespace_orig(*xs, **kwargs)
 ```
 
 (usage)=

pixi.lock

@@ -26,7 +26,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dynamic = ["version"]
-dependencies = []
+dependencies = ["array-api-compat"]
 
 [project.optional-dependencies]
 tests = [
@@ -96,6 +96,7 @@ numpy = "*"
 [tool.pixi.feature.tests.tasks]
 tests = { cmd = "pytest" }
 tests-ci = { cmd = "pytest -ra --cov --cov-report=xml --cov-report=term --durations=20" }
+tests-vendor = { cmd = "pytest vendor_tests" }
 
 [tool.pixi.feature.docs.dependencies]
 sphinx = ">=7.0"