API

Dispatch functions

reg.dispatch(*predicates, **kw)

Decorator to make a function dispatch based on its arguments.

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

Parameters:
Returns:

a function that you can use as if it were a reg.Dispatch instance.
class reg.Dispatch(predicates, callable, get_key_lookup)

Dispatch function.

You can register implementations based on particular predicates. The dispatch function dispatches to these implementations based on its arguments.

Parameters:
  • predicates – a list of predicates.
  • callable – the Python function object to register dispatch implementations for. The signature of an implementation needs to match that of this function. This function is used as a fallback implementation that is called if no specific implementations match.
  • get_key_lookup – a function that gets a PredicateRegistry instance and returns a key lookup. A PredicateRegistry instance is itself a key lookup, but you can return a caching key lookup (such as reg.DictCachingKeyLookup or reg.LruCachingKeyLookup) to make it more efficient.
add_predicates(predicates)

Add new predicates.

Extend the predicates used by this predicates. This can be used to add predicates that are configured during startup time.

Note that this clears up any registered implementations.

Parameters:predicates – a list of predicates to add.
all(*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.

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_by_keys(**kw)

Look up all functions dispatched to using keyword arguments.

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.

Kw:a dictionary. key is predicate name, value is predicate value. If omitted, predicate default is used.
Returns:iterable of functions being dispatched to.
clean()

Clean up implementations and added predicates.

This restores the dispatch function to its original state, removing registered implementations and predicates added using reg.Dispatch.add_predicates().

component(*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.

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_by_keys(**kw)

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.

Kw:key is predicate name, value is predicate value under which it was registered. If omitted, predicate default is used.
Returns:the function being dispatched to, or fallback.
fallback(*args, **kw)

Lookup fallback for args and kw.

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.
key_dict_to_predicate_key(key_dict)

Turn a key dict into a predicate key.

Given a key dict under which an implementation function is registered, return an immutable predicate key.

Parameters:key_dict – dict with registration information
Returns:an immutable predicate key
predicate_key(*args, **kw)

Construct predicate_key for function arguments.

For 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 TypeError.

Parameters:
  • 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(func=None, **key_dict)

Register an implementation.

If func is not specified, this method can be used as a decorator and the decorated function will be used as the actual func argument.

Parameters:
  • func – a function that implements behavior for this dispatch function. It needs to have the same signature as the original dispatch function. If this is a reg.DispatchMethod, then this means it needs to take a first context argument.
  • key_dict – keyword arguments describing the registration, with as keys predicate name and as values predicate values.
Returns:

func.
reg.match_key(name, func, fallback=None, default=None)

Predicate that returns a value used for dispatching.

Name:predicate name.
Func:a callable that accepts the same arguments as the generic function and returns the value used for dispatching. The returned value must be of an immutable type.
Fallback:the fallback value. By default it is None.
Default:optional default value.
Returns:a Predicate.
reg.match_instance(name, func=None, fallback=None, default=None)

Predicate that returns an instance whose class is used for dispatching.

Name:predicate name.
Func:a callable that accepts the same arguments as the generic function and returns the instance whose class is used for dispatching. If None, use a callable returning the argument with the same name as the predicate.
Fallback:the fallback value. By default it is None.
Default:optional default value.
Returns:a Predicate.
reg.match_class(name, func=None, fallback=None, default=None)

Predicate that returns a class used for dispatching.

Name:predicate name.
Func:a callable that accepts the same arguments as the generic function and returns a class used for dispatching. If None, use a callable returning the argument with the same name as the predicate.
Fallback:the fallback value. By default it is None.
Default:optional default value.
Returns:a Predicate.
class reg.DictCachingKeyLookup(key_lookup)

A key lookup that caches.

Implements the read-only API of reg.PredicateRegistry using a cache to speed up access.

This cache is backed by a simple dictionary so could potentially grow large if the dispatch in question can be called with a large combination of arguments that result in a large range of different predicate keys. If so, you can use reg.LruCachingKeyLookup instead.

Param:key_lookup - the PredicateRegistry to cache.
class reg.LruCachingKeyLookup(key_lookup, component_cache_size, all_cache_size, fallback_cache_size)

A key lookup that caches.

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

The cache is LRU so won’t grow beyond a certain limit, preserving memory. This is only useful if you except the access pattern to your function to involve a huge range of different predicate keys.

Param:

key_lookup - the PredicateRegistry 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(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:predicate_key – an immutable predicate key, constructed for the predicates given for this key.
Returns:An iterable of registered values.
component(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:predicate_key – an immutable predicate key, constructed for predicates given for this key.
Returns:a registered value, or None.
fallback(predicate_key)

Lookup fallback based on predicate_key.

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

Parameters: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.

Context-specific dispatch methods

reg.dispatch_method(*predicates, **kw)

Decorator to make a method on a context class dispatch.

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

Parameters:
class reg.DispatchMethod(predicates, callable, get_key_lookup)
add_predicates(predicates)

Add new predicates.

Extend the predicates used by this predicates. This can be used to add predicates that are configured during startup time.

Note that this clears up any registered implementations.

Parameters:predicates – a list of predicates to add.
all(*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.

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_by_keys(**kw)

Look up all functions dispatched to using keyword arguments.

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.

Kw:a dictionary. key is predicate name, value is predicate value. If omitted, predicate default is used.
Returns:iterable of functions being dispatched to.
clean()

Clean up implementations and added predicates.

This restores the dispatch function to its original state, removing registered implementations and predicates added using reg.Dispatch.add_predicates().

component(*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.

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_by_keys(**kw)

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.

Kw:key is predicate name, value is predicate value under which it was registered. If omitted, predicate default is used.
Returns:the function being dispatched to, or fallback.
fallback(*args, **kw)

Lookup fallback for args and kw.

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.
key_dict_to_predicate_key(key_dict)

Turn a key dict into a predicate key.

Given a key dict under which an implementation function is registered, return an immutable predicate key.

Parameters:key_dict – dict with registration information
Returns:an immutable predicate key
register(func=None, **key_dict)

Register an implementation.

If func is not specified, this method can be used as a decorator and the decorated function will be used as the actual func argument.

Parameters:
  • func – a function that implements behavior for this dispatch function. It needs to have the same signature as the original dispatch function. If this is a reg.DispatchMethod, then this means it needs to take a first context argument.
  • key_dict – keyword arguments describing the registration, with as keys predicate name and as values predicate values.
Returns:

func.
reg.clean_dispatch_methods(cls)

For a given class clean all dispatch methods.

This resets their registry to the original state using reg.DispatchMethod.clean().

Parameters:cls – a class that has reg.DispatchMethod methods on it.
reg.methodify(func, selfname=None)

Turn a function into a method, if needed.

If selfname is not specified, wrap the function so that it takes an additional first argument, like a method.

If selfname is specified, check whether it is the same as the name of the first argument of func. If itsn’t, wrap the function so that it takes an additional first argument, with the name specified by selfname.

If it is, the signature of func needn’t be amended, but wrapping might still be necessary.

In all cases, inspect_methodified() lets you retrieve the wrapped function.

Parameters:
  • func – the function to turn into method.
  • selfname – if specified, the name of the argument referencing the class instance. Typically, "self".
Returns:

function that can be used as a method when assigned to a class.

Errors

exception reg.RegistrationError

Registration error.

Argument introspection

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.

Predicate Registry

class reg.PredicateRegistry(predicate)
key_dict_to_predicate_key(d)

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: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.
class reg.Predicate(name, index, get_key=None, fallback=None, default=None)

A dispatch predicate.

Parameters:
  • name – predicate name. This is used by reg.Registry.register_function_by_name().
  • index – a function that constructs an index given a fallback argument; typically you supply either a KeyIndex or ClassIndex.
  • get_key – a callable that accepts a dictionary with the invocation arguments of the generic function and returns a key to be used for dispatching.
  • fallback – optional fallback value. The fallback of the the most generic index for which no values could be found is used.
  • default – optional predicate default. This is used by reg.Registry.register_function_by_name(), and supplies the value if it is not given explicitly.
class reg.ClassIndex(fallback=None)
permutations(key)

Permutations for class key.

Returns class and its base classes 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.

Parameters:
  • name – predicate name.
  • get_key – a callable that accepts a dictionary with the invocation arguments of the generic function and returns a key to be used for dispatching.
  • 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.

Parameters:
  • name – predicate name.
  • get_key – a callable that accepts a dictionary with the invocation arguments of the generic function and returns a key to be used for dispatching.
  • fallback – a fallback value. By default is None.
  • default – optional default value.
Returns:

a Predicate.