
    Wh              	         U d Z ddlmZ ddlmZmZ ddlmZmZm	Z	 ddl
mZ erddlZddlmZmZmZ  G d d	e	      Z ed
d      Z edde      Z edd      Z G d de	e         Z G d de	e         Z G d dee   ee   e	eef         Z edde      Z G d de	e         Z edeeef   dd      Z edeeef   deeef         Z G d d e	e         Z G d! d"e	e         Z G d# d$ee   ee   e	eef         Z d%Z!d&e"d'<   	  ed(d      Z# ed)de!      Z$ G d* d+e	e#         Z% G d, d-e	e$         Z& G d. d/e%e#   e&e$   e	e#e$f         Z' ed0      Z( G d1 d2e	e(         Z) ed3d      Z* G d4 d5e	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<Other>`
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<Other>`
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`.

## `<Other>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)IterableMapping)TYPE_CHECKINGAnyProtocol)TypeVarN)Self	TypeAliasTypeIsc                      e Zd ZdddZy)ArrowStreamExportableNc                     y N )selfrequested_schemas     M/var/www/html/jupyter_env/lib/python3.12/site-packages/narwhals/_translate.py__arrow_c_stream__z(ArrowStreamExportable.__arrow_c_stream__L           r   )r   zobject | Nonereturnobject)__name__
__module____qualname__r   r   r   r   r   r   K   s    Wr   r   ToNumpyT_coT)	covariantFromNumpyDT_contra)contravariantdefaultFromNumpyT_contra)r    c                      e Zd ZddZy)ToNumpyc                     y r   r   r   argskwdss      r   to_numpyzToNumpy.to_numpyW   r   r   N)r'   r   r(   r   r   r   r   r   r   r)   r   r   r   r$   r$   V       Cr   r$   c                      e Zd Zedd       Zy)	FromNumpyc                     y r   r   clsdatar'   r(   s       r   
from_numpyzFromNumpy.from_numpy[   s    SVr   N)r1   r"   r'   r   r(   r   r   r
   )r   r   r   classmethodr2   r   r   r   r-   r-   Z   s    V Vr   r-   c                      e Zd ZddZy)NumpyConvertiblec                    y r   r   )r   dtypecopys      r   r)   zNumpyConvertible.to_numpyd   r   r   N)r7   r   r8   zbool | Noner   r   r*   r   r   r   r5   r5   _   s    
 Mr   r5   FromIterableT_contrac                  .    e Zd Ze	 	 	 	 	 	 	 	 dd       Zy)FromIterablec                     y r   r   r/   s       r   from_iterablezFromIterable.from_iterablek   s     r   N)r1   zIterable[FromIterableT_contra]r'   r   r(   r   r   r
   )r   r   r   r3   r=   r   r   r   r;   r;   j   s4    1:=GJ	 r   r;   ToDictDT_cozdict[str, Any])boundr   r!   FromDictDT_contra)r?   r    r!   c                      e Zd ZddZy)ToDictc                     y r   r   r&   s      r   to_dictzToDict.to_dict}   r   r   N)r'   r   r(   r   r   r>   )r   r   r   rD   r   r   r   rB   rB   |   s    Br   rB   c                      e Zd Zedd       Zy)FromDictc                     y r   r   r/   s       r   	from_dictzFromDict.from_dict   s    RUr   N)r1   r@   r'   r   r(   r   r   r
   )r   r   r   r3   rH   r   r   r   rF   rF      s    U Ur   rF   c                      e Zd Zy)DictConvertibleNr   r   r   r   r   r   rJ   rJ           r   rJ   z ArrowStreamExportable | pa.Tabler   IntoArrowTableToArrowT_coFromArrowDT_contrac                      e Zd ZddZy)ToArrowc                     y r   r   r&   s      r   to_arrowzToArrow.to_arrow   r   r   N)r'   r   r(   r   r   rN   )r   r   r   rS   r   r   r   rQ   rQ      r+   r   rQ   c                      e Zd Zedd       Zy)	FromArrowc                     y r   r   r/   s       r   
from_arrowzFromArrow.from_arrow   s    TWr   N)r1   rO   r'   r   r(   r   r   r
   )r   r   r   r3   rW   r   r   r   rU   rU      s    W Wr   rU   c                      e Zd Zy)ArrowConvertibleNrK   r   r   r   rY   rY      rL   r   rY   FromNativeTc                  0    e Zd Zedd       Zedd       Zy)
FromNativec                     y r   r   r/   s       r   from_nativezFromNative.from_native   s    NQr   c                    y)z6Return `True` if `obj` can be passed to `from_native`.Nr   )objs    r   
_is_nativezFromNative._is_native   s     	r   N)r1   rZ   r'   r   r(   r   r   r
   )r`   zFromNativeT | Anyr   zTypeIs[FromNativeT])r   r   r   r3   r^   staticmethodra   r   r   r   r\   r\      s"    Q Q r   r\   ToNarwhalsT_coc                      e Zd ZddZy)
ToNarwhalsc                     y)z#Convert into public representation.Nr   )r   s    r   to_narwhalszToNarwhals.to_narwhals   s    r   N)r   rc   )r   r   r   rg   r   r   r   re   re      s    r   re   ),__doc__
__future__r   collections.abcr   r   typingr   r   r   narwhals._typing_compatr	   pyarrowpatyping_extensionsr
   r   r   r   r   r   r"   r$   r-   r5   r9   r;   strr>   r@   rB   rF   rJ   rM   __annotations__rN   rO   rQ   rU   rY   rZ   r\   rc   re   r   r   r   <module>rr      s5  <| # - / / +99XH X mt4k  /tD Dh{# DW*+ W
MK ![,,-M 5TSVW 801  c*dDT 
#s(
CH	 CXk" CVx)* V

;[++, ?	 >
 mt4n 
Dh{# DX+, X
K ![,,- m$+&  )T:.) r   