
    h              	         % S r SSKJr  SSKJrJr  SSKJrJrJ	r	  SSK
Jr  \(       a  SSKrSSKJrJrJr   " S S	\	5      r\" S
SS9r\" SS\S9r\" SSS9r " S S\	\   5      r " S S\	\   5      r " S S\\   \\   \	\\4   5      r\" SS\S9r " S S\	\   5      r\" S\\\4   SSS9r\" S\\\4   S\\\4   S9r " S S \	\   5      r " S! S"\	\   5      r " S# S$\\   \\   \	\\4   5      r S%r!S&\"S''    \" S(SS9r#\" S)S\!S9r$ " S* S+\	\#   5      r% " S, S-\	\$   5      r& " S. S/\%\#   \&\$   \	\#\$4   5      r'\" S05      r( " S1 S2\	\(   5      r)\" S3SS9r* " S4 S5\	\*   5      r+g)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                  "    \ rS rSrSSS jjrSrg)ArrowStreamExportableK   Nc                    g N )selfrequested_schemas     fC:\Users\julio\OneDrive\Documentos\Trabajo\Ideas Frescas\venv\Lib\site-packages\narwhals/_translate.py__arrow_c_stream__(ArrowStreamExportable.__arrow_c_stream__L   s    TW    r   r   )r   zobject | Nonereturnobject)__name__
__module____qualname____firstlineno__r   __static_attributes__r   r   r   r   r   K   s    WWr   r   ToNumpyT_coT)	covariantFromNumpyDT_contra)contravariantdefaultFromNumpyT_contra)r#   c                      \ rS rSrSS jrSrg)ToNumpyV   c                    g r   r   r   argskwdss      r   to_numpyToNumpy.to_numpyW       r   r   N)r+   r   r,   r   r   r    r   r   r   r   r-   r   r   r   r   r'   r'   V       Cr   r'   c                  (    \ rS rSr\SS j5       rSrg)	FromNumpyZ   c                    g r   r   clsdatar+   r,   s       r   
from_numpyFromNumpy.from_numpy[   s    SVr   r   N)r8   r%   r+   r   r,   r   r   r
   )r   r   r   r   classmethodr9   r   r   r   r   r3   r3   Z   s    V Vr   r3   c                      \ rS rSrSS jrSrg)NumpyConvertible_   c                   g r   r   )r   dtypecopys      r   r-   NumpyConvertible.to_numpyd   s    r   r   N)r@   r   rA   zbool | Noner   r    r0   r   r   r   r=   r=   _   s    
 Mr   r=   FromIterableT_contrac                  8    \ rS rSr\        SS j5       rSrg)FromIterablej   c                    g r   r   r6   s       r   from_iterableFromIterable.from_iterablek   s     r   r   N)r8   zIterable[FromIterableT_contra]r+   r   r,   r   r   r
   )r   r   r   r   r;   rH   r   r   r   r   rE   rE   j   s4    1:=GJ	 r   rE   ToDictDT_cozdict[str, Any])boundr!   r$   FromDictDT_contra)rK   r#   r$   c                      \ rS rSrSS jrSrg)ToDict|   c                    g r   r   r*   s      r   to_dictToDict.to_dict}   s    sr   r   N)r+   r   r,   r   r   rJ   )r   r   r   r   rQ   r   r   r   r   rN   rN   |   s    Br   rN   c                  (    \ rS rSr\SS j5       rSrg)FromDict   c                    g r   r   r6   s       r   	from_dictFromDict.from_dict   s    RUr   r   N)r8   rL   r+   r   r,   r   r   r
   )r   r   r   r   r;   rW   r   r   r   r   rT   rT      s    U Ur   rT   c                      \ rS rSrSrg)DictConvertible   r   Nr   r   r   r   r   r   r   r   rZ   rZ           r   rZ   z ArrowStreamExportable | pa.Tabler   IntoArrowTableToArrowT_coFromArrowDT_contrac                      \ rS rSrSS jrSrg)ToArrow   c                    g r   r   r*   s      r   to_arrowToArrow.to_arrow   r/   r   r   N)r+   r   r,   r   r   r_   )r   r   r   r   re   r   r   r   r   rb   rb      r1   r   rb   c                  (    \ rS rSr\SS j5       rSrg)	FromArrow   c                    g r   r   r6   s       r   
from_arrowFromArrow.from_arrow   s    TWr   r   N)r8   r`   r+   r   r,   r   r   r
   )r   r   r   r   r;   rk   r   r   r   r   rh   rh      s    W Wr   rh   c                      \ rS rSrSrg)ArrowConvertible   r   Nr\   r   r   r   rn   rn      r]   r   rn   FromNativeTc                  <    \ rS rSr\SS j5       r\SS j5       rSrg)
FromNative   c                    g r   r   r6   s       r   from_nativeFromNative.from_native   s    NQr   c                   g)z6Return `True` if `obj` can be passed to `from_native`.Nr   )objs    r   
_is_nativeFromNative._is_native   s     	r   r   N)r8   rp   r+   r   r,   r   r   r
   )rx   zFromNativeT | Anyr   zTypeIs[FromNativeT])	r   r   r   r   r;   ru   staticmethodry   r   r   r   r   rr   rr      s"    Q Q r   rr   ToNarwhalsT_coc                      \ rS rSrSS jrSrg)
ToNarwhals   c                    g)z#Convert into public representation.Nr   )r   s    r   to_narwhalsToNarwhals.to_narwhals   s    r   r   N)r   r|   )r   r   r   r   r   r   r   r   r   r~   r~      s    r   r~   ),__doc__
__future__r   collections.abcr   r   typingr   r   r   narwhals._typing_compatr	   pyarrowpatyping_extensionsr
   r   r   r   r    r"   r%   r'   r3   r=   rC   rE   strrJ   rL   rN   rT   rZ   r^   __annotations__r_   r`   rb   rh   rn   rp   rr   r|   r~   r   r   r   <module>r      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   