
    /_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      ZIy)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y)ArrowStreamExportableNc                     y N )selfrequested_schemas     R/var/www/html/land_sniper/venv/lib/python3.12/site-packages/narwhals/_translate.py__arrow_c_stream__z(ArrowStreamExportable.__arrow_c_stream__M           r   )r   zobject | Nonereturnobject)__name__
__module____qualname__r   r   r   r   r   r   L   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_numpyX   r   r   N)r*   r   r+   r   r   r    r   r   r   r,   r   r   r   r'   r'   W       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)r4   r%   r*   r   r+   r   r   r   )r   r   r   classmethodr5   r   r   r   r0   r0   [   s    V Vr   r0   c                      e Zd ZddZy)NumpyConvertiblec                    y r   r   )r   dtypecopys      r   r,   zNumpyConvertible.to_numpye   r   r   N)r:   r   r;   bool | Noner   r    r-   r   r   r   r8   r8   `   s    
 Mr   r8   FromIterableT_contrac                  .    e Zd Ze	 	 	 	 	 	 	 	 dd       Zy)FromIterablec                     y r   r   r2   s       r   from_iterablezFromIterable.from_iterablel   s     r   N)r4   zIterable[FromIterableT_contra]r*   r   r+   r   r   r   )r   r   r   r6   rA   r   r   r   r?   r?   k   s4    1:=GJ	 r   r?   ToDictDT_cozdict[str, Any])boundr!   r$   FromDictDT_contra)rC   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   rB   )r   r   r   rH   r   r   r   rF   rF   }   s    Br   rF   c                      e Zd Zedd       Zy)FromDictc                     y r   r   r2   s       r   	from_dictzFromDict.from_dict   s    RUr   N)r4   rD   r*   r   r+   r   r   r   )r   r   r   r6   rL   r   r   r   rJ   rJ      s    U Ur   rJ   c                      e Zd Zy)DictConvertibleNr   r   r   r   r   r   rN   rN           r   rN   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   rR   )r   r   r   rW   r   r   r   rU   rU      r.   r   rU   c                      e Zd Zedd       Zy)	FromArrowc                     y r   r   r2   s       r   
from_arrowzFromArrow.from_arrow   s    TWr   N)r4   rS   r*   r   r+   r   r   r   )r   r   r   r6   r[   r   r   r   rY   rY      s    W Wr   rY   c                      e Zd Zy)ArrowConvertibleNrO   r   r   r   r]   r]      rP   r   r]   FromNativeTc                  0    e Zd Zedd       Zedd       Zy)
FromNativec                     y r   r   r2   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)r4   r^   r*   r   r+   r   r   r   )rd   zFromNativeT | Anyr   zTypeIs[FromNativeT])r   r   r   r6   rb   staticmethodre   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   rg   )r   r   r   rk   r   r   r   ri   ri      s    r   ri   c                  ,    e Zd ZU ded<   ded<   ded<   y)_ExcludeSeriesbool
eager_onlyLiteral[False]series_onlyzLiteral[False] | Noneallow_seriesNr   r   r   __annotations__r   r   r   rm   rm      s    ''r   rm   F)totalc                      e Zd ZU ded<   y)ExcludeSeriesrn   pass_throughNrs   r   r   r   rw   rw          r   rw   c                  "    e Zd ZU ded<   ded<   y)ExcludeSeriesV1r<   rx   rp   eager_or_interchange_onlyNrs   r   r   r   r{   r{          --r   r{   c                  "    e Zd ZU ded<   ded<   y)ExcludeSeriesStrictV1r<   strictrp   r|   Nrs   r   r   r   r   r          --r   r   c                  ,    e Zd ZU ded<   ded<   ded<   y)_AllowSeriesrn   ro   rp   rq   Required[Literal[True]]rr   Nrs   r   r   r   r   r      s    ))r   r   c                      e Zd ZU ded<   y)AllowSeriesrn   rx   Nrs   r   r   r   r   r      ry   r   r   c                  "    e Zd ZU ded<   ded<   y)AllowSeriesV1r<   rx   rp   r|   Nrs   r   r   r   r   r      r}   r   r   c                  "    e Zd ZU ded<   ded<   y)AllowSeriesStrictV1r<   r   rp   r|   Nrs   r   r   r   r   r      r   r   r   c                  ,    e Zd ZU ded<   ded<   ded<   y)_OnlySeriesrn   ro   r   rq   r<   rr   Nrs   r   r   r   r   r      s    ((r   r   c                      e Zd ZU ded<   y)
OnlySeriesrn   rx   Nrs   r   r   r   r   r      ry   r   r   c                  "    e Zd ZU ded<   ded<   y)OnlySeriesV1r<   rx   rp   r|   Nrs   r   r   r   r   r      r}   r   r   c                  "    e Zd ZU ded<   ded<   y)OnlySeriesStrictV1r<   r   rp   r|   Nrs   r   r   r   r   r      r   r   r   c                  ,    e Zd ZU ded<   ded<   ded<   y)_OnlyEagerOrInterchanger   r|   rp   rq   r<   rr   Nrs   r   r   r   r   r      s    66r   r   c                      e Zd ZU ded<   y)OnlyEagerOrInterchanger<   rx   Nrs   r   r   r   r   r      s    r   r   c                      e Zd ZU ded<   y)OnlyEagerOrInterchangeStrictr<   r   Nrs   r   r   r   r   r     s    r   r   c                  ,    e Zd ZU ded<   ded<   ded<   y)
_AllowLazyrp   ro   rq   r<   rr   Nrs   r   r   r   r   r     s    r   r   c                      e Zd ZU ded<   y)	AllowLazyrn   rx   Nrs   r   r   r   r   r     ry   r   r   c                  "    e Zd ZU ded<   ded<   y)AllowLazyV1r<   rx   rp   r|   Nrs   r   r   r   r   r     r}   r   r   c                  "    e Zd ZU ded<   ded<   y)AllowLazyStrictV1r<   r   rp   r|   Nrs   r   r   r   r   r     r   r   r   c                  ,    e Zd ZU ded<   ded<   ded<   y)	_AllowAnyrp   ro   rq   r   rr   Nrs   r   r   r   r   r     s    ))r   r   c                      e Zd ZU ded<   y)AllowAnyrn   rx   Nrs   r   r   r   r   r   "  ry   r   r   c                  "    e Zd ZU ded<   ded<   y)
AllowAnyV1r<   rx   rp   r|   Nrs   r   r   r   r   r   &  r}   r   r   c                  "    e Zd ZU ded<   ded<   y)AllowAnyStrictV1r<   r   rp   r|   Nrs   r   r   r   r   r   +  r   r   r   c                  ,    e Zd ZU ded<   ded<   ded<   y)_Unknownrn   ro   rq   r<   rr   Nrs   r   r   r   r   r   0  s    r   r   c                      e Zd ZU ded<   y)PassThroughUnknownr   rx   Nrs   r   r   r   r   r   6  s    ))r   r   c                  "    e Zd ZU ded<   ded<   y)PassThroughUnknownV1r   rx   rn   r|   Nrs   r   r   r   r   r   :  s    ))##r   r   c                  "    e Zd ZU ded<   ded<   y)StrictUnknownV1zRequired[Literal[False]]r   rn   r|   Nrs   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'   r0   r8   r=   r?   strrB   rD   rF   rJ   rN   rQ   rt   rR   rS   rU   rY   r]   r^   r`   rg   ri   rm   rw   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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:.) (Ye (N% .nE .
.N% .
*9E *,e .L .
.,e .
)5 E .;e .
.E .
iu 4E #:% % 
% .*E .
.
% .
*	 *y .% .
.y .
y * *$85 $
$he $r   