§
    ÚóÉjc'  ã            	      óÆ  — 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
 ddlmZ erddlmZ 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/„ d0e(e&         e)e'         e
e&e'f         ¦  «        Z* ed1¦  «        Z+ G d2„ d3e
e+         ¦  «        Z, ed4d¬¦  «        Z- G d5„ d6e
e-         ¦  «        Z.e�rÍ G d7„ d8ed9d9¬:¦  «        Z/ G d;„ d<e/d9d¬:¦  «        Z0 G d=„ d>e/d9d¬:¦  «        Z1 G d?„ d@e/d9d¬:¦  «        Z2 G dA„ dBed9d9¬:¦  «        Z3 G dC„ dDe3d9d¬:¦  «        Z4 G dE„ dFe3d9d¬:¦  «        Z5 G dG„ dHe3d9d¬:¦  «        Z6 G dI„ dJed9d9¬:¦  «        Z7 G dK„ dLe7d9d¬:¦  «        Z8 G dM„ dNe7d9d¬:¦  «        Z9 G dO„ dPe7d9d¬:¦  «        Z: G dQ„ dRed9d9¬:¦  «        Z; G dS„ dTe;d9d¬:¦  «        Z< G dU„ dVe;d9d¬:¦  «        Z= G dW„ dXed9d9¬:¦  «        Z> G dY„ dZe>d9d¬:¦  «        Z? G d[„ d\e>d9d¬:¦  «        Z@ G d]„ d^e>d9d¬:¦  «        ZA G d_„ d`ed9d9¬:¦  «        ZB G da„ dbeBd9d¬:¦  «        ZC G dc„ ddeBd9d¬:¦  «        ZD G de„ dfeBd9d¬:¦  «        ZE G dg„ dhed9d9¬:¦  «        ZF G di„ djeFd9d¬:¦  «        ZG G dk„ dleFd9d¬:¦  «        ZH G dm„ dneFd9d¬:¦  «        ZIdS dS )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                  ó   — e Zd Zddd„ZdS )	ÚArrowStreamExportableNÚrequested_schemaúobject | NoneÚreturnÚobjectc                ó   — d S ©N© )Úselfr   s     úv/home/lighthouse/badge-speaker-benchmark/.benchmark-venv-community/lib/python3.11/site-packages/narwhals/_translate.pyÚ__arrow_c_stream__z(ArrowStreamExportable.__arrow_c_stream__O   ó   € € € ó    r   )r   r   r   r   )Ú__name__Ú
__module__Ú__qualname__r   r   r   r   r   r   N   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_numpyZ   r   r   N)r)   r   r*   r   r   r!   ©r   r   r    r-   r   r   r   r(   r(   Y   ó   € € € € € Ø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   € ØSVÐSVr   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_numpyg   r   r   N)r:   r   r;   r<   r   r!   r.   r   r   r   r9   r9   b   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_iterablen   s	   € ð ˆsr   N)r2   rA   r)   r   r*   r   r   r   )r   r   r    r7   rC   r   r   r   r@   r@   m   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   € ØRUÐRUr   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   € ØTWÐTWr   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   € ØNQÈcr   Ú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)ÚtotalÚclosedc                  ó   — 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€   Ê   ó*   € € € € € € Ø!Ð!Ð!Ñ!Ø1Ð1Ð1Ñ1Ð1Ð1r   r€   c                  ó$   — e Zd ZU ded<   ded<   dS )ÚExcludeSeriesStrictV1r<   Ústrictrt   r�   Nrw   r   r   r   r„   r„   Î   ó*   € € € € € € ØÐÐÑØ1Ð1Ð1Ñ1Ð1Ð1r   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   € € € € € € Ø:Ð:Ð:Ñ:Ø#Ð#Ð#Ñ#Ø!Ð!Ð!Ñ!Ð!Ð!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¯     s6   € € € € € € ØÐÐÑØÐÐÑØ!Ð!Ð!Ñ!Ð!Ð!r   r¯   c                  ó   — e Zd ZU ded<   dS )ÚPassThroughUnknownr‰   r}   Nrw   r   r   r   r±   r±   "  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	   Únarwhals._typing_compatr
   r   Ú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¿      so
  ðð=ð =ð =ð~ #Ð "Ð "Ð "Ð "Ð "à -Ð -Ð -Ð -Ð -Ð -Ð -Ð -Ø 8Ð 8Ð 8Ð 8Ð 8Ð 8Ð 8Ð 8Ð 8Ð 8Ð 8Ð 8à +Ð +Ð +Ð +Ð +Ð +àð DØ Ð Ð Ð Ð Ð àÐÐÐØCÐCÐCÐCÐCÐCÐCÐCÐCÐCÐCÐCðXð Xð Xð Xð X˜Hñ Xô Xð Xð ˆg�m¨tÐ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Ð5ÀTÐSVÐWÑWÔWÐ ðð ð ð ð �8Ð0Ô1ñ ô ð ð ˆgØ˜  c Ô*°dÐDTðñ ô €ð �GØØ
�#�s�(Ô
ØØ�C˜�HÔð	ñ ô Ð ðCð Cð Cð Cð CˆX�kÔ"ñ Cô Cð CðVð Vð Vð Vð VˆxÐ)Ô*ñ Vô Vð Vð
ð ð ð ð Ø
ˆ;ÔØÐÔØˆ[Ð+Ð+Ô,ñô ð ð ?€Ð >Ð >Ð >Ñ >ðð
 ˆg�m¨tÐ4Ñ4Ô4€Ø�WØ¨°nðñ ô Ð ð
Dð Dð Dð Dð Dˆh�{Ô#ñ Dô Dð DðXð Xð Xð Xð X�Ð+Ô,ñ Xô Xð Xð
ð ð ð ð ØˆKÔØÐ Ô!Øˆ[Ð,Ð,Ô-ñô ð ð ˆg�mÑ$Ô$€ðð ð ð ð �˜+Ô&ñ ô ð ð �Ð)°TÐ:Ñ:Ô:€ðð ð ð ð �˜.Ô)ñ ô ð ð ñ k(ð,ð ,ð ,ð ,ð ,˜¨%¸ð ,ñ ,ô ,ð ,ð
ð ð ð ð ˜¨e¸Dð ñ ô ð ð2ð 2ð 2ð 2ð 2˜.°¸dð 2ñ 2ô 2ð 2ð2ð 2ð 2ð 2ð 2 °eÀDð 2ñ 2ô 2ð 2ð.ð .ð .ð .ð .�y¨°eð .ñ .ô .ð .ð
ð ð ð ð �l¨%¸ð ñ ô ð ð2ð 2ð 2ð 2ð 2˜¨E¸$ð 2ñ 2ô 2ð 2ð2ð 2ð 2ð 2ð 2˜l°%Àð 2ñ 2ô 2ð 2ð"ð "ð "ð "ð "�i u°Uð "ñ "ô "ð "ð
ð ð ð ð �[¨°dð ñ ô ð ð2ð 2ð 2ð 2ð 2�{¨%¸ð 2ñ 2ô 2ð 2ð2ð 2ð 2ð 2ð 2˜[°¸dð 2ñ 2ô 2ð 2ð"ð "ð "ð "ð " )°5Àð "ñ "ô "ð "ð
"ð "ð "ð "ð "Ð!8ÀÈdð "ñ "ô "ð "ðð ð ð ð Ð'>ÀeÐTXð ñ ô ð ð"ð "ð "ð "ð "�Y e°Eð "ñ "ô "ð "ð
ð ð ð ð �J e°Dð ñ ô ð ð2ð 2ð 2ð 2ð 2�j¨°dð 2ñ 2ô 2ð 2ð2ð 2ð 2ð 2ð 2˜J¨e¸Dð 2ñ 2ô 2ð 2ð.ð .ð .ð .ð .�I U°5ð .ñ .ô .ð .ð
ð ð ð ð �9 E°$ð ñ ô ð ð2ð 2ð 2ð 2ð 2�Y e°Dð 2ñ 2ô 2ð 2ð2ð 2ð 2ð 2ð 2˜9¨E¸$ð 2ñ 2ô 2ð 2ð"ð "ð "ð "ð "�9 E°%ð "ñ "ô "ð "ð
.ð .ð .ð .ð .˜X¨U¸4ð .ñ .ô .ð .ð(ð (ð (ð (ð (˜x¨u¸Tð (ñ (ô (ð (ð(ð (ð (ð (ð (˜(¨%¸ð (ñ (ô (ð (ð (ð (ðSk(ð k(r   