giving.gvr
- class giving.gvr.Giver(*, keys=None, special=[], extra={}, context=<ContextVar name='global_context' default=()>, inherited=<ContextVar name='global_inherited' default={}>, transform=None)
Giver of key/value pairs.
Giver
is the class of thegive
object.- Parameters
keys – List of default keys to give. If
keys=["x"]
, thenself(123)
will give{"x": 123}
.special – List of special keys to give (e.g. “$line”, “$time”, etc.)
extra – Extra key/value pairs to give.
context – The ContextVar that contains a list of handlers to call when something is given.
inherited – A ContextVar to use for inherited key/value pairs to give, as set by
with self.inherit(key=value): ...
.transform – A function from dict to dict that modifies the values to give.
- copy(keys=None, special=None, extra=None, context=None, inherited=None, transform=None)
Copy this Giver with modified parameters.
- inherit(**keys)
Create a context manager within which extra values are given.
with give.inherit(a=1): give(b=2) # gives {"a": 1, "b": 2}
- Parameters
keys – The key/value pairs to give within the block.
- property line
Return a giver that gives the line where it is called.
- produce(values)
Give the values dictionary.
- property time
Return a giver that gives the time where it is called.
- variant(fn)
Create a version of give that transforms the data.
@give.variant def give_image(data): return {"image": data} ... give_image(x, y) # gives {"image": {"x": x, "y": y}}
- Parameters
fn – A function from a dict to a dict.
give – The base give function to wrap (defaults to global give).
- wrap(name, **keys)
Create a context manager that marks the beginning/end of the block.
wrap
first creates a unique ID to identify the block, then gives the$wrap
sentinel with name, uid and step=”begin” at the beginning of it gives the same$wrap
but with step=”end” at the end of the block.giving.gvn.ObservableProxy.wrap()
is the corresponding method on the ObservableProxy returned bygiven()
and it can be used to wrap another context manager on the same block.giving.gvn.ObservableProxy.group_wrap()
is another method that uses the sentinels produced bywrap
.with give.wrap("W", x=1): # gives: {"$wrap": {"name": "W", "step": "begin", "id": ID}, "x": 1} ... # end block, gives: {"$wrap": {"name": "W", "step": "end", "id": ID}, "x": 1}
- Parameters
name – The name to associate to this wrap block.
keys – Extra key/value pairs to give along with the sentinels.
- wrap_inherit(name, **keys)
Shorthand for using wrap and inherit.
with give.wrap_inherit("W", a=1): ...
Is equivalent to:
with give.inherit(a=1): with give.wrap("W"): ...
- Parameters
name – The name to associate to this wrap block.
keys – Key/value pairs to inherit.
- giving.gvr.register_special(key)
Return a decorator to register a function for a special key.
The function is called with no arguments whenever the special key is requested, e.g. with
Giver(special=["$specialkey"])
.Use
sys._getframe(3)
to get the frame in which give() was called.Example
@register_special("$time") def _special_time(): return time.time()
- Parameters
key – The key, conventionally starting with a “$”.
- giving.gvr.resolve(frame, func, args)
Return a {variable_name: value} dictionary depending on usage.
len(args) == 0
=> Use the variable assigned in the line before the call.len(args) == 1
=> Use the variable the call is assigned to.len(args) >= 1
=> Use the variables passed as arguments to the call.
- Parameters
frame – The number of frames to go up to find the context.
func – The Giver object that was called.
args – The arguments given to the Giver.