A separate typing package?

[lucascolley]

jumping off from #857 (comment) @asmeurer

---

For various reasons discussed in the linked issue, it seems like this repo may not be the ideal location for the development of static typing for the standard. One proposed idea is to create a new package to house type stubs, which could be used by array libraries to check their compliance, and be used to type libraries which consume array API standard arrays.

One idea which seems to have agreement:

• The stubs in this repo (i.e. the signatures, English descriptions of types, and English descriptions of behaviour) should remain the ultimate source of truth. The 'proper' type stubs should try to faithfully replicate the standard (but perhaps may not be able to get all the way there due to upstream Python typing limitations).

Otherwise, does a separate repo sound like a good idea? Or would it fit into one of the existing array-api-* repos? If we want to do this, how should we go about it?

Also quoting some higher-level questions from @jorenham:

• Will it be used as a verification suite for the static type annotations of array-api libraries?
• Will there be a "baseline" package that these protocols should at least be compatible with, e.g. numpy?
• Should it follow the official python typing specification, and if so, how will that be verified?
• Will it be distributed as a (standalone- or bundled-) package, and if so, should these types also be usable at runtime?

ping @betatim @rgommers @34j @BvB93 @nstarman @vnmabus @pmeier @TomNicholas

[nstarman]

This sounds like a great idea. I'm going to ping @ntessore, who's been thinking about this as well.

I appreciate having a single source of truth and if the consensus is to have that be the narrative docs, that sounds good to me.
Also having an official PyPI-installable library of runtime-checkable Protocol objects would be fantastic.

Some thoughts:

Such a package would presumably define

• Array (possibly parametrized)
• Namespace for the API namespace
• DType
• Device
• etc.

IMO this would not be in array-api-strict, etc, as it is would be an implementation-free definition of the Array API. I do think there is also space for a "universal" library that will work with any compatible arrays, without vendoring one itself. This could be in the typing package, or done separately. For example cos would be implemented as:

import array_api as api

def cos(x: api.Array, ...) -> api.Array:
    xp = x.__array_namespace__()
    return xp.cos(x)

A few years back I wrote an example library that defined the Protocols and the "universal" functions: https://github.com/nstarman/array_api

[ntessore]

Thanks for the ping @nstarman! Indeed, we have an ongoing project to make our cosmological simulation code fully Array API-compliant and typing is a central part of that. I would be happy for us to contribute to a coordinated effort instead of building our own solution.

As for making Array generic, I guess the idea would be to write functions as accepting an ArrayT typevar having api.Array as an upper bound. So typing library might provide an api.ArrayT, but the api.Array as such doesn't need to be generic. (Unless this is about parametrising the array type, e.g. np.floating, which I'm not sure about.)

[nstarman]

Wow I don't know which version of array-api your code is based on, but it is fantasitic in that it is fully checked and formatted. I think it is better to start here than with the code in this repository.

I would be happy to transfer that repo to the data-apis org if people think it's a good starting point.

[rgommers]

I would be happy to transfer that repo to the data-apis org if people think it's a good starting point.

Since the outcome of this discussion thread + the community meeting discussion we just had is to indeed create a new array-api-typing package with at least you and @jorenham as maintainers, I'd say if you both agree that that is a good starting point then sure let's do that. Or I can create a fresh repo and add you to it - just let me know!

[jorenham]

How about a fresh repo where we can gradually port over the relevant bits of https://github.com/nstarman/array_api? That way we can start by setting up the project and the tooling to validate the types against existing array-api libraries, and then incrementally port over the stuff from https://github.com/nstarman/array_api, while ensuring compatibility with the ecosystem.

[rgommers]

All thumbs up, so let's go! I created https://github.com/data-apis/array-api-typing and @data-apis/typing-team with maintain permissions. In addition, I gave @jorenham and @nstarman full admin access (setting up CI etc. will likely need that). Happy to help if other things are needed of course. If we want to give more folks commit rights (now or in the future) then please ping me - I'd say we let @jorenham and @nstarman make those decisions for now, so that they can really own the repo/package.

For populating the new repo, it'd be great if you copy over the license and code of conduct metadata files from this repo.

[34j]

In addition to the above matters, I suppose that the stub package should manually maintain only the classes that a TypeVar would frequently bound (Array, Dtype, Device, .... .info) , and the Protocols for other array-api functions should be automatically generated by a script. The following script https://github.com/data-apis/array-api/pull/858/files#diff-e86d9c4a581472cb53f58194cf98904663bc563f864a9e29edbd181dd12eec5d modified from #685 (comment) can be used as a prototype.

Typing functions as Protocols with dtype as a TypeVar could be complicated, but roughly speaking, there should be only two types of functions: creation functions and functions that handle numerical/any values, therefore I would like propose sticking to automatic generation.

[ntessore]

As a very happy adopter of an Array API typing spec, should one come to exist, here's my take on the questions you raise:

The stubs in this repo (i.e. the signatures, English descriptions of types, and English descriptions of behaviour) should remain the ultimate source of truth. The 'proper' type stubs should try to faithfully replicate the standard (but perhaps may not be able to get all the way there due to upstream Python typing limitations).

Fully agreed.

Otherwise, does a separate repo sound like a good idea? Or would it fit into one of the existing array-api-* repos? If we want to do this, how should we go about it?

As a user I would prefer a separate repo, if only to illustrate the distinction between the actual standard, the strict implementation, the compatibility layer, and the typing implementation.

Will there be a "baseline" package that these protocols should at least be compatible with, e.g. numpy?

I think that would defeat the purpose. It's easy to test that my library works with numpy (use numpy in testing). It's hard to verify my library works with any compliant array package.

Should it follow the official python typing specification, and if so, how will that be verified?

I'm not sure what that means, exactly, but you might want to pick one of the type checkers and verify that a test suite of annotations passes without complaints.

Will it be distributed as a (standalone- or bundled-) package, and if so, should these types also be usable at runtime?

I would very much hope for a stand-alone package that users of my library don't even have to worry about, unless we are in a TYPE_CHECKING situation.

[jorenham]

Should it follow the official python typing specification, and if so, how will that be verified?

I'm not sure what that means, exactly, but you might want to pick one of the type checkers and verify that a test suite of annotations passes without complaints.

This is what I meant: https://typing.readthedocs.io/en/latest/spec/index.html
And as far as static-type checkers are concerned; Pyright is a lot better at following it than mypy (source). An even better option would be basedpyright, which is a fork of pyright that has more (stricter) rules and better defaults.

[jorenham]

Will it be distributed as a (standalone- or bundled-) package, and if so, should these types also be usable at runtime?

I would very much hope for a stand-alone package that users of my library don't even have to worry about, unless we are in a TYPE_CHECKING situation.

The reason I was asking, is because typing in python isn't limited to static typing, as there are also many examples of applications of runtime typing (e.g. pydantic, typer, [beartype])(https://github.com/beartype/beartype), optype, etc). And in this case, the "runtime-protocols", which are typing.Protocol types that are decorated with @typing.runtime_checkable, might be interesting for the array-api-typing package.

[lucascolley]

@nstarman just to split this to a separate thread;

I do think there is also space for a "universal" library that will work with any compatible arrays, without vendoring one itself.

There are two similar efforts here. Xarray has implemented something similar for standard arrays wrapped by Xarray: pydata/xarray#9776.

There is also https://github.com/data-apis/array-api-extra, for “universal” functions which are not in the standard.

I suppose I don’t see the need for the kind of library you suggest. Is the main idea to avoid consumers having to call __array_namespace__ and keep track of xp? If so, that seems useful for new libraries, although I think it may be a bit too implicit for converting existing libraries - I think explicitly passing around xp when support is partial can make it clear what is supposed to be working.

[nstarman]

I suppose I don’t see the need for the kind of library you suggest.

Not a high priority. It just enables very easy support for all implementing array types. Converting a program that only supports numpy can become as simple as changing import numpy as np to import array_api as np.

[nstarman]

This might also be a good idea for a "array_api_compat.universal" library that eliminates even the need to call `array_api_compat.array_namespace"...

[lucascolley]

I think the main reason that hasn't happened yet it that it means array_namespace is called for every function call rather than just once.

[34j]

https://github.com/ivy-llc/ivy is a "universal" library I suppose (although it is not FOSS)

[jorenham]

I was planning on building this myself within optype, so that I could use it in scipy-stubs. But it's also fine by me if we make it into a separate package.

And for what it's worth; in jorenham/optype#25 I explain how you could go about typing the "untypeable" dtypes and devices.