pyswitch 1.2

A simple yet powerful 'switch'-like dispatcher system for Python

What is it ?

This is pyswitch, a simple yet powerful ‘switch’-like dispatcher for Python. It’s inspired by the C language switch statement, but with more flexibility; case values are not limited to integers like in C, but can be any value usable with the ‘==’ equality operator, or any string usable on the left-hand side of the ‘in’ operator, or any regular expression. Iterables of these types can also be use as case values.

New in Release 1.2:

It’s no longer necessary to call the switch method of the Switch class to dispatch a value, as the __call__ method is now a synonym. So instead, you can use:

mySwitch = Switch()

... register your cases ...

returnValue = mySwitch(value_to_switch_on)

But the switch method is still there for backwards compatibility.

Example

Here’s a small example of its use:

>>> from pyswitch import Switch, SwitchError

# Instantiate a Switch object.
>>> mySwitch = Switch()

# Register some cases and case handlers, using the handy-dandy
# decorators provided by the Switch object.

# A default handler.  A default handler is optional.  If defined,
# it will be called for all switch values not handled by any other
# handler.  If not defined, a SwitchError will be raised for an unhandled
# switch value.

# All handlers are passed the value being switched on, along with any
# other optional positional and keyword parameters given to the switch.
# Handlers can return a value, which is then returned by the call to
# switch which caused the handler to be called.

# Naturally, handlers can do anything you want.  In this default case
# example, we return a string of interesting info.
>>> @mySwitch.default
... def gotDefault(value, *args, **kwargs):
...    return "Default handler: I got unregistered value %r, "\
...          "with args: %r and kwargs: %r" % \
...          (value, args, kwargs)

# A single numeric case value.  The 'case' decorator is for exact matching
# to the switch value.  The value given to the case function, called
# the case value, can be any type usable with the '==' equality operator.
>>> @mySwitch.case(0)
... def gotZero(value, *args, **kwargs):
...    return "gotZero: I got a %d, with args: %r and kwargs: %r" % \
...          (value, args, kwargs)

# A range of numeric case values. An iterable of values can be given
# as the case value.
>>> @mySwitch.case(range(5, 10))
... def gotFiveThruNine(value, *args, **kwargs):
...    return "gotFiveThruNine: I got a %d, with args: %r and kwargs: %r" % \
...          (value, args, kwargs)

# A string case value, for an exact match.
>>> @mySwitch.case('Guido')
... def gotGuido(value, *args, **kwargs):
...    return "gotGuido: I got '%s', with args: %r and kwargs: %r" % \
...          (value, args, kwargs)

# A string value for use with the 'in' operator.
>>> @mySwitch.caseIn('lo')
... def gotLo(value, *args, **kwargs):
...    return "gotLo: I got '%s', with args: %r and kwargs: %r" % \
...          (value, args, kwargs)

# A regular expression pattern match in a string.
# You can also pass in a pre-compiled regular expression.
# For caseRegEx, the value passed to the case handler is actually
# the Match Object resulting from the successful regular expression
# pattern match.
>>> @mySwitch.caseRegEx(r'\b([Pp]y\w*)\b')
... def gotPyword(matchObj, *args, **kwargs):
...     return "gotPyword: I got a matchObject where group(1) is '%s', "\
...           "with args: %r and kwargs: %r" % \
...           (matchObj.group(1), args, kwargs)

# And lastly, you can pass a iterable of mixed-type values to case,
# caseIn, and caseRegEx.  Here, we pass in a list of heterogenous
# values to be use for exact matches.
>>> @mySwitch.case([ 99, 'yo', 200 ])
... def gotStuffInSeq(value, *args, **kwargs):
...     return "gotStuffInSeq: I got %r, with args: %r and kwargs: %r" % \
...           (value, args, kwargs)


# Now show what we can do.

>>> mySwitch(0, testing=False)
"gotZero: I got a 0, with args: () and kwargs: {'testing': False}"

>>> mySwitch(6, flag='boring')
"gotFiveThruNine: I got a 6, with args: () and kwargs: {'flag': 'boring'}"

>>> mySwitch(10, 42)
'Default handler: I got unregistered value 10, with args: (42,) and kwargs: {}'

>>> mySwitch('Guido', BDFL=True)
"gotGuido: I got 'Guido', with args: () and kwargs: {'BDFL': True}"

>>> mySwitch('Anyone seen Guido around?')
"Default handler: I got unregistered value 'Anyone seen Guido around?', with args: () and kwargs: {}"

>>> mySwitch('Yep, and he said "hello".', 99, yes='no')
"gotLo: I got 'lo', with args: (99,) and kwargs: {'yes': 'no'}"

>>> mySwitch('Bird is the Python word of the day.')
"gotPyword: I got a matchObject where group(1) is 'Python', with args: () and kwargs: {}"

>>> mySwitch('yo')
"gotStuffInSeq: I got 'yo', with args: () and kwargs: {}"