starpy.menu
index
/home/mcfletch/pylive/starpy/menu.py

IVR-based menuing system with retry, exit, and similar useful features
 
You use the menuing system by instantiating Interaction and Option sub-classes
as a tree of options that make up an IVR menu.  Calling the top-level menu 
produces a Deferred that fires with a list of [(Option,value),...] pairs,
where Option is the thing chosen and value is the value entered by the user
for choosing that option.
 
When programming an IVR you will likely want to make Option sub-classes that
are callable to accomplish the task indicated by the user.
 
XXX allow for starting the menu system anywhere in the hierarchy
XXX add the reject/accept menus to the CollectDigits (requires soundfiles
in standard locations on the server, complicates install)

 
Modules
       
basicproperty.basic
basicproperty.common
twisted.internet.defer
starpy.error
starpy.fastagi
twisted.application.internet
logging
starpy.manager
os
pprint
basicproperty.propertied
twisted.application.service
time
starpy.utilapplication

 
Classes
       
Propertied(object)
Interaction
CollectDigits
Menu
Option
ExitOn
SubMenu
Runner
CollectDigitsRunner
MenuRunner

 
class CollectDigits(Interaction)
    Collects some number of digits (e.g. an extension) from user
 
 
Method resolution order:
CollectDigits
Interaction
Propertied
object

Data and other attributes defined here:
maxDigits = <IntegerProperty 'maxDigits'>
Maximum number of digits to collect (only restricted if specified)
minDigits = <IntegerProperty 'minDigits'>
Minimum number of digits to collect (only restricted if specified)
readBack = <BooleanProperty 'readBack'>
Whether to read the entered value back to the user
runnerClass = <class 'starpy.menu.CollectDigitsRunner'>
User's single interaction to enter a set of digits
 
Note: Asterisk is hard-coded to use # to exit the entry-mode...
soundFile = <StringLocaleProperty 'soundFile'>
File (name) for the pre-recorded blurb
tellInvalid = <IntegerProperty 'tellInvalid'>
Whether to tell the user that their selection is unrecognised
textPrompt = <StringProperty 'textPrompt'>
Textual prompt describing the option

Methods inherited from Interaction:
__call__(self, agi, *args, **named)
Initiate AGI-based interaction with the user

Data and other attributes inherited from Interaction:
ALL_DIGITS = '0123456789*#'
maxRepetitions = <IntegerProperty 'maxRepetitions'>
Maximum number of times to play before failure
timeout = <FloatProperty 'timeout'>
Duration to wait for response before repeating message

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class CollectDigitsRunner(Runner)
    User's single interaction to enter a set of digits
 
Note: Asterisk is hard-coded to use # to exit the entry-mode...
 
 
Method resolution order:
CollectDigitsRunner
Runner
Propertied
object

Methods defined here:
__call__(self, *args, **named)
Begin the AGI processing for the menu
onReadDigits(self, (digits, timeout))
Deal with succesful result from reading digits
readDigits(self, result=None)
Begin process of reading digits from the user
validEntry(self, digits)
Determine whether given digits are considered a "valid" entry

Methods inherited from Runner:
returnError(self, reason)
Return failure of deferred to our original caller
returnResult(self, result)
Return result of deferred to our original caller

Data and other attributes inherited from Runner:
agi = <BasicProperty 'agi'>
The AGI instance we use to communicate with the user
alreadyRepeated = <IntegerProperty 'alreadyRepeated'>
Number of times we've repeated the message...
finalDF = <BasicProperty 'finalDF'>
Final deferred we will callback/errback on success/failure
model = <BasicProperty 'model'>
The data-model that we are presenting to the user (e.g. Menu)

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class ExitOn(Option)
    An option which exits from the current menu level
 
 
Method resolution order:
ExitOn
Option
Propertied
object

Methods defined here:
__call__(self, pressed, parent)
Raise a MenuExit error

Data and other attributes inherited from Option:
option = <StringLocaleProperty 'option'>
Keypad values which select this option (list of characters)

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class Interaction(Propertied)
    Base class for user-interaction operations
 
 
Method resolution order:
Interaction
Propertied
object

Methods defined here:
__call__(self, agi, *args, **named)
Initiate AGI-based interaction with the user

Data and other attributes defined here:
ALL_DIGITS = '0123456789*#'
maxRepetitions = <IntegerProperty 'maxRepetitions'>
Maximum number of times to play before failure
runnerClass = None
timeout = <FloatProperty 'timeout'>
Duration to wait for response before repeating message

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class Menu(Interaction)
    IVR-based menu, returns options selected by the user and keypresses
 
The Menu holds a collection of Option instances along with a soundFile 
which presents those options to the user.  The menu will attempt to 
collect the user's selected option up to maxRepetitions times, playing 
the soundFile each time.
 
If tellInvalid is true, will allow any character being pressed to stop
the playback, and will tell the user if the pressed character is not 
recognised.  Otherwise will simply ignore a pressed character which isn't
part of an Option object's 'option' property.
 
The menu will chain into callable Options, so that SubMenu and ExitOn can
be used to produce effects such as multi-level menus with options to 
return to the parent menu level.
 
Returns [(option,char(pressedKey))...] for each level of menu explored
 
 
Method resolution order:
Menu
Interaction
Propertied
object

Data and other attributes defined here:
INVALID_OPTION_FILE = 'pm-invalid-option'
options = <ListProperty 'options'>
Set of options the user may select
runnerClass = <class 'starpy.menu.MenuRunner'>
User's single interaction with a given menu
soundFile = <StringLocaleProperty 'soundFile'>
File (name) for the pre-recorded full-menu blurb
tellInvalid = <IntegerProperty 'tellInvalid'>
Whether to tell the user that their selection is unrecognised
textPrompt = <StringProperty 'textPrompt'>
Textual prompt describing the option

Methods inherited from Interaction:
__call__(self, agi, *args, **named)
Initiate AGI-based interaction with the user

Data and other attributes inherited from Interaction:
ALL_DIGITS = '0123456789*#'
maxRepetitions = <IntegerProperty 'maxRepetitions'>
Maximum number of times to play before failure
timeout = <FloatProperty 'timeout'>
Duration to wait for response before repeating message

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class MenuRunner(Runner)
    User's single interaction with a given menu
 
 
Method resolution order:
MenuRunner
Runner
Propertied
object

Methods defined here:
__call__(self, *args, **named)
Begin the AGI processing for the menu
onReadMenu(self, (pressed, position))
Deal with succesful result from reading menu
readMenu(self, result=None)
Read our menu to the user

Data and other attributes defined here:
escapeDigits = <StringLocaleProperty 'escapeDigits'>
Set of digits which escape from prompts to choose option

Methods inherited from Runner:
returnError(self, reason)
Return failure of deferred to our original caller
returnResult(self, result)
Return result of deferred to our original caller

Data and other attributes inherited from Runner:
agi = <BasicProperty 'agi'>
The AGI instance we use to communicate with the user
alreadyRepeated = <IntegerProperty 'alreadyRepeated'>
Number of times we've repeated the message...
finalDF = <BasicProperty 'finalDF'>
Final deferred we will callback/errback on success/failure
model = <BasicProperty 'model'>
The data-model that we are presenting to the user (e.g. Menu)

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class Option(Propertied)
    A single menu option that can be chosen by the user
 
 
Method resolution order:
Option
Propertied
object

Data and other attributes defined here:
option = <StringLocaleProperty 'option'>
Keypad values which select this option (list of characters)

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class Runner(Propertied)
    User's interaction with a given Interaction-type
 
 
Method resolution order:
Runner
Propertied
object

Methods defined here:
returnError(self, reason)
Return failure of deferred to our original caller
returnResult(self, result)
Return result of deferred to our original caller

Data and other attributes defined here:
agi = <BasicProperty 'agi'>
The AGI instance we use to communicate with the user
alreadyRepeated = <IntegerProperty 'alreadyRepeated'>
Number of times we've repeated the message...
finalDF = <BasicProperty 'finalDF'>
Final deferred we will callback/errback on success/failure
model = <BasicProperty 'model'>
The data-model that we are presenting to the user (e.g. Menu)

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
class SubMenu(Option)
    A menu-holding option, just forwards call to the held menu
 
 
Method resolution order:
SubMenu
Option
Propertied
object

Methods defined here:
__call__(self, pressed, parent)
Get result from the sub-menu, add ourselves into the result

Data and other attributes defined here:
menu = <BasicProperty 'menu'>
The sub-menu we are presenting to the user

Data and other attributes inherited from Option:
option = <StringLocaleProperty 'option'>
Keypad values which select this option (list of characters)

Methods inherited from Propertied:
__init__(self, *arguments, **namedarguments)
Propertied object initialisation, allows passing in initial values for properties by name
__str__(self)
Get a friendly representation of the object
clone(self, **newValues)
Clone this object, with optional new property values
 
This method calls the __init__ method of your class with
the current property values of your class.  Providing newValues
(a dictionary) overrides property settings with new values.
getCloneProperties(self)
Get properties dictionary (key:value) for use in cloning of the instance
 
By default you get getProperties()' values, with an
attempt made to use the property's name, then the property's
direct "__get__" method.
toString(self, indentation='', alreadyDone=None, indentString=' ')
Get a nicely formatted representation of this object
 
This version assumes that getProperties returns
the list of properties which should be presented,
it recursively calls it's children with greater
indents to get their representations.
 
indentation -- current string indentation level
alreadyDone -- set of object ids which are already finished
 
XXX Needs a far better API, likely a stand-alone class
        without the automatic inheritance problems here :(

Class methods inherited from Propertied:
getProperties(cls) from type
Get the BasicProperty properties for a particular object's class

Data and other attributes inherited from Propertied:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'Propertied' objects>
list of weak references to the object (if defined)

 
Data
        reactor = <twisted.internet.selectreactor.SelectReactor instance>