Migration guide post-merge review by mtsokol · Pull Request #1000 · data-apis/array-api

mtsokol · 2026-03-23T12:13:32Z

@lucascolley review of migration guide.

lucascolley

thanks Mateusz! A few more suggestions but this looks like a nice improvement!

@ev-br @kgryte did you want to take another look?

lucascolley · 2026-03-23T12:35:18Z

spec/draft/migration_guide.md

+This page is meant to help migrate your codebase to an array API standard
+compliant implementation. The guide is divided into three parts.


'Compliance' seems more relevant for producers. I guess for consumers it is rather about becoming interoperable with compliant implementations?

added the consumers' perspective as well in the intro sentence.

lucascolley · 2026-03-23T12:36:35Z

spec/draft/migration_guide.md

+The first part gives an overview of the {ref}`ecosystem` libraries, that
+are helpful in different contexts when working with the array API standard.

 The first part is dedicated for {ref}`array-producers`. If your library


second part

lucascolley · 2026-03-23T12:37:16Z

spec/draft/migration_guide.md

 their system/algorithm.

-The second part delves into details for Array API compatibility for
+The second part delves into details for array API standard compatibility for


lucascolley · 2026-03-23T15:17:54Z

spec/draft/migration_guide.md

+The first part gives an overview of the {ref}`ecosystem` libraries, that
+are helpful in different contexts when working with the array API standard.

 The first part is dedicated for {ref}`array-producers`. If your library


Suggested change

The first part is dedicated for {ref}`array-producers`. If your library

The first part is dedicated to {ref}`array-producers`. If your library

lucascolley · 2026-03-23T15:18:28Z

spec/draft/migration_guide.md

+mimics, for example, NumPy's or PyTorch's functionality, then you can find in
 the first part additional instructions and guidance on how to ensure


Suggested change

mimics, for example, NumPy's or PyTorch's functionality, then you can find in

the first part additional instructions and guidance on how to ensure

mimics, for example, NumPy's or PyTorch's functionality, then you can find in

here additional instructions and guidance on how to ensure

lucascolley · 2026-03-23T15:20:10Z

spec/draft/migration_guide.md

+Although NumPy, Dask, CuPy, and PyTorch support the array API standard, there
 are still some corner cases where their behavior diverges from the standard.


still not sure if we should claim support in this first phrase, particularly for Dask and PyTorch

right, I removed Dask and PyTorch from here.

lucascolley · 2026-03-23T15:20:35Z

spec/draft/migration_guide.md

-into array objects. As an array consumer, you can still rely on the original
-API while having access to the standard compatible one.
+`array-api-compat` provides a compatibility layer to cover an additional subset
+of these corner cases. This is also accompanied by a few utility functions fo


Suggested change

of these corner cases. This is also accompanied by a few utility functions fo

of these corner cases. This is also accompanied by a few utility functions for

lucascolley · 2026-03-23T15:21:47Z

spec/draft/migration_guide.md

+easier introspection into array objects. As an array consumer, you can still
+rely on the original API while having access to the standard compatible one.


Suggested change

easier introspection into array objects. As an array consumer, you can still

rely on the original API while having access to the standard compatible one.

easier introspection into array objects. As an array consumer, you can consume

standard-compliant namespaces as well as the wrapped namespaces in

`array-api-compat` at the same time.

lucascolley · 2026-03-23T15:22:42Z

spec/draft/migration_guide.md

+implementation of the array API standard. As a consumer, you can use
+`array-api-strict` for parametrising tests with it as an array namespace
+to ensure your code uses APIs compliant with the standard.


Suggested change

implementation of the array API standard. As a consumer, you can use

`array-api-strict` for parametrising tests with it as an array namespace

to ensure your code uses APIs compliant with the standard.

implementation of the array API standard. As a consumer, you can use

`array-api-strict` in parametrising tests over the array namespace

to ensure your code uses only APIs which are in the standard.

lucascolley · 2026-03-23T15:24:08Z

spec/draft/migration_guide.md

-standard define it:
+namespace variable. The convention used in the ecosystem is to name it `xp`.
+Then, it is vital to ensure that each method and function call is something that
+the array API standard supports. For example, `dot` is present in the NumPy's


Suggested change

the array API standard supports. For example, `dot` is present in the NumPy's

the array API standard supports. For example, `dot` is present in the NumPy

frazane · 2026-03-29T14:35:20Z

Hi @mtsokol, thanks for extending this migration guide, it's quite helpful. Just wondering about one thing - are there any guidelines on how to handle missing components of the array API standard? For instance, in my case I would love to see #725 addressed but I know it will take time. So in the meantime, is there any suggested approach on how I should extend the API in my own project?

Migration guide post-merge review

38d415b

mtsokol mentioned this pull request Mar 23, 2026

docs: add migration guides and tutorial #999

Merged

lucascolley self-requested a review March 23, 2026 12:23

lucascolley approved these changes Mar 23, 2026

View reviewed changes

lucascolley added the Narrative Content Narrative documentation content. label Mar 23, 2026

Review comments

a3375e7

		This page is meant to help migrate your codebase to an array API standard
		compliant implementation. The guide is divided into three parts.

	The first part is dedicated for {ref}`array-producers`. If your library
	The first part is dedicated to {ref}`array-producers`. If your library

		mimics, for example, NumPy's or PyTorch's functionality, then you can find in
		the first part additional instructions and guidance on how to ensure

		Although NumPy, Dask, CuPy, and PyTorch support the array API standard, there
		are still some corner cases where their behavior diverges from the standard.

	of these corner cases. This is also accompanied by a few utility functions fo
	of these corner cases. This is also accompanied by a few utility functions for

		easier introspection into array objects. As an array consumer, you can still
		rely on the original API while having access to the standard compatible one.

-easier introspection into array objects. As an array consumer, you can still
-rely on the original API while having access to the standard compatible one.
+easier introspection into array objects. As an array consumer, you can consume
+standard-compliant namespaces as well as the wrapped namespaces in
+`array-api-compat` at the same time.

	the array API standard supports. For example, `dot` is present in the NumPy's
	the array API standard supports. For example, `dot` is present in the NumPy

Conversation

mtsokol commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lucascolley left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frazane commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mtsokol commented Mar 23, 2026 •

edited

Loading