Hypothesis-awkward

Hypothesis strategies for Awkward Array.

Awkward Array represents deeply nested, variable-length, and mixed-type data — the kind of irregular structure common in scientific datasets. Its valid arrays therefore span a vast combinatorial space, and test data chosen by developers or generated by AI covers only a small corner of it. The edge cases that break code are often in the parts that no one wrote down. Predefined samples also let an implementation be fitted to them: an AI coding agent, for example, can return the expected outputs for those inputs without implementing the behavior for others. Either way, the tests pass while the code is wrong. Iterative development, whose cycles of refactoring and feature changes AI coding agents now shorten, depends on tests that pass only when the code behaves as expected.

Property-based testing addresses both problems. Instead of asserting specific outputs for predefined inputs, you assert properties that should hold for any valid input and let the framework generate the inputs at run time, so no implementation can be fitted to them. Hypothesis is a property-based testing library for Python: its strategies are composable objects that describe how to build test data, and when a test fails Hypothesis shrinks it, searching for a minimal sample that still triggers the failure.

This package, hypothesis-awkward, brings property-based testing to Awkward Array with a collection of strategies for generating Awkward Arrays. Its main strategy, arrays(), generates nearly fully general Awkward Arrays: called with no arguments, it produces nested, variable-length, record, and union layouts; leaf values of any NumPy dtype Awkward Array supports, as well as strings and bytestrings; optional, masked, and missing values; and virtual arrays — with options to constrain any of these. With this generality, these strategies can surface edge cases in tools that use Awkward Array, and in Awkward Array itself. Tests written with these strategies run in Awkward Array's continuous integration (CI). Together with this package's own tests, they have found bugs in Awkward Array, PyArrow, and Hypothesis; the bugs-found log lists them.

The documentation has a guide and the API reference.

Installation

You can install the package from PyPI using pip:

pip install hypothesis-awkward

This also installs Hypothesis and Awkward Array as dependencies unless they are already installed.

The strategy arrays()

The function arrays() is the main strategy. It generates Awkward Arrays with many options to control the output arrays.

Sample outputs of arrays()

To see sample outputs of arrays(), run a test such as the following with pytest -s, which shows printed output:

from hypothesis import given

import awkward as ak
import hypothesis_awkward.strategies as st_ak


@given(array=st_ak.constructors.arrays())
def test_array(array: ak.Array) -> None:
    print(f'{array=!r}')

For example, this might print:

array=<Array ['', '\U000c2f9f', ..., '@ú\x94j\U000c4364e'] type='4 * string'>
array=<Array [[], [], None, [], ..., [], [], None] type='42 * option[var * ?bytes]'>
array=<Array [??, ??, ??, ??, ??, ??] type='6 * var * unknown'>
array=<Array [NaT, NaT, ..., -9223372036854773681] type='26 * datetime64[Y]'>
array=<Array [[??, ??], [??, ??], ..., [??, ??]] type='8 * 2 * var * timedelta64[fs]'>
array=<Array [[[[[], [], [], [], []]]]] type='1 * 1 * 1 * var * var * var * bool'>
array=<Array [[16996], [10841], ..., [10841], None] type='7 * option[1 * uint16]'>
array=<Array [[None]] type='1 * 1 * option[1 * option[var * int16]]'>
array=<Array [[]] type='1 * option[var * 0 * union[timedelta64[D], 0 * unknown]]'>
array=<Array [0.0, inf, 0.0, nan, 0.0] type='5 * float16'>

In the type strings above, a ? marks an option type (e.g., ?int64), whose missing values print as None. Virtual arrays print as ??.

The options of arrays()

The strategy arrays() has many options to control the output arrays. You can find all options in the API reference:

• API reference: arrays()

Other strategies

In addition to arrays(), this package includes other strategies that generate Awkward Arrays and related data types, which can be found in the API reference:

• API reference

Citation

The citation for Hypothesis-awkward is as follows:

Tai Sakuma, Ianna Osborne, and Peter Elmer, Hypothesis-awkward: Property-Based Testing Strategies for Awkward Array, arXiv:2609.31820 (2026).

The repository's CITATION.cff holds the same citation in machine-readable form; GitHub offers it in APA and BibTeX through "Cite this repository".