Skip to content

Remove skimage specific array expression syntax #77

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

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
+23 −29
Draft

Remove skimage specific array expression syntax #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e7f3d77
Remove skimage specific array expression syntax
lagru Aug 18, 2025
375b8b3
Remove skimage array forms from example package
lagru Aug 18, 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
34 changes: 18 additions & 16 deletions docs/typing_syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,26 +75,28 @@ and **mappings** exist.

This expression allows adding shape and datatype information for data structures like [NumPy arrays](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html).

`array` and `ndarray`, and `array-like` and `array_like` can be used interchange-ably.
`array` and `ndarray`, and `array-like` and `array_like` can be used interchange-ably for the variable `ARRAY` below.

| Docstring type | Python type annotation |
|----------------------------------------|------------------------|
| `ARRAY of dtype DTYPE` | `ARRAY[DTYPE]` |
| `ARRAY of dtype DTYPE and shape SHAPE` | `ARRAY[DTYPE]` |
| `ARRAY of shape SHAPE` | `ARRAY[DTYPE]` |
| `ARRAY of shape SHAPE and dtype DTYPE` | `ARRAY[DTYPE]` |

E.g.

| Docstring type | Python type annotation |
|------------------------------------------|------------------------|
| `array of dtype int` | `ndarray[int]` |
| `ndarray of dtype bool and shape (4, 4)` | `ndarray[bool]` |
| `array-like of dtype float` | `ArrayLike[float]` |
| `array_like of shape (M, 2)` | `ArrayLike` |

| Docstring type | Python type annotation |
|-----------------------------|------------------------|
| `array of DTYPE` | `ndarray[DTYPE]` |
| `ndarray of dtype DTYPE` | `ndarray[DTYPE]` |
| `array-like of DTYPE` | `ArrayLike[DTYPE]` |
| `array_like of dtype DTYPE` | `ArrayLike[DTYPE]` |

> [!NOTE]
> Noting the **shape** of an array in the docstring is supported.
> However, Python's typing system is not yet able to express this information.
> It is therefore not included in the resulting type annotation.

| Docstring type | Python type annotation |
|--------------------------|------------------------|
| `(3,) array of DTYPE` | `ndarray[DTYPE]` |
| `(X, Y) array of DTYPE` | `ndarray[DTYPE]` |
| `([P,] M, N) array-like` | `ArrayLike` |
| `(M, ...) ndarray` | `ArrayLike` |
> However, [support for including shapes in generated stubs](https://github.com/scientific-python/docstub/issues/76) is not yet included in docstub.


## Literals
Expand Down
8 changes: 4 additions & 4 deletions examples/example_pkg/_numpy.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,12 @@ def func_ndarray(a1, a2, a3, a4=None):
----------
a1 : ndarray
a2 : np.NDArray
a3 : (N, 3) ndarray of float
a3 : ndarray of dtype float and shape (N, 3)
a4 : ndarray of shape (1,) and dtype uint8

Returns
-------
r1 : uint8 array
r1 : array of dtype uint8
r2 : array of dtype complex and shape (1, ..., 3)
"""

Expand All @@ -37,11 +37,11 @@ def func_array_like(a1, a2, a3, a4):
----------
a1 : array-like
a2 : array_like
a3 : (N, 3) array-like of float
a3 : array-like of dtype float and shape (N, 3)
a4 : array-like of shape (1,) and dtype uint8

Returns
-------
r1 : uint8 array-like
r1 : array-like of dtype uint8
r2 : array_like of dtype complex and shape (1, ..., 3)
"""
4 changes: 0 additions & 4 deletions src/docstub/doctype.lark
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,10 +89,6 @@ _natlang_mapping: qualname "of" "{" type ":" type "}"
// A natural language alternative to describe arrays with a dtype and shape.
natlang_array: array_name "of dtype" dtype ("and shape" shape)?
| array_name "of shape" shape ("and dtype" dtype)?
| shape array_name ("of" dtype)?
| shape? array_name "of" dtype
| shape dtype array_name
| dtype array_name


// Currently a bit of a hack. Since the `array_expression` is ambiguous, we
Expand Down
6 changes: 1 addition & 5 deletions tests/test_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,12 +228,9 @@ def test_rst_role(self, doctype, expected):
@pytest.mark.parametrize(
("fmt", "expected_fmt"),
[
("{shape} {name}", "{name}"),
("{shape} {name} of {dtype}", "{name}[{dtype}]"),
("{shape} {dtype} {name}", "{name}[{dtype}]"),
("{dtype} {name}", "{name}[{dtype}]"),
("{name} of shape {shape} and dtype {dtype}", "{name}[{dtype}]"),
("{name} of dtype {dtype} and shape {shape}", "{name}[{dtype}]"),
("{name} of {dtype}", "{name}[{dtype}]"),
],
)
@pytest.mark.parametrize("name", ["array", "ndarray", "array-like", "array_like"])
Expand Down Expand Up @@ -261,7 +258,6 @@ def escape(name: str) -> str:
("doctype", "expected"),
[
("ndarray of dtype (int or float)", "ndarray[int | float]"),
("([P,] M, N) (int or float) array", "array[int | float]"),
],
)
def test_natlang_array_specific(self, doctype, expected):
Expand Down
Loading