o
    Ýñh( ã                   @  sZ  U 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 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 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 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 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% d dl$m&Z& d dl$m'Z' er!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- d d!l.m/Z/ d d"l.m0Z0 d d#lm1Z1 d d$l2m3Z3 d d%l2m4Z4 d d&l2m5Z5 d d'l2m6Z6 d d(l2m7Z7 d d)l2m8Z8 d d*l2m9Z9 d d+l2m:Z: e+d,Z;e(d-Z<ee0eef ge/eef f Z=d.e>d/< G d0d1 d1Z?d1gZ@d2S )3é    )Úannotations)ÚTYPE_CHECKING)ÚAny)ÚCallable)ÚIterable)ÚMapping)ÚSequence)ÚExprKind)ÚExprMetadata)Ú
WindowKind©Úapply_n_ary_operation)Úcombine_metadata)Úcombine_metadata_binary_op)Úextract_compliant)Ú_validate_dtype)ÚInvalidOperationError)ÚLengthChangingExprError©ÚExprCatNamespace©ÚExprDateTimeNamespace©ÚExprListNamespace©ÚExprNameNamespace©ÚExprStringNamespace©ÚExprStructNamespace)Ú	to_native)Ú_validate_rolling_arguments)Úflatten)Úissue_deprecation_warning)ÚTypeVar)ÚConcatenate)Ú	ParamSpec)ÚSelf)Ú	TypeAlias)ÚCompliantExpr)ÚCompliantNamespace)ÚDType)ÚClosedInterval)ÚFillNullStrategy)ÚIntoExpr)ÚNonNestedLiteral)ÚNumericLiteral)Ú
RankMethod)ÚRollingInterpolationMethod)ÚTemporalLiteralÚPSÚRr(   Ú_ToCompliantc                   @  s¬  e 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*ddZ
d+d"d#Zd,d&d'Zd-d*d+Zd-d,d-Zd.d/d0Zd.d1d2Zd.d3d4Zd.d5d6Zd.d7d8Zd.d9d:Zd.d;d<Zd.d=d>Zd.d?d@Zd.dAdBZd.dCdDZd.dEdFZd.dGdHZd.dIdJZd.dKdLZd.dMdNZd.dOdPZd.dQdRZ d.dSdTZ!d.dUdVZ"d.dWdXZ#d.dYdZZ$d)d[d\Z%d)d]d^Z&d)d_d`Z'dadadadadbdcddded/dpdqZ(d)drdsZ)d)dtduZ*dcdvd0dxdyZ+dcdvd0dzd{Z,	ad1d2ddZ-d)ddZ.d3ddZ/d)ddZ0d)ddZ1d)ddZ2d)ddZ3d)ddZ4d)ddZ5d)ddZ6d)ddZ7dddd4ddZ8d)ddZ9d5ddZ:	ad1dadd6d€d¥Z;dddddŠd7d©dªZ<	«d8d9d±d²Z=d.d³dŽZ>d:d¶d·Z?d)džd¹Z@d)dºd»ZAd)dŒdœZB	a	a	ad;d<dÄdÅZCd)dÆdÇZD	ad1dadddadÈd=dÌdÍZEdadÎd>dÓdÔZFd)dÕdÖZGd)d×dØZHd)dÙdÚZId)dÛdÜZJd)dÝdÞZKd?dãdäZLd@d5dædçZMd@d5dèdéZNdAdBdìdíZOd)dîdïZPdAdCdñdòZQ	a	adDdEdôdõZRd)död÷ZSd)dødùZTdddd4dúdûZUdddd4düdýZVdddd4dþdÿZWdddd4d dZXdaddddFddZYdaddddFddZZdadddcd	dGd
dZ[dadddcd	dGddZ\dHddddIddZ]e^dJddZ_e^dKddZ`e^dLddZae^dMddZbe^dNd!d"Zce^dOd$d%ZddaS (P  ÚExprÚto_compliant_exprr6   Úmetadatar
   ÚreturnÚNonec                   s    d fdd}| _ | _d S )NÚplxúCompliantNamespace[Any, Any]r:   úCompliantExpr[Any, Any]c                   s   | } j |_ |S ©N©Ú	_metadata)r<   Úresult©Úselfr8   © úA/var/www/vscode/kcb/lib/python3.10/site-packages/narwhals/expr.pyÚfunc=   s   zExpr.__init__.<locals>.func)r<   r=   r:   r>   )Ú_to_compliant_exprrA   )rD   r8   r9   rG   rE   rC   rF   Ú__init__;   s   
zExpr.__init__úCallable[[Any], Any]r'   c                 C  s0   | j j ¡ r|  || j  tj¡¡S |  || j ¡S r?   )rA   ÚkindÚ	is_windowÚ	__class__Ú with_kind_and_uncloseable_windowr	   Ú	TRANSFORMrC   rE   rE   rF   Ú_with_callableE   s   þzExpr._with_callablec                 C  ó.   | j j ¡ rd}t||  || j  tj¡¡S ©Nz9Aggregations can't be applied to scalar-like expressions.)rA   rK   Úis_scalar_liker   rM   Ú	with_kindr	   ÚAGGREGATION©rD   r8   ÚmsgrE   rE   rF   Ú_with_aggregationQ   ó   ÿzExpr._with_aggregationc                 C  rQ   rR   )rA   rK   rS   r   rM   Úwith_kind_and_closeable_windowr	   rU   rV   rE   rE   rF   Ú!_with_order_dependent_aggregationY   s   þz&Expr._with_order_dependent_aggregationc                 C  rQ   )Nz<Length-changing can't be applied to scalar-like expressions.)rA   rK   rS   r   rM   rT   r	   Ú
FILTRATIONrV   rE   rE   rF   Ú_with_filtrationd   rY   zExpr._with_filtrationÚstrc                 C  s   d| j  dS )NzNarwhals Expr
metadata: Ú
r@   ©rD   rE   rE   rF   Ú__repr__l   ó   zExpr.__repr__c                   ó       fdd¡S )Nc                   s      | ¡ ¡  ¡ S r?   )rH   ÚabsÚsum©r<   r`   rE   rF   Ú<lambda>s   ó    z$Expr._taxicab_norm.<locals>.<lambda>©rX   r`   rE   r`   rF   Ú_taxicab_normo   s   
ÿzExpr._taxicab_normÚnamec                   ó      fdd¡S )uÄ  Rename the expression.

        Arguments:
            name: The new name.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2], "b": [4, 5]})
            >>> df = nw.from_native(df_native)
            >>> df.select((nw.col("b") + 10).alias("c"))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |          c       |
            |      0  14       |
            |      1  15       |
            ââââââââââââââââââââ
        c                   ó     | ¡  ¡S r?   )rH   Úaliasrf   ©rk   rD   rE   rF   rg      ó    zExpr.alias.<locals>.<lambda>©rP   )rD   rk   rE   ro   rF   rn   w   s   z
Expr.aliasÚfunctionú"Callable[Concatenate[Self, PS], R]ÚargsúPS.argsÚkwargsú	PS.kwargsr5   c                 O  s   || g|¢R i |€S )u  Pipe function call.

        Arguments:
            function: Function to apply.
            args: Positional arguments to pass to function.
            kwargs: Keyword arguments to pass to function.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 4]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_piped=nw.col("a").pipe(lambda x: x + 1))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |     a  a_piped   |
            |  0  1        2   |
            |  1  2        3   |
            |  2  3        4   |
            |  3  4        5   |
            ââââââââââââââââââââ
        rE   )rD   rr   rt   rv   rE   rE   rF   Úpipe   s    z	Expr.pipeÚdtypeúDType | type[DType]c                   s   t     fdd¡S )u=  Redefine an object's data type.

        Arguments:
            dtype: Data type that the object will be cast into.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("foo").cast(nw.Float32), nw.col("bar").cast(nw.UInt8))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |      foo  bar    |
            |   0  1.0    6    |
            |   1  2.0    7    |
            |   2  3.0    8    |
            ââââââââââââââââââââ
        c                   rm   r?   )rH   Úcastrf   ©ry   rD   rE   rF   rg   Ë   rp   zExpr.cast.<locals>.<lambda>)r   rP   )rD   ry   rE   r|   rF   r{   ²   s   z	Expr.castÚotherú
Self | Anyc                   ó      fddt ¡S )Nc                   ó   t | dd  ddS )Nc                 S  s   | |kS r?   rE   ©ÚxÚyrE   rE   rF   rg   Ñ   ó    z/Expr.__eq__.<locals>.<lambda>.<locals>.<lambda>T©Ú
str_as_litr   rf   ©r}   rD   rE   rF   rg   Ð   ó    ÿzExpr.__eq__.<locals>.<lambda>©rM   r   ©rD   r}   rE   r   rF   Ú__eq__Î   ó   üzExpr.__eq__c                   r   )Nc                   r   )Nc                 S  s   | |kS r?   rE   r   rE   rE   rF   rg   Ù   r   z/Expr.__ne__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   Ø   r   zExpr.__ne__.<locals>.<lambda>r   r   rE   r   rF   Ú__ne__Ö   r   zExpr.__ne__r   c                   r   )Nc                   r   )Nc                 S  s   | |@ S r?   rE   r   rE   rE   rF   rg   á   r   z0Expr.__and__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   à   r   zExpr.__and__.<locals>.<lambda>r   r   rE   r   rF   Ú__and__Þ   r   zExpr.__and__c                 C  s   | |@   d¡S ©NÚliteral©rn   r   rE   rE   rF   Ú__rand__æ   rb   zExpr.__rand__c                   r   )Nc                   r   )Nc                 S  s   | |B S r?   rE   r   rE   rE   rF   rg   ì   r   z/Expr.__or__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   ë   r   zExpr.__or__.<locals>.<lambda>r   r   rE   r   rF   Ú__or__é   r   zExpr.__or__c                 C  s   | |B   d¡S r   r   r   rE   rE   rF   Ú__ror__ñ   rb   zExpr.__ror__c                   r   )Nc                   r   )Nc                 S  s   | | S r?   rE   r   rE   rE   rF   rg   ÷   r   z0Expr.__add__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   ö   r   zExpr.__add__.<locals>.<lambda>r   r   rE   r   rF   Ú__add__ô   r   zExpr.__add__c                 C  s   | |   d¡S r   r   r   rE   rE   rF   Ú__radd__ü   rb   zExpr.__radd__c                   r   )Nc                   r   )Nc                 S  s   | | S r?   rE   r   rE   rE   rF   rg     r   z0Expr.__sub__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg     r   zExpr.__sub__.<locals>.<lambda>r   r   rE   r   rF   Ú__sub__ÿ   r   zExpr.__sub__c                   r   )Nc                   r   )Nc                 S  ó
   |   |¡S r?   )Ú__rsub__r   rE   rE   rF   rg     ó   
 z1Expr.__rsub__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   	  ó    ûzExpr.__rsub__.<locals>.<lambda>r   r   rE   r   rF   r     ó   øzExpr.__rsub__c                   r   )Nc                   r   )Nc                 S  s   | | S r?   rE   r   rE   rE   rF   rg     r   z4Expr.__truediv__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg     r   z"Expr.__truediv__.<locals>.<lambda>r   r   rE   r   rF   Ú__truediv__  r   zExpr.__truediv__c                   r   )Nc                   r   )Nc                 S  r   r?   )Ú__rtruediv__r   rE   rE   rF   rg     r   z5Expr.__rtruediv__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg     r   z#Expr.__rtruediv__.<locals>.<lambda>r   r   rE   r   rF   r     r   zExpr.__rtruediv__c                   r   )Nc                   r   )Nc                 S  s   | | S r?   rE   r   rE   rE   rF   rg   *  r   z0Expr.__mul__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   )  r   zExpr.__mul__.<locals>.<lambda>r   r   rE   r   rF   Ú__mul__'  r   zExpr.__mul__c                 C  s   | |   d¡S r   r   r   rE   rE   rF   Ú__rmul__/  rb   zExpr.__rmul__c                   r   )Nc                   r   )Nc                 S  s   | |kS r?   rE   r   rE   rE   rF   rg   5  r   z/Expr.__le__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   4  r   zExpr.__le__.<locals>.<lambda>r   r   rE   r   rF   Ú__le__2  r   zExpr.__le__c                   r   )Nc                   r   )Nc                 S  s   | |k S r?   rE   r   rE   rE   rF   rg   =  r   z/Expr.__lt__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   <  r   zExpr.__lt__.<locals>.<lambda>r   r   rE   r   rF   Ú__lt__:  r   zExpr.__lt__c                   r   )Nc                   r   )Nc                 S  s   | |kS r?   rE   r   rE   rE   rF   rg   E  r   z/Expr.__gt__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   D  r   zExpr.__gt__.<locals>.<lambda>r   r   rE   r   rF   Ú__gt__B  r   zExpr.__gt__c                   r   )Nc                   r   )Nc                 S  s   | |kS r?   rE   r   rE   rE   rF   rg   M  r   z/Expr.__ge__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   L  r   zExpr.__ge__.<locals>.<lambda>r   r   rE   r   rF   Ú__ge__J  r   zExpr.__ge__c                   r   )Nc                   r   )Nc                 S  s   | | S r?   rE   r   rE   rE   rF   rg   U  r   z0Expr.__pow__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   T  r   zExpr.__pow__.<locals>.<lambda>r   r   rE   r   rF   Ú__pow__R  r   zExpr.__pow__c                   r   )Nc                   r   )Nc                 S  r   r?   )Ú__rpow__r   rE   rE   rF   rg   ^  r   z1Expr.__rpow__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   \  r   zExpr.__rpow__.<locals>.<lambda>r   r   rE   r   rF   rŠ   Z  r   zExpr.__rpow__c                   r   )Nc                   r   )Nc                 S  s   | | S r?   rE   r   rE   rE   rF   rg   i  r   z5Expr.__floordiv__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   h  r   z#Expr.__floordiv__.<locals>.<lambda>r   r   rE   r   rF   Ú__floordiv__f  r   zExpr.__floordiv__c                   r   )Nc                   r   )Nc                 S  r   r?   )Ú__rfloordiv__r   rE   rE   rF   rg   r  r   z6Expr.__rfloordiv__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   p  r   z$Expr.__rfloordiv__.<locals>.<lambda>r   r   rE   r   rF   rš   n  r   zExpr.__rfloordiv__c                   r   )Nc                   r   )Nc                 S  s   | | S r?   rE   r   rE   rE   rF   rg   }  r   z0Expr.__mod__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg   |  r   zExpr.__mod__.<locals>.<lambda>r   r   rE   r   rF   Ú__mod__z  r   zExpr.__mod__c                   r   )Nc                   r   )Nc                 S  r   r?   )Ú__rmod__r   rE   rE   rF   rg     r   z1Expr.__rmod__.<locals>.<lambda>.<locals>.<lambda>Tr   r   rf   r   rE   rF   rg     r   zExpr.__rmod__.<locals>.<lambda>r   r   rE   r   rF   rª     r   zExpr.__rmod__c                   rc   )Nc                   ó      | ¡ ¡ S r?   )rH   Ú
__invert__rf   r`   rE   rF   rg     ó    z!Expr.__invert__.<locals>.<lambda>rq   r`   rE   r`   rF   r¬     s   zExpr.__invert__c                   rc   )u  Return whether any of the values in the column are `True`.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [True, False], "b": [True, True]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").any())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a     b   |
            |  0  True  True   |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úanyrf   r`   rE   rF   rg   ¥  r­   zExpr.any.<locals>.<lambda>ri   r`   rE   r`   rF   r®     ó   zExpr.anyc                   rc   )u  Return whether all values in the column are `True`.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [True, False], "b": [True, True]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").all())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |         a     b  |
            |  0  False  True  |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úallrf   r`   rE   rF   rg   º  r­   zExpr.all.<locals>.<lambda>ri   r`   rE   r`   rF   r°   §  r¯   zExpr.allNTé   F©ÚcomÚspanÚ	half_lifeÚalphaÚadjustÚmin_samplesÚignore_nullsr³   úfloat | NonerŽ   rµ   r¶   r·   Úboolrž   Úintr¹   c             
     s       fdd¡S )u)  Compute exponentially-weighted moving average.

        Arguments:
            com: Specify decay in terms of center of mass, $\gamma$, with <br> $\alpha = \frac{1}{1+\gamma}\forall\gamma\geq0$
            span: Specify decay in terms of span, $\theta$, with <br> $\alpha = \frac{2}{\theta + 1} \forall \theta \geq 1$
            half_life: Specify decay in terms of half-life, $\tau$, with <br> $\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \tau } \right\} \forall \tau > 0$
            alpha: Specify smoothing factor alpha directly, $0 < \alpha \leq 1$.
            adjust: Divide by decaying adjustment factor in beginning periods to account for imbalance in relative weightings

                - When `adjust=True` (the default) the EW function is calculated
                  using weights $w_i = (1 - \alpha)^i$
                - When `adjust=False` the EW function is calculated recursively by
                  $$
                  y_0=x_0
                  $$
                  $$
                  y_t = (1 - \alpha)y_{t - 1} + \alpha x_t
                  $$
            min_samples: Minimum number of observations in window required to have a value, (otherwise result is null).
            ignore_nulls: Ignore missing values when calculating weights.

                - When `ignore_nulls=False` (default), weights are based on absolute
                  positions.
                  For example, the weights of $x_0$ and $x_2$ used in
                  calculating the final weighted average of $[x_0, None, x_2]$ are
                  $(1-\alpha)^2$ and $1$ if `adjust=True`, and
                  $(1-\alpha)^2$ and $\alpha$ if `adjust=False`.
                - When `ignore_nulls=True`, weights are based
                  on relative positions. For example, the weights of
                  $x_0$ and $x_2$ used in calculating the final weighted
                  average of $[x_0, None, x_2]$ are
                  $1-\alpha$ and $1$ if `adjust=True`,
                  and $1-\alpha$ and $\alpha$ if `adjust=False`.

        Returns:
            Expr

        Examples:
            >>> import pandas as pd
            >>> import polars as pl
            >>> import narwhals as nw
            >>> from narwhals.typing import IntoFrameT
            >>>
            >>> data = {"a": [1, 2, 3]}
            >>> df_pd = pd.DataFrame(data)
            >>> df_pl = pl.DataFrame(data)

            We define a library agnostic function:

            >>> def agnostic_ewm_mean(df_native: IntoFrameT) -> IntoFrameT:
            ...     df = nw.from_native(df_native)
            ...     return df.select(
            ...         nw.col("a").ewm_mean(com=1, ignore_nulls=False)
            ...     ).to_native()

            We can then pass either pandas or Polars to `agnostic_ewm_mean`:

            >>> agnostic_ewm_mean(df_pd)
                      a
            0  1.000000
            1  1.666667
            2  2.428571

            >>> agnostic_ewm_mean(df_pl)  # doctest: +NORMALIZE_WHITESPACE
            shape: (3, 1)
            ââââââââââââ
            â a        â
            â ---      â
            â f64      â
            ââââââââââââ¡
            â 1.0      â
            â 1.666667 â
            â 2.428571 â
            ââââââââââââ
        c              	     s     | ¡j dS )Nr²   )rH   Úewm_meanrf   ©r·   r¶   r³   rµ   r¹   rž   rD   rŽ   rE   rF   rg     s   
 ùzExpr.ewm_mean.<locals>.<lambda>rq   )rD   r³   rŽ   rµ   r¶   r·   rž   r¹   rE   rŸ   rF   rœ   Œ  s   VÿzExpr.ewm_meanc                   rc   )ui  Get mean value.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [-1, 0, 1], "b": [2, 4, 6]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").mean())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a    b    |
            |   0  0.0  4.0    |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úmeanrf   r`   rE   rF   rg   1  r­   zExpr.mean.<locals>.<lambda>ri   r`   rE   r`   rF   r¿     r¯   z	Expr.meanc                   rc   )u  Get median value.

        Returns:
            A new expression.

        Notes:
            Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").median())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a    b    |
            |   0  3.0  4.0    |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úmedianrf   r`   rE   rF   rg   I  r­   zExpr.median.<locals>.<lambda>ri   r`   rE   r`   rF   rÀ   3  ó   zExpr.median©ÚddofrÃ   c                  rl   )u_  Get standard deviation.

        Arguments:
            ddof: "Delta Degrees of Freedom": the divisor used in the calculation is N - ddof,
                where N represents the number of elements. By default ddof is 1.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [20, 25, 60], "b": [1.5, 1, -1.4]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").std(ddof=0))
            âââââââââââââââââââââââ
            | Narwhals DataFrame  |
            |---------------------|
            |          a         b|
            |0  17.79513  1.265789|
            âââââââââââââââââââââââ
        c                   ó     | ¡j dS ©NrÂ   )rH   Ústdrf   ©rÃ   rD   rE   rF   rg   c  rh   zExpr.std.<locals>.<lambda>ri   ©rD   rÃ   rE   rÇ   rF   rÆ   K  ó   ÿzExpr.stdc                  rl   )un  Get variance.

        Arguments:
            ddof: "Delta Degrees of Freedom": the divisor used in the calculation is N - ddof,
                     where N represents the number of elements. By default ddof is 1.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [20, 25, 60], "b": [1.5, 1, -1.4]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").var(ddof=0))
            âââââââââââââââââââââââââ
            |  Narwhals DataFrame   |
            |-----------------------|
            |            a         b|
            |0  316.666667  1.602222|
            âââââââââââââââââââââââââ
        c                   rÄ   rÅ   )rH   Úvarrf   rÇ   rE   rF   rg   ~  rh   zExpr.var.<locals>.<lambda>ri   rÈ   rE   rÇ   rF   rÊ   f  rÉ   zExpr.varú(Callable[[Any], CompliantExpr[Any, Any]]Úreturn_dtypeúDType | Nonec                   s"      fddj tj¡¡S )u¯  Apply a custom python function to a whole Series or sequence of Series.

        The output of this custom function is presumed to be either a Series,
        or a NumPy array (in which case it will be automatically converted into
        a Series).

        Arguments:
            function: Function to apply to Series.
            return_dtype: Dtype of the output Series.
                If not set, the dtype will be inferred based on the first non-null value
                that is returned by the function.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.col("a", "b")
            ...     .map_batches(lambda s: s.to_numpy() + 1, return_dtype=nw.Float64)
            ...     .name.suffix("_mapped")
            ... )
            âââââââââââââââââââââââââââââ
            |    Narwhals DataFrame     |
            |---------------------------|
            |   a  b  a_mapped  b_mapped|
            |0  1  4       2.0       5.0|
            |1  2  5       3.0       6.0|
            |2  3  6       4.0       7.0|
            âââââââââââââââââââââââââââââ
        c                   ó     | ¡j dS )N)rr   rÌ   )rH   Úmap_batchesrf   ©rr   rÌ   rD   rE   rF   rg   ©  ó   
 ÿz"Expr.map_batches.<locals>.<lambda>)rM   rA   rZ   r	   r\   )rD   rr   rÌ   rE   rÐ   rF   rÏ     s   'ûzExpr.map_batchesc                   rc   )uŸ  Calculate the sample skewness of a column.

        Returns:
            An expression representing the sample skewness of the column.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 4, 5], "b": [1, 1, 2, 10, 100]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").skew())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |      a         b |
            | 0  0.0  1.472427 |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úskewrf   r`   rE   rF   rg   Ã  r­   zExpr.skew.<locals>.<lambda>ri   r`   rE   r`   rF   rÒ   °  r¯   z	Expr.skewc                   rc   )u  Return the sum value.

        Returns:
            A new expression.

        Examples:
            >>> import duckdb
            >>> import narwhals as nw
            >>> df_native = duckdb.sql("SELECT * FROM VALUES (5, 50), (10, 100) df(a, b)")
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").sum())
            âââââââââââââââââââââ
            |Narwhals LazyFrame |
            |-------------------|
            |ââââââââââ¬âââââââââ|
            |â   a    â   b    â|
            |â int128 â int128 â|
            |ââââââââââŒâââââââââ€|
            |â     15 â    150 â|
            |ââââââââââŽâââââââââ|
            âââââââââââââââââââââ
        c                   r«   r?   )rH   re   rf   r`   rE   rF   rg   Ü  r­   zExpr.sum.<locals>.<lambda>ri   r`   rE   r`   rF   re   Å  s   zExpr.sumc                   rc   )uz  Returns the minimum value(s) from a column(s).

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2], "b": [4, 3]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.min("a", "b"))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a  b      |
            |     0  1  3      |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úminrf   r`   rE   rF   rg   ñ  r­   zExpr.min.<locals>.<lambda>ri   r`   rE   r`   rF   rÓ   Þ  r¯   zExpr.minc                   rc   )u  Returns the maximum value(s) from a column(s).

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [10, 20], "b": [50, 100]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.max("a", "b"))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a    b    |
            |    0  20  100    |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úmaxrf   r`   rE   rF   rg     r­   zExpr.max.<locals>.<lambda>ri   r`   rE   r`   rF   rÔ   ó  r¯   zExpr.maxc                   rc   )uÍ  Returns the index of the minimum value.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [10, 20], "b": [150, 100]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").arg_min().name.suffix("_arg_min"))
            âââââââââââââââââââââââââ
            |  Narwhals DataFrame   |
            |-----------------------|
            |   a_arg_min  b_arg_min|
            |0          0          1|
            âââââââââââââââââââââââââ
        c                   r«   r?   )rH   Úarg_minrf   r`   rE   rF   rg     r­   zExpr.arg_min.<locals>.<lambda>©r[   r`   rE   r`   rF   rÕ     ó   
ÿzExpr.arg_minc                   rc   )uÍ  Returns the index of the maximum value.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [10, 20], "b": [150, 100]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").arg_max().name.suffix("_arg_max"))
            âââââââââââââââââââââââââ
            |  Narwhals DataFrame   |
            |-----------------------|
            |   a_arg_max  b_arg_max|
            |0          1          0|
            âââââââââââââââââââââââââ
        c                   r«   r?   )rH   Úarg_maxrf   r`   rE   rF   rg   3  r­   zExpr.arg_max.<locals>.<lambda>rÖ   r`   rE   r`   rF   rØ     r×   zExpr.arg_maxc                   rc   )u  Returns the number of non-null elements in the column.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3], "b": [None, 4, 4]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.all().count())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a  b      |
            |     0  3  2      |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úcountrf   r`   rE   rF   rg   I  r­   zExpr.count.<locals>.<lambda>ri   r`   rE   r`   rF   rÙ   6  r¯   z
Expr.countc                   rc   )u  Returns count of unique values.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 4, 5], "b": [1, 1, 3, 3, 5]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").n_unique())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a  b      |
            |     0  5  3      |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Ún_uniquerf   r`   rE   rF   rg   ^  r­   zExpr.n_unique.<locals>.<lambda>ri   r`   rE   r`   rF   rÚ   K  r¯   zExpr.n_uniquec                   rc   )u  Return unique values of this expression.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").unique().sum())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a   b     |
            |     0  9  12     |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úuniquerf   r`   rE   rF   rg   s  r­   zExpr.unique.<locals>.<lambda>©r]   r`   rE   r`   rF   rÛ   `  r¯   zExpr.uniquec                   rc   )uÖ  Return absolute value of each element.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, -2], "b": [-3, 4]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(nw.col("a", "b").abs().name.suffix("_abs"))
            âââââââââââââââââââââââ
            | Narwhals DataFrame  |
            |---------------------|
            |   a  b  a_abs  b_abs|
            |0  1 -3      1      3|
            |1 -2  4      2      4|
            âââââââââââââââââââââââ
        c                   r«   r?   )rH   rd   rf   r`   rE   rF   rg     r­   zExpr.abs.<locals>.<lambda>rq   r`   rE   r`   rF   rd   u  s   zExpr.abs©ÚreverserÞ   c                  ó       fddj tj¡¡S )u
  Return cumulative sum.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            reverse: reverse the operation

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_cum_sum=nw.col("a").cum_sum())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |   a  b  a_cum_sum|
            |0  1  2          1|
            |1  1  4          2|
            |2  3  4          5|
            |3  5  6         10|
            |4  5  6         15|
            ââââââââââââââââââââ
        c                   rÄ   ©NrÝ   )rH   Úcum_sumrf   ©rÞ   rD   rE   rF   rg   ª  rh   zExpr.cum_sum.<locals>.<lambda>©rM   rA   rZ   r	   ÚWINDOW©rD   rÞ   rE   râ   rF   rá     s   þzExpr.cum_sumc                   ó       fdd j tj¡¡S )uÛ  Returns the difference between each element and the previous one.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Returns:
            A new expression.

        Notes:
            pandas may change the dtype here, for example when introducing missing
            values in an integer column. To ensure, that the dtype doesn't change,
            you may want to use `fill_null` and `cast`. For example, to calculate
            the diff and fill missing values with `0` in a Int64 column, you could
            do:

                nw.col("a").diff().fill_null(0).cast(nw.Int64)

        Examples:
            >>> import polars as pl
            >>> import narwhals as nw
            >>> df_native = pl.DataFrame({"a": [1, 1, 3, 5, 5]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_diff=nw.col("a").diff())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            | shape: (5, 2)    |
            | âââââââ¬âââââââââ |
            | â a   â a_diff â |
            | â --- â ---    â |
            | â i64 â i64    â |
            | âââââââªâââââââââ¡ |
            | â 1   â null   â |
            | â 1   â 0      â |
            | â 3   â 2      â |
            | â 5   â 2      â |
            | â 5   â 0      â |
            | âââââââŽâââââââââ |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Údiffrf   r`   rE   rF   rg   Ù  r­   zExpr.diff.<locals>.<lambda>rã   r`   rE   r`   rF   rç   ®  s   *
þz	Expr.diffÚnc                   rß   )u  Shift values by `n` positions.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            n: Number of positions to shift values by.

        Returns:
            A new expression.

        Notes:
            pandas may change the dtype here, for example when introducing missing
            values in an integer column. To ensure, that the dtype doesn't change,
            you may want to use `fill_null` and `cast`. For example, to shift
            and fill missing values with `0` in a Int64 column, you could
            do:

                nw.col("a").shift(1).fill_null(0).cast(nw.Int64)

        Examples:
            >>> import polars as pl
            >>> import narwhals as nw
            >>> df_native = pl.DataFrame({"a": [1, 1, 3, 5, 5]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_shift=nw.col("a").shift(n=1))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |shape: (5, 2)     |
            |âââââââ¬ââââââââââ |
            |â a   â a_shift â |
            |â --- â ---     â |
            |â i64 â i64     â |
            |âââââââªââââââââââ¡ |
            |â 1   â null    â |
            |â 1   â 1       â |
            |â 3   â 1       â |
            |â 5   â 3       â |
            |â 5   â 5       â |
            |âââââââŽââââââââââ |
            ââââââââââââââââââââ
        c                   rm   r?   )rH   Úshiftrf   ©rè   rD   rE   rF   rg     rp   zExpr.shift.<locals>.<lambda>rã   )rD   rè   rE   rê   rF   ré   Ý  s   -þz
Expr.shift©rÌ   Úoldú!Sequence[Any] | Mapping[Any, Any]ÚnewúSequence[Any] | NoneúDType | type[DType] | Nonec                  sN    du rt tsd}t|t ¡  t ¡   fdd¡S )u  Replace all values by different values.

        This function must replace all non-null input values (else it raises an error).

        Arguments:
            old: Sequence of values to replace. It also accepts a mapping of values to
                their replacement as syntactic sugar for
                `replace_all(old=list(mapping.keys()), new=list(mapping.values()))`.
            new: Sequence of values to replace by. Length must match the length of `old`.
            return_dtype: The data type of the resulting expression. If set to `None`
                (default), the data type is determined automatically based on the other
                inputs.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [3, 0, 1, 2]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     b=nw.col("a").replace_strict(
            ...         [0, 1, 2, 3],
            ...         ["zero", "one", "two", "three"],
            ...         return_dtype=nw.String,
            ...     )
            ... )
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |      a      b    |
            |   0  3  three    |
            |   1  0   zero    |
            |   2  1    one    |
            |   3  2    two    |
            ââââââââââââââââââââ
        NzB`new` argument is required if `old` argument is not a Mapping typec                   s     | ¡j dS )Nrë   )rH   Úreplace_strictrf   ©rî   rì   rÌ   rD   rE   rF   rg   E  s   
 ÿz%Expr.replace_strict.<locals>.<lambda>)Ú
isinstancer   Ú	TypeErrorÚlistÚvaluesÚkeysrP   )rD   rì   rî   rÌ   rW   rE   rò   rF   rñ     s   -
ÿzExpr.replace_strict©Ú
descendingÚ
nulls_lastrù   rú   c                  s.   d}t |dd   fddj ¡ ¡S )aQ  Sort this column. Place null values first.

        !!! warning
            `Expr.sort` is deprecated and will be removed in a future version.
            Hint: instead of `df.select(nw.col('a').sort())`, use
            `df.select(nw.col('a')).sort()` instead.
            Note: this will remain available in `narwhals.stable.v1`.
            See [stable api](../backcompat.md/) for more information.

        Arguments:
            descending: Sort in descending order.
            nulls_last: Place null values last instead of first.

        Returns:
            A new expression.
        a$  `Expr.sort` is deprecated and will be removed in a future version.

Hint: instead of `df.select(nw.col('a').sort())`, use `df.select(nw.col('a')).sort()`.

Note: this will remain available in `narwhals.stable.v1`.
See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.
ú1.23.0©Ú_versionc                   rÎ   )Nrø   )rH   Úsortrf   ©rù   rú   rD   rE   rF   rg   c  rÑ   zExpr.sort.<locals>.<lambda>)r#   rM   rA   Úwith_uncloseable_window)rD   rù   rú   rW   rE   rÿ   rF   rþ   J  s   ÿüz	Expr.sortÚbothÚlower_boundúAny | IntoExprÚupper_boundÚclosedr,   c                   s8   d fdd  fdd	td
d
d
d¡S )uK  Check if this expression is between the given lower and upper bounds.

        Arguments:
            lower_bound: Lower bound value. String literals are interpreted as column names.
            upper_bound: Upper bound value. String literals are interpreted as column names.
            closed: Define which sides of the interval are closed (inclusive).

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 4, 5]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(b=nw.col("a").is_between(2, 4, "right"))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |      a      b    |
            |   0  1  False    |
            |   1  2  False    |
            |   2  3   True    |
            |   3  4   True    |
            |   4  5  False    |
            ââââââââââââââââââââ
        Úcompliant_exprr>   ÚlbÚubr:   c                   sX    dkr| |k| |k @ S  dkr| |k| |k@ S  dkr$| |k| |k @ S | |k| |k@ S )NÚleftÚrightÚnonerE   )r  r  r  )r  rE   rF   rG     s   zExpr.is_between.<locals>.funcc                   s   t |  ddS )NFr   r   rf   )rG   r  rD   r  rE   rF   rg     s    ÿz!Expr.is_between.<locals>.<lambda>F©r   Úallow_multi_outputÚto_single_outputN)r  r>   r  r>   r  r>   r:   r>   ©rM   r   )rD   r  r  r  rE   )r  rG   r  rD   r  rF   Ú
is_betweenj  s   "úüzExpr.is_betweenc                   s8   t  trt  ttfs  fdd¡S d}t|)u1  Check if elements of this expression are present in the other iterable.

        Arguments:
            other: iterable

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 9, 10]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(b=nw.col("a").is_in([1, 2]))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |       a      b   |
            |   0   1   True   |
            |   1   2   True   |
            |   2   9  False   |
            |   3  10  False   |
            ââââââââââââââââââââ
        c                   s     | ¡ t dd¡S )NT)Úpass_through)rH   Úis_inr    rf   r   rE   rF   rg   Â  s   
 
ÿzExpr.is_in.<locals>.<lambda>zyNarwhals `is_in` doesn't accept expressions as an argument, as opposed to Polars. You should provide an iterable instead.)ró   r   r^   ÚbytesrP   ÚNotImplementedError)rD   r}   rW   rE   r   rF   r  §  s   ÿz
Expr.is_inÚ
predicatesc                   s@   t | tg ¢R dddd tj¡}  fdd|¡S )uè  Filters elements based on a condition, returning a new expression.

        Arguments:
            predicates: Conditions to filter by (which get ANDed together).

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame(
            ...     {"a": [2, 3, 4, 5, 6, 7], "b": [10, 11, 12, 13, 14, 15]}
            ... )
            >>> df = nw.from_native(df_native)
            >>> df.select(
            ...     nw.col("a").filter(nw.col("a") > 4),
            ...     nw.col("b").filter(nw.col("b") < 13),
            ... )
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a   b     |
            |     3  5  10     |
            |     4  6  11     |
            |     5  7  12     |
            ââââââââââââââââââââ
        FTr  c                   s   t | dd g ¢R ddiS )Nc                  W  s   | d j | dd   S )Nr   r±   )Úfilter©ÚexprsrE   rE   rF   rg   ò  s    z/Expr.filter.<locals>.<lambda>.<locals>.<lambda>r   Fr   rf   ©Úflat_predicatesrD   rE   rF   rg   ð  s    ýüûzExpr.filter.<locals>.<lambda>)r"   r   rT   r	   r\   rM   )rD   r  r9   rE   r  rF   r  Ê  s    ÿþûúøzExpr.filterc                   rc   )u  Returns a boolean Series indicating which values are null.

        Returns:
            A new expression.

        Notes:
            pandas handles null values differently from Polars and PyArrow.
            See [null_handling](../pandas_like_concepts/null_handling.md/)
            for reference.

        Examples:
            >>> import duckdb
            >>> import narwhals as nw
            >>> df_native = duckdb.sql(
            ...     "SELECT * FROM VALUES (null, CAST('NaN' AS DOUBLE)), (2, 2.) df(a, b)"
            ... )
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     a_is_null=nw.col("a").is_null(), b_is_null=nw.col("b").is_null()
            ... )
            ââââââââââââââââââââââââââââââââââââââââââââ
            |            Narwhals LazyFrame            |
            |------------------------------------------|
            |âââââââââ¬âââââââââ¬ââââââââââââ¬ââââââââââââ|
            |â   a   â   b    â a_is_null â b_is_null â|
            |â int32 â double â  boolean  â  boolean  â|
            |âââââââââŒâââââââââŒââââââââââââŒââââââââââââ€|
            |â  NULL â    nan â true      â false     â|
            |â     2 â    2.0 â false     â false     â|
            |âââââââââŽâââââââââŽââââââââââââŽââââââââââââ|
            ââââââââââââââââââââââââââââââââââââââââââââ
        c                   r«   r?   )rH   Úis_nullrf   r`   rE   rF   rg     r­   zExpr.is_null.<locals>.<lambda>rq   r`   rE   r`   rF   r  ú  ó   !zExpr.is_nullc                   rc   )uÕ  Indicate which values are NaN.

        Returns:
            A new expression.

        Notes:
            pandas handles null values differently from Polars and PyArrow.
            See [null_handling](../pandas_like_concepts/null_handling.md/)
            for reference.

        Examples:
            >>> import duckdb
            >>> import narwhals as nw
            >>> df_native = duckdb.sql(
            ...     "SELECT * FROM VALUES (null, CAST('NaN' AS DOUBLE)), (2, 2.) df(a, b)"
            ... )
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     a_is_nan=nw.col("a").is_nan(), b_is_nan=nw.col("b").is_nan()
            ... )
            ââââââââââââââââââââââââââââââââââââââââââ
            |           Narwhals LazyFrame           |
            |----------------------------------------|
            |âââââââââ¬âââââââââ¬âââââââââââ¬âââââââââââ|
            |â   a   â   b    â a_is_nan â b_is_nan â|
            |â int32 â double â boolean  â boolean  â|
            |âââââââââŒâââââââââŒâââââââââââŒâââââââââââ€|
            |â  NULL â    nan â NULL     â true     â|
            |â     2 â    2.0 â false    â false    â|
            |âââââââââŽâââââââââŽâââââââââââŽâââââââââââ|
            ââââââââââââââââââââââââââââââââââââââââââ
        c                   r«   r?   )rH   Úis_nanrf   r`   rE   rF   rg   >  r­   zExpr.is_nan.<locals>.<lambda>rq   r`   rE   r`   rF   r    r  zExpr.is_nanc                   s"   d}t |dd    fdd¡S )zhFind elements where boolean expression is True.

        Returns:
            A new expression.
        zÐ`Expr.arg_true` is deprecated and will be removed in a future version.

Note: this will remain available in `narwhals.stable.v1`.
See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.
rû   rü   c                   r«   r?   )rH   Úarg_truerf   r`   rE   rF   rg   L  r­   zExpr.arg_true.<locals>.<lambda>©r#   r]   )rD   rW   rE   r`   rF   r  @  s   ÿzExpr.arg_trueÚvalueúExpr | NonNestedLiteralÚstrategyúFillNullStrategy | NoneÚlimitú
int | Nonec                   sr   durdurd}t |du rdu rd}t |dur-dvr-d }t |  fdd¡S )u&  Fill null values with given value.

        Arguments:
            value: Value or expression used to fill null values.
            strategy: Strategy used to fill null values.
            limit: Number of consecutive null values to fill when using the 'forward' or 'backward' strategy.

        Returns:
            A new expression.

        Notes:
            pandas handles null values differently from Polars and PyArrow.
            See [null_handling](../pandas_like_concepts/null_handling.md/)
            for reference.

        Examples:
            >>> import polars as pl
            >>> import narwhals as nw
            >>> df_native = pl.DataFrame(
            ...     {
            ...         "a": [2, None, None, 3],
            ...         "b": [2.0, float("nan"), float("nan"), 3.0],
            ...         "c": [1, 2, 3, 4],
            ...     }
            ... )
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.col("a", "b").fill_null(0).name.suffix("_filled"),
            ...     nw.col("a").fill_null(nw.col("c")).name.suffix("_filled_with_c"),
            ... )
            ââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
            |                     Narwhals DataFrame                     |
            |------------------------------------------------------------|
            |shape: (4, 6)                                               |
            |ââââââââ¬ââââââ¬ââââââ¬âââââââââââ¬âââââââââââ¬ââââââââââââââââââ|
            |â a    â b   â c   â a_filled â b_filled â a_filled_with_c â|
            |â ---  â --- â --- â ---      â ---      â ---             â|
            |â i64  â f64 â i64 â i64      â f64      â i64             â|
            |ââââââââªââââââªââââââªâââââââââââªâââââââââââªââââââââââââââââââ¡|
            |â 2    â 2.0 â 1   â 2        â 2.0      â 2               â|
            |â null â NaN â 2   â 0        â NaN      â 2               â|
            |â null â NaN â 3   â 0        â NaN      â 3               â|
            |â 3    â 3.0 â 4   â 3        â 3.0      â 3               â|
            |ââââââââŽââââââŽââââââŽâââââââââââŽâââââââââââŽââââââââââââââââââ|
            ââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

            Using a strategy:

            >>> df.select(
            ...     nw.col("a", "b"),
            ...     nw.col("a", "b")
            ...     .fill_null(strategy="forward", limit=1)
            ...     .name.suffix("_nulls_forward_filled"),
            ... )
            ââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
            |                       Narwhals DataFrame                       |
            |----------------------------------------------------------------|
            |shape: (4, 4)                                                   |
            |ââââââââ¬ââââââ¬âââââââââââââââââââââââââ¬âââââââââââââââââââââââââ|
            |â a    â b   â a_nulls_forward_filled â b_nulls_forward_filled â|
            |â ---  â --- â ---                    â ---                    â|
            |â i64  â f64 â i64                    â f64                    â|
            |ââââââââªââââââªâââââââââââââââââââââââââªâââââââââââââââââââââââââ¡|
            |â 2    â 2.0 â 2                      â 2.0                    â|
            |â null â NaN â 2                      â NaN                    â|
            |â null â NaN â null                   â NaN                    â|
            |â 3    â 3.0 â 3                      â 3.0                    â|
            |ââââââââŽââââââŽâââââââââââââââââââââââââŽâââââââââââââââââââââââââ|
            ââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
        Nz*cannot specify both `value` and `strategy`z0must specify either a fill `value` or `strategy`>   ÚforwardÚbackwardzstrategy not supported: c                   s      | ¡jt| dd dS )NTr   )r   r"  r$  )rH   Ú	fill_nullr   rf   ©r$  rD   r"  r   rE   rF   rg   €  s
   
 ýz Expr.fill_null.<locals>.<lambda>©Ú
ValueErrorrP   )rD   r   r"  r$  rW   rE   r)  rF   r(  N  s   L
ÿzExpr.fill_nullc                   rc   )uÐ  Drop null values.

        Returns:
            A new expression.

        Notes:
            pandas handles null values differently from Polars and PyArrow.
            See [null_handling](../pandas_like_concepts/null_handling.md/)
            for reference.

        Examples:
            >>> import polars as pl
            >>> import narwhals as nw
            >>> df_native = pl.DataFrame({"a": [2.0, 4.0, float("nan"), 3.0, None, 5.0]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a").drop_nulls())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |  shape: (5, 1)   |
            |  âââââââ         |
            |  â a   â         |
            |  â --- â         |
            |  â f64 â         |
            |  âââââââ¡         |
            |  â 2.0 â         |
            |  â 4.0 â         |
            |  â NaN â         |
            |  â 3.0 â         |
            |  â 5.0 â         |
            |  âââââââ         |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Ú
drop_nullsrf   r`   rE   rF   rg   Ï  r­   z!Expr.drop_nulls.<locals>.<lambda>rÜ   r`   rE   r`   rF   r,  ¬  s   "
ÿzExpr.drop_nulls©ÚfractionÚwith_replacementÚseedr.  r/  r0  c                  s*   d}t |dd   fdd¡S )aR  Sample randomly from this expression.

        !!! warning
            `Expr.sample` is deprecated and will be removed in a future version.
            Hint: instead of `df.select(nw.col('a').sample())`, use
            `df.select(nw.col('a')).sample()` instead.
            Note: this will remain available in `narwhals.stable.v1`.
            See [stable api](../backcompat.md/) for more information.

        Arguments:
            n: Number of items to return. Cannot be used with fraction.
            fraction: Fraction of items to return. Cannot be used with n.
            with_replacement: Allow values to be sampled more than once.
            seed: Seed for the random number generator. If set to None (default), a random
                seed is generated for each sample operation.

        Returns:
            A new expression.
        a*  `Expr.sample` is deprecated and will be removed in a future version.

Hint: instead of `df.select(nw.col('a').sample())`, use `df.select(nw.col('a')).sample()`.

Note: this will remain available in `narwhals.stable.v1`.
See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.
rû   rü   c                   s     | ¡j dS )Nr-  )rH   Úsamplerf   ©r.  rè   r0  rD   r/  rE   rF   rg   õ  ó   
 ÿzExpr.sample.<locals>.<lambda>r  )rD   rè   r.  r/  r0  rW   rE   r2  rF   r1  Ò  s   ÿÿzExpr.sample)Úorder_byÚpartition_byústr | Sequence[str]r4  ústr | Sequence[str] | Nonec          	        sê   j j ¡ rd}t|t|t|tr|gn| s$ s$d}t|tj	}j j
}| ¡ r5d}t| durFj j ¡ rF| ¡ sEJ n durT| ¡ sTd}t|j }| ¡ r^tjntj}t|||jd}  fdd|¡S )	uÉ  Compute expressions over the given groups (optionally with given order).

        Arguments:
            partition_by: Names of columns to compute window expression over.
                Must be names of columns, as opposed to expressions -
                so, this is a bit less flexible than Polars' `Expr.over`.
            order_by: Column(s) to order window functions by.
                For lazy backends, this argument is required when `over` is applied
                to order-dependent functions, see [order-dependence](../basics/order_dependence.md).

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 4], "b": ["x", "x", "y"]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_min_per_group=nw.col("a").min().over("b"))
            ââââââââââââââââââââââââââ
            |   Narwhals DataFrame   |
            |------------------------|
            |   a  b  a_min_per_group|
            |0  1  x                1|
            |1  2  x                1|
            |2  4  y                4|
            ââââââââââââââââââââââââââ

            Cumulative operations are also supported, but (currently) only for
            pandas and Polars:

            >>> df.with_columns(a_cum_sum_per_group=nw.col("a").cum_sum().over("b"))
            ââââââââââââââââââââââââââââââ
            |     Narwhals DataFrame     |
            |----------------------------|
            |   a  b  a_cum_sum_per_group|
            |0  1  x                    1|
            |1  2  x                    3|
            |2  4  y                    4|
            ââââââââââââââââââââââââââââââ
        z>`.over()` can not be used for expressions which change length.z?At least one of `partition_by` or `order_by` must be specified.z)Nested `over` statements are not allowed.NzJCannot use `order_by` in `over` on expression which isn't order-dependent.)Úwindow_kindÚexpansion_kindc                   ó     | ¡  ¡S r?   )rH   Úoverrf   ©Úflat_order_byÚflat_partition_byrD   rE   rF   rg   J  s   
 ÿzExpr.over.<locals>.<lambda>)rA   rK   Úis_filtrationr   r"   ró   r^   r+  r	   rO   r8  Ú	is_closedr   rL   Úis_openÚis_uncloseabler   ÚUNCLOSEABLEÚCLOSEDr
   r9  rM   )	rD   r4  r5  rW   rK   r8  Úcurrent_metaÚnext_window_kindÚ	next_metarE   r<  rF   r;  ú  s<   .ÿýüz	Expr.overc                 C  s
   |   ¡  S )uM  Return a boolean mask indicating duplicated values.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(nw.all().is_duplicated().name.suffix("_is_duplicated"))
            âââââââââââââââââââââââââââââââââââââââââââ
            |           Narwhals DataFrame            |
            |-----------------------------------------|
            |   a  b  a_is_duplicated  b_is_duplicated|
            |0  1  a             True             True|
            |1  2  a            False             True|
            |2  3  b            False            False|
            |3  1  c             True            False|
            âââââââââââââââââââââââââââââââââââââââââââ
        )Ú	is_uniquer`   rE   rE   rF   Úis_duplicatedP  s   
zExpr.is_duplicatedc                   rc   )uÙ  Return a boolean mask indicating unique values.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(nw.all().is_unique().name.suffix("_is_unique"))
            âââââââââââââââââââââââââââââââââââ
            |       Narwhals DataFrame        |
            |---------------------------------|
            |   a  b  a_is_unique  b_is_unique|
            |0  1  a        False        False|
            |1  2  a         True        False|
            |2  3  b         True         True|
            |3  1  c        False         True|
            âââââââââââââââââââââââââââââââââââ
        c                   r«   r?   )rH   rH  rf   r`   rE   rF   rg   ~  r­   z Expr.is_unique.<locals>.<lambda>rq   r`   rE   r`   rF   rH  h  rÁ   zExpr.is_uniquec                   rc   )ud  Count null values.

        Returns:
            A new expression.

        Notes:
            pandas handles null values differently from Polars and PyArrow.
            See [null_handling](../pandas_like_concepts/null_handling.md/)
            for reference.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame(
            ...     {"a": [1, 2, None, 1], "b": ["a", None, "b", None]}
            ... )
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.all().null_count())
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a  b      |
            |     0  1  2      |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Ú
null_countrf   r`   rE   rF   rg     r­   z!Expr.null_count.<locals>.<lambda>ri   r`   rE   r`   rF   rJ    s   
ÿzExpr.null_countc                   ræ   )u»  Return a boolean mask indicating the first occurrence of each distinct value.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.all().is_first_distinct().name.suffix("_is_first_distinct")
            ... )
            âââââââââââââââââââââââââââââââââââââââââââââââââââ
            |               Narwhals DataFrame                |
            |-------------------------------------------------|
            |   a  b  a_is_first_distinct  b_is_first_distinct|
            |0  1  a                 True                 True|
            |1  2  a                 True                False|
            |2  3  b                 True                 True|
            |3  1  c                False                 True|
            âââââââââââââââââââââââââââââââââââââââââââââââââââ
        c                   r«   r?   )rH   Úis_first_distinctrf   r`   rE   rF   rg   »  r­   z(Expr.is_first_distinct.<locals>.<lambda>rã   r`   rE   r`   rF   rK    ó   
þzExpr.is_first_distinctc                   ræ   )u  Return a boolean mask indicating the last occurrence of each distinct value.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.all().is_last_distinct().name.suffix("_is_last_distinct")
            ... )
            âââââââââââââââââââââââââââââââââââââââââââââââââ
            |              Narwhals DataFrame               |
            |-----------------------------------------------|
            |   a  b  a_is_last_distinct  b_is_last_distinct|
            |0  1  a               False               False|
            |1  2  a                True                True|
            |2  3  b                True                True|
            |3  1  c                True                True|
            âââââââââââââââââââââââââââââââââââââââââââââââââ
        c                   r«   r?   )rH   Úis_last_distinctrf   r`   rE   rF   rg   Ü  r­   z'Expr.is_last_distinct.<locals>.<lambda>rã   r`   rE   r`   rF   rM  ¿  rL  zExpr.is_last_distinctÚquantileÚfloatÚinterpolationr2   c                   s      fdd¡S )u  Get quantile value.

        Arguments:
            quantile: Quantile between 0.0 and 1.0.
            interpolation: Interpolation method.

        Returns:
            A new expression.

        Note:
            - pandas and Polars may have implementation differences for a given interpolation method.
            - [dask](https://docs.dask.org/en/stable/generated/dask.dataframe.Series.quantile.html) has
                its own method to approximate quantile and it doesn't implement 'nearest', 'higher',
                'lower', 'midpoint' as interpolation method - use 'linear' which is closest to the
                native 'dask' - method.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame(
            ...     {"a": list(range(50)), "b": list(range(50, 100))}
            ... )
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a", "b").quantile(0.5, interpolation="linear"))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |        a     b   |
            |  0  24.5  74.5   |
            ââââââââââââââââââââ
        c                   r:  r?   )rH   rN  rf   ©rP  rN  rD   rE   rF   rg     rh   zExpr.quantile.<locals>.<lambda>ri   )rD   rN  rP  rE   rQ  rF   rN  à  s   "ÿzExpr.quantileé
   c                   ó$   d}t |dd   fdd¡S )aô  Get the first `n` rows.

        !!! warning
            `Expr.head` is deprecated and will be removed in a future version.
            Hint: instead of `df.select(nw.col('a').head())`, use
            `df.select(nw.col('a')).head()` instead.
            Note: this will remain available in `narwhals.stable.v1`.
            See [stable api](../backcompat.md/) for more information.

        Arguments:
            n: Number of rows to return.

        Returns:
            A new expression.
        a$  `Expr.head` is deprecated and will be removed in a future version.

Hint: instead of `df.select(nw.col('a').head())`, use `df.select(nw.col('a')).head()`.

Note: this will remain available in `narwhals.stable.v1`.
See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.
rû   rü   c                   rm   r?   )rH   Úheadrf   rê   rE   rF   rg     rp   zExpr.head.<locals>.<lambda>r  ©rD   rè   rW   rE   rê   rF   rT    ó   ÿz	Expr.headc                   rS  )aó  Get the last `n` rows.

        !!! warning
            `Expr.tail` is deprecated and will be removed in a future version.
            Hint: instead of `df.select(nw.col('a').tail())`, use
            `df.select(nw.col('a')).tail()` instead.
            Note: this will remain available in `narwhals.stable.v1`.
            See [stable api](../backcompat.md/) for more information.

        Arguments:
            n: Number of rows to return.

        Returns:
            A new expression.
        a$  `Expr.tail` is deprecated and will be removed in a future version.

Hint: instead of `df.select(nw.col('a').tail())`, use `df.select(nw.col('a')).tail()`.

Note: this will remain available in `narwhals.stable.v1`.
See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.
rû   rü   c                   rm   r?   )rH   Útailrf   rê   rE   rF   rg   6  rp   zExpr.tail.<locals>.<lambda>r  rU  rE   rê   rF   rW    rV  z	Expr.tailr   Údecimalsc                   rl   )uð  Round underlying floating point data by `decimals` digits.

        Arguments:
            decimals: Number of decimals to round by.

        Returns:
            A new expression.


        Notes:
            For values exactly halfway between rounded decimal values pandas behaves differently than Polars and Arrow.

            pandas rounds to the nearest even value (e.g. -0.5 and 0.5 round to 0.0, 1.5 and 2.5 round to 2.0, 3.5 and
            4.5 to 4.0, etc..).

            Polars and Arrow round away from 0 (e.g. -0.5 to -1.0, 0.5 to 1.0, 1.5 to 2.0, 2.5 to 3.0, etc..).

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1.12345, 2.56789, 3.901234]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_rounded=nw.col("a").round(1))
            ââââââââââââââââââââââââ
            |  Narwhals DataFrame  |
            |----------------------|
            |          a  a_rounded|
            |0  1.123450        1.1|
            |1  2.567890        2.6|
            |2  3.901234        3.9|
            ââââââââââââââââââââââââ
        c                   rm   r?   )rH   Úroundrf   ©rX  rD   rE   rF   rg   Z  rp   zExpr.round.<locals>.<lambda>rq   )rD   rX  rE   rZ  rF   rY  8  s   !ÿz
Expr.roundc                   rc   )uK  Return the number of elements in the column.

        Null values count towards the total.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": ["x", "y", "z"], "b": [1, 2, 1]})
            >>> df = nw.from_native(df_native)
            >>> df.select(
            ...     nw.col("a").filter(nw.col("b") == 1).len().alias("a1"),
            ...     nw.col("a").filter(nw.col("b") == 2).len().alias("a2"),
            ... )
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |       a1  a2     |
            |    0   2   1     |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úlenrf   r`   rE   rF   rg   u  r­   zExpr.len.<locals>.<lambda>ri   r`   rE   r`   rF   r[  ]  s   zExpr.lenÚoffsetc                   s&   d}t |dd   fdd¡S )aT  Take every nth value in the Series and return as new Series.

        !!! warning
            `Expr.gather_every` is deprecated and will be removed in a future version.
            Hint: instead of `df.select(nw.col('a').gather_every())`, use
            `df.select(nw.col('a')).gather_every()` instead.
            Note: this will remain available in `narwhals.stable.v1`.
            See [stable api](../backcompat.md/) for more information.

        Arguments:
            n: Gather every *n*-th row.
            offset: Starting index.

        Returns:
            A new expression.
        a<  `Expr.gather_every` is deprecated and will be removed in a future version.

Hint: instead of `df.select(nw.col('a').gather_every())`, use `df.select(nw.col('a')).gather_every()`.

Note: this will remain available in `narwhals.stable.v1`.
See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.
rû   rü   c                   rÎ   )N)rè   r\  )rH   Úgather_everyrf   ©rè   r\  rD   rE   rF   rg     s    z#Expr.gather_every.<locals>.<lambda>r  )rD   rè   r\  rW   rE   r^  rF   r]  w  s   ÿÿzExpr.gather_everyú2IntoExpr | NumericLiteral | TemporalLiteral | Nonec                   s(      fddt dddd¡S )u{  Clip values in the Series.

        Arguments:
            lower_bound: Lower bound value. String literals are treated as column names.
            upper_bound: Upper bound value. String literals are treated as column names.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 2, 3]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_clipped=nw.col("a").clip(-1, 3))
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |    a  a_clipped  |
            | 0  1          1  |
            | 1  2          2  |
            | 2  3          3  |
            ââââââââââââââââââââ
        c                   s   t |  fdd ddS )Nc                    s2   | d    d ur| d nd d ur| d ¡S d ¡S )Nr   r±   é   )Úclipr  )r  r  rE   rF   rg   ³  s    þþz-Expr.clip.<locals>.<lambda>.<locals>.<lambda>Fr   r   rf   ©r  rD   r  rE   rF   rg   ±  s    ÷zExpr.clip.<locals>.<lambda>Fr  r  )rD   r  r  rE   rb  rF   ra    s   úôz	Expr.clipc                   rc   )u­  Compute the most occurring value(s).

        Can return multiple values.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 1, 2, 3], "b": [1, 1, 2, 2]})
            >>> df = nw.from_native(df_native)
            >>> df.select(nw.col("a").mode()).sort("a")
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |          a       |
            |       0  1       |
            ââââââââââââââââââââ
        c                   r«   r?   )rH   Úmoderf   r`   rE   rF   rg   Û  r­   zExpr.mode.<locals>.<lambda>rÜ   r`   rE   r`   rF   rc  Æ  s   z	Expr.modec                   rc   )u  Returns boolean values indicating which original values are finite.

        Warning:
            pandas handles null values differently from Polars and PyArrow.
            See [null_handling](../pandas_like_concepts/null_handling.md/)
            for reference.
            `is_finite` will return False for NaN and Null's in the Dask and
            pandas non-nullable backend, while for Polars, PyArrow and pandas
            nullable backends null values are kept as such.

        Returns:
            Expression of `Boolean` data type.

        Examples:
            >>> import polars as pl
            >>> import narwhals as nw
            >>> df_native = pl.DataFrame({"a": [float("nan"), float("inf"), 2.0, None]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(a_is_finite=nw.col("a").is_finite())
            ââââââââââââââââââââââââ
            |  Narwhals DataFrame  |
            |----------------------|
            |shape: (4, 2)         |
            |ââââââââ¬ââââââââââââââ|
            |â a    â a_is_finite â|
            |â ---  â ---         â|
            |â f64  â bool        â|
            |ââââââââªââââââââââââââ¡|
            |â NaN  â false       â|
            |â inf  â false       â|
            |â 2.0  â true        â|
            |â null â null        â|
            |ââââââââŽââââââââââââââ|
            ââââââââââââââââââââââââ
        c                   r«   r?   )rH   Ú	is_finiterf   r`   rE   rF   rg     r­   z Expr.is_finite.<locals>.<lambda>rq   r`   rE   r`   rF   rd  Ý  s   $zExpr.is_finitec                  rß   )u¹  Return the cumulative count of the non-null values in the column.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            reverse: reverse the operation

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": ["x", "k", None, "d"]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.col("a").cum_count().alias("a_cum_count"),
            ...     nw.col("a").cum_count(reverse=True).alias("a_cum_count_reverse"),
            ... )
            âââââââââââââââââââââââââââââââââââââââââââ
            |           Narwhals DataFrame            |
            |-----------------------------------------|
            |      a  a_cum_count  a_cum_count_reverse|
            |0     x            1                    3|
            |1     k            2                    2|
            |2  None            2                    1|
            |3     d            3                    1|
            âââââââââââââââââââââââââââââââââââââââââââ
        c                   rÄ   rà   )rH   Ú	cum_countrf   râ   rE   rF   rg   $  rh   z Expr.cum_count.<locals>.<lambda>rã   rå   rE   râ   rF   re    ó    þzExpr.cum_countc                  rß   )uh  Return the cumulative min of the non-null values in the column.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            reverse: reverse the operation

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [3, 1, None, 2]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.col("a").cum_min().alias("a_cum_min"),
            ...     nw.col("a").cum_min(reverse=True).alias("a_cum_min_reverse"),
            ... )
            ââââââââââââââââââââââââââââââââââââââ
            |         Narwhals DataFrame         |
            |------------------------------------|
            |     a  a_cum_min  a_cum_min_reverse|
            |0  3.0        3.0                1.0|
            |1  1.0        1.0                1.0|
            |2  NaN        NaN                NaN|
            |3  2.0        1.0                2.0|
            ââââââââââââââââââââââââââââââââââââââ
        c                   rÄ   rà   )rH   Úcum_minrf   râ   rE   rF   rg   I  rh   zExpr.cum_min.<locals>.<lambda>rã   rå   rE   râ   rF   rg  (  rf  zExpr.cum_minc                  rß   )uh  Return the cumulative max of the non-null values in the column.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            reverse: reverse the operation

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 3, None, 2]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.col("a").cum_max().alias("a_cum_max"),
            ...     nw.col("a").cum_max(reverse=True).alias("a_cum_max_reverse"),
            ... )
            ââââââââââââââââââââââââââââââââââââââ
            |         Narwhals DataFrame         |
            |------------------------------------|
            |     a  a_cum_max  a_cum_max_reverse|
            |0  1.0        1.0                3.0|
            |1  3.0        3.0                3.0|
            |2  NaN        NaN                NaN|
            |3  2.0        3.0                2.0|
            ââââââââââââââââââââââââââââââââââââââ
        c                   rÄ   rà   )rH   Úcum_maxrf   râ   rE   rF   rg   n  rh   zExpr.cum_max.<locals>.<lambda>rã   rå   rE   râ   rF   rh  M  rf  zExpr.cum_maxc                  rß   )u  Return the cumulative product of the non-null values in the column.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            reverse: reverse the operation

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1, 3, None, 2]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     nw.col("a").cum_prod().alias("a_cum_prod"),
            ...     nw.col("a").cum_prod(reverse=True).alias("a_cum_prod_reverse"),
            ... )
            ââââââââââââââââââââââââââââââââââââââââ
            |          Narwhals DataFrame          |
            |--------------------------------------|
            |     a  a_cum_prod  a_cum_prod_reverse|
            |0  1.0         1.0                 6.0|
            |1  3.0         3.0                 6.0|
            |2  NaN         NaN                 NaN|
            |3  2.0         6.0                 2.0|
            ââââââââââââââââââââââââââââââââââââââââ
        c                   rÄ   rà   )rH   Úcum_prodrf   râ   rE   rF   rg     rh   zExpr.cum_prod.<locals>.<lambda>rã   rå   rE   râ   rF   ri  r  rf  zExpr.cum_prod)rž   ÚcenterÚwindow_sizerj  c                  s4   t |d\  fddj tj¡¡S )u1  Apply a rolling sum (moving sum) over the values.

        A window of length `window_size` will traverse the values. The resulting values
        will be aggregated to their sum.

        The window at a given row will include the row itself and the `window_size - 1`
        elements before it.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            window_size: The length of the window in number of elements. It must be a
                strictly positive integer.
            min_samples: The number of values in the window that should be non-null before
                computing a result. If set to `None` (default), it will be set equal to
                `window_size`. If provided, it must be a strictly positive integer, and
                less than or equal to `window_size`
            center: Set the labels at the center of the window.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1.0, 2.0, None, 4.0]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     a_rolling_sum=nw.col("a").rolling_sum(window_size=3, min_samples=1)
            ... )
            âââââââââââââââââââââââ
            | Narwhals DataFrame  |
            |---------------------|
            |     a  a_rolling_sum|
            |0  1.0            1.0|
            |1  2.0            3.0|
            |2  NaN            3.0|
            |3  4.0            6.0|
            âââââââââââââââââââââââ
        ©rk  rž   c                   ó     | ¡j dS ©N)rk  rž   rj  )rH   Úrolling_sumrf   ©rj  Úmin_samples_intrD   rk  rE   rF   rg   Í  ó
   
 ýz"Expr.rolling_sum.<locals>.<lambda>©r!   rM   rA   rZ   r	   rä   ©rD   rk  rž   rj  rE   rp  rF   ro    ó   1
ÿúzExpr.rolling_sumc                  s4   t d\  fddj tj¡¡S )uC  Apply a rolling mean (moving mean) over the values.

        A window of length `window_size` will traverse the values. The resulting values
        will be aggregated to their mean.

        The window at a given row will include the row itself and the `window_size - 1`
        elements before it.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            window_size: The length of the window in number of elements. It must be a
                strictly positive integer.
            min_samples: The number of values in the window that should be non-null before
                computing a result. If set to `None` (default), it will be set equal to
                `window_size`. If provided, it must be a strictly positive integer, and
                less than or equal to `window_size`
            center: Set the labels at the center of the window.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1.0, 2.0, None, 4.0]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     a_rolling_mean=nw.col("a").rolling_mean(window_size=3, min_samples=1)
            ... )
            ââââââââââââââââââââââââ
            |  Narwhals DataFrame  |
            |----------------------|
            |     a  a_rolling_mean|
            |0  1.0             1.0|
            |1  2.0             1.5|
            |2  NaN             1.5|
            |3  4.0             3.0|
            ââââââââââââââââââââââââ
        rl  c                   rm  rn  )rH   Úrolling_meanrf   ©rj  rž   rD   rk  rE   rF   rg   	  rr  z#Expr.rolling_mean.<locals>.<lambda>rs  rt  rE   rw  rF   rv  Õ  ru  zExpr.rolling_mean)rž   rj  rÃ   c                  ó6   t d\  fddj tj¡¡S )u  Apply a rolling variance (moving variance) over the values.

        A window of length `window_size` will traverse the values. The resulting values
        will be aggregated to their variance.

        The window at a given row will include the row itself and the `window_size - 1`
        elements before it.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            window_size: The length of the window in number of elements. It must be a
                strictly positive integer.
            min_samples: The number of values in the window that should be non-null before
                computing a result. If set to `None` (default), it will be set equal to
                `window_size`. If provided, it must be a strictly positive integer, and
                less than or equal to `window_size`.
            center: Set the labels at the center of the window.
            ddof: Delta Degrees of Freedom; the divisor for a length N window is N - ddof.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1.0, 2.0, None, 4.0]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     a_rolling_var=nw.col("a").rolling_var(window_size=3, min_samples=1)
            ... )
            âââââââââââââââââââââââ
            | Narwhals DataFrame  |
            |---------------------|
            |     a  a_rolling_var|
            |0  1.0            NaN|
            |1  2.0            0.5|
            |2  NaN            0.5|
            |3  4.0            2.0|
            âââââââââââââââââââââââ
        rl  c                   ó     | ¡j dS ©N)rk  rž   rj  rÃ   )rH   Úrolling_varrf   ©rj  rÃ   rž   rD   rk  rE   rF   rg   K	  r3  z"Expr.rolling_var.<locals>.<lambda>rs  ©rD   rk  rž   rj  rÃ   rE   r|  rF   r{  	  s   3
ÿüzExpr.rolling_varc                  rx  )uº  Apply a rolling standard deviation (moving standard deviation) over the values.

        A window of length `window_size` will traverse the values. The resulting values
        will be aggregated to their standard deviation.

        The window at a given row will include the row itself and the `window_size - 1`
        elements before it.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            window_size: The length of the window in number of elements. It must be a
                strictly positive integer.
            min_samples: The number of values in the window that should be non-null before
                computing a result. If set to `None` (default), it will be set equal to
                `window_size`. If provided, it must be a strictly positive integer, and
                less than or equal to `window_size`.
            center: Set the labels at the center of the window.
            ddof: Delta Degrees of Freedom; the divisor for a length N window is N - ddof.

        Returns:
            A new expression.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [1.0, 2.0, None, 4.0]})
            >>> df = nw.from_native(df_native)
            >>> df.with_columns(
            ...     a_rolling_std=nw.col("a").rolling_std(window_size=3, min_samples=1)
            ... )
            âââââââââââââââââââââââ
            | Narwhals DataFrame  |
            |---------------------|
            |     a  a_rolling_std|
            |0  1.0            NaN|
            |1  2.0       0.707107|
            |2  NaN       0.707107|
            |3  4.0       1.414214|
            âââââââââââââââââââââââ
        rl  c                   ry  rz  )rH   Úrolling_stdrf   r|  rE   rF   rg   	  s   
 üz"Expr.rolling_std.<locals>.<lambda>rs  r}  rE   r|  rF   r~  Q	  s   3
ÿùzExpr.rolling_stdÚaverage)rù   Úmethodr1   c                  s:   h d£}|vrd d}t |  fdd¡S )u  Assign ranks to data, dealing with ties appropriately.

        Notes:
            The resulting dtype may differ between backends.

        !!! info
            For lazy backends, this operation must be followed by `Expr.over` with
            `order_by` specified, see [order-dependence](../basics/order_dependence.md).

        Arguments:
            method: The method used to assign ranks to tied elements.
                The following methods are available (default is 'average'):

                - 'average' : The average of the ranks that would have been assigned to
                  all the tied values is assigned to each value.
                - 'min' : The minimum of the ranks that would have been assigned to all
                    the tied values is assigned to each value. (This is also referred to
                    as "competition" ranking.)
                - 'max' : The maximum of the ranks that would have been assigned to all
                    the tied values is assigned to each value.
                - 'dense' : Like 'min', but the rank of the next highest element is
                   assigned the rank immediately after those assigned to the tied
                   elements.
                - 'ordinal' : All values are given a distinct rank, corresponding to the
                    order that the values occur in the Series.

            descending: Rank in descending order.

        Returns:
            A new expression with rank data.

        Examples:
            >>> import pandas as pd
            >>> import narwhals as nw
            >>> df_native = pd.DataFrame({"a": [3, 6, 1, 1, 6]})
            >>> df = nw.from_native(df_native)
            >>> result = df.with_columns(rank=nw.col("a").rank(method="dense"))
            >>> result
            ââââââââââââââââââââ
            |Narwhals DataFrame|
            |------------------|
            |       a  rank    |
            |    0  3   2.0    |
            |    1  6   3.0    |
            |    2  1   1.0    |
            |    3  1   1.0    |
            |    4  6   3.0    |
            ââââââââââââââââââââ
        >   rÔ   rÓ   Údenser  ÚordinalzTRanking method must be one of {'average', 'min', 'max', 'dense', 'ordinal'}. Found 'ú'c                   s     | ¡j dS )N)r  rù   )rH   Úrankrf   ©rù   r  rD   rE   rF   rg   Í	  rÑ   zExpr.rank.<locals>.<lambda>r*  )rD   r  rù   Úsupported_rank_methodsrW   rE   r  rF   r  	  s   2ÿÿÿz	Expr.rankúExprStringNamespace[Self]c                 C  ó   t | S r?   r   r`   rE   rE   rF   r^   Ò	  ó   zExpr.strúExprDateTimeNamespace[Self]c                 C  r  r?   r   r`   rE   rE   rF   ÚdtÖ	  r  zExpr.dtúExprCatNamespace[Self]c                 C  r  r?   r   r`   rE   rE   rF   ÚcatÚ	  r  zExpr.catúExprNameNamespace[Self]c                 C  r  r?   r   r`   rE   rE   rF   rk   Þ	  r  z	Expr.nameúExprListNamespace[Self]c                 C  r  r?   r   r`   rE   rE   rF   rõ   â	  r  z	Expr.listúExprStructNamespace[Self]c                 C  r  r?   r   r`   rE   rE   rF   Ústructæ	  r  zExpr.struct)r8   r6   r9   r
   r:   r;   )r8   rJ   r:   r'   )r:   r^   )r:   r'   )rk   r^   r:   r'   )rr   rs   rt   ru   rv   rw   r:   r5   )ry   rz   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Ã   rŒ   r:   r'   r?   )rr   rË   rÌ   rÍ   r:   r'   )r:   r7   )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  r  r,   r:   r'   )r  r   r:   r'   )NNN)r   r!  r"  r#  r$  r%  r:   r'   )
rè   r%  r.  rº   r/  r»   r0  r%  r:   r'   )r5  r6  r4  r7  r:   r'   )rN  rO  rP  r2   r:   r'   )rR  )r   )rX  rŒ   r:   r'   )rè   rŒ   r\  rŒ   r:   r'   )NN)r  r_  r  r_  r:   r'   )rk  rŒ   rž   r%  rj  r»   r:   r'   )
rk  rŒ   rž   r%  rj  r»   rÃ   rŒ   r:   r'   )r  )r  r1   rù   r»   r:   r'   )r:   r  )r:   r  )r:   r  )r:   r  )r:   r  )r:   r  )eÚ__name__Ú
__module__Ú__qualname__rI   rP   rX   r[   r]   ra   rj   rn   rx   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®   r°   rœ   r¿   rÀ   rÆ   rÊ   rÏ   rÒ   re   rÓ   rÔ   rÕ   rØ   rÙ   rÚ   rÛ   rd   rá   rç   ré   rñ   rþ   r  r  r  r  r  r  r(  r,  r1  r;  rI  rH  rJ  rK  rM  rN  rT  rW  rY  r[  r]  ra  rc  rd  re  rg  rh  ri  ro  rv  r{  r~  r  Úpropertyr^   r  r  rk   rõ   r  rE   rE   rE   rF   r7   :   s   
"÷bý/#/5ýû;$ü=#0##ü^(þú+ýV!!&%ý3&%%%)ûBûBúBúA@r7   N)AÚ
__future__r   Útypingr   r   r   r   r   r   Únarwhals._expression_parsingr	   r
   r   r   r   r   r   Únarwhals.dtypesr   Únarwhals.exceptionsr   r   Únarwhals.expr_catr   Únarwhals.expr_dtr   Únarwhals.expr_listr   Únarwhals.expr_namer   Únarwhals.expr_strr   Únarwhals.expr_structr   Únarwhals.translater    Únarwhals.utilsr!   r"   r#   r$   Útyping_extensionsr%   r&   r'   r(   Únarwhals._compliantr)   r*   r+   Únarwhals.typingr,   r-   r.   r/   r0   r1   r2   r3   r4   r5   r6   Ú__annotations__r7   Ú__all__rE   rE   rE   rF   Ú<module>   s    ÿ                   Eÿ