awkward-stubs-pilot-01

I listed three directions to pursue in terms of static typing in Awkward Array as a GitHub issue comment:

1. Type hints on the public API
2. Interface types for Content subclasses
3. Static types for data types

In this pilot, I'll show a proof of concept for the third direction: static types for data types. This repo provides type stubs for Awkward Array's data types; no modification to Awkward Array itself is needed.

Awkward Array has a strong runtime data type system based on Datashape. Data types can be represented as strings like "var * int64" and corresponding type objects like ListType(NumpyType(np.int64)).

With the type stubs in this repo, you can annotate arrays with data type classes. For example:

a: ak.Array[ListType[NumpyType[np.int64]]] = ak.Array([[1, 2], [3]])

Then, editors configured with a static type checker (e.g. Pyright in VS Code) can infer the data types when variables are hovered over.

d = a[0]    # Array[NumpyType[np.int64]]
e = d[0]    # np.int64

How to try it out

Python 3.12+ is required.

Check out and install. For example, with uv:

git clone https://github.com/TaiSakuma/awkward-stubs-pilot-01.git
cd awkward-stubs-pilot-01
uv venv
source .venv/bin/activate
uv pip install -e .

Launch an editor. For example, for VS Code:

code .

Enable a static type checker in the editor (e.g., install the Pyright extension in VS Code).

This repo contains two example files:

• examples_01.py for NumpyType, UnknownType, ListType, RegularType, UnionType, and OptionType.
• examples_02_record_type.py for RecordType.

Open them and hover over the variables to see their inferred types.