Contents¶

Strategies for Contents (layouts).

These strategies are related to the section of Awkward Array User Guide "Direct constructors".

Functions:

Name	Description
`contents`	Strategy for Awkward Array content layouts.
`content_lists`	Strategy for lists of contents within a size budget.
`leaf_contents`	Strategy for leaf content types.
`empty_array_contents`	Strategy for `ak.contents.EmptyArray` instances.
`numpy_array_contents`	Strategy for `ak.contents.NumpyArray` instances.
`regular_array_contents`	Strategy for `ak.contents.RegularArray` instances.
`list_array_contents`	Strategy for `ak.contents.ListArray` instances.
`list_offset_array_contents`	Strategy for `ak.contents.ListOffsetArray` instances.
`string_contents`	Strategy for string `ak.contents.ListOffsetArray` instances.
`bytestring_contents`	Strategy for bytestring `ak.contents.ListOffsetArray` instances.
`record_array_contents`	Strategy for `ak.contents.RecordArray` instances.
`option_contents`	Strategy for option-type content, selected by `st.one_of`.
`indexed_option_array_contents`	Strategy for `ak.contents.IndexedOptionArray` instances.
`byte_masked_array_contents`	Strategy for `ak.contents.ByteMaskedArray` instances.
`bit_masked_array_contents`	Strategy for `ak.contents.BitMaskedArray` instances.
`unmasked_array_contents`	Strategy for `ak.contents.UnmaskedArray` instances.
`union_array_contents`	Strategy for `ak.contents.UnionArray` instances.

contents ¶

contents(
    draw: DrawFn,
    *,
    dtypes: SearchStrategy[dtype] | None = None,
    max_size: int = 50,
    allow_nan: bool = True,
    allow_numpy: bool = True,
    allow_empty: bool = True,
    allow_string: bool = True,
    allow_bytestring: bool = True,
    allow_regular: bool = True,
    allow_list_offset: bool = True,
    allow_list: bool = True,
    allow_record: bool = True,
    allow_union: bool = True,
    allow_indexed_option: bool = True,
    allow_byte_masked: bool = True,
    allow_bit_masked: bool = True,
    allow_unmasked: bool = True,
    max_leaf_size: int | None = None,
    max_depth: int | None = None,
    max_length: int | None = None,
    allow_union_root: bool = True,
    allow_option_root: bool = True,
) -> Content

Strategy for Awkward Array content layouts.

The current implementation generates the following layouts:

Each type can be excluded separately with the corresponding allow_* argument.

The max_size is the main argument for constraining the array size. It counts most of the scalar values in the layout, including data elements, offsets, indices, field names, and parameters. The array size can also be constrained with max_leaf_size, max_depth, and max_length.

Parameters:

Name	Type	Description	Default
`dtypes`	`SearchStrategy[dtype] \| None`	A strategy for NumPy scalar dtypes used in `NumpyArray`. If `None`, the default strategy that generates any scalar dtype supported by Awkward Array is used. Does not affect string or bytestring content.	`None`
`max_size`	`int`	Upper bound on the number of scalars in the generated content. Counts data elements, offsets, indices, field names, and parameters.	`50`
`allow_nan`	`bool`	No `NaN`/`NaT` values are generated in `NumpyArray` if `False`.	`True`
`allow_numpy`	`bool`	No `NumpyArray` is generated if `False`.	`True`
`allow_empty`	`bool`	No `EmptyArray` is generated if `False`. `EmptyArray` has Awkward type `unknown` and carries no data. Unlike `NumpyArray`, it is unaffected by `dtypes` and `allow_nan`.	`True`
`allow_string`	`bool`	No string content is generated if `False`. A string is represented as a `ListOffsetArray` wrapping a `NumpyArray(uint8)`. Each character (uint8) and offset in the `ListOffsetArray` counts toward `max_size`. A string is considered a single leaf element in counting toward `max_leaf_size` and `max_depth`. Each string (not character) counts toward `max_leaf_size`. A string does not count toward `max_depth`. Unaffected by `dtypes` and `allow_nan`.	`True`
`allow_bytestring`	`bool`	No bytestring content is generated if `False`. A bytestring is represented as a `ListOffsetArray` wrapping a `NumpyArray(uint8)`. Each byte (uint8) and offset in the `ListOffsetArray` counts toward `max_size`. A bytestring is considered a single leaf element in counting toward `max_leaf_size` and `max_depth`. Each bytestring (not byte) counts toward `max_leaf_size`. A bytestring does not count toward `max_depth`. Unaffected by `dtypes` and `allow_nan`.	`True`
`allow_regular`	`bool`	No `RegularArray` is generated if `False`.	`True`
`allow_list_offset`	`bool`	No `ListOffsetArray` is generated if `False`.	`True`
`allow_list`	`bool`	No `ListArray` is generated if `False`.	`True`
`allow_record`	`bool`	No `RecordArray` is generated if `False`.	`True`
`allow_union`	`bool`	No `UnionArray` is generated if `False`.	`True`
`allow_indexed_option`	`bool`	No `IndexedOptionArray` is generated if `False`.	`True`
`allow_byte_masked`	`bool`	No `ByteMaskedArray` is generated if `False`.	`True`
`allow_bit_masked`	`bool`	No `BitMaskedArray` is generated if `False`.	`True`
`allow_unmasked`	`bool`	No `UnmaskedArray` is generated if `False`.	`True`
`max_leaf_size`	`int \| None`	Maximum total number of leaf elements in the generated content. Each numerical value, including complex and datetime, counts as one. Each string and bytestring (not character or byte) counts as one.	`None`
`max_depth`	`int \| None`	Maximum nesting depth. Each `RegularArray`, `ListOffsetArray`, `ListArray`, `RecordArray`, and `UnionArray` layer adds one level, excluding those that form string or bytestring content. Unbounded if `None`.	`None`
`max_length`	`int \| None`	Maximum `len()` of the generated array. Unbounded if `None`.	`None`
`allow_union_root`	`bool`	The outermost content node cannot be a `UnionArray` if `False`. Unlike `allow_union`, this does not prevent `UnionArray` at deeper levels. Awkward Array does not allow a `UnionArray` to directly contain another `UnionArray`.	`True`
`allow_option_root`	`bool`	The outermost content node cannot be an option type if `False`. Does not affect deeper levels. Prevents option-inside-option nesting.	`True`

Returns:

Type	Description
`Content`

Examples:

>>> c = contents().example()
>>> isinstance(c, Content)
True

content_lists ¶

content_lists(
    draw: DrawFn,
    st_content: StContent = contents,
    *,
    max_size: int = 50,
    max_leaf_size: int | None = None,
    min_len: int = 0,
    max_len: int | None = None,
    all_option_or_none: bool = False,
    st_option: StOption | None = None,
) -> list[Content]

Strategy for lists of contents within a size budget.

Parameters:

Name	Type	Description	Default
`st_content`	`StContent`	A callable that accepts `max_size` and `max_leaf_size` and returns a strategy for a single content.	`contents`
`max_size`	`int`	Upper bound on total `content_size()` across all contents in the list.	`50`
`max_leaf_size`	`int \| None`	Maximum total number of leaf elements across all contents in the list.	`None`
`min_len`	`int`	Minimum number of contents in the list.	`0`
`max_len`	`int \| None`	Maximum number of contents in the list. Unbounded if `None`.	`None`
`all_option_or_none`	`bool`	If `True`, enforce all-or-none option typing: the first child decides whether all children are option-wrapped. Requires `st_option`.	`False`
`st_option`	`StOption \| None`	A callable conforming to `StOption` that wraps content in an option type. Required when `all_option_or_none` is `True`.	`None`

Returns:

Type	Description
`list[Content]`

leaf_contents ¶

leaf_contents(
    *,
    dtypes: SearchStrategy[dtype] | None = None,
    allow_nan: bool = True,
    min_size: int = 0,
    max_size: int = 10,
    allow_numpy: bool = True,
    allow_empty: bool = True,
    allow_string: bool = True,
    allow_bytestring: bool = True,
) -> st.SearchStrategy[
    NumpyArray | EmptyArray | ListOffsetArray
]

Strategy for leaf content types.

This strategy generates EmptyArray, bytestring content, string content, and NumpyArray and shrinks in that order towards EmptyArray.

Parameters:

Name	Type	Description	Default
`dtypes`	`SearchStrategy[dtype] \| None`	A strategy for NumPy scalar dtypes used in `NumpyArray`. If `None`, the default strategy that generates any scalar dtype supported by Awkward Array is used. Does not affect string or bytestring content.	`None`
`allow_nan`	`bool`	No `NaN`/`NaT` values are generated in `NumpyArray` if `False`.	`True`
`min_size`	`int`	Minimum number of elements.	`0`
`max_size`	`int`	Maximum number of elements.	`10`
`allow_numpy`	`bool`	No `NumpyArray` is generated if `False`.	`True`
`allow_empty`	`bool`	No `EmptyArray` is generated if `False`.	`True`
`allow_string`	`bool`	No string content is generated if `False`.	`True`
`allow_bytestring`	`bool`	No bytestring content is generated if `False`.	`True`

Raises:

Type	Description
`ValueError`	If no content types are possible with the given options.

Returns:

Type	Description
`NumpyArray \| EmptyArray \| ListOffsetArray`

empty_array_contents ¶

empty_array_contents() -> st.SearchStrategy[EmptyArray]

Strategy for ak.contents.EmptyArray instances.

Returns:

Type	Description
`EmptyArray`

numpy_array_contents ¶

numpy_array_contents(
    *,
    dtypes: SearchStrategy[dtype] | None = None,
    allow_nan: bool = True,
    min_size: int = 0,
    max_size: int = 10,
) -> st.SearchStrategy[NumpyArray]

Strategy for ak.contents.NumpyArray instances.

Parameters:

Name	Type	Description	Default
`dtypes`	`SearchStrategy[dtype] \| None`	A strategy for NumPy scalar dtypes. If `None`, the default strategy that generates any scalar dtype supported by Awkward Array is used.	`None`
`allow_nan`	`bool`	No `NaN`/`NaT` values are generated if `False`.	`True`
`min_size`	`int`	Minimum number of elements.	`0`
`max_size`	`int`	Maximum number of elements.	`10`

Returns:

Type	Description
`NumpyArray`

Examples:

>>> c = numpy_array_contents().example()
>>> isinstance(c, NumpyArray)
True

regular_array_contents ¶

regular_array_contents(
    draw: DrawFn,
    content: SearchStrategy[Content]
    | Content
    | None = None,
    *,
    max_size: int | None = None,
    max_zeros_length: int | None = None,
    max_length: int | None = None,
) -> RegularArray

Strategy for ak.contents.RegularArray instances.

This strategy generates a RegularArray with the given content. It shrinks toward a shorter length (larger size) with no unreachable data.

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	content or strategy for the content. If `None`, draw from `contents()`.	`None`
`max_size`	`int \| None`	Upper bound on the size parameter of the `RegularArray`. If `None`, `len(content)` is used.	`None`
`max_zeros_length`	`int \| None`	Upper bound on the `zeros_length` parameter of the `RegularArray`. Only effective when size is zero.	`None`
`max_length`	`int \| None`	Upper bound on the length of the `RegularArray` (i.e., `len(result)`). Unbounded if `None`.	`None`

Returns:

Type	Description
`RegularArray`

Examples:

>>> c = regular_array_contents().example()
>>> isinstance(c, RegularArray)
True

Limit each element to at most 3 items:

>>> c = regular_array_contents(max_size=3).example()
>>> c.size <= 3
True

Limit the number of elements when size is zero:

>>> c = regular_array_contents(max_size=0, max_zeros_length=2).example()
>>> c.size == 0 and len(c) <= 2
True

Limit the number of groups:

>>> c = regular_array_contents(max_length=4).example()
>>> len(c) <= 4
True

list_array_contents ¶

list_array_contents(
    draw: DrawFn,
    content: SearchStrategy[Content]
    | Content
    | None = None,
    *,
    max_length: int | None = None,
) -> ListArray

Strategy for ak.contents.ListArray instances.

This strategy generates a ListArray with the given content. It produces all valid ListArray layouts including unreachable data, gaps, overlapping sublists, and out-of-order starts. It shrinks toward contiguous, monotonic starts with no unreachable data.

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	Child content. Can be a strategy for `Content`, a concrete `Content` instance, or `None` to draw from `contents()`.	`None`
`max_length`	`int \| None`	Upper bound on the number of lists, i.e., `len(result)`. If `None`, `len(content)` is used.	`None`

Returns:

Type	Description
`ListArray`

Examples:

>>> c = list_array_contents().example()
>>> isinstance(c, ListArray)
True

Limit the number of lists:

>>> c = list_array_contents(max_length=4).example()
>>> len(c) <= 4
True

list_offset_array_contents ¶

list_offset_array_contents(
    draw: DrawFn,
    content: SearchStrategy[Content]
    | Content
    | None = None,
    *,
    max_length: int | None = None,
) -> ListOffsetArray

Strategy for ak.contents.ListOffsetArray instances.

This strategy generates a ListOffsetArray with the given content. It produces layouts with and without unreachable data. It shrinks toward no unreachable data (offsets[0] == 0 and offsets[-1] == len(content)).

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	Child content. Can be a strategy for `Content`, a concrete `Content` instance, or `None` to draw from `contents()`.	`None`
`max_length`	`int \| None`	Upper bound on the number of lists, i.e., `len(result)`. If `None`, `len(content)` is used.	`None`

Returns:

Type	Description
`ListOffsetArray`

Examples:

>>> c = list_offset_array_contents().example()
>>> isinstance(c, ListOffsetArray)
True

Limit the number of lists:

>>> c = list_offset_array_contents(max_length=4).example()
>>> len(c) <= 4
True

string_contents ¶

string_contents(
    draw: DrawFn,
    *,
    alphabet: SearchStrategy[str] | None = None,
    min_size: int = 0,
    max_size: int = 10,
) -> ListOffsetArray

Strategy for string ak.contents.ListOffsetArray instances.

Parameters:

Name	Type	Description	Default
`alphabet`	`SearchStrategy[str] \| None`	A strategy for characters used in the generated strings. If `None`, the full Unicode range is used.	`None`
`min_size`	`int`	Minimum number of strings.	`0`
`max_size`	`int`	Maximum number of strings.	`10`

Returns:

Type	Description
`ListOffsetArray`

Examples:

>>> c = string_contents().example()
>>> isinstance(c, ListOffsetArray)
True

bytestring_contents ¶

bytestring_contents(
    draw: DrawFn, *, min_size: int = 0, max_size: int = 10
) -> ListOffsetArray

Strategy for bytestring ak.contents.ListOffsetArray instances.

Parameters:

Name	Type	Description	Default
`min_size`	`int`	Minimum number of bytestrings.	`0`
`max_size`	`int`	Maximum number of bytestrings.	`10`

Returns:

Type	Description
`ListOffsetArray`

Examples:

>>> c = bytestring_contents().example()
>>> isinstance(c, ListOffsetArray)
True

record_array_contents ¶

record_array_contents(
    draw: DrawFn,
    contents: list[Content]
    | SearchStrategy[list[Content]]
    | None = None,
    *,
    max_fields: int = 5,
    allow_tuple: bool = True,
    max_length: int | None = None,
) -> RecordArray

Strategy for ak.contents.RecordArray instances.

Parameters:

Name	Type	Description	Default
`contents`	`list[Content] \| SearchStrategy[list[Content]] \| None`	Child contents. Can be a strategy for a list of `Content`, a concrete list, or `None` to draw random children.	`None`
`max_fields`	`int`	Maximum number of fields when `contents` is `None`.	`5`
`allow_tuple`	`bool`	Allow tuple records (no field names) if `True`.	`True`
`max_length`	`int \| None`	Upper bound on the record length, i.e., `len(result)`.	`None`

Returns:

Type	Description
`RecordArray`

Examples:

>>> c = record_array_contents().example()
>>> isinstance(c, RecordArray)
True

Limit the number of fields:

>>> c = record_array_contents(max_fields=3).example()
>>> len(c.contents) <= 3
True

Limit the record length:

>>> c = record_array_contents(max_length=4).example()
>>> len(c) <= 4
True

option_contents ¶

option_contents(
    content: SearchStrategy[Content]
    | Content
    | None = None,
    *,
    max_size: int | None = None,
    allow_indexed_option: bool = True,
    allow_byte_masked: bool = True,
    allow_bit_masked: bool = True,
    allow_unmasked: bool = True,
) -> st.SearchStrategy[Content]

Strategy for option-type content, selected by st.one_of.

Picks among IndexedOptionArray, ByteMaskedArray, BitMaskedArray, and UnmaskedArray.

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	Forwarded to each per-type strategy.	`None`
`max_size`	`int \| None`	Forwarded to `indexed_option_array_contents()` to bound the index length. Unbounded if `None`.	`None`
`allow_indexed_option`	`bool`	No `IndexedOptionArray` is generated if `False`.	`True`
`allow_byte_masked`	`bool`	No `ByteMaskedArray` is generated if `False`.	`True`
`allow_bit_masked`	`bool`	No `BitMaskedArray` is generated if `False`.	`True`
`allow_unmasked`	`bool`	No `UnmaskedArray` is generated if `False`.	`True`

Returns:

Type	Description
`Content`

Examples:

>>> c = option_contents().example()
>>> isinstance(c, Content)
True

indexed_option_array_contents ¶

indexed_option_array_contents(
    draw: DrawFn,
    content: SearchStrategy[Content]
    | Content
    | None = None,
    *,
    max_size: int | None = None,
) -> IndexedOptionArray

Strategy for ak.contents.IndexedOptionArray instances.

The index length is drawn independently of the content length. Valid entries can reference any content position (duplicates allowed). Missing entries have index[i] = -1.

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	Child content. Can be a strategy for `Content`, a concrete `Content` instance, or `None` to draw from `contents()`.	`None`
`max_size`	`int \| None`	Upper bound on the index length, i.e., `len(result)`. If `None`, twice the content length is used.	`None`

Returns:

Type	Description
`IndexedOptionArray`

Examples:

>>> c = indexed_option_array_contents().example()
>>> isinstance(c, IndexedOptionArray)
True

byte_masked_array_contents ¶

byte_masked_array_contents(
    draw: DrawFn,
    content: SearchStrategy[Content]
    | Content
    | None = None,
) -> ByteMaskedArray

Strategy for ak.contents.ByteMaskedArray instances.

The mask length always equals len(content).

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	Child content. Can be a strategy for `Content`, a concrete `Content` instance, or `None` to draw from `contents()`.	`None`

Returns:

Type	Description
`ByteMaskedArray`

Examples:

>>> c = byte_masked_array_contents().example()
>>> isinstance(c, ByteMaskedArray)
True

bit_masked_array_contents ¶

bit_masked_array_contents(
    draw: DrawFn,
    content: SearchStrategy[Content]
    | Content
    | None = None,
) -> BitMaskedArray

Strategy for ak.contents.BitMaskedArray instances.

The logical length always equals len(content). The mask is bit-packed into uint8 bytes.

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	Child content. Can be a strategy for `Content`, a concrete `Content` instance, or `None` to draw from `contents()`.	`None`

Returns:

Type	Description
`BitMaskedArray`

Examples:

>>> c = bit_masked_array_contents().example()
>>> isinstance(c, BitMaskedArray)
True

unmasked_array_contents ¶

unmasked_array_contents(
    draw: DrawFn,
    content: SearchStrategy[Content]
    | Content
    | None = None,
) -> UnmaskedArray

Strategy for ak.contents.UnmaskedArray instances.

UnmaskedArray is an option type with no actual nulls. It simply wraps content, adding option-type semantics without a mask buffer.

Parameters:

Name	Type	Description	Default
`content`	`SearchStrategy[Content] \| Content \| None`	Child content. Can be a strategy for `Content`, a concrete `Content` instance, or `None` to draw from `contents()`.	`None`

Returns:

Type	Description
`UnmaskedArray`

Examples:

>>> c = unmasked_array_contents().example()
>>> isinstance(c, UnmaskedArray)
True

union_array_contents ¶

union_array_contents(
    draw: DrawFn,
    contents: list[Content]
    | SearchStrategy[list[Content]]
    | None = None,
    *,
    max_contents: int = 4,
    max_length: int | None = None,
) -> UnionArray

Strategy for ak.contents.UnionArray instances.

Parameters:

Name	Type	Description	Default
`contents`	`list[Content] \| SearchStrategy[list[Content]] \| None`	Child contents. Can be a strategy for a list of `Content`, a concrete list, or `None` to draw random children.	`None`
`max_contents`	`int`	Maximum number of child contents when `contents` is `None`.	`4`
`max_length`	`int \| None`	Upper bound on the union length, i.e., `len(result)`. Unbounded if `None`.	`None`

Returns:

Type	Description
`UnionArray`

Examples:

>>> c = union_array_contents().example()
>>> isinstance(c, UnionArray)
True

Limit the union length:

>>> c = union_array_contents(max_length=4).example()
>>> len(c) <= 4
True