Invisible Parameter Passing using Crosscuts

Have you ever found yourself needing to refactor massive amounts of code just to make sure that one stupid parameter got passed all the way down from the place it was defined, to another place where it was needed, even though none of the functions in between needed to use it? Or have you found yourself gritting your teeth and giving in to the urge to use a global or thread-local variable because the alternatives were just too painful, or because some of the code involved was part of another package?

The peak.util.crosscuts module provides a simple alternative, often found in other dynamic languages and AOP toolkits: dynamically-scoped variables. In essence, they're a way to pass an "invisible parameter" through the call stack, without actually changing any functions or adding any call-time overhead. A simple (and slightly stupid) example:

>>> from peak.util import crosscuts

Here, we define a receiver function to obtain the current Request object:

>>> @crosscuts.receiver
... def current_request():
...     raise RuntimeError("No current request")

Next, we mark the request local variable in this function as containing the current_request value for this function and its callees:

>>> @crosscuts.export(request=current_request)
... def wsgi_app(environ, start_response=None):
...     request = Request(environ)
...     for cb in callbacks: cb()   # look ma, no parameters

And make a zero-argument callback that uses the receiver function to get the current request:

>>> def some_callback():
...     print current_request()

Now, by default, the receiver function runs its original, default body if there's no current value on the call stack:

>>> some_callback()
Traceback (most recent call last):
  ...
RuntimeError: No current request

But, once everything's set up and we actually run the exporting function, the receiver returns the nearest active value on the call stack:

>>> callbacks = [some_callback]

>>> class Request:
...     def __init__(self, environ): self.environ = environ
...     def __repr__(self): return 'Request(%r)' % (self.environ,)

>>> wsgi_app({'x':'y'})
Request({'x': 'y'})

>>> wsgi_app({1:2})
Request({1: 2})

But then things go back to normal once there are no running exporters:

>>> some_callback()
Traceback (most recent call last):
  ...
RuntimeError: No current request

Multiple receivers and exporters can be in use at the same time, and the call stack is searched upward until a matching exporter is found for the called receiver:

>>> @crosscuts.receiver
... def database():
...     raise RuntimeError("No database")

>>> @crosscuts.export(db=database)
... def using_db(db, func, *args, **kw):
...     return func(*args, **kw)

>>> def another_callback():
...     print "Current database:", database()

>>> another_callback()
Traceback (most recent call last):
  ...
RuntimeError: No database

>>> callbacks.append(another_callback)

>>> using_db(123, wsgi_app, {4:5})
Request({4: 5})
Current database: 123

Notice, by the way, that if you're writing a framework that needs to pass its objects (requests, connections, whatever) around, your clients' code need not know about the crosscuts module: users can just import your receiver functions, and call them as they would any comparable API. Your code can simply export local variables from selected functions, instead of mucking around with global variables.

For more on the features, limitations, API details, and other cool stuff, please consult the complete Crosscuts developer's guide. Questions, comments, and bug reports for this package should be directed to the PEAK mailing list.

>>> @crosscuts.receiver
... def current_request():
...     raise RuntimeError("No current request")

>>> @crosscuts.receiver
... def dummy(a):
...     pass
Traceback (most recent call last):
  ...
AssertionError: Receivers can't take arguments

@crosscuts.export(request=current_request)
def wsgi_app(environ, start_response):
    request = Request(environ)
    # From here on (unless you 'del request' or the function is exited)
    # any functions called from this frame will receive the value of
    # `request` when they call `current_request()`.  However,
    # `current_request()` will still return its old value if it's
    # called *directly* from this function, regardless of the contents
    # of `request`.  (i.e., the new value is ONLY exported to callees.)

>>> @crosscuts.export(something=current_request)
... def dummy():
...     pass
Traceback (most recent call last):
  ...
TypeError: <function dummy...> has no local variable or argument 'something'

>>> @crosscuts.export(x=current_request, y=current_request)
... def dummy(x, y):
...     pass
Traceback (most recent call last):
  ...
TypeError: <...current_request...> is already exposed by 'y' in <...dummy...>

>>> @crosscuts.export(x=current_request)
... @crosscuts.export(y=current_request)
... def dummy(x, y):
...     pass
Traceback (most recent call last):
  ...
TypeError: <...current_request...> is already exposed by 'y' in <...dummy...>

>>> @crosscuts.export(x=current_request)
... @crosscuts.export(x=database)
... def dummy(x):
...     def nested():
...         print current_request(), database()
...     nested()

>>> dummy(42)
42 42

>>> @crosscuts.export(x=dummy)
... def dummy2(x):
...     pass
Traceback (most recent call last):
  ...
TypeError: ('Not a crosscuts.receiver', <function dummy...>)

>>> @crosscuts.export(request=current_request, db=database)
... def wsgi_app(environ, start_response=None):
...     request = Request(environ)
...     for cb in callbacks: cb()   # look ma, no parameters
...     db = None   # it's a variable, but not bound at callback time

>>> using_db(123, wsgi_app, {4:5})
Request({4: 5})
Current database: 123

>>> wsgi_app({1:2})
Traceback (most recent call last):
  ...
RuntimeError: No database

>>> def outer(x):
...     @crosscuts.export(x=database)
...     @crosscuts.export(x=current_request)
...     def inner():
...         x
...         for cb in callbacks: cb()
...     return inner

>>> outer(23)()
23
Current database: 23