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.
`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 = 10,
    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,
    max_depth: int = 5,
    max_length: int | None = None,
) -> Content

Strategy for Awkward Array content layouts.

Builds content layouts by recursively constructing a tree of content nodes. At each level, a coin flip decides whether to go deeper or produce a leaf. Leaf types include NumpyArray, EmptyArray, string, and bytestring. Wrapper types include RegularArray, ListOffsetArray, ListArray, RecordArray, and UnionArray.

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`	Maximum total number of 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.	`10`
`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_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_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`
`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_total_size: int = 10,
    min_size: int = 0,
    max_size: int | 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 returns a strategy for a single content.	`contents`
`max_total_size`	`int`	Maximum total number of leaf elements across all contents in the list.	`10`
`min_size`	`int`	Minimum number of contents in the list.	`0`
`max_size`	`int \| None`	Maximum number of contents in the list. By default there is no upper bound.	`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,
) -> Content

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 = 5,
) -> Content

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`	Upper bound on the number of lists, i.e., `len(result)`.	`5`

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 = 5,
) -> Content

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`	Upper bound on the number of lists, i.e., `len(result)`.	`5`

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,
) -> Content

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

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,
) -> Content

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