
    -Ph              	      
   U d Z ddl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  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
d/          Z' G d0 d1ee'                   Z( e
d2d
          Z) G d3 d4ee)                   Z*dS )5a 
  [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)TYPE_CHECKINGAnyIterableMapping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     S/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/narwhals/_translate.py__arrow_c_stream__z(ArrowStreamExportable.__arrow_c_stream__K             r   )r   r   r   r   )__name__
__module____qualname__r   r   r   r   r   r   J   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_numpyV   r   r   N)r&   r   r'   r   r   r   r   r   r   r*   r   r   r   r%   r%   U           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_numpyZ   s    SVSVr   N)r/   r#   r&   r   r'   r   r   r
   )r   r   r   classmethodr3   r   r   r   r.   r.   Y   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_numpyc   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_iterablej   s	     sr   N)r/   r>   r&   r   r'   r   r   r
   )r   r   r   r4   r@   r   r   r   r=   r=   i   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    RURUr   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    TWTWr   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    NQcr   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   typingr   r   r   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>rv      s  < < <| # " " " " " B B B B B B B B B B B B B B + + + + + + :9999999999X X X X XH X X X gmt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5TSVWWW     801    gc*dDT   G
#s(
CH	   C C C C CXk" C C CV V V V Vx)* V V V
    
;[++,   ? > > > >
 gmt444Wn   
D D D D Dh{# D D DX X X X X+, X X X
    K ![,,-   gm$$    +&    )T:::    .)     r   