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: - predicates – sequence of
reg.Predicate
instances to do the dispatch on. You create predicates usingreg.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 areg.match_instance()
predicate. - get_key_lookup – a function that gets a
PredicateRegistry
instance and returns a key lookup. APredicateRegistry
instance is itself a key lookup, but you can return a caching key lookup (such asreg.DictCachingKeyLookup
orreg.LruCachingKeyLookup
) to make it more efficient.
Returns: a function that you can use as if it were a
reg.Dispatch
instance.- predicates – sequence of
-
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. APredicateRegistry
instance is itself a key lookup, but you can return a caching key lookup (such asreg.DictCachingKeyLookup
orreg.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:
-
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 actualfunc
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
.- 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.
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.
- component_cache_size – how many cache entries to store for
the
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 usingreg.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. APredicateRegistry
instance is itself a key lookup, but you can return a caching key lookup (such asreg.DictCachingKeyLookup
orreg.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.
- predicates –
-
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:
-
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 actualfunc
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
.- 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.
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 offunc
. If itsn’t, wrap the function so that it takes an additional first argument, with the name specified byselfname
.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.
Argument introspection¶
-
reg.
arginfo
(callable)¶ Get information about the arguments of a callable.
Returns a
inspect.ArgSpec
object as forinspect.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
orClassIndex
. - 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.
- name – name used to identify the predicate when specifying
its expected value in