-PhvUddlmZddlZddlZddlmZddlmZmZm Z m Z m Z m Z m Z ddlmZmZmZmZmZmZddlmZmZmZmZmZmZmZmZmZmZddl m!Z!m"Z"m#Z#m$Z$ddl%m&Z&m'Z'dd l(m)Z)dd l*m+Z+m,Z,erWdd l-m.Z.dd l/m0Z0m1Z1dd l2m3Z3m4Z4ddl5m6Z6ddl7m8Z8m9Z9ddl:m;Z;ddlm?Z?ddl@mAZAmBZBmCZCmDZDmEZEmFZFmGZGmHZHmIZImJZJmKZKdZLdeMd<ddddZNed d!" dddd#dd/ZO ddd1ZPed23 dddd#dd9ZQdd<ZRed d!" dddd#dd>ZSddAZTed d!"ddd#ddDZUddFZVddGZWddIZXddLZYedMd!"ddd#ddPZZed d!"ddd#ddRZ[ed d!"ddd#ddSZ\ed d!"ddd#ddTZ]ddXZ^ddYZ_dd\Z`dd]Zadd^Zbdd`ZcddaZdddbZeddcZfdddZgddgZhddhZiddiZjGdjdkZkGdldme)ZlddoZmddpZndddsZoddtZpdduZqdvdwdxdd~ZrdS)) annotationsN)version) TYPE_CHECKINGAnyIterableLiteralMappingSequencecast)ExprKind ExprMetadataapply_n_ary_operationcombine_metadataextract_compliantis_scalar_like) ImplementationVersiondeprecate_native_namespaceflattenis_compliant_expris_eager_allowedis_sequence_but_not_str parse_versionsupports_arrow_c_streamvalidate_laziness)is_narwhals_seriesis_numpy_arrayis_numpy_array_2dis_pyarrow_table)InvalidOperationError ShapeError)Expr) from_native to_native) ModuleType) TypeAliasTypeIs) CompliantExprCompliantNamespace)IntoArrowTable) DataFrame LazyFrame)DTypeSchema)Series) ConcatMethodFrameT IntoDTypeIntoExpr IntoSeriesT NativeFrameNativeLazyFrame NativeSeriesNonNestedLiteral_1DArray_2DArray3Mapping[str, DType] | Schema | Sequence[str] | Noner& _IntoSchemaverticalhowitemsIterable[FrameT]r@r1returnr2c~ddlm}|sd}t|t|}t ||dvrd}t ||d}||r|dkrd}t ||}|| d|D| S) u\Concatenate 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. Returns: A new DataFrame or LazyFrame resulting from the concatenation. 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.>diagonalr> horizontalzDOnly vertical, horizontal and diagonal concatenations are supported.rGzdHorizontal concatenation is not supported for LazyFrames. Hint: you may want to use `join` instead.cg|] }|j S)_compliant_frame).0dfs R/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/narwhals/functions.py zconcat..s888BB'888r?) narwhals.dependenciesrE ValueErrorlistrNotImplementedErrorr __narwhals_namespace___with_compliantconcat)rAr@rEmsg first_itemplxs rMrVrVBsd<;;;;; (oo KKEe 888T!#&&&qJZ(()SL-@-@ 8 $C(((  + + - -C  % % 88%888c BB  rOz1.31.0T) warn_versionrequired)backendnative_namespacenamestrvaluesrdtypeIntoDType | Noner\(ModuleType | Implementation | str | Noner]ModuleType | None Series[Any]cHtd|}t||||S)uInstantiate 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 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| └─────────────────────┘ !ModuleType | Implementation | str)r\)r _new_series_impl)r^r`rar\r]s rM new_seriesris,f6@@G D&% A A AArOrgc0tj|}t|r[tjj|j}|j||||}| S|tj urt| } | |||}t|d|S#t$r} d} t| | d} ~ wwxYw|d|d} t!| )N)r^contextraT) 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_namespacerir#aliasAttributeErrorrQ) r^r`rar\implementationnsseries_native_namespace native_serieserWs rMrhrhs@$099N'' - \ # 0 0 @ @ J))&tRu)UU!!### >1 1 1*>>@@ -*;*F*Ffe++M}$???EEdKK K - - -XC %%1 , -  b bO] b b b S//s":C C>'C99C>z1.26.0)rZdataMapping[str, Any]schema#Mapping[str, DType] | Schema | NoneDataFrame[Any]cT|sd}t||t|\}}tj|}t |rXt jj|j}|j ||| S|tj urb| } | ||}n$#t$r} d}t|| d} ~ wwxYwt|dS|d|d }t|) 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. 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. 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 | └──────────────────┘ z0from_dict cannot be called with empty dictionaryN)rrkrz@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('rm)rQ_from_dict_no_backendrrnrrrorprq _dataframe from_dictrtrurvrxr# rrr\r]rWryrzr| native_framer~s rMrrsZl @oo-d33 g#099N'' : \ # 0 0 @ @ J}&&tFB&GGSSUUU >1 1 1*>>@@ -):(C(CDQW(C(X(XLL - - -TC %%1 , -z)_from_dict_no_backend..[s+ T T TeC5t444 T T TrO)r`r__native_namespace__ TypeErrorrA)rvalr]rWs rMrrQs{{}} c " " "7799  E xnn T Ttzz|| T T TD ! !!rOr;ctd|}t|sd}t|t|s"dt |d}t |t j|}t|rQtj j |j }| ||S|t jurb|} | ||}n$#t"$r} d}t#|| d} ~ wwxYwt%|d S|d |d }t|) 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`. 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. 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]] | └──────────────────┘ rgz)`from_numpy` only accepts 2D numpy arrayszi`schema` is expected to be one of the following types: Mapping[str, DType] | Schema | Sequence[str]. Got .rzAUnknown namespace is expected to implement `from_numpy` function.NTrz 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('rm)r rrQ_is_into_schematyperrrnrrrorprq from_numpyrtrurvrxr#rs rMrr_sv6@@G T " "9oo 6 " " #<< # # # nn#099N'' : \ # 0 0 @ @ J}}T6**66888 >1 1 1*>>@@ -):(D(DTRX(D(Y(YLL - - -UC %%1 , -` 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. 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 │ | | └─────┴─────┘ | └──────────────────┘ rgzGiven object of type z% does not support PyCapsule interface)rkzuUnknown namespace is expected to implement `DataFrame` class which accepts object which supports PyCapsule Interface.NTrz 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('rm)r rrrrrrnrrrorprqr from_arrowrtrurvr+rxr#rQ) rr\r]rWryrzr|nativer~s rMrrszf6@@G #L 1 15El5S5S_d<&8&8___nn#099N'' 4 \ # 0 0 @ @ J}'' b'AAMMOOO >1 1 1*>>@@ -#4"="=l"K"KFF - - -JC %%1 , -6d3333  M M:H M M M S//s.D D%D  D%dict[str, str]ctjdd}d|fdtjfdt jff}t |S)zSystem information. Returns system and Python version information Copied from sklearn Returns: Dictionary with system info.   python executablemachine)sysrreplacerplatformdict)rblobs rM _get_sys_inforsU[ s + +F 6 s~& H%''( D ::rOcvddlm}m}ddlm}d}d|i}|D]!} ||||<#|$rd||<YwxYw|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)PackageNotFoundErrorr) __version__)pandaspolarscudfmodinpyarrownumpynarwhals)importlib.metadatarrrr)rrrdeps deps_infomodnames rM_get_deps_infor%sA@@@@@@@$$$$$$ DD[)I$$ $!(!1!1Ig  # $ $ $!#Ig    $ s ) 66Nonec6t}t}td|D]\}}t|dd|td|D]\}}t|dd|dS)zPrint useful debugging information. Examples: >>> from narwhals import show_versions >>> show_versions() # doctest: +SKIP z System:z>10z: z Python dependencies:z>13N)rrprintrA)sys_inforkstats rM show_versionsrAsH  I +>>##""4    $  !!!! "###??$$""4    $  !!!!""rO5DataFrame[Any] | LazyFrame[Any] | Series[IntoSeriesT]&Literal['full', 'lazy', 'interchange']c|jS)aLevel of support Narwhals has for current object. Arguments: obj: Dataframe or Series. Returns: This can be one of - 'full': full Narwhals API support - 'lazy': only lazy operations are supported. This excludes anything which involves iterating over rows in Python. - 'interchange': only metadata operations are supported (`df.schema`) )_level)rs rM get_levelrTs :rOz1.27.2sourcekwargsc td|}tj|}|}|tjtjtjtjhvr|j|fi|}nX|tj urddl m }|j|fi|}n5 |jd d|i|}n$#t$r}d}t||d}~wwxYwt|dS) uRead 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. Examples: >>> import narwhals as nw >>> nw.read_csv("file.csv", backend="pandas") # doctest:+SKIP ┌──────────────────┐ |Narwhals DataFrame| |------------------| | a b | | 0 1 4 | | 1 2 5 | └──────────────────┘ rgrcsvrz?Unknown namespace is expected to implement `read_csv` function.NTrrI)r rrnrvPOLARSPANDASMODINCUDFread_csvPYARROWrrrxr#) rr\r]r eager_backendrrr~rWs rMrrgs+X6@@G"/88M$88::  1'0BB6BB .0 0 0#s|F55f55  -5+4MMFMfMMLL - - -SC %%1 , - | 5 5 55sB,, C 6CC LazyFrame[Any]c td|}tj|}|}|tjur|j|fi|}ni|tjtjtjtj tj tj hvr|j |fi|}n|tj urddlm}|j |fi|}n|r|ddx}d}t%||jd} |tjur5t-t/dd kr| |n| jd i||}n5 |jd d |i|}n$#t4$r} d }t5|| d} ~ wwxYwt7|S) uLazily 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. 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 │ └─────────┴───────┘ rgrrsessionNFSpark like backends require a session object to be passed in `kwargs`.rsqlframerrz?Unknown namespace is expected to implement `scan_csv` function.rI)r rrnrvrscan_csvrrrDASKDUCKDBIBISrrrr is_spark_likepoprQreadformatSQLFRAMErrloadoptionsrxr#lazy) rr\r]rryrrrrW csv_readerr~s rMrrs(d6@@G#099N%99;;...0'0BB6BB    1'0BB6BB >1 1 1#s|F55f55  % % ' '-zz)T22 2G ;ZCS// !\((// ."999!'*"5"566CC OOF # # # $#--f--226::   -5+4MMFMfMMLL - - -SC %%1 , - | $ $ ) ) + ++ F F=&F88F=c td|}tj|}|}|tjtjtjtjtjtj hvr|j |fi|}nX|tj urddl m }|j|fi|}n5 |j dd|i|}n$#t$r}d}t||d}~wwxYwt!|dS) uyRead 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. 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]] | └──────────────────┘ rgrNrzCUnknown namespace is expected to implement `read_parquet` function.TrrI)r rrnrvrrrrrr read_parquetrpyarrow.parquetparquet read_tablerxr#) rr\r]rryrpqr~rWs rMrr s7b6@@G#099N%99;; 5'4VFFvFF >1 1 1$$$$$$$r}V66v66  -9+8QQQ&QQLL - - -WC %%1 , - | 5 5 55s2C C# CC#c td|}tj|}|}|tjur|j|fi|}ni|tjtjtjtj tj tj hvr|j |fi|}n|tj urddlm}|j|fi|}n|r|ddx}d}t'||jd} |tjur5t/t1ddkr| |n| jd i||}n5 |jd d |i|}n$#t6$r} d }t7|| d} ~ wwxYwt9|S) 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`. 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. 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]] | └──────────────────┘ rgrNrrrrrrzCUnknown namespace is expected to implement `scan_parquet` function.rI)r rrnrvr scan_parquetrrrrrrrrrrrrrrQrrrrrrrrxr#r) rr\r]rryrrrrW pq_readerr~s rMrrXs(Z6@@G#099N%99;;...4'4VFFvFF    5'4VFFvFF >1 1 1$$$$$$$r}V66v66  % % ' '-zz)T22 2G ;ZCS// !L'' 22 ."999!'*"5"566CC NN6 " " " #",,V,,11&99   -9+8QQQ&QQLL - - -WC %%1 , - | $ $ ) ) + ++rnamesstr | Iterable[str]r"ct|dfd }t|tdkrtjntjS)uCreates 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. 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 │ | | └─────┴─────┘ | └──────────────────┘ rYrrCc|jSN)col)rY flat_namess rMfunczcol..funcssw ##rOrYrrCr)rr"lenr selector_singleselector_multi_named)rrrs @rMrrss:J$$$$$$  z??a   $&&&  . 0 0   rOctt|dfd }t|tjS)uCreates an expression that excludes columns by their name(s). Arguments: names: Name(s) of the columns to exclude. Returns: A new expression. 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 │ | | └─────┘ | └──────────────────┘ rYrrCc.|Sr)exclude)rY exclude_namess rMrzexclude..funcs{{=)))rOr) frozensetrr"r selector_multi_unnamed)rrr s @rMrrsQ:genn--M****** l9;; < <>> 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]] | └──────────────────┘ rYrrCc|jSr)nth)rY flat_indicess rMrznth..funcAssw %%rOrr)rr"rr rr )r rrs @rMrr!sw<7##L&&&&&&  |   ! ! $&&&  0 2 2   rOcFtdtjS)u[Instantiate an expression representing all columns. Returns: A new expression. 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 | └──────────────────┘ c*|Sr)allrYs rMzall_..asCGGIIrO)r"r r rIrOrMall_rMs!( %%|'J'L'L M MMrOcLdd}t|tjS)uReturn the number of rows. Returns: A new expression. 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 │ | | └─────┘ | └──────────────────┘ rYrrCc*|Sr)rrs rMrzlen_..funcswwyyrOr)r"r aggregation)rs rMlen_res14 l.00 1 11rOcolumnsc8t|S)uSum 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. 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 | └──────────────────┘ )rsumrs rMrr2 =    rOc8t|S)uGet 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. 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 rMr"r"s: =    rOc8t|S)u+Get 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. 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 rMr$r$sB =   ! !!rOc8t|S)u0Return 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. 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 rMr&r&s: =    rOc8t|S)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. Returns: A new expression. 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 rMr(r(r rOexprsIntoExpr | Iterable[IntoExpr]c|sd}t|t|tfdtjS)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. Returns: A new expression. 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 │| |└─────┴──────┴─────┘| └────────────────────┘ z:At least one expression must be passed to `sum_horizontal`c0t||jgRddiSN str_as_litF)rsum_horizontalrY flat_exprss rMrz sum_horizontal..H4) # &0   =B  rOrQrr"r from_horizontal_opr)rWr1s @rMr/r/!]D JooJ      '4   rOc|sd}t|t|tfdtjS)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. Returns: A new expression. 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]] | └──────────────────┘ z:At least one expression must be passed to `min_horizontal`c0t||jgRddiSr-)rmin_horizontalr0s rMrz min_horizontal..tr2rOr3r5s @rMr9r9Os]@ JooJ      '4   rOc|sd}t|t|tfdtjS)u 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. 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 │| |└─────┴──────┴───────┘| └──────────────────────┘ z:At least one expression must be passed to `max_horizontal`c0t||jgRddiSr-)rmax_horizontalr0s rMrz max_horizontal..r2rOr3r5s @rMr<r<{r6rOceZdZd dZd d Zd S) When predicatesr*rCrc<tt||_dSr)all_horizontalr _predicate)selfr?s rM__init__z When.__init__s('**=*=>rOr&IntoExpr | NonNestedLiteral | _1DArrayThenc tjd}jjjr|jsd}t |t fdtjdddS)NFr.zaIf you pass a scalar-like predicate to `nw.when`, then the `then` value must also be scalar-like.c>tfdjdS)Ncl|d|dS)Nrr)whenthen)argsrYs rMrz-When.then....s)chhtAw//44T!W==rOFrH)rrB)rYrCrs`rMrzWhen.then..s2-==== rOr.allow_multi_outputto_single_output)r from_into_exprrB _metadatarr!rFr)rCrkindrWs`` rMrLz When.thens&u??? ? $ 3 "Dr>s<????      rOr>ceZdZddZdS)rFrrErCr"c tjdjjr tsd}t |d fd }t |t ddd S) NFrHzfIf you pass a scalar-like predicate to `nw.when`, then the `otherwise` value must also be scalar-like.rYCompliantNamespace[Any, Any]rCCompliantExpr[Any, Any]c|}t|d}jjs3tr$t |r|}||S)NFrH)_to_compliant_exprrrRrr broadcast otherwise)rYcompliant_exprcompliant_valuerSrCrs rMrzThen.otherwise..funcs!44S99N/UuMMMON1 B"4(( B&o66 B #2";";D"A"A!++O<< ( "1E1E "B S// ! = = = = = = = =   #(!&       rON)rrErCr")rTrUrVr^rIrOrMrFrFs(      rOrFr?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 rMrKrKsN  rOc|sd}t|t|tfdtjS)uxCompute 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. 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")) ┌─────────────────────────────────────────┐ | 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]]| └─────────────────────────────────────────┘ z:At least one expression must be passed to `all_horizontal`c0t||jgRddiSr-)rrAr0s rMrz all_horizontal..:r2rOr3r5s @rMrArAr6rOrr9ctrd}t|tttfrd}t |t fdtjS)u 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. 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 c0|Sr)lit)rYrars rMrzlit..esCGGE511rO) rrQrrRtuplerSr"r literal)rrarWs`` rMrfrfAs2e S oo%$'''DUDD!#&&& 11111<3G3I3I J JJrOc|sd}t|t|tfdtjS)u Compute 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. Examples: >>> 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")) ┌─────────────────────────┐ | 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 │| |└───────┴───────┴───────┘| └─────────────────────────┘ z:At least one expression must be passed to `any_horizontal`c0t||jgRddiSr-)rany_horizontalr0s rMrz any_horizontal..r2rOr3r5s @rMrkrkhs]L JooJ      '4   rOc|sd}t|t|tfdtjS)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. Returns: A new expression. 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]] | └──────────────────┘ z;At least one expression must be passed to `mean_horizontal`c0t||jgRddiSr-)rmean_horizontalr0s rMrz!mean_horizontal..s4) $ '1   >C  rOr3r5s @rMrnrns\< KooJ      '4   rOrF separator ignore_nulls more_exprsr4rprqboolc tgt|g|tfdtddddS)upHorizontally 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. 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 | └──────────────────┘ c2tfdgRddiS)Nc j|dS)Nro) concat_str)rMrqrYrps rMrz.concat_str....s!.#.rOr.F)r)rYr1rqrps`rMrzconcat_str..sR)               rOFTrN)rr"r)r)rprqrrr1s `` @rMrwrwsx`97E7++9j9::J         EdUY      rO)rArBr@r1rCr2r) r^r_r`rrarbr\rcr]rdrCre) r^r_r`rrarbr\rgrCre) rrrrr\rcr]rdrCr)rrrCr) rr;rr<r\rcr]rdrCr)rrrCr)rr*r\rcr]rdrCr)rCr)rCr)rrrCr) rr_r\rcr]rdrrrCr) rr_r\rcr]rdrrrCr)rrrCr")r r rCr")rCr")rr_rCr")r)r*rCr")r?r*rCr>)rr9rarbrCr") r)r*rrr4rpr_rqrsrCr")s __future__rrrrrtypingrrrrr r r narwhals._expression_parsingr r rrrrnarwhals._utilsrrrrrrrrrrrPrrrrnarwhals.exceptionsr r! narwhals.exprr"narwhals.translater#r$typesr%typing_extensionsr&r'narwhals._compliantr(r)narwhals._translater*narwhals.dataframer+r,narwhals.dtypesr-rr/narwhals.seriesr0narwhals.typingr1r2r3r4r5r6r7r8r9r:r;r=__annotations__rVrirhrrrrrrrrrrrrrrrrrrrr"r$r&r(r/r9r<r>rFrKrArfrkrnrwrIrOrMrs?""""""" &&&&&&QQQQQQQQQQQQQQQQQQ                         BAAAAAAA55555555S      33333333EEEEEEEE22222277777777%%%%%%&&&&&&&&&&&&                          SKRRRR     4   B''''T++++\$K$K$K$K$KN////d''''Z ========rO