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
optionThis just specifies the language which the script should be using. The script will be assumed to be called
taco-lang
, wherelang
is the given language. For example aTaco
“client” constructed withTaco(lang='perl')
will try to run a script calledtaco-perl
. This script must be present in your search path for this to be successful.The
script
optionThis 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.Object-oriented Actions
These are invoked via methods of
TacoObject
instances.Convenience Methods
These methods each return a callable which can be used to perform a Taco action in a more natural manner.
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? ...