o ,wi@@sdZddlmZddlZddlZddlZddlmZmZm Z m Z e dZ ddZ dd Z efd d Zd d ZGdddZddZejGdddZddZddZe dddZd ddZdS)!a Functions that generate callable arguments each time they are called. The `arg_factory` package provides two function wrappers that can be used to generate parameter values each time a wrapped function is called: * `@arg_factory.supply_defaults` is a decorator that defines a "default factory" for one or more parameters. Each time the decorated function is called, any missing parameter with a default factory has its value filled in by calling the factory. For example, this can be used to define mutable default values for functions, that are created each time the function is called. * `arg_factory.partial` is a specialized version of `functools.partial` that binds parameters to factories rather than values. These factories are used to compute the parameter values each time the partial function is called. ## Differences between `supply_defaults` and `partial` These two wrappers have similar behavior for keyword arguments, but differ in how they handle factories for positional arguments: * When `arg_factory.partial` binds an argument positionally, that argument is removed from the signature. I.e., the wrapper function no longer expects that argument. * In contrast, `@arg_factory.supply_defaults` does not remove any arguments from the signature of the wrapped function. The wrappers also differ in their restrictions for positional-only arguments. Consider a function with signature `f(x, y, /)`: * `arg_factory.partial` may be used to define a factory for `x` without defining one for `y` (and doing so will "consume" the argument `x`); but `@arg_factory.supply_defaults` can not (since non-default arguments may not follow default arguments). * Conversely, `@arg_factory.supply_defaults` may be used to define a factory for `y` without defining one for `x` (and doing so will make `y` an optional argument); but `arg_factory.partial` can not (since `y` is a positional-only argument, so there's no way to bind it without also binding `x`). A final difference is that `@arg_factory.supply_defaults` may only be used to provide default factories for positional and keyword parameters in the wrapped function's signature; it may not be used to add factories for functions with var-positional (`*args`) or var-keyword (**kwargs`) parameters. But `arg_factory.partial` *can* be used to provide a default for a var-positional or var-keyword argument. E.g.: >>> def f(**kwargs): ... print(kwargs) >>> p = arg_factory.partial(f, x=list) >>> p(y=3) {'x': [], y: 3} ) annotationsN)AnyCallableTypeVaroverloadTcOD|^}}dd|D}dd|D}tjt|g|Ri|S)a$A specialized version of `functools.partial` that binds args to factories. `arg_factory.partial` is similar to `functools.partial`, except that it binds arguments to *factory functions* rather than *values*. These factory functions are used to construct a value for an argument each time the partial is called. Example: Consider the following code. >>> def f(x, noise): return x + noise >>> g = functools.partial(f, noise=random.random()) >>> g(5) == g(5) # noise has the same value for each call to `g`. True Here, the value for the `noise` parameter is set when the partial object is created, so each call to `g` will use the same value. If we want a new value for each call to the partial, we can use `arg_factory.partial`: >>> g = arg_factory.partial(f, noise=random.random) >>> g(5) == g(5) # noise has a new value for each call to g. False Since we used `arg_factory.partial`, each call to `g` will call the `random.random`, and so will use a different value for `noise`. If you need to define a partial function that specifies some parameters using values and other parameters using factories, then you should do so by composing `functools.partial` with `arg_factory.partial`. E.g.: >>> h = functools.partial(arg_factory.partial(f, noise=random.random), x=4) Args: *args: The function whose arguments should be bound to factories, followed by factories for positional arguments to `func`. **kwargs: Factories for keyword arguments to `func`. Returns: A `functools.partial` object. cSg|]}t|qS ArgFactory.0argr r T/home/ubuntu/sommelier/.venv/lib/python3.10/site-packages/fiddle/_src/arg_factory.py zpartial..cSi|] \}}|t|qSr r rnamerr r r zpartial..)items functoolspartial_InvokeArgFactoryWrapperargskwargsfuncr r rrUs*rcOr)a@Version of `functools.partialmethod` that supports binds args to factories. `arg_factory.partialmethod` behaves like `arg_factory.partial`, except that it is designed to be used as a method definition rather than being directly callable. See `functools.partialmethod` and `arg_factory.partial` for more details. Args: *args: The function whose arguments should be bound to factories, followed by factories for positional arguments to `func`. **kwargs: Factories for keyword arguments to `func`. Returns: A `functools.partialmethod` object. cSr r r r r r rrrz!partialmethod..cSrr r rr r rrrz!partialmethod..)rr partialmethodrrr r rr sr cCs.t|dt|dt|}|d|d|d)zFRaises a ValueError for an ArgFactory operation that is not supported. __qualname____name__zarg_factory.default_factory(z) does not support z. `arg_factory.default_factory(...)` should only be used as a default value for a function wrapped with `arg_factory.supply_defaults`; or as an argument to `arg_factory.partial`. Did you forget to apply the `@arg_factory.supply_defaults` decorator?)getattrrepr)factoryop_type error_typerr r r_raise_unsupported_op_errors r(csfdd}|S)z:Returns a function that calls _raise_unsupported_op_error.cs~~|j}t|dSN)_factoryr() arg_factoryrrr%r&r runsupported_op_handlersz,_unsupported..unsupported_op_handlerr )r&r-r r,r _unsupporteds r.cseZdZUdZded<ed$dd Zfd d Zd%fd d Zed dZ ddZ ddZ ddZ e dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZ e dZ!e dZ"e dZ#e dZ$e dZ%e dZ&e dZ'e dZ(e dZ)e dZ*e dZ+e dZ,e dZ-e dZ.e dZ/e dZ0e dZ1e dZ2e dZ3e dZ4e dZ5e dZ6e dZ7e dZ8e dZ9e dZ:e dZ;e dZe dZ?e dZ@e dZAe dZBe dZCe dZDe dZEe dZFe dZGe dZHe dZIe dZJe dZKe dZLe dZMe dZNe dZOe dZPe dZQddZRd d!ZSd"d#ZTZUS)&r aRA wrapper indicating that an argument should be computed with a factory. This wrapper is used by `arg_factory.partial` to define arguments whose value should should be built each time the partial is called. It is also used in as the default value in the signatures for `arg_factory.partial` and `arg_factory.supply_defaults`. Callable[..., Any]r*r%Callable[..., T]returnrcCdSr)r )clsr%r r r__new__zArgFactory.__new__cs~~t|Sr))superr4)r3rr __class__r rr4s cs*t|s td|dtd|dS)Nz@Expected arguments to `arg_factory.partial` to be callable. Got .r*)callable TypeErrorr6 __setattr__)selfr%r7r r__init__szArgFactory.__init__cCs|jSr))r*r=r r rszArgFactory.cCs*t|jdt|jdt|j}d|dS)Nr!r"z )r#r*r$r=rr r r__repr__s zArgFactory.__repr__cCst|to |j|jkSr)) isinstancer r*)r=otherr r r__eq__zArgFactory.__eq__cCs t|jSr))hashr*r?r r r__hash__s zArgFactory.__hash__zmath operations iterationlenreversedcontainscallinggetitemsetitemdelitemcCs(|dkrtn|j}t|d|tdS)Nr*the attribute )Ellipsisr*r(AttributeError)r=rr%r r r __getattr__/s zArgFactory.__getattr__cCst|jddS)Nzsetting attributesr(r*)r=rvaluer r rr<6szArgFactory.__setattr__cCst|jd|dS)NrQrUrAr r r __delattr__9rFzArgFactory.__delattr__r%r0r1r)r%r/)Vr" __module__r!__doc____annotations__rr4r>propertyr%rBrErHr.__ge____gt____le____lt____add____and__ __divmod__ __floordiv__ __lshift__ __matmul____mod____mul____or____pow__ __rshift____sub__ __truediv____xor____radd____rand____rdiv__ __rdivmod__ __rfloordiv__ __rlshift__ __rmatmul____rmod____rmul____ror____rpow__ __rrshift____rsub__ __rtruediv____rxor____iadd____iand__ __ifloordiv__ __ilshift__ __imatmul____imod____imul____ior____ipow__ __irshift____isub__ __itruediv____ixor____abs____neg____pos__ __invert__ __trunc__ __floor____ceil__ __round____int____bool__ __nonzero__ __complex__ __float____iter____next____len__ __reversed__ __contains____call__ __getitem__ __setitem__ __delitem__rTr<rW __classcell__r r r7rr s     r cCst|tjtjfot|jtS)zHReturns True if `partial_fn` was constructed with `arg_factory.partial`.)rCrrr rr) partial_fnr r ris_arg_factory_partial=s   rc@s.eZdZUdZded<ddZeddZdS) raFunction wrapper that invokes the factories of ArgFactory args. When called, this wrapper transforms the arguments by replacing each `ArgFactory` argument `x` with `x.factory()`; and then calls the wrapped function with the transformed arguments. r/rcOs4tdd|D}dd|D}|j|i|S)Ncss|]}t|VqdSr)_arg_factory_valuer r r r Psz4_InvokeArgFactoryWrapper.__call__..cSrr r)rkeyrr r rrQrz5_InvokeArgFactoryWrapper.__call__..)tuplerr)r=rrr r rrOsz!_InvokeArgFactoryWrapper.__call__cCs t|jSr))inspect signaturerr?r r r __signature__Ts z&_InvokeArgFactoryWrapper.__signature__N)r"rYr!rZr[rr\rr r r rrDs rcCst|tr |S|Sr))rCr r%)rVr r rrYrFrcsHtddjDstdtfdd}|S)aDecorator that defines default factories for a function's parameters. Each time the decorated function is called, any missing parameter with a default factory has its value filled in by calling the factory. Default factories are specified by setting the default value of a parameter to `arg_factory.default_factory()`. For example, this can be used to define mutable default values for functions, that are created each time the function is called: >>> @arg_factory.supply_defaults ... def append(elt, seq: list[Any] = arg_factory.default_factory(list)): ... seq.append(elt) ... return seq This decorator can also be used in other contexts where the default value for a parameter should be computed each time the function is called. E.g.: >>> @arg_factory.supply_defaults ... def add_noise(value, noise = arg_factory.default_factory(random.random)): ... return value + noise**2 This decorator uses `functools.wraps` to copy fields such as `__name__` and `__doc__` from the wrapped function to the wrapper function. Args: wrapped_func: The function that should be decorated. Returns: The decorated function. cSs$i|]}t|jtr|j|jjqSr )rCdefaultr rr%)rparamr r rr~s   z#supply_defaults..zi@supply_defaults expected at least one argument to have a default value constructed with default_factory.csJj|i|}D]\}}||jvr||j|<q |ji|jSr))bindr argumentsrr)rr bound_argsrr% factoriesr wrapped_funcr rwrappers   z supply_defaults..wrapper)rr parametersvalues ValueErrorrwraps)rrr rrsupply_defaults]s rr%r0r1cCr2r)r r%r r rdefault_factoryr5rr/cCst|S)aReturns a value used to declare the default factory for a parameter. `default_factory` should be used in conjuction with the `@supply_defaults` decorator to declare default factories for a function's parameters. See the documentation for `supply_defaults` for more information. Args: factory: The factory that should be used to construct the value for a parameter. This factory is called each time the function is called. r rr r rrs rX)r%r/r1r )rZ __future__r dataclassesrrtypingrrrrrrr rr(r.r r dataclassrrrrr r r rs* 90  ;