L i UdZddlmZddlmZmZddlmZmZm Z ddl m Z erddl Z ddlmZmZmZGdd e Ze d d Ze d d eZe dd ZGdde eZGdde eZGddeeeee eefZe dd eZGdde eZe deeefd dZe deeefd eeefZGdd e eZGd!d"e eZGd#d$eeeee eefZ d%Z!d&e"d'< e d(d Z#e d)d e!Z$Gd*d+e e#Z%Gd,d-e e$Z&Gd.d/e%e#e&e$e e#e$fZ'e d0Z(Gd1d2e e(Z)e d3d Z*Gd4d5e e*Z+y)6a [Protocols] defining conversion methods between representations. These come in 3 flavors and are [generic] to promote reuse. The following examples use the placeholder types `Narwhal` and `Other`: - `Narwhal`: some class written in `narwhals`. - `Other`: any other class, could be native, compliant, or a builtin. ## `To` When we want to convert or unwrap a `Narwhal` into an `Other`, we provide an **instance** method: ToOtherT_co = TypeVar("ToOtherT_co", covariant=True) class ToOther(Protocol[ToOtherT_co]): def to_other(self, *args: Any, **kwds: Any) -> ToOtherT_co: ... - `*args`, `**kwds` are defined to be *permissive* and allow a wider set of signatures when implementing. - In most cases, they are unused. - But come in handy when adapting an [upstream signature]. - We use a **covariant** `TypeVar`. ## `From` But what if we have `Other` and want to do the reverse? Our `Narwhal` will need to provide a `@classmethod`: FromOtherT_contra = TypeVar("FromOtherT_contra", contravariant=True) class FromOther(Protocol[FromOtherT_contra]): @classmethod def from_other(cls, data: FromOtherT_contra, *args: Any, **kwds: Any) -> Self: ... - `*args`, `**kwds` serve a similar purpose as before, but are much more frequently used. - We've added a **required** [positional-only] parameter `data` which will always be passed `Other`. - This removes the name from the contract of the protocol. - Implementations are free to use something more descriptive for documentation purposes. - We use a **contravariant** `TypeVar`. ## `Convertible` Combining our `to_` and `from_` methods allows us to convert in both directions `Narwhal` <-> `Other`: class OtherConvertible( ToOther[ToOtherT_co], FromOther[FromOtherT_contra], Protocol[ToOtherT_co, FromOtherT_contra], ): ... ## See Also Variance of `TypeVar`(s) can be tricky to wrap your head around. To learn more see [moist], [dry], or [even drier] - depending on how deep you wanna go. [Protocols]: https://typing.python.org/en/latest/spec/protocol.html [generic]: https://typing.python.org/en/latest/spec/generics.html [upstream signature]: https://numpy.org/doc/stable/user/basics.interoperability.html#the-array-method [positional-only]: https://peps.python.org/pep-0570/ [moist]: https://mypy.readthedocs.io/en/stable/generics.html#variance-of-generic-types [dry]: https://typing.python.org/en/latest/spec/generics.html#variance [even drier]: https://en.wikipedia.org/wiki/Covariance_and_contravariance_%28computer_science%29 ) annotations)IterableMapping) TYPE_CHECKINGAnyProtocol)TypeVarN)Self TypeAliasTypeIsceZdZdddZy)ArrowStreamExportableNcyN)selfrequested_schemas Y/mnt/ssd/data/python-lab/Trading/venv/lib/python3.12/site-packages/narwhals/_translate.py__arrow_c_stream__z(ArrowStreamExportable.__arrow_c_stream__Lr)rz object | Nonereturnobject)__name__ __module__ __qualname__rrrrrrKsWrr ToNumpyT_coT) covariantFromNumpyDT_contra) contravariantdefaultFromNumpyT_contra)r ceZdZddZy)ToNumpycyrrrargskwdss rto_numpyzToNumpy.to_numpyWrrN)r'rr(rrrrrrr)rrrr$r$VCrr$ceZdZeddZy) FromNumpycyrrclsdatar'r(s r from_numpyzFromNumpy.from_numpy[sSVrN)r1r"r'rr(rrr )rrr classmethodr2rrrr-r-ZsVVrr-ceZdZddZy)NumpyConvertiblecyrr)rdtypecopys rr)zNumpyConvertible.to_numpydrrN)r7rr8z bool | Nonerrr*rrrr5r5_s Mrr5FromIterableT_contrac.eZdZe ddZy) FromIterablecyrrr/s r from_iterablezFromIterable.from_iterableksrN)r1zIterable[FromIterableT_contra]r'rr(rrr )rrrr3r=rrrr;r;js41:=GJ rr; ToDictDT_cozdict[str, Any])boundrr!FromDictDT_contra)r?r r!ceZdZddZy)ToDictcyrrr&s rto_dictzToDict.to_dict}rrN)r'rr(rrr>)rrrrDrrrrBrB|sBrrBceZdZeddZy)FromDictcyrrr/s r from_dictzFromDict.from_dictsRUrN)r1r@r'rr(rrr )rrrr3rHrrrrFrFsUUrrFc eZdZy)DictConvertibleNrrrrrrrJrJrrJz ArrowStreamExportable | pa.Tabler IntoArrowTable ToArrowT_coFromArrowDT_contraceZdZddZy)ToArrowcyrrr&s rto_arrowzToArrow.to_arrowrrN)r'rr(rrrN)rrrrSrrrrQrQr+rrQceZdZeddZy) FromArrowcyrrr/s r from_arrowzFromArrow.from_arrowsTWrN)r1rOr'rr(rrr )rrrr3rWrrrrUrUsWWrrUc eZdZy)ArrowConvertibleNrKrrrrYrYrLrrY FromNativeTc0eZdZeddZeddZy) FromNativecyrrr/s r from_nativezFromNative.from_nativesNQrcy)z6Return `True` if `obj` can be passed to `from_native`.Nr)objs r _is_nativezFromNative._is_natives rN)r1rZr'rr(rrr )r`zFromNativeT | AnyrzTypeIs[FromNativeT])rrrr3r^ staticmethodrarrrr\r\s"QQ  rr\ToNarwhalsT_coceZdZddZy) ToNarwhalscy)z#Convert into public representation.Nr)rs r to_narwhalszToNarwhals.to_narwhalss rN)rrc)rrrrgrrrreres rre),__doc__ __future__rcollections.abcrrtypingrrrnarwhals._typing_compatr pyarrowpatyping_extensionsr r r rrrr"r$r-r5r9r;strr>r@rBrFrJrM__annotations__rNrOrQrUrYrZr\rcrerrrrrs5<|#-//+99XHXmt4 k/tDDh{#DW*+W M K  ! [, ,-M5TSVW801c*dDT  #s(  CH  CXk "CVx)*V  ;  [+ +,? > mt4 n Dh{#DX+,X  K  ! [, ,-m$  +& )T: .) r