
    }i$              	      ~   U d Z ddlmZ ddlmZmZ ddlmZmZ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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. G d6 d7ed89          Z/ G d: d;e/d89          Z0 G d< d=e/d89          Z1 G d> d?e/d89          Z2 G d@ dAed89          Z3 G dB dCe3d89          Z4 G dD dEe3d89          Z5 G dF dGe3d89          Z6 G dH dIed89          Z7 G dJ dKe7d89          Z8 G dL dMe7d89          Z9 G dN dOe7d89          Z: G dP dQed89          Z; G dR dSe;d89          Z< G dT dUe;d89          Z= G dV dWed89          Z> G dX dYe>d89          Z? G dZ d[e>d89          Z@ G d\ d]e>d89          ZA G d^ d_ed89          ZB G d` daeBd89          ZC G db dceBd89          ZD G dd deeBd89          ZE G df dged89          ZF G dh dieFd89          ZG G dj dkeFd89          ZH G dl dmeFd89          ZIdS )na
  [Protocols] defining conversion methods between representations, and related [structural] typing.

The protocols come in 3 flavors and are [generic] to promote reuse.

These 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
[structural]: https://typing.python.org/en/latest/spec/glossary.html#term-structural
[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LiteralProtocol	TypedDict)TypeVarN)RequiredSelf	TypeAliasTypeIsc                      e Zd ZdddZdS )	ArrowStreamExportableNrequested_schemaobject | Nonereturnobjectc                    d S N )selfr   s     G/home/jrussi/.local/lib/python3.11/site-packages/narwhals/_translate.py__arrow_c_stream__z(ArrowStreamExportable.__arrow_c_stream__M             r   )r   r   r   r   )__name__
__module____qualname__r   r   r   r   r   r   L   s        WWWWWWWr   r   ToNumpyT_coT)	covariantFromNumpyDT_contra)contravariantdefaultFromNumpyT_contra)r$   c                      e Zd ZddZdS )	ToNumpyargsr   kwdsr   r!   c                    d S r   r   r   r)   r*   s      r   to_numpyzToNumpy.to_numpyX   r   r   N)r)   r   r*   r   r   r!   r   r   r    r-   r   r   r   r(   r(   W           CCCCCCr   r(   c                  &    e Zd Zed
d            Zd	S )	FromNumpydatar&   r)   r   r*   r   r   c                    d S r   r   clsr2   r)   r*   s       r   
from_numpyzFromNumpy.from_numpy\   s    SVSVr   N)r2   r&   r)   r   r*   r   r   r   )r   r   r    classmethodr6   r   r   r   r1   r1   [   s&        VVV [VVVr   r1   c                      e Zd Zd	dZdS )
NumpyConvertibledtyper   copybool | Noner   r!   c                   d S r   r   )r   r:   r;   s      r   r-   zNumpyConvertible.to_numpye   r   r   N)r:   r   r;   r<   r   r!   r.   r   r   r   r9   r9   `   s        
 MLLLLLr   r9   FromIterableT_contrac                  &    e Zd Zed
d            Zd	S )FromIterabler2   Iterable[FromIterableT_contra]r)   r   r*   r   r   c                    d S r   r   r4   s       r   from_iterablezFromIterable.from_iterablel   s	     sr   N)r2   rA   r)   r   r*   r   r   r   )r   r   r    r7   rC   r   r   r   r@   r@   k   s2           [  r   r@   ToDictDT_cozdict[str, Any])boundr"   r%   FromDictDT_contra)rE   r$   r%   c                      e Zd ZddZdS )	ToDictr)   r   r*   r   rD   c                    d S r   r   r,   s      r   to_dictzToDict.to_dict~   r   r   N)r)   r   r*   r   r   rD   )r   r   r    rJ   r   r   r   rH   rH   }   s        BBBBBBr   rH   c                  &    e Zd Zed
d            Zd	S )FromDictr2   rF   r)   r   r*   r   r   c                    d S r   r   r4   s       r   	from_dictzFromDict.from_dict   s    RURUr   N)r2   rF   r)   r   r*   r   r   r   )r   r   r    r7   rN   r   r   r   rL   rL      s&        UUU [UUUr   rL   c                      e Zd ZdS )DictConvertibleNr   r   r    r   r   r   rP   rP               3r   rP   z ArrowStreamExportable | pa.Tabler   IntoArrowTableToArrowT_coFromArrowDT_contrac                      e Zd ZddZdS )	ToArrowr)   r   r*   r   rT   c                    d S r   r   r,   s      r   to_arrowzToArrow.to_arrow   r   r   N)r)   r   r*   r   r   rT   )r   r   r    rY   r   r   r   rW   rW      r/   r   rW   c                  &    e Zd Zed
d            Zd	S )	FromArrowr2   rU   r)   r   r*   r   r   c                    d S r   r   r4   s       r   
from_arrowzFromArrow.from_arrow   s    TWTWr   N)r2   rU   r)   r   r*   r   r   r   )r   r   r    r7   r]   r   r   r   r[   r[      s&        WWW [WWWr   r[   c                      e Zd ZdS )ArrowConvertibleNrQ   r   r   r   r_   r_      rR   r   r_   FromNativeTc                  >    e Zd Zedd            Zedd            ZdS )
FromNativer2   r`   r)   r   r*   r   r   c                    d S r   r   r4   s       r   from_nativezFromNative.from_native   s    NQcr   objFromNativeT | AnyTypeIs[FromNativeT]c                   dS )z6Return `True` if `obj` can be passed to `from_native`.Nr   )re   s    r   
_is_nativezFromNative._is_native   s	     	r   N)r2   r`   r)   r   r*   r   r   r   )re   rf   r   rg   )r   r   r    r7   rd   staticmethodri   r   r   r   rb   rb      sH        QQQ [Q   \  r   rb   ToNarwhalsT_coc                      e Zd ZddZdS )
ToNarwhalsr   rk   c                    dS )z#Convert into public representation.Nr   )r   s    r   to_narwhalszToNarwhals.to_narwhals   s    r   N)r   rk   )r   r   r    ro   r   r   r   rm   rm      s(             r   rm   c                  .    e Zd ZU ded<   ded<   ded<   dS )_ExcludeSeriesbool
eager_onlyLiteral[False]series_onlyzLiteral[False] | Noneallow_seriesNr   r   r    __annotations__r   r   r   rq   rq      s6         ''''''r   rq   F)totalc                      e Zd ZU ded<   dS )ExcludeSeriesrr   pass_throughNrw   r   r   r   r{   r{               r   r{   c                  $    e Zd ZU ded<   ded<   dS )ExcludeSeriesV1r<   r|   rt   eager_or_interchange_onlyNrw   r   r   r   r   r      *         ------r   r   c                  $    e Zd ZU ded<   ded<   dS )ExcludeSeriesStrictV1r<   strictrt   r   Nrw   r   r   r   r   r      *         ------r   r   c                  .    e Zd ZU ded<   ded<   ded<   dS )_AllowSeriesrr   rs   rt   ru   Required[Literal[True]]rv   Nrw   r   r   r   r   r      s6         ))))))r   r   c                      e Zd ZU ded<   dS )AllowSeriesrr   r|   Nrw   r   r   r   r   r      r}   r   r   c                  $    e Zd ZU ded<   ded<   dS )AllowSeriesV1r<   r|   rt   r   Nrw   r   r   r   r   r      r   r   r   c                  $    e Zd ZU ded<   ded<   dS )AllowSeriesStrictV1r<   r   rt   r   Nrw   r   r   r   r   r      r   r   r   c                  .    e Zd ZU ded<   ded<   ded<   dS )_OnlySeriesrr   rs   r   ru   r<   rv   Nrw   r   r   r   r   r      s6         ((((r   r   c                      e Zd ZU ded<   dS )
OnlySeriesrr   r|   Nrw   r   r   r   r   r      r}   r   r   c                  $    e Zd ZU ded<   ded<   dS )OnlySeriesV1r<   r|   rt   r   Nrw   r   r   r   r   r      r   r   r   c                  $    e Zd ZU ded<   ded<   dS )OnlySeriesStrictV1r<   r   rt   r   Nrw   r   r   r   r   r      r   r   r   c                  .    e Zd ZU ded<   ded<   ded<   dS )_OnlyEagerOrInterchanger   r   rt   ru   r<   rv   Nrw   r   r   r   r   r      s6         6666r   r   c                      e Zd ZU ded<   dS )OnlyEagerOrInterchanger<   r|   Nrw   r   r   r   r   r      s         r   r   c                      e Zd ZU ded<   dS )OnlyEagerOrInterchangeStrictr<   r   Nrw   r   r   r   r   r     s         r   r   c                  .    e Zd ZU ded<   ded<   ded<   dS )
_AllowLazyrt   rs   ru   r<   rv   Nrw   r   r   r   r   r     s6         r   r   c                      e Zd ZU ded<   dS )	AllowLazyrr   r|   Nrw   r   r   r   r   r     r}   r   r   c                  $    e Zd ZU ded<   ded<   dS )AllowLazyV1r<   r|   rt   r   Nrw   r   r   r   r   r     r   r   r   c                  $    e Zd ZU ded<   ded<   dS )AllowLazyStrictV1r<   r   rt   r   Nrw   r   r   r   r   r     r   r   r   c                  .    e Zd ZU ded<   ded<   ded<   dS )	_AllowAnyrt   rs   ru   r   rv   Nrw   r   r   r   r   r     s6         ))))))r   r   c                      e Zd ZU ded<   dS )AllowAnyrr   r|   Nrw   r   r   r   r   r   "  r}   r   r   c                  $    e Zd ZU ded<   ded<   dS )
AllowAnyV1r<   r|   rt   r   Nrw   r   r   r   r   r   &  r   r   r   c                  $    e Zd ZU ded<   ded<   dS )AllowAnyStrictV1r<   r   rt   r   Nrw   r   r   r   r   r   +  r   r   r   c                  .    e Zd ZU ded<   ded<   ded<   dS )_Unknownrr   rs   ru   r<   rv   Nrw   r   r   r   r   r   0  s6         r   r   c                      e Zd ZU ded<   dS )PassThroughUnknownr   r|   Nrw   r   r   r   r   r   6  s         ))))))r   r   c                  $    e Zd ZU ded<   ded<   dS )PassThroughUnknownV1r   r|   rr   r   Nrw   r   r   r   r   r   :  s*         ))))######r   r   c                  $    e Zd ZU ded<   ded<   dS )StrictUnknownV1zRequired[Literal[False]]r   rr   r   Nrw   r   r   r   r   r   ?  s*         $$$$######r   r   )J__doc__
__future__r   collections.abcr   r   typingr   r   r   r	   r
   narwhals._typing_compatr   pyarrowpatyping_extensionsr   r   r   r   r   r!   r#   r&   r(   r1   r9   r>   r@   strrD   rF   rH   rL   rP   rS   rx   rT   rU   rW   r[   r_   r`   rb   rk   rm   rq   r{   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   <module>r      s
  = = =~ # " " " " " - - - - - - - - C C C C C C C C C C C C C C + + + + + + DCCCCCCCCCCCCX X X X XH X X X gmt444Wk    G/tDDD D D D D Dh{# D D DW W W W W*+ W W W
M M M M MK ![,,-M M M w5TSVWWW     801    gc*dDT   G
#s(
CH	   C C C C CXk" C C CV V V V Vx)* V V V
    
;[++,   ? > > > >
 gmt444Wn   
D D D D Dh{# D D DX X X X X+, X X X
    K ![,,-   gm$$    +&    )T:::    .)   ( ( ( ( (Ye ( ( ( (    N%    . . . . .nE . . . .
. . . . .N% . . . .
* * * * *9E * * * *    ,e    . . . . .L . . . .
. . . . .,e . . . .
    )5        E    . . . . .;e . . . .
. . . . .E . . . .
    iu        4E        #:%        %        
%    . . . . .*E . . . .
. . . . .
% . . . .
* * * * *	 * * * *    y    . . . . .% . . . .
. . . . .y . . . .
    y    * * * * * * * * *$ $ $ $ $85 $ $ $ $
$ $ $ $ $he $ $ $ $ $ $r   