o
    $&]i$                     @  sf  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r7ddlZddlmZ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.G d6d7 d7ed8d9Z/G d:d; d;e/d8d9Z0G d<d= d=e/d8d9Z1G d>d? d?e/d8d9Z2G d@dA dAed8d9Z3G dBdC dCe3d8d9Z4G dDdE dEe3d8d9Z5G dFdG dGe3d8d9Z6G dHdI dIed8d9Z7G dJdK dKe7d8d9Z8G dLdM dMe7d8d9Z9G dNdO dOe7d8d9Z:G dPdQ dQed8d9Z;G dRdS dSe;d8d9Z<G dTdU dUe;d8d9Z=G dVdW dWed8d9Z>G dXdY dYe>d8d9Z?G dZd[ d[e>d8d9Z@G d\d] d]e>d8d9ZAG d^d_ d_ed8d9ZBG d`da daeBd8d9ZCG dbdc dceBd8d9ZDG ddde deeBd8d9ZEG dfdg dged8d9ZFG dhdi dieFd8d9ZGG djdk dkeFd8d9ZHG dldm dmeFd8d9ZIdS )na
  [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)TypeVarN)Required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   Q/var/www/html/IGF-ODF-V3/venv/lib/python3.10/site-packages/narwhals/_translate.py__arrow_c_stream__M       z(ArrowStreamExportable.__arrow_c_stream__r   )r   r   r   r   )__name__
__module____qualname__r   r   r   r   r   r   L   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_numpyX   r   zToNumpy.to_numpyN)r&   r   r'   r   r   r   r   r   r   r)   r   r   r   r   r%   W       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   classmethodr1   r   r   r   r   r-   [       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   r6   r7   r   r   r   r)   e   r   zNumpyConvertible.to_numpyN)r6   r   r7   r8   r   r   r*   r   r   r   r   r5   `   s    r5   FromIterableT_contrac                   @  r,   )FromIterabler.   Iterable[FromIterableT_contra]r&   r   r'   r   r   c                 O  r   r   r   r/   r   r   r   from_iterablel      zFromIterable.from_iterableN)r.   r;   r&   r   r'   r   r   r   )r   r   r   r3   r<   r   r   r   r   r:   k   r4   r:   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   rB   r   r   r   r   rA   }   r+   rA   c                   @  r,   )FromDictr.   r@   r&   r   r'   r   r   c                 O  r   r   r   r/   r   r   r   	from_dict   r2   zFromDict.from_dictN)r.   r@   r&   r   r'   r   r   r   )r   r   r   r3   rD   r   r   r   r   rC      r4   rC   c                   @     e Zd ZdS )DictConvertibleNr   r   r   r   r   r   r   rF          rF   z ArrowStreamExportable | pa.Tabler   IntoArrowTableToArrowT_coFromArrowDT_contrac                   @  r$   )
ToArrowr&   r   r'   r   rJ   c                 O  r   r   r   r(   r   r   r   to_arrow   r   zToArrow.to_arrowN)r&   r   r'   r   r   rJ   )r   r   r   rM   r   r   r   r   rL      r+   rL   c                   @  r,   )	FromArrowr.   rK   r&   r   r'   r   r   c                 O  r   r   r   r/   r   r   r   
from_arrow   r2   zFromArrow.from_arrowN)r.   rK   r&   r   r'   r   r   r   )r   r   r   r3   rO   r   r   r   r   rN      r4   rN   c                   @  rE   )ArrowConvertibleNrG   r   r   r   r   rP      rH   rP   FromNativeTc                   @  s(   e Zd Zeddd	ZedddZdS )
FromNativer.   rQ   r&   r   r'   r   r   c                 O  r   r   r   r/   r   r   r   from_native   r2   zFromNative.from_nativeobjFromNativeT | AnyTypeIs[FromNativeT]c                C     dS )z6Return `True` if `obj` can be passed to `from_native`.Nr   )rT   r   r   r   
_is_native   r=   zFromNative._is_nativeN)r.   rQ   r&   r   r'   r   r   r   )rT   rU   r   rV   )r   r   r   r3   rS   staticmethodrX   r   r   r   r   rR      s
    rR   ToNarwhalsT_coc                   @  s   e Zd ZdddZdS )
ToNarwhalsr   rZ   c                 C  rW   )z#Convert into public representation.Nr   )r   r   r   r   to_narwhals   s   zToNarwhals.to_narwhalsN)r   rZ   )r   r   r   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 )_ExcludeSeriesbool
eager_onlyLiteral[False]series_onlyzLiteral[False] | Noneallow_seriesNr   r   r   __annotations__r   r   r   r   r^         
 r^   F)totalc                   @     e Zd ZU ded< dS )ExcludeSeriesr_   pass_throughNrd   r   r   r   r   ri         
 ri   c                   @     e Zd ZU ded< ded< dS )ExcludeSeriesV1r8   rj   ra   eager_or_interchange_onlyNrd   r   r   r   r   rm         
 rm   c                   @  rl   )ExcludeSeriesStrictV1r8   strictra   rn   Nrd   r   r   r   r   rp      ro   rp   c                   @  r]   )_AllowSeriesr_   r`   ra   rb   Required[Literal[True]]rc   Nrd   r   r   r   r   rr      rf   rr   c                   @  rh   )AllowSeriesr_   rj   Nrd   r   r   r   r   rt      rk   rt   c                   @  rl   )AllowSeriesV1r8   rj   ra   rn   Nrd   r   r   r   r   ru      ro   ru   c                   @  rl   )AllowSeriesStrictV1r8   rq   ra   rn   Nrd   r   r   r   r   rv      ro   rv   c                   @  r]   )_OnlySeriesr_   r`   rs   rb   r8   rc   Nrd   r   r   r   r   rw      rf   rw   c                   @  rh   )
OnlySeriesr_   rj   Nrd   r   r   r   r   rx      rk   rx   c                   @  rl   )OnlySeriesV1r8   rj   ra   rn   Nrd   r   r   r   r   ry      ro   ry   c                   @  rl   )OnlySeriesStrictV1r8   rq   ra   rn   Nrd   r   r   r   r   rz      ro   rz   c                   @  r]   )_OnlyEagerOrInterchangers   rn   ra   rb   r8   rc   Nrd   r   r   r   r   r{      rf   r{   c                   @  rh   )OnlyEagerOrInterchanger8   rj   Nrd   r   r   r   r   r|      rk   r|   c                   @  rh   )OnlyEagerOrInterchangeStrictr8   rq   Nrd   r   r   r   r   r}     rk   r}   c                   @  &   e Zd ZU ded< ded< ded< dS )
_AllowLazyra   r`   rb   r8   rc   Nrd   r   r   r   r   r     rf   r   c                   @  rh   )	AllowLazyr_   rj   Nrd   r   r   r   r   r     rk   r   c                   @  rl   )AllowLazyV1r8   rj   ra   rn   Nrd   r   r   r   r   r     ro   r   c                   @  rl   )AllowLazyStrictV1r8   rq   ra   rn   Nrd   r   r   r   r   r     ro   r   c                   @  r~   )	_AllowAnyra   r`   rb   rs   rc   Nrd   r   r   r   r   r     rf   r   c                   @  rh   )AllowAnyr_   rj   Nrd   r   r   r   r   r   "  rk   r   c                   @  rl   )
AllowAnyV1r8   rj   ra   rn   Nrd   r   r   r   r   r   &  ro   r   c                   @  rl   )AllowAnyStrictV1r8   rq   ra   rn   Nrd   r   r   r   r   r   +  ro   r   c                   @  r~   )_Unknownr_   r`   rb   r8   rc   Nrd   r   r   r   r   r   0  rf   r   c                   @  rh   )PassThroughUnknownrs   rj   Nrd   r   r   r   r   r   6  rk   r   c                   @  rl   )PassThroughUnknownV1rs   rj   r_   rn   Nrd   r   r   r   r   r   :  ro   r   c                   @  rl   )StrictUnknownV1zRequired[Literal[False]]rq   r_   rn   Nrd   r   r   r   r   r   ?  ro   r   )J__doc__
__future__r   collections.abcr   r   typingr   r   r   r   r	   narwhals._typing_compatr
   pyarrowpatyping_extensionsr   r   r   r   r   r   r    r#   r%   r-   r5   r9   r:   strr>   r@   rA   rC   rF   rI   re   rJ   rK   rL   rN   rP   rQ   rR   rZ   r[   r^   ri   rm   rp   rr   rt   ru   rv   rw   rx   ry   rz   r{   r|   r}   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   <module>   s    ?







	