API

reg.dispatch(*predicates)

Decorator to make a function dispatch based on its arguments.

This takes the predicates to dispatch on as zero or more parameters.

Parameters:predicates – sequence of Predicate instances to do the dispatch on.
reg.match_key(name, func, fallback=None, default=None)

Predicate that extracts immutable key according to func.

Name:predicate name.
Func:argument that takes arguments. These arguments are extracted from the arguments given to the dispatch function. This function should return what to dispatch on.
Fallback:the fallback value. By default it is None.
Default:optional default value.
Returns:a Predicate.
reg.match_instance(name, func, fallback=None, default=None)

Predicate that extracts class of instance returned by func.

Name:predicate name.
Func:argument that takes arguments. These arguments are extracted from the arguments given to the dispatch function. This function should return an instance; dispatching is done on the class of that instance.
Fallback:the fallback value. By default it is None.
Default:optional default value.
Returns:a Predicate.
reg.match_argname(argname, fallback=None, default=None)

Predicate that extracts class of specified argument.

Name:predicate name.
Argname:name of the argument to dispatch on - its class will be used for the dispatch.
Fallback:the fallback value. By default it is None.
Default:optional default value.
Returns:a Predicate.
reg.match_class(name, func, fallback=None, default=None)

Predicate that extracts class returned by func.

Name:predicate name.
Func:argument that takes arguments. These arguments are extracted from the arguments given to the dispatch function. This function should return a class; dispatching is done on this class.
Fallback:the fallback value. By default it is None.
Default:optional default value.
Returns:a Predicate.
class reg.Lookup(key_lookup)

The lookup is used for generic dispatch.

The arguments to the lookup functions are those of the dispatch function being called. The lookup extract the predicate_key from these arguments and then looks up the actual function to call. This function is then called with the original arguments.

Parameters:key_lookup – the key lookup, either a Registry or CachingKeyLookup.
all(callable, *args, **kw)

Lookup all functions dispatched to with args and kw.

Looks up functions for all permutations based on predicate_key, where predicate_key is constructed from args and kw.

Parameters:callable – the dispatch function.
Args:varargs. Used to extract dispatch information to construct predicate_key.
Kw:keyword arguments. Used to extract dispatch information to construct predicate_key.
Returns:an iterable of functions.
all_key_dict(callable, key_dict)

Look up all functions dispatched to using on key_dict.

Looks up the function to dispatch to using a key_dict, mapping predicate name to predicate value. Returns the fallback value (default: None) if nothing could be found.

Parameters:callable – the dispatch function
Key_dict:a dictionary. key is predicate name, value is predicate value. If omitted, predicate default is used.
Returns:iterable of functions being dispatched to.
call(callable, *args, **kw)

Call callable with args and kw.

Do a dispatch call for callable. If nothing more specific is registered, call the dispatch function as a fallback.

Parameters:callable – the dispatch function to call.
Args:varargs for the call. Is also used to extract dispatch information to construct predicate_key.
Kw:keyword arguments for the call. Is also used to extract dispatch information to construct predicate_key.
Returns:the result of the call.
component(callable, *args, **kw)

Lookup function dispatched to with args and kw.

Looks up the function to dispatch to using args and kw. Returns the fallback value (default: None) if nothing could be found.

Parameters:callable – the dispatch function.
Args:varargs. Used to extract dispatch information to construct predicate_key.
Kw:keyword arguments. Used to extract dispatch information to construct predicate_key.
Returns:the function being dispatched to, or None.
component_key_dict(callable, key_dict)

Look up function based on key_dict.

Looks up the function to dispatch to using a key_dict, mapping predicate name to predicate value. Returns the fallback value (default: None) if nothing could be found.

Parameters:callable – the dispatch function
Key_dict:a dictionary. key is predicate name, value is predicate value. If omitted, predicate default is used.
Returns:the function being dispatched to, or fallback.
fallback(callable, *args, **kw)

Lookup fallback for args and kw.

Parameters:callable – the dispatch function.
Args:varargs. Used to extract dispatch information to construct predicate_key.
Kw:keyword arguments. Used to extract dispatch information to construct predicate_key.
Returns:the function being dispatched to, or fallback.
class reg.PredicateRegistry(predicate)
class reg.Predicate(name, index, get_key=None, fallback=None, default=None)

A dispatch predicate.

argnames()

argnames that this predicate needs to dispatch on.

class reg.ClassIndex(fallback=None)
permutations(key)

Permutations for class key.

Returns class and its based in mro order. If a classic class in Python 2, smuggle in object as the base class anyway to make lookups consistent.

class reg.KeyIndex(fallback=None)
fallback(key)

Return fallback if this index does not contain key.

If index contains permutations of key, then NOT_FOUND is returned.

permutations(key)

Permutations for a simple immutable key.

There is only a single permutation: the key itself.

reg.key_predicate(name, get_key=None, fallback=None, default=None)

Construct predicate indexed on any immutable value.

Name:predicate name.
Get_key:a KeyExtractor. Should return key to dispatch on.
Fallback:a fallback value. By default is None.
Default:optional default value.
Returns:a Predicate.
reg.class_predicate(name, get_key=None, fallback=None, default=None)

Construct predicate indexed on class.

Name:predicate name.
Get_key:a KeyExtractor. Should return class to dispatch on.
Fallback:a fallback value. By default is None.
Default:optional default value.
Returns:a Predicate.
class reg.Registry

A registry of predicate registries

The key is an immutable that we perform the lookup for. The permutation key is the key to do the lookup with. The value should be an immutable as well (or at least hashable).

The registry can be configured with predicates for a key, and the predicates are aware of permutations of keys. This means, among others, that a value registered for a base class is also matched when you look up a subclass.

The Registry is designed to be easily cacheable.

all(key, predicate_key)

Lookup iterable of values registered for predicate_key.

Looks up values registered for all permutations of predicate_key, the most specific first.

Parameters:
  • key – an immutable for which to look up the values.
  • predicate_key – an immutable predicate key, constructed for the predicates given for this key.
Returns:

An iterable of registered values.

clear()

Clear the registry.

component(key, predicate_key)

Lookup value in registry based on predicate_key.

If value for predicate_key cannot be found, looks up first permutation of predicate_key for which there is a value. Permutations are made according to the predicates registered for the key.

Parameters:
  • key – an immutable for which to look up the predicate_key.
  • predicate_key – an immutable predicate key, constructed for predicates given for this key.
Returns:

a registered value, or None if nothing was found.

fallback(key, predicate_key)

Lookup fallback based on predicate_key.

This finds the fallback for the most specific predicate that fails to match.

Parameters:
  • key – an immutable for which to look up the predicate_key.
  • predicate_key – an immutable predicate key, constructed for predicates given for this key.
Returns:

the fallback value for the most specific predicate the failed to match.

key_dict_to_predicate_key(callable, key_dict)

Construct predicate key from key dictionary.

Uses name and default attributes of predicate to construct the predicate key. If the key cannot be constructed then a KeyError is raised.

Parameters:
  • callable – the callable for which to extract the predicate_key
  • key_dict – dictionary with predicate name keys and predicate values. For omitted keys, the predicate default is used.
Returns:

an immutable predicate_key based on the dictionary and the names and defaults of the predicates the callable was configured with.

lookup()

A Lookup for this registry.

predicate_key(callable, *args, **kw)

Construct predicate_key for function arguments.

For a callable and its function arguments, construct the appropriate predicate_key. This is used by the dispatch mechanism to dispatch to the right function.

If the predicate_key cannot be constructed from args and kw, this raises a KeyExtractorError.

Parameters:
  • callable – the callable for which to extract the predicate_key
  • args – the varargs given to the callable.
  • kw – the keyword arguments given to the callable.
Returns:

an immutable predicate_key based on the predicates the callable was configured with.

register_callable_predicates(callable, predicates)

Register predicates for a callable key.

Works as register_predicates(), but also makes sure a predicate key can be constructed from arguments to this callable.

Parameters:
  • callable – a function from which to extract argument information.
  • predicates – a sequence of reg.Predicate objects.
Returns:

a reg.PredicateRegistry.

register_dispatch(callable)

Register a dispatch function.

Works as register_dispatch_predicates(), but extracts predicate information from information registered.

For dispatch() these are the predicates supplied to it in its arguments.

For dispatch_external_predicates() these are the predicates supplied using register_external_predicates().

Parameters:callable – a dispatch callable.
Returns:a reg.PredicateRegistry.
register_dispatch_predicates(callable, predicates)

Register a dispatch function.

Works as register_callable_predicates(), but works with a dispatch and makes sure predicates can’t be registered twice.

Parameters:
  • callable – a dispatch callable.
  • predicates – a sequence of reg.Predicate objects.
Returns:

a reg.PredicateRegistry.

register_external_predicates(callable, predicates)

Register external predicates for dispatch_external_predicates.

dispatch_external_predicates looks for predicates registered for the dispatch here. You can define them here.

Parameters:
  • callable – a dispatch_external_predicates callable.
  • predicates – a sequence of reg.Predicate objects.
register_function(callable, value, **key_dict)

Register a callable for a dispatch function.

Like register_function_by_predicate_key(), but constructs the predicate_key based on the key_dict argument, using the name and default arguments to Predicate.

register_function_by_predicate_key(callable, predicate_key, value)

Register a callable for a dispatch function.

Like register_value(), but makes sure that the value is a callable with the same signature as the original dispatch callable. If not, a reg.RegistrationError is raised.

register_predicates(key, predicates)

Register the predicates to use for a lookup key.

Parameters:
  • key – an immutable for which to register the predicates.
  • predicates – a sequence of reg.Predicate objects.
Returns:

a reg.PredicateRegistry.

register_value(key, predicate_key, value)

Register a value for a predicate_key.

Given a key, register a value for a particular predicate_key in the registry. Raises a reg.RegistrationError if the predicate_key is already known for this key.

Parameters:
  • key – an immutable
  • predicate_key – an immutable predicate key defined by the predicates for this key.
  • value – an immutable value to register.
class reg.CachingKeyLookup(key_lookup, component_cache_size, all_cache_size, fallback_cache_size)

A key lookup that caches.

Implements the read-only API of Registry, using a cache to speed up access.

The cache is LRU.

Param:

key_lookup - the Registry to cache.

Parameters:
  • component_cache_size – how many cache entries to store for the component() method. This is also used by dispatch calls.
  • all_cache_size – how many cache entries to store for the the all() method.
  • fallback_cache_size – how many cache entries to store for the fallback() method.
all(key, predicate_key)

Lookup iterable of values registered for predicate_key.

Looks up values registered for all permutations of predicate_key, the most specific first.

Parameters:
  • key – an immutable for which to look up the values.
  • predicate_key – an immutable predicate key, constructed for the predicates given for this key.
Returns:

An iterable of registered values.

component(key, predicate_key)

Lookup value in registry based on predicate_key.

If value for predicate_key cannot be found, looks up first permutation of predicate_key for which there is a value. Permutations are made according to the predicates registered for the key.

Parameters:
  • key – an immutable for which to look up the predicate_key.
  • predicate_key – an immutable predicate key, constructed for predicates given for this key.
Returns:

a registered value, or None.

fallback(key, predicate_key)

Lookup fallback based on predicate_key.

This finds the fallback for the most specific predicate that fails to match.

Parameters:
  • key – an immutable for which to look up the predicate_key.
  • predicate_key – an immutable predicate key, constructed for predicates given for this key.
Returns:

the fallback value for the most specific predicate the failed to match.

lookup()

A Lookup for this registry.

class reg.Lookup(key_lookup)

The lookup is used for generic dispatch.

The arguments to the lookup functions are those of the dispatch function being called. The lookup extract the predicate_key from these arguments and then looks up the actual function to call. This function is then called with the original arguments.

Parameters:key_lookup – the key lookup, either a Registry or CachingKeyLookup.
all(callable, *args, **kw)

Lookup all functions dispatched to with args and kw.

Looks up functions for all permutations based on predicate_key, where predicate_key is constructed from args and kw.

Parameters:callable – the dispatch function.
Args:varargs. Used to extract dispatch information to construct predicate_key.
Kw:keyword arguments. Used to extract dispatch information to construct predicate_key.
Returns:an iterable of functions.
all_key_dict(callable, key_dict)

Look up all functions dispatched to using on key_dict.

Looks up the function to dispatch to using a key_dict, mapping predicate name to predicate value. Returns the fallback value (default: None) if nothing could be found.

Parameters:callable – the dispatch function
Key_dict:a dictionary. key is predicate name, value is predicate value. If omitted, predicate default is used.
Returns:iterable of functions being dispatched to.
call(callable, *args, **kw)

Call callable with args and kw.

Do a dispatch call for callable. If nothing more specific is registered, call the dispatch function as a fallback.

Parameters:callable – the dispatch function to call.
Args:varargs for the call. Is also used to extract dispatch information to construct predicate_key.
Kw:keyword arguments for the call. Is also used to extract dispatch information to construct predicate_key.
Returns:the result of the call.
component(callable, *args, **kw)

Lookup function dispatched to with args and kw.

Looks up the function to dispatch to using args and kw. Returns the fallback value (default: None) if nothing could be found.

Parameters:callable – the dispatch function.
Args:varargs. Used to extract dispatch information to construct predicate_key.
Kw:keyword arguments. Used to extract dispatch information to construct predicate_key.
Returns:the function being dispatched to, or None.
component_key_dict(callable, key_dict)

Look up function based on key_dict.

Looks up the function to dispatch to using a key_dict, mapping predicate name to predicate value. Returns the fallback value (default: None) if nothing could be found.

Parameters:callable – the dispatch function
Key_dict:a dictionary. key is predicate name, value is predicate value. If omitted, predicate default is used.
Returns:the function being dispatched to, or fallback.
fallback(callable, *args, **kw)

Lookup fallback for args and kw.

Parameters:callable – the dispatch function.
Args:varargs. Used to extract dispatch information to construct predicate_key.
Kw:keyword arguments. Used to extract dispatch information to construct predicate_key.
Returns:the function being dispatched to, or fallback.
exception reg.RegistrationError

Registration error.

exception reg.KeyExtractorError

A lookup key could not be constructed.

class reg.implicit.Implicit

Implicit global lookup.

There will only one singleton instance of this, called reg.implicit. The lookup can then be accessed using reg.implicit.lookup.

Dispatch functions as well as their component and all methods make use of this information if you do not pass an explicit lookup argument to them. This is handy as it becomes unnecessary to have to pass a lookup object everywhere.

The drawback is that this single global lookup is implicit, which makes it harder to test in isolation. Reg supports testing with the explicit lookup argument, but that is not useful if you are testing code that relies on an implicit lookup. Therefore Reg strives to make the implicit global lookup as explicit as possible so that it can be manipulated in tests where this is necessary.

It is also possible for a framework to change the implicit lookup during run-time. This is done by simply assigning to implicit.lookup. The lookup is stored on a thread-local and is unique per thread.

To change the lookup back to a lookup in the global implicit registry, call reset.

The implicit lookup is thread-local: each thread has a separate implicit global lookup.

clear()

Clear global implicit lookup.

initialize(lookup)

Initialize implicit with lookup.

Parameters:lookup (ILookup.) – The lookup that will be the global implicit lookup.
lookup

Get the implicit ILookup.

reset()

Reset global implicit lookup to original lookup.

This can be used to wipe out any composed lookups that were installed in this thread.

exception reg.NoImplicitLookupError

No implicit lookup was registered.

Register an implicit lookup by calling reg.implicit.initialize(), or pass an explicit lookup argument to generic function calls.

reg.mapply(func, *args, **kw)

Apply keyword arguments to function only if it defines them.

So this works without error as b is ignored:

def foo(a):
    pass

mapply(foo, a=1, b=2)

Zope has an mapply that does this but a lot more too. py.test has an implementation of getting the argument names for a function/method that we’ve borrowed.

reg.arginfo(callable)

Get information about the arguments of a callable.

Returns a inspect.ArgSpec object as for inspect.getargspec().

inspect.getargspec() returns information about the arguments of a function. arginfo also works for classes and instances with a __call__ defined. Unlike getargspec, arginfo treats bound methods like functions, so that the self argument is not reported.

arginfo returns None if given something that is not callable.

arginfo caches previous calls (except for instances with a __call__), making calling it repeatedly cheap.

This was originally inspired by the pytest.core varnames() function, but has been completely rewritten to handle class constructors, also show other getarginfo() information, and for readability.