ó
    - jc'  ã            	      óT  • % S r SSKJr  SSKJrJr  SSKJrJrJ	r	J
r
  SSKJr  \(       a  SSKJr  SSKrSSKJr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/ S0\(\&   \)\'   \
\&\'4   5      r*\" S15      r+ " S2 S3\
\+   5      r,\" S4SS9r- " S5 S6\
\-   5      r.\(       Ga*   " S7 S8\S9S9S:9r/ " S; S<\/S9SS:9r0 " S= S>\/S9SS:9r1 " S? S@\/S9SS:9r2 " SA SB\S9S9S:9r3 " SC SD\3S9SS:9r4 " SE SF\3S9SS:9r5 " SG SH\3S9SS:9r6 " SI SJ\S9S9S:9r7 " SK SL\7S9SS:9r8 " SM SN\7S9SS:9r9 " SO SP\7S9SS:9r: " SQ SR\S9S9S:9r; " SS ST\;S9SS:9r< " SU SV\;S9SS:9r= " SW SX\S9S9S:9r> " SY SZ\>S9SS:9r? " S[ S\\>S9SS:9r@ " S] S^\>S9SS:9rA " S_ S`\S9S9S:9rB " Sa Sb\BS9SS:9rC " Sc Sd\BS9SS:9rD " Se Sf\BS9SS:9rE " Sg Sh\S9S9S:9rF " Si Sj\FS9SS:9rG " Sk Sl\FS9SS:9rH " Sm Sn\FS9SS:9rIgg)oa–
  [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)ÚTypeVar)Ú	TypeAliasN)ÚRequiredÚSelfÚ	TypedDictÚTypeIsc                  ó"   • \ rS rSrSSS jjrSrg)ÚArrowStreamExportableéN   Nc                ó   • g ©N© )ÚselfÚrequested_schemas     Ú¡C:\Users\johnn\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\site-packages\narwhals/_translate.pyÚ__arrow_c_stream__Ú(ArrowStreamExportable.__arrow_c_stream__O   s   € ÐTWó    r   r   )r   zobject | NoneÚreturnÚobject)Ú__name__Ú
__module__Ú__qualname__Ú__firstlineno__r   Ú__static_attributes__r   r   r   r   r   N   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)ÚToNumpyéY   c                ó   • g r   r   ©r   ÚargsÚkwdss      r   Úto_numpyÚToNumpy.to_numpyZ   ó   € Àr   r   N)r.   r   r/   r   r   r#   ©r   r   r    r!   r0   r"   r   r   r   r*   r*   Y   ó   † ßCr   r*   c                  ó(   • \ rS rSr\SS j5       rSrg)Ú	FromNumpyé]   c                ó   • g r   r   ©ÚclsÚdatar.   r/   s       r   Ú
from_numpyÚFromNumpy.from_numpy^   s   € ØSVr   r   N)r;   r(   r.   r   r/   r   r   r   )r   r   r    r!   Úclassmethodr<   r"   r   r   r   r6   r6   ]   s   † ØÛVó ÛVr   r6   c                  ó   • \ rS rSrSS jrSrg)ÚNumpyConvertibleéb   c               ó   • g r   r   )r   ÚdtypeÚcopys      r   r0   ÚNumpyConvertible.to_numpyg   s   € Èr   r   N)rC   r   rD   úbool | Noner   r#   r3   r   r   r   r@   r@   b   s   † ÷
 Mr   r@   ÚFromIterableT_contrac                  ó8   • \ rS rSr\        SS j5       rSrg)ÚFromIterableém   c                ó   • g r   r   r9   s       r   Úfrom_iterableÚFromIterable.from_iterablen   s   € ð r   r   N)r;   zIterable[FromIterableT_contra]r.   r   r/   r   r   r   )r   r   r    r!   r>   rL   r"   r   r   r   rI   rI   m   s4   † ØðØ1ðØ:=ðØGJðà	óó ór   rI   ÚToDictDT_cozdict[str, Any])Úboundr$   r'   ÚFromDictDT_contra)rO   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   rN   )r   r   r    r!   rU   r"   r   r   r   rR   rR      s   † ßBr   rR   c                  ó(   • \ rS rSr\SS j5       rSrg)ÚFromDictéƒ   c                ó   • g r   r   r9   s       r   Ú	from_dictÚFromDict.from_dict„   s   € ØRUr   r   N)r;   rP   r.   r   r/   r   r   r   )r   r   r    r!   r>   r[   r"   r   r   r   rX   rX   ƒ   s   † ØÛUó ÛUr   rX   c                  ó   • \ rS rSrSrg)ÚDictConvertibleéˆ   r   N©r   r   r    r!   r"   r   r   r   r^   r^   ˆ   ó   † ò r   r^   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œ   r2   r   r   N)r.   r   r/   r   r   rc   )r   r   r    r!   ri   r"   r   r   r   rf   rf   ›   r4   r   rf   c                  ó(   • \ rS rSr\SS j5       rSrg)Ú	FromArrowéŸ   c                ó   • g r   r   r9   s       r   Ú
from_arrowÚFromArrow.from_arrow    s   € ØTWr   r   N)r;   rd   r.   r   r/   r   r   r   )r   r   r    r!   r>   ro   r"   r   r   r   rl   rl   Ÿ   s   † ØÛWó ÛWr   rl   c                  ó   • \ rS rSrSrg)ÚArrowConvertibleé¤   r   Nr`   r   r   r   rr   rr   ¤   ra   r   rr   ÚFromNativeTc                  ó<   • \ rS rSr\SS j5       r\SS j5       rSrg)Ú
FromNativeé®   c                ó   • g r   r   r9   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)r;   rt   r.   r   r/   r   r   r   )r|   zFromNativeT | Anyr   zTypeIs[FromNativeT])	r   r   r    r!   r>   ry   Ústaticmethodr}   r"   r   r   r   rv   rv   ®   s"   † ØÛQó ØQØóó ór   rv   Ú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‚   c                  ó4   • \ rS rSr% S\S'   S\S'   S\S'   Srg	)
Ú_ExcludeSerieséÂ   ÚboolÚ
eager_onlyúLiteral[False]Úseries_onlyzLiteral[False] | NoneÚallow_seriesr   N©r   r   r    r!   Ú__annotations__r"   r   r   r   rˆ   rˆ   Â   s   ‡ ØÓØ#Ó#Ø+Ö+r   rˆ   F)ÚtotalÚclosedc                  ó    • \ rS rSr% S\S'   Srg)ÚExcludeSerieséÇ   rŠ   Úpass_throughr   Nr�   r   r   r   r”   r”   Ç   ó   ‡ ØÖr   r”   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚExcludeSeriesV1éÊ   rF   r–   rŒ   Úeager_or_interchange_onlyr   Nr�   r   r   r   r™   r™   Ê   ó   ‡ Ø!Ó!Ø#1Ö1r   r™   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚExcludeSeriesStrictV1éÎ   rF   ÚstrictrŒ   r›   r   Nr�   r   r   r   rž   rž   Î   ó   ‡ ØÓØ#1Ö1r   rž   c                  ó4   • \ rS rSr% S\S'   S\S'   S\S'   Srg	)
Ú_AllowSerieséÒ   rŠ   r‹   rŒ   r�   úRequired[Literal[True]]rŽ   r   Nr�   r   r   r   r£   r£   Ò   s   ‡ ØÓØ#Ó#Ø-Ö-r   r£   c                  ó    • \ rS rSr% S\S'   Srg)ÚAllowSeriesé×   rŠ   r–   r   Nr�   r   r   r   r§   r§   ×   r—   r   r§   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚAllowSeriesV1éÚ   rF   r–   rŒ   r›   r   Nr�   r   r   r   rª   rª   Ú   rœ   r   rª   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚAllowSeriesStrictV1éÞ   rF   r    rŒ   r›   r   Nr�   r   r   r   r­   r­   Þ   r¡   r   r­   c                  ó4   • \ rS rSr% S\S'   S\S'   S\S'   Srg	)
Ú_OnlySerieséâ   rŠ   r‹   r¥   r�   rF   rŽ   r   Nr�   r   r   r   r°   r°   â   s   ‡ ØÓØ,Ó,Ø!Ö!r   r°   c                  ó    • \ rS rSr% S\S'   Srg)Ú
OnlySerieséç   rŠ   r–   r   Nr�   r   r   r   r³   r³   ç   r—   r   r³   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚOnlySeriesV1éê   rF   r–   rŒ   r›   r   Nr�   r   r   r   r¶   r¶   ê   rœ   r   r¶   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚOnlySeriesStrictV1éî   rF   r    rŒ   r›   r   Nr�   r   r   r   r¹   r¹   î   r¡   r   r¹   c                  ó4   • \ rS rSr% S\S'   S\S'   S\S'   Srg	)
Ú_OnlyEagerOrInterchangeéò   r¥   r›   rŒ   r�   rF   rŽ   r   Nr�   r   r   r   r¼   r¼   ò   s   ‡ Ø#:Ó:Ø#Ó#Ø!Ö!r   r¼   c                  ó    • \ rS rSr% S\S'   Srg)ÚOnlyEagerOrInterchangeé÷   rF   r–   r   Nr�   r   r   r   r¿   r¿   ÷   s   ‡ Ø!Ö!r   r¿   c                  ó    • \ rS rSr% S\S'   Srg)ÚOnlyEagerOrInterchangeStrictéú   rF   r    r   Nr�   r   r   r   rÂ   rÂ   ú   s   ‡ ØÖr   rÂ   c                  ó4   • \ rS rSr% S\S'   S\S'   S\S'   Srg)	Ú
_AllowLazyéý   rŒ   r‹   r�   rF   rŽ   r   Nr�   r   r   r   rÅ   rÅ   ý   s   ‡ Ø"Ó"Ø#Ó#Ø!Ö!r   rÅ   c                  ó    • \ rS rSr% S\S'   Srg)Ú	AllowLazyi  rŠ   r–   r   Nr�   r   r   r   rÈ   rÈ     r—   r   rÈ   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚAllowLazyV1i  rF   r–   rŒ   r›   r   Nr�   r   r   r   rÊ   rÊ     rœ   r   rÊ   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚAllowLazyStrictV1i	  rF   r    rŒ   r›   r   Nr�   r   r   r   rÌ   rÌ   	  r¡   r   rÌ   c                  ó4   • \ rS rSr% S\S'   S\S'   S\S'   Srg)	Ú	_AllowAnyi  rŒ   r‹   r�   r¥   rŽ   r   Nr�   r   r   r   rÎ   rÎ     s   ‡ Ø"Ó"Ø#Ó#Ø-Ö-r   rÎ   c                  ó    • \ rS rSr% S\S'   Srg)ÚAllowAnyi  rŠ   r–   r   Nr�   r   r   r   rÐ   rÐ     r—   r   rÐ   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)Ú
AllowAnyV1i  rF   r–   rŒ   r›   r   Nr�   r   r   r   rÒ   rÒ     rœ   r   rÒ   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚAllowAnyStrictV1i  rF   r    rŒ   r›   r   Nr�   r   r   r   rÔ   rÔ     r¡   r   rÔ   c                  ó4   • \ rS rSr% S\S'   S\S'   S\S'   Srg)	Ú_Unknowni  rŠ   r‹   r�   rF   rŽ   r   Nr�   r   r   r   rÖ   rÖ     s   ‡ ØÓØÓØ!Ö!r   rÖ   c                  ó    • \ rS rSr% S\S'   Srg)ÚPassThroughUnknowni"  r¥   r–   r   Nr�   r   r   r   rØ   rØ   "  s   ‡ Ø-Ö-r   rØ   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚPassThroughUnknownV1i%  r¥   r–   rŠ   r›   r   Nr�   r   r   r   rÚ   rÚ   %  s   ‡ Ø-Ó-Ø#'Ö'r   rÚ   c                  ó*   • \ rS rSr% S\S'   S\S'   Srg)ÚStrictUnknownV1i)  zRequired[Literal[False]]r    rŠ   r›   r   Nr�   r   r   r   rÜ   rÜ   )  s   ‡ Ø(Ó(Ø#'Ö'r   rÜ   )JÚ__doc__Ú
__future__r   Úcollections.abcr   r   Útypingr   r   r   r	   Únarwhals._typing_compatr
   r   ÚpyarrowÚpaÚtyping_extensionsr   r   r   r   r   r#   r%   r(   r*   r6   r@   rG   rI   ÚstrrN   rP   rR   rX   r^   rb   r�   rc   rd   rf   rl   rr   rt   rv   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Ü   r   r   r   Ú<module>ræ      sö  ðò=õ~ #ç -ß 8Ó 8å +æÝ ãß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Ñ:€ô�˜.Ñ)ô ÷ ô,˜¨%¸ò ,ô
˜¨e¸Dò ô2˜.°¸dò 2ô2 °eÀDò 2ô.�y¨°eò .ô
�l¨%¸ò ô2˜¨E¸$ò 2ô2˜l°%Àò 2ô"�i u°Uò "ô
�[¨°dò ô2�{¨%¸ò 2ô2˜[°¸dò 2ô" )°5Àò "ô
"Ð!8ÀÈdò "ôÐ'>ÀeÐTXò ô"�Y e°Eò "ô
�J e°Dò ô2�j¨°dò 2ô2˜J¨e¸Dò 2ô.�I U°5ò .ô
�9 E°$ò ô2�Y e°Dò 2ô2˜9¨E¸$ò 2ô"�9 E°%ò "ô
.˜X¨U¸4ò .ô(˜x¨u¸Tò (ô(˜(¨%¸ó (ðS r   