Skip to main content

Hypothesis-awkward

Hypothesis strategies for Awkward Array.

pypi-python-badge pypi-badge conda-forge-badge

doi-badge arxiv-badge

test-badge codecov-badge

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; categorical data; 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:

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:

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".

Metadata

Release files for hypothesis-awkward 0.22.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hypothesis-awkward 0.22.0
File Size Uploaded Provenance Actions
hypothesis_awkward-0.22.0.tar.gz 257.8 kB With provenance Details for hypothesis_awkward-0.22.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hypothesis-awkward 0.22.0
File Interpreter ABI Platform Actions
hypothesis_awkward-0.22.0-py3-none-any.whl Python 3 none any Details for hypothesis_awkward-0.22.0-py3-none-any.whl

Total release size: 331.0 kB

Release files / hypothesis_awkward-0.22.0.tar.gz

Download URL hypothesis_awkward-0.22.0.tar.gz
Size 257.8 kB
Tags Source
SHA-256 checksum
How to use checksums
767168506ea16ddac8b415809f38507fe309a5e2ef6e00fbc39f45f256f851e2
BLAKE2b-256 checksum
How to use checksums
c9a26535adc3b6215f716af5900eedb73b6256f5b2861f373f0e104d2d7669eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / hypothesis_awkward-0.22.0-py3-none-any.whl

Download URL hypothesis_awkward-0.22.0-py3-none-any.whl
Size 73.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c0db8c95139f88a961851d7524ba45497e5f05f705376002e1e5f46ea08f9524
BLAKE2b-256 checksum
How to use checksums
c0c8267af4f73737b753c15c16c58a25aaf0b8001f50d42d2b7b0235d8328cdd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for hypothesis-awkward 0.22.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hypothesis_awkward-0.22.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.22.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page