L iUddlmZddlZddlZddlmZmZmZddlm Z m Z ddl m Z m Z mZmZddlmZmZmZmZmZmZmZmZmZddlmZmZmZmZddlm Z dd l!m"Z"dd l#m$Z$m%Z%e rWdd l&m'Z'dd l(m)Z)m*Z*dd l+m,Z,m-Z-m.Z.ddl/m0Z0ddl1m2Z2m3Z3m4Z4ddl5m6Z6m7Z7ddl8m9Z9ddl:m;Z;ddlZ>m?Z?m@Z@mAZAmBZBmCZCmDZDdZEdeFd<dddIdZG dJ dKdZH dJ dKdZIed dJddd dLdZJ dMd ZK dJ dNd!ZL dJ dOd"ZMdPd#ZN dQd$ZOdRd%ZPdRd&ZQdSd'ZR dTd(ZS dUd)ZT dTd*ZU dUd+ZVdVd,ZWdVd-ZXdWd.ZYdXd/ZZdXd0Z[dYd1Z\dYd2Z]dYd3Z^dYd4Z_dYd5Z`dZd6Zad[d7Zbd[d8Zcd[d9ZdGd:d;ZeGd<d=e"Zfd\d>Zgd]d?ZhdJd^d@Zid]dAZjd[dBZkdCdDdE d_dFZl d`dGZmdadHZny)b) annotationsN)IterableMappingSequence) TYPE_CHECKINGAny)ExprKindExprNodeis_expr is_series) ImplementationVersiondeprecate_native_namespaceflattenis_eager_allowedis_sequence_but_not_strnormalize_pathsupports_arrow_c_streamvalidate_laziness)is_narwhals_seriesis_numpy_arrayis_numpy_array_2dis_pyarrow_table)InvalidOperationError)Expr) from_native to_native) ModuleType) TypeAliasTypeIs)NativeDataFrameNativeLazyFrame NativeSeries)IntoArrowTable)Backend EagerAllowed IntoBackend) DataFrame LazyFrame)DType)Series) ConcatMethod FileSourceFrameT IntoDTypeIntoExpr IntoSchemaNonNestedLiteral_2DArray!IntoSchema | Sequence[str] | Noner _IntoSchemaverticalhowcVddlm}|s d}t|t|}t ||dvr d}t ||d}||r|dk(r d}t ||j}|j|j|Dcgc]}|jc}|Scc}w) uConcatenate multiple DataFrames, LazyFrames into a single entity. Arguments: items: DataFrames, LazyFrames to concatenate. how: concatenating strategy - vertical: Concatenate vertically. Column names must match. - horizontal: Concatenate horizontally. If lengths don't match, then missing rows are filled with null values. This is only supported when all inputs are (eager) DataFrames. - diagonal: Finds a union between the column schemas and fills missing column values with null. Raises: TypeError: The items to concatenate should either all be eager, or all lazy Examples: Let's take an example of vertical concatenation: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw Let's look at one case a for vertical concatenation (pandas backed): >>> df_pd_1 = nw.from_native(pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})) >>> df_pd_2 = nw.from_native(pd.DataFrame({"a": [5, 2], "b": [1, 4]})) >>> nw.concat([df_pd_1, df_pd_2], how="vertical") ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 1 4 | | 1 2 5 | | 2 3 6 | | 0 5 1 | | 1 2 4 | └──────────────────┘ Let's look at one case a for horizontal concatenation (polars backed): >>> df_pl_1 = nw.from_native(pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})) >>> df_pl_2 = nw.from_native(pl.DataFrame({"c": [5, 2], "d": [1, 4]})) >>> nw.concat([df_pl_1, df_pl_2], how="horizontal") ┌───────────────────────────┐ | Narwhals DataFrame | |---------------------------| |shape: (3, 4) | |┌─────┬─────┬──────┬──────┐| |│ a ┆ b ┆ c ┆ d │| |│ --- ┆ --- ┆ --- ┆ --- │| |│ i64 ┆ i64 ┆ i64 ┆ i64 │| |╞═════╪═════╪══════╪══════╡| |│ 1 ┆ 4 ┆ 5 ┆ 1 │| |│ 2 ┆ 5 ┆ 2 ┆ 4 │| |│ 3 ┆ 6 ┆ null ┆ null │| |└─────┴─────┴──────┴──────┘| └───────────────────────────┘ Let's look at one case a for diagonal concatenation (pyarrow backed): >>> df_pa_1 = nw.from_native(pa.table({"a": [1, 2], "b": [3.5, 4.5]})) >>> df_pa_2 = nw.from_native(pa.table({"a": [3, 4], "z": ["x", "y"]})) >>> nw.concat([df_pa_1, df_pa_2], how="diagonal") ┌──────────────────────────┐ | Narwhals DataFrame | |--------------------------| |pyarrow.Table | |a: int64 | |b: double | |z: string | |---- | |a: [[1,2],[3,4]] | |b: [[3.5,4.5],[null,null]]| |z: [[null,null],["x","y"]]| └──────────────────────────┘ r)is_narwhals_lazyframezNo items to concatenate.>diagonalr6 horizontalzDOnly vertical, horizontal and diagonal concatenations are supported.r<zdHorizontal concatenation is not supported for LazyFrames. Hint: you may want to use `join` instead.r7) narwhals.dependenciesr: ValueErrortuplerNotImplementedErrorr__narwhals_namespace___with_compliantconcat_compliant_frame)itemsr8r:msg first_itemplxdfs X/mnt/ssd/data/python-lab/Trading/venv/lib/python3.12/site-packages/narwhals/functions.pyrCrC7s^< (o %LEe 88T!#&&qJZ(SL-@ 8 $C((  + + -C  % % %8BB''8c B 8sB& c t||||S)u Instantiate 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`. Examples: >>> import pandas as pd >>> import narwhals as nw >>> >>> values = [4, 1, 2, 3] >>> nw.new_series(name="a", values=values, dtype=nw.Int32, backend=pd) ┌─────────────────────┐ | Narwhals Series | |---------------------| |0 4 | |1 1 | |2 2 | |3 3 | |Name: a, dtype: int32| └─────────────────────┘ backend)_new_series_impl)namevaluesdtyperMs rJ new_seriesrRsN D&% AActj|}t|rbtjj j|j }|jj||||}|jS|tjur@|j} |j|||}t|dj|S|d|d} t!| #t$r} d} t| | d} ~ wwxYw)N)rOcontextrQT) series_onlyzDUnknown namespace is expected to implement `new_series` constructor.z support in Narwhals is lazy-only, but `new_series` is an eager-only function. Hint: you may want to use an eager backend and then call `.lazy`, e.g.: nw.new_series('a', [1,2,3], backend='pyarrow').to_frame().lazy(''))r from_backendrrMAIN namespace compliant_series from_iterable to_narwhalsUNKNOWNto_native_namespacerRraliasAttributeErrorr>) rOrPrQrMimplementationnsseries_native_namespace native_serieserFs rJrNrNs $009N' \\ # # 0 0 @ J J))&tRu)U!!##///*>>@ -*;*F*Ffe+M}$?EEdK K  OO]N^^` b S/ -XC %1 , -s&.C(( D1C??Dz1.26.0) warn_version)rMnative_namespacec|t|\}}|rJ|rHt|jj|jx}rd|}t |t j |}t|r_tjjj |j}|jj|||jS|t jur1|j!} |j||} t%| dS|d|d }t'|#t"$r} d}t#|| d} ~ wwxYw) u\Instantiate 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. If any `dtype` is `None`, the data type for that column 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: deprecated, same as `backend`. Examples: >>> import pandas as pd >>> import narwhals as nw >>> data = {"c": [5, 2], "d": [1, 4]} >>> nw.from_dict(data, backend="pandas") ┌──────────────────┐ |Narwhals DataFrame| |------------------| | c d | | 0 5 1 | | 1 2 4 | └──────────────────┘ NzIKeys in `schema` and `data` are expected to match, found unmatched keys: )schemarUrlz@Unknown namespace is expected to implement `from_dict` function.T eager_onlyz support in Narwhals is lazy-only, but `from_dict` is an eager-only function. Hint: you may want to use an eager backend and then call `.lazy`, e.g.: nw.from_dict({'a': [1, 2]}, backend='pyarrow').lazy('rW)_from_dict_no_backendsetkeyssymmetric_differencerr rXrrrYrZr[ _dataframe from_dictr^r_r`rbrr>) datarlrMrjdiffrFrcrdrf native_framerhs rJrurusW^-d3 g $C $6$K$KDIIK$XXDXYZ^Y_`#C((#009N' \\ # # 0 0 @ J J}}&&tFB&GSSUU///*>>@ -->,G,GV-H-L ` 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`. Tip: If you expect non-uniform keys in `data`, consider passing `schema` for more consistent results, as **inference varies between backends**: - pandas uses all rows - polars uses the first 100 rows - pyarrow uses only the first row Examples: >>> import polars as pl >>> import narwhals as nw >>> data = [ ... {"item": "apple", "weight": 80, "price": 0.60}, ... {"item": "egg", "weight": 55, "price": 0.40}, ... ] >>> nw.DataFrame.from_dicts(data, backend="polars") ┌──────────────────────────┐ | Narwhals DataFrame | |--------------------------| |shape: (2, 3) | |┌───────┬────────┬───────┐| |│ item ┆ weight ┆ price │| |│ --- ┆ --- ┆ --- │| |│ str ┆ i64 ┆ f64 │| |╞═══════╪════════╪═══════╡| |│ apple ┆ 80 ┆ 0.6 │| |│ egg ┆ 55 ┆ 0.4 │| |└───────┴────────┴───────┘| └──────────────────────────┘ rL)rrY dataframe from_dicts)rvrlrMs rJrr?s'r << ! ! , ,T67 , KKrScLt|s d}t|t|sdt|d}t |t j |}t|rStjjj |j}|j||jS|t jur1|j} |j||}t#|dS|d |d }t|#t $r}d}t!||d}~wwxYw) uConstruct 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`. Examples: >>> import numpy as np >>> import pyarrow as pa >>> import narwhals as nw >>> >>> arr = np.array([[5, 2, 1], [1, 4, 3]]) >>> schema = {"c": nw.Int16(), "d": nw.Float32(), "e": nw.Int8()} >>> nw.from_numpy(arr, schema=schema, backend="pyarrow") ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | c: int16 | | d: float | | e: int8 | | ---- | | c: [[5,1]] | | d: [[2,4]] | | e: [[1,3]] | └──────────────────┘ z)`from_numpy` only accepts 2D numpy arrayszW`schema` is expected to be one of the following types: IntoSchema | Sequence[str]. Got .rmzAUnknown namespace is expected to implement `from_numpy` function.NTrnz support in Narwhals is lazy-only, but `from_numpy` is an eager-only function. Hint: you may want to use an eager backend and then call `.lazy`, e.g.: nw.from_numpy(arr, backend='pyarrow').lazy('rW)rr>_is_into_schematyper|r rXrrrYrZr[ from_numpyr^r_r`rbr) rvrlrMrFrcrdrfrxrhs rJrr{s8^ T "9o 6 " <. # n#009N' \\ # # 0 0 @ J J}}T6*6688///*>>@ -->,H,HV-I-L ` 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`. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> >>> df_native = pd.DataFrame({"a": [1, 2], "b": [4.2, 5.1]}) >>> nw.from_arrow(df_native, backend="polars") ┌──────────────────┐ |Narwhals DataFrame| |------------------| | shape: (2, 2) | | ┌─────┬─────┐ | | │ a ┆ b │ | | │ --- ┆ --- │ | | │ i64 ┆ f64 │ | | ╞═════╪═════╡ | | │ 1 ┆ 4.2 │ | | │ 2 ┆ 5.1 │ | | └─────┴─────┘ | └──────────────────┘ zGiven object of type z% does not support PyCapsule interface)rUzuUnknown namespace is expected to implement `DataFrame` class which accepts object which supports PyCapsule Interface.NTrnz support in Narwhals is lazy-only, but `from_arrow` is an eager-only function. Hint: you may want to use an eager backend and then call `.lazy`, e.g.: nw.from_arrow(df, backend='pyarrow').lazy('rW)rrrr|r rXrrrYrZr[rt from_arrowr^r_r`r(rbrr>)rxrMrFrcrdrfnativerhs rJrrs#J $L 15El5S%d<&8%99^_n#009N' \\ # # 0 0 @ J J}}'' b'AMMOO///*>>@ -'8&A&A,&OF6d33  ::H9I M S/ -JC %1 , -sD D DDctjjdd}d|fdtjfdt jff}t |S)zSystem information. Returns system and Python version information Copied from sklearn Returns: Dictionary with system info.   python executablemachine)sysversionreplacerplatformdict)rblobs rJ _get_sys_inforsT[[ s +F 6 s~~& H%%'( D :rSc` ddlm}d}tj}ddh t fdg||D}t j |d}|D]W}|jj|j}}||vr|||<3|D] }||r |j|s|||<WY|S)aOverview of the installed version of main dependencies. This function does not import the modules to collect the version numbers but instead relies on standard Python package metadata. Returns version information on relevant Python libraries This function and show_versions were copied from sklearn and adapted Returns: Mapping from dependency to version. r) distributions)narwhalsnumpyPYSPARK_CONNECTr_c3HK|]}|vs|jywN)lower).0rOexcludes rJ z!_get_deps_info..9s#$gBU s "") importlib.metadatarr _member_names_r?rfromkeysrOrr startswith) r extra_names member_names target_namesresultdist dist_name dist_versiontargetrs @rJ_get_deps_infor's1'K!00L ),G!>;!>!>L]]< ,F "&))//"3T\\<   ,F9 & f~)*>*>v*F%1F6N   MrSct}t}td|jD]\}}t|dd|td|jD]\}}t|dd|y)zPrint useful debugging information. Examples: >>> from narwhals import show_versions >>> show_versions() # doctest: +SKIP z System:z>10z: z Python dependencies:z>13N)rrprintrE)sys_info deps_infokstats rJ show_versionsrLsH I +>>#"4 3r$ !" "#??$"4 3r$ !"rSc tj|}|j}|tjtjtj tj hvr|jt|fi|}n|tjurddl m }|j|fi|}n|tjtjtjtjtj tj"hvrd|d|d|d}t%| |jd d|i|}t)|d S#t&$r}d}t'||d }~wwxYw) uPRead 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`. 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')`. Examples: >>> import narwhals as nw >>> nw.read_csv("file.csv", backend="pandas") # doctest:+SKIP ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 1 4 | | 1 2 5 | └──────────────────┘ rcsvExpected eager backend, found z . Hint: use nw.scan_csv(source= , backend=)sourcez?Unknown namespace is expected to implement `read_csv` function.NTrn)r rXr`POLARSPANDASMODINCUDFread_csvrPYARROWpyarrowrPYSPARKDASKDUCKDBIBISSQLFRAMErr>rbr) rrMkwargsimplrjrxrrFrhs rJrr_sc:  & &w /D//1   1'001GR6R '' '#s||F5f5 &&  -TF3,,28:gYa I o -5+44MFMfML | 55 -SC %1 , -s%E E"EE"c tj|}|j}t|}|tjur|j |fi|}nW|tj tjtjtjtjtjhvr|j|fi|}n|tjurddlm}|j|fi|}n|j!r|j#ddx} d}t%||j&j)d} |tj*ur$|j-dkr| j/|n | j0d i|j/|}n |j d d|i|}t5|j7S#t2$r} d }t3|| d} ~ wwxYw) ulLazily 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`. 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')`. Examples: >>> import duckdb >>> import narwhals as nw >>> >>> nw.scan_csv("file.csv", backend="duckdb").to_native() # doctest:+SKIP ┌─────────┬───────┐ │ a │ b │ │ varchar │ int32 │ ├─────────┼───────┤ │ x │ 1 │ │ y │ 2 │ │ z │ 3 │ └─────────┴───────┘ rrsessionNFSpark like backends require a session object to be passed in `kwargs`.rrrz?Unknown namespace is expected to implement `scan_csv` function.r)r rXr`rrscan_csvrrrrrrrrrr is_spark_likepopr>readformatr_backend_versionloadoptionsrbrlazy) rrMrrcrjrxrrrF csv_readerrhs rJrrsF$009N%99; F #F...0'00B6B   1'00B6B >11 1#s||F5f5  % % 'zz)T2 2G ;ZCS/ !\\((/ ."9"99"335 B OOF # $##-f-226:  -5+44MFMfML | $ ) ) ++ -SC %1 , -G G$GG$c tj|}|j}|tjtjtj tj hvrt|}|j|fi|}n|tjurddl m }|j|fi|}n|tjtjtjtj tj"tj$hvrd|d|d|d}t'| |jd d|i|}t+|d S#t($r}d}t)||d}~wwxYw) uRead 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`. 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')`. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> >>> nw.read_parquet("file.parquet", backend="pyarrow") # doctest:+SKIP ┌──────────────────┐ |Narwhals DataFrame| |------------------| |pyarrow.Table | |a: int64 | |c: double | |---- | |a: [[1,2]] | |c: [[0.2,0.1]] | └──────────────────┘ rNrz$. Hint: use nw.scan_parquet(source=rrrzCUnknown namespace is expected to implement `read_parquet` function.Trnr)r rXr`rrrrr read_parquetrpyarrow.parquetparquet read_tablerrrrrrr>rbr) rrMrrrjrxpqrFrhs rJrrsiD  & &w /D//1    '4'44VFvF '' '$$r}}V6v6 &&  -TF3006xz'! M o -9+88QQ&QL | 55 -WC %1 , -s'E E$EE$c tj|}|j}t|}|tjur|j |fi|}nW|tj tjtjtjtjtjhvr|j|fi|}n|tjurddlm}|j |fi|}n|j#r|j%ddx} d}t'||j(j+d} |tj,ur$|j/dkr| j1|n | j2d i|j1|}n |j d d|i|}t7|j9S#t4$r} d}t5|| d} ~ wwxYw) u Lazily 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`. 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')`. Examples: >>> import dask.dataframe as dd >>> from sqlframe.duckdb import DuckDBSession >>> import narwhals as nw >>> >>> nw.scan_parquet("file.parquet", backend="dask").collect() # doctest:+SKIP ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 1 4 | | 1 2 5 | └──────────────────┘ >>> nw.scan_parquet( ... "file.parquet", backend="sqlframe", session=DuckDBSession() ... ).collect() # doctest:+SKIP ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | a: int64 | | b: int64 | | ---- | | a: [[1,2]] | | b: [[4,5]] | └──────────────────┘ rNrrrrrzCUnknown namespace is expected to implement `scan_parquet` function.r)r rXr`rr scan_parquetrrrrrrrrrrrrrr>rrrrrrrbrr) rrMrrcrjrxrrrF pq_readerrhs rJrr9s|$009N%99; F #F...4'44VFvF   5'44VFvF >11 1$$r}}V6v6  % % 'zz)T2 2G ;ZCS/ !LL'' 2 ."9"99"335 B NN6 " #"",V,11&9  -9+88QQ&QL | $ ) ) ++ -WC %1 , -rcbt|}tttjd|S)uCreates an expression that references one or more columns by their name(s). Arguments: names: Name(s) of the columns to use. Examples: >>> import polars as pl >>> import narwhals as nw >>> >>> df_native = pl.DataFrame({"a": [1, 2], "b": [3, 4], "c": ["x", "z"]}) >>> nw.from_native(df_native).select(nw.col("a", "b") * nw.col("b")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | shape: (2, 2) | | ┌─────┬─────┐ | | │ a ┆ b │ | | │ --- ┆ --- │ | | │ i64 ┆ i64 │ | | ╞═════╪═════╡ | | │ 3 ┆ 9 │ | | │ 8 ┆ 16 │ | | └─────┴─────┘ | └──────────────────┘ colnames)rrr r COL)r flat_namess rJrrs%4J uJ? @@rSc ptttjdt t |S)u}Creates an expression that excludes columns by their name(s). Arguments: names: Name(s) of the columns to exclude. Examples: >>> import polars as pl >>> import narwhals as nw >>> >>> df_native = pl.DataFrame({"a": [1, 2], "b": [3, 4], "c": ["x", "z"]}) >>> nw.from_native(df_native).select(nw.exclude("c", "a")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | shape: (2, 1) | | ┌─────┐ | | │ b │ | | │ --- │ | | │ i64 │ | | ╞═════╡ | | │ 3 │ | | │ 4 │ | | └─────┘ | └──────────────────┘ rr)rr r EXCLUDE frozensetrrs rJrrs'4 ))9Igen>> import pyarrow as pa >>> import narwhals as nw >>> >>> df_native = pa.table({"a": [1, 2], "b": [3, 4], "c": [0.123, 3.14]}) >>> nw.from_native(df_native).select(nw.nth(0, 2) * 2) ┌──────────────────┐ |Narwhals DataFrame| |------------------| |pyarrow.Table | |a: int64 | |c: double | |---- | |a: [[2,4]] | |c: [[0.246,6.28]] | └──────────────────┘ nth)indices)rrr r NTH)r flat_indicess rJrrs&67#L ulC DDrScHtttjdS)u3Instantiate an expression representing all columns. Examples: >>> import pandas as pd >>> import narwhals as nw >>> >>> df_native = pd.DataFrame({"a": [1, 2], "b": [3.14, 0.123]}) >>> nw.from_native(df_native).select(nw.all() * 2) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 2 6.280 | | 1 4 0.246 | └──────────────────┘ all)rr r ALLrrSrJall_rs" u- ..rScHtttjdS)uReturn the number of rows. Examples: >>> import polars as pl >>> import narwhals as nw >>> >>> df_native = pl.DataFrame({"a": [1, 2], "b": [5, None]}) >>> nw.from_native(df_native).select(nw.len()) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | shape: (1, 1) | | ┌─────┐ | | │ len │ | | │ --- │ | | │ u32 │ | | ╞═════╡ | | │ 2 │ | | └─────┘ | └──────────────────┘ len)rr r AGGREGATIONrrSrJlen_rs, --u5 66rSc.t|jS)uSum all values. Note: Syntactic sugar for ``nw.col(columns).sum()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Examples: >>> import pandas as pd >>> import narwhals as nw >>> >>> df_native = pd.DataFrame({"a": [1, 2], "b": [-1.4, 6.2]}) >>> nw.from_native(df_native).select(nw.sum("a", "b")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 3 4.8 | └──────────────────┘ )rsumcolumnss rJrr,, =   rSc.t|jS)usGet the mean value. Note: Syntactic sugar for ``nw.col(columns).mean()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> >>> df_native = pa.table({"a": [1, 8, 3], "b": [3.14, 6.28, 42.1]}) >>> nw.from_native(df_native).select(nw.mean("a", "b")) ┌─────────────────────────┐ | Narwhals DataFrame | |-------------------------| |pyarrow.Table | |a: double | |b: double | |---- | |a: [[4]] | |b: [[17.173333333333336]]| └─────────────────────────┘ )rmeanrs rJr r Es4 =   rSc.t|jS)uGet 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 Examples: >>> import polars as pl >>> import narwhals as nw >>> >>> df_native = pl.DataFrame({"a": [4, 5, 2]}) >>> nw.from_native(df_native).select(nw.median("a")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | shape: (1, 1) | | ┌─────┐ | | │ a │ | | │ --- │ | | │ f64 │ | | ╞═════╡ | | │ 4.0 │ | | └─────┘ | └──────────────────┘ )rmedianrs rJr r bs< =   !!rSc.t|jS)uReturn the minimum value. Note: Syntactic sugar for ``nw.col(columns).min()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> >>> df_native = pa.table({"a": [1, 2], "b": [5, 10]}) >>> nw.from_native(df_native).select(nw.min("a", "b")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | a: int64 | | b: int64 | | ---- | | a: [[1]] | | b: [[5]] | └──────────────────┘ )rminrs rJr r s4 =   rSc.t|jS)uReturn the maximum value. Note: Syntactic sugar for ``nw.col(columns).max()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Examples: >>> import pandas as pd >>> import narwhals as nw >>> >>> df_native = pd.DataFrame({"a": [1, 2], "b": [5, 10]}) >>> nw.from_native(df_native).select(nw.max("a", "b")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 2 10 | └──────────────────┘ )rmaxrs rJrrrrSc~|sd|d}t|tttj|g|i|ddiS)Nz+At least one expression must be passed to ``allow_multi_outputT)r>rr r ELEMENTWISE)rOexprsrrFs rJ_expr_with_horizontal_oprsJ ;D6Co %%tWeWvWRVW rSc,tdgt|S)uSum 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. Examples: >>> import polars as pl >>> import narwhals as nw >>> >>> df_native = pl.DataFrame({"a": [1, 2, 3], "b": [5, 10, None]}) >>> nw.from_native(df_native).with_columns(sum=nw.sum_horizontal("a", "b")) ┌────────────────────┐ | Narwhals DataFrame | |--------------------| |shape: (3, 3) | |┌─────┬──────┬─────┐| |│ a ┆ b ┆ sum │| |│ --- ┆ --- ┆ --- │| |│ i64 ┆ i64 ┆ i64 │| |╞═════╪══════╪═════╡| |│ 1 ┆ 5 ┆ 6 │| |│ 2 ┆ 10 ┆ 12 │| |│ 3 ┆ null ┆ 3 │| |└─────┴──────┴─────┘| └────────────────────┘ sum_horizontalrrrs rJrr> $$4 Fwu~ FFrSc,tdgt|S)uGet 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. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> >>> df_native = pa.table({"a": [1, 8, 3], "b": [4, 5, None]}) >>> nw.from_native(df_native).with_columns(h_min=nw.min_horizontal("a", "b")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | a: int64 | | b: int64 | | h_min: int64 | | ---- | | a: [[1,8,3]] | | b: [[4,5,null]] | | h_min: [[1,5,3]] | └──────────────────┘ min_horizontalrrs rJrrs: $$4 Fwu~ FFrSc,tdgt|S)uGet 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. Examples: >>> import polars as pl >>> import narwhals as nw >>> >>> df_native = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, None]}) >>> nw.from_native(df_native).with_columns(h_max=nw.max_horizontal("a", "b")) ┌──────────────────────┐ | Narwhals DataFrame | |----------------------| |shape: (3, 3) | |┌─────┬──────┬───────┐| |│ a ┆ b ┆ h_max │| |│ --- ┆ --- ┆ --- │| |│ i64 ┆ i64 ┆ i64 │| |╞═════╪══════╪═══════╡| |│ 1 ┆ 4 ┆ 4 │| |│ 8 ┆ 5 ┆ 8 │| |│ 3 ┆ null ┆ 3 │| |└─────┴──────┴───────┘| └──────────────────────┘ max_horizontalrrs rJrrrrSceZdZddZddZy)Whenc6tt|ddi|_y)N ignore_nullsF)all_horizontalr _predicate)self predicatess rJ__init__z When.__init__'s('**=RERrSc dtttjd|j|dS)N when_thenF)r)Thenr r rr$)r%rs rJthenz When.then*s0 $$#(    rSN)r&IntoExpr | Iterable[IntoExpr]returnNone)rIntoExpr | NonNestedLiteralr-r*)__name__ __module__ __qualname__r'r+rrSrJr r &s S  rSr ceZdZddZy)r*c|jd}tttjdg|j |S)Nrr))_nodesrr r rr)r%rnodes rJ otherwisezThen.otherwise7s5{{1~HX11;SSUSTTrSN)rr/r-r)r0r1r2r7rrSrJr*r*6sUrSr*ct|S)uStart 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. Examples: >>> import pandas as pd >>> import narwhals as nw >>> >>> data = {"a": [1, 2, 3], "b": [5, 10, 15]} >>> df_native = pd.DataFrame(data) >>> nw.from_native(df_native).with_columns( ... nw.when(nw.col("a") < 3).then(5).otherwise(6).alias("a_when") ... ) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b a_when | | 0 1 5 5 | | 1 2 10 5 | | 2 3 15 6 | └──────────────────┘ )r )r&s rJwhenr9<sN  rSc2tdgt|d|iS)uCompute the bitwise AND horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. ignore_nulls: Whether to ignore nulls: - If `True`, null values are ignored. If there are no elements, the result is `True`. - If `False`, Kleene logic is followed. Note that this is not allowed for pandas with classical NumPy dtypes when null values are present. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> >>> data = { ... "a": [False, False, True, True, False, None], ... "b": [False, True, True, None, None, None], ... } >>> df_native = pa.table(data) >>> nw.from_native(df_native).select( ... "a", "b", all=nw.all_horizontal("a", "b", ignore_nulls=False) ... ) ┌─────────────────────────────────────────┐ | Narwhals DataFrame | |-----------------------------------------| |pyarrow.Table | |a: bool | |b: bool | |all: bool | |---- | |a: [[false,false,true,true,false,null]] | |b: [[false,true,true,null,null,null]] | |all: [[false,false,true,null,false,null]]| └─────────────────────────────────────────┘ r#r"rr"rs rJr#r#fs)L $ "5> 8D rSct|r d}t|t|ttfrd|}t |t ttjd||S)uReturn 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. Examples: >>> import pandas as pd >>> import narwhals as nw >>> >>> df_native = pd.DataFrame({"a": [1, 2]}) >>> nw.from_native(df_native).with_columns(nw.lit(3)) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a literal | | 0 1 3 | | 1 2 3 | └──────────────────┘ zvnumpy arrays are not supported as literal values. Consider using `with_columns` to create a new column from the array.z,Nested datatypes are not supported yet. Got lit)rrQ) rr>rlistr?r@rr r LITERAL)rrQrFs rJr=r=sd,e S o%$'>> import polars as pl >>> import narwhals as nw >>> >>> data = { ... "a": [False, False, True, True, False, None], ... "b": [False, True, True, None, None, None], ... } >>> df_native = pl.DataFrame(data) >>> nw.from_native(df_native).select( ... "a", "b", any=nw.any_horizontal("a", "b", ignore_nulls=False) ... ) ┌─────────────────────────┐ | Narwhals DataFrame | |-------------------------| |shape: (6, 3) | |┌───────┬───────┬───────┐| |│ a ┆ b ┆ any │| |│ --- ┆ --- ┆ --- │| |│ bool ┆ bool ┆ bool │| |╞═══════╪═══════╪═══════╡| |│ false ┆ false ┆ false │| |│ false ┆ true ┆ true │| |│ true ┆ true ┆ true │| |│ true ┆ null ┆ true │| |│ false ┆ null ┆ null │| |│ null ┆ null ┆ null │| |└───────┴───────┴───────┘| └─────────────────────────┘ any_horizontalr"rr;s rJrArAs)V $ "5> 8D rSc,tdgt|S)uCompute the mean of all values horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> >>> data = {"a": [1, 8, 3], "b": [4, 5, None], "c": ["x", "y", "z"]} >>> df_native = pa.table(data) We define a dataframe-agnostic function that computes the horizontal mean of "a" and "b" columns: >>> nw.from_native(df_native).select(nw.mean_horizontal("a", "b")) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | pyarrow.Table | | a: double | | ---- | | a: [[2.5,6.5,3]] | └──────────────────┘ mean_horizontalrrs rJrCrCs6 $$5 G GGrSrF separatorr"cTtgt|g|}tdg|||dS)uHHorizontally 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. Examples: >>> import pandas as pd >>> import narwhals as nw >>> >>> data = { ... "a": [1, 2, 3], ... "b": ["dogs", "cats", None], ... "c": ["play", "swim", "walk"], ... } >>> df_native = pd.DataFrame(data) >>> ( ... nw.from_native(df_native).select( ... nw.concat_str( ... [nw.col("a") * 2, nw.col("b"), nw.col("c")], separator=" " ... ).alias("full_sentence") ... ) ... ) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | full_sentence | | 0 2 dogs play | | 1 4 cats swim | | 2 None | └──────────────────┘ concat_strrD)rr)rrEr" more_exprs flat_exprss rJrGrGsCZ97E7+9j9:J # ! -6\ rScTtgt|g|}|Dcgc]*}t|tst|s t |s|,}}|r-dtddj d|D}t |tttjdg|ddiScc}w)uFolds the columns from left to right, keeping the first non-null value. Arguments: exprs: Columns to coalesce, must be a str, nw.Expr, or nw.Series where strings are parsed as column names and both nw.Expr/nw.Series are passed through as-is. Scalar values must be wrapped in `nw.lit`. *more_exprs: Additional columns to coalesce, specified as positional arguments. Raises: TypeError: If any of the inputs are not a str, nw.Expr, or nw.Series. Examples: >>> import polars as pl >>> import narwhals as nw >>> data = [ ... (1, 5, None), ... (None, 6, None), ... (None, None, 9), ... (4, 8, 10), ... (None, None, None), ... ] >>> df = pl.DataFrame(data, schema=["a", "b", "c"], orient="row") >>> nw.from_native(df).select(nw.coalesce("a", "b", "c", nw.lit(-1))) ┌──────────────────┐ |Narwhals DataFrame| |------------------| | shape: (5, 1) | | ┌─────┐ | | │ a │ | | │ --- │ | | │ i64 │ | | ╞═════╡ | | │ 1 │ | | │ 6 │ | | │ 9 │ | | │ 4 │ | | │ -1 │ | | └─────┘ | └──────────────────┘ z,All arguments to `coalesce` must be of type zJ, Expr, or Series. Got the following invalid arguments (type, value): z, c3HK|]}tt||fywr)reprr)rrhs rJrzcoalesce..msEatT!WaL1Es "coalescerT) rrstrr r joinr|rr r r)rrHrIexpr non_exprsrFs rJrMrM6sX97E7+9j9:J 4%)D/ I :3'BYYE9EEF H n %%zXJXSWX s/B%c|jdx}t|k7rd|dt|d}t|g}t|}t |j dD]M\}}|dkDr|j t|t|dkDs4|j t|Ot|dS)uHFormat expressions as a string. Arguments: f_string: A string that with placeholders. args: Expression(s) that fill the placeholders. Examples: >>> import duckdb >>> import narwhals as nw >>> rel = duckdb.sql("select * from values ('a', 1), ('b', 2), ('c', 3) df(a, b)") >>> df = nw.from_native(rel) >>> df.with_columns(formatted=nw.format("foo_{}_bar_{}", nw.col("a"), "b")) ┌─────────────────────────────────┐ | Narwhals LazyFrame | |---------------------------------| |┌─────────┬───────┬─────────────┐| |│ a │ b │ formatted │| |│ varchar │ int32 │ varchar │| |├─────────┼───────┼─────────────┤| |│ a │ 1 │ foo_a_bar_1 │| |│ b │ 2 │ foo_b_bar_2 │| |│ c │ 3 │ foo_c_bar_3 │| |└─────────┴───────┴─────────────┘| └─────────────────────────────────┘ z{}zFnumber of placeholders should equal the number of arguments. Expected z arguments, got rrr)rE) countrr>iter enumeratesplitappendnextr=rG)f_stringargsn_placeholdersrFritiss rJrrvs4#....3t9<VWeVffvwz{xAwBBCDo E dB(.../!1 q5 LLb " q6A: LLQ ! er **rS)rEzIterable[FrameT]r8r,r-r.r) rOrNrPrrQIntoDType | NonerMIntoBackend[EagerAllowed]r-z Series[Any]) rvzMapping[str, Any]rl.IntoSchema | Mapping[str, DType | None] | NonerMz IntoBackend[EagerAllowed] | NonerjzModuleType | Noner-DataFrame[Any])rvzMapping[str, Series[Any] | Any]r-z/tuple[dict[str, Series[Any] | Any], ModuleType])rvzSequence[Mapping[str, Any]]rlrarMr`r-rb)rvr3rlr4rMr`r-rb)rrr-zTypeIs[_IntoSchema])rxr$rMr`r-rb)r-zdict[str, str])r-r.)rr-rMr`rrr-rb)rr-rMzIntoBackend[Backend]rrr-zLazyFrame[Any])rzstr | Iterable[str]r-r)rzint | Sequence[int]r-r)r-r)rrNr-r)rOrNrr0rrr-r)rr,r-r)r&r,r-r )rr,r"boolr-r)rr2rQr_r-r) rr,rHr0rErNr"rcr-r)rr,rHr/r-r)rYrNrZr0r-r)o __future__rrrcollections.abcrrrtypingrrnarwhals._expression_parsingr r r r narwhals._utilsr rrrrrrrrr=rrrrnarwhals.exceptionsr narwhals.exprrnarwhals.translaterrtypesrtyping_extensionsrr narwhals._nativer!r"r#narwhals._translater$narwhals._typingr%r&r'narwhals.dataframer(r)narwhals.dtypesr*narwhals.seriesr+narwhals.typingr,r-r.r/r0r1r2r3r5__annotations__rCrRrNrurprrrrrrrrrrrrrrrrrr r r rrrrrr r*r9r#r=rArCrGrMrrrSrJrvs" 77%OO    65 3OO2CC7%&   AK@BH15*. H H :H. H ( H  H3HV " ) "4 " >B9L %9L :9L' 9L  9L|15N N -N' N  Nb; ;.G;;|*"J"&@6 @6$=@6IL@6@6FK, K,$8K,DGK,K,\F6 F6$=F6ILF6F6Rg, g,$8g,DGg,g,TA<X:E@/*722 :"B:2GDG@GD   U4U 'T(V!MH-`HB 0 (000 0  0f= (=7R= =@%+rS