Guide

Starting a Taco Session

A Taco “client” session is started by constructing a Taco instance. The constructor will run a Taco “server” script in a sub-process and attach a TacoTransport object to the sub-process’s standard input and standard output.

There are two ways to specify which “server” script to run:

• The lang option

  This just specifies the language which the script should be using. The script will be assumed to be called taco-lang, where lang is the given language. For example a Taco “client” constructed with Taco(lang='perl') will try to run a script called taco-perl. This script must be present in your search path for this to be successful.

• The script option

  This option allows you to specify the name of the “server” script directly. For example some of the integration tests run the Python “server” script directly from this package using Taco(script='scripts/taco-python').

Actions

The rôle of the Taco “client” class is to send actions to the “server” script. While the actions are intended to be generic, the exact behavior will depend will depend on the “server” script and what is suitable for its language. The TacoServer documentation includes some information about how the actions are implemented in Python.

• Procedural Actions

  These are invoked by calling Taco methods directly.

  • call_class_method()
  • call_function()
  • construct_object()
  • get_value()
  • import_module()
  • set_value()

• Object-oriented Actions

  These are invoked via methods of TacoObject instances.

  • call_method()
  • get_attribute()
  • set_attribute()

• Convenience Methods

  These methods each return a callable which can be used to perform a Taco action in a more natural manner.

  • function()
  • constructor()
  • method()

Taco action messages typically include a list called args and a dictionary called kwargs. The Python Taco “client” fills these parameters from the positional and keyword arguments of its method calls.

Return Values

The Taco system allows for the return of various responses to actions. Here are some examples of Taco actions and the responses to them:

• Function Results

  If you find that you need the weighted roll_dice() function from the Acme::Dice Perl module, you can import it and call the function as follows:

  >>> from taco import Taco
  >>> taco = Taco(lang='perl')
  >>> taco.import_module('Acme::Dice', 'roll_dice')
  >>> taco.call_function('roll_dice', dice=1, sides=6, favor=6, bias=100)
  6
  

  In this example, instantiating a Taco object starts a sub-process running a Perl script. This “server” script then handles the instructions to import a module and call one of its functions, returning the value 6.

• Object References

  To allow the use of object-oriented modules such as Acme::PricelessMethods, references to objects are returned as instances of the TacoObject class.

  >>> taco.import_module('Acme::PricelessMethods')
  >>> pm = taco.construct_object('Acme::PricelessMethods')
  >>> type(pm)
  <class 'taco.object.TacoObject'>
  

  These objects can be used to invoke further actions:

  >>> pm.call_method('is_machine_on')
  1
  

• Exceptions

  roll_dice() raises an exception if we try to roll more than 100 dice. The exception is caught and re-raised on the “client” side:

  >>> taco.call_function('roll_dice', dice=1000)
  Traceback (most recent call last):
  ...
  taco.error.TacoReceivedError: ... Really? Roll 1000 dice? ...