Ë
    ðmxi­$  ã            	      óÒ  — 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d8¬9«      Z/ G d:„ d;e/d8¬9«      Z0 G d<„ d=e/d8¬9«      Z1 G d>„ d?e/d8¬9«      Z2 G d@„ dAed8¬9«      Z3 G dB„ dCe3d8¬9«      Z4 G dD„ dEe3d8¬9«      Z5 G dF„ dGe3d8¬9«      Z6 G dH„ dIed8¬9«      Z7 G dJ„ dKe7d8¬9«      Z8 G dL„ dMe7d8¬9«      Z9 G dN„ dOe7d8¬9«      Z: G dP„ dQed8¬9«      Z; G dR„ dSe;d8¬9«      Z< G dT„ dUe;d8¬9«      Z= G dV„ dWed8¬9«      Z> G dX„ dYe>d8¬9«      Z? G dZ„ d[e>d8¬9«      Z@ G d\„ d]e>d8¬9«      ZA G d^„ d_ed8¬9«      ZB G d`„ daeBd8¬9«      ZC G db„ dceBd8¬9«      ZD G dd„ deeBd8¬9«      ZE G df„ dged8¬9«      ZF G dh„ dieFd8¬9«      ZG G dj„ dkeFd8¬9«      ZH G dl„ dmeFd8¬9«      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     úJ/home/htdocs/ttos/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ñ �m¨tÔ4€ÙØ¨°kôÐ ñ Ð/¸tÔDÐ ôDˆh�{Ñ#ô DôW�Ð*Ñ+ô Wô
MØˆKÑØÐ Ñ!Øˆ[Ð,Ð,Ñ-ôMñ Ð5ÀTÐSVÔWÐ ô�8Ð0Ñ1ô ñ Ø˜  c Ñ*°dÐDTô€ñ ØØ
�#�s�(Ñ
ØØ�C˜�HÑô	Ð ôCˆX�kÑ"ô CôVˆxÐ)Ñ*ô Vô
Ø
ˆ;ÑØÐÑØˆ[Ð+Ð+Ñ,ôð ?€�	Ó >ðñ
 �m¨tÔ4€ÙØ¨°nôÐ ô
Dˆh�{Ñ#ô DôX�Ð+Ñ,ô Xô
ØˆKÑØÐ Ñ!Øˆ[Ð,Ð,Ñ-ôñ �mÓ$€ô�˜+Ñ&ô ñ Ð)°TÔ:€ô�˜.Ñ)ô ô(�Y eõ (ô�N¨%õ ô.�n¨Eõ .ô
.˜N°%õ .ô
*�9 Eõ *ô�, eõ ô.�L¨õ .ô
.˜,¨eõ .ô
�) 5õ ô� Eõ ô.�; eõ .ô
.˜¨Eõ .ô
˜i¨uõ ôÐ4¸Eõ ôÐ#:À%õ ô� %õ ô�
 %õ ô.�* Eõ .ô
.˜
¨%õ .ô
*�	 õ *ôˆy õ ô.� %õ .ô
.�y¨õ .ô
ˆy õ ô*˜¨õ *ô$˜8¨5õ $ô
$�h eö $r   