hypothesis-awkward

Hypothesis strategies for Awkward Arrays.

Hypothesis is a property-based testing library. Its strategies are Python functions that strategically generate test data that can fail test cases in pytest and other testing frameworks. Once a test fails, Hypothesis searches for the simplest sample that causes the same error. Hypothesis automatically explores edge cases; developers do not need to craft test data manually.

Property-based testing is useful for finding edge cases in array libraries and in code that uses them. In fact, Hypothesis strategies for NumPy and pandas data types are included in Hypothesis itself. Xarray provides strategies for its data structure. The Apache Arrow codebase has strategies for PyArrow, which are not officially documented in its API reference.

This package, hypothesis-awkward, is a collection of Hypothesis strategies for Awkward Array, which can represent a wide variety of layouts of nested, variable-length, and mixed-type data. The current version of this package includes strategies that generate samples with certain types of layouts. The goal is to develop strategies that can generate fully general Awkward Arrays with multiple options to control the layout, data types, missing values, masks, and other array attributes. These strategies can help close in on edge cases in tools that use Awkward Array, and Awkward Array itself.

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()

You can see sample outputs of the current version of arrays() in the test case:

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 [[], [], [], [], [], [], [], []] type='8 * var * string'>
array=<Array [??, ??, ??, ??, ??, ??, ??, ??] type='8 * var * string'>
array=<Array [b'O\x01\x14\xecE\xdb_'] type='1 * bytes'>
array=<Array [??, ??] type='2 * var * bytes'>
array=<Array [None] type='1 * ?bytes'>
array=<Array [??, ??, ??, ??] type='4 * string'>
array=<Array [NaT, NaT, ..., -9223372036854773681] type='26 * datetime64[Y]'>
array=<Array [[??, ??], [??, ??], ..., [??, ??]] type='8 * 2 * var * timedelta64[fs]'>
array=<Array [[[[], [], [], [], []]]] type='1 * 1 * var * 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 [[0]] type='1 * option[1 * uint16]'>
array=<Array [??] type='1 * 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 [??, ??] type='2 * datetime64[D]'>
array=<Array [??, ??, ??, ??] type='4 * ?timedelta64[us]'>
array=<Array [??, ??, ??, ??, ??, ??, ..., ??, ??, ??, ??, ??, ??] type='14 * bytes'>
array=<Array [[], [], [], [], ..., [], [], [], []] type='55 * option[var * var * ...'>
array=<Array [0.0, inf, 0.0, nan, 0.0] type='5 * float16'>
array=<Array [None, -768614336404561008-11, ..., None] type='6 * ?datetime64[M]'>
array=<Array [??, ??] type='2 * option[var * 1 * string]'>

The current version generates arrays with NumpyArray, EmptyArray, string, and bytestring as leaf contents that can be nested multiple levels deep in RegularArray, ListOffsetArray, ListArray, RecordArray, and UnionArray. Option types (IndexedOptionArray, ByteMaskedArray, BitMaskedArray, UnmaskedArray) add nullable values shown as None in the output. The ? in type strings (e.g., ?int64) indicates option types. Arrays might be virtual, shown as ?? in the output.

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