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.
by_args(*args, **kw)

Lookup an implementation by invocation arguments.

Parameters:
  • args – positional arguments used in invocation.
  • kw – named arguments used in invocation.
Returns:

a reg.LookupEntry.

by_predicates(**predicate_values)

Lookup an implementation by predicate values.

Parameters:predicate_values – the values of the predicates to lookup.
Returns:a reg.LookupEntry.
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().

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=None, 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.

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_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.LookupEntry

The dispatch data associated to a key.

all_matches

The list of all compatible implementations.

component

The function to dispatch to, excluding fallbacks.

fallback

The approriate fallback implementation.

matches

An iterator over all the compatible implementations.

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.

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:
  • predicates

    sequence of Predicate instances to do the dispatch on. You create predicates using reg.match_instance(), reg.match_key(), reg.match_class(), or with a custom predicate class.

    You can also pass in plain string argument, which is turned into a reg.match_instance() predicate.

  • 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.
  • first_invocation_hook – a callable that accepts an instance of the class in which this decorator is used. It is invoked the first time the method is invoked.
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.
by_args(*args, **kw)

Lookup an implementation by invocation arguments.

Parameters:
  • args – positional arguments used in invocation.
  • kw – named arguments used in invocation.
Returns:

a reg.LookupEntry.

by_predicates(**predicate_values)

Lookup an implementation by predicate values.

Parameters:predicate_values – the values of the predicates to lookup.
Returns:a reg.LookupEntry.
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().

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.

Low-level predicate support

Typically, you’d be using reg.match_key(), reg.match_instance(), and reg.match_class() to define predicates. Should you require finer control, you can use the following classes:

class reg.Predicate(name, index, get_key=None, fallback=None, default=None)

A dispatch predicate.

Parameters:
  • name – name used to identify the predicate when specifying its expected value in reg.Dispatch.register().
  • 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 – default expected value of the predicate, to be used by reg.Dispatch.register() whenever the expected value for the predicate 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)
permutations(key)

Permutations for a simple immutable key.

There is only a single permutation: the key itself.