o
    Lh                     @  s>  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r1ddlZddlmZmZmZ G dd	 d	e	Zed
ddZeddedZedddZG dd de	e ZG dd de	e ZG dd dee ee e	eef ZeddedZG dd de	e Zedeeef dddZedeeef deeef dZG dd  d e	e ZG d!d" d"e	e ZG d#d$ d$ee ee e	eef Z d%Z!d&e"d'< 	 ed(ddZ#ed)de!dZ$G d*d+ d+e	e# Z%G d,d- d-e	e$ Z&G d.d/ d/e%e# e&e$ e	e#e$f Z'ed0Z(G d1d2 d2e	e( Z)ed3ddZ*G d4d5 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                   @  s   e Zd Zdd	ddZdS )
ArrowStreamExportableNrequested_schemaobject | Nonereturnobjectc                 C     d S N )selfr   r   r   T/var/www/html/Persson_Maskin/env/lib/python3.10/site-packages/narwhals/_translate.py__arrow_c_stream__L       z(ArrowStreamExportable.__arrow_c_stream__r   )r   r   r   r   )__name__
__module____qualname__r   r   r   r   r   r   K   s    r   ToNumpyT_coT)	covariantFromNumpyDT_contra)contravariantdefaultFromNumpyT_contra)r   c                   @     e Zd Zd	ddZdS )
ToNumpyargsr   kwdsr   r   c                 O  r   r   r   r   r#   r$   r   r   r   to_numpyW   r   zToNumpy.to_numpyN)r#   r   r$   r   r   r   r   r   r   r&   r   r   r   r   r"   V       r"   c                   @     e Zd Zeddd	Zd
S )	FromNumpydatar    r#   r   r$   r   r	   c                 O  r   r   r   clsr+   r#   r$   r   r   r   
from_numpy[      zFromNumpy.from_numpyN)r+   r    r#   r   r$   r   r   r	   )r   r   r   classmethodr.   r   r   r   r   r*   Z       r*   c                   @  s   e Zd Zd
ddZd	S )NumpyConvertibledtyper   copybool | Noner   r   c                C  r   r   r   )r   r3   r4   r   r   r   r&   d   r   zNumpyConvertible.to_numpyN)r3   r   r4   r5   r   r   r'   r   r   r   r   r2   _   s    r2   FromIterableT_contrac                   @  r)   )FromIterabler+   Iterable[FromIterableT_contra]r#   r   r$   r   r	   c                 O  r   r   r   r,   r   r   r   from_iterablek      zFromIterable.from_iterableN)r+   r8   r#   r   r$   r   r   r	   )r   r   r   r0   r9   r   r   r   r   r7   j   r1   r7   ToDictDT_cozdict[str, Any])boundr   r   FromDictDT_contra)r<   r   r   c                   @  r!   )
ToDictr#   r   r$   r   r;   c                 O  r   r   r   r%   r   r   r   to_dict}   r   zToDict.to_dictN)r#   r   r$   r   r   r;   )r   r   r   r?   r   r   r   r   r>   |   r(   r>   c                   @  r)   )FromDictr+   r=   r#   r   r$   r   r	   c                 O  r   r   r   r,   r   r   r   	from_dict   r/   zFromDict.from_dictN)r+   r=   r#   r   r$   r   r   r	   )r   r   r   r0   rA   r   r   r   r   r@      r1   r@   c                   @     e Zd ZdS )DictConvertibleNr   r   r   r   r   r   r   rC          rC   z ArrowStreamExportable | pa.Tabler
   IntoArrowTableToArrowT_coFromArrowDT_contrac                   @  r!   )
ToArrowr#   r   r$   r   rG   c                 O  r   r   r   r%   r   r   r   to_arrow   r   zToArrow.to_arrowN)r#   r   r$   r   r   rG   )r   r   r   rJ   r   r   r   r   rI      r(   rI   c                   @  r)   )	FromArrowr+   rH   r#   r   r$   r   r	   c                 O  r   r   r   r,   r   r   r   
from_arrow   r/   zFromArrow.from_arrowN)r+   rH   r#   r   r$   r   r   r	   )r   r   r   r0   rL   r   r   r   r   rK      r1   rK   c                   @  rB   )ArrowConvertibleNrD   r   r   r   r   rM      rE   rM   FromNativeTc                   @  s(   e Zd Zeddd	ZedddZdS )
FromNativer+   rN   r#   r   r$   r   r	   c                 O  r   r   r   r,   r   r   r   from_native   r/   zFromNative.from_nativeobjFromNativeT | AnyTypeIs[FromNativeT]c                C     dS )z6Return `True` if `obj` can be passed to `from_native`.Nr   )rQ   r   r   r   
_is_native   r:   zFromNative._is_nativeN)r+   rN   r#   r   r$   r   r   r	   )rQ   rR   r   rS   )r   r   r   r0   rP   staticmethodrU   r   r   r   r   rO      s
    rO   ToNarwhalsT_coc                   @  s   e Zd ZdddZdS )
ToNarwhalsr   rW   c                 C  rT   )z#Convert into public representation.Nr   )r   r   r   r   to_narwhals   s   zToNarwhals.to_narwhalsN)r   rW   )r   r   r   rY   r   r   r   r   rX      r(   rX   ),__doc__
__future__r   collections.abcr   r   typingr   r   r   narwhals._typing_compatr   pyarrowpatyping_extensionsr	   r
   r   r   r   r   r    r"   r*   r2   r6   r7   strr;   r=   r>   r@   rC   rF   __annotations__rG   rH   rI   rK   rM   rN   rO   rW   rX   r   r   r   r   <module>   sp    >







	