a
    yn„f:  ã                   @  sj   d dl mZ d dlZd dlmZ d dlmZ d dlm	Z	 dZ
e	 ¡ Zeƒ dd dd	d
œdd„ƒZdd„ ZdS )é    )ÚannotationsN)Úregularize_backend)Úhigh_level_function)ÚNumpyMetadata)Ú
to_buffersú{form_key}-{attribute}únode{id}ú<)Úid_startÚbackendÚ	byteorderc                c  s   | fV  t | ||||||ƒS )u‡  
    Args:
        array: Array-like data (anything #ak.to_layout recognizes).
        container (None or MutableMapping): The str â†’ NumPy arrays (or
            Python buffers) that represent the decomposed Awkward Array. This
            `container` is only assumed to have a `__setitem__` method that
            accepts strings as keys.
        buffer_key (str or callable): Python format string containing
            `"{form_key}"` and/or `"{attribute}"` or a function that takes these
            (and/or `layout`) as keyword arguments and returns a string to use
            as a key for a buffer in the `container`. The `form_key` is the result
            of applying `form_key` (below), and the `attribute` is a hard-coded
            string representing the buffer's function (e.g. `"data"`, `"offsets"`,
            `"index"`).
        form_key (str, callable): Python format string containing
            `"{id}"` or a function that takes this (and/or `layout`) as a keyword
            argument and returns a string to use as a key for a Form node.
            Together, the `buffer_key` and `form_key` links attributes of each Form
            node to data in the `container`.
        id_start (int): Starting `id` to use in `form_key` and hence `buffer_key`.
            This integer increases in a depth-first walk over the `array` nodes and
            can be used to generate unique keys for each Form.
        backend (`"cpu"`, `"cuda"`, `"jax"`, None): Backend to use to
            generate values that are put into the `container`. The default,
            `"cpu"`, makes NumPy arrays, which are in main memory
            (e.g. not GPU) and satisfy Python's Buffer protocol. If all the
            buffers in `array` have the same `backend` as this, they won't be
            copied. If the backend is None, then the backend of the layout
            will be used to generate the buffers.
        byteorder (`"<"`, `">"`): Endianness of buffers written to `container`.
            If the byteorder does not match the current system byteorder, the
            arrays will be copied.

    Decomposes an Awkward Array into a Form and a collection of memory buffers,
    so that data can be losslessly written to file formats and storage devices
    that only map names to binary blobs (such as a filesystem directory).

    This function returns a 3-tuple:

        (form, length, container)

    where the `form` is a #ak.forms.Form (whose string representation is JSON),
    the `length` is an integer (`len(array)`), and the `container` is either
    the MutableMapping you passed in or a new dict containing the buffers (as
    NumPy arrays).

    These are also the first three arguments of #ak.from_buffers, so a full
    round-trip is

        >>> reconstituted = ak.from_buffers(*ak.to_buffers(original))

    The `container` argument lets you specify your own MutableMapping, which
    might be an interface to some storage format or device (e.g. h5py). It's
    okay if the `container` drops NumPy's `dtype` and `shape` information,
    leaving raw bytes, since `dtype` and `shape` can be reconstituted from
    the #ak.forms.NumpyForm.

    The `buffer_key` and `form_key` arguments let you configure the names of the
    buffers added to the `container` and string labels on each Form node, so that
    the two can be uniquely matched later. `buffer_key` and `form_key` are distinct
    arguments to allow for more indirection (buffer keys can differ from Form keys,
    as long as there's a way to map them to each other) and because some Form nodes,
    such as #ak.forms.ListForm and #ak.forms.UnionForm, have more than one attribute
    (`starts` and `stops` for #ak.forms.ListForm and `tags` and `index` for
    #ak.forms.UnionForm).

    Awkward 1.x also included partition numbers (`"part0-"`, `"part1-"`, ...) in
    the buffer keys. In version 2.x onward, partitioning is handled externally by
    Dask, but partition numbers can be emulated by prepending a fixed `"partN-"`
    string to the `buffer_key`. The `array` represents exactly one partition.

    Here is a simple example:

        >>> original = ak.Array([[1, 2, 3], [], [4, 5]])
        >>> form, length, container = ak.to_buffers(original)
        >>> print(form)
        {
            "class": "ListOffsetArray",
            "offsets": "i64",
            "content": {
                "class": "NumpyArray",
                "primitive": "int64",
                "form_key": "node1"
            },
            "form_key": "node0"
        }
        >>> length
        3
        >>> container
        {'node0-offsets': array([0, 3, 3, 5]), 'node1-data': array([1, 2, 3, 4, 5])}

    which may be read back with

        >>> ak.from_buffers(form, length, container)
        <Array [[1, 2, 3], [], [4, 5]] type='3 * var * int64'>

    If you intend to use this function for saving data, you may want to pack it
    first with #ak.to_packed.

    See also #ak.from_buffers and #ak.to_packed.
    )Ú_impl)ÚarrayÚ	containerÚ
buffer_keyÚform_keyr
   r   r   © r   úc/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/awkward/operations/ak_to_buffers.pyr      s    qr   c              	   C  s<   t jj| ddd�}|d ur"t|ƒ}t jj|||||||d�S )NFÚerror)Zallow_recordZprimitive_policy)r   r   r   r
   r   r   )ÚakÚ
operationsZ	to_layoutr   Z_dor   )r   r   r   r   r
   r   r   Zlayoutr   r   r   r   †   s    ÿùr   )Nr   r   )Ú
__future__r   Zawkwardr   Zawkward._backends.dispatchr   Zawkward._dispatchr   Zawkward._nplikes.numpy_liker   Ú__all__ÚinstanceÚnpr   r   r   r   r   r   Ú<module>   s       üøv