§
    cŠtjÄ$  ã            	      ó†  — 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mZ ddlZddl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. G d7„ d8ed9¬:¦  «        Z/ G d;„ d<e/d9¬:¦  «        Z0 G d=„ d>e/d9¬:¦  «        Z1 G d?„ d@e/d9¬:¦  «        Z2 G dA„ dBed9¬:¦  «        Z3 G dC„ dDe3d9¬:¦  «        Z4 G dE„ dFe3d9¬:¦  «        Z5 G dG„ dHe3d9¬:¦  «        Z6 G dI„ dJed9¬:¦  «        Z7 G dK„ dLe7d9¬:¦  «        Z8 G dM„ dNe7d9¬:¦  «        Z9 G dO„ dPe7d9¬:¦  «        Z: G dQ„ dRed9¬:¦  «        Z; G dS„ dTe;d9¬:¦  «        Z< G dU„ dVe;d9¬:¦  «        Z= G dW„ dXed9¬:¦  «        Z> G dY„ dZe>d9¬:¦  «        Z? G d[„ d\e>d9¬:¦  «        Z@ G d]„ d^e>d9¬:¦  «        ZA G d_„ d`ed9¬:¦  «        ZB G da„ dbeBd9¬:¦  «        ZC G dc„ ddeBd9¬:¦  «        ZD G de„ dfeBd9¬:¦  «        ZE G dg„ dhed9¬:¦  «        ZF G di„ djeFd9¬:¦  «        ZG G dk„ dleFd9¬:¦  «        ZH G dm„ dneFd9¬:¦  «        ZId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Ú	TypedDict)ÚTypeVar)Ú	TypeAliasN)ÚRequiredÚSelfÚTypeIsc                  ó   — e Zd Zddd„ZdS )	ÚArrowStreamExportableNÚrequested_schemaúobject | NoneÚreturnÚobjectc                ó   — d S ©N© )Úselfr   s     úQ/var/www/html/CA-Chatbot/venv/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)Ú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®   2  s6   € € € € € € ØÐÐÑØÐÐÑØÐÐÑÐÐr   r®   c                  ó   — e Zd ZU ded<   dS )ÚPassThroughUnknownrˆ   r|   Nrw   r   r   r   r°   r°   8  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´   A  s*   € € € € € € Ø$Ð$Ð$Ñ$Ø#Ð#Ð#Ñ#Ð#Ð#r   r´   )JÚ__doc__Ú
__future__r   Úcollections.abcr   r   Útypingr   r   r   r	   r
   Únarwhals._typing_compatr   r   ÚpyarrowÚpaÚtyping_extensionsr   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à +Ð +Ð +Ð +Ð +Ð +àð 9Ø Ð Ð Ð Ð Ð àÐÐÐØ8Ð8Ð8Ð8Ð8Ð8Ð8Ð8Ð8Ð8ð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Ð:Ñ:Ô:€ðð ð ð ð �˜.Ô)ñ ô ð ð(ð (ð (ð (ð (�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   