feat: HasX attributes #34

nstarman · 2025-07-01T21:18:00Z

~~Requires #32. I'll rebase when that's in.~~

Now preceding #32.

nstarman · 2025-07-01T21:19:35Z

@jorenham @NeilGirdhar @lucascolley this doesn't resolve the current discussion re a DTypeT typevar or a DType protocol, but does mean Arrays can now understand any typevar or protocol we want to add.

jorenham

I like the Has* protocols. Optype will cover the CanArray* ones I think. There might be some that can't be expressed because Self can't be passed as generic type argument, but I suppose we can deal with it when needed.

One nit is that ... are not needed when there's a docstring, which already counts as an expression or statement or something.

nstarman · 2025-07-02T21:37:08Z

I like the Has* protocols. Optype will cover the CanArray* ones I think. There might be some that can't be expressed because Self can't be passed as generic type argument, but I suppose we can deal with it when needed.

What do we do about docstrings?

One nit is that ... are not needed when there's a docstring, which already counts as an expression or statement or something.

Yes, my pylint is complaining. But IMO empty methods should have ... to distinguish them from ones that aren't empty. Helps in understanding inheritance with a Protocol.

jorenham · 2025-07-02T21:42:40Z

What do we do about docstrings?

Hmm good question. Maybe a numpy-esque add_docstring function?

jorenham · 2025-07-02T21:44:49Z

Yes, my pylint is complaining. But IMO empty methods should have ... to distinguish them from ones that aren't empty. Helps in understanding inheritance with a Protocol.

Yea I guess there's something to be said for that. It just looks a bit weird to me to see a ... occupy a line on its own (but that might have something to do with me spending most of my breathing time looking at stubs).

src/array_api_typing/_array.py

Signed-off-by: nstarman <[email protected]>

Signed-off-by: Nathaniel Starkman <[email protected]>

Signed-off-by: nstarman <[email protected]>

nstarman · 2025-07-24T02:00:41Z

@jorenham I added tests and made the protocols public.

nstarman · 2025-07-27T03:21:06Z

@jorenham This should cover all the array attributes.

nstarman · 2025-08-01T17:30:10Z

@jorenham it might be easier to merge this before doing numpy type compat stuff from #32.

nstarman · 2025-08-01T19:58:44Z

src/array_api_typing/_array.py

+    """Protocol for array classes that have a shape attribute."""
+
+    @property
+    def shape(self) -> tuple[int | None, ...]:


I think in a followup we should add a type parameter UnknownDimsT = TypeVar(None, Never, default=None) so that it's possible to define an array where the dimensions are always known.

Array[..., UnknownDimsT=Never]

Then we can define the alias types

KnownDimsArray: TypeAlias = Array[..., Never] UnknownDimsArray: TypeAlias = Array[..., None]

what would UnknownDimsT be the type of, then?

we should add a type parameter UnknownDimsT = TypeVar(None, Never, default=None)

as in; what will it annotate

The dim types, like

def shape(self) -> tuple[int | UnknownDimsT, ...]:

Ah, ok, that makes sense. I was confused because it's a plural Dims.

jorenham · 2025-08-05T15:31:59Z

src/array_api_typing/_array.py

+        ...
+
+
+class HasSize(Protocol):


What's the use-case of this one? Is there anything this can help with, that HasShape can't?
Put differently; should we make this public API or not?

jorenham · 2025-08-05T15:33:22Z

src/array_api_typing/_array.py

+        ...
+
+
+class HasTranspose(Protocol):


Ah nice; this could be used to annotate functions that exclusively accept 2d arrays, without having to deal with shape-typing :)

jorenham · 2025-08-05T15:34:30Z

src/array_api_typing/_array.py

+    HasNDim,
+    HasShape,
+    HasSize,
+    HasTranspose,


This HasTranspose restricts this to 2d arrays

jorenham · 2025-08-05T15:37:13Z

tests/integration/test_numpy2p0.pyi

+_: np.dtype[F32] = x_f32.dtype
+_: np.dtype[I32] = x_i32.dtype
+_: np.dtype[B] = x_b.dtype
+
+# Check Attribute `.device`
+_: object = x_f32.device
+_: object = x_i32.device
+_: object = x_b.device


I'd go with typing.assert_type here

jorenham · 2025-08-05T15:37:42Z

tests/integration/test_numpy2p0.pyi

+_: int = x_f32.ndim
+_: int = x_i32.ndim
+_: int = x_b.ndim
+
+# Check Attribute `.shape`
+_: tuple[int | None, ...] = x_f32.shape
+_: tuple[int | None, ...] = x_i32.shape
+_: tuple[int | None, ...] = x_b.shape
+
+# Check Attribute `.size`
+_: int | None = x_f32.size
+_: int | None = x_i32.size
+_: int | None = x_b.size


typing.assert_type

jorenham · 2025-08-05T15:40:48Z

src/array_api_typing/_array.py

+        ...
+
+
+class HasMatrixTranspose(Protocol):


I'd move this one closer to HasTranspose

And the use-case of this is to require at least 2 dimensions, right?

jorenham · 2025-08-05T15:43:48Z

src/array_api_typing/_array.py

+        ...
+
+
+class HasNDim(Protocol):


Is there a situation where you'd wanna use HasNDim over e.g. HasShape? Otherwise we probably should keep this private, given that

There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.

jorenham · 2025-08-05T15:46:30Z

src/array_api_typing/_array.py

+    """Protocol for array classes that have a device attribute."""
+
+    @property
+    def device(self) -> object:  # TODO: more specific type


I can see how this can be helpful for users if it would be generic. So I propose we either keep it private until that time, or to just make it generic right now.

jorenham reviewed Jul 2, 2025

View reviewed changes

nstarman force-pushed the has_x_attributes branch 2 times, most recently from 8096aff to 3793c1f Compare July 21, 2025 15:56

nstarman mentioned this pull request Jul 22, 2025

✨: add CanArrayX protocols #32

Draft

nstarman force-pushed the has_x_attributes branch 5 times, most recently from cb3dbb3 to dec1842 Compare July 23, 2025 21:05

nstarman marked this pull request as ready for review July 23, 2025 21:10

nstarman requested a review from jorenham July 23, 2025 21:10

nstarman force-pushed the has_x_attributes branch from dec1842 to 53ddb98 Compare July 23, 2025 21:14

nstarman commented Jul 23, 2025

View reviewed changes

src/array_api_typing/_array.py Show resolved Hide resolved

nstarman added 7 commits July 23, 2025 21:57

💄rearrange protocols in Array

4de00ae

Signed-off-by: nstarman <[email protected]>

✨ HasDevice

591853b

Signed-off-by: nstarman <[email protected]>

✨ HasMatrixTranspose

b0b88cf

✨ HasNDim

ed33843

Signed-off-by: nstarman <[email protected]>

✨ HasShape

e49a73a

✨ HasSize

0eba222

Signed-off-by: Nathaniel Starkman <[email protected]>

✨ HasTranspose

a5e3d5b

Signed-off-by: nstarman <[email protected]>

nstarman force-pushed the has_x_attributes branch from 53ddb98 to a5e3d5b Compare July 24, 2025 01:57

nstarman added this to the v2021-12-0.0 milestone Aug 1, 2025

nstarman added the ✨ feature Introduce new features. label Aug 1, 2025

nstarman added the ✅ tests Add, update, or pass tests. label Aug 1, 2025

nstarman commented Aug 1, 2025

View reviewed changes

jorenham reviewed Aug 5, 2025

View reviewed changes

feat: HasX attributes #34

Are you sure you want to change the base?

feat: HasX attributes #34

Uh oh!

Conversation

nstarman commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nstarman commented Jul 1, 2025

Uh oh!

jorenham left a comment

Choose a reason for hiding this comment

Uh oh!

nstarman commented Jul 2, 2025

Uh oh!

jorenham commented Jul 2, 2025

Uh oh!

jorenham commented Jul 2, 2025

Uh oh!

Uh oh!

nstarman commented Jul 24, 2025

Uh oh!

nstarman commented Jul 27, 2025

Uh oh!

nstarman commented Aug 1, 2025

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!

Uh oh!

nstarman commented Jul 1, 2025 •

edited

Loading