This class provides a decorator that maps (transforms) arguments of the function before the function is called. Thus for example, we have similar code in many functions to determine whether an argument is the number of nodes to be created, or a list of nodes to be handled. The decorator provides the code to accept either -- transforming the indicated argument into a list of nodes before the actual function is called.
This decorator class allows us to process single or multiple arguments. The arguments to be processed can be specified by string, naming the argument, or by index, specifying the item in the args list.
An object of this class is callable and intended to be used when defining a decorator. Generally, a decorator takes a function as input and constructs a function as output. Specifically, an argmap
object returns the input function decorated/wrapped so that specified arguments are mapped (transformed) to new values before the decorated function is called.
As an overview, the argmap object returns a new function with all the dunder values of the original function (like :None:None:`__doc__`, :None:None:`__name__`, etc). Code for this decorated function is built based on the original function's signature. It starts by mapping the input arguments to potentially new values. Then it calls the decorated function with these new values in place of the indicated arguments that have been mapped. The return value of the original function is then returned. This new function is the function that is actually called by the user.
Three additional features are provided.
The code is lazily compiled. That is, the new function is returned
as an object without the code compiled, but with all information needed so it can be compiled upon it's first invocation. This saves time on import at the cost of additional time on the first call of the function. Subsequent calls are then just as fast as normal.
If the "try_finally" keyword-only argument is True, a try block
follows each mapped argument, matched on the other side of the wrapped call, by a finally block closing that mapping. We expect func to return a 2-tuple: the mapped value and a function to be called in the finally clause. This feature was included so the open_file
decorator could provide a file handle to the decorated function and close the file handle after the function call. It even keeps track of whether to close the file handle or not based on whether it had to open the file or the input was already open. So, the decorated function does not need to include any code to open or close files.
The maps applied can process multiple arguments. For example,
you could swap two arguments using a mapping, or transform them to their sum and their difference. This was included to allow a decorator in the :None:None:`quality.py` module that checks that an input :None:None:`partition` is a valid partition of the nodes of the input graph :None:None:`G`. In this example, the map has inputs :None:None:`(G, partition)`. After checking for a valid partition, the map either raises an exception or leaves the inputs unchanged. Thus many functions that make this check can use the decorator rather than copy the checking code into each function. More complicated nested argument structures are described below.
The remaining notes describe the code structure and methods for this class in broad terms to aid in understanding how to use it.
Instantiating an argmap
object simply stores the mapping function and the input identifiers of which arguments to map. The resulting decorator is ready to use this map to decorate any function. Calling that object (argmap.__call__
, but usually done via :None:None:`@my_decorator`) a lazily compiled thin wrapper of the decorated function is constructed, wrapped with the necessary function dunder attributes like :None:None:`__doc__` and :None:None:`__name__`. That thinly wrapped function is returned as the decorated function. When that decorated function is called, the thin wrapper of code calls :None:None:`argmap._lazy_compile` which compiles the decorated function (using argmap.compile
) and replaces the code of the thin wrapper with the newly compiled code. This saves the compilation step every import of networkx, at the cost of compiling upon the first call to the decorated function.
When the decorated function is compiled, the code is recursively assembled using the argmap.assemble
method. The recursive nature is needed in case of nested decorators. The result of the assembly is a number of useful objects.
sig
sig
wrapped_name
wrapped_name
functions
functions
mapblock
mapblock
finallys
finallys
mutable_args
mutable_args
After this recursive assembly process, the argmap.compile
method constructs code (as strings) to convert the tuple :None:None:`sig.args` to a list if needed. It joins the defining code with appropriate indents and compiles the result. Finally, this code is evaluated and the original wrapper's implementation is replaced with the compiled version (see :None:None:`argmap._lazy_compile` for more details).
Other argmap
methods include :None:None:`_name` and :None:None:`_count` which allow internally generated names to be unique within a python session. The methods :None:None:`_flatten` and :None:None:`_indent` process the nested lists of strings into properly indented python code ready to be compiled.
More complicated nested tuples of arguments also allowed though usually not used. For the simple 2 argument case, the argmap input ("a", "b") implies the mapping function will take 2 arguments and return a 2-tuple of mapped values. A more complicated example with argmap input :None:None:`("a", ("b", "c"))` requires the mapping function take 2 inputs, with the second being a 2-tuple. It then must output the 3 mapped values in the same nested structure :None:None:`(newa, (newb, newc))`. This level of generality is not often needed, but was convenient to implement when handling the multiple arguments.
The function to apply to arguments
A list of parameters, specified either as strings (their names), ints (numerical indices) or tuples, which may contain ints, strings, and (recursively) tuples. Each indicates which parameters the decorator should map. Tuples indicate that the map function takes (and returns) multiple parameters in the same order and nested structure as indicated here.
When True, wrap the function call in a try-finally block with code for the finally block created by :None:None:`func`. This is used when the map function constructs an object (like a file handle) that requires post-processing (like closing).
Note: try_finally decorators cannot be used to decorate generator functions.
A decorator to apply a map to arguments before calling the function
@convert_to("US_Dollars", "income") def show_me_the_money(name, income): print(f"{name} : {income}")
Despite this common idiom for argmap, most of the following examples use the :None:None:`@argmap(...)` idiom to save space.
@argmap(sum, "xlist", "zlist") def foo(xlist, y, zlist): return xlist - y + zlist
def foo(xlist, y, zlist):
x = sum(xlist) z = sum(zlist) return x - y + z
@argmap(sum, "xlist", 2) def foo(xlist, y, zlist): return xlist - y + zlist
@argmap(sum, "zlist", 0) def foo(xlist, y, zlist): return xlist - y + zlist
def swap(x, y):
return y, x
# the 2-tuple tells argmap that the map
:None:None:`swap`has 2 inputs/outputs. @argmap(swap, ("a", "b")): def foo(a, b, c): return a / b * c
def foo(a, b, c):
a, b = swap(a, b) return a / b * c
More generally, the applied arguments can be nested tuples of strings or ints. The syntax :None:None:`@argmap(some_func, ("a", ("b", "c")))` would expect :None:None:`some_func` to accept 2 inputs with the second expected to be a 2-tuple. It should then return 2 outputs with the second a 2-tuple. The returns values would replace input "a" "b" and "c" respectively. Similarly for :None:None:`@argmap(some_func, (0, ("b", 2)))`.
def double(a):
return 2 * a
@argmap(double, 3) def overflow(a, *args): return a, args
print(overflow(1, 2, 3, 4, 5, 6)) # output is 1, (2, 3, 8, 5, 6)
Try Finally
Additionally, this argmap
class can be used to create a decorator that initiates a try...finally block. The decorator must be written to return both the transformed argument and a closing function. This feature was included to enable the open_file
decorator which might need to close the file or not depending on whether it had to open that file. This feature uses the keyword-only :None:None:`try_finally` argument to :None:None:`@argmap`.
def open_file(fn):
f = open(fn) return f, lambda: f.close()
@argmap(open_file, "file", try_finally=True) def foo(file): print(file.read())
def foo(file):
file, close_file = open_file(file) try: print(file.read()) finally: close_file()
@argmap(open_file, 0, try_finally=True) def foo(file): print(file.read())
@my_closing_decorator("file") def fancy_reader(file=None): # this code doesn't need to worry about closing the file print(file.read())
@argmap(open_file, "file", try_finally=True) def file_to_lines(file): for line in file.readlines(): yield line
def file_to_lines_wrapped(file):
for line in file.readlines():
yield line
def file_to_lines_wrapper(file):
try:
file = open_file(file) return file_to_lines_wrapped(file)
finally:
file.close()
def file_to_lines_whoops(file):
file = open_file(file) file.close() for line in file.readlines(): yield line
because the :None:None:`finally` block of :None:None:`file_to_lines_wrapper` is executed before the caller has a chance to exhaust the iterator.
The following pages refer to to this document either explicitly or contain code examples using this.
networkx.utils.decorators.argmap
Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.
Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)
SVG is more flexible but power hungry; and does not scale well to 50 + nodes.
All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them