
    ^jD                    d   U d dl mZ d dlmZmZmZmZ d dlmZ d dl	m
Z
mZmZmZmZmZmZ d dlmZmZmZmZmZmZmZmZmZmZ d dlmZmZmZm Z m!Z!m"Z" d dl#m$Z$ d dl%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z.m/Z/m0Z0m1Z1 d d	l2m3Z3 e
rd d
l4m5Z5 d dl6m7Z7 d dl8m9Z9 d dl	m:Z: d dl;Z<d dl=Z>d dl?Z@d dlAmBZB d dlCmDZDmEZE d dlFmGZG d dlHmIZI d dlmJZJ d dlKmLZLmMZM d dl%mNZNmOZO d dlPmQZQ d dlRmSZS d dl2mTZT d dlUmVZVmWZWmXZXmYZYmZZZm[Z[m\Z\m]Z]m^Z^m_Z_m`Z`maZambZbmcZc eZddeed<   dZfdeed<   g dZg ed       Zhd!Zideed"<    ed#      Zj G d$ d%e(ej   eej   e!e"   eeeje"f         Zk G d& d'e d(   ed)eelef   f   ed*   eekeee"f   eeeee"f         Zm G d+ d,ekeee"f   eeee"f         Zn G d- d.emeeed/f   enedd/f   e&eeeeef         Zoy)0    )annotations)IteratorMappingSequenceSized)chain)TYPE_CHECKINGAnyFinalLiteralProtocolTypeVaroverload)
CompliantDataFrameAnyCompliantExprT_contraCompliantLazyFrameAnyCompliantNamespaceAnyCompliantSeriesT
EagerExprTEagerSeriesTNativeDataFrameTNativeLazyFrameTNativeSeriesT)ArrowConvertibleDictConvertible
FromNativeNumpyConvertible
ToNarwhalsToNarwhalsT_co)assert_never)ValidateBackendVersionVersion_StoresNativecheck_columns_existis_boolean_selectoris_compliant_seriesis_index_selectoris_rangeis_sequence_likeis_sized_multi_index_selectoris_slice_indexis_slice_none)MultiOutputExpressionError)BytesIO)Path)
ModuleType)	TypeAliasN)Self)CompliantGroupByDataFrameGroupBy)EagerNamespace)SparkSession)IntoArrowTable)_EagerAllowedImpl_LazyAllowedImpl)Implementation_LimitedContext)	DataFrame)DType)ColumnNotFoundError)AsofJoinStrategy	IntoDTypeJoinStrategyMultiColSelectorMultiIndexSelectorPivotAggSingleIndexSelectorSizedMultiIndexSelectorSizedMultiNameSelectorSizeUnitUniqueKeepStrategy_2DArray_SliceIndex
_SliceNamer1   
IncompleteFr   MYPY)CompliantDataFrameCompliantFrameCompliantLazyFrameEagerDataFrameT2dict[str, CompliantSeriesT] | dict[str, list[Any]]_ToDict_NativeFrameTc                     e Zd ZU dZded<   ded<   ded<   d"dZd#d	Zd$d
Zd%dZe	d&d       Z
ed'd       Zed(d       Zed)d       Zd)dZd*dZd+dZd,dZd-dZ	 	 	 	 	 	 d.dZd/dZ	 	 	 	 	 	 	 	 	 	 	 	 d0dZ	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d1dZd2dZd3dZd4dZ	 	 	 	 	 	 	 	 d5dZ	 	 	 	 	 	 	 	 d6dZ	 	 	 	 	 	 	 	 	 	 d7dZd3dZd8d Zy!)9rP   z)Common parts of `DataFrame`, `LazyFrame`.rV   _native_framer:   _implementationr"   _versionc                     y N selfs    V/opt/ringagent/.cad-venv/lib/python3.12/site-packages/narwhals/_compliant/dataframe.py__native_namespace__z#CompliantFrame.__native_namespace__j           c                     y r\   r]   r^   s    r`   __narwhals_namespace__z%CompliantFrame.__narwhals_namespace__k   rb   rc   c                     y r\   r]   )r_   dfs     r`   _with_nativezCompliantFrame._with_nativel   rb   rc   c                     y r\   r]   )r_   versions     r`   _with_versionzCompliantFrame._with_versionm   rb   rc   c                   y r\   r]   clsdatacontexts      r`   from_nativezCompliantFrame.from_nativen       WZrc   c                     y r\   r]   r^   s    r`   columnszCompliantFrame.columnsp       (+rc   c                    | j                   S r\   )rX   r^   s    r`   nativezCompliantFrame.nativer   s    !!!rc   c                     y r\   r]   r^   s    r`   schemazCompliantFrame.schemav   s    -0rc   c                     y r\   r]   r^   s    r`   collect_schemazCompliantFrame.collect_schemay   rb   rc   c                    y r\   r]   )r_   rt   stricts      r`   dropzCompliantFrame.dropz   rb   rc   c                     y r\   r]   r_   subsets     r`   
drop_nullszCompliantFrame.drop_nulls{   rb   rc   c                     y r\   r]   r_   rt   s     r`   explodezCompliantFrame.explode|   rb   rc   c                     y r\   r]   )r_   	predicates     r`   filterzCompliantFrame.filter}   rb   rc   c                    y r\   r]   r_   keysdrop_null_keyss      r`   group_byzCompliantFrame.group_by~   s    
 9<rc   c                     y r\   r]   )r_   ns     r`   headzCompliantFrame.head   rb   rc   c                    y r\   r]   )r_   otherhowleft_onright_onsuffixs         r`   joinzCompliantFrame.join        rc   c                    y r\   r]   )r_   r   r   r   by_leftby_rightstrategyr   s           r`   	join_asofzCompliantFrame.join_asof   s     rc   c                     y r\   r]   )r_   mappings     r`   renamezCompliantFrame.rename   rb   rc   c                     y r\   r]   r_   exprss     r`   selectzCompliantFrame.select   rb   rc   c                     y)z)`select` where all args are column names.Nr]   )r_   column_namess     r`   simple_selectzCompliantFrame.simple_select       rc   c                    y r\   r]   )r_   
descending
nulls_lastbys       r`   sortzCompliantFrame.sort       rc   c                    y r\   r]   )r_   r   keeporder_bys       r`   uniquezCompliantFrame.unique        rc   c                     y r\   r]   )r_   onindexvariable_name
value_names        r`   unpivotzCompliantFrame.unpivot   r   rc   c                     y r\   r]   r   s     r`   with_columnszCompliantFrame.with_columns   rb   rc   c                     y r\   r]   r_   namer   s      r`   with_row_indexzCompliantFrame.with_row_index   rb   rc   N)returnr0   )r   r
   )rg   rV   r   r2   )rj   r"   r   r2   )ro   rV   rp   r;   r   r2   )r   Sequence[str])r   rV   )r   zMapping[str, DType])rt   r   r}   boolr   r2   )r   Sequence[str] | Noner   r2   )rt   r   r   r2   )r   z"CompliantExprT_contra | Incompleter   r2   )r   /Sequence[str] | Sequence[CompliantExprT_contra]r   r   r   z-CompliantGroupBy[Self, CompliantExprT_contra])r   intr   r2   )r   r2   r   rA   r   r   r   r   r   strr   r2   )r   r2   r   r   r   r   r   r   r   r   r   r?   r   r   r   r2   )r   zMapping[str, str]r   r2   r   r   r   r2   )r   r   r   r2   )r   r   r   zbool | Sequence[bool]r   r   r   r2   )r   r   r   rI   r   r   r   r2   )
r   r   r   r   r   r   r   r   r   r2   )r   r   r   r   r   r2   ) __name__
__module____qualname____doc____annotations__ra   re   rh   rk   classmethodrq   propertyrt   rw   ry   r{   r~   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r]   rc   r`   rP   rP   ^   s    4  ##50::Z Z+ +" " 0 08HC:P<=< 	<
 
7< ( 	
 & '  


 	

 
 &
 '
 #
 
 

 >@$9GK	$ !	
 ' 
  $ 	
  
 GMrc   rP   c                     e Zd Zd%dZed&d       Ze	 	 	 	 	 	 	 	 d'd       Ze	 	 	 	 	 	 	 	 d(d       Ze	 	 	 	 	 	 	 	 d)d       Zd*dZ		 	 	 	 d+dZ
ed,d       Zd%d	Zd-d
Zd.dZd/dZ	 	 	 	 	 	 d0dZd1dZd2dZ	 	 	 	 	 	 d3dZd4dZ	 	 	 	 	 	 d5dZ	 	 	 	 	 	 	 	 	 	 	 	 	 	 d6dZd7dZ	 	 	 	 d8dZd9dZd:dZd;dZd<dZed=d       Zed>d       Z	 	 	 	 d?dZdd	 	 	 	 	 	 	 	 	 d@dZ dAd Z!edBd!       Z"edCd"       Z"dDd#Z"dCd$Z#y)ErO   c                     y r\   r]   r^   s    r`   __narwhals_dataframe__z)CompliantDataFrame.__narwhals_dataframe__   rb   rc   c                   y r\   r]   rm   s      r`   
from_arrowzCompliantDataFrame.from_arrow   rr   rc   c                   y r\   r]   rn   ro   rp   ry   s       r`   	from_dictzCompliantDataFrame.from_dict   r   rc   c                   y r\   r]   r   s       r`   
from_dictszCompliantDataFrame.from_dicts   r   rc   c                   y r\   r]   r   s       r`   
from_numpyzCompliantDataFrame.from_numpy   r   rc   c                    y r\   r]   )r_   dtypecopys      r`   	__array__zCompliantDataFrame.__array__   rb   rc   c                     y r\   r]   )r_   items     r`   __getitem__zCompliantDataFrame.__getitem__   r   rc   c                     y r\   r]   r^   s    r`   shapezCompliantDataFrame.shape   ru   rc   c                     y r\   r]   r^   s    r`   clonezCompliantDataFrame.clone   rb   rc   c                     y r\   r]   )r_   units     r`   estimated_sizez!CompliantDataFrame.estimated_size   rb   rc   c                     y r\   r]   )r_   r   offsets      r`   gather_everyzCompliantDataFrame.gather_every   rb   rc   c                     y r\   r]   )r_   r   s     r`   
get_columnzCompliantDataFrame.get_column   rb   rc   c                    y r\   r]   r   s      r`   r   zCompliantDataFrame.group_by   s    
 '*rc   c                     y r\   r]   )r_   rowcolumns      r`   r   zCompliantDataFrame.item   rb   rc   c                     y r\   r]   r^   s    r`   iter_columnszCompliantDataFrame.iter_columns   rb   rc   c                    y r\   r]   )r_   namedbuffer_sizes      r`   	iter_rowszCompliantDataFrame.iter_rows       BErc   c                     y r\   r]   r^   s    r`   	is_uniquezCompliantDataFrame.is_unique   rb   rc   c                    y r\   r]   )r_   backendsessions      r`   lazyzCompliantDataFrame.lazy        #rc   c                    y r\   r]   )r_   r   r   valuesaggregate_functionsort_columns	separators          r`   pivotzCompliantDataFrame.pivot   s     rc   c                     y r\   r]   )r_   r   s     r`   r   zCompliantDataFrame.row  rb   rc   c                    y r\   r]   )r_   r   s     r`   rowszCompliantDataFrame.rows  r   rc   c                    y r\   r]   )r_   r   with_replacementseeds       r`   samplezCompliantDataFrame.sample  rb   rc   c                     y r\   r]   r^   s    r`   to_arrowzCompliantDataFrame.to_arrow  rb   rc   c                     y r\   r]   r^   s    r`   	to_pandaszCompliantDataFrame.to_pandas  rb   rc   c                     y r\   r]   r^   s    r`   	to_polarszCompliantDataFrame.to_polars	  rb   rc   c                    y r\   r]   r_   	as_seriess     r`   to_dictzCompliantDataFrame.to_dict
  s    SVrc   c                    y r\   r]   r  s     r`   r  zCompliantDataFrame.to_dict  s    MPrc   c                    y r\   r]   r  s     r`   r  zCompliantDataFrame.to_dict  s    =@rc   N)maintain_orderc                    y r\   r]   )r_   r   r   r  r   s        r`   r   zCompliantDataFrame.unique  s     rc   c                     y r\   r]   r   s      r`   r   z!CompliantDataFrame.with_row_index  rb   rc   c                     y r\   r]   r_   files     r`   	write_csvzCompliantDataFrame.write_csv  s    ,/rc   c                     y r\   r]   r  s     r`   r  zCompliantDataFrame.write_csv  s    =@rc   c                     y r\   r]   r  s     r`   r  zCompliantDataFrame.write_csv  rb   rc   c                     y r\   r]   r  s     r`   write_parquetz CompliantDataFrame.write_parquet  rb   rc   r   r2   )ro   r7   rp   r;   r   r2   )ro   zMapping[str, Any]rp   r   ry   %Mapping[str, IntoDType | None] | Noner   r2   )ro   zSequence[Mapping[str, Any]]rp   r;   ry   r%  r   r2   )ro   rJ   rp   r;   ry   z.Mapping[str, IntoDType] | Sequence[str] | Noner   r2   )r   r
   r   bool | Noner   rJ   )r   zetuple[SingleIndexSelector | MultiIndexSelector[CompliantSeriesT], MultiColSelector[CompliantSeriesT]]r   r2   )r   ztuple[int, int])r   rH   r   zint | float)r   r   r   r   r   r2   )r   r   r   r   )r   r   r   r   r   zDataFrameGroupBy[Self, Any])r   
int | Noner   zint | str | Noner   r
   )r   zIterator[CompliantSeriesT])r   r   r   r   r   z7Iterator[tuple[Any, ...]] | Iterator[Mapping[str, Any]])r   r   )r   z_LazyAllowedImpl | Noner   zSparkSession | Noner   r   )r   r   r   r   r  r   r  zPivotAgg | Noner  r   r  r   r   r2   )r   r   r   ztuple[Any, ...])r   r   r   z7Sequence[tuple[Any, ...]] | Sequence[Mapping[str, Any]])r   r   r
  r   r  r'  r   r2   )r   pa.Table)r   zpd.DataFrame)r   zpl.DataFrame)r  zLiteral[True]r   zdict[str, CompliantSeriesT])r  zLiteral[False]r   zdict[str, list[Any]])r  r   r   rT   )
r   r   r   rI   r  r&  r   r   r   r2   )r   r   r   r   r   r2   )r  Noner   r   r  zstr | Path | BytesIOr   r)  )r  zstr | Path | BytesIO | Noner   z
str | None)$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  r#  r]   rc   r`   rO   rO      st    2Z Z
 ' 6 
  )
 ! 6 
  
 ! ? 
  K
 
 + + @<<*=* 	*
 
%* J=FF+.F	@F 1$.$<O$	$		 $		
 %	 ,	 	 	 
	 6FF	@F W',,V VP PA A	;A '+$ !	
 $ ' 
 U/ /@ @MDrc   rO   )rJ   rJ   z_ToDict[CompliantSeriesT])r(  r7   c                  @    e Zd ZddZddZd	dZ	 	 	 	 	 	 d
dZddZy)rQ   c                     y r\   r]   r^   s    r`   __narwhals_lazyframe__z)CompliantLazyFrame.__narwhals_lazyframe__&  rb   rc   c                     y r\   r]   r^   s    r`   _iter_columnsz CompliantLazyFrame._iter_columns(  rb   rc   c                     y)zk`select` where all args are aggregations or literals.

        (so, no broadcasting is necessary).
        Nr]   r   s     r`   	aggregatezCompliantLazyFrame.aggregate)  s    
 	rc   c                     y r\   r]   )r_   r   kwargss      r`   collectzCompliantLazyFrame.collect0  r   rc   c                     y r\   r]   r  s     r`   sink_parquetzCompliantLazyFrame.sink_parquet3  rb   rc   Nr$  )r   zIterator[Any]r   )r   z_EagerAllowedImpl | Noner3  r
   r   r   r*  )r   r   r   r-  r/  r1  r4  r6  r]   rc   r`   rQ   rQ   "  s2     21$/$;>$	$ Drc   rQ   c                      e Zd Zedd       Z	 	 ddZddZddZdd	 	 	 	 	 ddZddZ	dd	Z
dd
ZddZd dZe	 	 	 	 	 	 d!d       Zd"dZd#dZ	 	 	 	 d$dZ	 	 	 	 d%dZd&dZd'dZ	 	 	 	 d(dZd)dZy)*rR   c                6    | j                   j                         S r\   )rY   _backend_versionr^   s    r`   r9  zEagerDataFrame._backend_version>  s    ##4466rc   c                     y r\   r]   r^   s    r`   re   z%EagerDataFrame.__narwhals_namespace__B  s     rc   c                <    | j                   j                  | d      S )Nfull)level)rZ   	dataframer^   s    r`   to_narwhalszEagerDataFrame.to_narwhalsH  s    }}&&t6&::rc   c                      | j                   | S r\   )r   r   s     r`   r1  zEagerDataFrame.aggregateK  s     t{{E""rc   T)validate_column_namesc                    y r\   r]   )r_   rg   rA  s      r`   rh   zEagerDataFrame._with_nativeU  r   rc   c                0    t        || j                        S )N)	available)r$   rt   r   s     r`   _check_columns_existz#EagerDataFrame._check_columns_existY  s    "6T\\BBrc   c               d    | j                  |      }t        |      dk7  rd}t        |      |d   S )z6Evaluate `expr` and ensure it has a **single** output.   z4multi-output expressions not allowed in this contextr   )_evaluate_exprlenr-   )r_   exprresultmsgs       r`   _evaluate_single_output_exprz+EagerDataFrame._evaluate_single_output_expr\  s:    
 $$T*v;!HC,S11ayrc   c                R     t        t        j                   fd|D                    S )Nc              3  @   K   | ]  }j                  |        y wr\   )rH  ).0rJ  r_   s     r`   	<genexpr>z1EagerDataFrame._evaluate_exprs.<locals>.<genexpr>k  s     (Ut)<)<T)B(Us   )tupler   from_iterabler   s   ` r`   _evaluate_exprszEagerDataFrame._evaluate_exprsg  s!     U(((Uu(UUVVrc   c                   |j                  |       } ||       }t        |      |D cg c]  }|j                   c}x}k7  rd| d| }t        |      |S c c}w )a  Return list of raw columns.

        For eager backends we alias operations at each step.

        As a safety precaution, here we can check that the expected result names match those
        we were expecting from the various `evaluate_output_names` / `alias_output_names` calls.

        Note that for PySpark / DuckDB, we are less free to liberally set aliases whenever we want.
        z"Safety assertion failed, expected z, got )_evaluate_aliaseslistr   AssertionError)r_   rJ  aliasesrK  sresult_aliasesrL  s          r`   rH  zEagerDataFrame._evaluate_exprm  sj     ((.d=/56!qvv66N
 7wivnEUVC %%	 7s   Ac                    y)z@Extract native Series, broadcasting to `len(self)` if necessary.Nr]   )r_   r   s     r`   _extract_comparandz!EagerDataFrame._extract_comparand  r   rc   c               Z    t        |xs d t        | j                  d         D              S )Nc              3  &   K   | ]	  }d |   yw)column_Nr]   )rP  xs     r`   rQ  z5EagerDataFrame._numpy_column_names.<locals>.<genexpr>  s     L!'!Ls   rG  )rW  ranger   )ro   rt   s     r`   _numpy_column_namesz"EagerDataFrame._numpy_column_names  s'     GLLuTZZ]7KLMMrc   c                     y r\   r]   r_   r  s     r`   _gatherzEagerDataFrame._gather  rb   rc   c                     y r\   r]   re  s     r`   _gather_slicezEagerDataFrame._gather_slice  rb   rc   c                     y r\   r]   r   s     r`   _select_multi_indexz"EagerDataFrame._select_multi_index  r   rc   c                     y r\   r]   r   s     r`   _select_multi_namez!EagerDataFrame._select_multi_name  r   rc   c                     y r\   r]   r   s     r`   _select_slice_indexz"EagerDataFrame._select_slice_index  rb   rc   c                     y r\   r]   r   s     r`   _select_slice_namez!EagerDataFrame._select_slice_name  rb   rc   c                t   |\  }}| }t        |      sbt        |t              rt        |      dk(  r|j	                         S t        |      r- |j                  d t        |j                  |d      D         }nt        |      rat        |      st        |      r|j                  |      }nt        |      r| j                  |j                        }n|j                  |      }nt        |t               r*t"        r|j%                  |      }nh|j%                  |      }nVt        |      r| j'                  |j                        }n/t)        |      r| j'                  |      }nt"        rnt+        |       t        |      st        |t,              r|j/                  |g      }|S t        |t         t0        f      r|j3                  |      }|S t        |      r|j/                  |j                        }|S t5        |      r,t"        r|j/                  |      }|S |j/                  |      }|S t+        |       |S )Nr   c              3  *   K   | ]  \  }}|r|  y wr\   r]   )rP  colr   s      r`   rQ  z-EagerDataFrame.__getitem__.<locals>.<genexpr>  s      'C! s   F)r}   )r,   
isinstancer   rI  r   r%   r   ziprt   r'   r+   r(   rn  r&   rj  rw   slicerN   rp  rl  r)   r    r   rf  rb  rh  r*   )r_   r   r  rt   	compliants        r`   r   zEagerDataFrame.__getitem__  s    g	W%'5)c'la.? ''))"7+3I33+.y/@/@'RW+X	 #7+!'*hw.? ) = =g FI(1 $ 8 8 HI ) = =g FIGU+ ) < <W EI ) < <W EI$W- 33GNNC	!'* 33G<	W%T"$$%--tf5	  D5%.1%33D9	  %T*%--dkk:	  /t4 ) 1 1$ 7I 	 !* 1 1$ 7I  T"rc   c                $    | j                  |      S r\   )r#  r  s     r`   r6  zEagerDataFrame.sink_parquet  s    !!$''rc   N)r   ztuple[int, ...])r   zOEagerNamespace[Self, EagerSeriesT, EagerExprT, NativeDataFrameT, NativeSeriesT])r   DataFrame[NativeDataFrameT])r   r   r   r2   )rg   r   rA  r   r   r2   )r   r   r   zColumnNotFoundError | None)rJ  r   r   r   )r   r   r   Sequence[EagerSeriesT])rJ  r   r   rz  )r   r   r   r
   )ro   rJ   rt   r   r   z	list[str])r  &SizedMultiIndexSelector[NativeSeriesT]r   r2   )r  _SliceIndex | ranger   r2   )rt   r{  r   r2   )rt   z%SizedMultiNameSelector[NativeSeriesT]r   r2   )rt   r|  r   r2   )rt   rL   r   r2   )r   z]tuple[SingleIndexSelector | MultiIndexSelector[EagerSeriesT], MultiColSelector[EagerSeriesT]]r   r2   r*  )r   r   r   r   r9  re   r?  r1  rh   rE  rM  rT  rH  r]  staticmethodrc  rf  rh  rj  rl  rn  rp  r   r6  r]   rc   r`   rR   rR   6  s     7 7
;# FJ">B	C	W& NN!5N	N N
 QC=	<	 MB;
; 
;z(rc   rR   ry  )p
__future__r   collections.abcr   r   r   r   	itertoolsr   typingr	   r
   r   r   r   r   r   narwhals._compliant.typingr   r   r   r   r   r   r   r   r   r   narwhals._translater   r   r   r   r   r   narwhals._typing_compatr    narwhals._utilsr!   r"   r#   r$   r%   r&   r'   r(   r)   r*   r+   r,   narwhals.exceptionsr-   ior.   pathlibr/   typesr0   r1   pandaspdpolarsplpyarrowpatyping_extensionsr2   narwhals._compliant.group_byr3   r4   narwhals._compliant.namespacer5   narwhals._spark_like.utilsr6   r7   narwhals._typingr8   r9   r:   r;   narwhals.dataframer<   narwhals.dtypesr=   r>   narwhals.typingr?   r@   rA   rB   rC   rD   rE   rF   rG   rH   rI   rJ   rK   rL   rM   r   rN   __all__rS   rU   rV   rP   r   rO   rQ   rR   r]   rc   r`   <module>r     s   " > >  R R R    1    ;  &O<72D?,%7   "  J	e 
ZCLI I(SN- }~"M>AB	SNlkE+,/c1BBC12	(*:NJK46FVWkE\D(*:NJK"$4nDED(\(j"24QQ z<1NNO\:'7FG\(rc   