Skip to content
Merged
3 changes: 3 additions & 0 deletions docs/_toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,9 @@ subtrees:
- file: developers/contributing/dev_install
- file: developers/contributing/testing
- file: developers/contributing/typing
subtrees:
- entries:
- file: developers/contributing/typing_patterns
- file: developers/contributing/performance/index
subtrees:
- entries:
Expand Down
59 changes: 55 additions & 4 deletions docs/developers/contributing/typing.md

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I wasn't sure because it was so many lines here, but then reading through I quite like these minimal explanations and comparisons. The changes to this file are great!

Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,13 @@ every pull request and has to pass before we merge, but
**you are not expected to fix type errors in your own PR**. If it fails and the
fix isn't obvious, ask for help and a team member will be eager to guide you.

```{tip}
Why annotate at all? Type hints make code easier to read, because the
signature tells you what goes in and what comes out. They let the checker catch
many bugs before the code runs, and they give your editor better completion and
go-to-definition.
```

```{note}
Why we moved off mypy, and what we compared against, is in the Island Dispatch
post
Expand Down Expand Up @@ -37,12 +44,36 @@ addition, the [code editor integration](https://pyrefly.org/en/docs/IDE/) reads
the same `[tool.pyrefly]` configuration, but it sees your environment too — so
treat editor suggestions as a hint and `tox -e pyrefly` as the standard.

(napari-typing-annotating)=

## Annotating new code

1. **Annotate the parameters and return values** you are adding or changing,
and leave unrelated types alone — a bug fix shouldn't turn into a typing
sweep. Only modify previous annotations if they are relevant to the
contribution you are making.
contribution you are making. For example:

`````{tab-set}

````{tab-item} Without annotations
```python
def scale(values, factor=1.0):
return [value * factor for value in values]
```
````

````{tab-item} With annotations
```python
from collections.abc import Iterable


def scale(values: Iterable[float], factor: float = 1.0) -> list[float]:
return [value * factor for value in values]
```
````

`````

2. When feasible, **add `from __future__ import annotations`** at the top of
any module that doesn't have it yet. This makes annotations lazy, so they
are not executed at runtime until required, in order to infer the types.
Expand All @@ -52,13 +83,25 @@ treat editor suggestions as a hint and `tox -e pyrefly` as the standard.
and potential import cycles stay out of the runtime path. Ruff rules flag
these and will often move them for you with pre-commit. To do this, add
`from typing import TYPE_CHECKING` to the top of the file, then wrap the
imports in:
imports in it:

```python
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
from some_module import SomeType
import numpy as np


def describe(image: np.ndarray) -> str:
return f'{image.ndim}D image'
```

`typing.TYPE_CHECKING` is `False` when the program runs and is only treated
as `True` by type checkers, so the import inside the block is never executed
at runtime.

```{important}
Lazy evaluation of annotation breaks tools that require runtime type
inspection, such as magicgui decorators and Pydantic models. For those, type
Expand All @@ -76,7 +119,7 @@ treat editor suggestions as a hint and `tox -e pyrefly` as the standard.
contract other modules rely on, and locals are inferred well enough without
help.
- **Parameters should accept the widest type that works; returns give back the
concrete type you built.** When psosible, take `Iterable`, `Sequence` or
concrete type you built.** When possible, take `Iterable`, `Sequence` or
`Mapping` rather than `list` or `dict`, and hand back the `list` or `dict`
you actually made.
- **`Any` switches off checking for everything it touches.** It is sometimes
Expand All @@ -98,6 +141,9 @@ treat editor suggestions as a hint and `tox -e pyrefly` as the standard.
[NumPy typing guide](https://numpy.org/doc/stable/reference/typing.html),
including about `npt.ArrayLike` for inputs that can be converted to arrays.

For short, self-contained examples of these rules, see the
[typing cheat sheet](napari-typing-patterns).

## When the check complains

Suppressing should be rare. Most types can be written honestly, and a
Expand Down Expand Up @@ -172,3 +218,8 @@ wrong with the type it could see.
- [Type hints cheat sheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html)
— syntax suggestions to copy. It is written for mypy, but the syntax is the
same.
- [`typing` module reference](https://docs.python.org/3/library/typing.html)
— the standard library documentation for `TYPE_CHECKING`, `Protocol`,
`cast` and the other names used above.
- [Typing cheat sheet](napari-typing-patterns): napari's own short examples
of the patterns on this page.
209 changes: 209 additions & 0 deletions docs/developers/contributing/typing_patterns.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
(napari-typing-patterns)=

# Typing cheat sheet

Short, self-contained examples of the rules in [Type checking](napari-typing).
For how to run the checker and how to handle its errors, see the
[main page](napari-typing).

## Annotations with and without `from __future__ import annotations`

On Python versions before 3.14, without the `__future__` import, Python
evaluates annotations when the function or class is defined. A name that does
not exist yet at that point, such as the class being defined or a type imported
under `if TYPE_CHECKING:`, then has to be written as a string. With the import,
annotations are stored as strings automatically, so the quotes are not needed:

`````{tab-set}

````{tab-item} Without the import
```python
class Node:
children: list['Node']

def add_child(self, child: 'Node') -> 'Node':
self.children.append(child)
return child
```
````

````{tab-item} With the import
```python
from __future__ import annotations


class Node:
children: list[Node]

def add_child(self, child: Node) -> Node:
self.children.append(child)
return child
```
````

`````

Tools that read annotations at runtime, such as
[magicgui](https://pyapp-kit.github.io/magicgui/) and
[Pydantic](https://docs.pydantic.dev/latest/), need
extra care here, as explained in
[Annotating new code](napari-typing-annotating).

## Values that may be `None`

Write `X | None` for an optional value and `X | Y` for a union. They mean the
same as `Optional[X]` and `Union[X, Y]`, which you will still see in older
modules while napari's ruff config disables the automatic rewrite (`UP007`,
`UP045`).

```python
def format_float(value: float, precision: int | None = None) -> str:
if precision is None:
# since the input `precision` is `None`, set it to a default value
precision = 3
# from here on, the checker knows that `precision` is an `int`
return f'{value:.{precision}f}'
```

## Flexible inputs, concrete outputs

`collections.abc` is a Python module establishing abstract, reusable and
pythonic-like interfaces for customizable classes that implement common
patterns.

It's best to annotate the input types of a function or method through these
types. Instead, output types should return clearly defined types. In general
the idea is "flexible inputs, strict outputs".

An abstract type describes what an object can do, not which class it is. Any
class that defines `__iter__` counts as an `Iterable`, without inheriting from
it:

```python
from collections.abc import Iterable


class Fruits:
def __iter__(self):
yield 'apple'
yield 'banana'


isinstance(Fruits(), Iterable) # True
```

```python
from collections.abc import Iterable, Mapping


def unique_sorted(items: Iterable[str]) -> list[str]:
return sorted(set(items))


def normalize(weights: Mapping[str, float]) -> dict[str, float]:
total = sum(weights.values())
return {name: weight / total for name, weight in weights.items()}
```

`unique_sorted` accepts a list, a tuple, a set, a generator, or any custom
object that implements `__iter__`, such as `Fruits` above, without changing its
signature. If a function modifies its argument in place, ask for
`MutableSequence` or `MutableMapping` instead.
Comment on lines +110 to +111

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

this reads as a jump in logic to me, as the example above only uses Mapping -- so my immediate thought jumps to -- are there ImmutableMapping? Is Mapping by default mutable or immutable? Indeed, what is Mapping as Iterable has been explained. Oh, and there is Sequence here now too? Why Sequence. I know the answer to some (but not all) of these questions, but as a reader it feels abrupt. You could either remove such mentions or expand on them to make it more clear. Especially because Sequence is used in the next section.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Probably after this line it's better to add a note marker stating in a few words the difference between a mutable vs. immutable data structure.

Thing is, I don't want to make this guide a thorough walkthrough of the typing specification.

For example, Mapping is not mutable, while a MutableMapping is. Same for Sequence and MutableSequence. The difference is mainly in the supported methods.

I wouldn't know how to explain this section better without pulling a comparison between the supported methods...

Best we could do is point into the note to the collections.abc documentation. It provides exhaustive comparison of the supported methods.


```{note}
`Mapping` and `Sequence` only promise read access, such as lookups, `len()` and
iteration. `MutableMapping` and `MutableSequence` add the methods that change
the object, such as item assignment, `append()`, `pop()` and `update()`. The
[`collections.abc` documentation](https://docs.python.org/3/library/collections.abc.html)
lists the methods each type supports.
```

## Generic functions with `TypeVar`

When the output type depends on the input type, describe the relationship with
a `TypeVar`:

```python
from collections.abc import Sequence
from typing import TypeVar

T = TypeVar('T')


def first(items: Sequence[T]) -> T:
return items[0]
```

The checker now knows that `first([1, 2])` is an `int` and `first(["a"])` is a
`str`. napari still supports Python 3.11, so use `TypeVar` rather than the
`def first[T](...)` syntax added in Python 3.12.
Comment on lines +137 to +139

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

cool TIL and finally understand! Thank you :)


## NumPy arrays

```python
import numpy as np
import numpy.typing as npt


def to_float(data: npt.ArrayLike) -> npt.NDArray[np.float64]:
return np.asarray(data, dtype=np.float64)
```

`npt.NDArray` is generic in its dtype: `np.float64` fills that type parameter,
so `npt.NDArray[np.float64]` is shorthand for
`np.ndarray[tuple[Any, ...], np.dtype[np.float64]]`, an array of any shape with
a `float64` dtype. `npt.ArrayLike` accepts anything `np.asarray` can convert,
such as lists, tuples and arrays.

## Protocols for "anything with these members"

A `Protocol` describes what a function uses instead of which class it expects:

```python
from typing import Protocol


class HasShape(Protocol):
@property
def shape(self) -> tuple[int, ...]: ...


def ndim(data: HasShape) -> int:
return len(data.shape)
```
Comment on lines +158 to +173

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This section is incomplete, it should present what happens with read-write attributes (property is a read-only attribute) and methods


Any object with a `shape` attribute satisfies `HasShape` without inheriting
from it, so NumPy, dask and zarr arrays all work.

```python
from typing import Protocol


class Named(Protocol):
name: str

def label(self) -> str: ...


class Sample:
name: str

def __init__(self, name: str) -> None:
self.name = name

def label(self) -> str:
return self.name


sample: Named = Sample('cells')
sample.name = 'tissue'
sample.label()
```

The checker treats `name` as a read-write attribute, so assigning a `str` is

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

what do you mean by a read-write attribute? Is that something baked into Protocol or because of the type annotation on name?

I think I'm wondering if the HasShape and the Named block can be combined, there is much overlap in logic and by splitting like this I'm having a harder time following what is important.

@jacopoabramo jacopoabramo Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

what do you mean by a read-write attribute? Is that something baked into Protocol or because of the type annotation on name?

Consider the following:

class MyProto(Protocol):
    name: str
     
class MyOtherProto(Protocol):
    @property
    def name(self) -> str:
        ...
     
class MyClass:
    def __init__(self) -> None:
        self.name = "MyClass"
        
my_obj = MyClass()

isinstance(my_obj, MyProto) # prints True
isinstance(my_obj, MyOtherProto) # prints True

So yes, the distinction between read-write vs read-only attributes it's baked into the definition of a protocol. In this case the two protocols differ on the ability to write into name, and in the latter it's explicitly marked as @property which makes it read-only.

I think I'm wondering if the HasShape and the Named block can be combined, there is much overlap in logic and by splitting like this I'm having a harder time following what is important.

At a glance they can, and it would probably help to do so from a readability perspective but we could lose the explanation of the distinction above.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

excellent explanation, than you!

allowed and assigning another type is an error. `shape` on `HasShape` stays
read-only, so assigning to it is an error. `label` is a method: the object
must define it, and the checker checks the call and the `str` return.

Decorate the `Protocol` with `@runtime_checkable` only if you also need
`isinstance()` checks.
1 change: 1 addition & 0 deletions docs/developers/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ Resources for contributors
- [Development installation](dev-installation)
- [Testing](napari-testing)
- [Type checking](napari-typing)
- [Typing cheat sheet](napari-typing-patterns)
- [Performance](performance)
- [Profiling](napari-profiling)
- [Benchmarks](napari-benchmarks)
Expand Down
Loading