o
    ¹­§i;6  ã                   @  s‚   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 dl	m
Z
 er8d dlmZmZ d dlmZ d d	lmZ G d
d„ dƒZdS )é    )ÚannotationsN)ÚTYPE_CHECKING)Úparse_into_list_of_expressions)Úqualified_type_name)Ú	wrap_expr)ÚIterableÚSequence)ÚExpr)ÚIntoExprc                   @  sZ   e Zd ZdZdZd"dd„Zd#dd„Zd$dd„Zd%dd„Zd&dd„Z	d%dd„Z
d'dd „Zd!S )(ÚExprStructNameSpacez)Namespace for struct related expressions.ÚstructÚexprr	   ÚreturnÚNonec                 C  s   |j | _ d S )N)Ú_pyexpr)Úselfr   © r   úI/home/app/Keep/.python/lib/python3.10/site-packages/polars/expr/struct.pyÚ__init__   s   zExprStructNameSpace.__init__Úitemú	str | intc                 C  sL   t |tƒr
|  |¡S t |tƒrt| j |¡ƒS dt|ƒ›d|›d}t|ƒ‚)Nzexpected type 'int | str', got z (ú))	Ú
isinstanceÚstrÚfieldÚintr   r   Zstruct_field_by_indexr   Ú	TypeError)r   r   Úmsgr   r   r   Ú__getitem__   s   


zExprStructNameSpace.__getitem__Únameústr | list[str]Ú
more_namesr   c                 G  sJ   |rg t |tƒr|gn|¢|¢}t |tƒrt| j |¡ƒS t| j |¡ƒS )u  
        Retrieve one or multiple `Struct` field(s) as a new Series.

        Parameters
        ----------
        name
            Name of the struct field to retrieve.
        *more_names
            Additional struct field names.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "aaa": [1, 2],
        ...         "bbb": ["ab", "cd"],
        ...         "ccc": [True, None],
        ...         "ddd": [[1, 2], [3]],
        ...     }
        ... ).select(pl.struct("aaa", "bbb", "ccc", "ddd").alias("struct_col"))
        >>> df
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ struct_col           â”‚
        â”‚ ---                  â”‚
        â”‚ struct[4]            â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ {1,"ab",true,[1, 2]} â”‚
        â”‚ {2,"cd",null,[3]}    â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Retrieve struct field(s) as Series:

        >>> df.select(pl.col("struct_col").struct.field("bbb"))
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ bbb â”‚
        â”‚ --- â”‚
        â”‚ str â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ ab  â”‚
        â”‚ cd  â”‚
        â””â”€â”€â”€â”€â”€â”˜

        >>> df.select(
        ...     pl.col("struct_col").struct.field("bbb"),
        ...     pl.col("struct_col").struct.field("ddd"),
        ... )
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ bbb â”† ddd       â”‚
        â”‚ --- â”† ---       â”‚
        â”‚ str â”† list[i64] â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ ab  â”† [1, 2]    â”‚
        â”‚ cd  â”† [3]       â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Use wildcard expansion:

        >>> df.select(pl.col("struct_col").struct.field("*"))
        shape: (2, 4)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ aaa â”† bbb â”† ccc  â”† ddd       â”‚
        â”‚ --- â”† --- â”† ---  â”† ---       â”‚
        â”‚ i64 â”† str â”† bool â”† list[i64] â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ 1   â”† ab  â”† true â”† [1, 2]    â”‚
        â”‚ 2   â”† cd  â”† null â”† [3]       â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Retrieve multiple fields by name:

        >>> df.select(pl.col("struct_col").struct.field("aaa", "bbb"))
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”
        â”‚ aaa â”† bbb â”‚
        â”‚ --- â”† --- â”‚
        â”‚ i64 â”† str â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡
        â”‚ 1   â”† ab  â”‚
        â”‚ 2   â”† cd  â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”˜

        Retrieve multiple fields by regex expansion:

        >>> df.select(pl.col("struct_col").struct.field("^a.*|b.*$"))
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”
        â”‚ aaa â”† bbb â”‚
        â”‚ --- â”† --- â”‚
        â”‚ i64 â”† str â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡
        â”‚ 1   â”† ab  â”‚
        â”‚ 2   â”† cd  â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”˜

        Notes
        -----
        The `struct` namespace has implemented `__getitem__`
        so you can also access fields by index:

        >>> df.select(pl.col("struct_col").struct[1])
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”
        â”‚ bbb â”‚
        â”‚ --- â”‚
        â”‚ str â”‚
        â•žâ•â•â•â•â•â•¡
        â”‚ ab  â”‚
        â”‚ cd  â”‚
        â””â”€â”€â”€â”€â”€â”˜
        )r   r   Úlistr   r   Zstruct_multiple_fieldsZstruct_field_by_name)r   r   r!   r   r   r   r   "   s
   r
zExprStructNameSpace.fieldc                 C  s
   |   d¡S )uü  
        Expand the struct into its individual fields.

        Alias for `Expr.struct.field("*")`.

        >>> df = pl.DataFrame(
        ...     {
        ...         "aaa": [1, 2],
        ...         "bbb": ["ab", "cd"],
        ...         "ccc": [True, None],
        ...         "ddd": [[1, 2], [3]],
        ...     }
        ... ).select(pl.struct("aaa", "bbb", "ccc", "ddd").alias("struct_col"))
        >>> df
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ struct_col           â”‚
        â”‚ ---                  â”‚
        â”‚ struct[4]            â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ {1,"ab",true,[1, 2]} â”‚
        â”‚ {2,"cd",null,[3]}    â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        >>> df.select(pl.col("struct_col").struct.unnest())
        shape: (2, 4)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ aaa â”† bbb â”† ccc  â”† ddd       â”‚
        â”‚ --- â”† --- â”† ---  â”† ---       â”‚
        â”‚ i64 â”† str â”† bool â”† list[i64] â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ 1   â”† ab  â”† true â”† [1, 2]    â”‚
        â”‚ 2   â”† cd  â”† null â”† [3]       â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        Ú*)r   ©r   r   r   r   Úunnest›   s   
#zExprStructNameSpace.unnestÚnamesúSequence[str]c                 C  s   t | j |¡ƒS )u)
  
        Rename the fields of the struct.

        Parameters
        ----------
        names
            New names, given in the same order as the struct's fields.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "aaa": [1, 2],
        ...         "bbb": ["ab", "cd"],
        ...         "ccc": [True, None],
        ...         "ddd": [[1, 2], [3]],
        ...     }
        ... ).select(pl.struct("aaa", "bbb", "ccc", "ddd").alias("struct_col"))
        >>> df
        shape: (2, 1)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ struct_col           â”‚
        â”‚ ---                  â”‚
        â”‚ struct[4]            â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ {1,"ab",true,[1, 2]} â”‚
        â”‚ {2,"cd",null,[3]}    â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        >>> df.unnest("struct_col")
        shape: (2, 4)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ aaa â”† bbb â”† ccc  â”† ddd       â”‚
        â”‚ --- â”† --- â”† ---  â”† ---       â”‚
        â”‚ i64 â”† str â”† bool â”† list[i64] â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ 1   â”† ab  â”† true â”† [1, 2]    â”‚
        â”‚ 2   â”† cd  â”† null â”† [3]       â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Rename fields:

        >>> df = df.select(
        ...     pl.col("struct_col").struct.rename_fields(["www", "xxx", "yyy", "zzz"])
        ... )
        >>> df.unnest("struct_col")
        shape: (2, 4)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ www â”† xxx â”† yyy  â”† zzz       â”‚
        â”‚ --- â”† --- â”† ---  â”† ---       â”‚
        â”‚ i64 â”† str â”† bool â”† list[i64] â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ 1   â”† ab  â”† true â”† [1, 2]    â”‚
        â”‚ 2   â”† cd  â”† null â”† [3]       â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Following a rename, the previous field names (obviously) cannot be referenced:

        >>> df.select(pl.col("struct_col").struct.field("aaa"))  # doctest: +SKIP
        StructFieldNotFoundError: aaa
        )r   r   Zstruct_rename_fields)r   r&   r   r   r   Úrename_fieldsÀ   s   >z!ExprStructNameSpace.rename_fieldsc                 C  s   t | j ¡ ƒS )u  
        Convert this struct to a string column with json values.

        Examples
        --------
        >>> pl.DataFrame(
        ...     {"a": [{"a": [1, 2], "b": [45]}, {"a": [9, 1, 3], "b": None}]}
        ... ).with_columns(pl.col("a").struct.json_encode().alias("encoded"))
        shape: (2, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ a                â”† encoded                â”‚
        â”‚ ---              â”† ---                    â”‚
        â”‚ struct[2]        â”† str                    â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ {[1, 2],[45]}    â”† {"a":[1,2],"b":[45]}   â”‚
        â”‚ {[9, 1, 3],null} â”† {"a":[9,1,3],"b":null} â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        )r   r   Zstruct_json_encoder$   r   r   r   Újson_encode   s   zExprStructNameSpace.json_encodeÚexprsúIntoExpr | Iterable[IntoExpr]Únamed_exprsr
   c                 O  s<   t ttj dd¡ƒƒ}t|i |¤d|i¤Ž}t| j |¡ƒS )uü
  
        Add or overwrite fields of this struct.

        This is similar to `with_columns` on `DataFrame`.

        .. versionadded:: 0.20.27

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "coords": [{"x": 1, "y": 4}, {"x": 4, "y": 9}, {"x": 9, "y": 16}],
        ...         "multiply": [10, 2, 3],
        ...     }
        ... )
        >>> df
        shape: (3, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ coords    â”† multiply â”‚
        â”‚ ---       â”† ---      â”‚
        â”‚ struct[2] â”† i64      â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ {1,4}     â”† 10       â”‚
        â”‚ {4,9}     â”† 2        â”‚
        â”‚ {9,16}    â”† 3        â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        >>> df = df.with_columns(
        ...     pl.col("coords").struct.with_fields(
        ...         pl.field("x").sqrt(),
        ...         y_mul=pl.field("y") * pl.col("multiply"),
        ...     )
        ... )
        >>> df
        shape: (3, 2)
        â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ coords      â”† multiply â”‚
        â”‚ ---         â”† ---      â”‚
        â”‚ struct[3]   â”† i64      â”‚
        â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ {1.0,4,40}  â”† 10       â”‚
        â”‚ {2.0,9,18}  â”† 2        â”‚
        â”‚ {3.0,16,48} â”† 3        â”‚
        â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
        >>> df.unnest("coords")
        shape: (3, 4)
        â”Œâ”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
        â”‚ x   â”† y   â”† y_mul â”† multiply â”‚
        â”‚ --- â”† --- â”† ---   â”† ---      â”‚
        â”‚ f64 â”† i64 â”† i64   â”† i64      â”‚
        â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡
        â”‚ 1.0 â”† 4   â”† 40    â”† 10       â”‚
        â”‚ 2.0 â”† 9   â”† 18    â”† 2        â”‚
        â”‚ 3.0 â”† 16  â”† 48    â”† 3        â”‚
        â””â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”´â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

        Parameters
        ----------
        *exprs
            Field(s) to add, specified as positional arguments.
            Accepts expression input. Strings are parsed as column names, other
            non-expression inputs are parsed as literals.
        **named_exprs
            Additional fields to add, specified as keyword arguments.
            The columns will be renamed to the keyword used.

        See Also
        --------
        field
        ZPOLARS_AUTO_STRUCTIFYr   Z__structify)	Úboolr   ÚosÚenvironÚgetr   r   r   Zstruct_with_fields)r   r*   r,   Z	structifyZpyexprsr   r   r   Úwith_fields  s   JÿÿÿzExprStructNameSpace.with_fieldsN)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	   )Ú__name__Ú
__module__Ú__qualname__Ú__doc__Ú	_accessorr   r   r   r%   r(   r)   r1   r   r   r   r   r      s    


	
y
%
@r   )Ú
__future__r   r.   Útypingr   Zpolars._utils.parser   Zpolars._utils.variousr   Zpolars._utils.wrapr   Úcollections.abcr   r   Zpolarsr	   Zpolars._typingr
   r   r   r   r   r   Ú<module>   s    