Skip to content

🏷️ sparse: improved init stubs of sparse arrays with shape as positional argument. #704

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jorenham merged 6 commits into from
Jul 7, 2025
Merged

🏷️ sparse: improved init stubs of sparse arrays with shape as positional argument. #704

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2fe7a0d
Improved init stubs of sparse arrays with shape as positional argument.
JulVandenBroeck Jul 4, 2025
0ec1442
Added DOK stubs + merged dtype=None and dtype=np.float64 cases
JulVandenBroeck Jul 5, 2025
b3d1ee0
Added more test cases for CSR
JulVandenBroeck Jul 5, 2025
f2d57e8
Fixed constructor stubs for positional and keyword dtypes (other than…
JulVandenBroeck Jul 6, 2025
c34349a
Added missing keyword separators
JulVandenBroeck Jul 6, 2025
7796ded
Cleaned up comments for overloads of sparse array constructors
JulVandenBroeck Jul 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 45 additions & 2 deletions scipy-stubs/sparse/_bsr.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,10 +103,53 @@ class bsr_array(_bsr_base[_ScalarT_co], sparray[_ScalarT_co, tuple[int, int]], G
self: bsr_array[np.float64],
/,
arg1: ToShape2D,
shape: None = None,
shape: ToShape2D | None = None,
dtype: None = None,
Copy link
Member

@jorenham jorenham Jul 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This overload could be merged with the one at line 134:

Suggested change
dtype: None = None,
dtype: onp.AnyFloat64DType | None = None,

I believe that the same can be said for the other sparse formats.

Copy link
Contributor Author

@JulVandenBroeck JulVandenBroeck Jul 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, I included a default overload with just the None option to cover the base case (where the dtype is np.float64). If I remove and merge it with the specific np.float64 overload, another overload (np.bool_ in this case) gets selected first when I do not specify a dtype.
Would you rather I put the np.float64 one at the top of the overloads, so that it gets selected first, or I keep the current overloads?

Copy link
Contributor Author

@JulVandenBroeck JulVandenBroeck Jul 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I think you are alluding to the first option in the suggestions below, so I'll stick to that one!

copy: bool = False,
blocksize: tuple[int, int] | None = None,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[bool]
def __init__(
self: bsr_array[np.bool_],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
Copy link
Member

@jorenham jorenham Jul 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Passing dtype=None won't result in a bsr_array[np.bool_], so the dtype shouldn't have a default here.

But because dtype can be either a positional- or a keyword-arg, and because the preceeding shape parameter has a default, we now have two separate situations we need to deal with:

  1. bsr_array((2, 3), dtype=bool)
  2. bsr_array((2, 3), None, bool)

The first form is probably what most users will go with in practice. But technically speaking, the second form is also valid, although I don't think it's very a likely choice. But to be honest, I have no numbers to back up that claim.

Personally I wouldn't mind if we only cover the first form here. But if you want to be complete about it and don't mind the additional complexity, then you could also add extra overloads for the second form.

This is how I'd annotate the first form:

Suggested change
@overload # 2-d shape-like, dtype: type[bool]
def __init__(
self: bsr_array[np.bool_],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: bool-like (keyword)
def __init__(
self: bsr_array[np.bool_],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
*,
dtype: onp.AnyBoolDType,
copy: bool = False,
maxprint: int | None = None,
) -> None: ...

and if we also cover the second form, that'd be

Suggested change
@overload # 2-d shape-like, dtype: type[bool]
def __init__(
self: bsr_array[np.bool_],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: bool-like (keyword)
def __init__(
self: bsr_array[np.bool_],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
*,
dtype: onp.AnyBoolDType,
copy: bool = False,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: bool-like (positional)
def __init__(
self: bsr_array[np.bool_],
/,
arg1: ToShape2D,
shape: ToShape2D | None,
dtype: onp.AnyBoolDType,
copy: bool = False,
maxprint: int | None = None,
) -> None: ...

I'm fine with either option, as long as you consistently apply it for all 3 dtypes, 7 sparse formats, and >=1 shape types (so >21 overloads).

Copy link
Contributor Author

@JulVandenBroeck JulVandenBroeck Jul 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand that the | None option shouldn't be there for the types other than np.float64, but in practice these overloads will never be picked, since now the np.float64 one is at the top and will be opted for first.
At the same time, the current implementation (with | None for each dtype) covers all cases.
So, I think it's at most a bit "hacky" to put | None after each dtype, but it does the job and avoids 21+ extra overloads.

What do you think? Could be I missed something :)

Copy link
Member

@jorenham jorenham Jul 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but in practice these overloads will never be picked,

that is, unless you pass a dtype that is actually annotated as e.g. type[bool] | None :)

def create_sparse_array(dtype: bool | None = None):
    return scipy.sparse.bsr_array((2, 2), dtype=dtype)

Copy link
Contributor Author

@JulVandenBroeck JulVandenBroeck Jul 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aha, I see.. I'll look into the overloads to resolve this then.

@overload # 2-d shape-like, dtype: type[int]
def __init__(
self: bsr_array[np.int64],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyIntDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[float]
def __init__(
self: bsr_array[np.float64],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyFloat64DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
Copy link
Member

@jorenham jorenham Jul 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
@overload # 2-d shape-like, dtype: type[float]
def __init__(
self: bsr_array[np.float64],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyFloat64DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...

@overload # 2-d shape-like, dtype: type[complex]
def __init__(
self: bsr_array[np.complex128],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyComplex128DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
Expand Down
136 changes: 134 additions & 2 deletions scipy-stubs/sparse/_coo.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ class coo_array(_coo_base[_ScalarT_co, _ShapeT_co], sparray[_ScalarT_co, _ShapeT
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyFloat64DType | None = None,
dtype: None = None,
copy: bool = False,
*,
maxprint: int | None = None,
Expand All @@ -166,12 +166,111 @@ class coo_array(_coo_base[_ScalarT_co, _ShapeT_co], sparray[_ScalarT_co, _ShapeT
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyFloat64DType | None = None,
dtype: None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # >2-d shape-like, dtype: None
def __init__(
self: coo_array[np.float64, onp.AtLeast3D],
/,
arg1: ToShapeMin3D,
shape: ToShapeMin3D | None = None,
dtype: None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[bool]
def __init__(
self: coo_array[np.bool_, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[bool]
def __init__(
self: coo_array[np.bool_, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # >2-d shape-like, dtype: type[bool]
def __init__(
self: coo_array[np.bool_, onp.AtLeast3D],
/,
arg1: ToShapeMin3D,
shape: ToShapeMin3D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[int]
def __init__(
self: coo_array[np.int64, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyIntDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[int]
def __init__(
self: coo_array[np.int64, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyIntDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # >2-d shape-like, dtype: type[int]
def __init__(
self: coo_array[np.int64, onp.AtLeast3D],
/,
arg1: ToShapeMin3D,
shape: ToShapeMin3D | None = None,
dtype: onp.AnyIntDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[float]
def __init__(
self: coo_array[np.float64, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyFloat64DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[float]
def __init__(
self: coo_array[np.float64, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyFloat64DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # >2-d shape-like, dtype: type[float]
def __init__(
self: coo_array[np.float64, onp.AtLeast3D],
/,
Expand All @@ -182,6 +281,39 @@ class coo_array(_coo_base[_ScalarT_co, _ShapeT_co], sparray[_ScalarT_co, _ShapeT
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[complex]
def __init__(
self: coo_array[np.complex128, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyComplex128DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[complex]
def __init__(
self: coo_array[np.complex128, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyComplex128DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # >2-d shape-like, dtype: type[complex]
def __init__(
self: coo_array[np.complex128, onp.AtLeast3D],
/,
arg1: ToShapeMin3D,
shape: ToShapeMin3D | None = None,
dtype: onp.AnyComplex64DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # vector-like builtins.bool, dtype: type[bool] | None
def __init__(
self: coo_array[np.bool_, tuple[int]],
Expand Down
44 changes: 44 additions & 0 deletions scipy-stubs/sparse/_csc.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,39 @@ class csc_array(_csc_base[_ScalarT_co], sparray[_ScalarT_co, tuple[int, int]], G
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: None
def __init__(
self: csc_array[np.float64],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[bool]
def __init__(
self: csc_array[np.bool_],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[int]
def __init__(
self: csc_array[np.int64],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyIntDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[float]
def __init__(
self: csc_array[np.float64],
/,
Expand All @@ -88,6 +121,17 @@ class csc_array(_csc_base[_ScalarT_co], sparray[_ScalarT_co, tuple[int, int]], G
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[complex]
def __init__(
self: csc_array[np.complex128],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyComplex128DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d array-like bool, dtype: type[bool] | None
def __init__(
self: csc_array[np.bool_],
Expand Down
90 changes: 89 additions & 1 deletion scipy-stubs/sparse/_csr.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,12 +126,78 @@ class csr_array(_csr_base[_ScalarT_co, _ShapeT_co], sparray[_ScalarT_co, _ShapeT
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyFloat64DType | None = None,
dtype: None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: None
def __init__(
self: csr_array[np.float64, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[bool]
def __init__(
self: csr_array[np.bool_, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[bool]
def __init__(
self: csr_array[np.bool_, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyBoolDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[int]
def __init__(
self: csr_array[np.int64, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyIntDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[int]
def __init__(
self: csr_array[np.int64, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyIntDType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[float]
def __init__(
self: csr_array[np.float64, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyFloat64DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[float]
def __init__(
self: csr_array[np.float64, tuple[int, int]],
/,
Expand All @@ -142,6 +208,28 @@ class csr_array(_csr_base[_ScalarT_co, _ShapeT_co], sparray[_ScalarT_co, _ShapeT
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d shape-like, dtype: type[complex]
def __init__(
self: csr_array[np.complex128, tuple[int]],
/,
arg1: ToShape1D,
shape: ToShape1D | None = None,
dtype: onp.AnyComplex128DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 2-d shape-like, dtype: type[complex]
def __init__(
self: csr_array[np.complex128, tuple[int, int]],
/,
arg1: ToShape2D,
shape: ToShape2D | None = None,
dtype: onp.AnyComplex128DType | None = None,
copy: bool = False,
*,
maxprint: int | None = None,
) -> None: ...
@overload # 1-d array-like bool, dtype: type[bool] | None
def __init__(
self: csr_array[np.bool_, tuple[int]],
Expand Down
Loading