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 EmptyArray content.
`numpy_array_contents`	Strategy for NumpyArray content.
`regular_array_contents`	Strategy for RegularArray Content wrapping child Content.
`list_array_contents`	Strategy for ListArray Content wrapping child Content.
`list_offset_array_contents`	Strategy for ListOffsetArray Content wrapping child Content.
`string_contents`	Strategy for ListOffsetArray string content.
`bytestring_contents`	Strategy for ListOffsetArray bytestring content.
`record_array_contents`	Strategy for RecordArray Content from a list of child Contents.
`option_contents`	Strategy for option-type content, selected by `st.one_of`.
`indexed_option_array_contents`	Strategy for IndexedOptionArray Content wrapping child Content.
`byte_masked_array_contents`	Strategy for ByteMaskedArray Content wrapping child Content.
`bit_masked_array_contents`	Strategy for BitMaskedArray Content wrapping child Content.
`unmasked_array_contents`	Strategy for UnmaskedArray Content wrapping child Content.
`union_array_contents`	Strategy for UnionArray Content from a list of child Contents.

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_union_root: bool = True,
    allow_indexed_option: bool = True,
    allow_byte_masked: bool = True,
    allow_bit_masked: bool = True,
    allow_unmasked: bool = True,
    allow_option_root: bool = True,
    max_leaf_size: int | None = None,
    max_depth: int = 5,
    max_length: int | None = None,
) -> Content

Strategy for Awkward Array content layouts.

The current implementation generates the following layouts:

EmptyArray
NumpyArray
RegularArray
ListArray
ListOffsetArray
Strings
Bytestrings
RecordArray
IndexedOptionArray
ByteMaskedArray
BitMaskedArray
UnmaskedArray
UnionArray

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 `content_size()` of the generated content. Counts all scalars stored in the content tree: data elements, offset/index buffer elements, and metadata values (`RegularArray.size`, `RecordArray` field names).	`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`. Strings are represented as a `ListOffsetArray` wrapping a `NumpyArray(uint8)`. Each string (not character) counts toward `max_leaf_size`. The string itself does not count toward `max_depth`. Unaffected by `dtypes` and `allow_nan`.	`True`
`allow_bytestring`	`bool`	No bytestring content is generated if `False`. Bytestrings are represented as a `ListOffsetArray` wrapping a `NumpyArray(uint8)`. Each bytestring (not byte) counts toward `max_leaf_size`. The bytestring itself 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_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_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`
`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`
`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`	Maximum nesting depth. At each level below this limit, a coin flip decides whether to descend further or produce a leaf. Each RegularArray, ListOffsetArray, ListArray, RecordArray, and UnionArray layer adds one level, excluding those that form string or bytestring content.	`5`
`max_length`	`int \| None`	Maximum `len()` of the generated content. No constraint when `None` (the default).	`None`

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. By default there is no upper bound.	`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`

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.

Produces one of NumpyArray, EmptyArray, string, or bytestring content, selected by st.one_of.

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`

Examples:

>>> c = leaf_contents().example()
>>> isinstance(c, (NumpyArray, EmptyArray, ListOffsetArray))
True

empty_array_contents ¶

empty_array_contents() -> st.SearchStrategy[EmptyArray]

Strategy for EmptyArray content.

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 NumpyArray content.

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`

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 = 5,
    max_zeros_length: int = 5,
    max_length: int | None = None,
) -> RegularArray

Strategy for RegularArray Content wrapping child 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_size`	`int`	Upper bound on the length of each element.	`5`
`max_zeros_length`	`int`	Upper bound on the number of elements when each element is empty, i.e., when size is zero.	`5`
`max_length`	`int \| None`	Upper bound on the number of groups, i.e., `len(result)`.	`None`

Examples:

>>> c = regular_array_contents().example()
>>> isinstance(c, Content)
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 ListArray Content wrapping child 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)`. Defaults to `len(content)` when `None`.	`None`

Examples:

>>> c = list_array_contents().example()
>>> isinstance(c, Content)
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 ListOffsetArray Content wrapping child 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)`. Defaults to `len(content)` when `None`.	`None`

Examples:

>>> c = list_offset_array_contents().example()
>>> isinstance(c, Content)
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 ListOffsetArray string content.

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`

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 ListOffsetArray bytestring content.

Parameters:

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

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 RecordArray Content from a list of child Contents.

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`

Examples:

>>> c = record_array_contents().example()
>>> isinstance(c, Content)
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. `None` means no constraint.	`None`
`allow_indexed_option`	`bool`	Include `IndexedOptionArray` if `True`.	`True`
`allow_byte_masked`	`bool`	Include `ByteMaskedArray` if `True`.	`True`
`allow_bit_masked`	`bool`	Include `BitMaskedArray` if `True`.	`True`
`allow_unmasked`	`bool`	Include `UnmaskedArray` if `True`.	`True`

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 IndexedOptionArray Content wrapping child Content.

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)`. When `None`, defaults to twice the content length.	`None`

Examples:

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

byte_masked_array_contents ¶

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

Strategy for ByteMaskedArray Content wrapping child Content.

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`

Examples:

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

bit_masked_array_contents ¶

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

Strategy for BitMaskedArray Content wrapping child Content.

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`

Examples:

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

unmasked_array_contents ¶

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

Strategy for UnmaskedArray Content wrapping child Content.

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`

Examples:

>>> c = unmasked_array_contents().example()
>>> isinstance(c, Content)
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 UnionArray Content from a list of child Contents.

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)`. When `None`, no constraint is applied.	`None`

Examples:

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

Limit the union length:

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