a
    yn„f"¸ ã                   @  s  d dl mZ d dlZd dlZd dlZd dlZd dlZd dlZd dlZd dl	Z	d dl
Z
d dlZd dlmZmZmZmZ d dlmZ d dlZd dlZd dlmZmZ d dlmZ d dlmZ d dlmZmZm Z  d d	l!m"Z" d d
l#m$Z$ d dl%m&Z& d dl'm(Z( d dl)m*Z*m+Z+m,Z, d dl-m.Z. d dl/m0Z0m1Z1 d dl2m3Z3 d dl4m5Z5 d dl4m6Z7 dZ8e& 9¡ Z:e$ 9¡ Z;e <d¡Z=e1dej>j?d�Z@dd„ ZAd1dddœdd„ZBddd œd!d"„ZCG d#d$„ d$e(eeƒZDG d%d&„ d&e(ƒZEG d'd(„ d(eƒZFd)d*„ ZGed+d,œd-d.„ƒZHed+d,œd/d0„ƒZIdS )2é    )ÚannotationsN)ÚIterableÚMappingÚSequenceÚSized)Ú_ext)Úattrs_ofÚwithout_transient_attrs)Úregister_backend_lookup_factory)ÚNumpyBackend)Úbehavior_ofÚget_array_classÚget_record_class)Úwrap_layout)ÚNumpy)ÚNumpyMetadata)ÚNDArrayOperatorsMixin)Úcustom_reduceÚunpickle_array_schema_1Úunpickle_record_schema_1)Úis_non_string_like_iterable)ÚAnyÚTypeVar)ÚSTDOUT)Ú	Formatter)Úvaluestr)ÚArrayÚArrayBuilderÚRecordz^[a-zA-Z_]\w*$ÚT)Úboundc                   s   t  ˆ ¡‡ fdd„ƒ}t|ƒS )zRproperty factory that ensures IPython does not call the property during inspectionc                   s8   t tdƒr0ddlm} t ¡ j}|j|ju r0d S ˆ | ƒS )NZ__IPYTHON__r   )Údict_dir)	ÚhasattrÚbuiltinsZIPython.utils.wildcardr!   ÚinspectÚcurrentframeÚf_backÚf_codeÚ__code__)Úselfr!   Úcaller_frame©Úimpl© úT/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/awkward/highlevel.pyÚwrapper6   s    

z)non_inspectable_property.<locals>.wrapper)Ú	functoolsÚwrapsÚproperty)r,   r/   r-   r+   r.   Únon_inspectable_property3   s    
r3   úpart{}ÚintÚstr)Ú	partitionÚtemplatec                   sL   |  d¡› d�‰ |  |¡› d�‰dddœ‡ ‡fdd„‰‡‡fdd„‰ˆ| ƒS )	z‚Rewrite partition i as partition 0 for a given container.

    This routine is a helper function for reading awkward1 pickles
    r   ú-r6   )ÚkeyÚreturnc                   s   | t ˆ ƒd … }ˆ› |› �S ©N©Úlen)r:   Úsuffix)Údefault_prefixÚpart_prefixr-   r.   Úrename_form_keyL   s    z:_awkward_1_rewrite_partition_form.<locals>.rename_form_keyc              	     s¸   t | tjjtjjfƒr(| jˆ | jƒd�S t | tjjtjjtjj	tjj
tjjtjjtjjfƒrv| jˆ| jƒˆ | jƒd�S t | tjjtjjfƒr°| j‡fdd„| jD ƒˆ | jƒd�S t‚d S )N)Úform_key)ÚcontentrC   c                   s   g | ]}ˆ |ƒ‘qS r-   r-   )Ú.0Úc)Ú	transformr-   r.   Ú
<listcomp>i   ó    zH_awkward_1_rewrite_partition_form.<locals>.transform.<locals>.<listcomp>)ÚcontentsrC   )Ú
isinstanceÚakÚformsZ	NumpyFormZ	EmptyFormÚcopyrC   ZListFormZListOffsetFormZRegularFormZIndexedFormZIndexedOptionFormZByteMaskedFormZBitMaskedFormrD   Z	UnionFormZ
RecordFormrJ   ÚAssertionError)Úform)rB   rG   r-   r.   rG   Q   s4    ùþþþþz4_awkward_1_rewrite_partition_form.<locals>.transform)Úformat)rP   r7   r8   r-   )r@   rA   rB   rG   r.   Ú!_awkward_1_rewrite_partition_formD   s
    rR   zT | str | bytes)Úlayoutr;   c                 C  sZ   t | tjjƒrR|  d¡}|dkr.tj | j¡S |dkrLtj | j¡jdd�S | S n| S d S )NÚ	__array__ÚbyteÚcharÚsurrogateescape)Úerrors)	rK   rL   rJ   Ú
NumpyArrayÚ	parameterÚ_utilÚtobytesÚdataÚdecode)rS   Zarray_paramr-   r-   r.   Úprepare_layoutr   s    
r_   c                      s:  e Zd ZdZddddddœdd„Z‡ fdd„ZejjZ	d	d
„ Z
dd„ Zeddœdd„ƒZejddœdd„ƒZedd„ ƒZejdd„ ƒZedd„ ƒZejdd„ ƒZG dd„ dƒZedd„ ƒZdd„ Zdd „ Zdnd"d#„Zed$d%„ ƒZed&d'„ ƒZed(d)„ ƒZed*d+„ ƒZd,d-„ Zed.d/„ ƒZed0d1„ ƒZd2d3„ Zd4d5„ Zd6d7„ Zd8dœd9d:„Z d;d<„ Z!d=d>„ Z"‡ fd?d@„Z#‡ fdAdB„Z$‡ fdCdD„Z%dEdF„ Z&dGdH„ Z'‡ fdIdJ„Z(dKdLde)fddMdNœdOdP„Z*dodQdR„Z+dpdSdT„Z,dqdUdV„Z-dWdX„ Z.dYdZ„ Z/e0d[d\„ ƒZ1d]d^d_œd`da„Z2dbdc„ Z3ddde„ Z4dfdg„ Z5dhdi„ Z6e0djdk„ ƒZ7dldm„ Z8‡  Z9S )rr   uB  
    Args:
        data (#ak.contents.Content, #ak.Array, `np.ndarray`, `cp.ndarray`, `pyarrow.*`, str, dict, or iterable):
            Data to wrap or convert into an array.
               - If a NumPy array, the regularity of its dimensions is preserved
                 and the data are viewed, not copied.
               - CuPy arrays are treated the same way as NumPy arrays except that
                 they default to `backend="cuda"`, rather than `backend="cpu"`.
               - If a pyarrow object, calls #ak.from_arrow, preserving as much
                 metadata as possible, usually zero-copy.
               - If a dict of str â†’ columns, combines the columns into an
                 array of records (like Pandas's DataFrame constructor).
               - If a string, the data are assumed to be JSON.
               - If an iterable, calls #ak.from_iter, which assumes all dimensions
                 have irregular lengths.
        behavior (None or dict): Custom #ak.behavior for this Array only.
        with_name (None or str): Gives tuples and records a name that can be
            used to override their behavior (see below).
        check_valid (bool): If True, verify that the #layout is valid.
        backend (None, `"cpu"`, `"jax"`, `"cuda"`): If `"cpu"`, the Array will be placed in
            main memory for use with other `"cpu"` Arrays and Records; if `"cuda"`,
            the Array will be placed in GPU global memory using CUDA; if `"jax"`, the structure
            is copied to the CPU for use with JAX. if None, the `data` are left untouched.

    High-level array that can contain data of any type.

    For most users, this is the only class in Awkward Array that matters: it
    is the entry point for data analysis with an emphasis on usability. It
    intentionally has a minimum of methods, preferring standalone functions
    like

        ak.num(array1)
        ak.combinations(array1)
        ak.cartesian([array1, array2])
        ak.zip({"x": array1, "y": array2, "z": array3})

    instead of bound methods like

        array1.num()
        array1.combinations()
        array1.cartesian([array2, array3])
        array1.zip(...)   # ?

    because its namespace is valuable for domain-specific parameters and
    functionality. For example, if records contain a field named `"num"`,
    they can be accessed as

        array1.num

    instead of

        array1["num"]

    without any confusion or interference from #ak.num. The same is true
    for domain-specific methods that have been attached to the data. For
    instance, an analysis of mailing addresses might have a function that
    computes zip codes, which can be attached to the data with a method
    like

        latlon.zip()

    without any confusion or interference from #ak.zip. Custom methods like
    this can be added with #ak.behavior, and so the namespace of Array
    attributes must be kept clear for such applications.

    See also #ak.Record.

    Interfaces to other libraries
    =============================

    NumPy
    *****

    When NumPy
    [universal functions](https://docs.scipy.org/doc/numpy/reference/ufuncs.html)
    (ufuncs) are applied to an ak.Array, they are passed through the Awkward
    data structure, applied to the numerical data at its leaves, and the output
    maintains the original structure.

    For example,

        >>> array = ak.Array([[1, 4, 9], [], [16, 25]])
        >>> np.sqrt(array)
        <Array [[1, 2, 3], [], [4, 5]] type='3 * var * float64'>

    See also #ak.Array.__array_ufunc__.

    Some NumPy functions other than ufuncs are also handled properly in
    NumPy >= 1.17 (see
    [NEP 18](https://numpy.org/neps/nep-0018-array-function-protocol.html))
    and if an Awkward override exists. That is,

        np.concatenate

    can be used on an Awkward Array because

        ak.concatenate

    exists.

    Pandas
    ******

    Ragged arrays (list type) can be converted into Pandas
    [MultiIndex](https://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html)
    rows and nested records can be converted into MultiIndex columns. If the
    Awkward Array has only one "branch" of nested lists (i.e. different record
    fields do not have different-length lists, but a single chain of lists-of-lists
    is okay), then it can be losslessly converted into a single DataFrame.
    Otherwise, multiple DataFrames are needed, though they can be merged (with a
    loss of information).

    The #ak.to_dataframe function performs this conversion; if `how=None`, it
    returns a list of DataFrames; otherwise, `how` is passed to `pd.merge` when
    merging the resultant DataFrames.

    Numba
    *****

    Arrays can be used in [Numba](http://numba.pydata.org/): they can be
    passed as arguments to a Numba-compiled function or returned as return
    values. The only limitation is that Awkward Arrays cannot be *created*
    inside the Numba-compiled function; to make outputs, consider
    #ak.ArrayBuilder.

    Arrow
    *****

    Arrays are convertible to and from [Apache Arrow](https://arrow.apache.org/),
    a standard for representing nested data structures in columnar arrays.
    See #ak.to_arrow and #ak.from_arrow.

    JAX
    ********

    Derivatives of a calculation on an #ak.Array (s) can be calculated with
    [JAX](https://github.com/google/jax#readme), but only if the array
    functions in `ak` / `numpy` are used, not the functions in the `jax`
    library directly (apart from e.g. `jax.grad`).

    Like NumPy ufuncs, the function and its derivatives are evaluated on the
    numeric leaves of the data structure, maintaining structure in the output.
    NF©ÚbehaviorÚ	with_nameÚcheck_validÚbackendÚattrsc                C  sò  d | _ t|tjjƒr|}nêt|tƒrD|j}t||d�}t||d�}nÀt|t	ƒrÔg }g }	d }
| 
¡ D ]`\}}| |¡ |	 t|ƒj¡ |
d u r˜|	d j}
qb|
|	d jkrbtd|
› d|	d j› d�ƒ‚qbtj |	|¡}n0t|tƒrðtjj|dd�}ntjj|ddd	d
�}t|tjjƒ�stdƒ‚|d u�r<tjj||d||d�}|d u �sf||jjk�sftjj||dd�}|d u�r„t|tƒ�s„tdƒ‚|d u�r¢t|tƒ�s¢tdƒ‚|| _|| _|| _| d¡}t|tƒ�rÐ|| _|  ¡  |�rîtjj| dd� d S )N)ra   )re   éÿÿÿÿzIdict of arrays in ak.Array constructor must have arrays of equal length (z vs ú)F©Ú	highlevelÚerror)Zallow_recordZregulararrayZprimitive_policyz'could not convert data into an ak.Array©ri   ra   re   z"behavior must be None or a mappingzattrs must be None or a mappingÚ__doc__T©Ú	exception) Ú	_cpp_typerK   rL   rJ   ÚContentr   Ú_layoutr   r   ÚdictÚitemsÚappendrS   ÚlengthÚ
ValueErrorÚRecordArrayr6   Ú
operationsÚ	from_jsonZ	to_layoutÚ	TypeErrorrb   rd   ÚnameÚ
to_backendr   Ú	_behaviorÚ_attrsÚpurelist_parameterrl   Ú_update_classÚvalidity_error)r)   r]   ra   rb   rc   rd   re   rS   ÚfieldsrJ   ru   ÚkÚvÚdocstrr-   r-   r.   Ú__init__  sf    



ÿÿÿ
ÿ

ÿ
zArray.__init__c                   s"   t ƒ jf i |¤Ž tj | ¡ d S r<   ©ÚsuperÚ__init_subclass__rL   ZjaxZregister_behavior_class©ÚclsÚkwargs©Ú	__class__r-   r.   r‰   Y  s    zArray.__init_subclass__c                 C  s   t | ƒS r<   )Úid©r)   r-   r-   r.   Ú__dask_tokenize__`  s    zArray.__dask_tokenize__c                 C  s   d | _ t| j| jƒ| _d S r<   )Ú
_numbaviewr   rq   r}   rŽ   r�   r-   r-   r.   r€   c  s    zArray._update_classúMapping[str, Any]©r;   c                 C  s   | j du ri | _ | j S )a0  
        The mutable mapping containing top-level metadata, which is serialised
        with the array during pickling.

        Keys prefixed with `@` are identified as "transient" attributes
        which are discarded prior to pickling, permitting the storage of
        non-pickleable types.
        N©r~   r�   r-   r-   r.   re   g  s    

zArray.attrs©Úvaluec                 C  s   t |tƒr|| _ntdƒ‚d S ©Nzattrs must be a mapping©rK   r   r~   rz   ©r)   r—   r-   r-   r.   re   u  s    
c                 C  s   | j S )a†  
        The composable #ak.contents.Content elements that determine how this
        Array is structured.

        This may be considered a "low-level" view, as it distinguishes between
        arrays that have the same logical meaning (i.e. same JSON output and
        high-level #type) but different

        * node types, such as #ak.contents.ListArray and
             #ak.contents.ListOffsetArray,
        * integer type specialization, such as `int64` vs `int32`
        * or specific values, such as gaps in a #ak.contents.ListArray.

        The #ak.contents.Content elements are fully composable, whereas an
        Array is not; the high-level Array is a single-layer "shell" around
        its layout.

        Layouts are rendered as XML instead of a nested list. For example,
        the following `array`

            ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]])

        is presented as

            <Array [[1.1, 2.2, 3.3], [], [4.4, 5.5]] type='3 * var * float64'>

        but `array.layout` is presented as

            <ListOffsetArray len='3'>
                <offsets><Index dtype='int64' len='4'>
                    [0 3 3 5]
                </Index></offsets>
                <content>
                    <NumpyArray dtype='float64' len='5'>[1.1 2.2 3.3 4.4 5.5]</NumpyArray>
                </content>
            </ListOffsetArray>

        (with truncation for large arrays).
        ©rq   r�   r-   r-   r.   rS   |  s    )zArray.layoutc                 C  s*   t |tjjƒr|| _|  ¡  ntdƒ‚d S )Nz0layout must be a subclass of ak.contents.Content)rK   rL   rJ   rp   rq   r€   rz   ©r)   rS   r-   r-   r.   rS   §  s    
c                 C  s   | j S )a‚  
        The `behavior` parameter passed into this Array's constructor.

        * If a dict, this `behavior` overrides the global #ak.behavior.
             Any keys in the global #ak.behavior but not this `behavior` are
             still valid, but any keys in both are overridden by this
             `behavior`. Keys with a None value are equivalent to missing keys,
             so this `behavior` can effectively remove keys from the
             global #ak.behavior.

        * If None, the Array defaults to the global #ak.behavior.

        See #ak.behavior for a list of recognized key patterns and their
        meanings.
        ©r}   r�   r-   r-   r.   ra   ¯  s    zArray.behaviorc                 C  s.   |d u st |tƒr"|| _|  ¡  ntdƒ‚d S ©Nzbehavior must be None or a dict©rK   r   r}   r€   rz   ©r)   ra   r-   r-   r.   ra   Â  s    
c                   @  s   e Zd Zdd„ Zdd„ ZdS )z
Array.Maskc                 C  s
   || _ d S r<   )Ú_array)r)   Úarrayr-   r-   r.   r†   Ë  s    zArray.Mask.__init__c                 C  sP   t jjd| j|gi d��$ t jj| j|dd�W  d   ƒ S 1 sB0    Y  d S )Nzak.Array.mask)ÚargsrŒ   T)Z
valid_when)rL   Ú_errorsÚOperationErrorContextr¡   rx   Úmask©r)   Úwherer-   r-   r.   Ú__getitem__Î  s    ÿzArray.Mask.__getitem__N)Ú__name__Ú
__module__Ú__qualname__r†   r©   r-   r-   r-   r.   ÚMaskÊ  s   r­   c                 C  s
   |   | ¡S )aë  
        Whereas

            array[array_of_booleans]

        removes elements from `array` in which `array_of_booleans` is False,

            array.mask[array_of_booleans]

        returns data with the same length as the original `array` but False
        values in `array_of_booleans` are mapped to None. Such an output
        can be used in mathematical expressions with the original `array`
        because they are still aligned.

        See <<<filtering>>> and #ak.mask.
        )r­   r�   r-   r-   r.   r¦   Ô  s    z
Array.maskc                 C  s   |   ¡ S ©zã
        Converts this Array into Python objects; same as #ak.to_list
        (but without the underscore, like NumPy's
        [tolist](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.tolist.html)).
        ©Úto_listr�   r-   r-   r.   Útolistè  s    zArray.tolistc                 C  s   | j  | j¡S ©zO
        Converts this Array into Python objects; same as #ak.to_list.
        ©rq   r°   r}   r�   r-   r-   r.   r°   ð  s    zArray.to_listTc                 C  s   t jj| |d�S ©z\
        Converts this Array into a NumPy array, if possible; same as #ak.to_numpy.
        )Úallow_missing)rL   rx   Úto_numpy©r)   rµ   r-   r-   r.   r¶   ö  s    zArray.to_numpyc                 C  s   | j jS )ak  
        The total number of bytes in all the #ak.index.Index,
        and #ak.contents.NumpyArray buffers in this array tree.

        It does not count buffers that must be kept in memory because
        of ownership, but are not directly used in the array. Nor does it count
        the (small) Python objects that reference the (large) array buffers.
        ©rq   Únbytesr�   r-   r-   r.   r¹   ü  s    
zArray.nbytesc                 C  s   | j jS )a{  
        Number of dimensions (nested variable-length lists and/or regular arrays)
        before reaching a numeric type or a record.

        There may be nested lists within the record, as field values, but this
        number of dimensions does not count those.

        (Some fields may have different depths than others, which is why they
        are not counted.)
        )rq   Zpurelist_depthr�   r-   r-   r.   Úndim  s    z
Array.ndimc                 C  s   | j jS )a,  
        List of field names or tuple slot numbers (as strings) of the outermost
        record or tuple in this array.

        If the array contains nested records, only the fields of the outermost
        record are shown. If it contains tuples instead of records, its fields
        are string representations of integers, such as `"0"`, `"1"`, `"2"`, etc.
        The records or tuples may be within multiple layers of nested lists.

        If the array contains neither tuples nor records, it is an empty list.

        See also #ak.fields.
        ©rq   r‚   r�   r-   r-   r.   r‚     s    zArray.fieldsc                 C  s   | j jS ©z`
        If True, the top-most record structure has no named fields, i.e. it's a tuple.
        )rq   Úis_tupler�   r-   r-   r.   r½   '  s    zArray.is_tuplec                 C  s   | j jS r<   r»   r�   r-   r-   r.   Ú_ipython_key_completions_.  s    zArray._ipython_key_completions_c                 C  s   t j | jjj| jj| j¡S )aW  
        The high-level type of this Array; same as #ak.type.

        Note that the outermost element of an Array's type is always an
        #ak.types.ArrayType, which specifies the number of elements in the array.

        The type of a #ak.contents.Content (from #ak.Array.layout) is not
        wrapped by an #ak.types.ArrayType.
        )rL   ÚtypesÚ	ArrayTyperq   rP   Útyperu   r}   r�   r-   r-   r.   rÁ   1  s
    ýz
Array.typec                 C  s
   t | jƒS )zK
        The high-level type of this Array, presented as a string.
        ©r6   rÁ   r�   r-   r-   r.   ÚtypestrB  s    zArray.typestrc                 C  s   | j jS )zÉ
        The length of this Array, only counting the outermost structure.

        For example, the length of

            ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]])

        is `3`, not `5`.
        )rq   ru   r�   r-   r-   r.   Ú__len__I  s    
zArray.__len__c                 c  s*   | j D ]}tt|ƒ| jd| jd�V  qdS )a¬  
        Iterates over this Array in Python.

        Note that this is the *slowest* way to access data (even slower than
        native Python objects, like lists and dicts). Usually, you should
        express your problems in array-at-a-time operations.

        In other words, do this:

            >>> np.sqrt(ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]]))
            <Array [[1.05, 1.48, 1.82], [], [2.1, 2.35]] type='3 * var * float64'>

        not this:

            >>> for outer in ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]]):
            ...     for inner in outer:
            ...         print(np.sqrt(inner))
            ...
            1.0488088481701516
            1.4832396974191326
            1.816590212458495
            2.0976176963403033
            2.345207879911715

        Iteration over Arrays exists so that they can be more easily inspected
        as Python objects.

        See also #ak.to_list.
        T©Zallow_otherre   N)rq   r   r_   r}   r~   )r)   Úitemr-   r-   r.   Ú__iter__U  s    
üzArray.__iter__c                 C  sP   t j | |¡�. tt| j| ƒ| jd| jd�W  d  ƒ S 1 sB0    Y  dS )aCI  
        Args:
            where (many types supported; see below): Index of positions to
                select from this Array.

        Select items from the Array using an extension of NumPy's (already
        quite extensive) rules.

        All methods of selecting items described in
        [NumPy indexing](https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html)
        are supported with one exception
        ([combining advanced and basic indexing](https://numpy.org/doc/stable/user/basics.indexing.html#combining-advanced-and-basic-indexing)
        with basic indexes *between* two advanced indexes: the definition
        NumPy chose for the result does not have a generalization beyond
        rectilinear arrays).

        The `where` parameter can be any of the following or a tuple of
        the following.

        * **An integer** selects one element. Like Python/NumPy, it is
          zero-indexed: `0` is the first item, `1` is the second, etc.
          Negative indexes count from the end of the list: `-1` is the
          last, `-2` is the second-to-last, etc.
          Indexes beyond the size of the array, either because they're too
          large or because they're too negative, raise errors. In
          particular, some nested lists might contain a desired element
          while others don't; this would raise an error.
        * **A slice** (either a Python `slice` object or the
          `start:stop:step` syntax) selects a range of elements. The
          `start` and `stop` values are zero-indexed; `start` is inclusive
          and `stop` is exclusive, like Python/NumPy. Negative `step`
          values are allowed, but a `step` of `0` is an error. Slices
          beyond the size of the array are not errors but are truncated,
          like Python/NumPy.
        * **A string** selects a tuple or record field, even if its
          position in the tuple is to the left of the dimension where the
          tuple/record is defined. (See <<<projection>>> below.) This is
          similar to NumPy's
          [field access](https://numpy.org/doc/stable/user/basics.indexing.html#field-access),
          except that strings are allowed in the same tuple with other
          slice types. While record fields have names, tuple fields are
          integer strings, such as `"0"`, `"1"`, `"2"` (always
          non-negative). Be careful to distinguish these from non-string
          integers.
        * **An iterable of strings** (not the top-level tuple) selects
          multiple tuple/record fields.
        * **An ellipsis** (either the Python `Ellipsis` object or the
          `...` syntax) skips as many dimensions as needed to put the
          rest of the slice items to the innermost dimensions.
        * **A np.newaxis** or its equivalent, None, does not select items
          but introduces a new regular dimension in the output with size
          `1`. This is a convenient way to explicitly choose a dimension
          for broadcasting.
        * **A boolean array** with the same length as the current dimension
          (or any iterable, other than the top-level tuple) selects elements
          corresponding to each True value in the array, dropping those
          that correspond to each False. The behavior is similar to
          NumPy's
          [compress](https://docs.scipy.org/doc/numpy/reference/generated/numpy.compress.html)
          function.
        * **An integer array** (or any iterable, other than the top-level
          tuple) selects elements like a single integer, but produces a
          regular dimension of as many as are desired. The array can have
          any length, any order, and it can have duplicates and incomplete
          coverage. The behavior is similar to NumPy's
          [take](https://docs.scipy.org/doc/numpy/reference/generated/numpy.take.html)
          function.
        * **An integer Array with missing (None) items** selects multiple
          values by index, as above, but None values are passed through
          to the output. This behavior matches pyarrow's
          [Array.take](https://arrow.apache.org/docs/python/generated/pyarrow.Array.html#pyarrow.Array.take)
          which also manages arrays with missing values. See
          <<<option indexing>>> below.
        * **An Array of nested lists**, ultimately containing booleans or
          integers and having the same lengths of lists at each level as
          the Array to which they're applied, selects by boolean or by
          integer at the deeply nested level. Missing items at any level
          above the deepest level must broadcast. See <<<nested indexing>>> below.

        A tuple of the above applies each slice item to a dimension of the
        data, which can be very expressive. More than one flat boolean/integer
        array are "iterated as one" as described in the
        [NumPy documentation](https://numpy.org/doc/stable/user/basics.indexing.html#integer-array-indexing).

        Filtering
        *********

        A common use of selection by boolean arrays is to filter a dataset by
        some property. For instance, to get the odd values of

            >>> array = ak.Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

        one can put an array expression with True for each odd value inside
        square brackets:

            >>> array[array % 2 == 1]
            <Array [1, 3, 5, 7, 9] type='5 * int64'>

        This technique is so common in NumPy and Pandas data analysis that it
        is often read as a syntax, rather than a consequence of array slicing.

        The extension to nested arrays like

            >>> array = ak.Array([[[0, 1, 2], [], [3, 4], [5]], [[6, 7, 8], [9]]])

        allows us to use the same syntax more generally.

            >>> array[array % 2 == 1]
            <Array [[[1], [], [3], [5]], [[7], [9]]] type='2 * var * var * int64'>

        In this example, the boolean array is itself nested (see
        <<<nested indexing>>> below).

            >>> array % 2 == 1
            <Array [[[False, True, False], ..., [True]], ...] type='2 * var * var * bool'>

        This also applies to data with record structures.

        For nested data, we often need to select the first or first two
        elements from variable-length lists. That can be a problem if some
        lists are empty. A function like #ak.num can be useful for first
        selecting by the lengths of lists.

            >>> array = ak.Array([[1.1, 2.2, 3.3],
            ...                   [],
            ...                   [4.4, 5.5],
            ...                   [6.6],
            ...                   [],
            ...                   [7.7, 8.8, 9.9]])
            ...
            >>> array[ak.num(array) > 0, 0]
            <Array [1.1, 4.4, 6.6, 7.7] type='4 * float64'>
            >>> array[ak.num(array) > 1, 1]
            <Array [2.2, 5.5, 8.8] type='3 * float64'>

        It's sometimes also a problem that "cleaning" the dataset by dropping
        empty lists changes its alignment, so that it can no longer be used
        in calculations with "uncleaned" data. For this, #ak.mask can be
        useful because it inserts None in positions that fail the filter,
        rather than removing them.

            >>> ak.mask(array, ak.num(array) > 1)
            <Array [[1.1, 2.2, 3.3], ..., [7.7, ..., 9.9]] type='6 * option[var * float64]'>

        Note, however, that the `0` or `1` to pick the first or second
        item of each nested list is in the second dimension, so the first
        dimension of the slice must be a `:`.

            >>> ak.mask(array, ak.num(array) > 1)[:, 0]
            <Array [1.1, None, 4.4, None, None, 7.7] type='6 * ?float64'>
            >>> ak.mask(array, ak.num(array) > 1)[:, 1]
            <Array [2.2, None, 5.5, None, None, 8.8] type='6 * ?float64'>

        Another syntax for

            ak.mask(array, array_of_booleans)

        is

            array.mask[array_of_booleans]

        (which is 5 characters away from simply filtering the `array`).

        Projection
        **********

        The following

            >>> array = ak.Array([[{"x": 1.1, "y": [1]}, {"x": 2.2, "y": [2, 2]}],
            ...                   [{"x": 3.3, "y": [3, 3, 3]}],
            ...                   [{"x": 0, "y": []}, {"x": 1.1, "y": [1, 1, 1]}]])

        has records inside of nested lists:

            >>> array.type.show()
            3 * var * {
                x: float64,
                y: var * int64
            }

        In principle, one should select nested lists before record fields,

            >>> array[2, :, "x"]
            <Array [0, 1.1] type='2 * float64'>
            >>> array[::2, :, "x"]
            <Array [[1.1, 2.2], [0, 1.1]] type='2 * var * float64'>

        but it's also possible to select record fields first.

            >>> array["x"]
            <Array [[1.1, 2.2], [3.3], [0, 1.1]] type='3 * var * float64'>

        The string can "commute" to the left through integers and slices to
        get the same result as it would in its "natural" position.

            >>> array[2, :, "x"]
            <Array [0, 1.1] type='2 * float64'>
            >>> array[2, "x", :]
            <Array [0, 1.1] type='2 * float64'>
            >>> array["x", 2, :]
            <Array [0, 1.1] type='2 * float64'>

        The is analogous to selecting rows (integer indexes) before columns
        (string names) or columns before rows, except that the rows are
        more complex (like a Pandas
        [MultiIndex](https://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html)).
        This would be an expensive operation in a typical object-oriented
        environment, in which the records with fields `"x"` and `"y"` are
        akin to C structs, but for columnar Awkward Arrays, projecting
        through all records to produce an array of nested lists of `"x"`
        values just changes the metadata (no loop over data, and therefore
        fast).

        Thus, data analysts should think of records as fluid objects that
        can be easily projected apart and zipped back together with
        #ak.zip.

        Note, however, that while a column string can "commute" with row
        indexes to the left of its position in the tree, it can't commute
        to the right. For example, it's possible to use slices inside
        `"y"` because `"y"` is a list:

            >>> array[0, :, "y"]
            <Array [[1], [2, 2]] type='2 * var * int64'>
            >>> array[0, :, "y", 0]
            <Array [1, 2] type='2 * int64'>

        but it's not possible to move `"y"` to the right

            >>> array[0, :, 0, "y"]
            IndexError: while attempting to slice
                <Array [[{x: 1.1, y: [1]}, {...}], ...] type='3 * var * {x: float64, y:...'>
            with
                (0, :, 0, 'y')
            at inner NumpyArray of length 2, using sub-slice (0).

        because the `array[0, :, 0, ...]` slice applies to both `"x"` and
        `"y"` before `"y"` is selected, and `"x"` is a one-dimensional
        NumpyArray that can't take more than its share of slices.

        Finally, note that the dot (`__getattr__`) syntax is equivalent to a single
        string in a slice (`__getitem__`) if the field name is a valid Python
        identifier and doesn't conflict with #ak.Array methods or properties.

            >>> array.x
            <Array [[1.1, 2.2], [3.3], [0, 1.1]] type='3 * var * float64'>
            >>> array.y
            <Array [[[1], [2, 2]], ..., [[], [1, ...]]] type='3 * var * var * int64'>

        Nested Projection
        *****************

        If records are nested within records, you can use a series of strings in
        the selector to drill down. For instance, with the following

            >>> array = ak.Array([
            ...     {"a": {"x": 1, "y": 2}, "b": {"x": 10, "y": 20}, "c": {"x": 1.1, "y": 2.2}},
            ...     {"a": {"x": 1, "y": 2}, "b": {"x": 10, "y": 20}, "c": {"x": 1.1, "y": 2.2}},
            ...     {"a": {"x": 1, "y": 2}, "b": {"x": 10, "y": 20}, "c": {"x": 1.1, "y": 2.2}}])

        we can go directly to the numerical data by specifying a string for the
        outer field and a string for the inner field.

            >>> array["a", "x"]
            <Array [1, 1, 1] type='3 * int64'>
            >>> array["a", "y"]
            <Array [2, 2, 2] type='3 * int64'>
            >>> array["b", "y"]
            <Array [20, 20, 20] type='3 * int64'>
            >>> array["c", "y"]
            <Array [2.2, 2.2, 2.2] type='3 * float64'>

        As with single projections, the dot (`__getattr__`) syntax is equivalent
        to a single string in a slice (`__getitem__`) if the field name is a valid
        Python identifier and doesn't conflict with #ak.Array methods or properties.

            >>> array.a.x
            <Array [1, 1, 1] type='3 * int64'>

        You can even get every field of the same name within an outer record using
        a list of field names for the outer record. The following selects the `"x"`
        field of `"a"`, `"b"`, and `"c"` records:

            >>> array[["a", "b", "c"], "x"].show()
            [{a: 1, b: 10, c: 1.1},
             {a: 1, b: 10, c: 1.1},
             {a: 1, b: 10, c: 1.1}]

        You don't need to get all fields:

            >>> array[["a", "b"], "x"].show()
            [{a: 1, b: 10},
             {a: 1, b: 10},
             {a: 1, b: 10}]

        And you can select lists of field names at all levels:

            >>> array[["a", "b"], ["x", "y"]].show()
            [{a: {x: 1, y: 2}, b: {x: 10, y: 20}},
             {a: {x: 1, y: 2}, b: {x: 10, y: 20}},
             {a: {x: 1, y: 2}, b: {x: 10, y: 20}}]

        Option indexing
        ***************

        NumPy arrays can be sliced by all of the above slice types except
        arrays with missing values and arrays with nested lists, both of
        which are inexpressible in NumPy. Missing values, represented by
        None in Python, are called option types (#ak.types.OptionType) in
        Awkward Array and can be used as a slice.

        For example,

            >>> array = ak.Array([1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9])

        can be sliced with a boolean array

            >>> array[[False, False, False, False, True, False, True, False, True]]
            <Array [5.5, 7.7, 9.9] type='3 * float64'>

        or a boolean array containing None values:

            >>> array[[False, False, False, False, True, None, True, None, True]]
            <Array [5.5, None, 7.7, None, 9.9] type='5 * ?float64'>

        Similarly for arrays of integers and None:

            >>> array[[0, 1, None, None, 7, 8]]
            <Array [1.1, 2.2, None, None, 8.8, 9.9] type='6 * ?float64'>

        This is the same behavior as pyarrow's
        [Array.take](https://arrow.apache.org/docs/python/generated/pyarrow.Array.html#pyarrow.Array.take),
        which establishes a convention for how to interpret slice arrays
        with option type:

            >>> import pyarrow as pa
            >>> array = pa.array([1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9])
            >>> array.take(pa.array([0, 1, None, None, 7, 8]))
            <pyarrow.lib.DoubleArray object at 0x7efc7f060210>
            [
              1.1,
              2.2,
              null,
              null,
              8.8,
              9.9
            ]

        Nested indexing
        ***************

        Awkward Array's nested lists can be used as slices as well, as long
        as the type at the deepest level of nesting is boolean or integer.

        For example,

            >>> array = ak.Array([[[0.0, 1.1, 2.2], [], [3.3, 4.4]], [], [[5.5]]])

        can be sliced at the top level with one-dimensional arrays:

            >>> array[[False, True, True]]
            <Array [[], [[5.5]]] type='2 * var * var * float64'>
            >>> array[[1, 2]]
            <Array [[], [[5.5]]] type='2 * var * var * float64'>

        with singly nested lists:

            >>> array[[[False, True, True], [], [True]]]
            <Array [[[], [3.3, 4.4]], [], [[5.5]]] type='3 * var * var * float64'>
            >>> array[[[1, 2], [], [0]]]
            <Array [[[], [3.3, 4.4]], [], [[5.5]]] type='3 * var * var * float64'>

        and with doubly nested lists:

            >>> array[[[[False, True, False], [], [True, False]], [], [[False]]]]
            <Array [[[1.1], [], [3.3]], [], [[]]] type='3 * var * var * float64'>
            >>> array[[[[1], [], [0]], [], [[]]]]
            <Array [[[1.1], [], [3.3]], [], [[]]] type='3 * var * var * float64'>

        The key thing is that the nested slice has the same number of elements
        as the array it's slicing at every level of nesting that it reproduces.
        This is similar to the requirement that boolean arrays have the same
        length as the array they're filtering.

        This kind of slicing is useful because NumPy's
        [universal functions](https://docs.scipy.org/doc/numpy/reference/ufuncs.html)
        produce arrays with the same structure as the original array, which
        can then be used as filters.

            >>> ((array * 10) % 2 == 1).show()
            [[[False, True, False], [], [True, False]],
             [],
             [[True]]]
            >>> (array[(array * 10) % 2 == 1]).show()
            [[[1.1], [], [3.3]],
             [],
             [[5.5]]]

        Functions whose names start with "arg" return index positions, which
        can be used with the integer form.

            >>> np.argmax(array, axis=-1).show()
            [[2, None, 1],
             [],
             [0]]
            >>> array[np.argmax(array, axis=-1)].show()
            [[[3.3, 4.4], None, []],
             [],
             [[5.5]]]

        Here, the `np.argmax` returns the integer position of the maximum
        element or None for empty arrays. It's a nice example of
        <<<option indexing>>> with <<<nested indexing>>>.

        When applying a nested index with missing (None) entries at levels
        higher than the last level, the indexer must have the same dimension
        as the array being indexed, and the resulting output will have missing
        entries at the corresponding locations, e.g. for

            >>> array[ [[[0, None, 2, None, None], None, [1]], None, [[0]]] ].show()
            [[[0, None, 2.2, None, None], None, [4.4]],
             None,
             [[5.5]]]

        the sub-list at entry 0,0 is extended as the masked entries are
        acting at the last level, while the higher levels of the indexer all
        have the same dimension as the array being indexed.
        TrÅ   N©rL   r¤   ZSlicingErrorContextr   r_   rq   r}   r~   r§   r-   r-   r.   r©   {  s       0üzArray.__getitem__Úbytesc                 C  s@   t | jtjjƒr0| j d¡dv r0tj | jj¡S t	t
| ƒƒS d S )NrT   >   rV   rU   )rK   rq   rL   rJ   rY   rZ   r[   r\   r]   rÉ   Úiterr�   r-   r-   r.   Ú	__bytes__0  s    ÿþzArray.__bytes__c              	   C  s�   t j d| f||dœ¡�d t|tƒsHt|tƒr@tdd„ |D ƒƒsHtdƒ‚t jj	| j
||d| j| jd�| _
d| _W d  ƒ n1 s‚0    Y  dS )	a  
        Args:
            where (str or tuple of str): Field name to add to records in the array.
            what (#ak.Array): Array to add as the new field.

        Unlike #__getitem__, which allows a wide variety of slice types,
        only single field-slicing is supported for assignment.
        (#ak.contents.Content arrays are immutable; field assignment replaces
        the #layout with an array that has the new field using #ak.with_field.)

        However, a field can be assigned deeply into a nested record e.g.

            >>> nested = ak.zip({"a" : ak.zip({"x" : [1, 2, 3]})})
            >>> nested["a", "y"] = 2 * nested.a.x
            >>> nested.show()
            [{a: {x: 1, y: 2}},
             {a: {x: 2, y: 4}},
             {a: {x: 3, y: 6}}]

        Note that the following does **not** work:

            >>> nested["a"]["y"] = 2 * nested.a.x # does not work, nested["a"] is a copy!

        Always assign by passing the whole path to the top level

            >>> nested["a", "y"] = 2 * nested.a.x

        If necessary, the new field will be broadcasted to fit the array.
        For example, given

            >>> array = ak.Array([
            ...     [{"x": 1.1}, {"x": 2.2}, {"x": 3.3}], [], [{"x": 4.4}, {"x": 5.5}]
            ... ])

        which has three elements with nested data in each, assigning

            >>> array["y"] = [100, 200, 300]

        will result in

            >>> array.show()
            [[{x: 1.1, y: 100}, {x: 2.2, y: 100}, {x: 3.3, y: 100}],
             [],
             [{x: 4.4, y: 300}, {x: 5.5, y: 300}]]

        because the `100` in `what[0]` is broadcasted to all three nested
        elements of `array[0]`, the `200` in `what[1]` is broadcasted to the
        empty list `array[1]`, and the `300` in `what[2]` is broadcasted to
        both elements of `array[2]`.

        See #ak.with_field for a variant that does not change the #ak.Array
        in-place. (Internally, this method uses #ak.with_field, so performance
        is not a factor in choosing one over the other.)
        zak.Array.__setitem__©r¨   Úwhatc                 s  s   | ]}t |tƒV  qd S r<   ©rK   r6   ©rE   Úxr-   r-   r.   Ú	<genexpr>v  rI   z$Array.__setitem__.<locals>.<genexpr>ú4only fields may be assigned in-place (by field name)F)ri   re   ra   N)rL   r¤   r¥   rK   r6   ÚtupleÚallrz   rx   Z
with_fieldrq   r~   r}   r’   ©r)   r¨   rÍ   r-   r-   r.   Ú__setitem__8  s*    7ýÿþþúzArray.__setitem__c                 C  sŽ   t j d| fd|i¡�d t|tƒsFt|tƒr>tdd„ |D ƒƒsFtdƒ‚t jj	j
| j|d| j| jd�| _d| _W d  ƒ n1 s€0    Y  dS )	a  
        Args:
            where (str or tuple of str): Field name to remove from the array.

        For example:

            >>> array = ak.Array([{"x": 3.3, "y": {"this": 10, "that": 20}}])
            >>> del array["y", "that"]
            >>> array.show()
            [{x: 3.3, y: {this: 10}}]

        See #ak.without_field for a variant that does not change the #ak.Array
        in-place. (Internally, this method uses #ak.without_field, so performance
        is not a factor in choosing one over the other.)
        zak.Array.__delitem__r¨   c                 s  s   | ]}t |tƒV  qd S r<   rÎ   rÏ   r-   r-   r.   rÑ   ›  rI   z$Array.__delitem__.<locals>.<genexpr>ú3only fields may be removed in-place (by field name)Frk   N©rL   r¤   r¥   rK   r6   rÓ   rÔ   rz   rx   Zak_without_fieldÚ_implrq   r}   r~   r’   r§   r-   r-   r.   Ú__delitem__„  s(    ýÿþþûzArray.__delitem__c              
     sŠ   t t| ƒ|ƒrtƒ  |¡S || jjv rxz
| | W S  tyt } z,td|›dt|ƒ› d|›�ƒ|‚W Y d}~q†d}~0 0 ntd|›�ƒ‚dS )aÑ  
        Args:
            where (str): Attribute name to lookup

        Whenever possible, fields can be accessed as attributes.

        For example, the fields of

            >>> array = ak.Array([
            ...     [{"x": 1.1, "y": [1]}, {"x": 2.2, "y": [2, 2]}, {"x": 3.3, "y": [3, 3, 3]}],
            ...     [],
            ...     [{"x": 4.4, "y": [4, 4, 4, 4]}, {"x": 5.5, "y": [5, 5, 5, 5, 5]}]
            ... ])

        can be accessed as

            >>> array.x
            <Array [[1.1, 2.2, 3.3], [], [4.4, 5.5]] type='3 * var * float64'>
            >>> array.y
            <Array [[[1], [2, 2], [3, 3, 3]], [], [...]] type='3 * var * var * int64'>

        which are equivalent to `array["x"]` and `array["y"]`. (See
        <<<projection>>>.)

        Fields can't be accessed as attributes when

        * #ak.Array methods or properties take precedence,
        * a domain-specific behavior has methods or properties that take
             precedence, or
        * the field name is not a valid Python identifier or is a Python
             keyword.

        Note that while fields can be accessed as attributes, they cannot be
        *assigned* as attributes. See #ak.Array.__setitem__ for more.
        úwhile trying to get field ú, an exception occurred:
ú: Núno field named ©r"   rÁ   rˆ   Ú__getattribute__rq   r‚   Ú	ExceptionÚAttributeError©r)   r¨   Úerrr�   r-   r.   Ú__getattr__¨  s     $
ÿÿÿýzArray.__getattr__c                   sJ   |  d¡stt| ƒ|ƒr(tƒ  ||¡ n|| jjv r>tdƒ‚ntdƒ‚dS )a<  
        Args:
            where (str): Attribute name to set

        Set an attribute on the array.

        Only existing public attributes e.g. #ak.Array.layout, or private
        attributes (with leading underscores), can be set.

        Fields are not assignable to as attributes, i.e. the following doesn't work:

            array.z = new_field

        Instead, always use #ak.Array.__setitem__:

            array["z"] = new_field

        or #ak.with_field:

            array = ak.with_field(array, new_field, "z")

        to add or modify a field.
        Ú_úFfields cannot be set as attributes. use #__setitem__ or #ak.with_fieldzIonly private attributes (started with an underscore) can be set on arraysN©Ú
startswithr"   rÁ   rˆ   Ú__setattr__rq   r‚   râ   ©r)   r{   r—   r�   r-   r.   rê   Ú  s    ÿÿzArray.__setattr__c                   s:   t tdd„ tt| ƒƒD ƒttƒ ƒ dd„ | jjD ƒ ƒƒS )ú
        Lists all methods, properties, and field names (see #__getattr__)
        that can be accessed as attributes.
        c                 S  s   g | ]}|  d ¡s|‘qS ©ræ   ©ré   rÏ   r-   r-   r.   rH     rI   z!Array.__dir__.<locals>.<listcomp>c                 S  s$   g | ]}t  |¡rt |¡s|‘qS r-   ©Ú_dir_patternÚmatchÚkeywordÚ	iskeywordrÏ   r-   r-   r.   rH     s   þ©ÚsortedÚsetÚdirrÁ   rˆ   rq   r‚   r�   r�   r-   r.   Ú__dir__ý  s    ÿþþÿÿzArray.__dir__c                 C  s   t | ddƒS ©Né   éP   ©Úprettyprint_valuestrr�   r-   r-   r.   Ú__str__  s    zArray.__str__c                 C  s
   |   d¡S ©Nrû   ©Ú_reprr�   r-   r-   r.   Ú__repr__  s    zArray.__repr__c                   sH  zt ƒ  d¡}W n ty,   t| ƒj}Y n0 tt| jƒƒdd… }| jjj	j
rVd}nd}t|ƒt|ƒ tdƒ d |d k r |t|ƒt|ƒ tdƒ d  }n(td	t|d |t|ƒ td
ƒ d ƒƒ}|d t| d|ƒ }td|t|ƒ tdƒ t|ƒ ƒ}t|ƒ|k�r&d|d |d …  d }nd| d }d|› |› d|› d�S )Nrª   rú   rf   Ú ú-typetracerú type=''é   é   r   ú type='...'ú ú
type='...'ú'ú...'ú<ú type=ú>)rˆ   rà   râ   rÁ   rª   Úreprr6   rq   rd   ÚnplikeÚ
known_datar>   ÚmaxÚminrý   ©r)   Ú
limit_colsZpytyperÃ   r   Zstrwidthru   r�   r-   r.   r    s.    $"þþ"zArray._repré   rû   r  ©Ú	formatterÚ	precisionc                C  sx   t ||d�}t| |||d�}|rHt ¡ }	| jj|	d� d|	 ¡  | }
n|}
|du rX|
S |tu rftj}| 	|
d ¡ dS )aŠ  
        Args:
            limit_rows (int): Maximum number of rows (lines) to use in the output.
            limit_cols (int): Maximum number of columns (characters wide).
            type (bool): If True, print the type as well. (Doesn't count toward number
                of rows/lines limit.)
            stream (object with a ``write(str)`` method or None): Stream to write the
                output to. If None, return a string instead of writing to a stream.

            formatter (Mapping or None): Mapping of types/type-classes to string formatters.
                If None, use the default formatter.

        Display the contents of the array within `limit_rows` and `limit_cols`, using
        ellipsis (`...`) for hidden nested data.

        The `formatter` argument controls the formatting of individual values, c.f.
        https://numpy.org/doc/stable/reference/generated/numpy.set_printoptions.html
        As Awkward Array does not implement strings as a NumPy dtype, the `numpystr`
        key is ignored; instead, a `"bytes"` and/or `"str"` key is considered when formatting
        string values, falling back upon `"str_kind"`.
        ©r  ©r  ©Ústreamútype: NÚ
©
r   rý   ÚioÚStringIOrÁ   ÚshowÚgetvaluer   r  Úwrite©r)   Ú
limit_rowsr  rÁ   r  r  r  Úformatter_implr   ÚtmpÚoutr-   r-   r.   r$  4  s    ÿz
Array.showc           	      C  s¸   t  ¡ }| jd|d� | ¡  ¡ }t  ¡ }| jj|d� | ¡  ¡ }d|d › �|d< |d dkrh|d= tdd	„ t ||¡D ƒƒ}d
 	g |¢d| ‘|¢¡}dt
 |¡› d�t| ƒdœS )NF©rÁ   r  r  r  r   rf   r  c                 s  s   | ]}t |ƒV  qd S r<   r=   ©rE   Úliner-   r-   r.   rÑ   t  rI   z*Array._repr_mimebundle_.<locals>.<genexpr>r   r9   ú<pre>ú</pre>©z	text/htmlz
text/plain©r"  r#  r$  r%  Ú
splitlinesrÁ   r  Ú	itertoolsÚchainÚjoinÚhtmlÚescaper  ©	r)   ÚincludeÚexcludeZ
value_buffZheader_linesZ	type_buffZfooter_linesZn_colsÚbodyr-   r-   r.   Ú_repr_mimebundle_f  s    þzArray._repr_mimebundle_c                 C  sT   t j d| fd|i¡�* ddlm} || j|d�W  d  ƒ S 1 sF0    Y  dS )aì  
        Intercepts attempts to convert this Array into a NumPy array and
        either performs a zero-copy conversion or raises an error.

        This function is also called by the
        [np.asarray](https://docs.scipy.org/doc/numpy/reference/generated/numpy.asarray.html)
        family of functions, which have `copy=False` by default.

            >>> np.asarray(ak.Array([[1.1, 2.2, 3.3], [4.4, 5.5, 6.6]]))
            array([[1.1, 2.2, 3.3],
                   [4.4, 5.5, 6.6]])

        If the data are numerical and regular (nested lists have equal lengths
        in each dimension, as described by the #type), they can be losslessly
        converted to a NumPy array and this function returns without an error.

        Otherwise, the function raises an error. It does not create a NumPy
        array with dtype `"O"` for `np.object_` (see the
        [note on object_ type](https://docs.scipy.org/doc/numpy/reference/arrays.scalars.html#arrays-scalars-built-in))
        since silent conversions to dtype `"O"` arrays would not only be a
        significant performance hit, but would also break functionality, since
        nested lists in a NumPy `"O"` array are severed from the array and
        cannot be sliced as dimensions.
        únumpy.asarrayÚdtyper   ©Úconvert_to_array©r?  N)rL   r¤   r¥   Úawkward._connect.numpyrA  rq   ©r)   r?  rA  r-   r-   r.   rT   |  s
    ÿzArray.__array__c                 C  sb   t j t | ¡j› d�| fd|i¡�* ddlm} || j|d�W  d   ƒ S 1 sT0    Y  d S ©Nz.__arrow_array__rÁ   r   r@  )rÁ   )	rL   r¤   r¥   r#   rÁ   rª   Úawkward._connect.pyarrowrA  rq   ©r)   rÁ   rA  r-   r-   r.   Ú__arrow_array__œ  s
    ÿzArray.__arrow_array__c                 O  sd   t |ƒj› d|j› d|›�}tj |||¡�$ tjj ||||¡W  d  ƒ S 1 sV0    Y  dS )aõ  
        Intercepts attempts to pass this Array to a NumPy
        [universal functions](https://docs.scipy.org/doc/numpy/reference/ufuncs.html)
        (ufuncs) and passes it through the Array's structure.

        This method conforms to NumPy's
        [NEP 13](https://numpy.org/neps/nep-0013-ufunc-overrides.html)
        for overriding ufuncs, which has been
        [available since NumPy 1.13](https://numpy.org/devdocs/release/1.13.0-notes.html#array-ufunc-added)
        (and thus NumPy 1.13 is the minimum allowed version).

        When any ufunc is applied to an Awkward Array, it applies to the
        innermost level of structure and preserves the structure through the
        operation.

        For example, with

            >>> array = ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]])

        applying `np.sqrt` would yield

            >>> np.sqrt(array).show()
            [[1.05, 1.48, 1.82],
             [],
             [2.1, 2.35]]

        In addition, many unary and binary operators implicitly call ufuncs,
        such as `np.power` in

            >>> (array**2).show()
            [[1.21, 4.84, 10.9],
             [],
             [19.4, 30.2]]

        In the above example, `array` is a nested list of records and `2` is
        a scalar. Awkward Array applies the same broadcasting rules as NumPy
        plus a few more to deal with nested structures. In addition to
        broadcasting a scalar, as above, it is possible to broadcast
        arrays with less depth into arrays with more depth, such as

            >>> (array + ak.Array([10, 20, 30])).show()
            [[11.1, 12.2, 13.3],
             [],
             [34.4, 35.5]]

        See #ak.broadcast_arrays for details about broadcasting and the
        generalized set of broadcasting rules.

        Third party libraries can create ufuncs, not just NumPy, so any library
        that "plays well" with the NumPy ecosystem can be used with Awkward
        Arrays:

            >>> import numba as nb
            >>> @nb.vectorize([nb.float64(nb.float64)])
            ... def sqr(x):
            ...     return x * x
            ...
            >>> sqr(array).show()
            [[1.21, 4.84, 10.9],
             [],
             [19.4, 30.2]]

        See also #__array_function__.
        Ú.N©	rÁ   r«   rª   rL   r¤   r¥   Ú_connectÚnumpyZarray_ufunc©r)   ZufuncÚmethodÚinputsrŒ   r{   r-   r-   r.   Ú__array_ufunc__¤  s    AzArray.__array_ufunc__c                 C  s   t jjj||||| j| jd�S )a²  
        Intercepts attempts to pass this Array to those NumPy functions other
        than universal functions that have an Awkward equivalent.

        This method conforms to NumPy's
        [NEP 18](https://numpy.org/neps/nep-0018-array-function-protocol.html)
        for overriding functions, which has been
        [available since NumPy 1.17](https://numpy.org/devdocs/release/1.17.0-notes.html#numpy-functions-now-always-support-overrides-with-array-function)
        (and
        [NumPy 1.16 with an experimental flag set](https://numpy.org/devdocs/release/1.16.0-notes.html#numpy-functions-now-support-overrides-with-array-function)).

        See also #__array_ufunc__.
        ©ra   re   )rL   rK  rL  Zarray_functionr}   r~   )r)   Úfuncr¿   r£   rŒ   r-   r-   r.   Ú__array_function__é  s    ÿzArray.__array_function__c                 C  s<   t j ¡  | jdu r(t jjjj | ¡| _ddl}| | j¡S )á<  
        The type of this Array when it is used in Numba. It contains enough
        information to generate low-level code for accessing any element,
        down to the leaves.

        See [Numba documentation](https://numba.pydata.org/numba-doc/dev/reference/types.html)
        on types and signatures.
        Nr   )	rL   ÚnumbaÚregister_and_checkr’   rK  Ú	arrayviewZ	ArrayViewZ	fromarrayÚtypeof©r)   rU  r-   r-   r.   Ú
numba_typeû  s
    


zArray.numba_typer5   rÓ   ©Úprotocolr;   c           	      C  s¦   t | |ƒ}|tur|S tjj| jdd�}tjj|dddd�\}}}|dkr\dd	„ | ¡ D ƒ}| jtj	u rnd }n| j}| j
d u r†| j
}n
t| j
ƒ}t| ¡ ||||ffS )
NFrh   ú{form_key}-{attribute}únode{id}r  ©Ú
buffer_keyrC   Ú	byteorderé   c                 S  s   i | ]\}}|t  |¡“qS r-   ©ÚpickleÚPickleBuffer©rE   rƒ   r„   r-   r-   r.   Ú
<dictcomp>  rI   z'Array.__reduce_ex__.<locals>.<dictcomp>)r   ÚNotImplementedrL   rx   Ú	to_packedrq   Ú
to_buffersrs   r}   ra   r~   r	   r   Úto_dict©	r)   r\  ÚresultZpacked_layoutrP   ru   Ú	containerra   re   r-   r-   r.   Ú__reduce_ex__  s2    
ü

ûzArray.__reduce_ex__c                   sx   |^‰}‰ }}t |tƒrB‡ ‡fdd„t|ƒD ƒ}tj|ddd�}ntjjˆ|ˆ dddd�}|| _|| _d | _	|  
¡  d S )	Nc              
     s.   g | ]&\}}t jjtˆ|ƒ|ˆ d ddd�‘qS )Fr]  r  ©ri   r`  ra  )rL   rx   Úfrom_buffersrR   )rE   ÚiZpart_length©rn  rP   r-   r.   rH   4  s   
øúz&Array.__setstate__.<locals>.<listcomp>r   F)Zaxisri   r]  r  rp  )rK   r   Ú	enumeraterL   Zconcatenaterx   rq  rq   r}   r~   r€   )r)   Ústateru   ra   ræ   Zpart_layoutsrS   r-   rs  r.   Ú__setstate__0  s$    

öúzArray.__setstate__c                 C  s   t | j| j| jd�S ©NrQ  )r   rq   r}   r~   r�   r-   r-   r.   Ú__copy__S  s    zArray.__copy__c                 C  s,   t t | j|¡t | j|¡t | j|¡d�S rw  )r   rN   Údeepcopyrq   r}   r~   ©r)   Úmemor-   r-   r.   Ú__deepcopy__V  s
    ýzArray.__deepcopy__c                 C  s$   t | ƒdkrt| d ƒS tdƒ‚d S ©Nrú   r   zXthe truth value of an array whose length is not 1 is ambiguous; use ak.any() or ak.all()©r>   Úboolrv   r�   r-   r-   r.   Ú__bool__]  s
    ÿzArray.__bool__c                 C  sr   t j ¡  ddl}ddl}| jdu rlt jjj| jj	dd�| _
t j | j¡| _| j
 |j¡ d| j
 ¡ › �| _| jS )an  
        The C++ type of this Array when it is used in cppyy.

            cpp_type (None or str): Generated on demand when the Array needs to be passed
                to a C++ (possibly templated) function defined by a `cppyy` compiler.

        See [cppyy documentation](https://cppyy.readthedocs.io/en/latest/index.html)
        on types and signatures.
        r   NF)Zflatlist_as_rvecz	awkward::)rL   ÚcppyyrV  Zawkward._connect.clingro   rK  ZclingZtogeneratorrq   rP   Z
_generatorÚ_lookupZLookupÚgenerateZcppdefZ
class_type)r)   r�  Úawkwardr-   r-   r.   Úcpp_typef  s    

ÿzArray.cpp_typec                 C  s<   ddl }| jdu r| j| _t|j| jƒdt| ƒd| jjdƒS )a  
        The `__cast_cpp__` is called by cppyy to determine a C++ type of an `ak.Array`.
        It returns the C++ dataset type that is already registered with cppyy with the
        parameters needed to construct the C++ type of this Array when it is
        used in cppyy.
        r   N)r�  ro   r…  ÚgetattrZgblr>   r‚  Z	arrayptrs)r)   r�  r-   r-   r.   Ú__cast_cpp__�  s    
ÿzArray.__cast_cpp__)T)NN)N)N):rª   r«   r¬   rl   r†   r‰   r„  rK  ÚhistZ_histogram_module_r‘   r€   r2   re   ÚsetterrS   ra   r­   r¦   r±   r°   r¶   r¹   rº   r‚   r½   r¾   rÁ   rÃ   rÄ   rÇ   r©   rË   rÖ   rÚ   rå   rê   rø   rþ   r  r  r   r$  r=  rT   rH  rP  rS  r3   rZ  ro  rv  rx  r|  r€  r…  r‡  Ú__classcell__r-   r-   r�   r.   r      s¢    øI
*











&   8L$2#"ûø2

 
E
##	
r   c                      s¬  e Zd ZdZddddddœdd„Z‡ fdd„Zd	d
„ Zeddœdd„ƒZej	ddœdd„ƒZedd„ ƒZ
e
j	dd„ ƒZ
edd„ ƒZej	dd„ ƒZdd„ Zdd„ Zedd„ ƒZedd„ ƒZedd „ ƒZd!d"„ ZdZed#d$„ ƒZed%d&„ ƒZd'd(„ Zd)d*„ Zd+d,„ Z‡ fd-d.„Z‡ fd/d0„Z‡ fd1d2„Zd3d4„ Zd5d6„ Zd7d8„ Zd9d:defdd;d<œd=d>„ZdRd?d@„Z dAdB„ Z!edCdD„ ƒZ"dEdFdGœdHdI„Z#dJdK„ Z$dLdM„ Z%dNdO„ Z&dPdQ„ Z'‡  Z(S )Sr   aÁ  
    Args:
        data (#ak.record.Record, #ak.Record, str, or dict):
            Data to wrap or convert into a record.
            If a string, the data are assumed to be JSON.
            If a dict, calls #ak.from_iter, which assumes all inner
            dimensions have irregular lengths.
        behavior (None or dict): Custom #ak.behavior for this Record only.
        with_name (None or str): Gives the record type a name that can be
            used to override its behavior (see below).
        check_valid (bool): If True, verify that the #layout is valid.
        backend (None, `"cpu"`, `"jax"`, `"cuda"`): If `"cpu"`, the Array will be placed in
            main memory for use with other `"cpu"` Arrays and Records; if `"cuda"`,
            the Array will be placed in GPU global memory using CUDA; if `"jax"`, the structure
            is copied to the CPU for use with JAX. if None, the `data` are left untouched.

    High-level record that can contain fields of any type.

    Most users won't be creating Records manually. This class primarily exists
    to be overridden in the same way as #ak.Array.

    Records can be used in [Numba](http://numba.pydata.org/): they can be
    passed as arguments to a Numba-compiled function or returned as return
    values. The only limitation is that they cannot be *created*
    inside the Numba-compiled function; to make outputs, consider
    #ak.ArrayBuilder.

    See also #ak.Array and #ak.behavior.
    NFr`   c                C  s¦  t |tjjƒr|}nÈt |tƒr,|j}|j}n°t |tƒrHtjj|dd�}n”t |t	ƒrÄg }g }	| 
¡ D ]D\}
}| |
¡ t|ƒr”|	 t|ƒjtj ¡ qb|	 t|gƒj¡ qbtjjtj |	|¡dd�}nt |tƒrØtdƒ‚nd }t |tjjƒsòtdƒ‚|d u�rtjj||dd�}|d u �s8||jjk�s8tjj||dd�}|d u�rVt |tƒ�sVtdƒ‚|| _|| _|| _| d¡}t |tƒ�r„|| _|  ¡  |�r¢tjj| d	d
� d S )NFrh   r   )Úatz:could not convert non-dict into an ak.Record; try ak.Arrayz(could not convert data into an ak.Recordú behavior must be None or mappingrl   Trm   ) rK   rL   Úrecordr   rq   re   r6   rx   ry   rr   rs   rt   r   r   rS   ÚnpZnewaxisrJ   rw   r   rz   rb   rd   r{   r|   r   r}   r~   r   rl   r€   r�   )r)   r]   ra   rb   rc   rd   re   rS   r‚   rJ   rƒ   r„   r…   r-   r-   r.   r†   ±  sL    





ÿ

zRecord.__init__c                   s"   t ƒ jf i |¤Ž tj | ¡ d S r<   r‡   rŠ   r�   r-   r.   r‰   ò  s    zRecord.__init_subclass__c                 C  s   d | _ t| j| jƒ| _d S r<   )r’   r   rq   r}   rŽ   r�   r-   r-   r.   r€   ÷  s    zRecord._update_classr“   r”   c                 C  s   | j du ri | _ | j S )a)  
        The mapping containing top-level metadata, which is serialised
        with the record during pickling.

        Keys prefixed with `@` are identified as "transient" attributes
        which are discarded prior to pickling, permitting the storage of
        non-pickleable types.
        Nr•   r�   r-   r-   r.   re   û  s    

zRecord.attrsr–   c                 C  s   t |tƒr|| _ntdƒ‚d S r˜   r™   rš   r-   r-   r.   re   	  s    
c                 C  s   | j S )aL  
        The #ak.record.Record that contains composable #ak.contents.Content
        elements to determine how the array is structured.

        See #ak.Array.layout for a more complete description.

        The #ak.record.Record is not a subclass of #ak.contents.Content in
        Python and it is not composable with them: #ak.record.Record contains
        one #ak.contents.RecordArray (which is a #ak.contents.Content), but
        #ak.contents.Content nodes cannot contain a #ak.record.Record.

        A #ak.record.Record is not an independent entity from its
        #ak.contents.RecordArray; it's really just a marker indicating which
        element to select. The XML representation reflects that:

            >>> vectors = ak.Array([{"x": 0.1, "y": 1.0, "z": 30.0},
            ...                     {"x": 0.2, "y": 2.0, "z": 20.0},
            ...                     {"x": 0.3, "y": 3.0, "z": 10.0}])
            >>> vectors[1].layout
            <Record at='1'>
                <array><RecordArray is_tuple='false' len='3'>
                    <content index='0' field='x'>
                        <NumpyArray dtype='float64' len='3'>[0.1 0.2 0.3]</NumpyArray>
                    </content>
                    <content index='1' field='y'>
                        <NumpyArray dtype='float64' len='3'>[1. 2. 3.]</NumpyArray>
                    </content>
                    <content index='2' field='z'>
                        <NumpyArray dtype='float64' len='3'>[30. 20. 10.]</NumpyArray>
                    </content>
                </RecordArray></array>
            </Record>
        r›   r�   r-   r-   r.   rS     s    #zRecord.layoutc                 C  s*   t |tjjƒr|| _|  ¡  ntdƒ‚d S )Nz-layout must be a subclass of ak.record.Record)rK   rL   r�  r   rq   r€   rz   rœ   r-   r-   r.   rS   5  s    
c                 C  s   | j S )a„  
        The `behavior` parameter passed into this Record's constructor.

        * If a dict, this `behavior` overrides the global #ak.behavior.
             Any keys in the global #ak.behavior but not this `behavior` are
             still valid, but any keys in both are overridden by this
             `behavior`. Keys with a None value are equivalent to missing keys,
             so this `behavior` can effectively remove keys from the
             global #ak.behavior.

        * If None, the Record defaults to the global #ak.behavior.

        See #ak.behavior for a list of recognized key patterns and their
        meanings.
        r�   r�   r-   r-   r.   ra   =  s    zRecord.behaviorc                 C  s.   |d u st |tƒr"|| _|  ¡  ntdƒ‚d S rž   rŸ   r    r-   r-   r.   ra   P  s    
c                 C  s   |   ¡ S )zä
        Converts this Record into Python objects; same as #ak.to_list
        (but without the underscore, like NumPy's
        [tolist](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.tolist.html)).
        r¯   r�   r-   r-   r.   r±   X  s    zRecord.tolistc                 C  s   | j  | j¡S )zP
        Converts this Record into Python objects; same as #ak.to_list.
        r³   r�   r-   r-   r.   r°   `  s    zRecord.to_listc                 C  s   | j jS )as  
        The total number of bytes in all the #ak.index.Index,
        and #ak.contents.NumpyArray buffers in this array tree.

        It does not count buffers that must be kept in memory because
        of ownership, but are not directly used in the array. Nor does it count
        the (small) Python objects that reference the (large)
        array buffers.
        r¸   r�   r-   r-   r.   r¹   f  s    zRecord.nbytesc                 C  s
   | j jjS )zø
        List of field names or tuple slot numbers (as strings) of this record.

        If this is actually a tuple its fields are string representations of
        integers, such as `"0"`, `"1"`, `"2"`, etc.

        See also #ak.fields.
        ©rq   r¢   r‚   r�   r-   r-   r.   r‚   s  s    
zRecord.fieldsc                 C  s
   | j jjS r¼   )rq   r¢   r½   r�   r-   r-   r.   r½     s    zRecord.is_tuplec                 C  s
   | j jjS r<   r�  r�   r-   r-   r.   r¾   †  s    z Record._ipython_key_completions_c                 C  s   t j | jjjj| j¡S )a*  
        The high-level type of this Record; same as #ak.type.

        Note that the outermost element of a Record's type is always an
        #ak.types.ScalarType, which .

        The type of a #ak.record.Record (from #ak.Array.layout) is not
        wrapped by an #ak.types.ScalarType.
        )rL   r¿   Z
ScalarTyperq   r¢   rP   rÁ   r}   r�   r-   r-   r.   rÁ   Œ  s    zRecord.typec                 C  s
   t | jƒS )zL
        The high-level type of this Record, presented as a string.
        rÂ   r�   r-   r-   r.   rÃ   ™  s    zRecord.typestrc                 C  sP   t j | |¡�. tt| j| ƒ| jd| jd�W  d  ƒ S 1 sB0    Y  dS )aÂ  
        Args:
            where (many types supported; see below): Index of positions to
                select from this Record.

        Select items from the Record using an extension of NumPy's (already
        quite extensive) rules.

        See #ak.Array.__getitem__ for a more complete description. Since
        this is a record, the first item in the slice tuple must be a
        string, selecting a field.

        For example, with

            >>> record = ak.Record({"x": 3.3, "y": [1, 2, 3]})

        we can select

            >>> record["x"]
            3.3
            >>> record["y"]
            <Array [1, 2, 3] type='3 * int64'>
            >>> record["y", 1]
            2
        TrÅ   NrÈ   r§   r-   r-   r.   r©      s    üzRecord.__getitem__c              	   C  s’   t j d| f||dœ¡�f t|tƒsHt|tƒr@tdd„ |D ƒƒsHtdƒ‚t jj	j
| j||d| j| jd�| _d| _W d  ƒ n1 s„0    Y  dS )	aq  
        Args:
            where (str or tuple of str): Field name to add data to the record.
            what: Data to add as the new field.

        For example:

            >>> record = ak.Record({"x": 3.3})
            >>> record["y"] = 4
            >>> record["z"] = {"another": "record"}
            >>> record.show()
            {x: 3.3,
             y: 4,
             z: {another: 'record'}}

        See #ak.with_field for a variant that does not change the #ak.Record
        in-place. (Internally, this method uses #ak.with_field, so performance
        is not a factor in choosing one over the other.)
        zak.Record.__setitem__rÌ   c                 s  s   | ]}t |tƒV  qd S r<   rÎ   rÏ   r-   r-   r.   rÑ   Ý  rI   z%Record.__setitem__.<locals>.<genexpr>rÒ   Frk   N)rL   r¤   r¥   rK   r6   rÓ   rÔ   rz   rx   Zak_with_fieldrÙ   rq   r}   r~   r’   rÕ   r-   r-   r.   rÖ   Â  s*    ýÿþþúzRecord.__setitem__c                 C  sŽ   t j d| fd|i¡�d t|tƒsFt|tƒr>tdd„ |D ƒƒsFtdƒ‚t jj	j
| j|d| j| jd�| _d| _W d  ƒ n1 s€0    Y  dS )	a  
        Args:
            where (str or tuple of str): Field name to remove from the record.

        For example:

            >>> record = ak.Record({"x": 3.3, "y": {"this": 10, "that": 20}})
            >>> del record["y", "that"]
            >>> record.show()
            {x: 3.3,
             y: {this: 10}}

        See #ak.without_field for a variant that does not change the #ak.Record
        in-place. (Internally, this method uses #ak.without_field, so performance
        is not a factor in choosing one over the other.)
        zak.Record.__delitem__r¨   c                 s  s   | ]}t |tƒV  qd S r<   rÎ   rÏ   r-   r-   r.   rÑ     rI   z%Record.__delitem__.<locals>.<genexpr>r×   Frk   NrØ   r§   r-   r-   r.   rÚ   ë  s(    ýÿþþûzRecord.__delitem__c              
     sŠ   t t| ƒ|ƒrtƒ  |¡S || jjv rxz
| | W S  tyt } z,td|›dt|ƒ› d|›�ƒ|‚W Y d}~q†d}~0 0 ntd|›�ƒ‚dS )a  
        Whenever possible, fields can be accessed as attributes.

        For example, the fields of

            >>> record = ak.Record({"x": 1.1, "y": [2, 2], "z": "three"})

        can be accessed as

            >>> record.x
            1.1
            >>> record.y
            <Array [2, 2] type='2 * int64'>
            >>> record.z
            'three'

        which are equivalent to `record["x"]`, `record["y"]`, and
        `record["z"]`.

        Fields can't be accessed as attributes when

        * #ak.Record methods or properties take precedence,
        * a domain-specific behavior has methods or properties that take
             precedence, or
        * the field name is not a valid Python identifier or is a Python
             keyword.
        rÛ   rÜ   rÝ   NrÞ   rß   rã   r�   r-   r.   rå     s     
ÿÿÿýzRecord.__getattr__c                   sJ   |  d¡stt| ƒ|ƒr(tƒ  ||¡ n|| jjv r>tdƒ‚ntdƒ‚dS )aC  
        Args:
            where (str): Attribute name to set

        Set an attribute on the record.

        Only existing public attributes e.g. #ak.Record.layout, or private
        attributes (with leading underscores), can be set.

        Fields are not assignable to as attributes, i.e. the following doesn't work:

            record.z = new_field

        Instead, always use #ak.Record.__setitem__:

            record["z"] = new_field

        or #ak.with_field:

            record = ak.with_field(record, new_field, "z")

        to add or modify a field.
        ræ   rç   zJonly private attributes (started with an underscore) can be set on recordsNrè   rë   r�   r-   r.   rê   :  s    ÿÿzRecord.__setattr__c                   s:   t tdd„ tt| ƒƒD ƒttƒ ƒ dd„ | jjD ƒ ƒƒS )rì   c                 S  s   g | ]}|  d ¡s|‘qS rí   rî   rÏ   r-   r-   r.   rH   d  rI   z"Record.__dir__.<locals>.<listcomp>c                 S  s$   g | ]}t  |¡rt |¡s|‘qS r-   rï   rÏ   r-   r-   r.   rH   f  s   þrô   r�   r�   r-   r.   rø   ]  s    ÿþþÿÿzRecord.__dir__c                 C  s   t | ddƒS rù   rü   r�   r-   r-   r.   rþ   n  s    zRecord.__str__c                 C  s
   |   d¡S rÿ   r   r�   r-   r-   r.   r  q  s    zRecord.__repr__c                 C  s&  t | ƒj}tt| j ƒƒdd… }| jjjjjr4d}nd}t	|ƒt	|ƒ t	dƒ d |d k r~|t	|ƒt	|ƒ t	dƒ d  }n(t
dt|d |t	|ƒ t	d	ƒ d ƒƒ}|d
 t| d|ƒ }t
d|t	|ƒ t	dƒ t	|ƒ ƒ}t	|ƒ|k�rd|d |d …  d }nd| d }d|› |› d|› d�S )Nrú   rf   r  r  r  r  r  r   r  r	  r
  r  r  r  r  r  )rÁ   rª   r  r6   rq   r¢   rd   r  r  r>   r  r  rý   r  r-   r-   r.   r  t  s(    
$"þþ"zRecord._reprr  rû   r  r  c                C  sx   t ||d�}t| |||d�}|rHt ¡ }	| jj|	d� d|	 ¡  | }
n|}
|du rX|
S |tu rftj}| 	|
d ¡ dS )a‰  
        Args:
            limit_rows (int): Maximum number of rows (lines) to use in the output.
            limit_cols (int): Maximum number of columns (characters wide).
            type (bool): If True, print the type as well. (Doesn't count toward number
                of rows/lines limit.)
            stream (object with a ``write(str)`` method or None): Stream to write the
                output to. If None, return a string instead of writing to a stream.
            formatter (Mapping or None): Mapping of types/type-classes to string formatters.
                If None, use the default formatter.

        Display the contents of the array within `limit_rows` and `limit_cols`, using
        ellipsis (`...`) for hidden nested data.

        The `formatter` argument controls the formatting of individual values, c.f.
        https://numpy.org/doc/stable/reference/generated/numpy.set_printoptions.html
        As Awkward Array does not implement strings as a NumPy dtype, the `numpystr`
        key is ignored; instead, a `"bytes"` and/or `"str"` key is considered when formatting
        string values, falling back upon `"str_kind"`.
        r  r  r  r  Nr   r!  r'  r-   r-   r.   r$  ‘  s    ÿzRecord.showc           	      C  s¸   t  ¡ }| jd|d� | ¡  ¡ }t  ¡ }| jj|d� | ¡  ¡ }d|d › �|d< |d dkrh|d= tdd	„ t ||¡D ƒƒ}d
 	g |¢d| ‘|¢¡}dt
 |¡› d�t| ƒdœS )NFr,  r  r  r   rf   r  c                 s  s   | ]}t |ƒV  qd S r<   r=   r-  r-   r-   r.   rÑ   Ï  rI   z+Record._repr_mimebundle_.<locals>.<genexpr>r   r9   r/  r0  r1  r2  r9  r-   r-   r.   r=  Á  s    þzRecord._repr_mimebundle_c                 O  sd   t |ƒj› d|j› d|›�}tj |||¡�$ tjj ||||¡W  d  ƒ S 1 sV0    Y  dS )ai  
        Intercepts attempts to pass this Record to a NumPy
        [universal functions](https://docs.scipy.org/doc/numpy/reference/ufuncs.html)
        (ufuncs) and passes it through the Record's structure.

        This method conforms to NumPy's
        [NEP 13](https://numpy.org/neps/nep-0013-ufunc-overrides.html)
        for overriding ufuncs, which has been
        [available since NumPy 1.13](https://numpy.org/devdocs/release/1.13.0-notes.html#array-ufunc-added)
        (and thus NumPy 1.13 is the minimum allowed version).

        See #ak.Array.__array_ufunc__ for a more complete description.
        rI  NrJ  rM  r-   r-   r.   rP  ×  s    zRecord.__array_ufunc__c                 C  s<   t j ¡  | jdu r(t jjjj | ¡| _ddl}| | j¡S )a=  
        The type of this Record when it is used in Numba. It contains enough
        information to generate low-level code for accessing any element,
        down to the leaves.

        See [Numba documentation](https://numba.pydata.org/numba-doc/dev/reference/types.html)
        on types and signatures.
        Nr   )	rL   rU  rV  r’   rK  rW  Z
RecordViewZ
fromrecordrX  rY  r-   r-   r.   rZ  é  s
    


zRecord.numba_typer5   rÓ   r[  c           	      C  s¬   t | |ƒ}|tur|S tjj| jdd�}tjj|jdddd�\}}}|dkr^dd	„ | ¡ D ƒ}| j	tj
u rpd }n| j	}| jd u rˆ| j}n
t| jƒ}t| ¡ |||||jffS )
NFrh   r]  r^  r  r_  rb  c                 S  s   i | ]\}}|t  |¡“qS r-   rc  rf  r-   r-   r.   rg  	  rI   z(Record.__reduce_ex__.<locals>.<dictcomp>)r   rh  rL   rx   ri  rq   rj  r¢   rs   r}   ra   r~   r	   r   rk  r‹  rl  r-   r-   r.   ro  û  s4    
ü

úzRecord.__reduce_ex__c           	      C  sT   |^}}}}}}t jj|||dddd�}t j ||¡}|| _|| _d | _|  ¡  d S )NFr]  r  rp  )	rL   rx   rq  r�  r   rq   r}   r~   r€   )	r)   ru  rP   ru   rn  ra   r‹  ræ   rS   r-   r-   r.   rv   	  s    úzRecord.__setstate__c                 C  s   t | j| j| jd�S rw  )r   rq   r}   r~   r�   r-   r-   r.   rx  2	  s    zRecord.__copy__c                 C  s,   t t | j|¡t | j|¡t | j|¡d�S rw  )r   rN   ry  rq   r}   r~   rz  r-   r-   r.   r|  5	  s
    ýzRecord.__deepcopy__c                 C  s   t dƒ‚d S )NzRthe truth value of a record is ambiguous; use ak.any() or ak.all() or pick a field)rv   r�   r-   r-   r.   r€  <	  s    ÿzRecord.__bool__)NN))rª   r«   r¬   rl   r†   r‰   r€   r2   re   r‰  rS   ra   r±   r°   r¹   r‚   r½   r¾   rÇ   rÁ   rÃ   r©   rÖ   rÚ   rå   rê   rø   rþ   r  r  r   r$  r=  rP  rZ  ro  rv  rx  r|  r€  rŠ  r-   r-   r�   r.   r   ’  sz   "øA
$







")%*#ûø0

%r   c                   @  s   e Zd ZdZdddddœdd„Zedkdd	„ƒZed
dœdd„ƒZej	d
dœdd„ƒZedd„ ƒZ
e
j	dd„ ƒZ
dd„ Zdd„ Zdldd„Zedd„ ƒZedd„ ƒZdd„ Zd d!„ Zd"d#„ Zd$d%„ Zd&d'd(efdd)d*œd+d,„Zdmd-d.„Zdnd/d0„Zed1d2„ ƒZd3d4„ Zd5d6„ Zd7d8„ Zd9d:„ Zd;d<„ Zd=d>„ Zd?d@„ ZdAdB„ Z dCdD„ Z!dEdF„ Z"dGdH„ Z#dIdJ„ Z$dKdL„ Z%dMdN„ Z&dOdP„ Z'dQdR„ Z(dodSdT„Z)dUdV„ Z*dWdX„ Z+dYdZ„ Z,d[d\„ Z-G d]d^„ d^ƒZ.G d_d`„ d`e.ƒZ/dadb„ Z0G dcdd„ dde.ƒZ1dedf„ Z2G dgdh„ dhe.ƒZ3dpdidj„Z4dS )qr   a  
    Args:
        behavior (None or dict): Custom #ak.behavior for arrays built by
            this ArrayBuilder.
        initial (int): Initial size (in bytes) of buffers used by the `ak::ArrayBuilder`.
        resize (float): Resize multiplier for buffers used by the `ak::ArrayBuilder`;
            should be strictly greater than 1.

    General tool for building arrays of nested data structures from a sequence
    of commands. Most data types can be constructed by calling commands in the
    right order, similar to printing tokens to construct JSON output.

    To illustrate how this works, consider the following example.

        b = ak.ArrayBuilder()

        # fill commands   # as JSON   # current array type
        ##########################################################################################
        b.begin_list()    # [         # 0 * var * unknown     (initially, the type is unknown)
        b.integer(1)      #   1,      # 0 * var * int64
        b.integer(2)      #   2,      # 0 * var * int64
        b.real(3)         #   3.0     # 0 * var * float64     (all the integers have become floats)
        b.end_list()      # ],        # 1 * var * float64     (closed first list; array length is 1)
        b.begin_list()    # [         # 1 * var * float64
        b.end_list()      # ],        # 2 * var * float64     (closed empty list; array length is 2)
        b.begin_list()    # [         # 2 * var * float64
        b.integer(4)      #   4,      # 2 * var * float64
        b.null()          #   null,   # 2 * var * ?float64    (now the floats are nullable)
        b.integer(5)      #   5       # 2 * var * ?float64
        b.end_list()      # ],        # 3 * var * ?float64
        b.begin_list()    # [         # 3 * var * ?float64
        b.begin_record()  #   {       # 3 * var * union[?float64, ?{}]
        b.field("x")      #     "x":  # 3 * var * union[?float64, ?{x: unknown}]
        b.integer(1)      #      1,   # 3 * var * union[?float64, ?{x: int64}]
        b.field("y")      #      "y": # 3 * var * union[?float64, ?{x: int64, y: unknown}]
        b.begin_list()    #      [    # 3 * var * union[?float64, ?{x: int64, y: var * unknown}]
        b.integer(2)      #        2, # 3 * var * union[?float64, ?{x: int64, y: var * int64}]
        b.integer(3)      #        3  # 3 * var * union[?float64, ?{x: int64, y: var * int64}]
        b.end_list()      #      ]    # 3 * var * union[?float64, ?{x: int64, y: var * int64}]
        b.end_record()    #   }       # 3 * var * union[?float64, ?{x: int64, y: var * int64}]
        b.end_list()      # ]         # 4 * var * union[?float64, ?{x: int64, y: var * int64}]

    To get an array, we take a #snapshot of the ArrayBuilder's current state.

        >>> b.snapshot()
        <Array [[1, 2, 3], ..., [{x: 1, y: ..., ...}]] type='4 * var * union[?float...'>
        >>> b.snapshot().show()
        [[1, 2, 3],
         [],
         [4, None, 5],
         [{x: 1, y: [2, 3]}]]

    The full set of filling commands is the following.

    * #null: appends a None value.
    * #boolean: appends True or False.
    * #integer: appends an integer.
    * #real: appends a floating-point value.
    * #complex: appends a complex value.
    * #datetime: appends a datetime value.
    * #timedelta: appends a timedelta value.
    * #bytestring: appends an unencoded string (raw bytes).
    * #string: appends a UTF-8 encoded string.
    * #begin_list: begins filling a list; must be closed with #end_list.
    * #end_list: ends a list.
    * #begin_tuple: begins filling a tuple; must be closed with #end_tuple.
    * #index: selects a tuple slot to fill; must be followed by a command
         that actually fills that slot.
    * #end_tuple: ends a tuple.
    * #begin_record: begins filling a record; must be closed with
         #end_record.
    * #field: selects a record field to fill; must be followed by a command
         that actually fills that field.
    * #end_record: ends a record.
    * #append: generic method for filling #null, #boolean, #integer, #real,
         #bytestring, #string, #ak.Array, #ak.Record, or arbitrary Python data.
    * #extend: appends all the items from an iterable.
    * #list: context manager for #begin_list and #end_list.
    * #tuple: context manager for #begin_tuple and #end_tuple.
    * #record: context manager for #begin_record and #end_record.

    ArrayBuilders can be used in [Numba](http://numba.pydata.org/): they can
    be passed as arguments to a Numba-compiled function or returned as return
    values. (Since ArrayBuilder works by accumulating side-effects, it's not
    strictly necessary to return the object.)

    The primary limitation is that ArrayBuilders cannot be *created* and
    #snapshot cannot be called inside the Numba-compiled function. Awkward
    Array uses Numba as a transformer: #ak.Array and an empty #ak.ArrayBuilder
    go in and a filled #ak.ArrayBuilder is the result; #snapshot can be called
    outside of the compiled function.

    Also, context managers (Python's `with` statement) are not supported in
    Numba yet, so the #list, #tuple, and #record methods are not available
    in Numba-compiled functions.

    Here is an example of filling an ArrayBuilder in Numba, which makes a
    tree of dynamic depth.

        >>> import numba as nb
        >>> @nb.njit
        ... def deepnesting(builder, probability):
        ...     if np.random.uniform(0, 1) > probability:
        ...         builder.append(np.random.normal())
        ...     else:
        ...         builder.begin_list()
        ...         for i in range(np.random.poisson(3)):
        ...             deepnesting(builder, probability**2)
        ...         builder.end_list()
        ...
        >>> builder = ak.ArrayBuilder()
        >>> deepnesting(builder, 0.9)
        >>> builder.snapshot()
        <Array [[[-0.523, ..., [[2.16, ...], ...]]]] type='1 * var * var * union[fl...'>
        >>> builder.type.show()
        1 * var * var * union[
            float64,
            var * union[
                var * union[
                    float64,
                    var * unknown
                ],
                float64
            ]
        ]

    Note that this is a *general* method for building arrays; if the type is
    known in advance, more specialized procedures can be faster. This should
    be considered the "least effort" approach.
    Ni   é   )ra   re   ÚinitialÚresizec                C  s:   |d urt |tƒstdƒ‚tj||d�| _|| _|| _d S )NrŒ  )r‘  r’  )rK   r   rz   r   r   rq   r}   r~   )r)   ra   re   r‘  r’  r-   r-   r.   r†   Ç	  s
    zArrayBuilder.__init__c                 C  s0   t |tjƒsJ ‚|  | ¡}||_||_||_|S )aò  
        Args:
            layout (`ak._ext.ArrayBuilder`): Low-level builder to wrap.
            behavior (None or dict): Custom #ak.behavior for arrays built by
                this ArrayBuilder.

        Wraps a low-level `ak._ext.ArrayBuilder` as a high-level
        #ak.ArrayBulider.

        The #ak.ArrayBuilder constructor creates a new `ak._ext.ArrayBuilder`
        with no accumulated data, but Numba needs to wrap existing data
        when returning from a lowered function.
        )rK   r   r   Ú__new__rq   r}   r~   )r‹   rS   ra   re   r+  r-   r-   r.   Ú_wrapÏ	  s    
zArrayBuilder._wrapr“   r”   c                 C  s   | j du ri | _ | j S )a(  
        The mapping containing top-level metadata, which is serialised
        with the array during pickling.

        Keys prefixed with `@` are identified as "transient" attributes
        which are discarded prior to pickling, permitting the storage of
        non-pickleable types.
        Nr•   r�   r-   r-   r.   re   å	  s    

zArrayBuilder.attrsr–   c                 C  s   t |tƒr|| _ntdƒ‚d S r˜   r™   rš   r-   r-   r.   re   ó	  s    
c                 C  s   | j S )a‰  
        The `behavior` parameter passed into this ArrayBuilder's constructor.

        * If a dict, this `behavior` overrides the global #ak.behavior.
             Any keys in the global #ak.behavior but not this `behavior` are
             still valid, but any keys in both are overridden by this
             `behavior`. Keys with a None value are equivalent to missing keys,
             so this `behavior` can effectively remove keys from the
             global #ak.behavior.

        * If None, the Array defaults to the global #ak.behavior.

        See #ak.behavior for a list of recognized key patterns and their
        meanings.
        r�   r�   r-   r-   r.   ra   ú	  s    zArrayBuilder.behaviorc                 C  s&   |d u st |tƒr|| _ntdƒ‚d S rž   )rK   rr   r}   rz   r    r-   r-   r.   ra   
  s    c                 C  s   |   ¡ S r®   r¯   r�   r-   r-   r.   r±   
  s    zArrayBuilder.tolistc                 C  s   |   ¡  ¡ S r²   )Úsnapshotr°   r�   r-   r-   r.   r°   
  s    zArrayBuilder.to_listTc                 C  s   |   ¡ j|d�S r´   )r•  r¶   r·   r-   r-   r.   r¶   "
  s    zArrayBuilder.to_numpyc                 C  s,   t j | j ¡ ¡}t j |jt| jƒ| j	¡S )ab  
        The high-level type of the accumulated array; same as #ak.type.

        Note that the outermost element of an Array's type is always an
        #ak.types.ArrayType, which specifies the number of elements in the array.

        The type of a #ak.contents.Content (from #ak.Array.layout) is not
        wrapped by an #ak.types.ArrayType.
        )
rL   rM   ry   rq   rP   r¿   rÀ   rÁ   r>   r}   )r)   rP   r-   r-   r.   rÁ   (
  s    zArrayBuilder.typec                 C  s
   t | jƒS )zW
        The high-level type of this accumulated array, presented as a string.
        rÂ   r�   r-   r-   r.   rÃ   6
  s    zArrayBuilder.typestrc                 C  s
   t | jƒS )z>
        The current length of the accumulated array.
        )r>   rq   r�   r-   r-   r.   rÄ   =
  s    zArrayBuilder.__len__c                 C  s   |   ¡ S r<   )r  r�   r-   r-   r.   rþ   C
  s    zArrayBuilder.__str__c                 C  s
   |   d¡S rÿ   r   r�   r-   r-   r.   r  F
  s    zArrayBuilder.__repr__c                 C  sJ   t | jƒ}|tdƒ }t|ƒ|kr>|d |d … d |d  }d|› d�S )Nz<ArrayBuilder type=>é   ú...rf   z<ArrayBuilder type=r  )r  rÃ   r>   )r)   r  rÃ   Ú
limit_typer-   r-   r.   r  I
  s
    
zArrayBuilder._reprr  rû   Fr  r  c                C  s$   t ||d�}|  ¡ j|||||d�S )aõ  
        Args:
            limit_rows (int): Maximum number of rows (lines) to use in the output.
            limit_cols (int): Maximum number of columns (characters wide).
            type (bool): If True, print the type as well. (Doesn't count toward number
                of rows/lines limit.)
            stream (object with a ``write(str)`` method or None): Stream to write the
                output to. If None, return a string instead of writing to a stream.
            formatter (Mapping or None): Mapping of types/type-classes to string formatters.
                If None, use the default formatter.

        Display the contents of the array within `limit_rows` and `limit_cols`, using
        ellipsis (`...`) for hidden nested data.

        The `formatter` argument controls the formatting of individual values, c.f.
        https://numpy.org/doc/stable/reference/generated/numpy.set_printoptions.html
        As Awkward Array does not implement strings as a NumPy dtype, the `numpystr`
        key is ignored; instead, a `"bytes"` and/or `"str"` key is considered when formatting
        string values, falling back upon `"str_kind"`.

        This method takes a snapshot of the data and calls show on it, and a snapshot
        copies data.
        r  )r(  r  rÁ   r  r  )r   r•  r$  )r)   r(  r  rÁ   r  r  r  r)  r-   r-   r.   r$  R
  s    !ûzArrayBuilder.showc                 C  sV   t j d| fd|i¡�, ddlm} ||  ¡ |d�W  d  ƒ S 1 sH0    Y  dS )zî
        Intercepts attempts to convert a #snapshot of this array into a
        NumPy array and either performs a zero-copy conversion or raises
        an error.

        See #ak.Array.__array__ for a more complete description.
        r>  r?  r   r@  rB  N)rL   r¤   r¥   rC  rA  r•  rD  r-   r-   r.   rT   |
  s
    ÿzArrayBuilder.__array__c                 C  sd   t j t | ¡j› d�| fd|i¡�, ddlm} ||  ¡ |d�W  d   ƒ S 1 sV0    Y  d S rE  )	rL   r¤   r¥   r#   rÁ   rª   rF  rA  r•  rG  r-   r-   r.   rH  ‹
  s
    ÿzArrayBuilder.__arrow_array__c                 C  s   t j ¡  t jjj | j¡S )rT  )rL   rU  rV  rK  ÚbuilderZArrayBuilderTyper}   r�   r-   r-   r.   rZ  “
  s    

zArrayBuilder.numba_typec                 C  s$   t | ƒdkrt| d ƒS tdƒ‚d S r}  r~  r�   r-   r-   r.   r€  ¡
  s
    ÿzArrayBuilder.__bool__c                 C  sz   t j dg i ¡�V | j ¡ \}}}t j |¡}t jjj	|||ddt j
jdd| j| jd�
W  d  ƒ S 1 sl0    Y  dS )z•
        Converts the currently accumulated data into an #ak.Array.

        The currently accumulated data are *copied* into the new array.
        zak.ArrayBuilder.snapshotr]  ÚcpuT)r`  rd   ra  Úsimplifyri   ra   re   N)rL   r¤   r¥   rq   rj  rM   ry   rx   Zak_from_buffersrÙ   r[   Znative_byteorderr}   r~   )r)   Zformstrru   rn  rP   r-   r-   r.   r•  ª
  s    özArrayBuilder.snapshotc                 C  s   | j  ¡  dS )zX
        Appends a None value at the current position in the accumulated array.
        N)rq   Únullr�   r-   r-   r.   rœ  À
  s    zArrayBuilder.nullc                 C  s   | j  |¡ dS )zg
        Appends a boolean value `x` at the current position in the accumulated
        array.
        N)rq   Úboolean©r)   rÐ   r-   r-   r.   r�  Æ
  s    zArrayBuilder.booleanc                 C  s   | j  |¡ dS )zb
        Appends an integer `x` at the current position in the accumulated
        array.
        N)rq   Úintegerrž  r-   r-   r.   rŸ  Í
  s    zArrayBuilder.integerc                 C  s   | j  |¡ dS ©zo
        Appends a floating point number `x` at the current position in the
        accumulated array.
        N)rq   Úrealrž  r-   r-   r.   r¡  Ô
  s    zArrayBuilder.realc                 C  s   | j  |¡ dS r   )rq   Úcomplexrž  r-   r-   r.   r¢  Û
  s    zArrayBuilder.complexc                 C  s   | j  |¡ dS )zh
        Appends a datetime value `x` at the current position in the
        accumulated array.
        N)rq   Údatetimerž  r-   r-   r.   r£  â
  s    zArrayBuilder.datetimec                 C  s   | j  |¡ dS )zi
        Appends a timedelta value `x` at the current position in the
        accumulated array.
        N)rq   Ú	timedeltarž  r-   r-   r.   r¤  é
  s    zArrayBuilder.timedeltac                 C  s   | j  |¡ dS )zw
        Appends an unencoded string (raw bytes) `x` at the current position
        in the accumulated array.
        N)rq   Ú
bytestringrž  r-   r-   r.   r¥  ð
  s    zArrayBuilder.bytestringc                 C  s   | j  |¡ dS )zn
        Appends a UTF-8 encoded string `x` at the current position in the
        accumulated array.
        N)rq   Ústringrž  r-   r-   r.   r¦  ÷
  s    zArrayBuilder.stringc                 C  s   | j  ¡  dS )a†  
        Begins filling a list; must be closed with #end_list.

        For example,

            >>> builder = ak.ArrayBuilder()
            >>> builder.begin_list()
            >>> builder.real(1.1)
            >>> builder.real(2.2)
            >>> builder.real(3.3)
            >>> builder.end_list()
            >>> builder.begin_list()
            >>> builder.end_list()
            >>> builder.begin_list()
            >>> builder.real(4.4)
            >>> builder.real(5.5)
            >>> builder.end_list()

        produces

            >>> builder.show()
            [[1.1, 2.2, 3.3],
             [],
             [4.4, 5.5]]
        N)rq   Z	beginlistr�   r-   r-   r.   Ú
begin_listþ
  s    zArrayBuilder.begin_listc                 C  s   | j  ¡  dS )z
        Ends a list.
        N)rq   Zendlistr�   r-   r-   r.   Úend_list  s    zArrayBuilder.end_listc                 C  s   | j  |¡ dS )a¼  
        Begins filling a tuple with `numfields` fields; must be closed with
        #end_tuple.

        For example,

            >>> builder = ak.ArrayBuilder()
            >>> builder.begin_tuple(3)
            >>> builder.index(0).integer(1)
            >>> builder.index(1).real(1.1)
            >>> builder.index(2).string("one")
            >>> builder.end_tuple()
            >>> builder.begin_tuple(3)
            >>> builder.index(0).integer(2)
            >>> builder.index(1).real(2.2)
            >>> builder.index(2).string("two")
            >>> builder.end_tuple()

        produces

            >>> builder.show()
            [(1, 1.1, 'one'),
             (2, 2.2, 'two')]
        N)rq   Z
begintuple©r)   Ú	numfieldsr-   r-   r.   Úbegin_tuple   s    zArrayBuilder.begin_tuplec                 C  s   | j  |¡ | S )a  
        Args:
            i (int): The tuple slot to fill.

        This method also returns the #ak.ArrayBuilder, so that it can be
        chained with the value that fills the slot.

        Prepares to fill a tuple slot; see #begin_tuple for an example.
        )rq   Úindex)r)   rr  r-   r-   r.   r¬  ;  s    
zArrayBuilder.indexc                 C  s   | j  ¡  dS )z
        Ends a tuple.
        N)rq   Zendtupler�   r-   r-   r.   Ú	end_tupleH  s    zArrayBuilder.end_tuplec                 C  s   | j  |¡ dS )ar  
        Begins filling a record with an optional `name`; must be closed with
        #end_record.

        For example,

            >>> builder = ak.ArrayBuilder()
            >>> builder.begin_record("points")
            >>> builder.field("x").real(1)
            >>> builder.field("y").real(1.1)
            >>> builder.end_record()
            >>> builder.begin_record("points")
            >>> builder.field("x").real(2)
            >>> builder.field("y").real(2.2)
            >>> builder.end_record()

        produces

            >>> builder.show()
            [{x: 1, y: 1.1},
             {x: 2, y: 2.2}]

        with type

            >>> builder.type.show()
            2 * points[
                x: float64,
                y: float64
            ]

        The record type is named `"points"` because its `"__record__"`
        parameter is set to that value:

            >>> builder.snapshot().layout.parameters
            {'__record__': 'points'}

        The `"__record__"` parameter can be used to add behavior to the records
        in the array, as described in #ak.Array, #ak.Record, and #ak.behavior.
        N)rq   Zbeginrecord©r)   r{   r-   r-   r.   Úbegin_recordN  s    (zArrayBuilder.begin_recordc                 C  s   | j  |¡ | S )a  
        Args:
            key (str): The field key to fill.

        This method also returns the #ak.ArrayBuilder, so that it can be
        chained with the value that fills the slot.

        Prepares to fill a field; see #begin_record for an example.
        )rq   Úfield)r)   r:   r-   r-   r.   r°  x  s    
zArrayBuilder.fieldc                 C  s   | j  ¡  dS )z 
        Ends a record.
        N)rq   Z	endrecordr�   r-   r-   r.   Ú
end_record…  s    zArrayBuilder.end_recordc                 C  s   | j  |¡ dS )ag  
        Args:
            obj: The data to append (None, bool, int, float, bytes, str, or
                anything recognized by #ak.from_iter).

        Appends any type, which can be a shorthand for #null,
        #boolean, #integer, #real, #bytestring, or #string, but also
        an #ak.Array or #ak.Record to *reference* values from an existing
        dataset, or any Python object to *convert* to Awkward Array.

        If `obj` is an iterable (including dict), this is equivalent to
        #ak.from_iter except that it fills an existing #ak.ArrayBuilder,
        rather than creating a new one.
        N©rq   Zfromiter)r)   Úobjr-   r-   r.   rt   ‹  s    zArrayBuilder.appendc                 C  s   |D ]}| j  |¡ qdS )z�
        Args:
            obj (iterable): Iterable of data to extend this ArrayBuilder with.

        Appends every value from `obj`.
        Nr²  )r)   r³  rÐ   r-   r-   r.   Úextendœ  s    zArrayBuilder.extendc                   @  s   e Zd Zdd„ Zdd„ ZdS )zArrayBuilder._Nestedc                 C  s
   || _ d S r<   )Ú_arraybuilder)r)   Úarraybuilderr-   r-   r.   r†   §  s    zArrayBuilder._Nested.__init__c                 C  s^   t | jjƒ}dtdƒ t| jƒ }t|ƒ|krJ|d |d … d |d  }d| j› d|› d�S )	Nrû   z<ArrayBuilder. type=>r–  r—  rf   z<ArrayBuilder.r  r  )r  rµ  rÃ   r>   Ú_name)r)   rÃ   r˜  r-   r-   r.   r  ª  s
    zArrayBuilder._Nested.__repr__N)rª   r«   r¬   r†   r  r-   r-   r-   r.   Ú_Nested¦  s   r¸  c                   @  s    e Zd ZdZdd„ Zdd„ ZdS )zArrayBuilder.ListÚlistc                 C  s   | j  ¡  d S r<   )rµ  r§  r�   r-   r-   r.   Ú	__enter__¶  s    zArrayBuilder.List.__enter__c                 C  s   | j  ¡  d S r<   )rµ  r¨  ©r)   rÁ   r—   Ú	tracebackr-   r-   r.   Ú__exit__¹  s    zArrayBuilder.List.__exit__N)rª   r«   r¬   r·  rº  r½  r-   r-   r-   r.   ÚList³  s   r¾  c                 C  s
   |   | ¡S )a4  
        Context manager to prevent unpaired #begin_list and #end_list. The
        example in the #begin_list documentation can be rewritten as

            >>> builder = ak.ArrayBuilder()
            >>> with builder.list():
            ...     builder.real(1.1)
            ...     builder.real(2.2)
            ...     builder.real(3.3)
            ...
            >>> with builder.list():
            ...     pass
            ...
            >>> with builder.list():
            ...     builder.real(4.4)
            ...     builder.real(5.5)
            ...

        to produce the same result.

            >>> builder.show()
            [[1.1, 2.2, 3.3],
             [],
             [4.4, 5.5]]

        Since context managers aren't yet supported by Numba, this method
        can't be used in Numba.
        )r¾  r�   r-   r-   r.   r¹  ¼  s    zArrayBuilder.listc                      s0   e Zd ZdZ‡ fdd„Zdd„ Zdd„ Z‡  ZS )zArrayBuilder.TuplerÓ   c                   s   t ƒ  |¡ || _d S r<   )rˆ   r†   Ú
_numfields)r)   r¶  rª  r�   r-   r.   r†   Þ  s    zArrayBuilder.Tuple.__init__c                 C  s   | j  | j¡ d S r<   )rµ  r«  r¿  r�   r-   r-   r.   rº  â  s    zArrayBuilder.Tuple.__enter__c                 C  s   | j  ¡  d S r<   )rµ  r­  r»  r-   r-   r.   r½  å  s    zArrayBuilder.Tuple.__exit__©rª   r«   r¬   r·  r†   rº  r½  rŠ  r-   r-   r�   r.   ÚTupleÛ  s   rÁ  c                 C  s   |   | |¡S )aG  
        Context manager to prevent unpaired #begin_tuple and #end_tuple. The
        example in the #begin_tuple documentation can be rewritten as

            >>> builder = ak.ArrayBuilder()
            >>> with builder.tuple(3):
            ...     builder.index(0).integer(1)
            ...     builder.index(1).real(1.1)
            ...     builder.index(2).string("one")
            ...
            >>> with builder.tuple(3):
            ...     builder.index(0).integer(2)
            ...     builder.index(1).real(2.2)
            ...     builder.index(2).string("two")
            ...

        to produce the same result.

            >>> builder.show()
            [(1, 1.1, 'one'),
             (2, 2.2, 'two')]

        Since context managers aren't yet supported by Numba, this method
        can't be used in Numba.
        )rÁ  r©  r-   r-   r.   rÓ   è  s    zArrayBuilder.tuplec                      s0   e Zd ZdZ‡ fdd„Zdd„ Zdd„ Z‡  ZS )zArrayBuilder.Recordr�  c                   s   t ƒ  |¡ || _d S r<   )rˆ   r†   r·  )r)   r¶  r{   r�   r-   r.   r†     s    zArrayBuilder.Record.__init__c                 C  s   | j j| jd� d S )N)r{   )rµ  r¯  r·  r�   r-   r-   r.   rº    s    zArrayBuilder.Record.__enter__c                 C  s   | j  ¡  d S r<   )rµ  r±  r»  r-   r-   r.   r½    s    zArrayBuilder.Record.__exit__rÀ  r-   r-   r�   r.   r     s   r   c                 C  s   |   | |¡S )aô  
        Context manager to prevent unpaired #begin_record and #end_record. The
        example in the #begin_record documentation can be rewritten as

            >>> builder = ak.ArrayBuilder()
            >>> with builder.record("points"):
            ...     builder.field("x").real(1)
            ...     builder.field("y").real(1.1)
            ...
            >>> with builder.record("points"):
            ...     builder.field("x").real(2)
            ...     builder.field("y").real(2.2)
            ...

        to produce the same result.

            >>> builder.show()
            [{x: 1, y: 1.1},
             {x: 2, y: 2.2}]

        Since context managers aren't yet supported by Numba, this method
        can't be used in Numba.
        )r   r®  r-   r-   r.   r�    s    zArrayBuilder.record)NN)T)N)N)N)N)5rª   r«   r¬   rl   r†   Úclassmethodr”  r2   re   r‰  ra   r±   r°   r¶   rÁ   rÃ   rÄ   rþ   r  r  r   r$  rT   rH  rZ  r€  r•  rœ  r�  rŸ  r¡  r¢  r£  r¤  r¥  r¦  r§  r¨  r«  r¬  r­  r¯  r°  r±  rt   r´  r¸  r¾  r¹  rÁ  rÓ   r   r�  r-   r-   r-   r.   r   C	  s€    




ûø*


	
*
	r   c                 C  s
   d| _ | S )NT)Úignore_in_to_list)Zgetitem_functionr-   r-   r.   rÃ  ,  s    rÃ  rÁ   ©r³  c                 C  s@   t | ttfƒr ddœdd„}|S t | tƒr<ddœdd„}|S d S )Nr   rÄ  c                 S  s   | j jS r<   )rS   rd   rÄ  r-   r-   r.   Úfinder5  s    z&find_highlevel_backend.<locals>.finderr   c                 S  s   t  ¡ S r<   ©r   ÚinstancerÄ  r-   r-   r.   Únumpy_lookup;  s    z,find_highlevel_backend.<locals>.numpy_lookup)Ú
issubclassr   r   r   )r³  rÅ  rÈ  r-   r-   r.   Úfind_highlevel_backend1  s    
rÊ  c                 C  s"   t | tjƒrddœdd„}|S d S )Nr   rÄ  c                 S  s   t  ¡ S r<   rÆ  rÄ  r-   r-   r.   rÈ  E  s    z+find_lowlevel_backend.<locals>.numpy_lookup)rÉ  r   r   )r³  rÈ  r-   r-   r.   Úfind_lowlevel_backendA  s    rË  )r4   )JÚ
__future__r   r#   rN   r0   r7  r$   r"  r4  rò   rd  ÚreÚcollections.abcr   r   r   r   Zawkward_cpp.libr   r„  rL   Zawkward._connect.histZawkward._attrsr   r	   Zawkward._backends.dispatchr
   Zawkward._backends.numpyr   Zawkward._behaviorr   r   r   Zawkward._layoutr   Zawkward._nplikes.numpyr   Zawkward._nplikes.numpy_liker   Zawkward._operatorsr   Zawkward._pickler   r   r   Zawkward._regularizer   Zawkward._typingr   r   Zawkward._utilr   Zawkward.prettyprintr   r   rý   Ú__all__rÇ  rŽ  rL  Úcompilerð   rJ   rp   r   r3   rR   r_   r   r   r   rÃ  rÊ  rË  r-   r-   r-   r.   Ú<module>   s„   
.                 6     n