U )3gM@sddlmZddlZddlZddlmZddlmZddlmZddlmZddlm Z ddlm Z dd lm Z dd l m Z dd l mZdd lmZdd lmZddlmZddlmZe de e efdZerddlmZddlmZddlmZddlmZddlmZGddde Z ddddddddZ!dHd d!d"d#d$d%d&d'Z"dId d!d"d#d(d$d)d*d+Z#dJdd,d-d.d/d0d1d2d3Z$dKdd,d-d.d/d(d0d4d5d6Z%dd#d0d7d8d9Z&d:d;dd?Z(d@d;dAdBZ)dCdDdEdFdGZ*dS)L) annotationsN) TYPE_CHECKING)Any)Iterable)Literal)Protocol)TypeVar)Union) DataFrame) LazyFrame) from_native)Implementation) parse_version)validate_lazinessFrameT)bound) ModuleType)DType)SchemaSeries)DTypesc@seZdZddddddZdS)ArrowStreamExportableNz object | Noneobject)requested_schemareturncCsdS)N)selfrrr6/tmp/pip-unpacked-wheel-hfsjijke/narwhals/functions.py__arrow_c_stream__#sz(ArrowStreamExportable.__arrow_c_stream__)N)__name__ __module__ __qualname__rrrrrr"srverticalhowzIterable[FrameT]z#Literal[('horizontal', 'vertical')])itemsr%rcCsb|dkrd}t||s$d}t|t|}t||d}|}||jdd|D|dS)u_ Concatenate multiple DataFrames, LazyFrames into a single entity. Arguments: items: DataFrames, LazyFrames to concatenate. how: {'vertical', 'horizontal'} * vertical: Stacks Series from DataFrames vertically and fills with `null` if the lengths don't match. * horizontal: Stacks Series from DataFrames horizontally and fills with `null` if the lengths don't match. Returns: A new DataFrame, Lazyframe resulting from the concatenation. Raises: NotImplementedError: 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 narwhals as nw >>> data_1 = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> data_2 = {"a": [5, 2], "b": [1, 4]} >>> df_pd_1 = pd.DataFrame(data_1) >>> df_pd_2 = pd.DataFrame(data_2) >>> df_pl_1 = pl.DataFrame(data_1) >>> df_pl_2 = pl.DataFrame(data_2) Let's define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df1, df2): ... return nw.concat([df1, df2], how="vertical") >>> func(df_pd_1, df_pd_2) a b 0 1 4 1 2 5 2 3 6 0 5 1 1 2 4 >>> func(df_pl_1, df_pl_2) shape: (5, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 4 │ │ 2 ┆ 5 │ │ 3 ┆ 6 │ │ 5 ┆ 1 │ │ 2 ┆ 4 │ └─────┴─────┘ Let's look at case a for horizontal concatenation: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data_1 = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> data_2 = {"c": [5, 2], "d": [1, 4]} >>> df_pd_1 = pd.DataFrame(data_1) >>> df_pd_2 = pd.DataFrame(data_2) >>> df_pl_1 = pl.DataFrame(data_1) >>> df_pl_2 = pl.DataFrame(data_2) Defining a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df1, df2): ... return nw.concat([df1, df2], how="horizontal") >>> func(df_pd_1, df_pd_2) a b c d 0 1 4 5.0 1.0 1 2 5 2.0 4.0 2 3 6 NaN NaN >>> func(df_pl_1, df_pl_2) shape: (3, 4) ┌─────┬─────┬──────┬──────┐ │ a ┆ b ┆ c ┆ d │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 ┆ i64 │ ╞═════╪═════╪══════╪══════╡ │ 1 ┆ 4 ┆ 5 ┆ 1 │ │ 2 ┆ 5 ┆ 2 ┆ 4 │ │ 3 ┆ 6 ┆ null ┆ null │ └─────┴─────┴──────┴──────┘ )Z horizontalr#z9Only horizontal and vertical concatenations are supportedzNo items to concatenatercSsg|] }|jqSr)Z_compliant_frame).0Zdfrrr szconcat..r$)NotImplementedError ValueErrorlistrZ__narwhals_namespace__Z_from_compliant_dataframeconcat)r&r%msgZ first_itemZplxrrrr,(shr,strrzDType | type[DType] | Nonerr)namevaluesdtypenative_namespacercCsddlm}t|||||dS)a Instantiate Narwhals Series from raw data. 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`. native_namespace: The native library to use for DataFrame creation. Returns: A new Series Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... values = [4, 1, 2] ... native_namespace = nw.get_native_namespace(df) ... return nw.new_series("c", values, nw.Int32, native_namespace=native_namespace) Let's see what happens when passing pandas / Polars input: >>> func(pd.DataFrame(data)) 0 4 1 1 2 2 Name: c, dtype: int32 >>> func(pl.DataFrame(data)) # doctest: +NORMALIZE_WHITESPACE shape: (3,) Series: 'c' [i32] [ 4 1 2 ] rdtypesr2r4)narwhalsr4_new_series_impl)r/r0r1r2r4rrr new_seriess2 r8r)r/r0r1r2r4rc Cs:t|}|tjkrB|r0ddlm}|||d}|j|||d}n|tjtjtjhkr|rddl m}t |j } ||d|| |}|j|||d}n|tj kr|rddl m} | ||d}|j|g|d}n^|tjkrd} t| nFz||||}Wn2tk r&} zd} t| | W5d} ~ XYnXt|d d |S) Nrnarwhals_to_native_dtyper3)r/r0r1)r/r1)typezGDask support in Narwhals is lazy-only, so `new_series` is not supportedz@Unknown namespace is expected to implement `Series` constructor.T)Z series_only)r from_native_namespacePOLARSnarwhals._polars.utilsr:rPANDASMODINCUDFnarwhals._pandas_like.utilsr __version__PYARROWnarwhals._arrow.utilsZ chunked_arrayZDASKr)r8AttributeErrorr alias) r/r0r1r2r4implementationpolars_narwhals_to_native_dtypeZ native_series$pandas_like_narwhals_to_native_dtypebackend_versionarrow_narwhals_to_native_dtyper-errrr7sH           r7)r2zdict[str, Any]z dict[str, DType] | Schema | NonezModuleType | NonezDataFrame[Any])dataschemar2rcCsddlm}t||||dS)u Instantiate DataFrame from dictionary. 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}. native_namespace: The native library to use for DataFrame creation. Only necessary if inputs are not Narwhals Series. Returns: A new DataFrame Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's create a new dataframe of the same class as the dataframe we started with, from a dict of new data: >>> @nw.narwhalify ... def func(df): ... new_data = {"c": [5, 2], "d": [1, 4]} ... native_namespace = nw.get_native_namespace(df) ... return nw.from_dict(new_data, native_namespace=native_namespace) Let's see what happens when passing Pandas, Polars or PyArrow input: >>> func(pd.DataFrame(data)) c d 0 5 1 1 2 4 >>> func(pl.DataFrame(data)) shape: (2, 2) ┌─────┬─────┐ │ c ┆ d │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 5 ┆ 1 │ │ 2 ┆ 4 │ └─────┴─────┘ >>> func(pa.table(data)) pyarrow.Table c: int64 d: int64 ---- c: [[5,2]] d: [[1,4]] rr3r5)r6r4_from_dict_impl)rNrOr2r4rrr from_dicts= rQ)rNrOr2r4rc sddlm}ddlm|s(d}t||dkrv|D]}t||r8|}q`q8d}t|fdd| D}t |t j krˆrddl mfd d D|j|d }nt jt jt jhkr,|j|}rddlmt|jfd d|j D|}nt jkrxrhddlm|fd d  D|j|d }nBz||}Wn2tk r}zd}t||W5d}~XYnXt|ddS)Nrr to_nativez0from_dict cannot be called with empty dictionaryzpCalling `from_dict` without `native_namespace` is only supported if all input values are already Narwhals Seriescsi|]\}}||ddqS)T)Z pass_throughr)r'keyvaluerRrr rsz#_from_dict_impl..r9csi|]\}}||dqS)r3rr'r/r1)r4rIrrrV{s)rOc s&i|]\}}|||qSrr)r'r/Z native_type)rKr4rHrJrOrrrVscsg|]\}}||fqSrrrW)rLr4rrr(sz#_from_dict_impl..z@Unknown namespace is expected to implement `from_dict` function.TZ eager_only)narwhals.seriesrnarwhals.translaterSr*r0 isinstanceZ__native_namespace__ TypeErrorr&r r<r=r>r:rQr?r@rAr rBrrCr4ZastyperDrErOtablerFr ) rNrOr2r4rr-val native_framerMr)rLrKr4rHrJrIrOrSrrP]sb               rP)r_r2rc Cst|ds"dt|d}t|t|}|tjkrRt|jdkrR||}nZ|tj tj tj tjhkrRz ddl }Wn6t k r}zd|}t ||W5d}~XYnXt|jdkrd|}t |d||}|tj kr|}n`|tj krdd lm}||}n>|tj kr,|j|}n$|tjkrD||}n d }t|nZ|tjkrj||}nBz||}Wn2tk r}zd }t||W5d}~XYnXt|d d S)aB Construct a DataFrame from an object which supports the PyCapsule Interface. Arguments: native_frame: Object which implements `__arrow_c_stream__`. native_namespace: The native library to use for DataFrame creation. Returns: A new DataFrame Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} Let's define a dataframe-agnostic function which creates a PyArrow Table. >>> @nw.narwhalify ... def func(df): ... return nw.from_arrow(df, native_namespace=pa) Let's see what happens when passing pandas / Polars input: >>> func(pd.DataFrame(data)) # doctest: +SKIP pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] >>> func(pl.DataFrame(data)) # doctest: +SKIP pyarrow.Table a: int64 b: int64 ---- a: [[1,2,3]] b: [[4,5,6]] rzGiven object of type z% does not support PyCapsule interface)rNz@PyArrow>=14.0.0 is required for `from_arrow` for object of type )r) from_arrowzCcongratulations, you entered unrecheable code - please report a bugzuUnknown namespace is expected to implement `DataFrame` class which accepts object which supports PyCapsule Interface.TrX)hasattrr;r\r r<r=rrCr r?r@rApyarrowModuleNotFoundErrorr]Z to_pandasZmodin.pandas.utilsrcAssertionErrorrDrFr ) r_r2r-rHpaexcZtblrcrMrrrrcsX,                   rczdict[str, str])rcCs2tjdd}d|fdtjfdtff}t|S)zdSystem information Returns system and Python version information Copied from sklearn   python executablemachine)sysversionreplacermplatformdict)rlZblobrrr _get_sys_infos  rtc Csld}ddlm}d|i}ddlm}ddlm}|D]2}z||||<Wq4|k rdd||<Yq4Xq4|S) aNOverview 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 )ZpandasZpolarsZcudfZmodinreZnumpyr`)rCr6r)PackageNotFoundError)rp)rvrCimportlib.metadatarurp)depsrC deps_inforurpmodnamerrr_get_deps_info"s    r{NonecCslt}t}td|D]\}}t|dd|qtd|D]\}}t|dd|qJdS)z Print useful debugging information Examples: >>> from narwhals import show_versions >>> show_versions() # doctest: +SKIP z System:z>10z: z Python dependencies:z>13N)rtr{printr&)Zsys_inforykstatrrr show_versionsGs rz(DataFrame[Any] | LazyFrame[Any] | Seriesz Literal[('full', 'interchange')])objrcCs|jS)z Level of support Narwhals has for current object. This can be one of: - 'full': full Narwhals API support - 'metadata': only metadata operations are supported (`df.schema`) )_level)rrrr get_level]s r)N)N)N)N)+ __future__rrrrotypingrrrrrrr Znarwhals.dataframer r rZr Znarwhals.utilsr rrrtypesrZnarwhals.dtypesrZnarwhals.schemarrYrZnarwhals.typingrrr,r8r7rQrPrcrtr{rrrrrrsT                    z@<IQa%