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 the give object.

Parameters

  • keys – List of default keys to give. If keys=["x"], then self(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 by given() 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 by wrap.

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.

class giving.gvr.LinePosition(name, filename, lineno)
filename

Alias for field number 1

lineno

Alias for field number 2

name

Alias for field number 0