zh` UddlmZddlZddlZddlmZddlmZddlmZddl m Z ddl m Z ddl mZdd l mZdd lmZdd lmZdd lmZdd lmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z ddl!m"Z"ddl!m#Z#ddl!m$Z$ddl!m%Z%ddl!m&Z&ddl!m'Z'ddl!m(Z(ddl!m)Z)dd l!m*Z*dd!l!m+Z+dd"l!m,Z,dd#l!m-Z-dd$l!m.Z.dd%l!m/Z/dd&l!m0Z0dd'l!m1Z1dd(l!m2Z2dd)l!m3Z3dd*l!m4Z4dd+l!m5Z5dd,l!m6Z6dd-l!m7Z7dd.l!m8Z8dd/l!m9Z9dd0l!m:Z:dd1l;mZ>erdd4l?m@Z@dd5lmAZBddlCZDddlEZFdd6lGmHZHdd7lGmIZIdd8lGmJZJdd9lGmKZKdd:lGmLZLdd;lGmMZMddlNmQZQdd?lNmRZRdd@lNmSZSddAlNmTZTddBlNmUZUddClVmWZWddDlXmYZYddElXmZZZddFl[m\Z\ddGl[m]Z]ddHl^m_Z_ddIl^m`Z`ddJlambZbddKlcmdZdddLlemfZfddMlemgZgddNlemhZhddOlemiZiddPlemjZjddQlemkZkddRlemlZlddSlemmZmddTlemnZnddUlemoZoddVlempZpddWlemqZqddXlemrZrddYlemsZsddZlemtZtdd[lemuZued\ee`ee_eedef]Zved^Zwed_Zxed`ZyedaZzedbdc]Z{eJddZ|edeZ}edfZ~edgZGdhdieZGdjdkeZGdldmeZGdndoeZGdpdqeZGdrdseeeZGdtdueeeZGdvdweZedxdyzZed{dyzZed|du]Zd}Zd~ed<dZd~ed<GddeeZGddeeZGddeZGddeZej$dej&dej(dej*dej,dej.dej0dej2dej4dej6dej8di Zded< ddZddZddZddZddZddZddZe ddZe ddZe ddZe ddZe ddZe ddZe ddZddZddZ ddZddZ ddd ddZddZddZ ddZ ddZddZddZ ddZddZ ddZddZddZ ddZ ddZddZddZddZ ddZddZddZd dZd dZ d dZddd d d„Z d dÄZddĄZddńZÐddƄZ ddDŽZ ddȄZƐddɄZǐddʄZȐdd˄Zɐdd̄Z dd̈́Z dd΄Z ddτZ ddЄZ ddфZϐdd҄ZАddӄZѐddԄZҐddՄZ ddքZԐd dׄZՐd!d؄Zer"ddlZeאjdk\rddlmZn ddlGmZnd"dۄZGd܄dݫZڐd#dބZGd߄dZ d$dZ d%dZy(&) annotationsN)timezone)Enum)autowraps) find_spec)getattr_static)getdoc) token_hex) TYPE_CHECKING)Any)Callable) Container)Iterable)Literal)Protocol)Sequence)TypeVar)Union)cast)overload)warn)get_cudf)get_dask)get_dask_dataframe) get_duckdb)get_ibis) get_modin) get_pandas) get_polars) get_pyarrow) get_pyspark)get_pyspark_connect)get_pyspark_sql) get_sqlframe)is_cudf_series)is_modin_series)is_narwhals_series)is_narwhals_series_int)is_numpy_array_1d)is_numpy_array_1d_int)is_pandas_dataframe)is_pandas_like_dataframe)is_pandas_like_series)is_pandas_series)is_polars_series)is_pyarrow_chunked_array)ColumnNotFoundError)DuplicateError)InvalidOperationError) ModuleType) AbstractSet) Concatenate) LiteralString) ParamSpec)Self) TypeAlias)TypeIs) CompliantExpr)CompliantExprT)CompliantFrameT)CompliantSeriesOrNativeExprT_co)CompliantSeriesT)NativeFrameT_co)NativeSeriesT_co) EvalNames)EagerAllowedImplementation Namespace)ArrowStreamExportable)IntoArrowTable DataFrame LazyFrameDTypeSeries)CompliantDataFrame)CompliantLazyFrame)CompliantSeries) DataFrameLike)DTypes) IntoSeriesT)MultiIndexSelector)SingleIndexSelector)SizedMultiIndexSelector)SizeUnit)SupportsNativeNamespace)TimeUnit)_1DArray) _SliceIndex) _SliceName) _SliceNoneFrameOrSeriesT)bound_T_T1_T2_T3_FnzCallable[..., Any]PRR1R2ceZdZUded<y)_SupportsVersionstr __version__N__name__ __module__ __qualname____annotations__L/var/www/skyplay_api_hub/venv/lib/python3.12/site-packages/narwhals/utils.pyrorossrxroceZdZdddZy) _SupportsGetNcyNrw)selfinstanceowners ry__get__z_SupportsGet.__get__wsrxr})rrr Any | Nonereturnr)rsrtrurrwrxryr{r{vsQrxr{ceZdZUded<y)_StoresImplementationImplementation_implementationNrrrwrxryrrys ''MrxrceZdZUded<y)_StoresBackendVersiontuple[int, ...]_backend_versionNrrrwrxryrr}s ))1rxrceZdZUded<y)_StoresVersionVersion_versionNrrrwrxryrrs 0rxrceZdZdZy)_LimitedContextzRProvides 2 attributes. - `_backend_version` - `_version` Nrsrtru__doc__rwrxryrrs rxrceZdZdZy) _FullContextznProvides 3 attributes. - `_implementation` - `_backend_version` - `_version` Nrrwrxryrrs rxrceZdZeddZy)_StoresColumnscyr}rwr~s rycolumnsz_StoresColumns.columnss,/rxN)r Sequence[str])rsrtrupropertyrrwrxryrrs / /rxr NativeT_coT) covariant CompliantT_co _ContextTz&Callable[Concatenate[_ContextT, P], R]r<_Methodz Callable[Concatenate[_T, P], R2] _Constructorc"eZdZdZeddZy) _StoresNativezProvides access to a native object. Native objects have types like: >>> from pandas import Series >>> from pyarrow import Table cy)zReturn the native object.Nrwrs rynativez_StoresNative.native rxN)rr)rsrtrurrrrwrxryrr  rxrc"eZdZdZeddZy)_StoresCompliantzProvides access to a compliant object. Compliant objects have types like: >>> from narwhals._pandas_like.series import PandasLikeSeries >>> from narwhals._arrow.dataframe import ArrowDataFrame cy)zReturn the compliant object.Nrwrs ry compliantz_StoresCompliant.compliantrrxN)rr)rsrtrurrrrwrxryrrrrxrcLeZdZeZeZeddZeddZy)rcF|tjurddlm}|Sddlm}|S)NrrG)rMAINnarwhals._namespacerHnarwhals.stable.v1._namespace)r~rHs ry namespacezVersion.namespaces 7<<  5 ;rxcF|tjurddlm}|Sddlm}|S)Nr)dtypes)rrnarwhalsrnarwhals.stable.v1)r~r v1_dtypess ryrzVersion.dtypess 7<<  'M:rxN)rztype[Namespace[Any]])rrW) rsrtrurV1rrrrrwrxryrrs6 B 6D rxrceZdZdZeZ eZ eZ eZ eZ eZ eZ eZ eZ eZ eZ eZ e ddZe ddZe ddZddZddZddZddZdd Zdd Zdd Zdd Zdd ZddZddZddZ ddZ!ddZ"e#ddZ$ddZ%y)rz?Implementation of native object (pandas, Polars, PyArrow, ...).cVttjttjt tj ttjttjttjttjttj t#tj$t'tj(t+tj,i }|j/|tj0S)zInstantiate Implementation object from a native namespace module. Arguments: native_namespace: Native namespace. Returns: Implementation. )r rPANDASrMODINrCUDFr"PYARROWr%PYSPARKr!POLARSrDASKrDUCKDBrIBISr&SQLFRAMEr$PYSPARK_CONNECTgetUNKNOWN)clsnative_namespacemappings ryfrom_native_namespacez$Implementation.from_native_namespaces L.// K-- J++ M>11  ~55 L.//  ."5"5 L.// J++ NN33  !>#A#A  {{+^-C-CDDrxc tjtjtjtjtj tj tjtjtjtjtjd }|j|tjS)zInstantiate Implementation object from a native namespace module. Arguments: backend_name: Name of backend, expressed as string. Returns: Implementation. ) pandasmodincudfpyarrowpysparkpolarsdaskduckdbibissqlframepyspark_connect)rrrrrrrrrrrrrr)r backend_namers ry from_stringzImplementation.from_strings%++#))"''%--%--$++"''$++"''&//-==  {{<)?)?@@rxct|tr|j|St|tr|S|j |S)zInstantiate from native namespace module, string, or Implementation. Arguments: backend: Backend to instantiate Implementation from. Returns: Implementation. ) isinstancerprrr)rbackends ry from_backendzImplementation.from_backend*sL'3' OOG $ '>2 **73  rxcL|tjurddl}|S|tjurddl}|jS|tj urddl}|S|tjurddl}|S|tjurddl }|jS|tjurddl }|S|tjurddl}|j S|tj"urddl}|S|tj&urddl} | S|tj*urddl }|jSd} t-| )zyReturn the native namespace module corresponding to Implementation. Returns: Native module. rNzNot supported Implementation)rrrr modin.pandasrrrrr pyspark.sqlsqlrrrdask.dataframe dataframerrrrrAssertionError) r~pdrrparplrrrmsgs ryto_native_namespacez"Implementation.to_native_namespace>s >(( ( I >'' ' <<  >&& & K >)) ) I >)) ) ;;  >(( ( I >&& & !>> ! >(( ( M >** * O >11 1 ;; ,S!!rxc&|tjuS)a^Return whether implementation is pandas. Returns: Boolean. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pandas() True )rrrs ry is_pandaszImplementation.is_pandass~,,,,rxcd|tjtjtjhvS)asReturn whether implementation is pandas, Modin, or cuDF. Returns: Boolean. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pandas_like() True )rrrrrs ryis_pandas_likezImplementation.is_pandas_likes1  ! !       rxcd|tjtjtjhvS)apReturn whether implementation is pyspark or sqlframe. Returns: Boolean. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_spark_like() False )rrrrrs ry is_spark_likezImplementation.is_spark_likes1  " "  # #  * *   rxc&|tjuS)a^Return whether implementation is Polars. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_polars() True )rrrs ry is_polarszImplementation.is_polarsrrxc&|tjuS)a[Return whether implementation is cuDF. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_cudf() False )rrrs ryis_cudfzImplementation.is_cudf~****rxc&|tjuS)a]Return whether implementation is Modin. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_modin() False )rrrs ryis_modinzImplementation.is_modins~++++rxc&|tjuS)aaReturn whether implementation is PySpark. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pyspark() False )rrrs ry is_pysparkzImplementation.is_pyspark~----rxc&|tjuS)aiReturn whether implementation is PySpark. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pyspark_connect() False )rrrs ryis_pyspark_connectz!Implementation.is_pyspark_connects~5555rxc&|tjuS)aaReturn whether implementation is PyArrow. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_pyarrow() False )rrrs ry is_pyarrowzImplementation.is_pyarrowrrxc&|tjuS)a[Return whether implementation is Dask. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_dask() False )rrrs ryis_daskzImplementation.is_dask rrxc&|tjuS)a_Return whether implementation is DuckDB. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_duckdb() False )rrrs ry is_duckdbzImplementation.is_duckdbrrxc&|tjuS)a[Return whether implementation is Ibis. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_ibis() False )rrrs ryis_ibiszImplementation.is_ibis+rrxc&|tjuS)acReturn whether implementation is SQLFrame. Returns: Boolean. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation.is_sqlframe() False )rrrs ry is_sqlframezImplementation.is_sqlframe;s~....rxcptjdtjdtjdtjdtj dtj dtjdtjdtjd tjd tjd i }||S) zHFriendly name for errors. Returns: String. PandasPolarsDaskIbisModincuDFPyArrowPySparkDuckDBSQLFramezPySpark Connect) rrrrrrrrrrrr)r~rs ry_aliaszImplementation._aliasKs  ! !8  ! !8        '     " "I  " "I  ! !8  # #Z  * *,= 8 t}rxc|j}|tjtjtjtj hvr |}t|S|tjtjhvrt }t|S|tjurt}t|Sddl}|j}t|SNr) rrrrrrr#rsqlframe._versionr parse_version)r~r into_versionrs ryrzImplementation._backend_versionas))+   " "  * *     # #   "L\**n,,n.L.LM M&=L\** ^(( (#:L \** %#,,L\**rxN)r type[Self]rr6rr)rrrrprr)rrrz!str | Implementation | ModuleTyperr)rr6)rbool)rr9)rr)&rsrtrurrrrrrrrrrrrrr classmethodrrrrrrrrrrrrrrrrrrrrrwrxryrrsiI VF FE 6DfG!fG! VF 6D VF 6DvH"fO)fG!E E+5E EE4A A'*A AA4  "C   &3"j-  ( (- + , . 6 . + - + / *+rxr)r) ) )r)rr)i)))rrz%dict[Implementation, tuple[int, ...]] MIN_VERSIONScL|t|x}krd|d|d|}t|y)NzMinimum version of z supported by Narwhals is z , found: )r& ValueError)implementationbackend_version min_versionrs ryvalidate_backend_versionr,sCn)EE+F#N#33Mk]ZcdsctuoGrxcD|j|r|t|dS|Sr}) startswithlen)textprefixs ry remove_prefixr2s$ vCKM"" KrxcF|j|r|dt| S|Sr})endswithr/)r0suffixs ry remove_suffixr6s& }}VNs6{l## Krxcbtt|dk(rt|dr |dS|S)Nr#r)listr/ _is_iterable)argss ryflattenr;s. CIN|DG/DQ PP4 PPrxc8t|ttfs|fS|Sr})rr8tuple)args rytupleifyr?s cD%= )v Jrxc~ddlm}t|s t|rdt |d}t |t x}Rt||j|j|j|jfrdt |d}t |t|txrt|tt|f S)NrrQz(Expected Narwhals class or scalar, got: z2. Perhaps you forgot a `nw.from_native` somewhere?z`. Hint: Perhaps you - forgot a `nw.from_native` somewhere? - used `pl.col` instead of `nw.col`?)narwhals.seriesrRr-r0type TypeErrorr!rExprrLrNrrpbytes)r>rRrrs ryr9r9s&3#3C#88c Cuvnl'J bii",, =-7tCykB3 3 n c8 $ RZc5&=Q-R)RRrxct|tr|n |j}tjdd|}t d|j dDS)zSimple version parser; split into a tuple of ints for comparison. Arguments: version: Version string, or object with one, to parse. Returns: Parsed version number. z (\D?dev.*$)c3\K|]$}ttjdd|&yw)z\DrGN)intresub).0vs ry z parse_version..s"KqRVVE2q)*Ks*,.)rrprqrJrKr=split)version version_strs ryrrsH(5'7;N;NK&&[9K KK4E4Ec4JK KKrxcyr}rw obj_or_cls cls_or_tuples ryisinstance_or_issubclassrWsrxcyr}rwrTs ryrWrWs rxcyr}rwrTs ryrWrWs"rxcyr}rwrTs ryrWrWs+.rxcyr}rwrTs ryrWrWs%(rxcyr}rwrTs ryrWrWs7:rxcyr}rwrTs ryrWrWsrxcddlm}t||r t||St||xst|txr t ||S)NrrO)narwhals.dtypesrPrrB issubclass)rUrVrPs ryrWrWsF%*e$*l33 j, / :t$MJ )Mrxcddlmddlmtfd|Dstfd|Dryd|Dcgc] }t |c}}t |cc}w)NrrKrMc36K|]}t|ywr}r)rLitemrLs ryrNz$validate_laziness..s 94:dI & 9c36K|]}t|ywr}rc)rLrdrNs ryrNz$validate_laziness..s :DJtY ' :rezGThe items to concatenate should either all be eager, or all lazy, got: )narwhals.dataframerLrNallrBrC)itemsrdrrLrNs @@ryvalidate_lazinessrjsZ,, 95 99 :E :: SlqTrdhUYZ^U_TrSs tC C.UssAcddlm}ddlm}d d}t d|}t d|}t t |dd|rt t |dd|r||jjj||jjj|j|jj|jjj|jjjSt t |dd|rt t |dd|r||jjj||jjj|j|jj|jjj|jjjSt t |dd|rt t |dd|r||jjj||jjj|j|jj|jjj|jjjSt t |dd|rt t |dd|r||jjj||jjj|j|jj|jjj|jjjSt|t|k7r%d t|d t|}t||S) aAlign `lhs` to the Index of `rhs`, if they're both pandas-like. Arguments: lhs: Dataframe or Series. rhs: Dataframe or Series to align with. Returns: Same type as input. Notes: This is only really intended for backwards-compatibility purposes, for example if your library already aligns indices for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this only checks that `lhs` and `rhs` are the same length. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2]}, index=[3, 4]) >>> s_pd = pd.Series([6, 7], index=[4, 3]) >>> df = nw.from_native(df_pd) >>> s = nw.from_native(s_pd, series_only=True) >>> nw.to_native(nw.maybe_align_index(df, s)) a 4 2 3 1 r)PandasLikeDataFrame)PandasLikeSeriesrc6|js d}t|y)Nz'given index doesn't have a unique index) is_uniquer()indexrs ry_validate_indexz*maybe_align_index.._validate_index,s;CS/ !rx_compliant_frameN_compliant_seriesz6Expected `lhs` and `rhs` to have the same length, got z and )rprrNone)narwhals._pandas_like.dataframerlnarwhals._pandas_like.seriesrmrrgetattrrrrrp_with_compliant _with_nativelocrsr/r()lhsrhsrlrmrqlhs_anyrhs_anyrs rymaybe_align_indexrsJBD=" 5#G5#G+T24G WW&8$?AT U0077==>0077==>&&  $ $ 1 1((//33G4L4L4S4S4Y4YZ   +T24G WW&94@BR S0077==>1188>>?&&  $ $ 1 1((//33--44::   ,d35E WW&8$?AT U1188>>?0077==>&&  % % 2 2))0044,,3399   ,d35E WW&94@BR S1188>>?1188>>?&&  % % 2 2))0044--44::    7|s7|#Fs7|nTYZ]^eZfYgho Jrxctd|}|j}t|s t|r |jSy)aGet the index of a DataFrame or a Series, if it's pandas-like. Arguments: obj: Dataframe or Series. Returns: Same type as input. Notes: This is only really intended for backwards-compatibility purposes, for example if your library already aligns indices for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this returns `None`. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 5]}) >>> df = nw.from_native(df_pd) >>> nw.maybe_get_index(df) RangeIndex(start=0, stop=2, step=1) >>> series_pd = pd.Series([1, 2]) >>> series = nw.from_native(series_pd, series_only=True) >>> nw.maybe_get_index(series) RangeIndex(start=0, stop=2, step=1) rN)r to_nativer.r/rp)objobj_any native_objs rymaybe_get_indexrgs=:5#G""$J +/DZ/P rx)rpcddlm}td|}|j}|| d}t||s| d}t||.t |r|Dcgc] }||dc}n ||d}n|}t |r9|j |jj|j|St|rsddl m } |r d }t|| |||jj|jj }|j |jj|S|Scc}w) aSet the index of a DataFrame or a Series, if it's pandas-like. Arguments: obj: object for which maybe set the index (can be either a Narwhals `DataFrame` or `Series`). column_names: name or list of names of the columns to set as index. For dataframes, only one of `column_names` and `index` can be specified but not both. If `column_names` is passed and `df` is a Series, then a `ValueError` is raised. index: series or list of series to set as index. Returns: Same type as input. Raises: ValueError: If one of the following condition happens: - none of `column_names` and `index` are provided - both `column_names` and `index` are provided - `column_names` is provided and `df` is a Series Notes: This is only really intended for backwards-compatibility purposes, for example if your library already aligns indices for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this is a no-op. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 5]}) >>> df = nw.from_native(df_pd) >>> nw.to_native(nw.maybe_set_index(df, "b")) # doctest: +NORMALIZE_WHITESPACE a b 4 1 5 2 r)rrz8Only one of `column_names` or `index` should be providedz3Either `column_names` or `index` should be providedT) pass_through) set_indexz/Cannot set index using column names on a Series)r)r*)narwhals.translaterrr(r9r.rxrrryrr/narwhals._pandas_like.utilsrsrr) r column_namesrprdf_anyrridxkeysrs rymaybe_set_indexrsF^- % F!!#JE$5Ho EMCo E";@ @3Ys . @5t4  +%%  # # 0 01E1Ed1K L   z *9 CCS/ !  00@@11BB  %%f&>&>&K&KJ&WXX 5 AsD;ctd|}|j}t|rX|j}t ||r|S|j |j j|jdSt|rX|j}t ||r|S|j |jj|jdS|S)aReset the index to the default integer index of a DataFrame or a Series, if it's pandas-like. Arguments: obj: Dataframe or Series. Returns: Same type as input. Notes: This is only really intended for backwards-compatibility purposes, for example if your library already resets the index for users. If you're designing a new library, we highly encourage you to not rely on the Index. For non-pandas-like inputs, this is a no-op. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 5]}, index=([6, 7])) >>> df = nw.from_native(df_pd) >>> nw.to_native(nw.maybe_reset_index(df)) a b 0 1 4 1 2 5 >>> series_pd = pd.Series([1, 2]) >>> series = nw.from_native(series_pd, series_only=True) >>> nw.maybe_get_index(series) RangeIndex(start=0, stop=2, step=1) rT)drop) rrr.__native_namespace___has_default_indexrxrrry reset_indexr/rs)rrrrs rymaybe_reset_indexrs>5#G""$J +"779 j*: ;N&&  $ $ 1 1*2H2Hd2H2S T  Z("779 j*: ;N&&  % % 2 2:3I3It3I3T U   Nrxc.t||jSr})r RangeIndex)rrs ry_is_range_indexrs c+66 77rxc|j}t||xr:|jdk(xr)|jt |k(xr|j dk(S)Nrr#)rprstartstopr/step)native_frame_or_seriesrrps ryrrsW # ( (E/0  KK1   JJ#e* $  JJ!O rxc Rtd|}|j}t|r:|j|jj |j |i|St|r:|j|jj |j |i|S|S)aWConvert columns or series to the best possible dtypes using dtypes supporting ``pd.NA``, if df is pandas-like. Arguments: obj: DataFrame or Series. *args: Additional arguments which gets passed through. **kwargs: Additional arguments which gets passed through. Returns: Same type as input. Notes: For non-pandas-like inputs, this is a no-op. Also, `args` and `kwargs` just get passed down to the underlying library as-is. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> import numpy as np >>> df_pd = pd.DataFrame( ... { ... "a": pd.Series([1, 2, 3], dtype=np.dtype("int32")), ... "b": pd.Series([True, False, np.nan], dtype=np.dtype("O")), ... } ... ) >>> df = nw.from_native(df_pd) >>> nw.to_native( ... nw.maybe_convert_dtypes(df) ... ).dtypes # doctest: +NORMALIZE_WHITESPACE a Int32 b boolean dtype: object r) rrr.rxrrryconvert_dtypesr/rs)rr:kwargsrrs rymaybe_convert_dtypesr)sH5#G""$J +&&  $ $ 1 1) ))4:6:   Z(&&  % % 2 2) ))4:6:   Nrxcv|dvr|S|dvr|dz S|dvr|dz S|dvr|dz S|dvr|d z Sd |}t|) zScale size in bytes to other size units (eg: "kb", "mb", "gb", "tb"). Arguments: sz: original size in bytes unit: size unit to convert into Returns: Integer or float. >brE>kb kilobytesi>mb megabytesi>gb gigabytesi@>tb terabyteslz9`unit` must be one of {'b', 'kb', 'mb', 'gb', 'tb'}, got )r()szunitrs ry scale_bytesr^ss ~ $ $Dy $ $G| $ $G| $ $G|KD8Torxcddlm}|jjj}|j}t ||r9t |j |jr|jjdS|j |jk(ry|j |jk7ry|j}t|r|j jdk(St|rt|j j"St%|r|j j"St'|r|j j"St)|r0ddlm}||j.xr|j.j"Sy)aReturn whether indices of categories are semantically meaningful. This is a convenience function to accessing what would otherwise be the `is_ordered` property from the DataFrame Interchange Protocol, see https://data-apis.org/dataframe-protocol/latest/API.html. - For Polars: - Enums are always ordered. - Categoricals are ordered if `dtype.ordering == "physical"`. - For pandas-like APIs: - Categoricals are ordered if `dtype.cat.ordered == True`. - For PyArrow table: - Categoricals are ordered if `dtype.type.ordered == True`. Arguments: series: Input Series. Returns: Whether the Series is an ordered categorical. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data = ["x", "y"] >>> s_pd = pd.Series(data, dtype=pd.CategoricalDtype(ordered=True)) >>> s_pl = pl.Series(data, dtype=pl.Categorical(ordering="physical")) Let's define a library-agnostic function: >>> @nw.narwhalify ... def func(s): ... return nw.is_ordered_categorical(s) Then, we can pass any supported library to `func`: >>> func(s_pd) True >>> func(s_pl) True r)InterchangeSeries is_orderedTFphysical) is_dictionary)narwhals._interchange.seriesrrsrrrdtype Categoricalrdescribe_categoricalrrr1orderingr0rcatorderedr(r'r2narwhals._arrow.utilsrrB)seriesrrr native_seriesrs ryis_ordered_categoricalrws<T?  % % . . 5 5F((I)./J f((544\BB ||v{{" ||v)))$$&M &""++z99 &M%%--..}%  (((m$  ((( .7]//0O]5G5G5O5OO rxc:d}t|dt||S)Nz}Use `generate_temporary_column_name` instead. `generate_unique_token` is deprecated and it will be removed in future versions1.13.0r)n_bytesr)issue_deprecation_warninggenerate_temporary_column_name)rrrs rygenerate_unique_tokenrs% ?cH5 )'7 KKrxcfd} t|}||vr|S|dz }|dkDrd|d|}t|/)aGenerates a unique column name that is not present in the given list of columns. It relies on [python secrets token_hex](https://docs.python.org/3/library/secrets.html#secrets.token_hex) function to return a string nbytes random bytes. Arguments: n_bytes: The number of bytes to generate for the token. columns: The list of columns to check for uniqueness. Returns: A unique token that is not present in the given list of columns. Raises: AssertionError: If a unique token cannot be generated after 100 attempts. Examples: >>> import narwhals as nw >>> columns = ["abc", "xyz"] >>> nw.generate_temporary_column_name(n_bytes=8, columns=columns) not in columns True rr#dzMInternal Error: Narwhals was not able to generate a column name with n_bytes=z and not in )r r)rrcountertokenrs ryrrs_,G '"  L1  S=*L 3 !% % rxc|j}t|}|r/|Dcgc] }||vs| }}|rtj|||Stt |j t |}|Scc}w)N)missing_columnsavailable_columns)rr8r3'from_missing_and_available_column_namesset intersection)compliant_framerstrictcolsto_dropxrs ryparse_columns_to_droprs  " "D7mG &-?$1?? %MM /4  Ns4y--c'l;< N@s A7A7cHt|txrt|t Sr})rrrp)sequences ryis_sequence_but_not_strrs h ) K*Xs2K.KKrxcBt|txr|tdk(Sr})rslicers ry is_slice_noners c5 ! 8cU4[&88rxct|xr3t|dkDxrt|dtxst|dk(xs%t |xst |xs t |Sr)rr/rrIr,r*is_compliant_series_intrs ryis_sized_multi_index_selectorrsl $C ( Pc(Q,::c!fc#:NCA  ( ! %  ( "# &  ( #3 'rxcft|xs%t|xst|xs t|Sr})rr+r)is_compliant_seriesrs ryis_sequence_likers: $ $ S ! $ c " $ s # rxc t|txrrt|jtxsVt|jtxs:t|j txr|jduxr|jduSr})rrrrIrrrs ryis_slice_indexr!sh c5 ! 399c" R chh $ R sxx % P#))t*; PD@Prxc"t|tSr})rrangers ryis_ranger)s c5 !!rxcZtt|txrt|t Sr})rrrIrs ryis_single_index_selectorr-s#  3$BZT-B)B CCrxcLt|xst|xs t|Sr})rrrrs ryis_index_selectorr1s+ !%  ( -  # rxc^tt|txr|xrt|d|Sr)rrr8)rtps ry is_list_ofr;s)  3%H#H*SVR2H IIrxcxtt|xr%tt|dx}xr t ||Sr})rrnextiterr)rrfirsts ryis_sequence_ofr@s> $ "49d+ +U " ub ! rxcpddl}ddlm}ddl}t ||j j }|j}d} |re|j|}|j|s*t|jddx}r#|jdr|j}|dz }n ~|S|re ~|S#~wxYw)zFind the first place in the stack that is not inside narwhals. Returns: Stacklevel. Taken from: https://github.com/pandas-dev/pandas/blob/ab89c53f48df67709a533b6a95ce3d911871a0a8/pandas/util/_exceptions.py#L30-L51 rN)Path co_qualnamezsingledispatch.r#) inspectpathlibrrrp__file__parent currentframegetfiler.rwf_codef_back)rrnwpkg_dirframenfnamequalnames ryfind_stacklevelrIs$r{{#**+G  "E AOOE*E($U\\=$GGG''(9: Q  H'   H sA B2+B22B5c8t|tty)zIssue a deprecation warning. Arguments: message: The message associated with the warning. _version: Narwhals version when the warning was introduced. Just used for internal bookkeeping. )messagecategory stacklevelN)rDeprecationWarningr)rrs ryrrss #5/BSTrxcn|||}|S|||rd}t|d| }|S|| |Sd}t|)Nz`strict` in `from_native` is deprecated, please use `pass_through` instead. Note: `strict` will remain available in `narwhals.stable.v1`. See https://narwhals-dev.github.io/narwhals/backcompat/ for more information. rrz,Cannot pass both `strict` and `pass_through`)rr()rrpass_through_defaultemit_deprecation_warningrs ryvalidate_strict_and_pass_thoughr~sy~,.+     4 #b  &cH =!z  L4  =orxrGF) warn_versionrequiredcdfd }|S)a8Decorator to transition from `native_namespace` to `backend` argument. Arguments: warn_version: Emit a deprecation warning from this version. required: Raise when both `native_namespace`, `backend` are `None`. Returns: Wrapped function, with `native_namespace` **removed**. c6tdfd }|S)Nc|jdd}|jdd}||rd}t||}n2|| d}t|||rdjd}t|||d<|i|S)Nrrz`native_namespace` is deprecated, please use `backend` instead. Note: `native_namespace` will remain available in `narwhals.stable.v1`. See https://narwhals-dev.github.io/narwhals/backcompat/ for more information. rz0Can't pass both `native_namespace` and `backend`z `backend` must be specified in `z`.)poprr(rs)r:kwdsrrrfnrrs rywrapperz=deprecate_native_namespace..decorate..wrappershhy$/G#xx(:DA +j .cLI*!-'2EH o%!)go(8 RH o%%DOt$t$ $rx)r:P.argsrP.kwargsrrkr)rrrrs` rydecoratez,deprecate_native_namespace..decorates r %  %*rx)rCallable[P, R]rrrw)rrrs`` rydeprecate_native_namespacers2 Orxcb|dkr d}t|t|ts'|jj}d|d}t ||_|dkr d}t|t|ts'|jj}d|d}t |||kDr d}t |||fS|}||fS)Nr#z+window_size must be greater or equal than 1zargument 'window_size': 'z,' object cannot be interpreted as an integerz+min_samples must be greater or equal than 1zargument 'min_samples': 'z6`min_samples` must be less or equal than `window_size`)r(rrI __class__rsrCr5) window_size min_samplesr_types ry_validate_rolling_argumentsr"sQ;o k3 '%%..'w/( ( n ??CS/ !+s+))22E+E73,, C.  $JC', ,  ##"  ##rxc  tjj}|j j}td|D}|dz|krt|t|}dd|zd}|t|z }|dd |dzz|d |dz|dzzzd z }|dd |zd z }||z dz}||z dz||z dzz} |D]$} |dd |z| d | |zt| z zd z }&|d d|zd z }|Sdt|z } dddd | dzz|d | dz| dzzzddd S#t$r#t tj dd}Y:wxYw)NCOLUMNSPc32K|]}t|ywr})r/)rLlines ryrNz generate_repr..s>3t9>su┌u─u┐ | z| -u└u┘'uu───────────────────────────────────────u┐ |u/| | Use `.to_native` to see native output | └) osget_terminal_sizerOSErrorrIgetenv expandtabs splitlinesmaxr/) header native_reprterminal_width native_linesmax_native_widthlengthoutput header_extra start_extra end_extrar'diffs ry generate_reprr?s7--/77))+668L>>>!~-%s6{3uv~&e,F + Ac\Q./0 PQ@QT`cdTd@d9e8ffijjAcVn%S)) 00Q6 ..14AQ8QUV7VV   kD #-.tfSIHX'C!#&& Jrxc.tt|}t||k7rmddlm}||}|j Dcic]\}}|dkDs ||}}}dj d|j D}d|}t |ycc}}w)Nr)Counterr#rGc34K|]\}}d|d|dyw)z - 'z' z timesNrw)rLkrMs ryrNz0check_column_names_are_unique..s#LAaS1#V,Lsz"Expected unique column names, got:)r/r collectionsrGrijoinr4)rlen_unique_columnsrGrrIrM duplicatesrs rycheck_column_names_are_uniquerN sS\* 7|))''"'.}}@tq!!a%ad@ @ggL9I9I9KLL23%8S!!*As  BBc|hdnt|tr|hn t|}|dhn>t|ttfr t|hn|Dchc]}| t|ndc}}||fScc}w)N>smsnsus)rrprr) time_unit time_zone time_unitstz time_zoness ry_parse_time_unit_and_time_zonerYs    i %[ ^     i#x 1)n .fn@s rx)rgrrrrw)rbrs` rypassthrough_column_namesrh?s Irxc4t}t||||uSr})objectr )rattrsentinels ry_hasattr_staticrmFsxH #tX .h >>rxct|dS)N__narwhals_dataframe__rmrs ryis_compliant_dataframerqK 3 8 99rxct|dS)N__narwhals_lazyframe__rprs ryis_compliant_lazyframeruQrrrxct|dS)N__narwhals_series__rprs ryrrWs 3 5 66rxcPt|xr|jjSr})rr is_integerrs ryrr]s! s # > (<(<(>>rxct|dS)N__narwhals_expr__hasattrrs ryis_compliant_exprr~cs 3+ ,,rxc|tjtjtjtjtj hvSr})rrrrrrrs ryis_eager_allowedrisA   rxct|dS)Nrr|rs ryhas_native_namespacerss 3. //rxct|dS)N __dataframe__r|rs ry_supports_dataframe_interchangerws 3 ((rxct|dS)N__arrow_c_stream__rprs rysupports_arrow_c_streamr{s 3 4 55rxcHfd|D}tt||S)aORemap join keys to avoid collisions. If left keys collide with the right keys, append the suffix. If there's no collision, let the right keys be. Arguments: left_on: Left keys. right_on: Right keys. suffix: Suffix to append to right keys. Returns: A map of old to new right keys. c36K|]}|vr|n|ywr}rw)rLkeyleft_onr5s ryrNz(_remap_full_join_keys..s*8;C7N3%x3re)dictzip)rright_onr5right_keys_suffixeds` ` ry_remap_full_join_keysrs( ?G H12 33rxctdrPddl}ddlm}|j}|t ||}|j j||jSdt|jd}t|) zGuards `ArrowDataFrame.from_arrow` w/ safer imports. Arguments: data: Object which implements `__arrow_c_stream__`. context: Initialized compliant object. Returns: A PyArrow Table. rrN)ArrowNamespace)r*rQ)contextz@PyArrow>=14.0.0 is required for `from_arrow` for object of type rO) r rnarwhals._arrow.namespacerrr _dataframe from_arrowrrBrsModuleNotFoundError)datarrrrQrRrs ry_into_arrow_tablersv<"" M",=w O}}''b'9@@@PQUVZQ[QdQdPgghi!#&&rxc|S)aVisual-only marker for unstable functionality. Arguments: fn: Function to decorate. Returns: Decorated function (unchanged). Examples: >>> from narwhals.utils import unstable >>> @unstable ... def a_work_in_progress_feature(*args): ... return args >>> >>> a_work_in_progress_feature.__name__ 'a_work_in_progress_feature' >>> a_work_in_progress_feature(1, 2, 3) (1, 2, 3) rw)rs ryunstablers ( Irx)r  deprecatedcdd}|S)Nc|Sr}rw)funcs ryrzdeprecated..wrappersKrx)rrirrirw)rrs ryrrs rxcZeZdZdZd d dZd dZd dZ d d dZddZe ddZ y)not_implementedaMark some functionality as unsupported. Arguments: alias: optional name used instead of the data model hook [`__set_name__`]. Returns: An exception-raising [descriptor]. Notes: - Attribute/method name *doesn't* need to be declared twice - Allows different behavior when looked up on the class vs instance - Allows us to use `isinstance(...)` instead of monkeypatching an attribute to the function Examples: >>> from narwhals.utils import not_implemented >>> class Thing: ... def totally_ready(self) -> str: ... return "I'm ready!" ... ... not_ready_yet = not_implemented() >>> >>> thing = Thing() >>> thing.totally_ready() "I'm ready!" >>> thing.not_ready_yet() Traceback (most recent call last): ... NotImplementedError: 'not_ready_yet' is not implemented for: 'Thing'. ... >>> isinstance(Thing.not_ready_yet, not_implemented) True [`__set_name__`]: https://docs.python.org/3/reference/datamodel.html#object.__set_name__ [descriptor]: https://docs.python.org/3/howto/descriptor.html Nc||_yr})r)r~aliass ry__init__znot_implemented.__init__s #( rxcfdt|jd|jd|jS)N: rO)rBrs _name_owner_namers ry__repr__znot_implemented.__repr__s14:&&'s4+;+;*>> from narwhals.utils import requires, Implementation >>> class SomeBackend: ... _implementation = Implementation.PYARROW ... _backend_version = 20, 0, 0 ... ... @requires.backend_version((9000, 0, 0)) ... def really_complex_feature(self) -> str: ... return "hello" >>> backend = SomeBackend() >>> backend.really_complex_feature() Traceback (most recent call last): ... NotImplementedError: `really_complex_feature` is only available in PyArrow>='9000.0.0', found version '20.0.0'. r _min_versionrp_hintcD|j|}||_||_|S)zMethod decorator for raising below a minimum `_backend_version`. Arguments: minimum: Minimum backend version. hint: Optional suggested alternative. Returns: An exception-raising decorator. )__new__rr)rminimumhintrs ryr*zrequires.backend_versionNs&kk#"  rxc2djd|DS)NrOc3"K|]}| ywr}rw)rLds ryrNz,requires._unparse_version..`s811#8s )rK)r*s ry_unparse_versionzrequires._unparse_version^sxx8888rxc T|j|jk\ry|j}|jj}|j |j}|j |j}d|d|d|d|d }|j r|d|j }t|)N`z` is only available in z>=z, found version rO )rr _wrapped_namerrrrr)r~rmethodrrfoundrs ry_ensure_versionzrequires._ensure_versionbs  $ $(9(9 9 ##**11''(9(9:%%h&?&?@&0 G;FVW\V__`a ::EDJJ<(C!#&&rxcVj_tdfd }|S)Nc>j||g|i|Sr})r)rr:rrr~s ryrz"requires.__call__..wrapperqs&   *h... .rx)rrr:rrrrrk)rsrr)r~rrs`` ryrzrequires.__call__ns,[[ r /  / rxN)rG)rrprrrr;)r*rrrp)rrrrt)r_Method[_ContextT, P, R]rr) rsrtrurrvrr* staticmethodrrrrwrxryrr4sD,"! J  99 ' rxrc|j|j|jnd}|j|j|jdznd}|j}|||fS)Nr#)rrprr) str_slicerrrrs ryconvert_str_slice_to_int_slicerzsZ/8oo.IGMM)// *tE090J7== (1 ,PTD >>D 4 rxcdfd }|S)zSteal the class-level docstring from parent and attach to child `__init__`. Returns: Decorated constructor. Notes: - Passes static typing (mostly) - Passes at runtime c|jdk(r+tttrt|_|Sdt jd|j d}t|)Nrz`@zL` is only allowed to decorate an `__init__` with a class-level doc. Method: z Parent: )rsr`rBr r inherit_docrurC) init_childr tp_parents ryrzinherit_doc..decoratesr   * ,DOT1R!' !2J  [))*+%2256$-)  C. rx)r_Constructor[_T, P, R2]rrrw)rrs` ryrrs ! Orx)r)rr*rrrt)r0rpr1rprrp)r0rpr5rprrp)r:rrz list[Any])r>rrr)r>zAny | Iterable[Any]rr)rQz#str | ModuleType | _SupportsVersionrr)rUrBrVrrzTypeIs[type[_T]])rU object | typerVrrzTypeIs[_T | type[_T]])rUrBrVtuple[type[_T1], type[_T2]]rzTypeIs[type[_T1 | _T2]])rUrrVrrz#TypeIs[_T1 | _T2 | type[_T1 | _T2]])rUrBrV&tuple[type[_T1], type[_T2], type[_T3]]rzTypeIs[type[_T1 | _T2 | _T3]])rUrrVrrz/TypeIs[_T1 | _T2 | _T3 | type[_T1 | _T2 | _T3]])rUrrVztuple[type, ...]rz TypeIs[Any])rUrrVrrr)riz Iterable[Any]rrt)r{rcr|z-Series[Any] | DataFrame[Any] | LazyFrame[Any]rrc)rz-DataFrame[Any] | LazyFrame[Any] | Series[Any]rrr})rrcrzstr | list[str] | Nonerpz6Series[IntoSeriesT] | list[Series[IntoSeriesT]] | Nonerrc)rrcrrc)rrrrrzTypeIs[pd.RangeIndex])rzpd.Series[Any] | pd.DataFramerrrr)rrcr:rrz bool | strrrc)rrIrr\rz int | float)rz Series[Any]rr)rrIrrrrp)rrrz Iterable[str]rrrz list[str])rSequence[_T] | AnyrTypeIs[Sequence[_T]])rrrzTypeIs[_SliceNone])rrrzCTypeIs[SizedMultiIndexSelector[Series[Any] | CompliantSeries[Any]]])rrrz-TypeIs[Sequence[_T] | Series[Any] | _1DArray])rrrzTypeIs[_SliceIndex])rrrz TypeIs[range])rrrzTypeIs[SingleIndexSelector])rrrzTTypeIs[SingleIndexSelector | MultiIndexSelector[Series[Any] | CompliantSeries[Any]]])rrrrrzTypeIs[list[_T]])rrrrrr)rrI)rrprrprrt) r bool | Nonerrr rr rrr)rrprrrz*Callable[[Callable[P, R]], Callable[P, R]])rrIr z int | Nonerztuple[int, int])r4rpr5rprrp)rrrCzSequence[str] | Nonerrt)rrrrt)rTz$TimeUnit | Iterable[TimeUnit] | NonerUz7str | timezone | Iterable[str | timezone | None] | Nonerz%tuple[Set[TimeUnit], Set[str | None]]) rrPrrWrVz Set[TimeUnit]rXzSet[str | None]rr)rrrr)rrrbzContainer[str]rr)rbrrzEvalNames[Any])rrrkrprr)rzKCompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeFrameT_co] | AnyrzMTypeIs[CompliantDataFrame[CompliantSeriesT, CompliantExprT, NativeFrameT_co]])rz9CompliantLazyFrame[CompliantExprT, NativeFrameT_co] | Anyrz;TypeIs[CompliantLazyFrame[CompliantExprT, NativeFrameT_co]])rz'CompliantSeries[NativeSeriesT_co] | Anyrz)TypeIs[CompliantSeries[NativeSeriesT_co]])rzECompliantExpr[CompliantFrameT, CompliantSeriesOrNativeExprT_co] | AnyrzGTypeIs[CompliantExpr[CompliantFrameT, CompliantSeriesOrNativeExprT_co]])rrrz"TypeIs[EagerAllowedImplementation])rrrzTypeIs[SupportsNativeNamespace])rrrzTypeIs[DataFrameLike])rrrzTypeIs[ArrowStreamExportable])rrrrr5rprzdict[str, str])rrJrrrzpa.Table)rrirri)rrprzCallable[[_Fn], _Fn])rrprrprr)rrarrrz"tuple[int | None, int | None, Any])rzCallable[P, R1]rzr?r@rArBrCrDnarwhals._compliant.typingrErrFrHnarwhals._translaterIrJrgrLrNr_rPrArRnarwhals.typingrSrTrUrVrWrXrYrZr[r\r]r^r_r`rarbrcrerfrgrhrirjrkrlrmror{rrrrrrrrrrrvrrrrrrrrrrrrrrrrr&r,r2r6r;r?r9rrWrjrrrrrrrrrrrrrrrrrrrrrrrrrrr"r?rErNrYr]r`rdrhrmrqrurrr~rrrrrrrsys version_inforrrrrrrwrxryrs" $" **4,*+,,--51.0148375:722:3.5 )-/+&+(123C4344>-92,,%&22/-&+237(7((+**ininfSk&Q RN B %.C %.C %.C %3 4C#A A B B8RxRNN2211 /  ,ox 00 \T 2 48 K~ 6 ==< i<  HZ(    x .  d2\+T\+@ :*EF""F:4Z 7 3 "5D   Q S(L" $,     -5     ""$?"" "  ..-H.(. .  (($J("( (  ::-S:4: :  #3   \ \K\\~!L,0XEI X X(X B X  Xv/d8 9 MP   2 2 $20:22j2DNL L(LL"&J   $L9   H  2"D YJ ' TU   #   6&&)-&/&R!$!$#-!$!$H<' ""3"F"+"*     .; IX   M? : T:R: : B:@: 7 07.7 ? 0?.? - N-L- 0)64 4&34=@44,'2. 7" 6>Q(Q(h$CCL$1'Arx