-Ph6 ddlmZddlmZddlmZmZmZmZm Z m Z m Z m Z m Z ddlmZddlZddlmZmZmZmZddlmZddlmZmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&dd l'm(Z)m*Z+dd l,m-Z-dd l.m/Z/dd l0m1Z2dd l3m4Z4m5Z5m6Z6m7Z7ddl8m9Z:ddl;mm?Z?ddl@mAZAmBZBmCZCmDZDmEZEmFZFmGZGmHZHmIZImJZJmKZKmLZLmMZMmNZNmOZOmPZPmQZQmRZRmSZSmTZTmUZUmVZVmWZWmXZXmYZYmZZZm[Z[m\Z\ddl]m^Z^m_Z_m`Z`ddlambZbmcZcerddldmeZeddlfmgZgmhZhddlimjZjddl'mkZkmlZlddlmmnZnddlamoZompZpmqZqmrZrmsZsmtZtmuZumvZvmwZwmxZxeddZyeddZzedd Z{ed!e"Z|egd#Z}ed$Z~ed%d&e'ZGd(d)e)ebZ(Gd*d+e+ecZ*Gd,d-e=eZ<Gd.d/e2Z1Gd0d1e:Z9e dd6Ze dd9Ze dd<Ze dd>ZddAZe ddEZe ddFZe ddGZe ddIZe dJdJdKddUZe dJdJdVddWZe dJdJdJdXdd\Ze dJdJdJdXdd]Ze dJdJdJd^dd_Ze dJdJdJd^dd`Ze dJdJdJdadddZe dJdJdJdeddfZe dJdJdJdJdgddjZe dJdJdJdJdgddkZe dJdJdJdJdlddmZe dJdJdJdJdnddoZe dJdJdJdJdpddsZe dJdJdJdJdtd duZe dJdJdJdJdJdvd dyZe dJdJdJdJdJdvd dzZe dJdJdKd d}Ze dJdJdVd d~Ze dJdJdJdXddZe dJdJdJdXddZe dJdJdJd^ddZe dJdJdJd^ddZe dJdJdJdaddZe dJdJdJdeddZe dJdJdJdJdgddZe dJdJdJdJdgddZe dJdJdJdJdddZe dJdJdJdJdddZe dJdJdJdJdddZe dJdJdJdJdddZe dJdJdJdJdJdddZe ddddZdddddddddZe dJdddZe dJdddZe dJdddZe d dZe dJdd!dZe dJdd"dZe dJdd#dZe d$dZdddd%dZ d&dddddddd'dZd(dZd)dZd)dZd*dZd(dZd&d+dZd,dZd,dZd,dZd,dZd,d„Zd-dńZd-dƄZd-dDŽZd-dȄZd-dɄZd-dʄZddd̜d.dфZGd҄dejZGdԄdeje1Zd/dׄZedئ d&dddٜd0dZedئdddٜd1dZe d&dddٜd2dZedئ d&dddٜd3dZedئdddٜd4dZedئdddٜd5dZedئdddٜd4dZedئdddٜd5dZgdZdS(6) annotationswraps) TYPE_CHECKINGAnyCallableIterableLiteralMappingSequencecastoverload)warnN) dependencies exceptions functions selectors)TypeVar) ImplementationVersiondeprecate_native_namespacefind_stacklevelgenerate_temporary_column_name inherit_docis_ordered_categoricalmaybe_align_indexmaybe_convert_dtypesmaybe_get_indexmaybe_reset_indexmaybe_set_indexvalidate_strict_and_pass_though) DataFrame LazyFrame) get_polars)InvalidIntoExprErrorExpr)_new_series_implconcat get_level show_versions)SchemaSeries)dtypes)ArrayBinaryBoolean CategoricalDateDatetimeDecimalDurationEnumFieldFloat32Float64Int8Int16Int32Int64Int128ListObjectStringStructTimeUInt8UInt16UInt32UInt64UInt128Unknown)_from_native_implget_native_namespace to_py_scalar)IntoDataFrameT IntoFrameT) ModuleType) ParamSpecSelf)IntoArrowTable)MultiColSelectorMultiIndexSelector)DType) IntoDTypeIntoExpr IntoFrameIntoLazyFrameT IntoSeriesNonNestedLiteralSingleColSelectorSingleIndexSelector_1DArray_2DArray DataFrameTDataFrame[Any])bound LazyFrameTLazyFrame[Any]SeriesT Series[Any]T)defaultPR IntoSeriesTr\)rdrjcVeZdZeed.fd Zed/d Zed0d Ze d1dZ e d2dZ e d3dZ d4fd Z d5d6fd Z e ddd7d"Z e d8d%Z e d9d(Z d)dd9fd*Z d:fd+ Z d:fd, Zd;d-ZxZS)>++,,,rrorrprqrrrs)rrr)rrr)rrrrr)rrrrrh)rrrrrS)rrrrrr)rrrrrf)rrrrr)rrrrr)rrrrr)rrrhrrrS)__name__ __module__ __qualname__r NwDataFramer{propertyrrrrrrrrr __classcell__r~s@rr"r"ks[******111X1777X7ZZZXZ X   X  ) ) ) ) ) ) CG9999999 47WWWWWXW PPPXP <<<X<$(44444444333333//////--------rr"ceZdZeedfd Zedd Zdd Z ddfd Z d dZ d!d"fd Z d#d$dZ xZ S)%r#rorrprqrrrscx|jtjusJt||dSrurwr|s rr{zLazyFrame.__init__rrtype[DataFrame[Any]]ctSrr"rs r _dataframezLazyFrame._dataframerargc^ddlm}ddlm}ddlm}t ||r|jSt ||rd}t|t ||r'| | St |tr)| }| |St@dtt|vr"dt|d}t|tjt|) Nr BaseFramer&r-z.Mixing Series with LazyFrame is not supported.polarszExpected Narwhals object, got: z[. Perhaps you: - Forgot a `nw.from_native` somewhere? - Used `pl.col` instead of `nw.col`?)narwhals.dataframer narwhals.exprr'narwhals.seriesr. isinstance_compliant_frame TypeError_to_compliant_expr__narwhals_namespace__strcolr$typer%from_invalid_type)r}rrr'r.msgplxs r_extract_compliantzLazyFrame._extract_compliantsD 100000&&&&&&****** c9 % % (' ' c6 " " !BCC.. c4  I))$*E*E*G*GHH H c3   --//C773<<  << #CS NN(B(B7$s))777  C.. "4T#YY???rNrrkwargsrcc Tttjdd|i|S)Nrr)rrzcollect)r}rrr~s rrzLazyFrame.collects./%''/DD'DVDDEEErrSch|tS)zbPrivate, just used to test the stable API. Returns: A new lazyframe. rrs rrzLazyFrame._l1_normrrnintcFt|S)zGet the last `n` rows. Arguments: n: Number of rows to return. Returns: A subset of the LazyFrame of shape (n, n_columns). )rztail)r}rr~s rrzLazyFrame.tailsww||Arroffsetc`||j||S)zTake every nth row in the DataFrame and return as a new DataFrame. Arguments: n: Gather every *n*-th row. offset: Starting index. Returns: The LazyFrame containing only the selected rows. rr)_with_compliantr gather_everyr}rrs rrzLazyFrame.gather_everys5##  ! . .6 . B B   rrrrr)rrrrrr)rrrrrrrcr)rrrrrrSrrrrrrrrS)rrrr NwLazyFramer{rrrrrrrrrs@rr#r#s [******X@@@@:CGFFFFFFF ----                 rr#ceZdZeedfd Zedd Zd fd Zd d d d dd!fdZ d"d ddd#fdZ xZ S)$r.seriesrrprqrrrscx|jtjusJt||dSrurw)r}rrpr~s rr{zSeries.__init__s='*,,,, u-----rrctSrrrs rrzSeries._dataframerrrcc^ttSr)rrzto_framers rrzSeries.to_frames!%''**,,---rFNsortparallelname normalizerrrr str | Nonerchtt||||S)Nr)rrz value_counts)r}rrrrr~s rrzSeries.value_counts s< GG H49 !     rT) bin_countinclude_breakpointbinslist[float | int] | Noner int | Nonercddlm}ddlm}d}t |||t t |||S)Nr)r)NarwhalsUnstableWarningzZ`Series.hist` is being called from the stable API although considered an unstable feature.messagecategory stacklevel)rrr)narwhals._utilsrnarwhals.exceptionsrrrrzhist)r}rrrrrrr~s rr z Series.hist.s 433333?????? #  S#:GXGXYYYY GGLLYCU      r)rrrprqrrrsr)rrrc) rrrrrrrrrrrcr)rrrrrrrrrc) rrrrNwSeriesr{rrrrr rrs@rr.r.s[......X......          *. !%#'             rr.czeZdZdfd Zd d!dZd d!dZd"d#d Zd d d$dZdddd%dZddZ d&d dd dd'dZ xZ S)(r'rrrScDtSr)rz _taxicab_normrs rrz Expr._l1_normEsww$$&&&r rrc8fdS)zGet the first `n` rows. Arguments: n: Number of rows to return. Returns: A new expression. cT|Sr)rheadrrr}s rzExpr.head..R#//4499!<<r_with_orderable_filtrationr}rs``rrz Expr.headH-.. < < < < <   rc8fdS)zGet the last `n` rows. Arguments: n: Number of rows to return. Returns: A new expression. cT|Sr)rrrs rrzExpr.tail.._rrrrs``rrz Expr.tailUrrrrc<fdS)zTake every nth value in the Series and return as new Series. Arguments: n: Gather every *n*-th row. offset: Starting index. Returns: A new expression. cX|S)Nr)rr)rrrr}s rrz#Expr.gather_every..ms(//44AAAfAUUrrrs```rrzExpr.gather_everybs1.. U U U U U U   rN)maintain_orderr bool | Nonec|%d}t|ttfdS)aTReturn unique values of this expression. Arguments: maintain_order: Keep the same order as the original expression. This is deprecated and will be removed in a future version, but will still be kept around in `narwhals.stable.v1`. Returns: A new expression. Nzx`maintain_order` has no effect and is only kept around for backwards-compatibility. You can safely remove this argument.rcR|Sr)runiquerr}s rrzExpr.unique..s!1H1H1M1M1T1T1V1Vr)r UserWarningr_with_filtration)r}rrs` rr!z Expr.uniquepsP  %7  {?P?P Q Q Q Q$$%V%V%V%VWWWrF descending nulls_lastr&rr'c<fdS)zSort this column. Place null values first. Arguments: descending: Sort in descending order. nulls_last: Place null values last instead of first. Returns: A new expression. cX|S)Nr%)rr)rr&r'r}s rrzExpr.sort..s///4499%*:r)_with_unorderable_window)r}r&r's```rrz Expr.sorts=,,         rc4fdS)zhFind elements where boolean expression is True. Returns: A new expression. cR|Sr)rarg_truer"s rrzExpr.arg_true..s!//44==??rrrs`rr-z Expr.arg_trues) .. ? ? ? ?   rfractionwith_replacementseedrr/ float | Noner0r1cDfdS)aSample randomly from this expression. 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. c\|S)Nr.)rsample)rr/rr1r}r0s rrzExpr.sample..s4//44;;H7Gd<r)r$)r}rr/r0r1s`````rr5z Expr.samplesI($$           rr)rrrr)rrrrrS)r&rr'rrrrSr) rrr/r2r0rr1rrrrS) rrrrrrrr!rr-r5rrs@rr'r'Ds''''''                  7;XXXXXX&*/5           "&!&           rr'cTeZdZejZee ddfd ZxZ S) r,Nschema8Mapping[str, DType] | Iterable[tuple[str, DType]] | NonerrrscJt|dSr)rzr{)r}r7r~s rr{zSchema.__init__s#      rr)r7r8rrrs) rrrrryrxrNwSchemar{rrs@rr,r,sazH[QU!!!!!!!!!!!rr,objNwDataFrame[IntoFrameT]rrDataFrame[IntoFrameT]cdSrrr;s rrrGJsrNwLazyFrame[IntoFrameT]LazyFrame[IntoFrameT]cdSrrr?s rrrr@rNwSeries[IntoSeriesT]Series[IntoSeriesT]cdSrrr?s rrrCF3rNwExprcdSrrr?s rrrs%(SrRNwDataFrame[IntoFrameT] | NwLazyFrame[IntoFrameT] | NwSeries[IntoSeriesT] | NwExprJDataFrame[IntoFrameT] | LazyFrame[IntoFrameT] | Series[IntoSeriesT] | Exprcpt|tr8t|jt j|jSt|tr8t|jt j|jSt|tr8t|j t j|jSt|trt|j|jSdt#|}t%|)Nrvz5Expected DataFrame, LazyFrame, Series, or Expr, got: )rrr"r _with_versionrry_levelrr#r r._compliant_seriesrHr'r _metadatarAssertionError)r;rs rrrs #{##[-;;GJGGszZZZZ#{##[-;;GJGGszZZZZ#x  Yc+99'*EESZXXXX#v;C*CM::: M$s)) M MC   r native_objectkwdsrc dSrrrRrSs r from_nativerVsADrc dSrrrUs rrVrVr@rc dSrrrUs rrVrVr@rDataFrameT | LazyFrameTc dSrrrUs rrVrVs "cr.) eager_only series_onlyIntoDataFrameT | IntoSeriesTstrictrr[eager_or_interchange_onlyrr\ allow_series/DataFrame[IntoDataFrameT] | Series[IntoSeriesT]cdSrrrRr^r[r_r\r`s rrVrV 7:cr)r_r\cdSrrrcs rrVrVrdr)r[r\r`rOrsDataFrame[IntoDataFrameT]cdSrrrcs rrVrV !$rcdSrrrcs rrVrV  r)r_r\r`cdSrrrcs rrVrV rhrcdSrrrcs rrVrV,rjr)r[r_r\IntoFrameT | IntoSeriesTCDataFrame[IntoFrameT] | LazyFrame[IntoFrameT] | Series[IntoSeriesT]cdSrrrcs rrVrV8 KN#r)r[r_r`cdSrrrcs rrVrVD #r)r[r_r\r`rP-DataFrame[IntoFrameT] | LazyFrame[IntoFrameT]cdSrrrcs rrVrVP 58CrcdSrrrcs rrVrV\rjr)r^r[r\r`cdSrrrcs rrVrVhrhr)r^r_r\r`cdSrrrcs rrVrVtrhr)r^r[r_r\IntoFrame | IntoSeries-DataFrame[Any] | LazyFrame[Any] | Series[Any]cdSrrrcs rrVrVrur)r^r[r_r`cdSrrrcs rrVrVrrr)r^r[r_r\r`r[LazyFrame[IntoLazyFrameT]cdSrrrcs rrVrVrhrcdSrrrcs rrVrVrurIntoDataFrameT | IntoSeries pass_throughcdSrrrRrr[r_r\r`s rrVrVrhrcdSrrrs rrVrVrdrcdSrrrs rrVrVrhrcdSrrrs rrVrVrjrcdSrrrs rrVrVrhrcdSrrrs rrVrVrjrcdSrrrs rrVrVrprcdSrrrs rrVrVrrrcdSrrrs rrVrVrurcdSrrrs rrVrVrjr)rr[r\r`cdSrrrs rrVrV)rhr)rr_r\r`cdSrrrs rrVrV5rhr)rr[r_r\cdSrrrs rrVrVArur)rr[r_r`cdSrrrs rrVrVMrrrrr[r_r\r`cdSrrrs rrVrVYrurF)r_rrcdSrrrs rrVrVfs  #r)r^rr[r_r\r`5IntoFrameT | IntoFrame | IntoSeriesT | IntoSeries | TGLazyFrame[IntoFrameT] | DataFrame[IntoFrameT] | Series[IntoSeriesT] | Tc >t|ttfr|s|St|tr|s|r|St ||dd}|r.dt t |}t|t||||||tj S)a Convert `native_object` to Narwhals Dataframe, Lazyframe, or Series. Arguments: native_object: Raw object from user. Depending on the other arguments, input object can be - a Dataframe / Lazyframe / Series supported by Narwhals (pandas, Polars, PyArrow, ...) - an object which implements `__narwhals_dataframe__`, `__narwhals_lazyframe__`, or `__narwhals_series__` strict: Determine what happens if the object can't be converted to Narwhals - `True` or `None` (default): raise an error - `False`: pass object through as-is *Deprecated* (v1.13.0) Please use `pass_through` instead. Note that `strict` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). pass_through: Determine what happens if the object can't be converted to Narwhals - `False` or `None` (default): raise an error - `True`: pass object through as-is eager_only: Whether to only allow eager objects - `False` (default): don't require `native_object` to be eager - `True`: only convert to Narwhals if `native_object` is eager eager_or_interchange_only: Whether to only allow eager objects or objects which have interchange-level support in Narwhals - `False` (default): don't require `native_object` to either be eager or to have interchange-level support in Narwhals - `True`: only convert to Narwhals if `native_object` is eager or has interchange-level support in Narwhals See [interchange-only support](../extending.md/#interchange-only-support) for more details. series_only: Whether to only allow Series - `False` (default): don't require `native_object` to be a Series - `True`: only convert to Narwhals if `native_object` is a Series allow_series: Whether to allow Series (default is only Dataframe / Lazyframe) - `False` or `None` (default): don't convert to Narwhals if `native_object` is a Series - `True`: allow `native_object` to be a Series Returns: DataFrame, LazyFrame, Series, or original object, depending on which combination of parameters was passed. Fpass_through_defaultemit_deprecation_warningz1from_native() got an unexpected keyword argument )rr[r_r\r`version) rr"r#r.r!nextiterrrLrry) rRr^rr[r_r\r`rSrs rrVrVrs|-)Y!788-((k\2 5SXL V$tDzzBRBRVVnn !";!    r)r^narwhals_objectcdSrrrr^s r to_nativer SrcdSrrrs rrr rcdSrrrs rrr #rcdSrrrs rrrs=@SrrcdSrrrrs rrrrrcdSrrrs rrrrrcdSrrrs rrrrrcdSrrrs rrrrGr)r^rGDataFrame[IntoDataFrameT] | LazyFrame[IntoFrameT] | Series[IntoSeriesT]IntoFrameT | IntoSeriesT | Anycddlm}ddlm}ddlm}|||dd}t ||r |jjSt ||r |j j S|s"dt|d}t||S) a,Convert Narwhals object to native one. Arguments: narwhals_object: Narwhals object. strict: Determine what happens if `narwhals_object` isn't a Narwhals class - `True` (default): raise an error - `False`: pass object through as-is *Deprecated* (v1.13.0) Please use `pass_through` instead. Note that `strict` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). pass_through: Determine what happens if `narwhals_object` isn't a Narwhals class - `False` (default): raise an error - `True`: pass object through as-is Returns: Object of class that user started with. rr!rr-FrzExpected Narwhals object, got .) rr!rrrr.rr _native_framerOnativerr)rr^rr!rr.rs rrrs<@?????,,,,,,&&&&&&22 5SXL/9-->/==/6**8077 GtO/D/DGGGnn rTfuncCallable[..., Any] | NoneCallable[..., Any]cdt|ddd fd }||S||S) a Decorate function so it becomes dataframe-agnostic. This will try to convert any dataframe/series-like object into the Narwhals respective DataFrame/Series, while leaving the other parameters as they are. Similarly, if the output of the function is a Narwhals DataFrame or Series, it will be converted back to the original dataframe/series type, while if the output is another type it will be left as is. By setting `pass_through=False`, then every input and every output will be required to be a dataframe/series-like object. Arguments: func: Function to wrap in a `from_native`-`to_native` block. strict: Determine what happens if the object can't be converted to Narwhals *Deprecated* (v1.13.0) Please use `pass_through` instead. Note that `strict` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). - `True` or `None` (default): raise an error - `False`: pass object through as-is pass_through: Determine what happens if the object can't be converted to Narwhals - `False` or `None` (default): raise an error - `True`: pass object through as-is eager_only: Whether to only allow eager objects - `False` (default): don't require `native_object` to be eager - `True`: only convert to Narwhals if `native_object` is eager eager_or_interchange_only: Whether to only allow eager objects or objects which have interchange-level support in Narwhals - `False` (default): don't require `native_object` to either be eager or to have interchange-level support in Narwhals - `True`: only convert to Narwhals if `native_object` is eager or has interchange-level support in Narwhals See [interchange-only support](../extending.md/#interchange-only-support) for more details. series_only: Whether to only allow Series - `False` (default): don't require `native_object` to be a Series - `True`: only convert to Narwhals if `native_object` is a Series allow_series: Whether to allow Series (default is only Dataframe / Lazyframe) - `False` or `None`: don't convert to Narwhals if `native_object` is a Series - `True` (default): allow `native_object` to be a Series Returns: Decorated function. TFrrrrrcJtdfd }|S)Nargsrrrrc@ fd|D} fd|D}fdg||RD}|dkrd}t| |i|}t | S)Nc :g|]}t|SrrV).0rr`r[r_rr\s r zBnarwhalify..decorator..wrapper..[sL   !-).G +!-    rc Bi|]\}}|t|Srr)rrvaluer`r[r_rr\s r zBnarwhalify..decorator..wrapper..gsR    D%k!-).G +!-    rcJh|]}t|ddx S)__native_namespace__N)getattr)rvbs r zAnarwhalify..decorator..wrapper..ssG $:DAAAArz_Found multiple backends. Make sure that all dataframe/series inputs come from the same backend.r)itemsvalues__len__ ValueErrorr) rrbackendsrresultrr`r[r_rrr\s @rwrapperz.narwhalify..decorator..wrapperYs            D        $*<<>>   F242&--//22H !!A%%w oo%T4*6**FV,??? ?r)rrrrrrrr)rrr`r[r_rr\s` r decoratorznarwhalify..decoratorXs^ t% @% @% @% @% @% @% @% @% @% @ % @NrN)rrrrrr)rr^rr[r_r\r`rs ````` r narwhalifyrsx|3 4RWL))))))))))V |yrcBttjS)z`Instantiate an expression representing all columns. Returns: A new expression. )rnwrrrrrr bfhh  rnamesstr | Iterable[str]c8ttj|S)zCreates an expression that references one or more columns by their name(s). Arguments: names: Name(s) of the columns to use. Returns: A new expression. )rrrrs rrrs bfen % %%rc8ttj|S)zCreates an expression that excludes columns by their name(s). Arguments: names: Name(s) of the columns to exclude. Returns: A new expression. )rrexcluders rrrs bj%( ) ))rindicesint | Sequence[int]c8ttj|S)aICreates an expression that references one or more columns by their index(es). Notes: `nth` is not supported for Polars version<1.0.0. Please use [`narwhals.col`][] instead. Arguments: indices: One or more indices representing the columns to retrieve. Returns: A new expression. )rrnth)rs rrrs bfg& ' ''rcBttjS)zGReturn the number of rows. Returns: A new expression. )rrlenrrrrrrrrr]dtypeIntoDType | NonecFttj||S)a!Return an expression representing a literal value. Arguments: value: The value to use as literal. dtype: The data type of the literal value. If not provided, the data type will be inferred by the native library. Returns: A new expression. )rrlit)rrs rrrs bfUE** + ++rcolumnsrc8ttj|S)zReturn the minimum value. Note: Syntactic sugar for ``nw.col(columns).min()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Returns: A new expression. )rrminrs rrr bfg& ' ''rc8ttj|S)zReturn the maximum value. Note: Syntactic sugar for ``nw.col(columns).max()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Returns: A new expression. )rrmaxrs rrrrrc8ttj|S)zGet the mean value. Note: Syntactic sugar for ``nw.col(columns).mean()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. )rrmeanrs rrrs bgw' ( ((rc8ttj|S)atGet the median value. Notes: - Syntactic sugar for ``nw.col(columns).median()`` - Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median. Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. )rrmedianrs rrrs bi) * **rc8ttj|S)zSum all values. Note: Syntactic sugar for ``nw.col(columns).sum()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. )rrsumrs rrrrrexprsIntoExpr | Iterable[IntoExpr]c8ttj|S)a2Sum all values horizontally across columns. Warning: Unlike Polars, we support horizontal sum over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. )rrsum_horizontalrs rrr b'/ 0 00rc8ttj|S)zCompute the bitwise AND horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. )rrall_horizontalrs rrr/ b'/ 0 00rc8ttj|S)zCompute the bitwise OR horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. )rrany_horizontalrs rrr<rrc8ttj|S)zCompute the mean of all values horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. )rrmean_horizontalrs rrrIs b(%0 1 11rc8ttj|S)a*Get the minimum value horizontally across columns. Notes: We support `min_horizontal` over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. )rrmin_horizontalrs rrrVrrc8ttj|S)a*Get the maximum value horizontally across columns. Notes: We support `max_horizontal` over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. )rrmax_horizontalrs rrrfrr separator ignore_nulls more_exprsrYrrcHttj|g|R||dS)aHorizontally concatenate columns into a single string column. Arguments: exprs: Columns to concatenate into a single string column. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. Non-`String` columns are cast to `String`. *more_exprs: Additional columns to concatenate into a single string column, specified as positional arguments. separator: String that will be used to separate the values of each column. ignore_nulls: Ignore null values (default is `False`). If set to `False`, null values will be propagated and if the row contains any null values, the output is null. Returns: A new expression. r)rr concat_str)rrrrs rr r vs5,  eYjYYILYYY  rc8eZdZed dZd fd ZxZS) Whenwhen nw_f.Whenrrc"||jSr) _predicate)clsr s r from_whenzWhen.from_whenss4?###rr&IntoExpr | NonNestedLiteral | _1DArrayThencvtt|Sr)r from_thenrzthenr}rr~s rrz When.thens%~~eggll511222r)r rrrr )rrrrr)rrr classmethodrrrrs@rr r s[$$$[$3333333333rr c8eZdZed dZd fd ZxZS) rr nw_f.Thenrrc.||j|jSr)rrP)rrs rrzThen.from_thenss4*DN;;;rrrr'c`tt|Sr)rrz otherwisers rrzThen.otherwises#%''++E22333r)rrrrr)rrrrr')rrrrrrrrs@rrrs[<<<[<4444444444rr predicatescNttj|S)aStart a `when-then-otherwise` expression. Expression similar to an `if-else` statement in Python. Always initiated by a `pl.when().then()`, and optionally followed by a `.otherwise()` can be appended at the end. If not appended, and the condition is not `True`, `None` will be returned. Info: Chaining multiple `.when().then()` statements is currently not supported. See [Narwhals#668](https://github.com/narwhals-dev/narwhals/issues/668). Arguments: predicates: Condition(s) that must be met in order to apply the subsequent statement. Accepts one or more boolean expressions, which are implicitly combined with `&`. String input is parsed as a column name. Returns: A "when" object, which `.then` can be called on. )r rnw_fr )rs rr r s* >>$)Z0 1 11r)required)rnative_namespacerrrrr#ModuleType | Nonecbtd|}tt||||S)aPInstantiate Narwhals Series from iterable (e.g. list or array). Arguments: name: Name of resulting Series. values: Values of make Series from. dtype: (Narwhals) dtype. If not provided, the native library may auto-infer it from `values`. backend: specifies which eager backend instantiate to. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.31.0) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). Returns: A new Series !ModuleType | Implementation | strr)r rr()rrrrr#s r new_seriesr's5F6@@G &tVUGLLL M MMr native_framerTchtd|}ttj||S)aConstruct a DataFrame from an object which supports the PyCapsule Interface. Arguments: native_frame: Object which implements `__arrow_c_stream__`. backend: specifies which eager backend instantiate to. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.31.0) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). Returns: A new DataFrame. r&r)r rr! from_arrow)r(rr#s rr*r*s1<6@@G dolGDDD E EErdataMapping[str, Any]r7#Mapping[str, DType] | Schema | NonecJttj|||S)asInstantiate DataFrame from dictionary. Indexes (if present, for pandas-like backends) are aligned following the [left-hand-rule](../concepts/pandas_index.md/). Notes: For pandas-like dataframes, conversion to schema is applied after dataframe creation. Arguments: data: Dictionary to create DataFrame from. schema: The DataFrame schema as Schema or dict of {name: type}. If not specified, the schema will be inferred by the native library. backend: specifies which eager backend instantiate to. Only necessary if inputs are not Narwhals Series. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.26.0) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). Returns: A new DataFrame. r)rr! from_dictr+r7rr#s rr/r/s$R dnT67CCC D DDrra3Mapping[str, DType] | Schema | Sequence[str] | Nonecjtd|}ttj|||S)aConstruct a DataFrame from a NumPy ndarray. Notes: Only row orientation is currently supported. For pandas-like dataframes, conversion to schema is applied after dataframe creation. Arguments: data: Two-dimensional data represented as a NumPy ndarray. schema: The DataFrame schema as Schema, dict of {name: type}, or a sequence of str. backend: specifies which eager backend instantiate to. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.31.0) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). Returns: A new DataFrame. r&r)r rr! from_numpyr0s rr3r30s4L6@@G dodFGDDD E EErsourcerc dtd|}ttj|fd|i|S)aJRead a CSV file into a DataFrame. Arguments: source: Path to a file. backend: The eager backend for DataFrame creation. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.27.2) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). kwargs: Extra keyword arguments which are passed to the native CSV reader. For example, you could use `nw.read_csv('file.csv', backend='pandas', engine='pyarrow')`. Returns: DataFrame. r&r)r rr!read_csvr4rr#rs rr6r6Zs:B6@@G dmFFFGFvFF G GGrc dtd|}ttj|fd|i|S)aLazily read from a CSV file. For the libraries that do not support lazy dataframes, the function reads a csv file eagerly and then converts the resulting dataframe to a lazyframe. Arguments: source: Path to a file. backend: The eager backend for DataFrame creation. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.31.0) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). kwargs: Extra keyword arguments which are passed to the native CSV reader. For example, you could use `nw.scan_csv('file.csv', backend=pd, engine='pyarrow')`. Returns: LazyFrame. r&r)r rr!scan_csvr7s rr9r9s:H6@@G dmFFFGFvFF G GGrc dtd|}ttj|fd|i|S)aYRead into a DataFrame from a parquet file. Arguments: source: Path to a file. backend: The eager backend for DataFrame creation. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.31.0) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). kwargs: Extra keyword arguments which are passed to the native parquet reader. For example, you could use `nw.read_parquet('file.parquet', backend=pd, engine='pyarrow')`. Returns: DataFrame. r&r)r rr! read_parquetr7s rr;r;s;B6@@G d'JJJ6JJ K KKrc dtd|}ttj|fd|i|S)aLazily read from a parquet file. For the libraries that do not support lazy dataframes, the function reads a parquet file eagerly and then converts the resulting dataframe to a lazyframe. Note: Spark like backends require a session object to be passed in `kwargs`. For instance: ```py import narwhals as nw from sqlframe.duckdb import DuckDBSession nw.scan_parquet(source, backend="sqlframe", session=DuckDBSession()) ``` Arguments: source: Path to a file. backend: The eager backend for DataFrame creation. `backend` can be specified in various ways - As `Implementation.` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN`, `CUDF`, `PYSPARK` or `SQLFRAME`. - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"`, `"cudf"`, `"pyspark"` or `"sqlframe"`. - Directly as a module `pandas`, `pyarrow`, `polars`, `modin`, `cudf`, `pyspark.sql` or `sqlframe`. native_namespace: The native library to use for DataFrame creation. *Deprecated* (v1.31.0) Please use `backend` instead. Note that `native_namespace` is still available (and won't emit a deprecation warning) if you use `narwhals.stable.v1`, see [perfect backwards compatibility policy](../backcompat.md/). kwargs: Extra keyword arguments which are passed to the native parquet reader. For example, you could use `nw.scan_parquet('file.parquet', backend=pd, engine='pyarrow')`. Returns: LazyFrame. r&r)r rr! scan_parquetr7s rr=r=s;d6@@G d'JJJ6JJ K KKr)Pr0r1r2r3r"r4r5r6r7r8r'r9r:r;rr<r=r>r?r@r#rArBr,r.rCrDrErFrGrHrIrJrKrrrrr)r rr/rrr*r/rVr3rr*rMrrrrrrrrrr rrrrrrr'rr6r;r9r=rr+rrrrNr )r;r<rrr=)r;rArrrB)r;rDrrrE)r;rHrrr')r;rJrrrK)rRrgrSrrrrg)rRrbrSrrrrb)rRrerSrrrre)rRrYrSrrrrY)rRr]r^rr[rr_rr\rr`rrrra)rRr]r^rr[rr_rr\rr`rrrra)rRrOr^rr[rr_rr\rr`rsrrrf)rRrir^rr[rr_rr\rr`rsrrri)rRrOr^rr[rr_rr\rr`rsrrrf)rRrir^rr[rr_rr\rr`rsrrri)rRrmr^rr[rr_rr\rr`rrrrn)rRrmr^rr[rr_rr\rr`rsrrrE)rRrPr^rr[rr_rr\rr`rsrrrs)rRrir^rr[rr_rr\rr`rsrrri)rRrOr^rr[rr_rr\rr`rsrrrf)rRrOr^rr[rr_rr\rr`rsrrrf)rRryr^rr[rr_rr\rr`rrrrz)rRrmr^rr[rr_rr\rr`rsrrrE)rRr[r^rr[rr_rr\rr`rsrrr})rRrPr^rr[rr_rr\rr`rsrrrs)rRrrrr[rr_rr\rr`rrrrf)rRr]rrr[rr_rr\rr`rrrra)rRrOrrr[rr_rr\rr`rsrrrf)rRrirrr[rr_rr\rr`rsrrri)rRrOrrr[rr_rr\rr`rsrrrf)rRrirrr[rr_rr\rr`rsrrri)rRrmrrr[rr_rr\rr`rrrrn)rRrmrrr[rr_rr\rr`rsrrrE)rRrPrrr[rr_rr\rr`rsrrrs)rRrirrr[rr_rr\rr`rsrrri)rRrOrrr[rr_rr\rr`rsrrrf)rRrOrrr[rr_rr\rr`rsrrrf)rRryrrr[rr_rr\rr`rrrrz)rRrmrrr[rr_rr\rr`rsrrrE)rRrPrrr[rr_rr\rr`rsrrrs)rRrrrr[rr_rr\rr`rrrr)rRrr^rrrr[rr_rr\rr`rrSrrrr)rrfr^rrrrO)rrBr^rrrrP)rrEr^rrrrm)rrr^rrrr)rrfrrrrrO)rrBrrrrrP)rrErrrrrm)rrrrrrr)rrr^rrrrrrr)rrr^rrrr[rr_rr\rr`rrrr)rrr')rrrrr')rrrrr')rr]rrrrr')rrrrr')rrrrr') rrrrYrrrrrrr')rrrrr ) rrrrrrrrr#r$rrrh)r(rTrrr#r$rrrc) r+r,r7r-rrr#r$rrrc) r+rar7r1rrr#r$rrrc) r4rrrr#r$rrrrrc) r4rrrr#r$rrrrrf) __future__r functoolsrtypingrrrr r r r r rwarningsrnarwhalsrrrrr!rnarwhals._typing_compatrrrrrrrrrrrrrr r!rr"rr#rnarwhals.dependenciesr$rr%rr'rHnarwhals.functionsr(r)r*r+narwhals.schemar,r:rr.r narwhals.stable.v1r/narwhals.stable.v1.dtypesr0r1r2r3r4r5r6r7r8r9r:r;r<r=r>r?r@rArBrCrDrErFrGrHrIrJrKnarwhals.translaterLrMrNnarwhals.typingrOrPtypesrQtyping_extensionsrRrSnarwhals._translaterTrUrVnarwhals.dtypesrWrXrYrZr[r\r]r^r_r`rarbrergrirkrlrmrrVrrrrrrrrrrrrrrrrrrrr r rr r'r*r/r3r6r9r;r=__all__rrrrPs""""""                      KKKKKKKKKKKK++++++RQQQQQQQ,,,,,,444444((((((QQQQQQQQQQQQ............%%%%%%<UTTTTTTTTT66666666      11111111222222GGGGGGGG%%%%%%                        -=>>>J-=>>>Jgi}555GS!!!A #A Agm<EEE S-S-S-S-S- N+S-S-S-lJ J J J J J'J J J Z3 3 3 3 3 Xk "3 3 3 lq q q q q 6q q q h!!!!!X!!! JJJ J JJJ J FFF F ((( ($ DDD D JJJ J JJJ J """ "  "%"% ::::: : 14"% ::::: : "%"%$$$$$ $ "%"%        14"%$$$$$ $ 14"%        "%03"% NNNNN N "%03  "%03"%88888 8 "%03"%         !$"%$$$$$ $  03"%$$$$$ $  !$03"% 88888 8  !$03   !$03"%$$$$$ $  !$03"%88888 8 "%"% $$$$$ $ 14"% ::::: : "%"%$$$$$ $ "%"%        14"%$$$$$ $ 14"%        "%03"% NNNNN N "%03  "%03"%88888 8 "%03"%        $'!$"%$$$$$ $ $'03"%$$$$$ $ $'!$03"% 88888 8 $'!$03  $'!$03"%88888 8 ',   $&+ $RRRRRRj KN  GJ  EH  @@@ @ RU  NQ  LO  FFF F $ ......d'+q $&+ $qqqqqqh     & & & & * * * * ( ( ( (      , , , , , ( ( ( ( ( ( ( ( ) ) ) )++++" ( ( ( ( 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 1 1 1 1 1 1 1 1& 633333493334444449d44422220T***##N 9=*. #N#N#N#N#N+*#NLT***9=*. FFFFF+*FB37(E9=*. (E(E(E(E(E(EVT***CG&F9=*. &F&F&F&F&F+*&FRT***9=*. !H!H!H!H!H+*!HHT***9=*. $H$H$H$H$H+*$HNT***9=*. !L!L!L!L!L+*!LHT***9=*. 2L2L2L2L2L+*2LjQ Q Q r