1. Introduction

Pyro is short for PYthon Remote Objects. It is an advanced and powerful Distributed Object Technology system written entirely in Python, that is designed to be very easy to use. Never worry about writing network communication code again, when using Pyro you just write your Python objects like you would normally. With only a few lines of extra code, Pyro takes care of the network communication between your objects once you split them over different machines on the network. All the gory socket programming details are taken care of, you just call a method on a remote object as if it were a local object!

Pyro provides an object-oriented form of RPC. You can use Pyro within a single system but also use it for IPC. For those that are familiar with Java, Pyro resembles Java's Remote Method Invocation (RMI). It is less similar to CORBA - which is a system- and language independent Distributed Object Technology and has much more to offer than Pyro or RMI. But Pyro is small, simple, fun and free! For another overview of what Pyro is, see the Pyro page online (http://irmen.home.xs4all.nl/pyro3). You can also download the package from there.

Copyright and Disclaimer
This software is copyright © by Irmen de Jong. It is subject to change without notice. Pyro comes as-is, without warranty and in no event can Irmen de Jong be held liable for any problems resulting from this software. License: Pyro is released under the MIT license, see the file "LICENSE".

Security Warning
In the Security chapter is an important security warning that you absolutely must read!

Legacy version
Pyro 3.x is in maintenance mode. This means it will only get security- and bugfixes. New projects are strongly advised to use Pyro4 instead, which is the new Pyro version that is actively being developed.

Features of Pyro 3.x

• Written in 100% pure Python. It is small, simple and extremely portable - it runs everywhere Python runs and TCP/IP networking is available.
• Naming Service which keeps record of the location of objects. The location of the NS can be discovered by a broadcast mechanism, and various other ways, if your network doesn't support broadcasting. NS has option to keep its naming database persistent (on disk) so that it survives shutdowns.
• High-level Event Service with topic channels.
• Mobile objects. Clients and servers can pass objects around - even when the server has never known them before. Pyro will then automatically transfer the needed Python bytecode.
• Support for Python types only restricted by those that the standard 'pickle' module handles (all builtin types, and user created classes) Objects as arguments are also supported.
• Support for all Python argument types (variable argument lists and keyword arguments, *args and **keywords).
• Exceptions that occur in the remote object will actually be raised too on the client, just as if the error occured locally. Pyro's exception transportation mechanism makes this possible.
• Dynamic Proxies - no need for additional tools or classes.
• Direct remote attribute access with normal Python syntax.
• Server can dynamically create or remove new Pyro objects.
• Multithreaded server support to handle multiple requests simultaneously.
• Automatic reconnection in case of network connection failures.
• Fast one-way invocation possible.
• Pyro contains heavily tested network communication code that works reliable on all platforms
• Talk between 32-bit and 64-bit machines, regardless of processor architecture and operating system
• A lot of examples are included in the Pyro distribution!

To get an idea of how Pyro works, here is a scenario:

1. You write a module 'test' containing a class 'testclass', which will be accessed remotely.
2. The server creates one or more instances of the 'testclass', and registers them with the Pyro Name Server.
3. The client queries the Name Server for the location of those objects. It gets a Pyro URI (Universal Resource Identifier) for them.
4. The client creates proxies for the remote objects.
5. Because the proxy mimics the real 'testclass', the client can now invoke methods on the remote objects. The proxy will forward the method invocations and return the results, just as if it was the remote object itself. Not a single line of network communication code has been written.

To dive directly into the code, have a look at the various Pyro examples in the examples directory (read the Readme.txt). There is much to learn there. The easiest example to start with is the "simple" example, it shows how a normal python object is made into a Pyro object and accessed remotely from the client.

Required Software:

• This version of Pyro needs at least Python 2.5, but it is not compatible with Python 3.x. (you'll need Pyro 4.x for that).
• You will have to use the same major Python version everywhere to make sure the data format is compatible (if you are using the default builtin pickle protocol)
• Because basic Pyro does not depend on any third party libraries or extension modules, it runs wherever Python is available, however, the command line utility scripts are designed for Windows(NT) and Unix sh. You might experience problems trying to run them on other systems.
• The pyro-xnsc tool requires the Tkinter Python extension module, with Tcl/Tk installed.
• The pyro-wxnsc tool requires the WxPython extension module with WxWindows.

Important information Links

• Pyro 3.x home page
• Pyro4 home page - the successor of Pyro 3.x that is actively being developed.
• Python package index for Pyro
• Python package index for Pyro4
• Info about the Mailing list, which is the best way of getting help.

Related technology

• Java Remote Method Invocation (RMI)
• Common Object Request Broker Architecture (CORBA)
• OmniORB - a CORBA implementation with Python bindings

Thanks

I want to thank everybody on the Pyro mailing list, your participation is of great value. And to everybody who contacted me about Pyro, for positive remarks, comments, or with problems (it all helps to improve Pyro): Thank You!