
    Lpj$              	         % S r SSKJr  SSKJrJr  SSKJrJrJ	r	J
r
Jr  SSKJr  \(       a  SSKJr  SSKrSSKJrJrJr   " S	 S
\
5      r\" SSS9r\" SS\S9r\" SSS9r " S S\
\   5      r " S S\
\   5      r " S S\\   \\   \
\\4   5      r\" SS\S9r " S S\
\   5      r\" S\\\4   SSS9r\" S\\\4   S\\\4   S9r  " S  S!\
\   5      r! " S" S#\
\    5      r" " S$ S%\!\   \"\    \
\\ 4   5      r#S&r$S'\%S('    \" S)SS9r&\" S*S\$S9r' " S+ S,\
\&   5      r( " S- S.\
\'   5      r) " S/ S0\(\&   \)\'   \
\&\'4   5      r*\" S15      r+ " S2 S3\
\+   5      r,\" S4SS9r- " S5 S6\
\-   5      r. " S7 S8\S9S:9r/ " S; S<\/S9S:9r0 " S= S>\/S9S:9r1 " S? S@\/S9S:9r2 " SA SB\S9S:9r3 " SC SD\3S9S:9r4 " SE SF\3S9S:9r5 " SG SH\3S9S:9r6 " SI SJ\S9S:9r7 " SK SL\7S9S:9r8 " SM SN\7S9S:9r9 " SO SP\7S9S:9r: " SQ SR\S9S:9r; " SS ST\;S9S:9r< " SU SV\;S9S:9r= " SW SX\S9S:9r> " SY SZ\>S9S:9r? " S[ S\\>S9S:9r@ " S] S^\>S9S:9rA " S_ S`\S9S:9rB " Sa Sb\BS9S:9rC " Sc Sd\BS9S:9rD " Se Sf\BS9S:9rE " Sg Sh\S9S:9rF " Si Sj\FS9S:9rG " Sk Sl\FS9S:9rH " Sm Sn\FS9S:9rIg)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                  "    \ rS rSrSSS jjrSrg)ArrowStreamExportableN   Nc                    g N )selfrequested_schemas     O/var/www/html/pdf-tiff/venv/lib/python3.13/site-packages/narwhals/_translate.py__arrow_c_stream__(ArrowStreamExportable.__arrow_c_stream__O   s    TW    r   r   )r   zobject | Nonereturnobject)__name__
__module____qualname____firstlineno__r   __static_attributes__r   r   r   r   r   N   s    WWr   r   ToNumpyT_coT)	covariantFromNumpyDT_contra)contravariantdefaultFromNumpyT_contra)r&   c                      \ rS rSrSS jrSrg)ToNumpyY   c                    g r   r   r   argskwdss      r   to_numpyToNumpy.to_numpyZ       r   r   N)r.   r   r/   r   r   r#   r   r   r    r!   r0   r"   r   r   r   r*   r*   Y       Cr   r*   c                  (    \ rS rSr\SS j5       rSrg)	FromNumpy]   c                    g r   r   clsdatar.   r/   s       r   
from_numpyFromNumpy.from_numpy^   s    SVr   r   N)r;   r(   r.   r   r/   r   r   r   )r   r   r    r!   classmethodr<   r"   r   r   r   r6   r6   ]   s    V Vr   r6   c                      \ rS rSrSS jrSrg)NumpyConvertibleb   c                   g r   r   )r   dtypecopys      r   r0   NumpyConvertible.to_numpyg   s    r   r   N)rC   r   rD   bool | Noner   r#   r3   r   r   r   r@   r@   b   s    
 Mr   r@   FromIterableT_contrac                  8    \ rS rSr\        SS j5       rSrg)FromIterablem   c                    g r   r   r9   s       r   from_iterableFromIterable.from_iterablen   s     r   r   N)r;   zIterable[FromIterableT_contra]r.   r   r/   r   r   r   )r   r   r    r!   r>   rL   r"   r   r   r   rI   rI   m   s4    1:=GJ	 r   rI   ToDictDT_cozdict[str, Any])boundr$   r'   FromDictDT_contra)rO   r&   r'   c                      \ rS rSrSS jrSrg)ToDict   c                    g r   r   r-   s      r   to_dictToDict.to_dict   s    sr   r   N)r.   r   r/   r   r   rN   )r   r   r    r!   rU   r"   r   r   r   rR   rR      s    Br   rR   c                  (    \ rS rSr\SS j5       rSrg)FromDict   c                    g r   r   r9   s       r   	from_dictFromDict.from_dict   s    RUr   r   N)r;   rP   r.   r   r/   r   r   r   )r   r   r    r!   r>   r[   r"   r   r   r   rX   rX      s    U Ur   rX   c                      \ rS rSrSrg)DictConvertible   r   Nr   r   r    r!   r"   r   r   r   r^   r^           r   r^   z ArrowStreamExportable | pa.Tabler   IntoArrowTableToArrowT_coFromArrowDT_contrac                      \ rS rSrSS jrSrg)ToArrow   c                    g r   r   r-   s      r   to_arrowToArrow.to_arrow   r2   r   r   N)r.   r   r/   r   r   rc   )r   r   r    r!   ri   r"   r   r   r   rf   rf      r4   r   rf   c                  (    \ rS rSr\SS j5       rSrg)	FromArrow   c                    g r   r   r9   s       r   
from_arrowFromArrow.from_arrow   s    TWr   r   N)r;   rd   r.   r   r/   r   r   r   )r   r   r    r!   r>   ro   r"   r   r   r   rl   rl      s    W Wr   rl   c                      \ rS rSrSrg)ArrowConvertible   r   Nr`   r   r   r   rr   rr      ra   r   rr   FromNativeTc                  <    \ rS rSr\SS j5       r\SS j5       rSrg)
FromNative   c                    g r   r   r9   s       r   from_nativeFromNative.from_native   s    NQr   c                   g)z6Return `True` if `obj` can be passed to `from_native`.Nr   )objs    r   
_is_nativeFromNative._is_native   s     	r   r   N)r;   rt   r.   r   r/   r   r   r   )r|   zFromNativeT | Anyr   zTypeIs[FromNativeT])	r   r   r    r!   r>   ry   staticmethodr}   r"   r   r   r   rv   rv      s"    Q Q r   rv   ToNarwhalsT_coc                      \ rS rSrSS jrSrg)
ToNarwhals   c                    g)z#Convert into public representation.Nr   )r   s    r   to_narwhalsToNarwhals.to_narwhals   s    r   r   N)r   r   )r   r   r    r!   r   r"   r   r   r   r   r      s    r   r   c                  4    \ rS rSr% S\S'   S\S'   S\S'   Srg	)
_ExcludeSeries   bool
eager_onlyLiteral[False]series_onlyzLiteral[False] | Noneallow_seriesr   Nr   r   r    r!   __annotations__r"   r   r   r   r   r      s    ''r   r   F)totalc                       \ rS rSr% S\S'   Srg)ExcludeSeries   r   pass_throughr   Nr   r   r   r   r   r          r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)ExcludeSeriesV1   rF   r   r   eager_or_interchange_onlyr   Nr   r   r   r   r   r          --r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)ExcludeSeriesStrictV1   rF   strictr   r   r   Nr   r   r   r   r   r          --r   r   c                  4    \ rS rSr% S\S'   S\S'   S\S'   Srg	)
_AllowSeries   r   r   r   r   Required[Literal[True]]r   r   Nr   r   r   r   r   r      s    ))r   r   c                       \ rS rSr% S\S'   Srg)AllowSeries   r   r   r   Nr   r   r   r   r   r      r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)AllowSeriesV1   rF   r   r   r   r   Nr   r   r   r   r   r      r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)AllowSeriesStrictV1   rF   r   r   r   r   Nr   r   r   r   r   r      r   r   r   c                  4    \ rS rSr% S\S'   S\S'   S\S'   Srg	)
_OnlySeries   r   r   r   r   rF   r   r   Nr   r   r   r   r   r      s    ((r   r   c                       \ rS rSr% S\S'   Srg)
OnlySeries   r   r   r   Nr   r   r   r   r   r      r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)OnlySeriesV1   rF   r   r   r   r   Nr   r   r   r   r   r      r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)OnlySeriesStrictV1   rF   r   r   r   r   Nr   r   r   r   r   r      r   r   r   c                  4    \ rS rSr% S\S'   S\S'   S\S'   Srg	)
_OnlyEagerOrInterchange   r   r   r   r   rF   r   r   Nr   r   r   r   r   r      s    66r   r   c                       \ rS rSr% S\S'   Srg)OnlyEagerOrInterchangei  rF   r   r   Nr   r   r   r   r   r     s    r   r   c                       \ rS rSr% S\S'   Srg)OnlyEagerOrInterchangeStricti  rF   r   r   Nr   r   r   r   r   r     s    r   r   c                  4    \ rS rSr% S\S'   S\S'   S\S'   Srg)	
_AllowLazyi
  r   r   r   rF   r   r   Nr   r   r   r   r   r   
  s    r   r   c                       \ rS rSr% S\S'   Srg)	AllowLazyi  r   r   r   Nr   r   r   r   r   r     r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)AllowLazyV1i  rF   r   r   r   r   Nr   r   r   r   r   r     r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)AllowLazyStrictV1i  rF   r   r   r   r   Nr   r   r   r   r   r     r   r   r   c                  4    \ rS rSr% S\S'   S\S'   S\S'   Srg)		_AllowAnyi  r   r   r   r   r   r   Nr   r   r   r   r   r     s    ))r   r   c                       \ rS rSr% S\S'   Srg)AllowAnyi$  r   r   r   Nr   r   r   r   r   r   $  r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)
AllowAnyV1i(  rF   r   r   r   r   Nr   r   r   r   r   r   (  r   r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)AllowAnyStrictV1i-  rF   r   r   r   r   Nr   r   r   r   r   r   -  r   r   r   c                  4    \ rS rSr% S\S'   S\S'   S\S'   Srg)	_Unknowni2  r   r   r   rF   r   r   Nr   r   r   r   r   r   2  s    r   r   c                       \ rS rSr% S\S'   Srg)PassThroughUnknowni8  r   r   r   Nr   r   r   r   r   r   8  s    ))r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)PassThroughUnknownV1i<  r   r   r   r   r   Nr   r   r   r   r   r   <  s    ))##r   r   c                  *    \ rS rSr% S\S'   S\S'   Srg)StrictUnknownV1iA  zRequired[Literal[False]]r   r   r   r   Nr   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*   r6   r@   rG   rI   strrN   rP   rR   rX   r^   rb   r   rc   rd   rf   rl   rr   rt   rv   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   r   r   r   <module>r      s  =~ # - C C + 88XH X mt4k  /tD Dh{# DW*+ W
MK ![,,-M 5TSVW 801  c*dDT 
#s(
CH	 CXk" CVx)* V

;[++, ?	 >
 mt4n 
Dh{# DX+, X
K ![,,- m$+&  )T:.) (Ye (N% .nE .
.N% .
*9E *,e .L .
.,e .
)5 E .;e .
.E .
iu 4E #:% % 
% .*E .
.
% .
*	 *y .% .
.y .
y * *$85 $
$he $r   