+gd6NdZddlZddlZddlZddlZddlmZmZddlmZ ddl m Z m Z m Z mZddlmZmZddlmZddlmZmZmZmZmZmZmZddlmZddlZddlZ ddl!Z"ddl#m$Z%ddl&Z!dd l'm(Z)dd l'm*Z+d d l,m-Z-d d l.m/Z/m0Z0d dl1m2Z2d dl3m4Z4d dl5m6Z6m7Z7m8Z8ddl9m:Z:ddl;mm?Z?m@Z@e4jAeBZCde"jDdeEfdZFdeEde"jDfdZGdedeHdeHdeeeHffdZIdbdedefd ZJe Gd!d"ZKGd#d$ZLe Gd%d&eLZMe Gd'd(eLZNe Gd)d*eLZOe Gd+d,eLZPGd-d.e"jQZRGd/d0eRZSGd1d2eRZTGd3d4eRZUGd5d6eRZVdcd7e"jDd8eHdeHfd9ZWGd:d;e"j(ZXGd<d=e+ZYGd>d?e)ZZd@Z[e GdAdBZ\e GdCdDZee]e^e_eKe\e?e@eeMeNeOePe:e._dtype_error_msgsiiYaiii  *,,,,,{>C/0222 "8.II/55a88I&RTghh "9 9 9< 344 4  < 1 7 7 : :SUdUjUjklUmUm4n4n 14 AGGJJ =CCAFF}S^^SZZ@@@ $$&$"57J!Kfg $u , ,46I>SUdUjUjklUmUm4n4n 14 AGGJJ =CCAFF}S^^SZZ@@@ $$&$"57K!Lfg   "13FG``      U> U U(< U U U  rdobjonly_1d_for_numpyoptimize_list_castingc tjrdtjvrddl}tjrdtjvrddl}tjrdtjvrddlm }tj rdtjvrddl }t|tjr7|jdkr |ddfSr |jd kr|d fSfd |DdfStjrdtjvrt||jr|jdkr@| ddfSr |jd kr:| dfSfd | DdfStjrdtjvrt||jrm|jdkr| ddfSr |jd kr| dfSfd | DdfStjrdtjvrt||jrm|jdkrtj|ddfSr |jd krtj|dfSfdtj|DdfStj r9dtjvr+t||jjrt+|dfSt|t,jr,t1|ddfSt|t,jr6fd|dDdfSt|t,jr|dfSt|t,jr| dfSt|tBrYt|tD }i}|D]$\} } t1| \} } || z}| || <%|r|n||fSt|tFtHfrtK|dkrq|D]} tM| rnt1| \}}|ssfd|DdfSt|tFtHfr|d fStG|dfS|d fS|d fS)a Cast pytorch/tensorflow/pandas objects to python numpy array/lists. It works recursively. If `optimize_list_casting` is True, to avoid iterating over possibly long lists, it first checks (recursively) if the first element that is not None or empty (if it is a sequence) has to be casted. If the first element needs to be casted, then all the elements of the list will be casted, otherwise they'll stay the same. This trick allows to cast objects that contain tokenizers outputs without iterating over every single token for example. Args: obj: the object (nested struct) to cast. only_1d_for_numpy (bool): whether to keep the full multi-dim tensors as multi-dim numpy arrays, or convert them to nested lists of 1-dimensional numpy arrays. This can be useful to keep only 1-d arrays to instantiate Arrow arrays. Indeed Arrow only support converting 1-dimensional array values. optimize_list_casting (bool): whether to optimize list casting by checking the first non-null element to see if it needs to be casted and if it doesn't, not checking the rest of the list elements. Returns: casted_obj: the casted object has_changed (bool): True if the object has been changed, False if it is identical tensorflowrNtorchjaxPILTrFc@g|]}t|dSrrr_cast_to_python_objects.0xrrs rb z+_cast_to_python_objects..0K,->Vkrdc@g|]}t|dSrrrs rbrz+_cast_to_python_objects..?rrdc@g|]}t|dSrrrs rbrz+_cast_to_python_objects..Nrrdc@g|]}t|dSrrrs rbrz+_cast_to_python_objects..]rrdrcHi|]\}}|t|dSrr)rkeyvaluerrs rb z+_cast_to_python_objects..psR   C,->Vk   rdlistc@g|]}t|dSrr)relmtrrs rbrz+_cast_to_python_objects..sK!0 4E]rrd)'r TF_AVAILABLEsysmodulesrTORCH_AVAILABLEr JAX_AVAILABLE jax.numpynumpy PIL_AVAILABLE PIL.Image isinstancenpndarrayndimTensordetachcpuasarrayr!r"pdSeriesrtolist DataFrameto_dictitems Timestamp to_pydatetime Timedeltato_pytimedeltardictrtuplerj#_check_non_null_non_empty_recursive)rrrtfrjnpr has_changedoutputkvcasted_v has_changed_v first_elmtcasted_first_elmthas_changed_first_elmts `` rbrrso, |s{:: 'S["8"8    4 4  4 4#rz""w 8q==r7D= " ch!mm: !     hGs{$:$:z#u|?\?\$: 8q==::<<##%%++--b147 7" ch!mm::<<##%%++--t3 3!ZZ\\--//5577     Y!>> from datasets import Features >>> features = Features({'stars': Value(dtype='int32')}) >>> features {'stars': Value(dtype='int32', id=None)} ``` rlNidpa_typeFdefaultinitrepr_typec|jdkrd|_|jdkrd|_t|j|_dS)Ndoubler4floatr3)rlrrselfs rb __post_init__zValue.__post_init__s? : ! !"DJ : "DJ&tz22 rdc|jSNrrs rb__call__zValue.__call__ |rdctj|jrt |Stj|jrt |Stj|jrt|Stj |jrt|S|Sr) rOr@rBrr) is_integerr is_floatingrr`rQrrs rbencode_examplezValue.encode_examples 8  t| , , ;;  X  . . u::  X ! !$, / / <<  X   - - u:: Lrd)__name__ __module__ __qualname____doc__rQ__annotations__rrrrr rrrrrrrdrbrrs&&P JJJB !GXc]!!!wU???E3???333     rdrc eZdZdZdZdZdS)_ArrayXDc8t|j|_dSr)rshapers rbrz_ArrayXD.__post_init__s4:&& rdcpt|jjdz|j|j}|S)N ExtensionType)globals __class__rrrl)rrs rbrz_ArrayXD.__call__s1F'))DN3oEFtzSWS]^^rdcbt|tjr|}|Sr)rrrrrs rbrz_ArrayXD.encode_example s( eRZ ( ( #LLNNE rdN)rrrrrrrrdrbrrsA'''rdrcheZdZUdZeed<eed<dZeeed<e dddZ eed<dS) Array2Da?Create a two-dimensional array. Args: shape (`tuple`): The size of each dimension. dtype (`str`): The value of the data type. Example: ```py >>> from datasets import Features >>> features = Features({'x': Array2D(shape=(1, 3), dtype='int32')}) ``` rrlNrFrr rrrrrrrQrrrrrrdrbrre LLL JJJB yu5AAAE3AAAAArdrcheZdZUdZeed<eed<dZeeed<e dddZ eed<dS) Array3DaDCreate a three-dimensional array. Args: shape (`tuple`): The size of each dimension. dtype (`str`): The value of the data type. Example: ```py >>> from datasets import Features >>> features = Features({'x': Array3D(shape=(1, 2, 3), dtype='int32')}) ``` rrlNrFrrrrrdrbrr*rrdrcheZdZUdZeed<eed<dZeeed<e dddZ eed<dS) Array4DaFCreate a four-dimensional array. Args: shape (`tuple`): The size of each dimension. dtype (`str`): The value of the data type. Example: ```py >>> from datasets import Features >>> features = Features({'x': Array4D(shape=(1, 2, 2, 3), dtype='int32')}) ``` rrlNrFrrrrrdrbr r Crrdr cheZdZUdZeed<eed<dZeeed<e dddZ eed<dS) Array5DaICreate a five-dimensional array. Args: shape (`tuple`): The size of each dimension. dtype (`str`): The value of the data type. Example: ```py >>> from datasets import Features >>> features = Features({'x': Array5D(shape=(1, 2, 2, 3, 3), dtype='int32')}) ``` rrlNrFrrrrrdrbr r \rrdr cXeZdZUdZeeed<dedefdZ dZ dZ dZ d Z d ZdS) _ArrayXDExtensionTypeNndimsrrlc|j |jdkrtdt||jkrtd|d|jdtd|jD]}||td|t ||_||_||j|_tj ||jdS)NrzCYou must instantiate an array type with a value for dim that is > 1zshape=z and ndims=z don't matchz3Support only dynamic size on first dimension. Got: ) rrVrjrangerr value_type_generate_dtype storage_dtyperOPyExtensionType__init__)rrrldims rbrz_ArrayXDExtensionType.__init__xs : qbcc c u:: # #PePP PPPQQ QDJ'' ` `CSz! !^W\!^!^___"5\\ !11$/BB ##D$*<=====rdc,|j|j|jffSr)rrrrs rb __reduce__z _ArrayXDExtensionType.__reduce__s ~ J O   rdcDt|j|j|jfSr)hashrrrrs rb__hash__z_ArrayXDExtensionType.__hash__sT^TZABBBrdctSr)ArrayExtensionArrayrs rb__arrow_ext_class__z)_ArrayXDExtensionType.__arrow_ext_class__s""rdczt|}t|jD]}tj|}|Sr)rreversedrrOlist_)rrlds rbrz%_ArrayXDExtensionType._generate_dtypes>&&$*%% $ $AHUOOEE rdc*t|jSr)PandasArrayExtensionDtyperrs rbto_pandas_dtypez%_ArrayXDExtensionType.to_pandas_dtypes(999rd)rrrrrrrrrQrrrrrr&rrdrbrrusE8C= >e >C > > > >   CCC###:::::rdrceZdZdZdS)Array2DExtensionTyperNrrrrrrdrbr(r( EEErdr(ceZdZdZdS)Array3DExtensionTypeNr)rrdrbr,r,r*rdr,ceZdZdZdS)Array4DExtensionTypeNr)rrdrbr/r/r*rdr/ceZdZdZdS)Array5DExtensionTypeNr)rrdrbr2r2r*rdr2runnestcdtjdtjffd |r |}tj|o>tj|ptj| S)a When converting a pyarrow array to a numpy array, we must know whether this could be done in zero-copy or not. This function returns the value of the ``zero_copy_only`` parameter to pass to ``.to_numpy()``, given the type of the pyarrow array. # zero copy is available for all primitive types except booleans and temporal types (date, time, timestamp or duration) # primitive types are types for which the physical representation in arrow and in numpy # https://github.com/wesm/arrow/blob/c07b9b48cf3e0bbbab493992a492ae47e5b04cad/python/pyarrow/types.pxi#L821 # see https://arrow.apache.org/docs/python/generated/pyarrow.Array.html#pyarrow.Array.to_numpy # and https://issues.apache.org/jira/browse/ARROW-2871?jql=text%20~%20%22boolean%20to_numpy%22 rr&cftj|r|jS|Sr)rOr@is_listr)r_unnest_pa_types rbr8z+_is_zero_copy_only.._unnest_pa_types3 8  G $ $ 7"?7#566 6rd)rODataTyper@ is_primitiverB is_temporal)rr4r8s @rb_is_zero_copy_onlyr<s +!/'** 8  ) ) q283F3Fw3O3O3pSUS[SgSghoSpSp.qqrdc(eZdZdZdZddZdZdS)rcdt|jjd}||S)NTr4zero_copy_only)r<storagetypeto_numpy)rrAs rb __array__zArrayExtensionArray.__array__s-+DL,=dKKK}}N};;;rdc|j|SrrB)ris rb __getitem__zArrayExtensionArray.__getitem__s|ArdTc |j}|jjd/d}tjt ||d}t|jj D]+}||jj|z}| },||}|j t |t |z g|jjR}t |r?tj | tj|tjd}n|jj}|jj }g} tjd|jD} t%|dD]\}} | r | tj'|||dz} | |dz| |z } t|D]}| } | |}| |j | g|ddRt tjtj| dkr0tjt | t.}| |dd<ntj| }|S)NrrFr@axisc6g|]}|Sr)as_py)roffs rbrz0ArrayExtensionArray.to_numpy..s )Q)Q)Q##))++)Q)Q)Qrdrl)rBrCrrarangerjrArDrrflattenreshapeinsertastyper4nanarrayoffsets enumerateappenduniquediffemptyobject)rrArBsize null_indicesrH numpy_arrrrarraysfirst_dim_offsetsrA storage_el first_dimrrs rbrDzArrayExtensionArray.to_numpys $  9?1  )D9S\\227??3D3D3M3M]b3M3c3cdL49?++ , , **!//++(((GGI) )#d))c,6G6G*GZ$)/ZZZI<   bIi&6&6rz&B&BLRTRX_`aaa IOEIOEF ")Q)Q)Q)Q)Q R R '(9(9(B(BRW(B(X(XYY L L 7 LMM"&))))!(QU!3J 1!a% 8;LQ;O OI"5\\::%/%7%7%9%9 * 3 3> 3 R RIMM"3)"3I"Jabb "J"J"JKKKK29RW%6778899A==HS[[??? % !!! HV,, rdc t|jjd}||}|jjd.|jt krd|DS|S)NTr?r@rc6g|]}|Sr)rrarrs rbrz1ArrayExtensionArray.to_pylist..s ???SCJJLL???rd)r<rBrCrDrrlr^r)rrAras rb to_pylistzArrayExtensionArray.to_pylistsy+DL,=dKKKMMM@@ 9?1  %)/V*C*C??I,<,<,>,>??? ?##%% %rdN)T)rrrrErIrDrjrrdrbrrsV<<<))))V&&&&&rdrceZdZdZdedejffdZdeej ej ffdZ e dZ edefdZedefdZedefd Zedejfd Zd S) r%rc||_dSr _value_type)rrs rbrz"PandasArrayExtensionDtype.__init__s%rdrWc,t|tjr;|jtjd|jD}t|jjd}| |}t|S)Ncg|] }|j SrrG)rchunks rbrz.s;d;d;deEM;d;d;drdTr?r@) rrO ChunkedArrayrC wrap_array concat_arrayschunksr<rBrDPandasArrayExtensionArray)rrWrAras rb__from_arrow__z(PandasArrayExtensionDtype.__from_arrow__s eR_ - - gJ))"*:;d;dW\Wc;d;d;d*e*effE+EM,>tLLLNN.NAA (333rdctSr)rv)clss rbconstruct_array_typez.PandasArrayExtensionDtype.construct_array_type s((rdr&ctjSr)rrrs rbrCzPandasArrayExtensionDtype.types zrdcdS)NOrrs rbkindzPandasArrayExtensionDtype.kindssrdcd|jdS)Nzarray[r5)rrs rbnamezPandasArrayExtensionDtype.names*****rdc|jSrrmrs rbrz$PandasArrayExtensionDtype.value_types rdN)rrr _metadatarrrlrrOArrayrrrw classmethodrzpropertyrCrQr~rrrrdrbr%r%s#I&5)Dbh)N#O&&&&4E"(BO*C$D4444))[)dXcX+c+++X+ BH   X   rdr%c eZdZddejdefdZddZddeddfd Ze dd e e deddfd Z e d e dddfd Zede fdZedefdZdejfdZdeeeejfdeddfdZdeeeejfdeejdffdZ dde edededdfdZdefdZdejfdZdS) rvFdatacopycr|s|ntj||_t|j|_dSr)rrW_datar%rl_dtype)rrrs rbrz"PandasArrayExtensionArray.__init__"s/!%9TT28D>> / ;; rdNc$|tkrctjt|jt}t t|jD]}|j|||<|S||jS|j|S)a Convert to NumPy Array. Note that Pandas expects a 1D array when dtype is set to object. But for other dtypes, the returned shape is the same as the one of ``data``. More info about pandas 1D requirement for PandasExtensionArray here: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.api.extensions.ExtensionArray.html#pandas.api.extensions.ExtensionArray rP)r^rr]rjrrrU)rrloutrHs rbrEz#PandasArrayExtensionArray.__array__&s F??(3tz??&999C3tz??++ ' 'AAJ =: :$$U++ +rddeepr&c.t|jdS)NTr)rvr)rrs rbrzPandasArrayExtensionArray.copy:s($????rdrlctdkrz;PandasArrayExtensionArray._from_sequence..Asi$ $ jkJq"* % % e!'WQZ5E*E e!'U\]^U_UeJe$ $ $ $ $ $ rd)rlrrPr)rjallrrWrr]r^)ryrrlrrs ` rb_from_sequencez(PandasArrayExtensionArray._from_sequence=s w<PandasArrayExtensionArray._concat_same_type..Lsc& &  HNil06 6 e28>YWX\M_Me;e& & & & & & rdcg|] }|j Srrrrs rbrz?PandasArrayExtensionArray._concat_same_type..Ps;;;2bh;;;rdrPcg|] }|j Srrrs rbrz?PandasArrayExtensionArray._concat_same_type..Ss444Brx444rdFr)rjrrvstackr]r^)ryrrs ` rb_concat_same_typez+PandasArrayExtensionArray._concat_same_typeJs y>>A  #& & & & & & & # # 9;;;;;<._s,BBB))++BBBrd)rrWrrs rbrzPandasArrayExtensionArray.isna^s#xBBtzBBBCCCrdrrctr)NotImplementedError)rrrs rb __setitem__z%PandasArrayExtensionArray.__setitem__as!###rditemc~t|tr |j|St|j|dS)NFr)rrrrv)rrs rbrIz%PandasArrayExtensionArray.__getitem__ds; dC  $:d# #(D)9FFFFrdindices allow_fill fill_valuectj|t}|r| |jjntj||jj}|dk}|dkrtdt|dkrnetj |stdtj |gt|z|jj}t|dS|j |d}|r/|r|gtj|z||<t|dS) NrPrhzFInvalid value in `indices`, must be all >= -1 for `allow_fill` is TruerzAInvalid take for empty PandasArrayExtensionArray, must be all -1.FrrK)rrrrlna_valuerrrVrjr IndexErrorrWrvrtakesum)rrrrmaskrtooks rbrzPandasArrayExtensionArray.takeisE!j<<<  C'1'9 ##rz*\`\f\q?r?r?r b=D" !!## C !ijjjTQVD\\ C !deeex s7|| ;4:CXYYY0EBBBBzwQ//  5$((** 5$t 4DJ(E::::rdc*t|jSr)rjrrs rb__len__z!PandasArrayExtensionArray.__len__s4:rdct|tstdt||j|jkS)NzInvalid type to compare to: )rrvrrCrr)rothers rb__eq__z PandasArrayExtensionArray.__eq__sN%!:;; T%&RT%[[&R&RSS S ek)..000rdFr)NF)FN)rrrrrr)rrErrrr%r Sequence_rrrlrrrrslicer rrIrrrrrdrbrvrv!sb<>> from datasets import Features >>> features = Features({'label': ClassLabel(num_classes=3, names=['bad', 'ok', 'good'])}) >>> features {'label': ClassLabel(num_classes=3, names=['bad', 'ok', 'good'], id=None)} ``` N num_classesnames names_filerr-rlr_str2int_int2strFrrcb||_||_|j|jtd|ja|j ||j|_nx|j$dt |jD|_nMtdt |jts$tdt|j|jt|j|_nJ|jt|jkr-tdt|jd|jdd|jD|_ d t|j D|_ t|j t|j krtd dS) Nz7Please provide either names or names_file but not both.c,g|]}t|SrrQ)rrHs rbrz,ClassLabel.__post_init__..sFFFc!ffFFFrdz7Please provide either num_classes, names or names_file.z#Please provide names as a list, is zEClassLabel number of names do not match the defined num_classes. Got z names VS z num_classesc,g|]}t|Srrrrs rbrz,ClassLabel.__post_init__..s:::tT:::rdci|]\}}|| Srr)rrHrs rbrz,ClassLabel.__post_init__..sIIIWQqIIIrdzBSome label names are duplicated. Each label name should be unique.)rrrrV_load_names_from_filerr SequenceABC TypeErrorrCrjrrYr)rrrs rbrzClassLabel.__post_init__s&$ ? &4:+AVWW W : *!77HH !-FFeD4D.E.EFFF  !Z[[[DJ 44 VT$tzBRBRTTUU U   #"4:D    TZ 0 0Q4:QQ262BQQQ  ;:tz::: II $-0H0HIII t}  T]!3!3 3 3abb b 4 3rdc|jSrrrs rbrzClassLabel.__call__rrdvaluesr&ct|ts(t|tstd|dd}t|tr|g}d}fd|D}|r|n|dS)a Conversion class name `string` => `integer`. Example: ```py >>> from datasets import load_dataset >>> ds = load_dataset("rotten_tomatoes", split="train") >>> ds.features["label"].str2int('neg') 0 ``` Values zS should be a string or an Iterable (list, numpy array, pytorch, tensorflow tensors)TFc:g|]}|Sr _strval2int)rrrs rbrz&ClassLabel.str2int..s'>>>e$""5))>>>rdr)rrQrrV)rr return_listrs` rbstr2intzClassLabel.str2ints&#&& z&(/K/K u&uuu  fc " " XFK>>>>v>>>$3vv&)3rdrcPd}t|}|j|}|d|j|}|6 t |}|dks ||jkrd}n#t $rd}YnwxYw|rt d||S)NFrhTzInvalid string class label )rQrgetstriprrrV)rr failed_parse int_values rbrzClassLabel._strval2ints E M%%e,,   ))%++--88I , #E I!2~~d6F)F)F'+ "(((#'LLL(  DB5BBCC CsB BBcBt|ts(t|tstd|dd}t|tr|g}d}|D])}d|cxkr jksntd|d*fd|D}|r|n|dS) adConversion `integer` => class name `string`. Regarding unknown/missing labels: passing negative integers raises `ValueError`. Example: ```py >>> from datasets import load_dataset >>> ds = load_dataset("rotten_tomatoes", split="train") >>> ds.features["label"].int2str(0) 'neg' ``` rzU should be an integer or an Iterable (list, numpy array, pytorch, tensorflow tensors)TFrzInvalid integer class label r#cDg|]}jt|Sr)rr)rrrs rbrz&ClassLabel.int2str..!s&888A$-A'888rd)rrrrVr)rrrrrs` rbint2strzClassLabel.int2strs&#&& z&(/K/K w&www  fc " " XFK G GA,,,,D,,,,, !E!E!E!EFFF-9888888$3vv&)3rdc|jtdt|tr||}d|cxkr |jksntd|dd|j|S)NzlTrying to use ClassLabel feature with undefined number of class. Please set ClassLabel.names or num_classes.rh Class label r#% greater than configured num_classes )rrVrrQr)r example_datas rbrzClassLabel.encode_example$s   #>  lC ( ( 6<< 55L\4444D$44444sLsssaeaqsstt trdrBct|tjrkt|dkrXt j|}|djkr td|ddjnLt|tj r2tj fd| D}t|j S)aCast an Arrow array to the `ClassLabel` arrow storage type. The Arrow types that can be converted to the `ClassLabel` pyarrow storage type are: - `pa.string()` - `pa.int()` Args: storage (`Union[pa.StringArray, pa.IntegerArray]`): PyArrow array to cast. Returns: `pa.Int64Array`: Array in the `ClassLabel` arrow storage type. rmaxrrcBg|]}||ndSrr)rlabelrs rbrz+ClassLabel.cast_storage..Js1iiiEE,=!!%(((4iiird)rrO IntegerArrayrjpcmin_maxrNrrV StringArrayrWrjrr)rrBrs` rb cast_storagezClassLabel.cast_storage4s gr / / CLL14D4Dj))//11Gu~!111 j75>jjX\Xhjj2 0 0 hiiiiU\UfUfUhUhiiiG'4<000rdct|d5}d|dDcdddS#1swxYwYdS)Nutf-8)encodingc^g|]*}||+Sr)rrs rbrz4ClassLabel._load_names_from_file..Qs-RRRTTZZ\\RDJJLLRRRrd )openreadsplit)names_filepathfs rbrz ClassLabel._load_names_from_fileNs .7 3 3 3 SqRRQVVXX^^D-A-ARRR S S S S S S S S S S S S S S S S S Ss1AAA)'rrrrrrrrrrrrQrrrlrrOr-rr rrrrrrrrrrrrrrr Int64Arrayr staticmethodrrrdrbrrs<+/K#'...E49)-J &---B "E8C="""%RXZZGXc]''')-HhtCH~&---)-HhtCH~&---|%eDDDE3DDDccc:4eCM24uS(]7K44440*4eCM24uS(]7K4444< 1E"."/*I$J1r}11114SS\SSSrdrceZdZUdZeed<dZeed<dZe e ed<dZ e e ed<dZ e eed <edd d Ze ed <dS) ra Construct a list of feature from a single type or a dict of types. Mostly here for compatiblity with tfds. Args: feature: A list of features of a single type or a dictionary of types. length (`int`): Length of the sequence. Example: ```py >>> from datasets import Features, Sequence, Value, ClassLabel >>> features = Features({'post': Sequence(feature={'text': Value(dtype='string'), 'upvotes': Value(dtype='int32'), 'label': ClassLabel(num_classes=2, names=['hot', 'cold'])})}) >>> features {'post': Sequence(feature={'text': Value(dtype='string', id=None), 'upvotes': Value(dtype='int32', id=None), 'label': ClassLabel(num_classes=2, names=['hot', 'cold'], id=None)}, length=-1, id=None)} ``` featurerhlengthNrrrlrFrr)rrrrr rrrrrrQrlrrrrrrdrbrrTs&LLLFCB !E8C=!!!!GXc]!!!zEBBBE3BBBBBrdrschemacB|dSt|ttfr~|"t|tttfrZt |dkrE|n,t|ttfr |d}n|j}t |d|SdSdS)z Check if the object is not None. If the object is a list or a tuple, recursively check the first element of the sequence and stop if at any point the first element is not a sequence or is an empty sequence. NFrT)rrrrrjrr)rrs rbrrs  {u C$ ' ' V^z&SWY^`hRi?j?j^ s88a<<~FT5M22 (6s1vvFF F5trdcttr tjfdDSttr tjfdDStt t frKtdkrtdtd}tj |Sttrhtj }tj tr tjfd|DStj |j SS)a get_nested_type() converts a datasets.FeatureType into a pyarrow.DataType, and acts as the inverse of generate_from_arrow_type(). It performs double-duty as the implementation of Features.type and handles the conversion of datasets.Feature->pa.struct c<i|]}|t|Srget_nested_typerrrs rbrz#get_nested_type..' A A A3S/&+.. A A Ardc<i|]}|t|Srrrs rbrz#get_nested_type..rrdrzQWhen defining list feature, you should just provide one example of the inner typercZi|]'}|jtj|jj(Sr)rrOr"rCr)rrrs rbrz#get_nested_type..s-ZZZ!afbhqvv}&E&EZZZrd)rFeaturesrOstructrrrrjrVrr"rrr)rrs` rbrrsV&(##3y A A A A& A A A    FD ! !3y A A A A& A A A    FT5M * * 3 v;;!  pqq q$VAY// x ### FH % %3$V^44 fnd + + \9ZZZZzZZZ[[ [x FM222 688Ordc ttr7dkr|td|fdt|DndSttt frmd|dSt |dkr?|D]}t|rnt|dz|krfd|DSt |SttrJ|dStj tri}t|tt fr4tj g|RD]\}fdddD||< |Stj |D]\}\}fd |D||<|St|trtd |d t |dkr^|D]}t|j rnt|trtj |dz|krfd |DSt |Stttttt t"fr||ndS|S) aEncode a nested example. This is used since some features (in particular ClassLabel) have some logic during encoding. To avoid iterating over possibly long lists, it first checks (recursively) if the first element that is not None or empty (if it is a sequence) has to be encoded. If the first element needs to be encoded, then all the elements of the list will be encoded, otherwise they'll stay the same. rNz*Got None but expected a dictionary insteadc Hi|]\}\}}|t||dzSrlevelencode_nested_example)rr sub_schemasub_objrs rbrz)encode_nested_example..sH   ,A, G(WEAINNN   rdrrc:g|]}t|dzSr rrorrs rbrz)encode_nested_example..s.___VW1*auqyQQQ___rdcFg|]}td|dzS)rrrr)rr dict_tuplesrs rbrz)encode_nested_example..s5#w#w#wbc$9+a.!SX[\S\$]$]$]#w#w#wrdc:g|]}t|dzSr rrs rbrz)encode_nested_example..s/#l#l#l^_$9*auWXy$Y$Y$Y#l#l#lrdz+Got a string but expected a list instead: ''cDg|]}tj|dzSr )rr)rrrrs rbrz)encode_nested_example..s1cccZ[1&.!5ST9UUUcccrd)rrrVrrrrjrrrrrQr r!rr$rrr) rrrr list_dictrsub_objsrrs ` ` @@rbrrs6&$;G A::#+IJJ J      080E0E        FT5M * */GAY ;43xx!||"%J::zRR(ZuqyQQQU________[^____99  FH % %#G ;4 fnd + + !I#e}-- !&.v~&D&D&D&DxxNA{#w#w#w#w#wgrstsusugv#w#w#wIaLL  2:&.#1N1Nmm-A- H#l#l#l#l#lck#l#l#lIaLL  c3   Q3QQQRR R3xx!||"%J::v~VV#:t44d,V^ZuWXyYYY]gggccccc_bcccc99  FUE:7SUZ\de f fG-0_v$$S)))$F Jrdtoken_per_repo_idcttrdtDndStttfrgddSt dkr9D]}t |rnt||krfdDStSttrDtj trfdj DStj gStttfr j r |SS)aDecode a nested example. This is used since some features (in particular Audio and Image) have some logic during decoding. To avoid iterating over possibly long lists, it first checks (recursively) if the first element that is not None or empty (if it is a sequence) has to be decoded. If the first element needs to be decoded, then all the elements of the list will be decoded, otherwise they'll stay the same. Nc<i|]\}\}}|t||Srdecode_nested_example)rrrrs rbrz)decode_nested_example.. s/ q q q?WqBW:wQ%j':: q q qrdrc0g|]}t|Srr!)rrrs rbrz)decode_nested_example..s$NNNQ1*a@@NNNrdcVi|]%}|tj|g|&Sr)r"r)rrrrs rbrz)decode_nested_example.. s4bbbaA,fnQ.?-@#a&IIbbbrdr)rrrrrrjrr"rrr r!decodedecode_example)rrrrrs`` @rbr"r"s&$S r q[cdjlo[p[p q q q q FT5M * *SAY ;43xx!||"%J::zRR(Z@@JNNNNNN#NNNN99  FH % % S fnd + + @bbbbbSYSabbb b(&.)93?? ? FUEN + +S ?v}?((@Q(RR R Jrdct|tr d|DSd|vst|dtrd|DSt |d}|t kr8t t|d|ddSdt|D|d ifd |DS) aRegenerate the nested feature object from a deserialized dict. We use the '_type' fields to get the dataclass name to load. generate_from_dict is the recursive helper for Features.from_dict, and allows for a convenient constructor syntax to define features from deserialized JSON dictionaries. This function is used in particular when deserializing a :class:`DatasetInfo` that was dumped to a JSON object. This acts as an analogue to :meth:`Features.from_arrow_schema` and handles the recursive field-by-field instantiation, but doesn't require any mapping to/from pyarrow, except for the fact that it takes advantage of the mapping of pyarrow primitive dtypes that :class:`Value` automatically performs. c,g|]}t|Srgenerate_from_dict)rrs rbrz&generate_from_dict..8s!;;;e"5));;;rdrc4i|]\}}|t|Srr*)rrrs rbrz&generate_from_dict..;s'MMM:3'..MMMrdrrrhrrch|] }|j Srrrrs rb z%generate_from_dict..As666a16666rdc$i|] \}}|v || Srr)rrr field_namess rbrz&generate_from_dict..Bs)JJJ$!Qk9I9IA9I9I9Irdr) rrrrrpoprr+rr )r class_typer3s @rbr+r++s#t<;;s;;;;cZG d;;MMMMMM3777++,JX 23y> B B377S[]_K`K`aaaa666*#5#5666K : K KJJJJ#))++JJJ K KKrdct|tjr d|DSt|tjr(t t |j|jSt|tjrIt |j}t|tttfr|gSt |St|tr>ddtttt g|j}||j|jSt|tjrt(t|tjrt-t/|St1d|d) a generate_from_arrow_type accepts an arrow DataType and returns a datasets FeatureType to be used as the type for a single field. This is the high-level arrow->datasets type conversion and is inverted by get_nested_type(). This operates at the individual *field* level, whereas Features.from_arrow_schema() operates at the full schema level and holds the methods that represent the bijection from Features<->pyarrow.Schema cBi|]}|jt|jSrrgenerate_from_arrow_typerCrrs rbrz,generate_from_arrow_type..Ps'VVVU 4UZ@@VVVrdr-rN)rrlrPzCannot convert z to a Feature type.)rrO StructTypeFixedSizeListTyperr9r list_sizeListTyperrrrrrr r rrDictionaryTyperr9rrcrV)rr array_features rbr9r9Esi'2=))IVVgVVVV GR1 2 2I 89K L LU\Ufgggg GR[ ) ) I*7+=>> geT2 3 3 9 (((( G2 3 3ItWgwHW }7=8JKKKK GR. / /I!! GR[ ) )I3G<<====G7GGGHHHrdrirCctj|}tj||}t |jdz D]}t t|jd|j|z dz d}|j|j|z dz }tjtj |dz|ztj }tj ||}|S)z=Build a PyArrow ListArray from a multidimensional NumPy arrayrCrN) rrWrOrRrrr r rrQr, ListArray from_arrays)rirCrrH n_offsets step_offsetsrXs rbnumpy_to_pyarrow_listarrayrHcs (3--C Xckkmm$ / / /F 38a< ;;3 *.psDDD&!S A rdcg|]}||Srrrhs rbrz:list_of_pa_arrays_to_pyarrow_listarray..qs 5 5 5SS_S___rdrc,g|]}t|Sr)rjrhs rbrz:list_of_pa_arrays_to_pyarrow_listarray..ss)))Cs3xx)))rdrPrC) rYrcumsumr^rTrOrWr,rtrDrE)rIr`rXrs rb&list_of_pa_arrays_to_pyarrow_listarrayrOosDDIe$4$4DDDL 5 5E 5 5 5Ei ))5))))Git44GhwRXZZ000G  e $ $F < # #GV 4 44rdct|dkrtfd|DStjgS)zEBuild a PyArrow ListArray from a possibly nested list of NumPy arraysrc:g|]}|t|ndS)NrC)rH)rrirCs rbrz9list_of_np_array_to_pyarrow_listarray..s2 f f fY\3? '$ 7 7 7 7PT f f frdrC)rjrOrOrW)rIrCs `rb%list_of_np_array_to_pyarrow_listarrayrR{sS 5zzA~~5 f f f f`e f f f   x&&&&rdrct|tjrdSt|tr"t t |dSdS)zReturn `True` if data is a NumPy ndarray or (recursively) if first non-null value in list is a NumPy ndarray. Args: data (Any): Data. Returns: bool TrF)rrrrcontains_any_np_arrayr)rs rbrTrTsP$ ##t D$  $%9$%?%?%BCCCurdct|tjrt|St|trt fd|DSdS)a0Convert to PyArrow ListArray either a NumPy ndarray or (recursively) a list that may contain any NumPy ndarray. Args: data (Union[np.ndarray, List]): Data. type (pa.DataType): Explicit PyArrow DataType passed to coerce the ListArray data type. Returns: pa.ListArray rCc2g|]}t|S)rC)!any_np_array_to_pyarrow_listarray)rrHrCs rbrz5any_np_array_to_pyarrow_listarray..s*6u6u6ukl7XYZae7f7f7f6u6u6urdN)rrrrHrrO)rrCs `rbrWrWsp$ ##w)$T:::: D$  w56u6u6u6upt6u6u6uvvvwwrdct|rt||jStj||jS)zConvert to PyArrow ListArray. Args: data (Any): Sequence, iterable, np.ndarray or pd.Series. pa_type (_ArrayXDExtensionType): Any of the ArrayNDExtensionType. Returns: pyarrow.Array rC)rTrWrrOrWr)rrs rbto_pyarrow_listarrayrYs?T""50G.s+AA1#A&&AAAAAArdrr'T) rrrrrrr^rrhasattrr&)rrZs rbr^r^s'4  pAA0@0@AAAAAA GdE] + +p +++ GX & &p000w 011oMd7nw~~jnordcVt|tr+td|DSt|tt frt |dSt|trt |jSt|dS)zCheck if a (possibly nested) feature requires storage casting. Args: feature (FeatureType): the feature type to be checked Returns: :obj:`bool` c34K|]}t|VdSrrequire_storage_castr0s rbrz'require_storage_cast..+EEq'**EEEEEErdrr rrrrrrrcrrr_r;s rbrcrcs'4  0EEGNN4D4DEEEEEE GdE] + +0#GAJ/// GX & &0#GO444w///rdcVt|tr+td|DSt|tt frt |dSt|trt |jSt|dS)zCheck if a (possibly nested) feature requires embedding data into storage. Args: feature (FeatureType): the feature type to be checked Returns: :obj:`bool` c34K|]}t|VdSrrbr0s rbrz(require_storage_embed..rdrdr embed_storagerer;s rbrequire_storage_embedris'4  1EEGNN4D4DEEEEEE GdE] + +1#GAJ/// GX & &1#GO444w000rdcJtfd}d|_|S)z Wrapper to keep the secondary dictionary, which tracks whether keys are decodable, of the :class:`datasets.Features` object in sync with the main dictionary. c|r|d}|dd}n|d}|g|Ri|}t|dsJd|D|_|S)Nrrr_column_requires_decodingc4i|]\}}|t|Srr]rcolrs rbrz?keep_features_dicts_synced..wrapper..s()j)j)j\SRY#/?/H/H)j)j)jrd)r4r_rrl)argskwargsrrfuncs rbwrapperz+keep_features_dicts_synced..wrappers  2#AwD8DD%zz&11Dd4)$)))&))t899999)j)j]a]g]g]i]i)j)j)j& rd_keep_dicts_synced)r _decorator_name_)rrrss` rbkeep_features_dicts_syncedrvs=  4[[    [  4G Nrdc jeZdZdZfdZeejZeejZeej Z eej Z eej Z eej Z eej Z dZedZedZedejddfdZedd Zd Zdefd Zed eddfd ZdZdefdZdZd dedee ee!ee"dfffdZ#dedefdZ$d dedee ee!ee"dfffdZ%ddZ&d!dZ'd"ddZ(xZ)S)#r aA special dictionary that defines the internal structure of a dataset. Instantiated with a dictionary of type `dict[str, FieldType]`, where keys are the desired column names, and values are the type of that column. `FieldType` can be one of the following: - a [`~datasets.Value`] feature specifies a single typed value, e.g. `int64` or `string`. - a [`~datasets.ClassLabel`] feature specifies a field with a predefined set of classes which can have labels associated to them and will be stored as integers in the dataset. - a python `dict` which specifies that the field is a nested field containing a mapping of sub-fields to sub-fields features. It's possible to have nested fields of nested fields in an arbitrary manner. - a python `list` or a [`~datasets.Sequence`] specifies that the field contains a list of objects. The python `list` or [`~datasets.Sequence`] should be provided with a single sub-feature as an example of the feature type hosted in this list. A [`~datasets.Sequence`] with a internal dictionary feature will be automatically converted into a dictionary of lists. This behavior is implemented to have a compatilbity layer with the TensorFlow Datasets library but may be un-wanted in some cases. If you don't want this behavior, you can use a python `list` instead of the [`~datasets.Sequence`]. - a [`Array2D`], [`Array3D`], [`Array4D`] or [`Array5D`] feature for multidimensional arrays. - an [`Audio`] feature to store the absolute path to an audio file or a dictionary with the relative path to an audio file ("path" key) and its bytes content ("bytes" key). This feature extracts the audio data. - an [`Image`] feature to store the absolute path to an image file, an `np.ndarray` object, a `PIL.Image.Image` object or a dictionary with the relative path to an image file ("path" key) and its bytes content ("bytes" key). This feature extracts the image data. - [`~datasets.Translation`] and [`~datasets.TranslationVariableLanguages`], the two features specific to Machine Translation. c|std|^}}tt|j|i|d|D|_dS)Nz.+s4; ; ; /;sGC!'**; ; ; rd)rsuperr rrrl)rprqrrs rbrzFeatures.__init__%su \Z[[ [ t&h&7777; ; ?Czz||; ; ; &&&rdc0tt|ffSr)r rrs rbrzFeatures.__reduce__7s$t**&&rdc t|S)z] Features field types. Returns: :obj:`pyarrow.DataType` rrs rbrCz Features.type:st$$$rdcdd|ii}tj|jdt j|iS)zV Features schema. Returns: :obj:`pyarrow.Schema` infofeatures huggingface)rrOrrC with_metadatajsondumps)r hf_metadatas rb arrow_schemazFeatures.arrow_schemaDsJ DLLNN;< y##11=$*[BYBY2Z[[[rd pa_schemar&c||jdd|jvrtj|jdd}d|vr>d|dvr4|dd&t |ddSd|D}|di|S)a  Construct [`Features`] from Arrow Schema. It also checks the schema metadata for Hugging Face Datasets features. Args: pa_schema (`pyarrow.Schema`): Arrow Schema. Returns: [`Features`] Nrrr~rcBi|]}|jt|jSrr8r:s rbrz.Features.from_arrow_schema..as'WWWEuz3EJ??WWWrdr)metadataencoderloadsr&r  from_dict)ryrrrs rbfrom_arrow_schemazFeatures.from_arrow_schemaOs   )m.B.B7.K.KyOa.a.az)"4]5I5I'5R5R"S"Z"Z"\"\]]H!!jHV4D&D&DRXIYZdIeIq))(6*::*FGGGWWYWWWszzSzzrdc0t|}|di|S)a Construct [`Features`] from dict. Regenerate the nested feature object from a deserialized dict. We use the `_type` key to infer the dataclass name of the feature `FieldType`. It allows for a convenient constructor syntax to define features from deserialized JSON dictionaries. This function is used in particular when deserializing a [`DatasetInfo`] that was dumped to a JSON object. This acts as an analogue to [`Features.from_arrow_schema`] and handles the recursive field-by-field instantiation, but doesn't require any mapping to/from pyarrow, except for the fact that it takes advantage of the mapping of pyarrow primitive dtypes that [`Value`] automatically performs. Args: dic (`dict[str, Any]`): Python dictionary. Returns: `Features` Example:: >>> Features.from_dict({'_type': {'dtype': 'string', 'id': None, '_type': 'Value'}}) {'_type': Value(dtype='string', id=None)} rr*)rydicrs rbrzFeatures.from_dictds#4!%%szzSzzrdc t|Sr)rrs rbrzFeatures.to_dictsd||rdc|}dtdtfddtttfdtffd |dS)Nrr&ct|ts"tdt|d|t|dtr+t |ddgkr|dd|d<t|dtr+t |ddgkr|dd|d<t|dtr+t |ddgkr|dd|d<t|dtr+t |ddgkr|dd|d<t|dtr\t|ddt r.d t |ddD|dd<|S) NExpected a dict but got a : sequencerlr r class_labelrc4i|]\}}t||Srr)rlabel_id label_names rbrz.simplify..s13332F(JCMM:333rd)rrrrCrrrYr;s rbsimplifyz(Features._to_yaml_list..simplifysgt,, Y WT']] W Wg W WXXX '++j11488 CT'*BU=V=V[bZc=c=c&-j&9'&B #'++j11488 DT'*BU=V=V[cZd=d=d&-j&9(&C # '++f--t44 ;gfo9N9NSZR[9[9[")&/'":'++f--t44 <gfo9N9NS[R\9\9\")&/(";'++m44d;;  7S`KaKeKefmKnKnpt@u@u 33JST[\iTjkrTsJtJt333 &w/Nrdrc 2t|tr|dd}|dkr-|d}d|i|S|dkr|S|r|sdt|iS|rdt||iiSdfd|DiSt|t r%d |d iSt d t|d |) Nrrrrrrlr c4g|]\}}d|i|Sr/r)rr_feature to_yaml_inners rbrzAFeatures._to_yaml_list..to_yaml_inner..s4&s&s&sUcUY[c'P h8O8O'P&s&s&srdrr"Expected a dict or a list but got r)rrr4rrrrrC)rrrrrs rbrz-Features._to_yaml_list..to_yaml_inners]#t$$ Y..J&&"wwy11H#8Zx1H1H$PC$PQQQg%%Ju3u#%;E%B%BCCu#XX/Ee/L/Lc.R%S%STT$&s&s&s&sgjgpgpgrgr&s&s&sttC&& Yx--A2G2G)H)H IJJJ WT#YY W WRU W WXXXrdr )rrrr)r yaml_datarrs @@rb _to_yaml_listzFeatures._to_yaml_listsLLNN / d/ t/ / / / b YuT4Z0 YT Y Y Y Y Y Y Y&}Y''11rdrctj|}dtdtfddtttfdtttfffd ||S)Nrr&c >tts"tdtdtdt r ddid<tdt r ddid<tdtrtddtrt ddt}|rid |Dttt|d d zkr)td t|d d zd fd|Ddd<S)Nrrrrlrrr)rc,g|]}t|Sr)r)rrs rbrz@Features._from_yaml_list..unsimplify..s!J!J!JH#h--!J!J!Jrdrhrz1ClassLabel expected a value for all label ids [0:z] but some ids are missing.c8g|]}dd|S)rrr)rrrs rbrz@Features._from_yaml_list..unsimplify..s*2w2w2wai7=3I'3RS[3\2w2w2wrd) rrrrCrrQsortedrrrrV)r label_idss` rb unsimplifyz,Features._from_yaml_list..unsimplifysgt,, Y WT']] W Wg W WXXX '++j11377 E'. 0C&D # '++f--s33 =#*GFO"<'++m44d;; x 7S`KaKeKefmKnKnpt@u@u x"7=#9'#BLLL !J!J !J!J!JdSXY\]fgi]jYkYknoYoSpSpNqNq!q!q$CPYZ\P]L^L^abLb3x2w2w2wmv2w2w2w &w/Nrdrc>t|tr(|siStt|}|dkr1||}d|i|ddiS|dkr||gS|dkr|dS|dkrqt|dt rE t |di|ddiS#t$rdt|dicYSwxYw|dSdt|i||St|tr(d |D}fd t||DStd t|d |) Nrrrrrr rlrc8g|]}|dSr/)r4)rrs rbrzEFeatures._from_yaml_list..from_yaml_inner.. s$BBB(f--BBBrdc.i|]\}}||Srr)rrrfrom_yaml_inners rbrzEFeatures._from_yaml_list..from_yaml_inner..s)^^^ND(ooh77^^^rdrr) rrnextiterr4rQrrVrrziprrC)rrrrrrs rbrz1Features._from_yaml_list..from_yaml_inners#t$$ YIT#YYJ&&)z#22599H%x'@'@]C]R\]]]F??+OJJsOOE,BCCDDH$$*?3x=999g%%!#g,44 =S!#g,///# YtTz!2 YuT4Z7H Y Y Y Y Y Y Y>}}__Y77888rdc@t|}t||S)z Encode example into a format for Arrow. Args: example (`dict[str, Any]`): Data in a Dataset row. Returns: `dict[str, Any]` )rr)rexamples rbrzFeatures.encode_examples!)11$T7333rd column_namecBt|}fd|DS)a Encode column into a format for Arrow. Args: column (`list[Any]`): Data in a Dataset column. column_name (`str`): Dataset column name. Returns: `list[Any]` c<g|]}t|Srr)rrrrs rbrz*Features.encode_column..0s)PPP#%d;&7==PPPrd)rrcolumnrs` `rb encode_columnzFeatures.encode_column"s0(//PPPPPPPPPrdc"i}t|tkr/tdt|dt|D]&\}t|}fd|D|<'|S)z Encode batch into a format for Arrow. Args: batch (`dict[str, list[Any]]`): Data in a Dataset batch. Returns: `dict[str, list[Any]]` zColumn mismatch between batch z and features c<g|]}t|Srr)rrrrs rbrz)Features.encode_batch..Bs(!Z!Z!ZC"7S 3"G"G!Z!Z!Zrd)setrVrr)rbatch encoded_batchrrs` @rb encode_batchzFeatures.encode_batch2s u::T " "cc%jjccX[\`XaXaccdd d ;;== [ [KC+F33F!Z!Z!Z!Z!ZSY!Z!Z!ZM#  rdNrrc~fdtfdDDS)aDecode example with custom feature decoding. Args: example (`dict[str, Any]`): Dataset row data. token_per_repo_id (`dict`, *optional*): To access and decode audio or image files from private repositories on the Hub, you can pass a dictionary `repo_id (str) -> token (bool or str)`. Returns: `dict[str, Any]` c`i|]*\}\}}|j|rt||n|+S)r%)rlr")rrrrrrs rbrz+Features.decode_example..Ss]   . -gu -k:.wQbcccc   rdc$i|] \}}|v || Srr)rrrrs rbrz+Features.decode_example..Xs$MMM UcWnnennnrd)rr)rrrs```rbr'zFeatures.decode_exampleEsb     2:MMMMdjjllMMMw22     rdrcBjrfd|Dn|S)zDecode column with custom feature decoding. Args: column (`list[Any]`): Dataset column data. column_name (`str`): Dataset column name. Returns: `list[Any]` cDg|]}|t|ndSrr!)rrrrs rbrz*Features.decode_column..is5 p p p`e@Q "4 #4e < < token (bool or str) Returns: `dict[str, list[Any]]` cHg|]}|t|ndS)Nr%r!)rrrrrs rbrz)Features.decode_batch..~sN(*${*;UVghhhhrd)rrl)rrr decoded_batchrrs` ` @rb decode_batchzFeatures.decode_batchns #(;;==   K1+> "(  + & &rdc*tj|S)a Make a deep copy of [`Features`]. Returns: [`Features`] Example: ```py >>> from datasets import load_dataset >>> ds = load_dataset("rotten_tomatoes", split="train") >>> copy_of_features = ds.features.copy() >>> copy_of_features {'label': ClassLabel(num_classes=2, names=['neg', 'pos'], id=None), 'text': Value(dtype='string', id=None)} ``` )rrrs rbrz Features.copys$}T"""rdrcBdfd t||S)a Reorder Features fields to match the field order of other [`Features`]. The order of the fields is important since it matters for the underlying arrow data. Re-ordering the fields allows to make the underlying arrow data type match. Args: other ([`Features`]): The other [`Features`] to align with. Returns: [`Features`] Example:: >>> from datasets import Features, Sequence, Value >>> # let's say we have to features with a different order of nested fields (for a and b for example) >>> f1 = Features({"root": Sequence({"a": Value("string"), "b": Value("string")})}) >>> f2 = Features({"root": {"b": Sequence(Value("string")), "a": Sequence(Value("string"))}}) >>> assert f1.type != f2.type >>> # re-ordering keeps the base structure (here Sequence is defined at the root level), but make the fields order match >>> f1.reorder_fields_as(f2) {'root': Sequence(feature={'b': Value(dtype='string', id=None), 'a': Value(dtype='string', id=None)}, length=-1, id=None)} >>> assert f1.reorder_fields_as(f2).type == f2.type c fr dddznd}ttr>jttrdDngttrjjjc}}ttrYdD}td|D||Sg}t|d||Sttrttstd d |zttkrod d d  z d z d |z}t|fdDSttrttstd d |zttkrtdd |zfdttDSS)Nz at rrci|] \}}||g Srrrrrs rbrzIFeatures.reorder_fields_as..recursive_reorder.. @@@Aa!@@@rdci|] \}}||g Srrrs rbrzIFeatures.reorder_fields_as..recursive_reorder..rrdc&i|]\}}||dSrrrs rbrzIFeatures.reorder_fields_as..recursive_reorder..s"$K$K$KAQ!$K$K$Krd)rrrzType mismatch: between rizKeys mismatch: between z (source) and z (target). z are missing from target and z are missing from sourcec Pi|]"}|||d|z#Sr6r)rrrecursive_reordersourcestacktargets rbrzIFeatures.reorder_fields_as..recursive_reorder..sCnnn`c..vc{F3KQZUXQZQZIZ[[nnnrdzLength mismatch: between cHg|]}||dzS)z.r)rrHrrrrs rbrzIFeatures.reorder_fields_as..recursive_reorder..s7oooWX))&)VAY @QRRooord) rrrrrrrrVrkeysrrjr) rrrstack_positionid_r reorderedmessagers ``` rbrz5Features.reorder_fields_as..recursive_reorders38@VeABBi//bN&(++ &fd++&@@@@@FF$XF&(++ &,nfi#Vfd++I@@@@@F 1 1&&% H HI#$K$K9J9J$K$K$KPS\bcccc$XF 1 1&&% H HI#IaLSHHHHFD)) !&$//g$%Tv%T%TF%T%TWe%efff&>>VF^^33U&UUUU!;;==6UU%{{}}V[[]]:UUUWef %W---nnnnnnngmnnnnFD)) !&$//g$%Tv%T%TF%T%TWe%efffv;;#f++--$%V%V%Vf%V%VYg%ghhhooooooo\abeflbmbm\n\noooo rd)r)r )rrrs @rbreorder_fields_aszFeatures.reorder_fields_ass@6$ $ $ $ $ $ L))$66777rdctd|D]h}d}|}|D]3\}t|tr9d}|fd|D|=Tt|t rXt|jtr>d}|fd|jD|=t|drb| |krJd}|fd| D|=5|}|rnj|S)aXFlatten the features. Every dictionary column is removed and is replaced by all the subfields it contains. The new fields are named by concatenating the name of the original column and the subfield name like this: `.`. If a column contains nested dictionaries, then all the lower-level subfields names are also concatenated to form new columns: `..`, etc. Returns: [`Features`]: The flattened features. Example: ```py >>> from datasets import load_dataset >>> ds = load_dataset("squad", split="train") >>> ds.features.flatten() {'answers.answer_start': Sequence(feature=Value(dtype='int32', id=None), length=-1, id=None), 'answers.text': Sequence(feature=Value(dtype='string', id=None), length=-1, id=None), 'context': Value(dtype='string', id=None), 'id': Value(dtype='string', id=None), 'question': Value(dtype='string', id=None), 'title': Value(dtype='string', id=None)} ``` rTFc&i|] \}}d||Srrrrrrs rbrz$Features.flatten..s-%]%]%]$!Q&:&:q&:&:A%]%]%]rdcpi|]2\}}d|t|tst|n|g3Sr)rrrrs rbrz$Features.flatten..s\ $1 +00Q00ZPQSWEXEX2a(1+++_`^ardrRc&i|] \}}d||Srrrs rbrz$Features.flatten.. s-%g%g%g$!Q&:&:q&:&:A%g%g%grd) rrrrrupdaterrr_rR)r max_depthdepth no_change flattened subfeaturers @rbrRzFeatures.flattens41i((  EI I+/::<< / /' Zj$/// %I$$%]%]%]%]*JZJZJ\J\%]%]%]^^^!+.. H55 /*ZEWY]:^:^ / %I$$(2(:(@(@(B(B "+..Z33/ 8J8J8L8LPZ8Z8Z %I$$%g%g%g%g*J\J\J^J^JdJdJfJf%g%g%ghhh!+.D   rd)r&r r)rr r&r )r)*rrrrrrvrr __delitem__r setdefaultr4popitemclearrrrCrrrOSchemarrrrrrrrQrrrrrr)r'rrrrrR __classcell__)rs@rbr r s@     -,T-=>>K,,T-=>>K ' ' 4 4F++DO<..sBBBQaaBBBrd)r r)rrrs rbrz#_align_features..s> b b bHBBBB(--//BBB C C b b brd)rrrrl)rrrrrs @rb_align_featuresrsL!$$NN$$ $ $DAq $$LOU)K)K$P\]^P_PeioPoPo"# Q $ c b b bTa b b bbrdc i}|D]Q}|D]:\}}||vs,t||tr||jdkr|||<;R|D]j}|D]S\}}t|tr |jdks.|||kr"t d|d|d|d||d TkdS)zCheck if the dictionaries of features can be aligned. Two dictonaries of features can be aligned if the keys they share have the same type or some of them is of type `Value("null")`. r(z.The features can't be aligned because the key z of features z has unexpected type - z (expected either z or Value("null").N)rrrrlrV)rrrrrs rb!_check_if_features_can_be_alignedr sN L!$$NN$$ $ $DAq $$LOU)K)K$P\]^P_PeioPoPo"# Q $"NN$$  DAqq%(( QW->->LQROWXDXDX pappV^ppwxppMYZ[M\ppp rd)FTrrr)wrrrrrcollections.abcrrrr dataclassesrrrr functoolsr r operatorr typingr rrrrrrrrrpandasrr?rOpyarrow.computecomputer pyarrow.typespandas.api.extensionsrPandasExtensionArrayrPandasExtensionDtyperrnamingrrtablerutilsrutils.py_utilsrrraudior imager!r" translationr#r$ get_loggerrloggerr9rQrcrr)rrrrrrr r rrr(r,r/r2r<rr%rvrrrrr FeatureTyperrrr"r+r9rrDrHrrOrRrTrWrYr^rcrirvr rrrrdrbrs  cb --------333333999999999999########DDDDDDDDDDDDDDDDDD((((((HHHHHHHHHHHHCCCCCCCCCCCCCCCCCC********BBBBBBBB  H % %=`=`=`=`=`=`@RCRBKRRRRjYYYVZY_dehjnen_oYYYYx   ]`    2 CCCCCCC CL         BBBBBhBB B0 BBBBBhBB B0 BBBBBhBB B0 BBBBBhBB B0%:%:%:%:%:B.%:%:%:P0000rr rTrdrrrr,9&9&9&9&9&"+9&9&9&x     4   De1e1e1e1e1 4e1e1e1P;;;  BSBSBSBSBSBSBS BSJ CCCCCCC C:             $Xk5JVZ,KBKBEEEEP%%(4USVX\^bSbMcHcCd:e%%%%PLCLLLL4IbkIkIIII<  BJ bk R\     5$x7I2J 5r| 5 5 5 5''bj1A''`b`l''''" w wE"*d2B,C w2; wbdbn w w w w 5s 5-B 5rx 5 5 5 5 ppkpDpUYpppp(0+0$0000$1;141111$,NNNNNtNNNbc4>cd8nccccT(^rd