4. Pyro Usage

• Introduction
• Pyro script tools
• Writing the remote class
• Writing the server
• Writing the client
• Runtime setup
• Runtime control and Logging
• Last Notes

Introduction

1. You write a Python class that you want to access remotely. Do this as if it were a normal Python class (but see the rules in the Rules and Limitations chapter).
2. You decide if you want to use static precompiled proxies, or Pyro's dynamic proxy. If you choose the latter, skip the next step.
3. Using pyroc, the proxy compiler, you generate static client proxy code for your Python class.
4. Write a server process that performs the following tasks:
   • Create one or more instances of your remote object.
   • Create a Pyro Daemon instance.
   • Find the Name Server.
   • Connect the remote object instances to the Daemon that will register them with the Name Server.
   • Sit in a loop telling the Daemon to handle incoming requests.
5. Write a client program that does the following:
   • Find the Name Server.
   • Query the NS for the requires objects. You'll get URIs back.
   • Import the static proxy module (created by pyroc) and create static proxies for the obtained URI, or just create a Pyro Dynamic proxy.
   • Call methods on the proxy object as if it were the real thing.
6. Make sure the Pyro Name Server is running.
7. Start your server process. If it complains that the names it wants to register already exist, use the nsc tool to unregister them, or restart the NS.
8. Run the client!

Pyro script tools

genguid   (GUID generator)

- One optional argument; -x
- This is a very simple GUID generator. It uses the internal Pyro GUID generator to print a new GUID. If you use the '-x' argument, it prints the GUID in hexadecimal instead of ASCII-encoded format.

pyroc   (Proxy compiler)

- One argument; the name of the module to process (without .py suffix)
- The proxy compiler generates a module with static client proxies for each class in the processed module. If necessary, server side skeleton code is also generated.

ns, rns   (Name Server)

These scripts are explained in the Name Server chapter.

es   (Event Server)

This script is explained in the Event Server (Pyro Services) chapter.

nsc   (Name Server Control tool)

- Arguments: [-h host] [-p port] [-i identification] command [args...]
- Controls the Pyro Name Server. '-h host' specifies the host where the Name Server should be contacted. '-p port' specifies a non-standard NS broadcast port to contact. With '-i identification' you can supply the authentication passphrase that is used to connect to the Name Server. When it contains spaces, use quotes around it. If the host is specified, it is the direct Pyro port instead. 'command' is one of the following:

• ping: just check if the NS is up and running.
• list: prints the contents of a name group. Argument is the group name to list.
• listall: prints a list of all registered names (expanded).
• register: register a new name. Arguments are the name and the URI.
• resolve: search for names. Arguments are the names to search for.
• remove: remove registered names from the NS. Arguments are the names to remove.
• creategroup: create a name group. Argument is the group to create.
• deletegroup: delete a name group and all contents. Argument is the group to delete.
• shutdown: send the NS a shutdown request, so that a clean shutdown is performed. No arguments.

xnsc   (Graphical NS control tool)

- No arguments
- This is a graphical version of the nsc command-line tool. Currently it needs Tk for the GUI, so you have to have a Tk-enabled Python on your system. It doesn't work on AmigaPython for instance. The GUI is simple and should explain itself. You can enter the hostname in the textbox at the top and press <enter> to contact the NS at that host, or just press the 'Auto Discover' button at the top right. If the NS has been found, the rest of the buttons are enabled. If your Name Server requires an authorization passphrase, you must enter that first in the ID entry box. After that, you can connect to the NS. Once connected, the passphrase is erased in the display for security reasons. You have to type it again if you need to reconnect.

Steps 1, 2 and 3: Writing the remote class

• The remote class can't have a remote __init__ method. You should use a regular initialization method that you must call explicitly after binding to the remote object. The __init__ method will only be called on the server side when the object is created.
• The remote class can't have direct attribute access unless you conciously choose to use a special proxy that supports attribute access (before Pyro 1.2 this was impossible). See below. You don't have to use getters and setters for each member variable any more.
• Don't stick the class in a Python package if you want to use static proxies. pyroc can't yet deal fully with Python packages.

Static or dynamic proxy?

• A static proxy is (slightly) faster than a dynamic one.
• It has stricter and faster runtime argument checking. A static proxy exactly mirrors the method signatures of the remote class, so an invalid method call is detected by Python locally. A dynamic proxy has to do a remote invocation only to find out the argument list was invalid.
• But beware: Python has many subtleties and I'm not sure if the current static proxy code that pyroc generates can deal with all of them. It might turn out that the dynamic proxy accepts things that will fail with the static version. Only time will tell.
• Note: because of group name logic the Name Server can only easily be accessed by the static proxy that Pyro provides (Pyro.naming.NameServerProxy). Luckily this is no big deal.
• Note: Pyro 1.2 introduced another kind of Dynamic Proxy: one that allows direct object attribute access. This proxy is a few percent slower than the normal dynamic proxy. By the way, the static proxy (generated by pyroc) also supports direct attribute access.

Step 4: Writing the server

Initialization

   Pyro.core.initServer()

Create a Pyro Daemon

   daemon = Pyro.core.Daemon()
   daemon.useNameServer(ns)

If your daemon is no longer referenced, it might be garbage collected (destroyed) by Python. Even if you connected Pyro objects to the daemon. So you have to make sure that you keep a reference to your daemon object at all time. This is recommended anyway because you can then cleanly terminate your Pyro application by calling daemon.shutdown() when it exits. Usually this is not a problem because your program creates a deamon and calls its requestLoop. But a situation might arise where you don't keep a reference to the daemon object, and then things break.

Find the Name Server

   locator = Pyro.naming.NameServerLocator()
   ns = locator.getNS()

Create object instances

• Derive a new class from both Pyro.core.ObjBase and your original class. The class body can be a simple 'pass'. If you want to add a custom __init__ method, make sure you call the __init__ method of Pyro.core.ObjBase and of your own class, if it has one.

     class ObjectImpl(Pyro.core.ObjBase, test.MyClass):
        def __init__(self):
           Pyro.core.ObjBase.__init__(self)
           test.MyClass.__init__(self)
        ...
     obj = ObjectImpl()
      ... use obj ...

• Delegate Pattern. In this pattern you create two objects, and you tell one of them to delegate all calls to the other. Instead of deriving from Pyro.core.ObjBase you just create that object and tell it to use your own object as a delegate, by calling the delegateTo method.

     obj = Pyro.core.ObjBase()
     myobj = MyClass()
     obj.delegateTo(myobj)
      ... use obj ...

• Direct inheritance: subclass your class directly from Pyro.core.ObjBase. This is the least hassle but you have to change existing code if you want to make classes suitable for Pyro.

     class MyPyroObj(Pyro.core.ObjBase):
        def __init__(self):
           Pyro.core.ObjBase.__init__(self)
           ...obj init here...
         ...
     obj = MyPyroObj()
      ... use obj ...

Connect object instances

   daemon.connect(obj,'our_object')

In contrast to the simple (flat) name shown above ("our_object"), Pyro's Name Server supports a hierarchical object naming scheme. For more information about this, see the Name Server chapter.

The Daemon handleRequest loop

requestLoop(condition, timeout, others, callback)

For those that like to have more control over the request handling loop, there is also handleRequests. Usually your loop will look something like this:

   while continueLoop:
      daemon.handleRequests(3.0)
      ... do something when a timeout occured ...

   daemon.handleRequests(timeout, [obj1,obj2,obj3], callback_func)

This concludes our server. Full listings can be found in the Example chapter.

Step 5: Writing the client

Initialization

   Pyro.core.initClient()

Find the Name Server

Find object URIs

• Query the NS. This is the best way to go. You ask the NS to give you the URI for the object with the right name ("my_object" in this example):

     uri = ns.resolve('my_object')

• Read it from a special file that was written by the object. This is like what is done in the previous paragraph, about finding the NameServer. Be sure to convert the string you read from the file to a real PyroURI object before you use it. Just pass it to the constructur of PyroURI and you'll be fine.
• Use the special PYRONAME:// or PYROLOC:// URI strings. The first is a shortcut to the Name Server, the second bypasses the Name Server completely. Read more about them in the chapter on the Name Server, "The special PYRONAME:// and PYROLOC:// URIs".

Create a proxy

   obj = Pyro.core.getProxyForURI(uri)     # get a dynamic proxy
   obj = Pyro.core.getAttrProxyForURI(uri) # get a dyn proxy with attribute support
   obj = mymodule_proxy.myobject(uri)      # get a static proxy (also w/ attrib support)

   # if you're sure that the URI is a real PyroURI object, you can do this:
   obj = uri.getProxy()                    # get a dynamic proxy directly from the URI	
   obj = uri.getAttrProxy()                # same, but with attribute support

Remote method invocations

   obj.method(arg1, arg2)
   print obj.getName()
   a = obj.answerQuestion('What is the meaning of life?')
   # the following statements only work with a attribute-capable proxy:
   attrib = obj.attrib
   obj.sum = obj.sum+1

This concludes our client. Full listings can be found in the Example chapter. For information on using Pyro's logging/tracing facility, see Runtime control and Logging, below.

Steps 6, 7 and 8: Runtime setup

Starting the Name Server

irmen@atlantis:~ > projects/Pyro/bin/ns
*** Pyro Name Server ***
Pyro Server Initialized. Using Pyro V2.4
Will accept shutdown requests.
URI written to: /home/irmen/Pyro_NS_URI
URI is: PYRO://10.0.0.150:9090/0a000096-08620ada-6697d564-62110a9f
Name Server started.  

Running the server

Running the client

Runtime control and Logging

Controlling the Name Server

Controlling Pyro

Tracing (logging)

• System Log
  The system log is implemented by the Pyro.util.Log object, which is an instance of Pyro.util.SystemLogger. System log tracelevel is configured using the PYRO_TRACELEVEL config item, the logfile location is configured using the PYRO_LOGFILE config item.
• User log
  You should create your own user log object by creating a Pyro.util.UserLogger instance. User log tracelevel is configured using the PYRO_USER_TRACELEVEL config item, the user logfile location is configured using the PYRO_USER_LOGFILE config item.
• Using the Logger object: logging entries
  The logger class provides four methods:
  • msg(source, *args) - log a simple message (note). source is a string that identifies the source of the log entry, after that, any argument may follow to be printed in the logfile.
  • error(source, *args) - log an error. source is a string that identifies the source of the log entry, after that, any argument may follow to be printed in the logfile.
  • warn(source, *args) - log a warning. source is a string that identifies the source of the log entry, after that, any argument may follow to be printed in the logfile.
  • raw(string) - log a string (unformatted). string is the string to write to the logfile. This logging is done unconditionally, the tracelevel setting has no influence here.
  Logfile entries have the following format:
  "2002-01-16 16:45:02 [5884:MainThread] ** ERR! ** NameServerLocator ** Name Server not responding"
  (a date and timestamp, process ID:thread name, then "NOTE", "WARN" or "ERR!", indicating if this was a simple message, a warning or an error. After that, the source of the log entry - this can be any string but should be meaningful for the developer. After that, the actual log message. All elements are separated by two asterisks). Each log entry is one line in the logfile. Entries written by the raw method can have any format, including multiple lines.

Last Notes

These chapters contain invaluable information about the more detailed aspects and possibilities of Pyro.

Also have a look at the extensions package Pyro.ext, it contains two modules that provide extremely easy remoting for your programs. Take a look at the "quickstart" and "quickstart-noNS" examples for more details.