a .Sicݹ@sdZddlZddlZddlZddlmZddlmZddlm Z ddlm Z ddlm Z ddlm Z dd lmZddlm Z d Zd ZgZe d gd GdddeZe dgd GdddeZddZGdddeZddZddZeZe dddZiZddZd d!Zd"d#Ze d$d%d&Z d'd(Z!d)d*Z"d+d,Z#d-d.Z$iZ%d/d0Z&d1d2Z'gZ(gZ)gZ*iZ+iZ,d3Z-e d4d5d6Z.e d7d8d9Z/e d:d;d<Z0d=d>Z1d?d@Z2dAdBZ3dCdDZ4dEdFZ5dGdHZ6dIdJZ7dKdLZ8dMdNZ9dOdPZ:dQdRZ;e dSgd dXdTdUZz0_TypeBasedDispatcher._handles..TF) itertoolschainvaluesr+r'listtupleany)r rrargrr!r_handless  z_TypeBasedDispatcher._handlescCs&|||r|j|i|S|jSdSr&)r7r(r r rrrrs z_TypeBasedDispatcher.handleN)rrrrr*r7rrrrrr%sr%csfdd}|S)aDecorator to declare that a Python function overrides an op for a type. The decorated function is used to override `op` if any of the arguments or keyword arguments (including elements of lists or tuples) have one of the specified types. Example: ```python @dispatch_for_types(math_ops.add, RaggedTensor, RaggedTensorValue) def ragged_add(x, y, name=None): ... ``` Args: op: Python function: the operation that should be overridden. *types: The argument types for which this function should be used. cs0t|tkrtdt||S)NzYThe decorated function's signature must exactly match the signature of the overridden op.)r getargspecrr%r)funcrr)rr decoratorsz%dispatch_for_types..decoratorr)rr)r;rr:rdispatch_for_typessr<cCs&t|trtd|t|tg|S)z7Decorator that adds a dispatch_list attribute to an op.z%s already has a dispatch list)rrrsetattr)targetrrradd_fallback_dispatch_lists   r?zexperimental.dispatch_for_apicsVttddur"tdtfddDfdd}|S)a}Decorator that overrides the default implementation for a TensorFlow API. The decorated function (known as the "dispatch target") will override the default implementation for the API when the API is called with parameters that match a specified type signature. Signatures are specified using dictionaries that map parameter names to type annotations. E.g., in the following example, `masked_add` will be called for `tf.add` if both `x` and `y` are `MaskedTensor`s: >>> class MaskedTensor(tf.experimental.ExtensionType): ... values: tf.Tensor ... mask: tf.Tensor >>> @dispatch_for_api(tf.math.add, {'x': MaskedTensor, 'y': MaskedTensor}) ... def masked_add(x, y, name=None): ... return MaskedTensor(x.values + y.values, x.mask & y.mask) >>> mt = tf.add(MaskedTensor([1, 2], [True, False]), MaskedTensor(10, True)) >>> print(f"values={mt.values.numpy()}, mask={mt.mask.numpy()}") values=[11 12], mask=[ True False] If multiple type signatures are specified, then the dispatch target will be called if any of the signatures match. For example, the following code registers `masked_add` to be called if `x` is a `MaskedTensor` *or* `y` is a `MaskedTensor`. >>> @dispatch_for_api(tf.math.add, {'x': MaskedTensor}, {'y':MaskedTensor}) ... def masked_add(x, y): ... x_values = x.values if isinstance(x, MaskedTensor) else x ... x_mask = x.mask if isinstance(x, MaskedTensor) else True ... y_values = y.values if isinstance(y, MaskedTensor) else y ... y_mask = y.mask if isinstance(y, MaskedTensor) else True ... return MaskedTensor(x_values + y_values, x_mask & y_mask) The type annotations in type signatures may be type objects (e.g., `MaskedTensor`), `typing.List` values, or `typing.Union` values. For example, the following will register `masked_concat` to be called if `values` is a list of `MaskedTensor` values: >>> @dispatch_for_api(tf.concat, {'values': typing.List[MaskedTensor]}) ... def masked_concat(values, axis): ... return MaskedTensor(tf.concat([v.values for v in values], axis), ... tf.concat([v.mask for v in values], axis)) Each type signature must contain at least one subclass of `tf.CompositeTensor` (which includes subclasses of `tf.ExtensionType`), and dispatch will only be triggered if at least one type-annotated parameter contains a `CompositeTensor` value. This rule avoids invoking dispatch in degenerate cases, such as the following examples: * `@dispatch_for_api(tf.concat, {'values': List[MaskedTensor]})`: Will not dispatch to the decorated dispatch target when the user calls `tf.concat([])`. * `@dispatch_for_api(tf.add, {'x': Union[MaskedTensor, Tensor], 'y': Union[MaskedTensor, Tensor]})`: Will not dispatch to the decorated dispatch target when the user calls `tf.add(tf.constant(1), tf.constant(2))`. The dispatch target's signature must match the signature of the API that is being overridden. In particular, parameters must have the same names, and must occur in the same order. The dispatch target may optionally elide the "name" parameter, in which case it will be wrapped with a call to `tf.name_scope` when appropraite. Args: api: The TensorFlow API to override. *signatures: Dictionaries mapping parameter names or indices to type annotations, specifying when the dispatch target should be called. In particular, the dispatch target will be called if any signature matches; and a signature matches if all of the specified parameters have types that match with the indicated type annotations. If no signatures are specified, then a signature will be read from the dispatch target function's type annotations. Returns: A decorator that overrides the default implementation for `api`. #### Registered APIs The TensorFlow APIs that may be overridden by `@dispatch_for_api` are: <> Nz does not support dispatch.csg|]}t|qSr)_make_signature_checker)r, signature) api_signaturerr Tsz$dispatch_for_api..cst|std|t|}t|D]}||q.t|st|}t|}||t| ||S)z3Decorator that registers the given dispatch target.z-Expected dispatch_target to be callable; got ) callable TypeError_add_name_scope_wrapper_check_signatureZRegister_TYPE_BASED_DISPATCH_SIGNATURESextend_signature_from_annotationsr@r)dispatch_targetZsignature_checkerrAcheckerapirBr"Zsignature_checkers signaturesrrr;Ys    z#dispatch_for_api..decorator)rTYPE_BASED_DISPATCH_ATTR ValueErrorrrA)rNrOr;rrMrdispatch_for_apisU   rRcCsttdddS)zCReturns a list of TensorFlow APIs that support type-based dispatch.cSs|jd|jS)N.)rr)rNrrrzr/z/apis_with_type_based_dispatch..key)sortedrHrrrrapis_with_type_based_dispatchvsrXcs^fddi}tD]>\}}|D],\}}tt|}|r*||g|q*q|S)aReturns dispatch signatures that have been registered for a given class. This function is intended for documentation-generation purposes. Args: cls: The class to search for. Type signatures are searched recursively, so e.g., if `cls=RaggedTensor`, then information will be returned for all dispatch targets that have `RaggedTensor` anywhere in their type annotations (including nested in `typing.Union` or `typing.List`.) Returns: A `dict` mapping `api` -> `signatures`, where `api` is a TensorFlow API function; and `signatures` is a list of dispatch signatures for `api` that include `cls`. (Each signature is a dict mapping argument names to type annotations; see `dispatch_for_api` for more info.) cslt|tr$tfdd|DS|ur0dSt|sDt|rdt|}tfdd|DSdSdS)z#Returns true if `x` contains `cls`.c3s|]}|VqdSr&r)r,v contains_clsrrr.r/zKtype_based_dispatch_signatures_for..contains_cls..Tc3s|]}|VqdSr&r)r,r6rZrrr.r/FN)r+dictr5r2ris_generic_listis_generic_unionget_generic_type_args)x type_argsclsr[rrr[s   z8type_based_dispatch_signatures_for..contains_cls)rHitemsr3filter setdefaultrI)rcr#rNZapi_signatures_rOfilteredrrbr"type_based_dispatch_signatures_for}s ricsd|jvrSt}t}d|jvs6|jdur:St|jdfdd}t|}|j t|j |jdgd|_ |` |S)aWraps `func` to expect a "name" arg, and use it to call `ops.name_scope`. If `func` already expects a "name" arg, or if `api_signature` does not expect a "name" arg, then returns `func` as-is. Args: func: The function to wrap. Signature must match `api_signature` (except the "name" parameter may be missing. api_signature: The signature of the original API (used to find the index for the "name" parameter). Returns: The wrapped function (or the original function if no wrapping is needed). nameNcst|kr2|}|d|dd}n |dd}|durT|i|St||i|WdS1s0YdS)Nrj)lenpopr name_scope)rrrjr9 name_indexrr wrapped_funcs   z-_add_name_scope_wrapper..wrapped_func) parameters) rrrrAr8keywordsr3indexrmake_decoratorreplacer2 __signature__ _tf_decorator)r9rBfunc_signature func_argspecrqrrorrFs       rFz$experimental.unregister_dispatch_forc sd}tD].\}}|vr t|t}||=d}q fddtD}t|D].}t|D]\}}t|qft|=t|=d}qZ|st dddS)aUnregisters a function that was registered with `@dispatch_for_*`. This is primarily intended for testing purposes. Example: >>> # Define a type and register a dispatcher to override `tf.abs`: >>> class MyTensor(tf.experimental.ExtensionType): ... value: tf.Tensor >>> @tf.experimental.dispatch_for_api(tf.abs) ... def my_abs(x: MyTensor): ... return MyTensor(tf.abs(x.value)) >>> tf.abs(MyTensor(5)) MyTensor(value=) >>> # Unregister the dispatcher, so `tf.abs` no longer calls `my_abs`. >>> unregister_dispatch_for(my_abs) >>> tf.abs(MyTensor(5)) Traceback (most recent call last): ... ValueError: Attempt to convert a value ... to a Tensor. Args: dispatch_target: The function to unregister. Raises: ValueError: If `dispatch_target` was not registered using `@dispatch_for`, `@dispatch_for_unary_elementwise_apis`, or `@dispatch_for_binary_elementwise_apis`. FTcsg|]\}}|ur|qSrr)r,rVhandlerrKrrrCsz+unregister_dispatch_for..z Function z8 was not registered using a `@dispatch_for_*` decorator.N) rHrdrrPZ Unregister_ELEMENTWISE_API_HANDLERSset_ELEMENTWISE_API_TARGETSunregister_dispatch_forrQ) rKfoundrNrOr"Zelementwise_keys_to_deleterVrgr>rr|rrs$      rcCst||S)aClass decorator that registers a type for use with type-based dispatch. Should *not* be used with subclasses of `CompositeTensor` or `ExtensionType` (which are automatically registered). Note: this function is intended to support internal legacy use cases (such as RaggedTensorValue), and will probably not be exposed as a public API. Args: cls: The class to register. Returns: `cls`. )_api_dispatcherregister_dispatchable_type)rcrrrrs rcCsnt|trt|dt|\}}t|}|js<|jr@|St |tt |j |j |jttt|<|S)z@Adds a PythonAPIDispatcher to the given TensorFlow API function.z) already has a type-based API dispatcher.)rrPrQrunwraprr8varargsrsr=rZPythonAPIDispatcherrrdefaults collections defaultdictr3rH)r>rgZ unwrappedZtarget_argspecrrradd_type_based_api_dispatcher#s   rcCst|}|jdur(|jdur(|js(dSt|}t|jt|jk}|rt|j |j D]$\}}|j |j ks|j |j kr`d}q`|st d|d|ddS)aChecks that a dispatch target's signature is compatible with an API. Args: api_signature: The signature of the TensorFlow API. func: The dispatch target. Raises: ValueError: if the signatures are incompatible. Two signatures are considered compatible if they have the same number of parameters, and all corresponding parameters have the same `name` and `kind`. (Parameters are not required to have the same default value or the same annotation.) NFzDispatch function's signature z does not match API's signature rS) rr8rrsrrArlrrzipr2rjkindrQ)rBr9rzryokZparam_1Zparam_2rrrrG9s"     rGc Cst|trtdd|Ds$tdg}t|j}|D]\}}t|trn|t|jkrnt|j |j }|j |d}|durt d|d|j tjjtjjfvrt d|j d|dt|}||}|||fq:t|S) aBuilds a PySignatureChecker for the given type signature. Args: api_signature: The `inspect.Signature` of the API whose signature is being checked. signature: Dictionary mapping parameter names to type annotations. Returns: A `PySignatureChecker`. css|]}t|ttfVqdSr&)r+strint)r,krrrr.dr/z*_make_signature_checker..zLsignatures must be dictionaries mapping parameter names to type annotations.Nz4signature includes annotation for unknown parameter rSziDispatch currently only supports type annotations for positional parameters; can't handle annotation for z parameter )r+r\allrEr3rrrdrrlr2rjgetrQrr ParameterPOSITIONAL_ONLYPOSITIONAL_OR_KEYWORDmake_type_checkerrtrrZPySignatureChecker) rBrAZcheckers param_names param_nameZ param_typeparamrLrtrrrr@Xs8        r@cCs(t|rt|}dd|D}tt|td}t|dkrz|tvrXtj |}|t|<t|gdd|D}t |Sdd|D}t |St |rt|}t|dkrt dt |d}t|St|tr|tvrt |}|t|<t|S|d urt td Std |d d S) z5Builds a PyTypeChecker for the given type annotation.cSsg|]}t|tr|qSr)r+typer,trrrrCr/z%make_type_checker..rUrkcSsg|]}t|tst|qSr)r+rrrrrrrCs cSsg|] }t|qSr)rrrrrrCr/z2Expected List[...] to have a single type parameterrNzType annotation zi is not currently supported by dispatch. Supported annotations: type objects, List[...], and Union[...])rr^r_r4rWidrl_is_instance_checker_cacherZMakeInstanceCheckerZMakeUnionCheckerr]rrZMakeListCheckerr+rrQ) annotationra simple_typesrLoptionsZelt_typerrrrs8                rcCs2t|}tdd|jD}|s.td|S)z?Builds a dict mapping from parameter names to type annotations.cSs(g|] \}}|jtjjkr||jfqSr)rrrempty)r,rjrrrrrCsz/_signature_from_annotations..zThe dispatch_for_api decorator must be called with at least one signature, or applied to a function that has type annotations on its parameters.)rrAr\rrrdrQ)r9ryrArrrrJs rJZASSERT_API_TAGz0experimental.dispatch_for_unary_elementwise_apiscsfdd}|S)aDecorator to override default implementation for unary elementwise APIs. The decorated function (known as the "elementwise api handler") overrides the default implementation for any unary elementwise API whenever the value for the first argument (typically named `x`) matches the type annotation `x_type`. The elementwise api handler is called with two arguments: `elementwise_api_handler(api_func, x)` Where `api_func` is a function that takes a single parameter and performs the elementwise operation (e.g., `tf.abs`), and `x` is the first argument to the elementwise api. The following example shows how this decorator can be used to update all unary elementwise operations to handle a `MaskedTensor` type: >>> class MaskedTensor(tf.experimental.ExtensionType): ... values: tf.Tensor ... mask: tf.Tensor >>> @dispatch_for_unary_elementwise_apis(MaskedTensor) ... def unary_elementwise_api_handler(api_func, x): ... return MaskedTensor(api_func(x.values), x.mask) >>> mt = MaskedTensor([1, -2, -3], [True, False, True]) >>> abs_mt = tf.abs(mt) >>> print(f"values={abs_mt.values.numpy()}, mask={abs_mt.mask.numpy()}") values=[1 2 3], mask=[ True False True] For unary elementwise operations that take extra arguments beyond `x`, those arguments are *not* passed to the elementwise api handler, but are automatically added when `api_func` is called. E.g., in the following example, the `dtype` parameter is not passed to `unary_elementwise_api_handler`, but is added by `api_func`. >>> ones_mt = tf.ones_like(mt, dtype=tf.float32) >>> print(f"values={ones_mt.values.numpy()}, mask={ones_mt.mask.numpy()}") values=[1.0 1.0 1.0], mask=[ True False True] Args: x_type: A type annotation indicating when the api handler should be called. See `dispatch_for_api` for a list of supported annotation types. Returns: A decorator. #### Registered APIs The unary elementwise APIs are: <> csJftvr&tdtfdd|tf<tD]}t||q4|S)Nz&A unary elementwise dispatch handler (z") has already been registered for rS)r}rQ_UNARY_ELEMENTWISE_APIS'_add_dispatch_for_unary_elementwise_apir{rNx_typerrr; s   z6dispatch_for_unary_elementwise_apis..decoratorr)rr;rrr#dispatch_for_unary_elementwise_apiss5 rz1experimental.dispatch_for_binary_elementwise_apiscsfdd}|S)a{Decorator to override default implementation for binary elementwise APIs. The decorated function (known as the "elementwise api handler") overrides the default implementation for any binary elementwise API whenever the value for the first two arguments (typically named `x` and `y`) match the specified type annotations. The elementwise api handler is called with two arguments: `elementwise_api_handler(api_func, x, y)` Where `x` and `y` are the first two arguments to the elementwise api, and `api_func` is a TensorFlow function that takes two parameters and performs the elementwise operation (e.g., `tf.add`). The following example shows how this decorator can be used to update all binary elementwise operations to handle a `MaskedTensor` type: >>> class MaskedTensor(tf.experimental.ExtensionType): ... values: tf.Tensor ... mask: tf.Tensor >>> @dispatch_for_binary_elementwise_apis(MaskedTensor, MaskedTensor) ... def binary_elementwise_api_handler(api_func, x, y): ... return MaskedTensor(api_func(x.values, y.values), x.mask & y.mask) >>> a = MaskedTensor([1, 2, 3, 4, 5], [True, True, True, True, False]) >>> b = MaskedTensor([2, 4, 6, 8, 0], [True, True, True, False, True]) >>> c = tf.add(a, b) >>> print(f"values={c.values.numpy()}, mask={c.mask.numpy()}") values=[ 3 6 9 12 5], mask=[ True True True False False] Args: x_type: A type annotation indicating when the api handler should be called. y_type: A type annotation indicating when the api handler should be called. Returns: A decorator. #### Registered APIs The binary elementwise APIs are: <> csXftvr0tdtfddd|tf<tD]}t||q@|S)Nz'A binary elementwise dispatch handler (#) has already been registered for (, ).)r}rQ_BINARY_ELEMENTWISE_APIS(_add_dispatch_for_binary_elementwise_apirry_typerrr;Fs    z7dispatch_for_binary_elementwise_apis..decoratorrrrr;rrr$dispatch_for_binary_elementwise_apiss, rz8experimental.dispatch_for_binary_elementwise_assert_apiscsfdd}|S)aXDecorator to override default implementation for binary elementwise assert APIs. The decorated function (known as the "elementwise assert handler") overrides the default implementation for any binary elementwise assert API whenever the value for the first two arguments (typically named `x` and `y`) match the specified type annotations. The handler is called with two arguments: `elementwise_assert_handler(assert_func, x, y)` Where `x` and `y` are the first two arguments to the binary elementwise assert operation, and `assert_func` is a TensorFlow function that takes two parameters and performs the elementwise assert operation (e.g., `tf.debugging.assert_equal`). The following example shows how this decorator can be used to update all binary elementwise assert operations to handle a `MaskedTensor` type: >>> class MaskedTensor(tf.experimental.ExtensionType): ... values: tf.Tensor ... mask: tf.Tensor >>> @dispatch_for_binary_elementwise_assert_apis(MaskedTensor, MaskedTensor) ... def binary_elementwise_assert_api_handler(assert_func, x, y): ... merged_mask = tf.logical_and(x.mask, y.mask) ... selected_x_values = tf.boolean_mask(x.values, merged_mask) ... selected_y_values = tf.boolean_mask(y.values, merged_mask) ... assert_func(selected_x_values, selected_y_values) >>> a = MaskedTensor([1, 1, 0, 1, 1], [False, False, True, True, True]) >>> b = MaskedTensor([2, 2, 0, 2, 2], [True, True, True, False, False]) >>> tf.debugging.assert_equal(a, b) # assert passed; no exception was thrown >>> a = MaskedTensor([1, 1, 1, 1, 1], [True, True, True, True, True]) >>> b = MaskedTensor([0, 0, 0, 0, 2], [True, True, True, True, True]) >>> tf.debugging.assert_greater(a, b) Traceback (most recent call last): ... InvalidArgumentError: Condition x > y did not hold. Args: x_type: A type annotation indicating when the api handler should be called. y_type: A type annotation indicating when the api handler should be called. Returns: A decorator. #### Registered APIs The binary elementwise assert APIs are: <> csVtf}|tvr2tdt|ddd|t|<tD]}t||q>|S)Nz.A binary elementwise assert dispatch handler (rrr)_ASSERT_API_TAGr}rQ_BINARY_ELEMENTWISE_ASSERT_APISr)r{Zapi_handler_keyrNrrrr;s  z>dispatch_for_binary_elementwise_assert_apis..decoratorrrrrr+dispatch_for_binary_elementwise_assert_apisTs6 rcCs<t|tD]$\}}t|dkrt||d|q|S)zDDecorator that registers a TensorFlow op as a unary elementwise API.rkr)rrr}rdrlrr9rr{rrrregister_unary_elementwise_apis   rcCsBt|tD]*\}}t|dkrt||d|d|q|S)zEDecorator that registers a TensorFlow op as a binary elementwise API.rrk)rrr}rdrlrrrrrregister_binary_elementwise_apis   rcCsNt|tD]6\}}t|dkr|dturt||d|d|q|S)aDecorator that registers a TensorFlow op as a binary elementwise assert API. Different from `dispatch_for_binary_elementwise_apis`, this decorator is used for assert apis, such as assert_equal, assert_none_equal, etc, which return None in eager mode and an op in graph mode. Args: func: The function that implements the binary elementwise assert API. Returns: `func` rrrk)rrr}rdrlrrrrrr®ister_binary_elementwise_assert_apis rcCsttS)zFReturns a list of APIs that have been registered as unary elementwise.)r4rrrrrunary_elementwise_apissrcCsttS)zGReturns a list of APIs that have been registered as binary elementwise.)r4rrrrrbinary_elementwise_apissrcst}t|jdt|t|jdkp6d|jvt|ifdd}dj|_|j|_t |fg}| |fdS)zFRegisters a unary elementwise handler as a dispatcher for a given API.rrrjcst\}r.ddd}n }rNfdd}n}|durd||St|d|g||WdS1s0YdS)Nrrkcs|gRiSr&r)rYrNrrrrrTr/zR_add_dispatch_for_unary_elementwise_api..dispatch_target..)_extract_name_argrmrrn)rrrjr` tensor_apirNelementwise_api_handlerrpneed_to_bind_api_argsx_namerrrrKs  z@_add_dispatch_for_unary_elementwise_api..dispatch_target elementwise_dispatch_target_for_N rrAr3rr_find_name_indexrlrRrrrrfr)rNrrrBrK target_listrrrrs   rcst}t|jdd\t|t|jdkp>d|jvt||ifdd}dj|_|j|_t ||fg}| |fdS)zGRegisters a binary elementwise handler as a dispatcher for a given API.Nrrrjcst\}tdkr@dddd}}n@rhddd}d}nd}d}rfdd}n}|dur|||St|d||g|||WdS1s0YdS)Nrkrrcs||gRiSr&r)r v2rrrrTr/zS_add_dispatch_for_binary_elementwise_api..dispatch_target..)rrlrmrrn)rrrjr`yrrNrrprrZy_namerrrKs "   zA_add_dispatch_for_binary_elementwise_api..dispatch_targetrr)rNrrrrBrKrrrrrs  rcCs,zt|jdWSty&YdS0dS)zEReturns the index of the `name` parameter, or -1 if it's not present.rjN)r3rrrtrQ)rArrrrs rcCsV|dkrd}n>|t|kr@||}|d|||dd}n |dd}|||fS)zGExtracts the parameter `name` and returns `(args, kwargs, name_value)`.rNrkrj)rlrm)rrrp name_valuerrrrs  rcCs,ttttttttttttdS)a0Updates the docstrings of dispatch decorators with API lists. Updates docstrings for `dispatch_for_api`, `dispatch_for_unary_elementwise_apis`, and `dispatch_for_binary_elementwise_apis`, by replacing the string '<>' with a list of APIs that have been registered for that decorator. N) _update_docstring_with_api_listrrrrrrrRrHrrrr update_docstrings_with_api_lists*src Cstg}|D]H}tj|dd}|durt|j}|d|dd|dq||j dd ||_ dS) zFReplaces `<>` in target.__doc__ with the given list of APIs.T)add_prefix_to_v1_namesNz * `tf.(rz)`z <> ) tf_export_libget_canonical_name_for_symbolrrArrkeysrjoinsortrrv)r>Zapi_listlinesr9rjparamsrrrr<s rz*__internal__.dispatch.add_dispatch_supportcsTdus0tttfr(tddDs0tdfdd}|durH|S||SdS)aDecorator that adds a dispatch handling wrapper to a TensorFlow Python API. This wrapper adds the decorated function as an API that can be overridden using the `@dispatch_for_api` decorator. In the following example, we first define a new API (`double`) that supports dispatch, then define a custom type (`MaskedTensor`) and finally use `dispatch_for_api` to override the default implementation of `double` when called with `MaskedTensor` values: >>> @add_dispatch_support ... def double(x): ... return x * 2 >>> class MaskedTensor(tf.experimental.ExtensionType): ... values: tf.Tensor ... mask: tf.Tensor >>> @dispatch_for_api(double, {'x': MaskedTensor}) ... def masked_double(x): ... return MaskedTensor(x.values * 2, y.mask) The optional `iterable_parameter` argument can be used to mark parameters that can take arbitrary iterable values (such as generator expressions). These need to be handled specially during dispatch, since just iterating over an iterable uses up its values. In the following example, we define a new API whose second argument can be an iterable value; and then override the default implementatio of that API when the iterable contains MaskedTensors: >>> @add_dispatch_support(iterable_parameters=['ys']) ... def add_tensor_to_list_of_tensors(x, ys): ... return [x + y for y in ys] >>> @dispatch_for_api(add_tensor_to_list_of_tensors, ... {'ys': typing.List[MaskedTensor]}) ... def masked_add_tensor_to_list_of_tensors(x, ys): ... return [MaskedTensor(x+y.values, y.mask) for y in ys] (Note: the only TensorFlow API that currently supports iterables is `add_n`.) Args: target: The TensorFlow API that should support dispatch. iterable_parameters: Optional list of parameter names that may be called with iterables (such as the `inputs` parameter for `tf.add_n`). Returns: A decorator. Ncss|]}t|tVqdSr&)r+r)r,prrrr.|r/z'add_dispatch_support..z8iterable_parameters should be a list or tuple of string.cspdurdntjfddDtjfddtttt t dS)Ncsg|]}||fqSr)rt)r,rj) arg_namesrrrCsz;add_dispatch_support..decorator..c sdur8dur t||\}}||}|tur8|Sz|i|WSttfy~t||}|tjurx|YSYn0dS)z.decorator..op_dispatch_handler) rr8rrfilter_tracebackr?rrurrrPr|iterable_parameters)rrrKrrrr;s"  z'add_dispatch_support..decorator)r+r3r4rrE)r>rr;rrradd_dispatch_supportLs.  +rcCsXt|}|D]>\}}|t|kr2t||||<q ||vr t||||<q t||fS)aReturns (args, kwargs) with any iterable parameters converted to lists. Args: args: Positional rguments to a function kwargs: Keyword arguments to a function. iterable_params: A list of (name, index) tuples for iterable parameters. Returns: A tuple (args, kwargs), where any positional or keyword parameters in `iterable_params` have their value converted to a `list`. )r3rlr4)rrrrjrtrrrrs   r)NN)>rrr0typingtensorflow.python.frameworkrrrtensorflow.python.utilrrrrrr tensorflow.python.util.tf_exportrrPr rr rr$r%r<r?Zadd_dispatch_listrRrHrXrirFrrrrGr@rrrJrrrr}rrrrrrrrrrrrrrrrrrrrrrs/         +     x+- :-+ B 9 D  %(   c