§
    Šhþhà  ã            	      ó  — U d Z ddlmZ ddlmZmZ ddl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  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+dS )6a 
  [Protocols] defining conversion methods between representations.

These come in 3 flavors and are [generic] to promote reuse.

The following 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
[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ÚProtocol)ÚTypeVarN)ÚSelfÚ	TypeAliasÚTypeIsc                  ó   — e Zd Zddd„ZdS )	ÚArrowStreamExportableNÚrequested_schemaúobject | NoneÚreturnÚobjectc                ó   — d S ©N© )Úselfr   s     úJ/var/www/histauto/venv/lib/python3.11/site-packages/narwhals/_translate.pyÚ__arrow_c_stream__z(ArrowStreamExportable.__arrow_c_stream__L   ó   € € € ó    r   )r   r   r   r   )Ú__name__Ú
__module__Ú__qualname__r   r   r   r   r   r   K   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_numpyW   r   r   N)r&   r   r'   r   r   r   ©r   r   r   r*   r   r   r   r%   r%   V   ó   € € € € € Ø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   ©Úclsr/   r&   r'   s       r   Ú
from_numpyzFromNumpy.from_numpy[   s   € ØSVÐSVr   N)r/   r#   r&   r   r'   r   r   r
   )r   r   r   Úclassmethodr3   r   r   r   r.   r.   Z   s&   € € € € € ØØVÐVÐVñ „[ØVÐVÐVr   r.   c                  ó   — e Zd Zd	d„ZdS )
ÚNumpyConvertibleÚdtyper   Úcopyúbool | Noner   r   c               ó   — d S r   r   )r   r7   r8   s      r   r*   zNumpyConvertible.to_numpyd   r   r   N)r7   r   r8   r9   r   r   r+   r   r   r   r6   r6   _   s   € € € € € ð
 MÐLÐLÐLÐLÐLr   r6   ÚFromIterableT_contrac                  ó&   — e Zd Zed
d„¦   «         Zd	S )ÚFromIterabler/   úIterable[FromIterableT_contra]r&   r   r'   r   r
   c                ó   — d S r   r   r1   s       r   Úfrom_iterablezFromIterable.from_iterablek   s	   € ð ˆsr   N)r/   r>   r&   r   r'   r   r   r
   )r   r   r   r4   r@   r   r   r   r=   r=   j   s2   € € € € € Øðð ð ñ „[ðð ð r   r=   ÚToDictDT_cozdict[str, Any])Úboundr   r"   ÚFromDictDT_contra)rB   r!   r"   c                  ó   — e Zd Zdd„ZdS )	ÚToDictr&   r   r'   r   rA   c                ó   — d S r   r   r)   s      r   Úto_dictzToDict.to_dict}   r   r   N)r&   r   r'   r   r   rA   )r   r   r   rG   r   r   r   rE   rE   |   s   € € € € € ØBÐBÐBÐBÐBÐBr   rE   c                  ó&   — e Zd Zed
d„¦   «         Zd	S )ÚFromDictr/   rC   r&   r   r'   r   r
   c                ó   — d S r   r   r1   s       r   Ú	from_dictzFromDict.from_dict�   s   € ØRUÐRUr   N)r/   rC   r&   r   r'   r   r   r
   )r   r   r   r4   rK   r   r   r   rI   rI   €   s&   € € € € € ØØUÐUÐUñ „[ØUÐUÐUr   rI   c                  ó   — e Zd ZdS )ÚDictConvertibleN©r   r   r   r   r   r   rM   rM   …   ó   € € € € € ð €3r   rM   z ArrowStreamExportable | pa.Tabler   ÚIntoArrowTableÚToArrowT_coÚFromArrowDT_contrac                  ó   — e Zd Zdd„ZdS )	ÚToArrowr&   r   r'   r   rQ   c                ó   — d S r   r   r)   s      r   Úto_arrowzToArrow.to_arrow™   r   r   N)r&   r   r'   r   r   rQ   )r   r   r   rV   r   r   r   rT   rT   ˜   r,   r   rT   c                  ó&   — e Zd Zed
d„¦   «         Zd	S )Ú	FromArrowr/   rR   r&   r   r'   r   r
   c                ó   — d S r   r   r1   s       r   Ú
from_arrowzFromArrow.from_arrow�   s   € ØTWÐTWr   N)r/   rR   r&   r   r'   r   r   r
   )r   r   r   r4   rZ   r   r   r   rX   rX   œ   s&   € € € € € ØØWÐWÐWñ „[ØWÐWÐWr   rX   c                  ó   — e Zd ZdS )ÚArrowConvertibleNrN   r   r   r   r\   r\   ¡   rO   r   r\   ÚFromNativeTc                  ó>   — e Zd Zedd„¦   «         Zedd„¦   «         ZdS )Ú
FromNativer/   r]   r&   r   r'   r   r
   c                ó   — d S r   r   r1   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   )rb   s    r   Ú
_is_nativezFromNative._is_native®   s	   € ð 	ˆr   N)r/   r]   r&   r   r'   r   r   r
   )rb   rc   r   rd   )r   r   r   r4   ra   Ústaticmethodrf   r   r   r   r_   r_   «   sH   € € € € € ØØQÐQÐQñ „[ØQØðð ð ñ „\ðð ð r   r_   ÚToNarwhalsT_coc                  ó   — e Zd Zdd„ZdS )Ú
ToNarwhalsr   rh   c                ó   — dS )z#Convert into public representation.Nr   )r   s    r   Úto_narwhalszToNarwhals.to_narwhals¸   s   € àˆr   N)r   rh   )r   r   r   rl   r   r   r   rj   rj   ·   s(   € € € € € ðð ð ð ð ð r   rj   ),Ú__doc__Ú
__future__r   Úcollections.abcr   r   Útypingr   r   r   Únarwhals._typing_compatr	   ÚpyarrowÚpaÚtyping_extensionsr
   r   r   r   r   r    r#   r%   r.   r6   r;   r=   ÚstrrA   rC   rE   rI   rM   rP   Ú__annotations__rQ   rR   rT   rX   r\   r]   r_   rh   rj   r   r   r   ú<module>rw      sÔ  ðð<ð <ð <ð| #Ð "Ð "Ð "Ð "Ð "à -Ð -Ð -Ð -Ð -Ð -Ð -Ð -Ø /Ð /Ð /Ð /Ð /Ð /Ð /Ð /Ð /Ð /à +Ð +Ð +Ð +Ð +Ð +àð :ØÐÐÐØ9Ð9Ð9Ð9Ð9Ð9Ð9Ð9Ð9Ð9ð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Ð:Ñ:Ô:€ðð ð ð ð �˜.Ô)ñ ô ð ð ð r   