README

NAME

    tropo - The TropoPython module. This module implements a set of classes and methods for manipulating the 
    Web API for the Tropo cloud communications service at http://www.tropo.com/

    For more information about the Tropo Web API that is used with this module, please see:

        http://www.tropo.com/docs/webapi/

    As this python module is still in development, please report any bugs or issues by raising an issue here:

        http://github.com/tropo/tropo-webapi-python/issues

FILE

    http://github.com/tropo/tropo-webapi-python/blob/master/tropo.py

DESCRIPTION

    Usage:
    
    ----
    from tropo import Tropo

    tropo = Tropo()
    tropo.say("Hello, World")
    json = tropo.RenderJson() 
    ----
    
    You can write this JSON back to standard output to get Tropo to perform 
    the action. For example, on Google Appengine you might write something like:
    
    handler.response.out.write(json)
    
    Much of the time, a you will interact with Tropo by  examining the Result 
    object and communicating back to Tropo via the Tropo class methods, such 
    as "say". In some cases, you'll want to build a class object directly such as in :
    
        choices = tropo.Choices("[5 digits]").obj
    
        tropo.ask(choices, 
                  say="Please enter your 5 digit zip code.", 
                  attempts=3, bargein=True, name="zip", timeout=5, voice="dave")
        ...

NOTE ON PYTHON VERSIONS

    This module is for python 2.x and requires python 2.5 or higher.  
    There is a separate version available for python 3.x at:

      http://github.com/tropo/python-webapi/tree/python3

TESTS

	Run testsuite by issuing:

	cd test
	python test.py

CLASSES
    Ask
    Call
    Choices
    Conference
    Hangup
    Message
    On
    Record
    Redirect
    Reject
    Result
    Say
    Session
    StartRecording
    StopRecording
    Transfer
    Tropo
    unittest.TestCase(__builtin__.object)
        TestTropoPython
    
    class Ask
     |  Class representing the "ask" Tropo action. Builds an "ask" JSON object.
     |  Class constructor arg: choices, a Choices object
     |  Convenience function: Tropo.ask()
     |  Class constructor options: attempts, bargein, choices, minConfidence, name, recognizer, required, say, timeout, voice
     |  
     |  Request information from the caller and wait for a response.
     |  (See https://www.tropo.com/docs/webapi/ask.htm)
     |  
     |      { "ask": {
     |          "attempts": Integer,
     |          "bargein": Boolean,
     |          "choices": Object, #Required
     |          "minConfidence": Integer,
     |          "name": String,
     |          "recognizer": String,
     |          "required": Boolean,
     |          "say": Object,
     |          "timeout": Float,
     |          "voice": String } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, choices, **options)
    
    class Call
     |  Class representing the "call" Tropo action. Builds a "call" JSON object.
     |  Class constructor arg: to, a String
     |  Class constructor options: answerOnMedia, channel, from, headers, name, network, recording, required, timeout
     |  Convenience function: Tropo.call()
     |  
     |  (See https://www.tropo.com/docs/webapi/call.htm)
     |  
     |  { "call": {
     |      "to": String or Array,#Required
     |      "answerOnMedia": Boolean,
     |      "channel": string,
     |      "from": string,
     |      "headers": Object,
     |      "name": String,
     |      "network": String,
     |      "recording": Array or Object,
     |      "required": Boolean,
     |      "timeout": Float } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, to, **options)
    
    class Choices
     |  Class representing choice made by a user. Builds a "choices" JSON object.
     |  Class constructor options: terminator, mode
     |  
     |  (See https://www.tropo.com/docs/webapi/ask.htm)
     |  
     |  Methods defined here:
     |  
     |  __init__(self, value, **options)
    
    class Conference
     |  Class representing the "conference" Tropo action. Builds a "conference" JSON object.
     |  Class constructor arg: id, a String
     |  Convenience function: Tropo.conference()
     |  Class constructor options: mute, name, playTones, required, terminator
     |  
     |  (See https://www.tropo.com/docs/webapi/conference.htm)
     |  
     |  { "conference": {
     |      "id": String,#Required
     |      "mute": Boolean,
     |      "name": String,
     |      "playTones": Boolean,
     |      "required": Boolean,
     |      "terminator": String } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, id, **options)
    
    class Hangup
     |  Class representing the "hangup" Tropo action. Builds a "hangup" JSON object.
     |  Class constructor arg: 
     |  Class constructor options: 
     |  Convenience function: Tropo.hangup()
     |  
     |  (See https://www.tropo.com/docs/webapi/hangup.htm)
     |  
     |  { "hangup": { } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self)
    
    class Message
     |  Class representing the "message" Tropo action. Builds a "message" JSON object.
     |  Class constructor arg: say_obj, a Say object
     |  Class constructor arg: to, a String
     |  Class constructor options: answerOnMedia, channel, from, name, network, required, timeout, voice
     |  Convenience function: Tropo.message()
     |  
     |  (See https://www.tropo.com/docs/webapi/message.htm)
     |  { "message": {
     |          "say": Object,#Required
     |          "to": String or Array,#Required
     |          "answerOnMedia": Boolean,
     |          "channel": string,
     |          "from": Object,
     |          "name": String,
     |          "network": String,
     |          "required": Boolean,
     |          "timeout": Float,
     |          "voice": String } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, say_obj, to, **options)
    
    class On
     |  Class representing the "on" Tropo action. Builds an "on" JSON object.
     |  Class constructor arg: event, a String
     |  Class constructor options:  name,next,required,say
     |  Convenience function: Tropo.on()
     |  
     |  (See https://www.tropo.com/docs/webapi/on.htm)
     |  
     |  { "on": {
     |      "event": String,#Required
     |      "name": String,
     |      "next": String,
     |      "required": Boolean,
     |      "say": Object } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, event, **options)
    
    class Record
     |  Class representing the "record" Tropo action. Builds a "record" JSON object.
     |  Class constructor arg: 
     |  Class constructor options: attempts, bargein, beep, choices, format, maxSilence, maxTime, method, minConfidence, name, password, required, say, timeout, transcription, url, username
     |  Convenience function: Tropo.record()
     |  
     |  
     |  
     |  (See https://www.tropo.com/docs/webapi/record.htm)
     |  
     |      { "record": {
     |          "attempts": Integer,
     |          "bargein": Boolean,
     |          "beep": Boolean,
     |          "choices": Object,
     |          "format": String,
     |          "maxSilence": Float,
     |          "maxTime": Float,
     |          "method": String,
     |          "minConfidence": Integer,
     |          "name": String,
     |          "password": String,
     |          "required": Boolean,
     |          "say": Object,
     |          "timeout": Float,
     |          "transcription": Array or Object,
     |          "url": String,#Required ?????
     |          "username": String } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, **options)
    
    class Redirect
     |  Class representing the "redirect" Tropo action. Builds a "redirect" JSON object.
     |  Class constructor arg: to, a String
     |  Class constructor options:  name, required
     |  Convenience function: Tropo.redirect()
     |  
     |  (See https://www.tropo.com/docs/webapi/redirect.htm)
     |  
     |  { "redirect": {
     |      "to": Object,#Required
     |      "name": String,
     |      "required": Boolean } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, to, **options)
    
    class Reject
     |  Class representing the "reject" Tropo action. Builds a "reject" JSON object.
     |  Class constructor arg: 
     |  Class constructor options: 
     |  Convenience function: Tropo.reject()
     |  
     |  (See https://www.tropo.com/docs/webapi/reject.htm)
     |  
     |  { "reject": { } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self)
    
    class Result
     |  Returned anytime a request is made to the Tropo Web API. 
     |  Method: getValue 
     |  (See https://www.tropo.com/docs/webapi/result.htm)
     |  
     |      { "result": {
     |          "actions": Array or Object,
     |          "complete": Boolean,
     |          "error": String,
     |          "sequence": Integer,
     |          "sessionDuration": Integer,
     |          "sessionId": String,
     |          "state": String } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, result_json)
     |  
     |  getValue(self)
     |      Get the value of the previously POSTed Tropo action.
    
    class Say
     |  Class representing the "say" Tropo action. Builds a "say" JSON object.
     |  Class constructor arg: message, a String, or a List of Strings
     |  Class constructor options: attempts, bargein, choices, minConfidence, name, recognizer, required, say, timeout, voice
     |  Convenience function: Tropo.say()
     |  
     |  (See https://www.tropo.com/docs/webapi/say.htm)
     |  
     |  { "say": {
     |      "as": String,
     |      "name": String,
     |      "required": Boolean,
     |      "value": String #Required
     |      } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, message, **options)
    
    class Session
     |  Session is the payload sent as an HTTP POST to your web application when a new session arrives. 
     |  (See https://www.tropo.com/docs/webapi/session.htm)
     |  
     |  Methods defined here:
     |  
     |  __init__(self, session_json)
    
    class StartRecording
     |  Class representing the "startRecording" Tropo action. Builds a "startRecording" JSON object.
     |  Class constructor arg: url, a String
     |  Class constructor options: format, method, username, password
     |  Convenience function: Tropo.startRecording()
     |  
     |  (See https://www.tropo.com/docs/webapi/startrecording.htm)
     |  
     |  { "startRecording": {
     |      "format": String,
     |      "method": String,
     |      "url": String,#Required
     |      "username": String,
     |      "password": String } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, url, **options)
    
    class StopRecording
     |   Class representing the "stopRecording" Tropo action. Builds a "stopRecording" JSON object.
     |   Class constructor arg:
     |   Class constructor options:
     |   Convenience function: Tropo.stopRecording()
     |  
     |  (See https://www.tropo.com/docs/webapi/stoprecording.htm)
     |     { "stopRecording": { } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self)
    
    class TestTropoPython(unittest.TestCase)
     |  Class implementing a set of unit tests for TropoPython.
     |  
     |  Method resolution order:
     |      TestTropoPython
     |      unittest.TestCase
     |      __builtin__.object
     |  
     |  Methods defined here:
     |  
     |  test_ask(self)
     |      Test the "ask" Tropo class method.
     |  
     |  test_call(self)
     |      Test the "call" Tropo class method.
     |  
     |  test_conference(self)
     |      Test the "conference" Tropo class method.
     |  
     |  test_hangup(self)
     |      Test the "hangup" Tropo class method.
     |  
     |  test_list_say(self)
     |      Test the "say" Tropo class method, when a list of Strings is passed to it.
     |  
     |  test_message(self)
     |      Test the "message" Tropo class method.
     |  
     |  test_on(self)
     |      Test the "on" Tropo class method.
     |  
     |  test_record(self)
     |      Test the "record" Tropo class method.
     |  
     |  test_redirect(self)
     |      Test the "redirect" Tropo class method.
     |  
     |  test_reject(self)
     |      Test the "reject" Tropo class method.
     |  
     |  test_say(self)
     |      Test the "say" Tropo class method.
     |  
     |  test_startRecording(self)
     |      Test the "startRecording" Tropo class method.
     |  
     |  test_stopRecording(self)
     |      Test the "stopRecording" Tropo class method.
     |  
     |  test_transfer(self)
     |      Test the "transfer" Tropo class method.
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  ID = 'foo'
     |  
     |  MY_PHONE = '6021234567'
     |  
     |  RECORDING_URL = '/receive_recording.py'
     |  
     |  S3_URL = 'http://s3.amazonaws.com/xxx_s3_bucket/hello.wav'
     |  
     |  TO = '8005551212'
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from unittest.TestCase:
     |  
     |  __call__(self, *args, **kwds)
     |  
     |  __init__(self, methodName='runTest')
     |      Create an instance of the class that will use the named test
     |      method when executed. Raises a ValueError if the instance does
     |      not have a method with the specified name.
     |  
     |  __repr__(self)
     |  
     |  __str__(self)
     |  
     |  assertAlmostEqual = failUnlessAlmostEqual(self, first, second, places=7, msg=None)
     |      Fail if the two objects are unequal as determined by their
     |      difference rounded to the given number of decimal places
     |      (default 7) and comparing to zero.
     |      
     |      Note that decimal places (from zero) are usually not the same
     |      as significant digits (measured from the most signficant digit).
     |  
     |  assertAlmostEquals = failUnlessAlmostEqual(self, first, second, places=7, msg=None)
     |      Fail if the two objects are unequal as determined by their
     |      difference rounded to the given number of decimal places
     |      (default 7) and comparing to zero.
     |      
     |      Note that decimal places (from zero) are usually not the same
     |      as significant digits (measured from the most signficant digit).
     |  
     |  assertEqual = failUnlessEqual(self, first, second, msg=None)
     |      Fail if the two objects are unequal as determined by the '=='
     |      operator.
     |  
     |  assertEquals = failUnlessEqual(self, first, second, msg=None)
     |      Fail if the two objects are unequal as determined by the '=='
     |      operator.
     |  
     |  assertFalse = failIf(self, expr, msg=None)
     |      Fail the test if the expression is true.
     |  
     |  assertNotAlmostEqual = failIfAlmostEqual(self, first, second, places=7, msg=None)
     |      Fail if the two objects are equal as determined by their
     |      difference rounded to the given number of decimal places
     |      (default 7) and comparing to zero.
     |      
     |      Note that decimal places (from zero) are usually not the same
     |      as significant digits (measured from the most signficant digit).
     |  
     |  assertNotAlmostEquals = failIfAlmostEqual(self, first, second, places=7, msg=None)
     |      Fail if the two objects are equal as determined by their
     |      difference rounded to the given number of decimal places
     |      (default 7) and comparing to zero.
     |      
     |      Note that decimal places (from zero) are usually not the same
     |      as significant digits (measured from the most signficant digit).
     |  
     |  assertNotEqual = failIfEqual(self, first, second, msg=None)
     |      Fail if the two objects are equal as determined by the '=='
     |      operator.
     |  
     |  assertNotEquals = failIfEqual(self, first, second, msg=None)
     |      Fail if the two objects are equal as determined by the '=='
     |      operator.
     |  
     |  assertRaises = failUnlessRaises(self, excClass, callableObj, *args, **kwargs)
     |      Fail unless an exception of class excClass is thrown
     |      by callableObj when invoked with arguments args and keyword
     |      arguments kwargs. If a different type of exception is
     |      thrown, it will not be caught, and the test case will be
     |      deemed to have suffered an error, exactly as for an
     |      unexpected exception.
     |  
     |  assertTrue = failUnless(self, expr, msg=None)
     |      Fail the test unless the expression is true.
     |  
     |  assert_ = failUnless(self, expr, msg=None)
     |      Fail the test unless the expression is true.
     |  
     |  countTestCases(self)
     |  
     |  debug(self)
     |      Run the test without collecting errors in a TestResult
     |  
     |  defaultTestResult(self)
     |  
     |  fail(self, msg=None)
     |      Fail immediately, with the given message.
     |  
     |  failIf(self, expr, msg=None)
     |      Fail the test if the expression is true.
     |  
     |  failIfAlmostEqual(self, first, second, places=7, msg=None)
     |      Fail if the two objects are equal as determined by their
     |      difference rounded to the given number of decimal places
     |      (default 7) and comparing to zero.
     |      
     |      Note that decimal places (from zero) are usually not the same
     |      as significant digits (measured from the most signficant digit).
     |  
     |  failIfEqual(self, first, second, msg=None)
     |      Fail if the two objects are equal as determined by the '=='
     |      operator.
     |  
     |  failUnless(self, expr, msg=None)
     |      Fail the test unless the expression is true.
     |  
     |  failUnlessAlmostEqual(self, first, second, places=7, msg=None)
     |      Fail if the two objects are unequal as determined by their
     |      difference rounded to the given number of decimal places
     |      (default 7) and comparing to zero.
     |      
     |      Note that decimal places (from zero) are usually not the same
     |      as significant digits (measured from the most signficant digit).
     |  
     |  failUnlessEqual(self, first, second, msg=None)
     |      Fail if the two objects are unequal as determined by the '=='
     |      operator.
     |  
     |  failUnlessRaises(self, excClass, callableObj, *args, **kwargs)
     |      Fail unless an exception of class excClass is thrown
     |      by callableObj when invoked with arguments args and keyword
     |      arguments kwargs. If a different type of exception is
     |      thrown, it will not be caught, and the test case will be
     |      deemed to have suffered an error, exactly as for an
     |      unexpected exception.
     |  
     |  id(self)
     |  
     |  run(self, result=None)
     |  
     |  setUp(self)
     |      Hook method for setting up the test fixture before exercising it.
     |  
     |  shortDescription(self)
     |      Returns a one-line description of the test, or None if no
     |      description has been provided.
     |      
     |      The default implementation of this method returns the first line of
     |      the specified test method's docstring.
     |  
     |  tearDown(self)
     |      Hook method for deconstructing the test fixture after testing it.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from unittest.TestCase:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from unittest.TestCase:
     |  
     |  failureException = <type 'exceptions.AssertionError'>
     |      Assertion failed.
    
    class Transfer
     |  Class representing the "transfer" Tropo action. Builds a "transfer" JSON object.
     |  Class constructor arg: to, a String, or List
     |  Class constructor options: answerOnMedia, choices, from, name, required, terminator
     |  Convenience function: Tropo.transfer()
     |  
     |  (See https://www.tropo.com/docs/webapi/transfer.htm)
     |  { "transfer": {
     |      "to": String or Array,#Required
     |      "answerOnMedia": Boolean,
     |      "choices": Object,
     |      "from": Object,
     |      "name": String,
     |      "required": Boolean,
     |      "terminator": String,
     |      "timeout": Float } }
     |  
     |  Methods defined here:
     |  
     |  __init__(self, to, **options)
    
    class Tropo
     |  This is the top level class for all the Tropo web api actions.
     |  The methods of this class implement individual Tropo actions.
     |  Individual actions are each methods on this class.
     |  
     |  Each method takes one or more required arguments, followed by optional
     |  arguments expressed as key=value pairs.
     |  
     |  The optional arguments for these methods are described here:
     |  https://www.tropo.com/docs/webapi/
     |  
     |  Methods defined here:
     |  
     |  PrettyJson(self)
     |      Render a Tropo object into a Json string, pretty-printed with indents.
     |  
     |  RenderJson(self)
     |      Render a Tropo object into a Json string.
     |  
     |  __init__(self)
     |  
     |  ask(self, choices, **options)
     |      Sends a prompt to the user and optionally waits for a response.
     |      Arguments: "choices" is a Choices object
     |      See https://www.tropo.com/docs/webapi/ask.htm
     |  
     |  call(self, to, **options)
     |      Places a call or sends an an IM, Twitter, or SMS message. To start a call, use the Session API to tell Tropo to launch your code. 
     |      
     |      Arguments: to is a String.
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/call.htm
     |  
     |  conference(self, id, **options)
     |      This object allows multiple lines in separate sessions to be conferenced together so that the parties on each line can talk to each other simultaneously. 
     |      This is a voice channel only feature. 
     |      Argument: "id" is a String
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/conference.htm
     |  
     |  hangup(self)
     |      This method instructs Tropo to "hang-up" or disconnect the session associated with the current session.
     |      See https://www.tropo.com/docs/webapi/hangup.htm
     |  
     |  message(self, say_obj, to, **options)
     |      A shortcut method to create a session, say something, and hang up, all in one step. This is particularly useful for sending out a quick SMS or IM. 
     |      
     |      Argument: "say_obj" is a Say object
     |      Argument: "to" is a String
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/message.htm
     |  
     |  on(self, event, **options)
     |      Adds an event callback so that your application may be notified when a particular event occurs. 
     |      Possible events are: "continue", "error", "incomplete" and "hangup". 
     |      Argument: event is an event
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/on.htm
     |  
     |  record(self, **options)
     |      Plays a prompt (audio file or text to speech) and optionally waits for a response from the caller that is recorded. 
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/record.htm
     |  
     |  redirect(self, id, **options)
     |      Forwards an incoming call to another destination / phone number before answering it. 
     |      Argument: id is a String
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/redirect.htm
     |  
     |  reject(self)
     |      Allows Tropo applications to reject incoming sessions before they are answered. 
     |      See https://www.tropo.com/docs/webapi/reject.htm
     |  
     |  say(self, message, **options)
     |      When the current session is a voice channel this key will either play a message or an audio file from a URL. 
     |      In the case of an text channel it will send the text back to the user via i nstant messaging or SMS. 
     |      Argument: message is a string
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/say.htm
     |  
     |  startRecording(self, url, **options)
     |      Allows Tropo applications to begin recording the current session. 
     |      Argument: url is a string
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/startrecording.htm
     |  
     |  stopRecording(self)
     |      Stops a previously started recording.
     |      See https://www.tropo.com/docs/webapi/stoprecording.htm
     |  
     |  transfer(self, to, **options)
     |      Transfers an already answered call to another destination / phone number. 
     |      Argument: to is a string
     |      Argument: **options is a set of optional keyword arguments.
     |      See https://www.tropo.com/docs/webapi/transfer.htm